@pikku/inspector 0.12.102 → 0.12.103

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.12.103
+
+### Patch Changes
+
+- 53ac40d: An addon can ship screens: `wireAddon({ ui: true })` mounts what the package declares with `defineScreens`, the inspector reads them, `pikku all` emits the screens manifest and the installed-addons registry, and `x-pikku-addon` narrows a session to the addon's role. `pikku new addon --ui` scaffolds one; its tables must be prefixed `<name>_`.
+- Updated dependencies [a196a21]
+- Updated dependencies [53ac40d]
+- Updated dependencies [443fd40]
+- Updated dependencies [56c8047]
+  - @pikku/core@0.12.139
+
 ## 0.12.102
 
 ### Patch Changes

package/dist/add/add-define-screens.d.ts

@@ -0,0 +1,8 @@
+import * as ts from 'typescript';
+import type { InspectorState, InspectorLogger } from '../types.js';
+/**
+ * Detect `defineScreens({ title, icon, screens })` and record the manifest.
+ * A screen with a field that is not a literal is reported and left out: a
+ * navigation entry the host cannot read would otherwise vanish with no sign.
+ */
+export declare function addDefineScreens(node: ts.Node, state: InspectorState, logger: InspectorLogger): void;

package/dist/add/add-define-screens.js

@@ -0,0 +1,140 @@
+import * as ts from 'typescript';
+import { ErrorCode } from '../error-codes.js';
+const propName = (prop) => {
+    if (!ts.isPropertyAssignment(prop))
+        return undefined;
+    return ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)
+        ? prop.name.text
+        : undefined;
+};
+const stringArray = (node) => {
+    if (!ts.isArrayLiteralExpression(node))
+        return undefined;
+    const values = [];
+    for (const element of node.elements) {
+        if (!ts.isStringLiteral(element))
+            return undefined;
+        values.push(element.text);
+    }
+    return values;
+};
+/**
+ * The module specifier of `() => import('./screens/x')`. Anything else cannot
+ * be handed to the host's bundler as a lazy import, so it is not read.
+ */
+const lazyImportSpecifier = (node) => {
+    if (!ts.isArrowFunction(node))
+        return undefined;
+    const body = node.body;
+    if (!ts.isCallExpression(body) ||
+        body.expression.kind !== ts.SyntaxKind.ImportKeyword)
+        return undefined;
+    const [specifier] = body.arguments;
+    return specifier && ts.isStringLiteral(specifier) ? specifier.text : undefined;
+};
+/**
+ * Detect `defineScreens({ title, icon, screens })` and record the manifest.
+ * A screen with a field that is not a literal is reported and left out: a
+ * navigation entry the host cannot read would otherwise vanish with no sign.
+ */
+export function addDefineScreens(node, state, logger) {
+    if (!ts.isCallExpression(node))
+        return;
+    const { expression, arguments: args } = node;
+    if (!ts.isIdentifier(expression) || expression.text !== 'defineScreens')
+        return;
+    const [firstArg] = args;
+    if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
+        return;
+    const fail = (message) => logger.critical(ErrorCode.ADDON_SCREENS_NOT_STATIC, message);
+    let title;
+    let icon;
+    const screens = [];
+    for (const prop of firstArg.properties) {
+        const key = propName(prop);
+        if (!key || !ts.isPropertyAssignment(prop))
+            continue;
+        if (key === 'title' && ts.isStringLiteral(prop.initializer)) {
+            title = prop.initializer.text;
+        }
+        else if (key === 'icon' && ts.isStringLiteral(prop.initializer)) {
+            icon = prop.initializer.text;
+        }
+        else if (key === 'screens') {
+            if (!ts.isArrayLiteralExpression(prop.initializer)) {
+                fail(`defineScreens's screens must be an array literal, got: ${prop.initializer.getText()}`);
+                continue;
+            }
+            for (const element of prop.initializer.elements) {
+                if (!ts.isObjectLiteralExpression(element)) {
+                    fail(`A defineScreens screen must be an object literal, got: ${element.getText()}`);
+                    continue;
+                }
+                let path;
+                let screenTitle;
+                let nav;
+                let scopes;
+                let component;
+                let app;
+                for (const field of element.properties) {
+                    const fieldKey = propName(field);
+                    if (!fieldKey || !ts.isPropertyAssignment(field))
+                        continue;
+                    const value = field.initializer;
+                    if (fieldKey === 'path' && ts.isStringLiteral(value)) {
+                        path = value.text;
+                    }
+                    else if (fieldKey === 'title' && ts.isStringLiteral(value)) {
+                        screenTitle = value.text;
+                    }
+                    else if (fieldKey === 'nav' &&
+                        (value.kind === ts.SyntaxKind.TrueKeyword ||
+                            value.kind === ts.SyntaxKind.FalseKeyword)) {
+                        nav = value.kind === ts.SyntaxKind.TrueKeyword;
+                    }
+                    else if (fieldKey === 'scopes') {
+                        scopes = stringArray(value);
+                        if (!scopes) {
+                            fail(`A screen's scopes must be an array of string literals, got: ${value.getText()}`);
+                        }
+                    }
+                    else if (fieldKey === 'component') {
+                        component = lazyImportSpecifier(value);
+                        if (!component) {
+                            fail(`A screen's component must be () => import('<literal>'), got: ${value.getText()}`);
+                        }
+                    }
+                    else if (fieldKey === 'app' && ts.isStringLiteral(value)) {
+                        app = value.text;
+                    }
+                }
+                if (!path || !screenTitle || (!component && !app)) {
+                    fail(`A defineScreens screen needs a literal path and title, and either a lazy component or an app: ${element.getText()}`);
+                    continue;
+                }
+                if (component && app) {
+                    fail(`Screen '${path}' sets both component and app; a screen is one or the other`);
+                    continue;
+                }
+                screens.push({
+                    path,
+                    title: screenTitle,
+                    ...(nav !== undefined ? { nav } : {}),
+                    ...(scopes ? { scopes } : {}),
+                    ...(component ? { component } : { app: app }),
+                });
+            }
+        }
+    }
+    if (!title) {
+        fail(`defineScreens needs a literal title`);
+        return;
+    }
+    logger.debug(`• Found defineScreens: ${title} (${screens.length} screens)`);
+    state.screensManifest = {
+        title,
+        ...(icon ? { icon } : {}),
+        file: node.getSourceFile().fileName,
+        screens,
+    };
+}

