@jini-ai/cms 0.5.2 → 0.5.4

package/dist/widgets/host-ports.d.ts

@@ -0,0 +1,149 @@
+import type { Clock, JsonObject } from "@jini-ai/core/primitives";
+import type { OutboxPort } from "../core/ports.js";
+import type { createEntry, updateEntry, importEntry, toEntryOutbox } from "../entries/index.js";
+import type { registerContentType, toContentTypeOutbox, IndexProvisionerPort } from "../content-types/index.js";
+import type { findMediaByIdOrSlug, getLatestTransformDefinition } from "../media/index.js";
+import type { EntryRefRow } from "./ports.js";
+/** Host-owned post snapshot: only the fields the widgets services read or forward. */
+export interface PostRecord {
+    id: string;
+    workspaceId: string;
+    title: string;
+    slug: string;
+    bodyJson: JsonObject;
+    status: "draft" | "published";
+    kind: "post" | "page";
+    bodyFormat: "doc" | "html";
+    updatedAt: string;
+    version: number;
+    deletedAt?: string | null;
+    publishAt?: string | null;
+    templateChoice?: string | null;
+    overridesThemePage?: boolean | null;
+    ext?: JsonObject;
+}
+/** Host-owned blob content-type lookup; absent sha256 keys mean the blob has not been sniffed yet.
+ * Widgets only consumes batch reads; the host retains storage and write ownership. */
+export interface MediaContentTypeStorePort {
+    getMany(required: {
+        workspaceId: string;
+        sha256s: readonly string[];
+    }): Promise<Map<string, string>>;
+}
+/** Reads stay host-owned; post writes below receive this same bound repository. */
+export interface PostRepoPort {
+    findById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<PostRecord | null>;
+    findBySlug(required: {
+        workspaceId: string;
+        slug: string;
+    }): Promise<PostRecord | null>;
+}
+export type ForgetRemovedPostFn = (required: {
+    workspaceId: string;
+    id: string;
+}) => Promise<void>;
+export type BeforeSaveHookPort = (entry: {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly title: string;
+    readonly slug: string;
+    readonly status: PostRecord["status"];
+    readonly bodyJson: Readonly<Record<string, unknown>>;
+    readonly ext: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}) => Promise<JsonObject>;
+type PostWriteDeps = {
+    repo: PostRepoPort;
+    clock: Clock;
+    outbox: OutboxPort;
+    beforeSaveHook?: BeforeSaveHookPort | undefined;
+};
+type PostAttribution = {
+    actorId?: string;
+    delegatedByWorkspaceId?: string | null | undefined;
+    delegatedById?: string | null | undefined;
+};
+/** Required host behavior. No sibling-domain value enters the widgets runtime closure. */
+export interface WidgetHostPorts {
+    entries: {
+        createEntry: typeof createEntry;
+        updateEntry: typeof updateEntry;
+        importEntry: typeof importEntry;
+        toEntryOutbox: typeof toEntryOutbox;
+        isVersionConflict(error: unknown): boolean;
+    };
+    contentTypes: {
+        registerContentType: typeof registerContentType;
+        toContentTypeOutbox: typeof toContentTypeOutbox;
+        createIndexProvisioner(): IndexProvisionerPort;
+        alreadyExists(error: unknown): {
+            tombstoned: boolean;
+        } | null;
+    };
+    posts: {
+        isTrashed(post: PostRecord): boolean;
+        isVersionConflict(error: unknown): error is Error & {
+            currentVersion: number;
+        };
+        isNotFound(error: unknown): boolean;
+        updatePost(required: {
+            deps: PostWriteDeps;
+            input: PostAttribution & {
+                workspaceId: string;
+                id: string;
+                title: string;
+                slug: string;
+                status: PostRecord["status"];
+                bodyJson: JsonObject;
+                expectedVersion: number;
+            };
+        }, optional?: Record<string, never>): Promise<{
+            post: PostRecord;
+        }>;
+        restorePostForward(required: {
+            deps: PostWriteDeps & {
+                forgetRemoved: ForgetRemovedPostFn;
+            };
+            input: PostAttribution & {
+                prior: PostRecord;
+            };
+        }, optional?: Record<string, never>): Promise<unknown>;
+        findPublishedPostById(required: {
+            deps: {
+                repo: PostRepoPort;
+            };
+            input: {
+                workspaceId: string;
+                id: string;
+            };
+        }, optional?: Record<string, never>): Promise<PostRecord | null>;
+        findPublishedPostBySlug(required: {
+            deps: {
+                repo: PostRepoPort;
+            };
+            input: {
+                workspaceId: string;
+                slug: string;
+            };
+        }, optional?: Record<string, never>): Promise<PostRecord | null>;
+    };
+    media: {
+        findMediaByIdOrSlug: typeof findMediaByIdOrSlug;
+        getLatestTransformDefinition: typeof getLatestTransformDefinition;
+        publicTransformName: string;
+    };
+    entryRefs: {
+        extract(required: {
+            workspaceId: string;
+            sourceEntryId: string;
+            sourceEntryType: string;
+            bodyJson: unknown;
+            fieldsExt: Record<string, unknown>;
+        }, optional?: Record<string, never>): readonly EntryRefRow[];
+    };
+    slugify(text: string): string;
+}
+export {};
+//# sourceMappingURL=host-ports.d.ts.map

