@object-ui/app-shell 6.2.3 → 7.1.0

package/dist/views/metadata-admin/inspectors/json-schema-to-fields.js

@@ -0,0 +1,227 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+const REFERENCE_KINDS = new Set([
+    'object',
+    'object-field',
+    'flow',
+    'role',
+    'node',
+    'user',
+    'team',
+    'queue',
+    'department',
+    'connector',
+    'email-template',
+]);
+/**
+ * Read a valid `xRef` annotation off a schema node, or undefined. Accepts both
+ * the static shape (`{ kind }`) and the polymorphic shape (`{ kindFrom, map }`),
+ * validating every referenced kind against {@link REFERENCE_KINDS} so an unknown
+ * kind degrades to free text rather than a broken picker.
+ */
+function refOf(node) {
+    const x = node.xRef;
+    if (!x || typeof x !== 'object')
+        return undefined;
+    const objectSource = typeof x.objectSource === 'string' && x.objectSource ? { objectSource: x.objectSource } : {};
+    // Polymorphic: kindFrom + a map of discriminator value → kind.
+    if (typeof x.kindFrom === 'string' && x.kindFrom && x.map && typeof x.map === 'object') {
+        const map = {};
+        for (const [disc, kind] of Object.entries(x.map)) {
+            if (typeof kind === 'string' && REFERENCE_KINDS.has(kind))
+                map[disc] = kind;
+        }
+        if (Object.keys(map).length === 0)
+            return undefined;
+        return { kindFrom: x.kindFrom, map, ...objectSource };
+    }
+    // Static: a single concrete kind.
+    if (typeof x.kind === 'string' && REFERENCE_KINDS.has(x.kind)) {
+        return { kind: x.kind, ...objectSource };
+    }
+    return undefined;
+}
+/** "approvalStatusField" → "Approval Status Field"; "approve" → "Approve". */
+export function humanizeKey(key) {
+    const spaced = key
+        .replace(/[_-]+/g, ' ')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .trim();
+    if (!spaced)
+        return key;
+    return spaced
+        .split(/\s+/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/** The JSON Schema `type`, normalized to a single string (first non-null of a union). */
+function schemaType(node) {
+    if (Array.isArray(node.type))
+        return node.type.find((t) => t !== 'null');
+    if (typeof node.type === 'string')
+        return node.type;
+    // Infer from shape when `type` is omitted (common with enum-only schemas).
+    if (Array.isArray(node.enum))
+        return 'string';
+    if (node.properties)
+        return 'object';
+    if (node.items)
+        return 'array';
+    return undefined;
+}
+/** Build `{ value, label }` options from a string enum. */
+function enumOptions(values) {
+    return values
+        .filter((v) => typeof v === 'string')
+        .map((v) => ({ value: v, label: humanizeKey(v) }));
+}
+/** Default coerced to the string form the inspector's `defaultValue` expects. */
+function defaultString(node) {
+    if (node.default === undefined || node.default === null)
+        return undefined;
+    if (typeof node.default === 'boolean')
+        return String(node.default);
+    if (typeof node.default === 'number')
+        return String(node.default);
+    if (typeof node.default === 'string')
+        return node.default;
+    return undefined;
+}
+/** Scalar (non-object, non-array) → field kind. */
+function scalarKind(node) {
+    if (Array.isArray(node.enum))
+        return 'select';
+    const t = schemaType(node);
+    if (t === 'boolean')
+        return 'boolean';
+    if (t === 'number' || t === 'integer')
+        return 'number';
+    if (t === 'string')
+        return node.format === 'multiline' ? 'textarea' : 'text';
+    return undefined;
+}
+/** Derive `objectList` columns from an item object's properties. */
+function columnsFor(item) {
+    const props = item.properties ?? {};
+    const cols = [];
+    for (const [key, prop] of Object.entries(props)) {
+        if (!isObject(prop))
+            continue;
+        const t = schemaType(prop);
+        let kind;
+        let options;
+        // A reference annotation wins over the plain scalar mapping — the column is
+        // a typed reference and gets a picker (static or polymorphic via kindFrom).
+        const ref = refOf(prop);
+        if (ref) {
+            kind = 'reference';
+        }
+        else if (Array.isArray(prop.enum)) {
+            kind = 'select';
+            options = enumOptions(prop.enum);
+        }
+        else if (t === 'boolean') {
+            kind = 'boolean';
+        }
+        else {
+            kind = 'text';
+        }
+        cols.push({
+            key,
+            label: prop.title || humanizeKey(key),
+            kind,
+            ...(options ? { options } : {}),
+            ...(ref ? { ref } : {}),
+            // Columns have no help slot — surface the schema description as a hint.
+            ...(prop.description ? { placeholder: prop.description } : {}),
+        });
+    }
+    return cols;
+}
+/** Common field metadata derived from a schema node. */
+function meta(node, key) {
+    return {
+        label: node.title || humanizeKey(key),
+        ...(node.description ? { help: node.description } : {}),
+        ...(defaultString(node) ? { defaultValue: defaultString(node) } : {}),
+    };
+}
+/**
+ * Convert a published config JSON Schema (an object schema) into the inspector's
+ * `FlowConfigField[]`. Property order is preserved. Returns `null` when the
+ * schema is not a usable object schema, so callers fall back to their hardcoded
+ * field group.
+ */
+export function jsonSchemaToFlowFields(schema) {
+    if (!isObject(schema) || schemaType(schema) !== 'object' || !isObject(schema.properties)) {
+        return null;
+    }
+    const fields = [];
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        if (!isObject(prop))
+            continue;
+        const t = schemaType(prop);
+        // ── arrays ────────────────────────────────────────────────────────────
+        if (t === 'array') {
+            const item = isObject(prop.items) ? prop.items : undefined;
+            const itemType = item ? schemaType(item) : undefined;
+            if (item && itemType === 'object' && isObject(item.properties)) {
+                fields.push({ id: key, path: ['config', key], kind: 'objectList', columns: columnsFor(item), ...meta(prop, key) });
+            }
+            else if (itemType === 'string') {
+                fields.push({ id: key, path: ['config', key], kind: 'stringList', ...meta(prop, key) });
+            }
+            // arrays of anything else fall through to the Advanced block.
+            continue;
+        }
+        // ── nested object → flatten one level under config.<key>.* ──────────────
+        if (t === 'object' && isObject(prop.properties)) {
+            const subProps = Object.entries(prop.properties).filter(([, p]) => isObject(p));
+            // A boolean `enabled` toggle gates the rest of the group (mirrors the SLA
+            // escalation UX): the group's other fields reveal only when it is on.
+            const hasEnabled = subProps.some(([k, p]) => k === 'enabled' && schemaType(p) === 'boolean');
+            for (const [subKey, subProp] of subProps) {
+                const sp = subProp;
+                const subRef = refOf(sp);
+                const kind = subRef ? 'reference' : scalarKind(sp);
+                if (!kind)
+                    continue; // deeper nesting / unsupported → Advanced block
+                const id = `${key}.${subKey}`;
+                const isGate = hasEnabled && subKey === 'enabled';
+                const field = {
+                    id,
+                    path: ['config', key, subKey],
+                    kind,
+                    // The gate adopts the parent group's label; siblings keep their own.
+                    ...(isGate ? { label: prop.title || humanizeKey(key), ...(prop.description ? { help: prop.description } : {}), ...(defaultString(sp) ? { defaultValue: defaultString(sp) } : {}) } : meta(sp, subKey)),
+                    ...(subRef ? { ref: subRef } : {}),
+                    ...(kind === 'select' && Array.isArray(sp.enum) ? { options: enumOptions(sp.enum) } : {}),
+                    ...(hasEnabled && !isGate ? { showWhen: { field: `${key}.enabled`, equals: ['true'] } } : {}),
+                };
+                fields.push(field);
+            }
+            continue;
+        }
+        // ── scalars ─────────────────────────────────────────────────────────────
+        // A reference annotation (xRef) wins over the plain scalar mapping — the
+        // string is really a typed reference and gets a picker.
+        const ref = refOf(prop);
+        if (ref) {
+            fields.push({ id: key, path: ['config', key], kind: 'reference', ref, ...meta(prop, key) });
+            continue;
+        }
+        const kind = scalarKind(prop);
+        if (!kind)
+            continue; // unrepresentable → Advanced block
+        fields.push({
+            id: key,
+            path: ['config', key],
+            kind,
+            ...meta(prop, key),
+            ...(kind === 'select' && Array.isArray(prop.enum) ? { options: enumOptions(prop.enum) } : {}),
+        });
+    }
+    return fields;
+}

package/dist/views/metadata-admin/inspectors/useDatasetFields.d.ts

@@ -0,0 +1,72 @@
+export interface DatasetObjectOption {
+    /** Object API name (snake_case) — what `dataset.object` stores. */
+    name: string;
+    /** Human label (falls back to the name). */
+    label: string;
+}
+export interface DatasetRelationship {
+    /** Relationship field name — what goes in `dataset.include`. */
+    name: string;
+    /** Human label (falls back to the name). */
+    label: string;
+    /** Target object the relationship points at (for `rel.field` paths). */
+    referenceTo?: string;
+}
+export interface DatasetFieldOption {
+    /** Field path: a base field name or `relationship.field`. */
+    value: string;
+    /** Human label (falls back to the value). */
+    label: string;
+    /** Raw framework field type (e.g. 'text', 'currency', 'lookup'). */
+    type?: string;
+    /** Group heading: the base object label, or `rel → target`. */
+    group: string;
+}
+export interface DatasetFieldCatalog {
+    relationships: DatasetRelationship[];
+    fieldOptions: DatasetFieldOption[];
+    loading: boolean;
+}
+/** Resolve a string | i18n-object label down to a display string. */
+export declare function resolveLabel(label: unknown, fallback: string): string;
+/** Read a lookup/master_detail field's target object from its raw def. */
+export declare function resolveReferenceTo(def: Record<string, unknown>): string | undefined;
+/** Map a framework field type onto a dataset dimension type. */
+export declare function fieldTypeToDimensionType(type: string | undefined): string;
+export interface NormalizedObject {
+    label: string;
+    fields: Array<{
+        name: string;
+        label: string;
+        type?: string;
+        def: Record<string, unknown>;
+    }>;
+    relationships: DatasetRelationship[];
+}
+/** Normalize a raw object metadata doc into label + fields + relationships. */
+export declare function normalizeObject(doc: Record<string, unknown> | null | undefined, name: string): NormalizedObject;
+/**
+ * Build the flat `field` / `relationship.field` option list from the base
+ * object and the included relationships' (already-fetched) target objects.
+ */
+export declare function buildFieldOptions(base: NormalizedObject, include: string[], targets: Record<string, NormalizedObject>): DatasetFieldOption[];
+/** Recursively test whether a metadata doc references `datasetName` via a `dataset` key. */
+export declare function referencesDataset(doc: unknown, datasetName: string): boolean;
+/** Every object as `{ name, label }`, sorted by label. Fetched once. */
+export declare function useObjectOptions(): {
+    options: DatasetObjectOption[];
+    loading: boolean;
+};
+/**
+ * The base object's relationships (join allowlist) + a flat `field` /
+ * `relationship.field` option list. Refetches when `object` or the set of
+ * included relationships changes.
+ */
+export declare function useDatasetFieldCatalog(object: string | undefined, include: string[]): DatasetFieldCatalog;
+export interface DatasetUsage {
+    reports: number;
+    dashboards: number;
+    loading: boolean;
+}
+/** Reverse lineage: how many reports / dashboards bind this dataset by name. */
+export declare function useDatasetUsage(name: string | undefined): DatasetUsage;

package/dist/views/metadata-admin/issuePath.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+/**
+ * Render a (possibly nested) validation issue path into a human-readable trail
+ * that names the offending element. A Zod issue on a dashboard widget arrives as
+ * a dot-joined path like `widgets.2.layout`; shown as just its head field
+ * ("Widgets") the author can't tell WHICH widget or sub-field is at fault. This
+ * turns it into "Widgets → priority_split → layout" by resolving each array
+ * index to the item's stable identity (id/name/title) from the draft value.
+ *
+ * @param headLabel resolved human label for the first segment (caller knows the
+ *                  form/schema labels).
+ * @param path      dot-joined issue path (e.g. `widgets.2.layout`).
+ * @param rootValue the draft object the path indexes into (used to resolve an
+ *                  array index to the item's identity).
+ */
+export declare function describeIssuePath(headLabel: string, path: string, rootValue: unknown): string;

package/dist/views/metadata-admin/issuePath.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+/**
+ * Render a (possibly nested) validation issue path into a human-readable trail
+ * that names the offending element. A Zod issue on a dashboard widget arrives as
+ * a dot-joined path like `widgets.2.layout`; shown as just its head field
+ * ("Widgets") the author can't tell WHICH widget or sub-field is at fault. This
+ * turns it into "Widgets → priority_split → layout" by resolving each array
+ * index to the item's stable identity (id/name/title) from the draft value.
+ *
+ * @param headLabel resolved human label for the first segment (caller knows the
+ *                  form/schema labels).
+ * @param path      dot-joined issue path (e.g. `widgets.2.layout`).
+ * @param rootValue the draft object the path indexes into (used to resolve an
+ *                  array index to the item's identity).
+ */
+export function describeIssuePath(headLabel, path, rootValue) {
+    const segments = path.split('.');
+    if (segments.length <= 1)
+        return headLabel;
+    const parts = [headLabel];
+    let cursor = asRecord(rootValue)?.[segments[0]];
+    for (let i = 1; i < segments.length; i++) {
+        const seg = segments[i];
+        if (/^\d+$/.test(seg)) {
+            const idx = Number(seg);
+            const item = Array.isArray(cursor) ? cursor[idx] : undefined;
+            // 1-based index reads naturally for non-developers ("#1" not "#0").
+            parts.push(itemIdentity(item) ?? `#${idx + 1}`);
+            cursor = item;
+        }
+        else {
+            parts.push(seg);
+            cursor = asRecord(cursor)?.[seg];
+        }
+    }
+    return parts.join(' → ');
+}
+/** Best-effort stable identity of an array item, resolving an I18nLabel object
+ *  ({ key, defaultValue }) to its string. Returns undefined when none usable. */
+function itemIdentity(item) {
+    const o = asRecord(item);
+    if (!o)
+        return undefined;
+    for (const k of ['id', 'name', 'key', 'title', 'label']) {
+        const v = o[k];
+        if (typeof v === 'string' && v.trim())
+            return v;
+        const nested = asRecord(v);
+        if (nested) {
+            const s = nested.defaultValue ?? nested.key;
+            if (typeof s === 'string' && s.trim())
+                return s;
+        }
+    }
+    return undefined;
+}
+function asRecord(v) {
+    return v && typeof v === 'object' ? v : undefined;
+}

package/dist/views/metadata-admin/mergeServerFields.d.ts

@@ -0,0 +1,65 @@
+/**
+ * mergeServerFields — completes the cross-repo spec-skew root-cure for the
+ * CURATED inspectors (report / dashboard / view).
+ *
+ * Background: the curated "home" inspectors derive their authoring form from
+ * the BUNDLED `@objectstack/spec` (`getReportForm()`/`getReportSchema()` …).
+ * When the running server adds new fields to a metadata type (e.g. report's
+ * `dataset`/`rows`/`values`) before objectui bumps its bundled spec, those
+ * fields exist in the live server schema (`/meta/types` → `entry.schema`) but
+ * NOT in the bundled one — so the curated form can't render them. They were
+ * only reachable via the raw "source" tab / API.
+ *
+ * `clientValidation.ts` already stopped the bundled spec from being STRICTER
+ * than the server (no more false "required" banners). This is the symmetric
+ * other half: let the bundled-derived FORM be a SUPERSET of the bundled spec
+ * by grafting in any server-only top-level properties, so new fields become
+ * directly editable in the right-hand curated form.
+ *
+ * It is purely ADDITIVE and lag-tolerant:
+ *   - Only fields the server has and the bundle lacks are added; existing
+ *     bundled fields, ordering, sections and `visibleOn` predicates are
+ *     untouched.
+ *   - When the bundle catches up (the field appears in `bundledSchema`), the
+ *     merge becomes a no-op for that field automatically — no shim to remove.
+ *   - When no server schema is available (offline/older server), it returns
+ *     the bundled `{schema, form}` verbatim.
+ *
+ * SchemaForm renders ONLY the fields a `form` declares (see SchemaForm's
+ * sectioned path), so new properties must be added to BOTH the schema's
+ * `properties` AND the form (as a trailing section) to actually surface.
+ */
+import type { FormViewSpec } from './SchemaForm';
+type JsonSchema = Record<string, any>;
+export interface MergeServerFieldsArgs {
+    /** Bundled-spec JSONSchema for the whole document (may be undefined). */
+    bundledSchema: JsonSchema | undefined;
+    /** Bundled-spec authoring FormView (may be undefined). */
+    bundledForm: FormViewSpec | undefined;
+    /**
+     * Live server JSONSchema for this type (`RichMetadataTypeEntry.schema`).
+     * For nested documents (view), pass the relevant sub-schema (e.g.
+     * `serverSchema.properties.list`).
+     */
+    serverSchema: JsonSchema | undefined;
+    /**
+     * Top-level fields the curated inspector renders itself (e.g. report's
+     * `objectName`/`columns`/`label`) plus identity (`name`). These are never
+     * grafted into the spec form even if the server adds/keeps them, so they
+     * are not double-edited.
+     */
+    excludeFields: Set<string>;
+    /** Localized title for the trailing "new server fields" section. */
+    sectionTitle: string;
+}
+export interface MergeServerFieldsResult {
+    schema: JsonSchema | undefined;
+    form: FormViewSpec | undefined;
+}
+/**
+ * Return `{schema, form}` with server-only top-level properties grafted onto
+ * the bundled pair. No-op (returns the bundled pair) when there is nothing to
+ * add or no server schema to read.
+ */
+export declare function mergeServerFields({ bundledSchema, bundledForm, serverSchema, excludeFields, sectionTitle, }: MergeServerFieldsArgs): MergeServerFieldsResult;
+export {};

package/dist/views/metadata-admin/mergeServerFields.js

@@ -0,0 +1,56 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+/** Collect every field name a FormView's sections already declare. */
+function formDeclaredFields(form) {
+    const out = new Set();
+    for (const s of form?.sections ?? []) {
+        for (const f of s.fields ?? []) {
+            out.add(typeof f === 'string' ? f : f?.field);
+        }
+    }
+    return out;
+}
+/**
+ * Return `{schema, form}` with server-only top-level properties grafted onto
+ * the bundled pair. No-op (returns the bundled pair) when there is nothing to
+ * add or no server schema to read.
+ */
+export function mergeServerFields({ bundledSchema, bundledForm, serverSchema, excludeFields, sectionTitle, }) {
+    if (!bundledSchema)
+        return { schema: bundledSchema, form: bundledForm };
+    const serverProps = serverSchema?.properties;
+    if (!serverProps || typeof serverProps !== 'object') {
+        return { schema: bundledSchema, form: bundledForm };
+    }
+    const bundledProps = (bundledSchema.properties ?? {});
+    const alreadyShown = formDeclaredFields(bundledForm);
+    // Server-only fields = on the server, absent from the bundled schema, not
+    // curated-owned, and not already declared by the bundled form.
+    const newKeys = Object.keys(serverProps).filter((k) => !(k in bundledProps) &&
+        !excludeFields.has(k) &&
+        !alreadyShown.has(k));
+    if (newKeys.length === 0)
+        return { schema: bundledSchema, form: bundledForm };
+    // ── additive schema merge (shallow clone; bundled defs win on conflict) ──
+    const mergedSchema = {
+        ...bundledSchema,
+        properties: { ...bundledProps },
+    };
+    for (const k of newKeys) {
+        if (!(k in mergedSchema.properties))
+            mergedSchema.properties[k] = serverProps[k];
+    }
+    // ── additive form merge — append a trailing section with the new fields ──
+    // When the bundle ships no form at all, SchemaForm falls back to a flat
+    // property list (which already renders every property), so we only need to
+    // synthesise a form when one exists to preserve its curated layout.
+    let mergedForm = bundledForm;
+    if (bundledForm && typeof bundledForm === 'object') {
+        const clone = JSON.parse(JSON.stringify(bundledForm));
+        clone.sections = [
+            ...(clone.sections ?? []),
+            { label: sectionTitle, fields: newKeys.map((field) => ({ field })) },
+        ];
+        mergedForm = clone;
+    }
+    return { schema: mergedSchema, form: mergedForm };
+}

package/dist/views/metadata-admin/package-scope.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Sentinel "package" id for this environment's runtime, DB-authored metadata —
+ * items with no code-package binding (`package_id IS NULL`). The metadata
+ * list/get API treats `?package=sys_metadata` as exactly that local scope on
+ * READ, and a WRITE under it persists `package_id = null` (matching the
+ * server's runtime-only provenance, see framework #2252).
+ *
+ * Why this exists: a self-hosted, metadata-customizable environment is
+ * single-tenant — there is no "org" dimension here; the real axis is
+ * code-package vs. runtime (DB-authored). Before this scope, the package
+ * selector only listed code packages, so metadata authored at runtime
+ * (`package_id = null`) was filtered out of every code-package view and became
+ * un-navigable (the route redirected to "new"). Surfacing the local scope as a
+ * first-class, always-present selector entry makes it discoverable and editable.
+ */
+export declare const LOCAL_PACKAGE_ID = "sys_metadata";
+/**
+ * Build the Studio package-scope options from the raw `package` metadata list.
+ * Filters out system/cloud-scoped packages and appends a stable
+ * "Local / Custom (this environment)" scope so runtime metadata authored here
+ * is always selectable/visible — even when zero items exist yet.
+ */
+export declare function buildPackageScopeOptions(rawList: unknown[] | null | undefined): {
+    id: string;
+    name: string;
+}[];

package/dist/views/metadata-admin/package-scope.js

@@ -0,0 +1,43 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+import { detectLocale, t } from './i18n';
+/**
+ * Sentinel "package" id for this environment's runtime, DB-authored metadata —
+ * items with no code-package binding (`package_id IS NULL`). The metadata
+ * list/get API treats `?package=sys_metadata` as exactly that local scope on
+ * READ, and a WRITE under it persists `package_id = null` (matching the
+ * server's runtime-only provenance, see framework #2252).
+ *
+ * Why this exists: a self-hosted, metadata-customizable environment is
+ * single-tenant — there is no "org" dimension here; the real axis is
+ * code-package vs. runtime (DB-authored). Before this scope, the package
+ * selector only listed code packages, so metadata authored at runtime
+ * (`package_id = null`) was filtered out of every code-package view and became
+ * un-navigable (the route redirected to "new"). Surfacing the local scope as a
+ * first-class, always-present selector entry makes it discoverable and editable.
+ */
+export const LOCAL_PACKAGE_ID = 'sys_metadata';
+const SYSTEM_SCOPES = new Set(['system', 'cloud']);
+/**
+ * Build the Studio package-scope options from the raw `package` metadata list.
+ * Filters out system/cloud-scoped packages and appends a stable
+ * "Local / Custom (this environment)" scope so runtime metadata authored here
+ * is always selectable/visible — even when zero items exist yet.
+ */
+export function buildPackageScopeOptions(rawList) {
+    const rows = (rawList ?? [])
+        .map((raw) => {
+        const item = raw && typeof raw === 'object' && 'item' in raw ? raw.item : raw;
+        const m = (item?.manifest ?? item ?? {});
+        return {
+            id: m.id,
+            scope: m.scope,
+            name: m.name || m.id,
+        };
+    })
+        .filter((p) => p.id && !SYSTEM_SCOPES.has(p.scope));
+    rows.sort((a, b) => a.name.localeCompare(b.name));
+    const opts = rows.map((p) => ({ id: p.id, name: p.name }));
+    // Append (never default) so the existing first-code-package default is
+    // preserved; the user opts into the local scope explicitly.
+    return [...opts, { id: LOCAL_PACKAGE_ID, name: t('engine.package.local', detectLocale()) }];
+}

package/dist/views/metadata-admin/preview-registry.d.ts

@@ -19,6 +19,20 @@
  * empty "preview not available" surface is shown.
  */
 import type { ComponentType } from 'react';
+/**
+ * Identifies a sub-element selected inside a preview surface.
+ *
+ *   { kind: 'widget', id: 'metric_revenue', label: 'Revenue (KPI)' }
+ *
+ * `kind` is preview-defined (dashboard uses 'widget'; page may use
+ * 'block'; view may use 'column'). The host (`ResourceEditPage`) is
+ * agnostic — it only forwards the value to the registered inspector.
+ */
+export interface MetadataSelection {
+    kind: string;
+    id: string;
+    label?: string;
+}
 export interface MetadataPreviewProps {
     /** The metadata type, e.g. 'page', 'dashboard'. */
     type: string;
@@ -29,6 +43,47 @@ export interface MetadataPreviewProps {
      * as immutable and untrusted (validation may be in progress).
      */
     draft: Record<string, unknown>;
+    /**
+     * Optional: apply a shallow patch to the draft. When omitted, the
+     * preview surface is read-only (legacy behavior). When provided, the
+     * preview may offer in-place edits (Airtable-style column management,
+     * inline rename, etc.) — implementations should respect `editing`
+     * before exposing mutating affordances.
+     */
+    onPatch?: (patch: Record<string, unknown>) => void;
+    /**
+     * Optional: the last *published* version of this item, for previews
+     * that offer a review/diff mode (e.g. the object designer diffing an
+     * AI-authored draft against what's live). Undefined in create mode or
+     * when no published baseline exists.
+     */
+    baseline?: Record<string, unknown>;
+    /**
+     * Optional: whether the host is in edit mode. Previews that ship
+     * editing affordances should render them in a disabled/hidden state
+     * when `editing === false`.
+     */
+    editing?: boolean;
+    /**
+     * Optional: BCP-47 locale code (e.g. 'en', 'zh-CN') for previews that
+     * render localized labels. Defaults are derived from the host locale.
+     */
+    locale?: string;
+    /**
+     * Optional: the currently selected sub-element (e.g. a dashboard
+     * widget). Previews use this to render selection chrome (highlight
+     * ring, keyboard focus) and the host uses it to swap the inspector
+     * to a scoped sub-form. `null` means "nothing selected → show the
+     * top-level form".
+     */
+    selection?: MetadataSelection | null;
+    /**
+     * Optional: notify the host that the user picked (or cleared) a
+     * sub-element. Pair with {@link MetadataPreviewProps.selection} and
+     * a registered inspector (`registerMetadataInspector`) to get the
+     * "click widget → edit widget in the right panel" pattern.
+     */
+    onSelectionChange?: (selection: MetadataSelection | null) => void;
 }
 export type MetadataPreview = ComponentType<MetadataPreviewProps>;
 /**