@jini-ai/admin 0.3.10 → 0.4.0

package/dist/react/shell/AdminShell.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useMemo } from 'react';
+import { Sidebar } from '../components/Sidebar.js';
+import { useShellDrawer, useShellRoute } from './AdminShell.hooks.js';
+import { resolveAdminShellModel } from './model.js';
+import { useAdminShellSession } from './use-admin-shell-session.js';
+import { useAdminTheme } from './use-admin-theme.js';
+/**
+ * A host-composed admin layout with manifest navigation and a session gate.
+ * @param props Required host scope, ports, contributions, labels and slots; optional layout settings.
+ * @returns Loading/login/error UI or the authenticated sidebar, feature screen and pane slots.
+ */
+export function AdminShell(props) {
+    const context = useMemo(() => ({ apiBase: props.apiBase, workspace: props.workspace }), [props.apiBase, props.workspace]);
+    const session = useAdminShellSession({ port: props.session, context });
+    const appearance = useAdminTheme({ userId: session.state.status === 'authenticated' ? session.state.session.user.id : null, workspace: context.workspace }, {
+        ...(props.theme ? { theme: props.theme } : {}),
+        ...(props.colorScheme ? { colorScheme: props.colorScheme } : {}),
+        ...(props.themeEnvironment ? { environment: props.themeEnvironment } : {}),
+        ...(props.themePreferenceStore ? { preferenceStore: props.themePreferenceStore } : {}),
+        ...(props.onColorSchemeChange ? { onColorSchemeChange: props.onColorSchemeChange } : {}),
+    });
+    const routePath = useShellRoute({ navigation: props.navigation, base: props.adminBase });
+    const drawer = useShellDrawer({ routePath });
+    const id = useId();
+    const sidebarId = `${id}-sidebar`;
+    const mainId = `${id}-main`;
+    if (session.state.status === 'checking')
+        return _jsx("div", { className: "boot-screen", role: "status", children: props.labels.loading });
+    if (session.state.status === 'anonymous')
+        return props.slots.login({ context, refreshSession: session.refresh });
+    if (session.state.status === 'error') {
+        if (props.slots.sessionError)
+            return props.slots.sessionError({ error: session.state.error, retry: session.refresh });
+        return _jsxs("div", { role: "alert", children: [_jsx("p", { children: props.labels.sessionError }), _jsx("button", { type: "button", onClick: () => { void session.refresh(); }, children: props.labels.retry })] });
+    }
+    const model = resolveAdminShellModel({ panels: props.panels, session: session.state.session, routePath, defaultPanelId: props.defaultPanelId }, { capabilities: props.capabilities ?? [] });
+    const slotArgs = {
+        context, session: session.state.session, route: model.route, logout: session.logout, refreshSession: session.refresh,
+        ...(appearance ? { appearance } : {}),
+    };
+    const nav = props.translateNav ? props.translateNav({ groups: model.nav }) : model.nav;
+    const assistant = props.slots.assistant;
+    return (_jsxs("div", { className: ['admin-layout', props.className].filter(Boolean).join(' '), children: [_jsx("a", { href: `#${mainId}`, className: "skip-link", children: props.labels.skipToContent }), _jsxs(Sidebar, { activeId: model.route.panelId ?? '', base: props.adminBase, open: drawer.open, id: sidebarId, label: props.labels.navigation, railStorageKey: props.railStorageKey, railDefaultCollapsed: props.railDefaultCollapsed ?? false, children: [props.slots.sidebarHeader, _jsx(Sidebar.Nav, { groups: nav, soonLabel: props.labels.soon, collapsibleGroups: props.collapsibleGroups ?? [] }), _jsxs(Sidebar.Footer, { children: [_jsx(Sidebar.RailToggle, { expandLabel: props.labels.expandSidebar, collapseLabel: props.labels.collapseSidebar }), props.slots.sidebarFooter?.(slotArgs)] })] }), drawer.open && _jsx("button", { type: "button", className: "sidebar-backdrop", "aria-label": props.labels.closeNavigation, onClick: () => drawer.setOpen(false) }), _jsxs("div", { className: "admin-main-col", children: [_jsxs("div", { className: "admin-topbar", children: [_jsx("button", { type: "button", className: "admin-topbar-toggle", "aria-expanded": drawer.open, "aria-controls": sidebarId, "aria-label": drawer.open ? props.labels.closeNavigation : props.labels.openNavigation, onClick: () => drawer.setOpen((open) => !open), children: _jsx("svg", { viewBox: "0 0 18 18", fill: "none", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: _jsx("path", { d: "M2.5 5h13M2.5 9h13M2.5 13h13" }) }) }), _jsx("span", { className: "admin-topbar-title", children: props.title }), props.slots.topbar] }), _jsx("main", { ref: props.mainRef, id: mainId, className: "admin-content", tabIndex: -1, "data-agent-page": model.agentPageId ?? undefined, children: model.panel?.render(slotArgs) })] }), assistant && _jsx("aside", { className: "admin-assistant-pane", "aria-label": assistant.label, hidden: !assistant.open, children: assistant.content }), props.slots.overlays?.(slotArgs)] }));
+}
+//# sourceMappingURL=AdminShell.js.map

