@object-ui/app-shell 6.2.3 → 7.1.0

package/dist/layout/agentPicker.d.ts

@@ -0,0 +1,56 @@
+/**
+ * agentPicker
+ *
+ * Pure decision logic for the floating assistant's Build/Ask switcher. Kept in
+ * its own module (no React, no chat deps) so it can be unit-tested without
+ * dragging in the heavy chat component graph (FloatingChatbot → streamdown →
+ * shiki → @ai-sdk, ~20MB) that `ConsoleFloatingChatbot` pulls in.
+ * @module
+ */
+import { type AgentDescriptor } from '@object-ui/plugin-chatbot';
+/** Minimal catalog shape the decision needs — just the agent name. */
+type AgentLike = Pick<AgentDescriptor, 'name'>;
+export interface AgentPickerDecisionInput {
+    /** Live agent catalog from `useAgents` (the single source of truth). */
+    agents: AgentLike[];
+    /**
+     * Explicit host override. When defined it wins outright — `true` forces the
+     * switcher on, `false` forces it off — regardless of catalog or env.
+     */
+    showAgentPickerProp?: boolean;
+    /**
+     * `VITE_AI_SHOW_AGENT_PICKER === 'true'` — the power-user / admin global
+     * escape hatch that forces the switcher on without touching app metadata.
+     */
+    envOptIn?: boolean;
+    /**
+     * Whether AI Studio (authoring / "online development") is enabled for this
+     * deployment. When off, the build agent must not be reachable from the panel,
+     * so the auto-reveal is suppressed even if the catalog still serves `build`.
+     * Mirrors `ConsoleLayout`'s `aiStudioEnabled` gate. Defaults to true.
+     */
+    aiStudioEnabled?: boolean;
+}
+/**
+ * True when the live catalog exposes BOTH a data/query (`ask`) and an authoring
+ * (`build`) agent — alias-aware via {@link isAskAgent}/{@link isBuildAgent}, so
+ * a catalog still serving the legacy `data_chat`/`metadata_assistant` ids counts
+ * too. This is the "AI development is unlocked for this viewer" signal, the same
+ * `askAvailable && buildAvailable` notion HomePage uses to surface "Build with AI".
+ */
+export declare function isAiDevUnlocked(agents: AgentLike[]): boolean;
+/**
+ * Decide whether the floating assistant should reveal its Build/Ask switcher.
+ *
+ * Restrained by design (the original "end users shouldn't have to choose" rule):
+ * a pure end-user surface bound to a single `ask` agent never sees it. Precedence:
+ *  1. `showAgentPickerProp` — explicit host override wins (`true`/`false`).
+ *  2. `envOptIn` — `VITE_AI_SHOW_AGENT_PICKER` forces it on globally.
+ *  3. Auto-reveal — AI development is unlocked ({@link isAiDevUnlocked}) AND
+ *     authoring isn't deployment-disabled (`aiStudioEnabled`).
+ *
+ * Returns the *intent* only: the render site still requires more than one agent
+ * (`agents.length > 1`) to draw an actual choice.
+ */
+export declare function shouldShowAgentPicker({ agents, showAgentPickerProp, envOptIn, aiStudioEnabled, }: AgentPickerDecisionInput): boolean;
+export {};

package/dist/layout/agentPicker.js

