gazetta 0.5.0 → 0.7.0

package/dist/assets/manifest-default.js

@@ -0,0 +1,120 @@
+import { AssetManifestCorruptError, AssetManifestNotFoundError, AssetStorageError } from './errors.js';
+import { manifestPath } from './manifest.js';
+/**
+ * Read a default asset manifest from storage. Throws:
+ *   - `AssetManifestNotFoundError` when the manifest file doesn't exist
+ *   - `AssetManifestCorruptError` when it exists but doesn't validate
+ *   - `AssetStorageError` on any other storage failure
+ *
+ * Default manifests are required (vs. locale manifests which are optional);
+ * an asset that has no `{name}.asset.json` doesn't exist.
+ */
+export async function readDefaultManifest(storage, assetsRoot, assetName) {
+    const path = `${assetsRoot}/${manifestPath(assetName)}`;
+    const exists = await storage.exists(path).catch(err => {
+        throw new AssetStorageError('stat', path, err);
+    });
+    if (!exists)
+        throw new AssetManifestNotFoundError(assetName);
+    let raw;
+    try {
+        raw = await storage.readFile(path);
+    }
+    catch (err) {
+        throw new AssetStorageError('read', path, err);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new AssetManifestCorruptError(path, err);
+    }
+    if (!isDefaultManifest(parsed)) {
+        throw new AssetManifestCorruptError(path, new Error('manifest shape mismatch'));
+    }
+    return parsed;
+}
+/**
+ * Type guard: narrow a parsed-JSON value to `AssetManifest`.
+ *
+ * Validation order:
+ *   1. Common identity fields (version, name, kind, source)
+ *   2. Per-kind required field rules (today: same set across kinds; the
+ *      switch is in place for step 17's kind-specific divergence)
+ *   3. Common metadata fields (alt, uploadedAt, uploadedBy)
+ *
+ * Returns `false` on any failure — callers translate to
+ * `AssetManifestCorruptError` for I/O paths.
+ */
+export function isDefaultManifest(candidate) {
+    if (!candidate || typeof candidate !== 'object')
+        return false;
+    const m = candidate;
+    // 1. Identity fields (always present, never override-able)
+    if (m.version !== 1)
+        return false;
+    if (typeof m.name !== 'string')
+        return false;
+    if (m.kind !== 'embedded' && m.kind !== 'downloadable' && m.kind !== 'font')
+        return false;
+    if (m.source !== 'internal')
+        return false;
+    // 2. Per-kind required fields. Today all kinds require the same byte-
+    // describing set; step 17 will diverge fonts (add cssName/format/etc.)
+    // and downloadables (add title). This switch reserves the dispatch
+    // shape so adding a per-kind rule is an additive change.
+    if (!validateByteFields(m))
+        return false;
+    switch (m.kind) {
+        case 'embedded':
+            // No additional fields beyond byte-describing today.
+            break;
+        case 'downloadable':
+            // Step 17 will add: typeof m.title === 'string', etc.
+            break;
+        case 'font':
+            // Step 17 will add: cssName, format, weight, style, optional
+            // unicodeRange, etc.
+            break;
+    }
+    // 3. Common metadata
+    if (m.alt !== null && typeof m.alt !== 'string')
+        return false;
+    if (typeof m.uploadedAt !== 'string')
+        return false;
+    if (typeof m.uploadedBy !== 'string')
+        return false;
+    return true;
+}
+/**
+ * Byte-describing field validator. All three kinds today require the
+ * same set: mime, size, hash, width/height (or null), variants array.
+ * Extracted as a helper so the kind-specific switch above can compose
+ * it cleanly when a future kind needs different bytes contract (e.g.
+ * font subsetting changing what `variants` means).
+ */
+function validateByteFields(m) {
+    if (typeof m.mime !== 'string')
+        return false;
+    if (typeof m.size !== 'number')
+        return false;
+    if (typeof m.hash !== 'string')
+        return false;
+    if (m.width !== null && typeof m.width !== 'number')
+        return false;
+    if (m.height !== null && typeof m.height !== 'number')
+        return false;
+    if (!Array.isArray(m.variants))
+        return false;
+    if (!m.variants.every(isAssetVariant))
+        return false;
+    return true;
+}
+function isAssetVariant(candidate) {
+    if (!candidate || typeof candidate !== 'object')
+        return false;
+    const v = candidate;
+    return typeof v.width === 'number' && typeof v.path === 'string' && typeof v.size === 'number';
+}
+//# sourceMappingURL=manifest-default.js.map

