@jini-ai/admin 0.4.2 → 0.4.3

package/dist/widgets/controllers/region-editor.controller.d.ts

@@ -0,0 +1,42 @@
+import type { AdminWidgetsPort } from '../ports.js';
+import type { AdminWidgetArea, AdminWidgetPlacement, WidgetsTranslate } from '../models.js';
+export interface WidgetRegionEditorState {
+    area: AdminWidgetArea | null;
+    placements: AdminWidgetPlacement[];
+    message: string | null;
+    error: string | null;
+    loading: boolean;
+    saving: boolean;
+}
+/** One generation guards both load call sites (route changes and post-save rereads). */
+export declare function createWidgetRegionEditorController({ api, regionKey: initialKey }: {
+    api: AdminWidgetsPort;
+    regionKey: string;
+}, { t }?: {
+    t?: WidgetsTranslate | undefined;
+}): {
+    getSnapshot: () => Readonly<WidgetRegionEditorState>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    load: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    save: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    addPlacement: ({ widgetInstanceId }: {
+        widgetInstanceId: string;
+    }, _optional?: Record<string, never>) => void;
+    setRegionKey({ regionKey: next }: {
+        regionKey: string;
+    }, _optional?: Record<string, never>): void;
+    removeAt({ placementId }: {
+        placementId: string;
+    }, _optional?: Record<string, never>): void;
+    moveAt({ index, direction }: {
+        index: number;
+        direction: -1 | 1;
+    }, _optional?: Record<string, never>): void;
+    toggleEnabled({ placementId }: {
+        placementId: string;
+    }, _optional?: Record<string, never>): void;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+//# sourceMappingURL=region-editor.controller.d.ts.map

package/dist/widgets/controllers/region-editor.controller.js

@@ -0,0 +1,69 @@
+import { createControllerStore } from '../../core/module/controller-store.js';
+import { describeApiError } from '../../core/transport/errors.js';
+import { buildDraftPlacement, movePlacement, resolveWidgetRegionSaveError, widgetApiError } from '../rules.js';
+import { widgetsEnglish } from '../messages.en.js';
+/** One generation guards both load call sites (route changes and post-save rereads). */
+export function createWidgetRegionEditorController({ api, regionKey: initialKey }, { t = widgetsEnglish } = {}) {
+    const store = createControllerStore({ initial: { area: null, placements: [], message: null, error: null, loading: true, saving: false } });
+    let regionKey = initialKey, generation = 0;
+    async function load(_required = {}, _optional = {}) {
+        const ticket = ++generation;
+        store.set({ patch: { loading: true, error: null, saving: false } });
+        try {
+            const result = await api.getWidgetRegion({ regionKey }, { signal: store.signal });
+            if (ticket === generation && !store.signal.aborted)
+                store.set({ patch: { area: result.area, placements: result.placements } });
+        }
+        catch (error) {
+            if (ticket === generation && !store.signal.aborted)
+                store.set({ patch: { error: describeApiError({ e: widgetApiError({ error }) ?? error, fallback: t('failed to load region') }) } });
+        }
+        finally {
+            if (ticket === generation && !store.signal.aborted)
+                store.set({ patch: { loading: false } });
+        }
+    }
+    function addPlacement({ widgetInstanceId }, _optional = {}) {
+        const draft = buildDraftPlacement({ widgetInstanceId });
+        store.set({ patch: { placements: [...store.getSnapshot().placements, draft] } });
+        // A failed lookup keeps the draft saveable; the post-save reread supplies its title/type.
+        void api.getWidget({ id: widgetInstanceId }, { signal: store.signal }).then(({ widget }) => {
+            store.set({ patch: { placements: store.getSnapshot().placements.map(p => p.placementId === draft.placementId ? { ...p, widgetTitle: widget.title, widgetType: widget.widgetType } : p) } });
+        }).catch(() => { });
+    }
+    async function save(_required = {}, _optional = {}) {
+        const { area, placements } = store.getSnapshot();
+        if (!area)
+            return;
+        const ticket = generation;
+        store.set({ patch: { saving: true, message: null, error: null } });
+        let stale = false;
+        try {
+            const { area: saved } = await api.mutateWidgetRegionPlacements({ regionKey, baseVersion: area.version, placements: placements.map(p => ({ placementId: p.placementId, widgetEntryId: p.widgetEntryId, enabled: p.enabled })) }, { signal: store.signal });
+            stale = ticket !== generation || store.signal.aborted;
+            if (stale)
+                return;
+            store.set({ patch: { area: saved, message: t('Saved · version {version}').replace('{version}', String(saved.version)) } });
+            // A stale save must never mint a read generation that supersedes the new region's load.
+            void load();
+        }
+        catch (error) {
+            stale = ticket !== generation || store.signal.aborted;
+            if (!stale)
+                store.set({ patch: { error: resolveWidgetRegionSaveError({ error }, { t }) } });
+        }
+        finally {
+            if (!stale)
+                store.set({ patch: { saving: false } });
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, load, save, addPlacement,
+        setRegionKey({ regionKey: next }, _optional = {}) { regionKey = next; void load(); },
+        removeAt({ placementId }, _optional = {}) { store.set({ patch: { placements: store.getSnapshot().placements.filter(p => p.placementId !== placementId) } }); },
+        moveAt({ index, direction }, _optional = {}) { store.set({ patch: { placements: movePlacement({ items: store.getSnapshot().placements, index, direction }) } }); },
+        toggleEnabled({ placementId }, _optional = {}) { store.set({ patch: { placements: store.getSnapshot().placements.map(p => p.placementId === placementId ? { ...p, enabled: !p.enabled } : p) } }); },
+        dispose(_required = {}, _optional = {}) { generation++; store.dispose(); },
+    };
+}
+//# sourceMappingURL=region-editor.controller.js.map

package/dist/widgets/controllers/regions.controller.d.ts

@@ -0,0 +1,27 @@
+import type { AdminWidgetsPort } from '../ports.js';
+import type { AdminWidgetRegionBinding, WidgetsTranslate } from '../models.js';
+export interface WidgetRegionsState {
+    regions: AdminWidgetRegionBinding[] | null;
+    error: string | null;
+    newRegionKey: string;
+    binding: boolean;
+}
+/** Region keys stay free text: no admin-listable theme registry exists. Latest refresh wins. */
+export declare function createWidgetRegionsController({ api }: {
+    api: AdminWidgetsPort;
+}, { t, navigate }?: {
+    t?: WidgetsTranslate | undefined;
+    navigate?: ((path: string) => void) | undefined;
+}): {
+    getSnapshot: () => Readonly<WidgetRegionsState>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    load: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    bind: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    setNewRegionKey({ value }: {
+        value: string;
+    }, _optional?: Record<string, never>): void;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+//# sourceMappingURL=regions.controller.d.ts.map

package/dist/widgets/controllers/regions.controller.js

@@ -0,0 +1,44 @@
+import { createControllerStore } from '../../core/module/controller-store.js';
+import { describeApiError } from '../../core/transport/errors.js';
+import { widgetApiError } from '../rules.js';
+import { widgetsEnglish } from '../messages.en.js';
+/** Region keys stay free text: no admin-listable theme registry exists. Latest refresh wins. */
+export function createWidgetRegionsController({ api }, { t = widgetsEnglish, navigate } = {}) {
+    const store = createControllerStore({ initial: { regions: null, error: null, newRegionKey: '', binding: false } });
+    let generation = 0;
+    async function load(_required = {}, _optional = {}) {
+        const ticket = ++generation;
+        try {
+            const result = await api.listWidgetRegions({}, { signal: store.signal });
+            if (ticket === generation && !store.signal.aborted)
+                store.set({ patch: { regions: result.regions } });
+        }
+        catch (error) {
+            if (ticket === generation && !store.signal.aborted)
+                store.set({ patch: { error: describeApiError({ e: widgetApiError({ error }) ?? error, fallback: t('failed to load regions') }) } });
+        }
+    }
+    async function bind(_required = {}, _optional = {}) {
+        const regionKey = store.getSnapshot().newRegionKey.trim();
+        if (!regionKey)
+            return;
+        store.set({ patch: { binding: true, error: null } });
+        try {
+            await api.bindWidgetRegion({ regionKey }, { signal: store.signal });
+            store.set({ patch: { newRegionKey: '' } });
+            navigate?.(`/widgets/regions/${regionKey}`);
+        }
+        catch (error) {
+            store.set({ patch: { error: describeApiError({ e: widgetApiError({ error }) ?? error, fallback: t('bind failed') }) } });
+        }
+        finally {
+            store.set({ patch: { binding: false } });
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, load, bind,
+        setNewRegionKey({ value }, _optional = {}) { store.set({ patch: { newRegionKey: value } }); },
+        dispose(_required = {}, _optional = {}) { generation++; store.dispose(); },
+    };
+}
+//# sourceMappingURL=regions.controller.js.map

package/dist/widgets/index.d.ts

@@ -0,0 +1,11 @@
+export { widgetsModule, widgetsAgentPageIds, widgetsEditorPaths } from './widgets.module.js';
+export { widgetsApiToken, widgetsEventsToken, widgetsNavigationToken } from './ports.js';
+export type { AdminWidgetsPort, WidgetsEventsPort, WidgetsNavigationPort } from './ports.js';
+export type * from './models.js';
+export * from './rules.js';
+export { widgetsMessagesEn, widgetsEnglish } from './messages.en.js';
+export { createWidgetsLibraryController } from './controllers/library.controller.js';
+export { createWidgetInstanceEditorController } from './controllers/instance-editor.controller.js';
+export { createWidgetRegionsController } from './controllers/regions.controller.js';
+export { createWidgetRegionEditorController } from './controllers/region-editor.controller.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/widgets/index.js

@@ -0,0 +1,9 @@
+export { widgetsModule, widgetsAgentPageIds, widgetsEditorPaths } from './widgets.module.js';
+export { widgetsApiToken, widgetsEventsToken, widgetsNavigationToken } from './ports.js';
+export * from './rules.js';
+export { widgetsMessagesEn, widgetsEnglish } from './messages.en.js';
+export { createWidgetsLibraryController } from './controllers/library.controller.js';
+export { createWidgetInstanceEditorController } from './controllers/instance-editor.controller.js';
+export { createWidgetRegionsController } from './controllers/regions.controller.js';
+export { createWidgetRegionEditorController } from './controllers/region-editor.controller.js';
+//# sourceMappingURL=index.js.map

package/dist/widgets/messages.en.d.ts

@@ -0,0 +1,78 @@
+/** English source keys translated by the host widgets dictionary. */
+export declare const widgetsMessagesEn: {
+    readonly Back: "Back";
+    readonly "Widget type to create": "Widget type to create";
+    readonly Content: "Content";
+    readonly Text: "Text";
+    readonly "Social Links": "Social Links";
+    readonly "Collection list": "Collection list";
+    readonly Menu: "Menu";
+    readonly "Contact Form": "Contact Form";
+    readonly Widgets: "Widgets";
+    readonly "Widget Regions": "Widget Regions";
+    readonly "A region is a theme-declared placement area (e.g. \"header\", \"footer\", \"sidebar\"). Bind a region by its key to start placing widgets in it.": "A region is a theme-declared placement area (e.g. \"header\", \"footer\", \"sidebar\"). Bind a region by its key to start placing widgets in it.";
+    readonly "Binding\u2026": "Binding…";
+    readonly "Bind region": "Bind region";
+    readonly "No regions bound yet.": "No regions bound yet.";
+    readonly "Region key": "Region key";
+    readonly Placements: "Placements";
+    readonly Manage: "Manage";
+    readonly "Create reusable content blocks and place them into your theme's widget regions.": "Create reusable content blocks and place them into your theme's widget regions.";
+    readonly "Regions \u2192": "Regions →";
+    readonly "Add New": "Add New";
+    readonly "1 widget record in this workspace could not be read.": "1 widget record in this workspace could not be read.";
+    readonly "{n} widget records in this workspace could not be read.": "{n} widget records in this workspace could not be read.";
+    readonly "Show ids": "Show ids";
+    readonly "No widgets yet.": "No widgets yet.";
+    readonly "Create one above to get started.": "Create one above to get started.";
+    readonly Title: "Title";
+    readonly Type: "Type";
+    readonly Slug: "Slug";
+    readonly Status: "Status";
+    readonly Actions: "Actions";
+    readonly Trash: "Trash";
+    readonly "Move to trash?": "Move to trash?";
+    readonly "Move to trash": "Move to trash";
+    readonly "Move \"{title}\" to trash?": "Move \"{title}\" to trash?";
+    readonly Regions: "Regions";
+    readonly "Saving\u2026": "Saving…";
+    readonly Save: "Save";
+    readonly "Region:": "Region:";
+    readonly "Manage which widgets appear in this region and their order.": "Manage which widgets appear in this region and their order.";
+    readonly "No widgets placed in this region yet.": "No widgets placed in this region yet.";
+    readonly Enabled: "Enabled";
+    readonly "\u26A0 Broken reference": "⚠ Broken reference";
+    readonly "+ Add widget": "+ Add widget";
+    readonly "New widget": "New widget";
+    readonly "Edit widget": "Edit widget";
+    readonly "Configure this widget's title and settings.": "Configure this widget's title and settings.";
+    readonly "Widget title": "Widget title";
+    readonly "Type:": "Type:";
+    readonly "Region area": "Region area";
+    readonly "Inline embed": "Inline embed";
+    readonly "Used in 1 place:": "Used in 1 place:";
+    readonly "Used in {count} places:": "Used in {count} places:";
+    readonly "failed to load widget": "failed to load widget";
+    readonly "save failed": "save failed";
+    readonly "This widget changed since you loaded it, refresh and try again.": "This widget changed since you loaded it, refresh and try again.";
+    readonly "This region changed since you loaded it, refresh and try again.": "This region changed since you loaded it, refresh and try again.";
+    readonly "failed to load region": "failed to load region";
+    readonly "failed to load widgets": "failed to load widgets";
+    readonly "delete failed": "delete failed";
+    readonly "This item changed since you loaded it. Reload and try again.": "This item changed since you loaded it. Reload and try again.";
+    readonly "failed to load regions": "failed to load regions";
+    readonly "bind failed": "bind failed";
+    readonly "Loading widget\u2026": "Loading widget…";
+    readonly "No widget type specified.": "No widget type specified.";
+    readonly "Unknown widget type \"": "Unknown widget type \"";
+    readonly "Loading region\u2026": "Loading region…";
+    readonly "Move up": "Move up";
+    readonly "Move down": "Move down";
+    readonly Remove: "Remove";
+    readonly "Loading regions\u2026": "Loading regions…";
+    readonly "Loading widgets\u2026": "Loading widgets…";
+    readonly "Saved \u00B7 version {version}": "Saved · version {version}";
+};
+/** English fallback with the same interpolation convention as the host. */
+export declare function widgetsEnglish(key: string, vars?: Record<string, string | number> | undefined): string;
+//# sourceMappingURL=messages.en.d.ts.map

package/dist/widgets/messages.en.js

@@ -0,0 +1,83 @@
+/** English source keys translated by the host widgets dictionary. */
+export const widgetsMessagesEn = {
+    "Back": "Back",
+    "Widget type to create": "Widget type to create",
+    "Content": "Content",
+    "Text": "Text",
+    "Social Links": "Social Links",
+    "Collection list": "Collection list",
+    "Menu": "Menu",
+    "Contact Form": "Contact Form",
+    "Widgets": "Widgets",
+    "Widget Regions": "Widget Regions",
+    "A region is a theme-declared placement area (e.g. \"header\", \"footer\", \"sidebar\"). Bind a region by its key to start placing widgets in it.": "A region is a theme-declared placement area (e.g. \"header\", \"footer\", \"sidebar\"). Bind a region by its key to start placing widgets in it.",
+    "Binding…": "Binding…",
+    "Bind region": "Bind region",
+    "No regions bound yet.": "No regions bound yet.",
+    "Region key": "Region key",
+    "Placements": "Placements",
+    "Manage": "Manage",
+    "Create reusable content blocks and place them into your theme's widget regions.": "Create reusable content blocks and place them into your theme's widget regions.",
+    "Regions →": "Regions →",
+    "Add New": "Add New",
+    "1 widget record in this workspace could not be read.": "1 widget record in this workspace could not be read.",
+    "{n} widget records in this workspace could not be read.": "{n} widget records in this workspace could not be read.",
+    "Show ids": "Show ids",
+    "No widgets yet.": "No widgets yet.",
+    "Create one above to get started.": "Create one above to get started.",
+    "Title": "Title",
+    "Type": "Type",
+    "Slug": "Slug",
+    "Status": "Status",
+    "Actions": "Actions",
+    "Trash": "Trash",
+    "Move to trash?": "Move to trash?",
+    "Move to trash": "Move to trash",
+    "Move \"{title}\" to trash?": "Move \"{title}\" to trash?",
+    "Regions": "Regions",
+    "Saving…": "Saving…",
+    "Save": "Save",
+    "Region:": "Region:",
+    "Manage which widgets appear in this region and their order.": "Manage which widgets appear in this region and their order.",
+    "No widgets placed in this region yet.": "No widgets placed in this region yet.",
+    "Enabled": "Enabled",
+    "⚠ Broken reference": "⚠ Broken reference",
+    "+ Add widget": "+ Add widget",
+    "New widget": "New widget",
+    "Edit widget": "Edit widget",
+    "Configure this widget's title and settings.": "Configure this widget's title and settings.",
+    "Widget title": "Widget title",
+    "Type:": "Type:",
+    "Region area": "Region area",
+    "Inline embed": "Inline embed",
+    "Used in 1 place:": "Used in 1 place:",
+    "Used in {count} places:": "Used in {count} places:",
+    "failed to load widget": "failed to load widget",
+    "save failed": "save failed",
+    "This widget changed since you loaded it, refresh and try again.": "This widget changed since you loaded it, refresh and try again.",
+    "This region changed since you loaded it, refresh and try again.": "This region changed since you loaded it, refresh and try again.",
+    "failed to load region": "failed to load region",
+    "failed to load widgets": "failed to load widgets",
+    "delete failed": "delete failed",
+    "This item changed since you loaded it. Reload and try again.": "This item changed since you loaded it. Reload and try again.",
+    "failed to load regions": "failed to load regions",
+    "bind failed": "bind failed",
+    "Loading widget…": "Loading widget…",
+    "No widget type specified.": "No widget type specified.",
+    "Unknown widget type \"": "Unknown widget type \"",
+    "Loading region…": "Loading region…",
+    "Move up": "Move up",
+    "Move down": "Move down",
+    "Remove": "Remove",
+    "Loading regions…": "Loading regions…",
+    "Loading widgets…": "Loading widgets…",
+    "Saved · version {version}": "Saved · version {version}"
+};
+/** English fallback with the same interpolation convention as the host. */
+export function widgetsEnglish(key, vars) {
+    let message = widgetsMessagesEn[key] ?? key;
+    for (const [name, value] of Object.entries(vars ?? {}))
+        message = message.replaceAll(`{${name}}`, String(value));
+    return message;
+}
+//# sourceMappingURL=messages.en.js.map

package/dist/widgets/models.d.ts

@@ -0,0 +1,62 @@
+/** Host-defined widget types/status/reference kinds are open; the supplied catalog controls creation. */
+export type AdminWidgetType = 'text' | 'social-links' | 'recent-entries' | 'menu' | 'contact-form' | (string & {});
+export type AdminWidgetStatus = 'active' | 'trash' | 'purged' | (string & {});
+export interface AdminWidget {
+    id: string;
+    workspaceId: string;
+    slug: string;
+    title: string;
+    status: AdminWidgetStatus;
+    widgetType: AdminWidgetType;
+    config: Record<string, unknown>;
+    updatedAt: string;
+    version: number;
+}
+export interface AdminWidgetWhereUsedReference {
+    kind: 'region' | 'embed' | (string & {});
+    sourceEntryId: string;
+    fieldPath: string;
+}
+export interface AdminWidgetWhereUsed {
+    count: number;
+    references: AdminWidgetWhereUsedReference[];
+}
+export interface AdminWidgetPlacement {
+    placementId: string;
+    widgetEntryId: string;
+    enabled: boolean;
+    widgetTitle: string | null;
+    widgetType: string | null;
+    broken: boolean;
+}
+export interface AdminWidgetArea {
+    id: string;
+    workspaceId: string;
+    regionKey: string;
+    updatedAt: string;
+    version: number;
+}
+export interface AdminWidgetRegionBinding {
+    workspaceId: string;
+    regionKey: string;
+    areaEntryId: string;
+    updatedAt: string;
+    placementCount: number;
+}
+export type WidgetsTranslate = (key: string, vars?: Record<string, string | number> | undefined) => string;
+export interface WidgetTypeOption {
+    value: AdminWidgetType;
+    label: string;
+}
+export interface WidgetsRequestOptions {
+    signal?: AbortSignal | undefined;
+}
+export interface WidgetEditorParams {
+    widgetId: string | null;
+    widgetType: string | null;
+}
+export type WidgetSlugRedirectPath = (base: string, requestedId: string, item: {
+    id: string;
+    slug: string;
+}) => string | null;
+//# sourceMappingURL=models.d.ts.map

package/dist/widgets/models.js

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

package/dist/widgets/ports.d.ts

@@ -0,0 +1,79 @@
+import type { AdminShellNavigationPort } from '../core/ports/shell.js';
+import type { AdminWidget, AdminWidgetWhereUsed, AdminWidgetArea, AdminWidgetPlacement, AdminWidgetRegionBinding, AdminWidgetType, WidgetsRequestOptions } from './models.js';
+/** Instance and region administration share one workspace-scoped API. Hosts authorize widgets.*,
+ * validate configs and placement caps, and enforce baseVersion on writes. No purge or embed-write
+ * operation is exposed: the four screens never call one; embeds appear in whereUsed only. */
+export interface AdminWidgetsPort {
+    listWidgets(required: {
+        widgetType?: string | undefined;
+        includeInactive?: boolean | undefined;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<{
+        widgets: AdminWidget[];
+        skippedCount?: number | undefined;
+        skippedIds?: string[] | undefined;
+    }>;
+    getWidget(required: {
+        id: string;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<{
+        widget: AdminWidget;
+        whereUsed: AdminWidgetWhereUsed;
+    }>;
+    createWidget(required: {
+        widgetType: AdminWidgetType;
+        title: string;
+        config: Record<string, unknown>;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<{
+        widget: AdminWidget;
+    }>;
+    updateWidget(required: {
+        id: string;
+        baseVersion: number;
+        config: Record<string, unknown>;
+        title?: string | undefined;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<{
+        widget: AdminWidget;
+    }>;
+    trashWidget(required: {
+        id: string;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<{
+        ok: true;
+        version: number | null;
+    }>;
+    listWidgetRegions(required: Record<string, never>, optional?: WidgetsRequestOptions | undefined): Promise<{
+        regions: AdminWidgetRegionBinding[];
+    }>;
+    bindWidgetRegion(required: {
+        regionKey: string;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<{
+        area: AdminWidgetArea;
+    }>;
+    getWidgetRegion(required: {
+        regionKey: string;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<{
+        area: AdminWidgetArea;
+        placements: AdminWidgetPlacement[];
+    }>;
+    mutateWidgetRegionPlacements(required: {
+        regionKey: string;
+        baseVersion: number;
+        placements: Array<{
+            placementId: string;
+            widgetEntryId: string;
+            enabled: boolean;
+        }>;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<{
+        area: AdminWidgetArea;
+    }>;
+}
+/** The host filters refresh scope by resource, including null = all resources. */
+export interface WidgetsEventsPort {
+    subscribe(required: {
+        resource: string;
+        onRefresh: () => void;
+    }, optional?: Record<string, never> | undefined): () => void;
+}
+export type WidgetsNavigationPort = Pick<AdminShellNavigationPort, 'navigate'>;
+export declare const widgetsApiToken: import("../core/module/token.js").AdminPortToken<AdminWidgetsPort, "admin.widgets.api">;
+export declare const widgetsEventsToken: import("../core/module/token.js").AdminPortToken<WidgetsEventsPort, "admin.widgets.events">;
+export declare const widgetsNavigationToken: import("../core/module/token.js").AdminPortToken<WidgetsNavigationPort, "admin.widgets.navigation">;
+//# sourceMappingURL=ports.d.ts.map

package/dist/widgets/ports.js

@@ -0,0 +1,5 @@
+import { adminPort } from '../core/module/token.js';
+export const widgetsApiToken = adminPort({ id: 'admin.widgets.api' });
+export const widgetsEventsToken = adminPort({ id: 'admin.widgets.events' });
+export const widgetsNavigationToken = adminPort({ id: 'admin.widgets.navigation' });
+//# sourceMappingURL=ports.js.map

package/dist/widgets/react/components/WidgetInstanceNotices.d.ts

@@ -0,0 +1,14 @@
+import type { AdminWidgetWhereUsed, WidgetsTranslate as Translate } from "../../models.js";
+/** REQ-34/`ui.spec.md` §3.5 — rendered only when `references.length > 0`, before the config form. */
+export declare function WhereUsedBanner(props: {
+    whereUsed: AdminWidgetWhereUsed;
+    t: Translate;
+}): import("react").JSX.Element | null;
+import type { WidgetInstanceGuard } from '../../rules.js';
+/** Renders the notice for whichever guard applies — split from `widgetInstanceGuard` itself so the
+ *  decision (data in, data out) and the rendering stay separately testable. */
+export declare function WidgetInstanceGuardNotice({ guard, t }: {
+    guard: WidgetInstanceGuard;
+    t: (key: string) => string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=WidgetInstanceNotices.d.ts.map

package/dist/widgets/react/components/WidgetInstanceNotices.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** REQ-34/`ui.spec.md` §3.5 — rendered only when `references.length > 0`, before the config form. */
+export function WhereUsedBanner(props) {
+    const { t } = props;
+    if (props.whereUsed.count === 0)
+        return null;
+    return (_jsxs("div", { className: "notice widget-where-used-banner", children: [_jsx("strong", { children: props.whereUsed.count === 1
+                    ? t("Used in 1 place:")
+                    : t("Used in {count} places:").replace("{count}", String(props.whereUsed.count)) }), _jsx("ul", { children: props.whereUsed.references.map((ref, i) => (_jsxs("li", { children: [ref.kind === "region" ? t("Region area") : t("Inline embed"), " (", ref.sourceEntryId, ")"] }, i))) })] }));
+}
+/** Renders the notice for whichever guard applies — split from `widgetInstanceGuard` itself so the
+ *  decision (data in, data out) and the rendering stay separately testable. */
+export function WidgetInstanceGuardNotice({ guard, t }) {
+    switch (guard.kind) {
+        case "fetch-error":
+            return _jsx("div", { className: "notice error", children: guard.message });
+        case "loading":
+            return _jsx("div", { className: "notice", children: t("Loading widget…") });
+        case "no-type":
+            return _jsx("div", { className: "notice error", children: t("No widget type specified.") });
+        case "unknown-type":
+            return _jsxs("div", { className: "notice error", children: [t('Unknown widget type "'), guard.widgetType, "\"."] });
+    }
+}
+//# sourceMappingURL=WidgetInstanceNotices.js.map

package/dist/widgets/react/components/WidgetRegionEditorHeaderActions.d.ts

@@ -0,0 +1,22 @@
+/** The page header's Save-side actions cluster — the save-status message/error and the Save
+ *  button — pulled out of `WidgetRegionEditor`'s own render body as a top-level component under
+ *  the tightened ≤9/≤9 pass. Each of the three spans below is its own independent conditional (a
+ *  save succeeded, a save failed, the save is in flight); extracting the whole cluster moves all
+ *  three out of the parent's own scope at once.
+ *
+ * The "back to regions" link used to live in this same cluster (both sat together at the header's
+ * right edge). It moved out to `WidgetRegionEditor`'s own `.page-header-lead` (2026-09-22, split
+ * header pass — see that render's own comment) because the split header needs the back link and
+ * this actions cluster on OPPOSITE rails, not adjacent — a single component can't render into two
+ * non-adjacent grid cells with the title between them without breaking DOM/tab order, so the
+ * cluster shed the one piece that had to move. */
+export declare function WidgetRegionEditorHeaderActions({ message, error, saving, onSave, t, }: {
+    message: string | null;
+    error: string | null;
+    saving: boolean;
+    onSave: () => void;
+    /** Translator closure — see `WidgetRegionEditor()`'s own `t`. Optional (identity default) since
+     *  this component is exported and unit-tested directly without one. */
+    t?: ((key: string) => string) | undefined;
+}): import("react").JSX.Element;
+//# sourceMappingURL=WidgetRegionEditorHeaderActions.d.ts.map

package/dist/widgets/react/components/WidgetRegionEditorHeaderActions.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { agentHandle } from "@jini-ai/agentic";
+/** The page header's Save-side actions cluster — the save-status message/error and the Save
+ *  button — pulled out of `WidgetRegionEditor`'s own render body as a top-level component under
+ *  the tightened ≤9/≤9 pass. Each of the three spans below is its own independent conditional (a
+ *  save succeeded, a save failed, the save is in flight); extracting the whole cluster moves all
+ *  three out of the parent's own scope at once.
+ *
+ * The "back to regions" link used to live in this same cluster (both sat together at the header's
+ * right edge). It moved out to `WidgetRegionEditor`'s own `.page-header-lead` (2026-09-22, split
+ * header pass — see that render's own comment) because the split header needs the back link and
+ * this actions cluster on OPPOSITE rails, not adjacent — a single component can't render into two
+ * non-adjacent grid cells with the title between them without breaking DOM/tab order, so the
+ * cluster shed the one piece that had to move. */
+export function WidgetRegionEditorHeaderActions({ message, error, saving, onSave, t = (key) => key, }) {
+    return (_jsxs("div", { className: "page-header-actions page-actions", children: [message ? _jsx("span", { className: "save-ok", children: message }) : null, error ? (_jsx("span", { className: "save-error", role: "alert", children: error })) : null, _jsx("button", { onClick: onSave, disabled: saving, ...agentHandle({ handle: "widget-region-editor-save" }, { role: "button", label: "Save this region's placements" }), children: saving ? t("Saving…") : t("Save") })] }));
+}
+//# sourceMappingURL=WidgetRegionEditorHeaderActions.js.map

package/dist/widgets/react/components/WidgetsLibraryNotices.d.ts

@@ -0,0 +1,13 @@
+/** The list screen's two independent notices — a fetch/action error, and malformed widget records
+ *  the server could not read — pulled out of `WidgetsLibrary`'s own render body as a top-level
+ *  component under the tightened ≤9/≤9 pass. */
+export declare function WidgetsLibraryNotices({ error, skippedCount, skippedIds, t, }: {
+    error: string | null;
+    skippedCount: number;
+    skippedIds?: string[] | undefined;
+    /** Translator closure — see `WidgetsLibrary()`'s own `t`. Optional (identity default) since this
+     *  component is exported and unit-tested directly without one — same "default to the real thing,
+     *  a stub renders English" convention every `use*Hook` prop in this app already follows. */
+    t?: ((key: string) => string) | undefined;
+}): import("react").JSX.Element;
+//# sourceMappingURL=WidgetsLibraryNotices.d.ts.map

package/dist/widgets/react/components/WidgetsLibraryNotices.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/** The list screen's two independent notices — a fetch/action error, and malformed widget records
+ *  the server could not read — pulled out of `WidgetsLibrary`'s own render body as a top-level
+ *  component under the tightened ≤9/≤9 pass. */
+export function WidgetsLibraryNotices({ error, skippedCount, skippedIds = [], t = (key) => key, }) {
+    return (_jsxs(_Fragment, { children: [error ? _jsx("div", { className: "notice error", children: error }) : null, skippedCount > 0 ? (_jsxs("div", { className: "notice", children: [skippedCount === 1
+                        ? t("1 widget record in this workspace could not be read.")
+                        : t("{n} widget records in this workspace could not be read.").replace("{n}", String(skippedCount)), skippedIds.length > 0 ? (_jsxs("details", { children: [_jsx("summary", { children: t("Show ids") }), _jsx("ul", { children: skippedIds.map((id) => _jsx("li", { children: _jsx("code", { children: id }) }, id)) })] })) : null] })) : null] }));
+}
+//# sourceMappingURL=WidgetsLibraryNotices.js.map