@jini-ai/admin 0.3.10 → 0.4.0

package/dist/core/entities/rules.js

@@ -0,0 +1,344 @@
+/**
+ * @file The runtime half of `AdminEntityPort`: registration, descriptor validation, and the one
+ * erasure a screen generic over all entities needs.
+ *
+ * `core/ports/entities.ts` is types only, like every other port. Everything here is the code those
+ * types cannot be: checks that a descriptor is internally consistent, and the single cast that
+ * turns a descriptor-generic port into the shape a screen can hold.
+ *
+ * ## Why any of this is runtime rather than type-level
+ *
+ * Two of the descriptor's own promises are not expressible in the type system:
+ *
+ * - `titleField` names a `text` field on this same descriptor. Encoding that needs a conditional
+ *   type heavy enough to make every descriptor's error message unreadable — and a typo here is not
+ *   cosmetic: it makes every relation picker pointing at this entity render `undefined` for every
+ *   row, which looks like missing data rather than a typo.
+ * - `relation.target` names another *registered* entity. A descriptor cannot know what it will be
+ *   registered beside, so this can only be checked once the registry is assembled.
+ *
+ * Both are therefore checked at composition time, where they fail once, at startup, naming the
+ * problem — rather than at render time, silently, as blank cells.
+ */
+/** Row keys are never declared as fields — every row carries one implicitly. */
+const IMPLICIT_ROW_KEY = 'id';
+/** Bounds on the `json` conformance walk. Sized like `MAX_FIELD_DEFS` in `@jini-ai/cms`: large
+ *  enough that no honest payload hits them, small enough that a cyclic or adversarial value fails
+ *  fast instead of hanging a render. */
+const MAX_JSON_DEPTH = 32;
+const MAX_JSON_NODES = 10_000;
+/**
+ * Whether `value` is a JSON value: `null`, a boolean, a *finite* number, a string, an array of
+ * them, or a plain object of them.
+ *
+ * Bounded by {@link MAX_JSON_DEPTH}/{@link MAX_JSON_NODES}, which also makes it terminate on a
+ * cyclic value rather than recursing forever. "Storage-only" means not indexed — it does not mean
+ * not checked: a validator that returns true for everything is not a validator, and the values it
+ * would wave through (functions, `BigInt`, `undefined`, `NaN`, cycles) are exactly the ones that
+ * throw or silently vanish at the `JSON.stringify` boundary downstream of it.
+ *
+ * @returns `null` when the value conforms, otherwise a one-phrase reason.
+ * @complexity Time O(nodes) bounded by {@link MAX_JSON_NODES}; space O(depth) bounded by
+ *   {@link MAX_JSON_DEPTH}.
+ * @overallScore 100
+ */
+function describeNonJsonValue(value, depth = 0, budget = { nodes: 0 }) {
+    if (depth > MAX_JSON_DEPTH)
+        return `nests deeper than ${MAX_JSON_DEPTH} levels`;
+    if (++budget.nodes > MAX_JSON_NODES)
+        return `holds more than ${MAX_JSON_NODES} values`;
+    if (value === null)
+        return null;
+    const type = typeof value;
+    if (type === 'string' || type === 'boolean')
+        return null;
+    if (type === 'number')
+        return Number.isFinite(value) ? null : 'is a non-finite number';
+    if (type !== 'object')
+        return `is a ${type}`;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const reason = describeNonJsonValue(item, depth + 1, budget);
+            if (reason !== null)
+                return reason;
+        }
+        return null;
+    }
+    // Rejects class instances, `Map`, `Date`, and anything else that survives `typeof === 'object'`
+    // but does not round-trip through JSON as itself.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return 'is a non-plain object';
+    for (const item of Object.values(value)) {
+        const reason = describeNonJsonValue(item, depth + 1, budget);
+        if (reason !== null)
+            return reason;
+    }
+    return null;
+}
+/**
+ * Whether `value` is a legal runtime value for `field`.
+ *
+ * Exported because an EDITOR needs exactly this judgement and must not re-derive it. A generic form
+ * that decides for itself what an `integer` accepts will drift from what the conformance walk
+ * below rejects, and the two disagreeing is worse than either being wrong alone: the form saves a
+ * value the port then reports as a violation, so the write succeeds and the diagnostic blames the
+ * adapter. `1.5` in an `integer` and `Infinity` in a `real` are both reachable from a plain
+ * `<input type="number">` — `step` constrains the spinner, not the parsed value — so this is not a
+ * theoretical seam. One function, both callers.
+ *
+ * @param field The declared field the value is destined for.
+ * @param value The candidate value, typically a form draft entry or an adapter-returned cell.
+ * @returns `null` when it conforms, otherwise a one-phrase reason naming what arrived instead.
+ *   Phrased to complete the sentence "declared `<kind>`; ...".
+ * @complexity Time O(1) for every kind but `json`; see {@link describeNonJsonValue} for that one.
+ * @overallScore 100
+ */
+export function describeAdminEntityFieldMismatch(field, value) {
+    switch (field.kind) {
+        case 'text':
+        case 'relation':
+            return typeof value === 'string' ? null : `expected a string, got ${typeof value}`;
+        case 'datetime':
+            if (typeof value !== 'string')
+                return `expected an ISO-8601 string, got ${typeof value}`;
+            // A `datetime` that is not parseable renders fine and orders wrongly — the exact class of
+            // fault this whole check exists for, so it is a mismatch rather than a pass.
+            return Number.isNaN(Date.parse(value)) ? 'is not a parseable ISO-8601 timestamp' : null;
+        case 'integer':
+            if (typeof value !== 'number')
+                return `expected a number, got ${typeof value}`;
+            return Number.isInteger(value) ? null : 'is not an integer';
+        case 'real':
+            if (typeof value !== 'number')
+                return `expected a number, got ${typeof value}`;
+            return Number.isFinite(value) ? null : 'is not a finite number';
+        case 'boolean':
+            return typeof value === 'boolean' ? null : `expected a boolean, got ${typeof value}`;
+        case 'json': {
+            const reason = describeNonJsonValue(value);
+            return reason === null ? null : `is not a JSON value: it ${reason}`;
+        }
+    }
+}
+/**
+ * Every way `row` fails to match `descriptor`.
+ *
+ * Reports undeclared keys as well as missing and mistyped ones: a key the descriptor does not
+ * mention is invisible to a generic screen, so an adapter growing a field without declaring it
+ * shows up as data that exists and never renders — which reads as a screen bug rather than a
+ * descriptor gap.
+ *
+ * @complexity Time O(fields + row keys) plus the `json` walk; space O(violations).
+ * @overallScore 100
+ */
+function findRowViolations(descriptor, operation, row) {
+    const found = [];
+    const rowId = typeof row.id === 'string' && row.id !== '' ? row.id : '<no id>';
+    const push = (field, problem, detail) => {
+        found.push({ entity: descriptor.name, operation, rowId, field, problem, detail });
+    };
+    if (typeof row.id !== 'string' || row.id === '') {
+        push(IMPLICIT_ROW_KEY, 'wrong-type', 'every row must carry a non-empty string `id`');
+    }
+    const declared = new Set([IMPLICIT_ROW_KEY]);
+    for (const field of descriptor.fields) {
+        declared.add(field.name);
+        const value = row[field.name];
+        if (value === undefined) {
+            if (field.required === true) {
+                push(field.name, 'missing-required', 'declared `required: true` but absent from the row');
+            }
+            continue;
+        }
+        const mismatch = describeAdminEntityFieldMismatch(field, value);
+        if (mismatch !== null)
+            push(field.name, 'wrong-type', `declared \`${field.kind}\`; ${mismatch}`);
+    }
+    for (const key of Object.keys(row)) {
+        if (declared.has(key))
+            continue;
+        push(key, 'undeclared-field', 'present on the row but not declared on the descriptor');
+    }
+    return found;
+}
+/**
+ * Runs `row` past its descriptor and reports anything wrong, then returns it unchanged.
+ *
+ * Deliberately identity-returning: this is an observation point, never a repair point. Coercing a
+ * bad value here would hide the adapter bug it exists to expose.
+ *
+ * @complexity Time O(rows × fields); no-op and O(1) when `onViolation` is absent.
+ * @overallScore 100
+ */
+function checkRow(descriptor, operation, row, onViolation) {
+    if (onViolation === undefined)
+        return row;
+    for (const violation of findRowViolations(descriptor, operation, row))
+        onViolation(violation);
+    return row;
+}
+/**
+ * Erases a port's descriptor generic so a screen can hold ports for different entities in one
+ * collection.
+ *
+ * The `as unknown as` below is unavoidable and is the only one in this port. `create` and `update`
+ * take the row type as a *parameter*, so `AdminEntityPort<SpecificDescriptor>` is contravariant in
+ * it and is genuinely not assignable to any common supertype. The cast is sound in the direction
+ * that gets exercised — a typed row is a bag of unknowns — and unsound only if the adapter's rows
+ * do not match the descriptor it advertises, which is precisely what `options.onViolation` is here
+ * to surface.
+ *
+ * @param port A port whose rows are typed by its own descriptor.
+ * @param options Wire `onViolation` to have every row checked against the descriptor on the way
+ *   out; omit it for zero added cost.
+ * @returns The same port, typed as {@link AdminErasedEntityPort}; a fresh wrapper object when
+ *   `onViolation` is set, and the original object when it is not.
+ * @complexity Time O(1) to erase; O(rows × fields) per call when checking is on.
+ * @overallScore 100
+ */
+export function eraseEntityPort(port, options = {}) {
+    const erased = port;
+    const { onViolation } = options;
+    if (onViolation === undefined)
+        return erased;
+    const { descriptor } = port;
+    const checked = {
+        descriptor,
+        async list(query) {
+            const page = await erased.list(query);
+            for (const row of page.items)
+                checkRow(descriptor, 'list', row, onViolation);
+            return page;
+        },
+        async get(id) {
+            const row = await erased.get(id);
+            return row === null ? null : checkRow(descriptor, 'get', row, onViolation);
+        },
+        async create(input) {
+            return checkRow(descriptor, 'create', await erased.create(input), onViolation);
+        },
+        async update(id, patch) {
+            return checkRow(descriptor, 'update', await erased.update(id, patch), onViolation);
+        },
+    };
+    // Preserved by presence, not by a forwarding stub: a screen decides whether to render a delete
+    // affordance by testing `remove !== undefined`, so wrapping an absent one into an always-present
+    // function would give every entity a delete button that throws.
+    const { remove } = erased;
+    if (remove === undefined)
+        return checked;
+    // `.call(erased, ...)` rather than a bare reference: an adapter written as an object literal with
+    // shorthand methods may legitimately use `this` to reach its own store.
+    return { ...checked, remove: (id) => remove.call(erased, id) };
+}
+/**
+ * Every internal inconsistency in one descriptor, as human-readable sentences.
+ *
+ * @param descriptor The descriptor to check.
+ * @param registryKey The key it is being registered under.
+ * @param registeredNames Every name in the registry, for resolving `relation` targets.
+ * @complexity Time O(fields); space O(problems).
+ * @overallScore 100
+ */
+function findDescriptorProblems(descriptor, registryKey, registeredNames) {
+    const problems = [];
+    const at = `'${registryKey}'`;
+    if (descriptor.name !== registryKey) {
+        // One entity, one name. Allowing these to differ would leave the URL segment, the relation
+        // target, and the registry key as three identifiers with no stated relationship between them.
+        problems.push(`${at}: registered under '${registryKey}' but its descriptor is named '${descriptor.name}'`);
+    }
+    if (descriptor.labelSingular === '' || descriptor.labelPlural === '') {
+        problems.push(`${at}: labelSingular and labelPlural must both be non-empty`);
+    }
+    if (descriptor.fields.length === 0) {
+        problems.push(`${at}: declares no fields, so nothing but its id could ever be shown or edited`);
+    }
+    const seen = new Set();
+    for (const field of descriptor.fields) {
+        if (field.name === '') {
+            problems.push(`${at}: a field has an empty name`);
+            continue;
+        }
+        if (field.name === IMPLICIT_ROW_KEY) {
+            problems.push(`${at}: '${IMPLICIT_ROW_KEY}' is implicit on every row and must not be declared as a field`);
+        }
+        if (seen.has(field.name))
+            problems.push(`${at}: field '${field.name}' is declared more than once`);
+        seen.add(field.name);
+        if (field.kind === 'relation' && !registeredNames.has(field.target)) {
+            problems.push(`${at}: field '${field.name}' targets '${field.target}', which is not a registered entity`);
+        }
+    }
+    const titleField = descriptor.fields.find((field) => field.name === descriptor.titleField);
+    if (titleField === undefined) {
+        problems.push(`${at}: titleField '${descriptor.titleField}' does not name a declared field`);
+    }
+    else if (titleField.kind !== 'text') {
+        problems.push(`${at}: titleField '${descriptor.titleField}' is kind '${titleField.kind}'; a title must be 'text'`);
+    }
+    return problems;
+}
+/**
+ * Assembles entity ports into a registry, validating every descriptor first.
+ *
+ * Same ergonomics as `createAdminClient`: one object literal, `TPorts` inferred, host-owned and
+ * Jini-shipped entries indistinguishable. Registering an entity is one line.
+ *
+ * **No key is reserved.** `createAdminClient` reserves `'transport'` because it merges the
+ * transport into the same object it returns; this returns nothing but the ports, so there is
+ * nothing an entity named `transport` could shadow. The returned object has a `null` prototype, so
+ * a lookup by an attacker- or URL-supplied name (`'constructor'`, `'__proto__'`) resolves to
+ * `undefined` rather than walking to `Object.prototype` and yielding a truthy non-port.
+ *
+ * Deliberately takes no erasure options: a registry holds ports with their row types intact, and
+ * checking only becomes possible once those types are erased. `onViolation` therefore belongs to
+ * {@link getErasedEntityPort}/{@link listErasedEntityPorts}, at the point the guarantee is dropped.
+ *
+ * @param ports Entity name -> port. Each key must equal that port's `descriptor.name`.
+ * @returns A frozen, null-prototype registry preserving each port's own type.
+ * @throws {Error} listing *every* problem found, not just the first — a descriptor with three
+ *   typos should take one round trip to fix, not three.
+ * @complexity Time O(entities × fields); space O(entities).
+ * @overallScore 100
+ */
+export function createAdminEntityRegistry(ports) {
+    const entries = Object.entries(ports);
+    const registeredNames = new Set(entries.map(([, port]) => port.descriptor.name));
+    const problems = entries.flatMap(([key, port]) => findDescriptorProblems(port.descriptor, key, registeredNames));
+    if (problems.length > 0) {
+        throw new Error(`createAdminEntityRegistry: invalid descriptors\n- ${problems.join('\n- ')}`);
+    }
+    const registry = Object.create(null);
+    for (const [key, port] of entries)
+        registry[key] = port;
+    return Object.freeze(registry);
+}
+/**
+ * Every registered port, erased, in registration order — what a screen that renders any entity
+ * iterates.
+ *
+ * @complexity Time O(entities); space O(entities).
+ * @overallScore 100
+ */
+export function listErasedEntityPorts(registry, options = {}) {
+    return Object.values(registry).map((port) => eraseEntityPort(port, options));
+}
+/**
+ * The erased port registered under `name`, or `null`.
+ *
+ * `name` is routinely a URL segment, so this never trusts a bare property read: the registry's null
+ * prototype already stops `'constructor'` resolving to something truthy, and `Object.hasOwn` holds
+ * that guarantee even for a caller that hands in a plain object literal instead.
+ *
+ * @complexity Time O(1) for the lookup, O(1) for the erasure.
+ * @overallScore 100
+ */
+export function getErasedEntityPort(registry, name, options = {}) {
+    if (!Object.hasOwn(registry, name))
+        return null;
+    const port = registry[name];
+    return port === undefined ? null : eraseEntityPort(port, options);
+}
+//# sourceMappingURL=rules.js.map

