@object-ui/app-shell 6.2.3 → 7.0.0

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/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;

package/dist/preview/PreviewDraftEmptyState.js

@@ -0,0 +1,47 @@
+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 draft preview's own empty/error states.
+ *
+ * A `?preview=draft` tree (the Live Canvas iframe, or a hand-opened preview
+ * URL) must NEVER fall through to the console's generic "No Apps Configured"
+ * screen: that screen tells the user nothing exists and offers "Create Your
+ * First App" — both wrong and disorienting inside a preview of an app the AI
+ * just drafted. Preview has exactly three honest non-happy states, all
+ * rendered here:
+ *
+ *  - loading failed   → say so, offer Retry (the overlay read errored);
+ *  - app not in draft → the build likely failed or hasn't run — point the
+ *                       user back to the conversation, never to "create app";
+ *  - nothing drafted  → same message, generic (no app name in the URL).
+ *
+ * Deliberately CTA-free beyond Retry: the preview is a window owned by the
+ * build conversation; every corrective action lives there.
+ */
+import { Eye, RefreshCw, TriangleAlert } from 'lucide-react';
+import { Empty, EmptyTitle, EmptyDescription, Button } from '@object-ui/components';
+import { useObjectTranslation } from '@object-ui/i18n';
+export function PreviewDraftEmptyState({ appName, error, onRetry }) {
+    const { t } = useObjectTranslation();
+    const failed = Boolean(error);
+    return (_jsx("div", { className: "flex h-screen items-center justify-center", "data-testid": "preview-draft-empty-state", children: _jsxs(Empty, { children: [_jsx("div", { className: "mb-2 flex justify-center text-muted-foreground", "aria-hidden": "true", children: failed ? _jsx(TriangleAlert, { className: "h-8 w-8" }) : _jsx(Eye, { className: "h-8 w-8" }) }), _jsx(EmptyTitle, { children: failed
+                        ? t('preview.empty.loadFailedTitle', { defaultValue: 'Draft preview failed to load' })
+                        : appName
+                            ? t('preview.empty.notReadyTitle', {
+                                app: appName,
+                                defaultValue: '“{{app}}” isn’t in the draft yet',
+                            })
+                            : t('preview.empty.nothingTitle', { defaultValue: 'Nothing to preview yet' }) }), _jsx(EmptyDescription, { children: failed
+                        ? t('preview.empty.loadFailedDescription', {
+                            defaultValue: 'The draft overlay could not be read. Retry, or check your connection.',
+                        })
+                        : t('preview.empty.notReadyDescription', {
+                            defaultValue: 'The build may still be running, or it may have failed before this app was staged. Check the conversation for the build status — this pane refreshes as drafts land.',
+                        }) }), _jsx("div", { className: "mt-4 flex justify-center", children: _jsxs(Button, { variant: "outline", onClick: onRetry, "data-testid": "preview-draft-retry", children: [_jsx(RefreshCw, { className: "mr-1.5 h-3.5 w-3.5" }), t('preview.empty.retry', { defaultValue: 'Retry' })] }) })] }) }));
+}

