Files
pages/docs/design/city-immersive-map.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

5.2 KiB
Raw Permalink Blame History

City courtyard projection and immersive navigation

Implemented UI slice, 2026-09-14. Complements City organization and the larger City review; not a replacement for its authorization, reconciliation or Worker hardening work.

Interaction

The browsing sequence is Domain → Quartier → Street → Spot → Page. Clicking a Spot now explores its courtyard inside the map, rather than immediately navigating to its portal document. The central building represents the Spot; surrounding smaller buildings are its Page placements. The focused Spot offers a separate portal Page link. An actual boundary/portal Page is not repeated as its own surrounding Page building. A descendant suggested by the API as a fallback portal remains independently visible/selectable. Undefined placements use a fountain and retain yellow-green Page markers.

Page buildings link to their semantic Path, falling back to /o/uuid:{uuid}. These are rendering changes only: no document Paths, memberships, UUIDs, revisions or contents are changed. The displayed set follows existing SpotGraph membership, including explicit links; it is not a new filesystem hierarchy.

Breadcrumbs and clicking outside the courtyard ascend within the map. Map exploration does not call pushState or add browsing history. Actual Page links still navigate normally (from a map popup, in the containing window). Ctrl/Command selection and the existing merge/rename/move dialogs work for whole Spots and individual Page buildings, without following their links.

Layout and visual vocabulary

  • Domain/Quartier retain the single generated city fabric and its allocations.
  • Street close-ups use a deterministic courtyard layout, with generated road segments projected behind it and paths connecting courtyard gates to roads. This is a readable close-up schematic, not geometric continuity at every zoom level. Connected road allocation and natural parcel packing remain future work.
  • Nonoverlapping plots reserve space for the Spot, six nearby Pages and gates. At most six Spots are rendered per Street screen; further Spots are paginated.
  • A focused Spot renders at most 24 surrounding Pages per screen, also paginated. Page UUID deduplication prevents multiple graph edges creating duplicate houses.
  • Labels remain horizontal and visible at rest, with bounded two-line wrapping and full-name/Path tooltips. The existing label toggle controls the new labels.
  • Native SVG motifs include stucco/terracotta houses, a pediment and colonnade, stone paving, balustrades, cypresses, fountains and ornamental iron gates. Theme-derived stone/brass colors, the academic crest and compass carry the same visual language into the map frame and menu. No external images/fonts or raster-generation service are needed for these additions.

The new city-estates.js module owns only close-up layout and rendering. city-map.js retains topology, navigation, generated fabric and API interaction; city-organizer.js retains selection and mutations. The obsolete geometry script and mutation-observer Spot repositioning no longer run on the map. Pointer dragging and wheel zoom use SVG coordinates with a screen-pixel drag threshold, including differently sized close-up viewBoxes.

Utility menu

The initial normal and popup screens show the map, breadcrumb, menu launcher, small navigation hint, compass and (only when needed) pagination/selection bar. The permanent inspector, directory, planner and toolbar are moved into a themed native modal (city-menu.js):

  • Guide: selected locality, details link and existing editing operations.
  • Directory: named navigation to Quartier/Street/Spot views.
  • Planning, for authorized planners only: URL planning and one creation form at a time, selected by kind.
  • Settings: zoom/reset/labels, topology status, scoped search and account links.

The dialog uses native modal focus containment and Escape dismissal. Its Escape handler does not propagate to the containing map popup. There is no permanent outer-page scrolling; menu content can scroll independently. Mobile CSS reduces the frame and changes the menu navigation to two columns.

Verification and limits

Opt-in Chromium fixtures cover normal/popup modes: resting labels, Ctrl selection, title/group/merge/move regression, plot nonoverlap, six-Spot and 24-Page bounds, full pagination reachability, correct Page/portal links, unchanged map URL/history, menu panel switching, creation-form visibility, directory navigation and background ascent. Screenshots cover sparse Street, dense Spot and menu scenes, including a 390px viewport with Index White. Run:

PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run 'TestCity(Labels|Organizer|Immersive)Chromium' -count=1

These are DOM-rendering bounds, not server/API pagination. The map still loads topology and Page placements eagerly; the directory and some inspector option lists still traverse that loaded topology. Per-result authorization, bounded/lazy server projection, connected roads, Worker generation, keyboard directional navigation and auto-reconciliation remain open in CITY-A–D. This slice does not claim to solve those scaling/security gaps.