@oim-media/spec 0.0.0-stage → 1.27.9

package/BINARY_SPEC.md

@@ -0,0 +1,190 @@
+# OIM (Object Interactive Media) Container Binary Specification
+
+**Version:** 1.0  
+**Date:** 2026-09-22  
+**Status:** Normative / In force  
+**Authors:** OIM Architecture Team
+
+---
+
+## 1. Summary and Objectives
+
+A **`.oim`** (or **`.oim.png`**) file is an enriched, interactive and verifiable multimedia document carried inside an image file that conforms to the standard **ISO/IEC 15948:2004 (PNG)** specification.
+
+The objectives of this binary design are:
+1. **Universal compatibility (visual fallback):** Any image viewer, browser or client without OIM support can decode and render the file as a standard, high-fidelity static PNG image.
+2. **Zero network dependency (self-contained):** The document encapsulates all of its vector geometry, multilingual texts, animations, typefaces and interactive metadata within the image itself.
+3. **Cryptographic integrity and ECDSA signature (zero-trust):** The file embeds an asymmetric digital signature that indelibly binds the interactive metadata to the rendered pixels (`IDAT` chunks), preventing substitution or manipulation of the canvas or its layers.
+
+---
+
+## 2. Anatomy of the PNG Binary Container
+
+Every OIM file begins strictly with the canonical 8-byte PNG signature:
+
+```binary
+89 50 4E 47 0D 0A 1A 0A  (\x89PNG\r\n\x1a\n)
+```
+
+### 2.1. PNG Chunk Structure
+
+Each chunk in the PNG file follows the standard 4-field layout:
+
+| Field | Length | Description |
+|---|---|---|
+| **Length** | 4 bytes (Big-Endian) | Length of the `Data` field (excludes `Type` and `CRC`). |
+| **Type** | 4 bytes (ASCII) | Four-character identifier (e.g. `IHDR`, `tEXt`, `IDAT`, `IEND`). |
+| **Data** | *Length* bytes | Chunk payload. |
+| **CRC-32** | 4 bytes (Big-Endian) | CRC-32 checksum computed over `Type` + `Data`. |
+
+### 2.2. Placement and Injection of OIM Metadata
+
+OIM metadata is preferably stored in an ancillary text chunk:
+
+- **Chunk type:** `zTXt` (written since 29 Oct 2026). Readers also accept `tEXt` (earlier files) and `iTXt`.
+- **Chunk keyword:** `OIM_Data` (historically `OIM_JSON_DATA` was also recognised).
+- **Location in the file:**
+  - **AFTER** `IHDR` (and any palette/colour header chunks, if present).
+  - **BEFORE** or **AFTER** the image `IDAT` chunks.
+  - **ALWAYS BEFORE** the closing `IEND` chunk.
+
+> **Critical note on injection:** The metadata chunk must be inserted **surgically at byte level** into the PNG binary stream, without re-rendering or re-encoding the `IDAT` blocks, preserving the exact cryptographic hash of the canvas.
+
+---
+
+## 3. Encoding and Compression of the Payload
+
+The payload of the `zTXt` chunk has the following structure:
+
+```
+[ Keyword: "OIM_Data" ] + [ Null Separator: 0x00 ] + [ Method: 0x00 ] + [ zlib(JSON), binary ]
+```
+
+No Base64: measured on 29 Oct 2026, the file is 12–23 % smaller than with the
+earlier `tEXt` form (`"OIM_Data\0"` + Base64 of raw Deflate), which readers
+still accept.
+
+### 3.1. Packaging Flow (Serializer)
+
+1. The OIM metadata object (conforming to `OimMetadataSchema`) is serialised to a JSON string encoded in **UTF-8**.
+2. The UTF-8 string is compressed with **zlib** (RFC 1950: 2-byte header, DEFLATE, Adler-32), level 9.
+3. The `zTXt` chunk is assembled:
+   - `Length`: `8` (keyword) + `1` (null byte) + `1` (method) + `len(zlib)`
+   - `Type`: `7A 54 58 74` (`zTXt`)
+   - `Data`: `"OIM_Data\0\0"` + `<zlib_bytes>`
+   - `CRC-32`: computed over `Type` and `Data`.
+
+### 3.2. Extraction and Decompression Flow (Reader)
+
+A `zTXt` is read by skipping the NUL and the method byte and decompressing with
+zlib. For the earlier `tEXt` form, a conforming decoder must process the payload
+with the following fault tolerance:
+1. Extract the value of the chunk after the `0x00` delimiter.
+2. Decode the Base64 string into binary bytes.
+3. If the decoded plain text already starts with `{` (uncompressed JSON from debugging/draft), process it directly with `JSON.parse`.
+4. If it contains compressed binary data:
+   - Try to decompress with **Zlib Deflate** (`new DecompressionStream('deflate')` or `zlib.inflateSync`).
+   - If that fails, try to decompress with **Raw Deflate** (`new DecompressionStream('deflate-raw')` or `zlib.inflateRawSync`).
+5. Decode the resulting bytes with `TextDecoder("utf-8")` and parse the JSON.
+
+---
+
+## 4. The Image Integrity Seal (`image_hash`)
+
+To guarantee that a set of valid, signed interactive metadata cannot be cut out and pasted onto an arbitrary image (canvas-transplant attack), the format implements an image seal over the IDAT stream:
+
+### 4.1. Calculation Algorithm
+
+```
+image_hash = SHA256( IDAT_payload_1 || IDAT_payload_2 || ... || IDAT_payload_n )
+```
+
+- All chunks with the exact type `IDAT` are traversed, in the strict order in which they appear in the PNG container.
+- Only the payload of each chunk is extracted (`Data`, discarding the 4 length bytes, the 4 `IDAT` type bytes and the 4 CRC bytes).
+- All the bytes of the compressed raw image data are concatenated.
+- The **SHA-256** digest is computed and expressed in **lowercase hexadecimal** (64 characters).
+
+### 4.2. Metadata Fields
+- `image_hash`: Resulting SHA-256 hexadecimal string.
+- `image_hash_alg`: Literal `"sha256-idat"`.
+
+---
+
+## 5. ECDSA P-256 Cryptographic Signature Specification
+
+A signed `.oim` file guarantees the authorship, integrity and non-repudiation of the design.
+
+- **Cryptosystem:** ECDSA over the **NIST P-256** elliptic curve (secp256r1 / prime256v1).
+- **Hash function:** SHA-256.
+- **Signature format:** raw IEEE P1363 (`r || s`, 32 bytes for $r$ + 32 bytes for $s$ = exactly **64 binary bytes**).
+- **JSON serialisation:** Base64 of the 64 binary bytes in the `signature` property. *(No ASN.1/DER encoding is used.)*
+
+### 5.1. Canonical Serialisation Rules (OIM profile)
+
+So that any implementation in any language (TypeScript, Python, Rust, Go, Swift) verifies the signature identically, without a single byte of discrepancy, the payload to be signed or verified is built by strictly following these **7 rules**.
+
+This is OIM's own profile, **not RFC 8785 (JCS)**: rule 3 rounds numbers and rule 4 orders keys by code point, where JCS keeps the number and orders by UTF-16 code unit. A stock JCS library does not produce these bytes. [`canonical-cases.json`](canonical-cases.json) is a known-answer case every implementation in this repository is tested against.
+
+
+1. **Base object:** Take the decoded OIM metadata dictionary.
+2. **Root exclusions:** Exclude from the root only the fields:
+   - `signature`
+   - `key_version`
+   - `timestamp`
+   - `creator_user_id` *(excluded for privacy, GDPR / zero-knowledge)*.  
+   *(Note: if any of these keys exist in nested objects or styles, they are not removed.)*
+3. **Numeric normalisation:**
+   - If a decimal number has an exact integer value (e.g. `2.0` or `-0.0`), it is formatted as an integer (`2`, `0`).
+   - Floating-point numbers are formatted to a maximum of **6 decimal places** with standard symmetric rounding.
+   - **Range:** every number in the metadata, at any depth, must be finite and no larger in magnitude than **2^53 − 1** (`9007199254740991`). Beyond that, JSON parsers disagree on the value they read, so the number has no canonical form: a signer must refuse the metadata and a verifier must report the signature as invalid.
+4. **Lexical key ordering:** All object keys (at the root and recursively at every level and inside arrays) are sorted by ascending Unicode code point.
+5. **Compact serialisation:** No whitespace between keys, colons or commas: `{"a":1,"b":"dos"}`.
+6. **UTF-8 preservation:** Do not escape non-ASCII Unicode characters with `\uXXXX` sequences. They are emitted directly as native UTF-8 (e.g. `"Zürich"` instead of `"Z\u00fcrich"`).
+7. **Digest:** The resulting bytes encoded in UTF-8 are passed directly to the SHA-256 + ECDSA P-256 verification/signing function.
+
+---
+
+## 6. Embedded Font Handling (`fonts`)
+
+Since version 1.3.0, the `.oim` format is self-contained and makes no calls to third-party CDNs to render typefaces:
+
+- **Structure of the `fonts` array at the root:**
+  ```json
+  [
+    {
+      "family": "Bricolage Grotesque",
+      "name": "oim-a9f81-BricolageGrotesque",
+      "weight": 700,
+      "style": "normal",
+      "format": "woff2",
+      "data": "<base64_string_of_the_subsetted_woff2_binary>"
+    }
+  ]
+  ```
+- **Strict subsetting:** The embedded WOFF2 binaries must be subsetted only to the glyphs present in the project's texts, to minimise the total weight of the PNG (typically 4 KB to 18 KB per variant).
+- **Registration in the reader:**
+  1. Decode `data` from Base64.
+  2. Register the font via `FontFace` (in browsers) or register it in the native system's font engine under the unique identifier `name`.
+  3. Bind the slots that refer to `family` to the resolved variant.
+
+---
+
+## 7. Summary Table of Fields and Compatibility
+
+| Feature | Chunks / Key | Format | Mandatory |
+|---|---|---|---|
+| **Base image** | `IDAT` | Standard compressed PNG | Yes |
+| **OIM metadata** | `zTXt` (`OIM_Data`) | zlib(JSON), binary | Yes |
+| **IDAT seal** | `image_hash` | SHA-256 hex | Yes (since v1.2) |
+| **Digital signature** | `signature` | Base64(ECDSA P1363 64B) | Optional in drafts, required in published files |
+| **Key version** | `key_version` | String (e.g. `"v1"`) | Required if signed |
+| **Signing date** | `signed_at` | ISO-8601 UTC | Required if signed |
+| **Typefaces** | `fonts` | Array with WOFF2 Base64 | Recommended |
+| **Named palettes** (1.20.0) | `palettes`, `defaultPalette` | Object name → (role → CSS colour); string | Optional |
+
+### Named palettes (1.20.0)
+
+`palettes` and `defaultPalette` are optional at the root of the document. The
+rules for names, roles, the limit of six palettes and the resolution order are
+in `README.md` (section "Named palettes"). A reader that does not know them
+ignores both keys and paints each layer's fixed colours.

