Files
pages/docs/design/public-navigation.md
T
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

7.5 KiB

Permission-aware public navigation

Implemented 2026-09-16. Ordinary approved public Pages are navigable; the isolated, navigation-free presentation belongs to the future share-URL surface, not normal public semantic URLs. No share tokens/endpoints are added in this slice.

Public surfaces

  • Public Page headers have a Domain home link, breadcrumbs, directory/tree/City links and login. A parent-folder action and child-directory action make Pages with descendants traversable even without a children macro. Mobile headers use labelled icons; keyboard focus and a skip-to-content link are provided; the download button is removed. Existing authorized raw media remains usable.
  • children is expanded to asynchronously fetched, read-only listings, with list/detail/icon modes and lazy continuation. city, breadcrumbs, locality links and spot-pages use public projections. No private diagram/asset job or neighbor-relation expansion is triggered on an anonymous request.
  • GET/HEAD /v/children, /v/tree[/{path}], /v/browser[/{path}], /v/city and /_/api/v1/city/map admit absent credentials under enforcing mode. Invalid or expired credentials still cannot downgrade to anonymous. No new mutation, governance, search, object-hash/UUID or history route is opened.
  • Listings derive from currently approved Path/Object/Revision tuples, using the same live binding/head/governance/topology predicate as body/raw reads. A newly created or edited but unapproved child is not discoverable.
  • Private/absent parent bodies do not block traversal to public descendants: their already-disclosed URL segments become structural folders linking to /v/tree/{path}. This does not authorize the parent Page's body or metadata. Direct semantic requests for a parent (including /) also show the safe directory when it has approved descendants but no approved body. Raw requests never fall back to folders. If there are no approved descendants, the ordinary semantic authentication behavior is retained; explicit /v/browser and /v/tree roots show an empty public index. Unknown/private branches still fail.
  • City topology is filtered to visible branches. Titles/labels are derived from approved Paths, not private locality prose or placement labels; custom descriptions, summaries and relations are suppressed. Page counts and portals use approved Pages only. Unmapped approved Pages remain reachable in the tree.
  • Response HTML and JSON remain private, no-store. A dedicated public header does not expose private bookmarks, account state or administrative controls. Application CSP also covers the public tree and City Map.

Navigation UX hardening — 2026-09-16

  • /v/browser/{path} is a dedicated read-only public directory projection, not the authenticated file manager. Initial entries are server-rendered (120 by default, maximum 400); pagination links work without JavaScript. offset, bounded limit and exclude are retained across continuation. A Page with children has separate open-Page and browse-children links.
  • Tree rows use path-component ordering so /a/x stays within /a, before /a-b. Default all-expanded, per-folder/all collapse, all expand and local name/Path filtering are available. Matching ancestors remain visible. Arrow keys and Home/End move focus; left/right collapse/expand or navigate hierarchy. Filtering is not full-text search and never queries private metadata.
  • Children use the authenticated UI's icon buttons in the same order: ▦ (icon), ☷ (detail), ≡ (list), with matching compact sizing, localized tooltips and accessible names. Controls expose their active state. Only the view preference is stored in sessionStorage, not Paths, names or permissions. At most three fetches run per document; view changes abort old work and generation checks reject late successes and errors. Each fetch times out after 15 seconds and offers a local retry. Page exit aborts outstanding work. Lazy continuation replaces its sentinel; no thumbnail-generation job runs.
  • Macro placeholders offer a directory link without JavaScript. Directory first pages work without it; subsequent batches have ordinary links. Unknown or private names never affect pagination or continuation counts.
  • Public City Map has direct exits to directory/tree, while retaining immersive map navigation. No private search, authoring or planning control is added.
  • Regression coverage includes desktop/mobile Chromium, root/folder/Page round trips, failed-fetch retry, rapidly switched view modes, keyboard/tree prefix collisions, pagination/exclusions, invalid credentials, mutation denial and warm-cache publication withdrawal. No existing publication is auto-enabled.

Cache and permission boundaries

navigation_generation is a SQLite-backed invalidation sequence. Triggers on Paths, Revisions, City topology/placement data, configuration/Domain changes, governance epochs and publication manifests/entries advance it atomically with the mutation. This observes changes from other connections/processes and the CLI, not merely HTTP handler callbacks. It is conservative and global: unrelated Domain changes can invalidate data, rather than risking stale permissions.

Each Server holds at most eight Domain/kind cache entries with a 30-second retention limit. Every hit reads the current database generation. Misses are coalesced per key with cancellable waiters; a generation change while building rejects the mixed snapshot rather than caching it. Public metadata and generic Path catalogs are bounded to 20,000 entries / four MiB; tree depth is bounded to 128 and expanded branch count to 20,000. City uses its existing bounded metadata-only snapshot. No canonical Page bodies enter this cache.

Authenticated City/Path data caches contain data, not permissions. Each request reloads its Principal/group/locality filter before projecting cached data. Group removal must revoke navigation on the next request even when the data generation has not changed. Anonymous approvals are a separate cache kind; authenticated filtered responses are never shared with anonymous requests.

Tree branches are constructed from readable actual Paths. Children filtering and exclusion happen before pagination, so hidden children do not affect totals, continuation or empty pages. Detail/icon metadata queries are restricted to the visible page (at most 400 actual children); private virtual-parent metadata is not fetched. Icons do not enqueue foreground preview jobs.

Public pages/tree reload on BFCache restoration. City clears old rendered labels before revalidation and uses no-store fetches, so a failed refresh does not leave old authorized labels visible. Existing browser-side City geometry caches remain geometry-only; no names, grants or Page bodies are persisted there. Already delivered/in-flight data cannot be recalled; this is next-request invalidation, not a real-time push revocation protocol.

Remaining work

  • Per-Domain fine-grained data generations to reduce conservative misses; cache memory accounting and large-site paging beyond bounded first-slice limits.
  • Public dependency/asset/thumbnail manifests and neighbor relations, approved custom City labels, anonymous search and public named City detail pages.
  • Hierarchical approval requirements and reviewer notification Inbox: design and implementation TODO.
  • Dedicated isolated share-URL presentation with purpose-bound credentials; never reuse public navigation's broader discovery scope for a narrow share.