package/dist/assets/manifest-default.js.map

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

package/dist/assets/manifest-filename.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Asset manifest filename parsing — the inverse of `manifestPath` /
+ * `selectorSuffix`. Given a filename on disk, extract the asset name and
+ * (locale, theme) selector. Used by `enumerateAssetStoragePaths` to find
+ * existing locale/theme override manifests without trusting filename
+ * conventions blindly.
+ *
+ * Single responsibility: filename ↔ (assetName, selector). No I/O, no
+ * disambiguation across asset names, no schema awareness. Pure.
+ *
+ * Grammar (per design-media.md and dimensions.ts):
+ *   {name}.asset.json                          → default manifest, selector=null
+ *   {name}.asset.{locale}.json                 → locale-only override
+ *   {name}.asset.{theme}.json                  → theme-only override
+ *   {name}.asset.{locale}.{theme}.json         → locale + theme
+ *
+ * Selector tokens:
+ *   - locale: BCP 47 (lowercase), validated by `isValidLocale`
+ *   - theme: lowercase ASCII non-locale token, validated by `isValidTheme`
+ *
+ * Per `DIMENSION_ORDER` (locale before theme), classification is:
+ *   - 1 token: locale OR theme — try locale first; theme on miss
+ *   - 2 tokens: first is locale, second is theme. The first token MUST
+ *     validate as a locale and the second MUST validate as a theme — any
+ *     other shape is rejected (no slot reordering, no theme-then-locale).
+ *
+ * Adding a future dimension: extend the recognized-tokens loop to walk
+ * `DIMENSION_ORDER` and try each dimension's validator in turn. Today
+ * the closed two-dimension grammar lets us hardcode the cases for
+ * clarity.
+ */
+import { type Selector } from '../schema/dimensions.js';
+/**
+ * Parsed manifest filename. Carries the asset name and the selector
+ * extracted from the suffix. `selector === null` means default manifest.
+ */
+export interface ParsedManifestFilename {
+    readonly assetName: string;
+    readonly selector: Selector | null;
+}
+/**
+ * Try to parse `filename` as an asset manifest. Returns `null` when:
+ *   - the filename doesn't end in `.asset.json` (or `.asset.X.json` etc.)
+ *   - any selector token fails its validator
+ *   - the asset name (everything before `.asset`) is empty
+ *
+ * Strict — invalid selector tokens are rejected outright, not coerced.
+ * Callers that scan a directory pass every entry through this; matches
+ * surface as overrides, misses are skipped (could be unrelated files).
+ */
+export declare function parseManifestFilename(filename: string): ParsedManifestFilename | null;
+//# sourceMappingURL=manifest-filename.d.ts.map

package/dist/assets/manifest-filename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-filename.d.ts","sourceRoot":"","sources":["../../src/assets/manifest-filename.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAItE;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI,CA2BrF"}

package/dist/assets/manifest-filename.js