package/CANONICAL_SPEC.md

@@ -0,0 +1,409 @@
+# OIM (Object Interactive Media) Canonical Metadata Specification
+
+**Contract version:** 1.27.9  
+**Date:** 2026-11-02 (reviewed against `packages/core/src/schema.ts`; the source of truth is the schema, this document summarises it)  
+**Status:** Normative / In force  
+**License:** Apache-2.0  
+**Authority:** Xue Studios LLC & the OIM Architecture Team
+
+---
+
+## 1. Summary and Objectives of the Canonical Specification
+
+The **`.oim`** format defines a multi-platform interactive image specification. The metadata layer (historically called `oimdata` or `oimdata.json`, injected into the `OIM_Data` chunk of the PNG container) uses a **strongly typed, serialisable canonical language**.
+
+> **Note on OVM (`.ovm`):** The interactive video format (`ovm.schema.json` and `@oim-media/player-ovm`) is currently a **reserved placeholder pending specification**. The normative specification below governs **OIM (`.oim`)**.
+
+### Canonical Design Principles
+
+1. **Total independence from web engines (native platforms):**
+   - The format **prohibits free or arbitrary CSS** (`custom_loop_css`, `custom_keyframes`, free style strings).
+   - Every visual or dynamic attribute is parameterised in canonical types (numbers, enums, tuples or arrays). This allows native implementations on **iOS (SwiftUI / Core Animation)**, **Android (Jetpack Compose / RenderNode)**, **Desktop (Rust / Tauri / Skia)** or Web Components to paint and interact with 1:1 fidelity without requiring an embedded web browser.
+2. **One name per concept (zero ambiguity):**
+   - The compiler canonicalises shortcuts and duplicate names before signing:
+     - `size` ➔ `fontSize`
+     - `font` ➔ `fontFamily`
+     - `color` ➔ `fillColor`
+     - `bold: true` ➔ `fontWeight: 700`
+     - `italic: true` ➔ `fontStyle: "italic"`
+     - `underline: true` ➔ `textDecoration: "underline"`
+     - `fontSizeOverrides` ➔ unified inside the `fontSizes` map.
+     - `reedicion` (`"publico" | "solo_autor" | "sellado"`) ➔ `reedit` (`"public" | "author_only" | "sealed"`, 1.23.0; legacy files are normalised on read via `normalizeLegacyKeys`).
+3. **Determinism and security (zero-trust sandbox):**
+   - With no arbitrary CSS injection, attack vectors such as `@import`, covert network requests via `url()`, or breaking out of Shadow DOM isolation are eradicated.
+4. **Portable or not admitted:**
+   - Every visual effect is built from primitives that any graphics engine has cheaply — opacity, translation, scale, rotation and rectangular clipping, per unit (letter, word, line or layer). What exists only in a browser (per-letter blur, animated shadows, free `clip-path`) is not admitted, and what was already there is retired or rewritten into portable primitives (`glitchLayers`, `entranceFrameAt`, `revealFrames`).
+
+---
+
+## 2. Canonical Layer Types (`slot.type`)
+
+Every interactive element in the `slots` array declares a canonical type:
+
+| Type (`type`) | Purpose | Canonical Characteristics |
+|---|---|---|
+| `text` | Dynamic multilingual text | Supports localised `content`, sizes per language (`fontSizes`), widths per language (`maxWidths`), text marks (`marks`) and precalculated lines (`textRuns`). |
+| `image` | Secondary or embedded bitmap | Embedded `data:image/*` URI in `content`, framing (`objectFit`, `imageCrop`), mirroring (`flipX`, `flipY`), filters and accessible `alt`/`decorative`. |
+| `lottie` | Lottie vector animation | Embedded vector JSON. |
+| `geo` / `shape` | Pure vector geometry or photo frame | Governed by `style.geoShape` (24 catalog shapes including 12 photo-frame silhouettes), custom `svgPath`/`svgViewBox`, or `fillType: "image"` (`fillImage`, `fillImageCrop`, `fillImageFlipX`, `fillImageFlipY`). |
+| `draw` / `svg` | Free vector strokes | Supports standard SVG paths (`svgRawXml`, `svgPath`, `svgViewBox`, `customBlobPath`). |
+| `artistic-text` | 3D text with parametric extrusion | Vector extrusion (`extrusionDepth`, `extrusionAngle`, `curveAmount`, `curveType`). |
+| `pattern` | Repeating procedural pattern | Canonical presets (`clouds`, `bubbles`, `grid`, `waves`, `stars`, `stripes`, `dots`, `zigzags`, `bolt`, `leaf`, `drop`, `moon`, `crown`, `heart`). |
+| `filter` | Colour adjustment / optical filter layer | Named presets (`filterPreset`) and normalised numeric adjustments (`filterBrightness`, `filterContrast`, `filterSaturate`, `filterHueRotate`, `filterBlur`). |
+| `container` | Bounding box or frame | Supports geometry, fills, borders, shadows and clipping. |
+| `group` | Hierarchical container node | Groups child layers via `style.groupId`. Controls clipping (`slotClipping`) and scene loops (`style.sceneLoop`). |
+| `component` | Composite component instance | Encapsulated grouping of modular design. |
+| `mask` | Clipping or die-cut mask | Clipping by a base shape (`maskShape`, `maskMode`) or multiple vector cutouts (`cuts`). |
+| `zone` | Contextual anchor zone | Delimiter for anchoring slots to relative regions of the image. |
+
+---
+
+## 3. Root Structure of the Slot (`slotSchema`)
+
+```typescript
+interface OimSlot {
+  id: string;                       // Unique identifier (maximum 128 characters)
+  name?: string;                    // Name assigned by the author (max 256 chars)
+  type?: SlotType;                  // One of the canonical types in section 2
+  languages?: string[];             // Languages in which it is shown (default: ["*"])
+  pendingTranslation?: string[];    // Language codes pending translation
+  align?: "left" | "center" | "right";
+  position?: [number, number];      // Normalised coordinates [x, y] (percentage 0.0 to 100.0%)
+  width_px?: number;                // Virtual width in reference pixels
+  height_px?: number;               // Virtual height in reference pixels
+  content?: Record<string, string>; // Language -> content dictionary (e.g. { "en": "Text" })
+  style?: OimStyle;                 // Canonical style object (see section 4)
+  parallax?: OimParallax;           // Parallax configuration (see section 5; may also travel in style.parallax)
+  interaction?: OimInteraction;     // Declared interactions
+  tracking_data?: number[][];       // Tracking keyframes [time, x1..y4, cx, cy]
+  zone_id?: string;                 // ID of the containing zone
+}
+```
+
+---
+
+## 4. Canonical Style Contract (`styleSchema`)
+
+### 4.1. Typography and Text
+- `fontFamily`: String with the font name (max 128 chars).
+- `fontSize`: Pure number or container percentage (e.g. `24` or `"4.5cqw"`).
+- `fontWeight`: Numeric weight (`100` to `900`, `400` = normal, `700` = bold) or string keyword.
+- `fontStyle`: `"normal" | "italic" | "oblique"`.
+- `textDecoration`: `"none" | "underline"` (max 64 chars).
+- `textAlign`: `"left" | "center" | "right" | "justify"`.
+- `lineHeight`: Numeric multiplier factor (e.g. `1.2`, `1.5`) or a bounded string.
+- `letterSpacing`: A CSS length with its unit (`"2px"`, `"0.05em"`). A bare number is not a length: readers ignore it, as the browser does (section 4.8).
+- `maxWidth`: Container percentage string (e.g. `"80cqw"`, `"none"`) or numeric value.
+- `fontSizes`: Map of size specific to each language `{ "es": "3.0cqw", "ja": "2.5cqw" }`.
+- `maxWidths`: Map of maximum width specific to each language `{ "en": "60cqw" }`.
+- `textRole`: Semantic hierarchy hint (`"auto" | "title" | "subtitle" | "body"`).
+- **Text marks (1.11.0, `text_marks` capability):** `content` can wrap phrases in `{name}…{/name}`; literal braces are doubled (`{{`, `}}`). `style.marks` defines each mark with a closed set (`color`/`colorRole`, `bold`, `italic`, `underline`, `highlight{style, color, colorRole, paddingX, paddingY, borderRadius}`). Names `^[a-z][a-z0-9-]{0,23}$`, maximum 8 per layer, not nested. A single interpretation: `parseMarks`, `markStyle` (`@oim-media/core`). The backend does not sign malformed tags (`OIM_E_TEXT_MARKS_INVALID`).
+- `dropCap`: `{ enabled, lines: 2|3, fontFamily?, color?, marginRight? }`. Size is set with `dropCapStyle`; the rest of the text keeps its marks (`splitDropCap`).
+- `textHighlight`: **retired** (1.12.0). Kept read-only for published files; new writers use `marks`.
+- `textRuns`: **Precalculated lines**, only for readers **without** a paragraph layout engine. A reader that can lay out text (web, Flutter) ignores them: the exporter's line breaks can disagree with the real layout (section 4.8):
+  ```json
+  "textRuns": {
+    "es": {
+      "fontSize": 24,
+      "lineHeight": 28,
+      "lines": [
+        { "text": "First line of text", "width": 280, "yOffset": 0 },
+        { "text": "Second line, adjusted", "width": 260, "yOffset": 28 }
+      ]
+    }
+  }
+  ```
+
+### 4.2. Colours, Dynamic Roles and Fills (`cssColor`)
+Colours are validated against the strict `cssColor` pattern (hexadecimal `#RGB` / `#RRGGBB` / `#RRGGBBAA`, functions `rgb()`, `hsl()`, `"transparent"`, `"none"`, or dynamic colour tokens `var(--primary)`):
+- **Dynamic colour roles (`DYNAMIC_COLOR_ROLES`):**
+  `"primary" | "on-primary" | "secondary" | "on-secondary" | "surface" | "on-surface" | "outline" | "accent" | "text-primary" | "text-secondary" | "text-muted" | "text-on-accent"`.
+- `fillColor`: Main fill colour (or glyph colour in text layers).
+- `fillType`: `"none" | "color" | "gradient" | "pattern" | "generative" | "image"`.
+- `colorRole` / `fillColorRole` / `strokeColorRole` / `textStrokeColorRole` / `shadowColorRole` / `effectColorRole` / `maskBgColorRole` / `maskStrokeColorRole`: Semantic dynamic theme roles.
+- **Pattern colour roles (1.21.0):** `fillPatternColorRole`, `fillPatternBgColorRole`, `backgroundPatternColorRole`, `backgroundPatternBgColorRole`.
+- `fillGradient`: Canonical linear, radial or conic gradient function (`CSS_GRADIENT_PATTERN`).
+- `fillPatternType`: Repeating pattern preset:
+  `"clouds" | "bubbles" | "grid" | "waves" | "stars" | "stripes" | "dots" | "zigzags" | "bolt" | "leaf" | "drop" | "moon" | "crown" | "heart"`.
+- **Image fill and photo frames (1.17.0 / 1.19.0, `image_fill` and `frame_shapes` capabilities):**
+  - `fillImage`: Embedded `data:image/*` URI (up to 10 MB).
+  - `fillImageCrop`: `{ x: 0..100, y: 0..100, zoom: 1..10 }`.
+  - `fillImageFlipX` / `fillImageFlipY`: `boolean` (mirrors the photo inside the frame without moving the frame).
+- `fillGenerative`: Algorithmic procedural fill:
+  ```typescript
+  {
+    generatorId: string;           // Identifier of the generative algorithm
+    seed: number;                  // Deterministic seed
+    params: Record<string, number | string | boolean>;
+    colors: {
+      mode: "monochrome" | "palette";
+      stops: string[];             // Array of cssColor colours (max 16)
+      direction: "forward" | "reverse" | "radial";
+      background: string;
+      backgroundVisible: boolean;
+    }
+  }
+  ```
+
+### 4.3. Shapes, Frames, Strokes and Borders
+- `geoShape`:
+  - Base shapes: `"rectangle" | "circle" | "triangle" | "star" | "line" | "arrow" | "diamond" | "hexagon" | "heart" | "blob" | "scribble" | "custom"`.
+  - Frame shapes (1.19.0, `frame_shapes` capability): `"pill" | "octagon" | "pentagon" | "cross" | "moon" | "cloud" | "drop" | "bolt" | "bubble" | "flower" | "burst" | "arch"`.
+- `svgPath`: Validated SVG path data (`^[MmLlHhVvCcSsQqTtAaZz0-9eE.,\s+-]*$`, max 20,000 chars) for custom frames (`1.19.0`).
+- `svgViewBox`: Four-number coordinate box (`^-?\d+(\.\d+)?([\s,]+-?\d+(\.\d+)?){3}$`, max 64 chars).
+- `strokeColor`: Colour of the border or stroke.
+- `strokeWidth`: Stroke thickness in canvas units (minimum 0).
+- `strokeStyle`: `"solid" | "dashed" | "dotted"`.
+- `borderRadius`: Uniform numeric radius or four-value spatial form (e.g. `8` or `"1.0cqw 2.0cqw 0.0cqw 0.5cqw"`).
+
+### 4.4. Transform, Framing, Accessibility and Hierarchy
+- `width` / `height`: Layer dimensions in `cqw` or user units.
+- `rotation`: Rotation in degrees.
+- `flipX` / `flipY` (1.14.0): Mirror the layer on its own horizontal/vertical axes (`flipScale`).
+- `opacity`: Layer opacity (`0` to `100`).
+- `isVisible`: Initial visibility (`boolean`).
+- `groupId`: ID of the parent `group` slot (`slotParent`, `childrenByGroup`).
+- `objectFit`: `"contain" | "cover" | "fill" | "none" | "scale-down"`.
+- `imageCrop` (1.15.0): `{ x: 0..100, y: 0..100, zoom: 1..10 }` (`cropPlacement`, `cropCss`).
+- `alt` (1.16.0): `Record<string, string>` (per-language accessible description, max 300 chars per entry).
+- `decorative` (1.16.0): `boolean` (hides decorative imagery from assistive technology).
+
+### 4.5. Unified Effects, Shadows and Media Filters
+- `effects`: Modular array (`max(8)`) of discriminated effect objects (`oimEffectSchema`):
+  - `texture`: `{ type: "texture", preset, intensity: 0..100, blend, scale?: 0.2..5, color?, colorRole?, enabled? }`.
+  - `drop-shadow`: `{ type: "drop-shadow", x?, y?, blur?: 0..200, spread?, color?, colorRole?, enabled? }`.
+  - `blur`: `{ type: "blur", radius: 0..100, enabled? }`.
+  - `glow`: `{ type: "glow", color?, colorRole?, radius: 0..100, intensity?: 0..100, enabled? }`.
+  - `color-grade`: `{ type: "color-grade", preset: "warm-vintage" | "cool-cinema" | "cyberpunk" | "monochrome-contrast", intensity: 0..100, enabled? }`.
+- `shadowEnabled`, `shadowColor`, `shadowColorRole`, `shadowBlur` (`0..200`), `shadowOffsetX` (`-500..500`), `shadowOffsetY` (`-500..500`), `shadowOpacity` (`0..100`).
+- `layerBlur`: Layer blur (`0..100`).
+- **Media filters (1.18.0, `media_filters` capability):**
+  - `filterPreset`: `"none" | "duotone" | "grayscale" | "sepia" | "high-contrast" | "vintage" | "cool" | "warm" | "faded" | "cinema" | "nordic" | "sunset" | "noir" | "dramatic" | "cyberpunk" | "pastel" | "vhs"`.
+  - `filterBlur` (`0..100`), `filterBrightness` (`0..500`), `filterContrast` (`0..500`), `filterSaturate` (`0..500`), `filterHueRotate` (`0..360`).
+
+### 4.6. Artistic Text and 3D Relief (`artistic-text`)
+- `artisticPreset`: `"neon-cyberpunk" | "retro-wave-3d" | "comic-pop-extrusion" | "vintage-emboss" | "chrome-metallic" | "arcade-80s" | "custom"`.
+- `extrusionDepth`: Geometric extrusion depth (`0` to `100`).
+- `extrusionAngle`: Projection angle in degrees (`0` to `360`).
+- `extrusionColor`: Colour of the extrusion volume.
+- `extrusionShading`: Volumetric facet shading (`boolean`).
+- `curveAmount`: Text curvature (`-100` to `100`).
+- `curveType`: Curvature geometry (`"arc" | "wave" | "arch"`).
+- `outerStrokeColor`, `outerStrokeWidth`, `innerStrokeColor`, `innerStrokeWidth`, `textGradientType`.
+- **Rendering:** the layer is an SVG box of `width_px x height_px` canvas px (else `style.width`/`height`), fitted into the slot (`meet`) without clipping. `fontSize` is canvas px; a `cqw` value is a percentage of the canvas `natural_width`, not of a fixed width. Each line (`
+`) is drawn on its own, `fontSize * lineHeight` apart around the centre. Back to front: the extrusion layers (fill and a stroke of their colour, `outerStrokeWidth` or 1 px), the outer stroke (`outerStrokeWidth * 2`), the inner stroke and then the face. With `curveAmount` the glyphs sit on the curve path, centred on it. Curve path, line offsets and extrusion layers are in `artistic-text-cases.json`.
+
+### 4.7. Animations, Keyframes and Reveal (`animation`, `reveal`)
+- `animation.loop`: Loop preset (`"none" | "pulse" | "float" | "bounce" | "spin" | "glow" | "custom"`).
+- `animation.hover`: Cursor preset (`"none" | "grow" | "shrink" | "lift" | "glow" | "custom"`).
+- `animation.duration`: Duration in seconds (`0.1` to `20`).
+- `animation.delay`: Initial delay in seconds (`0` to `10`).
+- `animation.trigger` (1.22.0): `"load" | "action"` (`"action"` holds the layer at its first keyframe until triggered by a `"play"` state action).
+- `animation.keyframes`: Structured array of keyframes (`keyframeSchema`, `max(240)`):
+  ```typescript
+  interface OimKeyframe {
+    t: number;                      // Time in seconds (0 to 60)
+    o?: number;                     // Opacity (0.0 to 2.0, allows elastic overshoot)
+    s?: number;                     // Scale multiplier (0.0 to 10.0)
+    r?: number;                     // Rotation in degrees (-3600 to 3600)
+    x?: number;                     // X displacement in canvas coordinates
+    y?: number;                     // Y displacement in canvas coordinates
+    b?: number;                     // Blur (0 to 50)
+    e?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "steps(1, end)" | [number, number, number, number];
+  }
+  ```
+- `reveal` (1.22.0): How a layer enters when shown by an action and exits when hidden (`revealSchema`):
+  ```typescript
+  interface OimReveal {
+    effect: "fade" | "slide-up" | "slide-down" | "slide-left" | "slide-right" | "scale";
+    duration: number;               // Duration in ms (0 to 2000)
+    easing?: KeyframeEasing;
+  }
+  ```
+- `textAnimationType`: `"none" | "typewriter" | "wave-chars" | "glitch-cyberpunk" | "glitch-slice" | "fade-chars" | "slide-up" | "bounce-chars" | "reveal-mask" | "scale-in" | "rise-words" | "blur-chars"`, with `textAnimationSpeed` (`0..200`), `textAnimationDelay` (`0..100`), `textAnimationIntensity` (`0..100`) and `typewriterCursor`.
+  - `fade-chars`, `slide-up`, `bounce-chars`, `reveal-mask`, `scale-in` and `rise-words` are entrance effects defined as portable data in `@oim-media/core` (`text-effects.ts`).
+  - `glitch-cyberpunk` and `glitch-slice` are defined as portable layer primitives in `@oim-media/core` (`glitch.ts`).
+  - `blur-chars` is **retired** (not portable): it still validates, and readers draw the text without animation.
+
+### 4.8. Rendering rules for readers
+
+The web player (`@oim-media/player-oim`) is the reference renderer (section 9.1). These are the rules it
+follows that the schema alone does not say. Every reader must follow them; each one has cost a visible
+difference between renderers before it was written down.
+
+**Order and stacking**
+- Layers paint in `slots` order, except the background pattern layer (`is_background_pattern: true`, or
+  id `background-pattern-slot`), which always paints behind every other layer.
+
+**Text**
+- The text box is a column centred vertically (`justify-content: center`). Horizontal alignment is
+  `style.textAlign`, else the slot's `align`, else `left`.
+- The box has a right padding of `0.25em` and is anchored by its padded width: left-aligned text does not
+  move, centred text moves `0.125em` left and right-aligned text `0.25em` left.
+- Text with no colour is black.
+- `letterSpacing` applies only as a length with its unit (`px`, `em`); a bare number is ignored.
+- `textRuns` are ignored by a reader that lays out text itself; it lays out `content` instead.
+- A text layer's shadow follows the glyphs (CSS `text-shadow`).
+- The `lineHeight` leading is split evenly above and below the glyphs, as in CSS.
+- On a text layer, `effects` of type `drop-shadow` add one text-shadow (`x`, `y` default 0 and 4, `blur` default 12) and `glow` adds two, blurred `radius * 0.4` and `radius` (default 16, colour `#f59e0b`).
+
+**Shapes, strokes and fills**
+- A plain rectangle's stroke is a border outside its box: the box grows by `strokeWidth` on every side,
+  keeps its vertical centre, and is anchored horizontally by `textAlign` (left by default). The fill
+  paints under the border. Shapes drawn as SVG (catalogue shape, `svgPath`) stroke their outline instead.
+- Borders are drawn only from `strokeColor`, `strokeWidth` and `strokeStyle`. `borderColor` and
+  `borderWidth` are not contract keys and are not drawn.
+- A custom path (`svgPath`) is scaled from its `svgViewBox` into the layer box; a photo frame with its own
+  `svgPath` masks its colour layer to that path too, so no box of the fill colour shows around the photo.
+- A `container` layer paints like a `geo` layer.
+- A pattern tile is `160 × fillPatternScale` (or `backgroundPatternScale`) canvas units. A stored tile
+  (`svgRawXml`) wins over the one generated from the pattern type.
+
+**Effects**
+- The shadow of a non-text layer, and the `drop-shadow` effect, follow the layer's silhouette (its alpha),
+  not its bounding box, and paint under the layer.
+- `effects` apply in file order to the whole layer, before its flip and rotation. `blur` blurs with a
+  standard deviation of `radius` (default 8). On a non-text layer `drop-shadow` casts the silhouette
+  (Gaussian sigma `blur / 2`) and `glow` casts it twice, blurred `radius * 0.4` then `radius`.
+- A non-empty `effects` replaces the legacy `shadow*`, `layerBlur`/`blur` and `grain` fields.
+- `texture` repeats its preset tile (`@oim-media/core` `TEXTURE_CATALOG`) at `tile size * scale` canvas units, blended
+  with `blend` (default per preset). Text takes it inside its glyphs; `svg` and `image` layers over their pixels;
+  other layers over their box, faded once more by `intensity`. In document `metadata.effects` it covers the canvas.
+- Media filters (`filterPreset`, `filter*`) apply only to `image` layers and to the picture of an image
+  fill, never to the frame or to other layer types.
+- `opacity` is read as `0..100`.
+- Retired keys (section 8), such as `blendMode`, are not drawn.
+
+---
+
+## 5. Canonical Parallax (`parallaxSchema`)
+
+Configuration for layers with spatial depth and reactive or continuous displacement (carried on `slot.parallax` or `slot.style.parallax`):
+
+```typescript
+interface OimParallax {
+  enabled: boolean;                 // Default: true
+  depth: number;                    // Focal depth (-2.0 to 2.0)
+  mode: "mouse" | "scroll" | "infinite_horizontal";
+  axis: "both" | "x_only" | "y_only";
+  infinite?: {
+    enabled?: boolean;              // Default: false (true when active)
+    speedPxSec?: number;            // Continuous advance speed (-500 to 500 px/s; alias: speed_px_sec)
+    direction?: "left_to_right" | "right_to_left";
+    mirror?: boolean;               // Mirror alternate tiles (aliases: seamlessTile, seamless_tile)
+    pauseOnHover?: boolean;         // Pause when the cursor rests on it (alias: pause_on_hover)
+  };
+}
+```
+
+> Note: On group layers that form an editable loop scene, `style.sceneLoop` (`{ speedPxSec, direction, mirror, pauseOnHover }`) and child `style.loopDepth` (`0..1`) preserve the scene parameters for re-editing, while each moving child layer carries its resolved `parallax` (`speedPxSec = scene.speedPxSec * loopDepth`) for the player (`infiniteLayerPlan`).
+
+---
+
+## 6. Interactivity and State Machine (`isInteractive`, `states`)
+
+Allows declaring interactivity without writing JavaScript:
+
+```typescript
+interface OimInteractiveStates {
+  hover?: OimStateConfig;           // State when the cursor rests on it or a touch is held (reverted on leave)
+  active?: OimStateConfig;          // State when clicked or tapped (persists)
+}
+
+interface OimStateConfig {
+  scale?: number;                   // Percentage scale (0 to 1000%, e.g. 105 = 105%)
+  rotation?: number;                // Rotation (-360 to 360 degrees)
+  opacity?: number;                 // Percentage opacity (0 to 100%)
+  transitionDuration?: number;      // Transition time in ms (0 to 10000)
+  actions?: OimStateAction[];       // Chained actions on other layers (max 64)
+}
+
+interface OimStateAction {
+  target: string;                   // ID of the target slot (1 to 128 chars)
+  type: "show" | "hide" | "toggle" | "setText" | "play"; // "play" added in 1.22.0
+  value?: string;                   // Value to apply (e.g. new text if type is setText, max 10000 chars)
+}
+```
+
+---
+
+## 7. Root Document Metadata (`OimMetadataSchema`)
+
+Top-level structure carried in the `OIM_Data` payload:
+
+| Key | Type | Description |
+|---|---|---|
+| `oim` | `string` | Format version of the document (e.g. `"1.27.9"`), the contract version the backend signs against. |
+| `min_player` | `string` | Minimum player version required to rebuild the document (`minVersionFor`). |
+| `oim_id` | `string` | Unique document identifier for re-editing and registry checks (max 128 chars). |
+| `media_type` | `"image" \| "video"` | Media type of the OIM document. |
+| `name` | `string` | Official title of the work (max 256 chars). |
+| `description` | `Record<string, string>` | Per-language summary of the whole document for screen readers (1.16.0, max 1000 chars per language). |
+| `reedit` | `"public" \| "author_only" \| "sealed"` | Authorised cryptographic re-edit policy (1.23.0; replaces deprecated Spanish `reedicion`). |
+| `immutable_lock` | `boolean` | Cryptographic seal flag (`true` when `reedit === "sealed"`). |
+| `canvas` | `{ natural_width: number, natural_height: number }` | Base reference dimensions of the canvas. |
+| `lang` / `languages` | `string[]` | Catalogue of BCP-47 language codes present in the document (max 10 chars per tag). |
+| `palettes` | `Record<string, Partial<Record<DynamicColorRole, string>>>` | Up to 6 named colour palettes mapping semantic roles to CSS colours (1.20.0). |
+| `defaultPalette` | `string` | Name of the active palette in `palettes` (1.20.0). |
+| `slots` | `OimSlot[]` | Array of interactive layers (maximum `MAX_SLOTS` = 150). |
+| `zones` | `OimZone[]` | Optional catalogue of named bounding box zones. |
+| `capabilities` | `("vector_parallax" \| "infinite_parallax" \| "text_marks" \| "image_fill" \| "media_filters" \| "frame_shapes")[]` | Capabilities used by the document. |
+| `capabilities_required` | same as `capabilities` | Capabilities the reader **must** implement to paint with fidelity (glTF pattern). |
+| `fonts` | `EmbeddedFont[]` | Font variants embedded in base64 for offline rendering (1.3.0): subset, static (no `fvar`, `gvar`, `avar`, `HVAR`, `MVAR`; `STAT` may stay) WOFF, `format: "woff"`, written since 1.27.0; WOFF2 (`format: "woff2"`) is read forever. The content starts with the magic of its format (`wOFF` / `wOF2`). |
+| `image_hash` | `string` | SHA-256 hash of the base image `IDAT` chunk payloads (`imageDataHash`). |
+| `image_hash_alg` | `"sha256-idat"` | Image sealing algorithm identifier. |
+| `signature` | `string` | ECDSA P-256 digital signature (Base64) over RFC 8785 canonical JSON (`serializeCanonical`). |
+| `key_version` | `string` | Public key identifier in `keys.json` (e.g. `"v1"`, `"v2"`). |
+| `signed_at` | `string` | ISO-8601 timestamp with time zone included inside the signed payload to enforce key expiry. |
+| `timestamp` | `string` | ISO-8601 timestamp of package creation. |
+
+---
+
+## 8. Retired Keys (Read-Only for Backward Compatibility)
+
+These keys remain declared with `deprecated: true` in `oim.schema.json` so already-published files continue to validate, but **no new writer may emit them**:
+- **In `style`:** `textTransform`, `verticalAlign`, `shader_fx`, `blendMode` (closed to 9 values), `grain`/`grainIntensity`/`grainSize`/`grainBlend` (replaced by `style.effects` texture), `textHighlight` (replaced by `style.marks`), `animation.custom_loop_css`/`custom_keyframes`/`custom_hover_css` (retired in 1.9.0).
+- **At the root:** `reedicion` (renamed to `reedit` in 1.23.0; mapped by `normalizeLegacyKeys`), `grain` and `effects` (background grain is baked into the base image, 1.12.0), `elements` and `layers` (`slots` is the single canonical name, 1.12.0), `allowed_domains` (retired in 1.7.0), `redirect_membership_verified` and `terms_accepted` (retired in 1.1.0).
+- **In the slot:** `p`, `s`, `st`, `c`, `t` (short aliases retired in 1.12.0).
+
+---
+
+## 9. Verification and Conformance
+
+Conformance of any generator or reader with this specification is validated automatically by running the canonical vector suite and JSON Schema agreement tests:
+
+```bash
+pnpm conformance
+pnpm --filter @oim-media/core test
+```
+
+### 9.1. Visual conformance
+
+The metadata vectors cannot see pixels: two renderers can read the same JSON and paint it differently.
+Every vector therefore also has a golden: `vectors/golden/<vector>.web.png`, rendered by the web player,
+which is the reference renderer.
+
+**Procedure.** 800 px wide; height `round(800 × h / w)` from the vector's PNG header; device pixel ratio 1;
+animations disabled; white background; host font `sans-serif` for text that names no family. Goldens
+are only valid when rendered on the CI job's Linux image (`node tools/render-web-goldens.mjs vectors/golden`),
+because fonts rasterise differently on each system.
+
+**Metric** (`tools/parity-core.mjs`). A pixel differs when any channel differs by more than 40. The
+difference mask is eroded with a 3×3 kernel, which removes anti-aliasing edges. The outermost 1 px ring of the image is not measured (the kernel has no neighbours there). A render fails when the
+remaining area exceeds **0.4 %** of the image or any 4-connected blob exceeds **576 px** (a 24 × 24 square).
+
+The threshold was calibrated on 2026-11-07 against bugs reproduced on purpose:
+
+| Case | Area |
+|---|---|
+| Largest passing vector (text anti-aliasing, `typography-styling`) | 0.265 % |
+| Unitless `letterSpacing` ignored | 0.509 % |
+| Square shadow on a round shape | 6.96 % |
+| Shadow painted over the fill | 6.29 % |
+| Pattern tile at the wrong size | 10.9 % |
+| Pattern background painted over the layers | 24.6 % |
+
+**Running it.** A renderer writes `<vector>.png` per vector following the procedure, then
+`node tools/parity.mjs <renders-dir> --renderer <name> --out <diff-dir>` compares them and writes a red
+difference image for each failure. Known differences go in `vectors/golden/exceptions.json`, per renderer,
+with a reason; an excepted vector that passes fails the run, so a fixed bug cannot keep its exception.