@jini-ai/admin 0.6.15 → 0.6.16

package/dist/core/index.d.ts

@@ -7,7 +7,7 @@
  * without a DOM environment so a leak fails loudly rather than passing quietly.
  */
 export type { AdminNavEntry, AdminPanel, AdminRoutePattern } from './manifest/types.js';
-export { buildAgentPageMap, buildNav, panelHref, resolveAgentPageId, resolvePanels, } from './manifest/rules.js';
+export { buildAgentPageMap, buildAgentScreens, buildNav, panelHref, resolveAgentPageId, resolvePanels, } from './manifest/rules.js';
 export type { AdminNavGroup, AdminNavItem, AdminRegistryContext } from './manifest/rules.js';
 export type { AdminRoute } from './routing/types.js';
 export { DEFAULT_ADMIN_BASE, adminHref, currentRoutePath, matchRoute, stripTrailingSlash, } from './routing/rules.js';

package/dist/core/index.js

@@ -6,7 +6,7 @@
  * boundary is enforced by this package's vitest config, which deliberately runs `src/core/**`
  * without a DOM environment so a leak fails loudly rather than passing quietly.
  */
-export { buildAgentPageMap, buildNav, panelHref, resolveAgentPageId, resolvePanels, } from './manifest/rules.js';
+export { buildAgentPageMap, buildAgentScreens, buildNav, panelHref, resolveAgentPageId, resolvePanels, } from './manifest/rules.js';
 export { DEFAULT_ADMIN_BASE, adminHref, currentRoutePath, matchRoute, stripTrailingSlash, } from './routing/rules.js';
 // Permissions — affordance only, never an authorization boundary.
 export { hasPermission } from './permissions/rules.js';

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

@@ -99,4 +99,24 @@ export declare function resolveAgentPageId<T>({ panels, panelId, view }: {
     readonly panelId: string | null;
     readonly view: string | null;
 }): string | null;
+/** Extend the existing page projection with descriptions, templates and entity contracts.
+ * Host aliases come from its router adapter, keeping one route owner. Runtime fallback protects
+ * older/untyped panels; compile-time contracts and host drift tests require descriptions. @complexity O(p * r) for p panels. */
+export declare function buildAgentScreens<T>({ panels }: {
+    panels: readonly AdminPanel<T>[];
+}, { defaultReachable, paths }?: {
+    defaultReachable?: boolean;
+    paths?: Readonly<Record<string, string>>;
+}): {
+    id: string;
+    label: string;
+    description: string;
+    path: string;
+    routeTemplates: string[];
+    allowedQueryParams: Readonly<Record<string, readonly string[] | null>>;
+    entityTargets: {
+        type: string;
+        routeTemplate: string;
+    }[];
+}[];
 //# sourceMappingURL=rules.d.ts.map

package/dist/core/manifest/rules.js

@@ -128,4 +128,38 @@ export function resolveAgentPageId({ panels, panelId, view }) {
     const matched = (panel.routes ?? []).find((r) => r.view === view);
     return matched?.agentPageId ?? panel.id;
 }
+/** Extend the existing page projection with descriptions, templates and entity contracts.
+ * Host aliases come from its router adapter, keeping one route owner. Runtime fallback protects
+ * older/untyped panels; compile-time contracts and host drift tests require descriptions. @complexity O(p * r) for p panels. */
+export function buildAgentScreens({ panels }, { defaultReachable = false, paths = {} } = {}) {
+    const pages = buildAgentPageMap({ panels }, { defaultReachable });
+    return Object.entries(pages).map(([id, originalPath]) => {
+        const panel = panels.find(candidate => candidate.id === id || candidate.routes?.some(route => route.agentPageId === id));
+        if (!panel)
+            throw new Error(`Missing owner for admin page "${id}"`);
+        return projectAgentScreen({ id, path: paths[id] ?? originalPath, panel, paths });
+    });
+}
+/** Project the sidebar label or title-case a published route id. */
+function screenLabel({ id, panel }, _options = {}) {
+    const label = panel.id === id ? panel.nav?.label : undefined;
+    return label ?? id.split('-').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
+}
+/** Pure projection over the panel's own route declarations; no route may be invented here. */
+function projectAgentScreen({ id, path, panel, paths }, _options = {}) {
+    const label = screenLabel({ id, panel });
+    const base = (paths[panel.id] ?? panelHref({ panelId: panel.id })).split('?')[0];
+    const template = (pattern) => `${base === '/' ? '' : base}${pattern}` || '/';
+    return {
+        id, label, description: panel.description?.trim() || label, path,
+        routeTemplates: [...new Set([path.split('?')[0], ...(panel.routes ?? []).map(route => template(route.pattern))])],
+        allowedQueryParams: panel.allowedQueryParams ?? {},
+        entityTargets: entitiesForPage({ id, panel }).map(entity => ({ type: entity.type, routeTemplate: template(entity.pattern) })),
+    };
+}
+/** A secondary destination reports its own page identity, so it must not advertise an editor
+ * whose route reports the parent page instead. */
+function entitiesForPage({ id, panel }, _options = {}) {
+    return panel.id === id ? panel.agentEntities ?? [] : [];
+}
 //# sourceMappingURL=rules.js.map

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

