@object-ui/app-shell 6.2.3 → 7.0.0

package/dist/preview/UnpublishedAppBar.js

@@ -0,0 +1,79 @@
+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-0045 — the "unpublished app" banner. Renders while the CURRENT app is
+ * materialized-but-unlisted (`app.hidden === true`): the app is fully real —
+ * tables, data, interactions — but end users can't see it (launchers exclude
+ * it; the REST gate strips it for non-builders). The banner narrates that
+ * state and offers the one action that matters: Publish, which simply flips
+ * visibility (`hidden: false`) — instant and reversible, per ADR-0045.
+ *
+ * Sibling of DraftPreviewBar (the ADR-0037 draft-overlay watermark): that bar
+ * owns mutation preview (`?preview=draft`); this one owns the materialize
+ * regime. In preview mode this bar yields — the draft bar already narrates.
+ */
+import { useState } from 'react';
+import { useLocation, useParams } from 'react-router-dom';
+import { EyeOff, Rocket } from 'lucide-react';
+import { toast } from 'sonner';
+import { Button } from '@object-ui/components';
+import { useObjectTranslation } from '@object-ui/i18n';
+import { useMetadata } from '../providers/MetadataProvider';
+import { matchAppBySegment } from '../utils/appRoute';
+import { usePreviewDrafts } from './PreviewModeContext';
+export function UnpublishedAppBar() {
+    const preview = usePreviewDrafts();
+    const { appName } = useParams();
+    const location = useLocation();
+    const { apps, refresh } = useMetadata();
+    const { t } = useObjectTranslation();
+    const [publishing, setPublishing] = useState(false);
+    // The draft-preview watermark owns the preview tree; never stack both bars.
+    if (preview)
+        return null;
+    const routeApp = appName ?? location.pathname.match(/\/apps\/([^/?#]+)/)?.[1];
+    if (!routeApp)
+        return null;
+    const app = matchAppBySegment(apps ?? [], routeApp);
+    if (!app || app.hidden !== true)
+        return null;
+    const publish = async () => {
+        setPublishing(true);
+        try {
+            // Publish = the ADR-0045 visibility flip: one metadata write, no
+            // lifecycle machinery. Body is the full current app with hidden:false
+            // (the meta save endpoint replaces the overlay row).
+            const res = await fetch(`/api/v1/meta/app/${encodeURIComponent(routeApp)}`, {
+                method: 'PUT',
+                credentials: 'include',
+                headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                body: JSON.stringify({ ...app, hidden: false }),
+            });
+            if (!res.ok) {
+                const payload = await res.json().catch(() => null);
+                throw new Error(payload?.error?.message ?? payload?.error ?? `HTTP ${res.status}`);
+            }
+            toast.success(t('preview.unpublishedBar.published', {
+                defaultValue: 'Published! The app is now visible to your users.',
+            }));
+            refresh?.();
+        }
+        catch (e) {
+            toast.error(`${t('preview.unpublishedBar.publishFailed', { defaultValue: 'Publish failed' })}: ${e.message}`);
+        }
+        finally {
+            setPublishing(false);
+        }
+    };
+    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": "unpublished-app-bar", children: [_jsx(EyeOff, { className: "h-4 w-4 shrink-0" }), _jsx("p", { className: "min-w-0 flex-1 truncate", children: t('preview.unpublishedBar.message', {
+                    defaultValue: 'Unpublished app — fully functional, but only builders can see it. Publish to make it visible to your users.',
+                }) }), _jsxs(Button, { size: "sm", onClick: publish, disabled: publishing, "data-testid": "unpublished-app-publish", children: [_jsx(Rocket, { className: "mr-1 h-3.5 w-3.5" }), publishing
+                        ? t('preview.unpublishedBar.publishing', { defaultValue: 'Publishing…' })
+                        : t('preview.unpublishedBar.publish', { defaultValue: 'Publish' })] })] }));
+}

