@jini-ai/ui 0.3.14 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# @jini-ai/ui
+
+## 0.4.0 — 2026-10-02
+
+### BREAKING
+
+- Query cache clocks use core and browser fetch is injected. Product theme/process documents are archived; stylesheet exports remain explicit side effects.
+- Distribution includes runtime output, release documentation and required assets only. Process records and per-job neutrality checks are no longer part of the package surface.
+
+## Unreleased
+
+- Publish the browser entry `@jini-ai/ui/tab-strip` with types and ESM output from
+  the existing feature barrel, including `TabBar` and `TabBarTab`.
+
+- Align A2UI catalog/clock fixtures and MCP-UI RPC calls with the current agentic API; omit absent optional fetch properties to preserve strict optional-property typing and browser defaults.
+- BREAKING: remove the obsolete `A2uiClockPort` type re-export from `/a2ui`; consumers use `Clock` from `@jini-ai/core/primitives`.
+
+- BREAKING: `exportViaHttp` takes `{ exportPath, filenamePrefix }` and optional `{ fetch }`. Browser transports accept native fetch ports and no longer depend on platform; timeout errors now retain native reasons. Add `createMemoryHttpPorts`; neutralize obsolete connector-vendor references.
+
+- Adopt shared kernel contracts and preserve the module rationale in neutral documentation.
+- BREAKING: replace package-local clock contracts with core Clock.nowMs().
+
+
+### UI parity fixes
+
+- Keep replacement writes successful when an older read rejects, including their freshness timestamp.
+- Wire A2UI actions to each interactive provider's documented callback; custom registry entries may
+  declare an optional `actionProp`. Existing unannotated custom table callbacks remain compatible.
+- Re-render A2UI descendants and bound data when the root identity is unchanged; cache stable surface
+  snapshots so unrelated notifications do not re-render unchanged surfaces.
+- Clarify that parked iframes stay in a mounted container and missing crypto fails on token mint.
+- Pass notice handles through the current named agent API and use the declared tab-count font token.
+- Restart cached background reads on explicit refresh/invalidation; ignore superseded responses,
+  invalidate failed reads, reset initial retry errors, and reject undefined query data.
+- Pause offline reads and writes, resume them once online, and refresh stale enabled reads on reconnect.
+  Connectivity and opt-in focus events are injectable through `FetchQueryEnvironmentPort` on the provider.
+  The ten-second freshness, no automatic failure retries, and focus-disabled defaults are unchanged.
+
+### Integrated entry points
+
+- Publish and declare browser runtimes for `/admin-widgets`, `/panel-kit`, `/fetch-query`,
+  and `/admin-widgets.css`; `/core`, `/interactive-ui/manifests` and `/mcp-ui/surfaces` are universal. No new dependencies or version bump.
+- Align internal agent handle and A2UI interpreter calls with the current agentic ports.
+- Use neutral `data-jini-*` canvas markers for transient editor chrome.
+
+### BREAKING — public ui argument convention
+
+- Shared clipboard, endpoint, SSE, color/accent and wheel helpers now take named required objects.
+- Shared font, debounce, stable-handler, dismissal and global-keydown hooks split required and
+  optional objects; effect dependencies can be injected as ports. The font asset URL resolver
+  now takes `{ projectId, path }`.
+- `InteractiveUiRegistry` constructor and lookup/registration methods,
+  `buildA2uiCatalogFromRegistry`, and `AssetTreeClipboardPort.copyToClipboard` take object arguments.
+- Admin widget helpers, tab keyboard helpers, dictionary/template helpers and panel hooks take
+  required objects and separate optional configuration. The dictionary translator returned by
+  `createDictionaryTranslator` takes `{ locale, key }`. Panel controllers take `{ action, describeError }`,
+  `{ task }`, or `{ generation }`; dirty confirmation accepts `({}, { unsavedBeyondTracked })`.
+- Fetch-query hooks split required key/fetch/run dependencies from optional cache configuration.
+  Mutation, invalidation and loader replacement take `{ input }`, `{ key }`, and `{ value }`.
+- `RendererRegistry` creation/registration and manifest resolution use named objects; optional
+  resolution hints move to the second object, including the renderer matching port.
+- Canvas chrome attributes change to `data-jini-*`; hosts selecting the old attributes must update.
+
+
+- Add generic admin widgets with opt-in `@jini-ai/ui/admin-widgets.css`, using the existing
+  `--jini-*` tokens with standalone fallbacks. `TabBar` joins the existing `tab-strip` feature
+  and shares its tablist shell; existing `TabStrip` exports and behavior remain available.
+- Add a panel kit with focus trapping, unsaved-change protection, async actions, serial writes,
+  settlement generations, display helpers, and injected dictionary translators. Translation
+  and retry classification are supplied by the host; no product dictionaries or API client move.
+- Add a React-only fetch-query adapter behind `@jini-ai/ui/fetch-query` and `/panel-kit`,
+  preserving the keyed query contract without a new runtime dependency or optional peer.
+  All existing exports remain available; the version is reserved for the wave coordinator.
+
+## 0.1.2
+
+### Patch Changes
+
+- Add top-level `main`/`types` fields alongside the existing `exports` map. A consumer on
+  TypeScript's classic `moduleResolution: "node"` (node10) — which ignores `package.json#exports`
+  entirely — could not resolve this package's types at all (`TS2307: Cannot find module`) even
+  after the previous exports-map fix restored `require()` at runtime; type resolution and runtime
+  resolution are separate algorithms. Verified against a real external consumer (whose
+  tsconfig uses this legacy resolution mode): adding these two fields, with its tsconfig completely
+  unchanged, made the error disappear. Also fixes absolute-path `require()` (distinct from a bare
+  specifier, which already worked) for the same reason — `main` was previously absent.
+
+  Purely additive: every modern resolver (Node's own runtime `exports` resolution, TypeScript's
+  `bundler`/`node16`/`nodenext`) prefers `exports` over `main`/`types` when both are present, so
+  this changes nothing for a consumer already on a modern resolver.
+
+- Updated dependencies
+  - @jini-ai/renderers-react@0.1.2
+  - @jini-ai/agentic@0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Add a `"default"` export condition to every published package's `exports` map — every one of
+  them lacked it, which meant `require()` failed with `ERR_PACKAGE_PATH_NOT_EXPORTED` for any
+  CommonJS consumer (found via a real external integration attempt; Node needs `require(esm)`
+  support, i.e. Node >=22.12, for this to resolve).
+
+  `@jini-ai/agent-runtime`:
+
+  - **New**: `RuntimeBuildOptions.permissionMode` (`'bypass' | 'restricted'`) lets a caller opt a
+    run OUT of the auto-approve-every-permission-prompt flag every def with one
+    (`bypassPermissions` / `--yolo` / `--dangerously-skip-permissions`) previously pushed
+    unconditionally, with no way to turn it off. Omitting it keeps today's default (bypass)
+    behavior unchanged.
+  - **New**: `ClaudeStreamEvent`, `CopilotStreamEvent`, and `QoderEvent` are now real exported
+    discriminated unions instead of `Record<string, unknown>` — a real external consumer guessed a
+    nonexistent field name (`event.text` instead of the actual `event.delta`) against the old
+    untyped sink and silently lost every streamed token with no compile or runtime error.
+  - Fixed a doc/implementation mismatch in `claude-stream.ts`: the module doc claimed `tool_result`
+    events carry `{ tool_use_id, content, is_error }`; the actual emitted shape is
+    `{ toolUseId, content, isError }`.
+
+  `@jini-ai/daemon`: `AgentExecutorRunInput.permissionMode` forwards the new
+  `RuntimeBuildOptions.permissionMode` through to `buildArgs`, so a host can actually reach the new
+  opt-out from the daemon's real run-input surface, not just from `@jini-ai/agent-runtime` in
+  isolation.
+
+  `@jini-ai/agentic`: `setAtPointer` no longer throws on a malformed (e.g. missing leading `/`)
+  `updateDataModel` path — degrades to a no-op like its sibling `getAtPointer`, matching this
+  package's own "a bad binding must not crash the renderer" contract. That path is agent-authored
+  wire data with no error boundary above it in any host, so the uncaught throw could unmount an
+  entire chat UI from ~40 bytes of malformed input.
+
+  `@jini-ai/chat-react`: a local (client-resolved) A2UI button action is no longer a silent no-op —
+  `A2uiSurfaceCard` now surfaces the resolved value. New `ExtEventErrorBoundary` confines a
+  `kind: 'ext'` event group's renderer to its own card instead of letting a render/effect-phase
+  throw from agent-controlled content unmount the whole chat root (there was no error boundary
+  anywhere in this package or its hosts before this).
+
+- Updated dependencies
+  - @jini-ai/renderers-react@0.1.1
+  - @jini-ai/agentic@0.1.1