@@ -112,6 +112,15 @@ export interface AdminPanel<TRender = unknown> {
      * the page could not act on it without a translation table.
      */
     readonly id: string;
+    /** One plain-language sentence describing what an operator does here. */
+    readonly description: string;
+    /** Allowed route-state keys; null means a free text value, an array constrains its vocabulary. */
+    readonly allowedQueryParams?: Readonly<Record<string, readonly string[] | null>>;
+    /** Existing entity routes, relative to this panel. Empty pattern addresses the landing page. */
+    readonly agentEntities?: readonly {
+        readonly type: string;
+        readonly pattern: string;
+    }[];
     /** What the shell renders for this panel. */
     readonly render: TRender;
     /** Sidebar presence. Omit for a panel that is reachable by URL but not listed. */

package/dist/react/entities/contribution.js

@@ -46,6 +46,7 @@ export function createEntityPanel(args, options = {}) {
     const dependencies = { registry: args.registry, translate: args.translate, routes };
     return {
         id: args.panelId,
+        description: args.translate({ key: 'Browse and edit data records.' }),
         nav: options.nav ?? { label: args.translate({ key: 'Data' }) },
         agentReachable: options.agentReachable ?? false,
         ...(options.requires === undefined ? {} : { requires: options.requires }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/admin",
-  "version": "0.6.15",
+  "version": "0.6.16",
   "description": "Composable admin surface for Jini-hosted products: framework-free contracts, panel registry, and route model in `/core`; React shell and panels in `/react`. Import only the layers you need.",
   "license": "Apache-2.0",
   "repository": {
@@ -95,6 +95,16 @@
           "react-dom"
         ]
       }
+    },
+    "optionalPeers": {
+      "@jini-ai/agentic": "opt-in: agent-aware ui and protocols; import @jini-ai/admin/react — Agent-aware UI and protocols could not load @jini-ai/agentic. Install @jini-ai/agentic to enable this feature, or check its installed version and native binaries.",
+      "@jini-ai/ui": "opt-in: ui integrations; import @jini-ai/admin/react — UI integrations could not load @jini-ai/ui. Install @jini-ai/ui to enable this feature, or check its installed version and native binaries.",
+      "@jini-ai/ui-kit": "opt-in: ui kit integrations; import @jini-ai/admin/react — UI kit integrations could not load @jini-ai/ui-kit. Install @jini-ai/ui-kit to enable this feature, or check its installed version and native binaries.",
+      "@jini-ai/agent-plugins": "opt-in: agent plugin integrations — Agent plugin integrations could not load @jini-ai/agent-plugins. Install @jini-ai/agent-plugins to enable this feature, or check its installed version and native binaries.",
+      "@jini-ai/cms": "opt-in: cms integrations; import @jini-ai/admin/media — CMS integrations could not load @jini-ai/cms. Install @jini-ai/cms to enable this feature, or check its installed version and native binaries.",
+      "@jini-ai/core": "opt-in: core module integrations; import @jini-ai/admin/react — Core module integrations could not load @jini-ai/core. Install @jini-ai/core to enable this feature, or check its installed version and native binaries.",
+      "react": "opt-in: react admin bindings; import @jini-ai/admin/react — React admin bindings could not load react. Install react to enable this feature, or check its installed version.",
+      "react-dom": "opt-in: react admin bindings; import @jini-ai/admin/react — React admin bindings could not load react-dom. Install react-dom to enable this feature, or check its installed version."
     }
   },
   "type": "module",
@@ -455,13 +465,31 @@
     "@jini-ai/cms": "^0.6.10",
     "@jini-ai/core": "^0.6.10"
   },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@jini-ai/ui-kit": "^0.6.16",
+    "@jini-ai/agent-plugins": "^0.6.16",
+    "@jini-ai/cms": "^0.6.16",
+    "@jini-ai/agentic": "^0.6.16",
+    "@jini-ai/ui": "^0.6.16",
+    "@jini-ai/core": "^0.6.16"
+  },
+  "typesVersions": {
+    "*": {
+      "core/react": [
+        "./dist/core/react/index.d.ts"
+      ]
+    }
+  },
   "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
-    },
     "@jini-ai/agentic": {
       "optional": true
     },
@@ -479,30 +507,12 @@
     },
     "@jini-ai/core": {
       "optional": true
-    }
-  },
-  "devDependencies": {
-    "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/react": "^16.3.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "@vitest/coverage-v8": "^2.1.9",
-    "jsdom": "^25.0.1",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "@testing-library/user-event": "^14.6.1",
-    "@jini-ai/agentic": "^0.6.15",
-    "@jini-ai/agent-plugins": "^0.6.15",
-    "@jini-ai/ui-kit": "^0.6.15",
-    "@jini-ai/cms": "^0.6.15",
-    "@jini-ai/core": "^0.6.15",
-    "@jini-ai/ui": "^0.6.15"
-  },
-  "typesVersions": {
-    "*": {
-      "core/react": [
-        "./dist/core/react/index.d.ts"
-      ]
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "scripts": {