@caelo-cms/shared 0.10.22 → 0.10.24

package/dist/interactions.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * issue #160 — the vetted interaction baseline (epic #149).
+ *
+ * A header without a working mobile menu reads as broken, not minimal
+ * — and hand-rolled per-module JS gets focus/aria handling wrong more
+ * often than right. This module carries the FUNCTIONAL (non-aesthetic)
+ * CSS + JS for the built-in nav renderer: hamburger toggle under the
+ * mobile breakpoint, `aria-expanded` bookkeeping, escape-to-close.
+ * All colors/spacing stay the module/theme's business — these rules
+ * only govern show/hide behaviour, so they don't violate the
+ * no-global-look re-scope (#151).
+ *
+ * The composer includes each asset ONCE per page when at least one
+ * nav-menu module rendered (natural dedup, same rule as #158).
+ */
+/** Functional-only rules: collapse/expand mechanics, zero aesthetics. */
+export const NAV_FUNCTIONAL_CSS = ".caelo-nav-menu .caelo-nav-toggle{display:none;background:none;border:0;cursor:pointer;padding:0.5rem;color:inherit;font:inherit}" +
+    ".caelo-nav-menu .caelo-nav-toggle .caelo-nav-bar{display:block;width:1.25em;height:2px;background:currentColor;margin:0.25em 0}" +
+    "@media (max-width: 720px){" +
+    ".caelo-nav-menu .caelo-nav-toggle{display:inline-block}" +
+    ".caelo-nav-menu > ul{display:none}" +
+    '.caelo-nav-menu[data-nav-open="true"] > ul{display:block}' +
+    "}";
+/**
+ * Toggle behaviour. Runs deferred; idempotent per element via the
+ * data attribute; closes on Escape and returns focus to the toggle.
+ */
+export const NAV_TOGGLE_JS = "(function(){" +
+    "document.querySelectorAll('.caelo-nav-menu').forEach(function(nav){" +
+    "var btn=nav.querySelector('.caelo-nav-toggle');if(!btn)return;" +
+    "btn.addEventListener('click',function(){" +
+    "var open=nav.getAttribute('data-nav-open')==='true';" +
+    "nav.setAttribute('data-nav-open',String(!open));" +
+    "btn.setAttribute('aria-expanded',String(!open));" +
+    "});" +
+    "nav.addEventListener('keydown',function(e){" +
+    "if(e.key==='Escape'&&nav.getAttribute('data-nav-open')==='true'){" +
+    "nav.setAttribute('data-nav-open','false');" +
+    "btn.setAttribute('aria-expanded','false');btn.focus();" +
+    "}});" +
+    "});" +
+    "})();";
+//# sourceMappingURL=interactions.js.map

package/dist/interactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactions.js","sourceRoot":"","sources":["../src/interactions.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;GAcG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAC7B,mIAAmI;IACnI,iIAAiI;IACjI,4BAA4B;IAC5B,yDAAyD;IACzD,oCAAoC;IACpC,2DAA2D;IAC3D,GAAG,CAAC;AAEN;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,cAAc;IACd,qEAAqE;IACrE,gEAAgE;IAChE,0CAA0C;IAC1C,sDAAsD;IACtD,kDAAkD;IAClD,kDAAkD;IAClD,KAAK;IACL,6CAA6C;IAC7C,mEAAmE;IACnE,4CAA4C;IAC5C,wDAAwD;IACxD,MAAM;IACN,KAAK;IACL,OAAO,CAAC"}

package/dist/media.d.ts

@@ -15,7 +15,7 @@ import { z } from "zod";
  * pipeline strips `<script>` and event-handler attributes before
  * persisting (see {@link sanitizeSvg} in admin-core).
  */
-export declare const MEDIA_ALLOWED_MIMES: readonly ["image/jpeg", "image/png", "image/webp", "image/avif", "image/gif", "image/svg+xml", "application/pdf", "video/mp4"];
+export declare const MEDIA_ALLOWED_MIMES: readonly ["image/jpeg", "image/png", "image/webp", "image/avif", "image/gif", "image/svg+xml", "application/pdf", "video/mp4", "font/woff2", "font/woff", "font/ttf", "font/otf"];
 export type MediaMime = (typeof MEDIA_ALLOWED_MIMES)[number];
 /** Per-MIME size caps (bytes). Server enforces; client display only. */
 export declare const MEDIA_SIZE_CAPS: Record<MediaMime, number>;
@@ -37,33 +37,65 @@ export declare const MEDIA_VARIANT_WIDTHS: Record<Exclude<MediaVariantTag, "orig
  * shape; the static generator rewrites to `/_assets/...` (or a CDN
  * URL) at deploy time.
  *
- * Format: `/_caelo/media/<asset-id>/<variant>`. The asset id, not the
- * sha, so URLs survive a re-upload of the same content under a new id.
+ * Format (current): `/_caelo/media/<slug>` for the orig variant,
+ * `/_caelo/media/<slug>/<variant>` for a named variant (webp/crops). The
+ * `<slug>` is `media_assets.slug` — a human-meaningful name (e.g.
+ * `searchviu-logo`); the UUID id stays internal. The static generator
+ * rewrites these to `/_assets/<slug>.<ext>` (orig) / `/_assets/<slug>/<variant>.<ext>`.
+ *
+ * Legacy form `/_caelo/media/<uuid>/<variant>` is still PARSED (existing
+ * persisted embeds keep resolving), but never newly EMITTED.
  */
 export declare const MEDIA_URL_PREFIX = "/_caelo/media";
-export declare function buildMediaUrl(assetId: string, variant: MediaVariantTag): string;
 /**
- * Extract every (assetId, variant) pair referenced in an HTML string.
- * Used by the post-write usage-tracker and by the static-generator
- * media-pass. Returns a deduped list to keep callers' work proportional
- * to unique assets, not raw match count.
+ * Build the media URL for an asset SLUG + variant. The orig variant is
+ * flat (`/_caelo/media/<slug>`) so a plain image reads as a name, not a
+ * path; named variants (srcset webp / focal crops) nest under the slug.
+ * Widened to `| string` (run #10 D4): pickAiImageVariant returns whichever
+ * variant tag actually exists.
+ */
+export declare function buildMediaUrl(slug: string, variant: MediaVariantTag | string): string;
+/**
+ * Turn a human/asset label into a URL-safe media slug: lowercase ascii,
+ * kebab-case, extension + junk stripped, capped at 60 chars. NOT
+ * uniquified — the caller resolves collisions against the live library
+ * (append `-2`/`-3`…); see `resolveUniqueMediaSlug` in admin-core.
  */
-export declare function extractMediaRefs(html: string): {
-    assetId: string;
-    variant: string;
-}[];
+export declare function slugifyMediaName(name: string): string;
+/**
+ * One media reference parsed from HTML. `ref` is either an asset SLUG
+ * (`isSlug: true`) or a legacy UUID id (`isSlug: false`); callers resolve
+ * a slug ref to an asset id before touching the DB. `variant` defaults to
+ * `orig` for the flat slug form.
+ */
+export interface MediaRef {
+    readonly ref: string;
+    readonly isSlug: boolean;
+    readonly variant: string;
+}
+/**
+ * Extract every media reference in an HTML string (deduped). Used by the
+ * post-write usage-tracker and the static-generator media-pass. Handles
+ * both the current slug form and the legacy `<uuid>/<variant>` form.
+ */
+export declare function extractMediaRefs(html: string): MediaRef[];
 export declare const mediaUploadInputSchema: z.ZodObject<{
     sha256: z.ZodString;
     originalName: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
     mime: z.ZodEnum<{
-        "image/jpeg": "image/jpeg";
         "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
         "image/webp": "image/webp";
-        "image/avif": "image/avif";
         "image/gif": "image/gif";
+        "image/avif": "image/avif";
         "image/svg+xml": "image/svg+xml";
         "application/pdf": "application/pdf";
         "video/mp4": "video/mp4";
+        "font/woff2": "font/woff2";
+        "font/woff": "font/woff";
+        "font/ttf": "font/ttf";
+        "font/otf": "font/otf";
     }>;
     sizeBytes: z.ZodNumber;
     width: z.ZodNullable<z.ZodNumber>;
@@ -71,6 +103,14 @@ export declare const mediaUploadInputSchema: z.ZodObject<{
     alt: z.ZodDefault<z.ZodString>;
     storageKey: z.ZodString;
     storageProvider: z.ZodDefault<z.ZodString>;
+    sourceKind: z.ZodOptional<z.ZodEnum<{
+        upload: "upload";
+        ai_generated: "ai_generated";
+        imported: "imported";
+        external: "external";
+    }>>;
+    sourceDetail: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
     variants: z.ZodArray<z.ZodObject<{
         variant: z.ZodString;
         format: z.ZodString;
@@ -84,14 +124,18 @@ export type MediaUploadInput = z.infer<typeof mediaUploadInputSchema>;
 export declare const mediaListInputSchema: z.ZodObject<{
     query: z.ZodOptional<z.ZodString>;
     mime: z.ZodOptional<z.ZodEnum<{
-        "image/jpeg": "image/jpeg";
         "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
         "image/webp": "image/webp";
-        "image/avif": "image/avif";
         "image/gif": "image/gif";
+        "image/avif": "image/avif";
         "image/svg+xml": "image/svg+xml";
         "application/pdf": "application/pdf";
         "video/mp4": "video/mp4";
+        "font/woff2": "font/woff2";
+        "font/woff": "font/woff";
+        "font/ttf": "font/ttf";
+        "font/otf": "font/otf";
     }>>;
     sort: z.ZodDefault<z.ZodEnum<{
         recent: "recent";
@@ -106,6 +150,24 @@ export declare const mediaUpdateAltInputSchema: z.ZodObject<{
     alt: z.ZodString;
 }, z.core.$strict>;
 export type MediaUpdateAltInput = z.infer<typeof mediaUpdateAltInputSchema>;
+/**
+ * media.set_source (0181) — record/patch an asset's provenance after it
+ * exists. COALESCE semantics at the handler: omitted fields stay
+ * unchanged, so this both sets provenance the first time and patches a
+ * single field (e.g. a licence the operator states later).
+ */
+export declare const mediaSetSourceInputSchema: z.ZodObject<{
+    assetId: z.ZodString;
+    sourceKind: z.ZodOptional<z.ZodEnum<{
+        upload: "upload";
+        ai_generated: "ai_generated";
+        imported: "imported";
+        external: "external";
+    }>>;
+    sourceDetail: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type MediaSetSourceInput = z.infer<typeof mediaSetSourceInputSchema>;
 export declare const mediaDeleteInputSchema: z.ZodObject<{
     assetId: z.ZodString;
     force: z.ZodDefault<z.ZodBoolean>;
@@ -138,6 +200,29 @@ export interface MediaStorageAdapter {
     /** Bytes-on-disk for capacity reporting. */
     totalSizeBytes(): Promise<number>;
 }
+/**
+ * Object-store prefix for images the AI produced during a chat (screenshots
+ * of a page, of an external site, of a crawled source page).
+ *
+ * They are NOT media assets. The operator's library is their own curated
+ * space; filling it with machine screenshots would make it useless, and these
+ * images have no life outside the conversation that produced them. They live
+ * under their own prefix instead, and a scheduled sweep removes the ones whose
+ * conversations have aged out (see `chat_images.gc`).
+ *
+ * The key is `chat-images/<UTC day>/<sha256>.<ext>`:
+ *   - the day segment makes age the first thing you can see in a key, so a
+ *     sweep never has to open a file to decide;
+ *   - the content hash means re-shooting an unchanged page writes the SAME
+ *     key. That is not just a storage saving — an identical key keeps the
+ *     message history byte-identical, so the provider's prompt cache survives
+ *     a re-screenshot of something that did not change.
+ */
+export declare const CHAT_IMAGE_PREFIX = "chat-images";
+/** Build the storage key for a chat image. `day` is `YYYY-MM-DD` (UTC). */
+export declare function buildChatImageKey(day: string, sha256: string, ext: string): string;
+/** True for keys under the chat-image prefix — the sweep's safety check. */
+export declare function isChatImageKey(key: string): boolean;
 /** Build the canonical storage key for a given asset variant. */
 export declare function buildStorageKey(sha256: string, variant: MediaVariantTag | string, ext: string): string;
 //# sourceMappingURL=media.d.ts.map

package/dist/media.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../src/media.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,gIAStB,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,wEAAwE;AACxE,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CASrD,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,qEAMrB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,CAKjF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAE/E;AAWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAUrF;AAQD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAyBxB,CAAC;AACZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;kBAQtB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,yBAAyB;;;kBAK3B,CAAC;AACZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,sBAAsB;;;kBAKxB,CAAC;AAEZ,eAAO,MAAM,2BAA2B;;kBAK7B,CAAC;AACZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,2BAA2B;;kBAI7B,CAAC;AAEZ,eAAO,MAAM,sBAAsB;;;kBAKxB,CAAC;AACZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAOtE;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,4CAA4C;IAC5C,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,GAAG,MAAM,EACjC,GAAG,EAAE,MAAM,GACV,MAAM,CAER"}
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../src/media.ts"],"names":[],"mappings":"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"}

package/dist/media.js

@@ -25,6 +25,14 @@ export const MEDIA_ALLOWED_MIMES = [
     "image/svg+xml",
     "application/pdf",
     "video/mp4",
+    // issue #249 — webfonts. Migrated sites reference their own font
+    // files from replayed CSS; the media-migration pass downloads them
+    // into the library so the rebuilt site survives the source host
+    // going away. Stored as-is (no derived variants).
+    "font/woff2",
+    "font/woff",
+    "font/ttf",
+    "font/otf",
 ];
 /** Per-MIME size caps (bytes). Server enforces; client display only. */
 export const MEDIA_SIZE_CAPS = {
@@ -36,6 +44,10 @@ export const MEDIA_SIZE_CAPS = {
     "image/svg+xml": 1 * 1024 * 1024,
     "application/pdf": 20 * 1024 * 1024,
     "video/mp4": 50 * 1024 * 1024,
+    "font/woff2": 5 * 1024 * 1024,
+    "font/woff": 5 * 1024 * 1024,
+    "font/ttf": 5 * 1024 * 1024,
+    "font/otf": 5 * 1024 * 1024,
 };
 /** Hard ceiling on the multipart body. Per-MIME caps narrow further. */
 export const MEDIA_HARD_LIMIT_BYTES = 50 * 1024 * 1024;
@@ -65,33 +77,74 @@ export const MEDIA_VARIANT_WIDTHS = {
  * shape; the static generator rewrites to `/_assets/...` (or a CDN
  * URL) at deploy time.
  *
- * Format: `/_caelo/media/<asset-id>/<variant>`. The asset id, not the
- * sha, so URLs survive a re-upload of the same content under a new id.
+ * Format (current): `/_caelo/media/<slug>` for the orig variant,
+ * `/_caelo/media/<slug>/<variant>` for a named variant (webp/crops). The
+ * `<slug>` is `media_assets.slug` — a human-meaningful name (e.g.
+ * `searchviu-logo`); the UUID id stays internal. The static generator
+ * rewrites these to `/_assets/<slug>.<ext>` (orig) / `/_assets/<slug>/<variant>.<ext>`.
+ *
+ * Legacy form `/_caelo/media/<uuid>/<variant>` is still PARSED (existing
+ * persisted embeds keep resolving), but never newly EMITTED.
  */
 export const MEDIA_URL_PREFIX = "/_caelo/media";
-export function buildMediaUrl(assetId, variant) {
-    return `${MEDIA_URL_PREFIX}/${assetId}/${variant}`;
+/** Full-uuid shape — used to tell a legacy id ref from a slug ref. */
+const MEDIA_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * Build the media URL for an asset SLUG + variant. The orig variant is
+ * flat (`/_caelo/media/<slug>`) so a plain image reads as a name, not a
+ * path; named variants (srcset webp / focal crops) nest under the slug.
+ * Widened to `| string` (run #10 D4): pickAiImageVariant returns whichever
+ * variant tag actually exists.
+ */
+export function buildMediaUrl(slug, variant) {
+    return variant === "orig"
+        ? `${MEDIA_URL_PREFIX}/${slug}`
+        : `${MEDIA_URL_PREFIX}/${slug}/${variant}`;
 }
-// Variant token: `orig`, `webp-<width>`, or `<crop-name>-<width>`. We
-// accept any kebab-case slug so focal-point crop fan-outs like
-// `square-800` and `wide-1200` (added by P7 optimization #2) round-trip
-// without a regex update per crop name.
-const mediaUrlPattern = new RegExp(`${MEDIA_URL_PREFIX}/([0-9a-f-]{36})/([a-z][a-z0-9-]{0,63})`, "g");
 /**
- * Extract every (assetId, variant) pair referenced in an HTML string.
- * Used by the post-write usage-tracker and by the static-generator
- * media-pass. Returns a deduped list to keep callers' work proportional
- * to unique assets, not raw match count.
+ * Turn a human/asset label into a URL-safe media slug: lowercase ascii,
+ * kebab-case, extension + junk stripped, capped at 60 chars. NOT
+ * uniquified — the caller resolves collisions against the live library
+ * (append `-2`/`-3`…); see `resolveUniqueMediaSlug` in admin-core.
+ */
+export function slugifyMediaName(name) {
+    const noExt = name.replace(/\.[a-z0-9]{1,8}$/i, "");
+    const slug = noExt
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "") // strip combining accents
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60)
+        .replace(/-+$/g, "");
+    return slug.length > 0 ? slug : "image";
+}
+// Segment token: a slug or uuid (`[a-z0-9-]`) optionally followed by a
+// variant. `orig`, `webp-<width>`, `<crop-name>-<width>` all round-trip
+// without a per-crop regex update.
+const mediaUrlPattern = new RegExp(`${MEDIA_URL_PREFIX}/([a-z0-9][a-z0-9-]{0,63})(?:/([a-z][a-z0-9-]{0,63}))?`, "g");
+/**
+ * Extract every media reference in an HTML string (deduped). Used by the
+ * post-write usage-tracker and the static-generator media-pass. Handles
+ * both the current slug form and the legacy `<uuid>/<variant>` form.
  */
 export function extractMediaRefs(html) {
     const seen = new Set();
     const out = [];
     for (const m of html.matchAll(mediaUrlPattern)) {
-        const key = `${m[1]}/${m[2]}`;
+        const seg1 = m[1];
+        const seg2 = m[2];
+        // A full-uuid first segment with a trailing variant is the legacy id
+        // form; everything else is a slug (orig when no explicit variant).
+        const isLegacyId = MEDIA_UUID_RE.test(seg1) && seg2 !== undefined;
+        const ref = seg1;
+        const isSlug = !isLegacyId;
+        const variant = seg2 ?? "orig";
+        const key = `${isSlug ? "s" : "i"}:${ref}/${variant}`;
         if (seen.has(key))
             continue;
         seen.add(key);
-        out.push({ assetId: m[1], variant: m[2] });
+        out.push({ ref, isSlug, variant });
     }
     return out;
 }
@@ -103,6 +156,13 @@ export const mediaUploadInputSchema = z
     .object({
     sha256: sha256Schema,
     originalName: z.string().min(1).max(512),
+    /**
+     * Meaningful, human-facing label for the asset (e.g. "SearchVIU logo").
+     * The handler slugifies + uniquifies it into `media_assets.slug`, which
+     * becomes the public URL (`/_assets/<slug>.<ext>`); the id stays internal.
+     * Optional: falls back to `alt` → `originalName` → "image".
+     */
+    name: z.string().max(200).optional(),
     mime: z.enum(MEDIA_ALLOWED_MIMES),
     sizeBytes: z.number().int().positive(),
     width: z.number().int().positive().nullable(),
@@ -111,6 +171,16 @@ export const mediaUploadInputSchema = z
     storageKey: z.string().min(1),
     /** P7 optimization #3 — stamped by the upload endpoint via getMediaStorageProvider(). */
     storageProvider: z.string().min(1).max(64).default("local"),
+    /**
+     * Media provenance (0181). Where the asset came from + its licence
+     * when known. All optional — a plain human upload may leave them
+     * unset. `sourceDetail` is the origin: source URL for imported /
+     * external, "<provider>/<model>" for ai_generated, filename/NULL for
+     * a plain upload.
+     */
+    sourceKind: z.enum(["upload", "ai_generated", "imported", "external"]).optional(),
+    sourceDetail: z.string().max(2048).optional(),
+    license: z.string().max(200).optional(),
     variants: z
         .array(z.object({
         variant: z.string().min(1).max(64),
@@ -138,6 +208,20 @@ export const mediaUpdateAltInputSchema = z
     alt: z.string().max(2048),
 })
     .strict();
+/**
+ * media.set_source (0181) — record/patch an asset's provenance after it
+ * exists. COALESCE semantics at the handler: omitted fields stay
+ * unchanged, so this both sets provenance the first time and patches a
+ * single field (e.g. a licence the operator states later).
+ */
+export const mediaSetSourceInputSchema = z
+    .object({
+    assetId: z.string().uuid(),
+    sourceKind: z.enum(["upload", "ai_generated", "imported", "external"]).optional(),
+    sourceDetail: z.string().max(2048).optional(),
+    license: z.string().max(200).optional(),
+})
+    .strict();
 export const mediaDeleteInputSchema = z
     .object({
     assetId: z.string().uuid(),
@@ -161,6 +245,33 @@ export const mediaSetCdnInputSchema = z
     threshold: z.number().int().min(1).max(10000),
 })
     .strict();
+/**
+ * Object-store prefix for images the AI produced during a chat (screenshots
+ * of a page, of an external site, of a crawled source page).
+ *
+ * They are NOT media assets. The operator's library is their own curated
+ * space; filling it with machine screenshots would make it useless, and these
+ * images have no life outside the conversation that produced them. They live
+ * under their own prefix instead, and a scheduled sweep removes the ones whose
+ * conversations have aged out (see `chat_images.gc`).
+ *
+ * The key is `chat-images/<UTC day>/<sha256>.<ext>`:
+ *   - the day segment makes age the first thing you can see in a key, so a
+ *     sweep never has to open a file to decide;
+ *   - the content hash means re-shooting an unchanged page writes the SAME
+ *     key. That is not just a storage saving — an identical key keeps the
+ *     message history byte-identical, so the provider's prompt cache survives
+ *     a re-screenshot of something that did not change.
+ */
+export const CHAT_IMAGE_PREFIX = "chat-images";
+/** Build the storage key for a chat image. `day` is `YYYY-MM-DD` (UTC). */
+export function buildChatImageKey(day, sha256, ext) {
+    return `${CHAT_IMAGE_PREFIX}/${day}/${sha256}.${ext}`;
+}
+/** True for keys under the chat-image prefix — the sweep's safety check. */
+export function isChatImageKey(key) {
+    return key.startsWith(`${CHAT_IMAGE_PREFIX}/`);
+}
 /** Build the canonical storage key for a given asset variant. */
 export function buildStorageKey(sha256, variant, ext) {
     return `${sha256}/${variant}.${ext}`;

package/dist/media.js.map

@@ -1 +1 @@
-{"version":3,"file":"media.js","sourceRoot":"","sources":["../src/media.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../src/media.ts"],"names":[],"mappings":"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"}

package/dist/page-log.d.ts

@@ -0,0 +1,94 @@
+/**
+ * issue #264 — the per-page edit LOG: durable, append-only work history so a
+ * later chat or a fresh subagent that touches a page knows WHY it was edited,
+ * what decisions were taken, and which operator answers shaped it — without
+ * dragging the originating chat's full transcript through its context.
+ *
+ * This is FACT (what happened), not learned BEHAVIOUR — so, unlike
+ * `site_ai_memory`, it is ungated: any actor appends directly. The shared
+ * Zod schemas here are the single source of truth for the `page_log.append`
+ * op input, the `log_page_edit` tool schema, and the `page_log.list` output.
+ * `formatPageLogBlock` renders the `## Page log` context block the AI reads
+ * before touching a page.
+ */
+import { z } from "zod";
+/**
+ * The kinds of log entry, in the order the AI should reach for them:
+ * - `edited` — a substantive content/module change was made.
+ * - `decision` — a design/structure call the AI made and its rationale.
+ * - `operator_answer` — an answer the operator gave that shaped the page.
+ * - `open_question` — something still unresolved a future turn must settle.
+ * - `rebuilt` — the page was rebuilt from scratch (e.g. migration rebuild).
+ * - `note` — anything else worth preserving for a future editor.
+ */
+export declare const pageLogEntryKinds: readonly ["edited", "decision", "operator_answer", "open_question", "rebuilt", "note"];
+export declare const pageLogEntryKindSchema: z.ZodEnum<{
+    decision: "decision";
+    edited: "edited";
+    operator_answer: "operator_answer";
+    open_question: "open_question";
+    rebuilt: "rebuilt";
+    note: "note";
+}>;
+export type PageLogEntryKind = (typeof pageLogEntryKinds)[number];
+/**
+ * Optional structured context beyond the one-line summary — an OBJECT, never
+ * a bare scalar or array, so the jsonb column stores queryable keys (chosen
+ * option, operator's exact words, affected module ids). Writes go through
+ * `jsonbParam()` in the op handler to avoid the double-encode trap (issue
+ * #68).
+ */
+export declare const pageLogDetailSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type PageLogDetail = z.infer<typeof pageLogDetailSchema>;
+/** Input shape shared by `page_log.append` and the `log_page_edit` tool. */
+export declare const pageLogAppendInputSchema: z.ZodObject<{
+    pageId: z.ZodString;
+    entryKind: z.ZodEnum<{
+        decision: "decision";
+        edited: "edited";
+        operator_answer: "operator_answer";
+        open_question: "open_question";
+        rebuilt: "rebuilt";
+        note: "note";
+    }>;
+    summary: z.ZodString;
+    detail: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type PageLogAppendInput = z.infer<typeof pageLogAppendInputSchema>;
+/** One row as returned by `page_log.list`. */
+export declare const pageLogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    pageId: z.ZodString;
+    chatSessionId: z.ZodNullable<z.ZodString>;
+    actorKind: z.ZodEnum<{
+        system: "system";
+        human: "human";
+        ai: "ai";
+        plugin: "plugin";
+    }>;
+    entryKind: z.ZodEnum<{
+        decision: "decision";
+        edited: "edited";
+        operator_answer: "operator_answer";
+        open_question: "open_question";
+        rebuilt: "rebuilt";
+        note: "note";
+    }>;
+    summary: z.ZodString;
+    detail: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+export type PageLogEntry = z.infer<typeof pageLogEntrySchema>;
+/**
+ * Render the `## Page log` context block for a single page's recent entries
+ * (newest first). Returns `null` when there is nothing to show, so the
+ * caller omits the header entirely (CLAUDE.md §11 — render only when
+ * non-empty). Kept well under 2 KB: entries are capped and each summary is
+ * clamped, because the block rides in the system prompt on every turn that
+ * touches the page.
+ *
+ * @param entries page log rows, expected newest-first (as `page_log.list`
+ *   returns them). The renderer does not re-sort.
+ */
+export declare function formatPageLogBlock(entries: readonly PageLogEntry[]): string | null;
+//# sourceMappingURL=page-log.d.ts.map

package/dist/page-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-log.d.ts","sourceRoot":"","sources":["../src/page-log.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,wFAOpB,CAAC;AAEX,eAAO,MAAM,sBAAsB;;;;;;;EAA4B,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,wCAAoC,CAAC;AACrE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;kBAO1B,CAAC;AACZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;kBAepB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAS9D;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,GAAG,IAAI,CAyBlF"}