package/dist/preview/draftStatus.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+/**
+ * Live draft-status read for the chat's draft cards (panel-as-source-of-truth,
+ * made literal): how many drafts are still PENDING in a package, straight from
+ * the ADR-0033 `_drafts` endpoint. The chat passes this to
+ * `fetchPendingDraftCount` so a card's Publish/Published affordance reflects
+ * the server's CURRENT state — across conversation reloads, other sessions'
+ * publishes, and later edits into the same package — instead of replaying the
+ * tool-result snapshot it was born with.
+ *
+ * Cookie-authenticated like every other console call; tolerant of both
+ * response shapes (`[...]` and `{ drafts: [...] }`).
+ */
+export declare function fetchPendingDraftCount(packageId: string): Promise<number>;

package/dist/preview/draftStatus.js

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/**
+ * Live draft-status read for the chat's draft cards (panel-as-source-of-truth,
+ * made literal): how many drafts are still PENDING in a package, straight from
+ * the ADR-0033 `_drafts` endpoint. The chat passes this to
+ * `fetchPendingDraftCount` so a card's Publish/Published affordance reflects
+ * the server's CURRENT state — across conversation reloads, other sessions'
+ * publishes, and later edits into the same package — instead of replaying the
+ * tool-result snapshot it was born with.
+ *
+ * Cookie-authenticated like every other console call; tolerant of both
+ * response shapes (`[...]` and `{ drafts: [...] }`).
+ */
+export async function fetchPendingDraftCount(packageId) {
+    const res = await fetch(`/api/v1/meta/_drafts?packageId=${encodeURIComponent(packageId)}`, { 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 ?? data?.data?.drafts ?? [];
+    return Array.isArray(list) ? list.length : 0;
+}

package/dist/preview/usePublishAllDrafts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+type TranslateFn = (key: string, opts?: Record<string, unknown>) => string;
+export interface PublishAllResult {
+    ok: boolean;
+    /** Count of drafts the call attempted to publish. */
+    attempted: number;
+}
+export declare function usePublishAllDrafts(t: TranslateFn): {
+    publishAll: () => Promise<PublishAllResult>;
+    publishing: boolean;
+};
+export {};

package/dist/preview/usePublishAllDrafts.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+/**
+ * One-click "publish everything pending" — shared by the Home pending-drafts
+ * banner and the ADR-0037 draft-preview bar, so both surfaces publish through
+ * the SAME governed path and report the SAME health.
+ *
+ * Package-bound drafts go through `POST /packages/:id/publish-drafts` — the
+ * path that orders structure-before-seeds server-side and runs the ADR-0038
+ * L3 runtime probes; findings surface as a loud warning toast instead of a
+ * blind "Published!". Package-less drafts fall back to by-reference publish
+ * (structure first, seeds last) so they never dead-end.
+ */
+import { useCallback, useState } from 'react';
+import { toast } from 'sonner';
+import { publishHealthFromResponse } from '@object-ui/plugin-chatbot';
+import { useMetadataClient } from '../views/metadata-admin/useMetadata';
+export function usePublishAllDrafts(t) {
+    const client = useMetadataClient();
+    const [publishing, setPublishing] = useState(false);
+    const publishAll = useCallback(async () => {
+        setPublishing(true);
+        try {
+            const pending = ((await client.listDrafts?.({})) || [])
+                .filter((d) => 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,
+            }));
+            if (pending.length === 0) {
+                toast.info(t('home.pendingDrafts.nothing', { defaultValue: 'Nothing to publish.' }));
+                return { ok: true, attempted: 0 };
+            }
+            const packageIds = [...new Set(pending.map((d) => d.packageId).filter((p) => p !== null))];
+            const orphans = pending.filter((d) => d.packageId === null);
+            const seedProblems = [];
+            const probeProblems = [];
+            let seededRows = 0;
+            const recordHealth = (health) => {
+                if (!health)
+                    return;
+                if (health.seedError)
+                    seedProblems.push(health.seedError);
+                if (typeof health.seededRows === 'number')
+                    seededRows += health.seededRows;
+                for (const issue of health.issues ?? []) {
+                    if (issue.severity === 'error')
+                        probeProblems.push(issue.message);
+                }
+            };
+            for (const packageId of packageIds) {
+                const res = await fetch(`/api/v1/packages/${encodeURIComponent(packageId)}/publish-drafts`, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                    body: '{}',
+                });
+                const payload = await res.json().catch(() => null);
+                if (!res.ok || payload?.success === false) {
+                    throw new Error(payload?.error?.message || `HTTP ${res.status}`);
+                }
+                recordHealth(publishHealthFromResponse(payload));
+            }
+            const ordered = [
+                ...orphans.filter((d) => d.type !== 'seed'),
+                ...orphans.filter((d) => d.type === 'seed'),
+            ];
+            for (const d of ordered) {
+                const res = await client.publishDraft(d.type, d.name);
+                const seedApplied = res?.seedApplied;
+                if (seedApplied && seedApplied.success === false) {
+                    seedProblems.push(seedApplied.error ?? `${d.name}: sample data failed to load`);
+                }
+            }
+            if (probeProblems.length > 0) {
+                toast.warning(t('home.pendingDrafts.probeWarn', { defaultValue: 'Published, but verification found problems.' }), { description: probeProblems[0] });
+            }
+            else if (seedProblems.length > 0) {
+                toast.warning(t('home.pendingDrafts.seedWarn', { defaultValue: 'Published, but some sample data failed to load.' }), { description: seedProblems[0] });
+            }
+            else {
+                toast.success(seededRows > 0
+                    ? t('home.pendingDrafts.publishedVerified', {
+                        count: seededRows,
+                        defaultValue: 'Published & verified — {{count}} sample row(s) live.',
+                    })
+                    : t('home.pendingDrafts.published', { defaultValue: 'Published! Your changes are live.' }));
+            }
+            return { ok: true, attempted: pending.length };
+        }
+        catch (e) {
+            toast.error(`${t('home.pendingDrafts.publishFailed', { defaultValue: 'Publish failed' })}: ${e.message}`);
+            return { ok: false, attempted: 0 };
+        }
+        finally {
+            setPublishing(false);
+        }
+    }, [client, t]);
+    return { publishAll, publishing };
+}

