@jini-ai/cms 0.5.2 → 0.5.3

package/dist/widgets/resolvers/recent-entries.js

@@ -0,0 +1,165 @@
+import { getWidgetTypeRegistration } from "../registry.js";
+const NO_DISPLAY_FIELDS = [];
+/** Prefers `publishedAt`; falls back to `updatedAt` for the rare row with no `publishedAt` yet
+ *  (draft rows never reach either path — both queries filter to `status: 'published'` — but a
+ *  defensive fallback costs nothing). @complexity O(1). */
+function entryDateIso(entry) {
+    return entry.publishedAt ?? entry.updatedAt;
+}
+/** Pure display formatting for an entry's date (e.g. "Sep 3, 2026") — the same short en-US
+ *  convention `pages.ts`'s `formatPostPreviewDate` already established for post-previews/collection
+ *  cards. Duplicated rather than imported: that function is file-private and this widgets/route-layer
+ *  boundary has no barrel re-export for it, the same accepted-duplication precedent `pages.ts`'s own
+ *  `collectionEntryFieldValue` doc already documents for this exact kind of small formatting helper.
+ *  A malformed timestamp degrades to the raw ISO string rather than "Invalid Date".
+ *  @complexity O(1). */
+function formatEntryDate(iso) {
+    const parsed = new Date(iso);
+    if (Number.isNaN(parsed.getTime()))
+        return iso;
+    return parsed.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+}
+/** Legacy (no-`collection`) path: no single content type is in scope, so there is no field list to
+ *  display — matches today's rendering exactly (title only). @complexity O(1). */
+function toLegacyItemProps(entry, collectionList) {
+    const dateIso = entryDateIso(entry);
+    return { title: entry.title, href: collectionList.entryPublicHref(entry.type, entry.slug), dateIso, dateLabel: formatEntryDate(dateIso), fields: NO_DISPLAY_FIELDS };
+}
+/** Route-layer twin of `repo.sqlite.ts`'s `json_extract($.ext.site.<name>)` / `trash-aware-memory-
+ *  repo.ts`'s own private `siteFieldValue` — duplicated for the same module-boundary reason
+ *  `pages.ts`'s `collectionEntryFieldValue` already documents (no barrel re-export of either
+ *  internal helper). @complexity O(1). */
+function entryFieldValue(entry, name) {
+    const fields = entry.fieldsJson;
+    return fields?.ext?.site?.[name];
+}
+/** `collection`-path item: the content type's resolved `display.fields` (already validated/ordered
+ *  by `parseCollectionListConfig`) become this entry's shown field values.
+ *  @complexity O(f) over the displayed field count. */
+function toCollectionItemProps(entry, fields, collectionList) {
+    const dateIso = entryDateIso(entry);
+    return {
+        title: entry.title,
+        href: collectionList.entryPublicHref(entry.type, entry.slug),
+        dateIso,
+        dateLabel: formatEntryDate(dateIso),
+        fields: fields.map((f) => ({ name: f.name, label: collectionList.humanizeFieldName(f.name), kind: f.kind, value: entryFieldValue(entry, f.name) })),
+    };
+}
+const LEGACY_DEFAULT_LAYOUT = "list";
+const LEGACY_MIN_COLUMNS = 1;
+const LEGACY_MAX_COLUMNS = 6;
+const LEGACY_DEFAULT_COLUMNS = 3;
+/** Display-only, unvalidated-against-any-content-type knobs — new, additive keys an old config never
+ *  set, so absence falls back to the pre-existing visual shape (D7). `widgetLayout` applies on BOTH
+ *  paths: the widget's layout default is "list" even with `collection` set (D7), unlike the
+ *  collection marker's own "cards" default that `parseCollectionListConfig` applies.
+ *  @complexity O(1). */
+function widgetLayout(config, collectionList) {
+    return collectionList.isCollectionListLayout(config.layout) ? config.layout : LEGACY_DEFAULT_LAYOUT;
+}
+function legacyColumns(config) {
+    const raw = config.columns;
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return LEGACY_DEFAULT_COLUMNS;
+    return Math.min(Math.max(Math.floor(raw), LEGACY_MIN_COLUMNS), LEGACY_MAX_COLUMNS);
+}
+function toItemIr(props) {
+    // Cast: RecentEntryItemProps is a plain, JSON-serializable shape with no index signature of its
+    // own — same precedent as menu.ts's toMenuItemProps for ResolvedNavItem.
+    return { componentId: "entry-list-item", props: props };
+}
+function collectionKey(config) {
+    return typeof config.collection === "string" && config.collection.length > 0 ? config.collection : undefined;
+}
+/** Resolves the shared legacy-path batch query once, then slices/maps it per instance — REQ-24's
+ *  "one query per batch" contract, unchanged by this plan. @complexity O(n) over the shared result
+ *  per instance, n bounded by `registryMax`. */
+async function resolveLegacyInstances(deps, instances, workspaceId, registryMax, results) {
+    if (instances.length === 0)
+        return;
+    // Review fix 3b: SYSTEM_CONTENT_TYPES is excluded IN the query (via
+    // listByWorkspaceExcludingTypes), not filtered out of an already limit-bounded result — a batch
+    // of system rows newer than real content used to be able to fill the bounded query and leave
+    // nothing (or fewer than asked for) once filtered afterward.
+    const visible = await deps.entryList.listByWorkspaceExcludingTypes({
+        workspaceId,
+        excludeTypes: deps.collectionList.systemContentTypes,
+        status: "published",
+        orderBy: "updatedAt",
+        orderDirection: "desc",
+        limit: registryMax,
+    });
+    for (const instance of instances) {
+        const configuredMax = typeof instance.config.maxItems === "number" ? instance.config.maxItems : registryMax;
+        const max = Math.max(0, Math.min(configuredMax, registryMax));
+        const entries = visible.slice(0, max);
+        results.set(instance.id, {
+            ok: true,
+            ir: {
+                componentId: "recent-entries",
+                props: { layout: widgetLayout(instance.config, deps.collectionList), columns: legacyColumns(instance.config), typeKey: "recent-entries" },
+                children: entries.map((entry) => toItemIr(toLegacyItemProps(entry, deps.collectionList))),
+            },
+            dependencyKeys: entries.map((entry) => entry.id),
+        });
+    }
+}
+/** Resolves one `collection`-configured instance independently — each may name a different content
+ *  type/filter/sort, so (unlike the legacy path) there is no single shared query to batch across
+ *  instances. @complexity One `contentTypes.findByKey` plus, only once that and the config both
+ *  resolve, one bounded `listPublishedForDisplay` query (never an unbounded scan). */
+async function resolveCollectionInstance(deps, instance, workspaceId, registryMax, typeKey) {
+    const contentType = await deps.contentTypes.findByKey({ workspaceId, key: typeKey });
+    if (contentType === null) {
+        return { ok: false, reason: "target-disabled" };
+    }
+    const parsed = deps.collectionList.parseCollectionListConfig(instance.config, contentType, { limitKey: "maxItems", defaultSort: "updated" });
+    if (!parsed.ok) {
+        return { ok: false, reason: "invalid-config" };
+    }
+    // REQ-25 defense in depth: the parser's own ceiling (24) is wider than this registration's (20).
+    const boundedQuery = { ...parsed.query, limit: Math.min(parsed.query.limit, registryMax) };
+    const rows = await deps.entryList.listPublishedForDisplay({ workspaceId, query: boundedQuery });
+    return {
+        ok: true,
+        ir: {
+            componentId: "recent-entries",
+            // D7: the widget's own layout default is "list" — `parsed.display.layout` carries the
+            // collection MARKER's "cards" default for an absent key, so it is not used here.
+            // `structuredData` only here, never on the legacy path: that one lists mixed types, so it can
+            // never truthfully claim to be an FAQ (AW-7).
+            props: {
+                layout: widgetLayout(instance.config, deps.collectionList),
+                columns: parsed.display.columns,
+                typeKey,
+                ...(parsed.display.structuredData === undefined ? {} : { structuredData: parsed.display.structuredData }),
+            },
+            children: rows.map((row) => toItemIr(toCollectionItemProps(row, parsed.display.fields, deps.collectionList))),
+        },
+        dependencyKeys: rows.map((row) => row.id),
+    };
+}
+export function createRecentEntriesResolver(deps, _optional = {}) {
+    return {
+        async resolveMany(instances, context) {
+            // `"recent-entries"` is a literal, so `getWidgetTypeRegistration` returns THIS registration's
+            // own literal `clamps.maxItems: number` here, never the shared interface's optional form.
+            const registryMax = getWidgetTypeRegistration({ typeKey: "recent-entries" }).clamps.maxItems;
+            const results = new Map();
+            const legacyInstances = instances.filter((instance) => collectionKey(instance.config) === undefined);
+            const collectionInstances = instances.filter((instance) => collectionKey(instance.config) !== undefined);
+            await resolveLegacyInstances(deps, legacyInstances, context.workspaceId, registryMax, results);
+            // Each collection-configured instance may name a different content type/filter/sort — unlike
+            // the legacy batch above, there is no single shared query, so these resolve independently and
+            // concurrently (never one query per instance run serially).
+            await Promise.all(collectionInstances.map(async (instance) => {
+                // Safe: filtered by `collectionKey(instance.config) !== undefined` above.
+                const typeKey = collectionKey(instance.config);
+                results.set(instance.id, await resolveCollectionInstance(deps, instance, context.workspaceId, registryMax, typeKey));
+            }));
+            return results;
+        },
+    };
+}
+//# sourceMappingURL=recent-entries.js.map