package/dist/core/gated/types.d.ts

@@ -74,14 +74,18 @@ export interface GatedConfirmResult {
  * excludes it is describing the easy case and abandoning the one that matters. Widened rather than
  * documented around.
  *
- * The extra parameters default to `string`, so the simple case still reads
+ * The extra parameters default to objects carrying `token` and `confirmToken`, so the simple case still reads
  * `GatedOperation<PlanInput, Details, Result>` with no change.
  */
-export interface GatedOperation<TPlanInput, TDetails, TResult, TConfirmInput = string, TExecuteInput = string> {
+export interface GatedOperation<TPlanInput extends object, TDetails, TResult, TConfirmInput extends object = {
+    readonly token: string;
+}, TExecuteInput extends object = {
+    readonly confirmToken: string;
+}> {
     plan(input: TPlanInput): Promise<GatedPlanResult<TDetails>>;
-    /** Takes the plan's `token`, either bare or as one field of an operation-specific object. */
+    /** Takes the plan's `token` as a field of an operation-specific object. */
     confirm(input: TConfirmInput): Promise<GatedConfirmResult>;
-    /** Takes the confirm step's `confirmToken`, bare or within an operation-specific object. */
+    /** Takes the confirm step's `confirmToken` within an operation-specific object. */
     execute(input: TExecuteInput): Promise<TResult>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/core/index.d.ts

@@ -18,4 +18,8 @@ export type { GatedConfirmResult, GatedOperation, GatedPlanResult } from './gate
 export type { DataTableSortDirection, DataTableSortState } from './data-table/types.js';
 export type { AdminAnalyticsHit, AdminAnalyticsPort, AdminAuthPort, AdminAuthUser, AdminComment, AdminCommentsPort, AdminCommentsQueuePage, AdminDatabasePort, AdminDegradedBanner, AdminDisclosureResult, AdminExtensionEnabledResult, AdminExtensionsPort, AdminIdentityPort, AdminIdentityUser, AdminIntegrationDelivery, AdminIntegrationDeliverySummary, AdminIntegrationSubscription, AdminIntegrationsPort, AdminLedgerRow, AdminMedia, AdminMediaPort, AdminMember, AdminMembersPort, AdminPlugin, AdminPolicy, AdminRecoveryDeepLinkResult, AdminRecoveryPort, AdminRecoveryStatus, AdminRestorePoint, AdminRestorePointSummary, AdminRole, AdminSettingsPort, AdminWorkspace, AdminWorkspacePort, CategoryCount, CommentModerationAction, CommentsSettings, CommentStatus, DatabaseContextEnvelope, DegradedBannerActionKind, DegradedBannerKind, MigrateForwardResult, RestoreConfirmInput, RestoreExecuteInput, RestoreExecuteResult, RestorePointCostClass, SettingResolvedValue, SettingResetResponse, SettingScope, SettingValueResponse, } from './ports/index.js';
 export type { AdminAssignMenuLocationResult, AdminDeleteMenuResult, AdminFormCreateInput, AdminFormDefinition, AdminFormField, AdminFormNotifyConfig, AdminFormsPort, AdminFormSubmission, AdminFormSubmissionPage, AdminFormUpdatePatch, AdminMenu, AdminMenuBinding, AdminMenuCreateInput, AdminMenuCustomTarget, AdminMenuEntryTarget, AdminMenuItem, AdminMenuItemAttrs, AdminMenuRouteTarget, AdminMenusPort, AdminMenuTarget, AdminMenuTermTarget, AdminMenuUpdateTreeInput, AdminMenuUrlTarget, AdminRedirect, AdminRedirectCreateInput, AdminRedirectHitStats, AdminRedirectImportFailure, AdminRedirectImportResult, AdminRedirectListFilter, AdminRedirectsPort, AdminRedirectUpdatePatch, AdminSeoAnalysis, AdminSeoIssue, AdminSeoMeta, AdminSeoOpenGraph, AdminSeoOverrides, AdminSeoPort, AdminSeoRobotsDirective, AdminSeoRobotsRule, AdminSeoSettings, AdminSeoTwitterCard, FormDefinitionStatus, FormFieldType, MenuStatus, NavTargetKind, RedirectMatchType, RedirectSource, RedirectStatus, RedirectStatusCode, SeoIssueSeverity, SeoOpenGraphType, SeoTwitterCardKind, } from './ports/index.js';
+export type { AdminEntityDescriptor, AdminEntityField, AdminEntityFieldKind, AdminEntityFilter, AdminEntityJsonField, AdminEntityListQuery, AdminEntityPage, AdminEntityPort, AdminEntityRegistry, AdminEntityRelationField, AdminEntityRow, AdminEntityRowData, AdminEntityScalarField, AdminErasedEntityPort, } from './ports/index.js';
+export { createAdminEntityRegistry, describeAdminEntityFieldMismatch, eraseEntityPort, getErasedEntityPort, listErasedEntityPorts, } from './entities/rules.js';
+export type { AdminEntityErasureOptions, AdminEntityRowViolation } from './entities/rules.js';
+export type { AdminShellContext, AdminShellNavigationPort, AdminShellSession, AdminShellSessionPort } from './ports/shell.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -12,4 +12,5 @@ export { DEFAULT_ADMIN_BASE, adminHref, currentRoutePath, matchRoute, stripTrail
 export { hasPermission } from './permissions/rules.js';
 // Transport — the seam every route group is built on.
 export { AdminApiError, createAdminClient, createHttpTransport, describeApiError, } from './transport/index.js';
+export { createAdminEntityRegistry, describeAdminEntityFieldMismatch, eraseEntityPort, getErasedEntityPort, listErasedEntityPorts, } from './entities/rules.js';
 //# sourceMappingURL=index.js.map

package/dist/core/manifest/rules.d.ts

@@ -22,7 +22,9 @@ export interface AdminRegistryContext {
  * @complexity O(p * (r + m)) — p panels, r requirements each, m permissions each. All three are
  * small, bounded by what a developer typed into a manifest.
  */
-export declare function resolvePanels<T>(panels: readonly AdminPanel<T>[], context?: AdminRegistryContext): readonly AdminPanel<T>[];
+export declare function resolvePanels<T>({ panels }: {
+    readonly panels: readonly AdminPanel<T>[];
+}, context?: AdminRegistryContext): readonly AdminPanel<T>[];
 /** A sidebar group, ready to render. */
 export interface AdminNavGroup {
     /** Group heading; absent for the ungrouped top row. */
@@ -46,9 +48,18 @@ export interface AdminNavItem extends AdminNavEntry {
  *
  * @complexity O(n log n) on the items within each group; O(n) otherwise.
  */
-export declare function buildNav<T>(panels: readonly AdminPanel<T>[]): readonly AdminNavGroup[];
-/** Panel id -> its **route path**. `dashboard` is the root, not `/dashboard`. */
-export declare function panelHref(panelId: string): string;
+export declare function buildNav<T>({ panels }: {
+    readonly panels: readonly AdminPanel<T>[];
+}, options?: {
+    readonly defaultPanelId?: string;
+}): readonly AdminNavGroup[];
+/** Panel id -> its **route path**. `dashboard` is the root, not `/dashboard`, unless the host
+ *  assigns root to another default panel. Navigation and agent maps must share that policy. */
+export declare function panelHref({ panelId }: {
+    readonly panelId: string;
+}, { defaultPanelId }?: {
+    readonly defaultPanelId?: string;
+}): string;
 /**
  * The agent-navigable page ids: panel id -> route path.
  *
@@ -68,8 +79,11 @@ export declare function panelHref(panelId: string): string;
  * Note the ordering dependency: callers must pass the **resolved** panel set, not the raw one, or
  * an agent could navigate to a panel whose capability is not wired.
  */
-export declare function buildAgentPageMap<T>(panels: readonly AdminPanel<T>[], options?: {
+export declare function buildAgentPageMap<T>({ panels }: {
+    readonly panels: readonly AdminPanel<T>[];
+}, options?: {
     readonly defaultReachable?: boolean;
+    readonly defaultPanelId?: string;
 }): Readonly<Record<string, string>>;
 /**
  * The page id a resolved route reports through `data-agent-page`.
@@ -80,5 +94,9 @@ export declare function buildAgentPageMap<T>(panels: readonly AdminPanel<T>[], o
  * Falls back to the panel id so a detail route reports its list page (`/posts/abc` -> `posts`),
  * which is the nearest id an agent can actually act on.
  */
-export declare function resolveAgentPageId<T>(panels: readonly AdminPanel<T>[], panelId: string | null, view: string | null): string | null;
+export declare function resolveAgentPageId<T>({ panels, panelId, view }: {
+    readonly panels: readonly AdminPanel<T>[];
+    readonly panelId: string | null;
+    readonly view: string | null;
+}): string | null;
 //# sourceMappingURL=rules.d.ts.map

package/dist/core/manifest/rules.js

@@ -14,14 +14,14 @@ import { hasPermission } from '../permissions/rules.js';
  * @complexity O(p * (r + m)) — p panels, r requirements each, m permissions each. All three are
  * small, bounded by what a developer typed into a manifest.
  */
-export function resolvePanels(panels, context = {}) {
+export function resolvePanels({ panels }, context = {}) {
     const capabilities = context.capabilities ?? [];
     const permissions = context.permissions ?? [];
     return panels.filter((panel) => {
         const capabilitiesMet = (panel.requires ?? []).every((key) => capabilities.includes(key));
         if (!capabilitiesMet)
             return false;
-        return (panel.permissions ?? []).every((p) => hasPermission(permissions, p));
+        return (panel.permissions ?? []).every((p) => hasPermission({ permissions, permission: p }));
     });
 }
 /**
@@ -34,7 +34,7 @@ export function resolvePanels(panels, context = {}) {
  *
  * @complexity O(n log n) on the items within each group; O(n) otherwise.
  */
-export function buildNav(panels) {
+export function buildNav({ panels }, options = {}) {
     const groups = new Map();
     const groupOrder = [];
     // Sentinel for "no group". A panel cannot collide with it: `group` is `string | undefined`, and
@@ -48,7 +48,7 @@ export function buildNav(panels) {
             groups.set(key, []);
             groupOrder.push(key);
         }
-        groups.get(key)?.push({ ...panel.nav, id: panel.id, href: panelHref(panel.id) });
+        groups.get(key)?.push({ ...panel.nav, id: panel.id, href: panelHref({ panelId: panel.id }, options) });
     });
     // Ungrouped first regardless of when it was registered — it is the top row, not a peer group.
     const ordered = [
@@ -65,9 +65,10 @@ export function buildNav(panels) {
 function stableSortByOrder(items) {
     return [...items].sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER));
 }
-/** Panel id -> its **route path**. `dashboard` is the root, not `/dashboard`. */
-export function panelHref(panelId) {
-    return panelId === 'dashboard' ? '/' : `/${panelId}`;
+/** Panel id -> its **route path**. `dashboard` is the root, not `/dashboard`, unless the host
+ *  assigns root to another default panel. Navigation and agent maps must share that policy. */
+export function panelHref({ panelId }, { defaultPanelId = 'dashboard' } = {}) {
+    return panelId === 'dashboard' && defaultPanelId === 'dashboard' ? '/' : `/${panelId}`;
 }
 /**
  * The agent-navigable page ids: panel id -> route path.
@@ -88,12 +89,12 @@ export function panelHref(panelId) {
  * Note the ordering dependency: callers must pass the **resolved** panel set, not the raw one, or
  * an agent could navigate to a panel whose capability is not wired.
  */
-export function buildAgentPageMap(panels, options = {}) {
+export function buildAgentPageMap({ panels }, options = {}) {
     const defaultReachable = options.defaultReachable ?? false;
     const map = {};
     panels.forEach((panel) => {
         if ((panel.agentReachable ?? defaultReachable) === true)
-            map[panel.id] = panelHref(panel.id);
+            map[panel.id] = panelHref({ panelId: panel.id }, options);
         // A param-free detail route carrying an `agentPageId` is a destination in its own right —
         // the reference implementation publishes `widget-regions -> /widgets/regions` exactly this
         // way. A route WITH params
@@ -104,7 +105,7 @@ export function buildAgentPageMap(panels, options = {}) {
                 return;
             if (route.pattern.includes(':'))
                 return;
-            map[route.agentPageId] = `${panelHref(panel.id)}${route.pattern}`.replace('//', '/');
+            map[route.agentPageId] = `${panelHref({ panelId: panel.id }, options)}${route.pattern}`.replace('//', '/');
         });
     });
     return map;
@@ -118,7 +119,7 @@ export function buildAgentPageMap(panels, options = {}) {
  * Falls back to the panel id so a detail route reports its list page (`/posts/abc` -> `posts`),
  * which is the nearest id an agent can actually act on.
  */
-export function resolveAgentPageId(panels, panelId, view) {
+export function resolveAgentPageId({ panels, panelId, view }) {
     if (panelId == null)
         return null;
     const panel = panels.find((p) => p.id === panelId);

package/dist/core/module/controller-store.d.ts

@@ -0,0 +1,22 @@
+export interface ControllerStore<S> {
+    getSnapshot(required?: Record<string, never>, optional?: Record<string, never>): S;
+    subscribe(required: {
+        listener: () => void;
+    }, optional?: Record<string, never>): () => void;
+    dispose(required?: Record<string, never>, optional?: Record<string, never>): void;
+}
+/** Snapshot identity changes only on a write: useSyncExternalStore requires a cached snapshot. */
+export declare function createControllerStore<S extends object>({ initial }: {
+    initial: S;
+}, _optional?: Record<string, never>): {
+    getSnapshot: () => Readonly<S>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    set: ({ patch }: {
+        patch: Partial<S>;
+    }) => void;
+    signal: AbortSignal;
+    dispose: () => void;
+};
+//# sourceMappingURL=controller-store.d.ts.map

package/dist/core/module/controller-store.js

@@ -0,0 +1,32 @@
+/** Snapshot identity changes only on a write: useSyncExternalStore requires a cached snapshot. */
+export function createControllerStore({ initial }, _optional = {}) {
+    let state = Object.freeze(initial), disposed = false;
+    const listeners = new Set();
+    const abort = new AbortController();
+    return {
+        getSnapshot: () => state,
+        subscribe: ({ listener }) => {
+            if (!disposed)
+                listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        set: ({ patch }) => {
+            if (disposed)
+                return;
+            state = Object.freeze({ ...state, ...patch });
+            for (const listener of listeners)
+                listener();
+        },
+        signal: abort.signal,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            abort.abort();
+            listeners.clear();
+        },
+    };
+}
+//# sourceMappingURL=controller-store.js.map

package/dist/core/module/create-admin.d.ts

@@ -0,0 +1,41 @@
+import type { AdminInstance, AdminModule, TabId } from './types.js';
+import type { PortMap, PortValues } from './token.js';
+export declare class AdminConfigError extends Error {
+    readonly issues: readonly string[];
+    constructor({ issues }: {
+        issues: readonly string[];
+    }, _optional?: Record<string, never>);
+}
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type TabMaps<M extends AdminModule> = {
+    [P in keyof M['pages']]: {
+        [T in keyof M['pages'][P]['tabs']]: M['pages'][P]['tabs'][T] extends infer Tab ? Tab extends {
+            requires: infer R extends PortMap;
+        } ? R : {} : never;
+    }[keyof M['pages'][P]['tabs']];
+}[keyof M['pages']];
+type OptionalTabMaps<M extends AdminModule> = {
+    [P in keyof M['pages']]: {
+        [T in keyof M['pages'][P]['tabs']]: M['pages'][P]['tabs'][T] extends {
+            optional: infer R extends PortMap;
+        } ? R : {};
+    }[keyof M['pages'][P]['tabs']];
+}[keyof M['pages']];
+type Values<P> = P extends PortMap ? PortValues<P> : {};
+type RequiredValues<M extends AdminModule> = M extends unknown ? PortValues<NonNullable<M['requires']>> & UnionToIntersection<Values<TabMaps<M>>> : never;
+type ProvidedNames<M extends AdminModule> = M extends unknown ? keyof NonNullable<M['provides']> : never;
+type AllValues<M extends AdminModule> = M extends unknown ? RequiredValues<M> & UnionToIntersection<Values<OptionalTabMaps<M>>> & PortValues<NonNullable<M['optional']>> & PortValues<NonNullable<M['provides']>> : never;
+export type AdminHostPorts<Ms extends readonly AdminModule[]> = Omit<UnionToIntersection<RequiredValues<Ms[number]>>, ProvidedNames<Ms[number]>> & Partial<UnionToIntersection<AllValues<Ms[number]>>>;
+export interface AdminOptions<Ms extends readonly AdminModule[]> {
+    readonly omit?: readonly TabId<Ms[number]>[];
+    /** Host collisions are rejected unless the provider name is explicitly listed here. */
+    readonly overrides?: readonly ProvidedNames<Ms[number]>[];
+    /** No grant means no page/tab access. This UI gate does not replace server authorization. */
+    readonly permissions?: readonly string[];
+}
+export declare function createAdmin<const Ms extends readonly AdminModule[], const P extends AdminHostPorts<Ms>>({ modules, ports, }: {
+    modules: Ms;
+    ports: P & Record<Exclude<keyof P, keyof AdminHostPorts<Ms>>, never>;
+}, options?: AdminOptions<Ms>): AdminInstance;
+export {};
+//# sourceMappingURL=create-admin.d.ts.map