@@ -0,0 +1,40 @@
+/**
+ * agentPicker
+ *
+ * Pure decision logic for the floating assistant's Build/Ask switcher. Kept in
+ * its own module (no React, no chat deps) so it can be unit-tested without
+ * dragging in the heavy chat component graph (FloatingChatbot → streamdown →
+ * shiki → @ai-sdk, ~20MB) that `ConsoleFloatingChatbot` pulls in.
+ * @module
+ */
+import { isAskAgent, isBuildAgent } from '@object-ui/plugin-chatbot';
+/**
+ * True when the live catalog exposes BOTH a data/query (`ask`) and an authoring
+ * (`build`) agent — alias-aware via {@link isAskAgent}/{@link isBuildAgent}, so
+ * a catalog still serving the legacy `data_chat`/`metadata_assistant` ids counts
+ * too. This is the "AI development is unlocked for this viewer" signal, the same
+ * `askAvailable && buildAvailable` notion HomePage uses to surface "Build with AI".
+ */
+export function isAiDevUnlocked(agents) {
+    return (agents.some((a) => isAskAgent(a.name)) && agents.some((a) => isBuildAgent(a.name)));
+}
+/**
+ * Decide whether the floating assistant should reveal its Build/Ask switcher.
+ *
+ * Restrained by design (the original "end users shouldn't have to choose" rule):
+ * a pure end-user surface bound to a single `ask` agent never sees it. Precedence:
+ *  1. `showAgentPickerProp` — explicit host override wins (`true`/`false`).
+ *  2. `envOptIn` — `VITE_AI_SHOW_AGENT_PICKER` forces it on globally.
+ *  3. Auto-reveal — AI development is unlocked ({@link isAiDevUnlocked}) AND
+ *     authoring isn't deployment-disabled (`aiStudioEnabled`).
+ *
+ * Returns the *intent* only: the render site still requires more than one agent
+ * (`agents.length > 1`) to draw an actual choice.
+ */
+export function shouldShowAgentPicker({ agents, showAgentPickerProp, envOptIn = false, aiStudioEnabled = true, }) {
+    if (showAgentPickerProp !== undefined)
+        return showAgentPickerProp;
+    if (envOptIn)
+        return true;
+    return aiStudioEnabled && isAiDevUnlocked(agents);
+}

package/dist/observability/index.d.ts

@@ -7,3 +7,4 @@
  * @module
  */
 export { initSentry, captureError, setSentryUser, getSentry } from './sentry';
+export { beginRequest, endRequest, getPendingRequests, isIdle, subscribeSettle, whenIdle, withSettleSignal, installSettleSignalGlobal, type ObjectUiGlobal, } from './settleSignal';

package/dist/observability/index.js

@@ -7,3 +7,4 @@
  * @module
  */
 export { initSentry, captureError, setSentryUser, getSentry } from './sentry';
+export { beginRequest, endRequest, getPendingRequests, isIdle, subscribeSettle, whenIdle, withSettleSignal, installSettleSignalGlobal, } from './settleSignal';

package/dist/observability/settleSignal.d.ts

@@ -0,0 +1,64 @@
+/**
+ * settleSignal — global "is the app idle?" in-flight request counter.
+ *
+ * ADR-0054 "UI testability contract", invariant C5 (machine-readable async
+ * state). Gives an automated (AI) browser driver a single predicate to poll
+ * instead of hardcoding waits or scraping per-component spinners:
+ *
+ *   await page.waitForFunction(() => window.__objectui?.idle === true)
+ *   // or:  window.__objectui.pendingRequests === 0
+ *   // or:  await window.__objectui.whenIdle()
+ *
+ * The app-shell data layer increments the counter around every outbound request
+ * by wrapping the adapter's `fetch` with {@link withSettleSignal}. Async regions
+ * additionally expose `aria-busy`/`data-state` for region-level waiting.
+ *
+ * The counter is a module singleton (shared across the app); `window.__objectui`
+ * mirrors it via live getters installed by {@link installSettleSignalGlobal}.
+ *
+ * @module
+ */
+type Listener = (pending: number) => void;
+/** Mark one request as in-flight. Pair with {@link endRequest}. */
+export declare function beginRequest(): void;
+/** Mark one in-flight request as settled (clamped at 0). */
+export declare function endRequest(): void;
+/** Current number of in-flight requests. */
+export declare function getPendingRequests(): number;
+/** Whether the app is idle (no requests in flight). */
+export declare function isIdle(): boolean;
+/**
+ * Subscribe to in-flight count changes. Returns an unsubscribe function.
+ * Used by {@link useSettleSignal} and any consumer wanting a global busy state.
+ */
+export declare function subscribeSettle(cb: Listener): () => void;
+/**
+ * Resolve once the app is idle (no in-flight requests). Resolves immediately if
+ * already idle. `timeoutMs` (default 10s, `0` to disable) caps the wait so a
+ * pathological never-idle app — e.g. a held-open stream — can't hang a driver.
+ */
+export declare function whenIdle(timeoutMs?: number): Promise<void>;
+/**
+ * Wrap a `fetch` so each call increments the in-flight counter before the
+ * request and decrements it when the promise settles (success or failure).
+ */
+export declare function withSettleSignal(fetchFn: typeof fetch): typeof fetch;
+/** Shape mirrored onto `window.__objectui` for automated drivers. */
+export interface ObjectUiGlobal {
+    /** Live in-flight request count. */
+    readonly pendingRequests: number;
+    /** Live idle flag (`pendingRequests === 0`). */
+    readonly idle: boolean;
+    /** Resolve once idle (see {@link whenIdle}). */
+    whenIdle: (timeoutMs?: number) => Promise<void>;
+    /** Subscribe to in-flight count changes. */
+    subscribe: (cb: (pending: number) => void) => () => void;
+}
+/**
+ * Install live `window.__objectui` accessors (idempotent). Safe to call in any
+ * environment — a no-op when `window` is undefined (SSR/tests).
+ */
+export declare function installSettleSignalGlobal(): void;
+/** Test-only: reset the counter and listeners to a clean state. */
+export declare function __resetSettleSignal(): void;
+export {};