package/dist/widgets/resolvers/taxonomy.d.ts

@@ -0,0 +1,12 @@
+import type { TaxonomyListPort, TermListPort } from "../../taxonomy/index.js";
+import type { PageHtmlEmbedRef } from "../html/html-embeds.js";
+import type { WidgetRenderIR } from "../types.js";
+/** Workspace-scoped read ports are supplied by the host, like the other HTML embed resolvers. */
+export declare function resolveTaxonomyEmbeds({ refs, deps }: {
+    refs: readonly PageHtmlEmbedRef[];
+    deps: {
+        taxonomyRepo?: TaxonomyListPort;
+        termRepo?: TermListPort;
+    };
+}, _optional?: {}): Promise<ReadonlyMap<string, WidgetRenderIR>>;
+//# sourceMappingURL=taxonomy.d.ts.map

package/dist/widgets/resolvers/taxonomy.js

@@ -0,0 +1,34 @@
+/** Workspace-scoped read ports are supplied by the host, like the other HTML embed resolvers. */
+export async function resolveTaxonomyEmbeds({ refs, deps }, _optional = {}) {
+    const resolved = new Map();
+    if (!deps.taxonomyRepo || !deps.termRepo)
+        return resolved;
+    const taxonomies = (await deps.taxonomyRepo.list()).filter((taxonomy) => taxonomy.status !== "trash" && taxonomy.status !== "purged");
+    const termsById = new Map();
+    for (const ref of refs) {
+        const key = ref.id;
+        if (!key)
+            continue;
+        // Names are human-readable targets, but unlike slugs are not guaranteed unique.
+        // An ambiguous name is unresolved, never an arbitrary choice; real ids win.
+        const matches = taxonomies.filter((taxonomy) => taxonomy.name === key);
+        const taxonomy = taxonomies.find((candidate) => candidate.id === key) ?? (matches.length === 1 ? matches[0] : undefined);
+        if (!taxonomy)
+            continue;
+        let terms = termsById.get(taxonomy.id);
+        if (!terms) {
+            terms = await deps.termRepo.listByTaxonomy({ taxonomyId: taxonomy.id });
+            termsById.set(taxonomy.id, terms);
+        }
+        resolved.set(key, {
+            componentId: "taxonomy-list",
+            props: {
+                id: taxonomy.id, name: taxonomy.name, hierarchical: taxonomy.hierarchical,
+                terms: terms.filter((term) => term.taxonomyId === taxonomy.id && term.status !== "trash" && term.status !== "purged")
+                    .map((term) => ({ id: term.id, name: term.name, parentId: term.parentId })),
+            },
+        });
+    }
+    return resolved;
+}
+//# sourceMappingURL=taxonomy.js.map