package/dist/react/shell/index.d.ts

@@ -0,0 +1,7 @@
+export { AdminShell } from './AdminShell.js';
+export { resolveAdminShellModel, type AdminShellModel } from './model.js';
+export { useAdminShellSession } from './use-admin-shell-session.js';
+export type { AdminShellContext, AdminShellLabels, AdminShellNavigationPort, AdminShellPanel, AdminShellProps, AdminShellRenderArgs, AdminShellSession, AdminShellSessionController, AdminShellSessionPort, AdminShellSessionState, AdminShellSlotArgs, AdminShellSlots, } from './types.js';
+export type { AdminThemePreferenceStorePort, AdminThemeEnvironment, AdminShellAppearance } from './theme-ports.js';
+export { useAdminTheme } from './use-admin-theme.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/shell/index.js

@@ -0,0 +1,5 @@
+export { AdminShell } from './AdminShell.js';
+export { resolveAdminShellModel } from './model.js';
+export { useAdminShellSession } from './use-admin-shell-session.js';
+export { useAdminTheme } from './use-admin-theme.js';
+//# sourceMappingURL=index.js.map

package/dist/react/shell/model.d.ts

@@ -0,0 +1,25 @@
+import { type AdminNavGroup } from '../../core/manifest/rules.js';
+import type { AdminRoute } from '../../core/routing/types.js';
+import type { AdminShellPanel, AdminShellSession } from './types.js';
+export interface AdminShellModel {
+    readonly panels: readonly AdminShellPanel[];
+    readonly panel: AdminShellPanel | undefined;
+    readonly route: AdminRoute;
+    readonly nav: readonly AdminNavGroup[];
+    readonly agentPageId: string | null;
+}
+/**
+ * Derive navigation and render dispatch from one resolved manifest.
+ * @param args Required host manifest, session, route and fallback panel.
+ * @param options Optional wired capability keys.
+ * @returns A matched route or a clean default index route. Never mutates contributions.
+ */
+export declare function resolveAdminShellModel(args: {
+    readonly panels: readonly AdminShellPanel[];
+    readonly session: AdminShellSession;
+    readonly routePath: string;
+    readonly defaultPanelId: string;
+}, options?: {
+    readonly capabilities?: readonly string[];
+}): AdminShellModel;
+//# sourceMappingURL=model.d.ts.map

package/dist/react/shell/model.js

@@ -0,0 +1,29 @@
+import { buildNav, resolveAgentPageId, resolvePanels } from '../../core/manifest/rules.js';
+import { matchRoute } from '../../core/routing/rules.js';
+/**
+ * Derive navigation and render dispatch from one resolved manifest.
+ * @param args Required host manifest, session, route and fallback panel.
+ * @param options Optional wired capability keys.
+ * @returns A matched route or a clean default index route. Never mutates contributions.
+ */
+export function resolveAdminShellModel(args, options = {}) {
+    const panels = resolvePanels({ panels: args.panels }, {
+        capabilities: options.capabilities ?? [],
+        permissions: args.session.effectivePermissions ?? [],
+    });
+    const matched = matchRoute({ routePath: args.routePath, panels });
+    const rawPath = args.routePath.split('?')[0] ?? '';
+    const isRoot = rawPath.split('/').filter(Boolean).length === 0;
+    // The existing matcher maps root to dashboard. The shell's default is host-owned.
+    const route = isRoot || matched.panelId === null
+        ? { panelId: args.defaultPanelId, view: null, params: {}, query: matched.query }
+        : matched;
+    return {
+        panels,
+        panel: panels.find((panel) => panel.id === route.panelId),
+        route,
+        nav: buildNav({ panels }, { defaultPanelId: args.defaultPanelId }),
+        agentPageId: resolveAgentPageId({ panels, panelId: route.panelId, view: route.view }),
+    };
+}
+//# sourceMappingURL=model.js.map

package/dist/react/shell/theme-ports.d.ts

