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.
77 lines
4.4 KiB
Markdown
77 lines
4.4 KiB
Markdown
# 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.
|