gazetta 0.5.0 → 0.7.0

package/dist/schema/types.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Asset schema — reference and resolved type spaces, and the `Content<T>`
+ * utility that walks a Zod-inferred content type and swaps reference types
+ * for resolved types.
+ *
+ * Two distinct type spaces:
+ * - **Reference shapes** — what's stored in page/fragment content JSON. The
+ *   authoring model: "this content field points to asset X with this optional
+ *   override." Small, stable.
+ * - **Resolved shapes** — what templates receive at render time after the
+ *   resolver merges manifest + reference overrides. Large, evolves as
+ *   templates gain capabilities.
+ *
+ * Brands distinguish reference types from plain objects. `Content<T>` reads
+ * the brand to perform the swap. Brands are phantom — attached at the type
+ * level via `z.brand(...)` in `helpers.ts`, invisible at runtime.
+ *
+ * Branding is split across the two modules by role:
+ * - `types.ts` (this file) owns the `Resolved*Asset` shapes and the
+ *   `Content<T>` mapper that consumes brands.
+ * - `helpers.ts` owns the `embeddedAsset()` / `downloadable()` / `fontAsset()`
+ *   Zod schemas that attach brands to their inferred output.
+ */
+/** Embedded asset reference — stored in content JSON for image/video/audio fields. */
+export interface EmbeddedAssetRef {
+    /** Asset name (path-like, e.g. `"hero"` or `"products/shot"`). */
+    _asset: string;
+    /** Per-reference alt override. When absent, falls back to asset manifest's alt. */
+    alt?: string;
+    /** Per-reference focal-point override. Image assets only; 0–1 normalized. */
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+}
+/** Downloadable asset reference — stored in content JSON for file-download fields. */
+export interface DownloadableAssetRef {
+    _asset: string;
+    /** Per-reference title override (the human-readable link label). */
+    title?: string;
+    /** Optional blurb rendered next to the link. */
+    description?: string;
+}
+/** Font asset reference — stored in content JSON for @font-face fields. */
+export interface FontAssetRef {
+    _asset: string;
+}
+/**
+ * Asset rendering role — determines how templates use the asset.
+ *   - `embedded` — rendered inline (`<img>`, `<video>`, `<audio>`)
+ *   - `downloadable` — linked for download (`<a href download>`)
+ *   - `font` — loaded via `@font-face`, used by CSS name
+ *
+ * Set at upload time; identity attribute. Never overridable on locale
+ * variants.
+ */
+export type AssetKind = 'embedded' | 'downloadable' | 'font';
+/**
+ * A single responsive variant of an image asset. Pre-generated at
+ * upload time; the resolver composes these into a `srcset` string.
+ */
+export interface AssetVariant {
+    /** Target width in pixels. */
+    width: number;
+    /** Path relative to the assets root, e.g. `hero-a3b2c1d4-800w.jpg`. */
+    path: string;
+    /** On-disk size of the variant in bytes. */
+    size: number;
+}
+/**
+ * Asset manifest — the JSON written to `{name}.asset.json` for each asset.
+ * Storage shape, distinct from reference (content JSON) and resolved (template
+ * render). v1 slice fields; wider fields (animated, poster, font-specific,
+ * etc.) are added as those capabilities land.
+ *
+ * `version: 1` is the forward-compatibility lever for future changes.
+ *
+ * Deviation from design-media.md:
+ *   The design specifies a `variantsStatus: 'generating' | 'complete' | 'failed'`
+ *   tri-state alongside `variants`. We don't carry it in v1 because ingest
+ *   is synchronous + rolls back on variant-generation failure — when a
+ *   manifest exists, variants are always complete by invariant, so the
+ *   status field would be dead weight. If we ever move to async generation
+ *   (a separate step), the tri-state comes back and callers distinguish
+ *   "variants still generating" from "variants failed" the design-doc way.
+ */
+export interface AssetManifest {
+    version: 1;
+    /** Asset name (matches the library key and the reference `_asset`). */
+    name: string;
+    /** Rendering role — determines how templates use this asset. */
+    kind: AssetKind;
+    /** Whether bytes live on target (`internal`) or elsewhere. v1 slice: internal only. */
+    source: 'internal';
+    /** Canonical MIME type (sniffed from bytes at upload). */
+    mime: string;
+    /** Size in bytes of the default representation. */
+    size: number;
+    /** 8-char SHA-256 prefix of default bytes. Matches the on-disk filename suffix. */
+    hash: string;
+    /** Width in pixels (images) — null when not applicable. */
+    width: number | null;
+    /** Height in pixels (images) — null when not applicable. */
+    height: number | null;
+    /**
+     * Responsive-image variants, pre-generated at upload time. Empty for
+     * non-image assets (downloadable, font) or images smaller than the
+     * smallest target width (no point upscaling). Ordered ascending by width.
+     */
+    variants: readonly AssetVariant[];
+    /** Alt text per the three-state model; null means "not set". */
+    alt: string | null;
+    /**
+     * Focal point in normalized coordinates (0–1). Used by templates that
+     * crop the image to non-original aspect ratios — keeps the subject in
+     * frame. Optional: omitted = no preference set, treated as center
+     * (0.5, 0.5) by the resolver; explicit value = author's choice.
+     *
+     * Per-reference focal-point overrides live on the embedded ref in
+     * page/fragment manifests; this is the asset-level default for refs
+     * that don't override.
+     */
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Multi-frame indicator for animated images (GIF, APNG, animated WebP,
+     * animated AVIF). True when the source has > 1 frame; false / absent
+     * for static images. Resolver passes through to `ResolvedEmbeddedAsset.animated`.
+     */
+    animated?: boolean;
+    /** Frame count for animated content. Absent for static. */
+    frames?: number;
+    /**
+     * Duration in milliseconds for time-based content (animated images,
+     * future video, future audio). Null when the format technically
+     * supports it but the duration couldn't be derived; absent for
+     * static images.
+     */
+    duration?: number | null;
+    /**
+     * First-frame poster path (relative to assetsRoot) for animated
+     * content. Templates can render this for reduced-motion fallbacks
+     * or as a lazy-load placeholder. Absent for static; null when
+     * extraction failed despite the source being animated.
+     */
+    poster?: string | null;
+    /** Upload timestamp (ISO 8601 UTC). */
+    uploadedAt: string;
+    /** Author who uploaded; empty string when RBAC isn't configured. */
+    uploadedBy: string;
+}
+/**
+ * Per-kind manifest aliases. Today they all point at `AssetManifest` because
+ * no kind-specific fields exist yet — fonts, downloadables, and embedded
+ * images share the same shape. When kind-specific fields land (font's
+ * `cssName`/`format`/`weight`, downloadable's `title`/`description`), these
+ * aliases become genuinely distinct types and the union below ties them
+ * together. Authors writing schema helpers can already type-import the
+ * alias they need without churn at that point.
+ */
+export type EmbeddedAssetManifest = AssetManifest;
+export type DownloadableAssetManifest = AssetManifest;
+export type FontAssetManifest = AssetManifest;
+/**
+ * Locale-override manifest for embedded/downloadable assets — every field
+ * except identity (`version`, `name`) is optional. Authors create these via
+ * locale-bytes upload (per design-media.md → locale-specific bytes) or by
+ * editing alt/focal/etc. metadata for one locale.
+ *
+ * Two byte-presence states, enforced by the discriminated union:
+ *
+ *   1. Metadata-only override — no `hash`. Locale uses default bytes;
+ *      only metadata fields (alt, focalPoint) override.
+ *   2. Bytes override — `hash` set. Locale has its own bytes; `size`,
+ *      `mime`, `width`/`height`, `variants` MUST be present.
+ *
+ * `kind` and `source` are never overridable on a locale variant — those
+ * are identity attributes of the asset.
+ *
+ * Font locale variants have a different shape (always have bytes, never
+ * "override" — they ADD to a variant union). See `FontLocaleAdditiveManifest`.
+ */
+export type LocaleOverrideManifest = LocaleMetadataOverrideManifest | LocaleBytesOverrideManifest;
+/** Locale metadata-only override — no `hash`, no byte-describing fields. */
+export interface LocaleMetadataOverrideManifest {
+    version: 1;
+    name: string;
+    /** Discriminator: bytes are absent. */
+    hash?: undefined;
+    size?: undefined;
+    variants?: undefined;
+    width?: undefined;
+    height?: undefined;
+    mime?: undefined;
+    /** Optional alt override. Falls back to default's alt. */
+    alt?: string | null;
+    /**
+     * Optional focal-point override at the manifest level (per-asset default
+     * for this locale). Per-reference focal-point overrides live on the
+     * embedded ref, not here — see design-media.md.
+     */
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Optional title override (downloadable kind). */
+    title?: string;
+    /** Optional description override (downloadable kind). */
+    description?: string;
+}
+/** Locale bytes override — `hash` set; byte-describing fields all required. */
+export interface LocaleBytesOverrideManifest {
+    version: 1;
+    name: string;
+    /** 8-char SHA-256 prefix of THIS locale's bytes. */
+    hash: string;
+    /** Size in bytes of THIS locale's primary bytes. */
+    size: number;
+    /** MIME of THIS locale's bytes (may differ from default — e.g. webp override of jpeg default). */
+    mime: string;
+    /** Width in pixels of THIS locale's bytes. Null when not applicable. */
+    width: number | null;
+    /** Height in pixels of THIS locale's bytes. Null when not applicable. */
+    height: number | null;
+    /** Variant ladder for THIS locale's bytes. Empty when below smallest target width. */
+    variants: readonly AssetVariant[];
+    /** Optional metadata overrides — same as the metadata-only variant. */
+    alt?: string | null;
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    title?: string;
+    description?: string;
+}
+/**
+ * Font locale-additive manifest — contributes a variant to the resolved
+ * font's `@font-face` union. Distinct shape from `LocaleOverrideManifest`
+ * because font locale variants:
+ *   - ALWAYS have bytes (a font with no bytes is meaningless)
+ *   - NEVER override default metadata; they add a variant alongside the default
+ *   - carry font-specific fields (format, weight, style, optional unicodeRange)
+ *
+ * Browser picks the right variant per character via `unicode-range`.
+ */
+export interface FontLocaleAdditiveManifest {
+    version: 1;
+    name: string;
+    /** 8-char SHA-256 prefix of THIS variant's bytes. */
+    hash: string;
+    /** Size in bytes of THIS variant's bytes. */
+    size: number;
+    /** MIME of THIS variant's bytes. */
+    mime: string;
+    /** Font format the bytes are encoded in. */
+    format: 'woff2' | 'woff' | 'ttf' | 'otf';
+    /** Font weight — number or 'variable' for variable-axis fonts. */
+    weight: number | 'variable';
+    /** Font style. */
+    style: 'normal' | 'italic';
+    /**
+     * Unicode range covered by this variant. Browser uses it to pick the
+     * right variant per character. Null = no range restriction (variant
+     * applies to all characters).
+     */
+    unicodeRange: string | null;
+}
+/**
+ * Library-list summary — the compact projection of `AssetManifest` that
+ * the library UI displays. Deliberately smaller than the full manifest:
+ * `uploadedBy` is excluded (RBAC / audit concern, not UI concern), and
+ * future manifest fields (variants, animated flag, etc.) are only added
+ * here when the UI genuinely needs them.
+ */
+export interface AssetSummary {
+    name: string;
+    kind: AssetKind;
+    mime: string;
+    size: number;
+    hash: string;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    /** Focal point in normalized coordinates (0–1). Absent = no preference. */
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Multi-frame indicator. Absent for static images. */
+    animated?: boolean;
+    /** First-frame poster path for animated content. Absent for static. */
+    poster?: string | null;
+    uploadedAt: string;
+    /**
+     * Locales for which this asset has a manifest override (with or
+     * without bytes). Empty array means no locale variants. Detected
+     * from sibling `{name}.asset.{locale}.json` files in the same
+     * directory listing — no extra I/O.
+     *
+     * Drives the library card coverage badge (`[en✓ fr✓ ar—]`) and
+     * informs the upload dialog's default-vs-override prompt.
+     */
+    overrideLocales: readonly string[];
+    /**
+     * Themes for which this asset has a manifest override. Same shape
+     * and source as `overrideLocales`. Empty when the site has no theme
+     * dimension or no theme overrides exist.
+     */
+    overrideThemes: readonly string[];
+}
+/** Embedded asset after the resolver merges manifest + per-ref overrides. */
+export interface ResolvedEmbeddedAsset {
+    /** Absolute or root-relative URL. */
+    url: string;
+    /** Responsive `srcset` string; null for external, SVG, animated, or when variants aren't generated. */
+    srcset: string | null;
+    width: number | null;
+    height: number | null;
+    /** Duration in ms — video, audio, or animated image. Null otherwise. */
+    duration: number | null;
+    /** True for GIF, APNG, animated WebP, animated AVIF. */
+    animated: boolean;
+    /** First-frame URL for animated content; null for static. */
+    poster: string | null;
+    /** Alt text — always a string. Empty string (`""`) means "intentionally decorative". */
+    alt: string;
+    /** Normalized 0–1 focal point; null when not set. */
+    focalPoint: {
+        x: number;
+        y: number;
+    } | null;
+    mime: string;
+}
+/** Downloadable asset after the resolver merges manifest + per-ref overrides. */
+export interface ResolvedDownloadableAsset {
+    url: string;
+    title: string;
+    description: string | null;
+    size: number | null;
+    mime: string;
+}
+/** Font asset — a union of locale variants, each rendered as a `@font-face` declaration. */
+export interface ResolvedFontAsset {
+    /**
+     * Gazetta-stable CSS font-family name. Templates reference this in their
+     * `font-family` declarations. NOT the font file's intrinsic family name —
+     * Gazetta owns this identifier so multi-script fonts (e.g. Inter for Latin
+     * + Noto Sans Arabic for Arabic) can share one logical family from the
+     * template's perspective.
+     */
+    cssName: string;
+    variants: Array<{
+        url: string;
+        format: 'woff2' | 'woff' | 'ttf' | 'otf';
+        weight: number | 'variable';
+        style: 'normal' | 'italic';
+        /** Unicode range for multi-script fallback. Null means "no range restriction". */
+        unicodeRange: string | null;
+        mime: string;
+    }>;
+}
+import type { $brand } from 'zod/v4/core';
+/** True when `T` carries the `embedded` brand. */
+export type HasEmbeddedBrand<T> = T extends $brand<'embedded'> ? true : false;
+/** True when `T` carries the `downloadable` brand. */
+export type HasDownloadableBrand<T> = T extends $brand<'downloadable'> ? true : false;
+/** True when `T` carries the `font` brand. */
+export type HasFontBrand<T> = T extends $brand<'font'> ? true : false;
+/**
+ * Walks a content type `T` (typically `z.infer<typeof schema>`) and swaps every
+ * asset reference type for its resolved counterpart.
+ *
+ * Mapping rules:
+ * - branded `embedded` → `ResolvedEmbeddedAsset`
+ * - branded `downloadable` → `ResolvedDownloadableAsset`
+ * - branded `font` → `ResolvedFontAsset`
+ * - Array: `Content<T[]>` (recurse into element type)
+ * - Object: recurse into each property, preserving optionality
+ * - Primitive: unchanged
+ *
+ * Depends only on Zod's `$brand` symbol and the resolved types above. If Zod
+ * v5 changes brand representation, update only the `Has*Brand` predicates;
+ * the mapper body stays the same.
+ */
+export type Content<T> = HasEmbeddedBrand<T> extends true ? ResolvedEmbeddedAsset : HasDownloadableBrand<T> extends true ? ResolvedDownloadableAsset : HasFontBrand<T> extends true ? ResolvedFontAsset : T extends ReadonlyArray<infer U> ? ReadonlyArray<Content<U>> : T extends object ? {
+    [K in keyof T]: Content<T[K]>;
+} : T;
+//# sourceMappingURL=types.d.ts.map

