@jini-ai/agent-plugins 0.4.7 → 0.4.8

package/dist/admin-surfaces/surface-client.js

@@ -0,0 +1,219 @@
+/**
+ * @file The surface-side half of the admin-surface message protocol, for a plugin's own UI.
+ *
+ * Self-contained on purpose (no imports): a plugin's surface is plain static files, so it may import
+ * this module from the package or copy the compiled file next to its entry. The constants repeat
+ * `./protocol.ts`; the vertical-slice test proves the two still agree.
+ *
+ * Trust rules it applies: it accepts init only from its parent window (once), learns the host's
+ * origin from that init and posts only to that origin (never "*"), and accepts a response only from
+ * the parent, from that origin, for this mount, for a request it still has pending, in a valid shape.
+ *
+ * Theme: the host may send its design tokens with init and again in `theme` messages (`./theme.ts`).
+ * The client applies the `--jini-*` ones with a safe value as custom properties on the surface's root
+ * element (CSSOM `setProperty`, which a CSP without 'unsafe-inline' allows), plus `color-scheme` and
+ * `data-jini-scheme`, so the surface's own stylesheet can follow the admin's look and light/dark mode.
+ */
+const PROTOCOL = 'jini.admin-surface';
+const VERSION = 1;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const THEME_TOKEN = /^--jini-[a-z0-9-]{1,60}$/;
+const UNSAFE_THEME_VALUE = /url\(|image\(|image-set\(|[;{}<>\\@]/i;
+const MAX_THEME_TOKENS = 100;
+/** Rejection value of `call` when the host refused the action or the request timed out. */
+export class AdminSurfaceCallError extends Error {
+    code;
+    retryable;
+    constructor(required) {
+        super(required.message);
+        this.name = 'AdminSurfaceCallError';
+        this.code = required.code;
+        this.retryable = required.retryable;
+    }
+}
+function isMessage(data, kind) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const message = data;
+    return message.protocol === PROTOCOL && message.version === VERSION && message.kind === kind;
+}
+function isFailure(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const error = value;
+    return typeof error.code === 'string' && typeof error.message === 'string' && typeof error.retryable === 'boolean';
+}
+/** The host's theme with every unknown name or unsafe value dropped; undefined when it is not a theme. */
+function acceptedTheme(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const { scheme, tokens } = value;
+    if ((scheme !== 'light' && scheme !== 'dark') || typeof tokens !== 'object' || tokens === null)
+        return undefined;
+    const safe = Object.entries(tokens).slice(0, MAX_THEME_TOKENS).filter(([name, token]) => THEME_TOKEN.test(name)
+        && typeof token === 'string' && token.length > 0 && token.length <= 200 && !UNSAFE_THEME_VALUE.test(token));
+    return { scheme, tokens: Object.fromEntries(safe) };
+}
+/** The browser root when there is a document (none in a server-side test). */
+function documentRoot(scope) {
+    return scope.document?.documentElement ?? null;
+}
+/**
+ * The browser's size source: the body's height including what overflows it (an open toggletip), re-read
+ * on resize, DOM changes, hover and focus (hover/focus can show a CSS-only tooltip). Null without a DOM.
+ */
+function documentSize(scope) {
+    const body = scope.document?.body;
+    if (!body || !scope.ResizeObserver || !scope.MutationObserver || !scope.getComputedStyle)
+        return null;
+    const { ResizeObserver: Resize, MutationObserver: Mutation, getComputedStyle: computedStyle } = scope;
+    return (onHeight) => {
+        const measure = () => {
+            const style = computedStyle(body);
+            // scrollHeight is rounded to whole pixels; the box height keeps the fraction, which would
+            // otherwise leave a 1px inner scrollbar.
+            const content = Math.max(body.scrollHeight, body.getBoundingClientRect().height);
+            onHeight(Math.ceil(content + parseFloat(style.marginTop || '0') + parseFloat(style.marginBottom || '0')));
+        };
+        const resize = new Resize(measure);
+        const mutation = new Mutation(measure);
+        resize.observe(body);
+        mutation.observe(body, { subtree: true, childList: true, attributes: true, characterData: true });
+        body.addEventListener('mouseover', measure);
+        body.addEventListener('focusin', measure);
+        measure();
+        return () => { resize.disconnect(); mutation.disconnect(); body.removeEventListener('mouseover', measure); body.removeEventListener('focusin', measure); };
+    };
+}
+/** A response has `ok: true` with a result, or `ok: false` with a well-formed failure. */
+function isWellFormedResponse(message) {
+    return message.ok === true ? Object.hasOwn(message, 'result') : message.ok === false && isFailure(message.error);
+}
+/**
+ * Connects a surface to its host. In a browser:
+ * `createAdminSurfaceClient({ parent: window.parent, listen: (h) => { addEventListener('message', h); return () => removeEventListener('message', h); } })`.
+ * @param optional.timeoutMs - How long `call` waits for a response before rejecting with `timeout`.
+ * @complexity O(1) per message.
+ */
+export function createAdminSurfaceClient(required, optional = {}) {
+    const timeoutMs = optional.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const nowMs = optional.nowMs ?? Date.now;
+    const pending = new Map();
+    let init;
+    let nextRequest = 0;
+    // The Promise executor runs synchronously, so `resolveReady` is assigned before anything can call it.
+    let resolveReady;
+    const ready = new Promise((resolve) => { resolveReady = resolve; });
+    // The DOM's own observer/element types are wider than the structural subset this client reads.
+    const browser = optional.browser ?? globalThis;
+    const themeRoot = optional.themeRoot === undefined ? documentRoot(browser) : optional.themeRoot;
+    let currentTheme;
+    const size = optional.size === undefined ? documentSize(browser) : optional.size;
+    let stopSize;
+    let lastHeight = -1;
+    /** Tells the host this surface's height (only when it changed), so the frame fits its content. */
+    function reportHeight(height) {
+        if (init === undefined || !Number.isFinite(height) || height === lastHeight)
+            return;
+        lastHeight = height;
+        required.parent.postMessage({ protocol: PROTOCOL, version: VERSION, kind: 'resize', mountId: init.mountId, height }, init.origin);
+    }
+    /** Replaces the applied tokens: a token the new theme no longer sends falls back to the surface's CSS. */
+    function applyTheme(value) {
+        const next = acceptedTheme(value);
+        if (next === undefined)
+            return;
+        if (themeRoot !== null) {
+            for (const name of Object.keys(currentTheme?.tokens ?? {}))
+                if (!(name in next.tokens))
+                    themeRoot.style.removeProperty(name);
+            for (const [name, token] of Object.entries(next.tokens))
+                themeRoot.style.setProperty(name, token);
+            themeRoot.style.setProperty('color-scheme', next.scheme);
+            themeRoot.setAttribute('data-jini-scheme', next.scheme);
+        }
+        currentTheme = next;
+    }
+    function onInit(event, data) {
+        if (init !== undefined || typeof data.mountId !== 'string')
+            return;
+        init = { mountId: data.mountId, origin: event.origin, bootstrap: data.bootstrap };
+        applyTheme(data.theme);
+        stopSize = size?.(reportHeight);
+        resolveReady();
+    }
+    function onResponse(event, data) {
+        if (event.origin !== init?.origin || data.mountId !== init.mountId || typeof data.requestId !== 'string')
+            return;
+        const waiting = pending.get(data.requestId);
+        if (waiting === undefined || !isWellFormedResponse(data))
+            return;
+        pending.delete(data.requestId);
+        clearTimeout(waiting.timer);
+        if (data.ok === true)
+            waiting.resolve(data.result);
+        else
+            waiting.reject(new AdminSurfaceCallError(data.error));
+    }
+    const unsubscribe = required.listen((event) => {
+        if (event.source !== required.parent)
+            return;
+        if (isMessage(event.data, 'init'))
+            onInit(event, event.data);
+        else if (isMessage(event.data, 'theme')) {
+            if (event.origin === init?.origin && event.data.mountId === init.mountId)
+                applyTheme(event.data.theme);
+        }
+        else if (isMessage(event.data, 'action-response'))
+            onResponse(event, event.data);
+    });
+    /** Posts one request of `kind` to the host origin and waits for its `action-response`. */
+    async function send(kind, fields) {
+        if (init === undefined)
+            await ready;
+        const { mountId, origin } = init;
+        nextRequest += 1;
+        const requestId = `r${nextRequest}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(requestId);
+                reject(new AdminSurfaceCallError({ code: 'timeout', message: 'The host did not answer in time. Try again.', retryable: true }));
+            }, timeoutMs);
+            pending.set(requestId, { resolve, reject, timer });
+            required.parent.postMessage({ protocol: PROTOCOL, version: VERSION, kind, mountId, requestId, ...fields }, origin);
+        });
+    }
+    /** Asks the host to run one declared action; resolves with its result. */
+    function call(input) {
+        return send('action-request', { action: input.action, payload: input.payload });
+    }
+    /** Asks the host to open `url` outside the sandbox; only https links on the surface's declared
+     * `linkOrigins` open, and the host decides how (new tab, system browser). Rejects with the host's refusal. */
+    async function openLink(input) {
+        await send('open-link', { url: input.url });
+    }
+    /** The bootstrap `data` the host sent with init, or `undefined` once it has expired (or none was sent). */
+    function bootstrap() {
+        const envelope = init?.bootstrap;
+        if (typeof envelope !== 'object' || envelope === null)
+            return undefined;
+        const { expiresAt, data } = envelope;
+        return typeof expiresAt === 'number' && nowMs() < expiresAt ? data : undefined;
+    }
+    /** The host's theme as applied, or `undefined` when the host sent none. */
+    function theme() {
+        return currentTheme;
+    }
+    /** Stops listening and rejects every pending call. */
+    function close() {
+        unsubscribe();
+        stopSize?.();
+        for (const [requestId, waiting] of pending) {
+            clearTimeout(waiting.timer);
+            waiting.reject(new AdminSurfaceCallError({ code: 'closed', message: 'The surface was closed before the host answered.', retryable: false }));
+            pending.delete(requestId);
+        }
+    }
+    return { ready, call, openLink, bootstrap, theme, close };
+}
+//# sourceMappingURL=surface-client.js.map

package/dist/admin-surfaces/surface-handlers.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @file Plugin-supplied server-side handlers for admin surfaces: a surface may name a contained
+ * `.mjs` `handlerModule` that answers its declared actions and may provide its bootstrap data.
+ *
+ * Why it exists: without it a host can only answer a surface's actions with its own code, so a
+ * provider plugin cannot ship a working settings or resource-chooser screen. Why it is safe to run plugin code
+ * here: the module loads only through the lifecycle's one executable loader
+ * (`defineExecutablePluginContribution`: active plugin, shipped digest, on-disk containment), it
+ * receives host capability ports (never a raw secret) through the admin-surface capability session
+ * (`./surface-capabilities.ts`: only the surface's declared connections and config, revoked on disable,
+ * results and errors scanned for tokens the call obtained, the same gate as executable tools), and the
+ * dispatcher still checks the declared input and result schemas around it.
+ * Bootstrap data is the one answer allowed to carry an access token (a surface may need a short-lived
+ * one); it must match the surface's declared `bootstrap` schema and is never cached by the host.
+ */
+import { type LoadedPluginContribution, type PluginContributionDefinition } from '../lifecycle/contribution-loader.js';
+import type { IssuedTokenMemories } from '../lifecycle/tools/capabilities.js';
+import { type AdminSurfaceCapabilities, type AdminSurfaceCapabilitiesPort } from './surface-capabilities.js';
+import { type AdminSurfaceActionHandler } from './action-dispatcher.js';
+import { type AdminSurfaceDescriptor } from './descriptor.js';
+/** Who a call is for. The host route establishes it; plugin and surface ids are rebound to the
+ * loaded module's own before a handler sees them. */
+export interface AdminSurfaceHandlerContext {
+    readonly workspaceId: string;
+    readonly principalId?: string;
+    readonly pluginId: string;
+    readonly surfaceId: string;
+}
+/** Which kind of host is running the surface, so a plugin picks its flow (for example a sign-in in
+ * the system browser on desktop) without inferring it from config. */
+export type AdminSurfaceHostKind = 'hosted' | 'desktop';
+/** The context a handler sees: the route's context plus the plugin's own declared connection ids
+ * (ids, never refs: the host resolves the ref, so a plugin can never name another plugin's connection)
+ * and the host kind the host was built with (never a caller's or the plugin's value). */
+export interface AdminSurfacePluginContext extends AdminSurfaceHandlerContext {
+    readonly connectionIds: readonly string[];
+    readonly hostKind: AdminSurfaceHostKind;
+}
+/** What a bootstrap provider receives. */
+export interface AdminSurfaceBootstrapCall {
+    readonly capabilities: AdminSurfaceCapabilities;
+    readonly context: AdminSurfacePluginContext;
+}
+/** What an action handler receives. `input` already matched the action's declared input schema. */
+export interface AdminSurfaceHandlerCall extends AdminSurfaceBootstrapCall {
+    readonly input: unknown;
+    /** Builds a surface-safe failure to throw: `code` (lowercase hyphenated) and `message` reach the frame. */
+    readonly fail: (required: {
+        readonly code: string;
+        readonly message: string;
+    }, optional?: {
+        readonly retryable?: boolean;
+    }) => Error;
+}
+/** What a handler module's default export must be. */
+export interface AdminSurfaceHandlerModule {
+    /** Keyed by declared action name; a declared action without one answers `action-unavailable`. */
+    readonly actions: Readonly<Record<string, (required: AdminSurfaceHandlerCall, optional?: Record<string, never>) => unknown>>;
+    /** Data the surface starts with; requires a `bootstrap` schema on the surface. */
+    readonly bootstrap?: (required: AdminSurfaceBootstrapCall, optional?: Record<string, never>) => unknown;
+}
+type HandledSurface = AdminSurfaceDescriptor & {
+    readonly handlerModule: string;
+};
+export type LoadedAdminSurfaceHandlers = LoadedPluginContribution<HandledSurface, AdminSurfaceHandlerModule>;
+export declare const ADMIN_SURFACE_PLUGIN_DISABLED_MESSAGE = "This plugin was disabled, so its admin surface cannot act. Re-enable the plugin and reopen the surface.";
+/**
+ * The executable contribution for the host's surfaces file (the same file `defineAdminSurfaceContribution`
+ * reads): one item per surface that names a `handlerModule`.
+ * @param required.filename - The host-named surfaces file at the plugin root.
+ * @complexity O(1); each load parses the file and performs one contained import per handled surface.
+ */
+export declare function defineAdminSurfaceHandlerContribution(required: {
+    readonly filename: string;
+}, _optional?: Record<string, never>): PluginContributionDefinition<HandledSurface, LoadedAdminSurfaceHandlers>;
+/**
+ * Holds the admitted handler modules and answers for them. Call `sync` with every load of
+ * `defineAdminSurfaceHandlerContribution` (on boot and on every activation change); a surface missing
+ * from a load loses its handlers, and capabilities its module kept are revoked.
+ * @param required.capabilities - Host port building one call's admin-surface capabilities.
+ * @param required.issuedTokens - Per-plugin token memory shared with the plugin's tool projection.
+ * @param required.hostKind - The kind of host this process is; every handler and bootstrap call sees it.
+ * @throws TypeError when `hostKind` is neither `hosted` nor `desktop`.
+ * @returns `sync`, plus `handlersFor` and `bootstrapData` for the host's action dispatcher and bootstrap route.
+ * @complexity sync is O(s + a) surfaces and actions; lookups are O(1).
+ */
+export declare function createAdminSurfaceHandlerHost(required: {
+    readonly capabilities: AdminSurfaceCapabilitiesPort;
+    readonly issuedTokens: IssuedTokenMemories;
+    readonly hostKind: AdminSurfaceHostKind;
+}, _optional?: Record<string, never>): {
+    /** Admits one load result. @returns The loader's refusals plus this seam's own, in order. */
+    sync(input: {
+        readonly loaded: readonly LoadedAdminSurfaceHandlers[];
+        readonly refusals: readonly string[];
+    }, _options?: Record<string, never>): {
+        readonly refusals: readonly string[];
+    };
+    /** The plugin's handlers for one surface (empty when none are admitted), for `createAdminSurfaceActionDispatcher`. */
+    handlersFor(input: {
+        readonly pluginId: string;
+        readonly surfaceId: string;
+    }, _options?: Record<string, never>): Readonly<Record<string, AdminSurfaceActionHandler<AdminSurfaceHandlerContext>>>;
+    /** The plugin's bootstrap data for `context`'s surface, or null when it provides none.
+     * @throws Error when the data does not match the declared schema (the message names a path, never a value). */
+    bootstrapData(input: {
+        readonly context: AdminSurfaceHandlerContext;
+    }, _options?: Record<string, never>): Promise<unknown>;
+};
+export {};
+//# sourceMappingURL=surface-handlers.d.ts.map

package/dist/admin-surfaces/surface-handlers.js

@@ -0,0 +1,172 @@
+/**
+ * @file Plugin-supplied server-side handlers for admin surfaces: a surface may name a contained
+ * `.mjs` `handlerModule` that answers its declared actions and may provide its bootstrap data.
+ *
+ * Why it exists: without it a host can only answer a surface's actions with its own code, so a
+ * provider plugin cannot ship a working settings or resource-chooser screen. Why it is safe to run plugin code
+ * here: the module loads only through the lifecycle's one executable loader
+ * (`defineExecutablePluginContribution`: active plugin, shipped digest, on-disk containment), it
+ * receives host capability ports (never a raw secret) through the admin-surface capability session
+ * (`./surface-capabilities.ts`: only the surface's declared connections and config, revoked on disable,
+ * results and errors scanned for tokens the call obtained, the same gate as executable tools), and the
+ * dispatcher still checks the declared input and result schemas around it.
+ * Bootstrap data is the one answer allowed to carry an access token (a surface may need a short-lived
+ * one); it must match the surface's declared `bootstrap` schema and is never cached by the host.
+ */
+import { defineExecutablePluginContribution } from '../lifecycle/contribution-loader.js';
+import { openAdminSurfaceCapabilitySession } from './surface-capabilities.js';
+import { AdminSurfaceActionError } from './action-dispatcher.js';
+import { validateAdminSurfaceActionValue } from './action-schema.js';
+import { parseAdminSurfacesFile } from './descriptor.js';
+const HOST_KINDS = ['hosted', 'desktop'];
+export const ADMIN_SURFACE_PLUGIN_DISABLED_MESSAGE = 'This plugin was disabled, so its admin surface cannot act. Re-enable the plugin and reopen the surface.';
+const FAILURE_CODE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_FAILURE_CODE_LENGTH = 64;
+const MAX_FAILURE_MESSAGE_LENGTH = 300;
+const isFunction = (value) => typeof value === 'function';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The module's export as a handler module, or why not. Shape only; declarations are checked at sync. @complexity O(a) exported actions. */
+function validateHandlerModule({ exported }) {
+    if (!isRecord(exported))
+        return "its module's default export is not an object";
+    if (!isRecord(exported.actions) || !Object.values(exported.actions).every(isFunction))
+        return "its module's default export needs an actions object of functions";
+    if (exported.bootstrap !== undefined && !isFunction(exported.bootstrap))
+        return 'bootstrap must be a function';
+    return exported;
+}
+/**
+ * The executable contribution for the host's surfaces file (the same file `defineAdminSurfaceContribution`
+ * reads): one item per surface that names a `handlerModule`.
+ * @param required.filename - The host-named surfaces file at the plugin root.
+ * @complexity O(1); each load parses the file and performs one contained import per handled surface.
+ */
+export function defineAdminSurfaceHandlerContribution(required, _optional = {}) {
+    return defineExecutablePluginContribution({
+        filename: required.filename, contribution: 'admin surface handlers',
+        parse: ({ raw }) => {
+            const parsed = parseAdminSurfacesFile({ raw });
+            return parsed.ok ? { ok: true, descriptors: parsed.descriptors.filter((descriptor) => descriptor.handlerModule !== undefined) } : parsed;
+        },
+        modulePath: ({ descriptor }) => descriptor.handlerModule, validate: validateHandlerModule,
+        refusal: ({ plugin, descriptor, reason }) => `admin surface handlers for '${descriptor.id}' from '${plugin.pluginId}' were not loaded: ${reason}`,
+    });
+}
+/** A surface-safe failure, or a generic one when the plugin's code is not a valid id. @complexity O(1). */
+function fail(required, optional = {}) {
+    const { code, message } = required;
+    if (typeof code !== 'string' || code.length > MAX_FAILURE_CODE_LENGTH || !FAILURE_CODE_PATTERN.test(code))
+        return new Error('a plugin failure used an invalid code');
+    return new AdminSurfaceActionError({ code, message: String(message).slice(0, MAX_FAILURE_MESSAGE_LENGTH) }, { retryable: optional.retryable === true });
+}
+/** Why a loaded module cannot answer for its surface, or null. @complexity O(a) exported actions. */
+function admissionRefusal({ descriptor, module }) {
+    const undeclared = Object.keys(module.actions).find((name) => !descriptor.actions.some((action) => action.name === name));
+    if (undeclared !== undefined)
+        return `it exports a handler for undeclared action '${undeclared.slice(0, 64)}'`;
+    return module.bootstrap !== undefined && descriptor.bootstrap === undefined ? 'it exports bootstrap() but the surface declares no bootstrap schema' : null;
+}
+/** Plugin and surface ids cannot contain NUL, so the key is unambiguous. */
+const keyOf = (pluginId, surfaceId) => `${pluginId}\u0000${surfaceId}`;
+/**
+ * Holds the admitted handler modules and answers for them. Call `sync` with every load of
+ * `defineAdminSurfaceHandlerContribution` (on boot and on every activation change); a surface missing
+ * from a load loses its handlers, and capabilities its module kept are revoked.
+ * @param required.capabilities - Host port building one call's admin-surface capabilities.
+ * @param required.issuedTokens - Per-plugin token memory shared with the plugin's tool projection.
+ * @param required.hostKind - The kind of host this process is; every handler and bootstrap call sees it.
+ * @throws TypeError when `hostKind` is neither `hosted` nor `desktop`.
+ * @returns `sync`, plus `handlersFor` and `bootstrapData` for the host's action dispatcher and bootstrap route.
+ * @complexity sync is O(s + a) surfaces and actions; lookups are O(1).
+ */
+export function createAdminSurfaceHandlerHost(required, _optional = {}) {
+    // Checked at run time too: a JavaScript host may pass an unchecked config value, and a plugin would pick its flow from it.
+    if (!HOST_KINDS.includes(required.hostKind))
+        throw new TypeError("createAdminSurfaceHandlerHost: hostKind must be 'hosted' or 'desktop'.");
+    const { hostKind } = required;
+    let admitted = new Map();
+    /** One call's capability session, scoped to the loaded plugin and the route's workspace/principal. */
+    function sessionFor(self, context) {
+        const { pluginId, descriptor } = self.loaded;
+        const principal = context.principalId === undefined ? {} : { principalId: context.principalId };
+        const capabilities = required.capabilities({ pluginId, workspaceId: context.workspaceId, ...principal });
+        const session = openAdminSurfaceCapabilitySession({ capabilities, isLive: self.isLive, declared: descriptor, issued: self.issued }, { ...(principal.principalId !== undefined && { actorId: principal.principalId }) });
+        const connectionIds = (descriptor.connections ?? []).map((connection) => connection.id);
+        return { session, context: { workspaceId: context.workspaceId, ...principal, pluginId, surfaceId: descriptor.id, connectionIds, hostKind } };
+    }
+    function actionHandler(self, run) {
+        return async ({ payload, context: caller }) => {
+            if (!self.isLive())
+                throw new AdminSurfaceActionError({ code: 'plugin-disabled', message: ADMIN_SURFACE_PLUGIN_DISABLED_MESSAGE });
+            const { session, context } = sessionFor(self, caller);
+            try {
+                return session.release({ value: await run({ input: payload, capabilities: session.capabilities, context, fail }) });
+            }
+            catch (error) {
+                throw session.sanitize({ error });
+            }
+        };
+    }
+    /** A generation for one surface; live only while `admitted` holds this exact object. */
+    function admit(key, loaded) {
+        const declared = loaded.descriptor.actions.filter((action) => Object.hasOwn(loaded.module.actions, action.name));
+        const self = { loaded, handlers: {}, isLive: () => admitted.get(key) === self, issued: required.issuedTokens.forPlugin({ pluginId: loaded.pluginId }) };
+        Object.assign(self.handlers, Object.fromEntries(declared.map((action) => [action.name, actionHandler(self, loaded.module.actions[action.name])])));
+        return Object.freeze(self);
+    }
+    /** The previous generation when module and declaration are unchanged, so re-syncing never revokes it. */
+    function unchanged(previous, loaded) {
+        const same = previous !== undefined && previous.loaded.module === loaded.module && JSON.stringify(previous.loaded.descriptor) === JSON.stringify(loaded.descriptor);
+        return same ? previous : undefined;
+    }
+    return {
+        /** Admits one load result. @returns The loader's refusals plus this seam's own, in order. */
+        sync(input, _options = {}) {
+            const refusals = [...input.refusals];
+            const claims = new Map();
+            for (const entry of input.loaded)
+                claims.set(keyOf(entry.pluginId, entry.descriptor.id), (claims.get(keyOf(entry.pluginId, entry.descriptor.id)) ?? 0) + 1);
+            const next = new Map();
+            const previous = admitted;
+            for (const entry of input.loaded) {
+                const key = keyOf(entry.pluginId, entry.descriptor.id);
+                const reason = claims.get(key) > 1 ? 'more than one handler module claims this surface' : admissionRefusal(entry);
+                const line = `admin surface handlers for '${entry.descriptor.id}' from '${entry.pluginId}' were not loaded: ${reason}`;
+                if (reason !== null) {
+                    if (!refusals.includes(line))
+                        refusals.push(line);
+                    continue;
+                }
+                next.set(key, unchanged(previous.get(key), entry) ?? admit(key, entry));
+            }
+            admitted = next;
+            return { refusals };
+        },
+        /** The plugin's handlers for one surface (empty when none are admitted), for `createAdminSurfaceActionDispatcher`. */
+        handlersFor(input, _options = {}) {
+            return admitted.get(keyOf(input.pluginId, input.surfaceId))?.handlers ?? {};
+        },
+        /** The plugin's bootstrap data for `context`'s surface, or null when it provides none.
+         * @throws Error when the data does not match the declared schema (the message names a path, never a value). */
+        async bootstrapData(input, _options = {}) {
+            const self = admitted.get(keyOf(input.context.pluginId, input.context.surfaceId));
+            const provide = self?.loaded.module.bootstrap;
+            if (self === undefined || provide === undefined)
+                return null;
+            const { session, context } = sessionFor(self, input.context);
+            let data;
+            try {
+                data = await provide({ capabilities: session.capabilities, context });
+            }
+            catch (error) {
+                throw session.sanitize({ error });
+            }
+            // Admission guarantees a schema whenever the module provides bootstrap data.
+            const violation = validateAdminSurfaceActionValue({ schema: self.loaded.descriptor.bootstrap, value: data });
+            if (violation !== null)
+                throw new Error(`Admin surface '${context.surfaceId}' from '${context.pluginId}' returned bootstrap data outside its declared schema (${violation}); report it to the plugin author.`);
+            return data;
+        },
+    };
+}
+//# sourceMappingURL=surface-handlers.js.map

package/dist/admin-surfaces/theme.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @file The host's design tokens for plugin surfaces: which `--jini-*` custom properties a host
+ * shares with every surface frame, how it reads their current values, and the envelope that sends
+ * a change after init.
+ *
+ * Why: a surface is a sandboxed frame without `allow-same-origin`, so it cannot see the admin's
+ * stylesheets, and its CSP allows only its own files. Values posted in a message are the only way
+ * its screens can match the admin and follow a light/dark or admin-theme change. The surface client
+ * applies them as custom properties on its root (CSSOM, which the CSP allows; never a style
+ * attribute or a stylesheet), so a surface writes `var(--jini-primary, <fallback>)` and looks right
+ * with or without a host that sends tokens.
+ *
+ * Values are text a host computed from its own CSS; anything that could fetch (`url(`, `image-set(`)
+ * or leave a declaration (`;`, braces) is dropped here and again in the surface client.
+ */
+import { ADMIN_SURFACE_PROTOCOL, ADMIN_SURFACE_PROTOCOL_VERSION } from './protocol.js';
+/** The shared vocabulary: colours, type, radius, spacing, depth and focus. A host may send fewer. */
+export declare const ADMIN_SURFACE_THEME_TOKENS: readonly ["--jini-bg", "--jini-surface", "--jini-bg-subtle", "--jini-text", "--jini-text-muted", "--jini-border", "--jini-border-strong", "--jini-primary", "--jini-primary-ink", "--jini-link", "--jini-danger", "--jini-danger-bg", "--jini-success", "--jini-success-bg", "--jini-warning", "--jini-warning-bg", "--jini-font-ui", "--jini-font-mono", "--jini-font-size-xs", "--jini-font-size-sm", "--jini-font-size-base", "--jini-font-size-md", "--jini-radius-sm", "--jini-radius", "--jini-radius-md", "--jini-radius-pill", "--jini-space-1", "--jini-space-2", "--jini-space-3", "--jini-space-4", "--jini-shadow-xs", "--jini-shadow-sm", "--jini-control-bg", "--jini-control-border", "--jini-control-shadow-focus", "--jini-overlay-tooltip-bg", "--jini-overlay-tooltip-text", "--jini-overlay-tooltip-border"];
+export type AdminSurfaceThemeToken = (typeof ADMIN_SURFACE_THEME_TOKENS)[number];
+export type AdminSurfaceColorScheme = 'light' | 'dark';
+/** What a surface receives: the scheme for native controls plus the token values. */
+export interface AdminSurfaceTheme {
+    readonly scheme: AdminSurfaceColorScheme;
+    readonly tokens: Readonly<Partial<Record<AdminSurfaceThemeToken, string>>>;
+}
+/** Host page -> surface after init, whenever the admin's theme or colour scheme changes. */
+export interface AdminSurfaceThemeMessage {
+    readonly protocol: typeof ADMIN_SURFACE_PROTOCOL;
+    readonly version: typeof ADMIN_SURFACE_PROTOCOL_VERSION;
+    readonly kind: 'theme';
+    readonly mountId: string;
+    readonly theme: AdminSurfaceTheme;
+}
+/** Whether `value` is plain declaration text that cannot fetch anything or end its declaration.
+ * @complexity O(n) in the value length. */
+export declare function isSafeAdminSurfaceThemeValue(value: unknown): value is string;
+/**
+ * Reads the shared tokens from the host's computed style.
+ * @param required.style - Usually `getComputedStyle(element)` for the element the admin theme is on.
+ * @param optional.sources - Where to read a token when the host draws with its own name for it
+ *   (e.g. `{ '--jini-text': '--fg' }`); unnamed tokens are read under their own name.
+ * @returns Only the tokens with a safe, non-empty value.
+ * @complexity O(t) tokens.
+ */
+export declare function readAdminSurfaceTheme(required: {
+    readonly style: {
+        getPropertyValue(name: string): string;
+    };
+    readonly scheme: AdminSurfaceColorScheme;
+}, optional?: {
+    readonly sources?: Readonly<Partial<Record<AdminSurfaceThemeToken, string>>>;
+}): AdminSurfaceTheme;
+/** Builds the envelope that sends a changed theme to one mount's frame.
+ * @complexity O(1). */
+export declare function adminSurfaceThemeMessage(required: {
+    readonly mountId: string;
+    readonly theme: AdminSurfaceTheme;
+}, _optional?: Record<string, never>): AdminSurfaceThemeMessage;
+//# sourceMappingURL=theme.d.ts.map

package/dist/admin-surfaces/theme.js

@@ -0,0 +1,57 @@
+/**
+ * @file The host's design tokens for plugin surfaces: which `--jini-*` custom properties a host
+ * shares with every surface frame, how it reads their current values, and the envelope that sends
+ * a change after init.
+ *
+ * Why: a surface is a sandboxed frame without `allow-same-origin`, so it cannot see the admin's
+ * stylesheets, and its CSP allows only its own files. Values posted in a message are the only way
+ * its screens can match the admin and follow a light/dark or admin-theme change. The surface client
+ * applies them as custom properties on its root (CSSOM, which the CSP allows; never a style
+ * attribute or a stylesheet), so a surface writes `var(--jini-primary, <fallback>)` and looks right
+ * with or without a host that sends tokens.
+ *
+ * Values are text a host computed from its own CSS; anything that could fetch (`url(`, `image-set(`)
+ * or leave a declaration (`;`, braces) is dropped here and again in the surface client.
+ */
+import { ADMIN_SURFACE_PROTOCOL, ADMIN_SURFACE_PROTOCOL_VERSION } from './protocol.js';
+/** The shared vocabulary: colours, type, radius, spacing, depth and focus. A host may send fewer. */
+export const ADMIN_SURFACE_THEME_TOKENS = Object.freeze([
+    '--jini-bg', '--jini-surface', '--jini-bg-subtle', '--jini-text', '--jini-text-muted',
+    '--jini-border', '--jini-border-strong', '--jini-primary', '--jini-primary-ink', '--jini-link',
+    '--jini-danger', '--jini-danger-bg', '--jini-success', '--jini-success-bg', '--jini-warning', '--jini-warning-bg',
+    '--jini-font-ui', '--jini-font-mono', '--jini-font-size-xs', '--jini-font-size-sm', '--jini-font-size-base', '--jini-font-size-md',
+    '--jini-radius-sm', '--jini-radius', '--jini-radius-md', '--jini-radius-pill',
+    '--jini-space-1', '--jini-space-2', '--jini-space-3', '--jini-space-4',
+    '--jini-shadow-xs', '--jini-shadow-sm', '--jini-control-bg', '--jini-control-border', '--jini-control-shadow-focus',
+    '--jini-overlay-tooltip-bg', '--jini-overlay-tooltip-text', '--jini-overlay-tooltip-border',
+]);
+const MAX_VALUE_LENGTH = 200;
+const UNSAFE_VALUE = /url\(|image\(|image-set\(|[;{}<>\\@]/i;
+/** Whether `value` is plain declaration text that cannot fetch anything or end its declaration.
+ * @complexity O(n) in the value length. */
+export function isSafeAdminSurfaceThemeValue(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= MAX_VALUE_LENGTH && !UNSAFE_VALUE.test(value);
+}
+/**
+ * Reads the shared tokens from the host's computed style.
+ * @param required.style - Usually `getComputedStyle(element)` for the element the admin theme is on.
+ * @param optional.sources - Where to read a token when the host draws with its own name for it
+ *   (e.g. `{ '--jini-text': '--fg' }`); unnamed tokens are read under their own name.
+ * @returns Only the tokens with a safe, non-empty value.
+ * @complexity O(t) tokens.
+ */
+export function readAdminSurfaceTheme(required, optional = {}) {
+    const tokens = {};
+    for (const token of ADMIN_SURFACE_THEME_TOKENS) {
+        const value = required.style.getPropertyValue(optional.sources?.[token] ?? token).trim();
+        if (isSafeAdminSurfaceThemeValue(value))
+            tokens[token] = value;
+    }
+    return { scheme: required.scheme, tokens };
+}
+/** Builds the envelope that sends a changed theme to one mount's frame.
+ * @complexity O(1). */
+export function adminSurfaceThemeMessage(required, _optional = {}) {
+    return { protocol: ADMIN_SURFACE_PROTOCOL, version: ADMIN_SURFACE_PROTOCOL_VERSION, kind: 'theme', mountId: required.mountId, theme: required.theme };
+}
+//# sourceMappingURL=theme.js.map