@@ -0,0 +1,28 @@
+import type { AdminThemeDocument, AdminThemeTarget, ColorScheme, ColorSchemePreference, MatchMediaPort } from '@jini-ai/ui/theme';
+/** The host chooses storage and keys. Preferences are always scoped to a user and workspace. */
+export interface AdminThemePreferenceStorePort {
+    read(args: {
+        readonly userId: string;
+        readonly workspace: Readonly<Record<string, string>>;
+    }): ColorSchemePreference | null;
+    write(args: {
+        readonly userId: string;
+        readonly workspace: Readonly<Record<string, string>>;
+        readonly preference: ColorSchemePreference;
+    }): void;
+}
+/** Inject the same scope for the theme and color scheme; use the document root for portals. */
+export interface AdminThemeEnvironment {
+    readonly target: AdminThemeTarget;
+    readonly document: AdminThemeDocument;
+    readonly matchMedia: MatchMediaPort;
+}
+/** Exposed to slots so the host supplies its own light/dark/system picker and labels. */
+export interface AdminShellAppearance {
+    readonly preference: ColorSchemePreference;
+    readonly resolved: ColorScheme;
+    setPreference(args: {
+        readonly preference: ColorSchemePreference;
+    }): void;
+}
+//# sourceMappingURL=theme-ports.d.ts.map

package/dist/react/shell/theme-ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=theme-ports.js.map

package/dist/react/shell/types.d.ts

