@jini-ai/cms 0.5.2 → 0.5.4

package/dist/widgets/resolver-service.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @file `resolvePageWidgets` — the batch-first page-render resolution orchestrator (SPEC-043
+ * REQ-23..28; ADR-047 Debate Fold-In Amendment 2).
+ *
+ * Purpose:
+ * The single seam that turns "a page's widget references" (region-bound + inline-embedded) into
+ * data the theme can render — one batched entry-load query, grouped by type, at most one
+ * `resolveWidgetType` call per type present on the page (REQ-24). Mirrors the `render.ts` "theme is
+ * data, core resolves" stance — the theme never calls this directly or resolves a reference itself.
+ *
+ * `EntryRepoPort` (this task's frozen, real chokepoint contract) has no `findByIds`/batch-by-id
+ * primitive — only `findById` (one row) and `EntryListPort.listByWorkspace` (a full-type scan).
+ * REQ-24's "one batched query" is satisfied here via ONE `listByWorkspace({workspaceId}, {type: 'widget'})` call
+ * per render (not one query per placement/type), which is the batching guarantee AC-16 actually
+ * tests (via `resolveWidgetType`'s single-`resolveMany`-call assertion) — a literal `WHERE id IN
+ * (...)` primitive does not exist on the real, frozen `EntryRepoPort` this task must compose
+ * against without modifying `features/entries`.
+ *
+ * Architectural role:
+ * `widgets` domain logic (implementation outline C-004).
+ */
+import type { JsonObject, UUID } from "@jini-ai/core/primitives";
+import type { EntryListPort, EntryRepoPort } from "../entries/index.js";
+import type { WidgetHostPorts, PostRepoPort, MediaContentTypeStorePort } from "./host-ports.js";
+import type { MediaRepoPort, TransformDefinitionRepoPort } from "../media/index.js";
+import type { TaxonomyListPort, TermListPort } from "../taxonomy/index.js";
+import type { PageHtmlEmbedRef } from "./html/html-embeds.js";
+import type { WidgetRegionBindingRepoPort } from "./ports.js";
+import type { WidgetRegionKey, WidgetRenderIR, WidgetResolveContext } from "./types.js";
+export interface ResolvePageWidgetsDeps {
+    bindingRepo: WidgetRegionBindingRepoPort;
+    entryRepo: EntryRepoPort & EntryListPort;
+}
+/**
+ * The narrower dependency slice widget-instance resolution alone needs — `resolveWidgetInstances`
+ * and `resolveHtmlPageEmbeds` (below) never touch `bindingRepo` (that repo only backs region
+ * placements, which an `"html"`-format Page has no concept of). `ResolvePageWidgetsDeps` remains a
+ * structural supertype of this, so `resolvePageWidgets` passes its own full deps through unchanged.
+ */
+type WidgetInstanceResolutionDeps = Pick<ResolvePageWidgetsDeps, "entryRepo">;
+export interface ResolvePageWidgetsInput {
+    readonly workspaceId: UUID;
+    /**
+     * The already-fetched host document's `bodyJson`, when the caller has one to scan for inline
+     * `widgetEmbed` nodes (REQ-21) — e.g. a `PostRecord.bodyJson` on the `home`/`post` site routes.
+     * Passed as content rather than an id-to-fetch (unlike the old `pageEntryId` this replaces)
+     * because the only real callers already hold the document: `PostRecord` (`features/post`) is a
+     * separate, pre-ADR-022 table an `EntryRepoPort.findById` call can never resolve, which is why
+     * `pageEntryId` had no real caller and every `widgetEmbed` node in a post body rendered the
+     * REQ-28 placeholder forever, never real content. `undefined` when there is no host document
+     * (the home route) or nothing to scan.
+     */
+    readonly pageBodyJson?: unknown;
+    /** Region keys the current theme/template declares for this page. */
+    readonly resolvedRegions: readonly WidgetRegionKey[];
+}
+export interface ResolvePageWidgetsRequired {
+    deps: ResolvePageWidgetsDeps;
+    input: ResolvePageWidgetsInput;
+}
+export interface ResolvePageWidgetsResult {
+    readonly regions: Readonly<Record<WidgetRegionKey, readonly WidgetRenderIR[]>>;
+    /** Keyed by `placementId` — one entry per `widgetEmbed` node in the page's `bodyJson`. */
+    readonly inlineResolved: ReadonlyMap<UUID, WidgetRenderIR>;
+}
+export declare function resolvePageWidgets(required: ResolvePageWidgetsRequired, _optional?: Record<string, never>): Promise<ResolvePageWidgetsResult>;
+/**
+ * One embed type's resolver: given every {@link PageHtmlEmbedRef} of that type found on the page,
+ * resolve as many as possible into a map keyed by the referenced id. A ref whose `id` is `null`
+ * (missing or out-of-bounds `id` key in the marker config) can never be resolved — a resolver skips it and should
+ * log a resolver-internal miss (see `HTML_EMBED_RESOLVERS`'s own doc for why this is a DIFFERENT log
+ * line from "unknown embed type"). The returned map's "present-with-placeholder-vs-absent" shape
+ * (a genuinely nonexistent target is ABSENT; a found-but-broken target is PRESENT with a placeholder
+ * IR) mirrors {@link resolveWidgetInstances}'s own convention — both render identically via
+ * `render.ts`'s `renderHtmlPageBody`, so this is not a behavior bug, same as the pre-restructuring
+ * `widgetResolved`/`formResolved` shape this replaces.
+ */
+/**
+ * `resolveHtmlPageEmbeds`'s full dependency set — a structural superset of
+ * {@link WidgetInstanceResolutionDeps} (the `widget` resolver's own narrower need) plus the
+ * OPTIONAL `mediaRepo`/`transformRepo` pair the `media` resolver needs. Optional, not required
+ * (mirrors `PagesHtmlDocumentStoreDeps.entryRefsRepo`'s own "optional dependency" precedent), so
+ * every pre-existing widget-only call site and test keeps compiling and behaving unchanged; a
+ * `media` embed present with no `mediaRepo`/`transformRepo` supplied simply cannot resolve (logged,
+ * degrades to the REQ-28 placeholder like any other unresolved reference) rather than forcing every
+ * call site that never touches media to thread media dependencies through anyway.
+ */
+export interface ResolveHtmlPageEmbedsDeps extends WidgetInstanceResolutionDeps {
+    readonly host: Pick<WidgetHostPorts, "media" | "posts">;
+    readonly mediaRepo?: MediaRepoPort;
+    readonly transformRepo?: TransformDefinitionRepoPort;
+    readonly postRepo?: PostRepoPort;
+    readonly taxonomyRepo?: TaxonomyListPort;
+    readonly termRepo?: TermListPort;
+    /**
+     * Video/embed capability (2026-08-24) — optional, same "degrade gracefully when absent" contract
+     * `mediaRepo`/`transformRepo` already have. When present, {@link resolveMediaTypeEmbeds} uses it
+     * to tell a video asset from an image one (keyed by `MediaRecord.source.sha256`, the same key
+     * `routes/admin/media/upload.ts` already records under). Absent (every pre-existing call site
+     * before this feature, and any future one that never touches media) means every asset resolves as
+     * an image exactly as it always has — this is additive, not a behavior change for images.
+     */
+    readonly mediaContentTypeStore?: MediaContentTypeStorePort;
+    /**
+     * Template-preview pending-body fix (2026-08-12) — an explicitly-passed, per-call override for
+     * exactly one entity id's content, consulted ONLY by {@link resolveContentTypeEmbeds}. Lets
+     * `routes/admin/posts/template-preview.ts` preview the operator's unsaved, in-editor `bodyJson`
+     * through the real render pipeline: without this, the current entity's own `{"type":"content"}`
+     * slot (`injectCurrentEntityContentId`) always re-fetches by id via {@link findPublishedPostById},
+     * which returns the last-SAVED row and silently discards any in-memory override the caller built
+     * (`ADS-memory/reports/implementation/2026-08-11-template-preview-render-bug.md` documents the
+     * sibling `templateChoice`-only bug this closes the `bodyJson` half of).
+     *
+     * Deliberately per-call, never a shared/global/module-level cache — threaded fresh through this
+     * `deps` object on every `resolveHtmlPageEmbeds` call, so two concurrent preview requests for
+     * different posts (or the same post from two browser tabs) can never observe each other's pending
+     * body. `undefined` for every pre-existing call site; behavior for those is byte-identical to
+     * before this field existed.
+     *
+     * `title`/`slug`/`updatedAt` are carried alongside `bodyJson` because {@link resolveContentTypeEmbeds}'s
+     * resolved `"post-content"` IR needs all four regardless of source — this is the same shape a real
+     * `findPublishedPostById` result already provides, just supplied directly instead of fetched.
+     */
+    readonly pendingContentOverride?: {
+        readonly id: UUID;
+        readonly title: string;
+        readonly slug: string;
+        readonly updatedAt: string;
+        /** The row's go-live time — the date line shows it over `updatedAt` (`postDisplayDateIso`). */
+        readonly publishAt?: string | null;
+        readonly bodyJson: JsonObject;
+    };
+}
+type HtmlEmbedResolver = (refs: readonly PageHtmlEmbedRef[], deps: ResolveHtmlPageEmbedsDeps, context: WidgetResolveContext) => Promise<ReadonlyMap<string, WidgetRenderIR>>;
+/**
+ * Registry of known embed types (SPEC-047, generalized 2026-08-07). Adding a new embed type is
+ * registering one more entry here — no other file in `resolveHtmlPageEmbeds`'s call chain changes,
+ * and `html-embeds.ts`'s scanner already reports any type token it finds regardless of whether an
+ * entry exists here (see that file's own doc). A type ABSENT from this registry is the "unknown
+ * embed type" log path in {@link resolveHtmlPageEmbeds}; a type PRESENT here whose resolver still
+ * can't find a given id/name is the "resolver-internal miss" log path inside that resolver
+ * (`resolveWidgetTypeEmbeds`/`resolveMediaTypeEmbeds` above) — DECIDED (2026-08-07) to keep these
+ * two distinguishable in logs even though both render the identical REQ-28 placeholder externally:
+ * an author's markup typo (unknown type) and an author's stale reference (known type, dead id) are
+ * different problems needing different fixes.
+ *
+ * Historically `form` was removed (2026-08-10) because it was shorthand for a synthetic
+ * contact-form widget. The owner explicitly restores both spellings (2026-10-04): keep that
+ * synthetic instance on the SAME registered contact-form resolver so the two cannot drift.
+ */
+export declare const HTML_EMBED_RESOLVERS: Readonly<Record<string, HtmlEmbedResolver>>;
+/**
+ * Marker types that exist in the shared `data-embed-config` vocabulary (`core/embeds/marker.ts`) but
+ * are deliberately absent from {@link HTML_EMBED_RESOLVERS} — a theme's own structural markers, owned
+ * end-to-end by `features/theme/static-render.ts`'s `resolveSlots` (`"partial"`) and
+ * `injectMenuEmbeds` (`"menu"`), which run AFTER this stage on every static-tier page render
+ * (`routes/site/pages.ts`'s `renderViaTemplate`: `resolveHtmlPageEmbeds` first, then
+ * `renderStaticPage`). `isPageEmbedType`'s own doc already tells `render.ts`'s `renderHtmlPageBody` to
+ * leave these two untouched rather than substitute a placeholder over the nav — that fixed the
+ * SUBSTITUTION half of "this stage sees markers it does not own" (2026-08-10). This constant fixes the
+ * matching LOGGING half, which that earlier fix did not touch.
+ *
+ * Without this, {@link resolveHtmlPageEmbeds}'s "unknown embed type" warning fired for `menu`/`partial`
+ * on every single static-tier render — confirmed live during the 2026-08-16 GitHub Pages export
+ * (`gh-pages` commit `c0e52de2`, https://leonaburime-ucla.github.io/tovu-demo/): the log claimed "every
+ * occurrence degrades to the placeholder," which was false — curling the published page showed real,
+ * resolved `<a href>` links in both the nav and footer, zero placeholder markup anywhere. The page was
+ * never broken; only the diagnostic was. Left uncorrected, that false alarm fires on every render and
+ * trains a reader to ignore this log line, burying the ONE case it exists to catch: an author's actual
+ * markup typo (`HTML_EMBED_RESOLVERS`'s own doc on why "unknown type" and "known type, dead id" must
+ * stay distinguishable applies equally to "known-and-owned-elsewhere" vs. "owned nowhere").
+ *
+ * A type in this set must stay absent from `HTML_EMBED_RESOLVERS` — do not "fix" the warning by adding
+ * a resolver entry instead; see `isPageEmbedType`'s own doc for why that would reintroduce the
+ * substitution bug this file already fixed once.
+ *
+ * **Why this isn't just `!isPageEmbedType(type)`.** `isPageEmbedType` is membership in `PAGE_EMBED_TYPES`,
+ * which the compiler holds equal to `HTML_EMBED_RESOLVERS`'s keys — exactly the same fact this loop's own
+ * `HTML_EMBED_RESOLVERS[type]` lookup already tests, one
+ * bit: "is this resolver-service's own type." That bit is `false` for `partial`/`menu` AND for a genuine
+ * unregistered/typo type alike, so it cannot distinguish "known, owned by a later stage" from "owned
+ * nowhere" — using it to gate the warning would silence the ONE case the warning exists for, not just
+ * the two it shouldn't fire for. This set names the missing fact directly instead. It intentionally
+ * duplicates `static-render.ts`'s own `marker.type !== "menu"`/`!== "partial"` literals rather than
+ * importing them (that file is a different feature's territory in this change's dispatch) — the real
+ * fix, hoisting a shared constant into `core/embeds/marker.ts` for both files to import, is proposed but
+ * not yet authorized; see `ADS-memory/reports/2026-08-16-embed-placeholder-gap.md`'s "Reuse decision"
+ * section. Keep this set's members in sync with those two literals, not with `isPageEmbedType`.
+ *
+ * `"post-previews"` (2026-09-03) joins the set for the identical reason: it is resolved by
+ * `static-render.ts`'s `injectPostPreviewsEmbeds`, AFTER this stage, on every static-tier page
+ * render that reaches `renderStaticPage` — same duplicated-literal debt as the other two entries
+ * (see `POST_PREVIEWS_MARKER_TYPE`, `core/embeds/marker.ts`), not yet hoisted for the same reason.
+ *
+ * `"collection"` (2026-09-23) joins the set for the identical reason: it is resolved by
+ * `static-render.ts`'s `injectCollectionEmbeds`, AFTER this stage — same duplicated-literal debt as
+ * the other three entries (see `COLLECTION_MARKER_TYPE`, `core/embeds/marker.ts`).
+ *
+ * `"featured-image"` (2026-10-05) joins for the identical reason: `static-render.ts`'s
+ * `injectFeaturedImage` resolves it (see `FEATURED_IMAGE_MARKER_TYPE`, `core/embeds/marker.ts`).
+ */
+export declare const THEME_OWNED_MARKER_TYPES: ReadonlySet<string>;
+/**
+ * `isPageEmbedType` (the "does this stage OWN the marker type" question, with its own doc) lives in
+ * the dependency-free `page-embed-types.ts` so `render.ts` and the theme render workers can ask it
+ * without loading this file's service graph. Re-exported so existing importers keep working.
+ */
+export { isPageEmbedType } from "./page-embed-types.js";
+//# sourceMappingURL=resolver-service.d.ts.map