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

117 lines
7.5 KiB
Markdown

# 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](publication-approval-inbox.md).
- [ ] Dedicated isolated share-URL presentation with purpose-bound credentials;
never reuse public navigation's broader discovery scope for a narrow share.