package/dist/schema/types.d.ts.map

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

package/dist/schema/types.js

@@ -0,0 +1,25 @@
+/**
+ * Asset schema — reference and resolved type spaces, and the `Content<T>`
+ * utility that walks a Zod-inferred content type and swaps reference types
+ * for resolved types.
+ *
+ * Two distinct type spaces:
+ * - **Reference shapes** — what's stored in page/fragment content JSON. The
+ *   authoring model: "this content field points to asset X with this optional
+ *   override." Small, stable.
+ * - **Resolved shapes** — what templates receive at render time after the
+ *   resolver merges manifest + reference overrides. Large, evolves as
+ *   templates gain capabilities.
+ *
+ * Brands distinguish reference types from plain objects. `Content<T>` reads
+ * the brand to perform the swap. Brands are phantom — attached at the type
+ * level via `z.brand(...)` in `helpers.ts`, invisible at runtime.
+ *
+ * Branding is split across the two modules by role:
+ * - `types.ts` (this file) owns the `Resolved*Asset` shapes and the
+ *   `Content<T>` mapper that consumes brands.
+ * - `helpers.ts` owns the `embeddedAsset()` / `downloadable()` / `fontAsset()`
+ *   Zod schemas that attach brands to their inferred output.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/schema/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/selector-chain.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Cross-dimension fallback chain resolution.
+ *
+ * Produces an ordered list of `Selector`s to try, given the active locale
+ * + theme and the site's resolved locale + theme configuration. The list
+ * is in **most-specific-first** order — callers walk it and apply each
+ * variant's overrides on top of the previous (per-field cascade), with the
+ * default manifest always read separately as the base.
+ *
+ * # Locale-priority ordering (locked)
+ *
+ * For active `(fr, dark)` with site default `(en, light)`:
+ *
+ *   1. (fr, dark)             — most specific
+ *   2. (fr, light)            — locale match, default theme
+ *   3. (default-locale, dark) — only theme match
+ *   4. (default-locale, light) [the default manifest, read separately]
+ *
+ * Locale matches first, then theme. Documented in design-media.md and
+ * locked during foundation grilling — language matters more for
+ * comprehension than visual presentation, so when content has to fall
+ * back, it falls back along the theme axis before the locale axis.
+ *
+ * # Default exclusion
+ *
+ * The chain never includes the all-default selector (no locale, no theme
+ * overrides). That's the base manifest, always read separately. Including
+ * it would make every walker double-read the default.
+ *
+ * Selectors with `theme = default-theme` are also excluded when the
+ * default manifest already covers that theme — they would just be
+ * duplicate reads. The chain only carries selectors whose stored manifest
+ * could plausibly differ from the default.
+ *
+ * # Single-dimension sites
+ *
+ * - Site has no themes config → chain has only locale selectors.
+ * - Site has themes but no locales → chain has only theme selectors.
+ * - Site has both → cross-product, locale-priority.
+ *
+ * Single responsibility: combine config + active selector → ordered chain.
+ * No I/O, no manifest reads, no asset knowledge.
+ */
+import type { ResolvedLocales } from './locale.js';
+import { type Selector } from './schema/dimensions.js';
+import type { ResolvedThemes } from './themes.js';
+export interface CrossDimensionInput {
+    /** Active locale, if set. When unset, locale dimension contributes nothing. */
+    locale?: string;
+    /** Active theme, if set. When unset, theme dimension contributes nothing. */
+    theme?: string;
+    /** Resolved site locales — null when site is single-locale. */
+    locales: ResolvedLocales | null;
+    /** Resolved site themes — null when site has no theme dimension. */
+    themes: ResolvedThemes | null;
+}
+/**
+ * Build the most-specific-first list of selectors to read for cross-dimension
+ * fallback. Excludes the all-default selector (caller reads default manifest
+ * separately as the base).
+ */
+export declare function crossDimensionFallbackChain(input: CrossDimensionInput): readonly Selector[];
+//# sourceMappingURL=selector-chain.d.ts.map

