@jini-ai/admin 0.4.2 → 0.4.3

package/dist/seo/seo.module.d.ts

@@ -0,0 +1,114 @@
+/** Cadence separates defaults, sitemap operations and one-entry edits; the form stays whole. */
+export declare const seoModule: {
+    readonly id: "seo";
+    readonly requires: {
+        readonly seoApi: import("../core/module/token.js").AdminPortToken<import("./ports.js").AdminSeoPort, "admin.seo.api">;
+    };
+    readonly optional: {
+        readonly seoEvents: import("../core/module/token.js").AdminPortToken<import("./ports.js").SeoEventsPort, "admin.seo.events">;
+        readonly mediaPicker: import("../core/module/token.js").AdminPortToken<import("../contracts/media-picker.js").MediaPickerPort, "admin.media.picker">;
+    };
+    readonly messages: {
+        readonly "Site defaults": "Site defaults";
+        readonly Sitemap: "Sitemap";
+        readonly "Pages & posts": "Pages & posts";
+        readonly "This site publishes a sitemap.": "This site publishes a sitemap.";
+        readonly "This site does not publish a sitemap. Turn it on under Site defaults.": "This site does not publish a sitemap. Turn it on under Site defaults.";
+        readonly "Loading entries\u2026": "Loading entries…";
+        readonly Entry: "Entry";
+        readonly "Choose an entry\u2026": "Choose an entry…";
+        readonly Analysis: "Analysis";
+        readonly "Score:": "Score:";
+        readonly "No issues.": "No issues.";
+        readonly "Loading entry SEO\u2026": "Loading entry SEO…";
+        readonly "Per-entry overrides": "Per-entry overrides";
+        readonly "Fields show the currently-effective value (author override, or site default, or derived from the entry). Only fields you change here are saved as overrides.": "Fields show the currently-effective value (author override, or site default, or derived from the entry). Only fields you change here are saved as overrides.";
+        readonly "Empty a field and save to remove its override \u2014 the entry falls back to the site default.": "Empty a field and save to remove its override — the entry falls back to the site default.";
+        readonly Title: "Title";
+        readonly Description: "Description";
+        readonly "Canonical URL": "Canonical URL";
+        readonly Noindex: "Noindex";
+        readonly Nofollow: "Nofollow";
+        readonly "OG title": "OG title";
+        readonly "OG description": "OG description";
+        readonly "OG image (media ref or URL)": "OG image (media ref or URL)";
+        readonly "Twitter title": "Twitter title";
+        readonly "Twitter description": "Twitter description";
+        readonly "Twitter image (media ref or URL)": "Twitter image (media ref or URL)";
+        readonly "Saving\u2026": "Saving…";
+        readonly "Save overrides": "Save overrides";
+        readonly "Per-entry SEO": "Per-entry SEO";
+        readonly "Search appearance": "Search appearance";
+        readonly "Title template (must contain %s)": "Title template (must contain %s)";
+        readonly "Default meta description": "Default meta description";
+        readonly "Social sharing": "Social sharing";
+        readonly "Default Open Graph / Twitter image (media ref)": "Default Open Graph / Twitter image (media ref)";
+        readonly "Twitter @site handle": "Twitter @site handle";
+        readonly Crawling: "Crawling";
+        readonly "Default noindex": "Default noindex";
+        readonly "Default nofollow": "Default nofollow";
+        readonly "Sitemap enabled": "Sitemap enabled";
+        readonly "Save settings": "Save settings";
+        readonly "Cached sitemap": "Cached sitemap";
+        readonly "Force-rebuild the cached sitemap now, bypassing the normal cache-hit path.": "Force-rebuild the cached sitemap now, bypassing the normal cache-hit path.";
+        readonly "Working\u2026": "Working…";
+        readonly "Regenerate sitemap": "Regenerate sitemap";
+        readonly "View sitemap": "View sitemap";
+        readonly "Loading SEO settings\u2026": "Loading SEO settings…";
+        readonly Marketing: "Marketing";
+        readonly "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.": "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.";
+        readonly "Choose image": "Choose image";
+        readonly Remove: "Remove";
+        readonly "Sitemap \u00B7 {count} URLs": "Sitemap · {count} URLs";
+        readonly "sitemap.xml \u2197": "sitemap.xml ↗";
+        readonly Table: "Table";
+        readonly "Raw XML": "Raw XML";
+        readonly "The sitemap has no URLs yet.": "The sitemap has no URLs yet.";
+        readonly "Filter sitemap URLs": "Filter sitemap URLs";
+        readonly "Filter by URL\u2026": "Filter by URL…";
+        readonly "No URLs match this filter.": "No URLs match this filter.";
+        readonly URL: "URL";
+        readonly "Last modified": "Last modified";
+        readonly "\u2014": "—";
+        readonly "Sitemap is off. Turn on \"Sitemap enabled\" above to publish one.": "Sitemap is off. Turn on \"Sitemap enabled\" above to publish one.";
+        readonly "Loading sitemap\u2026": "Loading sitemap…";
+        readonly Close: "Close";
+        readonly "failed to load entries": "failed to load entries";
+        readonly "failed to load entry SEO data": "failed to load entry SEO data";
+        readonly "Saved.": "Saved.";
+        readonly "failed to save SEO overrides": "failed to save SEO overrides";
+        readonly "failed to load SEO settings": "failed to load SEO settings";
+        readonly "failed to save SEO settings": "failed to save SEO settings";
+        readonly "Sitemap regeneration accepted.": "Sitemap regeneration accepted.";
+        readonly "failed to regenerate sitemap": "failed to regenerate sitemap";
+        readonly "failed to load the sitemap": "failed to load the sitemap";
+        readonly "Could not load the sitemap (HTTP {status}).": "Could not load the sitemap (HTTP {status}).";
+    };
+    readonly pages: {
+        readonly settings: {
+            readonly path: "/seo";
+            readonly label: "SEO";
+            readonly permissions: readonly ["admin.seo.manage"];
+            readonly agentReachable: true;
+            readonly nav: {
+                readonly group: "content";
+                readonly icon: "search";
+            };
+            readonly tabs: {
+                readonly defaults: {
+                    readonly label: "Site defaults";
+                    readonly agentReachable: true;
+                };
+                readonly sitemap: {
+                    readonly label: "Sitemap";
+                    readonly agentReachable: true;
+                };
+                readonly entries: {
+                    readonly label: "Pages & posts";
+                    readonly agentReachable: true;
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=seo.module.d.ts.map

package/dist/seo/seo.module.js

@@ -0,0 +1,14 @@
+import { defineAdminModule } from '../core/module/index.js';
+import { mediaPickerToken } from '../contracts/media-picker.js';
+import { seoApiToken, seoEventsToken } from './ports.js';
+import { seoMessagesEn } from './messages.en.js';
+/** Cadence separates defaults, sitemap operations and one-entry edits; the form stays whole. */
+export const seoModule = defineAdminModule({
+    id: 'seo', requires: { seoApi: seoApiToken }, optional: { seoEvents: seoEventsToken, mediaPicker: mediaPickerToken }, messages: seoMessagesEn,
+    pages: { settings: {
+            path: '/seo', label: 'SEO', permissions: ['admin.seo.manage'], agentReachable: true,
+            nav: { group: 'content', icon: 'search' },
+            tabs: { defaults: { label: 'Site defaults', agentReachable: true }, sitemap: { label: 'Sitemap', agentReachable: true }, entries: { label: 'Pages & posts', agentReachable: true } },
+        } },
+});
+//# sourceMappingURL=seo.module.js.map

package/dist/source-control/react/hooks/ProvidersTab.hooks.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 export declare function useProvidersTab({ permissions }: TabViewProps, _optional?: {}): {
     denied: boolean;
     loading: boolean;

package/dist/source-control/react/hooks/ProvidersTab.hooks.js

@@ -1,4 +1,4 @@
-import { useController } from '../../../react/use-controller.js';
+import { useController } from '../../../core/react/use-controller.js';
 import { createSourceControlController } from '../../controllers/source-control.controller.js';
 import { blankSourceControlDraft, sourceControlProviders, defaultSourceControlCredential, sourceControlReady, safeSourceControlUrl } from '../../rules.js';
 import { useSourceControlPorts } from './SourceControlPorts.hooks.js';

package/dist/source-control/react/hooks/SourceControlPage.hooks.d.ts

@@ -1,4 +1,4 @@
-import type { ModulePageProps } from '../../../react/bind-react.js';
+import type { ModulePageProps } from '../../../core/react/bind-react.js';
 export declare function useSourceControlPage(props: ModulePageProps, _optional?: {}): {
     denied: boolean;
     ActiveTab: import("react").LazyExoticComponent<import("react").ComponentType<import("../../../react/bind-react.js").TabViewProps>> | undefined;

package/dist/source-control/react/index.js

@@ -1,4 +1,4 @@
-import { bindReact } from '../../react/bind-react.js';
+import { bindReact } from '../../core/react/bind-react.js';
 import { sourceControlModule } from '../source-control.module.js';
 import { SourceControlPortsContext } from './hooks/SourceControlPorts.hooks.js';
 export { useSourceControlPorts } from './hooks/SourceControlPorts.hooks.js';

package/dist/source-control/react/pages/SourceControlPage.d.ts

@@ -1,4 +1,4 @@
-import type { ModulePageProps } from '../../../react/bind-react.js';
+import type { ModulePageProps } from '../../../core/react/bind-react.js';
 export declare function SourceControlPage(props: ModulePageProps, _optional?: {}): import("react").JSX.Element;
 export default SourceControlPage;
 //# sourceMappingURL=SourceControlPage.d.ts.map

package/dist/source-control/react/tabs/ProvidersTab.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 export declare function ProvidersTab(props: TabViewProps, _optional?: {}): import("react").JSX.Element;
 export default ProvidersTab;
 //# sourceMappingURL=ProvidersTab.d.ts.map

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

@@ -0,0 +1,19 @@
+import type { AdminWidgetsPort } from '../ports.js';
+import type { WidgetsRequestOptions } from '../models.js';
+/** Host owns auth, JSON serialization, request deadlines/retries, and status/error decoding. */
+export interface WidgetsTransportPort {
+    request<T>(required: {
+        path: string;
+        method: 'GET' | 'POST' | 'PUT';
+        body?: unknown | undefined;
+    }, optional?: WidgetsRequestOptions | undefined): Promise<T>;
+    url(required: {
+        path: string;
+    }, optional?: Record<string, never> | undefined): string;
+}
+/** basePath is the host workspace root; the adapter adds /widgets and the shared /trash/items. */
+export declare function createHttpWidgetsApi({ transport, basePath }: {
+    transport: WidgetsTransportPort;
+    basePath: string;
+}, _optional?: Record<string, never>): AdminWidgetsPort;
+//# sourceMappingURL=http.d.ts.map

package/dist/widgets/adapters/http.js

@@ -0,0 +1,33 @@
+/** basePath is the host workspace root; the adapter adds /widgets and the shared /trash/items. */
+export function createHttpWidgetsApi({ transport, basePath }, _optional = {}) {
+    const root = basePath.replace(/\/$/, '');
+    const base = `${root}/widgets`;
+    const request = (path, method, body, options) => {
+        options.signal?.throwIfAborted();
+        return transport.request({ path, method, ...(body === undefined ? {} : { body }) }, options);
+    };
+    return {
+        listWidgets({ widgetType, includeInactive }, options = {}) {
+            const query = new URLSearchParams();
+            if (widgetType)
+                query.set('widgetType', widgetType);
+            if (includeInactive)
+                query.set('includeInactive', 'true');
+            const suffix = query.toString();
+            return request(`${base}${suffix ? `?${suffix}` : ''}`, 'GET', undefined, options);
+        },
+        getWidget({ id }, options = {}) { return request(`${base}/${encodeURIComponent(id)}`, 'GET', undefined, options); },
+        createWidget(input, options = {}) { return request(base, 'POST', input, options); },
+        updateWidget({ id, baseVersion, config, title }, options = {}) {
+            return request(`${base}/${encodeURIComponent(id)}`, 'PUT', { baseVersion, config, ...(title === undefined ? {} : { title }) }, options);
+        },
+        trashWidget({ id }, options = {}) { return request(`${root}/trash/items`, 'POST', { type: 'widget', id }, options); },
+        listWidgetRegions(_required, options = {}) { return request(`${base}/regions`, 'GET', undefined, options); },
+        bindWidgetRegion({ regionKey }, options = {}) { return request(`${base}/regions`, 'POST', { regionKey }, options); },
+        getWidgetRegion({ regionKey }, options = {}) { return request(`${base}/regions/${encodeURIComponent(regionKey)}`, 'GET', undefined, options); },
+        mutateWidgetRegionPlacements({ regionKey, baseVersion, placements }, options = {}) {
+            return request(`${base}/regions/${encodeURIComponent(regionKey)}`, 'PUT', { baseVersion, placements }, options);
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

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

@@ -0,0 +1,22 @@
+import type { AdminWidgetsPort } from '../ports.js';
+import type { AdminWidget, AdminWidgetArea, AdminWidgetPlacement, AdminWidgetRegionBinding, AdminWidgetWhereUsed } from '../models.js';
+export interface MemoryWidgetsSeed {
+    widgets?: AdminWidget[] | undefined;
+    regions?: AdminWidgetRegionBinding[] | undefined;
+    areas?: Record<string, {
+        area: AdminWidgetArea;
+        placements: AdminWidgetPlacement[];
+    }> | undefined;
+    whereUsed?: Record<string, AdminWidgetWhereUsed> | undefined;
+    skippedCount?: number | undefined;
+    skippedIds?: string[] | undefined;
+}
+/** JSON-shaped port snapshots are detached; mutable fixture arrays are explicit on the returned adapter. */
+export declare function createMemoryWidgetsApi({ widgets, regions, areas, whereUsed, skippedCount, skippedIds }?: MemoryWidgetsSeed, { workspaceId, now }?: {
+    workspaceId?: string | undefined;
+    now?: (() => string) | undefined;
+}): AdminWidgetsPort & {
+    readonly widgets: AdminWidget[];
+    readonly regions: AdminWidgetRegionBinding[];
+};
+//# sourceMappingURL=memory.d.ts.map

package/dist/widgets/adapters/memory.js

@@ -0,0 +1,93 @@
+import { AdminApiError } from '../../core/transport/errors.js';
+/** JSON-shaped port snapshots are detached; mutable fixture arrays are explicit on the returned adapter. */
+export function createMemoryWidgetsApi({ widgets = [], regions = [], areas = {}, whereUsed = {}, skippedCount, skippedIds } = {}, { workspaceId = 'fake-ws', now = () => new Date(0).toISOString() } = {}) {
+    const copy = (value) => structuredClone(value);
+    const rows = copy(widgets), bindings = copy(regions), regionRows = new Map(Object.entries(copy(areas)));
+    const usage = copy(whereUsed);
+    let widgetSequence = rows.length, areaSequence = Math.max(bindings.length, regionRows.size);
+    function fail(code, message) { throw new AdminApiError({ message, status: code === 'NOT_FOUND' ? 404 : 409 }, { code }); }
+    function instance(id) {
+        const index = rows.findIndex(w => w.slug === id);
+        const resolved = index < 0 ? rows.findIndex(w => w.id === id) : index;
+        if (resolved < 0)
+            return fail('NOT_FOUND', `fake widget not found: ${id}`);
+        return { index: resolved, widget: rows[resolved] };
+    }
+    function region(regionKey) {
+        const result = regionRows.get(regionKey);
+        return result ?? fail('NOT_FOUND', `fake widget region not found: ${regionKey}`);
+    }
+    return {
+        widgets: rows, regions: bindings,
+        async listWidgets({ widgetType, includeInactive }, options = {}) {
+            options.signal?.throwIfAborted();
+            return { widgets: copy(rows.filter(w => (!widgetType || w.widgetType === widgetType) && (includeInactive || w.status === 'active'))), ...(skippedCount === undefined ? {} : { skippedCount }), ...(skippedIds === undefined ? {} : { skippedIds: copy(skippedIds) }) };
+        },
+        async getWidget({ id }, options = {}) {
+            options.signal?.throwIfAborted();
+            const { widget } = instance(id);
+            return copy({ widget, whereUsed: usage[widget.id] ?? { count: 0, references: [] } });
+        },
+        async createWidget(input, options = {}) {
+            options.signal?.throwIfAborted();
+            let id;
+            do {
+                id = `fake-${++widgetSequence}`;
+            } while (rows.some(w => w.id === id || w.slug === `fake-slug-${widgetSequence}`));
+            const widget = { id, workspaceId, slug: `fake-slug-${widgetSequence}`, title: input.title, status: 'active', widgetType: input.widgetType, config: copy(input.config), updatedAt: now(), version: 1 };
+            rows.push(widget);
+            return { widget: copy(widget) };
+        },
+        async updateWidget({ id, baseVersion, config, title }, options = {}) {
+            options.signal?.throwIfAborted();
+            const { index, widget } = instance(id);
+            if (widget.version !== baseVersion)
+                fail('WIDGETS_VERSION_CONFLICT', 'Widget version conflict');
+            const updated = { ...widget, config: copy(config), title: title ?? widget.title, updatedAt: now(), version: widget.version + 1 };
+            rows[index] = updated;
+            return { widget: copy(updated) };
+        },
+        async trashWidget({ id }, options = {}) {
+            options.signal?.throwIfAborted();
+            const { index, widget } = instance(id);
+            // Shared Trash owns restoration and permanent removal; this API only moves status.
+            rows[index] = { ...widget, status: 'trash', version: widget.version + 1, updatedAt: now() };
+            return { ok: true, version: rows[index].version };
+        },
+        async listWidgetRegions(_required, options = {}) { options.signal?.throwIfAborted(); return { regions: copy(bindings) }; },
+        async bindWidgetRegion({ regionKey }, options = {}) {
+            options.signal?.throwIfAborted();
+            if (regionRows.has(regionKey) || bindings.some(b => b.regionKey === regionKey))
+                fail('WIDGETS_REGION_BOUND', 'Region already bound');
+            let id;
+            do {
+                id = `fake-area-${++areaSequence}`;
+            } while (bindings.some(b => b.areaEntryId === id) || [...regionRows.values()].some(r => r.area.id === id));
+            const area = { id, workspaceId, regionKey, updatedAt: now(), version: 1 };
+            bindings.push({ workspaceId, regionKey, areaEntryId: id, updatedAt: area.updatedAt, placementCount: 0 });
+            regionRows.set(regionKey, { area, placements: [] });
+            return { area: copy(area) };
+        },
+        async getWidgetRegion({ regionKey }, options = {}) { options.signal?.throwIfAborted(); return copy(region(regionKey)); },
+        async mutateWidgetRegionPlacements({ regionKey, baseVersion, placements }, options = {}) {
+            options.signal?.throwIfAborted();
+            const entry = region(regionKey);
+            if (entry.area.version !== baseVersion)
+                fail('WIDGETS_AREA_CONFLICT', 'Region version conflict');
+            const area = { ...entry.area, version: entry.area.version + 1, updatedAt: now() };
+            // Ordered rows retain identity and allow repeated widget refs; broken refs stay visible.
+            const saved = placements.map(p => {
+                const widget = rows.find(w => w.id === p.widgetEntryId && w.status === 'active');
+                return { ...p, widgetTitle: widget?.title ?? null, widgetType: widget?.widgetType ?? null, broken: !widget };
+            });
+            regionRows.set(regionKey, { area, placements: saved });
+            const binding = bindings.find(b => b.regionKey === regionKey);
+            if (binding) {
+                binding.placementCount = saved.length;
+                binding.updatedAt = area.updatedAt;
+            }
+            return { area: copy(area) };
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/widgets/conformance/widgets-api.conformance.d.ts

@@ -0,0 +1,6 @@
+import type { AdminWidgetsPort } from '../ports.js';
+/** Mutates an isolated adapter. Returns named checks and throws at the first contract failure. */
+export declare function runWidgetsApiConformance({ api }: {
+    api: AdminWidgetsPort;
+}, _optional?: Record<string, never>): Promise<readonly string[]>;
+//# sourceMappingURL=widgets-api.conformance.d.ts.map

package/dist/widgets/conformance/widgets-api.conformance.js

@@ -0,0 +1,55 @@
+/** Mutates an isolated adapter. Returns named checks and throws at the first contract failure. */
+export async function runWidgetsApiConformance({ api }, _optional = {}) {
+    const checks = [];
+    function assert(condition, name) { if (!condition)
+        throw new Error(`Widgets API conformance: ${name}`); checks.push(name); }
+    async function rejects(run, name) { let rejected = false; try {
+        await run();
+    }
+    catch {
+        rejected = true;
+    } assert(rejected, name); }
+    const input = { widgetType: 'text', title: 'Conformance widget', config: { body: 'initial' } };
+    const { widget } = await api.createWidget(input);
+    assert(widget.id.length > 0 && widget.slug.length > 0 && widget.status === 'active', 'create active instance');
+    input.config.body = 'caller changed';
+    assert((await api.getWidget({ id: widget.id })).widget.config.body === 'initial', 'create copies config input');
+    assert((await api.getWidget({ id: widget.slug })).widget.id === widget.id, 'get resolves slug or id');
+    const firstList = await api.listWidgets({});
+    assert(firstList.widgets.some(w => w.id === widget.id), 'active list includes created instance');
+    assert((await api.listWidgets({ widgetType: 'social-links' })).widgets.every(w => w.widgetType === 'social-links'), 'type filter');
+    const { widget: updated } = await api.updateWidget({ id: widget.id, baseVersion: widget.version, config: { body: 'updated' } });
+    assert(updated.title === widget.title && updated.version > widget.version, 'omitted title preserved and version advances');
+    assert(widget.config.body === 'initial' && firstList.widgets.find(w => w.id === widget.id)?.version === widget.version, 'prior snapshots stay detached');
+    await rejects(() => api.updateWidget({ id: widget.id, baseVersion: widget.version, config: {} }), 'stale instance write rejects');
+    const regionKey = `conformance-${widget.id}`;
+    const { area } = await api.bindWidgetRegion({ regionKey });
+    const initialAreaVersion = area.version;
+    assert((await api.listWidgetRegions({})).regions.some(r => r.regionKey === regionKey), 'bound region listed');
+    assert((await api.getWidgetRegion({ regionKey })).placements.length === 0, 'new region empty');
+    const placements = [
+        { placementId: 'p-one', widgetEntryId: widget.id, enabled: false },
+        { placementId: 'p-two', widgetEntryId: widget.id, enabled: true },
+        { placementId: 'p-broken', widgetEntryId: 'missing-conformance-widget', enabled: true },
+    ];
+    const { area: savedArea } = await api.mutateWidgetRegionPlacements({ regionKey, baseVersion: area.version, placements });
+    assert(savedArea.version > area.version && area.version === initialAreaVersion, 'region version advances without mutating old snapshot');
+    const placed = await api.getWidgetRegion({ regionKey });
+    assert(placed.placements.map(p => p.placementId).join() === placements.map(p => p.placementId).join(), 'ordered placement identities and repeated refs retained');
+    assert(placed.placements[0]?.enabled === false && placed.placements[1]?.widgetTitle === updated.title, 'placement enabled and title projection');
+    assert(placed.placements[2]?.broken === true, 'broken reference remains visible');
+    assert((await api.listWidgetRegions({})).regions.find(r => r.regionKey === regionKey)?.placementCount === placements.length, 'region list placement count updates');
+    await rejects(() => api.mutateWidgetRegionPlacements({ regionKey, baseVersion: area.version, placements: [] }), 'stale region write rejects');
+    const abort = new AbortController();
+    abort.abort();
+    await rejects(() => api.listWidgets({}, { signal: abort.signal }), 'aborted list rejects');
+    await rejects(() => api.updateWidget({ id: widget.id, baseVersion: updated.version, title: 'must not save', config: {} }, { signal: abort.signal }), 'aborted write rejects');
+    assert((await api.getWidget({ id: widget.id })).widget.title === widget.title, 'aborted write has no effects');
+    await rejects(() => api.getWidget({ id: 'missing-conformance-widget' }), 'missing instance rejects');
+    await rejects(() => api.getWidgetRegion({ regionKey: 'missing-conformance-region' }), 'missing region rejects');
+    await api.trashWidget({ id: widget.id });
+    assert(!(await api.listWidgets({})).widgets.some(w => w.id === widget.id), 'trash removes active listing');
+    assert((await api.listWidgets({ includeInactive: true })).widgets.find(w => w.id === widget.id)?.status === 'trash', 'trash retained for shared lifecycle');
+    return checks;
+}
+//# sourceMappingURL=widgets-api.conformance.js.map

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

@@ -0,0 +1,49 @@
+import type { AdminWidgetsPort } from '../ports.js';
+import type { AdminWidget, AdminWidgetWhereUsed, AdminWidgetType, WidgetsTranslate, WidgetEditorParams, WidgetSlugRedirectPath } from '../models.js';
+export interface WidgetInstanceEditorState {
+    isNew: boolean;
+    widget: AdminWidget | null;
+    whereUsed: AdminWidgetWhereUsed;
+    title: string;
+    config: Record<string, unknown>;
+    message: string | null;
+    error: string | null;
+    fieldErrors: Array<{
+        field: string;
+        reason: string;
+    }>;
+    loading: boolean;
+    saving: boolean;
+    widgetType: AdminWidgetType | null | undefined;
+}
+/** Editor identity includes both route params. Reads and saves cannot overwrite a different editor. */
+export declare function createWidgetInstanceEditorController({ api, params: initialParams, defaultConfig }: {
+    api: AdminWidgetsPort;
+    params: WidgetEditorParams;
+    defaultConfig: (type: AdminWidgetType) => Record<string, unknown>;
+}, { t, navigate, slugRedirectPath, getEntityKey }?: {
+    t?: WidgetsTranslate | undefined;
+    navigate?: ((path: string, options?: {
+        replace?: boolean;
+    }) => void) | undefined;
+    slugRedirectPath?: WidgetSlugRedirectPath | undefined;
+    getEntityKey?: (() => string) | undefined;
+}): {
+    getSnapshot: () => Readonly<WidgetInstanceEditorState>;
+    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>;
+    setParams({ params: next }: {
+        params: WidgetEditorParams;
+    }, _optional?: Record<string, never>): void;
+    setTitle({ title }: {
+        title: string;
+    }, _optional?: Record<string, never>): void;
+    setConfig({ config }: {
+        config: Record<string, unknown>;
+    }, _optional?: Record<string, never>): void;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+//# sourceMappingURL=instance-editor.controller.d.ts.map

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

@@ -0,0 +1,87 @@
+import { createControllerStore } from '../../core/module/controller-store.js';
+import { describeApiError } from '../../core/transport/errors.js';
+import { resolveEditorWidgetType, resolveWidgetSaveError, widgetApiError, widgetSlugRedirectPath, widgetEntityKey } from '../rules.js';
+import { widgetsEnglish } from '../messages.en.js';
+/** Editor identity includes both route params. Reads and saves cannot overwrite a different editor. */
+export function createWidgetInstanceEditorController({ api, params: initialParams, defaultConfig }, { t = widgetsEnglish, navigate, slugRedirectPath, getEntityKey } = {}) {
+    let params = initialParams;
+    const key = () => widgetEntityKey({ params });
+    const currentKey = () => getEntityKey?.() ?? activeKey;
+    let activeKey = key(), generation = 0;
+    const isNew = params.widgetId === null;
+    const store = createControllerStore({ initial: {
+            isNew, widget: null, whereUsed: { count: 0, references: [] }, title: '',
+            config: isNew ? defaultConfig(params.widgetType ?? 'text') : {}, message: null, error: null, fieldErrors: [],
+            loading: !isNew, saving: false, widgetType: resolveEditorWidgetType({ isNew, queryWidgetType: params.widgetType, widget: null }),
+        } });
+    async function load(_required = {}, _optional = {}) {
+        const ticket = ++generation;
+        const isNew = params.widgetId === null;
+        store.set({ patch: { isNew, saving: false } });
+        if (isNew) {
+            store.set({ patch: { widget: null, title: '', config: defaultConfig(params.widgetType ?? 'text'), whereUsed: { count: 0, references: [] }, loading: false, widgetType: params.widgetType } });
+            return;
+        }
+        const requestedId = params.widgetId;
+        store.set({ patch: { loading: true, error: null } });
+        try {
+            const result = await api.getWidget({ id: requestedId }, { signal: store.signal });
+            if (ticket !== generation || store.signal.aborted)
+                return;
+            store.set({ patch: { widget: result.widget, title: result.widget.title, config: result.widget.config, whereUsed: result.whereUsed, widgetType: result.widget.widgetType } });
+            // Replace rather than push: an old id bookmark should not add a Back-button stop.
+            const redirect = widgetSlugRedirectPath({ requestedId, widget: result.widget }, { slugRedirectPath });
+            if (redirect)
+                navigate?.(redirect, { replace: true });
+        }
+        catch (error) {
+            if (ticket === generation && !store.signal.aborted)
+                store.set({ patch: { error: describeApiError({ e: widgetApiError({ error }) ?? error, fallback: t('failed to load widget') }) } });
+        }
+        finally {
+            if (ticket === generation && !store.signal.aborted)
+                store.set({ patch: { loading: false } });
+        }
+    }
+    async function save(_required = {}, _optional = {}) {
+        const { widgetType, isNew, widget, title, config } = store.getSnapshot();
+        if (!widgetType)
+            return;
+        const savingFor = currentKey();
+        store.set({ patch: { saving: true, message: null, error: null, fieldErrors: [] } });
+        try {
+            if (isNew) {
+                const { widget: created } = await api.createWidget({ widgetType, title, config }, { signal: store.signal });
+                // Creation intentionally navigates even if route identity changed while it was in flight.
+                navigate?.(`/widgets/${created.slug}`);
+                return;
+            }
+            if (!widget)
+                return;
+            const { widget: saved } = await api.updateWidget({ id: widget.id, baseVersion: widget.version, title, config }, { signal: store.signal });
+            if (currentKey() !== savingFor || store.signal.aborted)
+                return;
+            store.set({ patch: { widget: saved, title: saved.title, config: saved.config, widgetType: saved.widgetType, message: t('Saved · version {version}').replace('{version}', String(saved.version)) } });
+        }
+        catch (error) {
+            if (currentKey() === savingFor && !store.signal.aborted)
+                store.set({ patch: resolveWidgetSaveError({ error }, { t }) });
+        }
+        finally {
+            if (currentKey() === savingFor && !store.signal.aborted)
+                store.set({ patch: { saving: false } });
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, load, save,
+        setParams({ params: next }, _optional = {}) {
+            params = next;
+            activeKey = key();
+            void load();
+        },
+        setTitle({ title }, _optional = {}) { store.set({ patch: { title } }); },
+        setConfig({ config }, _optional = {}) { store.set({ patch: { config } }); },
+        dispose(_required = {}, _optional = {}) { generation++; activeKey = ''; store.dispose(); },
+    };
+}
+//# sourceMappingURL=instance-editor.controller.js.map

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

@@ -0,0 +1,33 @@
+import type { AdminWidgetsPort } from '../ports.js';
+import type { AdminWidget, AdminWidgetType, WidgetsTranslate } from '../models.js';
+export interface WidgetsLibraryState {
+    widgets: AdminWidget[] | null;
+    error: string | null;
+    skippedCount: number;
+    skippedIds: string[];
+    createType: AdminWidgetType;
+    pendingTrash: AdminWidget | null;
+    trashingId: string | null;
+}
+/** Active-only library. Latest read wins across mount, refresh and write-triggered reads. */
+export declare function createWidgetsLibraryController({ api }: {
+    api: AdminWidgetsPort;
+}, { t }?: {
+    t?: WidgetsTranslate | undefined;
+}): {
+    getSnapshot: () => Readonly<WidgetsLibraryState>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    load: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    confirmTrash: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    setCreateType({ type }: {
+        type: AdminWidgetType;
+    }, _optional?: Record<string, never>): void;
+    requestTrash({ widget }: {
+        widget: AdminWidget;
+    }, _optional?: Record<string, never>): void;
+    cancelTrash(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+//# sourceMappingURL=library.controller.d.ts.map

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

@@ -0,0 +1,53 @@
+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';
+/** Active-only library. Latest read wins across mount, refresh and write-triggered reads. */
+export function createWidgetsLibraryController({ api }, { t = widgetsEnglish } = {}) {
+    const store = createControllerStore({ initial: { widgets: null, error: null, skippedCount: 0, skippedIds: [], createType: 'text', pendingTrash: null, trashingId: null } });
+    let generation = 0;
+    async function load(_required = {}, _optional = {}) {
+        const ticket = ++generation;
+        try {
+            // No includeInactive: trashed widgets belong to the shared Trash screen.
+            const result = await api.listWidgets({}, { signal: store.signal });
+            if (ticket !== generation || store.signal.aborted)
+                return;
+            store.set({ patch: { widgets: result.widgets, skippedCount: result.skippedCount ?? 0, skippedIds: result.skippedIds ?? [] } });
+        }
+        catch (e) {
+            if (ticket === generation && !store.signal.aborted)
+                store.set({ patch: { error: describeApiError({ e: widgetApiError({ error: e }) ?? e, fallback: t('failed to load widgets') }) } });
+        }
+    }
+    async function confirmTrash(_required = {}, _optional = {}) {
+        const widget = store.getSnapshot().pendingTrash;
+        if (!widget)
+            return;
+        store.set({ patch: { trashingId: widget.id, error: null } });
+        try {
+            await api.trashWidget({ id: widget.id }, { signal: store.signal });
+            void load();
+        }
+        catch (error) {
+            const e = widgetApiError({ error });
+            if (e?.code === 'NOT_FOUND')
+                void load();
+            else
+                store.set({ patch: { error: e?.code === 'TRASH_VERSION_CHANGED' ? t('This item changed since you loaded it. Reload and try again.') : describeApiError({ e: e ?? error, fallback: t('delete failed') }) } });
+        }
+        finally {
+            // A's completion cannot close a newly opened confirmation for B.
+            const current = store.getSnapshot();
+            store.set({ patch: { trashingId: current.trashingId === widget.id ? null : current.trashingId, pendingTrash: current.pendingTrash?.id === widget.id ? null : current.pendingTrash } });
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, load, confirmTrash,
+        setCreateType({ type }, _optional = {}) { store.set({ patch: { createType: type } }); },
+        requestTrash({ widget }, _optional = {}) { store.set({ patch: { error: null, pendingTrash: widget } }); },
+        cancelTrash(_required = {}, _optional = {}) { store.set({ patch: { pendingTrash: null } }); },
+        dispose(_required = {}, _optional = {}) { generation++; store.dispose(); },
+    };
+}
+//# sourceMappingURL=library.controller.js.map