package/dist/widgets/sql/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./tables.js";
+export * from "./repo.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/widgets/sql/index.js

@@ -0,0 +1,3 @@
+export * from "./tables.js";
+export * from "./repo.js";
+//# sourceMappingURL=index.js.map

package/dist/widgets/sql/repo.d.ts

@@ -0,0 +1,41 @@
+import type { StorageKernel } from "@jini-ai/db/kernel";
+import type { WidgetsDatabase, WidgetsTables } from "./tables.js";
+import type { UUID } from "@jini-ai/core/primitives";
+import type { WidgetRegionBindingRepoPort } from "../ports.js";
+import type { WidgetRegionBindingRow, WidgetRegionKey } from "../types.js";
+export declare class SqlWidgetRegionBindingRepo implements WidgetRegionBindingRepoPort {
+    protected readonly kernel: StorageKernel<WidgetsDatabase>;
+    protected readonly tables: WidgetsTables;
+    constructor({ kernel, tables }: {
+        kernel: StorageKernel<WidgetsDatabase>;
+        tables: WidgetsTables;
+    }, _optional?: Record<string, never>);
+    findByRegion(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+    }): Promise<WidgetRegionBindingRow | null>;
+    listByWorkspace(required: {
+        workspaceId: UUID;
+    }): Promise<WidgetRegionBindingRow[]>;
+    upsert(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+        areaEntryId: UUID;
+        updatedAt: string;
+    }): Promise<WidgetRegionBindingRow>;
+    markInactive(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+    }): Promise<void>;
+    /** Delete-then-insert in one kernel transaction, so a reader never sees the workspace half rebuilt. */
+    rebuildForWorkspace(required: {
+        workspaceId: UUID;
+        bindings: readonly WidgetRegionBindingRow[];
+    }): Promise<void>;
+}
+/** Borrow the host kernel through this repository's narrow SQL schema view; no connection work. */
+export declare function widgetRegionBindingRepoFor<DB>({ kernel, tables }: {
+    kernel: StorageKernel<DB>;
+    tables: WidgetsTables;
+}, _optional?: Record<string, never>): SqlWidgetRegionBindingRepo;
+//# sourceMappingURL=repo.d.ts.map