package/dist/selector-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector-chain.d.ts","sourceRoot":"","sources":["../src/selector-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+DAA+D;IAC/D,OAAO,EAAE,eAAe,GAAG,IAAI,CAAA;IAC/B,oEAAoE;IACpE,MAAM,EAAE,cAAc,GAAG,IAAI,CAAA;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,QAAQ,EAAE,CAkB3F"}

package/dist/selector-chain.js

@@ -0,0 +1,58 @@
+import { localeFallbackChain } from './locale.js';
+import { buildSelector } from './schema/dimensions.js';
+/**
+ * Build the most-specific-first list of selectors to read for cross-dimension
+ * fallback. Excludes the all-default selector (caller reads default manifest
+ * separately as the base).
+ */
+export function crossDimensionFallbackChain(input) {
+    const localeAxis = buildLocaleAxis(input);
+    const themeAxis = buildThemeAxis(input);
+    const result = [];
+    // Locale-priority: outer loop is locale (active first, then locale-fallbacks),
+    // inner loop is theme (active first, then default-theme).
+    for (const locale of localeAxis) {
+        for (const theme of themeAxis) {
+            const selector = buildSelector({
+                ...(locale !== null ? { locale } : {}),
+                ...(theme !== null ? { theme } : {}),
+            });
+            if (selector === null)
+                continue; // all-defaults, excluded
+            result.push(selector);
+        }
+    }
+    return result;
+}
+/**
+ * Locale axis values to try, in order. `null` means "no locale dimension"
+ * (default-locale, treated as identity on this axis).
+ *
+ * - When `locale` is unset OR equals default → `[null]` (no locale variants to try)
+ * - When `locale` is non-default → `[active, ...fallbacks, null]`
+ *   (try active locale, then configured fallbacks, then drop the locale dimension)
+ */
+function buildLocaleAxis(input) {
+    if (!input.locale || !input.locales)
+        return [null];
+    if (input.locale === input.locales.default)
+        return [null];
+    const chain = localeFallbackChain(input.locale, input.locales);
+    return [...chain, null];
+}
+/**
+ * Theme axis values to try, in order. `null` means "no theme dimension"
+ * (default-theme, treated as identity on this axis).
+ *
+ * - When `theme` is unset OR equals default → `[null]`
+ * - When `theme` is non-default → `[active, null]`
+ *   (try active theme, then drop the theme dimension)
+ */
+function buildThemeAxis(input) {
+    if (!input.theme || !input.themes)
+        return [null];
+    if (input.theme === input.themes.default)
+        return [null];
+    return [input.theme, null];
+}
+//# sourceMappingURL=selector-chain.js.map