package/README.md

@@ -18,12 +18,12 @@ vocabulary.
 brand/plugin/figma-specific components. Those stay in
 `foundry/integrations/open-design/` as OD's own UI if/when that adapter needs them.
 `SettingsDialog` itself is one of these (its `execution`/`orbit`/`media`/
-`composio`/`critiqueTheater`/`pet`/`designSystems`/`projectLocations`/
+`connector-provider`/`critiqueTheater`/`pet`/`designSystems`/`projectLocations`/
 `routines`/`about` tabs and its AMR/autosave shell state stay OD-specific) —
 but its reusable tabbed-dialog *shell* and 6 of its small, clean, generic
 tabs (`appearance`, `notifications`, `language`, `instructions`,
 `integrations`, `privacy`) shipped as `src/features/settings-dialog/`; see
-`packages/ui/source-map.md`.
+the archived provenance ledger.
 Also not here: chat/artifact UI — that's `@jini-ai/chat`'s `./core` and `./react` subpaths (the
 former standalone `@jini-ai/chat-core` package was retired into `./core` on 2026-08-03), and this
 package's own `./renderers` subpath (the artifact-renderer registry, once planned as a separate
@@ -52,7 +52,7 @@ package's own React layer. See the chat-core/chat-react split discussion in
   split: not "prepare for a Vue consumer" (no such consumer exists or is
   planned), just keeping the pure layer visibly and mechanically separate
   from the React layer within one package, at effectively zero cost. See
