@oim-media/spec 0.0.0-stage → 1.27.9

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,6 @@
+OIM Ecosystem
+Copyright 2026 Xue Studios LLC
+
+This product includes software developed at Xue Studios LLC.
+
+"OIM" and the "OIM compatible" mark are not licensed under Apache-2.0.

package/README.md

@@ -1,3 +1,446 @@
-# Temporary Holding Version
+# oim-spec — the format contract
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This is **not** a library. It is the definition of the `.oim` format, in data,
+so that an implementation in any language can be correct without reading the
+TypeScript.
+
+```
+BINARY_SPEC.md      Binary layout of the PNG container, compression and the image seal.
+CANONICAL_SPEC.md   Canonical form of the metadata, the bytes a signature covers.
+schema/             oim.schema.json and ovm.schema.json: JSON Schema, generated from @oim-media/core.
+keys.json           Public keys every player embeds (kid, jwk and key dates). Public parts only.
+marks-cases.json    Known-answer cases for text marks, shared with the backend's validator tests.
+canonical-cases.json  Known-answer case for the canonical form, checked by the TypeScript, Rust and Dart implementations.
+vectors/            37 signed .oim files, each with <name>.expected.json.
+tools/              Read-only checks: contract-summary.mjs, canonical-check.mjs, style-usage.mjs.
+```
+
+Published as `@oim-media/spec`. The tarball carries the schema, the vectors, both
+specifications, `keys.json`, `marks-cases.json`, this README, LICENSE and NOTICE.
+
+## Versioning
+
+`CONTRACT_VERSION` in `packages/core/src/compatibility.ts` is the version of the
+**format**, not of any package. Each release tag names it: tag `vX.Y.Z` is valid only
+when `X.Y.Z` equals `CONTRACT_VERSION`. `node tools/versions.mjs vX.Y.Z` checks this,
+and the release workflow runs it before publishing. The `$id` and `specVersion` of
+both schema files carry the same version. Every version has a one-line entry in the
+history comment above `CONTRACT_VERSION`.
+
+Packages can release without a format change. The root README describes what makes
+a minor, a major or a patch.
+
+## Why it exists
+
+The two repositories had copied the same code instead of sharing it, and the
+copies drifted: `grupos.ts` accumulated 546 lines that differed between the
+player and the editor, `layerComposition.ts` 775. A player in Swift or in Rust
+would repeat that mistake once per language.
+
+A contract in TypeScript only serves TypeScript. This directory is the part
+that survives the language.
+
+## Who is the authority today
+
+Today the source of truth is still `packages/core/src/schema.ts`: the JSON in
+`schema/` is **generated** from that Zod schema, and a test fails if someone
+edits the Zod without regenerating. This is deliberate — a generated contract
+cannot drift from its implementation, which is exactly the failure this closes.
+
+Other implementations now exist in this repository: the Rust crate and the
+Flutter SDK read the same files. They are held to the generated JSON Schema, the
+two specifications, the conformance vectors and the shared case files, not to
+the TypeScript source. The direction has not been reversed yet: the JSON Schema
+is still generated from the Zod schema rather than written first.
+
+## Regenerate
+
+```
+pnpm --filter @oim-media/core test -- -u
+```
+
+## Check whether the contract and the files have drifted
+
+```
+node tools/contract-summary.mjs          # readable report
+node tools/contract-summary.mjs --json   # the same data, for another tool
+node tools/contract-summary.mjs --write  # writes contract-summary.json
+
+node tools/canonical-check.mjs           # the signature: rebuilds the canonical form
+                                         # and verifies the real vectors
+```
+
+A test watches that the JSON Schema follows the Zod, but **nothing compared the
+contract against real signed files**. That gap had already let four divergences
+through, found by hand on 18 September 2026; the worst, `reedicion` — who may
+re-edit the work — goes in every file and is not declared anywhere.
+
+The script reports, it does not fix or fail. Turning drift into a red test is
+the right end state, but first the drift must be resolved: a test that starts
+red teaches everyone to ignore it.
+
+## `content` and the main `*` (since 1.2.0)
+
+On media layers (image, Lottie, vector), `content` can store the main media
+under the key `"*"` and only the exceptions under their language code:
+
+    "content": { "*": "oim-media:abc", "pt": "oim-media:def" }
+
+Reading rule: if `content` has `"*"`, the requested language uses **its own key
+if it exists, even if empty**; if it does not exist, it uses `"*"`. There are no
+further fallbacks. Without `"*"` (every file prior to 1.2.0, and every text),
+the usual rule applies: the requested language, then `en`, `es`, `default` and
+the first key.
+## `reedicion` and `name` at the root (since 1.4.0)
+
+Since 1.23.0 the permission is written as `reedit` (see below); `reedicion` is
+read as a legacy alias.
+
+Both were in **every** published file and in **no** version of the contract. A
+reader built by reading only the contract could not know they existed.
+
+`reedicion` was the worse of the two because **it decides a permission**:
+
+    "reedicion": "publico" | "solo_autor" | "sellado"
+
+An unknown value falls back to `solo_autor`, **never to `publico`**: the default
+of a permission system is chosen by what happens when something goes wrong. A
+reader that ignored it would treat as re-editable a work that is not.
+
+It travels together with `immutable_lock`, and this is not redundancy:
+`reedicion` is the declaration — it travels inside the file, so anyone who opens
+it knows what its author intended — and `immutable_lock` is what the backend
+stores and enforces. A declaration without enforcement is a suggestion; an
+enforcement without a declaration is a closed door with no sign. `reeditPermission.ts`
+is the canonical source of that rule, and it writes both fields at once so that
+they cannot be separated.
+
+`name` is the title of the work. Do not confuse it with `slot.name` or
+`fonts[].name`.
+
+## Names in English (since 1.23.0)
+
+The format keys are in English. `reedit` replaces `reedicion`, with the values
+`public`, `author_only` and `sealed` in place of `publico`, `solo_autor` and
+`sellado`. Writers emit only the English keys.
+
+`reedicion` is read forever as a legacy alias. Every file signed before 1.23.0
+carries it, and the signature covers the keys as they were written, so a reader
+verifies the signature first and maps the legacy key afterwards
+(`normalizeLegacyKeys`). An unknown value still falls back to `author_only`.
+
+The exported names of the packages are English too. The Spanish ones remain as
+deprecated aliases until 2.0.0. The player's `data-oim-*` attributes are doubled
+in the same contract version: the English names are added and the Spanish ones
+keep working.
+
+## Legacy keys on read
+
+Files signed before 1.23.0 carry Spanish keys. A reader maps them to the English
+ones after it has verified the signature, because the signature covers the keys as
+they were written:
+
+| Legacy key | English key | Legacy value | English value |
+|---|---|---|---|
+| `reedicion` | `reedit` | `publico` | `public` |
+| | | `solo_autor` | `author_only` |
+| | | `sellado` | `sealed` |
+
+A missing or unknown value becomes `author_only`, never `public`. If a file has both
+keys, `reedit` wins. The mapping is `normalizeLegacyKeys` in
+`packages/core/src/legacyKeys.ts`. Writers emit only the English keys, and the
+player's `data-oim-*` attributes keep their Spanish names as aliases until 2.0.0.
+
+## What is retired is marked, not deleted (since 1.4.0)
+
+`terms_accepted` and `redirect_membership_verified` carry `deprecated: true` in
+the JSON Schema, which is the **machine-readable** way of saying it: a new reader
+does not have to interpret a comment to know it must not write them.
+
+Version 1.1.0 left them behind when it retired `allow_external_urls`: their only
+readers — the backend's signing paths — sit behind `if allow_external_urls`, a
+key the contract no longer declares, so **the check cannot fire for a conforming
+file**.
+
+Marked and not deleted, on purpose. The backend still honours them if a file
+carries the retired key; removing them from the contract would make it lie in
+the other direction, which is the same failure with the sign flipped.
+
+**`allowed_domains` is not on that list, although it has been said otherwise.**
+It is still alive and the player enforces it: `worker.ts` turns it into
+`isDomainAllowed` and `securityVerdict` answers `domain_blocked`. A test exists
+that prevents it from being declared dead again.
+
+Nothing is removed and `min_player` does not go up: an old file is still valid,
+and a reader that ignores the four keys behaves exactly as before.
+
+## Embedded fonts (since 1.3.0)
+
+The root may carry `fonts`: one entry per font variant the work uses, trimmed to
+the characters it can display.
+
+    { "family": "Lora", "name": "oim-3f9a1c2b-Lora", "weight": 700,
+      "style": "italic", "format": "woff2", "data": "<base64>" }
+
+A reader that understands it registers each entry under the name in `name` and
+paints the layers of family `family` with that name first. A reader that does
+not understand it ignores it: the layers still say `family` and are painted as
+before. That is why `fonts` does not raise `min_player`.
+
+**Online fonts are inherited behaviour** since 17 September 2026: the editor no
+longer offers them and every new file carries its fonts inside. The reference
+player keeps its Google loader only for files already published, and a new
+reader does not have to implement it: without `fonts`, it is painted with the
+system's fallback typeface. An `.oim` does not request anything from third
+parties when it is opened, which is what 1.1.0 decided when it retired
+`allow_external_urls`.
+
+## Style stops being free text (since 1.8.0)
+
+Version 1.6 declared about forty style keys that the editor already wrote, but
+almost all as free strings: declaring a key without saying what it accepts
+documents that it exists, not how it is read. Version 1.8.0 gives them a shape:
+
+- **A single colour type**, `cssColor`, for the sixteen colour keys. It accepts
+  hex, `rgb()`/`hsl()`, `transparent`, `none`, `currentColor`, `inherit` and
+  `var(--name)` with a fallback, because dynamic colours go into real files. It
+  is the portable twin of `isSafeCssColor`, the player's sanitiser: a test
+  requires that **everything the contract accepts, the player accepts**, never the
+  other way around.
+- **Closed vocabularies** where the editor already closes them: colour roles, the
+  14 patterns, the 8 pattern directions, the text gradient and text animation,
+  and `geoShape` gains `scribble`, which was written but not declared.
+- **The three `any` have a shape**: `cuts` (mask cutouts), `fillGenerative`
+  (generator, seed, parameters and colours) and `fillGradient`.
+
+`fillGradient` was the serious hole. It ends up in `background-image`, which
+accepts a list of images, so `linear-gradient(red, blue), url(https://third-party/beacon)`
+made opening the file request a resource from a third party. Now the contract
+accepts **a single** gradient with colour functions inside, and the player discards
+anything else even if the file does not validate against the contract.
+
+Measured on 24 September 2026: the 42 `.oim` files on disk, including the 20
+vectors, validate against 1.8.0.
+
+## No raw CSS (since 1.9.0)
+
+`animation.custom_loop_css`, `custom_keyframes` and `custom_hover_css` carry
+`deprecated: true` and **no player may apply them**. `loop: "custom"` and
+`hover: "custom"` paint nothing.
+
+They were CSS from the file pasted as-is into a style sheet. The filter only
+rewrote `url(...)`, and there were three other ways of requesting a resource that
+passed through intact: `@import "https://…"`, `image-set("https://…" 1x)` and a
+`url` written with a CSS escape (`\75rl(…)`). `custom_hover_css` did not even go
+through the filter and was pasted inside `{ … }`, so a `}` could leave the rule
+and rewrite the entire player, including its own warnings.
+
+The editor never wrote them and no file uses them: they are removed rather than
+chasing the grammar of CSS with a blocklist. `cssAnimation` stays, restricted to
+the only form the editor writes,
+`background-animation-<direction> <n>s linear infinite`.
+
+## Named palettes (since 1.20.0)
+
+The root of the `.oim` may carry `palettes` and `defaultPalette`:
+
+- **`palettes`**: a map from name to palette. Each palette assigns colours to the
+  twelve roles of `DYNAMIC_COLOR_ROLES` (the eight from before plus `text-primary`,
+  `text-secondary`, `text-muted` and `text-on-accent`). At most six palettes. A
+  name matches `^[a-z][a-z0-9-]{0,23}$`. Colours are not validated in the
+  contract: the reader discards those that fail `isSafeCssColor` and keeps the
+  rest, the same as with a layer colour.
+- **`defaultPalette`**: the name of the default palette. If it does not name a
+  palette in `palettes`, the reader ignores it.
+
+**Resolution order** (`resolvePalette` in `@oim-media/core`):
+
+1. The palette requested by the host (the player's `palette` attribute).
+2. If the document carries `dark` and `light`, the one that `prefers-color-scheme` asks for.
+3. `defaultPalette`.
+4. None: each layer uses its fixed colour.
+
+The result is written to the viewer as `--oim-palette-<role>`, and
+`resolveCssColor(role, fixed)` emits `var(--oim-color-<role>, var(--oim-palette-<role>, fixed))`.
+The host's `--oim-color-*` still win over the palette, and `allow-dynamic-colors="false"`
+overrides all of them.
+
+A 1.20.0 file read by an earlier player is shown with each layer's fixed
+colours. Nothing breaks.
+
+## Conformance vectors
+
+`vectors/` holds 37 signed `.oim` files and their expected reads. They are
+generated by Xue Studios' signing service through the production pipeline and
+committed to this repository; the generator itself is not part of it. See
+[`vectors/README.md`](vectors/README.md).
+
+### How conformance uses them
+
+`pnpm conformance`, run from the repository root, executes
+`packages/core/src/conformance-vectors.test.ts`. For each `*.oim.png` in `vectors/`
+the test extracts the metadata with `extractOIM`, parses it with the contract's
+Zod schema, and compares the fields that two implementations can genuinely
+disagree on: geometry already normalised, group hierarchy, parallax depth, typography,
+declared interactivity and, from 1.23.0, the `reedit` permission. The test header
+explains why the whole metadata is not compared.
+
+A reader in another language should make the same comparison against the
+`expected.json` next to each vector. [`vectors/README.md`](vectors/README.md)
+lists the steps.
+
+### Visual conformance
+
+Each vector also has a golden rendered by the web player, `vectors/golden/<vector>.web.png`,
+and every other renderer is compared with it pixel by pixel. Procedure, metric and threshold:
+[`CANONICAL_SPEC.md`](CANONICAL_SPEC.md) section 9.1.
+
+```bash
+pnpm --filter @oim-media/spec goldens          # regenerate the goldens (on the CI image only)
+pnpm --filter @oim-media/spec parity <dir> --renderer flutter --out <diff-dir>
+```
+
+CI runs it in the `parity` job, on the same runner as `test`. A self-hosted runner
+(`vars.CI_RUNNER`) needs, once, with sudo: `sudo apt install unzip` (Flutter) and
+`pnpm --filter @oim-media/spec exec playwright install-deps chromium` (Chromium's system libraries).
+Known differences live in `vectors/golden/exceptions.json`, one entry per renderer and vector with
+its reason; remove the entry in the same change that fixes the renderer.
+
+## Precedent
+
+Lottie separated its specification from every implementation into `lottie/lottie-spec`
+— `/schema` split by object, `/tests` with vectors — and let each player be
+named as it wished in its ecosystem (`lottie-web`, `lottie-ios`,
+`com.airbnb.android:lottie`). There is no `@lottie/*` scope: the identity
+lives in the specification, not in the package name.
+
+## The canonical form of the signature
+
+Without this section, a second implementation can read the entire format and
+still **be unable to verify a single signature**. It is the only part of the
+contract that completely blocks a new reader: everything else can be ignored and
+degraded, the signature cannot.
+
+The signature is **ECDSA P-256 with SHA-256**, in raw IEEE P1363 format — `r || s`,
+32 bytes each, 64 in total — encoded in base64 inside `signature`. It is not
+DER: whoever uses a library that returns DER has to convert it.
+
+### The bytes that are signed
+
+Neither the chunk nor the JSON as written in the file is signed. What is signed
+is the result of these seven rules, in this order:
+
+1. **Start from the metadata object** already decoded from the chunk.
+2. **Remove from the root** `signature`, `key_version`, `timestamp` and
+   `creator_user_id`. Only from the root: if those names appear nested, they stay.
+3. **Normalise the numbers**: round to **6 decimals** and, if the result has no
+   fractional part, emit it as an integer (`2.0000001` → `2`).
+4. **Sort the keys** of all objects, recursively, by Unicode code point. Also
+   inside the objects that appear in arrays.
+5. **Serialise compactly**: no spaces, separators `,` and `:`.
+6. **Do not escape non-ASCII**: `Zürich` is emitted as-is, not as `Z\u00fcrich`.
+7. **Encode in UTF-8**. Those bytes are the ones that are signed and the ones
+   that are verified.
+
+`signed_at` goes **inside** the signature and `timestamp` **outside**. This is
+not an oversight: `timestamp` can be rewritten without breaking anything, and the
+key-expiry check needs a date that cannot be forged.
+
+`creator_user_id` is excluded because it is personal data, and a signed file is
+exactly what its author can no longer delete.
+
+### The image seal
+
+`image_hash` is the **hexadecimal SHA-256 of the concatenation of the payloads of
+the `IDAT` chunks** of the PNG — only the data, without length, without type and
+without CRC — and `image_hash_alg` is `sha256-idat`.
+
+Because `image_hash` is one more metadata field, **the signature covers it**: with
+a valid signature, the seal can no longer be changed. That is why the order
+matters and is not negotiable: normalise the PNG, compute the seal, sign, and
+insert the chunk **at byte level without re-encoding the image**. A simple "save
+again" after signing changes the `IDAT` and the seal stops matching forever.
+
+Files prior to 11 September 2026 carry no seal and are accepted without one.
+
+### Where this used to break
+
+Until 20 September 2026 the two reference implementations — `serialize_canonical`
+in Python and `serializeCanonical` in TypeScript — agreed **by construction, not
+by agreement**, and disagreed on three inputs. With `packages/core/src/canonical.ts`
+as the single source on the TypeScript side, measured again on 24 September:
+
+| Input | Python | TypeScript | Status |
+|---|---|---|---|
+| `creator_user_id` at the root | removes it | removes it | **closed** |
+| decimal with more than 6 digits | rounds | rounds | **closed** |
+| keys outside the BMP | code point | code point | **closed** |
+| decimal that becomes an integer when rounded | `2` | `2` | **closed on 24 Sept** |
+
+The fourth was found by the review of 24 September and was an **ordering** issue
+inside rule 3: `clean_floats` asked "is it an integer?" *before* rounding, and in a
+single pass left `2.0000001` as `2.0` and `1e-7` as `0.0`, where TypeScript emits
+`2` and `0`. The signer did not suffer it because it applies `clean_floats` twice;
+whoever reimplemented the Python with a single pass did. It now rounds first, and
+a test of the reference signer fixes the bytes.
+
+**What governs is what is signed**: round to 6 decimals first and, if the result
+has no fractional part, emit it as an integer. `-0` is emitted as `0`. No existing
+signature changes: with two passes the result was already that.
+
+A note on the citation: the comment in `canonical.ts` mentions RFC 8785 (JCS), but
+JCS sorts keys by **UTF-16 units**, not by code point. OIM sorts by code point;
+the two only differ with keys outside the BMP. The contract is this README, not the RFC.
+
+### What the script checks, and what it does not
+
+    node tools/canonical-check.mjs
+
+It rebuilds the seven rules and **verifies the real signature of each vector**
+with the v1 public key that the player carries inside. It does not compare against
+a digest pointed to by hand: if the rules were wrong, the signature would not validate.
+
+With the 20 vectors of the matrix — generated by the real pipeline and signed
+with the production key — each rule was removed one at a time:
+
+| Rule removed | Signatures that fail |
+|---|---|
+| 2 · root exclusions | 20 of 20 |
+| 6 · unescaped UTF-8 | 8 of 20 |
+| seal · SHA-256 of the `IDAT` | 19 of 19 sealed |
+| 3 · numbers | **0** |
+| 4 · key order | **0** |
+
+Rule 6 and the seal, which before were only held up by known-answer cases,
+**are now demonstrated by a signature**. Rules 3 and 4 are not, and **no vector
+signed by our pipeline could ever do so**: the signer writes the file from its own
+canonical bytes, so what remains in the chunk is already rounded and sorted. Those
+two rules only show up when someone **serialises the metadata again** — an editor
+that rewrites the chunk, another JSON library — and that is exactly where they
+are needed.
+
+That is why they remain covered by known-answer cases inside the script:
+they **catch a regression in the script, they do not prove that the signer agrees**.
+Proving it for real would require a hand-written vector, with unordered keys and a
+long decimal, signed over its canonical form: a file the real pipeline never produces.
+
+## What each tool prints
+
+| Command | Output |
+|---|---|
+| `node tools/contract-summary.mjs` | The contract's root keys, which are required, whether undeclared keys are accepted and its sub-definitions. Then the keys the vectors carry, and three kinds of drift: keys in the files but not in the contract, retired keys still declared, and keys in force that no vector exercises. It reports and exits 0. |
+| `node tools/contract-summary.mjs --json` | The same data as JSON on standard output. |
+| `node tools/contract-summary.mjs --write` | Writes the JSON to `packages/spec/contract-summary.json`. |
+| `node tools/canonical-check.mjs` | Rebuilds the seven canonical-form rules and verifies each vector's signature with the v1 public key. One line per vector; a vector without a signature is shown as `unsigned`. Exits 1 if any signature fails. |
+| `node tools/style-usage.mjs <file-or-url> ...` | For each file, its date, slot count and style-key count. Then the counts of keys declared in the contract, read by the player and present in the files, and the keys present but undeclared, most used first. `--vectors` runs it on the conformance vectors. |
+
+The scripts are read-only, except `contract-summary.mjs --write`.
+
+## Embedded player keys
+
+`keys.json` lists the public keys every player embeds (`kid`, `jwk`, and the
+`not_after` / `verify_until` dates where they apply). At 1.25.0 it has `v1` and `v2`.
+It is generated from the player's key set by `tools/keys-json.mjs` at the
+repository root. `node tools/keys-json.mjs --check` exits 1 when the file has
+drifted, and a test fails if the two disagree. Only public components are ever
+written.

package/action-cases.json

@@ -0,0 +1,13 @@
+[
+  { "name": "show", "actions": [{ "target": "a", "type": "show" }], "current": { "a": false }, "expected": { "visibility": { "a": true }, "texts": {} } },
+  { "name": "hide", "actions": [{ "target": "a", "type": "hide" }], "current": { "a": true }, "expected": { "visibility": { "a": false }, "texts": {} } },
+  { "name": "toggle a visible layer", "actions": [{ "target": "a", "type": "toggle" }], "current": { "a": true }, "expected": { "visibility": { "a": false }, "texts": {} } },
+  { "name": "toggle a hidden layer", "actions": [{ "target": "a", "type": "toggle" }], "current": { "a": false }, "expected": { "visibility": { "a": true }, "texts": {} } },
+  { "name": "toggle an unknown layer counts it as visible", "actions": [{ "target": "a", "type": "toggle" }], "current": {}, "expected": { "visibility": { "a": false }, "texts": {} } },
+  { "name": "setText with a value", "actions": [{ "target": "t", "type": "setText", "value": "Hola" }], "current": {}, "expected": { "visibility": {}, "texts": { "t": "Hola" } } },
+  { "name": "setText without a value clears", "actions": [{ "target": "t", "type": "setText" }], "current": {}, "expected": { "visibility": {}, "texts": { "t": "" } } },
+  { "name": "play changes no visibility", "actions": [{ "target": "i", "type": "play" }], "current": { "i": true }, "expected": { "visibility": {}, "texts": {} } },
+  { "name": "an empty target is skipped", "actions": [{ "target": "", "type": "hide" }], "current": {}, "expected": { "visibility": {}, "texts": {} } },
+  { "name": "chained toggle and hide", "actions": [{ "target": "panel", "type": "toggle" }, { "target": "alerta", "type": "hide" }], "current": { "panel": true, "alerta": true }, "expected": { "visibility": { "panel": false, "alerta": false }, "texts": {} } },
+  { "name": "the last action on a target wins", "actions": [{ "target": "a", "type": "hide" }, { "target": "a", "type": "show" }], "current": { "a": true }, "expected": { "visibility": { "a": true }, "texts": {} } }
+]