@object-ui/app-shell 6.2.2 → 7.0.0

package/README.md

@@ -75,6 +75,11 @@ function MyForm() {
 - **Lightweight**: ~50KB vs 500KB+ for full console
 - **Composable**: Mix and match components as needed
 - **Type-Safe**: Full TypeScript support
+- **Console AI Entry Point**: The lazy chatbot FAB keeps mobile bottom
+  navigation clear until the full assistant panel is loaded
+- **Full-Page AI Workspace**: The `/ai` surface provides a responsive chat
+  workspace with a desktop conversation rail, mobile Chats drawer, and a
+  constrained reading width for long conversations
 
 ## Components
 
@@ -140,6 +145,164 @@ Renders forms (modal or inline).
 />
 ```
 
+## Metadata designers
+
+The metadata-admin engine (`src/views/metadata-admin`) renders an in-app editor
+for each metadata type. Every type has a pure-renderer **preview** that doubles
+as its **designer** when given `editing` + `onPatch` props — no backend round
+trip is required to edit a draft.
+
+### Studio package scope
+
+Studio treats the selected package as the authoring scope. The package selector
+is mandatory, and Studio repairs missing `?package=` query parameters from the
+last selected package or the first project package so scoped pages do not drift
+out of sync with the sidebar. The Studio home overview, quick-create links,
+metadata counts, and diagnostics all follow that active package. The dedicated
+package-management page remains the global place to create, import, publish,
+enable, or disable packages; direct `/metadata/package` links redirect there.
+The Studio sidebar also flattens the root Overview group so Home and package
+navigation sit directly under the package selector.
+
+### Visual flow canvas
+
+The `flow` designer (`FlowPreview` → `FlowCanvas`) renders an automation as an
+industry-standard top-down node-link diagram (think n8n / Power Automate /
+Salesforce Flow Builder) instead of a flat step list. It is **dependency-free**
+— no ReactFlow / `@xyflow` — so the app-shell bundle stays lean.
+
+**JSON shape** (a `flow` draft):
+
+```jsonc
+{
+  "nodes": [
+    { "id": "start", "type": "start", "label": "Start" },
+    { "id": "decide", "type": "decision", "label": "Renew?",
+      "ui": { "x": 220, "y": 180 } },   // optional persisted canvas position
+    { "id": "email", "type": "action", "label": "Send reminder" },
+    { "id": "end", "type": "end", "label": "End" }
+  ],
+  "edges": [
+    { "source": "start", "target": "decide" },
+    { "source": "decide", "target": "email", "condition": "${days <= 30}", "label": "Due" },
+    { "source": "decide", "target": "end", "isDefault": true, "label": "Skip" },
+    { "source": "email", "target": "end" }
+  ]
+}
+```
+
+- **Layout** — nodes without a `ui` hint are placed by a deterministic layered
+  auto-layout (cycle-guarded), so a flow always renders cleanly even before any
+  manual positioning. Dragging a node persists its position to `node.ui.{x,y}`;
+  positions degrade gracefully (they are layout hints, not required data).
+- **Edges** — branch semantics (`condition`, `label`, `isDefault`) are rendered
+  as labels on the connectors and preserved when a node is inserted on an edge.
+
+**Interactions** (design mode):
+
+- **Add node** — toolbar palette (Action / Decision / Wait / Subflow / Signal /
+  End); the new node is auto-selected.
+- **Append** — the bottom `+` handle on a node adds a connected child.
+- **Insert on edge** — the `+` on a connector splices a node between two nodes,
+  preserving the original branch condition on the first segment.
+- **Reposition** — drag a node (committed on pointer-up).
+- **Delete** — `Delete` / `Backspace` removes the selected node and its edges.
+- **Navigate** — fit-to-view, zoom in/out, and background pan.
+
+Selecting a node opens `FlowNodeInspector`, which renders **typed form fields
+per node type** (see `flow-node-config.ts`) rather than a raw JSON blob. Node
+types follow the spec `FlowNodeAction` enum
+(`@objectstack/spec/automation/flow.zod.ts`): `start`, `decision`,
+`assignment`, `loop`, `create_record`, `update_record`, `delete_record`,
+`get_record`, `http_request`, `script`, `screen`, `wait`, `subflow`,
+`connector_action`, `parallel_gateway`, `join_gateway`, `boundary_event`,
+`end`. Field keys mirror the **real production vocabulary** used by installed
+apps (the spec leaves `config` freeform, so the app metadata is the de-facto
+standard): a `start` node exposes *Object* / *Entry condition* (`criteria`,
+a CEL string) / *Cron schedule* (`schedule`); the trigger **category** is a
+flow-level concern, so `start` deliberately stores **no** `triggerType`. A
+`decision` uses `condition`; `get_record`/`update_record`/`delete_record` use a
+`filter` object; `loop` uses `iteratorVariable`. Spec **structured blocks** are
+edited through dedicated fields, not JSON: a `wait` node maps `waitEventConfig.*`
+(Wait-for / Duration / Timeout / On timeout), a `connector_action` maps
+`connectorConfig.*` (Connector / Action / Input), and a `boundary_event` maps
+`boundaryConfig.*`. CRUD/script/http fields live under `node.config`; spec
+blocks and `timeoutMs` live at the node top-level. Type-specific fields sit under
+a **Configuration** divider, and **conditional fields** (`showWhen`) only appear
+when relevant — e.g. a `script` node switches between a *Code* / *Output
+variables* shape and an *email/SMS* notification shape (*Template* / *Recipients*
+/ *Template variables*) based on its *Action type* (`actionType`, defaulting to
+`code`), and a `wait` node shows *Duration* / *Signal name* based on the selected
+*Wait for* mode. A conditional field is never hidden while it still holds a
+value, so existing config is always reachable.
+
+Config keys come in three editable shapes so authors never hand-write JSON:
+
+- **Flat object maps** — a `create_record` node's **Field values**, a
+  `connector_action`'s **Input**, a `get_record`'s **Filter** — use an inline
+  **key/value editor** (`keyValue` kind). Scalar values are auto-typed (`3` →
+  number, `true` → boolean); object/array values such as a filter operator
+  `{"$ne": null}` round-trip losslessly.
+- **String arrays** — a script's **Recipients** / **Output variables** — use a
+  single-column **string-list editor** (`stringList` kind).
+- **Arrays of objects** — a `screen` node's **Fields** (a list of
+  `{name,label,type,required,visibleWhen}` definitions) — use a column-driven
+  **object-list repeater** (`objectList` kind).
+
+Anything still not covered by a field (nested objects, arrays, plugin-specific
+keys) lives in an **optional** Advanced (JSON) escape hatch: it is shown only
+when such keys already exist, and is otherwise reachable through a low-emphasis
+"Advanced (JSON)" button — it never alarms authors into thinking the form is
+incomplete, and it can never overwrite a key a form field already owns. Node
+types with no configuration (e.g. `parallel`) show a plain "No configuration
+needed" note instead of an empty JSON box. The `ui` layout hint is always kept
+out of the config entirely and preserved across edits.
+
+### Flow simulator (designer-time debug runner)
+
+The canvas toolbar has a **Debug** toggle that opens an in-designer **flow
+simulator** (`FlowSimulatorPanel` → `simulator/flow-simulator.ts`). It lets a
+low-code author *test a flow draft without a backend* — answering "how do I
+mock-run and step through this flow?".
+
+It is a **pure, client-side interpreter**. It **never** calls a `dataSource`:
+every side-effecting node (CRUD / `get_record` / `http_request` /
+`connector_action` / `script`) is **MOCKED**, so a simulation can never write or
+delete real data and never needs a live environment. Its guiding rule is *never
+silently simulate semantics that differ from the runtime* — anything that cannot
+be faithfully modelled is surfaced loudly instead of faked.
+
+- **Preflight validation** — before a run, `validateFlowDraft` blocks on
+  structural errors (no resolvable entry, duplicate ids, edges to missing nodes,
+  multiple decision defaults) and warns on soft issues (unreachable nodes, a
+  decision with no default). Errors disable **Run** so problems surface up front.
+- **Controls** — **Run** (to completion), **Step** (one node), **Reset**, and
+  **Continue** (after a pause). Flow `variables` marked `isInput` become a seed
+  form; values are auto-typed (`30` → number, `true` → boolean, `{…}` → JSON).
+- **Set variables / Mock outputs** — because a decision often reads a value no
+  declared input produces (e.g. a computed `daysToExpiry`), the panel adds a
+  free-form **Set variables** editor that injects/overrides *any* variable at
+  start, so **every branch is reachable**. A **Mock outputs** editor lets the
+  author pin what each mocked side-effect node "returns" (written to its
+  `outputVariable` / `outputVariables`), so data-dependent logic downstream of a
+  `get_record` or `script` can be exercised too.
+- **Semantics** — `start`/`assignment` pass through; a `decision` routes
+  **edge-first** (first truthy outgoing `condition`, else the `isDefault` edge,
+  else a surfaced dead-end), evaluating CEL via `@object-ui/core`'s
+  `ExpressionEvaluator` and **surfacing eval errors** (not swallowing them);
+  side-effect nodes write their mock to `outputVariable` / `outputVariables[]`;
+  `wait` and `screen` **pause** for manual continue; `join_gateway`, `subflow`,
+  and `boundary_event` are marked **unsupported** (token sync / nested runs are
+  not modelled) rather than faked.
+- **Live feedback** — the panel shows a **variable watch**, a **step timeline**
+  (status badges `OK` / `MOCKED` / `PAUSED` / `SKIPPED` / `ERROR`, per-decision
+  edge diagnostics, and write summaries), while the canvas highlights the
+  **active** node (pulsing sky ring), **visited** nodes (emerald), and
+  **traversed** edges (sky), dimming nodes not yet reached.
+
+The engine is covered by unit tests in
+`previews/simulator/__tests__/flow-simulator.test.ts`.
+
 ## Architecture
 
 This package sits between the low-level `@object-ui/react` (SchemaRenderer) and the high-level `apps/console` (full application):
@@ -261,6 +424,135 @@ for the adapter contract, backend schema, and how to plug in your own backend.
 
 <!-- release-metadata:v3.3.0 -->
 
+## Command palette (⌘K)
+
+`<ConsoleShell>` mounts a global ⌘K command palette for cross-app navigation and
+record search. Its open state and the command that opens it are provided by
+`CommandPaletteProvider` (wired in by `ConsoleLayout`) and exposed via
+`useCommandPalette()`.
+
+```tsx
+import { useCommandPalette } from '@object-ui/app-shell';
+
+function MyToolbarButton() {
+  const { openCommandPalette } = useCommandPalette();
+  // Idempotent: calling when already open is a no-op.
+  return <button onClick={openCommandPalette}>Search…</button>;
+}
+```
+
+Designed to be deterministic for automated (AI) browser testing — see
+[ADR-0054 "UI testability contract"](../../docs/adr/0054-ui-testability-contract.md):
+
+- **Idempotent, direct open (C1).** The top-bar search button, the ⌘K shortcut,
+  and the deep-link all call the *same* idempotent `openCommandPalette()`
+  (`setOpen(true)`), never a `toggle()`. The button calls the command directly —
+  it does **not** re-dispatch a synthetic `⌘K` `KeyboardEvent` (which silently
+  did nothing under automation and in ⌘K-reserving browsers). ⌘K stays a
+  keyboard *accelerator* and may still toggle (close-on-repeat).
+- **URL-addressable (C3).** Open state lives in the `?palette=1` search param, so
+  the palette is deep-linkable (`/apps/<app>?palette=1`), restores on reload, and
+  works with browser back/forward. `?cmdk=1` is accepted as an alias on read.
+- **Stable locators (C4).** The dialog carries `data-testid="overlay:command-palette"`
+  plus an ARIA role/name; the header trigger carries
+  `data-testid="action:command-palette:open"` (and `:open-mobile` for the compact
+  header). `CommandDialog` accepts `contentProps` to forward a `data-testid`/ARIA
+  name onto the underlying dialog element.
+- **Trusted-input note (C6).** The palette search is a controlled + debounced
+  input. Value-injection (`el.value = …`) does **not** fire React's `onChange`;
+  drive it with a real-input / CDP-keystroke driver so the debounced fetch fires.
+
+## URL-addressable overlays (`useUrlOverlay`)
+
+`useUrlOverlay(key)` is the reusable building block behind the command palette's
+URL-addressable open state (ADR-0054 C3). It stores a navigable overlay's open
+state in a `?<key>=1` search param instead of component `useState`, so the
+overlay is deep-linkable, restores on reload, and works with back/forward — and
+its open path is idempotent (C1).
+
+```tsx
+import { useUrlOverlay } from '@object-ui/app-shell';
+
+function HelpMenu() {
+  const { open, setOpen, openOverlay } = useUrlOverlay('shortcuts');
+  // Header button (any component under the router):  onClick={openOverlay}
+  // Dialog (elsewhere, reads the same param):        <Dialog open={open} onOpenChange={setOpen}>
+  // Deep-link that opens on load:                    /apps/foo?shortcuts=1
+}
+```
+
+Because state lives in the URL, a trigger and the overlay it controls need no
+shared provider or prop-drilling — they just use the same `key`. The
+command palette (`?palette=1`, `?cmdk=1` alias) and the keyboard-shortcuts dialog
+(`?shortcuts=1`, openable from the Help menu — no longer `?`-key-only) both build
+on it. `replace`/`alias`/`value` are configurable.
+
+The shared overlay primitives in `@object-ui/components`
+(`Dialog`/`Sheet`/`Drawer`/`Popover`/`DropdownMenu`/`AlertDialog`) already forward
+a `data-testid` onto their content element and emit Radix `data-state="open|closed"`,
+so overlays are locatable and their open/closed state is machine-readable by
+construction (C4).
+
+## Settle signal (is the app idle?)
+
+`<ConsoleShell>` exposes one global "no requests in flight" predicate so an
+automated (AI) browser driver can wait for the app to settle instead of
+hardcoding timeouts (ADR-0054 C5). The data layer increments a counter around
+every outbound request (it wraps the adapter's `fetch`), mirrored onto
+`window.__objectui`:
+
+```js
+// In an e2e / browser driver:
+await page.waitForFunction(() => window.__objectui?.idle === true);
+// or:  window.__objectui.pendingRequests === 0
+// or:  await window.__objectui.whenIdle();   // resolves when settled (10s cap)
+```
+
+In React, `useSettleSignal()` returns `{ pending, idle }` for a global busy
+indicator; the lower-level `getPendingRequests` / `subscribeSettle` / `whenIdle`
+/ `withSettleSignal` / `installSettleSignalGlobal` are also exported.
+
+Async data regions additionally expose region-level state for finer waits: the
+list view and record-picker results set `aria-busy` while fetching and
+`data-state="loading|idle"`, complementing the Radix `data-state` already on
+overlays.
+
+## Field locators (`field:{object}.{field}`)
+
+Generated forms emit a metadata-derived stable locator on every field wrapper, so
+an automated (AI) driver can target a field without relying on i18n-fragile labels
+or positional selectors (ADR-0054 C4). The form renderer derives it from the
+form's `objectName` and each field's name — every form (`ObjectForm`, `ModalForm`,
+`DrawerForm`, `SplitForm`, `WizardForm`) inherits it with zero per-app work:
+
+```html
+<div data-testid="field:account.industry" data-field="industry"> … input … </div>
+```
+
+```js
+// e2e / AI driver:
+await page.getByTestId('field:account.industry').locator('input').fill('SaaS');
+```
+
+The object prefix is omitted (`field:{field}`) when a form has no owning object.
+This complements the action/overlay locators already emitted by the renderer
+(`overlay:command-palette`, `action:command-palette:open`, …).
+
+## Testability ratchet
+
+The invariants above are kept from regressing (ADR-0054 Phase 5, "counts can only
+go down"):
+
+- A conformance test (runs in the gating `pnpm test` job) fails the build if a new
+  **synthetic-event trigger** (`el.dispatchEvent(new KeyboardEvent/MouseEvent/
+  PointerEvent …)`) is introduced anywhere in `packages/*/src` or `apps/*/src`.
+  Legitimate `CustomEvent` / `PopStateEvent` dispatch (event bus / history nudge)
+  is allowed. Replace a synthetic trigger with a direct, idempotent command
+  (`useCommandPalette` / `useUrlOverlay`).
+- A matching ESLint rule `object-ui/no-synthetic-event-trigger` flags the same
+  pattern in-editor (the repo `Lint` workflow is manual, so the test is the CI
+  gate).
+
 ## Compatibility
 
 - **React:** 18.x or 19.x

package/dist/assistant/assistantBus.d.ts

@@ -0,0 +1,72 @@
+export interface AssistantEditorField {
+    name: string;
+    type?: string;
+    label?: string;
+    required?: boolean;
+}
+export interface AssistantEditorContext {
+    /** Metadata type, e.g. 'object'. */
+    type: string;
+    /** Item primary-key name (may be empty in create mode). */
+    name: string;
+    label?: string;
+    /** Lightweight field summary — enough for the agent to reason, not the full draft. */
+    fields?: AssistantEditorField[];
+}
+/** A metadata item the chat has asked the host to open in review/diff. */
+export interface AssistantReviewTarget {
+    type: string;
+    name: string;
+}
+export interface AssistantSnapshot {
+    /** What the user is currently editing, or null when no designer is active. */
+    editor: AssistantEditorContext | null;
+    /** Monotonic counter — bumped each time a surface requests the chat to open. */
+    openSeq: number;
+    /**
+     * Monotonic counter — bumped each time the chat asks the host to open a
+     * drafted item in review (ADR-0033 Phase B). The host (which knows the app
+     * base) watches this and navigates to the designer.
+     */
+    reviewSeq: number;
+    /** The item to review, set alongside the latest `reviewSeq` bump. */
+    reviewTarget: AssistantReviewTarget | null;
+}
+export declare const assistantBus: {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): AssistantSnapshot;
+    /** Publish the currently-edited item (or null to clear). No-op if unchanged. */
+    setEditor(next: AssistantEditorContext | null): void;
+    /** Ask the global chat to open (and warm/mount the lazy FAB). */
+    requestOpen(): void;
+    /**
+     * Ask the host to open `target` in the designer's review/diff (ADR-0033
+     * Phase B). The chat calls this from the "Review N change(s)" affordance;
+     * a navigator that knows the app base performs the routing.
+     */
+    requestReview(target: AssistantReviewTarget): void;
+};
+export interface CanvasInvalidation {
+    type: string;
+    name: string;
+}
+/** Announce that a draft artifact changed (chat hosts call this). */
+export declare function emitCanvasInvalidate(inv: CanvasInvalidation): void;
+/** Subscribe to draft-artifact invalidations; returns an unsubscriber. */
+export declare function subscribeCanvasInvalidate(listener: (inv: CanvasInvalidation) => void): () => void;
+/** Announce that the live metadata registry changed (publish / install hosts call this). */
+export declare function emitMetadataRefresh(): void;
+/** Subscribe to live-metadata-changed events; returns an unsubscriber. */
+export declare function subscribeMetadataRefresh(listener: () => void): () => void;
+/** Subscribe a component to the assistant bus snapshot. */
+export declare function useAssistant(): AssistantSnapshot;
+/**
+ * Publish the currently-edited item to the assistant for the lifetime of
+ * the calling component (auto-clears on unmount). Pass `null` to register
+ * nothing. Stable across renders with equal content.
+ */
+export declare function useRegisterAssistantEditor(ctx: AssistantEditorContext | null): void;
+/** Open the global AI chat from anywhere (e.g. an "Ask AI" button). */
+export declare function requestAssistantOpen(): void;
+/** Ask the host to open a drafted item in the designer's review/diff. */
+export declare function requestAssistantReview(target: AssistantReviewTarget): void;

package/dist/assistant/assistantBus.js

@@ -0,0 +1,133 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Assistant bus — a tiny framework-agnostic singleton that connects the
+ * metadata designers to the global AI chat (`ConsoleFloatingChatbot`).
+ *
+ * Two channels:
+ *   1. **Editor context** — a designer publishes *what the user is
+ *      currently editing* (`{ type, name, label, fields }`). The chatbot
+ *      reads it and merges it into the `context` it sends the agent, so
+ *      "add a priority field" acts on the open object without the user
+ *      restating which object they mean.
+ *   2. **Open signal** — a designer can ask the global chat to open (e.g.
+ *      an "Ask AI" button). The lazy chat FAB arms + opens on the signal.
+ *
+ * Why a singleton bus instead of React context? The chat FAB is
+ * lazy-mounted on a different branch of the tree from the designers, and
+ * the open-signal must cross that boundary without a shared Provider
+ * being threaded through every layout. A module singleton + (subscribe,
+ * getSnapshot) reads cleanly via `useSyncExternalStore`.
+ */
+import { useEffect, useSyncExternalStore } from 'react';
+let editor = null;
+let openSeq = 0;
+let reviewSeq = 0;
+let reviewTarget = null;
+// Cached snapshot — its reference only changes on a real state change so
+// useSyncExternalStore doesn't loop.
+let snapshot = { editor, openSeq, reviewSeq, reviewTarget };
+const listeners = new Set();
+function commit() {
+    snapshot = { editor, openSeq, reviewSeq, reviewTarget };
+    for (const l of listeners)
+        l();
+}
+function sameEditor(a, b) {
+    if (a === b)
+        return true;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+export const assistantBus = {
+    subscribe(listener) {
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    },
+    getSnapshot() {
+        return snapshot;
+    },
+    /** Publish the currently-edited item (or null to clear). No-op if unchanged. */
+    setEditor(next) {
+        if (sameEditor(editor, next))
+            return;
+        editor = next;
+        commit();
+    },
+    /** Ask the global chat to open (and warm/mount the lazy FAB). */
+    requestOpen() {
+        openSeq += 1;
+        commit();
+    },
+    /**
+     * Ask the host to open `target` in the designer's review/diff (ADR-0033
+     * Phase B). The chat calls this from the "Review N change(s)" affordance;
+     * a navigator that knows the app base performs the routing.
+     */
+    requestReview(target) {
+        reviewSeq += 1;
+        reviewTarget = target;
+        commit();
+    },
+};
+const invalidateListeners = new Set();
+/** Announce that a draft artifact changed (chat hosts call this). */
+export function emitCanvasInvalidate(inv) {
+    for (const l of invalidateListeners)
+        l(inv);
+}
+/** Subscribe to draft-artifact invalidations; returns an unsubscriber. */
+export function subscribeCanvasInvalidate(listener) {
+    invalidateListeners.add(listener);
+    return () => {
+        invalidateListeners.delete(listener);
+    };
+}
+// ── Live-metadata-changed signal ─────────────────────────────
+// The live registry just changed out-of-band from the metadata trees — a
+// publish promoted staged drafts, or a marketplace install merged a package.
+// Unlike the per-artifact, draft-only canvas invalidations above, this is a
+// coarse "the live world changed, refetch" pulse: EVERY mounted
+// MetadataProvider (nav sidebar included, not just the surface that triggered
+// it) refetches its loaded types so already-open forms/views/nav pick up the
+// change WITHOUT a full page reload. Fire-and-forget, off the snapshot bus
+// (same reasoning as canvas invalidations — an event, not state).
+const metadataRefreshListeners = new Set();
+/** Announce that the live metadata registry changed (publish / install hosts call this). */
+export function emitMetadataRefresh() {
+    for (const l of metadataRefreshListeners)
+        l();
+}
+/** Subscribe to live-metadata-changed events; returns an unsubscriber. */
+export function subscribeMetadataRefresh(listener) {
+    metadataRefreshListeners.add(listener);
+    return () => {
+        metadataRefreshListeners.delete(listener);
+    };
+}
+/** Subscribe a component to the assistant bus snapshot. */
+export function useAssistant() {
+    return useSyncExternalStore(assistantBus.subscribe, assistantBus.getSnapshot, assistantBus.getSnapshot);
+}
+/**
+ * Publish the currently-edited item to the assistant for the lifetime of
+ * the calling component (auto-clears on unmount). Pass `null` to register
+ * nothing. Stable across renders with equal content.
+ */
+export function useRegisterAssistantEditor(ctx) {
+    // Serialize for a cheap, content-based effect dependency.
+    const key = ctx ? JSON.stringify(ctx) : '';
+    useEffect(() => {
+        assistantBus.setEditor(ctx);
+        return () => assistantBus.setEditor(null);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+}
+/** Open the global AI chat from anywhere (e.g. an "Ask AI" button). */
+export function requestAssistantOpen() {
+    assistantBus.requestOpen();
+}
+/** Ask the host to open a drafted item in the designer's review/diff. */
+export function requestAssistantReview(target) {
+    assistantBus.requestReview(target);
+}

package/dist/chrome/CommandPalette.d.ts

@@ -17,5 +17,5 @@ interface CommandPaletteProps {
      */
     dataSource?: any;
 }
-export declare function CommandPalette({ apps, activeApp, objects, onAppChange, dataSource }: CommandPaletteProps): import("react/jsx-runtime").JSX.Element;
+export declare function CommandPalette({ apps, activeApp, objects, onAppChange, dataSource }: CommandPaletteProps): import("react").JSX.Element;
 export {};

package/dist/chrome/CommandPalette.js

@@ -10,39 +10,36 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useState, useCallback, useMemo } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
 import { CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, } from '@object-ui/components';
-import { LayoutDashboard, FileText, BarChart3, Moon, Sun, Monitor, Search, Plus, } from 'lucide-react';
+import { LayoutDashboard, FileText, BarChart3, Moon, Sun, Monitor, Search, } from 'lucide-react';
 import { useRecordSearch } from '@object-ui/react';
 import { useTheme } from './ThemeProvider';
 import { useExpressionContext, evaluateVisibility } from '../providers/ExpressionProvider';
 import { useObjectTranslation } from '@object-ui/i18n';
-import { resolveI18nLabel, getRecordDisplayName } from '../utils';
+import { resolveI18nLabel, getRecordDisplayName, appRouteSegment } from '../utils';
 import { getIcon } from '../utils/getIcon';
 import { useRecentItems } from '../context/RecentItemsProvider';
+import { useCommandPalette } from '../context/CommandPaletteProvider';
+import { resolveHref } from '@object-ui/layout';
+import { useAuth } from '@object-ui/auth';
 export function CommandPalette({ apps, activeApp, objects, onAppChange, dataSource }) {
-    const [open, setOpen] = useState(false);
+    const { open, setOpen } = useCommandPalette();
     const [inputValue, setInputValue] = useState('');
     const navigate = useNavigate();
     const { appName } = useParams();
     const { setTheme } = useTheme();
     const { evaluator } = useExpressionContext();
     const { t } = useObjectTranslation();
-    // ⌘+K / Ctrl+K shortcut
-    useEffect(() => {
-        const down = (e) => {
-            if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
-                e.preventDefault();
-                setOpen(prev => !prev);
-            }
-        };
-        document.addEventListener('keydown', down);
-        return () => document.removeEventListener('keydown', down);
-    }, []);
+    // The ⌘K / Ctrl+K accelerator and the open-state source of truth now live in
+    // CommandPaletteProvider so the keyboard shortcut, the header button, and the
+    // ?palette=1 deep-link all drive the SAME idempotent open path (ADR-0054 C1/C3).
     // Reset query when the palette closes so reopening doesn't show stale state.
     useEffect(() => {
         if (!open)
             setInputValue('');
     }, [open]);
-    const baseUrl = `/apps/${appName || activeApp?.name}`;
+    const baseUrl = `/apps/${appName || appRouteSegment(activeApp)}`;
+    const { user } = useAuth();
+    const templateContext = useMemo(() => ({ currentUserId: user?.id ?? null }), [user?.id]);
     const runCommand = useCallback((command) => {
         setOpen(false);
         command();
@@ -71,7 +68,14 @@ export function CommandPalette({ apps, activeApp, objects, onAppChange, dataSour
     const { recentItems } = useRecentItems();
     const recentRecords = useMemo(() => recentItems.filter((it) => it.type === 'record').slice(0, 5), [recentItems]);
     const showRecentRecords = open && inputValue.trim().length === 0 && recentRecords.length > 0;
-    return (_jsxs(CommandDialog, { open: open, onOpenChange: setOpen, children: [_jsx(CommandInput, { placeholder: t('console.commandPalette.placeholder'), value: inputValue, onValueChange: setInputValue }), _jsxs(CommandList, { children: [_jsx(CommandEmpty, { children: isSearching ? (_jsxs("span", { className: "inline-flex items-center gap-2 text-muted-foreground", children: [_jsx("span", { "aria-hidden": true, className: "inline-block h-1.5 w-1.5 rounded-full bg-primary motion-safe:animate-pulse" }), t('console.commandPalette.searching', { defaultValue: 'Searching…' })] })) : (t('console.commandPalette.noResults')) }), showRecentRecords && (_jsx(CommandGroup, { heading: t('console.commandPalette.recentRecords', { defaultValue: 'Recently viewed' }), children: recentRecords.map((item) => (_jsxs(CommandItem, { value: `recent ${item.label} ${item.id}`, onSelect: () => runCommand(() => navigate(item.href)), children: [_jsx(Search, { className: "mr-2 h-4 w-4" }), _jsx("span", { className: "truncate", children: item.label })] }, `recent:${item.id}`))) })), recordHits.length > 0 && (_jsx(CommandGroup, { heading: _jsxs("span", { className: "inline-flex items-center gap-2", children: [t('console.commandPalette.records', { defaultValue: 'Records' }), isSearching && (_jsx("span", { "aria-hidden": true, className: "inline-block h-1.5 w-1.5 rounded-full bg-primary motion-safe:animate-pulse" }))] }), children: recordHits.map((hit) => {
+    return (_jsxs(CommandDialog, { open: open, onOpenChange: setOpen, 
+        // Accessible name/description (rendered visually-hidden as the required
+        // Radix DialogTitle/Description) — gives the dialog a stable ARIA name (C4).
+        title: t('console.commandPalette.title', { defaultValue: 'Command palette' }), description: t('console.commandPalette.placeholder'), contentProps: {
+            // Stable locator so the overlay is addressable by an automated driver
+            // without relying on i18n-fragile visible text (C4).
+            'data-testid': 'overlay:command-palette',
+        }, children: [_jsx(CommandInput, { placeholder: t('console.commandPalette.placeholder'), value: inputValue, onValueChange: setInputValue }), _jsxs(CommandList, { children: [_jsx(CommandEmpty, { children: isSearching ? (_jsxs("span", { className: "inline-flex items-center gap-2 text-muted-foreground", children: [_jsx("span", { "aria-hidden": true, className: "inline-block h-1.5 w-1.5 rounded-full bg-primary motion-safe:animate-pulse" }), t('console.commandPalette.searching', { defaultValue: 'Searching…' })] })) : (t('console.commandPalette.noResults')) }), showRecentRecords && (_jsx(CommandGroup, { heading: t('console.commandPalette.recentRecords', { defaultValue: 'Recently viewed' }), children: recentRecords.map((item) => (_jsxs(CommandItem, { value: `recent ${item.label} ${item.id}`, onSelect: () => runCommand(() => navigate(item.href)), children: [_jsx(Search, { className: "mr-2 h-4 w-4" }), _jsx("span", { className: "truncate", children: item.label })] }, `recent:${item.id}`))) })), recordHits.length > 0 && (_jsx(CommandGroup, { heading: _jsxs("span", { className: "inline-flex items-center gap-2", children: [t('console.commandPalette.records', { defaultValue: 'Records' }), isSearching && (_jsx("span", { "aria-hidden": true, className: "inline-block h-1.5 w-1.5 rounded-full bg-primary motion-safe:animate-pulse" }))] }), children: recordHits.map((hit) => {
                             const Icon = getIcon(hit.icon);
                             return (_jsxs(CommandItem, { 
                                 // Embed the live query so cmdk's client-side filter doesn't
@@ -81,19 +85,19 @@ export function CommandPalette({ apps, activeApp, objects, onAppChange, dataSour
                             .filter(i => i.type === 'object')
                             .map(item => {
                             const Icon = getIcon(item.icon);
-                            return (_jsxs(CommandItem, { value: `object ${resolveI18nLabel(item.label, t)} ${item.objectName}`, onSelect: () => runCommand(() => navigate(`${baseUrl}/${item.objectName}`)), children: [_jsx(Icon, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(item.label, t) })] }, item.id));
+                            return (_jsxs(CommandItem, { value: `object ${resolveI18nLabel(item.label, t)} ${item.objectName}`, onSelect: () => runCommand(() => navigate(resolveHref(item, baseUrl, templateContext).href)), children: [_jsx(Icon, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(item.label, t) })] }, item.id));
                         }) })), navItems.filter(i => i.type === 'dashboard').length > 0 && (_jsx(CommandGroup, { heading: t('console.commandPalette.dashboards'), children: navItems
                             .filter(i => i.type === 'dashboard')
-                            .map(item => (_jsxs(CommandItem, { value: `dashboard ${resolveI18nLabel(item.label, t)} ${item.dashboardName}`, onSelect: () => runCommand(() => navigate(`${baseUrl}/dashboard/${item.dashboardName}`)), children: [_jsx(LayoutDashboard, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(item.label, t) })] }, item.id))) })), navItems.filter(i => i.type === 'page').length > 0 && (_jsx(CommandGroup, { heading: t('console.commandPalette.pages'), children: navItems
+                            .map(item => (_jsxs(CommandItem, { value: `dashboard ${resolveI18nLabel(item.label, t)} ${item.dashboardName}`, onSelect: () => runCommand(() => navigate(resolveHref(item, baseUrl, templateContext).href)), children: [_jsx(LayoutDashboard, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(item.label, t) })] }, item.id))) })), navItems.filter(i => i.type === 'page').length > 0 && (_jsx(CommandGroup, { heading: t('console.commandPalette.pages'), children: navItems
                             .filter(i => i.type === 'page')
-                            .map(item => (_jsxs(CommandItem, { value: `page ${resolveI18nLabel(item.label, t)} ${item.pageName}`, onSelect: () => runCommand(() => navigate(`${baseUrl}/page/${item.pageName}`)), children: [_jsx(FileText, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(item.label, t) })] }, item.id))) })), navItems.filter(i => i.type === 'report').length > 0 && (_jsx(CommandGroup, { heading: t('console.commandPalette.reports'), children: navItems
+                            .map(item => (_jsxs(CommandItem, { value: `page ${resolveI18nLabel(item.label, t)} ${item.pageName}`, onSelect: () => runCommand(() => navigate(resolveHref(item, baseUrl, templateContext).href)), children: [_jsx(FileText, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(item.label, t) })] }, item.id))) })), navItems.filter(i => i.type === 'report').length > 0 && (_jsx(CommandGroup, { heading: t('console.commandPalette.reports'), children: navItems
                             .filter(i => i.type === 'report')
-                            .map(item => (_jsxs(CommandItem, { value: `report ${resolveI18nLabel(item.label, t)} ${item.reportName}`, onSelect: () => runCommand(() => navigate(`${baseUrl}/report/${item.reportName}`)), children: [_jsx(BarChart3, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(item.label, t) })] }, item.id))) })), apps.filter(a => a.active !== false).length > 1 && (_jsxs(_Fragment, { children: [_jsx(CommandSeparator, {}), _jsx(CommandGroup, { heading: t('console.commandPalette.switchApp'), children: apps
+                            .map(item => (_jsxs(CommandItem, { value: `report ${resolveI18nLabel(item.label, t)} ${item.reportName}`, onSelect: () => runCommand(() => navigate(resolveHref(item, baseUrl, templateContext).href)), children: [_jsx(BarChart3, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(item.label, t) })] }, item.id))) })), apps.filter(a => a.active !== false).length > 1 && (_jsxs(_Fragment, { children: [_jsx(CommandSeparator, {}), _jsx(CommandGroup, { heading: t('console.commandPalette.switchApp'), children: apps
                                     .filter(a => a.active !== false)
                                     .map(app => {
                                     const Icon = getIcon(app.icon);
-                                    return (_jsxs(CommandItem, { value: `app ${resolveI18nLabel(app.label, t)} ${app.name}`, onSelect: () => runCommand(() => onAppChange(app.name)), children: [_jsx(Icon, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(app.label, t) }), app.name === activeApp?.name && (_jsx("span", { className: "ml-auto text-xs text-muted-foreground", children: t('console.commandPalette.current') }))] }, app.name));
-                                }) })] })), _jsx(CommandSeparator, {}), _jsxs(CommandGroup, { heading: t('console.commandPalette.preferences'), children: [_jsxs(CommandItem, { value: "theme light", onSelect: () => runCommand(() => setTheme('light')), children: [_jsx(Sun, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.lightTheme') })] }), _jsxs(CommandItem, { value: "theme dark", onSelect: () => runCommand(() => setTheme('dark')), children: [_jsx(Moon, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.darkTheme') })] }), _jsxs(CommandItem, { value: "theme system", onSelect: () => runCommand(() => setTheme('system')), children: [_jsx(Monitor, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.systemTheme') })] })] }), _jsx(CommandSeparator, {}), _jsxs(CommandGroup, { heading: t('console.commandPalette.actions'), children: [_jsxs(CommandItem, { value: "create new app application", onSelect: () => runCommand(() => navigate(`${baseUrl}/create-app`)), children: [_jsx(Plus, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.createApp') })] }), _jsxs(CommandItem, { value: "search all results full page", onSelect: () => runCommand(() => navigate(`${baseUrl}/search`)), children: [_jsx(Search, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.openFullSearch') })] })] })] })] }));
+                                    return (_jsxs(CommandItem, { value: `app ${resolveI18nLabel(app.label, t)} ${app.name}`, onSelect: () => runCommand(() => onAppChange(appRouteSegment(app) ?? app.name)), children: [_jsx(Icon, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: resolveI18nLabel(app.label, t) }), app.name === activeApp?.name && (_jsx("span", { className: "ml-auto text-xs text-muted-foreground", children: t('console.commandPalette.current') }))] }, app.name));
+                                }) })] })), _jsx(CommandSeparator, {}), _jsxs(CommandGroup, { heading: t('console.commandPalette.preferences'), children: [_jsxs(CommandItem, { value: "theme light", onSelect: () => runCommand(() => setTheme('light')), children: [_jsx(Sun, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.lightTheme') })] }), _jsxs(CommandItem, { value: "theme dark", onSelect: () => runCommand(() => setTheme('dark')), children: [_jsx(Moon, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.darkTheme') })] }), _jsxs(CommandItem, { value: "theme system", onSelect: () => runCommand(() => setTheme('system')), children: [_jsx(Monitor, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.systemTheme') })] })] }), _jsx(CommandSeparator, {}), _jsx(CommandGroup, { heading: t('console.commandPalette.actions'), children: _jsxs(CommandItem, { value: "search all results full page", onSelect: () => runCommand(() => navigate(`${baseUrl}/search`)), children: [_jsx(Search, { className: "mr-2 h-4 w-4" }), _jsx("span", { children: t('console.commandPalette.openFullSearch') })] }) })] })] }));
 }
 /** Flatten nested navigation groups into a flat list of leaf items */
 function flattenNavigation(items) {

package/dist/chrome/ConditionalAuthWrapper.d.ts

@@ -19,5 +19,5 @@ interface ConditionalAuthWrapperProps {
  * 3. On failure, shows the LoadingScreen in error mode with a Retry button
  *    (no silent fallback to "auth enabled" — the user is told the server is unreachable)
  */
-export declare function ConditionalAuthWrapper({ children, authUrl }: ConditionalAuthWrapperProps): import("react/jsx-runtime").JSX.Element;
+export declare function ConditionalAuthWrapper({ children, authUrl }: ConditionalAuthWrapperProps): import("react").JSX.Element;
 export {};

package/dist/chrome/ConsoleToaster.d.ts

@@ -7,5 +7,5 @@
  */
 import { Toaster as Sonner } from 'sonner';
 type ToasterProps = React.ComponentProps<typeof Sonner>;
-export declare function ConsoleToaster(props: ToasterProps): import("react/jsx-runtime").JSX.Element;
+export declare function ConsoleToaster(props: ToasterProps): import("react").JSX.Element;
 export {};