package/dist/observability/settleSignal.js

@@ -0,0 +1,131 @@
+/**
+ * settleSignal — global "is the app idle?" in-flight request counter.
+ *
+ * ADR-0054 "UI testability contract", invariant C5 (machine-readable async
+ * state). Gives an automated (AI) browser driver a single predicate to poll
+ * instead of hardcoding waits or scraping per-component spinners:
+ *
+ *   await page.waitForFunction(() => window.__objectui?.idle === true)
+ *   // or:  window.__objectui.pendingRequests === 0
+ *   // or:  await window.__objectui.whenIdle()
+ *
+ * The app-shell data layer increments the counter around every outbound request
+ * by wrapping the adapter's `fetch` with {@link withSettleSignal}. Async regions
+ * additionally expose `aria-busy`/`data-state` for region-level waiting.
+ *
+ * The counter is a module singleton (shared across the app); `window.__objectui`
+ * mirrors it via live getters installed by {@link installSettleSignalGlobal}.
+ *
+ * @module
+ */
+let pending = 0;
+const listeners = new Set();
+let idleWaiters = [];
+function notify() {
+    for (const l of listeners) {
+        try {
+            l(pending);
+        }
+        catch {
+            /* a listener throwing must not break request accounting */
+        }
+    }
+    if (pending === 0 && idleWaiters.length > 0) {
+        const waiters = idleWaiters;
+        idleWaiters = [];
+        for (const resolve of waiters) {
+            try {
+                resolve();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/** Mark one request as in-flight. Pair with {@link endRequest}. */
+export function beginRequest() {
+    pending += 1;
+    notify();
+}
+/** Mark one in-flight request as settled (clamped at 0). */
+export function endRequest() {
+    pending = Math.max(0, pending - 1);
+    notify();
+}
+/** Current number of in-flight requests. */
+export function getPendingRequests() {
+    return pending;
+}
+/** Whether the app is idle (no requests in flight). */
+export function isIdle() {
+    return pending === 0;
+}
+/**
+ * Subscribe to in-flight count changes. Returns an unsubscribe function.
+ * Used by {@link useSettleSignal} and any consumer wanting a global busy state.
+ */
+export function subscribeSettle(cb) {
+    listeners.add(cb);
+    return () => {
+        listeners.delete(cb);
+    };
+}
+/**
+ * Resolve once the app is idle (no in-flight requests). Resolves immediately if
+ * already idle. `timeoutMs` (default 10s, `0` to disable) caps the wait so a
+ * pathological never-idle app — e.g. a held-open stream — can't hang a driver.
+ */
+export function whenIdle(timeoutMs = 10000) {
+    if (pending === 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        };
+        idleWaiters.push(finish);
+        if (timeoutMs > 0 && typeof setTimeout !== 'undefined') {
+            setTimeout(finish, timeoutMs);
+        }
+    });
+}
+/**
+ * Wrap a `fetch` so each call increments the in-flight counter before the
+ * request and decrements it when the promise settles (success or failure).
+ */
+export function withSettleSignal(fetchFn) {
+    return (async (...args) => {
+        beginRequest();
+        try {
+            return await fetchFn(...args);
+        }
+        finally {
+            endRequest();
+        }
+    });
+}
+/**
+ * Install live `window.__objectui` accessors (idempotent). Safe to call in any
+ * environment — a no-op when `window` is undefined (SSR/tests).
+ */
+export function installSettleSignalGlobal() {
+    if (typeof window === 'undefined')
+        return;
+    const w = window;
+    const ns = (w.__objectui ?? (w.__objectui = {}));
+    // Live getters so reads always reflect the current count.
+    Object.defineProperty(ns, 'pendingRequests', { get: getPendingRequests, configurable: true });
+    Object.defineProperty(ns, 'idle', { get: isIdle, configurable: true });
+    ns.whenIdle = whenIdle;
+    ns.subscribe = subscribeSettle;
+}
+/** Test-only: reset the counter and listeners to a clean state. */
+export function __resetSettleSignal() {
+    pending = 0;
+    listeners.clear();
+    idleWaiters = [];
+}

package/dist/preview/CommitTimeline.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export interface CommitTimelineProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    packageId: string;
+    /** Called after a successful revert so the host can refresh the app view. */
+    onReverted?: () => void;
+}
+export declare function CommitTimeline({ open, onOpenChange, packageId, onReverted }: CommitTimelineProps): import("react").JSX.Element;

package/dist/preview/CommitTimeline.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * ADR-0067 — the package "Build history" timeline. Lists every commit an AI
+ * build (or edit) landed, newest-first, with "Revert" per apply commit: undo
+ * that change set (artifacts it created are soft-removed; ones it edited are
+ * restored) as a NEW append-only revert commit. This is the history-not-confirm
+ * surface — the user reviews and reverts instead of approving each publish.
+ *
+ * Sibling of DraftChangesPanel (which lists PENDING drafts before a publish);
+ * this lists what already LANDED, and can undo it.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { GitBranch, Undo2, Loader2 } from 'lucide-react';
+import { toast } from 'sonner';
+import { Badge, Button, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, } from '@object-ui/components';
+import { useObjectTranslation } from '@object-ui/i18n';
+import { fetchCommits, revertCommit } from './commitHistory';
+function relativeTime(iso) {
+    if (!iso)
+        return '';
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return '';
+    const secs = Math.max(0, Math.round((Date.now() - then) / 1000));
+    if (secs < 60)
+        return `${secs}s`;
+    const mins = Math.round(secs / 60);
+    if (mins < 60)
+        return `${mins}m`;
+    const hrs = Math.round(mins / 60);
+    if (hrs < 24)
+        return `${hrs}h`;
+    return `${Math.round(hrs / 24)}d`;
+}
+export function CommitTimeline({ open, onOpenChange, packageId, onReverted }) {
+    const { t } = useObjectTranslation();
+    const [commits, setCommits] = useState(null);
+    const [error, setError] = useState(null);
+    const [reverting, setReverting] = useState(null);
+    const load = useCallback(async () => {
+        setCommits(null);
+        setError(null);
+        try {
+            setCommits(await fetchCommits(packageId));
+        }
+        catch (e) {
+            setError(e.message);
+        }
+    }, [packageId]);
+    useEffect(() => {
+        if (open)
+            void load();
+    }, [open, load]);
+    const onRevert = async (commitId) => {
+        setReverting(commitId);
+        try {
+            await revertCommit(packageId, commitId);
+            toast.success(t('preview.history.reverted', { defaultValue: 'Reverted — the change has been undone.' }));
+            onReverted?.();
+            await load();
+        }
+        catch (e) {
+            toast.error(`${t('preview.history.revertFailed', { defaultValue: 'Revert failed' })}: ${e.message}`);
+        }
+        finally {
+            setReverting(null);
+        }
+    };
+    return (_jsx(Sheet, { open: open, onOpenChange: onOpenChange, children: _jsxs(SheetContent, { side: "right", className: "w-[420px] sm:max-w-[420px]", "data-testid": "commit-timeline-panel", children: [_jsxs(SheetHeader, { children: [_jsx(SheetTitle, { children: t('preview.history.title', { defaultValue: 'Build history' }) }), _jsx(SheetDescription, { children: t('preview.history.description', {
+                                defaultValue: 'Every change to this app, newest first. Revert any step to undo it — no publish confirmation needed.',
+                            }) })] }), _jsx("div", { className: "mt-4 flex flex-col gap-2 overflow-y-auto px-4 pb-6", children: error ? (_jsxs("p", { className: "text-sm text-destructive", children: [t('preview.history.loadFailed', { defaultValue: 'Could not load history:' }), " ", error] })) : commits === null ? (_jsxs("div", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), t('preview.history.loading', { defaultValue: 'Loading history…' })] })) : commits.length === 0 ? (_jsx("p", { className: "text-sm text-muted-foreground", children: t('preview.history.empty', { defaultValue: 'No history yet for this app.' }) })) : (commits.map((c) => (_jsxs("div", { className: "flex items-start gap-2.5 rounded-md border px-2.5 py-2 text-sm", "data-testid": "commit-row", children: [_jsx(GitBranch, { className: `mt-0.5 h-4 w-4 shrink-0 ${c.operation === 'revert' ? 'text-muted-foreground' : 'text-primary'}` }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "truncate font-medium", children: c.message ??
+                                            (c.operation === 'revert'
+                                                ? t('preview.history.revertLabel', { defaultValue: 'Reverted a change' })
+                                                : t('preview.history.applyLabel', { defaultValue: 'Build change' })) }), _jsxs("p", { className: "mt-0.5 flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground", children: [c.operation === 'revert' ? (_jsx(Badge, { variant: "outline", className: "border-muted-foreground/30", children: t('preview.history.revert', { defaultValue: 'revert' }) })) : null, _jsxs("span", { children: [c.itemCount, " ", t('preview.history.items', { defaultValue: 'item(s)' })] }), c.actor ? _jsxs("span", { children: ["\u00B7 ", c.actor] }) : null, c.createdAt ? _jsxs("span", { children: ["\u00B7 ", relativeTime(c.createdAt)] }) : null] })] }), c.operation === 'apply' ? (_jsx(Button, { size: "sm", variant: "ghost", className: "shrink-0", disabled: reverting !== null, onClick: () => onRevert(c.id), "data-testid": "commit-revert", children: reverting === c.id ? (_jsx(Loader2, { className: "h-3.5 w-3.5 animate-spin" })) : (_jsxs(_Fragment, { children: [_jsx(Undo2, { className: "mr-1 h-3.5 w-3.5" }), t('preview.history.revertAction', { defaultValue: 'Revert' })] })) })) : null] }, c.id)))) })] }) }));
+}

