@jini-ai/cms 0.5.4 → 0.5.6

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

package/dist/widgets/html/gallery-render.js

@@ -0,0 +1,65 @@
+import { escapeHtml } from '@jini-ai/core/text';
+import { parseEmbedHtmlAttributes } from '../markers/html-attributes.js';
+import { parseGalleryConfig } from '../markers/gallery.js';
+/** Layout-only baseline; host themes override jini classes/custom properties without palette coupling. */
+export const GALLERY_STYLE = `<style data-jini-gallery-style>
+.jini-gallery{gap:var(--jini-gallery-gap,1rem)}
+.jini-gallery-item{margin:0;min-width:0;break-inside:avoid}
+.jini-gallery audio{display:block;width:100%}
+.jini-gallery img,.jini-gallery video{display:block;width:100%;height:auto;aspect-ratio:var(--jini-gallery-ratio,auto);object-fit:cover}
+.jini-gallery-single{display:grid;grid-template-columns:1fr}
+.jini-gallery-grid{display:grid;grid-template-columns:repeat(var(--jini-gallery-columns,3),minmax(0,1fr))}
+.jini-gallery-masonry{columns:var(--jini-gallery-columns,3);column-gap:var(--jini-gallery-gap,1rem)}
+.jini-gallery-masonry .jini-gallery-item{margin-block-end:var(--jini-gallery-gap,1rem)}
+.jini-gallery-carousel{display:flex;overflow-x:auto;scroll-snap-type:x mandatory}
+.jini-gallery-carousel .jini-gallery-item{flex:0 0 min(85%,36rem);scroll-snap-align:start}
+@media(max-width:48rem){.jini-gallery-grid{grid-template-columns:repeat(2,minmax(0,1fr))}.jini-gallery-masonry{columns:2}}
+@media(max-width:30rem){.jini-gallery-grid{grid-template-columns:1fr}.jini-gallery-masonry{columns:1}}
+</style>`;
+/** Render one ordered figure using the host's established image renderer and alt fallback.
+ * Missing alt is flagged in markup as well as validation; an explicit empty alt stays decorative.
+ */
+function renderFigure({ image, media, renderImage }) {
+    if ((image.slug !== undefined || image.mediaId !== undefined) && !media)
+        return '';
+    const storedAlt = typeof media?.alt === 'string' && media.alt.length > 0 ? media.alt : undefined;
+    const alt = image.alt ?? storedAlt;
+    const missingAlt = alt === undefined ? ' data-jini-alt-missing="true"' : '';
+    const markup = renderImage({ image: { ...image, alt: alt ?? '' }, media });
+    const caption = image.caption === undefined ? '' : `<figcaption>${escapeHtml({ text: image.caption })}</figcaption>`;
+    return `<figure class="jini-gallery-item"${missingAlt}>${markup}${caption}</figure>`;
+}
+/** 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 function renderGallery({ config, media, renderImage, renderRawHtml }, _optional = {}) {
+    const parsed = parseGalleryConfig({ config }, { allowEmpty: true });
+    if (!parsed.config)
+        return '';
+    const gallery = parsed.config;
+    const records = typeof media === 'object' && media !== null && !Array.isArray(media) ? media : {};
+    if (gallery.mode === 'html')
+        return renderRawHtml?.({ html: gallery.html ?? '', media: records }) ?? '';
+    // Media-mode configs come from the Media widget editor; naming the Gallery editor there misleads.
+    if (gallery.images.length === 0)
+        return `<div class="jini-gallery jini-gallery-empty" role="note">${gallery.mode === 'media' ? 'Choose media in the Media widget editor.' : 'Choose images in the Gallery widget editor.'}</div>`;
+    const figures = gallery.images.map(image => renderFigure({ image, media: (image.slug ?? image.mediaId) !== undefined && Object.hasOwn(records, (image.slug ?? image.mediaId)) ? records[(image.slug ?? image.mediaId)] : undefined, renderImage })).join('');
+    const ratio = gallery.aspectRatio === undefined ? '' : `;--jini-gallery-ratio:${gallery.aspectRatio}`;
+    // TODO: bind data-jini-lightbox through a host theme's lightbox script slot when one exists.
+    // Until then the gallery stays readable and keyboard-scrollable without any client script.
+    const attributes = {
+        role: 'region', 'aria-label': gallery.mode === 'media' ? 'Media' : 'Image gallery',
+        ...(gallery.layout === 'carousel' ? { tabindex: '0', 'aria-roledescription': 'carousel' } : {}),
+        ...(gallery.lightbox === true ? { 'data-jini-lightbox': 'true' } : {}),
+        ...parseEmbedHtmlAttributes({ text: gallery.htmlAttributes ?? '' }).attributes,
+    };
+    const extraClass = [gallery.cssClass, attributes.class].filter(Boolean).join(' ');
+    delete attributes.class;
+    // Layout styles remain the base; authored safe style declarations override them in order.
+    const authoredStyle = attributes.style;
+    delete attributes.style;
+    const extra = Object.entries(attributes).map(([name, value]) => ` ${name}="${escapeHtml({ text: value })}"`).join('');
+    return GALLERY_STYLE + `<div class="jini-gallery jini-gallery-${gallery.layout}${extraClass ? ` ${escapeHtml({ text: extraClass })}` : ''}"${extra} style="--jini-gallery-columns:${gallery.columns ?? 3}${ratio}${authoredStyle ? `;${escapeHtml({ text: authoredStyle })}` : ''}">${figures}</div>`;
+}
+//# sourceMappingURL=gallery-render.js.map

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

@@ -107,6 +107,8 @@ import { type MarkerAttribute } from "../markers/marker.js";
  * — this interface is the compatibility seam, not a ceiling.
  */
 export interface PageHtmlEmbedRef {
+    /** Occurrence identity for placement overrides sharing one saved widget. */
+    readonly placementKey?: string;
     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
@@ -129,6 +131,8 @@ export interface PageHtmlEmbedRef {
      */
     readonly header: boolean;
     readonly mode?: "html";
+    /** Full inline configuration for compound embeds; existing scalar projections remain stable. */
+    readonly config?: Readonly<Record<string, unknown>>;
 }
 /**
  * Resource bound (Programmer workflow step 5a4) mirroring `embed-service.ts`'s

package/dist/widgets/html/html-embeds.js

@@ -156,12 +156,18 @@ function configBooleanDefaultTrue(config, key) {
 function toEmbedRef(marker) {
     return {
         type: marker.type.toLowerCase(),
-        id: normalizeEmbedId(configString(marker.config, "id")),
+        // Only saved widget overlays use placement keys. Inline Media content already has its own
+        // occurrence id below; a second key would make rendering miss the resolver's media:<n> result.
+        ...(marker.type.toLowerCase() === "widget" && marker.config.content !== undefined ? { placementKey: `placement:${marker.occurrence}` } : {}),
+        // Inline galleries have no target entity. Key by occurrence so repeated assets with different
+        // layouts/captions cannot overwrite each other's resolved IR, even with an authored id.
+        id: (marker.type.toLowerCase() === "gallery" || (marker.type.toLowerCase() === "media" && (marker.config.content !== undefined || marker.config.items !== undefined || marker.config.html !== undefined))) ? `${marker.type.toLowerCase()}:${marker.occurrence}` : normalizeEmbedId(configString(marker.config, "id")),
         slug: normalizeEmbedSlug(configString(marker.config, "slug")),
         name: configString(marker.config, "name"),
         variant: configString(marker.config, "variant"),
         header: configBooleanDefaultTrue(marker.config, "header"),
         ...(marker.config.mode === "html" ? { mode: "html" } : {}),
+        config: marker.config,
     };
 }
 /**

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

@@ -1,5 +1,8 @@
+export { resolveGalleryWidgetMedia } from "../resolver-service.js";
 export * from "./html-embeds.js";
 export * from "./legacy-widget-markers.js";
+export * from "./gallery-render.js";
 export * from "./resolve-html-page-embeds.js";
 export type { ResolveHtmlPageEmbedsDeps } from "../resolver-service.js";
+export * from './server-fragment.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/widgets/html/index.js

@@ -1,4 +1,7 @@
+export { resolveGalleryWidgetMedia } from "../resolver-service.js";
 export * from "./html-embeds.js";
 export * from "./legacy-widget-markers.js";
+export * from "./gallery-render.js";
 export * from "./resolve-html-page-embeds.js";
+export * from './server-fragment.js';
 //# sourceMappingURL=index.js.map

package/dist/widgets/html/server-fragment.d.ts

@@ -0,0 +1,9 @@
+/** Reject executable/unsupported markup rather than quietly preserving a plugin's unsafe output.
+ * URLs are local or HTTP(S); form submission remains native. No inline style, events, SVG,
+ * iframe, script, srcdoc, data URLs, or enhancement assets are admitted. */
+export declare function validateServerWidgetFragment(required: {
+    html: string;
+}, optional?: {
+    maxBytes?: number;
+}): string;
+//# sourceMappingURL=server-fragment.d.ts.map

package/dist/widgets/html/server-fragment.js

@@ -0,0 +1,38 @@
+/** Public plugin fragments are HTML, never same-origin script (ADR-025). Use the existing
+ * HTML parser, not regex sanitization: decoded attributes and foreign namespaces matter. */
+import { parseFragment, serialize } from 'parse5';
+const ELEMENTS = new Set(['div', 'span', 'p', 'br', 'hr', 'strong', 'em', 'b', 'i', 'small', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'ul', 'ol', 'li', 'dl', 'dt', 'dd', 'blockquote', 'pre', 'code', 'a', 'img', 'figure', 'figcaption', 'table', 'thead', 'tbody', 'tr', 'th', 'td', 'section', 'article', 'aside', 'header', 'footer', 'nav', 'form', 'label', 'input', 'textarea', 'select', 'option', 'button']);
+const ATTRIBUTES = new Set(['id', 'class', 'title', 'role', 'href', 'src', 'alt', 'width', 'height', 'action', 'method', 'name', 'value', 'type', 'required', 'disabled', 'checked', 'selected', 'multiple', 'placeholder', 'for', 'rows', 'cols', 'min', 'max', 'step', 'colspan', 'rowspan']);
+/** Reject executable/unsupported markup rather than quietly preserving a plugin's unsafe output.
+ * URLs are local or HTTP(S); form submission remains native. No inline style, events, SVG,
+ * iframe, script, srcdoc, data URLs, or enhancement assets are admitted. */
+export function validateServerWidgetFragment(required, optional = {}) {
+    if (new TextEncoder().encode(required.html).byteLength > (optional.maxBytes ?? 65536))
+        throw new Error('widget HTML exceeds its size cap');
+    const root = parseFragment(required.html);
+    const visit = (node) => {
+        if ('tagName' in node) {
+            if (node.namespaceURI !== 'http://www.w3.org/1999/xhtml' || !ELEMENTS.has(node.tagName))
+                throw new Error('executable or unsupported widget element');
+            for (const attr of node.attrs) {
+                if (attr.namespace || (!ATTRIBUTES.has(attr.name) && !/^aria-[a-z-]+$/.test(attr.name)))
+                    throw new Error('executable or unsupported widget attribute');
+                if (['href', 'src', 'action'].includes(attr.name)) {
+                    // URL parsing catches entity-decoded schemes and embedded tab/newline obfuscation.
+                    const value = attr.value;
+                    if (/[\u0000-\u0020\\]/.test(value) || value.startsWith('//'))
+                        throw new Error('unsafe widget URL');
+                    const url = new URL(value, 'https://widget.invalid/');
+                    if (!['http:', 'https:'].includes(url.protocol))
+                        throw new Error('unsafe widget URL');
+                }
+            }
+            for (const child of node.childNodes)
+                visit(child);
+        }
+    };
+    for (const node of root.childNodes)
+        visit(node);
+    return serialize(root);
+}
+//# sourceMappingURL=server-fragment.js.map