@@ -0,0 +1,99 @@
+import type { ReactNode, Ref } from 'react';
+import type { AdminTheme, ColorSchemePreference } from '@jini-ai/ui/theme';
+import type { AdminShellAppearance, AdminThemeEnvironment, AdminThemePreferenceStorePort } from './theme-ports.js';
+import type { AdminPanel } from '../../core/manifest/types.js';
+import type { AdminNavGroup } from '../../core/manifest/rules.js';
+import type { AdminRoute } from '../../core/routing/types.js';
+import type { AdminShellContext, AdminShellNavigationPort, AdminShellSession, AdminShellSessionPort } from '../../core/ports/shell.js';
+export type { AdminShellContext, AdminShellNavigationPort, AdminShellSession, AdminShellSessionPort } from '../../core/ports/shell.js';
+export interface AdminShellRenderArgs {
+    readonly context: AdminShellContext;
+    readonly session: AdminShellSession;
+    readonly route: AdminRoute;
+}
+/** A feature contribution uses the existing manifest, with a React renderer taking one object. */
+export type AdminShellPanel = AdminPanel<(args: AdminShellRenderArgs) => ReactNode>;
+export type AdminShellSessionState = {
+    readonly status: 'checking';
+} | {
+    readonly status: 'anonymous';
+} | {
+    readonly status: 'authenticated';
+    readonly session: AdminShellSession;
+} | {
+    readonly status: 'error';
+    readonly error: unknown;
+};
+export interface AdminShellSessionController {
+    readonly state: AdminShellSessionState;
+    /** Re-read after the host's login UI finishes; also refreshes effective permissions. */
+    readonly refresh: () => Promise<void>;
+    readonly logout: () => Promise<void>;
+}
+export interface AdminShellSlotArgs extends AdminShellRenderArgs {
+    readonly appearance?: AdminShellAppearance;
+    readonly logout: () => Promise<void>;
+    readonly refreshSession: () => Promise<void>;
+}
+export interface AdminShellSlots {
+    readonly login: (args: {
+        readonly context: AdminShellContext;
+        readonly refreshSession: () => Promise<void>;
+    }) => ReactNode;
+    readonly sessionError?: (args: {
+        readonly error: unknown;
+        readonly retry: () => Promise<void>;
+    }) => ReactNode;
+    readonly sidebarHeader?: ReactNode;
+    readonly sidebarFooter?: (args: AdminShellSlotArgs) => ReactNode;
+    readonly topbar?: ReactNode;
+    readonly overlays?: (args: AdminShellSlotArgs) => ReactNode;
+    /** Always mounted while authenticated; hidden when closed. The host owns pane controls. */
+    readonly assistant?: {
+        readonly content: ReactNode;
+        readonly label: string;
+        readonly open: boolean;
+    };
+}
+/** Required host copy, so branding and language never fall back to another product's values. */
+export interface AdminShellLabels {
+    readonly navigation: string;
+    readonly openNavigation: string;
+    readonly closeNavigation: string;
+    readonly skipToContent: string;
+    readonly loading: string;
+    readonly sessionError: string;
+    readonly retry: string;
+    readonly expandSidebar: string;
+    readonly collapseSidebar: string;
+    readonly soon: string;
+}
+export interface AdminShellProps extends AdminShellContext {
+    readonly theme?: AdminTheme;
+    /** Controlled when supplied; otherwise the injected store restores the user's choice. */
+    readonly colorScheme?: ColorSchemePreference;
+    readonly themeEnvironment?: AdminThemeEnvironment;
+    readonly themePreferenceStore?: AdminThemePreferenceStorePort;
+    readonly onColorSchemeChange?: (args: {
+        readonly preference: ColorSchemePreference;
+    }) => void;
+    readonly adminBase: string;
+    readonly defaultPanelId: string;
+    readonly railStorageKey: string;
+    readonly title: ReactNode;
+    readonly session: AdminShellSessionPort;
+    readonly navigation: AdminShellNavigationPort;
+    readonly panels: readonly AdminShellPanel[];
+    readonly slots: AdminShellSlots;
+    readonly labels: AdminShellLabels;
+    readonly capabilities?: readonly string[];
+    readonly railDefaultCollapsed?: boolean;
+    readonly collapsibleGroups?: readonly string[];
+    readonly translateNav?: (args: {
+        readonly groups: readonly AdminNavGroup[];
+    }) => readonly AdminNavGroup[];
+    /** Optional page-driver/measurement seam; the host owns any agent or screenshot integration. */
+    readonly mainRef?: Ref<HTMLElement>;
+    readonly className?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/react/shell/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/react/shell/use-admin-shell-session.d.ts

@@ -0,0 +1,13 @@
+import type { AdminShellContext, AdminShellSessionController, AdminShellSessionPort } from './types.js';
+interface Owner {
+    readonly context: AdminShellContext;
+    readonly port: AdminShellSessionPort;
+}
+/**
+ * Own session reads and invalidation without any host API imports.
+ * @param args Stable context and session port. Changing either starts a new session check.
+ * @returns Gate state plus refresh/logout actions; adapter failures become an error state.
+ */
+export declare function useAdminShellSession(args: Owner): AdminShellSessionController;
+export {};
+//# sourceMappingURL=use-admin-shell-session.d.ts.map

package/dist/react/shell/use-admin-shell-session.js

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * Own session reads and invalidation without any host API imports.
+ * @param args Stable context and session port. Changing either starts a new session check.
+ * @returns Gate state plus refresh/logout actions; adapter failures become an error state.
+ */
+export function useAdminShellSession(args) {
+    const { context, port } = args;
+    const active = useRef(null);
+    const loggingOut = useRef(null);
+    const generation = useRef(0);
+    const [owned, setOwned] = useState({ context, port, state: { status: 'checking' } });
+    const run = useCallback(async (operation) => {
+        const owner = active.current;
+        if (!owner || owner.context !== context || owner.port !== port)
+            return;
+        // A refresh must not race a pending logout and restore a soon-to-be-revoked principal.
+        if (loggingOut.current === owner)
+            return;
+        if (operation === 'logout')
+            loggingOut.current = owner;
+        const request = ++generation.current;
+        const isCurrent = () => active.current === owner && generation.current === request;
+        setOwned({ context, port, state: { status: 'checking' } });
+        try {
+            if (operation === 'logout') {
+                await port.logout(context);
+                if (isCurrent())
+                    setOwned({ context, port, state: { status: 'anonymous' } });
+                return;
+            }
+            const session = await port.read(context);
+            if (!isCurrent())
+                return;
+            const state = session === null
+                ? { status: 'anonymous' }
+                : { status: 'authenticated', session };
+            setOwned({ context, port, state });
+        }
+        catch (error) {
+            // Local sign-out must complete even when the server cannot revoke its cookie. A read
+            // retry here would quietly restore that still-valid session instead of showing login.
+            if (isCurrent())
+                setOwned({ context, port, state: operation === 'logout'
+                        ? { status: 'anonymous' }
+                        : { status: 'error', error } });
+        }
+        finally {
+            if (operation === 'logout' && loggingOut.current === owner)
+                loggingOut.current = null;
+        }
+    }, [context, port]);
+    const refresh = useCallback(() => run('read'), [run]);
+    const logout = useCallback(() => run('logout'), [run]);
+    useEffect(() => {
+        const owner = { context, port };
+        active.current = owner;
+        const unsubscribe = port.onUnauthenticated({
+            ...context,
+            onUnauthenticated: () => {
+                if (active.current !== owner)
+                    return;
+                // Retire all older reads before clearing the gate; none may restore the principal.
+                generation.current += 1;
+                setOwned({ context, port, state: { status: 'anonymous' } });
+            },
+        });
+        void refresh();
+        return () => {
+            active.current = null;
+            generation.current += 1;
+            unsubscribe();
+        };
+    }, [context, port, refresh]);
+    // Mask the old workspace synchronously, before effect cleanup/initialization executes.
+    const state = owned.context === context && owned.port === port
+        ? owned.state
+        : { status: 'checking' };
+    return { state, refresh, logout };
+}
+//# sourceMappingURL=use-admin-shell-session.js.map

package/dist/react/shell/use-admin-theme.d.ts

@@ -0,0 +1,16 @@
+import { type AdminTheme, type ColorSchemePreference } from '@jini-ai/ui/theme';
+import type { AdminShellAppearance, AdminThemeEnvironment, AdminThemePreferenceStorePort } from './theme-ports.js';
+/** Keep effects inside the host's scope; storage reads/writes never use ambient browser state. */
+export declare function useAdminTheme({ userId, workspace }: {
+    readonly userId: string | null;
+    readonly workspace: Readonly<Record<string, string>>;
+}, { theme, colorScheme, environment, preferenceStore, onColorSchemeChange }?: {
+    readonly theme?: AdminTheme;
+    readonly colorScheme?: ColorSchemePreference;
+    readonly environment?: AdminThemeEnvironment;
+    readonly preferenceStore?: AdminThemePreferenceStorePort;
+    readonly onColorSchemeChange?: (args: {
+        readonly preference: ColorSchemePreference;
+    }) => void;
+}): AdminShellAppearance | undefined;
+//# sourceMappingURL=use-admin-theme.d.ts.map

package/dist/react/shell/use-admin-theme.js

@@ -0,0 +1,57 @@
+import { useCallback, useEffect, useState } from 'react';
+import { applyAdminTheme, resolveColorScheme } from '@jini-ai/ui/theme';
+/** Keep effects inside the host's scope; storage reads/writes never use ambient browser state. */
+export function useAdminTheme({ userId, workspace }, { theme, colorScheme, environment, preferenceStore, onColorSchemeChange } = {}) {
+    const scope = JSON.stringify([userId, Object.entries(workspace).sort(([a], [b]) => a.localeCompare(b))]);
+    const [saved, setSaved] = useState(null);
+    const [mediaRevision, setMediaRevision] = useState(0);
+    const preference = colorScheme ?? (saved?.scope === scope ? saved.preference : 'system');
+    useEffect(() => {
+        if (!userId || !preferenceStore) {
+            setSaved(null);
+            return;
+        }
+        const stored = preferenceStore.read({ userId, workspace });
+        setSaved(stored === 'light' || stored === 'dark' || stored === 'system' ? { scope, preference: stored } : null);
+    }, [userId, workspace, scope, preferenceStore]);
+    useEffect(() => {
+        if (!theme)
+            return;
+        if (!environment)
+            throw new TypeError('AdminShell theme requires a themeEnvironment port');
+        return applyAdminTheme({ theme }, environment);
+    }, [theme, environment]);
+    useEffect(() => {
+        if (!environment || preference !== 'system')
+            return;
+        const media = environment.matchMedia('(prefers-color-scheme: dark)');
+        const changed = () => setMediaRevision((revision) => revision + 1);
+        media.addEventListener?.('change', changed);
+        return () => media.removeEventListener?.('change', changed);
+    }, [environment, preference]);
+    // A revision refreshes the live media snapshot; explicit choices never query the OS.
+    void mediaRevision;
+    const resolved = environment ? resolveColorScheme({ preference }, { matchMedia: environment.matchMedia }) : 'light';
+    useEffect(() => {
+        if (!environment)
+            return;
+        const previous = environment.target.getAttribute('data-color-scheme');
+        environment.target.setAttribute('data-color-scheme', resolved);
+        return () => {
+            if (previous === null)
+                environment.target.removeAttribute('data-color-scheme');
+            else
+                environment.target.setAttribute('data-color-scheme', previous);
+        };
+    }, [environment, resolved]);
+    const setPreference = useCallback(({ preference: next }) => {
+        if (next !== 'light' && next !== 'dark' && next !== 'system')
+            throw new TypeError('Invalid color scheme preference');
+        if (userId && preferenceStore)
+            preferenceStore.write({ userId, workspace, preference: next });
+        setSaved({ scope, preference: next });
+        onColorSchemeChange?.({ preference: next });
+    }, [userId, preferenceStore, workspace, scope, onColorSchemeChange]);
+    return environment ? { preference, resolved, setPreference } : undefined;
+}
+//# sourceMappingURL=use-admin-theme.js.map

package/dist/react/types.d.ts

@@ -18,11 +18,13 @@
 export type ConfirmTone = 'default' | 'warning' | 'danger';
 /** Maps a tone onto the class name the host stylesheet is expected to define. `"default"` yields
  *  `undefined` — the plain button, no class. */
-export declare function toneClassName(tone: ConfirmTone): string | undefined;
+export declare function toneClassName({ tone }: {
+    readonly tone: ConfirmTone;
+}): string | undefined;
 /** `tone` wins when both `tone` and the deprecated `destructive` are passed; `destructive: true`
  *  alone still maps to `"danger"` (its only prior meaning) for callers that haven't migrated. */
-export declare function resolveTone(source: {
-    tone?: ConfirmTone;
-    destructive?: boolean;
+export declare function resolveTone(_requiredArgs: Record<string, never>, source?: {
+    tone?: ConfirmTone | undefined;
+    destructive?: boolean | undefined;
 }): ConfirmTone;
 //# sourceMappingURL=types.d.ts.map

package/dist/react/types.js

@@ -8,7 +8,7 @@
  */
 /** Maps a tone onto the class name the host stylesheet is expected to define. `"default"` yields
  *  `undefined` — the plain button, no class. */
-export function toneClassName(tone) {
+export function toneClassName({ tone }) {
     if (tone === 'danger')
         return 'btn-danger';
     if (tone === 'warning')
@@ -17,7 +17,7 @@ export function toneClassName(tone) {
 }
 /** `tone` wins when both `tone` and the deprecated `destructive` are passed; `destructive: true`
  *  alone still maps to `"danger"` (its only prior meaning) for callers that haven't migrated. */
-export function resolveTone(source) {
+export function resolveTone(_requiredArgs, source = {}) {
     return source.tone ?? (source.destructive ? 'danger' : 'default');
 }
 //# sourceMappingURL=types.js.map

package/dist/react/use-controller.d.ts

@@ -0,0 +1,16 @@
+import type { DependencyList } from 'react';
+import type { ControllerStore } from '../core/module/controller-store.js';
+/** Factory runs after commit, never during render. Each effect attachment owns a fresh
+ * controller, so StrictMode's cleanup/replay cannot revive a disposed controller. */
+export declare function useController<C extends ControllerStore<unknown>>({ create, dependencies }: {
+    create: () => C;
+    dependencies: DependencyList;
+}, { start, }?: {
+    start?: (required: {
+        controller: C;
+    }, optional?: Record<string, never>) => void;
+}): {
+    controller: C | null;
+    snapshot: ReturnType<C["getSnapshot"]> | null;
+};
+//# sourceMappingURL=use-controller.d.ts.map

package/dist/react/use-controller.js

@@ -0,0 +1,18 @@
+import { useEffect, useState, useSyncExternalStore, useCallback } from 'react';
+/** Factory runs after commit, never during render. Each effect attachment owns a fresh
+ * controller, so StrictMode's cleanup/replay cannot revive a disposed controller. */
+export function useController({ create, dependencies }, { start, } = {}) {
+    const [controller, setController] = useState(null);
+    useEffect(() => {
+        const current = create();
+        setController(current);
+        start?.({ controller: current });
+        return () => current.dispose();
+        // Dependencies are explicitly supplied by the owning hook, like useMemo's contract.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, dependencies);
+    const subscribe = useCallback((listener) => controller?.subscribe({ listener }) ?? (() => { }), [controller]);
+    const snapshot = useSyncExternalStore(subscribe, () => (controller?.getSnapshot() ?? null), () => null);
+    return { controller, snapshot };
+}
+//# sourceMappingURL=use-controller.js.map

package/dist/security/adapters/http.d.ts

@@ -0,0 +1,16 @@
+import type { SecurityApiPort, SecurityTransportPort, OtherCredentialsPort, RootKeyPort } from '../ports.js';
+export declare function createHttpSecurityApi({ transport, workspacePath }: {
+    transport: SecurityTransportPort;
+    workspacePath: string;
+}, _optional?: {}): SecurityApiPort;
+export declare function createHttpOtherCredentials({ transport, workspacePath }: {
+    transport: SecurityTransportPort;
+    workspacePath: string;
+}, { mediaLabels }?: {
+    mediaLabels?: Readonly<Record<string, string>>;
+}): OtherCredentialsPort;
+export declare function createHttpRootKey({ transport, workspacePath }: {
+    transport: SecurityTransportPort;
+    workspacePath: string;
+}, _optional?: {}): RootKeyPort;
+//# sourceMappingURL=http.d.ts.map

package/dist/security/adapters/http.js

@@ -0,0 +1,94 @@
+/** Explicit projection strips accidental server extras, including token/ciphertext/hex. */
+function summary(row, kind) {
+    return Object.freeze({ kind, id: row.id, providerId: row.providerId ?? '', label: row.label, configured: row.configured, isDefault: row.isDefault ?? false, createdAt: row.createdAt, updatedAt: row.updatedAt,
+        ...(row.accountLabel !== undefined ? { accountLabel: row.accountLabel } : {}), ...(kind === 'custom' ? { category: row.category ?? 'general', baseUrl: row.baseUrl ?? '', additionalHosts: Object.freeze([...(row.additionalHosts ?? [])]), ...(row.username ? { username: row.username } : {}) } : {}) });
+}
+export function createHttpSecurityApi({ transport, workspacePath }, _optional = {}) {
+    const base = workspacePath.replace(/\/$/, '');
+    function store(kind, suffix) {
+        const path = `${base}/system/${suffix}/credentials`;
+        async function mutate(method, target, body, options) { options.signal?.throwIfAborted(); const r = await transport.request({ method, path: target, body }, options); return summary(r.credential, kind); }
+        return {
+            async list(_r, options = {}) { options.signal?.throwIfAborted(); const r = await transport.request({ method: 'GET', path }, options); return Object.freeze(r.credentials.map(row => summary(row, kind))); },
+            create(input, options = {}) { return mutate('POST', path, input, options); },
+            update({ id, patch }, options = {}) { return mutate('PUT', `${path}/${encodeURIComponent(id)}`, patch, options); },
+            async remove({ id }, options = {}) { options.signal?.throwIfAborted(); await transport.request({ method: 'DELETE', path: `${path}/${encodeURIComponent(id)}` }, options); },
+        };
+    }
+    return {
+        async providers(_r, options = {}) {
+            options.signal?.throwIfAborted();
+            const [publish, source] = await Promise.all([
+                transport.request({ method: 'GET', path: `${base}/system/publish-targets` }, options),
+                transport.request({ method: 'GET', path: `${base}/system/source-control/providers` }, options),
+            ]);
+            const map = (kind, d) => ({ kind, id: d.id, label: d.label, vendorLabel: d.credential?.vendorLabel ?? d.label, category: kind === 'publish' ? 'hosting' : 'source-control', tokenField: d.credential?.tokenField ?? 'token', fields: d.credential?.fields ?? [], ...(d.credential?.tokenPageUrl ? { tokenPageUrl: d.credential.tokenPageUrl } : {}), ...((d.credential?.userHelp ?? d.credential?.help) ? { help: d.credential.userHelp ?? d.credential.help } : {}) });
+            return [...publish.targets.filter(d => d.credential).map(d => map('publish', d)), ...source.providers.map(d => map('source-control', d))];
+        },
+        publish: store('publish', 'publish'), sourceControl: store('source-control', 'source-control'), custom: store('custom', 'custom'),
+    };
+}
+/** Replacing the ENTIRE map requires sibling settings unchanged. Blank apiKey preserves their stored keys. */
+function rebuildMedia(current, id, token) {
+    const next = {};
+    for (const [key, entry] of Object.entries(current)) {
+        if (key === id && token === undefined)
+            continue;
+        next[key] = { ...(entry.baseUrl !== undefined ? { baseUrl: entry.baseUrl } : {}), ...(entry.model !== undefined ? { model: entry.model } : {}), ...(key === id && token !== undefined ? { apiKey: token } : {}) };
+    }
+    return next;
+}
+export function createHttpOtherCredentials({ transport, workspacePath }, { mediaLabels = {} } = {}) {
+    const base = workspacePath.replace(/\/$/, '');
+    const singles = { 'site-assistant': { path: '/assistant/site-credential', label: 'Assistant model key' }, 'admin-byok': { path: '/assistant/execution-credential', label: 'Admin model key' } };
+    async function request(path, method, options, body) { options.signal?.throwIfAborted(); return transport.request({ path: `${base}${path}`, method, ...(body !== undefined ? { body } : {}) }, options); }
+    return {
+        async list({ store }, options = {}) {
+            if (store === 'site-assistant' || store === 'admin-byok') {
+                const r = await request(singles[store].path, 'GET', options);
+                return r.data.isSet ? [{ store, id: store, label: singles[store].label, category: 'ai', configured: true, supportsReplace: true, updatedAt: r.data.updatedAt }] : [];
+            }
+            if (store === 'media-provider') {
+                const map = await request('/media/providers', 'GET', options);
+                return Object.entries(map).filter(([, entry]) => entry.apiKeyConfigured).map(([id]) => ({ store, id, label: mediaLabels[id] ?? id, category: 'media', configured: true, supportsReplace: true }));
+            }
+            const { servers } = await request('/mcp-servers', 'GET', options);
+            return servers.map(s => ({ store, id: s.serverId, label: s.label, category: 'ai', configured: true, supportsReplace: false, envNames: Object.freeze([...s.envNames]) }));
+        },
+        async replace({ store, id, token }, options = {}) {
+            if (!token.trim())
+                throw new Error('Enter a credential');
+            if (store === 'external-mcp')
+                throw new Error('Edit the full server configuration on its own screen');
+            if (store === 'media-provider') {
+                const current = await request('/media/providers', 'GET', options);
+                await request('/media/providers', 'PUT', options, rebuildMedia(current, id, token));
+            }
+            else
+                await request(singles[store].path, 'PUT', options, { apiKey: token });
+        },
+        async remove({ store, id }, options = {}) {
+            if (store === 'media-provider') {
+                const current = await request('/media/providers', 'GET', options);
+                await request('/media/providers', 'PUT', options, rebuildMedia(current, id));
+            }
+            else if (store === 'external-mcp')
+                await request(`/mcp-servers/${encodeURIComponent(id)}`, 'DELETE', options);
+            else
+                await request(singles[store].path, 'DELETE', options);
+        },
+    };
+}
+export function createHttpRootKey({ transport, workspacePath }, _optional = {}) {
+    const path = `${workspacePath.replace(/\/$/, '')}/system/site-token`;
+    async function request(suffix, method, options, body) { options.signal?.throwIfAborted(); return transport.request({ path: `${path}${suffix}`, method, ...(body !== undefined ? { body } : {}) }, options); }
+    function result(r) { return { outcome: r.outcome, fingerprint: r.fingerprint, keyFilePath: r.keyFilePath, runtimeMode: r.runtimeMode, ...(r.resealed !== undefined ? { resealed: r.resealed } : {}), ...(r.discarded !== undefined ? { discarded: r.discarded } : {}), ...(r.kept !== undefined ? { kept: r.kept } : {}), ...(r.restorePointId ? { restorePointId: r.restorePointId } : {}), ...(r.affectedWebhooks ? { affectedWebhooks: r.affectedWebhooks.map(w => ({ label: w.label, targetUrl: w.targetUrl })) } : {}) }; }
+    return {
+        async status(_r, o = {}) { const r = await request('', 'GET', o); return { active: r.active, source: r.source, state: r.state, keyFilePath: r.keyFilePath, runtimeMode: r.runtimeMode, ...(r.fingerprint ? { fingerprint: r.fingerprint } : {}), ...(r.invalid !== undefined ? { invalid: r.invalid } : {}) }; },
+        async generate(_r, o = {}) { return result(await request('/generate', 'POST', o)); },
+        async importToken({ token }, o = {}) { return result(await request('/import', 'POST', o, { token })); },
+        async previewStartFresh(_r, o = {}) { const r = await request('/start-fresh', 'GET', o); return { removes: r.removes, detail: r.detail, runtimeMode: r.runtimeMode, affectedWebhooks: r.affectedWebhooks.map(w => ({ label: w.label, targetUrl: w.targetUrl })) }; },
+        async startFresh({ confirm }, o = {}) { return result(await request('/start-fresh', 'POST', o, { confirm })); },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/security/adapters/memory.d.ts

@@ -0,0 +1,15 @@
+import type { SecurityApiPort, OtherCredentialsPort, RootKeyPort } from '../ports.js';
+import type { CredentialSummary, CredentialProvider, OtherCredentialSummary, RootKeyStatus, RootKeyPreview } from '../models.js';
+/** Fake backend: retains only read models, never credential material. */
+export declare function createMemorySecurityApi({ providers, rows }: {
+    providers?: readonly CredentialProvider[];
+    rows?: readonly CredentialSummary[];
+}, _optional?: {}): SecurityApiPort;
+export declare function createMemoryOtherCredentials({ rows }: {
+    rows?: readonly OtherCredentialSummary[];
+}, _optional?: {}): OtherCredentialsPort;
+export declare function createMemoryRootKey({ status, preview }: {
+    status?: RootKeyStatus;
+    preview?: RootKeyPreview;
+}, _optional?: {}): RootKeyPort;
+//# sourceMappingURL=memory.d.ts.map