package/dist/widgets/sql/repo.js

@@ -0,0 +1,82 @@
+/**
+ * @file THE durable `WidgetRegionBindingRepoPort`: one Kysely query body for every dialect the
+ * storage kernel drives (storage plan §4, ADR-066). ADR-006 rule-of-two "second adapter" half —
+ * `repo.memory.ts`'s `InMemoryWidgetRegionBindingRepo` is the first; `repo.sqlite.ts` is the thin
+ * subclass the composition root builds from the content db handle. `upsert` targets the composite
+ * `UNIQUE(workspace_id, region_key)` index (a real strengthening of INV-02 over the in-memory
+ * adapter's single-process-only guarantee).
+ *
+ * Architectural role:
+ * Infrastructure adapter. No feature logic — `region-area-service.ts` owns every write decision;
+ * this class only persists what it's told.
+ */
+function toRecord(row) {
+    return {
+        workspaceId: row.workspace_id,
+        regionKey: row.region_key,
+        areaEntryId: row.area_entry_id,
+        updatedAt: row.updated_at,
+    };
+}
+function toRow(binding) {
+    return {
+        workspace_id: binding.workspaceId,
+        region_key: binding.regionKey,
+        area_entry_id: binding.areaEntryId,
+        updated_at: binding.updatedAt,
+    };
+}
+export class SqlWidgetRegionBindingRepo {
+    kernel;
+    tables;
+    constructor({ kernel, tables }, _optional = {}) { this.kernel = kernel; this.tables = tables; }
+    async findByRegion(required) {
+        const row = await this.kernel.run((db) => db
+            .selectFrom(this.tables.regionBindings)
+            .selectAll()
+            .where("workspace_id", "=", required.workspaceId)
+            .where("region_key", "=", required.regionKey)
+            .limit(1)
+            .executeTakeFirst());
+        return row ? toRecord(row) : null;
+    }
+    async listByWorkspace(required) {
+        const rows = await this.kernel.run((db) => db.selectFrom(this.tables.regionBindings).selectAll().where("workspace_id", "=", required.workspaceId).execute());
+        return rows.map(toRecord);
+    }
+    async upsert(required) {
+        const row = {
+            workspaceId: required.workspaceId,
+            regionKey: required.regionKey,
+            areaEntryId: required.areaEntryId,
+            updatedAt: required.updatedAt,
+        };
+        await this.kernel.run((db) => db
+            .insertInto(this.tables.regionBindings)
+            .values(toRow(row))
+            .onConflict((oc) => oc.columns(["workspace_id", "region_key"]).doUpdateSet({ area_entry_id: row.areaEntryId, updated_at: row.updatedAt }))
+            .execute());
+        return row;
+    }
+    async markInactive(required) {
+        await this.kernel.run((db) => db
+            .deleteFrom(this.tables.regionBindings)
+            .where("workspace_id", "=", required.workspaceId)
+            .where("region_key", "=", required.regionKey)
+            .execute());
+    }
+    /** Delete-then-insert in one kernel transaction, so a reader never sees the workspace half rebuilt. */
+    async rebuildForWorkspace(required) {
+        await this.kernel.transaction(async () => {
+            await this.kernel.run((db) => db.deleteFrom(this.tables.regionBindings).where("workspace_id", "=", required.workspaceId).execute());
+            if (required.bindings.length === 0)
+                return;
+            await this.kernel.run((db) => db.insertInto(this.tables.regionBindings).values(required.bindings.map(toRow)).execute());
+        });
+    }
+}
+/** Borrow the host kernel through this repository's narrow SQL schema view; no connection work. */
+export function widgetRegionBindingRepoFor({ kernel, tables }, _optional = {}) {
+    return new SqlWidgetRegionBindingRepo({ kernel: kernel, tables });
+}
+//# sourceMappingURL=repo.js.map