-  `packages/ui/source-map.md`'s `features/connectors/` section for the
+  the archived provenance ledger's `features/connectors/` section for the
   worked example. **Retrofitted onto the flat `src/components/` bucket
   (2026-07-18, now `src/react/components/`)**; `src/hooks/` below is not —
   it still sits at the top level; revisit if this pattern proves worth
@@ -67,7 +67,7 @@ package's own React layer. See the chat-core/chat-react split discussion in
 - `src/utils/` — non-component pure helpers and small stateful browser-API
   wrappers that don't need the full ports+dependencies ceremony. Added in the
   i18n/observability/utils porting task (2026-07-16); see
-  `packages/ui/source-map.md`.
+  the archived provenance ledger.
 
 ## `./core` — the framework-free half, importable without React
 
@@ -82,7 +82,7 @@ This used to be a genuinely separate package, `@jini-ai/ui-core`, until it becam
 earned that: it was always the framework-free half of *this* package's features, and its own name
 — "core of the UI package" — gave no hint that it was one half of a per-feature split. Folded back
 in here 2026-08-01, once that confusion cost real time (including for the person who built it).
-`packages/ui/source-map.md` has the dated entry.
+the archived provenance ledger has the dated entry.
 
 ### Feature map
 
@@ -162,7 +162,7 @@ package.
 ## Status
 
 Real content has landed in several parallel passes — see
-`packages/ui/source-map.md` for full per-section provenance:
+the archived provenance ledger for full per-section provenance:
 
 - `src/utils/` — a framework-free DOM/pure-function layer (2026-07-16), plus
   a second batch (i18n/observability-adjacent utils: notifications, uuid,
@@ -185,7 +185,7 @@ Real content has landed in several parallel passes — see
   viewport-preset switcher, and ports for `onNavigate`/history storage/
   brand-bridge registration) — not the full file. The first feature to use
   the new `react/{hooks,components}/` layout described above. See
-  `packages/ui/source-map.md` for the full breakdown, including a confirmed
+  the archived provenance ledger for the full breakdown, including a confirmed
   duplicate with `FileViewer.tsx`'s (not-yet-ported) viewport controls.
 - `src/features/sketch-editor/` — `SketchEditor.tsx`'s Excalidraw-integration
   shim (2026-07-17), per the god-components-extraction-plan.md Consolidation
@@ -214,9 +214,11 @@ Real content has landed in several parallel passes — see
   — extracted from `SettingsDialog.tsx` (2026-07-17), per
   `ADS-memory/reports/jini-port/god-components-extraction-plan.md` item 5. Uses the NEW
   `react/{hooks,components}` layout (this is the first feature built with it
-  from scratch). See `packages/ui/source-map.md`.
+  from scratch). See the archived provenance ledger.
 - `src/features/tab-strip/` — a consolidated draggable/reorderable tab-strip
-  primitive (2026-07-18), per `ADS-memory/reports/jini-port/god-components-extraction-plan.md`'s
+  primitive, published through the browser entry `@jini-ai/ui/tab-strip`, including
+  `TabBar`, `TabBarProps`, `TabBarTab`, `TabStrip`, `TabStripItem`, and their hooks.
+  The feature was consolidated (2026-07-18), per `ADS-memory/reports/jini-port/god-components-extraction-plan.md`'s
   Consolidation map §A `features/tab-strip/` row: `WorkspaceTabsBar.tsx`'s
   workspace-tab strip and `FileWorkspace.tsx`'s independently-reimplemented
   inline `Tab` component (r6 confirms these are two divergent
@@ -227,7 +229,7 @@ Real content has landed in several parallel passes — see
   option and pinned-tab drop-edge coercion), active/close-button
   affordances, host-injected tab content. A dual-shape test proves both
   source interaction shapes work correctly through the same code paths, not
-  just that they compile. See `packages/ui/source-map.md`.
+  just that they compile. See the archived provenance ledger.
 - `src/features/list-detail-panel/` — a generic `ListDetailPanel<TItem>`
   master-detail (list+preview) navigator shell, ported from
   `DesignSystemsTab.tsx` (2026-07-18), per
@@ -236,12 +238,12 @@ Real content has landed in several parallel passes — see
   read and confirmed NOT to share this shape (a portal overlay and a
   resizable 2-pane split, respectively) — scoped to `DesignSystemsTab.tsx`
   alone rather than forcing a broader generalization. See
-  `packages/ui/source-map.md`.
+  the archived provenance ledger.
 - 10 more `src/components/` flat atoms (2026-07-18) — the Section C
   bucket-A batch from `NewProjectPanel.tsx` (`OptionCards`, `CompactToggle`,
   `ToggleRow`), `PluginsView.tsx` (`StatCard`, `Notice`, `ImportChoice`,
   `FileImportPanel`), and `EntryShell.tsx` (`OnboardingPanelHeader`,
-  `OnboardingChipField`, `OnboardingDropdown`). See `packages/ui/source-map.md`.
+  `OnboardingChipField`, `OnboardingDropdown`). See the archived provenance ledger.
 - `src/features/memory/` — ported from OD's never-merged PR #5228 (a
   vertical-slice decomposition of `MemorySection.tsx`, 2026-07-18): the
   saved-memory list/editor, the extraction-history stream, and the