package/dist/add/add-wire-addon.js

@@ -87,7 +87,8 @@ export function addWireAddon(node, state, logger) {
     if (!ts.isCallExpression(node))
         return;
     const { expression, arguments: args } = node;
-    if (!ts.isIdentifier(expression) || expression.text !== 'wireAddon')
+    if (!ts.isIdentifier(expression) ||
+        expression.text !== 'wireAddon')
         return;
     const [firstArg] = args;
     if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
@@ -99,8 +100,10 @@ export function addWireAddon(node, state, logger) {
     let expose;
     let mcpEndpoint;
     let auth;
+    let ui;
     let tags;
     let scopes;
+    let uses;
     let secretOverrides;
     let variableOverrides;
     let credentialOverrides;
@@ -108,6 +111,9 @@ export function addWireAddon(node, state, logger) {
     let credentialGrants;
     let globalSecrets;
     let globalCredentials;
+    let contentBucket;
+    let contentGrants;
+    let globalContent;
     for (const prop of firstArg.properties) {
         if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
             continue;
@@ -154,12 +160,25 @@ export function addWireAddon(node, state, logger) {
                 prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
             auth = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
         }
+        else if (key === 'ui' &&
+            (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
+            ui = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
+        }
         else if (key === 'tags') {
             tags = parseStringArray(prop.initializer);
         }
         else if (key === 'scopes') {
             scopes = parseStringArray(prop.initializer);
         }
+        else if (key === 'uses') {
+            if (ts.isObjectLiteralExpression(prop.initializer)) {
+                uses = parseStringRecord(prop.initializer);
+            }
+            else {
+                logger.critical(ErrorCode.ADDON_EXPOSE_NOT_STATIC, `wireAddon's uses must be an object literal, got: ${prop.initializer.getText()}`);
+            }
+        }
         else if (key === 'secretOverrides' &&
             ts.isObjectLiteralExpression(prop.initializer)) {
             secretOverrides = parseStringRecord(prop.initializer);
@@ -190,12 +209,26 @@ export function addWireAddon(node, state, logger) {
                 ? prop.initializer.text
                 : prop.initializer.getText();
         }
+        else if (key === 'contentBucket' &&
+            ts.isStringLiteral(prop.initializer)) {
+            contentBucket = prop.initializer.text;
+        }
+        else if (key === 'contentGrants' &&
+            ts.isObjectLiteralExpression(prop.initializer)) {
+            contentGrants = parseStringRecord(prop.initializer);
+        }
+        else if (key === 'globalContent') {
+            globalContent = ts.isStringLiteral(prop.initializer)
+                ? prop.initializer.text
+                : prop.initializer.getText();
+        }
     }
     if (!name || !pkg)
         return;
-    logger.debug(`• Found wireAddon: ${name} → ${pkg}`);
+    logger.debug(`• Found ${expression.text}: ${name} → ${pkg}`);
     state.rpc.wireAddonDeclarations.set(name, {
         package: pkg,
+        ...(ui ? { ui } : {}),
         file: node.getSourceFile().fileName,
         rpcEndpoint,
         mcp,
@@ -204,6 +237,7 @@ export function addWireAddon(node, state, logger) {
         auth,
         tags,
         scopes,
+        uses,
         secretOverrides,
         variableOverrides,
         credentialOverrides,
@@ -211,6 +245,9 @@ export function addWireAddon(node, state, logger) {
         credentialGrants,
         globalSecrets,
         globalCredentials,
+        contentBucket,
+        contentGrants,
+        globalContent,
     });
     state.rpc.usedAddons.add(name);
     state.rpc.wireAddonFiles.add(node.getSourceFile().fileName);

package/dist/error-codes.d.ts

@@ -36,6 +36,11 @@ export declare enum ErrorCode {
     ADDON_MCP_FUNCTION_NOT_FOUND = "PKU341",
     ADDON_EXPOSE_FUNCTION_NOT_FOUND = "PKU343",
     ADDON_EXPOSE_NOT_STATIC = "PKU344",
+    ADDON_SCREENS_NOT_STATIC = "PKU345",
+    ADDON_UI_HAS_NO_SCREENS = "PKU346",
+    ADDON_USES_NOT_WIRED = "PKU347",
+    ADDON_NEEDS_NOT_MAPPED = "PKU348",
+    ADDON_CONTENT_GRANT_INVALID = "PKU349",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",

package/dist/error-codes.js

@@ -39,6 +39,11 @@ export var ErrorCode;
     ErrorCode["ADDON_MCP_FUNCTION_NOT_FOUND"] = "PKU341";
     ErrorCode["ADDON_EXPOSE_FUNCTION_NOT_FOUND"] = "PKU343";
     ErrorCode["ADDON_EXPOSE_NOT_STATIC"] = "PKU344";
+    ErrorCode["ADDON_SCREENS_NOT_STATIC"] = "PKU345";
+    ErrorCode["ADDON_UI_HAS_NO_SCREENS"] = "PKU346";
+    ErrorCode["ADDON_USES_NOT_WIRED"] = "PKU347";
+    ErrorCode["ADDON_NEEDS_NOT_MAPPED"] = "PKU348";
+    ErrorCode["ADDON_CONTENT_GRANT_INVALID"] = "PKU349";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { inspect, getInitialInspectorState } from './inspector.js';
 export type { TypesMap } from './types-map.js';
-export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
+export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, ScreensManifestMeta, AddonScreenMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
 export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';

package/dist/inspector.js

@@ -9,7 +9,7 @@ import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
 import { toProgramPath } from './utils/program-path.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateAddonUses, validateAddonContentGrants, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
@@ -427,6 +427,8 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validateSecretOverrides(logger, state);
         validateVariableOverrides(logger, state);
         validateCredentialOverrides(logger, state);
+        validateAddonUses(logger, state);
+        validateAddonContentGrants(logger, state);
         validateRemoteAddonDependencies(logger, state);
         validateRemoteAddonAuth(logger, state);
         applyDeclaredScopes(state);

package/dist/types.d.ts

@@ -491,7 +491,38 @@ export type CredentialOverrideMeta = string | {
     name?: string;
     mode?: 'singleton' | 'wire';
 };
+/** A screen of an addon as `defineScreens` declares it, read statically. */
+export type AddonScreenMeta = {
+    path: string;
+    title: string;
+    nav?: boolean;
+    scopes?: string[];
+} & ({
+    component: string;
+    app?: undefined;
+} | {
+    app: string;
+    component?: undefined;
+});
+export type ScreensManifestMeta = {
+    title: string;
+    icon?: string;
+    /** The source file whose `defineScreens` call declared this manifest. */
+    file: string;
+    screens: AddonScreenMeta[];
+    /**
+     * The addon's role: every scope its own functions require, derived by
+     * `pikku all` and never declared. Absent from the raw `defineScreens` read.
+     * On a wired instance it also carries the host's `wireAddon` scopes, which
+     * the runner demands of every function in the package.
+     */
+    scopes?: string[];
+};
 export interface InspectorState {
+    /** Set when this package calls `defineScreens`: the screens it ships. */
+    screensManifest?: ScreensManifestMeta;
+    /** The screens of the addons this project wires with `ui: true`, by namespace. */
+    addonScreens?: Record<string, ScreensManifestMeta>;
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
     wireServicesTypeImportMap: PathToNameAndType;
@@ -605,7 +636,11 @@ export interface InspectorState {
             package: string;
             /** The app source file whose `wireAddon` call declared this instance. */
             file?: string;
+            /** Declared with `ui: true`: the package must ship screens, and the host mounts them. */
+            ui?: boolean;
             rpcEndpoint?: string;
+            /** The other addons this instance may call: package -> the name it is wired under. */
+            uses?: Record<string, string>;
             /**
              * `true` offers every function the addon declared `mcp: true`; a list
              * names the functions to offer, whatever the addon declared. Absent
@@ -660,6 +695,13 @@ export interface InspectorState {
              * `CredentialService` instead of one scoped to its declared credentials.
              */
             globalCredentials?: string;
+            contentBucket?: string;
+            contentGrants?: Record<string, string>;
+            /**
+             * The app's stated reason for handing this instance the whole
+             * `ContentService` instead of one scoped to its own folder.
+             */
+            globalContent?: string;
         }>;
         wireAddonFiles: Set<string>;
     };

package/dist/utils/load-addon-functions-meta.d.ts

@@ -8,11 +8,6 @@ export declare const describeMissingAddonMeta: (namespace: string, packageName:
  * Every source starts off: the app turns one on at runtime.
  */
 export declare const namespaceAddonWebhookSources: (sources: WebhookSourcesMeta, namespace: string) => WebhookSourcesMeta;
-/**
- * After the setup sweep discovers wireAddon() declarations, load each addon
- * package's function metadata so that wiring handlers (channels, HTTP routes,
- * schedules, etc.) can look up addon function types during the routes sweep.
- */
 export declare function loadAddonFunctionsMeta(logger: InspectorLogger, state: InspectorState): Promise<void>;
 /**
  * Load addon schemas into state.schemas. Called after generateAllSchemas

package/dist/utils/load-addon-functions-meta.js

@@ -181,6 +181,27 @@ export const namespaceAddonWebhookSources = (sources, namespace) => {
  * package's function metadata so that wiring handlers (channels, HTTP routes,
  * schedules, etc.) can look up addon function types during the routes sweep.
  */
+const loadScreensManifest = async (require, packageName) => {
+    const path = resolveAddonMeta(require, packageName, 'screens/pikku-screens-meta');
+    if (!path)
+        return null;
+    return JSON.parse(await readFile(path, 'utf-8'));
+};
+const readAddonNeeds = async (dirs, packageName) => {
+    const dir = findInstalledPackageDir(dirs, packageName);
+    if (!dir)
+        return [];
+    try {
+        const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf-8'));
+        const uses = pkg?.pikku?.uses;
+        return Array.isArray(uses)
+            ? uses.filter((u) => typeof u === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+};
 export async function loadAddonFunctionsMeta(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (wireAddonDeclarations.size === 0)
@@ -194,6 +215,37 @@ export async function loadAddonFunctionsMeta(logger, state) {
         const dirs = addonResolutionDirs(state.rootDir, decl.file);
         const require = createAddonResolver(dirs);
         try {
+            for (const needed of await readAddonNeeds(dirs, decl.package)) {
+                if (!decl.uses?.[needed]) {
+                    logger.critical(ErrorCode.ADDON_NEEDS_NOT_MAPPED, `${decl.package} needs ${needed}, but wireAddon('${namespace}') does not map it. Wire ${needed} and add uses: { '${needed}': '<name>' } to this wireAddon.`);
+                }
+            }
+            if (decl.ui) {
+                let manifest;
+                let unreadable = false;
+                try {
+                    manifest = await loadScreensManifest(require, decl.package);
+                }
+                catch (e) {
+                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but the screens manifest of ${decl.package} could not be read: ${e instanceof Error ? e.message : e}`);
+                    unreadable = true;
+                }
+                if (unreadable) {
+                    // reported above; the addon's functions and scopes still load
+                }
+                else if (!manifest || manifest.screens.length === 0) {
+                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but ${decl.package} declares no screens. Add a defineScreens call to the package, or drop ui.`);
+                }
+                else {
+                    ;
+                    (state.addonScreens ??= {})[namespace] = {
+                        ...manifest,
+                        scopes: [
+                            ...new Set([...(manifest.scopes ?? []), ...(decl.scopes ?? [])]),
+                        ].sort(),
+                    };
+                }
+            }
             // Verbose first. `description` is one of the fields stripped from the
             // minimal copy, and it is what an addon's function is offered to a model
             // under — both as an MCP tool below and as an agent tool. Read the minimal

package/dist/utils/post-process.d.ts

@@ -31,6 +31,8 @@ export declare function extractWireNames(list?: Array<MiddlewareMetadata | Permi
  */
 export declare function aggregateRequiredServices(state: InspectorState | Omit<InspectorState, "typesLookup">): void;
 export declare function validateSecretOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateAddonUses(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateAddonContentGrants(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
 export declare function validateCredentialOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
 export declare function validateVariableOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
 /**

package/dist/utils/post-process.js

@@ -393,6 +393,39 @@ export function validateSecretOverrides(logger, state) {
         }
     }
 }
+export function validateAddonUses(logger, state) {
+    const { wireAddonDeclarations } = state.rpc;
+    if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
+        return;
+    for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
+        for (const [pkg, target] of Object.entries(addonDecl.uses ?? {})) {
+            const wired = wireAddonDeclarations.get(target);
+            if (!wired) {
+                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but no addon is wired under the name '${target}'. Wired: ${Array.from(wireAddonDeclarations.keys()).join(", ")}`);
+            }
+            else if (wired.package !== pkg) {
+                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but '${target}' is wired from '${wired.package}'.`);
+            }
+        }
+    }
+}
+export function validateAddonContentGrants(logger, state) {
+    const { wireAddonDeclarations } = state.rpc;
+    if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
+        return;
+    const buckets = new Set(Array.from(wireAddonDeclarations.entries()).map(([namespace, decl]) => decl.contentBucket ?? namespace));
+    for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+        for (const [prefix, mode] of Object.entries(decl.contentGrants ?? {})) {
+            if (mode !== "read" && mode !== "write") {
+                logger.critical(ErrorCode.ADDON_CONTENT_GRANT_INVALID, `Addon '${namespace}' grants '${prefix}' as '${mode}', but a content grant must be 'read' or 'write'.`);
+            }
+            const first = prefix.split("/").find((segment) => segment !== "");
+            if (!first || !buckets.has(first)) {
+                logger.critical(ErrorCode.ADDON_CONTENT_GRANT_INVALID, `Addon '${namespace}' grants content under '${prefix}', but '${first ?? ""}' is not the content bucket of any wired addon. Buckets: ${Array.from(buckets).join(", ")}`);
+            }
+        }
+    }
+}
 export function validateCredentialOverrides(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)

package/dist/utils/serialize-inspector-state.d.ts

@@ -204,6 +204,9 @@ export interface SerializableInspectorState {
                 credentialGrants?: string[];
                 globalSecrets?: string;
                 globalCredentials?: string;
+                contentBucket?: string;
+                contentGrants?: Record<string, string>;
+                globalContent?: string;
             }
         ]>;
         wireAddonFiles: string[];
@@ -317,6 +320,8 @@ export interface SerializableInspectorState {
     openAPISpec: Record<string, any> | null;
     diagnostics: InspectorDiagnostic[];
     addonFunctions: InspectorState['addonFunctions'];
+    screensManifest?: InspectorState['screensManifest'];
+    addonScreens?: InspectorState['addonScreens'];
     exportedContracts: InspectorState['exportedContracts'];
 }
 /**

package/dist/utils/serialize-inspector-state.js

@@ -182,6 +182,8 @@ export function serializeInspectorState(state) {
         openAPISpec: state.openAPISpec,
         diagnostics: state.diagnostics,
         addonFunctions: state.addonFunctions,
+        screensManifest: state.screensManifest,
+        addonScreens: state.addonScreens,
         exportedContracts: state.exportedContracts,
     };
 }
@@ -378,6 +380,8 @@ export function deserializeInspectorState(data) {
         openAPISpec: data.openAPISpec || null,
         diagnostics: data.diagnostics || [],
         addonFunctions: data.addonFunctions || {},
+        screensManifest: data.screensManifest,
+        addonScreens: data.addonScreens,
         exportedContracts: data.exportedContracts || {
             http: {},
             cli: {},

package/dist/visit.js

@@ -15,6 +15,7 @@ import { addChannel } from './add/add-channel.js';
 import { addGateway } from './add/add-gateway.js';
 import { addRPCInvocations } from './add/add-rpc-invocations.js';
 import { addWireAddon } from './add/add-wire-addon.js';
+import { addDefineScreens } from './add/add-define-screens.js';
 import { addWireRemoteAddon } from './add/add-wire-remote-addon.js';
 import { addMiddleware } from './add/add-middleware.js';
 import { addPermission } from './add/add-permission.js';
@@ -47,6 +48,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addOutgoingWebhook(logger, node, checker, state);
     addRPCInvocations(node, state, logger);
     addWireAddon(node, state, logger);
+    addDefineScreens(node, state, logger);
     addWireRemoteAddon(node, state, logger);
     addMiddleware(logger, node, checker, state, options);
     addPermission(logger, node, checker, state, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.102",
+  "version": "0.12.103",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -54,10 +54,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.137"
+    "@pikku/core": "^0.12.139"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.137",
+    "@pikku/core": "^0.12.139",
     "@types/node": "^24.13.3"
   },
   "engines": {