package/dist/widgets/host-ports.js

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

package/dist/widgets/html/html-embeds.d.ts

@@ -0,0 +1,247 @@
+/**
+ * @file The embed-reference view of a `"html"`-format Page's body (SPEC-047 Slice 2, generalized
+ * 2026-08-07 per `project-tovu-generic-embed-contract`, rewired onto the shared marker parser
+ * 2026-08-10).
+ *
+ * Purpose:
+ * A TipTap `widgetEmbed` node has a structured home (`bodyJson`) to carry a `{placementId,
+ * widgetEntryId}` attrs object. A Page's body is a free-form HTML string with no such tree, so an
+ * embed there has to be a literal markup convention instead:
+ * `<div data-embed-config='{"type":"widget","id":"{widgetEntryId}"}'></div>` (or `"type":"media"`,
+ * `"post"`, or any future type token), anywhere in the page's `body_html`.
+ *
+ * **This file no longer owns a pattern.** Locating and parsing a marker is `core/embeds/marker.ts`'s
+ * single job; this module is only the adapter that projects a parsed marker into the
+ * {@link PageHtmlEmbedRef} shape `resolver-service.ts` resolves against. Before the 2026-08-10
+ * unification there were four regexes for one concept — this one, `static-render.ts`'s,
+ * `entry-refs/extractor.ts`'s deliberate second copy, and the theme-slot pair — and they had already
+ * drifted: this one required an EMPTY `<div></div>`, while the theme path deliberately matched a
+ * marker WITH authored fallback content inside it. Sharing the parser is what makes "what render.ts
+ * embeds" and "what entry_refs indexes" incapable of disagreeing, rather than merely tested for
+ * agreement after the fact.
+ *
+ * **Why `type` is a free string, not a closed union.** A closed union would mean this file's own
+ * type signature has to change every time a new embed type is added — exactly the coupling the
+ * generic contract exists to remove. Adding a fourth type is a new resolver registration
+ * (`resolver-service.ts`'s `HTML_EMBED_RESOLVERS`), never a scanner change. Unknown types flow
+ * through untouched; "is this type known" is a resolution-time question, never a scan-time one.
+ *
+ * **Inner content is now allowed, and that is a widening.** The old empty-div requirement meant any
+ * content inside a placeholder kept it from matching at all — it rendered verbatim and inert. The
+ * shared parser captures inner content instead, because a theme marker's authored content is a real
+ * fallback that must survive when nothing resolves. For most types the consequence is that
+ * {@link substituteHtmlEmbeds} replaces the WHOLE element, fallback content included, exactly as it
+ * already replaced the whole empty div: an html Page's embed placeholder is scaffolding for the
+ * resolved widget, not a nav that must survive a failed lookup. Unresolved still degrades to the
+ * REQ-28 placeholder via the caller's own `resolve`, never to a crash and never to raw marker markup
+ * reaching a visitor.
+ *
+ * **`"media"`, `"post"`, and `"content"` are wrapper-preserving.** An author who wraps one of these
+ * markers in their own element — `<div style="max-width:600px"
+ * data-embed-config='{"type":"media","id":"..."}'></div>`, or `<main class="page-body"
+ * data-embed-config='{"type":"content","id":"..."}'></main>` — expects that element and its own
+ * attributes (style, class, id, aria-*) to survive; only the marker's CONTENT should become the
+ * resolved markup. See {@link WRAPPER_PRESERVING_EMBED_TYPES}'s own doc for the per-type reasoning,
+ * and {@link substituteHtmlEmbeds}'s own doc for the one tag-nesting exception `"media"` alone needs.
+ *
+ * **`"widget"` (and any other type this stage resolves) keeps its element ONLY if the author gave it
+ * attributes (2026-09-16, direct owner ask: "regular attributes that somebody puts on a
+ * data-embed-config should work on the rendered tag").** A BARE `<div
+ * data-embed-config='{"type":"widget","id":"w1"}'></div>` is still whole-element replaced,
+ * byte-identical to before — `"widget"`'s resolved root tag is not a small, closed set (see
+ * {@link WRAPPER_PRESERVING_EMBED_TYPES}'s own doc for why it still cannot unconditionally join the
+ * wrapper-preserving group), but an author who wrote `<div style="max-width:600px"
+ * data-embed-config='{"type":"widget","id":"w1"}'></div>` plainly wants that `style` to survive.
+ * {@link withElementKeptIfAttributed} is the shared primitive for this rule.
+ *
+ * **`"media"`'s own attributes (2026-09-16) are partitioned, not simply kept-or-dropped.** See
+ * {@link MEDIA_ELEMENT_ATTRIBUTE_NAMES} and {@link substituteHtmlEmbeds}'s own doc.
+ *
+ * **Why attribute VALUES are not re-validated here for injection safety.** A Page's `body_html` is
+ * already unescaped, trusted-ish markup by the time it reaches this module (see
+ * `update-html.ts`'s own disclosure) — nothing this file does widens that trust boundary. The one
+ * thing this module owns defensively is bounding how much work an adversarial/oversized page can
+ * demand at render/index time (`MAX_HTML_EMBEDS_PER_PAGE`) and never using a captured id for
+ * anything other than a map/repo lookup key (never re-emitted into HTML unescaped, never
+ * interpolated into a query) — see `resolver-service.ts`'s `resolveHtmlPageEmbeds` and
+ * `extractor.ts`'s html-ref collector, both of which only ever use the id that way.
+ *
+ * **`slug`, an author-memorable alternative to `id` (2026-08-31).** The owner's own complaint —
+ * `{"type":"widget","id":"29721c44-a811-444f-b7b5-e61a9918a3a9"}` is not something a person can
+ * type from memory — is real, and this is the fix: `{"type":"widget","slug":"contact-form"}`.
+ * `slug` is projected here exactly like `name`/`variant` already are (a raw, unvalidated config
+ * key; deciding whether it is USABLE is a resolver-side concern), but it is a genuinely different
+ * mechanism from the dormant `name` field above, not a rename of it. `name` was scaffolded
+ * (2026-08-05/07 generic-embed-contract design, `project-tovu-generic-embed-contract` in
+ * `ADS-memory/`) for a fuzzy, POSSIBLY-AMBIGUOUS match — "exactly one match resolves; zero or >1
+ * degrades to the placeholder, never a guess" — and no resolver in this codebase has ever
+ * implemented that ambiguity guard. `slug` needs no such guard: it targets a column
+ * (`entries.slug`) carrying a real database `UNIQUE(workspace_id, type, slug)` index, so "more than
+ * one match" cannot occur by construction, not merely by convention. Reusing `name`'s never-shipped,
+ * ambiguity-hedged semantics for a value that is unique by database constraint would be modeling a
+ * problem this feature does not have.
+ *
+ * **`id` stays authoritative.** When a marker carries both, `id` wins and `slug` is not even
+ * consulted — this is a strict widening of the pre-existing "the id resolves" rule (a marker with no
+ * `slug` key behaves byte-identically to before), not a new fallback CHAIN where a present-but-broken
+ * `id` triggers a `slug` retry; nothing in this codebase's history committed to that stronger contract
+ * and building it would add a second resolution path for no requirement in hand. See
+ * `resolver-service.ts`'s `resolveWidgetTypeEmbeds` for where `slug` is actually resolved — today
+ * that is `"widget"` only (`entries.slug` is unique per `(workspaceId, type)`; `posts.slug` is
+ * equally unique and could gain the identical treatment cheaply in a follow-up, but is intentionally
+ * left untouched by this change; `media` has no `slug` column at all and cannot support this without
+ * a schema migration).
+ */
+import { type MarkerAttribute } from "../markers/marker.js";
+/**
+ * One embed reference found in a Page's `body_html`. `type` is deliberately a free string (see this
+ * file's header) — the scanner never validates it against a known-type list. `id`/`slug`/`name`/
+ * `variant` are `null` when the corresponding CONFIG KEY is absent or not a string (or, for `id`/
+ * `slug`, out of {@link MAX_EMBED_ID_LENGTH} bounds) — the scanner reports what is literally written
+ * in the markup; deciding whether an absent/invalid key makes the reference resolvable is a
+ * resolver-side concern (`resolver-service.ts`), not a scanner-side one.
+ *
+ * Kept as a narrow projection of `EmbedMarker.config` rather than replaced by it: every resolver in
+ * `HTML_EMBED_RESOLVERS` reads exactly these five fields, and `null`-for-absent is the shape their
+ * skip branches already test. A resolver needing a new key reads it off the marker config directly
+ * — this interface is the compatibility seam, not a ceiling.
+ */
+export interface PageHtmlEmbedRef {
+    readonly type: string;
+    readonly id: string | null;
+    /** See this file's header for why this is NOT the same mechanism as `name` below, despite the
+     *  similar shape — `slug` targets a database-unique column, `name` a never-implemented fuzzy match. */
+    readonly slug: string | null;
+    readonly name: string | null;
+    readonly variant: string | null;
+    /**
+     * `false` only when the config key is the literal JSON boolean `false`; every other case
+     * (absent, `true`, or any non-boolean value) is `true` (2026-09-04). Today read only by the
+     * `"content"` resolver (`resolver-service.ts`'s `resolveContentTypeEmbeds`), which threads it
+     * into the `"post-content"` IR's `props.header` so `render.ts`'s `renderWidgetPostContent` can
+     * skip its `.post-detail-header` (`<h1>` + date byline) wrapper — previously unconditional
+     * application code a template had no way to opt out of, forcing a `display:none` CSS workaround
+     * for a homepage doc-format row that does not want a dated byline. `true`-by-default is load-
+     * bearing: no existing template (a `kind:"post"` detail page, the listing page, `about`, `docs`)
+     * carries a `header` key, and this default is what keeps every one of them rendering byte-
+     * identically to before this field existed. Not read by `"widget"`/`"media"`/the legacy `"post"`
+     * type — this is a `"content"`-marker-specific concern, not a general marker attribute.
+     */
+    readonly header: boolean;
+    readonly mode?: "html";
+}
+/**
+ * Resource bound (Programmer workflow step 5a4) mirroring `embed-service.ts`'s
+ * `DEFAULT_MAX_EMBEDS_PER_DOCUMENT` for the TipTap path — same policy, same value, applied here
+ * because an html Page has no equivalent write-time guardrail (`PagesHtmlDocumentStore.write()`
+ * accepts any string; `embed-validation.ts`'s `validateWidgetEmbedMutation` is never in this path).
+ * Without a cap, a page carrying thousands of embed placeholders would grow `entry_refs` and the
+ * render-time resolved-id set unboundedly. `scanHtmlEmbeds` truncates AT this many refs; occurrences
+ * beyond the cap simply resolve to the same REQ-28 placeholder every other unresolved reference
+ * does (see `substituteHtmlEmbeds`'s own doc for why it does not need a matching count check).
+ *
+ * **This is a render/index-time resource guard, NOT a write-time invariant.** Nothing stops
+ * `pages_write_html`/the admin HTML editor from storing a page with 5,000 embed placeholders in
+ * `body_html` — `PagesHtmlDocumentStore.write()` has no count check of its own, unlike
+ * `embed-validation.ts`'s `validateWidgetEmbedMutation` (REQ-20) on the TipTap path, which rejects
+ * an over-limit mutation before it is ever persisted. This constant only bounds how much of an
+ * already-stored oversized page gets resolved/indexed on any single render or reindex pass — it
+ * does not guarantee such a page can never exist. A write-time cap would need its own design
+ * decision (reject vs. truncate vs. warn the operator) that has not been made; do not read this
+ * constant as implying one already has been.
+ */
+export declare const MAX_HTML_EMBEDS_PER_PAGE = 50;
+/**
+ * Every embed reference in `html`, in document order, truncated at
+ * {@link MAX_HTML_EMBEDS_PER_PAGE}. Pure — no I/O, never throws. Shared by the render-time resolver
+ * (`resolver-service.ts`'s `resolveHtmlPageEmbeds`, which needs to know what to batch-load) and
+ * anything that needs to enumerate a page's embed set without rendering it.
+ *
+ * A marker whose config does not parse is simply absent from the result — render-time stays
+ * forgiving (warn + degrade, never throw), and the unparseable marker's own markup survives
+ * untouched into the output because {@link substituteHtmlEmbeds} cannot see it either. The LOUD
+ * treatment of `rejected` belongs to `core/entry-refs/extractor.ts` (the integrity path a dropped
+ * reference would let a delete proceed against) and to the write chokepoint, not here.
+ *
+ * @complexity O(n) over `html`'s length for the shared scan, plus O(min(k, cap)) to build the
+ * returned array, where k is the number of markers.
+ * @overallScore 100
+ */
+export declare function scanHtmlEmbeds({ html }: {
+    html: string;
+}, _optional?: Record<string, never>): PageHtmlEmbedRef[];
+/**
+ * Attribute names D2 (2026-09-16 embed-attributes plan) says mean something on a rendered
+ * `<video>`/`<img>` and NOTHING on a `<div>`/other wrapper tag — so when a `"media"` marker is
+ * authored on a non-self-rendering wrapper, an attribute in this set moves off the wrapper and onto
+ * the resolved media element; every other authored attribute (`class`, `style`, `id`, `data-*`,
+ * `aria-*`, an unknown name) stays on the wrapper. See {@link substituteHtmlEmbeds}'s own doc for how
+ * this partition is used, and `render.ts`'s merge helper for how `EmbedOccurrence.elementAttributes`
+ * actually lands on the rendered tag (D3's precedence rules).
+ *
+ * `controls` is listed here (it means nothing on a `<div>` either) even though it is ALSO read
+ * separately into {@link EmbedOccurrence.controls} — see {@link resolveMarkerControls}'s own doc for
+ * why a raw `controls` attribute is never itself re-emitted onto the rendered element.
+ */
+export declare const MEDIA_ELEMENT_ATTRIBUTE_NAMES: ReadonlySet<string>;
+/**
+ * One marker occurrence's forwarded attribute data (2026-09-16 embed-attributes plan), handed to
+ * `resolve` alongside its {@link PageHtmlEmbedRef} — the per-occurrence half of "attributes on the
+ * marker element reach the rendered output" that a `PageHtmlEmbedRef` alone cannot carry (it is keyed
+ * by config content, not by which literal marker element authored it; `entry_refs`/the resolver both
+ * intentionally do not need presentation data on that shape).
+ */
+export interface EmbedOccurrence {
+    /**
+     * Only meaningful for `"media"`: on a wrapper, the authored attributes D2
+     * ({@link MEDIA_ELEMENT_ATTRIBUTE_NAMES}) says belong on `<video>`/`<img>`, not the wrapper; on a
+     * marker authored directly on a self-rendering tag ({@link SELF_RENDERING_MEDIA_TAGS}), every
+     * authored attribute. Empty for every other type.
+     */
+    readonly elementAttributes: readonly MarkerAttribute[];
+    /**
+     * `false` only when the marker's own `controls` attribute resolves to off — see
+     * {@link resolveMarkerControls}. `true` (the pre-existing default) for every non-`"media"` type,
+     * where the field is unused.
+     */
+    readonly controls: boolean;
+}
+/**
+ * Replaces every embed placeholder in `html` with `resolve(ref, occurrence)`'s return value.
+ * `resolve` is synchronous and pure from this function's own perspective — the caller is expected
+ * to have already batch-resolved every ref it cares about (mirroring how `render.ts`'s
+ * `renderDocNode` receives an already-resolved `inlineResolved` map rather than doing its own I/O);
+ * a ref `resolve` doesn't recognize (unknown type, never loaded, or beyond
+ * {@link MAX_HTML_EMBEDS_PER_PAGE}) is `resolve`'s own call to degrade safely, not something this
+ * function special-cases — every caller here (`render.ts`'s `renderHtmlPageBody`) already returns
+ * the REQ-28 placeholder for an unresolved ref, which is exactly what "no cap-aware branch needed
+ * here" relies on.
+ *
+ * `resolve` returning `undefined` means **leave this marker exactly as authored**, forwarded straight
+ * to `substituteMarkers`' own invariant of the same name. That is not a convenience: since the
+ * 2026-08-10 unification this stage SEES markers it does not own (a theme's `partial`/`menu`), and a
+ * later stage resolves them. Substituting anything at all over one of those — including the REQ-28
+ * placeholder — silently deletes a nav. Which types this stage owns is `resolver-service.ts`'s
+ * `isPageEmbedType` to answer; this function only carries the answer through.
+ *
+ * Per-type handling (2026-09-16):
+ * - **`"media"`**: {@link planMediaMarkerAttributes} computes the occurrence AND the wrapper split.
+ *   On the marker's own self-rendering tag ({@link SELF_RENDERING_MEDIA_TAGS}) the replacement is
+ *   returned as-is (no wrapper, unchanged from before). On any other tag: if nothing moved, the
+ *   wrapper is rebuilt via the byte-identical {@link withInnerContentFinal} path; otherwise via
+ *   {@link withInnerContentAndAttributes} with only the reduced wrapper attribute list.
+ * - **`"post"`/`"content"`** ({@link WRAPPER_PRESERVING_EMBED_TYPES}): spliced via
+ *   {@link spliceWrapperPreservingReplacement}, occurrence attributes always empty.
+ * - **Every other type** (`"widget"`, and any type this stage does not itself own but still
+ *   resolves): {@link withElementKeptIfAttributed} — a bare marker keeps the pre-existing
+ *   whole-element replace; an attributed one keeps its element around the resolved output.
+ *
+ * @complexity O(n) over `html`'s length for the shared scan, plus O(k) per `"media"` marker in its own
+ * attribute count (one two-way partition), O(1) per marker otherwise.
+ * @overallScore 100
+ */
+export declare function substituteHtmlEmbeds({ html, resolve }: {
+    html: string;
+    resolve: (ref: PageHtmlEmbedRef, occurrence: EmbedOccurrence) => string | undefined;
+}, _optional?: Record<string, never>): string;
+//# sourceMappingURL=html-embeds.d.ts.map