package/dist/widgets/sql/tables.d.ts

@@ -0,0 +1,13 @@
+/** Region-binding table names are a required host choice. */
+export interface WidgetsTables {
+    regionBindings: string;
+}
+/** Local narrow SQL row; widgets never imports a host-generated database schema. */
+export interface WidgetRegionBindingsTable {
+    workspace_id: string;
+    region_key: string;
+    area_entry_id: string;
+    updated_at: string;
+}
+export type WidgetsDatabase = Record<string, WidgetRegionBindingsTable>;
+//# sourceMappingURL=tables.d.ts.map

package/dist/widgets/sql/tables.js

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

package/dist/widgets/types.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @file Core type definitions for the Tovu `widgets` library (ADR-047, SPEC-043).
+ *
+ * Purpose:
+ * Widgets are placeable, reusable, individually-configured components (a contact
+ * form, a recent-posts list, a text block, social links, a menu) placed either
+ * into a theme-declared region (an ordered list, backed by a seeded
+ * `widget_area` entry) or embedded inline inside a page's rich-text body (a
+ * `widgetEmbed` TipTap node). A widget instance is a seeded ADR-022 content
+ * entry (type `widget`), exactly as a menu is (ADR-029) — this file mirrors
+ * `navigation/types.ts` deliberately, per the ADR-047 debate's finding that the
+ * region-binding mechanism must structurally match `nav_location_bindings`
+ * (source-of-truth-on-the-entry + a derived, reconciled binding index), not
+ * merely resemble it.
+ *
+ * How it relates to the project:
+ * - `core/ports.ts` supplies the shared primitives (`UUID`, `JsonObject`, …).
+ * - `widgets/ports.ts` declares the one rule-of-two port this library adds
+ *   (`WidgetRegionBindingRepoPort`, mirroring `NavLocationBindingRepoPort`).
+ * - `widgets/registry.ts` declares the v1 widget-type registry as plain data —
+ *   see that file for why type *registration* and type *behavior* are split.
+ * - The theme renderer never resolves a widget reference itself (ADR-020 §7 /
+ *   ADR-029 §7's "theme receives resolved data" boundary, unchanged here).
+ *
+ * Architectural role:
+ * INTERFACES + TYPES ONLY (no feature logic). This is the design-frozen shape
+ * ADR-047 (as amended by its 2026-07-21 debate fold-in) introduces; the entries
+ * repo, revisions, and the command gateway are reused unchanged from ADR-022 /
+ * ADR-008.
+ */
+import type { ISODateTime, JsonObject, UUID } from "@jini-ai/core/primitives";
+/** `widget` ships as a seeded content-type registry row (ADR-022 §1), like `post`/`page`/`menu`. */
+export declare const WIDGET_CONTENT_TYPE: "widget";
+/**
+ * `widget_area` ships as a seeded, **system-managed** content-type registry
+ * row — never publicly routable, never itself placeable as a widget, never a
+ * valid `widgetEmbed` target (REQ-17 — no recursion into a region from inside
+ * a region).
+ */
+export declare const WIDGET_AREA_CONTENT_TYPE: "widget_area";
+/** The extension-field owner namespace for widget-level fields (`fields.ext.widget.*`). */
+export declare const WIDGET_FIELD_NAMESPACE: "widget";
+/** The extension-field owner namespace for a `widget_area` entry's region assignment. */
+export declare const WIDGET_AREA_FIELD_NAMESPACE: "widgets";
+/**
+ * The v1 widget-type keys (SPEC-043 REQ-09). Kept as a closed union rather than
+ * a bare `string` so a typo in a registration or a call site is a compile error,
+ * not a runtime `unknown-type` surprise.
+ */
+export type WidgetTypeKey = "text" | "social-links" | "recent-entries" | "menu" | "contact-form";
+/**
+ * A widget type's declared capability class (ADR-047 Debate Fold-In Amendment
+ * 3). `static` types render validated config directly with no resolver;
+ * `query`/`form`/`entry-reference` types have a registered resolver in the
+ * closed `CORE_RESOLVERS` map (`resolvers/index.ts`).
+ */
+export type WidgetCapability = "static" | "query" | "form" | "entry-reference";
+/** Where a widget type may legally be placed. */
+export type WidgetPlacementContext = "region" | "inline";
+/**
+ * A widget type's **registration** — plain, JSON-serializable data (SPEC-043
+ * REQ-07). Never imports or references executable behavior; the only pointer
+ * to code this record carries is `resolverId`, which must resolve *only*
+ * through the closed `CORE_RESOLVERS` map (REQ-08) — never a module path,
+ * function name, query string, or expression.
+ */
+export interface WidgetTypeRegistration {
+    readonly typeKey: WidgetTypeKey;
+    readonly capability: WidgetCapability;
+    /** JSON-Schema-shaped description of `fields.ext.widget.*`'s valid shape for this type. */
+    readonly configSchema: JsonObject;
+    readonly placementContexts: readonly WidgetPlacementContext[];
+    /** Cost clamps enforced by core at the orchestration layer, never by the resolver's own discipline (REQ-25). */
+    readonly clamps: {
+        readonly maxItems?: number;
+        readonly timeoutMs: number;
+    };
+    /** `undefined` for `static`-capability types (REQ-10). Indexes into `CORE_RESOLVERS` only. */
+    readonly resolverId?: string;
+}
+/**
+ * `purged` is observably distinct from `trash` (REQ-43): both are treated identically everywhere a
+ * widget instance's availability is checked (resolution, placement validation — see
+ * `resolver-service.ts`/`region-area-service.ts`), but only `purged` records that the instance was
+ * force-deleted past a known reference (`purgeWidgetInstance({ force: true })`), vs. an ordinary
+ * `trash` that may still be restored with no prior reference conflict. No real hard-delete exists in
+ * this codebase for any content type (`EntryRepoPort` has no delete method) — this status is the
+ * cheap, in-model way to keep that distinction visible without one.
+ *
+ * No `draft` member (Fable adversarial-review fix, 2026-07-21, Finding F) — `write-service.ts`
+ * creates every widget instance directly as `active`; nothing anywhere in this codebase ever writes
+ * `draft`. A prior version of this union carried it anyway, which was a live landmine: the
+ * resolver/placement-validation skip lists above only ever checked for `trash`/`purged`, so a
+ * `draft` status — had anything ever produced one — would have rendered publicly instead of being
+ * held back. Removed rather than defensively added to the skip lists, since there is no real
+ * "draft" concept for widget instances to guard.
+ */
+export type WidgetInstanceStatus = "active" | "trash" | "purged";
+/**
+ * A typed read model over a `type='widget'` entries row (ADR-022 §2 universal
+ * columns) plus the parsed `fields.ext.widget.*` config bag. A projection, not
+ * a new table — widget instances are entries (REQ-01).
+ */
+export interface WidgetInstanceEntry {
+    readonly id: UUID;
+    readonly workspaceId: UUID;
+    readonly slug: string;
+    readonly title: string;
+    readonly status: WidgetInstanceStatus;
+    readonly widgetType: WidgetTypeKey;
+    /** Validated against the type's registered `configSchema` on every write (REQ-02). */
+    readonly config: JsonObject;
+    readonly updatedAt: ISODateTime;
+    readonly version: number;
+}
+/** A theme-registered region key (e.g. `header`, `footer`, `sidebar`). */
+export type WidgetRegionKey = string;
+/** One entry in a `widget_area`'s ordered placement list (lives in the area entry's `bodyJson`). */
+export interface WidgetPlacementNode {
+    /** Stable ULID, minted once, preserved across reorders — for diagnostics and `entry_refs` locators. */
+    readonly placementId: UUID;
+    readonly widgetEntryId: UUID;
+    readonly enabled: boolean;
+}
+/** The full region-composition document stored in a `widget_area` entry's `bodyJson`. */
+export interface WidgetAreaDoc {
+    readonly schemaVersion: number;
+    readonly placements: readonly WidgetPlacementNode[];
+}
+/**
+ * A typed read model over a `type='widget_area'` entries row. `regionKey` is
+ * the **source of truth** for which region this area fills
+ * (`fields.ext.widgets.regionKey`) — mirrors `NavMenuEntry.locations` exactly
+ * (ADR-047 Debate Fold-In Amendment 1).
+ */
+export interface WidgetAreaEntry {
+    readonly id: UUID;
+    readonly workspaceId: UUID;
+    readonly regionKey: WidgetRegionKey;
+    readonly doc: WidgetAreaDoc;
+    readonly updatedAt: ISODateTime;
+    readonly version: number;
+}
+/**
+ * A row of the derived `widget_region_bindings` index. **Derived + rebuildable**
+ * from `WidgetAreaEntry.regionKey` at the write chokepoint (same species as
+ * `nav_location_bindings` and ADR-022 §5 `entry_refs`), NOT a source of truth
+ * and NOT revision-generating (INV-02). Reconciled by exactly one code path
+ * (`region-area-service.ts`'s `reconcileWidgetRegionBindings`) — never
+ * hand-authored.
+ */
+export interface WidgetRegionBindingRow {
+    readonly workspaceId: UUID;
+    readonly regionKey: WidgetRegionKey;
+    readonly areaEntryId: UUID;
+    readonly updatedAt: ISODateTime;
+}
+/** A theme/plugin-registered widget region (mirrors `NavLocationDescriptor`). */
+export interface WidgetRegionDescriptor {
+    readonly key: WidgetRegionKey;
+    readonly label: string;
+    readonly registeredBy: string;
+    readonly description?: string;
+}
+/**
+ * The `widgetEmbed` node's persisted shape. A block-level atom (REQ-18) — never
+ * nested inside a widget instance's own `bodyJson` (REQ-19, INV-04), enforced
+ * by `embed-validation.ts`'s `validateWidgetEmbedMutation`, the single
+ * validator both the live-editor path and the server-side/AI path call.
+ */
+export interface WidgetEmbedNode {
+    readonly type: "widgetEmbed";
+    readonly placementId: UUID;
+    readonly widgetEntryId: UUID;
+}
+/** The internal render IR node shape every resolved widget produces (ADR-020's canonical render IR). */
+export interface WidgetRenderIR {
+    readonly componentId: string;
+    readonly props: JsonObject;
+    readonly children?: readonly WidgetRenderIR[];
+}
+/** Context passed to a resolver for one page render (REQ-23). */
+export interface WidgetResolveContext {
+    readonly workspaceId: UUID;
+    readonly locale?: string;
+    readonly preview: boolean;
+}
+/** A minimal, read-only view of a widget instance passed into a resolver — never a raw DB handle (SPEC-043's REQ-24 batching contract). */
+export interface WidgetInstanceView {
+    readonly id: UUID;
+    readonly widgetType: WidgetTypeKey;
+    readonly config: JsonObject;
+}
+/** Why a widget resolution failed (SPEC-043 REQ-27's closed failure taxonomy). */
+export type WidgetResolveFailureReason = "unknown-type" | "invalid-config" | "target-disabled" | "timeout" | "resolver-error";
+export type WidgetResolveResult = {
+    readonly ok: true;
+    readonly ir: WidgetRenderIR;
+    readonly dependencyKeys: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: WidgetResolveFailureReason;
+};
+/**
+ * The typed resolver contract every dynamic (non-`static`) widget type
+ * implements (REQ-23/24). **Batch-first by design** — `resolveMany` is called
+ * at most once per type per page render (REQ-24), never once per placement, so
+ * N+1 query cost is a contract violation, not an optimization opportunity.
+ */
+export interface WidgetResolver {
+    resolveMany(instances: readonly WidgetInstanceView[], context: WidgetResolveContext): Promise<ReadonlyMap<UUID, WidgetResolveResult>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/widgets/types.js

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// Content-type identity
+// ---------------------------------------------------------------------------
+/** `widget` ships as a seeded content-type registry row (ADR-022 §1), like `post`/`page`/`menu`. */
+export const WIDGET_CONTENT_TYPE = "widget";
+/**
+ * `widget_area` ships as a seeded, **system-managed** content-type registry
+ * row — never publicly routable, never itself placeable as a widget, never a
+ * valid `widgetEmbed` target (REQ-17 — no recursion into a region from inside
+ * a region).
+ */
+export const WIDGET_AREA_CONTENT_TYPE = "widget_area";
+/** The extension-field owner namespace for widget-level fields (`fields.ext.widget.*`). */
+export const WIDGET_FIELD_NAMESPACE = "widget";
+/** The extension-field owner namespace for a `widget_area` entry's region assignment. */
+export const WIDGET_AREA_FIELD_NAMESPACE = "widgets";
+//# sourceMappingURL=types.js.map

package/dist/widgets/where-used.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file REQ-34's "where used" projection for widgets — the model-facing shape every caller that
+ * surfaces reference data renders (the widget-editor banner, the purge-blocked 409 body, the
+ * `widgets.diagnose` AI tool), so no consumer has to special-case where the data came from.
+ *
+ * Architectural role:
+ * This is a response SHAPER, not transport. It maps `entry_refs` rows — this domain's own
+ * reference-integrity index (`core/entry-refs`) — onto the disclosure vocabulary widgets speaks
+ * (`region` | `embed`). It touches no `Response`, no status code, and no error mapping; those stay
+ * in the HTTP layer.
+ *
+ * Why it lives here rather than under the HTTP admin layer, where it used to:
+ * it was the single import edge that made `widgets` depend on the composition root, and `server/`
+ * transitively reaches the whole tree — that one edge inflated this domain's transitive closure
+ * from 47 files / 7 modules to 162 files / 31 modules, which is the entire reason widgets looked
+ * unextractable. A host importing a domain's projection is the correct direction; a domain
+ * importing its host's transport module is not. Same misplacement species as
+ * `core/rate-limit/rate-limit.ts` and `features/plugin-runtime/admin-response.ts`, both already
+ * relocated. `server/http/site/page-head.ts` is the same species but NOT relocated — its own doc
+ * comment records a deliberate ADR-032 decision that the render layer, not `seo`, owns this seam,
+ * which the 2026-08-02 module-graph analysis's "page-head.ts -> seo/" suggestion did not account
+ * for; that one needs an architecture decision, not a mechanical move (2026-08-12 Refactor pass).
+ * The HTTP layer re-exports this symbol so its own consumers keep their existing import site.
+ */
+import type { EntryRefRow } from "./ports.js";
+/** One disclosed reference: which widgets-level location holds it, and where inside that source. */
+export interface WhereUsedReference {
+    /** `entry_refs` distinguishes several source kinds; widgets discloses them as exactly two. */
+    kind: "region" | "embed";
+    sourceEntryId: string;
+    fieldPath: string;
+}
+/** REQ-34's where-used disclosure shape. */
+export interface WhereUsedResponse {
+    count: number;
+    references: WhereUsedReference[];
+}
+export declare function toWhereUsedResponse({ refs }: {
+    refs: readonly EntryRefRow[];
+}, _optional?: Record<string, never>): WhereUsedResponse;
+//# sourceMappingURL=where-used.d.ts.map

package/dist/widgets/where-used.js

@@ -0,0 +1,11 @@
+export function toWhereUsedResponse({ refs }, _optional = {}) {
+    return {
+        count: refs.length,
+        references: refs.map((ref) => ({
+            kind: ref.sourceKind === "widget-embed" ? "embed" : "region",
+            sourceEntryId: ref.sourceEntryId,
+            fieldPath: ref.fieldPath,
+        })),
+    };
+}
+//# sourceMappingURL=where-used.js.map