@@ -0,0 +1,104 @@
+/**
+ * Asset manifest filename parsing — the inverse of `manifestPath` /
+ * `selectorSuffix`. Given a filename on disk, extract the asset name and
+ * (locale, theme) selector. Used by `enumerateAssetStoragePaths` to find
+ * existing locale/theme override manifests without trusting filename
+ * conventions blindly.
+ *
+ * Single responsibility: filename ↔ (assetName, selector). No I/O, no
+ * disambiguation across asset names, no schema awareness. Pure.
+ *
+ * Grammar (per design-media.md and dimensions.ts):
+ *   {name}.asset.json                          → default manifest, selector=null
+ *   {name}.asset.{locale}.json                 → locale-only override
+ *   {name}.asset.{theme}.json                  → theme-only override
+ *   {name}.asset.{locale}.{theme}.json         → locale + theme
+ *
+ * Selector tokens:
+ *   - locale: BCP 47 (lowercase), validated by `isValidLocale`
+ *   - theme: lowercase ASCII non-locale token, validated by `isValidTheme`
+ *
+ * Per `DIMENSION_ORDER` (locale before theme), classification is:
+ *   - 1 token: locale OR theme — try locale first; theme on miss
+ *   - 2 tokens: first is locale, second is theme. The first token MUST
+ *     validate as a locale and the second MUST validate as a theme — any
+ *     other shape is rejected (no slot reordering, no theme-then-locale).
+ *
+ * Adding a future dimension: extend the recognized-tokens loop to walk
+ * `DIMENSION_ORDER` and try each dimension's validator in turn. Today
+ * the closed two-dimension grammar lets us hardcode the cases for
+ * clarity.
+ */
+import { buildSelector } from '../schema/dimensions.js';
+import { isValidLocale } from '../locale.js';
+import { isValidTheme } from '../themes.js';
+/**
+ * Try to parse `filename` as an asset manifest. Returns `null` when:
+ *   - the filename doesn't end in `.asset.json` (or `.asset.X.json` etc.)
+ *   - any selector token fails its validator
+ *   - the asset name (everything before `.asset`) is empty
+ *
+ * Strict — invalid selector tokens are rejected outright, not coerced.
+ * Callers that scan a directory pass every entry through this; matches
+ * surface as overrides, misses are skipped (could be unrelated files).
+ */
+export function parseManifestFilename(filename) {
+    if (!filename.endsWith('.json'))
+        return null;
+    // Strip the trailing `.json`.
+    const withoutExt = filename.slice(0, -'.json'.length);
+    // Find the `.asset` marker. The asset name is everything before it;
+    // the selector tokens are everything after (dot-separated).
+    const markerIdx = withoutExt.lastIndexOf('.asset');
+    if (markerIdx < 0)
+        return null;
+    const assetName = withoutExt.slice(0, markerIdx);
+    const afterMarker = withoutExt.slice(markerIdx + '.asset'.length);
+    if (assetName.length === 0)
+        return null;
+    // Default manifest — no selector tokens.
+    if (afterMarker.length === 0) {
+        return { assetName, selector: null };
+    }
+    // Selector tokens follow as `.token1` or `.token1.token2`. Anything
+    // else (no leading dot, empty token from `..`) is invalid.
+    if (!afterMarker.startsWith('.'))
+        return null;
+    const tokens = afterMarker.slice(1).split('.');
+    if (tokens.length === 0 || tokens.length > 2)
+        return null;
+    if (tokens.some(t => t.length === 0))
+        return null;
+    const selector = classifySelectorTokens(tokens);
+    if (selector === null)
+        return null;
+    return { assetName, selector };
+}
+/**
+ * Classify selector tokens into a Selector. Returns null if the tokens
+ * don't form a valid (locale?, theme?) shape per the grammar.
+ *
+ * One-token forms try locale first, then theme. Both validators reject
+ * each other's shapes (theme rejects BCP 47; isValidLocale rejects
+ * lowercase-only non-BCP-47), so the order is unambiguous in practice
+ * and this preference matters only for the rare case where both
+ * validators accept (which the validators are designed not to do).
+ */
+function classifySelectorTokens(tokens) {
+    if (tokens.length === 1) {
+        const t = tokens[0];
+        if (isValidLocale(t))
+            return buildSelector({ locale: t });
+        if (isValidTheme(t))
+            return buildSelector({ theme: t });
+        return null;
+    }
+    // Two tokens: locked order is locale, then theme.
+    const [t1, t2] = tokens;
+    if (!isValidLocale(t1))
+        return null;
+    if (!isValidTheme(t2))
+        return null;
+    return buildSelector({ locale: t1, theme: t2 });
+}
+//# sourceMappingURL=manifest-filename.js.map

