gazetta 0.5.0 → 0.7.0

package/dist/assets/update-metadata.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Update an asset's metadata (alt today; tags, focalPoint, title,
+ * description as those land).
+ *
+ * Single responsibility: merge a metadata patch into the existing
+ * default manifest, validate, persist, record history. Doesn't touch
+ * bytes, doesn't enumerate paths, doesn't scan refs.
+ *
+ * Three-state alt semantics (per design-media.md):
+ *   - patch.alt === undefined  → leave alt unchanged (caller didn't send it)
+ *   - patch.alt === "string"   → meaningful description
+ *   - patch.alt === ""         → intentionally decorative
+ *   - patch.alt === null       → not set (resolver falls back to '')
+ *
+ * The discriminator is `'alt' in patch` vs `patch.alt`. JS-level distinct
+ * meaning of "absent" vs "explicit null". The HTTP layer translates
+ * between JSON's `null` (explicit) and field-not-present (absent) so the
+ * three-state contract survives the wire.
+ */
+import type { ContentRoot } from '../content-root.js';
+import type { HistoryProvider } from '../history.js';
+import type { AssetManifest } from '../schema/types.js';
+import type { StorageProvider } from '../types.js';
+/**
+ * Patch shape — every field optional; only present fields are applied.
+ * Undefined = "don't change," explicit `null` = "set to null state."
+ */
+export interface AssetMetadataPatch {
+    /** Three-state alt (string | "" | null). Absent in patch = unchanged. */
+    alt?: string | null;
+    /**
+     * Focal point in normalized coordinates (0–1). Two-state:
+     *   - `{ x, y }` → set it
+     *   - `null`     → clear (manifest field becomes absent, falls back
+     *                  to center at render time)
+     *   - omitted    → unchanged
+     */
+    focalPoint?: {
+        x: number;
+        y: number;
+    } | null;
+}
+export interface UpdateAssetMetadataInput {
+    storage: StorageProvider;
+    assetsRoot: string;
+    assetName: string;
+    patch: AssetMetadataPatch;
+    history?: HistoryProvider;
+    contentRoot?: ContentRoot;
+    author?: string;
+}
+/**
+ * Apply a metadata patch to the asset's default manifest. Throws:
+ *   - `AssetManifestNotFoundError` — asset doesn't exist
+ *   - `AssetStorageError` — manifest write failed
+ *
+ * Returns the updated manifest so callers can re-summarize for the
+ * client without an extra round-trip.
+ */
+export declare function updateAssetMetadata(input: UpdateAssetMetadataInput): Promise<AssetManifest>;
+//# sourceMappingURL=update-metadata.d.ts.map

package/dist/assets/update-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-metadata.d.ts","sourceRoot":"","sources":["../../src/assets/update-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAIlD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAE7C;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,eAAe,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,kBAAkB,CAAA;IACzB,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC,CAyDjG"}

package/dist/assets/update-metadata.js

@@ -0,0 +1,82 @@
+import { recordWrite } from '../history-recorder.js';
+import { manifestPath, readManifest, writeManifest } from './manifest.js';
+import { AssetStorageError } from './errors.js';
+/**
+ * Apply a metadata patch to the asset's default manifest. Throws:
+ *   - `AssetManifestNotFoundError` — asset doesn't exist
+ *   - `AssetStorageError` — manifest write failed
+ *
+ * Returns the updated manifest so callers can re-summarize for the
+ * client without an extra round-trip.
+ */
+export async function updateAssetMetadata(input) {
+    const current = await readManifest(input.storage, input.assetsRoot, input.assetName);
+    // Apply patch: only fields explicitly present in the patch object
+    // overwrite the manifest. Each new metadata field adds one
+    // `'field' in input.patch` clause here.
+    const next = { ...current };
+    if ('alt' in input.patch) {
+        next.alt = input.patch.alt ?? null;
+    }
+    if ('focalPoint' in input.patch) {
+        const fp = input.patch.focalPoint;
+        if (fp === null) {
+            // Clear → remove the field so the manifest serializes without it.
+            delete next.focalPoint;
+        }
+        else if (fp !== undefined) {
+            // Range-check (0–1 inclusive). Invalid input is a programmer
+            // error at this layer — the route validator should reject before
+            // calling. Defensive throw rather than silent clamp.
+            if (fp.x < 0 || fp.x > 1 || fp.y < 0 || fp.y > 1) {
+                throw new Error(`Focal point out of range: x=${fp.x}, y=${fp.y} (must be 0–1)`);
+            }
+            next.focalPoint = { x: fp.x, y: fp.y };
+        }
+    }
+    // Short-circuit no-op patches: identical manifest = identical history
+    // entry, but the recorder doesn't dedup entries that produce the same
+    // snapshot, so we'd accumulate empty revisions. Skip if nothing changed.
+    if (sameManifest(current, next))
+        return current;
+    const path = `${input.assetsRoot}/${manifestPath(next.name)}`;
+    const serialized = `${JSON.stringify(next, null, 2)}\n`;
+    // Record history BEFORE the write — same pattern as ingest/replace.
+    // First-time baseline scan must capture pre-op state.
+    if (input.history) {
+        if (!input.contentRoot) {
+            throw new Error('updateAssetMetadata: history requires contentRoot');
+        }
+        const items = [{ path, content: serialized }];
+        await recordWrite({
+            history: input.history,
+            contentRoot: input.contentRoot,
+            operation: 'save',
+            author: input.author,
+            items,
+            message: `Update metadata for ${input.assetName}`,
+        });
+    }
+    try {
+        await writeManifest(input.storage, input.assetsRoot, next);
+    }
+    catch (err) {
+        throw new AssetStorageError('write', path, err);
+    }
+    return next;
+}
+function sameManifest(a, b) {
+    // Cheap deep-equal for the fields a metadata patch can change. Avoids
+    // a full JSON.stringify compare for the hot no-op path.
+    if (a.alt !== b.alt)
+        return false;
+    return sameFocalPoint(a.focalPoint, b.focalPoint);
+}
+function sameFocalPoint(a, b) {
+    if (a === undefined && b === undefined)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    return a.x === b.x && a.y === b.y;
+}
+//# sourceMappingURL=update-metadata.js.map

package/dist/assets/update-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-metadata.js","sourceRoot":"","sources":["../../src/assets/update-metadata.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,WAAW,EAAoB,MAAM,wBAAwB,CAAA;AAGtE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AA8B/C;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,KAA+B;IACvE,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IAEpF,kEAAkE;IAClE,2DAA2D;IAC3D,wCAAwC;IACxC,MAAM,IAAI,GAAkB,EAAE,GAAG,OAAO,EAAE,CAAA;IAC1C,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAA;IACpC,CAAC;IACD,IAAI,YAAY,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAA;QACjC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,kEAAkE;YAClE,OAAO,IAAI,CAAC,UAAU,CAAA;QACxB,CAAC;aAAM,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YAC5B,6DAA6D;YAC7D,iEAAiE;YACjE,qDAAqD;YACrD,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjD,MAAM,IAAI,KAAK,CAAC,+BAA+B,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,gBAAgB,CAAC,CAAA;YACjF,CAAC;YACD,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAA;QACxC,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,sEAAsE;IACtE,yEAAyE;IACzE,IAAI,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC;QAAE,OAAO,OAAO,CAAA;IAE/C,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;IAC7D,MAAM,UAAU,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAA;IAEvD,oEAAoE;IACpE,sDAAsD;IACtD,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;QACtE,CAAC;QACD,MAAM,KAAK,GAAkB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAA;QAC5D,MAAM,WAAW,CAAC;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,SAAS,EAAE,MAAM;YACjB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,KAAK;YACL,OAAO,EAAE,uBAAuB,KAAK,CAAC,SAAS,EAAE;SAClD,CAAC,CAAA;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;IAC5D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,iBAAiB,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;IACjD,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,YAAY,CAAC,CAAgB,EAAE,CAAgB;IACtD,sEAAsE;IACtE,wDAAwD;IACxD,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG;QAAE,OAAO,KAAK,CAAA;IACjC,OAAO,cAAc,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAA;AACnD,CAAC;AAED,SAAS,cAAc,CAAC,CAAuC,EAAE,CAAuC;IACtG,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACnD,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACpD,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AACnC,CAAC"}

package/dist/assets/url.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Asset URL construction — pure function from (siteUrl, asset manifest
+ * fields, extension) to the URL the template emits.
+ *
+ * Kept separate from `resolve.ts` because:
+ * - The resolver composes manifest I/O + URL construction + override merging.
+ *   URL construction is the only piece that's purely computational.
+ * - Future transform adapters (Cloudflare Images, imgproxy) build URLs too —
+ *   they share the `{name}-{hash}.{ext}` origin-URL shape and wrap it. Having
+ *   that builder in one place means adapters compose rather than duplicate.
+ *
+ * Output is root-relative when `siteUrl` is absent, absolute when present.
+ * Root-relative works anywhere; absolute is needed for targets that live on
+ * a different origin from the admin (CDN-split deployments).
+ */
+/** Path prefix (relative to storage root) where internal asset bytes live. */
+export declare const ASSETS_URL_PREFIX = "/assets";
+import { type Selector } from '../schema/dimensions.js';
+export interface BuildAssetUrlInput {
+    /** Asset name (the canonical identifier). */
+    name: string;
+    /**
+     * 8-char SHA-256 prefix of the bytes (matches the manifest `hash`).
+     * For locale-bytes overrides this is the OVERRIDE's hash, distinct
+     * from the default's hash.
+     */
+    hash: string;
+    /** File extension without the dot (e.g., `"jpg"`). */
+    ext: string;
+    /**
+     * Optional site URL — absolute URL prefix for targets served from a separate
+     * origin (e.g., `"https://cdn.example.com"`). When absent, the returned URL
+     * is root-relative.
+     */
+    siteUrl?: string;
+    /**
+     * Optional selector — when set, builds the URL for a locale/theme override.
+     * Path becomes `/assets/{name}-{hash}.{locale}[.{theme}].{ext}`. Null/omitted
+     * = default-bytes URL.
+     */
+    selector?: Selector | null;
+}
+/**
+ * Construct the public URL for an internal asset. Path pattern is
+ * `{ASSETS_URL_PREFIX}/{name}-{hash}[.{locale}][.{theme}].{ext}`, optionally
+ * prefixed with `siteUrl`.
+ *
+ * Normalizes trailing slashes — `siteUrl: "https://cdn.example.com/"` and
+ * `siteUrl: "https://cdn.example.com"` both produce the same URL.
+ */
+export declare function buildAssetUrl(input: BuildAssetUrlInput): string;
+/**
+ * Construct the public URL for a variant whose filename is already
+ * known (from the manifest's `variants[].path`). The filename is
+ * already hash-encoded and width-suffixed at ingest time, so this
+ * helper is just a prefix composer — keeps siteUrl normalization in
+ * one place.
+ */
+export declare function buildVariantUrl(variantPath: string, siteUrl?: string): string;
+/**
+ * Build the responsive `srcset` string from a manifest's variant list.
+ * Each variant contributes one `<url> <width>w` descriptor; the browser
+ * picks the best match for the viewport. Joined with `", "` per the
+ * HTML `srcset` spec.
+ *
+ * Lives here (not in `resolve.ts`) because URL composition — including
+ * this multi-variant flavor — is the `url.ts` module's single
+ * responsibility. Future transform adapters (Cloudflare Images,
+ * imgproxy) that build their own srcset ladders will compose this or
+ * substitute their own from the same module.
+ */
+export declare function buildSrcset(variants: readonly {
+    width: number;
+    path: string;
+}[], siteUrl?: string): string;
+/**
+ * Derive a file extension from a MIME type for the v1 allowlist.
+ * Returns `null` for unknown MIMEs — callers should already have validated
+ * MIME before reaching URL construction, so this is a defensive fallback.
+ */
+export declare function extFromMime(mime: string): string | null;
+//# sourceMappingURL=url.d.ts.map

package/dist/assets/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/assets/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,YAAY,CAAA;AAE1C,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,yBAAyB,CAAA;AAEvE,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAA;IACX;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAQ/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1G;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgCvD"}

package/dist/assets/url.js

@@ -0,0 +1,103 @@
+/**
+ * Asset URL construction — pure function from (siteUrl, asset manifest
+ * fields, extension) to the URL the template emits.
+ *
+ * Kept separate from `resolve.ts` because:
+ * - The resolver composes manifest I/O + URL construction + override merging.
+ *   URL construction is the only piece that's purely computational.
+ * - Future transform adapters (Cloudflare Images, imgproxy) build URLs too —
+ *   they share the `{name}-{hash}.{ext}` origin-URL shape and wrap it. Having
+ *   that builder in one place means adapters compose rather than duplicate.
+ *
+ * Output is root-relative when `siteUrl` is absent, absolute when present.
+ * Root-relative works anywhere; absolute is needed for targets that live on
+ * a different origin from the admin (CDN-split deployments).
+ */
+/** Path prefix (relative to storage root) where internal asset bytes live. */
+export const ASSETS_URL_PREFIX = '/assets';
+import { selectorSuffix } from '../schema/dimensions.js';
+/**
+ * Construct the public URL for an internal asset. Path pattern is
+ * `{ASSETS_URL_PREFIX}/{name}-{hash}[.{locale}][.{theme}].{ext}`, optionally
+ * prefixed with `siteUrl`.
+ *
+ * Normalizes trailing slashes — `siteUrl: "https://cdn.example.com/"` and
+ * `siteUrl: "https://cdn.example.com"` both produce the same URL.
+ */
+export function buildAssetUrl(input) {
+    const suffix = selectorSuffix(input.selector ?? null);
+    const path = `${ASSETS_URL_PREFIX}/${input.name}-${input.hash}${suffix}.${input.ext}`;
+    if (!input.siteUrl)
+        return path;
+    // Strip trailing slash from siteUrl before appending the root-relative path.
+    const base = input.siteUrl.endsWith('/') ? input.siteUrl.slice(0, -1) : input.siteUrl;
+    return `${base}${path}`;
+}
+/**
+ * Construct the public URL for a variant whose filename is already
+ * known (from the manifest's `variants[].path`). The filename is
+ * already hash-encoded and width-suffixed at ingest time, so this
+ * helper is just a prefix composer — keeps siteUrl normalization in
+ * one place.
+ */
+export function buildVariantUrl(variantPath, siteUrl) {
+    const path = `${ASSETS_URL_PREFIX}/${variantPath}`;
+    if (!siteUrl)
+        return path;
+    const base = siteUrl.endsWith('/') ? siteUrl.slice(0, -1) : siteUrl;
+    return `${base}${path}`;
+}
+/**
+ * Build the responsive `srcset` string from a manifest's variant list.
+ * Each variant contributes one `<url> <width>w` descriptor; the browser
+ * picks the best match for the viewport. Joined with `", "` per the
+ * HTML `srcset` spec.
+ *
+ * Lives here (not in `resolve.ts`) because URL composition — including
+ * this multi-variant flavor — is the `url.ts` module's single
+ * responsibility. Future transform adapters (Cloudflare Images,
+ * imgproxy) that build their own srcset ladders will compose this or
+ * substitute their own from the same module.
+ */
+export function buildSrcset(variants, siteUrl) {
+    return variants.map(v => `${buildVariantUrl(v.path, siteUrl)} ${v.width}w`).join(', ');
+}
+/**
+ * Derive a file extension from a MIME type for the v1 allowlist.
+ * Returns `null` for unknown MIMEs — callers should already have validated
+ * MIME before reaching URL construction, so this is a defensive fallback.
+ */
+export function extFromMime(mime) {
+    switch (mime) {
+        // Images
+        case 'image/jpeg':
+            return 'jpg';
+        case 'image/png':
+            return 'png';
+        case 'image/svg+xml':
+            return 'svg';
+        case 'image/gif':
+            return 'gif';
+        // Audio
+        case 'audio/mpeg':
+            return 'mp3';
+        case 'audio/wav':
+        case 'audio/x-wav':
+            return 'wav';
+        case 'audio/flac':
+        case 'audio/x-flac':
+            return 'flac';
+        case 'audio/ogg':
+            return 'ogg';
+        case 'audio/opus':
+            return 'opus';
+        case 'audio/aac':
+            return 'aac';
+        case 'audio/mp4':
+        case 'audio/x-m4a':
+            return 'm4a';
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=url.js.map

package/dist/assets/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/assets/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAE1C,OAAO,EAAiB,cAAc,EAAE,MAAM,yBAAyB,CAAA;AA2BvE;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAA;IACrD,MAAM,IAAI,GAAG,GAAG,iBAAiB,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,GAAG,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,CAAA;IACrF,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IAE/B,6EAA6E;IAC7E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAA;IACrF,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,CAAA;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,OAAgB;IACnE,MAAM,IAAI,GAAG,GAAG,iBAAiB,IAAI,WAAW,EAAE,CAAA;IAClD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;IACnE,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,CAAA;AACzB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,QAAoD,EAAE,OAAgB;IAChG,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACxF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,QAAQ,IAAI,EAAE,CAAC;QACb,SAAS;QACT,KAAK,YAAY;YACf,OAAO,KAAK,CAAA;QACd,KAAK,WAAW;YACd,OAAO,KAAK,CAAA;QACd,KAAK,eAAe;YAClB,OAAO,KAAK,CAAA;QACd,KAAK,WAAW;YACd,OAAO,KAAK,CAAA;QACd,QAAQ;QACR,KAAK,YAAY;YACf,OAAO,KAAK,CAAA;QACd,KAAK,WAAW,CAAC;QACjB,KAAK,aAAa;YAChB,OAAO,KAAK,CAAA;QACd,KAAK,YAAY,CAAC;QAClB,KAAK,cAAc;YACjB,OAAO,MAAM,CAAA;QACf,KAAK,WAAW;YACd,OAAO,KAAK,CAAA;QACd,KAAK,YAAY;YACf,OAAO,MAAM,CAAA;QACf,KAAK,WAAW;YACd,OAAO,KAAK,CAAA;QACd,KAAK,WAAW,CAAC;QACjB,KAAK,aAAa;YAChB,OAAO,KAAK,CAAA;QACd;YACE,OAAO,IAAI,CAAA;IACf,CAAC;AACH,CAAC"}

package/dist/assets/validate.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Default per-asset upload size cap — 50 MB. Sites override per target
+ * via `targets.{name}.assets.maxBytes` in `site.yaml`. Targets that
+ * don't override get this value.
+ *
+ * Why a default at all (per Q5):
+ *   - DoS / OOM bound: ingest buffers the full upload in memory today
+ *     (`collectBytes` in ingest.ts). Concurrent uploads × cap = peak
+ *     memory; without a cap, one careless or malicious client can
+ *     exhaust the admin process.
+ *   - Storage-cost protection: a 200 MB raw photo × variant ladder ×
+ *     locale overrides quickly compounds. The cap forces explicit
+ *     opt-in for unusual sizes.
+ *   - Worker-tier ceiling: Cloudflare Workers Free/Pro have a 100 MB
+ *     response body limit — a target on that tier can't serve assets
+ *     above it via the worker. Sites should lower the cap below the
+ *     worker tier they're on.
+ *
+ * 50 MB is conservative for image-only v1. Sites with raw-photo
+ * workflows (24-48 MP camera output) have headroom; sites on free
+ * worker tiers should reduce explicitly.
+ */
+export declare const DEFAULT_ASSET_MAX_BYTES: number;
+/**
+ * @deprecated Renamed to `DEFAULT_ASSET_MAX_BYTES`. Use the per-target
+ * config (`targets.{name}.assets.maxBytes`) for site-specific limits;
+ * this constant is the fallback default. Kept exported until the next
+ * major version so external callers (tests, integrations) don't break.
+ */
+export declare const ASSET_MAX_BYTES: number;
+/**
+ * v1 MIME allowlist. Image side: JPEG, PNG, SVG, GIF. Audio side:
+ * MP3, WAV, FLAC, Opus, AAC, M4A, OGG.
+ *
+ *   - SVG is sanitized before persistence (`svg-sanitize.ts`)
+ *   - GIF is checked for animation by `animatedImageAnalyzer`
+ *   - Audio MIMEs are analyzed by `audioAnalyzer` for duration
+ *     (`music-metadata`); personal-metadata stripping is a v1.5
+ *     opt-in via a future preprocessor surface
+ *
+ * Animated WebP/AVIF, video, and documents widen via this set in
+ * v1.1+. The analyzer/preprocessor abstractions accommodate each
+ * format-specific need without orchestrator edits.
+ */
+export declare const ALLOWED_MIMES: Set<string>;
+export interface UploadCandidate {
+    /** Desired asset name (what the author chose, pre-slug). */
+    name: string;
+    /** Bytes received so far; the stream is still flowing. */
+    claimedSize: number;
+    /** MIME sniffed from the bytes. Null when sniffing failed. */
+    sniffedMime: string | null;
+}
+/**
+ * Per-target validation policy. Today carries the size cap; future
+ * fields (allowed MIMEs subset, name pattern overrides) extend this
+ * interface without changing the validator's signature.
+ */
+export interface UploadPolicy {
+    /** Override the default per-target. When undefined, uses DEFAULT_ASSET_MAX_BYTES. */
+    maxBytes?: number;
+}
+/**
+ * Validate an upload candidate against the per-target policy. Throws
+ * the specific `AssetValidationError` subclass for the first failure
+ * encountered — policy enforces fail-fast so the HTTP route returns a
+ * single, specific reason to the client.
+ *
+ * `policy` is optional — callers that haven't migrated to per-target
+ * config get the default size cap. Once asset routes thread the
+ * target config through, `policy` is always present.
+ */
+export declare function validateUpload(candidate: UploadCandidate, policy?: UploadPolicy): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/assets/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/assets/validate.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,uBAAuB,QAAmB,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAA0B,CAAA;AAEtD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,aAiBxB,CAAA;AAWF,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAA;IACnB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,GAAE,YAAiB,GAAG,IAAI,CAI1F"}

package/dist/assets/validate.js

@@ -0,0 +1,136 @@
+/**
+ * Asset-upload validation policy. Pure — takes a candidate (name, claimed
+ * size, claimed MIME, sniffed MIME) and throws a typed validation error on
+ * the first failure. No I/O, no storage, no network.
+ *
+ * Keeping this pure means:
+ * - Tests are trivial: pass candidate data in, assert the thrown class
+ * - The same policy applies whether the caller is the HTTP route, a CLI
+ *   import command, or the future paste-URL handler
+ * - Policy evolves in one place
+ *
+ * Each validation failure throws a distinct `AssetValidationError`
+ * subclass (`AssetNameInvalidError`, `AssetPathTraversalError`, etc.).
+ * Callers that want to group all input-validation failures uniformly can
+ * still pattern-match on the base `AssetValidationError`.
+ */
+import { AssetMimeMismatchError, AssetNameInvalidError, AssetNameReservedError, AssetPathTraversalError, AssetSizeExceededError, } from './errors.js';
+/**
+ * Default per-asset upload size cap — 50 MB. Sites override per target
+ * via `targets.{name}.assets.maxBytes` in `site.yaml`. Targets that
+ * don't override get this value.
+ *
+ * Why a default at all (per Q5):
+ *   - DoS / OOM bound: ingest buffers the full upload in memory today
+ *     (`collectBytes` in ingest.ts). Concurrent uploads × cap = peak
+ *     memory; without a cap, one careless or malicious client can
+ *     exhaust the admin process.
+ *   - Storage-cost protection: a 200 MB raw photo × variant ladder ×
+ *     locale overrides quickly compounds. The cap forces explicit
+ *     opt-in for unusual sizes.
+ *   - Worker-tier ceiling: Cloudflare Workers Free/Pro have a 100 MB
+ *     response body limit — a target on that tier can't serve assets
+ *     above it via the worker. Sites should lower the cap below the
+ *     worker tier they're on.
+ *
+ * 50 MB is conservative for image-only v1. Sites with raw-photo
+ * workflows (24-48 MP camera output) have headroom; sites on free
+ * worker tiers should reduce explicitly.
+ */
+export const DEFAULT_ASSET_MAX_BYTES = 50 * 1024 * 1024;
+/**
+ * @deprecated Renamed to `DEFAULT_ASSET_MAX_BYTES`. Use the per-target
+ * config (`targets.{name}.assets.maxBytes`) for site-specific limits;
+ * this constant is the fallback default. Kept exported until the next
+ * major version so external callers (tests, integrations) don't break.
+ */
+export const ASSET_MAX_BYTES = DEFAULT_ASSET_MAX_BYTES;
+/**
+ * v1 MIME allowlist. Image side: JPEG, PNG, SVG, GIF. Audio side:
+ * MP3, WAV, FLAC, Opus, AAC, M4A, OGG.
+ *
+ *   - SVG is sanitized before persistence (`svg-sanitize.ts`)
+ *   - GIF is checked for animation by `animatedImageAnalyzer`
+ *   - Audio MIMEs are analyzed by `audioAnalyzer` for duration
+ *     (`music-metadata`); personal-metadata stripping is a v1.5
+ *     opt-in via a future preprocessor surface
+ *
+ * Animated WebP/AVIF, video, and documents widen via this set in
+ * v1.1+. The analyzer/preprocessor abstractions accommodate each
+ * format-specific need without orchestrator edits.
+ */
+export const ALLOWED_MIMES = new Set([
+    // Images
+    'image/jpeg',
+    'image/png',
+    'image/svg+xml',
+    'image/gif',
+    // Audio
+    'audio/mpeg',
+    'audio/wav',
+    'audio/x-wav',
+    'audio/flac',
+    'audio/x-flac',
+    'audio/ogg',
+    'audio/opus',
+    'audio/aac',
+    'audio/mp4',
+    'audio/x-m4a',
+]);
+/** Asset-name validation: lowercase ASCII-safe characters. */
+const VALID_NAME = /^[a-z0-9][a-z0-9\-_]*(?:\.[a-z0-9]+)?$/;
+/** Max chars per asset name. */
+const MAX_NAME_LENGTH = 200;
+/** Reserved name patterns — authors can't upload anything that would collide with internals. */
+const RESERVED_PREFIXES = ['.', '_refs/', '.gazetta/'];
+const RESERVED_SUFFIXES = ['.asset.json'];
+/**
+ * Validate an upload candidate against the per-target policy. Throws
+ * the specific `AssetValidationError` subclass for the first failure
+ * encountered — policy enforces fail-fast so the HTTP route returns a
+ * single, specific reason to the client.
+ *
+ * `policy` is optional — callers that haven't migrated to per-target
+ * config get the default size cap. Once asset routes thread the
+ * target config through, `policy` is always present.
+ */
+export function validateUpload(candidate, policy = {}) {
+    assertName(candidate.name);
+    assertSize(candidate.claimedSize, policy.maxBytes ?? DEFAULT_ASSET_MAX_BYTES);
+    assertMime(candidate.sniffedMime);
+}
+function assertName(name) {
+    if (name.length === 0 || name.length > MAX_NAME_LENGTH) {
+        throw new AssetNameInvalidError(name, `Asset name must be 1–${MAX_NAME_LENGTH} characters (got ${name.length})`);
+    }
+    // Path-traversal: `..`, leading `/`, or backslash anywhere
+    if (name.includes('..') || name.startsWith('/') || name.includes('\\')) {
+        throw new AssetPathTraversalError(name);
+    }
+    // Reserved prefixes and suffixes
+    for (const prefix of RESERVED_PREFIXES) {
+        if (name.startsWith(prefix)) {
+            throw new AssetNameReservedError(name, prefix, 'prefix');
+        }
+    }
+    for (const suffix of RESERVED_SUFFIXES) {
+        if (name.endsWith(suffix)) {
+            throw new AssetNameReservedError(name, suffix, 'suffix');
+        }
+    }
+    // Character rules (lowercase ASCII, digits, hyphens, underscores, optional extension)
+    if (!VALID_NAME.test(name)) {
+        throw new AssetNameInvalidError(name, `Asset name must be lowercase ASCII letters/digits/hyphens/underscores with optional extension: ${name}`);
+    }
+}
+function assertSize(claimedSize, maxBytes) {
+    if (claimedSize <= 0 || claimedSize > maxBytes) {
+        throw new AssetSizeExceededError(claimedSize, maxBytes);
+    }
+}
+function assertMime(sniffedMime) {
+    if (!sniffedMime || !ALLOWED_MIMES.has(sniffedMime)) {
+        throw new AssetMimeMismatchError(sniffedMime, [...ALLOWED_MIMES]);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/assets/validate.js.map

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

package/dist/assets/variants.d.ts

@@ -0,0 +1,23 @@
+/** The v1 srcset ladder. Ordered ascending — callers rely on this. */
+export declare const VARIANT_WIDTHS: readonly number[];
+export interface GeneratedVariant {
+    /** Target width this variant was rendered at. */
+    width: number;
+    /** The resized image bytes. */
+    bytes: Uint8Array;
+}
+/**
+ * Generate responsive variants from a source image buffer. Produces one
+ * variant per `VARIANT_WIDTHS` entry that is ≤ the source image's width.
+ *
+ * Same output format as the input (JPEG stays JPEG, PNG stays PNG) —
+ * re-compression is implicit via sharp's encoder, which applies its
+ * quality defaults. Explicit quality/compression tuning is deferred to
+ * a future image-pipeline config module.
+ *
+ * Throws whatever sharp throws on unreadable input — the caller is
+ * responsible for treating that as a hard ingest failure (per v1
+ * contract: rollback + fail the upload).
+ */
+export declare function generateVariants(source: Uint8Array): Promise<GeneratedVariant[]>;
+//# sourceMappingURL=variants.d.ts.map

package/dist/assets/variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.d.ts","sourceRoot":"","sources":["../../src/assets/variants.ts"],"names":[],"mappings":"AAkBA,sEAAsE;AACtE,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAA2B,CAAA;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,+BAA+B;IAC/B,KAAK,EAAE,UAAU,CAAA;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAsBtF"}