@jini-ai/cms 0.5.5 → 0.5.7

package/dist/routing/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @file Core type definitions for the Tovu `routing` Tier-2 library (ADR-039 v0).
+ *
+ * Purpose:
+ * Declares the `RouteTarget` vocabulary, the workspace-scoped resolve context,
+ * the inverse-resolver result shape, the forward resolution pipeline's phase
+ * vocabulary, and the `SlugChangeCapture` slot's payload shape. This is the one
+ * place `entryRef | termRef | url | route` is defined — promoted from
+ * Menus-local (ADR-029 §3) to routing-owned per ADR-039 §3, so Menus/SEO/
+ * Redirects share one vocabulary instead of inventing three.
+ *
+ * How it relates to the project:
+ * - `core/ports.ts` supplies the shared primitives (`UUID`, `ISODateTime`, …).
+ * - `routing/ports.ts` declares the dependency shape `urlFor`/`isActive` need
+ *   (the existing `PostRepoPort`, reused rather than duplicated).
+ * - `routing/routing.ts` implements the resolve functions against these types.
+ *
+ * Architectural role:
+ * INTERFACES + TYPES ONLY (no feature logic). ADR-039 v0 is deliberately the
+ * minimal shape three other sections depend on; full permalink-structure
+ * design is explicitly deferred (ADR-039 "Open").
+ */
+import type { JsonObject, UUID } from "@jini-ai/core/primitives";
+/** Discriminant values for {@link RouteTarget}. */
+export type RouteTargetKind = "entryRef" | "termRef" | "url" | "route";
+/**
+ * A link to a content entry by id. Only `post` has a real resolver in this
+ * repo today (ADR-039 v0); `contentType` is accepted for forward-compat with
+ * future content types but is not required to resolve a post reference.
+ */
+export interface EntryRefTarget {
+    readonly kind: "entryRef";
+    readonly entryId: UUID;
+    readonly contentType?: string;
+}
+/**
+ * A link to a taxonomy term (category/tag archive).
+ *
+ * NOT resolvable today: taxonomy isn't implemented in this repo, and ADR-029's
+ * Round-3 audit fold promoted "term-link schema" from an Open item to an
+ * explicit Wave-1 acceptance blocker — ADR-022 §5's `entry_refs` covers
+ * entry-to-entry references only, with no term-target schema yet (content-lib
+ * sign-off owed). `urlFor`/`isActive` resolve every `termRef` target to `null`
+ * until that schema lands; see the stub in `routing.ts`.
+ */
+export interface TermRefTarget {
+    readonly kind: "termRef";
+    readonly termId: UUID;
+    readonly taxonomy: string;
+}
+/**
+ * An external or site-relative URL, passed through as given (scheme-validated:
+ * `javascript:`/`data:` are rejected and resolve to `null`, mirroring the
+ * "unavailable → null" contract rather than throwing).
+ */
+export interface UrlTarget {
+    readonly kind: "url";
+    readonly href: string;
+}
+/** A named core route (e.g. `home`, `search`), resolved via the route registry. */
+export interface RouteRefTarget {
+    readonly kind: "route";
+    readonly route: string;
+    /** Optional static params; unused by the v0 registry, reserved for v0.1 param interpolation. */
+    readonly params?: JsonObject;
+}
+/** v0 discriminated union of route targets (ADR-039 §3). */
+export type RouteTarget = EntryRefTarget | TermRefTarget | UrlTarget | RouteRefTarget;
+/**
+ * Workspace-scoped context threaded through every resolve call. `siteId`/
+ * `locale`/`originKey` are reserved for multi-site/i18n v0.1 work (ADR-039
+ * "Open"); only `workspaceId` is load-bearing today.
+ *
+ * `originOverride` is a stand-in for `core/origin` (ADR-040), which is being
+ * built in parallel and does not exist yet. Once it lands, `canonicalUrl`
+ * composition should read the verified origin from
+ * `OriginRegistryPort.canonicalOrigin(ctx)` instead of this field.
+ */
+export interface RouteResolveContext {
+    readonly workspaceId: UUID;
+    readonly siteId?: string;
+    readonly locale?: string;
+    readonly originKey?: string;
+    /**
+     * TODO(ADR-040): compose canonicalUrl from OriginRegistryPort.canonicalOrigin(ctx)
+     * once src/origin exists. Until then, a caller that knows the verified origin
+     * may pass it here; absent, canonicalUrl falls back to the relative path.
+     */
+    readonly originOverride?: string;
+}
+/** Result of a successful inverse resolve — the shape Menus/SEO consume. */
+export interface RouteUrl {
+    readonly path: string;
+    readonly canonicalUrl: string;
+}
+/**
+ * The two registerable phases of the forward pipeline
+ * (`normalize → pre_content → content-resolve → post_content → 404`).
+ * `content-resolve` is fixed core content lookup and is not a registerable
+ * phase of this library; it is out of scope for ADR-039 v0's registration
+ * mechanism.
+ */
+export type RouteResolvePhaseName = "pre_content" | "post_content";
+/** Terminal decision a phase resolver may return; anything else falls through. */
+export type RouteResolvePhaseOutcome = {
+    readonly kind: "redirect";
+    readonly location: string;
+    readonly statusCode: number;
+} | {
+    readonly kind: "resolved";
+    readonly path: string;
+} | {
+    readonly kind: "not_found";
+};
+/**
+ * A single phase resolver. Returns `null` to fall through to the next
+ * registered resolver in the same phase (and eventually the next phase);
+ * returns an outcome to short-circuit the pipeline (ADR-039 §1 invariant:
+ * `pre_content` may only redirect/gone, never turn a resolvable live path
+ * into a 404 — Round-2 amendment 5).
+ */
+export type RouteResolvePhaseHandler = (path: string, ctx: RouteResolveContext) => Promise<RouteResolvePhaseOutcome | null>;
+/** Final outcome of {@link resolve} after all phases have run. */
+export type RouteResolveResult = {
+    readonly matched: false;
+} | {
+    readonly matched: true;
+    readonly phase: RouteResolvePhaseName;
+    readonly outcome: RouteResolvePhaseOutcome;
+};
+/** Payload handed to the bound {@link SlugChangeCapture} inside the rename transaction. */
+export interface SlugChangeCaptureInput {
+    readonly workspaceId: UUID;
+    readonly entryId: UUID;
+    readonly oldPath: string;
+    readonly newPath: string;
+    readonly actor: UUID;
+    readonly changeSetId?: UUID;
+}
+/**
+ * The single named slot content's write chokepoint calls inside the rename
+ * transaction (ADR-039 §4). Declared here by routing (content knows nothing of
+ * redirects); implemented by the redirects library; wired by the composition
+ * root. **No slot implementation may be plugin-supplied** (Round-2 amendment 1
+ * — the slot is core-resident by definition).
+ *
+ * Constraints on any bound implementation (Round-2 amendment 2): idempotent by
+ * `changeSetId`, no external I/O, no in-tx publish (an outbox row may be
+ * written in-tx per the transactional-outbox pattern, but dispatch happens
+ * post-commit), and a strict lock order of content row before redirect rows.
+ *
+ * Fail-closed nuance (Round-2 amendment 3, not enforced by this library):
+ * absent binding is a no-op only before Redirects is installed, or while
+ * slug-preservation is disabled for the workspace. Once link-preservation is
+ * enabled, a slug-changing rename with no bound capture MUST fail
+ * `LINK_PRESERVATION_UNAVAILABLE` rather than silently skip the redirect. That
+ * enforcement belongs to the content write chokepoint (which knows whether
+ * preservation is enabled) and to Redirects (which doesn't exist yet in this
+ * repo) — this library only exposes the registration slot.
+ */
+export interface SlugChangeCapture {
+    onSlugChange(input: SlugChangeCaptureInput): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/routing/types.js

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

package/dist/seo/media.d.ts

@@ -29,6 +29,29 @@ export declare function resolveSeoImageRef(required: {
     deps: ResolveSeoImageRefDeps;
     input: ResolveSeoImageRefInput;
 }, _optional?: Record<string, never>): Promise<string | undefined>;
+/** Metadata belongs to the selected transform, never the asset's editable display-size fields. */
+export interface SeoImageDetails {
+    url: string;
+    /** Original source choice for admin diagnostics; a resized rendition can conceal a tiny source. */
+    ref?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    type?: string | undefined;
+}
+/** Resolve through the existing media owners, optionally selecting a host's share transform.
+ * Absolute external URLs remain unchanged with unknown metadata; no remote fetch occurs.
+ * The latest definition keeps the anonymous lazy-generation guarantee documented above.
+ * @param required Media ports, workspace and persisted reference.
+ * @param optional Host-selected transform; omitted or unregistered retains the reference's named transform.
+ * @returns URL and known output metadata, or undefined on a lookup miss.
+ * @complexity O(v) in registered transform versions; up to three bounded repository reads.
+ */
+export declare function resolveSeoImageDetails(required: {
+    deps: ResolveSeoImageRefDeps;
+    input: ResolveSeoImageRefInput;
+}, optional?: {
+    transformName?: string | undefined;
+}): Promise<SeoImageDetails | undefined>;
 /**
  * The write-path refusal for an `ogImage`/`twitterImage`/`defaultOgImage` value (2026-10-05): the
  * message to refuse it with, or `null` to accept it. Both SEO write chokepoints call it

package/dist/seo/media.js

@@ -1,3 +1,4 @@
+import { mimeForTransformFormat } from "../media/transform-types.js";
 /**
  * @file `resolveSeoImageRef` (ADR-PIPE-008 Decision §6, C-013, EC-07;
  * EC-07's "never generates" clause AMENDED 2026-09-05 — see the ADR's
@@ -83,23 +84,47 @@ function buildSeoImageUrl(deps, asset, transformName, latest) {
  * version listing).
  */
 export async function resolveSeoImageRef(required, _optional = {}) {
+    return (await resolveSeoImageDetails(required))?.url;
+}
+/** Resolve through the existing media owners, optionally selecting a host's share transform.
+ * Absolute external URLs remain unchanged with unknown metadata; no remote fetch occurs.
+ * The latest definition keeps the anonymous lazy-generation guarantee documented above.
+ * @param required Media ports, workspace and persisted reference.
+ * @param optional Host-selected transform; omitted or unregistered retains the reference's named transform.
+ * @returns URL and known output metadata, or undefined on a lookup miss.
+ * @complexity O(v) in registered transform versions; up to three bounded repository reads.
+ */
+export async function resolveSeoImageDetails(required, optional = {}) {
     const { deps, input } = required;
     const ref = input.ref?.trim();
     if (!ref)
         return undefined;
     if (isAbsoluteUrl(ref))
-        return ref;
+        return { url: ref, ...(optional.transformName === undefined ? {} : { ref }) };
     const parts = parseMediaRefParts(ref);
     if (!parts)
         return undefined;
-    const { idOrSlug, transformName } = parts;
-    const asset = await resolveVisibleAsset(deps, input.workspaceId, idOrSlug);
+    const asset = await resolveVisibleAsset(deps, input.workspaceId, parts.idOrSlug);
     if (!asset)
         return undefined;
-    const latest = await resolveLatestTransformVersion(deps, input.workspaceId, transformName);
+    let transformName = optional.transformName ?? parts.transformName;
+    let latest = await resolveLatestTransformVersion(deps, input.workspaceId, transformName);
+    // Share-transform registration may still be in flight at boot. Keep the persisted reference
+    // servable through its own transform rather than dropping the image from both social cards.
+    if (!latest && transformName !== parts.transformName) {
+        transformName = parts.transformName;
+        latest = await resolveLatestTransformVersion(deps, input.workspaceId, transformName);
+    }
     if (!latest)
         return undefined;
-    return buildSeoImageUrl(deps, asset, transformName, latest);
+    // inside/outside fit does not produce the exact declared box, so don't advertise that box.
+    const exactBox = latest.params.width !== undefined && latest.params.height !== undefined && latest.params.fit !== "inside" && latest.params.fit !== "outside";
+    return {
+        url: buildSeoImageUrl(deps, asset, transformName, latest),
+        ...(optional.transformName === undefined ? {} : { ref }),
+        ...(exactBox ? { width: latest.params.width, height: latest.params.height } : {}),
+        type: mimeForTransformFormat({ format: latest.params.format }),
+    };
 }
 /**
  * The write-path refusal for an `ogImage`/`twitterImage`/`defaultOgImage` value (2026-10-05): the

package/dist/seo/page-head.js

@@ -22,8 +22,15 @@ function buildOpenGraphElements(og) {
         { kind: "og", property: "og:type", content: og.type, priority: 141 },
         { kind: "og", property: "og:url", content: og.url, priority: 142 },
     ];
-    if (og.image)
+    if (og.image) {
         elements.push({ kind: "og", property: "og:image", content: og.image, priority: 143 });
+        if (og.imageWidth !== undefined)
+            elements.push({ kind: "og", property: "og:image:width", content: String(og.imageWidth), priority: 143 });
+        if (og.imageHeight !== undefined)
+            elements.push({ kind: "og", property: "og:image:height", content: String(og.imageHeight), priority: 143 });
+        if (og.imageType)
+            elements.push({ kind: "og", property: "og:image:type", content: og.imageType, priority: 143 });
+    }
     if (og.description)
         elements.push({ kind: "og", property: "og:description", content: og.description, priority: 144 });
     return elements;

package/dist/seo/seo.d.ts

@@ -37,6 +37,8 @@ export interface GetEntryMetaDeps {
     postRepo: SeoPostReadPort;
     settings: SeoSettingsReaderPort;
     media: ResolveSeoImageRefDeps;
+    /** Host-owned share-card variant; omitted preserves persisted transform choices. */
+    shareImageTransform?: string | undefined;
     originRegistry: OriginRegistryPort;
     runtimeMode: string;
     urls: SeoUrlsPort;

package/dist/seo/seo.js

@@ -1,6 +1,6 @@
 import { resolveWorkspaceOrigin, toAbsoluteUrl } from "./absolute-url.js";
 import { SeoEntryNotFoundError } from "./errors.js";
-import { resolveSeoImageRef } from "./media.js";
+import { resolveSeoImageDetails } from "./media.js";
 /** Featured image (2026-10-05) as a share-image ref: the core "public" transform every `/m/` URL
  *  already serves (`deps.ts`'s ADR-027 §4 registration). */
 function featuredImageRef(post) {
@@ -106,7 +106,7 @@ async function resolveRobots(deps, post, overrides, settings, workspaceId) {
 /** The first of `refs` that resolves through media, or `undefined`. @complexity O(r) resolves. */
 async function firstResolvedImage(deps, workspaceId, refs) {
     for (const ref of refs) {
-        const resolved = ref ? await resolveSeoImageRef({ deps: deps.media, input: { workspaceId, ref } }) : undefined;
+        const resolved = ref ? await resolveSeoImageDetails({ deps: deps.media, input: { workspaceId, ref } }, { transformName: deps.shareImageTransform }) : undefined;
         if (resolved)
             return resolved;
     }
@@ -125,8 +125,8 @@ async function resolveShareImages(deps, post, overrides, settings, workspaceId,
     const ogImageResolved = await firstResolvedImage(deps, workspaceId, overrides.ogImage ? [overrides.ogImage] : fallbacks);
     const twitterImageResolved = await firstResolvedImage(deps, workspaceId, overrides.twitterImage ? [overrides.twitterImage] : fallbacks);
     return {
-        ogImage: ogImageResolved ? toAbsoluteUrl({ origin, path: ogImageResolved }) : undefined,
-        twitterImage: twitterImageResolved ? toAbsoluteUrl({ origin, path: twitterImageResolved }) : undefined,
+        ogImage: ogImageResolved ? { ...ogImageResolved, url: toAbsoluteUrl({ origin, path: ogImageResolved.url }) } : undefined,
+        twitterImage: twitterImageResolved ? { ...twitterImageResolved, url: toAbsoluteUrl({ origin, path: twitterImageResolved.url }) } : undefined,
     };
 }
 /** title: override, else titleTemplate applied to entry.title. description: override > site default >
@@ -150,7 +150,11 @@ function buildOpenGraph(overrides, title, description, ogType, canonical, ogImag
         description: overrides.ogDescription ?? description,
         type: ogType,
         url: canonical,
-        image: ogImage,
+        image: ogImage?.url,
+        ...(ogImage?.ref === undefined ? {} : { imageRef: ogImage.ref }),
+        ...(ogImage?.width === undefined ? {} : { imageWidth: ogImage.width }),
+        ...(ogImage?.height === undefined ? {} : { imageHeight: ogImage.height }),
+        ...(ogImage?.type === undefined ? {} : { imageType: ogImage.type }),
         siteName: undefined,
     };
 }
@@ -159,7 +163,8 @@ function buildTwitter(overrides, title, description, twitterImage, settings) {
         card: overrides.twitterCard ?? "summary_large_image",
         title: overrides.twitterTitle ?? title,
         description: overrides.twitterDescription ?? description,
-        image: twitterImage,
+        image: twitterImage?.url,
+        ...(twitterImage?.ref === undefined ? {} : { imageRef: twitterImage.ref }),
         site: settings.twitterSite,
     };
 }

package/dist/seo/types.d.ts

@@ -188,6 +188,12 @@ export interface OpenGraph {
     type: OpenGraphType;
     url: string;
     image?: string | undefined;
+    /** Original selected source for admin diagnostics, before any share-card resize. */
+    imageRef?: string | undefined;
+    /** Known output metadata from the selected named transform, omitted for external URLs. */
+    imageWidth?: number | undefined;
+    imageHeight?: number | undefined;
+    imageType?: string | undefined;
     siteName?: string | undefined;
 }
 export interface TwitterCard {
@@ -195,6 +201,8 @@ export interface TwitterCard {
     title: string;
     description?: string | undefined;
     image?: string | undefined;
+    /** Original selected source for admin diagnostics, before any share-card resize. */
+    imageRef?: string | undefined;
     site?: string | undefined;
 }
 export interface RobotsDirective {

package/dist/seo/xml-escape.d.ts

@@ -10,7 +10,5 @@
  */
 /** {@link escapeHtml} with the XML named entity `'` for the apostrophe (sitemap and feed XML).
  *  @complexity O(text length). */
-export declare function escapeXml(required: {
-    text: string;
-}, _optional?: Record<string, never>): string;
+export { escapeXml } from "@jini-ai/core/text";
 //# sourceMappingURL=xml-escape.d.ts.map

package/dist/seo/xml-escape.js

@@ -8,12 +8,7 @@
  * other character first would double-escape the `&` that replacement introduced. The apostrophe
  * becomes the numeric `'` in HTML, because `'` is undefined in HTML4/XHTML1.
  */
-const XML_ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" };
-const SPECIAL = /[&<>"']/g;
 /** {@link escapeHtml} with the XML named entity `&apos;` for the apostrophe (sitemap and feed XML).
  *  @complexity O(text length). */
-// escapeHtml stays with the host renderer. A shared core owner for this leaf is a coordinator follow-up.
-export function escapeXml(required, _optional = {}) {
-    return required.text.replace(SPECIAL, (char) => XML_ENTITIES[char] ?? char);
-}
+export { escapeXml } from "@jini-ai/core/text";
 //# sourceMappingURL=xml-escape.js.map

package/dist/widgets/concurrency.d.ts

@@ -1,3 +1,27 @@
+/**
+ * @file A tiny per-key async mutex (SPEC-043 REQ-06/15, AC-04/EC-02).
+ *
+ * Purpose:
+ * `features/entries/write-service.ts`'s `updateEntry` reads the current row, checks
+ * `expectedVersion`, then writes — but `InMemoryEntryRepo.transaction` provides no real
+ * serialization (`async transaction(fn) { return fn(); }`), and the version check itself happens
+ * BEFORE that transaction call. Two truly concurrent callers racing the same entry id can both
+ * observe the pre-write version and both pass the check under the in-memory adapter (the real
+ * `SqliteEntryRepo.transaction`'s `BEGIN IMMEDIATE` already serializes real concurrent writers at
+ * the DB layer — this mutex is redundant-but-harmless there, and load-bearing for the in-memory
+ * path this test suite's concurrency assertions exercise).
+ *
+ * This module serializes the whole "read current version -> validate -> call updateEntry" sequence
+ * per entry id at the WIDGETS domain layer, restoring correct optimistic-concurrency semantics
+ * deterministically regardless of the underlying repo adapter's own concurrency properties.
+ *
+ * Architectural role:
+ * `widgets` domain-internal helper, not a frozen public contract.
+ */
+export type EntryLockState = Map<string, Promise<void>>;
+/** A host can own this state; the compatibility adapter still serializes existing callers.
+ * Idle keys are removed by withEntryLock. @complexity O(1). */
+export declare function createEntryLockState(_required: Record<string, never>, _optional?: Record<string, never>): EntryLockState;
 /**
  * Runs `fn` exclusively with respect to every other `withEntryLock` call sharing the same `key` —
  * callers queue in call order, each waiting for the previous holder to finish.
@@ -8,5 +32,7 @@
 export declare function withEntryLock<T>({ key, fn }: {
     key: string;
     fn: () => Promise<T>;
-}, _optional?: Record<string, never>): Promise<T>;
+}, { locks }?: {
+    locks?: EntryLockState;
+}): Promise<T>;
 //# sourceMappingURL=concurrency.d.ts.map

package/dist/widgets/concurrency.js

@@ -1,24 +1,9 @@
-/**
- * @file A tiny per-key async mutex (SPEC-043 REQ-06/15, AC-04/EC-02).
- *
- * Purpose:
- * `features/entries/write-service.ts`'s `updateEntry` reads the current row, checks
- * `expectedVersion`, then writes — but `InMemoryEntryRepo.transaction` provides no real
- * serialization (`async transaction(fn) { return fn(); }`), and the version check itself happens
- * BEFORE that transaction call. Two truly concurrent callers racing the same entry id can both
- * observe the pre-write version and both pass the check under the in-memory adapter (the real
- * `SqliteEntryRepo.transaction`'s `BEGIN IMMEDIATE` already serializes real concurrent writers at
- * the DB layer — this mutex is redundant-but-harmless there, and load-bearing for the in-memory
- * path this test suite's concurrency assertions exercise).
- *
- * This module serializes the whole "read current version -> validate -> call updateEntry" sequence
- * per entry id at the WIDGETS domain layer, restoring correct optimistic-concurrency semantics
- * deterministically regardless of the underlying repo adapter's own concurrency properties.
- *
- * Architectural role:
- * `widgets` domain-internal helper, not a frozen public contract.
- */
-const locks = new Map();
+/** A host can own this state; the compatibility adapter still serializes existing callers.
+ * Idle keys are removed by withEntryLock. @complexity O(1). */
+export function createEntryLockState(_required, _optional = {}) {
+    return new Map();
+}
+const defaultLocks = createEntryLockState({});
 /**
  * Runs `fn` exclusively with respect to every other `withEntryLock` call sharing the same `key` —
  * callers queue in call order, each waiting for the previous holder to finish.
@@ -26,19 +11,23 @@ const locks = new Map();
  * @complexity O(1) scheduling overhead beyond `fn`'s own cost.
  * @overallScore 100
  */
-export async function withEntryLock({ key, fn }, _optional = {}) {
+export async function withEntryLock({ key, fn }, { locks = defaultLocks } = {}) {
     const previous = locks.get(key) ?? Promise.resolve();
     let release;
     const next = new Promise((resolve) => {
         release = resolve;
     });
-    locks.set(key, previous.then(() => next));
+    const tail = previous.then(() => next);
+    locks.set(key, tail);
     await previous;
     try {
         return await fn();
     }
     finally {
         release();
+        // A newer waiter owns the key until it finishes; deleting its tail would let callers race.
+        if (locks.get(key) === tail)
+            locks.delete(key);
     }
 }
 //# sourceMappingURL=concurrency.js.map

package/dist/widgets/config-validation.js

@@ -1,3 +1,4 @@
+import { parseGalleryConfig } from "./markers/gallery.js";
 import { isNonArrayRecord } from "@jini-ai/core";
 /** Reports every key in `schema.required` that is missing from `value`. */
 function validateRequiredKeys(value, schema, path, errors) {
@@ -94,6 +95,11 @@ function walk(value, schema, path, errors) {
 export function validateWidgetConfig(required, _optional = {}) {
     const errors = [];
     walk(required.config, required.schema, "config", errors);
+    // The shared parser owns layout, id and CSS-ratio invariants; the schema narrows widgets to library images.
+    if (required.schema["x-gallery-config"] === true) {
+        for (const reason of parseGalleryConfig({ config: required.config }, { allowEmpty: true }).errors)
+            errors.push({ field: "config", reason });
+    }
     return { valid: errors.length === 0, fieldErrors: errors };
 }
 /** Pushes each declared free-text string under `schema` (recursion into declared `properties` and

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

@@ -0,0 +1,23 @@
+import type { PageHtmlEmbedRef } from './html/html-embeds.js';
+import type { WidgetRenderIR } from './types.js';
+export type GalleryMediaResolver = (required: {
+    refs: readonly PageHtmlEmbedRef[];
+}, optional?: Record<string, never>) => Promise<ReadonlyMap<string, WidgetRenderIR>>;
+export type GalleryIssueReporter = (required: {
+    key: string | null;
+    messages: readonly string[];
+}, optional?: Record<string, never>) => void;
+/** Resolve bounded, deduplicated gallery assets through the existing media resolver port.
+ * Occurrence keys preserve different layouts/alt/captions for the same assets on one page.
+ * At the page media budget, whole later galleries degrade instead of silently losing images.
+ * @complexity O(g*i) time/space for g markers and i<=50 images; one media batch of at most maxMedia.
+ */
+export declare function resolveGalleryEmbeds({ refs, resolveMedia }: {
+    refs: readonly PageHtmlEmbedRef[];
+    resolveMedia: GalleryMediaResolver;
+}, { maxMedia, timeoutMs, reportIssue }?: {
+    maxMedia?: number;
+    timeoutMs?: number;
+    reportIssue?: GalleryIssueReporter;
+}): Promise<ReadonlyMap<string, WidgetRenderIR>>;
+//# sourceMappingURL=gallery-resolver.d.ts.map

package/dist/widgets/gallery-resolver.js

@@ -0,0 +1,80 @@
+import { galleryMediaReferences, parseGalleryConfig } from './markers/gallery.js';
+/** Bound the media wait without taking ownership of the host repository's cancellation policy.
+ * The port has no abort signal; an expired call may finish in the background but is never awaited
+ * indefinitely and its timer is always released. No retries or duplicate repository calls.
+ */
+async function resolveGalleryMedia({ resolveMedia, refs, timeoutMs }) {
+    let timer;
+    try {
+        return await Promise.race([
+            resolveMedia({ refs }),
+            new Promise(resolve => { timer = setTimeout(() => resolve(undefined), timeoutMs); }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Resolve bounded, deduplicated gallery assets through the existing media resolver port.
+ * Occurrence keys preserve different layouts/alt/captions for the same assets on one page.
+ * At the page media budget, whole later galleries degrade instead of silently losing images.
+ * @complexity O(g*i) time/space for g markers and i<=50 images; one media batch of at most maxMedia.
+ */
+export async function resolveGalleryEmbeds({ refs, resolveMedia }, { maxMedia = 50, timeoutMs = 10000, reportIssue } = {}) {
+    const accepted = [];
+    const legacyIds = new Set();
+    const slugKeys = new Set();
+    const mediaRefs = new Map();
+    for (const ref of refs) {
+        const config = ref.config?.content ?? ref.config;
+        const parsed = parseGalleryConfig({ config }, { allowEmpty: ref.type === 'media' });
+        if (!parsed.config || ref.id === null) {
+            reportIssue?.({ key: ref.id, messages: parsed.errors });
+            continue;
+        }
+        const ids = new Set(parsed.config.mode === 'html'
+            ? galleryMediaReferences({ config: { html: parsed.config.html } }).map(item => item.mediaId)
+            : parsed.config.images.flatMap(item => (item.slug ?? item.mediaId) === undefined ? [] : [(item.slug ?? item.mediaId)]));
+        const added = [...ids].filter(id => !mediaRefs.has(id));
+        if (mediaRefs.size + added.length > maxMedia) {
+            reportIssue?.({ key: ref.id, messages: [`gallery media exceeds the page budget of ${maxMedia} distinct assets`] });
+            continue;
+        }
+        accepted.push({ ...ref, config: config });
+        const legacy = parsed.config.mode === undefined;
+        for (const key of ids)
+            (legacy ? legacyIds : slugKeys).add(key);
+        for (const id of added)
+            mediaRefs.set(id, { type: 'media', id: legacy ? id : null, slug: legacy ? null : id, name: null, variant: null, header: true });
+    }
+    // No second repository lifecycle: media owns workspace lookup, visibility, transforms and metadata.
+    const media = mediaRefs.size === 0 ? new Map() : await resolveGalleryMedia({ resolveMedia, refs: [...mediaRefs.values()], timeoutMs });
+    if (media === undefined) {
+        reportIssue?.({ key: null, messages: ['gallery media resolution timed out'] });
+        return new Map();
+    }
+    // Author-supplied ids are map keys, including names such as __proto__; never assign them onto
+    // an object with a prototype or inherit a fake media record from Object.prototype.
+    const imageProps = Object.create(null);
+    for (const [id, ir] of media) {
+        // Legacy mediaId is an indexed asset id, not the single-media marker's slug alias. The reused
+        // media resolver accepts both; accepting a slug here would render an asset that the pure
+        // entry_refs extractor cannot protect, since it cannot resolve a slug to the canonical id.
+        // New slug content deliberately indexes authored keys; the host usage adapter reads id and slug.
+        if (legacyIds.has(id) && !slugKeys.has(id)) {
+            if (ir.props.assetId !== id) {
+                reportIssue?.({ key: id, messages: ['gallery mediaId must be the canonical media id, not a slug'] });
+                continue;
+            }
+            // A video resolved by the generic media pipeline is not an image in a legacy gallery.
+            if (typeof ir.props.contentType === 'string' && (ir.props.contentType.startsWith('video/') || ir.props.contentType.startsWith('audio/')))
+                continue;
+        }
+        imageProps[id] = ir.props;
+    }
+    for (const key of slugKeys)
+        if (!media.has(key))
+            reportIssue?.({ key, messages: [`unknown media slug: ${key}`] });
+    return new Map(accepted.map(ref => [ref.id, { componentId: ref.type === 'media' ? 'media' : 'gallery', props: { config: ref.config, media: imageProps } }]));
+}
+//# sourceMappingURL=gallery-resolver.js.map

package/dist/widgets/html/gallery-render.d.ts

@@ -0,0 +1,24 @@
+import type { JsonObject } from '@jini-ai/core/primitives';
+import { type GalleryImage } from '../markers/gallery.js';
+/** Layout-only baseline; host themes override jini classes/custom properties without palette coupling. */
+export declare const GALLERY_STYLE = "<style data-jini-gallery-style>\n.jini-gallery{gap:var(--jini-gallery-gap,1rem)}\n.jini-gallery-item{margin:0;min-width:0;break-inside:avoid}\n.jini-gallery audio{display:block;width:100%}\n.jini-gallery img,.jini-gallery video{display:block;width:100%;height:auto;aspect-ratio:var(--jini-gallery-ratio,auto);object-fit:cover}\n.jini-gallery-single{display:grid;grid-template-columns:1fr}\n.jini-gallery-grid{display:grid;grid-template-columns:repeat(var(--jini-gallery-columns,3),minmax(0,1fr))}\n.jini-gallery-masonry{columns:var(--jini-gallery-columns,3);column-gap:var(--jini-gallery-gap,1rem)}\n.jini-gallery-masonry .jini-gallery-item{margin-block-end:var(--jini-gallery-gap,1rem)}\n.jini-gallery-carousel{display:flex;overflow-x:auto;scroll-snap-type:x mandatory}\n.jini-gallery-carousel .jini-gallery-item{flex:0 0 min(85%,36rem);scroll-snap-align:start}\n@media(max-width:48rem){.jini-gallery-grid{grid-template-columns:repeat(2,minmax(0,1fr))}.jini-gallery-masonry{columns:2}}\n@media(max-width:30rem){.jini-gallery-grid{grid-template-columns:1fr}.jini-gallery-masonry{columns:1}}\n</style>";
+export type GalleryImageRenderer = (required: {
+    image: GalleryImage & {
+        alt: string;
+    };
+    media: JsonObject | undefined;
+}, optional?: Record<string, never>) => string;
+/** Server-render accessible gallery markup. Image URLs, metadata and srcset belong to the host
+ * image pipeline supplied as a port, never templated here. Invalid config produces no output.
+ * @complexity O(n) time and output space for at most 50 images, without I/O.
+ */
+export declare function renderGallery({ config, media, renderImage, renderRawHtml }: {
+    config: unknown;
+    media?: unknown;
+    renderImage: GalleryImageRenderer;
+    renderRawHtml?: (required: {
+        html: string;
+        media: Record<string, JsonObject>;
+    }, optional?: Record<string, never>) => string;
+}, _optional?: Record<string, never>): string;
+//# sourceMappingURL=gallery-render.d.ts.map