package/dist/assets/manifest-filename.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-filename.js","sourceRoot":"","sources":["../../src/assets/manifest-filename.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,aAAa,EAAiB,MAAM,yBAAyB,CAAA;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAW3C;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAA;IAC5C,8BAA8B;IAC9B,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACrD,oEAAoE;IACpE,4DAA4D;IAC5D,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAA;IAClD,IAAI,SAAS,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAC9B,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;IAChD,MAAM,WAAW,GAAG,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;IACjE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEvC,yCAAyC;IACzC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;IACtC,CAAC;IAED,oEAAoE;IACpE,2DAA2D;IAC3D,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAC7C,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC9C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACzD,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAEjD,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAA;IAC/C,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IAClC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;AAChC,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,sBAAsB,CAAC,MAAyB;IACvD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAE,CAAA;QACpB,IAAI,aAAa,CAAC,CAAC,CAAC;YAAE,OAAO,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;QACzD,IAAI,YAAY,CAAC,CAAC,CAAC;YAAE,OAAO,aAAa,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA;QACvD,OAAO,IAAI,CAAA;IACb,CAAC;IACD,kDAAkD;IAClD,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,MAA0B,CAAA;IAC3C,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAA;IACnC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAA;IAClC,OAAO,aAAa,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAA;AACjD,CAAC"}