package/dist/providers/AdapterProvider.d.ts

@@ -18,4 +18,4 @@ interface AdapterProviderProps {
  * Creates an ObjectStackAdapter, connects to the API, then provides it to children.
  * Shows nothing (returns null) until the adapter is ready.
  */
-export declare function AdapterProvider({ children, adapter: externalAdapter }: AdapterProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function AdapterProvider({ children, adapter: externalAdapter }: AdapterProviderProps): import("react").JSX.Element;

package/dist/providers/AdapterProvider.js

@@ -11,6 +11,7 @@ import { useState, useEffect } from 'react';
 import { ObjectStackAdapter } from '@object-ui/data-objectstack';
 import { createAuthenticatedFetch } from '@object-ui/auth';
 import { AdapterCtx } from '@object-ui/react';
+import { installSettleSignalGlobal, withSettleSignal } from '../observability/settleSignal';
 export { useAdapter } from '@object-ui/react';
 /**
  * Creates an ObjectStackAdapter, connects to the API, then provides it to children.
@@ -24,11 +25,15 @@ export function AdapterProvider({ children, adapter: externalAdapter }) {
             return;
         }
         let cancelled = false;
+        // Expose window.__objectui.{pendingRequests,idle,whenIdle} so an automated
+        // (AI) browser driver has one "is the app settled?" predicate (ADR-0054 C5).
+        installSettleSignalGlobal();
         async function init() {
             try {
                 const a = new ObjectStackAdapter({
                     baseUrl: import.meta.env.VITE_SERVER_URL || '',
-                    fetch: createAuthenticatedFetch(),
+                    // Count every outbound request in the global in-flight signal (C5).
+                    fetch: withSettleSignal(createAuthenticatedFetch()),
                     autoReconnect: true,
                     maxReconnectAttempts: 5,
                     reconnectDelay: 1000,

package/dist/providers/ExpressionProvider.d.ts

@@ -41,7 +41,7 @@ interface ExpressionProviderProps {
     data?: Record<string, any>;
     features?: Record<string, any>;
 }
-export declare function ExpressionProvider({ children, user, app, data, features }: ExpressionProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ExpressionProvider({ children, user, app, data, features }: ExpressionProviderProps): React.JSX.Element;
 /**
  * Hook to access the expression context.
  * Returns the full context value or a default empty context.

package/dist/providers/MetadataProvider.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-import type { ObjectStackAdapter } from '@object-ui/data-objectstack';
+import { type ObjectStackAdapter } from '@object-ui/data-objectstack';
 import { useMetadata, type MetadataContextValue, type MetadataState } from '@object-ui/react';
 export type { MetadataState, MetadataContextValue };
 export { useMetadataItem } from '@object-ui/react';
@@ -10,7 +10,22 @@ interface MetadataProviderProps {
     adapter: ObjectStackAdapter;
     ttlMs?: number;
 }
-export declare function MetadataProvider({ children, adapter, ttlMs }: MetadataProviderProps): import("react/jsx-runtime").JSX.Element;
+/** Exported for tests — both metadata sources must normalize identically. */
+export declare function extractItems(res: unknown): any[];
+export declare function mergeViewsIntoObjects(objects: any[], views: any[]): any[];
+/**
+ * Relationship-driven master-detail: a child object's `master_detail`/`lookup`
+ * field can carry `inlineEdit: true` to declare "edit me inline within my
+ * parent's form". This pass scans every object for such fields and merges the
+ * resulting child collections into each parent object's form view as
+ * `subforms` — so the parent's standard create/edit form renders an atomic
+ * master-detail form with NO view config and NO bespoke page. The intent lives
+ * in the data model (where it's defined once, e.g. by an AI modelling the
+ * schema); forms just follow. An explicit `form.subforms` entry for the same
+ * child overrides the model-derived one.
+ */
+export declare function attachInlineSubforms(objects: any[]): any[];
+export declare function MetadataProvider({ children, adapter, ttlMs }: MetadataProviderProps): import("react").JSX.Element;
 export declare function useMetadataType(type: string): {
     items: any[];
     loading: boolean;

package/dist/providers/MetadataProvider.js

@@ -1,6 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useState, useEffect, useCallback, useRef, useMemo, } from 'react';
+import { MetadataClient } from '@object-ui/data-objectstack';
+import { resolveInlineMode } from '@object-ui/plugin-form';
 import { MetadataCtx, useMetadata } from '@object-ui/react';
+import { usePreviewDrafts } from '../preview/PreviewModeContext';
+import { subscribeCanvasInvalidate, subscribeMetadataRefresh } from '../assistant/assistantBus';
 export { useMetadataItem } from '@object-ui/react';
 export { useMetadata };
 // ---------------------------------------------------------------------------
@@ -41,7 +45,15 @@ function debug(...args) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-function extractItems(res) {
+/** Exported for tests — both metadata sources must normalize identically. */
+export function extractItems(res) {
+    // Both source shapes must parse: the adapter SDK returns the wrapped
+    // `{ type, items: [...] }` envelope, while the ADR-0037 preview path's
+    // MetadataClient.list() returns the already-unwrapped array. Dropping the
+    // bare-array shape silently emptied the ENTIRE draft-preview world (every
+    // type read 0 items), stranding the Live Canvas on "No Apps Configured".
+    if (Array.isArray(res))
+        return res;
     if (res && typeof res === 'object' && 'items' in res && Array.isArray(res.items)) {
         return res.items;
     }
@@ -61,14 +73,54 @@ function isNamedItem(item) {
         'name' in item &&
         typeof item.name === 'string');
 }
-function mergeViewsIntoObjects(objects, views) {
+/** A first-class ViewItem carries a `viewKind` discriminant + `object` binding. */
+function isViewItem(view) {
+    return !!view && typeof view === 'object' && !!view.viewKind && !!view.object;
+}
+export function mergeViewsIntoObjects(objects, views) {
+    var _a;
     if (!objects.length || !views.length)
         return objects;
     const byObject = {};
+    // Objects that received expanded ViewItems — their legacy aggregated
+    // container (also present in the `view` list) is superseded and skipped.
+    const hasViewItems = new Set();
+    for (const view of views) {
+        if (isViewItem(view))
+            hasViewItems.add(view.object);
+    }
     for (const view of views) {
+        // ── New protocol: independent ViewItem ({ name, object, viewKind, config }) ──
+        if (isViewItem(view)) {
+            const bucket = (byObject[_a = view.object] || (byObject[_a] = { listViews: {}, formViews: {} }));
+            // Canonical `<object>.<key>` name doubles as the view id, so `/view/<name>`
+            // URLs resolve directly against the switcher tab ids.
+            const key = view.name || `${view.object}.${view.viewKind}`;
+            const body = view.config && typeof view.config === 'object' ? view.config : {};
+            // Flatten `config` to the legacy NamedListView/FormView shape the
+            // renderer consumes (type/data/columns/sections at top level); carry the
+            // item-level label/isDefault and stamp `name` so primary-view promotion
+            // (which matches on `list.name`) finds this entry by its listViews key.
+            const entry = { ...body, name: key, label: view.label ?? body.label, isDefault: !!view.isDefault };
+            if (view.viewKind === 'form') {
+                bucket.formViews[key] = entry;
+                if (view.isDefault || !bucket.form)
+                    bucket.form = entry;
+            }
+            else {
+                bucket.listViews[key] = entry;
+                if (view.isDefault)
+                    bucket.primary = entry;
+            }
+            continue;
+        }
+        // ── Legacy aggregated container ({ list, form, listViews, formViews }) ──
         const objName = view?.name || view?.list?.data?.object || view?.form?.data?.object;
         if (!objName)
             continue;
+        // Expanded ViewItems supersede the bare container for this object.
+        if (hasViewItems.has(objName))
+            continue;
         const bucket = (byObject[objName] || (byObject[objName] = { listViews: {}, formViews: {} }));
         if (view.list) {
             // Preserve the primary list view as `obj.list` per @objectstack/spec
@@ -115,6 +167,67 @@ function mergeViewsIntoObjects(objects, views) {
         return merged;
     });
 }
+/**
+ * Relationship-driven master-detail: a child object's `master_detail`/`lookup`
+ * field can carry `inlineEdit: true` to declare "edit me inline within my
+ * parent's form". This pass scans every object for such fields and merges the
+ * resulting child collections into each parent object's form view as
+ * `subforms` — so the parent's standard create/edit form renders an atomic
+ * master-detail form with NO view config and NO bespoke page. The intent lives
+ * in the data model (where it's defined once, e.g. by an AI modelling the
+ * schema); forms just follow. An explicit `form.subforms` entry for the same
+ * child overrides the model-derived one.
+ */
+export function attachInlineSubforms(objects) {
+    if (!objects?.length)
+        return objects;
+    const inlineByParent = {};
+    for (const child of objects) {
+        const fields = child?.fields;
+        if (!fields)
+            continue;
+        const entries = Array.isArray(fields)
+            ? fields.map((f) => [f?.name, f])
+            : Object.entries(fields);
+        for (const [fname, fdef] of entries) {
+            const d = fdef;
+            if (!fname || !d?.inlineEdit)
+                continue;
+            if (d.type !== 'master_detail' && d.type !== 'lookup')
+                continue;
+            const parent = d.reference;
+            if (!parent)
+                continue;
+            (inlineByParent[parent] || (inlineByParent[parent] = [])).push({
+                childObject: child.name,
+                relationshipField: fname,
+                // Resolve the inline-edit form factor (grid vs per-row form) from the
+                // declared value, falling back to the smart default by child shape.
+                inlineMode: resolveInlineMode(child, d.inlineEdit, { relationshipField: fname }),
+                ...(d.inlineTitle ? { title: d.inlineTitle } : {}),
+                ...(Array.isArray(d.inlineColumns) ? { columns: d.inlineColumns } : {}),
+                ...(typeof d.inlineAmountField === 'string' ? { amountField: d.inlineAmountField } : {}),
+            });
+        }
+    }
+    if (!Object.keys(inlineByParent).length)
+        return objects;
+    return objects.map((obj) => {
+        const derived = inlineByParent[obj.name];
+        if (!derived?.length)
+            return obj;
+        const form = { ...(obj.form || { type: 'simple' }) };
+        const explicit = Array.isArray(form.subforms) ? form.subforms : [];
+        const explicitChildren = new Set(explicit.map((s) => s.childObject));
+        // Model-derived first; an explicit view subform for the same child wins.
+        form.subforms = [...derived.filter((d) => !explicitChildren.has(d.childObject)), ...explicit];
+        const next = { ...obj, form };
+        if (obj.formViews?.default) {
+            next.formViews = { ...obj.formViews, default: { ...obj.formViews.default, subforms: form.subforms } };
+        }
+        return next;
+    });
+}
 function emptyEntry() {
     return {
         status: 'idle',
@@ -157,6 +270,20 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
     const itemPromisesRef = useRef(new Map());
     const adapterRef = useRef(adapter);
     adapterRef.current = adapter;
+    // ADR-0037 Live Canvas: when the tree is in draft-preview mode, metadata
+    // reads come from the REST `?preview=draft` overlay (pending ADR-0033
+    // drafts win over active) instead of the adapter SDK. The MetadataClient
+    // is used because the SDK's meta API doesn't carry the preview flag; same
+    // endpoints, same cookie auth. Reads only — every write path is unchanged.
+    const previewDrafts = usePreviewDrafts();
+    const previewClient = useMemo(() => {
+        if (!previewDrafts)
+            return null;
+        const baseUrl = (typeof import.meta !== 'undefined' && import.meta.env?.VITE_SERVER_URL) || '';
+        return new MetadataClient({ baseUrl, previewDrafts: true });
+    }, [previewDrafts]);
+    const previewClientRef = useRef(previewClient);
+    previewClientRef.current = previewClient;
     const [version, setVersion] = useState(0);
     // Defer state bumps so they never occur synchronously during a consumer's
     // render phase. `ensureType` may be invoked from inside `useMemo` getters
@@ -171,6 +298,14 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
             Promise.resolve().then(() => setVersion(v => v + 1));
         }
     }, []);
+    // Entering/leaving preview swaps the entire metadata source — the published
+    // and draft-overlaid worlds must never mix in one cache. Drop everything and
+    // let consumers refetch through the new source.
+    useEffect(() => {
+        cacheRef.current.clear();
+        itemPromisesRef.current.clear();
+        bump();
+    }, [previewDrafts, bump]);
     const getEntry = useCallback((type) => {
         let entry = cacheRef.current.get(type);
         if (!entry) {
@@ -190,9 +325,13 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
         const started = Date.now();
         entry.status = 'loading';
         entry.error = null;
-        const client = adapterRef.current.getClient();
-        const promise = client.meta
-            .getItems(type)
+        // Preview mode reads the draft-overlaid world (`?preview=draft`);
+        // normal mode reads the adapter SDK as before.
+        const preview = previewClientRef.current;
+        const fetchItems = preview
+            ? preview.list(type)
+            : adapterRef.current.getClient().meta.getItems(type);
+        const promise = fetchItems
             .then((res) => {
             const items = extractItems(res);
             entry.items = items;
@@ -206,7 +345,9 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
                     entry.byName.set(it.name, it);
                 }
             }
-            if (type === 'app')
+            // Never let the draft-overlaid world poison the published session
+            // cache — preview is ephemeral by design.
+            if (type === 'app' && !preview)
                 saveToSession(type, items);
             debug(`fetched type=${type} items=${items.length} in ${Date.now() - started}ms`);
             bump();
@@ -243,9 +384,11 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
         if (existing)
             return existing;
         const started = Date.now();
-        const client = adapterRef.current.getClient();
-        const promise = client.meta
-            .getItem(type, name)
+        const preview = previewClientRef.current;
+        const fetchItem = preview
+            ? preview.get(type, name)
+            : adapterRef.current.getClient().meta.getItem(type, name);
+        const promise = fetchItem
             .then((res) => {
             const item = extractItem(res);
             if (item)
@@ -297,11 +440,35 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
         }
         bump();
     }, [bump]);
+    // ADR-0037 P2.5 — same-document live refresh: while this tree renders the
+    // draft overlay, chat hosts announce each drafted artifact on the assistant
+    // bus; drop that type's cache entry so the next read refetches the updated
+    // draft world. Published-mode trees ignore the events entirely.
+    useEffect(() => {
+        if (!previewDrafts)
+            return;
+        return subscribeCanvasInvalidate(({ type }) => {
+            invalidate(type);
+        });
+    }, [previewDrafts, invalidate]);
+    // Live-metadata-changed refresh: a publish (drafts → live) or a marketplace
+    // install changed the registry out-of-band, so the schema this tree cached
+    // is stale. Refetch every loaded type — open forms/views/nav then reflect
+    // the new live world without a manual page reload (the chat-card "Publish"
+    // and Browse-page install paths do not reload, unlike the DraftPreviewBar).
+    // NOT gated to preview-drafts mode: the live world every tree reads changed.
+    useEffect(() => {
+        return subscribeMetadataRefresh(() => {
+            void refresh();
+        });
+    }, [refresh]);
     const [initialLoading, setInitialLoading] = useState(true);
     const [initialError, setInitialError] = useState(null);
     useEffect(() => {
         let cancelled = false;
-        const cached = loadFromSession('app');
+        // Session-cached apps are PUBLISHED-world data — seeding them while in
+        // draft preview would flash the wrong universe before the fetch lands.
+        const cached = previewDrafts ? null : loadFromSession('app');
         if (cached) {
             const entry = getEntry('app');
             entry.items = cached;
@@ -334,7 +501,7 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
         return () => {
             cancelled = true;
         };
-    }, [adapter, ensureType, getEntry, bump]);
+    }, [adapter, ensureType, getEntry, bump, previewDrafts]);
     const value = useMemo(() => {
         void version;
         const readType = (type) => {
@@ -350,7 +517,8 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
             get objects() {
                 const objs = readType(TYPE_BY_STATE_KEY.objects);
                 const views = readType('view');
-                return views.length ? mergeViewsIntoObjects(objs, views) : objs;
+                const merged = views.length ? mergeViewsIntoObjects(objs, views) : objs;
+                return attachInlineSubforms(merged);
             },
             get dashboards() {
                 return readType(TYPE_BY_STATE_KEY.dashboards);
@@ -368,6 +536,9 @@ export function MetadataProvider({ children, adapter, ttlMs = DEFAULT_TTL_MS })
             ensureType,
             getItem,
             getItemsByType,
+            // Pure read — must NOT kick a fetch, so render-phase status checks
+            // can't recurse into ensureType.
+            getTypeStatus: (type) => getEntry(type).status,
         };
         return base;
     }, [version, initialLoading, initialError, ensureType, getItem, getEntry, refresh, invalidate]);