@object-ui/app-shell 6.2.2 → 7.0.0

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

@@ -25,6 +25,35 @@
  *     `sys_metadata_history`).
  */
 import type { ComponentType, ReactNode } from 'react';
+/**
+ * Live field-to-field derivation rule used by the generic create form.
+ * See {@link MetadataResourceConfig.createDerive}.
+ */
+export interface CreateDeriveRule {
+    /** Source field path (top-level key in the draft). */
+    from: string;
+    /** Target field path (top-level key in the draft). */
+    to: string;
+    /**
+     * Named transform applied to `from`'s value. Closed set on purpose:
+     *
+     *   - `slugify`     — "Sales Order" → `sales_order`. ASCII letters,
+     *                     digits, and `_`; CJK / non-Latin scripts yield
+     *                     empty (caller must enter `name` manually).
+     *   - `plural-en`   — naive English plural ("Order" → "Orders",
+     *                     "Box" → "Boxes", "Category" → "Categories").
+     *                     Non-Latin inputs returned unchanged.
+     *   - `titlecase`   — "sales_order" → "Sales Order".
+     *   - `first-token` — strip everything past the first separator.
+     */
+    transform: 'slugify' | 'plural-en' | 'titlecase' | 'first-token';
+    /**
+     * When true (default), the rule stops firing once the user manually
+     * edits the `to` field. Lets us auto-suggest a name and then get out
+     * of the way as soon as the operator takes over.
+     */
+    untilUserEdits?: boolean;
+}
 export type MetadataDomain = 'data' | 'ui' | 'automation' | 'ai' | 'system' | 'platform' | 'identity' | 'security' | 'other';
 /**
  * One row in the registry — describes how the generic engine should
@@ -46,6 +75,15 @@ export interface MetadataResourceConfig {
     primaryKey?: string;
     /** Fields searched by the free-text filter. Default `['name','label','description']`. */
     searchableFields?: string[];
