@jini-ai/cms 0.3.5 → 0.3.7

package/dist/media/media-service.js

@@ -54,21 +54,46 @@ import { createHash } from "node:crypto";
 import { MediaConflictError, MediaNotFoundError, MediaSourceImmutableError, MediaStillReferencedError, MediaValidationError, } from "./types.js";
 import { withSha256Lock } from "./blob-gc-lock.js";
 import { tombstoneBlobIfUnreferenced } from "./blob-gc.js";
+import { describeMediaHtmlAttributeError, parseMediaHtmlAttributes } from "./html-attributes.js";
 export { MediaConflictError, MediaNotFoundError, MediaSourceImmutableError, MediaStillReferencedError, MediaValidationError, };
 /** Default byte-size cap (this pass's stand-in for the real ingress policy's streaming cap). */
 export const DEFAULT_MAX_UPLOAD_BYTES = 10 * 1024 * 1024; // 10 MiB
+/**
+ * Renders a byte count as a human-readable MB figure for the size-cap rejection below (2026-09-21).
+ * Every real caller passes a MiB-scale `maxUploadBytes` (10 MiB default, or a host override such as
+ * Tovu's 50 MiB), so one decimal place is enough precision without ever showing a raw byte count —
+ * the whole point of this fix (see `uploadMedia`'s size-cap check, and `agent-tools.ts`'s file header
+ * for why the catalog description can no longer state a specific number either). `toFixed(1)`'s
+ * trailing `.0` is trimmed so a clean multiple of 1 MB (the common case) reads as `10 MB`, not `10.0
+ * MB`.
+ *
+ * @complexity O(1).
+ */
+function formatMaxUploadBytesAsMb(bytes) {
+    const mb = bytes / (1024 * 1024);
+    const rounded = mb.toFixed(1);
+    return `${rounded.endsWith(".0") ? rounded.slice(0, -2) : rounded} MB`;
+}
 /**
  * Advisory MIME allowlist. SVG is deliberately EXCLUDED (not "TODO, forgot") —
  * SVG must be sanitized at ingest before it's safe to store;
  * that sanitizer is not built in this pass, so SVG upload is rejected rather
  * than accepted unsanitized.
  *
+ * `image/avif` (owner-directed, 2026-09-06): a fifth still-image type, on the
+ * same footing as the four above — `content-type-sniffer.ts` identifies it by
+ * ISO-BMFF brand and the installed `sharp`/libvips build decodes it, so it
+ * flows through the ordinary transform/rendition pipeline and is re-encoded
+ * like any other image. Adding it required a matching sniffer fix, not just
+ * this line: AVIF shares MP4's `ftyp` container tag, so before that fix an
+ * AVIF was sniffed as `video/mp4` and served as an unplayable video.
+ *
  * `video/mp4`/`video/webm` (owner-directed, 2026-08-24): the two formats
  * `content-type-sniffer.ts` already recognizes by magic bytes. Unlike the four
  * image types above, an accepted video is never re-encoded — there is no
  * `TransformFormat` for video (`transform-types.ts`'s union is image-only), so
  * a video asset's public URL bypasses the transform/rendition pipeline
- * entirely and serves the original bytes as-is (host concern; see Tovu's
+ * entirely and serves the original bytes as-is (host concern; see the host's
  * `routes/site/media-rendition.ts`). This widens the SAME advisory,
  * client-declared-string check item 4 above already discloses as untrusted —
  * no new ingress hardening was added for video.
@@ -78,6 +103,7 @@ export const DEFAULT_ALLOWED_MIME_TYPES = new Set([
     "image/png",
     "image/webp",
     "image/gif",
+    "image/avif",
     "video/mp4",
     "video/webm",
 ]);
@@ -108,6 +134,103 @@ function deriveTitleFromFilename(filename) {
     const base = filename.trim().replace(/\.[^./\\]+$/, "");
     return base.trim() || "Untitled";
 }
+/** Shared slug-format rule (2026-09-07) — same shape as `post`'s `SLUG_FORMAT_PATTERN`: lowercase
+ *  letters, digits, and dashes only. Media slugs have no reserved-word list (`post`'s `admin`/`api`
+ *  exclusions exist because a post slug can become a literal URL path segment a route dispatches
+ *  on; a media slug is only ever a lookup key, never a route itself, so that hazard doesn't apply). */
+const MEDIA_SLUG_FORMAT_PATTERN = /^[a-z0-9-]+$/;
+/**
+ * Slugs that spell a UUID are refused outright (2026-09-07 fix).
+ *
+ * A lowercase UUID is `[a-z0-9-]+` character for character, so {@link MEDIA_SLUG_FORMAT_PATTERN}
+ * happily accepted one — and {@link findMediaByIdOrSlug} used to resolve SLUG FIRST, so pointing one
+ * asset's slug at another asset's `id` silently took over every reference already authored against
+ * that id (every `/m/{id}/…` URL a host's renderer has ever emitted for the victim). That resolution
+ * order is now id-first, which closes the hijack for rows that already carry such a slug; this rule
+ * is the write-path half — a slug that can only ever shadow an id is not a slug anyone wants, so it
+ * is refused where a human can still see why rather than silently shadowed at read time.
+ *
+ * Shape-based, not a lookup: it rejects EVERY UUID-shaped value, not only ones that currently
+ * collide, so a slug cannot become a hijack later when some future upload happens to mint that id.
+ * Ordinary hex-and-dash slugs (`abc-123-def`, `2026-09-07-launch-clip`) are unaffected — nothing but
+ * the exact 8-4-4-4-12 hex grouping matches.
+ */
+const MEDIA_SLUG_UUID_SHAPE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** Shared slug max-length rule (2026-09-07) — same bound as `post.ts`'s `MAX_SLUG_LENGTH`, reused
+ *  rather than inventing a second number. `post.ts` only enforces this on its EXPLICIT/caller-
+ *  supplied slug path (`resolveExplicitSlug`, reject-with-error); its own title-derived path is
+ *  uncapped. Media applies the same bound to BOTH paths, but differently per path's nature: an
+ *  explicit edit ({@link resolveSlugForUpdate}) rejects with an error, exactly like `post.ts`,
+ *  because a human typed it and should see why it was refused; a derived slug
+ *  ({@link deriveUniqueMediaSlug}) truncates instead of rejecting, because nothing is prompting a
+ *  human for a shorter value — silently truncating an internally-derived value is the same
+ *  "coerce, don't fail" convention `deriveTitleFromFilename`/`slugifyMediaTitle` already use. */
+const MEDIA_MAX_SLUG_LENGTH = 120;
+export function isValidMediaSlugFormat(slug) {
+    return MEDIA_SLUG_FORMAT_PATTERN.test(slug) && !MEDIA_SLUG_UUID_SHAPE_PATTERN.test(slug);
+}
+/** Truncates a slug candidate to `maxLength`, stripping a trailing dash the cut can introduce (so a
+ *  truncation never leaves a slug ending mid-word with a dangling "-"), falling back to `"untitled"`
+ *  if nothing legible survives (only reachable when `maxLength` itself is tiny, e.g. while reserving
+ *  room for a long numeric suffix — see {@link deriveUniqueMediaSlug}). A no-op when `candidate` is
+ *  already within bounds. */
+function capSlugCandidate(candidate, maxLength) {
+    if (candidate.length <= maxLength)
+        return candidate;
+    return candidate.slice(0, Math.max(maxLength, 0)).replace(/-+$/, "") || "untitled";
+}
+/** Turns free text into a slug candidate: lowercase, non-alphanumeric runs collapsed to one dash,
+ *  leading/trailing dashes trimmed. Same algorithm as `post.ts`'s private `slugify` (duplicated, not
+ *  imported — cross-repo: `post.ts` lives in the host, this file in `@jini-ai/cms`; this codebase's own
+ *  precedent for a small hand-copied helper mirrored across a repo boundary is `DEFAULT_ALLOWED_MIME_TYPES`
+ *  vs. the host's `FILE_HANDLER_ALLOWED_MIME_TYPES`/`IMPORTABLE_CONTENT_TYPES`). Never throws and never
+ *  returns `undefined` — an all-punctuation input collapses to `""`, which every caller here treats
+ *  as "derive nothing, fall back to a fixed default" rather than a malformed-input error. */
+function slugifyMediaTitle(title) {
+    return title
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Derives a unique-per-workspace slug from `title`, suffixing `-2`, `-3`, … on collision — the
+ * identical loop shape `post.ts`'s `createPost` uses for its own derived-slug path. Shared by
+ * {@link uploadMedia} (derive-on-create) and the backfill a host runs once for pre-existing rows
+ * with no slug yet (see the host's `development/scripts/backfill-media-slugs.ts`).
+ *
+ * `base` falls back to `"untitled"` when `title` slugifies to the empty string (all-punctuation or
+ * non-Latin titles that `slugifyMediaTitle` strips to nothing) — `uploadMedia`'s own title is never
+ * empty (`deriveTitleFromFilename` guarantees a non-empty string), but the backfill script
+ * (`development/scripts/backfill-media-slugs.ts`, host-side) calls this against arbitrary pre-existing
+ * titles, so this fallback is load-bearing there, not just a defensive floor. Note this is the SAME
+ * fallback base every empty-slugifying title collapses onto, so two such titles in one workspace
+ * collide on `"untitled"` and are disambiguated by the ordinary suffix loop below exactly like any
+ * other collision — an empty derived slug is never inserted as a bare empty string (which a unique
+ * index would treat as one specific value, not "no value," and a SECOND empty string would then
+ * violate it outright rather than surfacing a friendly conflict).
+ *
+ * `base` (after the empty-string fallback) is also capped at {@link MEDIA_MAX_SLUG_LENGTH} via
+ * {@link capSlugCandidate} before any suffix is considered — a long machine-generated title must not
+ * produce an equally long slug. When a collision forces a suffix, the BASE (never the suffix itself)
+ * is re-truncated just enough to keep the whole `base-suffix` candidate within the cap, so every
+ * candidate this loop ever checks already obeys the length bound, not just the first one.
+ *
+ * @complexity O(n) repo round-trips in the worst case, where n is the number of prior collisions on
+ * the same base slug — bounded in practice by how many same-titled uploads exist in one workspace.
+ */
+async function deriveUniqueMediaSlug(mediaRepo, workspaceId, title) {
+    const base = capSlugCandidate(slugifyMediaTitle(title) || "untitled", MEDIA_MAX_SLUG_LENGTH);
+    let slug = base;
+    let suffix = 1;
+    while (await mediaRepo.findBySlug({ workspaceId, slug })) {
+        suffix += 1;
+        const suffixText = `-${suffix}`;
+        const truncatedBase = capSlugCandidate(base, MEDIA_MAX_SLUG_LENGTH - suffixText.length);
+        slug = `${truncatedBase}${suffixText}`;
+    }
+    return slug;
+}
 /**
  * Validates, hashes, dedups by `(workspaceId, sha256)`, and writes a new media
  * asset. Ordering (INV-1a): bytes are written (or found already
@@ -126,7 +249,8 @@ function deriveTitleFromFilename(filename) {
  *
  * @complexity O(1) — one hash, one blob lookup, at most one blob write, one
  * media write, one rendition write (the lock itself adds O(1) scheduling
- * overhead, not a scan).
+ * overhead, not a scan) — plus {@link deriveUniqueMediaSlug}'s own O(n) in the number of prior
+ * same-base-slug collisions (see that function's doc).
  * @overallScore 100
  */
 export async function uploadMedia(required, optional = {}) {
@@ -140,7 +264,7 @@ export async function uploadMedia(required, optional = {}) {
         throw new MediaValidationError("uploaded file is empty");
     }
     if (input.bytes.byteLength > maxUploadBytes) {
-        throw new MediaValidationError(`uploaded file exceeds the ${maxUploadBytes}-byte size cap`);
+        throw new MediaValidationError(`uploaded file exceeds the ${formatMaxUploadBytesAsMb(maxUploadBytes)} size cap`);
     }
     const sha256 = createHash("sha256").update(input.bytes).digest("hex");
     const nowIso = deps.clock.nowIso();
@@ -170,10 +294,13 @@ export async function uploadMedia(required, optional = {}) {
         });
         return written.storageKey;
     });