package/dist/preview/DraftChangesPanel.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export interface DraftChangeEntry {
+    type: string;
+    name: string;
+    packageId: string | null;
+    /** `new` = no published version; `update` = overwrites one; undefined = probing. */
+    kind?: 'new' | 'update';
+}
+export interface DraftChangesPanelProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+export declare function DraftChangesPanel({ open, onOpenChange }: DraftChangesPanelProps): import("react").JSX.Element;

package/dist/preview/DraftChangesPanel.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * "What will publishing change?" — the draft changeset, answered before the
+ * user commits. Lists every pending ADR-0033 draft grouped by metadata type,
+ * and classifies each as NEW (no published version exists — publishing adds
+ * it) or UPDATE (a published version exists — publishing overwrites it).
+ * This is the review surface that turns Publish from a leap of faith into an
+ * informed click; the per-item designer diff remains the deep-dive.
+ *
+ * Read-only: fetches `_drafts` + per-item `/published` probes on open, and
+ * never writes. Publishing stays with the caller (DraftPreviewBar / chat).
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { FilePlus2, FilePen, Loader2 } from 'lucide-react';
+import { Badge, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, } from '@object-ui/components';
+import { useObjectTranslation } from '@object-ui/i18n';
+/** Pending drafts straight from the ADR-0033 `_drafts` endpoint. */
+async function listPendingDrafts() {
+    const res = await fetch('/api/v1/meta/_drafts', {
+        credentials: 'include',
+        headers: { Accept: 'application/json' },
+        cache: 'no-store',
+    });
+    if (!res.ok)
+        throw new Error(`_drafts HTTP ${res.status}`);
+    const data = (await res.json());
+    const list = Array.isArray(data) ? data : data?.drafts ?? [];
+    return list
+        .filter((d) => typeof d?.type === 'string' && typeof d?.name === 'string')
+        .map((d) => ({
+        type: d.type,
+        name: d.name,
+        packageId: typeof d.packageId === 'string' && d.packageId ? d.packageId : null,
+    }));
+}
+/**
+ * Names that exist in the PUBLISHED world for a type — the plain (no
+ * `preview=draft`) list. One request classifies every draft of that type:
+ * a draft whose name is absent here is NEW; present means publish UPDATES it.
+ * (A per-item `/published` probe would be O(drafts) requests, and the REST
+ * tree has no such sub-route — the generic :name handler answers anything.)
+ */
+async function publishedNamesOf(type) {
+    const res = await fetch(`/api/v1/meta/${encodeURIComponent(type)}`, {
+        credentials: 'include',
+        headers: { Accept: 'application/json' },
+        cache: 'no-store',
+    });
+    if (!res.ok)
+        throw new Error(`published list HTTP ${res.status}`);
+    const data = (await res.json());
+    const list = Array.isArray(data) ? data : data?.items ?? [];
+    return new Set(list
+        .map((it) => (typeof it?.name === 'string' ? it.name : null))
+        .filter((n) => n !== null));
+}
+export function DraftChangesPanel({ open, onOpenChange }) {
+    const { t } = useObjectTranslation();
+    const [entries, setEntries] = useState(null);
+    const [error, setError] = useState(null);
+    const load = useCallback(async () => {
+        setEntries(null);
+        setError(null);
+        try {
+            const drafts = await listPendingDrafts();
+            setEntries(drafts);
+            // Classify new-vs-update per TYPE: one published-list read covers every
+            // draft of that type. A type whose read fails stays unclassified
+            // (rendered neutrally) rather than failing the whole panel.
+            const types = [...new Set(drafts.map((d) => d.type))];
+            await Promise.all(types.map(async (type) => {
+                let published = null;
+                try {
+                    published = await publishedNamesOf(type);
+                }
+                catch {
+                    return;
+                }
+                setEntries((prev) => prev
+                    ? prev.map((entry) => entry.type === type
+                        ? { ...entry, kind: published.has(entry.name) ? 'update' : 'new' }
+                        : entry)
+                    : prev);
+            }));
+        }
+        catch (e) {
+            setError(e.message);
+        }
+    }, []);
+    useEffect(() => {
+        if (open)
+            void load();
+    }, [open, load]);
+    const byType = new Map();
+    for (const entry of entries ?? []) {
+        const bucket = byType.get(entry.type) ?? [];
+        bucket.push(entry);
+        byType.set(entry.type, bucket);
+    }
+    return (_jsx(Sheet, { open: open, onOpenChange: onOpenChange, children: _jsxs(SheetContent, { side: "right", className: "w-[420px] sm:max-w-[420px]", "data-testid": "draft-changes-panel", children: [_jsxs(SheetHeader, { children: [_jsx(SheetTitle, { children: t('preview.changes.title', { defaultValue: 'Pending changes' }) }), _jsx(SheetDescription, { children: t('preview.changes.description', {
+                                defaultValue: 'What publishing will change. New items are added; updates overwrite the live version.',
+                            }) })] }), _jsx("div", { className: "mt-4 flex flex-col gap-4 overflow-y-auto px-4 pb-6", children: error ? (_jsxs("p", { className: "text-sm text-destructive", children: [t('preview.changes.loadFailed', { defaultValue: 'Could not load pending changes:' }), ' ', error] })) : entries === null ? (_jsxs("div", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), t('preview.changes.loading', { defaultValue: 'Loading pending changes…' })] })) : entries.length === 0 ? (_jsx("p", { className: "text-sm text-muted-foreground", children: t('preview.changes.empty', { defaultValue: 'Nothing pending — every draft has been published.' }) })) : ([...byType.entries()].map(([type, items]) => (_jsxs("div", { children: [_jsxs("h4", { className: "mb-1.5 text-xs font-semibold uppercase tracking-wide text-muted-foreground", children: [type, " \u00B7 ", items.length] }), _jsx("ul", { className: "flex flex-col gap-1", children: items.map((entry) => (_jsxs("li", { className: "flex items-center gap-2 rounded-md border px-2.5 py-1.5 text-sm", children: [entry.kind === 'new' ? (_jsx(FilePlus2, { className: "h-3.5 w-3.5 shrink-0 text-emerald-600" })) : entry.kind === 'update' ? (_jsx(FilePen, { className: "h-3.5 w-3.5 shrink-0 text-amber-600" })) : (_jsx(Loader2, { className: "h-3.5 w-3.5 shrink-0 animate-spin text-muted-foreground" })), _jsx("span", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: entry.name }), entry.kind ? (_jsx(Badge, { variant: "outline", className: entry.kind === 'new'
+                                                ? 'border-emerald-200 bg-emerald-50 text-emerald-700'
+                                                : 'border-amber-200 bg-amber-50 text-amber-700', children: entry.kind === 'new'
+                                                ? t('preview.changes.kindNew', { defaultValue: 'New' })
+                                                : t('preview.changes.kindUpdate', { defaultValue: 'Update' }) })) : null] }, `${entry.type}:${entry.name}`))) })] }, type)))) })] }) }));
+}