+    /**
+     * Optional client-side list predicate — return `false` to HIDE a row
+     * from the resource list page. Runs against the unwrapped item shape
+     * after search / source / package filters. Use this to drop back-compat
+     * or synthetic rows (e.g. `view` hides the bare aggregated container the
+     * framework keeps for runtime dual-read, since its views are listed
+     * individually as expanded ViewItems). Pure function; keep it cheap.
+     */
+    listFilter?: (item: Record<string, unknown>) => boolean;
     /** Columns rendered in the list page. */
     listColumns?: Array<{
         key: string;
@@ -66,30 +104,12 @@ export interface MetadataResourceConfig {
      * Fully custom edit page. Receives `{ type, name }`.
      *
      * Use this when the bespoke editor replaces the JSONSchema form entirely
-     * (e.g. PermissionMatrix grid). For visual designers that should coexist
-     * with the generic Form/Layers/References tabs, prefer `DesignerTab`.
+     * (e.g. PermissionMatrix grid).
      */
     EditPage?: ComponentType<{
         type: string;
         name: string;
     }>;
-    /**
-     * Optional visual designer that renders inside its own dedicated tab on
-     * the generic edit page, alongside Form / Layers / References. Receives
-     * `{ type, name }` and should render without an outer `PageShell` — the
-     * generic engine owns the chrome.
-     *
-     * When both `EditPage` and `DesignerTab` are provided, `EditPage` wins
-     * (full takeover); the tab variant is only used when `EditPage` is unset.
-     */
-    DesignerTab?: ComponentType<{
-        type: string;
-        name: string;
-    }>;
-    /**
-     * Optional label for the Designer tab. Defaults to "Designer".
-     */
-    designerTabLabel?: string;
     /**
      * Fully custom create page. Receives `{ type }`.
      */
@@ -100,6 +120,107 @@ export interface MetadataResourceConfig {
     hiddenFields?: string[];
     /** Suggested form field order (top to bottom). */
     fieldOrder?: string[];
+    /**
+     * Field paths shown in the create form. Order is preserved.
+     *
+     * - When omitted, the engine falls back to: every `required` field
+     *   from the JSONSchema, plus `name` and `label` if present.
+     * - Fields not in this list are still sent on save (after
+     *   `createDefaults` merge), they're just not asked for.
+     *
+     * Example: `['label', 'pluralLabel', 'name', 'description']`.
+     */
+    createFields?: string[];
+    /**
+     * Live derivation rules — typically used to auto-fill `name` from
+     * `label` (slug) and an English plural from a singular label. Each
+     * rule transforms the value at `from` and writes it to `to`. When
+     * `untilUserEdits` is true (default) the rule stops firing once the
+     * user edits the target field directly.
+     *
+     * Transforms are intentionally a small closed set so the contract
+     * stays declarative — adding "smart" behavior should mean adding a
+     * named transform here, not embedding code in registry entries.
+     */
+    createDerive?: CreateDeriveRule[];
+    /**
+     * Shallow-merged into the saved body before PUT. Use this for the
+     * "empty content" shape that lets the user land in the designer
+     * (e.g. `{ fields: {} }` for object, `{ sections: [] }` for page).
+     */
+    createDefaults?: Record<string, unknown>;
+    /**
+     * Optional body builder. When present, takes precedence over
+     * `createDefaults`: receives the user's `createFields` draft and
+     * returns the full body to PUT. Use this when the wire shape isn't
+     * a flat merge — e.g. `view` nests user-picked `object` inside
+     * `{ list: { data: { object } } }`, or `validation` picks the
+     * variant's required fields based on `draft.type`.
+     *
+     * Returned body should include the `identityField` (defaults to
+     * `name`) — the engine still re-injects it from the URL slug, but
+     * having it in the body keeps things explicit.
+     */
+    createBuildBody?: (draft: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Async create-time body augmentation that needs runtime context the pure
+     * {@link createBuildBody} can't reach — e.g. fetching another metadata item.
+     * Its returned fields are merged into the create body AFTER `createBuildBody`
+     * / `createDefaults`. Best-effort: errors are swallowed (the create still
+     * proceeds with the un-augmented body). Used by `page` to seed a record
+     * page's `regions` from the bound object's synthesized default detail page,
+     * so authoring starts from the auto-generated layout instead of blank.
+     */
+    createSeed?: (draft: Record<string, unknown>, ctx: {
+        client: any;
+    }) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Optional load-time normaliser: the wire item returned by the server
+     * (`layered.effective` / a pending draft) → the draft shape the editor
+     * (SchemaForm / inspector / preview) expects. Applied on initial load
+     * AND after every save-refresh, so the editor always sees the canonical
+     * draft shape. Must be a pure function and a no-op for shapes it does
+     * not recognise. Pair with {@link fromDraft} for the save round-trip.
+     *
+     * Example: `view` unwraps an expanded ViewItem's `config` into the
+     * `{ list | form }` family key the View inspector reads.
+     */
+    toDraft?: (item: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Optional save-time serialiser — the inverse of {@link toDraft}. The
+     * editor draft → the wire shape PUT back to the server. Applied to the
+     * body just before save (edit mode). Must be a pure function and a
+     * no-op for drafts it does not recognise.
+     */
+    fromDraft?: (draft: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Optional schema override for create mode only. When present, the
+     * engine uses this schema (instead of the server's edit schema) to
+     * render the create form and validate the draft. The saved body still
+     * goes through `createBuildBody` / `createDefaults`, so this schema
+     * just describes the simplified create-time input.
+     *
+     * Use this for wrapper types like `view` whose top-level schema has
+     * no flat identity fields (only `{list,form,listViews,formViews}`):
+     * a `createSchema` lets us ask for `{name,label,object}` up front,
+     * then `createBuildBody` wraps them into the right nested shape.
+     */
+    createSchema?: Record<string, unknown>;
+    /**
+     * Field path used as the metadata's identity — the URL slug AND
+     * the key on the saved body. Defaults to `'name'`. Override when
+     * the spec uses a different identifier (e.g. `permission` uses `id`
+     * in 7.1+). The engine reads the identity out of the draft / body
+     * at that path and writes it back at save time, so URL routing
+     * stays stable across types.
+     */
+    identityField?: string;
+    /**
+     * One-line copy shown above the create form. Defaults to a generic
+     * "Create a new <type>". When set to the empty string, the hint row
+     * is suppressed.
+     */
+    createHint?: string;
     /** Whether the type opts in to the history tab. Default true. */
     supportsHistory?: boolean;
     /**

package/dist/views/metadata-admin/report-schema.d.ts

@@ -0,0 +1,26 @@
+import type { FormViewSpec } from './SchemaForm';
+type JsonSchema = Record<string, any>;
+/** JSONSchema for the whole (flat) Report document. */
+export declare function getReportSchema(): JsonSchema | undefined;
+/**
+ * The canonical authoring FormView, with the fields the curated inspector
+ * owns directly (dataset / values / rows / name) pruned from every section so
+ * they are not double-rendered. Everything else — including the type-
+ * conditional joined-blocks section — flows through verbatim from the spec.
+ *
+ * Two alignment passes on top of the verbatim clone:
+ *
+ * 1. Fields the form declares but the *schema* no longer carries are pruned.
+ *    The 9.0 single-form cutover removed the query-form fields (`objectName` /
+ *    `columns` / `groupingsDown` / `groupingsAcross` / `filter`) from
+ *    `ReportSchema`, but the bundled `reportForm` may still declare them (the
+ *    spec-side form fix ships separately) — rendering controls whose output
+ *    the schema strips at parse time. The schema is the source of truth; the
+ *    pass is a no-op once the bundled form catches up.
+ *
+ * 2. `runtimeFilter` (which replaced `filter` in 9.0) is appended when the
+ *    schema carries it and no section declares it, so the render-time scope
+ *    filter stays editable in the meantime.
+ */
+export declare function getReportForm(): FormViewSpec | undefined;
+export {};

package/dist/views/metadata-admin/report-schema.js

@@ -0,0 +1,121 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * report-schema.ts — the SINGLE source of truth for Report authoring
+ * metadata, sourced directly from `@objectstack/spec` (the protocol) rather
+ * than hand-written field lists. Mirrors {@link ./view-schema.ts}.
+ *
+ * Why: the Report inspector must render the CORRECT config fields for EVERY
+ * report type (tabular / summary / matrix / joined) without hardcoding them.
+ * The spec already describes this:
+ *
+ *   • `reportForm`   — the canonical authoring FormView: sections for basics,
+ *                      columns, groupings, joined blocks, filter & chart, and
+ *                      advanced. One section (joined blocks) is type-
+ *                      conditional via a `visibleOn` CEL predicate.
+ *   • `ReportSchema` — the zod schema for the whole (flat) Report document.
+ *
+ * We convert the zod schema to JSONSchema once (memoised) via zod 4's native
+ * `z.toJSONSchema`, and feed `{ form, schema }` straight into the existing
+ * {@link SchemaForm}. Adding a new report type or config prop to the spec
+ * therefore flows through automatically — zero code changes here.
+ */
+import { z } from 'zod';
+import { ReportSchema, reportForm as specReportForm } from '@objectstack/spec/ui';
+const TO_JSON_OPTS = { io: 'input', unrepresentable: 'any' };
+/** Fields the curated inspector owns directly, pruned from the spec form. */
+const FORM_FIELDS_OWNED_ELSEWHERE = new Set([
+    'dataset', // dataset binding rendered as a dedicated picker
+    'values', // managed by the dedicated measures list
+    'rows', // managed by the dedicated dimensions list
+    'columns', // matrix across-dimensions — dedicated list (ADR-0021 D2)
+    'name', // record identity — not user-editable here
+]);
+let _reportDocSchema;
+let _reportDocFailed = false;
+/** JSONSchema for the whole (flat) Report document. */
+export function getReportSchema() {
+    if (_reportDocSchema || _reportDocFailed)
+        return _reportDocSchema;
+    try {
+        _reportDocSchema = z.toJSONSchema(ReportSchema, TO_JSON_OPTS);
+    }
+    catch (err) {
+        _reportDocFailed = true;
+        if (typeof console !== 'undefined') {
+            console.warn('[report-schema] failed to derive Report JSONSchema from spec', err);
+        }
+    }
+    return _reportDocSchema;
+}
+let _reportForm;
+/**
+ * The canonical authoring FormView, with the fields the curated inspector
+ * owns directly (dataset / values / rows / name) pruned from every section so
+ * they are not double-rendered. Everything else — including the type-
+ * conditional joined-blocks section — flows through verbatim from the spec.
+ *
+ * Two alignment passes on top of the verbatim clone:
+ *
+ * 1. Fields the form declares but the *schema* no longer carries are pruned.
+ *    The 9.0 single-form cutover removed the query-form fields (`objectName` /
+ *    `columns` / `groupingsDown` / `groupingsAcross` / `filter`) from
+ *    `ReportSchema`, but the bundled `reportForm` may still declare them (the
+ *    spec-side form fix ships separately) — rendering controls whose output
+ *    the schema strips at parse time. The schema is the source of truth; the
+ *    pass is a no-op once the bundled form catches up.
+ *
+ * 2. `runtimeFilter` (which replaced `filter` in 9.0) is appended when the
+ *    schema carries it and no section declares it, so the render-time scope
+ *    filter stays editable in the meantime.
+ */
+export function getReportForm() {
+    if (_reportForm)
+        return _reportForm;
+    if (!specReportForm || typeof specReportForm !== 'object')
+        return undefined;
+    try {
+        const clone = JSON.parse(JSON.stringify(specReportForm));
+        const schemaProps = getReportSchema()?.properties;
+        for (const section of clone.sections ?? []) {
+            section.fields = (section.fields ?? []).filter((f) => {
+                const name = typeof f === 'string' ? f : f?.field;
+                if (FORM_FIELDS_OWNED_ELSEWHERE.has(name))
+                    return false;
+                // Schema-subset pass: drop form fields the schema no longer carries.
+                if (schemaProps && !(name in schemaProps))
+                    return false;
+                return true;
+            });
+        }
+        if (schemaProps && 'runtimeFilter' in schemaProps) {
+            const declared = new Set();
+            for (const s of clone.sections ?? []) {
+                for (const f of s.fields ?? []) {
+                    declared.add(typeof f === 'string' ? f : f?.field);
+                }
+            }
+            if (!declared.has('runtimeFilter')) {
+                clone.sections = [
+                    ...(clone.sections ?? []),
+                    {
+                        label: 'Filter',
+                        description: 'Render-time scope filter, ANDed at query time.',
+                        collapsible: true,
+                        collapsed: true,
+                        fields: [{ field: 'runtimeFilter', widget: 'json' }],
+                    },
+                ];
+            }
+        }
+        // Drop now-empty sections so we don't render bare headers.
+        clone.sections = (clone.sections ?? []).filter((s) => (s.fields ?? []).length > 0);
+        _reportForm = clone;
+    }
+    catch (err) {
+        if (typeof console !== 'undefined') {
+            console.warn('[report-schema] failed to prepare reportForm from spec', err);
+        }
+        return undefined;
+    }
+    return _reportForm;
+}

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

@@ -1,10 +1,63 @@
-import { MetadataClient } from '@object-ui/data-objectstack';
+import { MetadataClient, type MetadataDiagnosticsSummary, type MetadataDiagnosticsEntry } from '@object-ui/data-objectstack';
+/**
+ * A declarative **type-level** action surfaced on a metadata type by the
+ * framework's `/meta/types` endpoint (spec `ActionSchema`). Mirrors how a
+ * business object carries `actions`, but scoped to the metadata type itself
+ * (e.g. datasource → "Test connection"). The metadata-admin engine renders
+ * these with the same button mechanism objects use — see `MetadataTypeActions`.
+ */
+export interface MetadataTypeAction {
+    /** Machine name (lowercase snake_case) — stable key. */
+    name: string;
+    /** Display label (plain string; framework already localised it). */
+    label?: string;
+    /** Interaction type. Only `'api'` is wired in the engine today. */
+    type?: string;
+    /**
+     * URL / endpoint. Supports `${ctx.X}` and `${param.X}` interpolation —
+     * the engine resolves `${ctx.recordId}` to the current item name.
+     */
+    target?: string;
+    /** HTTP method for `type:'api'` (defaults to POST). */
+    method?: string;
+    /** Lucide icon name. */
+    icon?: string;
+    /** Button visual variant. */
+    variant?: 'primary' | 'secondary' | 'danger' | 'ghost' | 'link';
+    /** Locations where this action is visible (list_toolbar, record_header, …). */
+    locations?: string[];
+    /** Confirmation prompt shown before execution. */
+    confirmText?: string;
+    /** Reload the view after a successful run. */
+    refreshAfter?: boolean;
+    /**
+     * Inputs. Either an array of ActionParam descriptors (collected from the user
+     * in a dialog before running — same as business-object actions), or a static
+     * key→value bag forwarded as the request body.
+     */
+    params?: Record<string, unknown> | unknown[];
+    /** Success toast message (when no resultDialog). */
+    successMessage?: string;
+    /** Error toast prefix shown when the action fails. */
+    errorMessage?: string;
+    /** Render the API response in a result dialog (spec Action.resultDialog). */
+    resultDialog?: Record<string, unknown>;
+}
 export interface RichMetadataTypeEntry {
     type: string;
     label?: string;
     description?: string;
     domain?: string;
     allowOrgOverride?: boolean;
+    /** Declarative type-level actions (GAP-1). Rendered by `MetadataTypeActions`. */
+    actions?: MetadataTypeAction[];
+    /**
+     * Two-tier model (PR-10d.7): brand-new items of this type can be
+     * authored at runtime even when `allowOrgOverride` is false. UI
+     * affordances ("+ New", Save, Delete on DB-only items) should
+     * activate when either flag is true.
+     */
+    allowRuntimeCreate?: boolean;
     /** 'registry' = ADR opt-in; 'env' = unlocked via OBJECTSTACK_METADATA_WRITABLE. */
     overrideSource?: 'registry' | 'env';
     supportsOverlay?: boolean;
@@ -16,7 +69,15 @@ export interface RichMetadataTypeEntry {
     /** UI hints (icon, color, etc.) the framework may include. */
     ui?: Record<string, unknown>;
 }
-/** Use a single MetadataClient for the whole admin engine. */
+/**
+ * Use a single MetadataClient for the whole admin engine.
+ *
+ * The base resolves to `VITE_SERVER_URL` so `/meta/*` writes reach the backend
+ * even when the SPA and API are served from different origins (the split-origin
+ * `pnpm dev` setup: SPA on :5180, backend on :3000). In same-origin production
+ * `VITE_SERVER_URL` is unset → falls back to `''` (relative, current origin),
+ * matching every other client in the app (see `apps/console/src/main.tsx`).
+ */
 export declare function useMetadataClient(environmentId?: string): MetadataClient;
 /**
  * Fetch and cache the rich `/meta/types` registry response. Most pages
@@ -35,3 +96,40 @@ export declare function useMetadataTypes(client: MetadataClient): {
 export declare function useTypesIndex(entries: RichMetadataTypeEntry[]): Record<string, RichMetadataTypeEntry>;
 /** Free-text filter helper used by list pages + QuickFind. */
 export declare function matchesQuery(item: Record<string, unknown>, query: string, fields?: string[]): boolean;
+/**
+ * Fetch the cross-type `/meta/diagnostics` sweep once and expose
+ * both the raw entry list and a per-type aggregate (used by the
+ * directory page tiles + the governance overview page).
+ *
+ * `severity` defaults to `'error'` — pass `'warning'` to include
+ * warning-only entries in the count.
+ *
+ * `packageId` (optional) scopes the whole sweep to a single software
+ * package: the server then reports per-package counts/packages, so tile
+ * numbers match the scoped list pages. Omit for a global sweep.
+ */
+export declare function useGlobalDiagnostics(client: MetadataClient, severity?: 'error' | 'warning', packageId?: string): {
+    loading: boolean;
+    error: string | null;
+    summary: MetadataDiagnosticsSummary;
+    byType: Record<string, number>;
+    /**
+     * Per-type warning-only count. Only populated when `severity` is
+     * `'warning'` (server omits warnings when severity is `'error'`).
+     */
+    warnByType: Record<string, number>;
+    /** Per-type item count (from server-side sweep). Empty on older servers. */
+    countsByType: Record<string, number>;
+    /** Per-type *locked* item count (where `_lock` ≠ `none`). Empty on older servers. */
+    lockedByType: Record<string, number>;
+    /** Per-type list of contributing packages. Empty on older servers. */
+    packagesByType: Record<string, string[]>;
+    /** Sorted, deduped union of all packages seen across all types. */
+    allPackages: string[];
+    reload: () => void;
+};
+/**
+ * Re-export so consumers can type their callbacks without reaching
+ * into the data-objectstack package directly.
+ */
+export type { MetadataDiagnosticsEntry, MetadataDiagnosticsSummary };

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

@@ -15,12 +15,45 @@
  */
 import { useEffect, useMemo, useState } from 'react';
 import { MetadataClient } from '@object-ui/data-objectstack';
-/** Use a single MetadataClient for the whole admin engine. */
+import { usePreviewDrafts } from '../../preview/PreviewModeContext';
+/**
+ * Use a single MetadataClient for the whole admin engine.
+ *
+ * The base resolves to `VITE_SERVER_URL` so `/meta/*` writes reach the backend
+ * even when the SPA and API are served from different origins (the split-origin
+ * `pnpm dev` setup: SPA on :5180, backend on :3000). In same-origin production
+ * `VITE_SERVER_URL` is unset → falls back to `''` (relative, current origin),
+ * matching every other client in the app (see `apps/console/src/main.tsx`).
+ */
 export function useMetadataClient(environmentId) {
+    // ADR-0037: inside a draft-preview tree (?preview=draft), reads overlay
+    // pending drafts on the active registry. Writes are unaffected.
+    const previewDrafts = usePreviewDrafts();
     return useMemo(() => {
-        const c = new MetadataClient({ baseUrl: '' });
+        const baseUrl = (typeof import.meta !== 'undefined' &&
+            import.meta.env?.VITE_SERVER_URL) ||
+            '';
+        const c = new MetadataClient({ baseUrl, previewDrafts });
         return environmentId ? c.withEnvironment(environmentId) : c;
-    }, [environmentId]);
+    }, [environmentId, previewDrafts]);
+}
+/**
+ * Drop camelCase aliases when the registry also exposes a snake_case
+ * sibling. The framework's `/meta/types` endpoint surfaces both forms
+ * for some 7.1 system types (e.g. `analytics_cube` + `analyticsCube`,
+ * `sharing_rule` + `sharingRule`) and we don't want the directory to
+ * render the same logical type twice. Keep the snake_case row because
+ * it matches our `TYPE_LABELS_*` keys and the framework's preferred
+ * file naming convention.
+ */
+function dedupeCamelAliases(list) {
+    const have = new Set(list.map((e) => e.type));
+    return list.filter((e) => {
+        if (!/[A-Z]/.test(e.type))
+            return true;
+        const snake = e.type.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+        return !(snake !== e.type && have.has(snake));
+    });
 }
 /**
  * Fetch and cache the rich `/meta/types` registry response. Most pages
@@ -52,7 +85,7 @@ export function useMetadataTypes(client) {
                     }
                 }
                 if (!cancelled) {
-                    setEntries(list);
+                    setEntries(dedupeCamelAliases(list));
                     setLoading(false);
                 }
             }
@@ -94,3 +127,121 @@ export function matchesQuery(item, query, fields = ['name', 'label', 'descriptio
     }
     return false;
 }
+/**
+ * Fetch the cross-type `/meta/diagnostics` sweep once and expose
+ * both the raw entry list and a per-type aggregate (used by the
+ * directory page tiles + the governance overview page).
+ *
+ * `severity` defaults to `'error'` — pass `'warning'` to include
+ * warning-only entries in the count.
+ *
+ * `packageId` (optional) scopes the whole sweep to a single software
+ * package: the server then reports per-package counts/packages, so tile
+ * numbers match the scoped list pages. Omit for a global sweep.
+ */
+export function useGlobalDiagnostics(client, severity = 'error', packageId) {
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [summary, setSummary] = useState({
+        entries: [],
+        total: 0,
+        scannedTypes: 0,
+        scannedItems: 0,
+        stats: {},
+    });
+    const [tick, setTick] = useState(0);
+    useEffect(() => {
+        let cancelled = false;
+        setLoading(true);
+        setError(null);
+        (async () => {
+            try {
+                const res = await client.diagnostics(packageId ? { severity, packageId } : { severity });
+                if (cancelled)
+                    return;
+                setSummary(res);
+                setLoading(false);
+            }
+            catch (err) {
+                if (cancelled)
+                    return;
+                // Older servers without /meta/diagnostics: surface as empty,
+                // not as a fatal error — the directory page should still load.
+                setError(err?.message ?? String(err));
+                setSummary({ entries: [], total: 0, scannedTypes: 0, scannedItems: 0, stats: {} });
+                setLoading(false);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [client, severity, packageId, tick]);
+    const byType = useMemo(() => {
+        const c = {};
+        for (const e of summary.entries) {
+            // Only count entries that actually have errors — when severity is
+            // 'warning' the server returns BOTH error and warning-only rows
+            // in the same list, and we want a strict error count here so
+            // headline numbers stay consistent across severity modes.
+            if ((e.diagnostics?.errors?.length ?? 0) > 0) {
+                c[e.type] = (c[e.type] ?? 0) + 1;
+            }
+        }
+        return c;
+    }, [summary]);
+    const warnByType = useMemo(() => {
+        const c = {};
+        for (const e of summary.entries) {
+            const errs = e.diagnostics?.errors?.length ?? 0;
+            const warns = e.diagnostics?.warnings?.length ?? 0;
+            // "Warn-only" = no errors, ≥1 warning. Items with errors are
+            // already counted in `byType` and the louder tier dominates the
+            // UI badge — surfacing them under both would be noisy.
+            if (errs === 0 && warns > 0) {
+                c[e.type] = (c[e.type] ?? 0) + 1;
+            }
+        }
+        return c;
+    }, [summary]);
+    const countsByType = useMemo(() => {
+        const c = {};
+        for (const [t, s] of Object.entries(summary.stats ?? {}))
+            c[t] = s.count;
+        return c;
+    }, [summary]);
+    const lockedByType = useMemo(() => {
+        const c = {};
+        for (const [t, s] of Object.entries(summary.stats ?? {})) {
+            if (typeof s.locked === 'number' && s.locked > 0) {
+                c[t] = s.locked;
+            }
+        }
+        return c;
+    }, [summary]);
+    const packagesByType = useMemo(() => {
+        const c = {};
+        for (const [t, s] of Object.entries(summary.stats ?? {}))
+            c[t] = s.packages ?? [];
+        return c;
+    }, [summary]);
+    const allPackages = useMemo(() => {
+        const set = new Set();
+        for (const s of Object.values(summary.stats ?? {})) {
+            for (const p of s.packages ?? [])
+                set.add(p);
+        }
+        return [...set].sort();
+    }, [summary]);
+    return {
+        loading,
+        error,
+        summary,
+        byType,
+        warnByType,
+        countsByType,
+        lockedByType,
+        packagesByType,
+        allPackages,
+        reload: () => setTick((n) => n + 1),
+    };
+}

package/dist/views/metadata-admin/view-item-normalize.d.ts

@@ -0,0 +1,20 @@
+/**
+ * True when `item` is a **bare aggregated view container** — the legacy
+ * per-object `defineView({ list, form, listViews, formViews })` document
+ * the framework still registers under the bare `<object>` key for runtime
+ * back-compat (dual-read). It carries NO `viewKind` discriminant and holds
+ * at least one of the aggregate buckets.
+ *
+ * Studio expands every such container into independent `<object>.<viewKey>`
+ * ViewItems (including the defaults), so the container row is fully
+ * redundant in the metadata list and should be hidden there.
+ */
+export declare function isAggregatedViewContainer(item: unknown): boolean;
+/**
+ * Derive the display "type" of a view list row. Expanded ViewItems keep
+ * their display type under `config.type` (`grid` / `calendar` / `kanban`
+ * / …) and only the list/form *family* at the top level (`viewKind`); a
+ * legacy flat view carries `type` directly. Returns `undefined` when
+ * nothing is resolvable (e.g. an aggregated container).
+ */
+export declare function viewDisplayType(item: unknown): string | undefined;