package/dist/assets/manifest-locale.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Locale-variant manifest I/O + validation, dispatched by asset kind.
+ *
+ * Three kinds, three locale-variant shapes:
+ *   - embedded → `LocaleOverrideManifest` (override-merge per Q3 lock)
+ *   - downloadable → `LocaleOverrideManifest` (same shape as embedded)
+ *   - font → `FontLocaleAdditiveManifest` (additive variant union, NOT
+ *     override; per Q3 lock fonts compose differently)
+ *
+ * # The interface
+ *
+ * `LocaleManifestVariant<T>` packages "validate + read" for one kind's
+ * locale-variant shape. Three implementations (one per kind), one
+ * dispatch table. Adding a new kind = new implementation + table entry,
+ * no changes to existing kinds.
+ *
+ * # Why locale variants are optional
+ *
+ * Default manifests are required (no default = asset doesn't exist);
+ * locale variants are optional. Reads return `null` when the file is
+ * missing — same shape as "no override for this locale." Throwing on
+ * missing would force every walker to wrap in try/catch when "absent"
+ * is the common case.
+ *
+ * # Why a separate module from manifest-default.ts
+ *
+ * Default and locale shapes are genuinely distinct (locale-override has
+ * optional byte fields; locale-additive-font has font-specific fields).
+ * Separate modules let each evolve independently. The dispatch table
+ * (`localeManifestVariants`) is the only place a caller bridges them —
+ * keying by `AssetKind` keeps the bridge mechanical.
+ */
+import type { StorageProvider } from '../types.js';
+import type { Selector } from '../schema/dimensions.js';
+import type { AssetKind, FontLocaleAdditiveManifest, LocaleOverrideManifest } from '../schema/types.js';
+/**
+ * Variant of locale-manifest I/O for one asset kind. Three concrete
+ * implementations; the dispatch table picks based on the default
+ * manifest's `kind` (which is read separately, before any locale
+ * variant lookup).
+ */
+export interface LocaleManifestVariant<T> {
+    /** Type guard for parsed JSON. Returns false on shape mismatch. */
+    validate(parsed: unknown): parsed is T;
+    /**
+     * Read + parse + validate. Returns `null` when the file doesn't
+     * exist (the common case). Throws `AssetManifestCorruptError` on
+     * shape mismatch, `AssetStorageError` on I/O failure.
+     */
+    read(storage: StorageProvider, assetsRoot: string, assetName: string, selector: Selector): Promise<T | null>;
+}
+/**
+ * Get the locale-manifest variant for a given asset kind. Type
+ * narrows the return so callers see the right manifest shape.
+ */
+export declare function localeManifestVariantFor(kind: 'embedded'): LocaleManifestVariant<LocaleOverrideManifest>;
+export declare function localeManifestVariantFor(kind: 'downloadable'): LocaleManifestVariant<LocaleOverrideManifest>;
+export declare function localeManifestVariantFor(kind: 'font'): LocaleManifestVariant<FontLocaleAdditiveManifest>;
+export declare function localeManifestVariantFor(kind: AssetKind): LocaleManifestVariant<LocaleOverrideManifest> | LocaleManifestVariant<FontLocaleAdditiveManifest>;
+//# sourceMappingURL=manifest-locale.d.ts.map

package/dist/assets/manifest-locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-locale.d.ts","sourceRoot":"","sources":["../../src/assets/manifest-locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAgB,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAIrH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,CAAC,CAAA;IACtC;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;CAC7G;AAsDD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG,qBAAqB,CAAC,sBAAsB,CAAC,CAAA;AACzG,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,cAAc,GAAG,qBAAqB,CAAC,sBAAsB,CAAC,CAAA;AAC7G,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAAC,0BAA0B,CAAC,CAAA;AACzG,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,GACd,qBAAqB,CAAC,sBAAsB,CAAC,GAAG,qBAAqB,CAAC,0BAA0B,CAAC,CAAA"}

package/dist/assets/manifest-locale.js

@@ -0,0 +1,206 @@
+import { AssetManifestCorruptError, AssetStorageError } from './errors.js';
+import { manifestPath } from './manifest.js';
+// ---------- Embedded locale-override variant ----------
+const embeddedVariant = {
+    validate(parsed) {
+        return validateLocaleOverride(parsed);
+    },
+    async read(storage, assetsRoot, assetName, selector) {
+        return readLocaleOverride(storage, assetsRoot, assetName, selector);
+    },
+};
+// ---------- Downloadable locale-override variant ----------
+// Today's downloadable shape matches embedded's locale-override shape
+// exactly — both share `LocaleOverrideManifest`. They diverge structurally
+// only when downloadable gains its own fields (`title`, `description`)
+// in step 17. The validator gains those checks then; today the same
+// `validateLocaleOverride` covers both, with the kind-specific switch
+// living in this dispatch.
+const downloadableVariant = {
+    validate(parsed) {
+        return validateLocaleOverride(parsed);
+    },
+    async read(storage, assetsRoot, assetName, selector) {
+        return readLocaleOverride(storage, assetsRoot, assetName, selector);
+    },
+};
+// ---------- Font locale-additive variant ----------
+const fontVariant = {
+    validate(parsed) {
+        return validateFontLocaleAdditive(parsed);
+    },
+    async read(storage, assetsRoot, assetName, selector) {
+        return readFontLocaleAdditive(storage, assetsRoot, assetName, selector);
+    },
+};
+// ---------- Dispatch table ----------
+/**
+ * Map kind → locale variant. Walker reads the default first to discover
+ * `kind`, then looks up the right variant here. Type narrows via the
+ * indexed access in `localeManifestVariantFor`.
+ */
+const variantsByKind = {
+    embedded: embeddedVariant,
+    downloadable: downloadableVariant,
+    font: fontVariant,
+};
+export function localeManifestVariantFor(kind) {
+    return variantsByKind[kind];
+}
+// ---------- Shared read helper for embedded/downloadable ----------
+async function readLocaleOverride(storage, assetsRoot, assetName, selector) {
+    const path = `${assetsRoot}/${manifestPath(assetName, selector)}`;
+    const exists = await storage.exists(path).catch(err => {
+        throw new AssetStorageError('stat', path, err);
+    });
+    if (!exists)
+        return null;
+    let raw;
+    try {
+        raw = await storage.readFile(path);
+    }
+    catch (err) {
+        throw new AssetStorageError('read', path, err);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new AssetManifestCorruptError(path, err);
+    }
+    if (!validateLocaleOverride(parsed)) {
+        throw new AssetManifestCorruptError(path, new Error('locale-override manifest shape mismatch'));
+    }
+    return parsed;
+}
+async function readFontLocaleAdditive(storage, assetsRoot, assetName, selector) {
+    const path = `${assetsRoot}/${manifestPath(assetName, selector)}`;
+    const exists = await storage.exists(path).catch(err => {
+        throw new AssetStorageError('stat', path, err);
+    });
+    if (!exists)
+        return null;
+    let raw;
+    try {
+        raw = await storage.readFile(path);
+    }
+    catch (err) {
+        throw new AssetStorageError('read', path, err);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new AssetManifestCorruptError(path, err);
+    }
+    if (!validateFontLocaleAdditive(parsed)) {
+        throw new AssetManifestCorruptError(path, new Error('font-locale-additive manifest shape mismatch'));
+    }
+    return parsed;
+}
+// ---------- Validators ----------
+/**
+ * Validate a locale-override manifest. Two valid shapes (per the
+ * discriminated union in schema/types.ts):
+ *
+ *   1. Metadata-only override — no `hash`. All byte-describing fields
+ *      must be absent. Optional metadata fields validate per their type.
+ *   2. Bytes override — `hash` set. `size`, `mime`, `width`, `height`,
+ *      `variants` MUST all be present (byte-presence-coupled).
+ */
+function validateLocaleOverride(candidate) {
+    if (!candidate || typeof candidate !== 'object')
+        return false;
+    const m = candidate;
+    // Identity fields (always present)
+    if (m.version !== 1)
+        return false;
+    if (typeof m.name !== 'string')
+        return false;
+    // Byte-presence coupling: hash present ⇒ all bytes-describing fields present
+    const hasHash = m.hash !== undefined;
+    if (hasHash) {
+        if (typeof m.hash !== 'string')
+            return false;
+        if (typeof m.size !== 'number')
+            return false;
+        if (typeof m.mime !== 'string')
+            return false;
+        if (m.width !== null && typeof m.width !== 'number')
+            return false;
+        if (m.height !== null && typeof m.height !== 'number')
+            return false;
+        if (!Array.isArray(m.variants))
+            return false;
+        if (!m.variants.every(isAssetVariant))
+            return false;
+    }
+    else {
+        // Metadata-only: byte-describing fields must all be absent
+        if (m.size !== undefined)
+            return false;
+        if (m.mime !== undefined)
+            return false;
+        if (m.width !== undefined)
+            return false;
+        if (m.height !== undefined)
+            return false;
+        if (m.variants !== undefined)
+            return false;
+    }
+    // Optional metadata overrides (shared by metadata-only and bytes-override)
+    if (m.alt !== undefined && m.alt !== null && typeof m.alt !== 'string')
+        return false;
+    if (m.focalPoint !== undefined && !isFocalPoint(m.focalPoint))
+        return false;
+    if (m.title !== undefined && typeof m.title !== 'string')
+        return false;
+    if (m.description !== undefined && typeof m.description !== 'string')
+        return false;
+    return true;
+}
+/**
+ * Validate a font locale-additive manifest. Fonts always have bytes
+ * (a font with no bytes is meaningless) AND font-specific fields.
+ */
+function validateFontLocaleAdditive(candidate) {
+    if (!candidate || typeof candidate !== 'object')
+        return false;
+    const m = candidate;
+    if (m.version !== 1)
+        return false;
+    if (typeof m.name !== 'string')
+        return false;
+    // Bytes are mandatory for fonts
+    if (typeof m.hash !== 'string')
+        return false;
+    if (typeof m.size !== 'number')
+        return false;
+    if (typeof m.mime !== 'string')
+        return false;
+    // Font-specific fields
+    if (m.format !== 'woff2' && m.format !== 'woff' && m.format !== 'ttf' && m.format !== 'otf')
+        return false;
+    if (m.weight !== 'variable' && typeof m.weight !== 'number')
+        return false;
+    if (m.style !== 'normal' && m.style !== 'italic')
+        return false;
+    if (m.unicodeRange !== null && typeof m.unicodeRange !== 'string')
+        return false;
+    return true;
+}
+function isAssetVariant(candidate) {
+    if (!candidate || typeof candidate !== 'object')
+        return false;
+    const v = candidate;
+    return typeof v.width === 'number' && typeof v.path === 'string' && typeof v.size === 'number';
+}
+function isFocalPoint(candidate) {
+    if (!candidate || typeof candidate !== 'object')
+        return false;
+    const f = candidate;
+    return typeof f.x === 'number' && typeof f.y === 'number';
+}
+//# sourceMappingURL=manifest-locale.js.map

package/dist/assets/manifest-locale.js.map

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

package/dist/assets/manifest-merge.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Manifest field-merge primitives. Pure functions; no I/O.
+ *
+ * Two operations:
+ *   - `applyLocaleOverrides` — shallow spread of one override on top of a
+ *     base manifest. The override's non-undefined fields win; everything
+ *     else falls through to the base.
+ *   - `foldLocaleChain` — multi-overlay fold: read each chain entry and
+ *     spread it on the previous, most-specific-LAST so most-specific
+ *     wins per field.
+ *
+ * # Why a separate module
+ *
+ * The merge is the one piece of logic shared between embedded and
+ * downloadable kind resolvers (per Q3 lock). Font resolver does NOT
+ * use override-merge — it composes a variant union, structurally
+ * different. So the merge primitive lives separately and the kinds
+ * that share semantics compose it; the one that doesn't, doesn't.
+ *
+ * # Shallow vs deep
+ *
+ * The merge is SHALLOW. `focalPoint`, `variants`, `width`, `height` are
+ * atomic values from the override's perspective — partial focal-point
+ * overrides aren't a concept. If a locale variant carries `focalPoint`,
+ * its full {x, y} pair replaces the default's; you don't mix x from one
+ * with y from another.
+ *
+ * # Why use spread of `Partial<M>` instead of typed `LocaleOverrideManifest`
+ *
+ * Generic over manifest type so the same primitive can serve embedded
+ * and downloadable (and any future kind that wants override-wins
+ * semantics) without re-implementing per kind.
+ */
+/**
+ * Spread `override`'s non-undefined fields onto `base`. Returns a new
+ * object — `base` is not mutated.
+ *
+ * Fields that are `undefined` in `override` do NOT shadow `base`'s value.
+ * That's the whole point: a locale manifest with only `alt` set should
+ * keep the default's everything-else.
+ *
+ * `null` is treated as a value, not "absent". `alt: null` on the override
+ * explicitly clears the default's alt — useful for "this locale's image
+ * is decorative even though the default has alt text."
+ */
+export declare function applyLocaleOverrides<M extends object>(base: M, override: Partial<M> | null): M;
+/**
+ * Fold a chain of overrides onto a base. Chain order is
+ * most-specific-LAST so the final fold step replaces fields from
+ * less-specific entries.
+ *
+ * Example for active `pt-BR` with fallback `pt`:
+ *
+ *   chain = [pt-manifest, pt-BR-manifest]   // least-specific FIRST
+ *   foldLocaleChain(default, chain)
+ *
+ * Step 1: apply pt overrides onto default → pt-effective
+ * Step 2: apply pt-BR overrides onto pt-effective → pt-BR-effective
+ *
+ * Most-specific (pt-BR) wins per field. Entries that are `null` (locale
+ * manifest didn't exist) are skipped — same effect as no overrides.
+ *
+ * Caller responsibility: order the chain correctly. Most-specific LAST.
+ */
+export declare function foldLocaleChain<M extends object>(base: M, chain: readonly (Partial<M> | null)[]): M;
+//# sourceMappingURL=manifest-merge.d.ts.map

package/dist/assets/manifest-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-merge.d.ts","sourceRoot":"","sources":["../../src/assets/manifest-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAQ9F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAMnG"}