# webOS Archive Docs / Help Flow

An interactive, progressive-disclosure help site for setting up, activating, and
using legacy Palm/HP webOS devices. It's the primary help entry point for
webOS Archive, replacing an older flat mkdocs documentation site.

Live at `https://docs.webosarchive.org`. Repo: `webOSArchive/webos-docs`.

## Git branches

- `main` — this site (what you're looking at).
- `old-version` — the complete history of the previous mkdocs-based docs
  site, preserved unchanged. If content here seems thinner than before, or
  you need to recover exact old wording/links/images, check that branch —
  it's the source of truth for pre-rewrite content. Some things were
  deliberately cut or restructured (the old site was flat per-topic pages;
  this one is a step-by-step wizard), so a diff isn't automatically a bug.
- `main`'s history also has `old-version`'s tip as a merge-commit ancestor
  (the cutover was done as a history-preserving merge, not a squash), so
  the old commits are reachable from `main` too, not just via the branch.

## Hard constraints — read before touching JS/CSS

This has to run correctly on real 2010-2011-era webOS browsers (TouchPad at
1024x768, Pre3 at 480x800) *as well as* modern desktop/phone browsers. That
means:

- **JS: plain ES5 only.** No arrow functions, `let`/`const`, template
  literals, classes, or newer `Array`/`Object` methods.
- **CSS: no flexbox, no grid, no custom properties, no `rem` units.**
  Layout is done with floats + `overflow:hidden` clearfix tricks (see
  `.site-header-text`, `.header-actions` in `style.css` for the pattern).
- No build step, no bundler, no npm dependencies. Everything is loaded as
  plain `<script>`/`<link>` tags.
- Prefer relative links for anything on this site. For links to
  `webosarchive.org` resources, always use plain `http://`, never
  `https://` — legacy devices can't do modern TLS, and we never want to
  force a protocol upgrade on them. Third-party links keep whatever scheme
  they require.
- When adding an icon/image that gets displayed small (buttons, favicons),
  pre-scale it close to its CSS display size rather than relying on the
  browser to downscale a large source image — old WebKit's scaler produces
  visible aliasing on a large ratio (e.g. a 320px source shown at 36px). A
  clean rule of thumb: ship at ~2x the CSS display size.

## File layout

- `index.php` — the only HTML entry point. Also does one server-side job:
  fetches the shared webOS Archive top nav (`www.webosarchive.org/menu.php`)
  over the *same protocol the request arrived on* and inlines it directly
  into the page. This is server-side specifically because
  `www.webosarchive.org` sends no CORS headers, so a client-side fetch from
  a different origin would be blocked by the browser — inlining via PHP
  sidesteps that entirely. **Requires a PHP-enabled host.** Local dev:
  `php -S 127.0.0.1:PORT` from the repo root — NOT `python3 -m http.server`,
  which can't execute `.php` files (it'll just serve the raw source).
- `flow-data.js` — all step/question/answer content. No rendering logic.
- `app.js` — the rendering/state engine. No content. See "Content model"
  below for the shape it expects from `flow-data.js`.
- `style.css` — site styling.
- `css/wosa-menu.css` — positions the injected top-nav bar (fixed, 45px
  tall) and reserves page space for it, only when `index.php`'s
  server-side fetch actually succeeded (graceful degradation — a failed
  fetch leaves no empty gap).
- `images/` — content images, icons, favicons. `DeviceIcons/` — the four
  device-category icons used in Steps 3 and 6 (order must match
  `DEVICE_CATEGORY_ICONS` in `flow-data.js`).

## Content model (`flow-data.js`)

- A **node** is one question: `{ q, code, info, options }`.
- An **option** is one answer: `{ label, content, next }` — `content` is
  HTML shown once picked; `next` is an optional nested node for a
  follow-up question.
- A **step** is a top-level numbered row: `{ id, title, node }`, collected
  in the `FLOW` array in step order.