+    const title = deriveTitleFromFilename(input.filename);
+    const slug = await deriveUniqueMediaSlug(deps.mediaRepo, input.workspaceId, title);
     const media = {
         id: deps.idGen.newId(),
         workspaceId: input.workspaceId,
-        title: deriveTitleFromFilename(input.filename),
+        title,
+        slug,
         alt: input.alt?.trim() ?? "",
         caption: input.caption?.trim() ?? "",
         credit: input.credit?.trim() ?? "",
@@ -187,6 +314,7 @@ export async function uploadMedia(required, optional = {}) {
         width: null,
         height: null,
         cssClass: null,
+        htmlAttributes: null,
     };
     await deps.mediaRepo.save(media);
     await deps.renditionRepo.save({
@@ -228,12 +356,45 @@ export async function getMediaById(required, _optional = {}) {
     return { media };
 }
 /**
- * Updates editorial-only fields (title/alt/caption/credit). `source.sha256` is
- * write-once — this function's input type has no `sha256` field,
+ * Resolves a media asset by either its id or its slug — ID FIRST, slug second. The slug is the
+ * handle a human typed into an embed marker or a hand-authored `<img>`/`<video>` tag; the id is the
+ * opaque UUID every existing reference already uses, and every URL a host's renderer emits.
+ *
+ * THE ORDER IS A SECURITY PROPERTY, not a preference (2026-09-07). This resolved slug-first, on the
+ * documented assumption that "an id never collides with a slug in practice since slugs pass through
+ * {@link isValidMediaSlugFormat}". That assumption was false: a lowercase UUID matched the old slug
+ * pattern `[a-z0-9-]+` exactly, so setting asset B's slug to asset A's id made every `/m/{A.id}/…`
+ * URL — the ones a renderer emitted for A, already live in published pages — resolve to B instead.
+ * An id is minted by the system and is never a value a human chooses, so it must always win; the
+ * write path additionally refuses UUID-shaped slugs now (see
+ * {@link MEDIA_SLUG_UUID_SHAPE_PATTERN}), but ordering is what protects rows written before that
+ * rule existed. Id-first costs nothing on the slug path: a real slug simply misses the id lookup and
+ * falls through.
+ *
+ * Never throws (unlike {@link getMediaById}): every call site that needs this (an embed resolver, a
+ * public rendition route) already has its own REQ-27-style non-throwing-miss contract, so this
+ * returns `null` on failure and lets the caller apply its own not-found handling rather than forcing
+ * one shape on every caller.
+ *
+ * @complexity O(1) — at most two indexed repo lookups, short-circuited on the first hit.
+ */
+export async function findMediaByIdOrSlug(required, _optional = {}) {
+    const { deps, input } = required;
+    const byId = await deps.mediaRepo.findById({ workspaceId: input.workspaceId, id: input.idOrSlug });
+    if (byId)
+        return byId;
+    return deps.mediaRepo.findBySlug({ workspaceId: input.workspaceId, slug: input.idOrSlug });
+}
+/**
+ * Updates editorial-only fields (title/alt/caption/credit/slug/width/height/cssClass).
+ * `source.sha256` is write-once — this function's input type has no `sha256` field,
  * so there is no code path here that can touch it (see `resolveWriteOnceSource`
  * doc for the directly-tested invariant this relies on).
  *
- * @complexity O(1).
+ * `slug` (2026-09-07) is validated and uniqueness-checked by {@link resolveSlugForUpdate} when
+ * provided; every other field keeps its pre-existing undefined-means-unchanged contract.
+ *
+ * @complexity O(1) plus {@link resolveSlugForUpdate}'s own O(1) when `input.slug` is provided.
  * @overallScore 100
  */
 /** Validates a `width`/`height` override: must be a positive integer. `null` (explicit clear) and
@@ -243,6 +404,54 @@ function assertPositiveIntegerOrThrow(value, field) {
         throw new MediaValidationError(`media.${field} must be a positive integer, got ${value}`);
     }
 }
+/**
+ * Validates and normalizes an explicit `slug` edit, then enforces per-workspace uniqueness against
+ * every OTHER row — an app-level courtesy check, not the enforcement itself (see `MediaRecord.slug`'s
+ * doc): the host's DB unique index is what actually prevents two rows from landing on the same slug
+ * under a concurrent write; this check only exists so a normal, non-racing caller sees a clear
+ * `MediaConflictError` naming the conflict instead of a raw constraint-violation message surfacing
+ * from whatever the host's repo adapter throws. Mirrors `post.ts`'s `assertSlugAvailableForUpdate`
+ * (same "claiming your own current slug is not a conflict" rule).
+ *
+ * @complexity O(1) — one format check, one uniqueness lookup.
+ */
+async function resolveSlugForUpdate(mediaRepo, workspaceId, id, rawSlug) {
+    const slug = rawSlug.trim().toLowerCase();
+    if (!slug || !isValidMediaSlugFormat(slug)) {
+        throw new MediaValidationError("slug must use lowercase letters, numbers, and dashes, and must not be shaped like a UUID");
+    }
+    // Same bound and rejection style as `post.ts`'s `resolveExplicitSlug` — a human typed this value,
+    // so it is refused with a clear reason rather than silently truncated (unlike the derived-on-
+    // upload path, see `MEDIA_MAX_SLUG_LENGTH`'s doc).
+    if (slug.length > MEDIA_MAX_SLUG_LENGTH) {
+        throw new MediaValidationError(`slug must be ${MEDIA_MAX_SLUG_LENGTH} characters or fewer`);
+    }
+    const duplicate = await mediaRepo.findBySlug({ workspaceId, slug });
+    if (duplicate && duplicate.id !== id) {
+        throw new MediaConflictError(`slug '${slug}' is already used by media '${duplicate.id}'`);
+    }
+    return slug;
+}
+/**
+ * Validates an explicit `htmlAttributes` edit against `html-attributes.ts`'s allowlist — a stored-
+ * XSS boundary, not a syntax convenience (see `MediaRecord.htmlAttributes`'s own doc). Throws
+ * `MediaValidationError` naming the exact rejected attribute the moment `parseMediaHtmlAttributes`
+ * reports one; the caller (`updateMediaMetadata`) must never reach its own `save()` call when this
+ * throws, so an invalid value is never partially or fully persisted. A value that validates but
+ * trims to empty stores as `null`, matching `cssClass`'s identical "empty means unset" convention.
+ *
+ * @complexity O(n) in the input string's length (one `parseMediaHtmlAttributes` pass).
+ */
+function resolveHtmlAttributesForUpdate(rawValue) {
+    const trimmed = rawValue.trim();
+    if (trimmed === "")
+        return null;
+    const parsed = parseMediaHtmlAttributes(trimmed);
+    if (parsed.error) {
+        throw new MediaValidationError(`media.htmlAttributes: ${describeMediaHtmlAttributeError(parsed.error)}`);
+    }
+    return trimmed;
+}
 export async function updateMediaMetadata(required, _optional = {}) {
     const { deps, input } = required;
     const existing = await deps.mediaRepo.findById({ workspaceId: input.workspaceId, id: input.id });
@@ -252,15 +461,29 @@ export async function updateMediaMetadata(required, _optional = {}) {
         assertPositiveIntegerOrThrow(input.width, "width");
     if (input.height !== undefined && input.height !== null)
         assertPositiveIntegerOrThrow(input.height, "height");
+    const slug = input.slug !== undefined
+        ? await resolveSlugForUpdate(deps.mediaRepo, input.workspaceId, input.id, input.slug)
+        : existing.slug;
+    // Validated BEFORE the record is built (same "fail before any write" discipline `assertPositive
+    // IntegerOrThrow` above already follows) — an invalid value must never reach `save()`.
+    const htmlAttributes = input.htmlAttributes !== undefined
+        ? input.htmlAttributes === null
+            ? null
+            : resolveHtmlAttributesForUpdate(input.htmlAttributes)
+        : existing.htmlAttributes;
     const media = {
         ...existing,
+        // `title` and `slug` are deliberately independent (see `MediaRecord.slug`'s doc): renaming the
+        // title never recomputes `slug`, and editing `slug` never touches `title`.
         title: input.title !== undefined ? input.title.trim() || existing.title : existing.title,
+        slug,
         alt: input.alt !== undefined ? input.alt.trim() : existing.alt,
         caption: input.caption !== undefined ? input.caption.trim() : existing.caption,
         credit: input.credit !== undefined ? input.credit.trim() : existing.credit,
         width: input.width !== undefined ? input.width : existing.width,
         height: input.height !== undefined ? input.height : existing.height,
         cssClass: input.cssClass !== undefined ? (input.cssClass === null ? null : input.cssClass.trim() || null) : existing.cssClass,
+        htmlAttributes,
         updatedAt: deps.clock.nowIso(),
         version: existing.version + 1,
     };

package/dist/media/ports.d.ts

@@ -31,6 +31,12 @@ export interface MediaRepoPort {
         workspaceId: UUID;
         id: UUID;
     }): Promise<MediaRecord | null>;
+    /** Second lookup key (2026-09-07) — `MediaRecord.slug`'s own doc has the full identity-model
+     *  rationale. Mirrors `AssetBlobRepoPort.findByHash`'s shape: one indexed field, one row or `null`. */
+    findBySlug(required: {
+        workspaceId: UUID;
+        slug: string;
+    }): Promise<MediaRecord | null>;
     list(required: {
         workspaceId: UUID;
     }): Promise<MediaRecord[]>;

package/dist/media/rendition-service.d.ts

@@ -13,7 +13,13 @@ export interface ResolveMediaRenditionDeps {
 }
 export interface ResolveMediaRenditionInput {
     workspaceId: UUID;
-    assetId: UUID;
+    /** The `{assetId}` path segment, verbatim — despite the name, this may be either the asset's real
+     *  `id` (a UUID) OR its `slug` (2026-09-07: `resolveMediaRendition` now resolves either via
+     *  `findMediaByIdOrSlug`, so a hand-authored `<img src="/m/{slug}/...">` resolves the same asset a
+     *  UUID-based one always has). Every rendition-table operation inside this function uses the
+     *  RESOLVED record's own `media.id`, never this raw field, once the lookup succeeds — see that
+     *  local rebinding's own comment for why that distinction matters. */
+    assetId: string;
     /** The `{transformName}` path segment — cosmetic slug/ext are stripped by the caller (route). */
     transformName: string;
     /** The `{version}` parsed out of the `.v{version}` path segment. */

package/dist/media/rendition-service.js

@@ -29,6 +29,7 @@
  *  - The real `entry_refs` "referenced by published content" check.
  */
 import { createHash } from "node:crypto";
+import { findMediaByIdOrSlug } from "./media-service.js";
 import { mimeForTransformFormat } from "./transform-types.js";
 import { isLatestTransformVersion, isReferencedByPublishedContent } from "./transform-registry.js";
 import { withRenditionLock } from "./transform-lock.js";
@@ -56,11 +57,16 @@ import { withRenditionLock } from "./transform-lock.js";
  */
 export async function resolveMediaRendition(required, _optional = {}) {
     const { deps, input } = required;
-    const media = await deps.mediaRepo.findById({ workspaceId: input.workspaceId, id: input.assetId });
+    const media = await findMediaByIdOrSlug({ deps: { mediaRepo: deps.mediaRepo }, input: { workspaceId: input.workspaceId, idOrSlug: input.assetId } });
     if (!media)
         return { outcome: "not-found" };
     if (media.status === "trashed")
         return { outcome: "gone" };
+    // From here on, every `asset_renditions`/blob operation keys on the RESOLVED record's own `id` —
+    // never the raw `input.assetId`, which may have been a slug. `asset_renditions.assetId` is a FK to
+    // `media.id`; keying it on the slug text instead would both miss every rendition already stored
+    // under the real id and, on the generation path below, write a second, slug-keyed row alongside it.
+    const assetId = media.id;
     const definition = await deps.transformRepo.findByNameVersion({
         workspaceId: input.workspaceId,
         name: input.transformName,
@@ -70,7 +76,7 @@ export async function resolveMediaRendition(required, _optional = {}) {
         return { outcome: "not-found" };
     const existing = await deps.renditionRepo.findOne({
         workspaceId: input.workspaceId,
-        assetId: input.assetId,
+        assetId,
         transformName: input.transformName,
         version: input.version,
     });
@@ -100,7 +106,7 @@ export async function resolveMediaRendition(required, _optional = {}) {
         // `imageTransformer.transform` a second time.
         const racedExisting = await deps.renditionRepo.findOne({
             workspaceId: input.workspaceId,
-            assetId: input.assetId,
+            assetId,
             transformName: input.transformName,
             version: input.version,
         });
@@ -120,7 +126,7 @@ export async function resolveMediaRendition(required, _optional = {}) {
         const row = {
             id: deps.idGen.newId(),
             workspaceId: input.workspaceId,
-            assetId: input.assetId,
+            assetId,
             transformName: input.transformName,
             version: input.version,
             storageKey,

package/dist/media/repo.memory.d.ts

@@ -20,6 +20,10 @@ export declare class InMemoryMediaRepo implements MediaRepoPort {
         workspaceId: UUID;
         id: UUID;
     }): Promise<MediaRecord | null>;
+    findBySlug(required: {
+        workspaceId: UUID;
+        slug: string;
+    }): Promise<MediaRecord | null>;
     list(required: {
         workspaceId: UUID;
     }): Promise<MediaRecord[]>;

package/dist/media/repo.memory.js

@@ -6,6 +6,9 @@ export class InMemoryMediaRepo {
     async findById(required) {
         return (this.rows.find((row) => row.workspaceId === required.workspaceId && row.id === required.id) ?? null);
     }
+    async findBySlug(required) {
+        return (this.rows.find((row) => row.workspaceId === required.workspaceId && row.slug === required.slug) ?? null);
+    }
     async list(required) {
         return this.rows.filter((row) => row.workspaceId === required.workspaceId);
     }

package/dist/media/tool-registrations.d.ts

@@ -92,6 +92,18 @@ export interface MediaToolDeps {
         media: MediaRecord;
         bytes: Uint8Array;
     }) => Promise<void>;
+    /**
+     * Optional host-supplied override of `uploadMedia`'s own `DEFAULT_MAX_UPLOAD_BYTES` (10 MiB,
+     * `media-service.ts`), forwarded verbatim as `uploadMedia`'s third (`optional`) argument in the
+     * `media_upload_asset` handler below (2026-09-21). Before this field existed, the handler called
+     * `uploadMedia({ deps, input })` with no third argument at all, so EVERY host's assistant upload
+     * tool was hard-capped at 10 MiB regardless of what limit that host's own HTTP upload route
+     * enforced — a host raising its own cap (e.g. to 50 MiB) had no way to raise this tool's cap to
+     * match. Omitted: `uploadMedia`'s own default applies unchanged, matching this field's own
+     * pre-2026-09-21 absence for every host that has not opted in yet — the same degrade-soft
+     * contract {@link resolvePublicUrls} and {@link recordUploadContentType} already established.
+     */
+    maxUploadBytes?: number;
 }
 /**
  * This wiring layer's OWN risk classification, authored from what each handler below actually

package/dist/media/tool-registrations.js

@@ -30,6 +30,7 @@ function isMediaShapeRejection(error) {
 function toMediaToolView(record) {
     return {
         id: record.id,
+        slug: record.slug,
         title: record.title,
         alt: record.alt,
         caption: record.caption,
@@ -37,6 +38,8 @@ function toMediaToolView(record) {
         sha256: record.source.sha256,
         status: record.status,
         version: record.version,
+        cssClass: record.cssClass,
+        htmlAttributes: record.htmlAttributes,
     };
 }
 /**
@@ -92,7 +95,7 @@ export function buildMediaRegistrations(routeDeps) {
                         credit: typeof input.credit === "string" ? input.credit : undefined,
                         createdByPrincipal: ctx.principal.id,
                     },
-                });
+                }, { maxUploadBytes: routeDeps.maxUploadBytes });
                 if (routeDeps.recordUploadContentType) {
                     try {
                         await routeDeps.recordUploadContentType({ media, bytes });
@@ -121,18 +124,23 @@ export function buildMediaRegistrations(routeDeps) {
             const input = requireInputRecord(ctx.input);
             const mediaId = requireString(input, "mediaId");
             await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "media.update", entityType: "media", entityId: mediaId });
-            const { media } = await updateMediaMetadata({
-                deps: { clock: routeDeps.clock, mediaRepo: routeDeps.mediaRepo },
-                input: {
-                    workspaceId: routeDeps.workspaceId,
-                    id: mediaId,
-                    title: typeof input.title === "string" ? input.title : undefined,
-                    alt: typeof input.alt === "string" ? input.alt : undefined,
-                    caption: typeof input.caption === "string" ? input.caption : undefined,
-                    credit: typeof input.credit === "string" ? input.credit : undefined,
-                },
+            return withSchemaOnRejection({ toolId: "media_update_metadata", catalog: CATALOG_BY_ID, isShapeRejection: isMediaShapeRejection }, async () => {
+                const { media } = await updateMediaMetadata({
+                    deps: { clock: routeDeps.clock, mediaRepo: routeDeps.mediaRepo },
+                    input: {
+                        workspaceId: routeDeps.workspaceId,
+                        id: mediaId,
+                        title: typeof input.title === "string" ? input.title : undefined,
+                        alt: typeof input.alt === "string" ? input.alt : undefined,
+                        caption: typeof input.caption === "string" ? input.caption : undefined,
+                        credit: typeof input.credit === "string" ? input.credit : undefined,
+                        slug: typeof input.slug === "string" ? input.slug : undefined,
+                        cssClass: typeof input.cssClass === "string" ? input.cssClass : undefined,
+                        htmlAttributes: typeof input.htmlAttributes === "string" ? input.htmlAttributes : undefined,
+                    },
+                });
+                return { media: toMediaToolView(media) };
             });
-            return { media: toMediaToolView(media) };
         },
         media_trash_asset: async (ctx) => {
             const mediaId = requireString(requireInputRecord(ctx.input), "mediaId");

package/dist/media/types.d.ts

@@ -42,6 +42,20 @@ export interface MediaRecord {
     id: UUID;
     workspaceId: UUID;
     title: string;
+    /**
+     * Human-memorable, unique-per-workspace lookup key (owner-directed, 2026-09-07) — an ADDITIONAL
+     * key alongside `id`, never a replacement: `id` stays the canonical primary key every existing
+     * embed/reference resolves by, and this column only gives a second, human-typeable way to reach
+     * the same row (`findMediaByIdOrSlug` in `media-service.ts` tries this first, `id` second).
+     *
+     * Derived from `title` at upload time (`deriveMediaSlug`), then independently editable afterward
+     * — renaming `title` does NOT recompute this field; it changes only on an explicit `slug` write.
+     * Unique per `(workspaceId, slug)`, enforced by the host's own DB index (see the host's
+     * `idx_media_workspace_slug`) — `updateMediaMetadata`'s own `findBySlug` check is a friendly-error
+     * courtesy on top of that, not the enforcement itself, the same split `posts_workspace_slug_unique`
+     * already establishes for `post`'s identical `slug` field.
+     */
+    slug: string;
     alt: string;
     caption: string;
     credit: string;
@@ -63,6 +77,18 @@ export interface MediaRecord {
     width: number | null;
     height: number | null;
     cssClass: string | null;
+    /**
+     * Owner-directed (2026-09-07) free-text HTML attributes threaded onto this asset's public
+     * `<img>`/`<video>` tag (stated uses: animations, custom WebMCP hooks) — raw, ALREADY-VALIDATED
+     * source text (e.g. `data-motion="fade-in" loading="lazy"`), the same "one string column, `null`
+     * means not set" shape {@link cssClass} already establishes; `null` by default. This is a stored-
+     * XSS boundary: `updateMediaMetadata` validates it against `html-attributes.ts`'s allowlist before
+     * ever writing it (`on*` handlers, `javascript:` values, and any name not on the allowlist are
+     * rejected outright, never sanitized), and a host's render path must re-validate before emitting
+     * it onto a real tag rather than trusting a stored value was never written by an older code path
+     * or a direct DB edit.
+     */
+    htmlAttributes: string | null;
 }
 /**
  * Blob-GC lifecycle status (INV-1's two-phase journaled protocol,

package/dist/navigation/agent-tools.js

@@ -55,6 +55,7 @@
  * published, there), so the target schema below is hand-authored against `types.ts`'s `NavTarget`
  * union and cross-checked by this catalog's own contract test rather than imported.
  */
+import { ALLOWED_HREF_SHAPES_DESCRIPTION } from "./menu-service.js";
 const MENU_ID_SCHEMA = {
     type: "string",
     description: "The menu's id, as returned by menus_list_menus, menus_get_menu, or menus_create_menu.",
@@ -90,7 +91,13 @@ const NAV_TARGET_SCHEMA = {
             required: ["kind", "href"],
             properties: {
                 kind: { const: "url" },
-                href: { type: "string", description: "An absolute or site-relative URL. 'javascript:', 'data:', and 'vbscript:' schemes are rejected." },
+                href: {
+                    type: "string",
+                    // Derived from `menu-service.ts`'s own `ALLOWED_HREF_SHAPES_DESCRIPTION` (the single
+                    // source of truth `isAllowedHref`'s rejection message also draws from) rather than
+                    // hand-copied, so this schema description cannot drift out of sync with the real check.
+                    description: `Accepted shapes: ${ALLOWED_HREF_SHAPES_DESCRIPTION}. Anything else — including 'javascript:', 'data:', 'vbscript:', 'file:', 'blob:', 'about:', a protocol-relative '//...' URL, or a bare relative path with no leading '/' — is rejected.`,
+                },
             },
         },
         {

package/dist/navigation/index.d.ts

@@ -16,7 +16,16 @@ export { createNavMenuReadModel, type NavMenuReadModelDeps } from "./read-model.
  * adapter implements it directly, the same way it implements `NavLocationBindingRepoPort`.
  */
 export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, type MenuRepoPort, } from "./repo.memory.js";
-export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, type TreeValidationLimits, type CreateMenuDeps, type CreateMenuServiceInput, type CreateMenuRequired, type CreateMenuOptional, type UpdateMenuTreeDeps, type UpdateMenuTreeServiceInput, type UpdateMenuTreeRequired, type UpdateMenuTreeOptional, type AssignLocationDeps, type AssignLocationServiceInput, type AssignLocationRequired, type AssignLocationOptional, type DeleteMenuDeps, type DeleteMenuServiceInput, type DeleteMenuRequired, type DeleteMenuOptional, } from "./menu-service.js";
+/**
+ * `isAllowedHref`/`ALLOWED_HREF_SHAPES_DESCRIPTION` (2026-09-03): the canonical author-link
+ * allowlist, promoted here specifically so a HOST can import it rather than hand-copy it — the
+ * dependency direction a host -> `@jini-ai/cms` is the one that is actually legal (the reverse is
+ * not). The host's own render-time `safeHref` (`server/inbound/public-http/http/site/render.ts` and its
+ * `features/theme/static-render.ts` duplicate) have not yet been migrated to import this — see
+ * `menu-service.ts`'s own doc comment on `isAllowedHref` for the retirement plan and why nothing in
+ * `check:boundaries` blocks either host-side call site from doing so.
+ */
+export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, isAllowedHref, ALLOWED_HREF_SHAPES_DESCRIPTION, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, type TreeValidationLimits, type CreateMenuDeps, type CreateMenuServiceInput, type CreateMenuRequired, type CreateMenuOptional, type UpdateMenuTreeDeps, type UpdateMenuTreeServiceInput, type UpdateMenuTreeRequired, type UpdateMenuTreeOptional, type AssignLocationDeps, type AssignLocationServiceInput, type AssignLocationRequired, type AssignLocationOptional, type DeleteMenuDeps, type DeleteMenuServiceInput, type DeleteMenuRequired, type DeleteMenuOptional, } from "./menu-service.js";
 export { resolveForLocation, resolveMenuDoc, type ResolveTargetHrefFn, type ResolvedTargetHref, type ResolveForLocationDeps, type ResolveForLocationServiceInput, type ResolveForLocationRequired, type ResolveForLocationOptional, } from "./resolver.js";
 export { rebuildNavLocationBindings, type RebuildNavLocationBindingsDeps, type RebuildNavLocationBindingsResult, } from "./reconcile.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */

package/dist/navigation/index.js

@@ -7,7 +7,16 @@ export { createNavMenuReadModel } from "./read-model.js";
  * adapter implements it directly, the same way it implements `NavLocationBindingRepoPort`.
  */
 export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, } from "./repo.memory.js";
-export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, } from "./menu-service.js";
+/**
+ * `isAllowedHref`/`ALLOWED_HREF_SHAPES_DESCRIPTION` (2026-09-03): the canonical author-link
+ * allowlist, promoted here specifically so a HOST can import it rather than hand-copy it — the
+ * dependency direction a host -> `@jini-ai/cms` is the one that is actually legal (the reverse is
+ * not). The host's own render-time `safeHref` (`server/inbound/public-http/http/site/render.ts` and its
+ * `features/theme/static-render.ts` duplicate) have not yet been migrated to import this — see
+ * `menu-service.ts`'s own doc comment on `isAllowedHref` for the retirement plan and why nothing in
+ * `check:boundaries` blocks either host-side call site from doing so.
+ */
+export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, isAllowedHref, ALLOWED_HREF_SHAPES_DESCRIPTION, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, } from "./menu-service.js";
 export { resolveForLocation, resolveMenuDoc, } from "./resolver.js";
 export { rebuildNavLocationBindings, } from "./reconcile.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */