@object-ui/app-shell 6.2.3 → 7.0.0

package/dist/runtime-config.d.ts

@@ -9,8 +9,8 @@
  * those don't reflect the runtime the SPA is actually attached to (e.g.
  * a tenant ObjectOS runtime pointing at a separate cloud control plane).
  *
- * Mirrors `apps/studio/src/lib/config.ts` but lives in app-shell because
- * the Console SPA in `apps/console` consumes app-shell code.
+ * The runtime-config shape lives in app-shell because the Console SPA in
+ * `apps/console` consumes app-shell code.
  *
  * Server-side: see
  *   cloud/packages/service-cloud/src/multi-environment-plugins.ts
@@ -22,6 +22,41 @@ export interface RuntimeFeatures {
     installLocal: boolean;
     /** `/api/v1/marketplace/*` is reachable from this runtime. */
     marketplace: boolean;
+    /**
+     * AI-driven metadata authoring ("online development") is offered by this
+     * runtime. Default true; the capability is still gated server-side by the
+     * presence of the metadata-authoring agent. When false, the SPA hides the
+     * AI authoring affordances (generic data-chat assistant is unaffected).
+     */
+    aiStudio: boolean;
+    /**
+     * Auto-publish AI-built apps in the author's own environment. When true, the
+     * Studio chat fires the publish-drafts call automatically the moment the
+     * agent drafts an app, so the user refreshes and sees it live WITH its sample
+     * data — no manual "go home and publish" step. Server-derived from the plan
+     * (env-revertible via `OS_AI_AUTOPUBLISH_DISABLED`). Default true.
+     */
+    autoPublishAiBuilds: boolean;
+    /**
+     * Branded subdomains + custom (BYO-DNS) domains are available on this
+     * environment's plan. Optional commercial flag — absent on self-hosted /
+     * vanilla runtimes (treated as off). When false the SPA hides custom-domain
+     * settings (or shows them as an upgrade affordance). Server-derived from the
+     * plan entitlements (cloud ADR-0011/0012).
+     */
+    customDomain?: boolean;
+    /**
+     * SSO / SAML enterprise login is available on this environment's plan.
+     * Optional commercial flag — absent on self-hosted / vanilla runtimes
+     * (treated as off). Server-derived from the plan entitlements.
+     */
+    sso?: boolean;
+}
+export interface RuntimeBranding {
+    /** Product name shown in browser title, splash, account chrome. */
+    productName: string;
+    /** Short variant for PWA shortName / compact spots. */
+    productShortName: string;
 }
 export interface RuntimeConfig {
     /**
@@ -35,6 +70,7 @@ export interface RuntimeConfig {
     defaultOrgId?: string | null;
     defaultEnvironmentId?: string | null;
     features: RuntimeFeatures;
+    branding: RuntimeBranding;
 }
 /**
  * Fetch the server-pushed runtime config and merge it into the singleton.
@@ -49,6 +85,14 @@ export interface RuntimeConfig {
 export declare function initRuntimeConfig(baseUrl?: string): Promise<void>;
 /** Read-only accessor. Returns the current snapshot. */
 export declare function getRuntimeConfig(): RuntimeConfig;
+/**
+ * Product name shown in browser title, splash, account chrome.
+ * Falls back to `'ObjectOS'` when the server hasn't been contacted yet.
+ * Operators override via `OS_PRODUCT_NAME` env var or
+ * `new RuntimeConfigPlugin({ productName: 'Acme Studio' })`.
+ */
+export declare function getProductName(): string;
+export declare function getProductShortName(): string;
 /** Whether `initRuntimeConfig()` has run at least once. */
 export declare function isRuntimeConfigInitialised(): boolean;
 /**

package/dist/runtime-config.js

@@ -4,7 +4,8 @@ const defaults = {
     singleEnvironment: false,
     defaultOrgId: null,
     defaultEnvironmentId: null,
-    features: { installLocal: false, marketplace: true },
+    features: { installLocal: false, marketplace: true, aiStudio: true, autoPublishAiBuilds: true, customDomain: false, sso: false },
+    branding: { productName: 'ObjectOS', productShortName: 'ObjectOS' },
 };
 let current = { ...defaults };
 let initialised = false;
@@ -17,6 +18,10 @@ function applyUpdate(patch) {
             ...current.features,
             ...(patch.features ?? {}),
         },
+        branding: {
+            ...current.branding,
+            ...(patch.branding ?? {}),
+        },
     };
 }
 /**
@@ -50,8 +55,24 @@ export async function initRuntimeConfig(baseUrl = '') {
                 ? {
                     installLocal: !!body.features.installLocal,
                     marketplace: body.features.marketplace !== false,
+                    aiStudio: body.features.aiStudio !== false,
+                    autoPublishAiBuilds: body.features.autoPublishAiBuilds !== false,
+                    // Commercial flags default OFF unless the server explicitly grants
+                    // them — never show a paid surface on an unknown/older runtime.
+                    customDomain: body.features.customDomain === true,
+                    sso: body.features.sso === true,
                 }
                 : current.features,
+            branding: body.branding
+                ? {
+                    productName: typeof body.branding.productName === 'string' && body.branding.productName.trim()
+                        ? body.branding.productName.trim()
+                        : current.branding.productName,
+                    productShortName: typeof body.branding.productShortName === 'string' && body.branding.productShortName.trim()
+                        ? body.branding.productShortName.trim()
+                        : current.branding.productShortName,
+                }
+                : current.branding,
         });
     }
     catch {
@@ -66,6 +87,18 @@ export async function initRuntimeConfig(baseUrl = '') {
 export function getRuntimeConfig() {
     return current;
 }
+/**
+ * Product name shown in browser title, splash, account chrome.
+ * Falls back to `'ObjectOS'` when the server hasn't been contacted yet.
+ * Operators override via `OS_PRODUCT_NAME` env var or
+ * `new RuntimeConfigPlugin({ productName: 'Acme Studio' })`.
+ */
+export function getProductName() {
+    return current.branding?.productName || 'ObjectOS';
+}
+export function getProductShortName() {
+    return current.branding?.productShortName || getProductName();
+}
 /** Whether `initRuntimeConfig()` has run at least once. */
 export function isRuntimeConfigInitialised() {
     return initialised;
@@ -81,6 +114,10 @@ export function getCloudBase() {
 }
 /** Test/dev helper. */
 export function resetRuntimeConfigForTesting() {
-    current = { ...defaults, features: { ...defaults.features } };
+    current = {
+        ...defaults,
+        features: { ...defaults.features },
+        branding: { ...defaults.branding },
+    };
     initialised = false;
 }

package/dist/services/builtinComponents.js

@@ -1,4 +1,3 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 /**
  * Built-in component registrations — Phase 3b + 3c.
@@ -7,21 +6,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * own admin UI is registered with the ComponentRegistry before
  * AppContent mounts the first `<Route path="component/...">`.
  *
- * Plugins follow the same pattern: their package entry point imports
- * a similar registration module, so `import '@object-ui/plugin-foo'`
- * is enough to make the plugin's component refs reachable from app
- * metadata.
- *
- * Phase 3c — also registers the new generic metadata admin engine and
- * pre-wires specialised editors for `object` and `field` so admins
- * still get the polished ObjectManager / FieldDesigner experience
- * inside the unified Setup-app shell.
+ * Registers the generic metadata admin engine and a specialised
+ * permission-matrix editor for `permission`. The previous View /
+ * Dashboard / Page bespoke "designer" tabs were removed: they never
+ * produced usable output and confused authors. Those types now use the
+ * same JSONSchema-driven Form + Preview experience as every other
+ * metadata type.
  */
-import { lazy, Suspense } from 'react';
 import { registerAppComponent } from './componentRegistry';
 import { MetadataDirectoryPage, MetadataResourceRouter, registerMetadataResource, } from '../views/metadata-admin';
 import { PermissionMatrixEditPage } from '../views/metadata-admin/PermissionMatrixEditor';
-import { DesignerEditorBody } from '../views/metadata-admin/DesignerEditorWrapper';
+import { PackagesPage } from '../views/metadata-admin/PackagesPage';
+import { isAggregatedViewContainer, viewDisplayType, } from '../views/metadata-admin/view-item-normalize';
 /* -------------------------------------------------------------------------- */
 /* 1) Top-level admin pages — bound to `metadata:directory` + `metadata:resource` */
 /* -------------------------------------------------------------------------- */
@@ -35,18 +31,16 @@ registerAppComponent({
     ref: 'metadata:resource',
     label: 'Metadata Resource',
     source: '@object-ui/app-shell',
-    // The router switches between list / new / edit / history based on
-    // the sub-path under `/component/metadata/resource/...`.
     component: MetadataResourceRouter,
 });
+registerAppComponent({
+    ref: 'developer:packages',
+    label: 'Packages',
+    source: '@object-ui/app-shell',
+    component: PackagesPage,
+});
 /* -------------------------------------------------------------------------- */
-/* 2) Specialised editors for flagship types — opt the generic engine        */
-/*    out for the types that already have polished bespoke surfaces.         */
-/*                                                                            */
-/*    Note: `object` and `field` intentionally use the generic engine so the */
-/*    Metadata Directory has a consistent list/edit experience across every  */
-/*    type (only `permission`, `view`, `dashboard`, `page` keep bespoke      */
-/*    editors below — those are visual designers, not list/form pages).      */
+/* 2) Generic resources — list + JSONSchema-driven form for every type.       */
 /* -------------------------------------------------------------------------- */
 registerMetadataResource({
     type: 'object',
@@ -96,58 +90,42 @@ registerMetadataResource({
     ],
 });
 /* -------------------------------------------------------------------------- */
-/* 4) Bespoke designers wired through DesignerEditorWrapper (Phase 3d).      */
-/*    These types continue to use the generic AutoForm-style list and        */
-/*    history pages but swap the edit page for the existing visual designer. */
+/* 4) UI metadata types — list + form. No bespoke visual designers: views,   */
+/*    dashboards and pages are authored as JSON metadata; the Preview tab    */
+/*    renders them live for verification.                                    */
 /* -------------------------------------------------------------------------- */
-const ObjectViewConfigurator = lazy(() => import('@object-ui/plugin-designer').then((m) => ({ default: m.ObjectViewConfigurator })));
-const DashboardEditor = lazy(() => import('@object-ui/plugin-designer').then((m) => ({ default: m.DashboardEditor })));
-const PageCanvasEditor = lazy(() => import('@object-ui/plugin-designer').then((m) => ({ default: m.PageCanvasEditor })));
-function ViewEditPage(props) {
-    return (_jsx(DesignerEditorBody, { ...props, fromMetadata: (raw) => {
-            // Normalize backend view metadata into the shape ObjectViewConfigurator expects.
-            // Built-in views may omit `columns` or use legacy field names.
-            const base = raw && typeof raw === 'object' ? raw : {};
-            return {
-                viewType: base.viewType ?? base.type ?? 'grid',
-                columns: Array.isArray(base.columns) ? base.columns : [],
-                filters: Array.isArray(base.filters) ? base.filters : [],
-                sorts: Array.isArray(base.sorts) ? base.sorts : [],
-                pageSize: typeof base.pageSize === 'number' ? base.pageSize : 25,
-                ...base,
-            };
-        }, renderDesigner: (value, onChange, readOnly) => (_jsx(Suspense, { fallback: _jsx(DesignerFallback, { label: "view designer" }), children: _jsx(ObjectViewConfigurator, { config: value, onChange: (next) => onChange(next), readOnly: readOnly }) })) }));
-}
-function DashboardEditPage(props) {
-    return (_jsx(DesignerEditorBody, { ...props, renderDesigner: (value, onChange, readOnly) => (_jsx(Suspense, { fallback: _jsx(DesignerFallback, { label: "dashboard editor" }), children: _jsx(DashboardEditor, { schema: value, onChange: (next) => onChange(next), readOnly: readOnly }) })) }));
-}
-function PageEditPage(props) {
-    return (_jsx(DesignerEditorBody, { ...props, renderDesigner: (value, onChange, readOnly) => (_jsx(Suspense, { fallback: _jsx(DesignerFallback, { label: "page canvas" }), children: _jsx(PageCanvasEditor, { schema: value, onChange: (next) => onChange(next), readOnly: readOnly }) })) }));
-}
-function DesignerFallback({ label }) {
-    return (_jsxs("div", { className: "p-6 text-sm text-muted-foreground", children: ["Loading ", label, "\u2026"] }));
-}
 registerMetadataResource({
     type: 'view',
     label: 'Views',
     description: 'Saved list / kanban / calendar / gantt configurations on top of an object.',
     domain: 'ui',
-    DesignerTab: ViewEditPage,
-    designerTabLabel: 'View designer',
     listColumns: [
         { key: 'name', label: 'Name', width: '30%' },
         { key: 'object', label: 'Object', width: '20%' },
-        { key: 'type', label: 'Type', width: '15%' },
+        {
+            key: 'type',
+            label: 'Type',
+            width: '15%',
+            // Expanded ViewItems keep their display type under `config.type`
+            // and only the list/form family at the top level — derive it so the
+            // column shows "calendar" / "grid" / "form" instead of "—".
+            render: (_v, item) => viewDisplayType(item) ?? '—',
+        },
         { key: 'label', label: 'Label' },
     ],
+    // ADR-0017 — the framework exposes each view as a canonical first-class
+    // ViewItem ({ name, object, viewKind, label, config }). The inspector and
+    // preview read that shape directly (`draft.config`), so NO toDraft/fromDraft
+    // adapter is wired here — the canonical shape round-trips untouched.
+    // Hide the bare aggregated container the framework keeps for runtime
+    // dual-read — its views are already listed as expanded ViewItems.
+    listFilter: (item) => !isAggregatedViewContainer(item),
 });
 registerMetadataResource({
     type: 'dashboard',
     label: 'Dashboards',
     description: 'Composed dashboards with charts, KPIs, and tables.',
     domain: 'ui',
-    DesignerTab: DashboardEditPage,
-    designerTabLabel: 'Dashboard designer',
     listColumns: [
         { key: 'name', label: 'Name', width: '30%' },
         { key: 'label', label: 'Label', width: '30%' },
@@ -157,13 +135,44 @@ registerMetadataResource({
 registerMetadataResource({
     type: 'page',
     label: 'Pages',
-    description: 'Visual page layouts authored in the Page Canvas editor.',
+    description: 'Visual page layouts authored as JSON metadata.',
     domain: 'ui',
-    DesignerTab: PageEditPage,
-    designerTabLabel: 'Page canvas',
     listColumns: [
         { key: 'name', label: 'Name', width: '30%' },
         { key: 'label', label: 'Label', width: '30%' },
         { key: 'route', label: 'Route' },
     ],
 });
+/* -------------------------------------------------------------------------- */
+/* 5) Documentation — the `book` navigation spine (ADR-0046 §6). A book is an  */
+/*    ordered set of groups whose membership over docs is DERIVED from each    */
+/*    group's include rule; the Preview tab renders that spine for authoring.  */
+/* -------------------------------------------------------------------------- */
+registerMetadataResource({
+    type: 'book',
+    label: 'Documentation Books',
+    description: 'Documentation navigation spine — ordered groups with membership derived over docs (glob/tag rules), plus an explicit pages override for curated order.',
+    domain: 'system',
+    searchableFields: ['name', 'label', 'description', 'slug'],
+    listColumns: [
+        { key: 'name', label: 'Name', width: '25%' },
+        { key: 'label', label: 'Label', width: '25%' },
+        {
+            key: 'audience',
+            label: 'Audience',
+            width: '12%',
+            render: (v) => v == null
+                ? 'org'
+                : typeof v === 'object' && v && 'profile' in v
+                    ? `profile: ${v.profile}`
+                    : String(v),
+        },
+        {
+            key: 'groups',
+            label: 'Groups',
+            width: '10%',
+            render: (v) => (Array.isArray(v) ? String(v.length) : '0'),
+        },
+        { key: 'description', label: 'Description' },
+    ],
+});

package/dist/skeletons/SkeletonDashboard.d.ts

@@ -9,5 +9,5 @@ interface SkeletonDashboardProps {
     /** Number of widget cards to render */
     cards?: number;
 }
-export declare function SkeletonDashboard({ cards }: SkeletonDashboardProps): import("react/jsx-runtime").JSX.Element;
+export declare function SkeletonDashboard({ cards }: SkeletonDashboardProps): import("react").JSX.Element;
 export {};

package/dist/skeletons/SkeletonDetail.d.ts

@@ -11,5 +11,5 @@ interface SkeletonDetailProps {
     /** Number of columns */
     columns?: number;
 }
-export declare function SkeletonDetail({ fields, columns }: SkeletonDetailProps): import("react/jsx-runtime").JSX.Element;
+export declare function SkeletonDetail({ fields, columns }: SkeletonDetailProps): import("react").JSX.Element;
 export {};

package/dist/skeletons/SkeletonGrid.d.ts

@@ -11,5 +11,5 @@ interface SkeletonGridProps {
     /** Number of columns to render */
     columns?: number;
 }
-export declare function SkeletonGrid({ rows, columns }: SkeletonGridProps): import("react/jsx-runtime").JSX.Element;
+export declare function SkeletonGrid({ rows, columns }: SkeletonGridProps): import("react").JSX.Element;
 export {};

package/dist/utils/appRoute.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ADR-0048 (option A) — the `/apps/<segment>` route is keyed on the **package
+ * id** (reverse-domain, globally unique), not the app's display name. This makes
+ * two vendors' same-named apps unambiguous and self-describing in the URL.
+ *
+ * - `appRouteSegment(app)` — the canonical route segment for linking TO an app
+ *   (its package id; falls back to `name` for runtime/DB apps with no
+ *   `_packageId`).
+ * - `matchAppBySegment(apps, seg)` — resolve a route segment back to its app,
+ *   preferring the package id and falling back to the app name. The name
+ *   fallback doubles as a per-tenant friendly alias and keeps legacy
+ *   name-based URLs/bookmarks working. Callers keep their own
+ *   default/first-app fallback around this match.
+ */
+type AppLike = {
+    name?: unknown;
+    _packageId?: unknown;
+} & Record<string, unknown>;
+export declare function appRouteSegment(app: AppLike | null | undefined): string | undefined;
+export declare function matchAppBySegment<T extends AppLike>(apps: readonly T[] | null | undefined, seg: string | null | undefined): T | undefined;
+export {};

package/dist/utils/appRoute.js

@@ -0,0 +1,25 @@
+/**
+ * ADR-0048 (option A) — the `/apps/<segment>` route is keyed on the **package
+ * id** (reverse-domain, globally unique), not the app's display name. This makes
+ * two vendors' same-named apps unambiguous and self-describing in the URL.
+ *
+ * - `appRouteSegment(app)` — the canonical route segment for linking TO an app
+ *   (its package id; falls back to `name` for runtime/DB apps with no
+ *   `_packageId`).
+ * - `matchAppBySegment(apps, seg)` — resolve a route segment back to its app,
+ *   preferring the package id and falling back to the app name. The name
+ *   fallback doubles as a per-tenant friendly alias and keeps legacy
+ *   name-based URLs/bookmarks working. Callers keep their own
+ *   default/first-app fallback around this match.
+ */
+export function appRouteSegment(app) {
+    if (!app)
+        return undefined;
+    const seg = app._packageId ?? app.name;
+    return seg ?? undefined;
+}
+export function matchAppBySegment(apps, seg) {
+    if (!apps || seg == null)
+        return undefined;
+    return apps.find((a) => a?._packageId === seg) ?? apps.find((a) => a?.name === seg);
+}

package/dist/utils/deriveRelatedLists.d.ts

@@ -0,0 +1,54 @@
+/**
+ * deriveRelatedLists — the read-side mirror of `attachInlineSubforms`.
+ *
+ * Where `inlineEdit: true` on a child's `master_detail`/`lookup` field pulls
+ * that child INTO the parent's entry form (write side), the detail-page
+ * RELATED LIST is the read-side counterpart: a child collection surfaced on the
+ * parent's record DETAIL page. Both intents live on the relationship in the
+ * data model — not in a hand-authored page.
+ *
+ * This helper scans every object for fields whose `reference`/`reference_to`
+ * points back at the parent object and produces one related-list descriptor per
+ * child collection. The detail page (`RecordDetailView`) feeds these into the
+ * `record:related_list` renderers (and the legacy `DetailView.related`).
+ *
+ * Rules (kept in lockstep with the relationship-level `relatedList` spec flag):
+ *   - Owned children (`master_detail`) and `lookup` children are SHOWN by
+ *     default. Set `relatedList: false` on the FK field to suppress a noisy
+ *     association/audit link.
+ *   - `relatedListTitle` / `relatedListColumns` on the FK field override the
+ *     derived title / columns.
+ *   - Audit FKs (`created_by` / `updated_by` / `owner_id`) are skipped — they
+ *     exist on virtually every object and would balloon the detail page into
+ *     dozens of duplicate cards.
+ *   - One related list per child object (deduped by child object name): the
+ *     first non-audit, non-suppressed FK wins.
+ *   - Owned (`master_detail`) children are ordered before plain `lookup`
+ *     children, preserving discovery order within each group.
+ */
+export interface DerivedRelatedList {
+    /** Child object name (the `api` for the related list query). */
+    childObject: string;
+    /** Best-effort human label for the child object. */
+    childLabel: string;
+    /** FK field on the child pointing back at this parent. */
+    referenceField: string;
+    /** Title override from `relatedListTitle` (else derive from the object label). */
+    title?: string;
+    /** Explicit columns override from `relatedListColumns` (else auto-derived by the renderer). */
+    columns?: any[];
+    /** True when the child→parent link is a `master_detail` (owned) relationship. */
+    isOwned: boolean;
+}
+interface ObjectLike {
+    name?: string;
+    label?: string;
+    fields?: Record<string, any> | any[];
+}
+/**
+ * Derive the detail-page related lists for `objectDef` from the full object
+ * registry. Returns owned (`master_detail`) children first, then `lookup`
+ * children; deterministic and side-effect free (safe to memoize).
+ */
+export declare function deriveRelatedLists(objectDef: ObjectLike | null | undefined, objects: ObjectLike[] | null | undefined): DerivedRelatedList[];
+export {};

package/dist/utils/deriveRelatedLists.js

@@ -0,0 +1,91 @@
+/**
+ * deriveRelatedLists — the read-side mirror of `attachInlineSubforms`.
+ *
+ * Where `inlineEdit: true` on a child's `master_detail`/`lookup` field pulls
+ * that child INTO the parent's entry form (write side), the detail-page
+ * RELATED LIST is the read-side counterpart: a child collection surfaced on the
+ * parent's record DETAIL page. Both intents live on the relationship in the
+ * data model — not in a hand-authored page.
+ *
+ * This helper scans every object for fields whose `reference`/`reference_to`
+ * points back at the parent object and produces one related-list descriptor per
+ * child collection. The detail page (`RecordDetailView`) feeds these into the
+ * `record:related_list` renderers (and the legacy `DetailView.related`).
+ *
+ * Rules (kept in lockstep with the relationship-level `relatedList` spec flag):
+ *   - Owned children (`master_detail`) and `lookup` children are SHOWN by
+ *     default. Set `relatedList: false` on the FK field to suppress a noisy
+ *     association/audit link.
+ *   - `relatedListTitle` / `relatedListColumns` on the FK field override the
+ *     derived title / columns.
+ *   - Audit FKs (`created_by` / `updated_by` / `owner_id`) are skipped — they
+ *     exist on virtually every object and would balloon the detail page into
+ *     dozens of duplicate cards.
+ *   - One related list per child object (deduped by child object name): the
+ *     first non-audit, non-suppressed FK wins.
+ *   - Owned (`master_detail`) children are ordered before plain `lookup`
+ *     children, preserving discovery order within each group.
+ */
+/** Audit/ownership FKs that exist on nearly every object — never related lists. */
+const AUDIT_FK_FIELDS = new Set(['created_by', 'updated_by', 'owner_id']);
+/** Normalize an object's `fields` (record or array) into `[name, def]` pairs. */
+function fieldEntries(fields) {
+    if (!fields)
+        return [];
+    if (Array.isArray(fields)) {
+        return fields
+            .filter((f) => f && (f.name != null))
+            .map((f) => [String(f.name), f]);
+    }
+    return Object.entries(fields);
+}
+/**
+ * Derive the detail-page related lists for `objectDef` from the full object
+ * registry. Returns owned (`master_detail`) children first, then `lookup`
+ * children; deterministic and side-effect free (safe to memoize).
+ */
+export function deriveRelatedLists(objectDef, objects) {
+    if (!objectDef?.name || !Array.isArray(objects) || objects.length === 0)
+        return [];
+    const parentName = objectDef.name;
+    const owned = [];
+    const referenced = [];
+    const seenChild = new Set();
+    for (const child of objects) {
+        if (!child?.name || child.name === parentName)
+            continue;
+        for (const [fieldName, fieldDef] of fieldEntries(child.fields)) {
+            if (!fieldDef)
+                continue;
+            const type = fieldDef.type;
+            if (type !== 'lookup' && type !== 'master_detail')
+                continue;
+            if ((fieldDef.reference_to || fieldDef.reference) !== parentName)
+                continue;
+            if (AUDIT_FK_FIELDS.has(fieldName))
+                continue;
+            // Explicit opt-out lives on the relationship.
+            if (fieldDef.relatedList === false)
+                continue;
+            // One related list per child object — the first eligible FK wins.
+            if (seenChild.has(child.name))
+                continue;
+            seenChild.add(child.name);
+            const entry = {
+                childObject: child.name,
+                childLabel: child.label || child.name,
+                referenceField: fieldName,
+                isOwned: type === 'master_detail',
+                ...(typeof fieldDef.relatedListTitle === 'string' && fieldDef.relatedListTitle
+                    ? { title: fieldDef.relatedListTitle }
+                    : {}),
+                ...(Array.isArray(fieldDef.relatedListColumns) && fieldDef.relatedListColumns.length > 0
+                    ? { columns: fieldDef.relatedListColumns }
+                    : {}),
+            };
+            (entry.isOwned ? owned : referenced).push(entry);
+            break; // move on to the next child object
+        }
+    }
+    return [...owned, ...referenced];
+}

package/dist/utils/index.d.ts

@@ -3,6 +3,10 @@
  */
 export { resolveRecordFormTarget, } from './recordFormNavigation';
 export type { ObjectDefinitionForNavigation, RecordFormTarget, } from './recordFormNavigation';
+export { deriveRelatedLists } from './deriveRelatedLists';
+export type { DerivedRelatedList } from './deriveRelatedLists';
+export { preferLocal } from './preferLocal';
+export { appRouteSegment, matchAppBySegment } from './appRoute';
 /**
  * Resolves an I18nLabel to a plain string.
  * I18nLabel can be either a string or an object { key, defaultValue?, params? }.

package/dist/utils/index.js

@@ -2,6 +2,9 @@
  * Utility functions for ObjectStack Console
  */
 export { resolveRecordFormTarget, } from './recordFormNavigation';
+export { deriveRelatedLists } from './deriveRelatedLists';
+export { preferLocal } from './preferLocal';
+export { appRouteSegment, matchAppBySegment } from './appRoute';
 /**
  * Resolves an I18nLabel to a plain string.
  * I18nLabel can be either a string or an object { key, defaultValue?, params? }.

package/dist/utils/managedByEmptyState.d.ts

@@ -26,4 +26,11 @@ export interface ManagedByEmptyState {
     message: string;
     icon: string;
 }
-export declare function resolveManagedByEmptyState(managedBy: string | undefined | null): ManagedByEmptyState | undefined;
+/**
+ * Translator function, structurally compatible with the `t` returned by
+ * `useObjectTranslation()`. Accepts a key and optional options (including a
+ * `defaultValue` used as the English fallback when a locale lacks the key).
+ */
+type TranslateFn = (key: string, options?: Record<string, unknown>) => string;
+export declare function resolveManagedByEmptyState(managedBy: string | undefined | null, t: TranslateFn): ManagedByEmptyState | undefined;
+export {};

package/dist/utils/managedByEmptyState.js

@@ -1,22 +1,28 @@
-export function resolveManagedByEmptyState(managedBy) {
+export function resolveManagedByEmptyState(managedBy, t) {
     switch (managedBy) {
         case 'system':
             return {
                 icon: 'Lock',
-                title: 'Nothing here yet',
-                message: 'Entries appear automatically when their source action runs (e.g. Submit for Approval, Share, Invite). Trigger one of those on a source record to create a row.',
+                title: t('list.managedBy.system.title', { defaultValue: 'Nothing here yet' }),
+                message: t('list.managedBy.system.message', {
+                    defaultValue: 'Entries appear automatically when their source action runs (e.g. Submit for Approval, Share, Invite). Trigger one of those on a source record to create a row.',
+                }),
             };
         case 'append-only':
             return {
                 icon: 'Archive',
-                title: 'No events recorded',
-                message: 'This is an immutable audit log. Rows are written by the platform when events occur — you can export the history but cannot create entries from here.',
+                title: t('list.managedBy.appendOnly.title', { defaultValue: 'No events recorded' }),
+                message: t('list.managedBy.appendOnly.message', {
+                    defaultValue: 'This is an immutable audit log. Rows are written by the platform when events occur — you can export the history but cannot create entries from here.',
+                }),
             };
         case 'better-auth':
             return {
                 icon: 'ShieldAlert',
-                title: 'No identity records',
-                message: 'Identity rows are managed by the authentication provider. Use the dedicated identity workflows (Invite User, Reset Password, …) to create new entries.',
+                title: t('list.managedBy.betterAuth.title', { defaultValue: 'No identity records' }),
+                message: t('list.managedBy.betterAuth.message', {
+                    defaultValue: 'Identity rows are managed by the authentication provider. Use the dedicated identity workflows (Invite User, Reset Password, …) to create new entries.',
+                }),
             };
         default:
             return undefined;

package/dist/utils/preferLocal.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ADR-0048 Phase 2 — prefer-local (container-scoped) metadata resolution.
+ *
+ * Two installed packages may legitimately ship the same bare name (e.g. a
+ * `page` named `home`) — the install-time namespace gate keeps their namespaces
+ * distinct, and resolution disambiguates them by container. When resolving a
+ * bare name we prefer the item owned by the *current* container (the active
+ * app's package), so a user inside `/apps/crm` sees crm's `home`, not whichever
+ * package's `home` happened to load first.
+ *
+ * Falls back to the first name match when the container owns no such item or
+ * its owning package is unknown (runtime/DB apps with no `_packageId`), so this
+ * never regresses the prior first-match behaviour.
+ */
+export declare function preferLocal<T extends {
+    name?: unknown;
+    _packageId?: unknown;
+}>(list: readonly T[] | undefined | null, name: string | undefined | null, ownerPackageId?: unknown): T | undefined;