package/dist/selector-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector-chain.js","sourceRoot":"","sources":["../src/selector-chain.ts"],"names":[],"mappings":"AA4CA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,aAAa,EAAiB,MAAM,wBAAwB,CAAA;AAcrE;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAA0B;IACpE,MAAM,UAAU,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;IACzC,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IAEvC,MAAM,MAAM,GAAe,EAAE,CAAA;IAC7B,+EAA+E;IAC/E,0DAA0D;IAC1D,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;YAC9B,MAAM,QAAQ,GAAG,aAAa,CAAC;gBAC7B,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtC,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACrC,CAAC,CAAA;YACF,IAAI,QAAQ,KAAK,IAAI;gBAAE,SAAQ,CAAC,yBAAyB;YACzD,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACvB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,KAA0B;IACjD,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACzD,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9D,OAAO,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,KAA0B;IAChD,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAChD,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;AAC5B,CAAC"}

package/dist/seo.d.ts

@@ -0,0 +1,56 @@
+/**
+ * SEO tag resolution — computes `<head>` tags from a fallback chain:
+ *   metadata field → content field → site default → omit
+ *
+ * Single responsibility: this module owns the fallback logic and HTML
+ * tag generation for SEO. The renderer calls `resolveSeoTags()` and
+ * injects the result into `<head>` — it doesn't know about title
+ * truncation, OG deduplication, or robots directives.
+ *
+ * Open for extension: adding a new tag type is a new block in
+ * `resolveSeoTags()`, not a change to the renderer.
+ */
+import type { PageMetadata } from './types.js';
+/** Escape HTML attribute values — prevents XSS in generated meta tags. */
+export declare function escapeAttr(s: string): string;
+/**
+ * SEO context for a rendering pass — assembled by the caller from
+ * whatever sources it has (site manifest, target config, etc.).
+ * The renderer and seo module depend on this interface only, not
+ * on SiteManifest or TargetConfig (DIP).
+ */
+export interface SeoContext {
+    /** Site name — appended to auto-generated titles ("Page — Site Name"). */
+    siteName?: string;
+    /** Target's public URL for canonical/og:url (e.g. "https://gazetta.studio"). */
+    siteUrl?: string;
+    /** Site locale for `<html lang>` (e.g. "en", "fr"). Default: "en". */
+    locale?: string;
+    /** Default OG image for pages that don't specify their own. */
+    defaultOgImage?: string;
+    /**
+     * Locale alternates for hreflang — maps locale code to absolute URL.
+     * Only set for subpath targets (same domain, all locales).
+     * Cross-domain hreflang is handled via sitemap, not HTML tags.
+     * Example: { en: "https://example.com/about", fr: "https://example.com/fr/about" }
+     */
+    hreflangAlternates?: Record<string, string>;
+    /** The default locale code — used for x-default hreflang. */
+    defaultLocale?: string;
+}
+export interface ResolveSeoTagsInput {
+    metadata?: PageMetadata;
+    content?: Record<string, unknown>;
+    route?: string;
+    seo: SeoContext;
+    /** Template-provided head HTML — tags already present won't be duplicated. */
+    templateHead?: string;
+}
+/**
+ * Resolve all SEO `<head>` tags using the fallback chain. Returns raw
+ * HTML string for injection. Template-provided tags are checked for
+ * duplicates — a metadata tag is only emitted when the template head
+ * doesn't already include it.
+ */
+export declare function resolveSeoTags(input: ResolveSeoTagsInput): string;
+//# sourceMappingURL=seo.d.ts.map

package/dist/seo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.d.ts","sourceRoot":"","sources":["../src/seo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,UAAU,CAAA;IACf,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAyEjE"}