@object-ui/app-shell 11.3.0 → 11.5.0

package/dist/views/metadata-admin/inspectors/nav-target.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Nav-item target resolution (#2245) — the pure logic behind
+ * AppNavInspector's type + per-type target editing.
+ *
+ * The nav contract is a discriminated union on `type`; each type carries its
+ * own typed target field. `object` items additionally have FOUR mutually
+ * exclusive landing modes matching resolveHref's precedence
+ * (`recordId` → `filters` → `viewName` → bare default). The mode is NEVER
+ * persisted — it is derived from which fields are present — and switching
+ * type/mode explicitly clears the other target fields plus the legacy
+ * off-spec keys (`path` / `kind` / aliases), so every edit normalizes the
+ * item to spec shape ("edit is the migration").
+ */
+/** Nav item types the inspector offers (spec union minus separator/action). */
+export declare const NAV_ITEM_TYPES: readonly ["object", "page", "dashboard", "report", "url", "group"];
+export type NavItemType = (typeof NAV_ITEM_TYPES)[number];
+/** Landing modes for `type: 'object'`, in resolveHref precedence order. */
+export declare const OBJECT_TARGET_MODES: readonly ["default", "view", "record", "filters"];
+export type ObjectTargetMode = (typeof OBJECT_TARGET_MODES)[number];
+/**
+ * Per-type target descriptor: which field the picker writes and which
+ * metadata list feeds its options (`client.list(metaType)`); free-text
+ * types have no metaType.
+ */
+export declare const NAV_TYPE_TARGETS: Record<NavItemType, {
+    targetKey?: string;
+    metaType?: string;
+}>;
+/**
+ * Infer the effective type of a (possibly legacy) nav node for display:
+ * spec `type` wins; else legacy `kind`; else the presence of typed or
+ * legacy target fields; else children ⇒ group; else null (unset).
+ */
+export declare function inferNavItemType(node: Record<string, unknown>): NavItemType | null;
+/**
+ * Derive an object item's landing mode from field presence, following
+ * resolveHref's precedence — the mode is a projection, never stored.
+ */
+export declare function deriveObjectTargetMode(node: Record<string, unknown>): ObjectTargetMode;
+/**
+ * The patch that clears everything EXCEPT the fields the given type+mode
+ * legitimately owns. Always includes the legacy keys. Spread this before
+ * the fields being set so a type/mode switch leaves no stale target behind.
+ */
+export declare function clearedTargetPatch(keep?: ReadonlyArray<string>): Record<string, undefined>;
+/** Fields each object landing mode owns (besides objectName). */
+export declare const OBJECT_MODE_FIELDS: Record<ObjectTargetMode, ReadonlyArray<string>>;
+/**
+ * Ensure a spec-valid snake_case `id`. Existing ids are kept; otherwise one
+ * is derived from the target/label and uniqued against sibling ids.
+ */
+export declare function ensureNavId(node: Record<string, unknown>, siblings: ReadonlyArray<Record<string, unknown>>, seed?: string): string;

package/dist/views/metadata-admin/inspectors/nav-target.js

@@ -0,0 +1,149 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Nav-item target resolution (#2245) — the pure logic behind
+ * AppNavInspector's type + per-type target editing.
+ *
+ * The nav contract is a discriminated union on `type`; each type carries its
+ * own typed target field. `object` items additionally have FOUR mutually
+ * exclusive landing modes matching resolveHref's precedence
+ * (`recordId` → `filters` → `viewName` → bare default). The mode is NEVER
+ * persisted — it is derived from which fields are present — and switching
+ * type/mode explicitly clears the other target fields plus the legacy
+ * off-spec keys (`path` / `kind` / aliases), so every edit normalizes the
+ * item to spec shape ("edit is the migration").
+ */
+/** Nav item types the inspector offers (spec union minus separator/action). */
+export const NAV_ITEM_TYPES = ['object', 'page', 'dashboard', 'report', 'url', 'group'];
+/** Landing modes for `type: 'object'`, in resolveHref precedence order. */
+export const OBJECT_TARGET_MODES = ['default', 'view', 'record', 'filters'];
+/**
+ * Per-type target descriptor: which field the picker writes and which
+ * metadata list feeds its options (`client.list(metaType)`); free-text
+ * types have no metaType.
+ */
+export const NAV_TYPE_TARGETS = {
+    object: { targetKey: 'objectName', metaType: 'object' },
+    page: { targetKey: 'pageName', metaType: 'page' },
+    dashboard: { targetKey: 'dashboardName', metaType: 'dashboard' },
+    report: { targetKey: 'reportName', metaType: 'report' },
+    url: { targetKey: 'url' },
+    group: {},
+};
+/** Typed target fields across the whole union. */
+const TYPED_TARGET_FIELDS = [
+    'objectName',
+    'viewName',
+    'recordId',
+    'recordMode',
+    'filters',
+    'pageName',
+    'dashboardName',
+    'reportName',
+    'url',
+    'target',
+    'params',
+];
+/**
+ * Legacy / off-spec keys that runtime resolution ignores and save-time
+ * validation rejects. Cleared on EVERY inspector edit so stale keys never
+ * hijack behavior or fail validation (`navigation.0: Invalid input`).
+ */
+const LEGACY_KEYS = ['path', 'kind', 'href', 'route', 'object', 'page', 'dashboard', 'report'];
+/**
+ * Map a legacy `kind` value (the old inspector's vocabulary) to the spec
+ * type; `link` was never a spec member — it maps to `url`.
+ */
+const LEGACY_KIND_TO_TYPE = {
+    object: 'object',
+    page: 'page',
+    dashboard: 'dashboard',
+    report: 'report',
+    link: 'url',
+    url: 'url',
+    group: 'group',
+};
+/**
+ * Infer the effective type of a (possibly legacy) nav node for display:
+ * spec `type` wins; else legacy `kind`; else the presence of typed or
+ * legacy target fields; else children ⇒ group; else null (unset).
+ */
+export function inferNavItemType(node) {
+    const t = node.type;
+    if (typeof t === 'string' && NAV_ITEM_TYPES.includes(t)) {
+        return t;
+    }
+    const kind = node.kind;
+    if (typeof kind === 'string' && LEGACY_KIND_TO_TYPE[kind])
+        return LEGACY_KIND_TO_TYPE[kind];
+    if (node.objectName || node.object)
+        return 'object';
+    if (node.pageName || node.page)
+        return 'page';
+    if (node.dashboardName || node.dashboard)
+        return 'dashboard';
+    if (node.reportName || node.report)
+        return 'report';
+    if (node.url || node.href)
+        return 'url';
+    if (Array.isArray(node.children) && node.children.length > 0)
+        return 'group';
+    const path = node.path;
+    if (typeof path === 'string' && /^https?:/i.test(path))
+        return 'url';
+    return null;
+}
+/**
+ * Derive an object item's landing mode from field presence, following
+ * resolveHref's precedence — the mode is a projection, never stored.
+ */
+export function deriveObjectTargetMode(node) {
+    if (node.recordId)
+        return 'record';
+    const filters = node.filters;
+    if (filters && typeof filters === 'object' && !Array.isArray(filters))
+        return 'filters';
+    if (node.viewName)
+        return 'view';
+    return 'default';
+}
+/**
+ * The patch that clears everything EXCEPT the fields the given type+mode
+ * legitimately owns. Always includes the legacy keys. Spread this before
+ * the fields being set so a type/mode switch leaves no stale target behind.
+ */
+export function clearedTargetPatch(keep = []) {
+    const patch = {};
+    for (const key of [...TYPED_TARGET_FIELDS, ...LEGACY_KEYS]) {
+        if (!keep.includes(key))
+            patch[key] = undefined;
+    }
+    return patch;
+}
+/** Fields each object landing mode owns (besides objectName). */
+export const OBJECT_MODE_FIELDS = {
+    default: ['objectName'],
+    view: ['objectName', 'viewName'],
+    record: ['objectName', 'recordId', 'recordMode'],
+    filters: ['objectName', 'filters'],
+};
+/**
+ * Ensure a spec-valid snake_case `id`. Existing ids are kept; otherwise one
+ * is derived from the target/label and uniqued against sibling ids.
+ */
+export function ensureNavId(node, siblings, seed) {
+    const existing = node.id;
+    if (typeof existing === 'string' && existing)
+        return existing;
+    const raw = (seed ?? String(node.objectName ?? node.label ?? 'item'))
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '') || 'item';
+    const base = `nav_${raw}`;
+    const taken = new Set(siblings.map((s) => (typeof s.id === 'string' ? s.id : '')).filter(Boolean));
+    if (!taken.has(base))
+        return base;
+    let n = 2;
+    while (taken.has(`${base}_${n}`))
+        n++;
+    return `${base}_${n}`;
+}

package/dist/views/metadata-admin/nav-selection.d.ts

@@ -0,0 +1,20 @@
+/** Search param carrying the designer's selected element. */
+export declare const DESIGNER_SEL_PARAM = "sel";
+/** Parse a `sel` param value; returns the nav item id for `nav:<id>`. */
+export declare function parseNavSelParam(value: string | null | undefined): string | null;
+export declare function formatNavSelParam(navId: string): string;
+/**
+ * Locate a nav item by its `id` across all accepted root keys, returning
+ * the positional selection id the canvas/inspector pair uses
+ * (`<rootKey>[i]` / `<rootKey>[i].children[j]`), or null when absent.
+ */
+export declare function findNavPositionById(draft: Record<string, unknown>, navId: string): {
+    selectionId: string;
+    label?: string;
+} | null;
+/**
+ * Read the nav item `id` at a positional selection id (the inverse of
+ * {@link findNavPositionById}); null when the path is invalid or the node
+ * has no id.
+ */
+export declare function navIdAtPosition(draft: Record<string, unknown>, positionalId: string): string | null;

package/dist/views/metadata-admin/nav-selection.js

@@ -0,0 +1,81 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Nav-item deep-link selection (#2272).
+ *
+ * The designer's internal selection ids are POSITIONAL (`navigation[2]`,
+ * `nav[0].children[1]`) — cheap for canvas/inspector wiring but unstable:
+ * they drift on reorder and mean nothing outside one editing session. The
+ * EXTERNAL contract is the nav item's spec-required snake_case `id`,
+ * carried in the URL as `?sel=nav:<id>`. These helpers translate between
+ * the two at the designer boundary; positions never leave component state.
+ */
+import { APP_NAV_ROOT_KEYS } from './inspectors/AppNavInspector';
+/** Search param carrying the designer's selected element. */
+export const DESIGNER_SEL_PARAM = 'sel';
+/** Parse a `sel` param value; returns the nav item id for `nav:<id>`. */
+export function parseNavSelParam(value) {
+    if (!value || !value.startsWith('nav:'))
+        return null;
+    const id = value.slice(4);
+    return id.length > 0 ? id : null;
+}
+export function formatNavSelParam(navId) {
+    return `nav:${navId}`;
+}
+/**
+ * Locate a nav item by its `id` across all accepted root keys, returning
+ * the positional selection id the canvas/inspector pair uses
+ * (`<rootKey>[i]` / `<rootKey>[i].children[j]`), or null when absent.
+ */
+export function findNavPositionById(draft, navId) {
+    const walk = (nodes, prefix) => {
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i];
+            if (!node || typeof node !== 'object')
+                continue;
+            const pos = `${prefix}[${i}]`;
+            if (node.id === navId) {
+                const label = node.label ?? node.title ?? node.name;
+                return { selectionId: pos, label: typeof label === 'string' ? label : undefined };
+            }
+            if (Array.isArray(node.children)) {
+                const hit = walk(node.children, `${pos}.children`);
+                if (hit)
+                    return hit;
+            }
+        }
+        return null;
+    };
+    for (const rootKey of APP_NAV_ROOT_KEYS) {
+        const arr = draft[rootKey];
+        if (!Array.isArray(arr))
+            continue;
+        const hit = walk(arr, rootKey);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/**
+ * Read the nav item `id` at a positional selection id (the inverse of
+ * {@link findNavPositionById}); null when the path is invalid or the node
+ * has no id.
+ */
+export function navIdAtPosition(draft, positionalId) {
+    const segs = positionalId.split('.');
+    let node;
+    for (let s = 0; s < segs.length; s++) {
+        const m = /^([a-zA-Z_]\w*)\[(\d+)\]$/.exec(segs[s]);
+        if (!m)
+            return null;
+        const key = m[1];
+        const index = Number(m[2]);
+        const arr = s === 0 ? draft[key] : node?.[key];
+        if (!Array.isArray(arr))
+            return null;
+        node = arr[index];
+        if (!node || typeof node !== 'object')
+            return null;
+    }
+    return typeof node?.id === 'string' && node.id ? node.id : null;
+}

package/dist/views/metadata-admin/permission-slice.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Package-scoped slice merge for the permission matrix (ADR-0086 P0).
+ *
+ * A Permission Set / Profile is a single metadata record whose `objects` and
+ * `fields` maps accumulate authorization rows contributed by many packages.
+ * When the Access matrix is opened inside a package context it must:
+ *
+ *   1. show only the objects that package declares (scope), and
+ *   2. on Save write back ONLY that slice — leaving every row contributed by
+ *      other packages byte-for-byte intact.
+ *
+ * Overwriting the whole record (the pre-P0 behavior) silently drops the rows
+ * other packages contributed. {@link mergePermissionSlice} rebuilds the record
+ * from a freshly-read base, keeping the set-level identity and every
+ * out-of-scope row, and overlaying only the in-scope rows the user edited.
+ */
+export interface ObjectPerm {
+    allowCreate?: boolean;
+    allowRead?: boolean;
+    allowEdit?: boolean;
+    allowDelete?: boolean;
+    allowTransfer?: boolean;
+    allowRestore?: boolean;
+    allowPurge?: boolean;
+    viewAllRecords?: boolean;
+    modifyAllRecords?: boolean;
+}
+export interface FieldPerm {
+    readable?: boolean;
+    editable?: boolean;
+}
+export interface PermissionSetDraft {
+    name: string;
+    label?: string;
+    isProfile?: boolean;
+    objects: Record<string, ObjectPerm>;
+    fields?: Record<string, FieldPerm>;
+    systemPermissions?: string[];
+    tabPermissions?: Record<string, 'visible' | 'hidden' | 'default_on' | 'default_off'>;
+    [extra: string]: unknown;
+}
+/**
+ * Object name embedded in a `${object}.${field}` field-permission key. Object
+ * and field names are field-name-safe (snake_case, no dots), so the object is
+ * everything up to the first dot.
+ */
+export declare function fieldKeyObject(key: string): string;
+/**
+ * Narrow a permission set down to just the rows whose object is in `scope`.
+ * Used to drive the matrix display so a package panel lists only its own
+ * objects (and their field overrides), never the whole environment.
+ */
+export declare function scopePermissionSet(set: Pick<PermissionSetDraft, 'objects' | 'fields'>, scope: Iterable<string>): {
+    objects: Record<string, ObjectPerm>;
+    fields: Record<string, FieldPerm>;
+};
+/**
+ * Merge the edited in-scope slice back onto a freshly-read full `base`.
+ *
+ * Out-of-scope rows (other packages' contributions) are copied verbatim from
+ * `base`; in-scope rows are taken entirely from `edited` (so removing a grant
+ * in the package panel deletes only that package's row). Set-level identity and
+ * any extra keys (systemPermissions, tabPermissions, …) come from `base`, with
+ * name / label / isProfile taking the user's edits.
+ */
+export declare function mergePermissionSlice(base: PermissionSetDraft, edited: PermissionSetDraft, scope: Iterable<string>): PermissionSetDraft;

package/dist/views/metadata-admin/permission-slice.js

@@ -0,0 +1,70 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Object name embedded in a `${object}.${field}` field-permission key. Object
+ * and field names are field-name-safe (snake_case, no dots), so the object is
+ * everything up to the first dot.
+ */
+export function fieldKeyObject(key) {
+    const dot = key.indexOf('.');
+    return dot === -1 ? key : key.slice(0, dot);
+}
+function asScopeSet(scope) {
+    return scope instanceof Set ? scope : new Set(scope);
+}
+/**
+ * Narrow a permission set down to just the rows whose object is in `scope`.
+ * Used to drive the matrix display so a package panel lists only its own
+ * objects (and their field overrides), never the whole environment.
+ */
+export function scopePermissionSet(set, scope) {
+    const scopeSet = asScopeSet(scope);
+    const objects = {};
+    for (const [k, v] of Object.entries(set.objects ?? {})) {
+        if (scopeSet.has(k))
+            objects[k] = v;
+    }
+    const fields = {};
+    for (const [k, v] of Object.entries(set.fields ?? {})) {
+        if (scopeSet.has(fieldKeyObject(k)))
+            fields[k] = v;
+    }
+    return { objects, fields };
+}
+/**
+ * Merge the edited in-scope slice back onto a freshly-read full `base`.
+ *
+ * Out-of-scope rows (other packages' contributions) are copied verbatim from
+ * `base`; in-scope rows are taken entirely from `edited` (so removing a grant
+ * in the package panel deletes only that package's row). Set-level identity and
+ * any extra keys (systemPermissions, tabPermissions, …) come from `base`, with
+ * name / label / isProfile taking the user's edits.
+ */
+export function mergePermissionSlice(base, edited, scope) {
+    const scopeSet = asScopeSet(scope);
+    const objects = {};
+    for (const [k, v] of Object.entries(base.objects ?? {})) {
+        if (!scopeSet.has(k))
+            objects[k] = v; // preserve other packages' rows
+    }
+    for (const [k, v] of Object.entries(edited.objects ?? {})) {
+        if (scopeSet.has(k))
+            objects[k] = v; // write this package's slice
+    }
+    const fields = {};
+    for (const [k, v] of Object.entries(base.fields ?? {})) {
+        if (!scopeSet.has(fieldKeyObject(k)))
+            fields[k] = v;
+    }
+    for (const [k, v] of Object.entries(edited.fields ?? {})) {
+        if (scopeSet.has(fieldKeyObject(k)))
+            fields[k] = v;
+    }
+    return {
+        ...base,
+        name: edited.name,
+        label: edited.label,
+        isProfile: edited.isProfile,
+        objects,
+        fields,
+    };
+}

package/dist/views/metadata-admin/previews/AppNavCanvas.js

@@ -19,6 +19,7 @@ import * as React from 'react';
 import { BarChart3, Compass, Database, FileText, Folder, GripVertical, LayoutDashboard, Link as LinkIcon, Plus, Trash2, } from 'lucide-react';
 import { Badge, cn } from '@object-ui/components';
 import { appendArray, moveArray, spliceArray } from '../inspectors/_shared';
+import { t, useMetadataLocale } from '../i18n';
 const DND_MIME = 'text/x-objectui-nav';
 function inferKind(it) {
     if (it.kind)
@@ -100,6 +101,7 @@ function navPath(it) {
     return typeof p === 'string' && p ? p : undefined;
 }
 export function AppNavCanvas({ draft, rootKey, onPatch, selection, onSelectionChange, }) {
+    const locale = useMetadataLocale();
     const items = React.useMemo(() => {
         const v = draft[rootKey];
         return Array.isArray(v) ? v : [];
@@ -114,15 +116,24 @@ export function AppNavCanvas({ draft, rootKey, onPatch, selection, onSelectionCh
     const addItem = React.useCallback(() => {
         if (!onPatch)
             return;
-        const newItem = { label: 'New item', path: '' };
+        const newLabel = t('engine.appNav.newItem', locale);
+        // Spec invariants from birth (#2245): a snake_case `id` and a `type`
+        // (object is the 80% case per the app-composition guide) — never the
+        // old `{label, path:''}` placeholder that failed save validation. The
+        // item completes once the inspector's object picker fills `objectName`.
+        const taken = new Set(items.map((it) => (typeof it.id === 'string' ? it.id : '')).filter(Boolean));
+        let navId = `nav_item_${items.length + 1}`;
+        for (let n = items.length + 2; taken.has(navId); n++)
+            navId = `nav_item_${n}`;
+        const newItem = { id: navId, type: 'object', label: newLabel };
         const next = appendArray(items, newItem);
         setItems(next);
         onSelectionChange?.({
             kind: 'nav',
             id: `${rootKey}[${next.length - 1}]`,
-            label: 'New item',
+            label: newLabel,
         });
-    }, [onPatch, items, setItems, rootKey, onSelectionChange]);
+    }, [onPatch, items, setItems, rootKey, onSelectionChange, locale]);
     const removeItem = React.useCallback((index) => {
         if (!onPatch)
             return;
@@ -158,7 +169,7 @@ export function AppNavCanvas({ draft, rootKey, onPatch, selection, onSelectionCh
             label: navLabel(next[to] ?? {}, to),
         });
     }, [onPatch, items, setItems, rootKey, onSelectionChange]);
-    return (_jsxs("div", { className: "rounded-md border bg-card/40", children: [_jsxs("div", { className: "flex items-center justify-between border-b px-3 py-2", children: [_jsxs("div", { className: "flex items-center gap-2 text-xs", children: [_jsx("span", { className: "font-mono uppercase tracking-wide text-muted-foreground", children: rootKey }), _jsxs(Badge, { variant: "outline", className: "text-[10px]", children: [items.length, " ", items.length === 1 ? 'item' : 'items'] })] }), onPatch && (_jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded border border-dashed px-2 py-1 text-[11px] text-muted-foreground hover:bg-muted/30 hover:text-foreground", onClick: addItem, children: [_jsx(Plus, { className: "h-3 w-3" }), " Add nav item"] }))] }), _jsx("div", { className: "space-y-1.5 p-2", onDragOver: (e) => {
+    return (_jsxs("div", { className: "rounded-md border bg-card/40", children: [_jsxs("div", { className: "flex items-center justify-between border-b px-3 py-2", children: [_jsxs("div", { className: "flex items-center gap-2 text-xs", children: [_jsx("span", { className: "font-medium uppercase tracking-wide text-muted-foreground", children: t('engine.appNav.heading', locale) }), _jsxs(Badge, { variant: "outline", className: "text-[10px]", children: [items.length, " ", items.length === 1 ? t('engine.appNav.itemOne', locale) : t('engine.appNav.itemOther', locale)] })] }), onPatch && (_jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded border border-dashed px-2 py-1 text-[11px] text-muted-foreground hover:bg-muted/30 hover:text-foreground", onClick: addItem, children: [_jsx(Plus, { className: "h-3 w-3" }), " ", t('engine.appNav.addItem', locale)] }))] }), _jsx("div", { className: "space-y-1.5 p-2", onDragOver: (e) => {
                     if (!onPatch)
                         return;
                     if (!e.dataTransfer.types.includes(DND_MIME))
@@ -176,8 +187,8 @@ export function AppNavCanvas({ draft, rootKey, onPatch, selection, onSelectionCh
                     moveItem(dragIndex, items.length);
                     setDragIndex(null);
                 }, children: items.length === 0 ? (_jsx("div", { className: "rounded border border-dashed px-3 py-4 text-center text-[11px] text-muted-foreground", children: onPatch
-                        ? 'Empty — click "Add nav item" to start'
-                        : 'No top-level nav items yet' })) : (items.map((it, i) => (_jsx(NavCardTree, { item: it, index: i, depth: 0, path: `${rootKey}[${i}]`, selectedId: selectedId, canEdit: !!onPatch, onClick: (p, lbl) => onSelectionChange?.({ kind: 'nav', id: p, label: lbl }), onRename: (lbl) => renameItem(i, lbl), onRemove: () => removeItem(i), onDragStart: () => setDragIndex(i), onDragEnd: () => setDragIndex(null), onDropBefore: () => {
+                        ? t('engine.appNav.empty', locale)
+                        : t('engine.appNav.emptyReadonly', locale) })) : (items.map((it, i) => (_jsx(NavCardTree, { item: it, index: i, depth: 0, path: `${rootKey}[${i}]`, selectedId: selectedId, canEdit: !!onPatch, onClick: (p, lbl) => onSelectionChange?.({ kind: 'nav', id: p, label: lbl }), onRename: (lbl) => renameItem(i, lbl), onRemove: () => removeItem(i), onDragStart: () => setDragIndex(i), onDragEnd: () => setDragIndex(null), onDropBefore: () => {
                         if (dragIndex == null)
                             return;
                         moveItem(dragIndex, i);
@@ -192,6 +203,7 @@ function NavCardTree({ item, index, depth, path, selectedId, canEdit, onClick, o
                 })] }));
 }
 function NavCard({ item, index, depth, path, isSelected, canEdit, onClick, onRename, onRemove, onDragStart, onDragEnd, onDropBefore, }) {
+    const locale = useMetadataLocale();
     const kind = inferKind(item);
     const Icon = kindIcon(kind);
     const tone = kindTone(kind);
@@ -256,5 +268,5 @@ function NavCard({ item, index, depth, path, isSelected, canEdit, onClick, onRen
                                 e.stopPropagation();
                                 onRemove();
                             }
-                        }, className: "inline-flex h-6 w-6 items-center justify-center rounded text-muted-foreground hover:bg-destructive/10 hover:text-destructive", "aria-label": "Remove nav item", children: _jsx(Trash2, { className: "h-3 w-3" }) }))] })] }));
+                        }, className: "inline-flex h-6 w-6 items-center justify-center rounded text-muted-foreground hover:bg-destructive/10 hover:text-destructive", "aria-label": t('engine.appNav.removeItem', locale), children: _jsx(Trash2, { className: "h-3 w-3" }) }))] })] }));
 }

package/dist/views/metadata-admin/previews/AppPreview.js

@@ -80,8 +80,10 @@ export function AppPreview({ name, draft, editing, selection, onSelectionChange,
         }
         return { rootKey: null, navItems: [] };
     }, [draft]);
-    // For Add we need a root key even when empty — default to "nav".
-    const addRootKey = rootKey ?? 'nav';
+    // For Add we need a root key even when empty — default to `navigation`,
+    // the only root key the spec (AppSchema) actually accepts; `nav` /
+    // `tabs` / `items` are read-back tolerances, not write targets (#2245).
+    const addRootKey = rootKey ?? 'navigation';
     const designMode = !!(editing && onSelectionChange);
     const canEdit = designMode && !!onPatch;
     const selectedId = selection && selection.kind === 'nav' ? selection.id : null;

package/dist/views/metadata-admin/previews/FlowRunsPanel.d.ts

@@ -10,16 +10,20 @@
  * designer.
  */
 import * as React from 'react';
+/** An error on a run/step. The engine sends the run-level `error` as a plain
+ *  string (`ExecutionLog.error`) while a step-level error is a `{code,message}`
+ *  object — the panel accepts either shape. */
+type RunError = string | {
+    code?: string;
+    message?: string;
+};
 /** Step entry of a run log (spec `ExecutionStepLogSchema`, fields we render). */
 interface RunStep {
     nodeId: string;
     nodeType?: string;
     status: 'success' | 'failure' | 'skipped' | string;
     durationMs?: number;
-    error?: {
-        code?: string;
-        message?: string;
-    };
+    error?: RunError;
 }
 /** Run log entry (spec `ExecutionLogSchema`, fields we render). */
 export interface FlowRun {
@@ -34,10 +38,15 @@ export interface FlowRun {
         object?: string;
     };
     steps?: RunStep[];
-    error?: {
-        message?: string;
-    };
+    error?: RunError;
 }
+/**
+ * Normalize a run/step error to its human-readable message. The engine emits a
+ * run-level `error` as a plain string but a step-level error as `{code,message}`
+ * — reading `.message` off the string case silently dropped the run failure
+ * reason (the whole point of the Runs panel for a failed run), so accept both.
+ */
+export declare function errorText(e: RunError | undefined | null): string | undefined;
 /** Fetch a flow's run history. Exposed for tests. */
 export declare function fetchFlowRuns(flowName: string, signal?: AbortSignal): Promise<FlowRun[] | null>;
 export declare function FlowRunsPanel({ flowName }: {

package/dist/views/metadata-admin/previews/FlowRunsPanel.js

@@ -15,6 +15,20 @@ import * as React from 'react';
 import { AlertCircle, CheckCircle2, ChevronDown, ChevronRight, Clock, Loader2, PauseCircle, RefreshCw, SkipForward } from 'lucide-react';
 import { cn } from '@object-ui/components';
 import { apiBase } from './useFlowNodePalette';
+/**
+ * Normalize a run/step error to its human-readable message. The engine emits a
+ * run-level `error` as a plain string but a step-level error as `{code,message}`
+ * — reading `.message` off the string case silently dropped the run failure
+ * reason (the whole point of the Runs panel for a failed run), so accept both.
+ */
+export function errorText(e) {
+    if (!e)
+        return undefined;
+    if (typeof e === 'string')
+        return e || undefined;
+    const m = e.message;
+    return typeof m === 'string' && m ? m : undefined;
+}
 /** Fetch a flow's run history. Exposed for tests. */
 export async function fetchFlowRuns(flowName, signal) {
     try {
@@ -60,14 +74,16 @@ function StepRow({ step }) {
         : step.status === 'failure'
             ? 'text-rose-600 dark:text-rose-400'
             : 'text-muted-foreground';
-    return (_jsxs("li", { className: "flex items-baseline gap-1.5 py-0.5", children: [_jsx("span", { className: cn('shrink-0 text-[9px] font-semibold uppercase', cls), children: step.status }), _jsx("span", { className: "truncate font-mono text-[10px]", title: step.nodeId, children: step.nodeId }), step.nodeType && _jsx("span", { className: "shrink-0 text-[9px] uppercase text-muted-foreground", children: step.nodeType }), fmtDuration(step.durationMs) && (_jsx("span", { className: "ml-auto shrink-0 text-[9px] text-muted-foreground", children: fmtDuration(step.durationMs) })), step.error?.message && (_jsx("span", { className: "min-w-0 truncate text-[9px] text-rose-600", title: step.error.message, children: step.error.message }))] }));
+    const stepErr = errorText(step.error);
+    return (_jsxs("li", { className: "flex items-baseline gap-1.5 py-0.5", children: [_jsx("span", { className: cn('shrink-0 text-[9px] font-semibold uppercase', cls), children: step.status }), _jsx("span", { className: "truncate font-mono text-[10px]", title: step.nodeId, children: step.nodeId }), step.nodeType && _jsx("span", { className: "shrink-0 text-[9px] uppercase text-muted-foreground", children: step.nodeType }), fmtDuration(step.durationMs) && (_jsx("span", { className: "ml-auto shrink-0 text-[9px] text-muted-foreground", children: fmtDuration(step.durationMs) })), stepErr && (_jsx("span", { className: "min-w-0 truncate text-[9px] text-rose-600", title: stepErr, children: stepErr }))] }));
 }
 function RunRow({ run }) {
     const [open, setOpen] = React.useState(false);
     const meta = statusMeta(run.status);
     const Icon = meta.icon;
     const steps = Array.isArray(run.steps) ? run.steps : [];
-    return (_jsxs("li", { className: "rounded border bg-background", children: [_jsxs("button", { type: "button", onClick: () => setOpen((v) => !v), className: "flex w-full items-center gap-1.5 p-1.5 text-left", "aria-expanded": open, children: [open ? (_jsx(ChevronDown, { className: "h-3 w-3 shrink-0 text-muted-foreground" })) : (_jsx(ChevronRight, { className: "h-3 w-3 shrink-0 text-muted-foreground" })), _jsx(Icon, { className: cn('h-3.5 w-3.5 shrink-0', meta.cls, run.status === 'running' && 'animate-spin') }), _jsx("span", { className: cn('shrink-0 text-[10px] font-semibold', meta.cls), children: meta.label }), _jsx("span", { className: "min-w-0 truncate text-[10px] text-muted-foreground", title: run.id, children: fmtTime(run.startedAt) }), fmtDuration(run.durationMs) && (_jsx("span", { className: "ml-auto shrink-0 text-[10px] text-muted-foreground", children: fmtDuration(run.durationMs) }))] }), open && (_jsxs("div", { className: "border-t px-2 py-1.5", children: [_jsxs("div", { className: "pb-1 font-mono text-[9px] text-muted-foreground", title: run.id, children: ["run ", run.id, run.trigger?.type && ` · trigger ${run.trigger.type}`] }), run.error?.message && (_jsx("div", { className: "pb-1 text-[10px] text-rose-600", children: run.error.message })), steps.length === 0 ? (_jsx("div", { className: "text-[10px] italic text-muted-foreground", children: "No step log recorded." })) : (_jsx("ul", { className: "divide-y divide-border/50", children: steps.map((s, i) => (_jsx(StepRow, { step: s }, `${s.nodeId}#${i}`))) }))] }))] }));
+    const runErr = errorText(run.error);
+    return (_jsxs("li", { className: "rounded border bg-background", children: [_jsxs("button", { type: "button", onClick: () => setOpen((v) => !v), className: "flex w-full items-center gap-1.5 p-1.5 text-left", "aria-expanded": open, children: [open ? (_jsx(ChevronDown, { className: "h-3 w-3 shrink-0 text-muted-foreground" })) : (_jsx(ChevronRight, { className: "h-3 w-3 shrink-0 text-muted-foreground" })), _jsx(Icon, { className: cn('h-3.5 w-3.5 shrink-0', meta.cls, run.status === 'running' && 'animate-spin') }), _jsx("span", { className: cn('shrink-0 text-[10px] font-semibold', meta.cls), children: meta.label }), _jsx("span", { className: "min-w-0 truncate text-[10px] text-muted-foreground", title: run.id, children: fmtTime(run.startedAt) }), fmtDuration(run.durationMs) && (_jsx("span", { className: "ml-auto shrink-0 text-[10px] text-muted-foreground", children: fmtDuration(run.durationMs) }))] }), open && (_jsxs("div", { className: "border-t px-2 py-1.5", children: [_jsxs("div", { className: "pb-1 font-mono text-[9px] text-muted-foreground", title: run.id, children: ["run ", run.id, run.trigger?.type && ` · trigger ${run.trigger.type}`] }), runErr && (_jsx("div", { className: "pb-1 text-[10px] text-rose-600", children: runErr })), steps.length === 0 ? (_jsx("div", { className: "text-[10px] italic text-muted-foreground", children: "No step log recorded." })) : (_jsx("ul", { className: "divide-y divide-border/50", children: steps.map((s, i) => (_jsx(StepRow, { step: s }, `${s.nodeId}#${i}`))) }))] }))] }));
 }
 export function FlowRunsPanel({ flowName }) {
     const [runs, setRuns] = React.useState([]);

package/dist/views/studio-design/BuilderLanding.d.ts

@@ -0,0 +1,15 @@
+/**
+ * BuilderLanding — the application builder's front door.
+ *
+ * The journey from login: Home → Studio app → the App Builder landing (this page, embedded
+ * in the app chrome via the `studio:builder` component ref) → pick or create a
+ * writable base package → the full-screen pillar builder
+ * (`/studio/:packageId/:tab`). Also served standalone at bare `/studio` so the
+ * builder is bookmarkable.
+ *
+ * Writable bases (where authoring happens) lead; read-only code packages are
+ * listed secondary for browsing. Writability is the shared display heuristic
+ * from packages-io — the ADR-0070 D4 gate stays the server-side authority.
+ */
+import * as React from 'react';
+export declare function BuilderLanding(): React.ReactElement;