- `q`, `info`, and `options` can each be either a plain value/array, or a
  **function** evaluated fresh on every render (e.g. reading the device
  filter). See `wosaResolveField`/`wosaResolveOptions` in `app.js`. Use
  this when a question's wording or choices need to depend on state
  already collected elsewhere in the flow.
- Steps 7 and 8 don't use the question/option wizard shape at all — they're
  `{ topics: [{label, content}, ...], after }`, rendered by
  `wosaRenderTopics` as a continuous flowing document (like the old docs
  pages), not a click-to-expand list.

## Device filter

Steps 3 and 6 (`FILTER_STEP_IDS`) both ask the same top-level "which
device?" question (`DEVICE_CATEGORY_LABELS`/`_SHORT`/`_ICONS`, a shared
4-entry array: Older Phone, Later Phone, TouchPad 10", TouchPad Go).
Answering it anywhere seeds `wosaState.deviceFilter` and carries the answer
into whichever of the two hasn't been asked yet, so the user is never asked
twice.

`FILTER_DEPENDENT_STEP_IDS` (currently `[4, 5]`) lists steps whose *own*
`options` function reads that filter to narrow its choices (e.g. Step 4's
recovery-mode procedure differs by device). Any answer change within a
filter step (not just the top-level device pick — e.g. Step 3's nested
"upgrade to Community Edition" sub-answer) invalidates those steps' stored
answers via `wosaInvalidateFilterDependents()`, so a stale option index can
never silently point at the wrong choice once the filtered list reshuffles.

When a filter-dependent node's `options` function resolves to exactly one
real choice, `wosaRenderNode` auto-selects it — no point making someone tap
the only available answer. This never applies to a node that's *naturally*
single-option by design (a plain array, e.g. the "confirm deviceTool
finished" checkpoint), which still requires a deliberate tap since it's
confirming a real-world action, not narrowing a question.

`wosaIsCEUpgrade()` in `flow-data.js` is a further example of this pattern:
it derives (purely from Step 3's own path — TouchPad 10" filter plus its
"Upgrade to webOS 3.1.0 Community Edition" sub-answer) whether Steps 4 and
5 should skip their normal instructions in favor of a short "already
handled by the CE Doctor" message.

## Rendering / state

- State lives in `localStorage` (`wosaHelpFlowState2`): `{ path,
  deviceFilter, collapsedSteps }`. `wosaReset()` clears it back to
  defaults (step 1 expanded, everything else collapsed).
- Every state change triggers a full re-render (`wosaRender()` rebuilds
  the entire `#app` innerHTML from `FLOW`) — there's no incremental DOM
  patching.
- Because of that, entrance animations are scoped via a transient,
  non-persisted global, `wosaAnimateFrom = {stepId, level}`, set right
  before a re-render so only the genuinely-new content (deeper than the
  level that was just answered) gets the reveal animation — otherwise
  already-visible content would replay its animation on every unrelated
  re-render.
- Options stay visible after being answered (highlighted green, others
  dimmed) rather than collapsing away — changing an answer is just
  clicking a different visible option.

## Testing pattern used during development

- **Headless smoke tests**: fake minimal `document`/`window` objects in a
  Node one-liner, `eval` `flow-data.js` then `app.js`, call `wosaChoose`/
  `wosaGoto` directly, and inspect the generated `innerHTML` string for
  expected classes/content. Fast, no browser needed, good for verifying
  render-tree logic (auto-select, filter narrowing, CE-upgrade branches).
- **Live browser verification**: needed for anything visual (layout,
  animation, icon rendering) or to catch caching gotchas — the browser
  caches `app.js`/`flow-data.js` separately from `index.php`, so a
  cache-busting query string on the page alone won't bust the script
  cache; a real hard reload is needed after editing JS.
- Always reset state (`wosaReset()`) before ending a test session so the
  next visitor doesn't inherit leftover test state from localStorage.