package/dist/preview/PreviewModeContext.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 Live Canvas — preview mode plumbing.
+ *
+ * One URL flag (`?preview=draft`) flips the whole renderer tree into
+ * "as-if-published" mode: metadata reads overlay pending ADR-0033 drafts on
+ * the active registry, so an unpublished app/view/dashboard renders exactly
+ * what Publish would make real. The canvas (and the Preview button in chat)
+ * navigate with this flag; everything below just reads the context.
+ *
+ * Read-only by design: preview changes the SOURCE of metadata reads, never
+ * writes, and Publish remains the single commit gate.
+ */
+import { type ReactNode } from 'react';
+/** Query flag that switches the console into draft-preview mode. */
+export declare const PREVIEW_QUERY_FLAG = "preview";
+export declare const PREVIEW_QUERY_VALUE = "draft";
+/** True when `search` (a `location.search` string) carries `preview=draft`. */
+export declare function isPreviewSearch(search: string): boolean;
+/**
+ * Declare that the NEXT navigation is an intentional exit from draft preview.
+ * Call right before navigating away (e.g. the preview bar's Exit button);
+ * without it, the sticky keeper re-applies `?preview=draft` to in-app
+ * navigation so a click inside the previewed app can't silently drop the
+ * draft world mid-session.
+ */
+export declare function markPreviewExit(): void;
+/**
+ * Provides the preview-mode flag to the tree. Reads the router location
+ * LIVE, so entering/leaving `?preview=draft` flips consumers without a
+ * remount. `force` overrides the URL — the Live Canvas mounts its embedded
+ * renderer subtree with `force` so the canvas is always a draft window
+ * regardless of the host page's own URL.
+ *
+ * STICKY by design: preview is URL-keyed, but in-app navigation (the app's
+ * landing redirect, sidebar links, row clicks) builds URLs without the
+ * query string. Once the tree is in preview, this provider re-applies the
+ * flag (history REPLACE, no extra entry) to any same-session navigation
+ * that lost it — so the only way out of the draft world is the explicit
+ * Exit affordance ({@link markPreviewExit}), never an accidental click.
+ */
+export declare function PreviewModeProvider({ force, children }: {
+    force?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Whether the current tree renders the draft-overlaid world. Defaults to
+ * false outside a provider, so surfaces that never mount preview (login,
+ * bare pages) keep reading published metadata only.
+ */
+export declare function usePreviewDrafts(): boolean;

package/dist/preview/PreviewModeContext.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx } 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 Live Canvas — preview mode plumbing.
+ *
+ * One URL flag (`?preview=draft`) flips the whole renderer tree into
+ * "as-if-published" mode: metadata reads overlay pending ADR-0033 drafts on
+ * the active registry, so an unpublished app/view/dashboard renders exactly
+ * what Publish would make real. The canvas (and the Preview button in chat)
+ * navigate with this flag; everything below just reads the context.
+ *
+ * Read-only by design: preview changes the SOURCE of metadata reads, never
+ * writes, and Publish remains the single commit gate.
+ */
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+const PreviewModeContext = createContext(false);
+/** Query flag that switches the console into draft-preview mode. */
+export const PREVIEW_QUERY_FLAG = 'preview';
+export const PREVIEW_QUERY_VALUE = 'draft';
+/** True when `search` (a `location.search` string) carries `preview=draft`. */
+export function isPreviewSearch(search) {
+    return new URLSearchParams(search).get(PREVIEW_QUERY_FLAG) === PREVIEW_QUERY_VALUE;
+}
+// Set by markPreviewExit() for exactly one navigation: the user explicitly
+// left preview (DraftPreviewBar's Exit / post-publish), so the keeper below
+// must NOT re-stick the flag onto the next location.
+let previewExitRequested = false;
+/**
+ * Declare that the NEXT navigation is an intentional exit from draft preview.
+ * Call right before navigating away (e.g. the preview bar's Exit button);
+ * without it, the sticky keeper re-applies `?preview=draft` to in-app
+ * navigation so a click inside the previewed app can't silently drop the
+ * draft world mid-session.
+ */
+export function markPreviewExit() {
+    previewExitRequested = true;
+}
+/**
+ * Provides the preview-mode flag to the tree. Reads the router location
+ * LIVE, so entering/leaving `?preview=draft` flips consumers without a
+ * remount. `force` overrides the URL — the Live Canvas mounts its embedded
+ * renderer subtree with `force` so the canvas is always a draft window
+ * regardless of the host page's own URL.
+ *
+ * STICKY by design: preview is URL-keyed, but in-app navigation (the app's
+ * landing redirect, sidebar links, row clicks) builds URLs without the
+ * query string. Once the tree is in preview, this provider re-applies the
+ * flag (history REPLACE, no extra entry) to any same-session navigation
+ * that lost it — so the only way out of the draft world is the explicit
+ * Exit affordance ({@link markPreviewExit}), never an accidental click.
+ */
+export function PreviewModeProvider({ force, children }) {
+    const location = useLocation();
+    const navigate = useNavigate();
+    const fromUrl = useMemo(() => isPreviewSearch(location.search), [location.search]);
+    // Sticky state: stays true across the flag-less navigation window so the
+    // CONTEXT VALUE never flickers false mid-session. A flicker is not benign —
+    // it swaps the whole metadata source to published for one render, which
+    // (a) wastes a full refetch and (b) feeds cross-world diffs to effects
+    // like NavigationSyncEffect that must never see the two worlds as one
+    // timeline (that misread once WROTE nav changes from inside a preview).
+    const [sticky, setSticky] = useState(fromUrl);
+    useEffect(() => {
+        if (fromUrl) {
+            setSticky(true);
+            previewExitRequested = false;
+            return;
+        }
+        if (!sticky)
+            return;
+        if (previewExitRequested) {
+            previewExitRequested = false;
+            setSticky(false);
+            return;
+        }
+        // In-app navigation lost the flag without an explicit exit — restore it
+        // in place (history REPLACE, no extra entry) so a refresh/share of the
+        // URL stays in the draft world too.
+        const params = new URLSearchParams(location.search);
+        params.set(PREVIEW_QUERY_FLAG, PREVIEW_QUERY_VALUE);
+        navigate(`${location.pathname}?${params.toString()}${location.hash}`, { replace: true });
+    }, [fromUrl, sticky, location.pathname, location.search, location.hash, navigate]);
+    return (_jsx(PreviewModeContext.Provider, { value: force ?? (fromUrl || sticky), children: children }));
+}
+/**
+ * Whether the current tree renders the draft-overlaid world. Defaults to
+ * false outside a provider, so surfaces that never mount preview (login,
+ * bare pages) keep reading published metadata only.
+ */
+export function usePreviewDrafts() {
+    return useContext(PreviewModeContext);
+}

package/dist/preview/UnpublishedAppBar.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 UnpublishedAppBar(): import("react").JSX.Element | null;