@@ -250,7 +252,7 @@ Real content has landed in several parallel passes — see
   independently confirmed pre-existing in OD's original monolith, not
   introduced by the decomposition), plus one additional fix
   (`fetchMemoryList()`'s under-validated response) made during this port. See
-  `packages/ui/source-map.md` for the full provenance note, including why its
+  the archived provenance ledger for the full provenance note, including why its
   connector-reconciliation reducers reuse `features/connectors/rules.ts`
   instead of re-deriving a third copy.
 
@@ -260,14 +262,14 @@ Real content has landed in several parallel passes — see
   `ADS-memory/reports/jini-port/god-components-extraction-plan.md`'s Consolidation map.
   Also added flat `src/components/{PillButton,PopoverMenu,PopoverItem}.tsx`
   and `src/utils/timezone.ts`, both from the same source file. See
-  `packages/ui/source-map.md`.
+  the archived provenance ledger.
 - `src/features/mention-autocomplete/` — `MentionAutocomplete`, a generic
   "type a trigger character, get a filtered picker" mention/capability
   autocomplete (2026-07-18), also ported from `NewAutomationModal.tsx`, per
   the same Consolidation map row. Checked against `QuickSwitcher.tsx` and
   the `composer/*` Lexical `@mention` system for a possible 3-way overlap —
   concluded they're three distinct shapes, not one primitive done three
-  times; see `packages/ui/source-map.md` for the full comparison (read that
+  times; see the archived provenance ledger for the full comparison (read that
   section before extracting either of those two).
 
 - `src/react/components/EditorIcon.tsx` (2026-07-18) — a flat icon-by-key
@@ -276,7 +278,7 @@ Real content has landed in several parallel passes — see
   `src/react/components/` path (the `refactor/ui-flat-components-under-react`
   rename hadn't landed on this branch's base yet, so this is a new folder
   alongside the still-present flat `src/components/`). See
-  `packages/ui/source-map.md`.
+  the archived provenance ledger.
 - `src/features/iframe-pool/` — a generic, host-configurable "cap N mounted
   iframes, LRU-evict inactive ones, park the rest off-DOM" pool (2026-07-18),
   ported from `IframeKeepAlivePool.tsx` per
@@ -287,7 +289,7 @@ Real content has landed in several parallel passes — see
   `OD_PREVIEW_KEEP_ALIVE` env-var toggle. Fixed two real bugs found while
   porting (a missing `px`-unit append on numeric style values, and a reused
   parked iframe never having its hidden/inert markers undone) — see
-  `packages/ui/source-map.md`.
+  the archived provenance ledger.
 - `src/features/command-palette/` — `CommandPalette`, a generic Cmd/Ctrl+P
   fuzzy file-and-item palette (2026-07-18), ported from `QuickSwitcher.tsx`.
   Collapses the origin's file/tab discriminated union into one
@@ -295,7 +297,7 @@ Real content has landed in several parallel passes — see
   `localStorage`-backed `CommandPaletteRecentsPort`. Confirmed distinct from
   `features/mention-autocomplete/` (already checked in that feature's
   source-map section) rather than re-litigated. See
-  `packages/ui/source-map.md`.
+  the archived provenance ledger.
 - `src/features/tab-launcher-menu/` — `TabLauncherMenu`, an anchored,
   portal-rendered "+"-button command-palette dropdown (2026-07-18), ported
   from `TabLauncherMenu.tsx`. Generic `TabLauncherResultItem` shared by both
@@ -304,21 +306,21 @@ Real content has landed in several parallel passes — see
   OD-specific `LauncherContext`. `features/tab-strip/` does not exist on
   this branch despite the extraction plan describing it as already shipped
   — documented as a discrepancy, matching the same pattern already recorded
-  for `features/progress-card/`. See `packages/ui/source-map.md`.
+  for `features/progress-card/`. See the archived provenance ledger.
 - `src/features/revision-review/` — `RevisionDiffCard`/`RevisionHistoryList`,
   a generic "proposed change review" widget (2026-07-18), ported from
   `DesignSystemFlow.tsx`'s remaining pieces. Genericizes `DesignSystemRevision`
   to `RevisionReviewItem<TMeta>`; unifies the origin's two duplicate diff
   functions into one `diffAddedLines`. Confirmed distinct from
   `features/progress-card/` rather than folded in. See
-  `packages/ui/source-map.md`.
+  the archived provenance ledger.
 - `src/react/components/{TokenChip,ValueChip,ComponentKitPreview}.tsx`
   (2026-07-18) — the rest of `DesignSystemFlow.tsx`'s remaining pieces: a
   color-swatch chip, a plain-value chip, and the theme-toggle-driven
   style-guide preview panel that renders both, with the token source
   genericized to host-injected data (the origin's markdown-parsing pipeline
   is not ported). Reuses the already-shipped `utils/color-math.ts` rather
-  than re-deriving its math a second time. See `packages/ui/source-map.md`.
+  than re-deriving its math a second time. See the archived provenance ledger.
 - `src/features/file-dropzone/` — `FileDropzone`, a consolidated file-staging
   primitive (2026-07-18) ported from **two** independent OD file-staging
   zones — `DesignSystemAssetDropzone.tsx` (a kind-aware thumbnail grid +
@@ -329,7 +331,7 @@ Real content has landed in several parallel passes — see
   utilities the two features already duplicated a third time (from
   `features/asset-tree-browser/rules.ts`) up to `utils/file-transfer.ts` and
   `browser/useFileDropTarget.ts`, so this package now has exactly one copy.
-  See `packages/ui/source-map.md` for the consolidation evidence, a real
+  See the archived provenance ledger for the consolidation evidence, a real
   infinite-render-loop bug found and fixed during this port, and full
   test/coverage numbers.
 - `src/features/folder-path-drop/` (2026-09-14) — dropping a folder onto a
@@ -337,20 +339,20 @@ Real content has landed in several parallel passes — see
   `webUtils.getPathForFile` as a `FolderPathDropPort`) inserts the folder's
   absolute path as text instead of uploading its contents. The
   framework-free rules are also on `./core`; `useFolderPathDropCapture`
-  returns a stable `onDropCapture` handler. See `packages/ui/source-map.md`.
+  returns a stable `onDropCapture` handler. See the archived provenance ledger.
 - `src/utils/scroll-tabs-with-wheel.ts` and `src/utils/color-math.ts`
   (2026-07-18) — two flat bucket-A atoms from
   `ADS-memory/reports/jini-port/god-components-extraction-plan.md`'s Consolidation map §C:
   a generic wheel-to-horizontal-scroll handler for an overflowing tab strip
   (from `FileWorkspace.tsx`'s `scrollWorkspaceTabsWithWheel`) and hex/RGB/
   luminance/mix color-math primitives (from `DesignSystemFlow.tsx`). See
-  `packages/ui/source-map.md` for the full writeup, including what was
+  the archived provenance ledger for the full writeup, including what was
   deliberately left behind (the OD-specific color-selection heuristic that
   consumes the math, not the math itself).
 - `src/features/lexical-rich-text-editor/` (renamed from `rich-text-input/`,
   2026-07-26 — the feature is Lexical specifically, not a general rich-text
   input, so the old name promised an engine-neutrality its Lexical-shaped API
-  never had; see `packages/ui/source-map.md`'s dated rename entry) — a real Lexical (Meta's
+  never had; see the archived provenance ledger's dated rename entry) — a real Lexical (Meta's
   rich-text framework) editor integration ported from OD's chat composer
   (2026-07-18): editor setup/config, an atomic `@mention`/`/command`
   token node type (generic, host-injected `resolveMentionColor` instead of
@@ -358,7 +360,7 @@ Real content has landed in several parallel passes — see
   positioning hook/component, and serialize/deserialize between the
   editor's document model and a plain `@token` string. Named by three
   prior tasks (`mention-autocomplete`'s own "3-way overlap" note among
-  them) as this exact destination. See `packages/ui/source-map.md`,
+  them) as this exact destination. See the archived provenance ledger,
   including four dead branches found and refactored away during the
   coverage-driven-refactor loop (a `mention-parser.ts` merge pass, a
   `rules.ts` selection catch-all, a `useSeededValue` StrictMode guard, and
@@ -373,3 +375,95 @@ Consolidation map's naming-reconciliation note) and `rich-text-input`
 (renamed `lexical-rich-text-editor`, 2026-07-26) are now landed, per above —
 no longer in this "not started" list. The god-components-extraction-plan.md
 list beyond the features enumerated above is also not started.
+
+## Integrated widgets and panel APIs
+
+See [API-CONVENTION.md](./API-CONVENTION.md) for the widget, panel-kit, fetch-query, port and
+object-argument API shapes, including the breaking changes collected in [CHANGELOG.md](./CHANGELOG.md).
+
+
+## Theming the admin
+
+Import `@jini-ai/ui/styles/admin.css` for the variable contract, admin aliases and widgets.
+For a custom layout that needs only the contract, import `@jini-ai/ui/styles/variables.css`.
+The existing `admin-widgets.css`, `tabbed-dialog.css` and `settings-dialog.css` subpaths remain.
+`@jini-ai/tokens` has been removed; no alias package is provided.
+
+`@jini-ai/ui/theme` exports `AdminTheme`, `defaultAdminTheme`, `validateAdminTheme`,
+`applyAdminTheme` and `resolveColorScheme`. A theme supplies `name`, body/heading fonts, an
+optional mono font and font stylesheet URLs, complete light/dark palettes, and optional base
+radius/density. The ten palette fields are `primary`, `primaryInk`, `bg`, `surface`, `text`,
+`muted`, `border`, `danger`, `success` and `warning`. Existing variable names derive from this
+compact contract. Palettes accept concrete hex, RGB/HSL/OKLCH/OKLab/Lab/LCH values or basic
+color keywords; URLs, dependent variables, injected declarations and incomplete palettes fail
+validation. Radius is a nonnegative px/rem/em length; density is a multiplier from 0.5 to 2.
+The validator reports `{ valid, theme }` or `{ valid, errors }`; applying an invalid theme throws
+before any DOM mutation. Neutral defaults hold no product brand.
+
+```tsx
+import '@jini-ai/ui/styles/admin.css';
+import { defaultAdminTheme } from '@jini-ai/ui/theme';
+import { AdminShell } from '@jini-ai/admin/react/shell';
+
+// The host supplies its document and storage adapters, along with the existing shell props.
+const themeEnvironment = {
+  target: document.documentElement,
+  document,
+  matchMedia: window.matchMedia.bind(window),
+};
+
+<AdminShell {...hostShellProps}
+  theme={defaultAdminTheme}
+  themeEnvironment={themeEnvironment}
+  themePreferenceStore={hostUserPreferenceStore}
+/>;
+```
+
+The preference store implements `read({ userId, workspace })` and
+`write({ userId, workspace, preference })`; reads return `light`, `dark`, `system` or `null`.
+The host owns persistent storage and keys. No user preference is written during mounting.
+Authenticated slots receive `appearance`, including `setPreference({ preference })`, so the
+host provides its own picker and labels. `colorScheme` makes the setting controlled when supplied;
+`onColorSchemeChange({ preference })` tells that host to update it. Without a controlled prop,
+the shell restores the user's stored choice or follows the system. User/workspace changes discard
+the previous user's selection.
+
+For other layouts call `applyAdminTheme({ theme }, { target, document })`; its cleanup restores
+the scope and releases owned font links, with deduplication across active themes. Then call
+`resolveColorScheme({ preference }, { matchMedia })` and set the target's `data-color-scheme`
+attribute to the returned `light` or `dark`. A `system` preference requires the injected media
+port. `AdminShell` subscribes to system changes and cleans up on unmount. Inject the document
+root when components portal so dialogs share the palette. Former `data-theme` attributes must be
+migrated to this resolved attribute. Independent theme scopes can use different target elements.
+
+The `ZANA-THEME.md` and `the host-THEME.md` files preserve product data for later host adoption;
+they are documentation, not runtime themes. Derived ramps/radius scales and the neutral defaults
+change the previous look, so review both schemes during adoption. Verification was not run in the
+extraction job at the owner's direction.
+
+## Design decisions
+
+- [Reusable navigation hooks own state while the host owns effects](docs/decisions/DR-001-state-hooks-effect-ownership.md).
+
+## Kernel contracts
+
+Fetch-query caches accept the shared `Clock` from `@jini-ai/core/primitives` through
+`new FetchQueryCache({}, { clock })`; clocks implement `nowMs()`. Freshness remains ten seconds
+by default and idle retention five minutes. Browser HTTP defaults now use injected
+native fetch ports and have no platform imports.
+
+The A2UI interpreter uses that same core `Clock` with `nowMs()`; import the clock type
+directly from `@jini-ai/core/primitives`. The obsolete `A2uiClockPort` re-export is removed.
+Create the basic catalog with `createLabCatalog({})` and inject it through
+`createA2uiInterpreter({ catalog, clock, ids })`.
+
+## Browser transport ports
+
+`useBrandFonts({ fonts }, { fetch?, manifest?, ... })` and
+`ExportDiagnosticsButton`'s `fetch` prop accept native fetch implementations.
+Memory's `createMemoryHttpPorts({}, { fetch? })` returns `{ config, entries, extractions }`;
+pass these ports to the existing feature hooks. Omitted fetch uses `globalThis.fetch`.
+Quick requests abort after 15 seconds and archive downloads after 120 seconds;
+a caller signal is combined with the timeout. Browser failures retain native abort
+reasons, including `TimeoutError`, rather than platform's `FetchTimeoutError`.
+The package no longer depends on platform. Connector examples are vendor-neutral.

package/dist/browser/index.js

@@ -1,7 +1,7 @@
 // @jini-ai/ui/browser — small, generic browser-interaction hooks shared across
 // feature extractions (popovers/dialogs dismissing on outside-click/Escape,
 // global keydown shortcuts scoped to a component's active lifetime). See
-// packages/ui/source-map.md for the extractions that motivated this and
+// packages/ui/archived provenance ledger for the extractions that motivated this and
 // AGENTS.md's `packages/ui` entry for how this directory relates to
 // `utils/`, `hooks/`, and `components/`.
 export * from './useDismissOnOutsideOrEscape.js';

package/dist/browser/useDismissOnOutsideOrEscape.d.ts

@@ -1,5 +1,6 @@
 import type { RefObject } from 'react';
 export interface UseDismissOnOutsideOrEscapeOptions {
+    subscription?: DismissSubscriptionPort;
     /** Skip attaching any listeners while `false` (e.g. only while a menu is open). Defaults to `true`. */
     enabled?: boolean;
     /**
@@ -10,9 +11,17 @@ export interface UseDismissOnOutsideOrEscapeOptions {
      */
     containerRef?: RefObject<HTMLElement | null>;
 }
+export interface DismissSubscriptionPort {
+    subscribe(requiredArgs: {
+        containerRef: RefObject<HTMLElement | null> | undefined;
+        onDismiss: () => void;
+    }): () => void;
+}
 /**
  * Calls `onDismiss` on a `pointerdown` outside `options.containerRef` (when
  * supplied) or on the Escape key anywhere. A no-op outside the browser (SSR).
  */
-export declare function useDismissOnOutsideOrEscape(onDismiss: () => void, options?: UseDismissOnOutsideOrEscapeOptions): void;
+export declare function useDismissOnOutsideOrEscape({ onDismiss }: {
+    onDismiss: () => void;
+}, options?: UseDismissOnOutsideOrEscapeOptions): void;
 //# sourceMappingURL=useDismissOnOutsideOrEscape.d.ts.map

package/dist/browser/useDismissOnOutsideOrEscape.js

@@ -22,12 +22,15 @@
 // indirection so callers don't have to memoize `onDismiss`.
 import { useEffect, useRef } from 'react';
 import { subscribeOutsideClickOrEscape } from '../utils/dom-subscriptions.js';
+const browserSubscription = {
+    subscribe: ({ containerRef, onDismiss }) => subscribeOutsideClickOrEscape(containerRef, onDismiss),
+};
 /**
  * Calls `onDismiss` on a `pointerdown` outside `options.containerRef` (when
  * supplied) or on the Escape key anywhere. A no-op outside the browser (SSR).
  */
-export function useDismissOnOutsideOrEscape(onDismiss, options = {}) {
-    const { enabled = true, containerRef } = options;
+export function useDismissOnOutsideOrEscape({ onDismiss }, options = {}) {
+    const { enabled = true, containerRef, subscription = browserSubscription } = options;
     // Latest-ref indirection so callers don't need to memoize `onDismiss` for
     // the subscription effect below to stay attached with fresh behavior.
     const onDismissRef = useRef(onDismiss);
@@ -37,7 +40,7 @@ export function useDismissOnOutsideOrEscape(onDismiss, options = {}) {
     useEffect(() => {
         if (!enabled)
             return;
-        return subscribeOutsideClickOrEscape(containerRef, () => onDismissRef.current());
-    }, [enabled, containerRef]);
+        return subscription.subscribe({ containerRef, onDismiss: () => onDismissRef.current() });
+    }, [enabled, containerRef, subscription]);
 }
 //# sourceMappingURL=useDismissOnOutsideOrEscape.js.map

package/dist/browser/useGlobalKeydown.d.ts

@@ -1,5 +1,15 @@
-export declare function resolveGlobalKeydownTarget(target: 'window' | 'document'): EventTarget | undefined;
+export declare function resolveGlobalKeydownTarget({ target }: {
+    target: 'window' | 'document';
+}, { globals }?: {
+    globals?: {
+        window?: EventTarget;
+        document?: EventTarget;
+    };
+}): EventTarget | undefined;
 export interface UseGlobalKeydownOptions {
+    resolveTarget?: (requiredArgs: {
+        target: 'window' | 'document';
+    }) => EventTarget | undefined;
     /** Skip attaching the listener while `false` (e.g. only while a surface is active/mounted-and-open). Defaults to `true`. */
     enabled?: boolean;
     /** Listener target. Defaults to `'window'`. */
@@ -12,5 +22,7 @@ export interface UseGlobalKeydownOptions {
  * `true`, removing it on cleanup or when `enabled` flips to `false`. A no-op
  * outside the browser (SSR).
  */
-export declare function useGlobalKeydown(handler: (event: KeyboardEvent) => void, options?: UseGlobalKeydownOptions): void;
+export declare function useGlobalKeydown({ handler }: {
+    handler: (event: KeyboardEvent) => void;
+}, options?: UseGlobalKeydownOptions): void;
 //# sourceMappingURL=useGlobalKeydown.d.ts.map

package/dist/browser/useGlobalKeydown.js

@@ -15,19 +15,19 @@ import { useEffect, useRef } from 'react';
 // a direct unit test — driving it through a real `renderHook` mount hits
 // React DOM internals that themselves dereference `window` well before this
 // hook's own effect ever runs, making that branch unreachable via a
-// rendered test (see packages/ui/source-map.md's 2026-07-22 dated entry;
+// rendered test (see packages/ui/archived provenance ledger's 2026-07-22 dated entry;
 // same "extract into a directly-testable pure function" precedent as
 // `@jini-ai/mcp`'s `oauth.ts` readCappedText).
-export function resolveGlobalKeydownTarget(target) {
-    return target === 'document' ? globalThis.document : globalThis.window;
+export function resolveGlobalKeydownTarget({ target }, { globals = globalThis } = {}) {
+    return target === 'document' ? globals.document : globals.window;
 }
 /**
  * Attaches `handler` as a `keydown` listener for as long as `enabled` stays
  * `true`, removing it on cleanup or when `enabled` flips to `false`. A no-op
  * outside the browser (SSR).
  */
-export function useGlobalKeydown(handler, options = {}) {
-    const { enabled = true, target = 'window', capture = false } = options;
+export function useGlobalKeydown({ handler }, options = {}) {
+    const { enabled = true, target = 'window', capture = false, resolveTarget = resolveGlobalKeydownTarget } = options;
     // Latest-ref indirection so callers don't need to memoize `handler` for
     // the listener effect below to stay attached with fresh behavior.
     const handlerRef = useRef(handler);
@@ -37,17 +37,8 @@ export function useGlobalKeydown(handler, options = {}) {
     useEffect(() => {
         if (!enabled)
             return;
-        const eventTarget = resolveGlobalKeydownTarget(target);
-        // `resolveGlobalKeydownTarget` itself has a direct, real test proving
-        // it CAN return `undefined` (see this file's own test). This call
-        // site's guard against that, though, is empirically and structurally
-        // unreachable through any real mount: `useEffect` bodies only ever run
-        // client-side, after React has already committed real DOM nodes via
-        // `ReactDOM` — which itself requires `window` (and, for a 'document'
-        // target, `document`) to already exist. There is no real browser
-        // session in which this hook's effect runs at all while its own
-        // resolved target has vanished. See packages/ui/source-map.md's
-        // 2026-07-22 dated entry.
+        const eventTarget = resolveTarget({ target });
+        // A host may intentionally provide no target while its surface is detached.
         if (typeof eventTarget === 'undefined')
             return;
         function onKeyDown(event) {
@@ -55,6 +46,6 @@ export function useGlobalKeydown(handler, options = {}) {
         }
         eventTarget.addEventListener('keydown', onKeyDown, capture);
         return () => eventTarget.removeEventListener('keydown', onKeyDown, capture);
-    }, [enabled, target, capture]);
+    }, [enabled, target, capture, resolveTarget]);
 }
 //# sourceMappingURL=useGlobalKeydown.js.map

package/dist/features/a2ui/catalog-from-registry.d.ts

@@ -2,12 +2,12 @@ import type { Catalog } from './protocol.js';
 import type { InteractiveUiRegistry } from '../interactive-ui/registry.js';
 export interface BuildA2uiCatalogFromRegistryOptions {
     /**
-     * A catalog to merge registry components into — typically `createLabCatalog()`, so the result
+     * A catalog to merge registry components into — typically `createLabCatalog({})`, so the result
      * has both the 18 basic layout/text primitives (`Row`/`Column`/`Card`/`Text`/`Button`/etc.) AND
      * registry-sourced components (`native.data-table`, `shadcn.data-table`). Without a `base`, the
      * result has only registry components, which is enough to validate/resolve one in isolation but
      * cannot compose a tree — a table alone isn't a page, it needs a container to sit in. Omitted
-     * entirely (not defaulted to `createLabCatalog()` here) so a caller that only ever wants
+     * entirely (not defaulted to `createLabCatalog({})` here) so a caller that only ever wants
      * registry components — the manifests-only MCP search path, for one — doesn't pull in basic-type
      * schemas it will never use. `functions` come from `base` unchanged; registry components don't
      * define any of their own.
@@ -26,5 +26,8 @@ export interface BuildA2uiCatalogFromRegistryOptions {
  * `kind` for these entries anyway — it resolves by matching `component.component` directly
  * against the registry, so this is a documented simplification, not a load-bearing choice.
  */
-export declare function buildA2uiCatalogFromRegistry(registry: InteractiveUiRegistry, catalogId: string, options?: BuildA2uiCatalogFromRegistryOptions): Catalog;
+export declare function buildA2uiCatalogFromRegistry({ registry, catalogId }: {
+    registry: Pick<InteractiveUiRegistry, 'list'>;
+    catalogId: string;
+}, options?: BuildA2uiCatalogFromRegistryOptions): Catalog;
 //# sourceMappingURL=catalog-from-registry.d.ts.map

package/dist/features/a2ui/catalog-from-registry.js

@@ -10,7 +10,7 @@
  * `kind` for these entries anyway — it resolves by matching `component.component` directly
  * against the registry, so this is a documented simplification, not a load-bearing choice.
  */
-export function buildA2uiCatalogFromRegistry(registry, catalogId, options = {}) {
+export function buildA2uiCatalogFromRegistry({ registry, catalogId }, options = {}) {
     const registryComponents = registry.list().map((entry) => [
         entry.id,
         { kind: 'container', propsSchema: entry.propsSchema },

package/dist/features/a2ui/index.d.ts

@@ -1,4 +1,4 @@
-export { createA2uiInterpreter, createLabCatalog, type A2uiInterpreter, type ApplyMessageResult, type BuildActionResult, type ComponentInstance, type SurfaceSnapshot, type Catalog, type ComponentSpec, type ComponentKind, } from './protocol.js';
+export { createA2uiInterpreter, createLabCatalog, type A2uiInterpreter, type A2uiIdsPort, type ApplyMessageResult, type BuildActionResult, type ComponentInstance, type SurfaceSnapshot, type Catalog, type ComponentSpec, type ComponentKind, } from './protocol.js';
 export { buildA2uiCatalogFromRegistry, type BuildA2uiCatalogFromRegistryOptions, } from './catalog-from-registry.js';
 export { useA2uiSurfaceRoot } from './use-a2ui-surface.js';
 export { A2uiSurfaceRenderer, type A2uiSurfaceRendererProps } from './renderer.js';