package/dist/preview/DraftPreviewBar.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export declare function DraftPreviewBar(): import("react").JSX.Element | null;

package/dist/preview/DraftPreviewBar.js

@@ -0,0 +1,86 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * ADR-0037 — the persistent "Draft preview" watermark. Renders only while the
+ * tree is in preview mode (`?preview=draft`); makes the mode unmistakable and
+ * offers the only two actions that matter: leave the preview, or make it real
+ * (the same governed one-click publish the Home banner uses). The bar is what
+ * keeps a read-only preview from ever being confused with the live app.
+ */
+import { useEffect, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import { Eye, X, Rocket, GitCompareArrows } from 'lucide-react';
+import { Button } from '@object-ui/components';
+import { useObjectTranslation } from '@object-ui/i18n';
+import { usePreviewDrafts, markPreviewExit, PREVIEW_QUERY_FLAG } from './PreviewModeContext';
+import { usePublishAllDrafts } from './usePublishAllDrafts';
+import { DraftChangesPanel } from './DraftChangesPanel';
+export function DraftPreviewBar() {
+    const preview = usePreviewDrafts();
+    const location = useLocation();
+    const navigate = useNavigate();
+    const { t } = useObjectTranslation();
+    const { publishAll, publishing } = usePublishAllDrafts(t);
+    const [changesOpen, setChangesOpen] = useState(false);
+    // Pending-draft count for the Changes button label — what Publish will
+    // actually promote. Refreshed per pathname so drafts staged while the
+    // preview is open (the chat keeps building) update the count.
+    const [pendingCount, setPendingCount] = useState(null);
+    useEffect(() => {
+        if (!preview)
+            return;
+        let cancelled = false;
+        void fetch('/api/v1/meta/_drafts', {
+            credentials: 'include',
+            headers: { Accept: 'application/json' },
+            cache: 'no-store',
+        })
+            .then((r) => (r.ok ? r.json() : null))
+            .then((data) => {
+            if (cancelled || !data)
+                return;
+            const list = Array.isArray(data) ? data : data?.drafts ?? [];
+            setPendingCount(Array.isArray(list) ? list.length : null);
+        })
+            .catch(() => {
+            /* count is decorative — the panel itself reports errors */
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [preview, location.pathname]);
+    if (!preview)
+        return null;
+    const exit = () => {
+        // Tell the sticky preview keeper this is an INTENTIONAL exit, or it
+        // would immediately re-apply the flag we are about to remove.
+        markPreviewExit();
+        const params = new URLSearchParams(location.search);
+        params.delete(PREVIEW_QUERY_FLAG);
+        const qs = params.toString();
+        navigate(`${location.pathname}${qs ? `?${qs}` : ''}${location.hash}`, { replace: true });
+    };
+    const publish = async () => {
+        const result = await publishAll();
+        if (!result.ok)
+            return;
+        // The draft world just became the real world — exit preview and reload so
+        // every renderer re-reads the published registry.
+        exit();
+        setTimeout(() => { try {
+            window.location.reload();
+        }
+        catch { /* ignore */ } }, 300);
+    };
+    return (_jsxs("div", { className: "sticky top-0 z-40 flex items-center gap-3 border-b border-amber-300/70 bg-amber-50 px-4 py-2 text-sm text-amber-900 dark:border-amber-700/60 dark:bg-amber-950/40 dark:text-amber-200", "data-testid": "draft-preview-bar", children: [_jsx(Eye, { className: "h-4 w-4 shrink-0" }), _jsx("p", { className: "min-w-0 flex-1 truncate", children: t('preview.draftBar.message', {
+                    defaultValue: 'Draft preview — you are seeing unpublished changes. Nothing here is live until you publish.',
+                }) }), _jsxs(Button, { size: "sm", variant: "outline", onClick: () => setChangesOpen(true), "data-testid": "draft-preview-changes", children: [_jsx(GitCompareArrows, { className: "mr-1 h-3.5 w-3.5" }), t('preview.draftBar.changes', { defaultValue: 'Changes' }), typeof pendingCount === 'number' ? ` (${pendingCount})` : ''] }), _jsxs(Button, { size: "sm", onClick: publish, disabled: publishing, "data-testid": "draft-preview-publish", children: [_jsx(Rocket, { className: "mr-1 h-3.5 w-3.5" }), publishing
+                        ? t('preview.draftBar.publishing', { defaultValue: 'Publishing…' })
+                        : t('preview.draftBar.publish', { defaultValue: 'Publish' })] }), _jsx(DraftChangesPanel, { open: changesOpen, onOpenChange: setChangesOpen }), _jsxs(Button, { size: "sm", variant: "outline", onClick: exit, "data-testid": "draft-preview-exit", children: [_jsx(X, { className: "mr-1 h-3.5 w-3.5" }), t('preview.draftBar.exit', { defaultValue: 'Exit preview' })] })] }));
+}

package/dist/preview/PreviewDraftEmptyState.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export interface PreviewDraftEmptyStateProps {
+    /** The app the URL asked to preview (`/apps/:appName?preview=draft`). */
+    appName?: string;
+    /** Why the draft world failed to load, when it errored (null = loaded fine). */
+    error?: Error | null;
+    /** Re-read the draft overlay (MetadataProvider.refresh). */
+    onRetry: () => void;
+}
+export declare function PreviewDraftEmptyState({ appName, error, onRetry }: PreviewDraftEmptyStateProps): import("react").JSX.Element;