Files
pages/docs/design/city-worker-navigation.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

77 lines
4.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# City generation Worker and directional navigation
Implemented bounded CITY-C/D slice, 2026-09-14. Preserves the generated fabric
and [courtyard projection](city-immersive-map.md); this does not replace the
server topology/reconciliation work in [the City audit](city-review-and-reconciliation.md).
## Generation and lifecycle
`city-generator-client.js` retains the asynchronous `PagesWikiGenCity` facade,
but the generator bundle is no longer loaded into the main document. A local
`city-generator-worker.js` imports the rebuilt gen-city 1.4.6 bundle and returns
only numeric roads/building polygons. Its synchronous internals therefore cannot
block browser input or navigation. The Worker is terminated when finished, on
abort/supersession, on page suspension, or after a 5-second deadline. There is
one active generation job per map/client. Same-key requests share the job.
Inputs are limited to a 256-character stable Domain key and integer dimensions
64–320 by 64–240 (the map requests 240 by 160). The adapter and Worker enforce
these bounds; returned geometry is limited to 4,096 roads, 4,096 buildings and
16 finite vertices per building. The main-thread deadline can kill runaway
synchronous Worker code without waiting for it to process a cancellation message.
The base seed is the Domain UUID, not a topology version or membership count.
Geometry-only caches use the generator/layout version, Domain UUID and dimensions
as their key. Memory and sessionStorage each retain at most three fabrics; a
serialized storage entry must fit 512 KiB. Storage denial, quota exhaustion and
corruption do not disable generation. No Page names, Paths, grants, topology
or principal information are cached here. Authorized API results remain separate.
The map aborts superseded fetches and discards late render responses. `pagehide`
cancels fetch/generation; BFCache `pageshow` reloads the authorized model and
reuses valid geometry. An unsupported/blocked Worker, timeout or malformed result
shows a retry action and error without executing gen-city synchronously as a
fallback. Utility menus remain usable; this is not a claim that the map works
without Workers. The SVG exposes its busy state to assistive technology.
## Keyboard interaction
`city-navigation.js` handles directional focus over currently visible Quartier,
Street, Spot entry, Page/portal links and overflow controls:
- Arrow keys, WASD and HJKL choose the nearest useful candidate in the requested
screen-space direction; there is no arbitrary wrap across the map.
- Enter/Space activates the focused element. Repeated activation keydown is
suppressed to avoid drilling through multiple levels while a key is held.
- Backspace moves to the parent locality and restores the former child's focus.
At the Domain level it stays in the map. It never calls browser back/history.
- Ctrl/Command/Alt shortcuts, IME composition, editable fields, controls outside
the map, open modals and context menus are not consumed. Ctrl selection and
existing dialogs continue to work. Escape remains available to the containing
popup/menu rather than being repurposed for hierarchy navigation.
The existing mouse, semantic Page hrefs, popup top-window Page navigation,
horizontal labels and courtyard design are unchanged. Navigation changes local
view state only; actual Page links still navigate normally.
## Verification and remaining limits
Opt-in Chromium tests run in normal and popup modes with the real Worker and
real gen-city output. They cover stable repeated seeds, a deliberately busy
Worker while main-thread timers keep running, timeout/abort/supersession,
stale messages, storage bounds, invalid results and pagehide/BFCache resumption.
Keyboard tests cover all key families, semantic Page activation, focus restoration,
modifier/IME/editing/modal exclusion and unchanged URL/history. Existing label,
organization, immersive/pagination and mobile-light-theme fixtures still pass:
```sh
PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run 'TestCity(Labels|Organizer|Immersive|Keyboard|Worker)Chromium' -count=1
```
This isolates base-fabric generation, not all City work. Topology-to-road
allocation, SVG DOM construction and loaded directory/inspector options remain
on the main thread. Connected road allocation, lazy locality projections and
larger-scale DOM virtualization remain separate tasks. A future server-side
geometry cache could share work across tabs/devices; no cross-tab worker pool
or server generation scheduler is introduced here.