diff --git a/.github/workflows/audio.yml b/.github/workflows/audio.yml
index 0104f848e..0517efe6f 100644
--- a/.github/workflows/audio.yml
+++ b/.github/workflows/audio.yml
@@ -44,7 +44,7 @@ jobs:
       # Each feature on its own, so code that needs another feature fails here.
       - name: Clippy, each feature alone
         run: |
-          for f in "" decode decode-native symphonia encode lossless-encode pcm-encode flac-encode peaks aac-decode aac-encode "aac-encode,rayon" opus-decode ac3-decode mpa-decode serde; do
+          for f in "" decode decode-native symphonia encode lossless-encode pcm-encode flac-encode peaks aac-decode aac-encode "aac-encode,rayon" opus-decode opus-encode ac3-decode mpa-decode serde; do
             echo "::group::features: ${f:-none}"
             cargo clippy -p craft-audio --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings
             echo "::endgroup::"
diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md
index 19d38973d..32bae195d 100644
--- a/ATTRIBUTION.md
+++ b/ATTRIBUTION.md
@@ -6,6 +6,7 @@ author, source and license. Library code and original assets are under the repos
 
 | File | Author | Source | License |
 |---|---|---|---|
+| `licenses/dwg/acadrust-MPL-2.0.txt`, `licenses/dwg/acadrust-THIRD_PARTY_NOTICES.md` | `acadrust` contributors; ACadSharp authors for the noted ported routines | [acadrust 0.6.6](https://github.com/hakanaktt/acadrust), used unmodified as `craft-dwg`'s optional native dependency | MPL-2.0; embedded ACadSharp notice is MIT; see both retained files |
 | `crates/cms/profiles/photocraft-coated-cmyk.icc` | PhotoCraft contributors; generated by `craft_cms::synth::coated_cmyk` | [PhotoCraft `crates/cms`](https://github.com/storytold/photocraft/tree/b3222ee8e7e6bcb4799c37f904c595f20f9baf5e/crates/cms) | CC0-1.0 |
 | `crates/cms/profiles/craft-coated-fogra39.icc` | craft-libs contributors; generated by `crates/cms/tests/fogra39.rs` from the FOGRA39 data below | this repository | CC0-1.0 |
 | `crates/font-store/index/sources.json` (unmodified) | craft-font-index contributors | [aiongg/craft-font-index@5a9a7f8](https://github.com/aiongg/craft-font-index/tree/5a9a7f8038c8f3e2e1583a79c92a816e8e71b34f) | Apache-2.0 |
diff --git a/Cargo.lock b/Cargo.lock
index 09d5fa6a9..6a4d8e0e9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,6 +2,30 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "acadrust"
+version = "0.6.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8923c99ea1f151cb7fc17ce2fc14f8b1e330fa22611e535602d985c0cc3c89a2"
+dependencies = [
+ "anyhow",
+ "bitflags 2.13.2",
+ "byteorder",
+ "encoding_rs",
+ "flate2",
+ "foldhash 0.2.0",
+ "indexmap",
+ "itoa",
+ "memmap2",
+ "nom 7.1.3",
+ "oem_cp",
+ "once_cell",
+ "rayon",
+ "ryu",
+ "thiserror 2.0.21",
+ "web-time",
+]
+
 [[package]]
 name = "accesskit"
 version = "0.25.1"
@@ -98,24 +122,6 @@ dependencies = [
  "zerocopy",
 ]
 
-[[package]]
-name = "aligned"
-version = "0.4.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ee4508988c62edf04abd8d92897fca0c2995d907ce1dfeaf369dac3716a40685"
-dependencies = [
- "as-slice",
-]
-
-[[package]]
-name = "aligned-vec"
-version = "0.6.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc890384c8602f339876ded803c97ad529f3842aba97f6392b3dba0dd171769b"
-dependencies = [
- "equator",
-]
-
 [[package]]
 name = "alloc-no-stdlib"
 version = "2.0.4"
@@ -198,23 +204,6 @@ version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 
-[[package]]
-name = "arbitrary"
-version = "1.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3bc62ac97cc33321f50863d514c3bc38a453947a8f9e781137e47c7401020aed"
-
-[[package]]
-name = "arg_enum_proc_macro"
-version = "0.3.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0ae92a5119aa49cdbcf6b9f893fe4e1d98b04ccbf82ee0584ad948a44a734dea"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "argon2"
 version = "0.5.3"
@@ -249,15 +238,6 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "175571dd1d178ced59193a6fc02dde1b972eb0bc56c892cde9beeceac5bf0f6b"
 
-[[package]]
-name = "as-slice"
-version = "0.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "516b6b4f0e40d50dcda9365d53964ec74560ad4284da2e7fc97122cd83174516"
-dependencies = [
- "stable_deref_trait",
-]
-
 [[package]]
 name = "ash"
 version = "0.38.0+1.3.281"
@@ -410,49 +390,6 @@ version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
-[[package]]
-name = "av-scenechange"
-version = "0.14.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0f321d77c20e19b92c39e7471cf986812cbb46659d2af674adc4331ef3f18394"
-dependencies = [
- "aligned",
- "anyhow",
- "arg_enum_proc_macro",
- "arrayvec",
- "log",
- "num-rational",
- "num-traits",
- "pastey",
- "rayon",
- "thiserror 2.0.21",
- "v_frame",
- "y4m",
-]
-
-[[package]]
-name = "av1-grain"
-version = "0.2.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8cfddb07216410377231960af4fcab838eaa12e013417781b78bd95ee22077f8"
-dependencies = [
- "anyhow",
- "arrayvec",
- "log",
- "nom",
- "num-rational",
- "v_frame",
-]
-
-[[package]]
-name = "avif-serialize"
-version = "0.8.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e7178fe5f7d460b13895ebb9dcb28a3a6216d2df2574a0806cb51b555d297f38"
-dependencies = [
- "arrayvec",
-]
-
 [[package]]
 name = "aws-lc-rs"
 version = "1.18.1"
@@ -580,15 +517,6 @@ version = "2.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 
-[[package]]
-name = "bitstream-io"
-version = "4.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7eff00be299a18769011411c9def0d827e8f2d7bf0c3dbf53633147a8867fd1f"
-dependencies = [
- "no_std_io2",
-]
-
 [[package]]
 name = "bitvec"
 version = "1.1.1"
@@ -799,12 +727,6 @@ dependencies = [
  "memchr",
 ]
 
-[[package]]
-name = "built"
-version = "0.8.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c0e531d93d39c34eef561e929e8a7f86d77a5af08aac4f6d6e39976c51858e9"
-
 [[package]]
 name = "bumpalo"
 version = "3.20.3"
@@ -1388,6 +1310,17 @@ dependencies = [
  "proptest",
 ]
 
+[[package]]
+name = "craft-designcraft-format"
+version = "0.1.0"
+dependencies = [
+ "craft-document-bundle",
+ "craft-eps",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+]
+
 [[package]]
 name = "craft-dialogs"
 version = "0.1.0"
@@ -1490,12 +1423,21 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "craft-dwg"
+version = "0.1.0"
+dependencies = [
+ "acadrust",
+ "log",
+]
+
 [[package]]
 name = "craft-dxf"
 version = "0.1.0"
 dependencies = [
  "craft-codepage",
  "encoding_rs",
+ "kurbo 0.13.1",
  "log",
  "thiserror 2.0.21",
 ]
@@ -1512,6 +1454,12 @@ dependencies = [
 [[package]]
 name = "craft-eps"
 version = "0.1.0"
+dependencies = [
+ "kurbo 0.13.1",
+ "thiserror 2.0.21",
+ "vectorcraft-doc",
+ "vectorcraft-eps",
+]
 
 [[package]]
 name = "craft-epub"
@@ -1557,6 +1505,17 @@ dependencies = [
  "zip",
 ]
 
+[[package]]
+name = "craft-figcraft-format"
+version = "0.1.0"
+dependencies = [
+ "craft-zip",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+ "zip",
+]
+
 [[package]]
 name = "craft-figma-rest"
 version = "0.1.0"
@@ -1578,6 +1537,21 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "craft-file-import"
+version = "0.1.0"
+dependencies = [
+ "craft-dxf",
+ "craft-eps",
+ "craft-file-formats",
+ "craft-pdf 0.1.0",
+ "craft-raster-codecs",
+ "craft-svg",
+ "kurbo 0.13.1",
+ "thiserror 2.0.21",
+ "vectorcraft-geom",
+]
+
 [[package]]
 name = "craft-flags"
 version = "0.1.0"
@@ -1680,6 +1654,7 @@ dependencies = [
 name = "craft-gif"
 version = "0.1.0"
 dependencies = [
+ "gif",
  "image",
 ]
 
@@ -1752,30 +1727,6 @@ dependencies = [
  "zip",
 ]
 
-[[package]]
-name = "craft-image-codecs"
-version = "0.1.0"
-dependencies = [
- "craft-heif",
- "craft-jpeg",
- "exr",
- "flate2",
- "half",
- "image",
- "image-webp",
- "jpeg-encoder 0.6.1",
- "jxl-oxide",
- "png 0.18.1",
- "proptest",
- "rayon",
- "serde_json",
- "thiserror 2.0.21",
- "tiff",
- "zune-core",
- "zune-jpeg",
- "zune-jpegxl",
-]
-
 [[package]]
 name = "craft-indd"
 version = "0.1.0"
@@ -1800,6 +1751,16 @@ dependencies = [
  "zune-jpeg",
 ]
 
+[[package]]
+name = "craft-jxl"
+version = "0.1.0"
+dependencies = [
+ "craft-cms",
+ "jixel",
+ "jxl-oxide",
+ "thiserror 2.0.21",
+]
+
 [[package]]
 name = "craft-keymap"
 version = "0.1.0"
@@ -1846,6 +1807,7 @@ dependencies = [
 name = "craft-lottie"
 version = "0.1.0"
 dependencies = [
+ "craft-zip",
  "serde_json",
  "thiserror 2.0.21",
 ]
@@ -2097,6 +2059,17 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "craft-pdf"
+version = "0.1.0"
+source = "git+https://github.com/storytold/craft-libs?rev=92d392cff132eaf53e13afff77f38b5c11b73aa0#92d392cff132eaf53e13afff77f38b5c11b73aa0"
+dependencies = [
+ "hayro-interpret",
+ "hayro-syntax",
+ "krilla",
+ "thiserror 2.0.21",
+]
+
 [[package]]
 name = "craft-pdn"
 version = "0.1.0"
@@ -2153,7 +2126,7 @@ name = "craft-plate-test"
 version = "0.1.0"
 dependencies = [
  "craft-cms",
- "craft-pdf",
+ "craft-pdf 0.1.0",
  "hayro-syntax",
  "serde",
  "serde_json",
@@ -2214,7 +2187,7 @@ name = "craft-prepress"
 version = "0.1.0"
 dependencies = [
  "craft-cms",
- "craft-pdf",
+ "craft-pdf 0.1.0",
  "craft-plate-test",
  "kurbo 0.13.1",
  "linesweeper",
@@ -2282,7 +2255,6 @@ name = "craft-raster-codecs"
 version = "0.1.0"
 dependencies = [
  "base64 0.23.1",
- "craft-image-codecs",
  "image",
  "rayon",
  "thiserror 2.0.21",
@@ -2323,6 +2295,20 @@ dependencies = [
  "proptest",
 ]
 
+[[package]]
+name = "craft-scraft-format"
+version = "0.1.0"
+dependencies = [
+ "craft-audio",
+ "craft-midi",
+ "craft-time",
+ "craft-zip",
+ "proptest",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+]
+
 [[package]]
 name = "craft-settings"
 version = "0.1.0"
@@ -2366,6 +2352,19 @@ dependencies = [
  "zip",
 ]
 
+[[package]]
+name = "craft-stencilcraft-document"
+version = "0.1.0"
+dependencies = [
+ "craft-atomic",
+ "craft-stencilcraft-format",
+ "craft-svg",
+ "kurbo 0.13.1",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+]
+
 [[package]]
 name = "craft-stencilcraft-format"
 version = "0.1.0"
@@ -2397,6 +2396,8 @@ dependencies = [
  "roxmltree 0.21.2",
  "thiserror 2.0.21",
  "usvg 0.48.1",
+ "vectorcraft-geom",
+ "vectorcraft-pathops",
 ]
 
 [[package]]
@@ -2437,10 +2438,21 @@ dependencies = [
  "thiserror 2.0.21",
 ]
 
+[[package]]
+name = "craft-time"
+version = "0.1.0"
+dependencies = [
+ "proptest",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+]
+
 [[package]]
 name = "craft-timeline"
 version = "0.1.0"
 dependencies = [
+ "craft-time",
  "craft-xml",
  "proptest",
  "serde",
@@ -2614,6 +2626,14 @@ dependencies = [
  "thiserror 2.0.21",
 ]
 
+[[package]]
+name = "craft-xfl"
+version = "0.1.0"
+dependencies = [
+ "miniz_oxide 0.8.9",
+ "thiserror 2.0.21",
+]
+
 [[package]]
 name = "craft-xls"
 version = "0.1.0"
@@ -3321,7 +3341,7 @@ dependencies = [
  "bitflags 2.13.2",
  "emath",
  "epaint",
- "itertools 0.15.0",
+ "itertools",
  "log",
  "nohash-hasher",
  "profiling",
@@ -3378,7 +3398,7 @@ dependencies = [
  "ahash",
  "egui",
  "enum-map",
- "itertools 0.15.0",
+ "itertools",
  "log",
  "profiling",
  "resvg",
@@ -3586,7 +3606,7 @@ dependencies = [
  "emath",
  "epaint_default_fonts",
  "font-types 0.12.7",
- "harfrust",
+ "harfrust 0.12.0",
  "log",
  "nohash-hasher",
  "parking_lot",
@@ -3607,26 +3627,6 @@ name = "epaint_default_fonts"
 version = "0.37.0"
 source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a"
 
-[[package]]
-name = "equator"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4711b213838dfee0117e3be6ac926007d7f433d7bbe33595975d4190cb07e6fc"
-dependencies = [
- "equator-macro",
-]
-
-[[package]]
-name = "equator-macro"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "44f23cf4b44bfce11a86ace86f8a73ffdec849c9fd00a386a53d278bd9e81fb3"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -3683,7 +3683,6 @@ dependencies = [
  "lebe",
  "miniz_oxide 0.8.9",
  "multiversion",
- "rayon-core",
  "smallvec",
  "zune-inflate",
 ]
@@ -3835,6 +3834,12 @@ version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
 
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
 [[package]]
 name = "foldhash"
 version = "0.2.0"
@@ -4133,7 +4138,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d99fc21d493812643aae86d53b7bbd02f376434a90317e8a790bc209fdd6605e"
 dependencies = [
  "bytemuck",
- "foldhash",
+ "foldhash 0.2.0",
  "hashbrown 0.17.1",
  "log",
  "peniko",
@@ -4150,7 +4155,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "282a26c1e23de04bdab3e34a21b6f877a479b96737792516b9b8b8f69b6661be"
 dependencies = [
  "bytemuck",
- "foldhash",
+ "foldhash 0.2.0",
  "hashbrown 0.17.1",
  "log",
  "peniko",
@@ -4325,6 +4330,28 @@ dependencies = [
  "smallvec",
 ]
 
+[[package]]
+name = "harfrust"
+version = "0.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "948d0741125ba89cd3e1c23e5642415b6ade7e1d29d67ba25fb925b533e989d6"
+dependencies = [
+ "bitflags 2.13.2",
+ "bytemuck",
+ "once_cell",
+ "read-fonts 0.43.3",
+ "smallvec",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash 0.1.5",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.16.1"
@@ -4333,7 +4360,7 @@ checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
 dependencies = [
  "allocator-api2",
  "equivalent",
- "foldhash",
+ "foldhash 0.2.0",
 ]
 
 [[package]]
@@ -4342,7 +4369,7 @@ version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 dependencies = [
- "foldhash",
+ "foldhash 0.2.0",
 ]
 
 [[package]]
@@ -4381,7 +4408,7 @@ dependencies = [
  "hayro-syntax",
  "kurbo 0.13.1",
  "moxcms",
- "phf",
+ "phf 0.13.1",
  "rustc-hash 2.1.3",
  "siphasher",
  "skrifa 0.47.0",
@@ -4903,9 +4930,6 @@ dependencies = [
  "moxcms",
  "num-traits",
  "png 0.18.1",
- "qoi",
- "ravif",
- "rgb",
  "tiff",
  "zune-core",
  "zune-jpeg",
@@ -4944,12 +4968,6 @@ name = "indd"
 version = "0.1.0"
 source = "git+https://github.com/storytold/indd-utils?rev=7f3060e5bce78d21ea70e0d5eacb96edce15dfbe#7f3060e5bce78d21ea70e0d5eacb96edce15dfbe"
 
-[[package]]
-name = "imgref"
-version = "1.12.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6e44b0a4eaa4c82f441d50a963f2d5f05a787240aeee097597033e72accfd22f"
-
 [[package]]
 name = "indexmap"
 version = "2.14.2"
@@ -4979,17 +4997,6 @@ dependencies = [
  "hybrid-array",
 ]
 
-[[package]]
-name = "interpolate_name"
-version = "0.2.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c34819042dc3d3971c46c2190835914dfbe0c3c13f61449b2997f4e9722dfa60"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "io-extras"
 version = "0.19.0"
@@ -5037,15 +5044,6 @@ dependencies = [
  "once_cell",
 ]
 
-[[package]]
-name = "itertools"
-version = "0.14.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
-dependencies = [
- "either",
-]
-
 [[package]]
 name = "itertools"
 version = "0.15.0"
@@ -5061,6 +5059,12 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
+[[package]]
+name = "jixel"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "278a75e12caacec34be774d62ad05e45fc0b6a52d1f4e9f7fbc0209ecdf794f3"
+
 [[package]]
 name = "jni"
 version = "0.22.4"
@@ -5310,8 +5314,6 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "25f15eb830aa77a7f21148d72e153562a26bfe570139bd4922eab1908dd499d3"
 dependencies = [
- "rayon",
- "rayon-core",
  "tracing",
 ]
 
@@ -5472,16 +5474,6 @@ version = "0.2.190"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
 
-[[package]]
-name = "libfuzzer-sys"
-version = "0.4.13"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a9fd2f41a1cba099f79a0b6b6c35656cf7c03351a7bae8ff0f28f25270f929d2"
-dependencies = [
- "arbitrary",
- "cc",
-]
-
 [[package]]
 name = "libloading"
 version = "0.8.9"
@@ -5569,15 +5561,6 @@ version = "0.4.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
 
-[[package]]
-name = "loop9"
-version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fae87c125b03c1d2c0150c90365d7d6bcc53fb73a9acaef207d2d065860f062"
-dependencies = [
- "imgref",
-]
-
 [[package]]
 name = "lru-slab"
 version = "0.1.3"
@@ -5590,15 +5573,6 @@ version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4facc753ae494aeb6e3c22f839b158aebd4f9270f55cd3c79906c45476c47ab4"
 
-[[package]]
-name = "maybe-rayon"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ea1f30cedd69f0a2954655f7188c6a834246d2bcf1e315e2ac40c4b24dc9519"
-dependencies = [
- "cfg-if",
-]
-
 [[package]]
 name = "md-5"
 version = "0.10.6"
@@ -5659,6 +5633,12 @@ dependencies = [
  "walkdir",
 ]
 
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -5814,12 +5794,6 @@ dependencies = [
  "jni-sys 0.3.1",
 ]
 
-[[package]]
-name = "new_debug_unreachable"
-version = "1.0.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
-
 [[package]]
 name = "nix"
 version = "0.31.3"
@@ -5832,21 +5806,22 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "no_std_io2"
-version = "0.9.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "418abd1b6d34fbf6cae440dc874771b0525a604428704c76e48b29a5e67b8003"
-dependencies = [
- "memchr",
-]
-
 [[package]]
 name = "nohash-hasher"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2bf50223579dc7cdcfb3bfcacf7069ff68243f8c363f62ffa99cf000a6b9c451"
 
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
 [[package]]
 name = "nom"
 version = "8.0.0"
@@ -5856,12 +5831,6 @@ dependencies = [
  "memchr",
 ]
 
-[[package]]
-name = "noop_proc_macro"
-version = "0.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0676bb32a98c1a483ce53e500a81ad9c3d5b3f7c920c28c24e9cb0980d0b5bc8"
-
 [[package]]
 name = "nu-ansi-term"
 version = "0.50.3"
@@ -5871,16 +5840,6 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "num-bigint"
-version = "0.4.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"
-dependencies = [
- "num-integer",
- "num-traits",
-]
-
 [[package]]
 name = "num-bigint-dig"
 version = "0.8.6"
@@ -5913,17 +5872,6 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 
-[[package]]
-name = "num-derive"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "num-integer"
 version = "0.1.47"
@@ -5943,17 +5891,6 @@ dependencies = [
  "num-traits",
 ]
 
-[[package]]
-name = "num-rational"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
-dependencies = [
- "num-bigint",
- "num-integer",
- "num-traits",
-]
-
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -6317,6 +6254,15 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "oem_cp"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c7959d3349f484aec36462f98226983578bf7d33f9b034c32967489c7000e1f"
+dependencies = [
+ "phf 0.11.3",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -6367,6 +6313,15 @@ dependencies = [
  "libredox",
 ]
 
+[[package]]
+name = "ordered-channel"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95be4d57809897b5a7539fc15a7dfe0e84141bc3dfaa2e9b1b27caa90acf61ab"
+dependencies = [
+ "crossbeam-channel",
+]
+
 [[package]]
 name = "ordered-float"
 version = "5.5.0"
@@ -6511,18 +6466,6 @@ dependencies = [
  "subtle",
 ]
 
-[[package]]
-name = "paste"
-version = "1.0.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
-
-[[package]]
-name = "pastey"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "35fb2e5f958ec131621fdd531e9fc186ed768cbe395337403ae56c17a74c68ec"
-
 [[package]]
 name = "pbkdf2"
 version = "0.13.0"
@@ -6637,7 +6580,7 @@ dependencies = [
  "log",
  "md-5 0.10.6",
  "memchr",
- "nom",
+ "nom 8.0.0",
  "num-bigint-dig",
  "num-traits",
  "num_enum",
@@ -6663,6 +6606,15 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "phf"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
+dependencies = [
+ "phf_shared 0.11.3",
+]
+
 [[package]]
 name = "phf"
 version = "0.13.1"
@@ -6670,7 +6622,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c1562dc717473dbaa4c1f85a36410e03c047b2e7df7f45ee938fbef64ae7fadf"
 dependencies = [
  "phf_macros",
- "phf_shared",
+ "phf_shared 0.13.1",
 ]
 
 [[package]]
@@ -6680,7 +6632,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "135ace3a761e564ec88c03a77317a7c6b80bb7f7135ef2544dbe054243b89737"
 dependencies = [
  "fastrand",
- "phf_shared",
+ "phf_shared 0.13.1",
 ]
 
 [[package]]
@@ -6690,12 +6642,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "812f032b54b1e759ccd5f8b6677695d5268c588701effba24601f6932f8269ef"
 dependencies = [
  "phf_generator",
- "phf_shared",
+ "phf_shared 0.13.1",
  "proc-macro2",
  "quote",
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "phf_shared"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
+dependencies = [
+ "siphasher",
+]
+
 [[package]]
 name = "phf_shared"
 version = "0.13.1"
@@ -7049,19 +7010,6 @@ name = "profiling"
 version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d595e54a326bc53c1c197b32d295e14b169e3cfeaa8dc82b529f947fba6bcf5"
-dependencies = [
- "profiling-procmacros",
-]
-
-[[package]]
-name = "profiling-procmacros"
-version = "1.0.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4488a4a36b9a4ba6b9334a32a39971f77c1436ec82c38707bce707699cc3bbcb"
-dependencies = [
- "quote",
- "syn 2.0.119",
-]
 
 [[package]]
 name = "proptest"
@@ -7089,15 +7037,6 @@ version = "0.1.30"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
 
-[[package]]
-name = "qoi"
-version = "0.4.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f6d64c71eb498fe9eae14ce4ec935c555749aef511cca85b5568910d6e48001"
-dependencies = [
- "bytemuck",
-]
-
 [[package]]
 name = "quick-error"
 version = "1.2.3"
@@ -7219,20 +7158,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e058c7de0b26af77780c769414d6257830bb240f3c38477dbc2c16e5f54d6d4c"
 dependencies = [
  "libc",
- "rand_chacha 0.3.1",
+ "rand_chacha",
  "rand_core 0.6.4",
 ]
 
-[[package]]
-name = "rand"
-version = "0.9.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
-dependencies = [
- "rand_chacha 0.9.0",
- "rand_core 0.9.5",
-]
-
 [[package]]
 name = "rand"
 version = "0.10.3"
@@ -7254,16 +7183,6 @@ dependencies = [
  "rand_core 0.6.4",
 ]
 
-[[package]]
-name = "rand_chacha"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
-dependencies = [
- "ppv-lite86",
- "rand_core 0.9.5",
-]
-
 [[package]]
 name = "rand_core"
 version = "0.6.4"
@@ -7273,15 +7192,6 @@ dependencies = [
  "getrandom 0.2.17",
 ]
 
-[[package]]
-name = "rand_core"
-version = "0.9.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
-dependencies = [
- "getrandom 0.3.4",
-]
-
 [[package]]
 name = "rand_core"
 version = "0.10.1"
@@ -7312,55 +7222,6 @@ version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ca45419789ae5a7899559e9512e58ca889e41f04f1f2445e9f4b290ceccd1d08"
 
-[[package]]
-name = "rav1e"
-version = "0.8.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43b6dd56e85d9483277cde964fd1bdb0428de4fec5ebba7540995639a21cb32b"
-dependencies = [
- "aligned-vec",
- "arbitrary",
- "arg_enum_proc_macro",
- "arrayvec",
- "av-scenechange",
- "av1-grain",
- "bitstream-io",
- "built",
- "cfg-if",
- "interpolate_name",
- "itertools 0.14.0",
- "libc",
- "libfuzzer-sys",
- "log",
- "maybe-rayon",
- "new_debug_unreachable",
- "noop_proc_macro",
- "num-derive",
- "num-traits",
- "paste",
- "profiling",
- "rand 0.9.5",
- "rand_chacha 0.9.0",
- "simd_helpers",
- "thiserror 2.0.21",
- "v_frame",
- "wasm-bindgen",
-]
-
-[[package]]
-name = "ravif"
-version = "0.13.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e52310197d971b0f5be7fe6b57530dcd27beb35c1b013f29d66c1ad73fbbcc45"
-dependencies = [
- "avif-serialize",
- "imgref",
- "loop9",
- "quick-error 2.0.1",
- "rav1e",
- "rgb",
-]
-
 [[package]]
 name = "raw-window-handle"
 version = "0.6.2"
@@ -7429,6 +7290,17 @@ dependencies = [
  "once_cell",
 ]
 
+[[package]]
+name = "read-fonts"
+version = "0.43.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "005c8acf251756c478b0bf402885bfd88a1476020c4c7e6060edc1aa68da38ea"
+dependencies = [
+ "bytemuck",
+ "font-types 0.12.7",
+ "once_cell",
+]
+
 [[package]]
 name = "read-fonts"
 version = "0.44.0"
@@ -7447,7 +7319,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4edc8db0d972de88e53a085b1f01fb3fbdae7bb0cb7a0ce2b2f8285a412fe3ef"
 dependencies = [
  "bytemuck",
- "foldhash",
+ "foldhash 0.2.0",
  "font-types 0.12.7",
  "once_cell",
  "yoke",
@@ -8398,15 +8270,6 @@ dependencies = [
  "simdutf8",
 ]
 
-[[package]]
-name = "simd_helpers"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "95890f873bec569a0362c235787f3aca6e1e887302ba4840839bcc6459c42da6"
-dependencies = [
- "quote",
-]
-
 [[package]]
 name = "simdutf8"
 version = "0.1.5"
@@ -8606,6 +8469,16 @@ dependencies = [
  "float-cmp",
 ]
 
+[[package]]
+name = "string-interner"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23de088478b31c349c9ba67816fa55d9355232d63c3afea8bf513e31f0f1d2c0"
+dependencies = [
+ "hashbrown 0.15.5",
+ "serde",
+]
+
 [[package]]
 name = "stringprep"
 version = "0.1.5"
@@ -9049,6 +8922,15 @@ dependencies = [
  "syn 3.0.6",
 ]
 
+[[package]]
+name = "thread_local"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "tiff"
 version = "0.11.3"
@@ -9574,7 +9456,7 @@ dependencies = [
  "base64 0.23.1",
  "data-url",
  "fontdb",
- "harfrust",
+ "harfrust 0.12.0",
  "imagesize 0.15.0",
  "kurbo 0.13.1",
  "log",
@@ -9621,6 +9503,221 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "vectorcraft-brush"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "kurbo 0.13.1",
+ "serde",
+ "serde_json",
+ "vectorcraft-color",
+ "vectorcraft-doc",
+ "vectorcraft-geom",
+]
+
+[[package]]
+name = "vectorcraft-color"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "kurbo 0.13.1",
+ "moxcms",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "vectorcraft-doc"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "chrono",
+ "hayro-ccitt",
+ "image",
+ "kurbo 0.13.1",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+ "tiff",
+ "vectorcraft-color",
+ "vectorcraft-geom",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "vectorcraft-effects"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "image",
+ "kurbo 0.13.1",
+ "serde_json",
+ "vectorcraft-doc",
+ "vectorcraft-geom",
+ "vectorcraft-pathops",
+ "vectorcraft-plugins",
+ "vectorcraft-text",
+ "vectorcraft-three-d",
+]
+
+[[package]]
+name = "vectorcraft-eps"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "flate2",
+ "hayro-ccitt",
+ "image",
+ "kurbo 0.13.1",
+ "memchr",
+ "ruzstd",
+ "serde_json",
+ "vectorcraft-brush",
+ "vectorcraft-color",
+ "vectorcraft-doc",
+ "vectorcraft-effects",
+ "vectorcraft-geom",
+ "vectorcraft-metafile",
+ "vectorcraft-pdf",
+ "vectorcraft-render",
+ "vectorcraft-text",
+]
+
+[[package]]
+name = "vectorcraft-geom"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "kurbo 0.13.1",
+ "serde",
+ "thiserror 2.0.21",
+]
+
+[[package]]
+name = "vectorcraft-metafile"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "image",
+ "kurbo 0.13.1",
+ "vectorcraft-brush",
+ "vectorcraft-color",
+ "vectorcraft-doc",
+ "vectorcraft-effects",
+ "vectorcraft-geom",
+ "vectorcraft-text",
+]
+
+[[package]]
+name = "vectorcraft-pathops"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "kurbo 0.13.1",
+ "linesweeper",
+ "thiserror 2.0.21",
+ "vectorcraft-geom",
+]
+
+[[package]]
+name = "vectorcraft-pdf"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "aes 0.8.4",
+ "chrono",
+ "craft-pdf 0.1.0 (git+https://github.com/storytold/craft-libs?rev=92d392cff132eaf53e13afff77f38b5c11b73aa0)",
+ "flate2",
+ "getrandom 0.4.3",
+ "image",
+ "jpeg-encoder 0.6.1",
+ "kurbo 0.13.1",
+ "log",
+ "md-5 0.10.6",
+ "roxmltree 0.21.2",
+ "serde",
+ "sha2 0.10.9",
+ "skrifa 0.47.0",
+ "smallvec",
+ "thiserror 2.0.21",
+ "vectorcraft-brush",
+ "vectorcraft-color",
+ "vectorcraft-doc",
+ "vectorcraft-effects",
+ "vectorcraft-geom",
+ "vectorcraft-text",
+ "weezl 0.2.1",
+]
+
+[[package]]
+name = "vectorcraft-plugins"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "serde",
+ "serde_json",
+ "thiserror 2.0.21",
+ "vectorcraft-color",
+ "vectorcraft-doc",
+ "vectorcraft-geom",
+ "wasmi",
+]
+
+[[package]]
+name = "vectorcraft-render"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "flate2",
+ "gif",
+ "image",
+ "jpeg-encoder 0.6.1",
+ "log",
+ "png 0.18.1",
+ "vectorcraft-brush",
+ "vectorcraft-color",
+ "vectorcraft-doc",
+ "vectorcraft-effects",
+ "vectorcraft-geom",
+ "vectorcraft-text",
+ "vello_common 0.2.0",
+ "vello_cpu 0.2.0",
+ "weezl 0.2.1",
+ "winsafe",
+]
+
+[[package]]
+name = "vectorcraft-text"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "harfrust 0.13.3",
+ "icu_segmenter",
+ "kurbo 0.13.1",
+ "log",
+ "skrifa 0.47.0",
+ "subsetter",
+ "unicode-bidi",
+ "unicode-general-category",
+ "unicode-script",
+ "unicode-segmentation",
+ "vectorcraft-doc",
+ "vectorcraft-geom",
+ "vello_cpu 0.2.0",
+ "windows-registry",
+]
+
+[[package]]
+name = "vectorcraft-three-d"
+version = "0.18.0"
+source = "git+https://github.com/storytold/vectorcraft.git?rev=6b3a6b8788ebcb420d69449199cbdf323888d27e#6b3a6b8788ebcb420d69449199cbdf323888d27e"
+dependencies = [
+ "vectorcraft-geom",
+ "vectorcraft-pathops",
+]
+
 [[package]]
 name = "v_frame"
 version = "0.3.9"
@@ -9632,6 +9729,7 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+
 [[package]]
 name = "vello_common"
 version = "0.0.8"
@@ -9702,9 +9800,13 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ace506ca414548966fcf3c283be94eb1cad8254de488791ee698bf438b0890a9"
 dependencies = [
  "bytemuck",
+ "crossbeam-channel",
  "glifo 0.3.0",
  "hashbrown 0.17.1",
+ "ordered-channel",
  "png 0.18.1",
+ "rayon",
+ "thread_local",
  "vello_common 0.2.0",
 ]
 
@@ -9862,6 +9964,56 @@ version = "0.2.129"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4f692aa943ccd88363733b77063f32cfed5bc6cbea8e6e8b251b302f881606fe"
 
+[[package]]
+name = "wasmi"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78693fcdd618e0fc34af59c6b8efa9ac5d58c68df940beff4bedddb6acfe7c27"
+dependencies = [
+ "spin",
+ "wasmi_collections",
+ "wasmi_core",
+ "wasmi_ir",
+ "wasmparser",
+]
+
+[[package]]
+name = "wasmi_collections"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a8be2aa467cf2d29e96ff759472c36eeb44a3c81c67fc9cb76c9a24c519c557"
+dependencies = [
+ "string-interner",
+]
+
+[[package]]
+name = "wasmi_core"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69372d5fda3ea3d1e0aa6603c7888110e0187e88ea17cd8fc2e2df0a0e1f37fa"
+dependencies = [
+ "libm",
+]
+
+[[package]]
+name = "wasmi_ir"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f17b774caa13c618c7244f1ee51fe23c5e7b8538a471fa46d9949779758aed6"
+dependencies = [
+ "wasmi_core",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.228.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4abf1132c1fdf747d56bbc1bb52152400c70f336870f968b85e89ea422198ae3"
+dependencies = [
+ "bitflags 2.13.2",
+ "indexmap",
+]
+
 [[package]]
 name = "wayland-backend"
 version = "0.3.17"
@@ -10419,7 +10571,7 @@ dependencies = [
 [[package]]
 name = "winprint"
 version = "0.2.1"
-source = "git+https://github.com/storytold/winprint.rs?rev=72951d7455ebcab569fbd9386c513d3d9f53fb02#72951d7455ebcab569fbd9386c513d3d9f53fb02"
+source = "git+https://github.com/dotCooCoo/winprint.rs?rev=72951d7455ebcab569fbd9386c513d3d9f53fb02#72951d7455ebcab569fbd9386c513d3d9f53fb02"
 dependencies = [
  "flate2",
  "fmt-derive",
@@ -10654,12 +10806,6 @@ version = "0.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9440ea3e5aeabb0ac63af70daf835274065238cdd0cec83418f417eae38bacee"
 
-[[package]]
-name = "y4m"
-version = "0.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7a5a4b21e1a62b67a2970e6831bc091d7b87e119e7f9791aef9702e3bef04448"
-
 [[package]]
 name = "yeslogic-fontconfig-sys"
 version = "6.0.1"
diff --git a/Cargo.toml b/Cargo.toml
index 5ca3bf2ab..dd7607666 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -11,6 +11,8 @@ rust-version = "1.95"
 repository = "https://github.com/storytold/craft-libs"
 
 [workspace.dependencies]
+acadrust = "=0.6.6"
+log = "0.4"
 # internal: add each crate here as `craft-<name> = { path = "crates/<name>" }`
 craft-platform = { path = "crates/platform" }
 craft-aep = { path = "crates/aep" }
@@ -40,13 +42,20 @@ craft-dialogs = { path = "crates/dialogs" }
 craft-doc-binary = { path = "crates/doc-binary" }
 craft-docx = { path = "crates/docx" }
 craft-document-bundle = { path = "crates/document-bundle" }
+craft-designcraft-format = { path = "crates/designcraft-format" }
 craft-dxf = { path = "crates/dxf" }
 craft-drawingml = { path = "crates/drawingml" }
 craft-eps = { path = "crates/eps" }
 craft-file-formats = { path = "crates/file-formats" }
+craft-file-import = { path = "crates/file-import" }
+vectorcraft-doc = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
+vectorcraft-eps = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
+vectorcraft-geom = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
+vectorcraft-pathops = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
 craft-doc = { path = "crates/doc" }
 craft-docpath = { path = "crates/docpath" }
 craft-dpx = { path = "crates/dpx" }
+craft-dwg = { path = "crates/dwg" }
 craft-ecproj-format = { path = "crates/ecproj-format" }
 craft-figma-rest = { path = "crates/figma-rest" }
 craft-exr = { path = "crates/exr" }
@@ -70,6 +79,7 @@ craft-indd = { path = "crates/indd" }
 craft-jmap = { path = "crates/jmap" }
 craft-ical = { path = "crates/ical" }
 craft-jpeg = { path = "crates/jpeg" }
+craft-jxl = { path = "crates/jxl" }
 craft-kiwi = { path = "crates/kiwi" }
 craft-keymap = { path = "crates/keymap" }
 craft-assuan = { path = "crates/assuan" }
@@ -114,9 +124,12 @@ craft-raw = { path = "crates/raw" }
 craft-sheet = { path = "crates/sheet" }
 craft-sketch = { path = "crates/sketch" }
 craft-settings = { path = "crates/settings" }
+craft-scraft-format = { path = "crates/scraft-format" }
+craft-time = { path = "crates/time" }
 craft-silhouette-studio = { path = "crates/silhouette-studio" }
 craft-svg = { path = "crates/svg" }
 craft-stencilcraft-format = { path = "crates/stencilcraft-format" }
+craft-stencilcraft-document = { path = "crates/stencilcraft-document" }
 craft-svg-paths = { path = "crates/svg-paths" }
 craft-stream-codecs = { path = "crates/stream-codecs" }
 craft-text = { path = "crates/text" }
@@ -130,6 +143,7 @@ craft-vcard = { path = "crates/vcard" }
 craft-vectorcraft-format = { path = "crates/vectorcraft-format" }
 craft-vectordrawable = { path = "crates/vectordrawable" }
 craft-xls = { path = "crates/xls" }
+craft-xfl = { path = "crates/xfl" }
 craft-wordmodel = { path = "crates/wordmodel" }
 craft-xlsx = { path = "crates/xlsx" }
 indd = { git = "https://github.com/storytold/indd-utils", rev = "7f3060e5bce78d21ea70e0d5eacb96edce15dfbe" }
@@ -146,6 +160,8 @@ craft-web-host = { path = "crates/web-host" }
 craft-webp = { path = "crates/webp" }
 egui = { version = "0.37", default-features = false }
 md5 = { package = "md-5", version = "0.10", default-features = false }
+jxl-oxide = { version = "0.12", default-features = false }
+jixel = "=0.3.4"
 rayon = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
diff --git a/NOTICE b/NOTICE
index 10e0fcc19..e1cffb26c 100644
--- a/NOTICE
+++ b/NOTICE
@@ -5,6 +5,17 @@ Licensed under the MIT License or the Apache License, Version 2.0, at your optio
 
 Third-party material
 
+Optional DWG bridge
+
+`craft-dwg` uses `acadrust` 0.6.6 unmodified as a separate dependency for DWG reading and writing.
+It is licensed under the Mozilla Public License 2.0. The license text and upstream third-party
+notices are retained in `licenses/dwg/`; the crate is available from crates.io and
+https://github.com/hakanaktt/acadrust.
+
+The byte-level bridge source was moved from CADCraft `crates/dwg` at revision
+`664837df8925f932e90a7ae37c58d2f54e7a1320`. The bridge itself is MIT OR Apache-2.0; its only
+MPL-2.0 component is the unmodified `acadrust` dependency.
+
 This product bundles third-party material under its own licenses, listed below. The per-file
 list (author, source, license) is in ATTRIBUTION.md.
 
diff --git a/README.md b/README.md
index c79fa2aff..aa47358da 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,9 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit
   pages and version detection, and written back; and `model`, the drawing above the tags (header
   variables, tables, blocks, layouts, entities) and its writer (R12 to 2018), merged from CADCraft's and VectorCraft's readers. Bounded
   on hostile input. Mapping the model onto a document stays in each app.
+- [`craft-dwg`](crates/dwg/README.md): bounded byte-level DWG↔DXF conversion with diagnostics,
+  capped output and an optional child-process worker; the `acadrust` dependency remains isolated
+  behind bytes and is unavailable on wasm32 and FreeBSD/aarch64.
 - [`craft-ecproj-format`](crates/ecproj-format/README.md): the envelope of EffectCraft `.ecproj`
   project files: `savedBy`, the schema version and its check, and the file object with the
   project and its saved view as type parameters. The project model stays in EffectCraft.
@@ -203,6 +206,8 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit
   decoder is bounded and returns its partial output on damage. From PdfCraft; a PDF filter chain
   is built on it in `craft-pdf`.
 - [`craft-timeline`](crates/timeline/README.md): editorial timeline interchange: exact media time and SMPTE timecode, import/export reports, media path and `file://` URL handling, Avid Log Exchange (ALE) and CMX 3600 EDL documents, format detection. From FilmCraft.
+- [`craft-time`](crates/time/README.md): exact rational ticks and SMPTE time across media, with a `soundcraft` compatibility module retaining SoundCraft's sample-index timebase, tempo maps, grids and session serialization semantics.
+- [`craft-scraft-format`](crates/scraft-format/README.md): SoundCraft's typed `.scraft` session schema, versioned reader/writer, hostile-input validation, and `.scraftz` bundle reader/writer. Engine and UI mapping stays in SoundCraft.
 - [`craft-metadata`](crates/metadata/README.md): photo metadata, from LightCraft: EXIF (read and write,
   maker-note lens and focus point, every tag by name), IPTC-IIM, XMP packets (read, write, and a merge
   that keeps what another program wrote), GPX track logs, and the blocks that carry them in JPEG, PNG,
@@ -325,7 +330,8 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit
 - [`craft-sheet`](crates/sheet/README.md): spreadsheet vocabulary shared by `craft-xls`, `craft-xlsx` and `craft-ods`: cell positions and A1 text, cell values and error values, sheet-name quoting, Excel's built-in number formats and indexed colour palette. Not a file format; no dependencies.
 - [`craft-sf2`](crates/sf2/README.md): SoundFont 2 (`.sf2`) reader: the sample pool and, per preset, the key and velocity regions a note sounds, with tuning, loop points, pan, level and volume envelope resolved from the preset and instrument zones. Bounded on hostile input. From LoopCraft.
 - [`craft-silhouette-studio`](crates/silhouette-studio/src/lib.rs): bounded, fail-closed reader for Silhouette Studio `.studio` and `.studio3` documents: outlines, line colours and page size in millimetres. Protected designs are refused.
-- [`craft-stencilcraft-format`](crates/stencilcraft-format/README.md): the versioned `.stencilcraft` JSON wire schema and envelope: required members, version 1 defaults, optional fields, and header checks. The app retains its document model and domain validation.
+- [`craft-stencilcraft-format`](crates/stencilcraft-format/README.md): the versioned `.stencilcraft` JSON wire schema and envelope: required members, version 1 defaults, optional fields, and header checks.
+- `craft-stencilcraft-document`: StencilCraft's typed document model, geometry helpers, validation, and native `.stencilcraft` codec.
 - [`craft-sketch`](crates/sketch/README.md): clean-room reader for the `.sketch` container (Sketch 48 and newer): the ZIP archive, the version cut, `document.json`, the pages in document order and images, as the JSON the file holds. Bounded on hostile input. Carved from FigCraft.
 - [`craft-svg`](crates/svg/src/lib.rs): SVG. `sniff` recognises SVG and SVGZ data; `svgz` unpacks
   SVGZ within a byte limit, decodes UTF-8, UTF-16 and ISO 8859-1, and compresses; `guard` bounds
diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml
index 822c8a8ad..9b6200198 100644
--- a/crates/audio/Cargo.toml
+++ b/crates/audio/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "craft-audio"
-description = "Audio file I/O and codecs: WAV/AIFF read and write, FLAC encoder, AAC and ALAC decoders and encoders, AC-3/E-AC-3 decoder and encoder, MP3 decoder and encoder, Opus and MP1/MP2 decoders."
+description = "Audio file I/O and codecs: WAV/AIFF read and write, FLAC encoder, AAC and ALAC decoders and encoders, AC-3/E-AC-3 decoder and encoder, MP3 decoder and encoder, Opus decoder and encoder, MP1/MP2 decoders."
 version.workspace = true
 edition.workspace = true
 license.workspace = true
@@ -22,8 +22,8 @@ decode = ["decode-native", "symphonia"]
 decode-native = ["aac-decode", "alac-decode", "opus-decode", "ac3-decode", "mpa-decode", "mp3-decode", "craft-media/isobmff", "craft-media/matroska", "craft-media/ogg", "dep:log"]
 # The symphonia fallback for the formats with no native decoder yet.
 symphonia = ["decode-native", "dep:symphonia"]
-# Every encoder: the lossless file writers and the AAC, ALAC, AC-3/E-AC-3 and MP3 encoders.
-encode = ["lossless-encode", "aac-encode", "alac-encode", "ac3-encode", "eac3-encode", "mp3-encode"]
+# Every encoder: the lossless file writers and the AAC, ALAC, AC-3/E-AC-3, MP3 and Opus encoders.
+encode = ["lossless-encode", "aac-encode", "alac-encode", "ac3-encode", "eac3-encode", "mp3-encode", "opus-encode"]
 # Encode WAV/BWF/RF64, AIFF/AIFF-C and FLAC files.
 lossless-encode = ["pcm-encode", "flac-encode"]
 # Encode WAV/BWF/RF64 and AIFF/AIFF-C files.
@@ -34,6 +34,7 @@ flac-encode = ["craft-media/bitstream"]
 aac-decode = ["craft-media/bitstream"]
 aac-encode = ["craft-media/bitstream"]
 opus-decode = []
+opus-encode = []
 ac3-decode = ["craft-media/bitstream"]
 mpa-decode = ["craft-media/bitstream"]
 # MPEG-1/2 Layer III (MP3) decoder (`mp3::Decoder`).
diff --git a/crates/audio/README.md b/crates/audio/README.md
index 30f09ea57..518dbeb4c 100644
--- a/crates/audio/README.md
+++ b/crates/audio/README.md
@@ -1,7 +1,8 @@
 # craft-audio
 
 Audio file I/O and codecs for the Craft apps. Native implementations: WAV and AIFF read/write,
-FLAC encoder, AAC and ALAC decoders/encoders, AC-3/E-AC-3 decoder/encoder, MP3 decoder/encoder, Opus and MP1/MP2 decoders.
+FLAC encoder, AAC and ALAC decoders/encoders, AC-3/E-AC-3 decoder/encoder, MP3 decoder/encoder, Opus
+decoder/encoder, MP1/MP2 decoders.
 Formats without a native decoder are decoded by [symphonia](#symphonia), which is to be replaced
 by native decoders.
 
@@ -28,14 +29,14 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
 | `decode` | `decode`, `probe`, `Decoder`, `tracks`, `TrackDecoder`; every format in [Format support](#format-support) | `decode-native`, `symphonia` |
 | `decode-native` | the same, native formats only (others are `Unsupported`); `wav_pcm`, `aiff_pcm` (a file's integer PCM bit for bit, as `RawPcm`) | the six decoders below, craft-media `isobmff`/`matroska`/`ogg`, `log` |
 | `symphonia` | the fallback for formats with no native decoder; turning it on is the same as `decode` | `decode-native`, symphonia |
-| `encode` | every encoder: the WAV, AIFF and FLAC file writers, and the AAC, ALAC, AC-3/E-AC-3 and MP3 encoders | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode` |
+| `encode` | every encoder: the WAV, AIFF and FLAC file writers, and the AAC, ALAC, AC-3/E-AC-3, MP3 and Opus encoders | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode` |
 | `lossless-encode` | WAV, AIFF and FLAC writing | `pcm-encode`, `flac-encode` |
 | `pcm-encode` | `encode`, `FileEncoder` for WAV and AIFF; `wav_float_header`; `pcm_wav_file`, `pcm_wav_header`, `pcm_aiff_file`, `pcm_aiff_header` (minimal files around integer PCM bytes, for essence embedded in AAF / OMF) | none |
 | `flac-encode` | `encode`, `FileEncoder` for FLAC; `flac::Encoder`, the packet encoder for callers that mux FLAC themselves | craft-media `bitstream` |
 | `aac-decode`, `aac-encode` | `aac::Decoder`, `aac::Encoder`; with `aac-decode`, `aac::latm_config` / `latm_split` for LOAS / LATM frames (AAC in MPEG transport streams) | craft-media `bitstream` |
 | `alac-decode` | `alac::Decoder` | none |
 | `alac-encode` | `alac::Encoder` | none |
-| `opus-decode` | `opus::Decoder`/`StreamDecoder` | none |
+| `opus-decode`, `opus-encode` | `opus::Decoder`/`StreamDecoder`, `opus::Encoder` | none |
 | `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` |
 | `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder` | craft-media `bitstream` |
 | `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` |
@@ -264,6 +265,40 @@ Ls Rs) has no equivalent in that layout; passed unchanged, its channels go to th
 are a playable `.aac` file. To write MP4 or Matroska, pass the access units to craft-media's
 muxers ([MP4](../media/README.md#muxing), [Matroska](../media/README.md#muxing-1)).
 
+### Encode Opus
+
+```rust
+use craft_audio::opus::Encoder;
+
+let mut enc = Encoder::new(2, 128_000)?;            // channels, bits per second
+let frame_len = Encoder::FRAME_SIZE * 2;            // 20 ms, interleaved stereo
+let mut samples = buf.interleaved();                // 48 kHz audio
+// Silence after the audio flushes the encoder's delay (the pre-skip) and fills the last frame.
+let frames = samples.len() / 2 + enc.pre_skip() as usize;
+samples.resize(frames.div_ceil(Encoder::FRAME_SIZE) * frame_len, 0.0);
+let mut packets = Vec::new();
+for frame in samples.chunks_exact(frame_len) {
+    packets.push(enc.encode_float(frame)?);
+}
+let head = enc.opus_head();     // Matroska's CodecPrivate
+let pre_skip = enc.pre_skip();  // samples the player drops at the start
+```
+
+The encoder takes 48 kHz only, and craft-audio has no resampler.
+
+craft-media has no Ogg muxer, so `.opus` files cannot be written yet; Opus goes into
+Matroska/WebM or MP4:
+
+- **Matroska/WebM:** `head` is the track's `CodecPrivate`, and the pre-skip goes in
+  `TrackSpec::codec_delay_ns` (in nanoseconds at 48 kHz). The Matroska muxer cannot write
+  `DiscardPadding`, so the padding at the end stays in the file.
+- **MP4:** the sample entry takes an `isobmff::OpusConfig` (`dOps`) with the same fields as the
+  `OpusHead`: channels, pre-skip, input rate, gain and mapping family. `TrackConfig::media_start`
+  set to the pre-skip skips it. To drop the padding as well, give `TrackConfig::edits` one
+  `Edit` instead, which replaces the edit `media_start` makes: `media_time` the pre-skip (track
+  timescale), `segment_duration` the audio's length (movie timescale), `media_rate`
+  `0x0001_0000`.
+
 ### Waveform overviews
 
 ```rust
@@ -309,11 +344,12 @@ match craft_audio::decode(&bytes, None) {
 | AIFF, AIFF-C | native | native |
 | FLAC | symphonia | native |
 | AAC-LC | native | native |
-| HE-AAC v1/v2 | native, core only (see [Limits](#limits)) | — |
+| HE-AAC v1 | native (SBR) | — |
+| HE-AAC v2 | native, without parametric stereo (see [Limits](#limits)) | — |
 | ALAC | native | native, packets (`alac::Encoder`; no file writer) |
 | MP1, MP2 (MPEG audio Layer I/II) | native | — |
 | MP3 (Layer III) | native | native, frames (`mp3::Encoder`; the frames in a row are an `.mp3` file) |
-| Opus | native | — |
+| Opus | native | native |
 | AC-3, E-AC-3 | native | native packet encoder |
 | Vorbis, ADPCM, A-law, µ-law | symphonia | — |
 
@@ -329,10 +365,10 @@ match craft_audio::decode(&bytes, None) {
 
 ## Limits
 
-- HE-AAC: the AAC-LC core is decoded. `decode`, `Decoder` and `TrackDecoder` upsample it 2×;
-  `aac::Decoder` alone outputs the core rate. SBR is not reconstructed, so there is no content
-  above the core's Nyquist frequency.
-- HE-AAC v2: parametric stereo is not reconstructed either, so the mono core decodes as mono.
+- HE-AAC: `decode`, `Decoder` and `TrackDecoder` decode SBR at twice the core rate.
+  `aac::Decoder` outputs the core rate unless `set_sbr(true)` is called. Downsampled SBR (an
+  output rate equal to the core rate) plays the core alone.
+- HE-AAC v2: parametric stereo is not reconstructed, so the mono core decodes as mono, with SBR.
 - AAC: Main, SSR and LTP profiles, coupling channels and 960-sample frames are unsupported.
 - Raw ADTS: frames with several raw data blocks are unsupported: a stream of them is refused, and
   one among other frames decodes as silence of its length and counts as damaged, as does a frame
@@ -413,8 +449,8 @@ Each codec module's rustdoc lists the coding tools it implements.
 |---|---|---|---|
 | WAV, AIFF | Microsoft RIFF, Apple AIFF/AIFF-C | read: integer 8–32-bit, float 32/64-bit, `WAVE_FORMAT_EXTENSIBLE` masks, RF64/BW64, BWF `bext`, truncated files; write: 16/24/32-bit integer and 32-bit float, RF64 above 4 GiB, any layout, TPDF dither | round trips; hostile-input tests |
 | FLAC encoder | RFC 9639 | 16, 24, 32 bits; 1–8 channels, layouts decoders would not assume for the count as a `WAVEFORMATEXTENSIBLE_CHANNEL_MASK` comment; up to 655,350 Hz; LPC, stereo decorrelation, wasted bits, STREAMINFO MD5 | bit-exact through ffmpeg, STREAMINFO MD5 checked against ffmpeg |
-| AAC (`aac`) | ISO/IEC 14496-3 | AAC-LC decode and encode (CBR, VBR, ADTS), 1–8 channels; HE-AAC: see [Limits](#limits) | ffmpeg: ~135 dB SNR; PNS noise differs per sample at equal band energy |
-| Opus (`opus`) | RFC 6716, 8251, 7845 | decoder: SILK, hybrid, CELT, all frame sizes, PLC and FEC, multistream (`Decoder`) and single stream (`StreamDecoder`), 8–48 kHz output | all 36 RFC 8251 conformance cases |
+| AAC (`aac`) | ISO/IEC 14496-3; SBR tables from ETSI ES 201 980 Annex I | AAC-LC decode and encode (CBR, VBR, ADTS), 1–8 channels; HE-AAC (SBR) decode, see [Limits](#limits) | ffmpeg: ~135 dB SNR; PNS noise differs per sample at equal band energy. HE-AAC from AudioToolbox, 1–6 channels: same 962-sample delay as ffmpeg, ~54 dB SNR, high band level within 0.01 dB |
+| Opus (`opus`) | RFC 6716, 8251, 7845 | decoder: SILK, hybrid, CELT, all frame sizes, PLC and FEC, multistream (`Decoder`) and single stream (`StreamDecoder`), 8–48 kHz output; encoder (`Encoder`): SILK, hybrid, CELT, 48 kHz, 20 ms frames, mono or stereo | all 36 RFC 8251 conformance cases; encoder output through ffmpeg's two Opus decoders |
 | AC-3/E-AC-3 (`ac3`) | decoder: ATSC A/52:2012; encoder/programme API: ETSI TS 102 366 V1.4.1 | single-syncframe and complete-programme decoding; packet encoding through discrete 7.1 (see below) | decoder comparisons and encoder output through ffmpeg, CRC/channel/timing/bit-budget regressions; synthetic quality limitations below |
 | MP1/MP2 (`mpa`) | ISO/IEC 11172-3, 13818-3 | Layer I and II, MPEG-1/2/2.5, 8–48 kHz; also the Layer II rate/mode pairs the spec disallows (ffmpeg's default mono 384 kbit/s); no free format | ffmpeg-encoded streams, 73–84 dB SNR |
 | MP3 decoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, MPEG-1/2/2.5, 8–48 kHz, every bit rate, CBR and VBR; mono, stereo, dual channel, joint stereo (mid/side and intensity); long, short and mixed blocks; bit reservoir; CRC read, not checked; Xing / Info / VBRI and LAME tags; no free format (read through symphonia) | ffmpeg's float decoder: 127–131 dB SNR on LAME streams of every sampling frequency (CBR, VBR, CRC, no reservoir, transients with short blocks) and on this crate's encoder's; intensity stereo and mixed blocks through LAME frames edited to use them (112–131 dB) |
@@ -582,6 +618,7 @@ the full tests with ffmpeg and the vectors required.
 | MP3 decoder | written here, from ISO/IEC 11172-3 and 13818-3; shares the encoder's tables and the MP1/MP2 synthesis filter |
 | MP3 encoder | FilmCraft `filmcraft-mp3enc` [4bec22b](https://github.com/storytold/filmcraft/commit/4bec22bd03bd1d995c9cf72e02a284f96d3d72cd) |
 | ALAC | Apple's reference implementation [macosforge/alac@c38887c](https://github.com/macosforge/alac/tree/c38887c5c5e64a4b31108733bd79ca9b2496d987/codec), Copyright © 2011 Apple Inc., Apache-2.0; ported to Rust and modified (see the `alac` module docs and [NOTICE](../../NOTICE)) |
+| Opus encoder | EffectCraft `effectcraft-opusenc` [c618429](https://github.com/storytold/effectcraft/commit/c618429252587525a2a6d4b5bccbe4ec5261e1b9) |
 
 Where apps had overlapping implementations, the one that measured better was kept, with the
 tests of both:
@@ -598,7 +635,8 @@ For the apps switching from their own code; to be removed once all three have sw
 
 The codec modules' public items keep their names, so apps can re-export them
 (`pub use craft_audio::aac::*;`). Names kept only for that are `#[doc(hidden)]`:
-`ac3::Decoded` (now `ac3::Frame`), `aac::Upsample2x`, `aac::ProgramConfig::parse`,
+`ac3::Decoded` (now `ac3::Frame`), `opus::encoder::OpusEncoder` (now `opus::Encoder`),
+`aac::Upsample2x`, `aac::ProgramConfig::parse`,
 `aac::config_layout` and `aac::sample_rate_index`. What else an app adjusts:
 
 - `AudioInfo` has `container`, `codec`, `layout` and `damaged` instead of SoundCraft's `format`.
@@ -624,8 +662,10 @@ The codec modules' public items keep their names, so apps can re-export them
 - `TrackInfo::sample_rate` and `channels` are `Option`s.
 - Features are per codec. SoundCraft's `encode` (WAV, AIFF, FLAC) is now `lossless-encode`, made
   of `pcm-encode` (WAV, AIFF) and `flac-encode`. `encode` turns on every encoder, including AAC,
-  ALAC and AC-3/E-AC-3. Writing a format whose feature is off returns `AudioError::Unsupported`.
+  ALAC, AC-3/E-AC-3 and Opus. Writing a format whose feature is off returns `AudioError::Unsupported`.
 - AAC encoder settings it cannot use are `aac::Error::InvalidSettings` (`AudioError::Encode`).
+- The Opus encoder's constructors and `encode_float` return `Result` instead of panicking on an
+  invalid channel count, mode/bandwidth or frame length.
 - `TrackDecoder::decode` returns an error for a corrupt Opus packet, as for the other codecs;
   call `conceal`.
 - `FileEncoder::write` takes any per-channel slices, but refuses a block with missing channels or
diff --git a/crates/audio/src/aac/decoder.rs b/crates/audio/src/aac/decoder.rs
index 8c4d41300..825ebb23a 100644
--- a/crates/audio/src/aac/decoder.rs
+++ b/crates/audio/src/aac/decoder.rs
@@ -6,6 +6,7 @@ use crate::aac::config::{AudioSpecificConfig, ElementType, ProgramConfig};
 use crate::aac::huffman::{self, INTENSITY_HCB, INTENSITY_HCB2, NOISE_HCB, ZERO_HCB};
 use crate::aac::ics::{IcsInfo, WindowSequence};
 use crate::aac::mdct::{MdctScratch, WindowShape, mdct_long, mdct_short, window};
+use crate::aac::sbr;
 use crate::aac::tables::{pow43, pow43_table, sf_gain};
 use crate::aac::tns::{self, TnsData};
 use crate::aac::{Error, Result};
@@ -63,7 +64,14 @@ impl Scratch {
     }
 }
 
-/// AAC-LC decoder.
+/// Where the SBR data of a channel element sits in its access unit: the bit range of the fill
+/// element's payload after its extension type, and whether a CRC leads it.
+type SbrRef = (usize, usize, bool);
+
+/// An access unit's core output, and the SBR data of each layout entry.
+type Decoded = (Vec<Vec<f32>>, Vec<Option<SbrRef>>);
+
+/// AAC-LC decoder, with the SBR tool of HE-AAC when [`Decoder::set_sbr`] turns it on.
 #[derive(Clone)]
 pub struct Decoder {
     asc: AudioSpecificConfig,
@@ -75,6 +83,11 @@ pub struct Decoder {
     scratch: Scratch,
     /// A fill element carried SBR data (implicitly signalled HE-AAC).
     sbr_seen: bool,
+    /// The SBR decoder of each layout entry, when output is at twice the core rate.
+    sbr_out: Option<Vec<sbr::Element>>,
+    /// The layout `sbr_out` was built for. Kept apart from `layout`, so that an access unit whose
+    /// new program config fails (and whose layout is put back) leaves the SBR history alone.
+    sbr_layout: Vec<(ElementType, u8)>,
 }
 
 impl Decoder {
@@ -110,6 +123,8 @@ impl Decoder {
             noise_state: NOISE_SEED,
             scratch: Scratch::new(),
             sbr_seen: false,
+            sbr_out: None,
+            sbr_layout: Vec::new(),
         };
         d.set_layout(layout);
         Ok(d)
@@ -131,16 +146,27 @@ impl Decoder {
     pub fn config(&self) -> &AudioSpecificConfig {
         &self.asc
     }
-    /// Output sampling rate in Hz: the AAC-LC core rate.
+    /// Output sampling rate in Hz: the AAC-LC core rate, or twice it with [`Self::set_sbr`] on.
     pub fn sample_rate(&self) -> u32 {
-        self.asc.sample_rate
+        if self.sbr_out.is_some() { self.asc.sample_rate.saturating_mul(2) } else { self.asc.sample_rate }
     }
     /// Whether the stream is HE-AAC: SBR signalled in the `AudioSpecificConfig` (explicit) or SBR
-    /// data seen in a fill element of a decoded access unit (implicit). Only the AAC-LC core is
-    /// decoded, at [`Self::sample_rate`]; the SBR high band is not reconstructed.
+    /// data seen in a fill element of a decoded access unit (implicit). Without [`Self::set_sbr`],
+    /// only the AAC-LC core is decoded.
     pub fn sbr(&self) -> bool {
         self.asc.sbr || self.sbr_seen
     }
+    /// Decode HE-AAC at twice the core rate (`true`) or the AAC-LC core alone (`false`, the
+    /// default). With SBR on, [`Self::decode`] returns 2048 samples per channel: the core through
+    /// the SBR filter banks, delayed by [`SBR_DELAY`](crate::aac::SBR_DELAY) samples, with the high
+    /// band rebuilt from each frame's SBR data. Until the stream's first SBR header, and for a
+    /// frame whose SBR data is missing or damaged, the high band is empty. Parametric stereo
+    /// (HE-AAC v2) is not decoded: its mono core stays mono.
+    pub fn set_sbr(&mut self, on: bool) {
+        if on != self.sbr_out.is_some() {
+            self.sbr_out = on.then(Vec::new);
+        }
+    }
     /// Output channels of the current element layout.
     pub fn channels(&self) -> usize {
         self.channels.len()
@@ -158,30 +184,61 @@ impl Decoder {
             c.overlap.fill(0.0);
             c.prev_shape = WindowShape::Sine;
         }
+        for e in self.sbr_out.iter_mut().flatten() {
+            e.reset();
+        }
     }
 
     fn sf_index(&self) -> u8 {
         self.asc.sf_index
     }
 
-    /// Decode one access unit (one `raw_data_block`) into 1024 samples per channel. An access unit
-    /// that fails leaves the decoder as it was, but for [`Self::sbr`]: its damage, including a damaged
-    /// program config element, does not reach the access units after it.
+    /// Decode one access unit (one `raw_data_block`) into 1024 samples per channel (2048 with
+    /// [`Self::set_sbr`] on). An access unit that fails leaves the decoder as it was, but for
+    /// [`Self::sbr`]: its damage, including a damaged program config element, does not reach the
+    /// access units after it. Damaged SBR data alone does not fail it.
     pub fn decode(&mut self, au: &[u8]) -> Result<Vec<Vec<f32>>> {
         let before = (self.asc.pce.clone(), self.layout.clone(), self.offsets.clone(), self.channels.clone(), self.noise_state);
-        let decoded = self.decode_block(au, true);
-        if decoded.is_err() {
-            (self.asc.pce, self.layout, self.offsets, self.channels, self.noise_state) = before;
+        match self.decode_block(au, true) {
+            Ok((pcm, sbr_refs)) => Ok(self.apply_sbr(au, pcm, &sbr_refs)),
+            Err(e) => {
+                (self.asc.pce, self.layout, self.offsets, self.channels, self.noise_state) = before;
+                Err(e)
+            }
         }
-        decoded
     }
 
-    fn decode_block(&mut self, au: &[u8], allow_reconfig: bool) -> Result<Vec<Vec<f32>>> {
+    /// Run each layout entry's channels through its SBR decoder, when SBR is on.
+    fn apply_sbr(&mut self, au: &[u8], pcm: Vec<Vec<f32>>, refs: &[Option<SbrRef>]) -> Vec<Vec<f32>> {
+        let rate = self.sample_rate();
+        let Some(elements) = self.sbr_out.as_mut() else {
+            return pcm;
+        };
+        // a new layout (a program config element) starts the SBR decoders afresh: their history
+        // belongs to the old element order, even where the channel counts match
+        if elements.len() != self.layout.len() || self.sbr_layout != self.layout {
+            *elements = self.layout.iter().map(|l| sbr::Element::new(l.0.channels(), rate)).collect();
+            self.sbr_layout.clone_from(&self.layout);
+        }
+        let mut out = Vec::with_capacity(pcm.len());
+        for (i, e) in elements.iter_mut().enumerate() {
+            let first = self.offsets.get(i).copied().unwrap_or(0);
+            let core = pcm.get(first..first + e.channels()).unwrap_or_default();
+            let payload = refs.get(i).copied().flatten().map(|(start, end, crc)| sbr::Payload { data: au, start, end, crc });
+            out.extend(e.process(core, payload));
+        }
+        out
+    }
+
+    fn decode_block(&mut self, au: &[u8], allow_reconfig: bool) -> Result<Decoded> {
         let mut br = BitReader::new(au);
         let nch = self.channels.len();
         let mut saw_element = false;
         let mut out: Vec<Option<Vec<f32>>> = vec![None; nch];
         let mut used = vec![false; self.layout.len()];
+        // SBR data belongs to the single channel or pair element before its fill element
+        let mut sbr_refs: Vec<Option<SbrRef>> = vec![None; self.layout.len()];
+        let mut last_slot = None;
         loop {
             let id = br.read_bits(3)?;
             saw_element |= matches!(id, ID_SCE | ID_CPE | ID_LFE);
@@ -191,6 +248,7 @@ impl Decoder {
                     let ty = if id == ID_SCE { ElementType::Sce } else { ElementType::Lfe };
                     let slot = self.find_slot(ty, tag, &used)?;
                     used[slot] = true;
+                    last_slot = (id == ID_SCE).then_some(slot);
                     let mut ics = self.decode_ics(&mut br, None)?;
                     let ch = self.offsets[slot];
                     self.fill_noise(&mut ics, None);
@@ -200,6 +258,7 @@ impl Decoder {
                     let tag = br.read_bits(4)? as u8;
                     let slot = self.find_slot(ElementType::Cpe, tag, &used)?;
                     used[slot] = true;
+                    last_slot = Some(slot);
                     let ch = self.offsets[slot];
                     let [a, b] = self.decode_cpe(&mut br, ch)?;
                     out[ch] = Some(a);
@@ -237,8 +296,13 @@ impl Decoder {
                     }
                     if count > 0 {
                         let ext = br.read_bits(4)?;
-                        self.sbr_seen |= matches!(ext, EXT_SBR_DATA | EXT_SBR_DATA_CRC);
+                        let is_sbr = matches!(ext, EXT_SBR_DATA | EXT_SBR_DATA_CRC);
+                        self.sbr_seen |= is_sbr;
+                        let start = br.position();
                         br.skip(count * 8 - 4)?;
+                        if let (true, Some(slot)) = (is_sbr, last_slot.take()) {
+                            sbr_refs[slot] = Some((start, br.position(), ext == EXT_SBR_DATA_CRC));
+                        }
                     }
                 }
                 _ => break, // ID_END
@@ -251,7 +315,7 @@ impl Decoder {
         for o in out {
             res.push(o.ok_or(Error::Bitstream("access unit is missing a channel element"))?);
         }
-        Ok(res)
+        Ok((res, sbr_refs))
     }
 
     fn find_slot(&self, ty: ElementType, tag: u8, used: &[bool]) -> Result<usize> {
@@ -637,6 +701,85 @@ mod tests {
         assert_eq!(dec.sample_rate(), 22_050);
     }
 
+    /// With SBR on, an access unit decodes to 2048 samples, and over a silent core the high band
+    /// its SBR fill element describes is there; with SBR off, the core alone (silence).
+    #[test]
+    fn sbr_fill_elements_rebuild_the_high_band() {
+        let au = sbr_au(0);
+        // AAC-LC, 22.05 kHz, mono
+        let asc = AudioSpecificConfig::lc(7, 1);
+        let mut dec = Decoder::from_config(asc.clone()).unwrap();
+        let core = dec.decode(&au).unwrap();
+        assert_eq!((core[0].len(), dec.sample_rate()), (1024, 22_050));
+        assert!(dec.sbr() && core[0].iter().all(|&s| s == 0.0));
+        let mut dec = Decoder::from_config(asc).unwrap();
+        dec.set_sbr(true);
+        assert_eq!(dec.sample_rate(), 44_100);
+        let mut out = Vec::new();
+        for _ in 0..4 {
+            out.extend(dec.decode(&au).unwrap().remove(0));
+        }
+        assert_eq!(out.len(), 4 * 2048);
+        let rms = (out[2048..].iter().map(|s| s * s).sum::<f32>() / (out.len() - 2048) as f32).sqrt();
+        assert!(rms > 1e-4, "{rms}");
+    }
+
+    /// A program config that changes the layout restarts the SBR decoders, even where the
+    /// channel counts match, and one in an access unit that fails leaves their history alone: the
+    /// access units after it decode as if it had not been there.
+    #[test]
+    fn a_new_layout_restarts_sbr_and_a_failed_one_keeps_it() {
+        let au = sbr_au(0);
+        let one = ProgramConfig { front: vec![(false, 0)], ..Default::default() };
+        let six = ProgramConfig { front: vec![(false, 0), (true, 0)], back: vec![(true, 1)], lfe: vec![0], ..Default::default() };
+        let decoder = || {
+            let mut d = Decoder::from_config(AudioSpecificConfig { pce: Some(one.clone()), ..AudioSpecificConfig::lc(7, 0) }).unwrap();
+            d.set_sbr(true);
+            d
+        };
+        let (mut kept, mut failed) = (decoder(), decoder());
+        for _ in 0..3 {
+            assert_eq!(kept.decode(&au).unwrap(), failed.decode(&au).unwrap());
+        }
+        // the new layout's elements are missing from this access unit
+        assert!(failed.decode(&silent_au(Some(&six), &[(ID_SCE, 0)])).is_err());
+        for _ in 0..2 {
+            assert_eq!(kept.decode(&au).unwrap(), failed.decode(&au).unwrap());
+        }
+        // the same channel count under another tag is a new layout: the SBR decoder starts over,
+        // as in a decoder that had that layout from the start
+        let tag1 = ProgramConfig { front: vec![(false, 1)], ..Default::default() };
+        let mut fresh = Decoder::from_config(AudioSpecificConfig { pce: Some(tag1.clone()), ..AudioSpecificConfig::lc(7, 0) }).unwrap();
+        fresh.set_sbr(true);
+        kept.set_layout(tag1.layout());
+        assert_eq!(kept.decode(&sbr_au(1)).unwrap(), fresh.decode(&sbr_au(1)).unwrap());
+    }
+
+    /// One access unit of SCE `tag` with an SBR fill element of [`sbr::test_payload`] (44.1 kHz
+    /// output).
+    fn sbr_au(tag: u32) -> Vec<u8> {
+        let payload = sbr::test_payload(44_100, |_| 40, |_| 0).unwrap();
+        let mut bw = BitWriter::new();
+        bw.write_bits(ID_SCE, 3);
+        bw.write_bits(tag, 4);
+        bw.write_bits(0, 8 + 11 + 3); // global_gain, ics_info (max_sfb 0), no pulse/TNS/gain control
+        bw.write_bits(ID_FIL, 3);
+        let count = (4 + 8 * payload.len()).div_ceil(8);
+        if count < 15 {
+            bw.write_bits(count as u32, 4);
+        } else {
+            bw.write_bits(15, 4);
+            bw.write_bits((count - 14) as u32, 8);
+        }
+        bw.write_bits(EXT_SBR_DATA, 4);
+        for &b in &payload {
+            bw.write_bits(u32::from(b), 8);
+        }
+        bw.write_bits(0, 4);
+        bw.write_bits(ID_END, 3);
+        bw.finish()
+    }
+
     /// An access unit whose elements are all empty: `elements` are (id, tag), then ID_END.
     fn silent_au(pce: Option<&ProgramConfig>, elements: &[(u32, u32)]) -> Vec<u8> {
         let mut bw = BitWriter::new();
diff --git a/crates/audio/src/aac/huffman.rs b/crates/audio/src/aac/huffman.rs
index adac5c9c9..0c29673e7 100644
--- a/crates/audio/src/aac/huffman.rs
+++ b/crates/audio/src/aac/huffman.rs
@@ -62,12 +62,12 @@ const SUB: u32 = 1 << 31;
 /// entry with `SUB` set is `SUB | offset << 5 | width` and selects a sub-table of `1 << width`
 /// leaves indexed by the next `width` bits. An entry of 0 is a bit pattern that no codeword starts
 /// with (the codebooks are complete, so this does not occur).
-struct Lut {
+pub(crate) struct Lut {
     t: Vec<u32>,
 }
 
 impl Lut {
-    fn build(codes: &[(u32, u8)]) -> Lut {
+    pub(crate) fn build(codes: &[(u32, u8)]) -> Lut {
         let mut t = vec![0u32; 1 << L1];
         // sub-table width per first-level prefix
         let mut width = vec![0u32; 1 << L1];
@@ -103,7 +103,7 @@ impl Lut {
 
     /// The symbol of the codeword at the reader position; `Eof` if the codeword is cut off.
     #[inline]
-    fn decode(&self, br: &mut BitReader) -> Result<u32> {
+    pub(crate) fn decode(&self, br: &mut BitReader) -> Result<u32> {
         let bits = br.peek(32);
         let mut e = self.t[(bits >> (32 - L1)) as usize];
         if e & SUB != 0 {
diff --git a/crates/audio/src/aac/mod.rs b/crates/audio/src/aac/mod.rs
index 0a5f639a4..297aa7972 100644
--- a/crates/audio/src/aac/mod.rs
+++ b/crates/audio/src/aac/mod.rs
@@ -5,13 +5,13 @@
 //!   model, window switching, M/S, TNS, bit reservoir, CBR/VBR, 1–8 channels.
 //! - [`Decoder`] (feature `aac-decode`): `AudioSpecificConfig` + raw access units → planar f32.
 //!   Supports M/S, intensity stereo, PNS, TNS, pulse data, both window shapes and every window
-//!   sequence.
+//!   sequence, and the SBR tool of HE-AAC ([`Decoder::set_sbr`]).
 //! - [`latm_config`] / [`latm_split`] (feature `aac-decode`): the configuration and payload of
 //!   LOAS / LATM frames (AAC in MPEG transport streams), for the decoder.
 //!
-//! HE-AAC (SBR/PS), Main/SSR/LTP profiles, coupling channels and 960-sample frames are not
-//! supported; for HE-AAC only the AAC-LC core is decoded (at the core rate; [`Decoder::sbr`] says
-//! when).
+//! Parametric stereo (HE-AAC v2), Main/SSR/LTP profiles, coupling channels and 960-sample frames
+//! are not supported. HE-AAC decodes at twice the core rate with [`Decoder::set_sbr`] on
+//! ([`Decoder::sbr`] says when a stream uses SBR), and as its AAC-LC core otherwise.
 //!
 //! From FilmCraft's `filmcraft-aac` (storytold/filmcraft@8fda2f2). Public items keep their names,
 //! so FilmCraft can re-export this module.
@@ -53,6 +53,8 @@ mod ics;
 #[cfg(feature = "aac-decode")]
 mod latm;
 mod mdct;
+#[cfg(feature = "aac-decode")]
+mod sbr;
 mod tables;
 mod tns;
 
@@ -68,6 +70,12 @@ pub use latm::{LatmConfig, latm_config, latm_split};
 pub use mdct::WindowShape;
 pub use tables::{SAMPLE_RATES, sample_rate_index};
 
+/// Output samples by which [`Decoder`] with [`Decoder::set_sbr`] on delays the core: the SBR filter
+/// banks and the SBR frame's lag behind the core frame. HE-AAC encoders count it in the priming the
+/// container signals.
+#[cfg(feature = "aac-decode")]
+pub const SBR_DELAY: usize = sbr::DELAY;
+
 /// Samples per AAC-LC frame (per channel).
 pub const FRAME_LEN: usize = 1024;
 
@@ -197,9 +205,9 @@ const UPSAMPLE_DELAY: usize = 481;
 #[cfg(feature = "aac-decode")]
 const UPSAMPLE_HISTORY: usize = UPSAMPLE_DELAY + UPSAMPLE_HALF;
 
-/// 2× upsampler for HE-AAC. The decoder reconstructs the AAC-LC core at half the output rate and
-/// not yet the SBR high band, so the core is interpolated to the output rate: timing and pitch are
-/// right and the band above the core's Nyquist stays empty. Even outputs are the input samples,
+/// 2× upsampler: interpolates an AAC-LC core to twice its rate, leaving the band above the core's
+/// Nyquist empty. [`Decoder::set_sbr`] decodes HE-AAC with its high band instead; this stays for
+/// callers that want the core alone at the output rate. Even outputs are the input samples,
 /// odd ones a Blackman-windowed sinc half-band interpolation over 2 × `UPSAMPLE_HALF` inputs.
 /// The output is delayed by `UPSAMPLE_DELAY` input samples, as an SBR decoder's is; the state
 /// carries across packets, so a seek primed with the preceding packet gives the same samples as
diff --git a/crates/audio/src/aac/sbr/bitstream.rs b/crates/audio/src/aac/sbr/bitstream.rs
new file mode 100644
index 000000000..0e8e70c3a
--- /dev/null
+++ b/crates/audio/src/aac/sbr/bitstream.rs
@@ -0,0 +1,493 @@
+//! The SBR bitstream (ISO/IEC 14496-3 §4.4.2.8 syntax, §4.5.2.8 semantics): the header and the
+//! single and channel pair elements of an `EXT_SBR_DATA` fill element.
+
+use std::sync::OnceLock;
+
+use craft_media::bitstream::BitReader;
+
+use super::freq::FreqTables;
+use super::tables::{
+    F_ENV_1_5DB, F_ENV_3_0DB, F_ENV_BAL_1_5DB, F_ENV_BAL_3_0DB, T_ENV_1_5DB, T_ENV_3_0DB, T_ENV_BAL_1_5DB, T_ENV_BAL_3_0DB, T_NOISE_3_0DB,
+    T_NOISE_BAL_3_0DB,
+};
+use super::{Header, MAX_ENV};
+use crate::aac::huffman::Lut;
+use crate::aac::{Error, Result};
+
+/// `bs_frame_class`: fixed leading and trailing frame borders.
+pub(crate) const FIXFIX: u8 = 0;
+/// Fixed leading border, variable trailing border.
+pub(crate) const FIXVAR: u8 = 1;
+/// Variable leading border, fixed trailing border.
+pub(crate) const VARFIX: u8 = 2;
+/// Variable leading and trailing borders.
+pub(crate) const VARVAR: u8 = 3;
+
+/// SBR time slots per frame (`numTimeSlots`; two QMF slots each).
+const TIME_SLOTS: usize = 16;
+
+/// Decoding tables for the SBR Huffman codes, in [`Book`] order.
+fn luts() -> &'static [Lut; 10] {
+    static LUTS: OnceLock<[Lut; 10]> = OnceLock::new();
+    LUTS.get_or_init(|| {
+        [
+            Lut::build(&T_ENV_1_5DB),
+            Lut::build(&F_ENV_1_5DB),
+            Lut::build(&T_ENV_BAL_1_5DB),
+            Lut::build(&F_ENV_BAL_1_5DB),
+            Lut::build(&T_ENV_3_0DB),
+            Lut::build(&F_ENV_3_0DB),
+            Lut::build(&T_ENV_BAL_3_0DB),
+            Lut::build(&F_ENV_BAL_3_0DB),
+            Lut::build(&T_NOISE_3_0DB),
+            Lut::build(&T_NOISE_BAL_3_0DB),
+        ]
+    })
+}
+
+/// One of the SBR Huffman codes, and its largest absolute value.
+#[derive(Clone, Copy)]
+struct Book(usize, i32);
+
+const T_ENV_15: Book = Book(0, 60);
+const F_ENV_15: Book = Book(1, 60);
+const T_BAL_15: Book = Book(2, 24);
+const F_BAL_15: Book = Book(3, 24);
+const T_ENV_30: Book = Book(4, 31);
+const F_ENV_30: Book = Book(5, 31);
+const T_BAL_30: Book = Book(6, 12);
+const F_BAL_30: Book = Book(7, 12);
+const T_NOISE: Book = Book(8, 31);
+const T_NOISE_BAL: Book = Book(9, 12);
+
+fn huff(br: &mut BitReader, book: Book) -> Result<i32> {
+    Ok(luts()[book.0].decode(br)? as i32 - book.1)
+}
+
+fn bits(br: &mut BitReader, n: u32) -> Result<usize> {
+    Ok(br.read_bits(n)? as usize)
+}
+
+impl Header {
+    /// `sbr_header()`, with the defaults of the fields its extra parts leave out.
+    pub(crate) fn read(br: &mut BitReader) -> Result<Header> {
+        let amp_res = br.read_flag()?;
+        let start_freq = br.read_bits(4)? as u8;
+        let stop_freq = br.read_bits(4)? as u8;
+        let xover_band = br.read_bits(3)? as u8;
+        br.skip(2)?; // bs_reserved
+        let (extra_1, extra_2) = (br.read_flag()?, br.read_flag()?);
+        let mut h = Header {
+            amp_res,
+            start_freq,
+            stop_freq,
+            xover_band,
+            freq_scale: 2,
+            alter_scale: true,
+            noise_bands: 2,
+            limiter_bands: 2,
+            limiter_gains: 2,
+            interpol_freq: true,
+            smoothing_mode: true,
+        };
+        if extra_1 {
+            h.freq_scale = br.read_bits(2)? as u8;
+            h.alter_scale = br.read_flag()?;
+            h.noise_bands = br.read_bits(2)? as u8;
+        }
+        if extra_2 {
+            h.limiter_bands = br.read_bits(2)? as u8;
+            h.limiter_gains = br.read_bits(2)? as u8;
+            h.interpol_freq = br.read_flag()?;
+            h.smoothing_mode = br.read_flag()?;
+        }
+        Ok(h)
+    }
+}
+
+/// The time/frequency grid of one channel in one frame (`sbr_grid()`, §4.6.18.3.3).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct Grid {
+    pub(crate) class: u8,
+    /// Envelopes (1 to 5).
+    pub(crate) num_env: usize,
+    /// Envelope borders in time slots; `t_env[num_env]` may reach past the frame (up to 19).
+    pub(crate) t_env: [usize; MAX_ENV + 1],
+    /// Noise floors (1 or 2).
+    pub(crate) num_noise: usize,
+    /// Noise floor borders.
+    pub(crate) t_noise: [usize; 3],
+    /// High frequency resolution per envelope.
+    pub(crate) freq_res: [bool; MAX_ENV],
+    /// The transient envelope `l_A`, if any (it may be `num_env`: the next frame's first).
+    pub(crate) la: Option<usize>,
+    /// 3 dB envelope steps (the header's choice, but 1.5 dB for a single FIXFIX envelope).
+    pub(crate) amp_res: bool,
+}
+
+/// `ceil(log2(num_env + 1))`: the width of `bs_pointer`.
+fn pointer_bits(num_env: usize) -> u32 {
+    usize::BITS - num_env.leading_zeros()
+}
+
+fn read_rel(br: &mut BitReader, n: usize) -> Result<[usize; 3]> {
+    let mut rel = [0; 3];
+    for r in rel.iter_mut().take(n) {
+        *r = 2 * bits(br, 2)? + 2;
+    }
+    Ok(rel)
+}
+
+impl Grid {
+    fn read(br: &mut BitReader, amp_res: bool) -> Result<Grid> {
+        let bad = || Error::Bitstream("invalid SBR time grid");
+        let class = br.read_bits(2)? as u8;
+        let mut t = [0i64; MAX_ENV + 1];
+        let mut freq_res = [false; MAX_ENV];
+        let (n, pointer) = match class {
+            FIXFIX => {
+                let n = 1usize << br.read_bits(2)?;
+                if n > 4 {
+                    return Err(bad());
+                }
+                freq_res = [br.read_flag()?; MAX_ENV];
+                for (l, t) in t.iter_mut().enumerate().take(n + 1) {
+                    *t = (l * TIME_SLOTS / n) as i64;
+                }
+                (n, 0)
+            }
+            FIXVAR | VARFIX => {
+                let abs = bits(br, 2)?;
+                let rels = bits(br, 2)?;
+                let n = rels + 1;
+                let rel = read_rel(br, rels)?;
+                let pointer = bits(br, pointer_bits(n))?;
+                for l in 0..n {
+                    freq_res[if class == FIXVAR { n - 1 - l } else { l }] = br.read_flag()?;
+                }
+                if class == FIXVAR {
+                    t[n] = (abs + TIME_SLOTS) as i64;
+                    for l in (1..n).rev() {
+                        t[l] = t[l + 1] - rel[n - 1 - l] as i64;
+                    }
+                } else {
+                    (t[0], t[n]) = (abs as i64, TIME_SLOTS as i64);
+                    for l in 1..n {
+                        t[l] = t[l - 1] + rel[l - 1] as i64;
+                    }
+                }
+                (n, pointer)
+            }
+            _ => {
+                let abs0 = bits(br, 2)?;
+                let abs1 = bits(br, 2)? + TIME_SLOTS;
+                let (rels0, rels1) = (bits(br, 2)?, bits(br, 2)?);
+                let n = rels0 + rels1 + 1;
+                if n > MAX_ENV {
+                    return Err(bad());
+                }
+                let (rel0, rel1) = (read_rel(br, rels0)?, read_rel(br, rels1)?);
+                let pointer = bits(br, pointer_bits(n))?;
+                for r in freq_res.iter_mut().take(n) {
+                    *r = br.read_flag()?;
+                }
+                (t[0], t[n]) = (abs0 as i64, abs1 as i64);
+                for l in 1..=rels0 {
+                    t[l] = t[l - 1] + rel0[l - 1] as i64;
+                }
+                for l in (rels0 + 1..n).rev() {
+                    t[l] = t[l + 1] - rel1[n - 1 - l] as i64;
+                }
+                (n, pointer)
+            }
+        };
+        if t[0] < 0 || t[..=n].windows(2).any(|w| w[0] >= w[1]) {
+            return Err(bad());
+        }
+        // l_A: in ISO/IEC 14496-3 a VARFIX pointer of 1, like 0, marks no transient envelope
+        let la = match (pointer, class) {
+            (0, _) | (1, VARFIX) => None,
+            (p, FIXVAR | VARVAR) => Some((n + 1).checked_sub(p).ok_or_else(bad)?),
+            (p, _) => Some(p - 1),
+        };
+        if la.is_some_and(|la| la > n) {
+            return Err(bad());
+        }
+        let t_env: [usize; MAX_ENV + 1] = std::array::from_fn(|i| t[i] as usize);
+        let (num_noise, t_noise) = if n == 1 {
+            (1, [t_env[0], t_env[1], 0])
+        } else {
+            let middle = match (class, pointer) {
+                (FIXFIX, _) => n / 2,
+                (VARFIX, 0) => 1,
+                (VARFIX, 1) => n - 1,
+                (VARFIX, p) => p - 1,
+                (_, 0 | 1) => n - 1,
+                (_, p) => (n + 1).checked_sub(p).ok_or_else(bad)?,
+            };
+            if middle == 0 || middle >= n {
+                return Err(bad());
+            }
+            (2, [t_env[0], t_env[middle], t_env[n]])
+        };
+        Ok(Grid { class, num_env: n, t_env, num_noise, t_noise, freq_res, la, amp_res: amp_res && !(class == FIXFIX && n == 1) })
+    }
+}
+
+/// The data of one channel as transmitted: delta-coded envelope and noise floor values (the
+/// first frequency-coded value of each is absolute), not yet scaled for a balance channel.
+#[derive(Clone, Debug)]
+pub(crate) struct ChannelData {
+    pub(crate) grid: Grid,
+    pub(crate) df_env: [bool; MAX_ENV],
+    pub(crate) df_noise: [bool; 2],
+    pub(crate) invf: [u8; 5],
+    pub(crate) env: [[i32; 64]; MAX_ENV],
+    pub(crate) noise: [[i32; 5]; 2],
+    /// `bs_add_harmonic` per high-resolution band, when `bs_add_harmonic_flag` is set.
+    pub(crate) harmonic: Option<[bool; 64]>,
+}
+
+impl ChannelData {
+    fn new(grid: Grid) -> ChannelData {
+        ChannelData {
+            grid,
+            df_env: [false; MAX_ENV],
+            df_noise: [false; 2],
+            invf: [0; 5],
+            env: [[0; 64]; MAX_ENV],
+            noise: [[0; 5]; 2],
+            harmonic: None,
+        }
+    }
+
+    fn read_dtdf(&mut self, br: &mut BitReader) -> Result<()> {
+        for d in self.df_env.iter_mut().take(self.grid.num_env) {
+            *d = br.read_flag()?;
+        }
+        for d in self.df_noise.iter_mut().take(self.grid.num_noise) {
+            *d = br.read_flag()?;
+        }
+        Ok(())
+    }
+
+    fn read_invf(&mut self, br: &mut BitReader, t: &FreqTables) -> Result<()> {
+        for m in self.invf.iter_mut().take(t.n_q()) {
+            *m = br.read_bits(2)? as u8;
+        }
+        Ok(())
+    }
+
+    /// `sbr_envelope()`; `balance` for the second channel of a coupled pair.
+    fn read_envelope(&mut self, br: &mut BitReader, t: &FreqTables, balance: bool) -> Result<()> {
+        let (t_book, f_book, start_bits) = match (self.grid.amp_res, balance) {
+            (false, false) => (T_ENV_15, F_ENV_15, 7),
+            (false, true) => (T_BAL_15, F_BAL_15, 6),
+            (true, false) => (T_ENV_30, F_ENV_30, 6),
+            (true, true) => (T_BAL_30, F_BAL_30, 5),
+        };
+        for l in 0..self.grid.num_env {
+            let n = t.bands(self.grid.freq_res[l]).len() - 1;
+            let row = &mut self.env[l];
+            if self.df_env[l] {
+                for v in row.iter_mut().take(n) {
+                    *v = huff(br, t_book)?;
+                }
+            } else {
+                row[0] = br.read_bits(start_bits)? as i32;
+                for v in row.iter_mut().take(n).skip(1) {
+                    *v = huff(br, f_book)?;
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// `sbr_noise()`.
+    fn read_noise(&mut self, br: &mut BitReader, t: &FreqTables, balance: bool) -> Result<()> {
+        let (t_book, f_book) = if balance { (T_NOISE_BAL, F_BAL_30) } else { (T_NOISE, F_ENV_30) };
+        for l in 0..self.grid.num_noise {
+            let row = &mut self.noise[l];
+            if self.df_noise[l] {
+                for v in row.iter_mut().take(t.n_q()) {
+                    *v = huff(br, t_book)?;
+                }
+            } else {
+                row[0] = br.read_bits(5)? as i32;
+                for v in row.iter_mut().take(t.n_q()).skip(1) {
+                    *v = huff(br, f_book)?;
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// `bs_add_harmonic_flag` and `sbr_sinusoidal_coding()`.
+    fn read_harmonics(&mut self, br: &mut BitReader, t: &FreqTables) -> Result<()> {
+        if br.read_flag()? {
+            let mut h = [false; 64];
+            for v in h.iter_mut().take(t.n_high()) {
+                *v = br.read_flag()?;
+            }
+            self.harmonic = Some(h);
+        }
+        Ok(())
+    }
+}
+
+/// Skip `bs_extended_data` (parametric stereo, for one, is not decoded).
+fn skip_extended(br: &mut BitReader) -> Result<()> {
+    if br.read_flag()? {
+        let mut count = bits(br, 4)?;
+        if count == 15 {
+            count += bits(br, 8)?;
+        }
+        br.skip(8 * count)?;
+    }
+    Ok(())
+}
+
+/// The SBR data of one channel element.
+#[derive(Clone, Debug)]
+pub(crate) struct Frame {
+    /// The pair codes its second channel as a balance against the first.
+    pub(crate) coupling: bool,
+    pub(crate) channels: Vec<ChannelData>,
+}
+
+/// `sbr_single_channel_element()` (`channels` 1) or `sbr_channel_pair_element()` (2).
+pub(crate) fn read_data(br: &mut BitReader, t: &FreqTables, amp_res: bool, channels: usize) -> Result<Frame> {
+    if br.read_flag()? {
+        br.skip(4 * channels)?; // bs_reserved
+    }
+    if channels == 1 {
+        let mut c = ChannelData::new(Grid::read(br, amp_res)?);
+        c.read_dtdf(br)?;
+        c.read_invf(br, t)?;
+        c.read_envelope(br, t, false)?;
+        c.read_noise(br, t, false)?;
+        c.read_harmonics(br, t)?;
+        skip_extended(br)?;
+        return Ok(Frame { coupling: false, channels: vec![c] });
+    }
+    let coupling = br.read_flag()?;
+    let (mut a, mut b);
+    if coupling {
+        a = ChannelData::new(Grid::read(br, amp_res)?);
+        b = ChannelData::new(a.grid.clone());
+        a.read_dtdf(br)?;
+        b.read_dtdf(br)?;
+        a.read_invf(br, t)?;
+        b.invf = a.invf;
+        a.read_envelope(br, t, false)?;
+        a.read_noise(br, t, false)?;
+        b.read_envelope(br, t, true)?;
+        b.read_noise(br, t, true)?;
+    } else {
+        a = ChannelData::new(Grid::read(br, amp_res)?);
+        b = ChannelData::new(Grid::read(br, amp_res)?);
+        a.read_dtdf(br)?;
+        b.read_dtdf(br)?;
+        a.read_invf(br, t)?;
+        b.read_invf(br, t)?;
+        a.read_envelope(br, t, false)?;
+        b.read_envelope(br, t, false)?;
+        a.read_noise(br, t, false)?;
+        b.read_noise(br, t, false)?;
+    }
+    a.read_harmonics(br, t)?;
+    b.read_harmonics(br, t)?;
+    skip_extended(br)?;
+    Ok(Frame { coupling, channels: vec![a, b] })
+}
+
+#[cfg(test)]
+mod tests {
+    use craft_media::bitstream::BitWriter;
+
+    use super::*;
+
+    /// Every SBR Huffman table is a complete prefix code, with the shortest codeword for a zero
+    /// delta, and its decoder reads back every codeword.
+    #[test]
+    fn huffman_tables_are_complete_prefix_codes() {
+        let tables: [&[(u32, u8)]; 10] = [
+            &T_ENV_1_5DB,
+            &F_ENV_1_5DB,
+            &T_ENV_BAL_1_5DB,
+            &F_ENV_BAL_1_5DB,
+            &T_ENV_3_0DB,
+            &F_ENV_3_0DB,
+            &T_ENV_BAL_3_0DB,
+            &F_ENV_BAL_3_0DB,
+            &T_NOISE_3_0DB,
+            &T_NOISE_BAL_3_0DB,
+        ];
+        let lavs = [60, 60, 24, 24, 31, 31, 12, 12, 31, 12];
+        for (i, (codes, lav)) in tables.iter().zip(lavs).enumerate() {
+            assert_eq!(codes.len(), 2 * lav + 1, "table {i}");
+            let max = u32::from(codes.iter().map(|c| c.1).max().unwrap());
+            assert_eq!(codes.iter().map(|&(_, l)| 1u64 << (max - u32::from(l))).sum::<u64>(), 1 << max, "table {i}: Kraft sum");
+            let shortest = codes.iter().map(|c| c.1).min().unwrap();
+            assert_eq!(codes[lav].1, shortest, "table {i}");
+            for (sym, &(code, len)) in codes.iter().enumerate() {
+                let mut bw = BitWriter::new();
+                bw.write_bits(code, u32::from(len));
+                bw.write_bits(0x5A5A5A, 24);
+                let data = bw.finish();
+                let mut br = BitReader::new(&data);
+                assert_eq!(huff(&mut br, Book(i, lav as i32)).unwrap(), sym as i32 - lav as i32, "table {i}");
+                assert_eq!(br.position(), usize::from(len));
+            }
+        }
+    }
+
+    fn grid(bits: &[(u32, u32)]) -> Result<Grid> {
+        let mut bw = BitWriter::new();
+        for &(v, n) in bits {
+            bw.write_bits(v, n);
+        }
+        bw.write_bits(0, 16);
+        let data = bw.finish();
+        Grid::read(&mut BitReader::new(&data), true)
+    }
+
+    /// The four frame classes give the borders, noise floors and transient envelope of
+    /// §4.6.18.3.3; a FIXFIX frame of one envelope uses 1.5 dB steps.
+    #[test]
+    fn grids_of_each_frame_class() {
+        // FIXFIX, 4 envelopes, high resolution
+        let g = grid(&[(FIXFIX as u32, 2), (2, 2), (1, 1)]).unwrap();
+        assert_eq!((g.num_env, &g.t_env[..5], g.num_noise, g.t_noise, g.la, g.amp_res), (4, &[0, 4, 8, 12, 16][..], 2, [0, 8, 16], None, true));
+        let g = grid(&[(FIXFIX as u32, 2), (0, 2), (0, 1)]).unwrap();
+        assert_eq!((g.num_env, g.t_noise, g.amp_res), (1, [0, 16, 0], false));
+        // FIXVAR: trailing border 16 + 2, two relative borders (4, 2) back from it, pointer 1,
+        // resolutions sent last envelope first
+        let g = grid(&[(FIXVAR as u32, 2), (2, 2), (2, 2), (1, 2), (0, 2), (1, 2), (0, 1), (1, 1), (1, 1)]).unwrap();
+        assert_eq!((g.num_env, &g.t_env[..4]), (3, &[0, 12, 14, 18][..]));
+        assert_eq!((g.la, g.t_noise, g.freq_res[..3].to_vec()), (Some(3), [0, 14, 18], vec![true, true, false]));
+        // VARFIX: leading border 1, relative 2, pointer 2: l_A = 1
+        let g = grid(&[(VARFIX as u32, 2), (1, 2), (1, 2), (0, 2), (2, 2), (1, 1), (0, 1)]).unwrap();
+        assert_eq!((g.num_env, &g.t_env[..3], g.la, g.t_noise), (2, &[1, 3, 16][..], Some(1), [1, 3, 16]));
+        // the same with pointer 1: no transient envelope, the noise floors still split at 3
+        let g = grid(&[(VARFIX as u32, 2), (1, 2), (1, 2), (0, 2), (1, 2), (1, 1), (0, 1)]).unwrap();
+        assert_eq!((g.la, g.t_noise), (None, [1, 3, 16]));
+        // VARVAR: 1 .. 17 with one border from each end
+        let g = grid(&[(VARVAR as u32, 2), (1, 2), (1, 2), (1, 2), (1, 2), (0, 2), (0, 2), (0, 2), (0, 1), (0, 1), (0, 1)]).unwrap();
+        assert_eq!((g.num_env, &g.t_env[..4], g.la), (3, &[1, 3, 15, 17][..], None));
+    }
+
+    /// Grids whose borders do not increase, too many envelopes and a pointer past the envelopes
+    /// are refused.
+    #[test]
+    fn invalid_grids_are_refused() {
+        // FIXFIX with 8 envelopes
+        assert!(grid(&[(FIXFIX as u32, 2), (3, 2), (0, 1)]).is_err());
+        // VARVAR with 7 envelopes
+        assert!(grid(&[(VARVAR as u32, 2), (0, 2), (0, 2), (3, 2), (3, 2)]).is_err());
+        // FIXVAR whose relative borders run back past the start: 16 - (8 + 8 + 8)
+        assert!(grid(&[(FIXVAR as u32, 2), (0, 2), (3, 2), (3, 2), (3, 2), (3, 2), (0, 3), (0, 4)]).is_err());
+        // VARFIX, 2 envelopes, pointer 3: the middle border would be the trailing one
+        assert!(grid(&[(VARFIX as u32, 2), (0, 2), (1, 2), (0, 2), (3, 2), (0, 1), (0, 1)]).is_err());
+    }
+}
diff --git a/crates/audio/src/aac/sbr/freq.rs b/crates/audio/src/aac/sbr/freq.rs
new file mode 100644
index 000000000..7bb372dc4
--- /dev/null
+++ b/crates/audio/src/aac/sbr/freq.rs
@@ -0,0 +1,372 @@
+//! Frequency band tables (ISO/IEC 14496-3 §4.6.18.3.2) and the patches and limiter bands built on
+//! them (§4.6.18.6.3, §4.6.18.7.3). Every table holds QMF channel borders.
+
+use super::Header;
+
+/// The most patches the HF generator may build.
+const MAX_PATCHES: usize = 5;
+
+/// The tables of one SBR header at one output rate.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct FreqTables {
+    /// First QMF channel of the master table (the start of the SBR range before the crossover).
+    pub(crate) k0: usize,
+    /// First QMF channel of the SBR range.
+    pub(crate) kx: usize,
+    /// Channels in the SBR range (`kx + m` is its end).
+    pub(crate) m: usize,
+    /// High-resolution envelope bands (`n_high + 1` borders).
+    pub(crate) high: Vec<usize>,
+    /// Low-resolution envelope bands.
+    pub(crate) low: Vec<usize>,
+    /// Noise floor bands (1 to 5).
+    pub(crate) noise: Vec<usize>,
+    /// Limiter bands.
+    pub(crate) lim: Vec<usize>,
+    /// `(first source channel, channels)` of each patch, in order from `kx` up.
+    pub(crate) patches: Vec<(usize, usize)>,
+}
+
+/// Round half up, as the specification's `NINT`.
+fn nint(x: f64) -> i64 {
+    (x + 0.5).floor() as i64
+}
+
+/// The start channel offsets of `bs_start_freq`, by output rate (§4.6.18.3.2.1).
+fn start_offsets(fs: u32) -> &'static [i8; 16] {
+    match fs {
+        0..=16_000 => &[-8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7],
+        16_001..=22_050 => &[-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13],
+        22_051..=24_000 => &[-5, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13, 16],
+        24_001..=32_000 => &[-6, -4, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13, 16],
+        32_001..=64_000 => &[-4, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13, 16, 20],
+        _ => &[-2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13, 16, 20, 24],
+    }
+}
+
+/// `NINT(f · 128 / fs)` for the 3/4/5 kHz (start) or 6/8/10 kHz (stop) minimum at `fs`.
+fn min_channel(fs: u32, low: f64, mid: f64, high: f64) -> i64 {
+    let f = if fs < 32_000 {
+        low
+    } else if fs < 64_000 {
+        mid
+    } else {
+        high
+    };
+    nint(f * 128.0 / f64::from(fs))
+}
+
+/// The start and stop channels `k0`, `k2` of the master table.
+fn start_stop(h: &Header, fs: u32) -> Option<(usize, usize)> {
+    let k0 = min_channel(fs, 3000.0, 4000.0, 5000.0) + i64::from(start_offsets(fs)[usize::from(h.start_freq & 15)]);
+    let k2 = match h.stop_freq {
+        14 => 2 * k0,
+        15 => 3 * k0,
+        s => {
+            let stop_min = min_channel(fs, 6000.0, 8000.0, 10_000.0);
+            if stop_min <= 0 {
+                return None;
+            }
+            let ratio = 64.0 / stop_min as f64;
+            let at = |p: i64| nint(stop_min as f64 * ratio.powf(p as f64 / 13.0));
+            let mut dk: Vec<i64> = (0..13).map(|p| at(p + 1) - at(p)).collect();
+            dk.sort_unstable();
+            stop_min + dk.iter().take(usize::from(s)).sum::<i64>()
+        }
+    }
+    .min(64);
+    // the low band reaches only the analysis bank's 32 channels (`kx` is checked against them
+    // once the crossover is known)
+    (1..=32).contains(&k0).then_some(())?;
+    (k2 > k0).then_some((k0 as usize, k2 as usize))
+}
+
+/// The master table for `bs_freq_scale` 0: bands of one or two channels.
+fn master_linear(k0: usize, k2: usize, alter_scale: bool) -> Option<Vec<usize>> {
+    let (dk, bands) = if alter_scale { (2, 2 * nint((k2 - k0) as f64 / 4.0) as usize) } else { (1, 2 * ((k2 - k0) / 2)) };
+    if bands == 0 {
+        return None;
+    }
+    let mut v = vec![dk as i64; bands];
+    let mut diff = k2 as i64 - (k0 + bands * dk) as i64;
+    // take the difference from the lowest bands (too wide) or give it to the highest (too narrow)
+    let mut k = if diff < 0 { 0 } else { bands - 1 };
+    while diff != 0 {
+        let step = if diff < 0 { 1 } else { -1 };
+        *v.get_mut(k)? -= step;
+        diff += step;
+        k = if step == 1 { k + 1 } else { k.checked_sub(1)? };
+    }
+    cumulative(k0, &v)
+}
+
+/// The borders `start, start + d[0], …`; `None` unless every band is at least a channel wide.
+fn cumulative(start: usize, d: &[i64]) -> Option<Vec<usize>> {
+    let mut out = Vec::with_capacity(d.len() + 1);
+    out.push(start);
+    let mut at = start as i64;
+    for &d in d {
+        if d <= 0 {
+            return None;
+        }
+        at += d;
+        out.push(at as usize);
+    }
+    Some(out)
+}
+
+/// The band widths of `2 · NINT(bands · log2(hi / lo) / (2 · warp))` logarithmic bands.
+fn log_widths(lo: usize, hi: usize, bands: f64, warp: f64) -> Vec<i64> {
+    let ratio = hi as f64 / lo as f64;
+    let n = 2 * nint(bands * ratio.log2() / (2.0 * warp));
+    let at = |k: i64| nint(lo as f64 * ratio.powf(k as f64 / n as f64));
+    let mut d: Vec<i64> = (0..n.max(0)).map(|k| at(k + 1) - at(k)).collect();
+    d.sort_unstable();
+    d
+}
+
+/// The master table for `bs_freq_scale` 1–3: 12, 10 or 8 bands per octave, warped above
+/// `2 · k0` by `bs_alter_scale`.
+fn master_log(k0: usize, k2: usize, freq_scale: u8, alter_scale: bool) -> Option<Vec<usize>> {
+    let bands = [12.0, 10.0, 8.0][usize::from(freq_scale.clamp(1, 3) - 1)];
+    let two_regions = k2 as f64 / k0 as f64 > 2.2449;
+    let k1 = if two_regions { 2 * k0 } else { k2 };
+    let d0 = log_widths(k0, k1, bands, 1.0);
+    let mut table = cumulative(k0, &d0)?;
+    if table.len() < 2 {
+        return None;
+    }
+    if two_regions {
+        let mut d1 = log_widths(k1, k2, bands, if alter_scale { 1.3 } else { 1.0 });
+        let max0 = d0.iter().copied().max()?;
+        if d1.first().is_some_and(|&d| d < max0) {
+            // widen the first upper band to the widest lower one, at the cost of the last
+            let change = max0 - d1[0];
+            d1[0] = max0;
+            *d1.last_mut()? -= change;
+            d1.sort_unstable();
+        }
+        table.extend(cumulative(k1, &d1)?.into_iter().skip(1));
+    }
+    Some(table)
+}
+
+impl FreqTables {
+    /// The tables of `h` at output rate `fs`, or `None` if the header asks for an invalid layout.
+    pub(crate) fn new(h: &Header, fs: u32) -> Option<FreqTables> {
+        let (k0, k2) = start_stop(h, fs)?;
+        let master = if h.freq_scale == 0 { master_linear(k0, k2, h.alter_scale)? } else { master_log(k0, k2, h.freq_scale, h.alter_scale)? };
+        let n_master = master.len().checked_sub(1)?;
+        let xover = usize::from(h.xover_band);
+        if xover >= n_master {
+            return None;
+        }
+        let high: Vec<usize> = master.get(xover..)?.to_vec();
+        let n_high = high.len() - 1;
+        let (kx, end) = (high[0], *high.last()?);
+        if kx > 32 || end > 64 || end <= kx {
+            return None;
+        }
+        let m = end - kx;
+        // every other border, keeping the first (and the second when the count is odd)
+        let n_low = n_high - n_high / 2;
+        let low: Vec<usize> = (0..=n_low).map(|k| high[if k == 0 { 0 } else { 2 * k - (n_high & 1) }]).collect();
+        let n_q = if h.noise_bands == 0 { 1 } else { (nint(f64::from(h.noise_bands) * (end as f64 / kx as f64).log2()) as usize).max(1) };
+        if n_q > 5 || n_q > n_low {
+            return None;
+        }
+        let mut noise = vec![low[0]];
+        let mut i = 0;
+        for k in 1..=n_q {
+            i += (n_low - i) / (n_q + 1 - k);
+            noise.push(*low.get(i)?);
+        }
+        let patches = patches(&master, k0, kx, m, fs)?;
+        let lim = limiter(&low, &patches, kx, h.limiter_bands);
+        Some(FreqTables { k0, kx, m, high, low, noise, lim, patches })
+    }
+
+    /// High-resolution envelope bands.
+    pub(crate) fn n_high(&self) -> usize {
+        self.high.len() - 1
+    }
+
+    /// Noise floor bands.
+    pub(crate) fn n_q(&self) -> usize {
+        self.noise.len() - 1
+    }
+
+    /// The envelope band table of a resolution (`true`: high).
+    pub(crate) fn bands(&self, high_res: bool) -> &[usize] {
+        if high_res { &self.high } else { &self.low }
+    }
+}
+
+/// Map the low band onto the SBR range (§4.6.18.6.3): runs of source channels, each ending below
+/// `k0`, that together cover `kx .. kx + m`.
+fn patches(master: &[usize], k0: usize, kx: usize, m: usize, fs: u32) -> Option<Vec<(usize, usize)>> {
+    let n_master = master.len() - 1;
+    let goal = nint(2.048e6 / f64::from(fs)).max(0) as usize;
+    let mut k = if goal < kx + m { master.iter().position(|&f| f >= goal).unwrap_or(n_master) } else { n_master };
+    let (mut msb, mut usb) = (k0, kx);
+    let mut out: Vec<(usize, usize)> = Vec::new();
+    // each pass either adds a patch or lowers `msb` to `kx`; a stream that does neither twice
+    // running cannot finish. One patch over the limit may still be a short last one that is
+    // dropped below.
+    for _ in 0..2 * (MAX_PATCHES + 2) {
+        // the highest master border the patch can reach from below k0
+        let mut j = k + 1;
+        let (sb, odd) = loop {
+            j = j.checked_sub(1)?;
+            let sb = *master.get(j)?;
+            let odd = (sb + k0) % 2;
+            if sb + odd < k0 + msb {
+                break (sb, odd);
+            }
+        };
+        let count = sb.saturating_sub(usb);
+        if count > 0 {
+            let start = (k0 - odd).checked_sub(count)?;
+            out.push((start, count));
+            if out.len() > MAX_PATCHES + 1 {
+                return None;
+            }
+            (usb, msb) = (sb, sb);
+        } else {
+            msb = kx;
+        }
+        if master.get(k)?.saturating_sub(sb) < 3 {
+            k = n_master;
+        }
+        if sb == kx + m {
+            if out.len() > 1 && out.last().is_some_and(|p| p.1 < 3) {
+                out.pop();
+            }
+            return (!out.is_empty() && out.len() <= MAX_PATCHES).then_some(out);
+        }
+    }
+    None
+}
+
+/// The limiter band table (§4.6.18.7.3): one band over the range, or about 1.2, 2 or 3 bands per
+/// octave on the low-resolution and patch borders.
+fn limiter(low: &[usize], patches: &[(usize, usize)], kx: usize, limiter_bands: u8) -> Vec<usize> {
+    let (Some(&first), Some(&last)) = (low.first(), low.last()) else {
+        return Vec::new();
+    };
+    if limiter_bands == 0 {
+        return vec![first, last];
+    }
+    let per_octave = [1.2, 2.0, 3.0][usize::from(limiter_bands.clamp(1, 3) - 1)];
+    let mut borders = vec![kx];
+    for p in patches {
+        borders.push(borders.last().copied().unwrap_or(kx) + p.1);
+    }
+    let mut t: Vec<usize> = low.to_vec();
+    t.extend(borders.iter().skip(1).take(patches.len().saturating_sub(1)));
+    t.sort_unstable();
+    let is_border = |v: usize| borders.contains(&v);
+    let mut k = 1;
+    while k < t.len() {
+        let octaves = if t[k - 1] == 0 { f64::INFINITY } else { (t[k] as f64 / t[k - 1] as f64).log2() };
+        if octaves * per_octave >= 0.49 {
+            k += 1;
+        } else if t[k] == t[k - 1] || !is_border(t[k]) {
+            t.remove(k);
+        } else if !is_border(t[k - 1]) {
+            t.remove(k - 1);
+        } else {
+            k += 1;
+        }
+    }
+    if t.len() < 2 {
+        return vec![first, last];
+    }
+    t
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn header(start: u8, stop: u8, xover: u8, freq_scale: u8, alter: bool, noise: u8) -> Header {
+        Header {
+            amp_res: true,
+            start_freq: start,
+            stop_freq: stop,
+            xover_band: xover,
+            freq_scale,
+            alter_scale: alter,
+            noise_bands: noise,
+            limiter_bands: 2,
+            limiter_gains: 2,
+            interpol_freq: true,
+            smoothing_mode: true,
+        }
+    }
+
+    /// Every header field combination at every output rate gives tables that are strictly
+    /// increasing, start at `kx`, end at `kx + m`, keep the low band within the analysis bank and
+    /// patch from below `k0` (or is refused).
+    #[test]
+    fn every_header_gives_consistent_tables_or_none() {
+        let mut valid = 0;
+        for fs in [16_000, 22_050, 24_000, 32_000, 44_100, 48_000, 64_000, 88_200, 96_000] {
+            for start in 0..16 {
+                for stop in 0..16 {
+                    for xover in 0..8 {
+                        for fsc in 0..4 {
+                            for alter in [false, true] {
+                                for noise in 0..4 {
+                                    let Some(t) = FreqTables::new(&header(start, stop, xover, fsc, alter, noise), fs) else { continue };
+                                    valid += 1;
+                                    for v in [&t.high, &t.low, &t.noise, &t.lim] {
+                                        assert!(v.windows(2).all(|w| w[0] < w[1]), "{v:?}");
+                                        assert_eq!(v[0], t.kx);
+                                    }
+                                    for v in [&t.high, &t.low, &t.noise] {
+                                        assert_eq!(*v.last().unwrap(), t.kx + t.m);
+                                    }
+                                    assert!(t.kx <= 32 && t.kx + t.m <= 64 && t.n_q() <= 5);
+                                    // a last patch of under 3 channels is dropped, and the limiter
+                                    // bands may then stop short of the range's end
+                                    assert!(t.patches.iter().map(|p| p.1).sum::<usize>() <= t.m);
+                                    assert!(t.lim.len() >= 2 && *t.lim.last().unwrap() <= t.kx + t.m);
+                                    assert!(t.patches.iter().all(|&(s, n)| s + n <= t.k0));
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        assert!(valid > 10_000, "{valid}");
+    }
+
+    /// The highest start a header can give, 32 at 24 kHz (start 15), is valid: with stop 14
+    /// (twice the start) and linear bands it covers channels 32 to 64.
+    #[test]
+    fn a_start_at_channel_32_is_accepted() {
+        let t = FreqTables::new(&header(15, 14, 0, 0, false, 2), 24_000).unwrap();
+        assert_eq!((t.k0, t.kx, t.m), (32, 32, 32));
+    }
+
+    /// At 96 kHz this header builds patches of 6, 6, 6, 6, 5 and 2 channels: the short sixth is
+    /// dropped, as any short last patch is, and the five left are within the limit.
+    #[test]
+    fn a_short_sixth_patch_is_dropped_before_the_limit() {
+        let t = FreqTables::new(&header(3, 9, 0, 0, false, 2), 96_000).unwrap();
+        assert_eq!((t.k0, t.kx + t.m), (8, 39));
+        assert_eq!(t.patches.iter().map(|p| p.1).collect::<Vec<_>>(), [6, 6, 6, 6, 5]);
+    }
+
+    /// A typical 44.1 kHz header: start channel 12 + offset, stop near 64, three noise bands.
+    #[test]
+    fn a_44k_header_has_the_expected_layout() {
+        let t = FreqTables::new(&header(5, 9, 0, 2, true, 2), 44_100).unwrap();
+        // startMin 12 + offset 2 = 14
+        assert_eq!((t.k0, t.kx), (14, 14));
+        assert_eq!(t.low.len() - 1, t.n_high() - t.n_high() / 2);
+        assert!(t.n_q() >= 1);
+    }
+}
diff --git a/crates/audio/src/aac/sbr/hf.rs b/crates/audio/src/aac/sbr/hf.rs
new file mode 100644
index 000000000..1c2fd81ac
--- /dev/null
+++ b/crates/audio/src/aac/sbr/hf.rs
@@ -0,0 +1,333 @@
+//! HF generation (ISO/IEC 14496-3 §4.6.18.6) and HF adjustment (§4.6.18.7) of one channel.
+
+use super::bitstream::Grid;
+use super::freq::FreqTables;
+use super::tables::NOISE;
+use super::{Cx, Header, MAX_ENV, T_HF_ADJ, X_SLOTS};
+
+/// Low band subband samples of a frame: slots -8 .. 32 relative to the frame (`X_Low`).
+pub(crate) type LowBand = [[Cx; 32]; X_SLOTS];
+/// High band subband samples, at slot `l + T_HF_ADJ` for QMF slot `l` of the frame's envelopes.
+pub(crate) type HighBand = [[Cx; 64]; X_SLOTS];
+
+/// The per-channel state the HF tools carry from frame to frame.
+#[derive(Clone, Debug)]
+pub(crate) struct History {
+    /// `bs_invf_mode` and chirp factor per noise band.
+    invf: [u8; 5],
+    bw: [f32; 5],
+    /// The last frame's transient envelope was its last (`l_A = L_E`): no noise in this frame's
+    /// first.
+    la_at_end: bool,
+    /// Sinusoids present in the last envelope, by channel above `kx`.
+    sine: [bool; 64],
+    /// Gains and noise levels of the last four slots, newest first (smoothing).
+    gains: [[f32; 64]; 4],
+    noise_levels: [[f32; 64]; 4],
+    /// The smoothing history holds data of the current tables.
+    primed: bool,
+    noise_index: usize,
+    sine_index: usize,
+}
+
+impl History {
+    pub(crate) fn new() -> History {
+        History {
+            invf: [0; 5],
+            bw: [0.0; 5],
+            la_at_end: false,
+            sine: [false; 64],
+            gains: [[0.0; 64]; 4],
+            noise_levels: [[0.0; 64]; 4],
+            primed: false,
+            noise_index: 0,
+            sine_index: 0,
+        }
+    }
+
+    /// Forget what depends on the frequency tables (after a header that changes them).
+    pub(crate) fn reset_tables(&mut self) {
+        self.sine = [false; 64];
+        self.primed = false;
+        self.noise_index = 0;
+    }
+}
+
+/// The chirp factor of a noise band from its inverse filtering mode and the last frame's.
+fn chirp(mode: u8, prev_mode: u8, prev_bw: f32) -> f32 {
+    let new_bw = match (mode, prev_mode) {
+        (0, 1) => 0.6,
+        (0, _) => 0.0,
+        (1, 0) => 0.6,
+        (1, _) => 0.75,
+        (2, _) => 0.9,
+        _ => 0.98,
+    };
+    let bw = if new_bw < prev_bw { 0.75 * new_bw + 0.25 * prev_bw } else { 0.90625 * new_bw + 0.09375 * prev_bw };
+    if bw < 0.015625 { 0.0 } else { bw }
+}
+
+/// Second order linear prediction of one low band channel over the frame and the 6 slots
+/// before it (the covariance method, §4.6.18.6.2): `(α0, α1)`.
+fn predictor(x: &LowBand, k: usize) -> (Cx, Cx) {
+    // φ(i, j) = Σ x(n − i + 2) · conj(x(n − j + 2)), n = 0 .. 37
+    let phi = |i: usize, j: usize| {
+        let (mut re, mut im) = (0f64, 0f64);
+        for n in 0..SLOTS_PLUS_6 {
+            let (a, b) = (x[n + 2 - i][k], x[n + 2 - j][k]);
+            re += f64::from(a.re) * f64::from(b.re) + f64::from(a.im) * f64::from(b.im);
+            im += f64::from(a.im) * f64::from(b.re) - f64::from(a.re) * f64::from(b.im);
+        }
+        (re, im)
+    };
+    let (p01, p02, p11, p12, p22) = (phi(0, 1), phi(0, 2), phi(1, 1).0, phi(1, 2), phi(2, 2).0);
+    let d = p22 * p11 - (p12.0 * p12.0 + p12.1 * p12.1) / (1.0 + 1e-6);
+    let a1 = if d != 0.0 {
+        // (φ01 · φ12 − φ02 · φ11) / d
+        ((p01.0 * p12.0 - p01.1 * p12.1 - p02.0 * p11) / d, (p01.0 * p12.1 + p01.1 * p12.0 - p02.1 * p11) / d)
+    } else {
+        (0.0, 0.0)
+    };
+    let a0 = if p11 != 0.0 {
+        // −(φ01 + α1 · conj(φ12)) / φ11
+        (-(p01.0 + a1.0 * p12.0 + a1.1 * p12.1) / p11, -(p01.1 + a1.1 * p12.0 - a1.0 * p12.1) / p11)
+    } else {
+        (0.0, 0.0)
+    };
+    let mag = |a: (f64, f64)| (a.0 * a.0 + a.1 * a.1).sqrt();
+    if mag(a0) >= 4.0 || mag(a1) >= 4.0 {
+        return (Cx::default(), Cx::default());
+    }
+    (Cx { re: a0.0 as f32, im: a0.1 as f32 }, Cx { re: a1.0 as f32, im: a1.1 as f32 })
+}
+
+/// Slots of the covariance sums: the frame's 32 and 6 before it.
+const SLOTS_PLUS_6: usize = super::SLOTS + 6;
+
+/// The index of the band of `bands` holding channel `k` (bands are increasing borders).
+fn band_of(bands: &[usize], k: usize) -> usize {
+    bands.partition_point(|&b| b <= k).saturating_sub(1).min(bands.len().saturating_sub(2))
+}
+
+/// Patch the low band into the SBR range, inverse filtered (§4.6.18.6.3), for QMF slots
+/// `from .. to` of the frame.
+pub(crate) fn generate(x: &LowBand, t: &FreqTables, invf: &[u8; 5], h: &mut History, (from, to): (usize, usize), out: &mut HighBand) {
+    let mut bw = [0f32; 5];
+    for i in 0..t.n_q() {
+        bw[i] = chirp(invf[i], h.invf[i], h.bw[i]);
+    }
+    (h.invf, h.bw) = (*invf, bw);
+    let mut pred: [Option<(Cx, Cx)>; 32] = [None; 32];
+    let mut k = t.kx;
+    for &(start, count) in &t.patches {
+        for p in start..start + count {
+            let (a0, a1) = *pred[p].get_or_insert_with(|| predictor(x, p));
+            let g = bw[band_of(&t.noise, k)];
+            let (c0, c1) = (a0.scale(g), a1.scale(g * g));
+            for l in from..to {
+                let i = l + T_HF_ADJ;
+                out[i][k] = x[i][p] + c0 * x[i - 1][p] + c1 * x[i - 2][p];
+            }
+            k += 1;
+        }
+    }
+}
+
+/// Dequantised envelope and noise floor values of one channel in one frame.
+#[derive(Clone, Debug)]
+pub(crate) struct Levels {
+    /// Envelope energy per envelope and band (of that envelope's resolution).
+    pub(crate) energy: [[f32; 64]; MAX_ENV],
+    /// Noise to signal ratio per noise floor and noise band.
+    pub(crate) noise: [[f32; 5]; 2],
+}
+
+/// Gains for one envelope, per channel of the SBR range.
+struct EnvelopeGains {
+    gain: [f32; 64],
+    noise: [f32; 64],
+    sine: [f32; 64],
+}
+
+const LIMITER_GAINS: [f32; 4] = [0.70795, 1.0, 1.41254, 1e10];
+/// `h_smooth`, as the specification gives it.
+#[allow(clippy::excessive_precision)]
+const SMOOTHING: [f32; 5] = [0.33333333333333, 0.30150283239582, 0.21816949906249, 0.11516383427084, 0.03183050093751];
+const EPS: f32 = 1.0;
+const EPS0: f32 = 1e-12;
+
+/// What the adjustment of one channel's frame works from.
+pub(crate) struct Frame<'a> {
+    /// The generated high band.
+    pub(crate) x: &'a HighBand,
+    pub(crate) t: &'a FreqTables,
+    pub(crate) hdr: &'a Header,
+    pub(crate) g: &'a Grid,
+    pub(crate) lv: &'a Levels,
+    /// `bs_add_harmonic`, when the frame codes sinusoids.
+    pub(crate) harmonic: Option<&'a [bool; 64]>,
+}
+
+/// The gains of envelope `l` (§4.6.18.7.3–4): `delta` is 0 for a transient envelope, which gets
+/// no noise.
+fn envelope_gains(f: &Frame, l: usize, sine_index: &[bool; 64], delta: bool) -> EnvelopeGains {
+    let Frame { x, t, hdr, g, lv, .. } = *f;
+    let (kx, m) = (t.kx, t.m);
+    let bands = t.bands(g.freq_res[l]);
+    let (from, to) = (2 * g.t_env[l] + T_HF_ADJ, 2 * g.t_env[l + 1] + T_HF_ADJ);
+    let slots = (to - from) as f32;
+    let floor = usize::from(g.num_noise == 2 && g.t_env[l] >= g.t_noise[1]);
+    // per channel: original energy, current energy, noise ratio, sinusoid in its band
+    let mut e_orig = [0f32; 64];
+    let mut e_curr = [0f32; 64];
+    let mut q = [0f32; 64];
+    let mut s_band = [false; 64];
+    for j in 0..bands.len() - 1 {
+        let (lo, hi) = (bands[j] - kx, bands[j + 1] - kx);
+        let any_sine = sine_index[lo..hi].iter().any(|&s| s);
+        let mut sum = 0f32;
+        for c in lo..hi {
+            let ch = c + kx;
+            let e: f32 = (from..to).map(|i| x[i][ch].norm_sqr()).sum::<f32>() / slots;
+            e_curr[c] = e;
+            sum += e;
+            e_orig[c] = lv.energy[l][j];
+            q[c] = lv.noise[floor][band_of(&t.noise, ch)];
+            s_band[c] = any_sine;
+        }
+        if !hdr.interpol_freq {
+            e_curr[lo..hi].fill(sum / (hi - lo) as f32);
+        }
+    }
+    let mut out = EnvelopeGains { gain: [0.0; 64], noise: [0.0; 64], sine: [0.0; 64] };
+    for c in 0..m {
+        // `q / (1 + q)` first: energy and noise ratio are each clamped, their product is not
+        let (eo, ec, q) = (e_orig[c], e_curr[c], q[c]);
+        let share = q / (1.0 + q);
+        out.noise[c] = (eo * share).sqrt();
+        if sine_index[c] {
+            out.sine[c] = (eo / (1.0 + q)).sqrt();
+        }
+        out.gain[c] = if s_band[c] { (eo / (EPS + ec) * share).sqrt() } else { (eo / ((EPS + ec) * (1.0 + if delta { q } else { 0.0 }))).sqrt() };
+    }
+    // limit per limiter band, then boost back the energy the limiter took
+    let lim_gain = LIMITER_GAINS[usize::from(hdr.limiter_gains & 3)];
+    for w in t.lim.windows(2) {
+        let (lo, hi) = (w[0] - kx, w[1] - kx);
+        let (so, sc) = (e_orig[lo..hi].iter().sum::<f32>(), e_curr[lo..hi].iter().sum::<f32>());
+        let max = (lim_gain * ((EPS0 + so) / (EPS0 + sc)).sqrt()).min(1e5);
+        let mut den = 0f32;
+        for c in lo..hi {
+            if out.gain[c] > max {
+                out.noise[c] *= max / out.gain[c];
+                out.gain[c] = max;
+            }
+            den += e_curr[c] * out.gain[c] * out.gain[c];
+            if out.sine[c] != 0.0 {
+                den += out.sine[c] * out.sine[c];
+            } else if delta {
+                den += out.noise[c] * out.noise[c];
+            }
+        }
+        let boost = ((EPS0 + so) / (EPS0 + den)).sqrt().min(1.584_893_2);
+        for c in lo..hi {
+            out.gain[c] *= boost;
+            out.noise[c] *= boost;
+            out.sine[c] *= boost;
+        }
+    }
+    out
+}
+
+/// Adjust the generated high band to the transmitted envelopes and add noise and sinusoids
+/// (§4.6.18.7), for the frame's envelopes, into `y`.
+pub(crate) fn adjust(f: &Frame, h: &mut History, y: &mut HighBand) {
+    let Frame { x, t, hdr, g, harmonic, .. } = *f;
+    let (kx, m) = (t.kx, t.m);
+    let smooth = !hdr.smoothing_mode;
+    let prev_la_at_end = h.la_at_end;
+    for l in 0..g.num_env {
+        // sinusoids start at the transient envelope, unless one was already playing in the band
+        let mut sine_index = [false; 64];
+        if let Some(harm) = harmonic {
+            for i in 0..t.n_high() {
+                let c = (t.high[i] + t.high[i + 1]) / 2 - kx;
+                sine_index[c] = harm[i] && (g.la.is_none_or(|la| l >= la) || h.sine[c]);
+            }
+        }
+        let transient = g.la == Some(l) || (l == 0 && prev_la_at_end);
+        let e = envelope_gains(f, l, &sine_index, !transient);
+        if !h.primed {
+            h.gains = [e.gain; 4];
+            h.noise_levels = [e.noise; 4];
+            h.primed = true;
+        }
+        for i in 2 * g.t_env[l]..2 * g.t_env[l + 1] {
+            let (mut gain, mut noise) = (e.gain, e.noise);
+            if smooth && !transient {
+                for c in 0..m {
+                    gain[c] = SMOOTHING[0] * e.gain[c] + (0..4).map(|j| SMOOTHING[j + 1] * h.gains[j][c]).sum::<f32>();
+                    noise[c] = SMOOTHING[0] * e.noise[c] + (0..4).map(|j| SMOOTHING[j + 1] * h.noise_levels[j][c]).sum::<f32>();
+                }
+            }
+            h.gains.rotate_right(1);
+            h.noise_levels.rotate_right(1);
+            (h.gains[0], h.noise_levels[0]) = (e.gain, e.noise);
+            let (sin_re, sin_im) = [(1.0, 0.0), (0.0, 1.0), (-1.0, 0.0), (0.0, -1.0)][h.sine_index];
+            let row = &mut y[i + T_HF_ADJ];
+            for c in 0..m {
+                let ch = c + kx;
+                let mut v = x[i + T_HF_ADJ][ch].scale(gain[c]);
+                h.noise_index = (h.noise_index + 1) & 511;
+                if e.sine[c] != 0.0 {
+                    let sign = if ch % 2 == 0 { 1.0 } else { -1.0 };
+                    v.re += e.sine[c] * sin_re;
+                    v.im += e.sine[c] * sin_im * sign;
+                } else if !transient {
+                    let [nr, ni] = NOISE[h.noise_index];
+                    v.re += noise[c] * nr;
+                    v.im += noise[c] * ni;
+                }
+                row[ch] = v;
+            }
+            h.sine_index = (h.sine_index + 1) & 3;
+        }
+        if l + 1 == g.num_env {
+            h.sine = sine_index;
+        }
+    }
+    h.la_at_end = g.la == Some(g.num_env);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The chirp factor follows §4.6.18.6.2: rising quickly, falling slowly, and zero below 1/64.
+    #[test]
+    fn chirp_factors() {
+        assert!((chirp(3, 3, 0.0) - 0.90625 * 0.98).abs() < 1e-6);
+        assert!((chirp(0, 3, 0.98) - 0.25 * 0.98).abs() < 1e-6);
+        assert_eq!(chirp(0, 0, 0.05), 0.0);
+        assert!((chirp(1, 0, 0.0) - 0.90625 * 0.6).abs() < 1e-6);
+    }
+
+    /// A channel that is a decaying complex exponential is predicted exactly by its first order
+    /// term.
+    #[test]
+    fn prediction_of_a_resonance() {
+        let mut x: LowBand = [[Cx::default(); 32]; X_SLOTS];
+        let r = Cx { re: 0.9 * 0.3f32.cos(), im: 0.9 * 0.3f32.sin() };
+        let mut v = Cx { re: 1.0, im: 0.0 };
+        for slot in x.iter_mut() {
+            slot[3] = v;
+            v = v * r;
+        }
+        let (a0, a1) = predictor(&x, 3);
+        // x(n) + α0·x(n−1) + α1·x(n−2) = 0 with α0 = −r, α1 = 0
+        assert!((a0.re + r.re).abs() < 1e-3 && (a0.im + r.im).abs() < 1e-3, "{a0:?}");
+        assert!(a1.re.abs() < 1e-3 && a1.im.abs() < 1e-3, "{a1:?}");
+        // a silent channel has no predictor
+        assert_eq!(predictor(&x, 4), (Cx::default(), Cx::default()));
+    }
+}
diff --git a/crates/audio/src/aac/sbr/mod.rs b/crates/audio/src/aac/sbr/mod.rs
new file mode 100644
index 000000000..752cd03a0
--- /dev/null
+++ b/crates/audio/src/aac/sbr/mod.rs
@@ -0,0 +1,544 @@
+//! Spectral band replication (HE-AAC, ISO/IEC 14496-3 §4.6.18): rebuilds the band above the
+//! AAC-LC core from the core's own low band and the envelope data of the stream's SBR fill
+//! elements, at twice the core rate.
+//!
+//! Each channel's core output goes through a 32-band QMF analysis bank. The HF generator copies
+//! (patches) low band channels into the SBR range, inverse filtered; the HF adjuster scales them
+//! to the transmitted envelopes and adds noise and sinusoids; a 64-band QMF synthesis bank merges
+//! the delayed low band and the new high band. A frame without usable SBR data (none sent yet, or
+//! damaged) still passes through the banks, so the output keeps its rate and delay.
+//!
+//! Written from the SBR description and tables of ETSI ES 201 980 (DRM, Annex I has the tables it
+//! shares with ISO/IEC 14496-3) and the decoder process of ISO/IEC 14496-3. Parametric stereo
+//! (HE-AAC v2) is not decoded: its extension is skipped and the mono core is extended alone.
+
+mod bitstream;
+mod freq;
+mod hf;
+mod qmf;
+mod tables;
+
+use std::ops::{Add, Mul};
+
+use craft_media::bitstream::BitReader;
+
+use self::bitstream::{ChannelData, Frame};
+use self::freq::FreqTables;
+use self::hf::{HighBand, History, Levels, LowBand};
+use self::qmf::{Analysis, Synthesis};
+
+/// QMF slots per frame: 1024 core samples in slots of 32.
+pub(crate) const SLOTS: usize = 32;
+/// The most envelopes in a frame.
+pub(crate) const MAX_ENV: usize = 5;
+/// Slots of the last frame kept ahead of this one's low band (`t_HFGen`).
+const T_HF_GEN: usize = 8;
+/// The SBR frame lags the core frame by `T_HF_GEN − T_HF_ADJ` slots.
+pub(crate) const T_HF_ADJ: usize = 2;
+/// Slots in the low and high band buffers: the frame and `T_HF_GEN` before it.
+pub(crate) const X_SLOTS: usize = SLOTS + T_HF_GEN;
+/// The 16-bit full scale the specification's energies are in.
+const PCM_SCALE: f32 = 32768.0;
+/// `NOISE_FLOOR_OFFSET`.
+const NOISE_OFFSET: i32 = 6;
+
+/// Output samples by which the SBR decoder delays the core: the filter banks, and the SBR frame
+/// lagging the core frame by `T_HF_GEN − T_HF_ADJ` slots of 64.
+pub const DELAY: usize = qmf::DELAY + 64 * (T_HF_GEN - T_HF_ADJ);
+
+/// A complex subband sample.
+#[derive(Clone, Copy, Default, Debug, PartialEq)]
+pub(crate) struct Cx {
+    pub(crate) re: f32,
+    pub(crate) im: f32,
+}
+
+impl Cx {
+    fn scale(self, g: f32) -> Cx {
+        Cx { re: self.re * g, im: self.im * g }
+    }
+    fn norm_sqr(self) -> f32 {
+        self.re * self.re + self.im * self.im
+    }
+}
+
+impl Add for Cx {
+    type Output = Cx;
+    fn add(self, o: Cx) -> Cx {
+        Cx { re: self.re + o.re, im: self.im + o.im }
+    }
+}
+
+impl Mul for Cx {
+    type Output = Cx;
+    fn mul(self, o: Cx) -> Cx {
+        Cx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
+    }
+}
+
+/// `sbr_header()` (§4.5.2.8.1).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct Header {
+    pub(crate) amp_res: bool,
+    pub(crate) start_freq: u8,
+    pub(crate) stop_freq: u8,
+    pub(crate) xover_band: u8,
+    pub(crate) freq_scale: u8,
+    pub(crate) alter_scale: bool,
+    pub(crate) noise_bands: u8,
+    pub(crate) limiter_bands: u8,
+    pub(crate) limiter_gains: u8,
+    pub(crate) interpol_freq: bool,
+    pub(crate) smoothing_mode: bool,
+}
+
+impl Header {
+    /// Whether `o` keeps the frequency band tables (a change of any of these fields is an SBR
+    /// reset).
+    fn same_tables(&self, o: &Header) -> bool {
+        (self.start_freq, self.stop_freq, self.freq_scale, self.alter_scale, self.xover_band, self.noise_bands)
+            == (o.start_freq, o.stop_freq, o.freq_scale, o.alter_scale, o.xover_band, o.noise_bands)
+    }
+}
+
+/// Where an element's SBR data is: the access unit, and the bit range of the fill element's
+/// payload after its extension type.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct Payload<'a> {
+    pub(crate) data: &'a [u8],
+    pub(crate) start: usize,
+    pub(crate) end: usize,
+    /// `EXT_SBR_DATA_CRC`: a 10-bit CRC leads the data.
+    pub(crate) crc: bool,
+}
+
+/// Quantised envelope values per envelope and band, and noise floor values per floor and band.
+type Quantised = ([[i32; 64]; MAX_ENV], [[i32; 5]; 2]);
+
+/// One channel's state across frames.
+#[derive(Clone)]
+struct Channel {
+    analysis: Analysis,
+    synthesis: Synthesis,
+    /// Low band of the frame, with the last `T_HF_GEN` slots of the frame before ahead of it.
+    x_low: Box<LowBand>,
+    /// Adjusted high band of the last frame (its envelopes may reach into this one).
+    y_prev: Box<HighBand>,
+    /// Where `y_prev` holds data: QMF channels, and the end of its slots.
+    y_prev_range: (usize, usize),
+    y_prev_end: usize,
+    /// Quantised envelope values of the last envelope, and its resolution; noise floor values of
+    /// the last noise floor (time-direction delta coding).
+    env: [i32; 64],
+    env_high_res: bool,
+    noise: [i32; 5],
+    history: History,
+}
+
+impl Channel {
+    fn new() -> Channel {
+        Channel {
+            analysis: Analysis::new(),
+            synthesis: Synthesis::new(),
+            x_low: Box::new([[Cx::default(); 32]; X_SLOTS]),
+            y_prev: Box::new([[Cx::default(); 64]; X_SLOTS]),
+            y_prev_range: (0, 0),
+            y_prev_end: 0,
+            env: [0; 64],
+            env_high_res: false,
+            noise: [0; 5],
+            history: History::new(),
+        }
+    }
+
+    /// Decode the delta-coded envelope and noise floor values (§4.6.18.3.4); `scale` is 2 for a
+    /// balance channel.
+    fn absolute(&mut self, d: &ChannelData, t: &FreqTables, scale: i32) -> Quantised {
+        let mut env = [[0i32; 64]; MAX_ENV];
+        for l in 0..d.grid.num_env {
+            let res = d.grid.freq_res[l];
+            let n = t.bands(res).len() - 1;
+            if d.df_env[l] {
+                for k in 0..n {
+                    // the value this band refers to in the last envelope, mapped across resolutions
+                    let reference = if res == self.env_high_res {
+                        k
+                    } else if res {
+                        hf_band_of(t.bands(false), t.high[k])
+                    } else {
+                        t.high.iter().position(|&b| b == t.low[k]).unwrap_or(0)
+                    };
+                    env[l][k] = self.env.get(reference).copied().unwrap_or(0) + scale * d.env[l][k];
+                }
+            } else {
+                env[l][0] = scale * d.env[l][0];
+                for k in 1..n {
+                    env[l][k] = env[l][k - 1] + scale * d.env[l][k];
+                }
+            }
+            (self.env, self.env_high_res) = (env[l], res);
+        }
+        let mut noise = [[0i32; 5]; 2];
+        for l in 0..d.grid.num_noise {
+            for k in 0..t.n_q() {
+                let delta = scale * d.noise[l][k];
+                noise[l][k] = if d.df_noise[l] {
+                    self.noise[k] + delta
+                } else if k == 0 {
+                    delta
+                } else {
+                    noise[l][k - 1] + delta
+                };
+            }
+            self.noise = noise[l];
+        }
+        (env, noise)
+    }
+}
+
+/// The index of the band of `bands` holding channel `k`.
+fn hf_band_of(bands: &[usize], k: usize) -> usize {
+    bands.partition_point(|&b| b <= k).saturating_sub(1)
+}
+
+/// `2^x`, kept to a range whose energies stay finite.
+fn exp2(x: f32) -> f32 {
+    x.clamp(-64.0, 64.0).exp2()
+}
+
+/// Dequantise one channel (§4.6.18.3.5), or a coupled pair from its level and balance channels.
+fn dequantise(frame: &Frame, values: &[Quantised], t: &FreqTables) -> Vec<Levels> {
+    let g = &frame.channels[0].grid;
+    let amp = if g.amp_res { 1.0 } else { 0.5 };
+    let mut out = vec![Levels { energy: [[0.0; 64]; MAX_ENV], noise: [[0.0; 5]; 2] }; values.len()];
+    if frame.coupling && values.len() == 2 {
+        let pan = if g.amp_res { 12.0 } else { 24.0 };
+        let ((e0, q0), (e1, q1)) = (&values[0], &values[1]);
+        for l in 0..g.num_env {
+            for k in 0..t.bands(g.freq_res[l]).len() - 1 {
+                let level = 64.0 * exp2(amp * e0[l][k] as f32 + 1.0);
+                let balance = amp * (pan - e1[l][k] as f32);
+                out[0].energy[l][k] = level / (1.0 + exp2(balance));
+                out[1].energy[l][k] = level / (1.0 + exp2(-balance));
+            }
+        }
+        for l in 0..g.num_noise {
+            for k in 0..t.n_q() {
+                let level = exp2((NOISE_OFFSET - q0[l][k] + 1) as f32);
+                let balance = (12 - q1[l][k]) as f32;
+                out[0].noise[l][k] = level / (1.0 + exp2(balance));
+                out[1].noise[l][k] = level / (1.0 + exp2(-balance));
+            }
+        }
+        return out;
+    }
+    for ((lv, (e, q)), d) in out.iter_mut().zip(values).zip(&frame.channels) {
+        let g = &d.grid;
+        let amp = if g.amp_res { 1.0 } else { 0.5 };
+        for l in 0..g.num_env {
+            for k in 0..t.bands(g.freq_res[l]).len() - 1 {
+                lv.energy[l][k] = 64.0 * exp2(amp * e[l][k] as f32);
+            }
+        }
+        for l in 0..g.num_noise {
+            for k in 0..t.n_q() {
+                lv.noise[l][k] = exp2((NOISE_OFFSET - q[l][k]) as f32);
+            }
+        }
+    }
+    out
+}
+
+/// The SBR decoder of one channel element: a single channel (SCE, or an LFE, which has no SBR
+/// data) or a channel pair (CPE).
+#[derive(Clone)]
+pub(crate) struct Element {
+    /// Output sampling rate.
+    rate: u32,
+    header: Option<Header>,
+    tables: Option<FreqTables>,
+    channels: Vec<Channel>,
+}
+
+impl Element {
+    pub(crate) fn new(channels: usize, rate: u32) -> Element {
+        Element { rate, header: None, tables: None, channels: (0..channels).map(|_| Channel::new()).collect() }
+    }
+
+    pub(crate) fn channels(&self) -> usize {
+        self.channels.len()
+    }
+
+    /// Forget the signal (a seek). The header is kept: it holds until the stream sends another.
+    pub(crate) fn reset(&mut self) {
+        for c in &mut self.channels {
+            *c = Channel::new();
+        }
+    }
+
+    /// Read an element's SBR data: `None` without a header to read it by.
+    fn read(&mut self, p: Payload) -> Option<Frame> {
+        let mut br = BitReader::new(p.data);
+        br.seek_bits(p.start);
+        if p.crc {
+            br.skip(10).ok()?;
+        }
+        if br.read_flag().ok()? {
+            let h = Header::read(&mut br).ok()?;
+            // a header that runs past its fill element is damaged: keep the one in use
+            (br.position() <= p.end).then_some(())?;
+            if self.header != Some(h) {
+                if self.header.is_none_or(|o| !o.same_tables(&h)) {
+                    for c in &mut self.channels {
+                        c.history.reset_tables();
+                    }
+                }
+                self.tables = FreqTables::new(&h, self.rate);
+                self.header = Some(h);
+            }
+        }
+        let (h, t) = (self.header?, self.tables.as_ref()?);
+        let frame = bitstream::read_data(&mut br, t, h.amp_res, self.channels.len()).ok()?;
+        (br.position() <= p.end).then_some(frame)
+    }
+
+    /// Decode one frame: 1024 core samples per channel in, 2048 out.
+    pub(crate) fn process(&mut self, core: &[Vec<f32>], payload: Option<Payload>) -> Vec<Vec<f32>> {
+        for (c, pcm) in self.channels.iter_mut().zip(core) {
+            c.x_low.copy_within(SLOTS..X_SLOTS, 0);
+            let scaled: Vec<f32> = pcm.iter().map(|s| s * PCM_SCALE).collect();
+            c.analysis.process(&scaled, &mut c.x_low[T_HF_GEN..]);
+        }
+        let frame = payload.and_then(|p| self.read(p));
+        let mut y: Vec<Box<HighBand>> = self.channels.iter().map(|_| Box::new([[Cx::default(); 64]; X_SLOTS])).collect();
+        // per channel: kx, m, and the first and end slot of `y` this frame fills
+        let mut current: Vec<Option<(usize, usize, usize, usize)>> = vec![None; self.channels.len()];
+        if let (Some(frame), Some(h), Some(t)) = (&frame, self.header, self.tables.as_ref()) {
+            let values: Vec<_> = self
+                .channels
+                .iter_mut()
+                .zip(&frame.channels)
+                .enumerate()
+                .map(|(i, (c, d))| c.absolute(d, t, if frame.coupling && i == 1 { 2 } else { 1 }))
+                .collect();
+            let levels = dequantise(frame, &values, t);
+            for (((c, d), (lv, y)), cur) in self.channels.iter_mut().zip(&frame.channels).zip(levels.iter().zip(&mut y)).zip(&mut current) {
+                let g = &d.grid;
+                let slots = (2 * g.t_env[0], 2 * g.t_env[g.num_env]);
+                let mut x_high: Box<HighBand> = Box::new([[Cx::default(); 64]; X_SLOTS]);
+                hf::generate(&c.x_low, t, &d.invf, &mut c.history, slots, &mut x_high);
+                let f = hf::Frame { x: &x_high, t, hdr: &h, g, lv, harmonic: d.harmonic.as_ref() };
+                hf::adjust(&f, &mut c.history, y);
+                *cur = Some((t.kx, t.m, slots.0 + T_HF_ADJ, slots.1 + T_HF_ADJ));
+            }
+        }
+        let mut out = vec![vec![0f32; 2 * 1024]; self.channels.len()];
+        for (((c, y), out), current) in self.channels.iter_mut().zip(y).zip(&mut out).zip(current) {
+            for (l, block) in out.as_chunks_mut::<64>().0.iter_mut().enumerate() {
+                let i = l + T_HF_ADJ;
+                let mut x = [Cx::default(); 64];
+                // the high band of this slot: this frame's envelopes, the last frame's reaching
+                // into this one, or none
+                let high = match current {
+                    Some((kx, m, from, to)) if (from..to).contains(&i) => Some((&y[i], kx, m)),
+                    _ if i + SLOTS < c.y_prev_end => Some((&c.y_prev[i + SLOTS], c.y_prev_range.0, c.y_prev_range.1)),
+                    _ => None,
+                };
+                let low = high.map_or(current.map_or(32, |cur| cur.0), |h| h.1);
+                x[..low].copy_from_slice(&c.x_low[i][..low]);
+                if let Some((row, kx, m)) = high {
+                    x[kx..kx + m].copy_from_slice(&row[kx..kx + m]);
+                }
+                c.synthesis.process(&x, 64, block);
+            }
+            for s in out.iter_mut() {
+                *s /= PCM_SCALE;
+            }
+            c.y_prev = y;
+            (c.y_prev_range, c.y_prev_end) = current.map_or(((0, 0), 0), |cur| ((cur.0, cur.1), cur.3));
+        }
+        out
+    }
+}
+
+/// The header of [`test_payload`].
+#[cfg(test)]
+pub(crate) const TEST_HEADER: Header = Header {
+    amp_res: true,
+    start_freq: 5,
+    stop_freq: 9,
+    xover_band: 0,
+    freq_scale: 2,
+    alter_scale: true,
+    noise_bands: 2,
+    limiter_bands: 2,
+    limiter_gains: 2,
+    interpol_freq: true,
+    smoothing_mode: true,
+};
+
+/// An SBR single channel element for tests at output rate `rate`: [`TEST_HEADER`] (3 dB steps,
+/// start 5, stop 9, the default extra fields), then one FIXFIX envelope at high resolution with
+/// band `k` at `env(k)` (1.5 dB steps, as a single FIXFIX envelope has) and noise band `k` at
+/// `noise(k)`.
+#[cfg(test)]
+pub(crate) fn test_payload(rate: u32, env: impl Fn(usize) -> i32, noise: impl Fn(usize) -> i32) -> Option<Vec<u8>> {
+    use craft_media::bitstream::BitWriter;
+    let t = FreqTables::new(&TEST_HEADER, rate)?;
+    let (env, noise): (Vec<i32>, Vec<i32>) = ((0..t.n_high()).map(env).collect(), (0..t.n_q()).map(noise).collect());
+    let mut bw = BitWriter::new();
+    bw.write_bits(1, 1); // bs_header_flag
+    for (v, n) in [(1, 1), (5, 4), (9, 4), (0, 3), (0, 2), (0, 1), (0, 1)] {
+        bw.write_bits(v, n); // amp_res, start, stop, xover, reserved, no extra fields
+    }
+    bw.write_bits(0, 1); // bs_data_extra
+    bw.write_bits(u32::from(bitstream::FIXFIX), 2);
+    bw.write_bits(0, 2); // one envelope
+    bw.write_bits(1, 1); // high resolution
+    bw.write_bits(0, 2); // frequency-direction envelope and noise floor
+    for _ in &noise {
+        bw.write_bits(0, 2); // no inverse filtering
+    }
+    bw.write_bits(env[0] as u32, 7);
+    for w in env.windows(2) {
+        let (code, len) = tables::F_ENV_1_5DB[(w[1] - w[0] + 60) as usize];
+        bw.write_bits(code, u32::from(len));
+    }
+    bw.write_bits(noise[0] as u32, 5);
+    for w in noise.windows(2) {
+        let (code, len) = tables::F_ENV_3_0DB[(w[1] - w[0] + 31) as usize];
+        bw.write_bits(code, u32::from(len));
+    }
+    bw.write_bits(0, 2); // no sinusoids, no extended data
+    Some(bw.finish())
+}
+
+#[cfg(test)]
+mod tests {
+    use std::f64::consts::PI;
+
+    use super::*;
+
+    const RATE: u32 = 44_100;
+
+    fn tables() -> FreqTables {
+        FreqTables::new(&TEST_HEADER, RATE).unwrap()
+    }
+
+    /// Mean energy per DFT bin of `x` between `lo` and `hi` QMF channels (64 per half rate).
+    fn energy(x: &[f32], lo: usize, hi: usize) -> f64 {
+        let n = x.len();
+        let (b0, b1) = (lo * n / 128, hi * n / 128);
+        let mut e = 0f64;
+        for b in b0 + 2..b1 - 2 {
+            let (mut re, mut im) = (0f64, 0f64);
+            for (i, &s) in x.iter().enumerate() {
+                let w = 0.5 - 0.5 * (2.0 * PI * i as f64 / n as f64).cos();
+                let ph = 2.0 * PI * (b * i) as f64 / n as f64;
+                re += f64::from(s) * w * ph.cos();
+                im += f64::from(s) * w * ph.sin();
+            }
+            e += re * re + im * im;
+        }
+        e / (b1 - b0 - 4) as f64
+    }
+
+    fn run(e: &mut Element, data: &[u8], frames: usize) -> Vec<f32> {
+        let core = vec![vec![0f32; 1024]];
+        let mut out = Vec::new();
+        for _ in 0..frames {
+            let p = Payload { data, start: 0, end: 8 * data.len(), crc: false };
+            let block = e.process(&core, Some(p));
+            assert_eq!((block.len(), block[0].len()), (1, 2048));
+            assert!(block[0].iter().all(|s| s.is_finite()));
+            out.extend_from_slice(&block[0]);
+        }
+        out
+    }
+
+    /// Over a silent core the high band is the noise the envelope asks for: the upper bands,
+    /// 12 steps of 1.5 dB above the lower ones, come out 18 dB louder, and nothing below `kx`.
+    #[test]
+    fn the_high_band_follows_the_envelope() {
+        let t = tables();
+        let mid = t.n_high() / 2;
+        let data = test_payload(RATE, |k| if k < mid { 30 } else { 42 }, |_| 0).unwrap();
+        let mut e = Element::new(1, RATE);
+        let out = run(&mut e, &data, 6);
+        let tail = &out[out.len() - 4096..];
+        let (lower, upper) = (energy(tail, t.high[0], t.high[mid]), energy(tail, t.high[mid], t.high[t.n_high()]));
+        let step = 10.0 * (upper / lower).log10();
+        assert!((step - 18.06).abs() < 1.5, "{step:.2} dB");
+        let below = energy(tail, 1, t.kx - 1);
+        assert!(10.0 * (lower / below.max(1e-30)).log10() > 60.0);
+        // the same envelope without its header is not read: an element that has seen none
+        // passes the core through alone
+        let mut fresh = Element::new(1, RATE);
+        let mut no_header = data.clone();
+        no_header[0] &= 0x7F;
+        assert!(run(&mut fresh, &no_header, 3).iter().all(|&s| s == 0.0));
+    }
+
+    /// Damaged SBR data (flipped bits, cut short, or noise) never panics and keeps the output
+    /// finite and of full length.
+    #[test]
+    fn damaged_sbr_data_is_survived() {
+        let good = test_payload(RATE, |k| 20 + k as i32, |_| 3).unwrap();
+        let mut seed = 0x1234_5678u32;
+        let mut next = || {
+            seed ^= seed << 13;
+            seed ^= seed >> 17;
+            seed ^= seed << 5;
+            seed
+        };
+        let mut e = Element::new(1, RATE);
+        let mut pair = Element::new(2, RATE);
+        for i in 0..600 {
+            let mut data = good.clone();
+            for _ in 0..1 + next() % 6 {
+                let bit = next() as usize % (8 * data.len());
+                data[bit / 8] ^= 0x80 >> (bit % 8);
+            }
+            if i % 3 == 0 {
+                data.truncate(1 + next() as usize % data.len());
+            }
+            if i % 5 == 0 {
+                data = (0..1 + next() % 40).map(|_| next() as u8).collect();
+                data[0] |= 0x80;
+            }
+            run(&mut e, &data, 1);
+            let p = Payload { data: &data, start: 0, end: 8 * data.len(), crc: i % 2 == 0 };
+            let out = pair.process(&[vec![0.1; 1024], vec![-0.1; 1024]], Some(p));
+            assert!(out.iter().all(|c| c.len() == 2048 && c.iter().all(|s| s.is_finite())));
+        }
+    }
+
+    /// The largest envelope (127 steps of 1.5 dB) with the largest noise floor (each band 31
+    /// steps below the last) keeps the output finite: the gains are formed so that no
+    /// intermediate product of two clamped levels overflows.
+    #[test]
+    fn extreme_levels_stay_finite() {
+        let rate =
+            [22_050, 24_000, 32_000, 44_100, 48_000].into_iter().find(|&r| FreqTables::new(&TEST_HEADER, r).is_some_and(|t| t.n_q() >= 3)).unwrap();
+        let data = test_payload(rate, |_| 127, |k| -31 * k as i32).unwrap();
+        let mut e = Element::new(1, rate);
+        run(&mut e, &data, 3);
+    }
+
+    /// A header that runs past the end of its fill element is not taken: the one in use stays,
+    /// and the frame is dropped.
+    #[test]
+    fn a_header_cut_short_is_not_taken() {
+        let data = test_payload(RATE, |_| 30, |_| 0).unwrap();
+        let mut e = Element::new(1, RATE);
+        run(&mut e, &data, 1);
+        assert_eq!(e.header, Some(TEST_HEADER));
+        // another start frequency (bits 2..6), in an element that ends 6 bits in
+        let mut cut = data.clone();
+        cut[0] ^= 0x04;
+        assert!(e.read(Payload { data: &cut, start: 0, end: 6, crc: false }).is_none());
+        assert_eq!(e.header, Some(TEST_HEADER));
+        assert!(e.read(Payload { data: &cut, start: 0, end: 8 * cut.len(), crc: false }).is_some());
+        assert_ne!(e.header, Some(TEST_HEADER));
+    }
+}
diff --git a/crates/audio/src/aac/sbr/qmf.rs b/crates/audio/src/aac/sbr/qmf.rs
new file mode 100644
index 000000000..de947f303
--- /dev/null
+++ b/crates/audio/src/aac/sbr/qmf.rs
@@ -0,0 +1,155 @@
+//! The SBR filter banks (ISO/IEC 14496-3 §4.6.18.4): a 32-band complex QMF analysis bank at the
+//! core rate and a 64-band complex QMF synthesis bank at the output rate, sharing the window `c`.
+//!
+//! Each bank is a polyphase window followed by a complex modulation: analysis
+//! `2·exp(iπ(k + ½)(2n − ½)/64)`, synthesis `exp(iπ(k + ½)(2n − 251)/128)/64`. With the window's
+//! indexing, the two phase offsets put the banks' combined response on its centre tap, so the low
+//! band comes back unchanged (to about -60 dB, the window's own limit), 576 output samples late.
+//! The synthesis bank holds back its last two output samples, which makes it 578: with the SBR
+//! frame's lag, the 962 samples by which HE-AAC decoders (ffmpeg's among them) delay the core, and
+//! which the priming encoders signal counts on.
+
+use std::f64::consts::PI;
+use std::sync::OnceLock;
+
+use super::Cx;
+use super::tables::QMF_WINDOW;
+
+/// Output samples by which analysis followed by synthesis delays the low band.
+pub(crate) const DELAY: usize = 578;
+
+/// Modulation matrices, computed once.
+struct Kernels {
+    /// Analysis, at `[k][n]`: 32 × 64.
+    analysis: Vec<[Cx; 64]>,
+    /// Synthesis, at `[n][k]`: 128 × 64.
+    synthesis: Vec<[Cx; 64]>,
+}
+
+fn kernels() -> &'static Kernels {
+    static K: OnceLock<Kernels> = OnceLock::new();
+    K.get_or_init(|| {
+        let cx = |phase: f64, scale: f64| Cx { re: (phase.cos() * scale) as f32, im: (phase.sin() * scale) as f32 };
+        let analysis = (0..32).map(|k| std::array::from_fn(|n| cx(PI * (k as f64 + 0.5) * (2.0 * n as f64 - 0.5) / 64.0, 2.0))).collect();
+        let synthesis = (0..128).map(|n| std::array::from_fn(|k| cx(PI * (k as f64 + 0.5) * (2.0 * n as f64 - 251.0) / 128.0, 1.0 / 64.0))).collect();
+        Kernels { analysis, synthesis }
+    })
+}
+
+/// The 32-band analysis bank of one channel.
+#[derive(Clone)]
+pub(crate) struct Analysis {
+    /// The last 320 input samples, newest first.
+    x: Box<[f32; 320]>,
+}
+
+impl Analysis {
+    pub(crate) fn new() -> Analysis {
+        Analysis { x: Box::new([0.0; 320]) }
+    }
+
+    /// Split `32 · out.len()` input samples into `out.len()` slots of 32 subbands.
+    pub(crate) fn process(&mut self, input: &[f32], out: &mut [[Cx; 32]]) {
+        let k = kernels();
+        for (block, slot) in input.as_chunks::<32>().0.iter().zip(out.iter_mut()) {
+            self.x.copy_within(0..288, 32);
+            for (n, &s) in block.iter().enumerate() {
+                self.x[31 - n] = s;
+            }
+            let mut u = [0f32; 64];
+            for (n, u) in u.iter_mut().enumerate() {
+                *u = (0..5).map(|j| self.x[n + 64 * j] * QMF_WINDOW[2 * (n + 64 * j)]).sum();
+            }
+            for (sb, row) in slot.iter_mut().zip(&k.analysis) {
+                let (mut re, mut im) = (0f32, 0f32);
+                for (u, m) in u.iter().zip(row) {
+                    re += u * m.re;
+                    im += u * m.im;
+                }
+                *sb = Cx { re, im };
+            }
+        }
+    }
+}
+
+/// The 64-band synthesis bank of one channel.
+#[derive(Clone)]
+pub(crate) struct Synthesis {
+    v: Box<[f32; 1280]>,
+    /// The last two output samples, which the next slot puts out first.
+    held: [f32; 2],
+}
+
+impl Synthesis {
+    pub(crate) fn new() -> Synthesis {
+        Synthesis { v: Box::new([0.0; 1280]), held: [0.0; 2] }
+    }
+
+    /// Merge one slot of 64 subbands into 64 output samples (`out[..64]`, of which it needs 64).
+    /// Bands from `bands` up are taken as zero.
+    pub(crate) fn process(&mut self, x: &[Cx; 64], bands: usize, out: &mut [f32]) {
+        let k = kernels();
+        let bands = bands.min(64);
+        self.v.copy_within(0..1152, 128);
+        for (n, row) in k.synthesis.iter().enumerate() {
+            self.v[n] = x[..bands].iter().zip(row).map(|(x, m)| x.re * m.re - x.im * m.im).sum();
+        }
+        let mut slot = [0f32; 66];
+        slot[..2].copy_from_slice(&self.held);
+        for (n, o) in slot[2..].iter_mut().enumerate() {
+            let mut s = 0f32;
+            for i in 0..5 {
+                s += self.v[256 * i + n] * QMF_WINDOW[128 * i + n];
+                s += self.v[256 * i + 192 + n] * QMF_WINDOW[128 * i + 64 + n];
+            }
+            *o = s;
+        }
+        self.held = [slot[64], slot[65]];
+        for (o, s) in out.iter_mut().zip(&slot[..64]) {
+            *o = *s;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::SLOTS;
+    use super::*;
+
+    fn tones(t: f64) -> f64 {
+        [0.0371, 0.0913, 0.1527, 0.2211, 0.2903, 0.3519, 0.4127].iter().enumerate().map(|(j, f)| (2.0 * PI * f * t + j as f64).sin() * 0.1).sum()
+    }
+
+    /// Tones across the core band through analysis and synthesis (low 32 bands only) come out at
+    /// twice the rate, [`DELAY`] samples late, with the error 60 dB down.
+    #[test]
+    fn analysis_then_synthesis_reconstructs_the_input() {
+        let input: Vec<f32> = (0..8 * 1024).map(|i| tones(i as f64) as f32).collect();
+        let (mut a, mut s) = (Analysis::new(), Synthesis::new());
+        let mut out = Vec::new();
+        let mut slots = [[Cx::default(); 32]; SLOTS];
+        for frame in input.as_chunks::<1024>().0 {
+            a.process(frame, &mut slots);
+            for slot in &slots {
+                let mut x = [Cx::default(); 64];
+                x[..32].copy_from_slice(slot);
+                let mut o = [0f32; 64];
+                s.process(&x, 32, &mut o);
+                out.extend_from_slice(&o);
+            }
+        }
+        assert_eq!(out.len(), 2 * input.len());
+        let snr_at = |delay: usize| {
+            let (mut err, mut sig) = (0f64, 0f64);
+            for (i, &o) in out.iter().enumerate().skip(3000) {
+                let want = tones((i as f64 - delay as f64) / 2.0);
+                err += (o as f64 - want).powi(2);
+                sig += want * want;
+            }
+            10.0 * (sig / err).log10()
+        };
+        let snr = snr_at(DELAY);
+        assert!(snr > 60.0, "reconstruction SNR {snr:.1} dB");
+        assert!(snr_at(DELAY - 1) < 40.0 && snr_at(DELAY + 1) < 40.0);
+    }
+}
diff --git a/crates/audio/src/aac/sbr/tables.rs b/crates/audio/src/aac/sbr/tables.rs
new file mode 100644
index 000000000..7a648120e
--- /dev/null
+++ b/crates/audio/src/aac/sbr/tables.rs
@@ -0,0 +1,357 @@
+//! SBR tables (ETSI ES 201 980 V1.2.2 Annex I, the SBR tables it shares with ISO/IEC 14496-3 §4.A.6).
+//!
+//! Transcribed from the specification's tables, which give the window to 14 digits (more than an
+//! `f32` holds). Annex I misprints the labels of `c[297]` and `c[305]`; the values are in order.
+//! Each Huffman table is a complete prefix code (see the tests in `sbr::bitstream`).
+
+#![allow(clippy::excessive_precision)]
+
+/// The QMF bank window `c` (640 coefficients).
+#[rustfmt::skip]
+pub(crate) static QMF_WINDOW: [f32; 640] = [
+    -0.00055252865047, -0.00056176925738, -0.00049475180896, -0.00048752279712, -0.00048937912498, -0.00050407143497, -0.00052265642972, -0.00054665656337,
+    -0.00056778025613, -0.00058709304852, -0.00061327473938, -0.00063124935319, -0.00065403333621, -0.00067776907764, -0.00069416146273, -0.00071577364744,
+    -0.00072550431222, -0.00074409418541, -0.00074905980532, -0.00076813719270, -0.00077248485949, -0.00078343322877, -0.00077798694927, -0.00078036647100,
+    -0.00078014496257, -0.00077579773310, -0.00076307935757, -0.00075300014201, -0.00073193571525, -0.00072153919876, -0.00069179375372, -0.00066504150893,
+    -0.00063415949025, -0.00059461189330, -0.00055645763906, -0.00051455722108, -0.00046063254803, -0.00040951214522, -0.00035011758756, -0.00028969811748,
+    -0.00020983373440, -0.00014463809349, -0.00006173344072, 0.00001349497418, 0.00010943831274, 0.00020430170688, 0.00029495311041, 0.00040265402160,
+    0.00051073884952, 0.00062393761391, 0.00074580258865, 0.00086084433262, 0.00098859883015, 0.00112501551307, 0.00125778846475, 0.00139024948272,
+    0.00154432198471, 0.00168680832531, 0.00183482654224, 0.00198411407369, 0.00214615835557, 0.00230172547746, 0.00246256169126, 0.00262017586902,
+    0.00278704643465, 0.00294694477165, 0.00311254206525, 0.00327396134847, 0.00344188741828, 0.00360082681231, 0.00376039229104, 0.00392074323703,
+    0.00408197531935, 0.00422642692270, 0.00437307196781, 0.00452098527825, 0.00466064606118, 0.00479325608498, 0.00491376035745, 0.00503930226013,
+    0.00514073539032, 0.00524611661324, 0.00534716811982, 0.00541967759307, 0.00548760401507, 0.00554757145088, 0.00559380230045, 0.00562206432097,
+    0.00564551969164, 0.00563891995151, 0.00562661141932, 0.00559171286630, 0.00554043639400, 0.00547537830770, 0.00538389758970, 0.00527157587272,
+    0.00513822754514, 0.00498396877629, 0.00481094690600, 0.00460395301471, 0.00438018617447, 0.00412516423270, 0.00384564081246, 0.00354012465507,
+    0.00320918858098, 0.00284467578623, 0.00245085400321, 0.00202741761850, 0.00157846825768, 0.00109023290512, 0.00058322642480, 0.00002760451905,
+    -0.00054642808664, -0.00115681355227, -0.00180394725893, -0.00248267236449, -0.00319337783900, -0.00394011240522, -0.00472225962400, -0.00553372111088,
+    -0.00637922932685, -0.00726158168517, -0.00817982333726, -0.00913253296085, -0.01011502154986, -0.01113155480321, -0.01218499959508, -0.01327182200351,
+    0.01439046660792, 0.01554055533423, 0.01673247129989, 0.01794333813443, 0.01918724313698, 0.02045317933555, 0.02174675502535, 0.02306801692862,
+    0.02441609920285, 0.02578758475467, 0.02718594296329, 0.02860721736385, 0.03005026574279, 0.03150176087389, 0.03297540810337, 0.03446209487686,
+    0.03596975605542, 0.03748128504252, 0.03900536794745, 0.04053491705584, 0.04206490946367, 0.04360975421304, 0.04514884056413, 0.04668430272642,
+    0.04821657200672, 0.04973857556014, 0.05125561555216, 0.05276307465207, 0.05424527683589, 0.05571736482138, 0.05716164501299, 0.05859156836260,
+    0.05998374801761, 0.06134551717207, 0.06268578081172, 0.06397158980681, 0.06522471064380, 0.06643675122104, 0.06760759851228, 0.06870438283512,
+    0.06976302447127, 0.07076287107266, 0.07170026731102, 0.07256825833083, 0.07336202550803, 0.07410036424342, 0.07474525581194, 0.07531373362019,
+    0.07580083586584, 0.07619924793396, 0.07649921704119, 0.07670934904245, 0.07681739756964, 0.07682300113923, 0.07672049241746, 0.07650507183194,
+    0.07617483218536, 0.07573057565061, 0.07515762552870, 0.07446643947564, 0.07364060057620, 0.07267746427299, 0.07158263647903, 0.07035330735093,
+    0.06896640131951, 0.06745250215166, 0.06576906686508, 0.06394448059633, 0.06196027790387, 0.05981665708090, 0.05751526919867, 0.05504600343009,
+    0.05240938217366, 0.04959786763445, 0.04663033051701, 0.04347687821958, 0.04014582784127, 0.03664181168133, 0.03295839306691, 0.02908240060125,
+    0.02503075618909, 0.02079970728622, 0.01637012582228, 0.01176238327857, 0.00696368621617, 0.00197656014503, -0.00320868968304, -0.00857117491366,
+    -0.01412888273558, -0.01988341292573, -0.02582272888064, -0.03195312745332, -0.03827765720822, -0.04478068215856, -0.05148041767934, -0.05837053268336,
+    -0.06544098531359, -0.07269433008129, -0.08013729344279, -0.08775475365593, -0.09555333528914, -0.10353295311463, -0.11168269317730, -0.12000779846800,
+    -0.12850028503878, -0.13715517611934, -0.14597664911870, -0.15496070710605, -0.16409588556669, -0.17338081721706, -0.18281725485142, -0.19239667457267,
+    -0.20212501768103, -0.21197358538056, -0.22196526964149, -0.23206908706791, -0.24230168845974, -0.25264803095722, -0.26310532994603, -0.27366340405625,
+    -0.28432141891085, -0.29507167170646, -0.30590985751916, -0.31682789136456, -0.32781137272105, -0.33887226938665, -0.34999141229310, -0.36115899031355,
+    0.37237955463061, 0.38363500139043, 0.39492117615675, 0.40623176767625, 0.41756968968409, 0.42891199207373, 0.44025537543665, 0.45159965356824,
+    0.46293080852757, 0.47424532146115, 0.48552530911099, 0.49677082545707, 0.50798175000434, 0.51912349702391, 0.53022408956855, 0.54125534487322,
+    0.55220512585061, 0.56307891401370, 0.57385241316923, 0.58454032354679, 0.59511230862496, 0.60557835389180, 0.61591099320291, 0.62612426956055,
+    0.63619801077286, 0.64612696959461, 0.65590163024671, 0.66551398801627, 0.67496631901712, 0.68423532934598, 0.69332823767032, 0.70223887193539,
+    0.71094104263095, 0.71944626349561, 0.72774489002994, 0.73582117582769, 0.74368278636488, 0.75131374561237, 0.75870807608242, 0.76586748650939,
+    0.77277808813327, 0.77942875190216, 0.78583531203920, 0.79197358416424, 0.79784664137700, 0.80344857518505, 0.80876950044491, 0.81381912706217,
+    0.81857760046468, 0.82304198905409, 0.82722753473360, 0.83110384571520, 0.83469373618402, 0.83797173378865, 0.84095413924722, 0.84362382812005,
+    0.84598184698206, 0.84803157770763, 0.84978051984268, 0.85119715249343, 0.85230470352147, 0.85310209497017, 0.85357205739107, 0.85373856005937,
+    0.85357205739107, 0.85310209497017, 0.85230470352147, 0.85119715249343, 0.84978051984268, 0.84803157770763, 0.84598184698206, 0.84362382812005,
+    0.84095413924722, 0.83797173378865, 0.83469373618402, 0.83110384571520, 0.82722753473360, 0.82304198905409, 0.81857760046468, 0.81381912706217,
+    0.80876950044491, 0.80344857518505, 0.79784664137700, 0.79197358416424, 0.78583531203920, 0.77942875190216, 0.77277808813327, 0.76586748650939,
+    0.75870807608242, 0.75131374561237, 0.74368278636488, 0.73582117582769, 0.72774489002994, 0.71944626349561, 0.71094104263095, 0.70223887193539,
+    0.69332823767032, 0.68423532934598, 0.67496631901712, 0.66551398801627, 0.65590163024671, 0.64612696959461, 0.63619801077286, 0.62612426956055,
+    0.61591099320291, 0.60557835389180, 0.59511230862496, 0.58454032354679, 0.57385241316923, 0.56307891401370, 0.55220512585061, 0.54125534487322,
+    0.53022408956855, 0.51912349702391, 0.50798175000434, 0.49677082545707, 0.48552530911099, 0.47424532146115, 0.46293080852757, 0.45159965356824,
+    0.44025537543665, 0.42891199207373, 0.41756968968409, 0.40623176767625, 0.39492117615675, 0.38363500139043, 0.37237955463061, 0.36115899031355,
+    -0.34999141229310, -0.33887226938665, -0.32781137272105, -0.31682789136456, -0.30590985751916, -0.29507167170646, -0.28432141891085, -0.27366340405625,
+    -0.26310532994603, -0.25264803095722, -0.24230168845974, -0.23206908706791, -0.22196526964149, -0.21197358538056, -0.20212501768103, -0.19239667457267,
+    -0.18281725485142, -0.17338081721706, -0.16409588556669, -0.15496070710605, -0.14597664911870, -0.13715517611934, -0.12850028503878, -0.12000779846800,
+    -0.11168269317730, -0.10353295311463, -0.09555333528914, -0.08775475365593, -0.08013729344279, -0.07269433008129, -0.06544098531359, -0.05837053268336,
+    -0.05148041767934, -0.04478068215856, -0.03827765720822, -0.03195312745332, -0.02582272888064, -0.01988341292573, -0.01412888273558, -0.00857117491366,
+    -0.00320868968304, 0.00197656014503, 0.00696368621617, 0.01176238327857, 0.01637012582228, 0.02079970728622, 0.02503075618909, 0.02908240060125,
+    0.03295839306691, 0.03664181168133, 0.04014582784127, 0.04347687821958, 0.04663033051701, 0.04959786763445, 0.05240938217366, 0.05504600343009,
+    0.05751526919867, 0.05981665708090, 0.06196027790387, 0.06394448059633, 0.06576906686508, 0.06745250215166, 0.06896640131951, 0.07035330735093,
+    0.07158263647903, 0.07267746427299, 0.07364060057620, 0.07446643947564, 0.07515762552870, 0.07573057565061, 0.07617483218536, 0.07650507183194,
+    0.07672049241746, 0.07682300113923, 0.07681739756964, 0.07670934904245, 0.07649921704119, 0.07619924793396, 0.07580083586584, 0.07531373362019,
+    0.07474525581194, 0.07410036424342, 0.07336202550803, 0.07256825833083, 0.07170026731102, 0.07076287107266, 0.06976302447127, 0.06870438283512,
+    0.06760759851228, 0.06643675122104, 0.06522471064380, 0.06397158980681, 0.06268578081172, 0.06134551717207, 0.05998374801761, 0.05859156836260,
+    0.05716164501299, 0.05571736482138, 0.05424527683589, 0.05276307465207, 0.05125561555216, 0.04973857556014, 0.04821657200672, 0.04668430272642,
+    0.04514884056413, 0.04360975421304, 0.04206490946367, 0.04053491705584, 0.03900536794745, 0.03748128504252, 0.03596975605542, 0.03446209487686,
+    0.03297540810337, 0.03150176087389, 0.03005026574279, 0.02860721736385, 0.02718594296329, 0.02578758475467, 0.02441609920285, 0.02306801692862,
+    0.02174675502535, 0.02045317933555, 0.01918724313698, 0.01794333813443, 0.01673247129989, 0.01554055533423, 0.01439046660792, 0.01327182200351,
+    -0.01218499959508, -0.01113155480321, -0.01011502154986, -0.00913253296085, -0.00817982333726, -0.00726158168517, -0.00637922932685, -0.00553372111088,
+    -0.00472225962400, -0.00394011240522, -0.00319337783900, -0.00248267236449, -0.00180394725893, -0.00115681355227, -0.00054642808664, 0.00002760451905,
+    0.00058322642480, 0.00109023290512, 0.00157846825768, 0.00202741761850, 0.00245085400321, 0.00284467578623, 0.00320918858098, 0.00354012465507,
+    0.00384564081246, 0.00412516423270, 0.00438018617447, 0.00460395301471, 0.00481094690600, 0.00498396877629, 0.00513822754514, 0.00527157587272,
+    0.00538389758970, 0.00547537830770, 0.00554043639400, 0.00559171286630, 0.00562661141932, 0.00563891995151, 0.00564551969164, 0.00562206432097,
+    0.00559380230045, 0.00554757145088, 0.00548760401507, 0.00541967759307, 0.00534716811982, 0.00524611661324, 0.00514073539032, 0.00503930226013,
+    0.00491376035745, 0.00479325608498, 0.00466064606118, 0.00452098527825, 0.00437307196781, 0.00422642692270, 0.00408197531935, 0.00392074323703,
+    0.00376039229104, 0.00360082681231, 0.00344188741828, 0.00327396134847, 0.00311254206525, 0.00294694477165, 0.00278704643465, 0.00262017586902,
+    0.00246256169126, 0.00230172547746, 0.00214615835557, 0.00198411407369, 0.00183482654224, 0.00168680832531, 0.00154432198471, 0.00139024948272,
+    0.00125778846475, 0.00112501551307, 0.00098859883015, 0.00086084433262, 0.00074580258865, 0.00062393761391, 0.00051073884952, 0.00040265402160,
+    0.00029495311041, 0.00020430170688, 0.00010943831274, 0.00001349497418, -0.00006173344072, -0.00014463809349, -0.00020983373440, -0.00028969811748,
+    -0.00035011758756, -0.00040951214522, -0.00046063254803, -0.00051455722108, -0.00055645763906, -0.00059461189330, -0.00063415949025, -0.00066504150893,
+    -0.00069179375372, -0.00072153919876, -0.00073193571525, -0.00075300014201, -0.00076307935757, -0.00077579773310, -0.00078014496257, -0.00078036647100,
+    -0.00077798694927, -0.00078343322877, -0.00077248485949, -0.00076813719270, -0.00074905980532, -0.00074409418541, -0.00072550431222, -0.00071577364744,
+    -0.00069416146273, -0.00067776907764, -0.00065403333621, -0.00063124935319, -0.00061327473938, -0.00058709304852, -0.00056778025613, -0.00054665656337,
+    -0.00052265642972, -0.00050407143497, -0.00048937912498, -0.00048752279712, -0.00049475180896, -0.00056176925738, -0.00055252865047, 0.00000000000000,
+];
+
+/// The SBR noise table `V` (Table I.13): 512 unit-variance complex values (re, im).
+#[rustfmt::skip]
+pub(crate) static NOISE: [[f32; 2]; 512] = [
+    [-0.99948153278296, -0.59483417516607], [0.97113454393991, -0.67528515225647], [0.14130051758487, -0.95090983575689], [-0.47005496701697, -0.37340549728647],
+    [0.80705063769351, 0.29653668284408], [-0.38981478896926, 0.89572605717087], [-0.01053049862020, -0.66959058036166], [-0.91266367957293, -0.11522938140034],
+    [0.54840422910309, 0.75221367176302], [0.40009252867955, -0.98929400334421], [-0.99867974711855, -0.88147068645358], [-0.95531076805040, 0.90908757154593],
+    [-0.45725933317144, -0.56716323646760], [-0.72929675029275, -0.98008272727324], [0.75622801399036, 0.20950329995549], [0.07069442601050, -0.78247898470706],
+    [0.74496252926055, -0.91169004445807], [-0.96440182703856, -0.94739918296622], [0.30424629369539, -0.49438267012479], [0.66565033746925, 0.64652935542491],
+    [0.91697008020594, 0.17514097332009], [-0.70774918760427, 0.52548653416543], [-0.70051415345560, -0.45340028808763], [-0.99496513054797, -0.90071908066973],
+    [0.98164490790123, -0.77463155528697], [-0.54671580548181, -0.02570928536004], [-0.01689629065389, 0.00287506445732], [-0.86110349531986, 0.42548583726477],
+    [-0.98892980586032, -0.87881132267556], [0.51756627678691, 0.66926784710139], [-0.99635026409640, -0.58107730574765], [-0.99969370862163, 0.98369989360250],
+    [0.55266258627194, 0.59449057465591], [0.34581177741673, 0.94879421061866], [0.62664209577999, -0.74402970906471], [-0.77149701404973, -0.33883658042801],
+    [-0.91592244254432, 0.03687901376713], [-0.76285492357887, -0.91371867919124], [0.79788337195331, -0.93180971199849], [0.54473080610200, -0.11919206037186],
+    [-0.85639281671058, 0.42429854760451], [-0.92882402971423, 0.27871809078609], [-0.11708371046774, -0.99800843444966], [0.21356749817493, -0.90716295627033],
+    [-0.76191692573909, 0.99768118356265], [0.98111043100884, -0.95854459734407], [-0.85913269895572, 0.95766566168880], [-0.93307242253692, 0.49431757696466],
+    [0.30485754879632, -0.70540034357529], [0.85289650925190, 0.46766131791044], [0.91328082618125, -0.99839597361769], [-0.05890199924154, 0.70741827819497],
+    [0.28398686150148, 0.34633555702188], [0.95258164539612, -0.54893416026939], [-0.78566324168507, -0.75568541079691], [-0.95789495447877, -0.20423194696966],
+    [0.82411158711197, 0.96654618432562], [-0.65185446735885, -0.88734990773289], [-0.93643603134666, 0.99870790442385], [0.91427159529618, -0.98290505544444],
+    [-0.70395684036886, 0.58796798221039], [0.00563771969365, 0.61768196727244], [0.89065051931895, 0.52783352697585], [-0.68683707712762, 0.80806944710339],
+    [0.72165342518718, -0.69259857349564], [-0.62928247730667, 0.13627037407335], [0.29938434065514, -0.46051329682246], [-0.91781958879280, -0.74012716684186],
+    [0.99298717043688, 0.40816610075661], [0.82368298622748, -0.74036047190173], [-0.98512833386833, -0.99972330709594], [-0.95915368242257, -0.99237800466040],
+    [-0.21411126572790, -0.93424819052545], [-0.68821476106884, -0.26892306315457], [0.91851997982317, 0.09358228901785], [-0.96062769559127, 0.36099095133739],
+    [0.51646184922287, -0.71373332873917], [0.61130721139669, 0.46950141175917], [0.47336129371299, -0.27333178296162], [0.90998308703519, 0.96715662938132],
+    [0.44844799194357, 0.99211574628306], [0.66614891079092, 0.96590176169121], [0.74922239129237, -0.89879858826087], [-0.99571588506485, 0.52785521494349],
+    [0.97401082477563, -0.16855870075190], [0.72683747733879, -0.48060774432251], [0.95432193457128, 0.68849603408441], [-0.72962208425191, -0.76608443420917],
+    [-0.85359479233537, 0.88738125901579], [-0.81412430338535, -0.97480768049637], [-0.87930772356786, 0.74748307690436], [-0.71573331064977, -0.98570608178923],
+    [0.83524300028228, 0.83702537075163], [-0.48086065601423, -0.98848504923531], [0.97139128574778, 0.80093621198236], [0.51992825347895, 0.80247631400510],
+    [-0.00848591195325, -0.76670128000486], [-0.70294374303036, 0.55359910445577], [-0.95894428168140, -0.43265504344783], [0.97079252950321, 0.09325857238682],
+    [-0.92404293670797, 0.85507704027855], [-0.69506469500450, 0.98633412625459], [0.26559203620024, 0.73314307966524], [0.28038443336943, 0.14537913654427],
+    [-0.74138124825523, 0.99310339807762], [-0.01752795995444, -0.82616635284178], [-0.55126773094930, -0.98898543862153], [0.97960898850996, -0.94021446752851],
+    [-0.99196309146936, 0.67019017358456], [-0.67684928085260, 0.12631491649378], [0.09140039465500, -0.20537731453108], [-0.71658965751996, -0.97788200391224],
+    [0.81014640078925, 0.53722648362443], [0.40616991671205, -0.26469008598449], [-0.67680188682972, 0.94502052337695], [0.86849774348749, -0.18333598647899],
+    [-0.99500381284851, -0.02634122068550], [0.84329189340667, 0.10406957462213], [-0.09215968531446, 0.69540012101253], [0.99956173327206, -0.12358542001404],
+    [-0.79732779473535, -0.91582524736159], [0.96349973642406, 0.96640458041000], [-0.79942778496547, 0.64323902822857], [-0.11566039853896, 0.28587846253726],
+    [-0.39922954514662, 0.94129601616966], [0.99089197565987, -0.92062625581587], [0.28631285179909, -0.91035047143603], [-0.83302725605608, -0.67330410892084],
+    [0.95404443402072, 0.49162765398743], [-0.06449863579434, 0.03250560813135], [-0.99575054486311, 0.42389784469507], [-0.65501142790847, 0.82546114655624],
+    [-0.81254441908887, -0.51627234660629], [-0.99646369485481, 0.84490533520752], [0.00287840603348, 0.64768261158166], [0.70176989408455, -0.20453028573322],
+    [0.96361882270190, 0.40706967140989], [-0.68883758192426, 0.91338958840772], [-0.34875585502238, 0.71472290693300], [0.91980081243087, 0.66507455644919],
+    [-0.99009048343881, 0.85868021604848], [0.68865791458395, 0.55660316809678], [-0.99484402129368, -0.20052559254934], [0.94214511408023, -0.99696425367461],
+    [-0.67414626793544, 0.49548221180078], [-0.47339353684664, -0.85904328834047], [0.14323651387360, -0.94145598222488], [-0.29268293575672, 0.05759224927952],
+    [0.43793861458754, -0.78904969892724], [-0.36345126374441, 0.64874435357162], [-0.08750604656825, 0.97686944362527], [-0.96495267812511, -0.53960305946511],
+    [0.55526940659947, 0.78891523734774], [0.73538215752630, 0.96452072373404], [-0.30889773919437, -0.80664389776860], [0.03574995626194, -0.97325616900959],
+    [0.98720684660488, 0.48409133691962], [-0.81689296271203, -0.90827703628298], [0.67866860118215, 0.81284503870856], [-0.15808569732583, 0.85279555024382],
+    [0.80723395114371, -0.24717418514605], [0.47788757329038, -0.46333147839295], [0.96367554763201, 0.38486749303242], [-0.99143875716818, -0.24945277239809],
+    [0.83081876925833, -0.94780851414763], [-0.58753191905341, 0.01290772389163], [0.95538108220960, -0.85557052096538], [-0.96490920476211, -0.64020970923102],
+    [-0.97327101028521, 0.12378128133110], [0.91400366022124, 0.57972471346930], [-0.99925837363824, 0.71084847864067], [-0.86875903507313, -0.20291699203564],
+    [-0.26240034795124, -0.68264554369108], [-0.24664412953388, -0.87642273115183], [0.02416275806869, 0.27192914288905], [0.82068619590515, -0.85087787994476],
+    [0.88547373760759, -0.89636802901469], [-0.18173078152226, -0.26152145156800], [0.09355476558534, 0.54845123045604], [-0.54668414224090, 0.95980774020221],
+    [0.37050990604091, -0.59910140383171], [-0.70373594262891, 0.91227665827081], [-0.34600785879594, -0.99441426144200], [-0.68774481731008, -0.30238837956299],
+    [-0.26843291251234, 0.83115668004362], [0.49072334613242, -0.45359708737775], [0.38975993093975, 0.95515358099121], [-0.97757125224150, 0.05305894580606],
+    [-0.17325552859616, -0.92770672250494], [0.99948035025744, 0.58285545563426], [-0.64946246527458, 0.68645507104960], [-0.12016920576437, -0.57147322153312],
+    [-0.58947456517751, -0.34847132454388], [-0.41815140454465, 0.16276422358861], [0.99885650204884, 0.11136095490444], [-0.56649614128386, -0.90494866361587],
+    [0.94138021032330, 0.35281916733018], [-0.75725076534641, 0.53650549640587], [0.20541973692630, -0.94435144369918], [0.99980371023351, 0.79835913565599],
+    [0.29078277605775, 0.35393777921520], [-0.62858772103030, 0.38765693387102], [0.43440904467688, -0.98546330463232], [-0.98298583762390, 0.21021524625209],
+    [0.19513029146934, -0.94239832251867], [-0.95476662400101, 0.98364554179143], [0.93379635304810, -0.70881994583682], [-0.85235410573336, -0.08342347966410],
+    [-0.86425093011245, -0.45795025029466], [0.38879779059045, 0.97274429344593], [0.92045124735495, -0.62433652524220], [0.89162532251878, 0.54950955570563],
+    [-0.36834336949252, 0.96458298020975], [0.93891760988045, -0.89968353740388], [0.99267657565094, -0.03757034316958], [-0.94063471614176, 0.41332338538963],
+    [0.99740224117019, -0.16830494996370], [-0.35899413170555, -0.46633226649613], [0.05237237274947, -0.25640361602661], [0.36703583957424, -0.38653265641875],
+    [0.91653180367913, -0.30587628726597], [0.69000803499316, 0.90952171386132], [-0.38658751133527, 0.99501571208985], [-0.29250814029851, 0.37444994344615],
+    [-0.60182204677608, 0.86779651036123], [-0.97418588163217, 0.96468523666475], [0.88461574003963, 0.57508405276414], [0.05198933055162, 0.21269661669964],
+    [-0.53499621979720, 0.97241553731237], [-0.49429560226497, 0.98183865291903], [-0.98935142339139, -0.40249159006933], [-0.98081380091130, -0.72856895534041],
+    [-0.27338148835532, 0.99950922447209], [0.06310802338302, -0.54539587529618], [-0.20461677199539, -0.14209977628489], [0.66223843141647, 0.72528579940326],
+    [-0.84764345483665, 0.02372316801261], [-0.89039863483811, 0.88866581484602], [0.95903308477986, 0.76744927173873], [0.73504123909879, -0.03747203173192],
+    [-0.31744434966056, -0.36834111883652], [-0.34110827591623, 0.40211222807691], [0.47803883714199, -0.39423219786288], [0.98299195879514, 0.01989791390047],
+    [-0.30963073129751, -0.18076720599336], [0.99992588229018, -0.26281872094289], [-0.93149731080767, -0.98313162570490], [0.99923472302773, -0.80142993767554],
+    [-0.26024169633417, -0.75999759855752], [-0.35712514743563, 0.19298963768574], [-0.99899084509530, 0.74645156992493], [0.86557171579452, 0.55593866696299],
+    [0.33408042438752, 0.86185953874709], [0.99010736374716, 0.04602397576623], [-0.66694269691195, -0.91643611810148], [0.64016792079480, 0.15649530836856],
+    [0.99570534804836, 0.45844586038111], [-0.63431466947340, 0.21079116459234], [-0.07706847005931, -0.89581437101329], [0.98590090577724, 0.88241721133981],
+    [0.80099335254678, -0.36851896710853], [0.78368131392666, 0.45506999802597], [0.08707806671691, 0.80938994918745], [-0.86811883080712, 0.39347308654705],
+    [-0.39466529740375, -0.66809432114456], [0.97875325649683, -0.72467840967746], [-0.95038560288864, 0.89563219587625], [0.17005239424212, 0.54683053962658],
+    [-0.76910792026848, -0.96226617549298], [0.99743281016846, 0.42697157037567], [0.95437383549973, 0.97002324109952], [0.99578905365569, -0.54106826257356],
+    [0.28058259829990, -0.85361420634036], [0.85256524470573, -0.64567607735589], [-0.50608540105128, -0.65846015480300], [-0.97210735183243, -0.23095213067791],
+    [0.95424048234441, -0.99240147091219], [-0.96926570524023, 0.73775654896574], [0.30872163214726, 0.41514960556126], [-0.24523839572639, 0.63206633394807],
+    [-0.33813265086024, -0.38661779441897], [-0.05826828420146, -0.06940774188029], [-0.22898461455054, 0.97054853316316], [-0.18509915019881, 0.47565762892084],
+    [-0.10488238045009, -0.87769947402394], [-0.71886586182037, 0.78030982480538], [0.99793873738654, 0.90041310491497], [0.57563307626120, -0.91034337352097],
+    [0.28909646383717, 0.96307783970534], [0.42188998312520, 0.48148651230437], [0.93335049681047, -0.43537023883588], [-0.97087374418267, 0.86636445711364],
+    [0.36722871286923, 0.65291654172961], [-0.81093025665696, 0.08778370229363], [-0.26240603062237, -0.92774095379098], [0.83996497984604, 0.55839849139647],
+    [-0.99909615720225, -0.96024605713970], [0.74649464155061, 0.12144893606462], [-0.74774595569805, -0.26898062008959], [0.95781667469567, -0.79047927052628],
+    [0.95472308713099, -0.08588776019550], [0.48708332746299, 0.99999041579432], [0.46332038247497, 0.10964126185063], [-0.76497004940162, 0.89210929242238],
+    [0.57397389364339, 0.35289703373760], [0.75374316974495, 0.96705214651335], [-0.59174397685714, -0.89405370422752], [0.75087906691890, -0.29612672982396],
+    [-0.98607857336230, 0.25034911730023], [-0.40761056640505, -0.90045573444695], [0.66929266740477, 0.98629493401748], [-0.97463695257310, -0.00190223301301],
+    [0.90145509409859, 0.99781390365446], [-0.87259289048043, 0.99233587353666], [-0.91529461447692, -0.15698707534206], [-0.03305738840705, -0.37205262859764],
+    [0.07223051368337, -0.88805001733626], [0.99498012188353, 0.97094358113387], [-0.74904939500519, 0.99985483641521], [0.04585228574211, 0.99812337444082],
+    [-0.89054954257993, -0.31791913188064], [-0.83782144651251, 0.97637632547466], [0.33454804933804, -0.86231516800408], [-0.99707579362824, 0.93237990079441],
+    [-0.22827527843994, 0.18874759397997], [0.67248046289143, -0.03646211390569], [-0.05146538187944, -0.92599700120679], [0.99947295749905, 0.93625229707912],
+    [0.66951124390363, 0.98905825623893], [-0.99602956559179, -0.44654715757688], [0.82104905483590, 0.99540741724928], [0.99186510988782, 0.72023001312947],
+    [-0.65284592392918, 0.52186723253637], [0.93885443798188, -0.74895312615259], [0.96735248738388, 0.90891816978629], [-0.22225968841114, 0.57124029781228],
+    [-0.44132783753414, -0.92688840659280], [-0.85694974219574, 0.88844532719844], [0.91783042091762, -0.46356892383970], [0.72556974415690, -0.99899555770747],
+    [-0.99711581834508, 0.58211560180426], [0.77638976371966, 0.94321834873819], [0.07717324253925, 0.58638399856595], [-0.56049829194163, 0.82522301569036],
+    [0.98398893639988, 0.39467440420569], [0.47546946844938, 0.68613044836811], [0.65675089314631, 0.18331637134880], [0.03273375457980, -0.74933109564108],
+    [-0.38684144784738, 0.51337349030406], [-0.97346267944545, -0.96549364384098], [-0.53282156061942, -0.91423265091354], [0.99817310731176, 0.61133572482148],
+    [-0.50254500772635, -0.88829338134294], [0.01995873238855, 0.85223515096765], [0.99930381973804, 0.94578896296649], [0.82907767600783, -0.06323442598128],
+    [-0.58660709669728, 0.96840773806582], [-0.17573736667267, -0.48166920859485], [0.83434292401346, -0.13023450646997], [0.05946491307025, 0.20511047074866],
+    [0.81505484574602, -0.94685947861369], [-0.44976380954860, 0.40894572671545], [-0.89746474625671, 0.99846578838537], [0.39677256130792, -0.74854668609359],
+    [-0.07588948563079, 0.74096214084170], [0.76343198951445, 0.41746629422634], [-0.74490104699626, 0.94725911744610], [0.64880119792759, 0.41336660830571],
+    [0.62319537462542, -0.93098313552599], [0.42215817594807, -0.07712787385208], [0.02704554141885, -0.05417518053666], [0.80001773566818, 0.91542195141039],
+    [-0.79351832348816, -0.36208897989136], [0.63872359151636, 0.08128252493444], [0.52890520960295, 0.60048872455592], [0.74238552914587, 0.04491915291044],
+    [0.99096131449250, -0.19451182854402], [-0.80412329643109, -0.88513818199457], [-0.64612616129736, 0.72198674804544], [0.11657770663191, -0.83662833815041],
+    [-0.95053182488101, -0.96939905138082], [-0.62228872928622, 0.82767262846661], [0.03004475787316, -0.99738896333384], [-0.97987214341034, 0.36526129686425],
+    [-0.99986980746200, -0.36021610299715], [0.89110648599879, -0.97894250343044], [0.10407960510582, 0.77357793811619], [0.95964737821728, -0.35435818285502],
+    [0.50843233159162, 0.96107691266205], [0.17006334670615, -0.76854025314829], [0.25872675063360, 0.99893303933816], [-0.01115998681937, 0.98496019742444],
+    [-0.79598702973261, 0.97138411318894], [-0.99264708948101, -0.99542822402536], [-0.99829663752818, 0.01877138824311], [-0.70801016548184, 0.33680685948117],
+    [-0.70467057786826, 0.93272777501857], [0.99846021905254, -0.98725746254433], [-0.63364968534650, -0.16473594423746], [-0.16258217500792, -0.95939125400802],
+    [-0.43645594360633, -0.94805030113284], [-0.99848471702976, 0.96245166923809], [-0.16796458968998, -0.98987511890470], [-0.87979225745213, -0.71725725041680],
+    [0.44183099021786, -0.93568974498761], [0.93310180125532, -0.99913308068246], [-0.93941931782002, -0.56409379640356], [-0.88590003188677, 0.47624600491382],
+    [0.99971463703691, -0.83889954253462], [-0.75376385639978, 0.00814643438625], [0.93887685615875, -0.11284528204636], [0.85126435782309, 0.52349251543547],
+    [0.39701421446381, 0.81779634174316], [-0.37024464187437, -0.87071656222959], [-0.36024828242896, 0.34655735648287], [-0.93388812549209, -0.84476541096429],
+    [-0.65298804552119, -0.18439575450921], [0.11960319006843, 0.99899346780168], [0.94292565553160, 0.83163906518293], [0.75081145286948, -0.35533223142265],
+    [0.56721979748394, -0.24076836414499], [0.46857766746029, -0.30140233457198], [0.97312313923635, -0.99548191630031], [-0.38299976567017, 0.98516909715427],
+    [0.41025800019463, 0.02116736935734], [0.09638062008048, 0.04411984381457], [-0.85283249275397, 0.91475563922421], [0.88866808958124, -0.99735267083226],
+    [-0.48202429536989, -0.96805608884164], [0.27572582416567, 0.58634753335832], [-0.65889129659168, 0.58835634138583], [0.98838086953732, 0.99994349600236],
+    [-0.20651349620689, 0.54593044066355], [-0.62126416356920, -0.59893681700392], [0.20320105410437, -0.86879180355289], [-0.97790548600584, 0.96290806999242],
+    [0.11112534735126, 0.21484763313301], [-0.41368337314182, 0.28216837680365], [0.24133038992960, 0.51294362630238], [-0.66393410674885, -0.08249679629081],
+    [-0.53697829178752, -0.97649903936228], [-0.97224737889348, 0.22081333579837], [0.87392477144549, -0.12796173740361], [0.19050361015753, 0.01602615387195],
+    [-0.46353441212724, -0.95249041539006], [-0.07064096339021, -0.94479803205886], [-0.92444085484466, -0.10457590187436], [-0.83822593578728, -0.01695043208885],
+    [0.75214681811150, -0.99955681042665], [-0.42102998829339, 0.99720941999394], [-0.72094786237696, -0.35008961934255], [0.78843311019251, 0.52851398958271],
+    [0.97394027897442, -0.26695944086561], [0.99206463477946, -0.57010120849429], [0.76789609461795, -0.76519356730966], [-0.82002421836409, -0.73530179553767],
+    [0.81924990025724, 0.99698425250579], [-0.26719850873357, 0.68903369776193], [-0.43311260380975, 0.85321815947490], [0.99194979673836, 0.91876249766422],
+    [-0.80692001248487, -0.32627540663214], [0.43080003649976, -0.21919095636638], [0.67709491937357, -0.95478075822906], [0.56151770568316, -0.70693811747778],
+    [0.10831862810749, -0.08628837174592], [0.91229417540436, -0.65987351408410], [-0.48972893932274, 0.56289246362686], [-0.89033658689697, -0.71656563987082],
+    [0.65269447475094, 0.65916004833932], [0.67439478141121, -0.81684380846796], [-0.47770832416973, -0.16789556203025], [-0.99715979260878, -0.93565784007648],
+    [-0.90889593602546, 0.62034397054380], [-0.06618622548177, -0.23812217221359], [0.99430266919728, 0.18812555317553], [0.97686402381843, -0.28664534366620],
+    [0.94813650221268, -0.97506640027128], [-0.95434497492853, -0.79607978501983], [-0.49104783137150, 0.32895214359663], [0.99881175120751, 0.88993983831354],
+    [0.50449166760303, -0.85995072408434], [0.47162891065108, -0.18680204049569], [-0.62081581361840, 0.75000676218956], [-0.43867015250812, 0.99998069244322],
+    [0.98630563232075, -0.53578899600662], [-0.61510362277374, -0.89515019899997], [-0.03841517601843, -0.69888815681179], [-0.30102157304644, -0.07667808922205],
+    [0.41881284182683, 0.02188098922282], [-0.86135454941237, 0.98947480909359], [0.67226861393788, -0.13494389011014], [-0.70737398842068, -0.76547349325992],
+    [0.94044946687963, 0.09026201157416], [-0.82386352534327, 0.08924768823676], [-0.32070666698656, 0.50143421908753], [0.57593163224487, -0.98966422921509],
+    [-0.36326018419965, 0.07440243123228], [0.99979044674350, -0.14130287347405], [-0.92366023326932, -0.97979298068180], [-0.44607178518598, -0.54233252016394],
+    [0.44226800932956, 0.71326756742752], [0.03671907158312, 0.63606389366675], [0.52175424682195, -0.85396826735705], [-0.94701139690956, -0.01826348194255],
+    [-0.98759606946049, 0.82288714303073], [0.87434794743625, 0.89399495655433], [-0.93412041758744, 0.41374052024363], [0.96063943315511, 0.93116709541280],
+    [0.97534253457837, 0.86150930812689], [0.99642466504163, 0.70190043427512], [-0.94705089665984, -0.29580042814306], [0.91599807087376, -0.98147830385781],
+];
+
+/// `t_huffman_env_1_5dB` (`(codeword, length)` by index): envelope, time direction, 1.5 dB steps (LAV 60).
+#[rustfmt::skip]
+pub(crate) static T_ENV_1_5DB: [(u32, u8); 121] = [
+    (0x3ffd6, 18), (0x3ffd7, 18), (0x3ffd8, 18), (0x3ffd9, 18), (0x3ffda, 18), (0x3ffdb, 18), (0x7ffb8, 19), (0x7ffb9, 19),
+    (0x7ffba, 19), (0x7ffbb, 19), (0x7ffbc, 19), (0x7ffbd, 19), (0x7ffbe, 19), (0x7ffbf, 19), (0x7ffc0, 19), (0x7ffc1, 19),
+    (0x7ffc2, 19), (0x7ffc3, 19), (0x7ffc4, 19), (0x7ffc5, 19), (0x7ffc6, 19), (0x7ffc7, 19), (0x7ffc8, 19), (0x7ffc9, 19),
+    (0x7ffca, 19), (0x7ffcb, 19), (0x7ffcc, 19), (0x7ffcd, 19), (0x7ffce, 19), (0x7ffcf, 19), (0x7ffd0, 19), (0x7ffd1, 19),
+    (0x7ffd2, 19), (0x7ffd3, 19), (0x1ffe6, 17), (0x3ffd4, 18), (0xfff0, 16), (0x1ffe9, 17), (0x3ffd5, 18), (0x1ffe7, 17),
+    (0xfff1, 16), (0xffec, 16), (0xffed, 16), (0xffee, 16), (0x7ff4, 15), (0x3ff9, 14), (0x3ff7, 14), (0x1ffa, 13),
+    (0x1ff9, 13), (0xffb, 12), (0x7fc, 11), (0x3fc, 10), (0x1fd, 9), (0xfd, 8), (0x7d, 7), (0x3d, 6),
+    (0x1d, 5), (0xd, 4), (0x5, 3), (0x1, 2), (0x0, 2), (0x4, 3), (0xc, 4), (0x1c, 5),
+    (0x3c, 6), (0x7c, 7), (0xfc, 8), (0x1fc, 9), (0x3fd, 10), (0xffa, 12), (0x1ff8, 13), (0x3ff6, 14),
+    (0x3ff8, 14), (0x7ff5, 15), (0xffef, 16), (0x1ffe8, 17), (0xfff2, 16), (0x7ffd4, 19), (0x7ffd5, 19), (0x7ffd6, 19),
+    (0x7ffd7, 19), (0x7ffd8, 19), (0x7ffd9, 19), (0x7ffda, 19), (0x7ffdb, 19), (0x7ffdc, 19), (0x7ffdd, 19), (0x7ffde, 19),
+    (0x7ffdf, 19), (0x7ffe0, 19), (0x7ffe1, 19), (0x7ffe2, 19), (0x7ffe3, 19), (0x7ffe4, 19), (0x7ffe5, 19), (0x7ffe6, 19),
+    (0x7ffe7, 19), (0x7ffe8, 19), (0x7ffe9, 19), (0x7ffea, 19), (0x7ffeb, 19), (0x7ffec, 19), (0x7ffed, 19), (0x7ffee, 19),
+    (0x7ffef, 19), (0x7fff0, 19), (0x7fff1, 19), (0x7fff2, 19), (0x7fff3, 19), (0x7fff4, 19), (0x7fff5, 19), (0x7fff6, 19),
+    (0x7fff7, 19), (0x7fff8, 19), (0x7fff9, 19), (0x7fffa, 19), (0x7fffb, 19), (0x7fffc, 19), (0x7fffd, 19), (0x7fffe, 19),
+    (0x7ffff, 19),
+];
+
+/// `f_huffman_env_1_5dB` (`(codeword, length)` by index): envelope, frequency direction, 1.5 dB steps (LAV 60).
+#[rustfmt::skip]
+pub(crate) static F_ENV_1_5DB: [(u32, u8); 121] = [
+    (0x7ffe7, 19), (0x7ffe8, 19), (0xfffd2, 20), (0xfffd3, 20), (0xfffd4, 20), (0xfffd5, 20), (0xfffd6, 20), (0xfffd7, 20),
+    (0xfffd8, 20), (0x7ffda, 19), (0xfffd9, 20), (0xfffda, 20), (0xfffdb, 20), (0xfffdc, 20), (0x7ffdb, 19), (0xfffdd, 20),
+    (0x7ffdc, 19), (0x7ffdd, 19), (0xfffde, 20), (0x3ffe4, 18), (0xfffdf, 20), (0xfffe0, 20), (0xfffe1, 20), (0x7ffde, 19),
+    (0xfffe2, 20), (0xfffe3, 20), (0xfffe4, 20), (0x7ffdf, 19), (0xfffe5, 20), (0x7ffe0, 19), (0x3ffe8, 18), (0x7ffe1, 19),
+    (0x3ffe0, 18), (0x3ffe9, 18), (0x1ffef, 17), (0x3ffe5, 18), (0x1ffec, 17), (0x1ffed, 17), (0x1ffee, 17), (0xfff4, 16),
+    (0xfff3, 16), (0xfff0, 16), (0x7ff7, 15), (0x7ff6, 15), (0x3ffa, 14), (0x1ffa, 13), (0x1ff9, 13), (0xffa, 12),
+    (0xff8, 12), (0x7f9, 11), (0x3fb, 10), (0x1fc, 9), (0x1fa, 9), (0xfb, 8), (0x7c, 7), (0x3c, 6),
+    (0x1c, 5), (0xc, 4), (0x5, 3), (0x1, 2), (0x0, 2), (0x4, 3), (0xd, 4), (0x1d, 5),
+    (0x3d, 6), (0xfa, 8), (0xfc, 8), (0x1fb, 9), (0x3fa, 10), (0x7f8, 11), (0x7fa, 11), (0x7fb, 11),
+    (0xff9, 12), (0xffb, 12), (0x1ff8, 13), (0x1ffb, 13), (0x3ff8, 14), (0x3ff9, 14), (0xfff1, 16), (0xfff2, 16),
+    (0x1ffea, 17), (0x1ffeb, 17), (0x3ffe1, 18), (0x3ffe2, 18), (0x3ffea, 18), (0x3ffe3, 18), (0x3ffe6, 18), (0x3ffe7, 18),
+    (0x3ffeb, 18), (0xfffe6, 20), (0x7ffe2, 19), (0xfffe7, 20), (0xfffe8, 20), (0xfffe9, 20), (0xfffea, 20), (0xfffeb, 20),
+    (0xfffec, 20), (0x7ffe3, 19), (0xfffed, 20), (0xfffee, 20), (0xfffef, 20), (0xffff0, 20), (0x7ffe4, 19), (0xffff1, 20),
+    (0x3ffec, 18), (0xffff2, 20), (0xffff3, 20), (0x7ffe5, 19), (0x7ffe6, 19), (0xffff4, 20), (0xffff5, 20), (0xffff6, 20),
+    (0xffff7, 20), (0xffff8, 20), (0xffff9, 20), (0xffffa, 20), (0xffffb, 20), (0xffffc, 20), (0xffffd, 20), (0xffffe, 20),
+    (0xfffff, 20),
+];
+
+/// `t_huffman_env_bal_1_5dB` (`(codeword, length)` by index): envelope balance, time direction, 1.5 dB steps (LAV 24).
+#[rustfmt::skip]
+pub(crate) static T_ENV_BAL_1_5DB: [(u32, u8); 49] = [
+    (0xffe4, 16), (0xffe5, 16), (0xffe6, 16), (0xffe7, 16), (0xffe8, 16), (0xffe9, 16), (0xffea, 16), (0xffeb, 16),
+    (0xffec, 16), (0xffed, 16), (0xffee, 16), (0xffef, 16), (0xfff0, 16), (0xfff1, 16), (0xfff2, 16), (0xfff3, 16),
+    (0xfff4, 16), (0xffe2, 16), (0xffc, 12), (0x7fc, 11), (0x1fe, 9), (0x7e, 7), (0x1e, 5), (0x6, 3),
+    (0x0, 1), (0x2, 2), (0xe, 4), (0x3e, 6), (0xfe, 8), (0x7fd, 11), (0xffd, 12), (0x7ff0, 15),
+    (0xffe3, 16), (0xfff5, 16), (0xfff6, 16), (0xfff7, 16), (0xfff8, 16), (0xfff9, 16), (0xfffa, 16), (0x1fff6, 17),
+    (0x1fff7, 17), (0x1fff8, 17), (0x1fff9, 17), (0x1fffa, 17), (0x1fffb, 17), (0x1fffc, 17), (0x1fffd, 17), (0x1fffe, 17),
+    (0x1ffff, 17),
+];
+
+/// `f_huffman_env_bal_1_5dB` (`(codeword, length)` by index): envelope balance, frequency direction, 1.5 dB steps (LAV 24).
+#[rustfmt::skip]
+pub(crate) static F_ENV_BAL_1_5DB: [(u32, u8); 49] = [
+    (0x3ffe2, 18), (0x3ffe3, 18), (0x3ffe4, 18), (0x3ffe5, 18), (0x3ffe6, 18), (0x3ffe7, 18), (0x3ffe8, 18), (0x3ffe9, 18),
+    (0x3ffea, 18), (0x3ffeb, 18), (0x3ffec, 18), (0x3ffed, 18), (0x3ffee, 18), (0x3ffef, 18), (0x3fff0, 18), (0xfff7, 16),
+    (0x1fff0, 17), (0x3ffc, 14), (0x7fe, 11), (0x7fc, 11), (0xfe, 8), (0x7e, 7), (0xe, 4), (0x2, 2),
+    (0x0, 1), (0x6, 3), (0x1e, 5), (0x3e, 6), (0x1fe, 9), (0x7fd, 11), (0xffe, 12), (0x7ffa, 15),
+    (0xfff6, 16), (0x3fff1, 18), (0x3fff2, 18), (0x3fff3, 18), (0x3fff4, 18), (0x3fff5, 18), (0x3fff6, 18), (0x3fff7, 18),
+    (0x3fff8, 18), (0x3fff9, 18), (0x3fffa, 18), (0x3fffb, 18), (0x3fffc, 18), (0x3fffd, 18), (0x3fffe, 18), (0x7fffe, 19),
+    (0x7ffff, 19),
+];
+
+/// `t_huffman_env_3_0dB` (`(codeword, length)` by index): envelope, time direction, 3 dB steps (LAV 31).
+#[rustfmt::skip]
+pub(crate) static T_ENV_3_0DB: [(u32, u8); 63] = [
+    (0x3ffed, 18), (0x3ffee, 18), (0x7ffde, 19), (0x7ffdf, 19), (0x7ffe0, 19), (0x7ffe1, 19), (0x7ffe2, 19), (0x7ffe3, 19),
+    (0x7ffe4, 19), (0x7ffe5, 19), (0x7ffe6, 19), (0x7ffe7, 19), (0x7ffe8, 19), (0x7ffe9, 19), (0x7ffea, 19), (0x7ffeb, 19),
+    (0x7ffec, 19), (0x1fff4, 17), (0xfff7, 16), (0xfff9, 16), (0xfff8, 16), (0x3ffb, 14), (0x3ffa, 14), (0x3ff8, 14),
+    (0x1ffa, 13), (0xffc, 12), (0x7fc, 11), (0xfe, 8), (0x3e, 6), (0xe, 4), (0x2, 2), (0x0, 1),
+    (0x6, 3), (0x1e, 5), (0x7e, 7), (0x1fe, 9), (0x7fd, 11), (0x1ffb, 13), (0x3ff9, 14), (0x3ffc, 14),
+    (0x7ffa, 15), (0xfff6, 16), (0x1fff5, 17), (0x3ffec, 18), (0x7ffed, 19), (0x7ffee, 19), (0x7ffef, 19), (0x7fff0, 19),
+    (0x7fff1, 19), (0x7fff2, 19), (0x7fff3, 19), (0x7fff4, 19), (0x7fff5, 19), (0x7fff6, 19), (0x7fff7, 19), (0x7fff8, 19),
+    (0x7fff9, 19), (0x7fffa, 19), (0x7fffb, 19), (0x7fffc, 19), (0x7fffd, 19), (0x7fffe, 19), (0x7ffff, 19),
+];
+
+/// `f_huffman_env_3_0dB` (`(codeword, length)` by index): envelope and noise floor, frequency direction, 3 dB steps (LAV 31).
+#[rustfmt::skip]
+pub(crate) static F_ENV_3_0DB: [(u32, u8); 63] = [
+    (0xffff0, 20), (0xffff1, 20), (0xffff2, 20), (0xffff3, 20), (0xffff4, 20), (0xffff5, 20), (0xffff6, 20), (0x3fff3, 18),
+    (0x7fff5, 19), (0x7ffee, 19), (0x7ffef, 19), (0x7fff6, 19), (0x3fff4, 18), (0x3fff2, 18), (0xffff7, 20), (0x7fff0, 19),
+    (0x1fff5, 17), (0x3fff0, 18), (0x1fff4, 17), (0xfff7, 16), (0xfff6, 16), (0x7ff8, 15), (0x3ffb, 14), (0xffd, 12),
+    (0x7fd, 11), (0x3fd, 10), (0x1fd, 9), (0xfd, 8), (0x3e, 6), (0xe, 4), (0x2, 2), (0x0, 1),
+    (0x6, 3), (0x1e, 5), (0xfc, 8), (0x1fc, 9), (0x3fc, 10), (0x7fc, 11), (0xffc, 12), (0x1ffc, 13),
+    (0x3ffa, 14), (0x7ff9, 15), (0x7ffa, 15), (0xfff8, 16), (0xfff9, 16), (0x1fff6, 17), (0x1fff7, 17), (0x3fff5, 18),
+    (0x3fff6, 18), (0x3fff1, 18), (0xffff8, 20), (0x7fff1, 19), (0x7fff2, 19), (0x7fff3, 19), (0xffff9, 20), (0x7fff7, 19),
+    (0x7fff4, 19), (0xffffa, 20), (0xffffb, 20), (0xffffc, 20), (0xffffd, 20), (0xffffe, 20), (0xfffff, 20),
+];
+
+/// `t_huffman_env_bal_3_0dB` (`(codeword, length)` by index): envelope balance, time direction, 3 dB steps (LAV 12).
+#[rustfmt::skip]
+pub(crate) static T_ENV_BAL_3_0DB: [(u32, u8); 25] = [
+    (0x1ff2, 13), (0x1ff3, 13), (0x1ff4, 13), (0x1ff5, 13), (0x1ff6, 13), (0x1ff7, 13), (0x1ff8, 13), (0xff8, 12),
+    (0xfe, 8), (0x7e, 7), (0xe, 4), (0x6, 3), (0x0, 1), (0x2, 2), (0x1e, 5), (0x3e, 6),
+    (0x1fe, 9), (0x1ff9, 13), (0x1ffa, 13), (0x1ffb, 13), (0x1ffc, 13), (0x1ffd, 13), (0x1ffe, 13), (0x3ffe, 14),
+    (0x3fff, 14),
+];
+
+/// `f_huffman_env_bal_3_0dB` (`(codeword, length)` by index): envelope and noise floor balance, frequency direction, 3 dB steps (LAV 12).
+#[rustfmt::skip]
+pub(crate) static F_ENV_BAL_3_0DB: [(u32, u8); 25] = [
+    (0x1ff7, 13), (0x1ff8, 13), (0x1ff9, 13), (0x1ffa, 13), (0x1ffb, 13), (0x3ff8, 14), (0x3ff9, 14), (0x7fc, 11),
+    (0xfe, 8), (0x7e, 7), (0xe, 4), (0x2, 2), (0x0, 1), (0x6, 3), (0x1e, 5), (0x3e, 6),
+    (0x1fe, 9), (0xffa, 12), (0x1ff6, 13), (0x3ffa, 14), (0x3ffb, 14), (0x3ffc, 14), (0x3ffd, 14), (0x3ffe, 14),
+    (0x3fff, 14),
+];
+
+/// `t_huffman_noise_3_0dB` (`(codeword, length)` by index): noise floor, time direction (LAV 31).
+#[rustfmt::skip]
+pub(crate) static T_NOISE_3_0DB: [(u32, u8); 63] = [
+    (0x1fce, 13), (0x1fcf, 13), (0x1fd0, 13), (0x1fd1, 13), (0x1fd2, 13), (0x1fd3, 13), (0x1fd4, 13), (0x1fd5, 13),
+    (0x1fd6, 13), (0x1fd7, 13), (0x1fd8, 13), (0x1fd9, 13), (0x1fda, 13), (0x1fdb, 13), (0x1fdc, 13), (0x1fdd, 13),
+    (0x1fde, 13), (0x1fdf, 13), (0x1fe0, 13), (0x1fe1, 13), (0x1fe2, 13), (0x1fe3, 13), (0x1fe4, 13), (0x1fe5, 13),
+    (0x1fe6, 13), (0x1fe7, 13), (0x7f2, 11), (0xfd, 8), (0x3e, 6), (0xe, 4), (0x6, 3), (0x0, 1),
+    (0x2, 2), (0x1e, 5), (0xfc, 8), (0x3f8, 10), (0x1fcc, 13), (0x1fe8, 13), (0x1fe9, 13), (0x1fea, 13),
+    (0x1feb, 13), (0x1fec, 13), (0x1fcd, 13), (0x1fed, 13), (0x1fee, 13), (0x1fef, 13), (0x1ff0, 13), (0x1ff1, 13),
+    (0x1ff2, 13), (0x1ff3, 13), (0x1ff4, 13), (0x1ff5, 13), (0x1ff6, 13), (0x1ff7, 13), (0x1ff8, 13), (0x1ff9, 13),
+    (0x1ffa, 13), (0x1ffb, 13), (0x1ffc, 13), (0x1ffd, 13), (0x1ffe, 13), (0x3ffe, 14), (0x3fff, 14),
+];
+
+/// `t_huffman_noise_bal_3_0dB` (`(codeword, length)` by index): noise floor balance, time direction (LAV 12).
+#[rustfmt::skip]
+pub(crate) static T_NOISE_BAL_3_0DB: [(u32, u8); 25] = [
+    (0xec, 8), (0xed, 8), (0xee, 8), (0xef, 8), (0xf0, 8), (0xf1, 8), (0xf2, 8), (0xf3, 8),
+    (0xf4, 8), (0xf5, 8), (0x1c, 5), (0x2, 2), (0x0, 1), (0x6, 3), (0x3a, 6), (0xf6, 8),
+    (0xf7, 8), (0xf8, 8), (0xf9, 8), (0xfa, 8), (0xfb, 8), (0xfc, 8), (0xfd, 8), (0xfe, 8),
+    (0xff, 8),
+];
diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs
index 3ed684245..f8441a51d 100644
--- a/crates/audio/src/lib.rs
+++ b/crates/audio/src/lib.rs
@@ -24,9 +24,9 @@
 //!   file bit for bit, and minimal files around such PCM, for essence embedded in other containers.
 //! - [`peaks`] (feature `peaks`): min/max/RMS pyramid for waveform drawing.
 //! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`,
-//!   `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`), [`ac3`]
-//!   (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] (`mp3-decode`, `mp3-encode`),
-//!   [`flac`] (`flac-encode`: the packet encoder).
+//!   `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and
+//!   [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`]
+//!   (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder).
 //!
 //! The shared types below build with no features.
 
@@ -42,7 +42,7 @@ mod layout;
 pub mod mp3;
 #[cfg(feature = "mpa-decode")]
 pub mod mpa;
-#[cfg(feature = "opus-decode")]
+#[cfg(any(feature = "opus-decode", feature = "opus-encode"))]
 pub mod opus;
 #[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))]
 mod pcm;
@@ -207,6 +207,13 @@ impl From<alac::Error> for AudioError {
     }
 }
 
+#[cfg(feature = "opus-encode")]
+impl From<opus::encoder::Error> for AudioError {
+    fn from(e: opus::encoder::Error) -> Self {
+        AudioError::Encode(e.to_string())
+    }
+}
+
 /// The file formats [`encode`] writes. Each needs its feature: WAV and AIFF `pcm-encode`, FLAC
 /// `flac-encode`; asking for one that is not built returns [`AudioError::Unsupported`].
 #[non_exhaustive]
diff --git a/crates/audio/src/opus/encoder/bands.rs b/crates/audio/src/opus/encoder/bands.rs
new file mode 100644
index 000000000..604aab595
--- /dev/null
+++ b/crates/audio/src/opus/encoder/bands.rs
@@ -0,0 +1,497 @@
+//! Band shape coding: PVQ search and codeword indexing, spreading, recursive band splitting
+//! (RFC 6716 §4.3.4, encoder direction).
+//!
+//! The encoder codes 20 ms long-block frames only (no transients, no TF changes), and stereo
+//! as dual (independent L/R) stereo, so a band is always coded by `quant_partition` with a single
+//! block. Every bit-budget computation mirrors the decoder so both sides take the same
+//! split/pulse decisions.
+
+use crate::opus::encoder::range::{BITRES, RangeEncoder, ilog};
+use crate::opus::encoder::rate::{Mode, QTHETA_OFFSET, get_pulses};
+use crate::opus::encoder::tables::{EBANDS, NB_EBANDS};
+
+pub const SPREAD_NORMAL: usize = 2;
+
+#[inline]
+fn frac_mul16(a: i32, b: i32) -> i32 {
+    (16384 + (a as i16 as i32) * (b as i16 as i32)) >> 15
+}
+
+fn bitexact_cos(x: i32) -> i32 {
+    let tmp = (4096 + x * x) >> 13;
+    let x2 = tmp;
+    let x2 = (32767 - x2) + frac_mul16(x2, -7651 + frac_mul16(x2, 8277 + frac_mul16(-626, x2)));
+    1 + x2
+}
+
+fn bitexact_log2tan(isin: i32, icos: i32) -> i32 {
+    let lc = ilog(icos as u32);
+    let ls = ilog(isin as u32);
+    let icos = icos << (15 - lc);
+    let isin = isin << (15 - ls);
+    (ls - lc) * (1 << 11) + frac_mul16(isin, frac_mul16(isin, -2597) + 7932) - frac_mul16(icos, frac_mul16(icos, -2597) + 7932)
+}
+
+fn compute_qn(n: i32, b: i32, offset: i32, pulse_cap: i32, stereo: bool) -> i32 {
+    const EXP2_TABLE8: [i32; 8] = [16384, 17866, 19483, 21247, 23170, 25267, 27554, 30048];
+    let mut n2 = 2 * n - 1;
+    if stereo && n == 2 {
+        n2 -= 1;
+    }
+    let mut qb = (b + n2 * offset) / n2;
+    qb = qb.min(b - pulse_cap - (4 << BITRES));
+    qb = qb.min(8 << BITRES);
+    if qb < (1 << BITRES >> 1) {
+        1
+    } else {
+        let qn = EXP2_TABLE8[(qb & 0x7) as usize] >> (14 - (qb >> BITRES));
+        (qn + 1) >> 1 << 1
+    }
+}
+
+/// One elementary pass of the spreading rotation, inverted (the decoder applies the forward
+/// pass; the encoder undoes it before the pulse search).
+fn exp_rotation1_inv(x: &mut [f32], len: usize, stride: usize, c: f32, s: f32) {
+    if len <= stride {
+        return;
+    }
+    if len >= 2 * stride + 1 {
+        for i in 0..=len - 2 * stride - 1 {
+            let x1 = x[i];
+            let x2 = x[i + stride];
+            x[i + stride] = c * x2 - s * x1;
+            x[i] = c * x1 + s * x2;
+        }
+    }
+    for i in (0..len - stride).rev() {
+        let x1 = x[i];
+        let x2 = x[i + stride];
+        x[i + stride] = c * x2 - s * x1;
+        x[i] = c * x1 + s * x2;
+    }
+}
+
+/// Inverse of the decoder's spreading rotation (§4.3.4.3) for one block of `len` samples.
+pub fn exp_rotation_inv(x: &mut [f32], len: usize, k: usize, spread: usize) {
+    const SPREAD_FACTOR: [usize; 3] = [15, 10, 5];
+    if 2 * k >= len || spread == 0 {
+        return;
+    }
+    let factor = SPREAD_FACTOR[spread - 1];
+    let gain = len as f32 / (len + factor * k) as f32;
+    let theta = 0.5 * gain * gain;
+    let c = (0.5 * std::f32::consts::PI * theta).cos();
+    let s = (0.5 * std::f32::consts::PI * (1.0 - theta)).cos();
+    let mut stride2 = 0;
+    if len >= 8 {
+        stride2 = 1;
+        while stride2 * stride2 + stride2 < len {
+            stride2 += 1;
+        }
+    }
+    // The decoder applies (stride2: s, c) then (1: c, s); undo in reverse order.
+    exp_rotation1_inv(x, len, 1, c, s);
+    if stride2 != 0 {
+        exp_rotation1_inv(x, len, stride2, s, c);
+    }
+}
+
+/// Greedy PVQ search: the integer vector `y` with `sum |y| = k` closest in direction to `x`.
+pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) {
+    let n = x.len();
+    y[..n].fill(0);
+    let abs: Vec<f32> = x.iter().map(|v| v.abs()).collect();
+    let sum: f32 = abs.iter().sum();
+    if !sum.is_finite() || sum <= 1e-15 {
+        y[0] = k as i32;
+        return;
+    }
+    let mut placed = 0usize;
+    let mut xy = 0f32;
+    let mut yy = 0f32;
+    if k > n / 2 {
+        // Pre-project onto the pyramid (rounding down) and place the rest greedily.
+        let r = (k as f32 - 1.0) / sum;
+        for j in 0..n {
+            let p = (abs[j] * r).floor() as i32;
+            y[j] = p;
+            placed += p as usize;
+            xy += abs[j] * p as f32;
+            yy += (p * p) as f32;
+        }
+    }
+    while placed < k {
+        let mut best = 0usize;
+        let mut best_num = -1f32;
+        let mut best_den = 1f32;
+        for j in 0..n {
+            let num = xy + abs[j];
+            let num = num * num;
+            let den = yy + 2.0 * y[j] as f32 + 1.0;
+            if num * best_den > best_num * den {
+                best_num = num;
+                best_den = den;
+                best = j;
+            }
+        }
+        xy += abs[best];
+        yy += 2.0 * y[best] as f32 + 1.0;
+        y[best] += 1;
+        placed += 1;
+    }
+    for j in 0..n {
+        if x[j] < 0.0 {
+            y[j] = -y[j];
+        }
+    }
+}
+
+/// Encodes the PVQ codeword `y` (`sum |y| = k`) as the index the RFC 6716 §4.3.4.2 decoder maps
+/// back to `y`.
+pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder, v: &mut Vec<u64>) {
+    let n = y.len();
+    let w = k + 1;
+    v.clear();
+    v.resize((n + 1) * w, 0);
+    v[0] = 1;
+    for nn in 1..=n {
+        v[nn * w] = 1;
+        for kk in 1..=k {
+            let a = v[(nn - 1) * w + kk];
+            let b = v[nn * w + kk - 1];
+            let c = v[(nn - 1) * w + kk - 1];
+            v[nn * w + kk] = a.saturating_add(b).saturating_add(c);
+        }
+    }
+    let total = v[n * w + k];
+    let vv = |nn: usize, kx: usize| v[nn * w + kx];
+    let mut index = 0u64;
+    let mut kk = k;
+    for j in 0..n {
+        if kk == 0 {
+            break;
+        }
+        let rem = n - j;
+        let t = y[j].unsigned_abs() as usize;
+        // Codewords with |y_j| = t start at sum_{m < kk - t} V(rem-1, m) within their sign half.
+        let mut base: u64 = (0..kk - t).map(|m| vv(rem - 1, m)).sum();
+        if y[j] < 0 {
+            base += (vv(rem - 1, kk) + vv(rem, kk)) / 2;
+        }
+        index += base;
+        kk -= t;
+    }
+    debug_assert!(total <= u32::MAX as u64);
+    if total >= 2 {
+        enc.uint(index as u32, total as u32);
+    }
+}
+
+pub struct BandEnc<'m, 'e> {
+    pub m: &'m Mode,
+    pub enc: &'e mut RangeEncoder,
+    pub i: usize,
+    pub spread: usize,
+    pub remaining_bits: i32,
+    pvq_v: Vec<u64>,
+    iy: Vec<i32>,
+    tmp: Vec<f32>,
+}
+
+impl BandEnc<'_, '_> {
+    /// `compute_theta` for a mono split (single block): measures the energy split between the
+    /// two halves and codes the quantised angle with the triangular pdf.
+    fn compute_theta_split(&mut self, xa: &[f32], xb: &[f32], b: &mut i32, lm: i32) -> (i32, i32, i32) {
+        let n = xa.len() as i32;
+        let i = self.i;
+        let pulse_cap = self.m.log_n[i] + lm * (1 << BITRES);
+        let offset = (pulse_cap >> 1) - QTHETA_OFFSET;
+        let qn = compute_qn(n, *b, offset, pulse_cap, false);
+        let tell = self.enc.tell_frac();
+        let mut itheta = 0i32;
+        if qn != 1 {
+            let mid = xa.iter().map(|v| v * v).sum::<f32>().sqrt();
+            let side = xb.iter().map(|v| v * v).sum::<f32>().sqrt();
+            let ang = (side as f64).atan2(mid as f64) * std::f64::consts::FRAC_2_PI;
+            let it = ((ang * qn as f64 + 0.5).floor() as i32).clamp(0, qn) as u32;
+            let q = qn as u32;
+            let half = q >> 1;
+            let ft = (half + 1) * (half + 1);
+            let (fl, fs) = if it <= half { (it * (it + 1) >> 1, it + 1) } else { (ft - ((q + 1 - it) * (q + 2 - it) >> 1), q + 1 - it) };
+            self.enc.encode(fl, fl + fs, ft);
+            itheta = ((it * 16384) / q) as i32;
+        }
+        let qalloc = self.enc.tell_frac() - tell;
+        *b -= qalloc;
+        let delta = if itheta == 0 {
+            -16384
+        } else if itheta == 16384 {
+            16384
+        } else {
+            let imid = bitexact_cos(itheta);
+            let iside = bitexact_cos(16384 - itheta);
+            frac_mul16((n - 1) << 7, bitexact_log2tan(iside, imid))
+        };
+        (itheta, delta, qalloc)
+    }
+
+    /// `quant_partition` (single block, encoder side).
+    pub fn quant_partition(&mut self, x: &[f32], mut b: i32, mut lm: i32) {
+        let n = x.len();
+        let i = self.i;
+        let cache = self.m.cache(lm, i);
+        let cache_max = cache[cache[0] as usize] as i32;
+        if lm != -1 && b > cache_max + 12 && n > 2 {
+            let half = n >> 1;
+            let (xa, xb) = x.split_at(half);
+            lm -= 1;
+            let (itheta, delta, qalloc) = self.compute_theta_split(xa, xb, &mut b, lm);
+            let mut mbits = 0.max(b.min((b - delta) / 2));
+            let mut sbits = b - mbits;
+            self.remaining_bits -= qalloc;
+            let mut rebalance = self.remaining_bits;
+            if mbits >= sbits {
+                self.quant_partition(xa, mbits, lm);
+                rebalance = mbits - (rebalance - self.remaining_bits);
+                if rebalance > 3 << BITRES && itheta != 0 {
+                    sbits += rebalance - (3 << BITRES);
+                }
+                self.quant_partition(xb, sbits, lm);
+            } else {
+                self.quant_partition(xb, sbits, lm);
+                rebalance = sbits - (rebalance - self.remaining_bits);
+                if rebalance > 3 << BITRES && itheta != 16384 {
+                    mbits += rebalance - (3 << BITRES);
+                }
+                self.quant_partition(xa, mbits, lm);
+            }
+            return;
+        }
+        let m = self.m;
+        let mut q = m.bits2pulses(i, lm, b);
+        let mut curr_bits = m.pulses2bits(i, lm, q);
+        self.remaining_bits -= curr_bits;
+        while self.remaining_bits < 0 && q > 0 {
+            self.remaining_bits += curr_bits;
+            q -= 1;
+            curr_bits = m.pulses2bits(i, lm, q);
+            self.remaining_bits -= curr_bits;
+        }
+        if q != 0 {
+            let k = get_pulses(q) as usize;
+            let mut tmp = std::mem::take(&mut self.tmp);
+            tmp.clear();
+            tmp.extend_from_slice(x);
+            exp_rotation_inv(&mut tmp, n, k, self.spread);
+            let mut iy = std::mem::take(&mut self.iy);
+            iy.clear();
+            iy.resize(n, 0);
+            pvq_search(&tmp, k, &mut iy);
+            encode_pulses(&iy, k, self.enc, &mut self.pvq_v);
+            self.iy = iy;
+            self.tmp = tmp;
+        }
+    }
+}
+
+/// Codes all band shapes (`quant_all_bands`, encoder side, long blocks). `x` holds `c` channels
+/// of `n` normalised MDCT coefficients each.
+#[allow(clippy::too_many_arguments)]
+pub fn quant_all_bands(
+    m: &Mode,
+    start: usize,
+    end: usize,
+    x: &[f32],
+    n_total: usize,
+    c: usize,
+    pulses: &[i32; NB_EBANDS],
+    spread: usize,
+    dual_stereo: bool,
+    intensity: usize,
+    total_bits: i32,
+    mut balance: i32,
+    enc: &mut RangeEncoder,
+    lm: usize,
+    coded_bands: usize,
+) {
+    let mm = 1usize << lm;
+    debug_assert!(c == 1 || dual_stereo || intensity <= start, "stereo frames are coded as dual stereo");
+    let mut ctx = BandEnc { m, enc, i: 0, spread, remaining_bits: 0, pvq_v: Vec::new(), iy: Vec::new(), tmp: Vec::new() };
+    for i in start..end {
+        ctx.i = i;
+        let xo = mm * EBANDS[i] as usize;
+        let n = mm * EBANDS[i + 1] as usize - xo;
+        let tell = ctx.enc.tell_frac();
+        if i != start {
+            balance -= tell;
+        }
+        let remaining_bits = total_bits - tell - 1;
+        ctx.remaining_bits = remaining_bits;
+        let b = if i < coded_bands {
+            let curr_balance = balance / 3.min(coded_bands as i32 - i as i32);
+            0.max(16383.min((remaining_bits + 1).min(pulses[i] + curr_balance)))
+        } else {
+            0
+        };
+        // Bands at and above `intensity` (= coded_bands) carry no bits, so they emit no symbols.
+        if i < coded_bands || c == 1 {
+            if c == 2 && dual_stereo && i < intensity {
+                ctx.quant_partition(&x[xo..xo + n], b / 2, lm as i32);
+                ctx.quant_partition(&x[n_total + xo..n_total + xo + n], b / 2, lm as i32);
+            } else {
+                ctx.quant_partition(&x[xo..xo + n], b, lm as i32);
+            }
+        }
+        balance += pulses[i] + tell;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::opus::encoder::range::dec::RangeDecoder;
+
+    fn exp_rotation1(x: &mut [f32], len: usize, stride: usize, c: f32, s: f32) {
+        let ms = -s;
+        if len <= stride {
+            return;
+        }
+        for i in 0..len - stride {
+            let x1 = x[i];
+            let x2 = x[i + stride];
+            x[i + stride] = c * x2 + s * x1;
+            x[i] = c * x1 + ms * x2;
+        }
+        if len >= 2 * stride + 1 {
+            for i in (0..=len - 2 * stride - 1).rev() {
+                let x1 = x[i];
+                let x2 = x[i + stride];
+                x[i + stride] = c * x2 + s * x1;
+                x[i] = c * x1 + ms * x2;
+            }
+        }
+    }
+
+    /// The decoder's spreading rotation (single block).
+    fn exp_rotation(x: &mut [f32], len: usize, k: usize, spread: usize) {
+        const SPREAD_FACTOR: [usize; 3] = [15, 10, 5];
+        if 2 * k >= len || spread == 0 {
+            return;
+        }
+        let factor = SPREAD_FACTOR[spread - 1];
+        let gain = len as f32 / (len + factor * k) as f32;
+        let theta = 0.5 * gain * gain;
+        let c = (0.5 * std::f32::consts::PI * theta).cos();
+        let s = (0.5 * std::f32::consts::PI * (1.0 - theta)).cos();
+        let mut stride2 = 0;
+        if len >= 8 {
+            stride2 = 1;
+            while stride2 * stride2 + stride2 < len {
+                stride2 += 1;
+            }
+        }
+        if stride2 != 0 {
+            exp_rotation1(x, len, stride2, s, c);
+        }
+        exp_rotation1(x, len, 1, c, s);
+    }
+
+    #[test]
+    fn spreading_inverse_is_exact() {
+        for &len in &[8usize, 16, 24, 48, 96, 176] {
+            for k in [1usize, 2, 3, 5] {
+                let orig: Vec<f32> = (0..len).map(|i| ((i * 31 % 17) as f32 - 8.0) / 8.0).collect();
+                let mut x = orig.clone();
+                exp_rotation_inv(&mut x, len, k, SPREAD_NORMAL);
+                exp_rotation(&mut x, len, k, SPREAD_NORMAL);
+                for (a, b) in x.iter().zip(&orig) {
+                    assert!((a - b).abs() < 1e-4, "len={len} k={k}");
+                }
+            }
+        }
+    }
+
+    /// PVQ decoder of RFC 6716 §4.3.4.2 (as in FilmCraft's decoder).
+    fn decode_pulses(n: usize, k: usize, dec: &mut RangeDecoder) -> Vec<i32> {
+        let w = k + 1;
+        let mut v = vec![0u64; (n + 1) * w];
+        v[0] = 1;
+        for nn in 1..=n {
+            v[nn * w] = 1;
+            for kk in 1..=k {
+                v[nn * w + kk] = v[(nn - 1) * w + kk].saturating_add(v[nn * w + kk - 1]).saturating_add(v[(nn - 1) * w + kk - 1]);
+            }
+        }
+        let total = v[n * w + k];
+        let mut i = if total >= 2 { dec.uint(total as u32) as u64 } else { 0 };
+        let mut y = vec![0i32; n];
+        let mut kk = k;
+        for j in 0..n {
+            let rem = n - j;
+            if kk == 0 {
+                break;
+            }
+            let vv = |nn: usize, kx: usize| v[nn * w + kx];
+            let mut p = (vv(rem - 1, kk) + vv(rem, kk)) / 2;
+            let neg = i >= p;
+            if neg {
+                i -= p;
+            }
+            let k0 = kk;
+            p -= vv(rem - 1, kk);
+            while p > i && kk > 0 {
+                kk -= 1;
+                p -= vv(rem - 1, kk);
+            }
+            let mag = (k0 - kk) as i32;
+            y[j] = if neg { -mag } else { mag };
+            i -= p.min(i);
+        }
+        y
+    }
+
+    fn all_codewords(n: usize, k: usize) -> Vec<Vec<i32>> {
+        if n == 0 {
+            return if k == 0 { vec![vec![]] } else { vec![] };
+        }
+        let mut out = Vec::new();
+        for t in -(k as i32)..=(k as i32) {
+            for mut rest in all_codewords(n - 1, k - t.unsigned_abs() as usize) {
+                rest.insert(0, t);
+                out.push(rest);
+            }
+        }
+        out
+    }
+
+    #[test]
+    fn pvq_index_roundtrip_exhaustive() {
+        let mut v = Vec::new();
+        for n in 1..6usize {
+            for k in 1..6usize {
+                for y in all_codewords(n, k) {
+                    let mut e = RangeEncoder::new();
+                    encode_pulses(&y, k, &mut e, &mut v);
+                    let buf = e.done(16);
+                    let mut d = RangeDecoder::new(&buf);
+                    assert_eq!(decode_pulses(n, k, &mut d), y, "n={n} k={k}");
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn pvq_search_finds_good_direction() {
+        let x: Vec<f32> = (0..32).map(|i| ((i as f32) * 0.7).sin()).collect();
+        let mut y = vec![0i32; 32];
+        for k in [1usize, 4, 16, 64] {
+            pvq_search(&x, k, &mut y);
+            assert_eq!(y.iter().map(|v| v.unsigned_abs() as usize).sum::<usize>(), k);
+            let xy: f32 = x.iter().zip(&y).map(|(a, &b)| a * b as f32).sum();
+            let yy: f32 = y.iter().map(|&b| (b * b) as f32).sum();
+            let xx: f32 = x.iter().map(|a| a * a).sum();
+            let corr = xy / (xx * yy).sqrt();
+            assert!(corr > if k >= 16 { 0.9 } else { 0.2 }, "k={k} corr={corr}");
+        }
+    }
+}
diff --git a/crates/audio/src/opus/encoder/energy.rs b/crates/audio/src/opus/encoder/energy.rs
new file mode 100644
index 000000000..8d4f357d0
--- /dev/null
+++ b/crates/audio/src/opus/encoder/energy.rs
@@ -0,0 +1,230 @@
+//! Band energy quantisation: Laplace-coded coarse energy with inter/intra prediction, fine
+//! energy and the final refinement bits (RFC 6716 §4.3.2, encoder direction).
+//!
+//! The quantised energies are updated with exactly the decoder's arithmetic so the prediction
+//! state never drifts between encoder and decoder.
+
+use crate::opus::encoder::range::RangeEncoder;
+use crate::opus::encoder::rate::MAX_FINE_BITS;
+use crate::opus::encoder::tables::{BETA_COEF, BETA_INTRA, E_PROB_MODEL, NB_EBANDS, PRED_COEF, SMALL_ENERGY_ICDF};
+
+const LAPLACE_MINP: u32 = 1;
+const LAPLACE_NMIN: u32 = 16;
+
+fn laplace_get_freq1(fs0: u32, decay: u32) -> u32 {
+    let ft = 32768 - LAPLACE_MINP * (2 * LAPLACE_NMIN) - fs0;
+    (ft * (16384 - decay)) >> 15
+}
+
+/// Encodes a Laplace-distributed integer (`fs` = probability of 0 in Q15, `decay` in Q14).
+/// Returns the value actually coded (very large magnitudes are clamped to the representable
+/// range).
+pub fn laplace_encode(enc: &mut RangeEncoder, value: i32, mut fs: u32, decay: u32) -> i32 {
+    let mut fl = 0u32;
+    let mut coded = value;
+    if value != 0 {
+        let s: i32 = if value < 0 { -1 } else { 0 };
+        let val = value.abs();
+        fl = fs;
+        fs = laplace_get_freq1(fs, decay);
+        let mut i = 1;
+        while fs > 0 && i < val {
+            fs *= 2;
+            fl += fs + 2 * LAPLACE_MINP;
+            fs = (fs * decay) >> 15;
+            i += 1;
+        }
+        if fs == 0 {
+            let ndi_max = (32768 - fl + LAPLACE_MINP - 1) as i32;
+            let ndi_max = (ndi_max - s) >> 1;
+            let di = (val - i).min(ndi_max - 1);
+            fl = (fl as i32 + (2 * di + 1 + s) * LAPLACE_MINP as i32) as u32;
+            fs = LAPLACE_MINP.min(32768 - fl);
+            let mag = i + di;
+            coded = if s < 0 { -mag } else { mag };
+        } else {
+            fs += LAPLACE_MINP;
+            if s == 0 {
+                fl += fs;
+            }
+        }
+    }
+    enc.encode_bin(fl, fl + fs, 15);
+    coded
+}
+
+/// `quant_coarse_energy` for one prediction mode. `e` holds the target log2 energies (relative
+/// to `E_MEANS`), `old_e` the quantised energies, updated in place. `budget` is the frame size in
+/// bits.
+#[allow(clippy::too_many_arguments)]
+pub fn quant_coarse_energy(
+    start: usize,
+    end: usize,
+    e: &[f32; 2 * NB_EBANDS],
+    old_e: &mut [f32; 2 * NB_EBANDS],
+    intra: bool,
+    enc: &mut RangeEncoder,
+    c: usize,
+    lm: usize,
+    budget: i32,
+) {
+    let prob = &E_PROB_MODEL[lm][intra as usize];
+    let (coef, beta) = if intra { (0.0, BETA_INTRA) } else { (PRED_COEF[lm], BETA_COEF[lm]) };
+    let mut prev = [0f32; 2];
+    for i in start..end {
+        for ch in 0..c {
+            let idx = i + ch * NB_EBANDS;
+            let oldc = old_e[idx].max(-9.0);
+            let x = e[idx];
+            let f = x - coef * oldc - prev[ch];
+            let mut qi = (f + 0.5).floor().clamp(-64.0, 64.0) as i32;
+            let tell = enc.tell();
+            // Keep a few bits per remaining band in reserve when the budget runs out.
+            let bits_left = budget - tell - 3 * c as i32 * (end - i) as i32;
+            if i != start && bits_left < 30 {
+                if bits_left < 24 {
+                    qi = qi.min(1);
+                }
+                if bits_left < 16 {
+                    qi = qi.max(-1);
+                }
+            }
+            if budget - tell >= 15 {
+                let pi = 2 * i.min(20);
+                qi = laplace_encode(enc, qi, (prob[pi] as u32) << 7, (prob[pi + 1] as u32) << 6);
+            } else if budget - tell >= 2 {
+                qi = qi.clamp(-1, 1);
+                enc.icdf(if qi < 0 { (-2 * qi - 1) as usize } else { (2 * qi) as usize }, &SMALL_ENERGY_ICDF, 2);
+            } else if budget - tell >= 1 {
+                qi = qi.clamp(-1, 0);
+                enc.bit_logp(qi == -1, 1);
+            } else {
+                qi = -1;
+            }
+            let q = qi as f32;
+            old_e[idx] = oldc;
+            let tmp = coef * old_e[idx] + prev[ch] + q;
+            old_e[idx] = tmp;
+            prev[ch] = prev[ch] + q - beta * q;
+        }
+    }
+}
+
+/// `quant_fine_energy`: raw bits refining each band's quantised energy.
+pub fn quant_fine_energy(
+    start: usize,
+    end: usize,
+    e: &[f32; 2 * NB_EBANDS],
+    old_e: &mut [f32; 2 * NB_EBANDS],
+    fine_quant: &[i32; NB_EBANDS],
+    enc: &mut RangeEncoder,
+    c: usize,
+) {
+    for i in start..end {
+        let fq = fine_quant[i];
+        if fq <= 0 {
+            continue;
+        }
+        for ch in 0..c {
+            let idx = i + ch * NB_EBANDS;
+            let err = e[idx] - old_e[idx];
+            let levels = 1i32 << fq;
+            let q2 = (((err + 0.5) * levels as f32).floor() as i32).clamp(0, levels - 1);
+            enc.bits(q2 as u32, fq as u32);
+            let offset = (q2 as f32 + 0.5) * (1 << (14 - fq)) as f32 / 16384.0 - 0.5;
+            old_e[idx] += offset;
+        }
+    }
+}
+
+/// `quant_energy_finalise`: spends the bits left at the end of the frame on one more bit of
+/// energy resolution per band, in priority order.
+#[allow(clippy::too_many_arguments)]
+pub fn quant_energy_finalise(
+    start: usize,
+    end: usize,
+    e: &[f32; 2 * NB_EBANDS],
+    old_e: &mut [f32; 2 * NB_EBANDS],
+    fine_quant: &[i32; NB_EBANDS],
+    fine_priority: &[i32; NB_EBANDS],
+    mut bits_left: i32,
+    enc: &mut RangeEncoder,
+    c: usize,
+) {
+    for prio in 0..2 {
+        let mut i = start;
+        while i < end && bits_left >= c as i32 {
+            if fine_quant[i] >= MAX_FINE_BITS || fine_priority[i] != prio {
+                i += 1;
+                continue;
+            }
+            for ch in 0..c {
+                let idx = i + ch * NB_EBANDS;
+                let q2 = (e[idx] - old_e[idx] >= 0.0) as u32;
+                enc.bits(q2, 1);
+                let offset = (q2 as f32 - 0.5) * (1 << (14 - fine_quant[i] - 1)) as f32 / 16384.0;
+                old_e[idx] += offset;
+                bits_left -= 1;
+            }
+            i += 1;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::opus::encoder::range::dec::RangeDecoder;
+
+    /// Laplace decoder of RFC 6716 §4.3.2.1 (as in FilmCraft's decoder).
+    fn laplace_decode(dec: &mut RangeDecoder, mut fs: u32, decay: u32) -> i32 {
+        let mut val = 0i32;
+        let fm = dec.decode(32768);
+        let mut fl = 0u32;
+        if fm >= fs {
+            val += 1;
+            fl = fs;
+            fs = laplace_get_freq1(fs, decay) + LAPLACE_MINP;
+            while fs > LAPLACE_MINP && fm >= fl + 2 * fs {
+                fs *= 2;
+                fl += fs;
+                fs = (((fs - 2 * LAPLACE_MINP) * decay) >> 15) + LAPLACE_MINP;
+                val += 1;
+            }
+            if fs <= LAPLACE_MINP {
+                let di = (fm - fl) >> 1;
+                val += di as i32;
+                fl += 2 * di * LAPLACE_MINP;
+            }
+            if fm < fl + fs {
+                val = -val;
+            } else {
+                fl += fs;
+            }
+        }
+        dec.update(fl, (fl + fs).min(32768), 32768);
+        val
+    }
+
+    #[test]
+    fn laplace_roundtrip_all_models() {
+        for lm in 0..4 {
+            for intra in 0..2 {
+                for band in 0..21 {
+                    let prob = &E_PROB_MODEL[lm][intra];
+                    let (fs, decay) = ((prob[2 * band] as u32) << 7, (prob[2 * band + 1] as u32) << 6);
+                    let vals: Vec<i32> = (-64..=64).collect();
+                    let mut e = RangeEncoder::new();
+                    let coded: Vec<i32> = vals.iter().map(|&v| laplace_encode(&mut e, v, fs, decay)).collect();
+                    let size = (e.tell() as usize).div_ceil(8);
+                    let buf = e.done(size);
+                    let mut d = RangeDecoder::new(&buf);
+                    for (&v, &c) in vals.iter().zip(&coded) {
+                        assert!(c == v || (c.signum() == v.signum() && c.abs() < v.abs()), "clamp {v} -> {c}");
+                        assert_eq!(laplace_decode(&mut d, fs, decay), c, "lm={lm} intra={intra} band={band} v={v}");
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/audio/src/opus/encoder/mdct.rs b/crates/audio/src/opus/encoder/mdct.rs
new file mode 100644
index 000000000..6a42cce96
--- /dev/null
+++ b/crates/audio/src/opus/encoder/mdct.rs
@@ -0,0 +1,294 @@
+//! Forward MDCT with the CELT low-overlap window (RFC 6716 §4.3.7, run in the analysis
+//! direction).
+//!
+//! A 20 ms frame is a 1920-point MDCT (960 coefficients) whose window is zero for 420 samples,
+//! rises over the 120-sample overlap, is flat for 840 samples, falls over the next 120 samples
+//! and is zero again for the last 420. The input block is therefore the 120 overlap samples kept
+//! from the previous frame followed by the 960 new samples. The MDCT is folded into a DCT-IV,
+//! which is computed with an N/2-point complex FFT.
+
+use crate::opus::encoder::tables::OVERLAP;
+
+#[derive(Clone, Copy, Default, Debug)]
+pub struct Cpx {
+    pub re: f32,
+    pub im: f32,
+}
+
+impl Cpx {
+    #[inline]
+    fn mul(self, o: Cpx) -> Cpx {
+        Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
+    }
+    #[inline]
+    fn add(self, o: Cpx) -> Cpx {
+        Cpx { re: self.re + o.re, im: self.im + o.im }
+    }
+}
+
+/// Mixed-radix (2, 3, 4, 5) forward complex FFT, unscaled (decimation in time, recursive).
+pub struct Fft {
+    n: usize,
+    factors: Vec<usize>,
+    twiddle: Vec<Cpx>,
+}
+
+impl Fft {
+    pub fn new(n: usize) -> Fft {
+        let mut factors = Vec::new();
+        let mut m = n;
+        for p in [4usize, 2, 3, 5] {
+            while m.is_multiple_of(p) {
+                factors.push(p);
+                m /= p;
+            }
+        }
+        assert_eq!(m, 1, "unsupported FFT size {n}");
+        let twiddle = (0..n)
+            .map(|k| {
+                let ph = -2.0 * std::f64::consts::PI * k as f64 / n as f64;
+                Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
+            })
+            .collect();
+        Fft { n, factors, twiddle }
+    }
+
+    pub fn process(&self, data: &mut [Cpx], scratch: &mut Vec<Cpx>) {
+        scratch.clear();
+        scratch.extend_from_slice(&data[..self.n]);
+        self.rec(&mut data[..self.n], scratch, 1, self.n, 0, 1);
+    }
+
+    fn rec(&self, out: &mut [Cpx], inp: &[Cpx], in_stride: usize, n: usize, fi: usize, tw_stride: usize) {
+        let p = self.factors[fi];
+        let m = n / p;
+        if m == 1 {
+            for (i, o) in out.iter_mut().enumerate().take(p) {
+                *o = inp[i * in_stride];
+            }
+        } else {
+            for q in 0..p {
+                self.rec(&mut out[q * m..(q + 1) * m], &inp[q * in_stride..], in_stride * p, m, fi + 1, tw_stride * p);
+            }
+        }
+        let big = self.n;
+        let mut t = [Cpx::default(); 5];
+        for k in 0..m {
+            for (q, tq) in t.iter_mut().enumerate().take(p) {
+                *tq = out[q * m + k].mul(self.twiddle[(q * k * tw_stride) % big]);
+            }
+            for q2 in 0..p {
+                let mut acc = Cpx::default();
+                for (q, tq) in t.iter().enumerate().take(p) {
+                    acc = acc.add(tq.mul(self.twiddle[((q * q2) % p) * (big / p)]));
+                }
+                out[q2 * m + k] = acc;
+            }
+        }
+    }
+}
+
+/// Forward MDCT producing `n` coefficients from a block of `n + OVERLAP` samples.
+pub struct Mdct {
+    /// Number of coefficients (half the MDCT length).
+    n: usize,
+    fft: Fft,
+    pre: Vec<Cpx>,
+    post: Vec<Cpx>,
+    /// Rising half of the low-overlap window (RFC 6716 §4.3.7).
+    pub window: [f32; OVERLAP],
+    scale: f32,
+    z: Vec<Cpx>,
+    scratch: Vec<Cpx>,
+    v: Vec<f32>,
+}
+
+impl Mdct {
+    pub fn new(n: usize) -> Mdct {
+        let n2 = n / 2;
+        let pi = std::f64::consts::PI;
+        let pre = (0..n2)
+            .map(|m| {
+                let ph = -pi * m as f64 / n as f64;
+                Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
+            })
+            .collect();
+        let post = (0..n2)
+            .map(|p| {
+                let ph = -pi * (p as f64 + 0.25) / n as f64;
+                Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
+            })
+            .collect();
+        let mut window = [0f32; OVERLAP];
+        for (i, w) in window.iter_mut().enumerate() {
+            let x = std::f64::consts::FRAC_PI_2 * (i as f64 + 0.5) / OVERLAP as f64;
+            let s = x.sin();
+            *w = (std::f64::consts::FRAC_PI_2 * s * s).sin() as f32;
+        }
+        Mdct { n, fft: Fft::new(n2), pre, post, window, scale: 2.0 / n as f32, z: Vec::new(), scratch: Vec::new(), v: vec![0.0; n] }
+    }
+
+    /// Transforms `block` (`n + OVERLAP` samples: the previous frame's last `OVERLAP` samples, then
+    /// `n` new ones) into `out[..n]`, scaled so that the RFC 6716 decoder's inverse MDCT and
+    /// overlap-add reproduce the input.
+    pub fn forward(&mut self, block: &[f32], out: &mut [f32]) {
+        let n = self.n;
+        let n2 = n / 2;
+        debug_assert_eq!(block.len(), n + OVERLAP);
+        // Place the windowed block into the (virtual) 2n-sample MDCT input u at offset `pad`.
+        let pad = (n - OVERLAP) / 2;
+        let w = &self.window;
+        let u = |t: usize| -> f32 {
+            if t < pad || t >= pad + n + OVERLAP {
+                return 0.0;
+            }
+            let j = t - pad;
+            let g = if j < OVERLAP {
+                w[j]
+            } else if j >= n {
+                w[OVERLAP - 1 - (j - n)]
+            } else {
+                1.0
+            };
+            block[j] * g
+        };
+        // Fold to a DCT-IV input: v = (-c_r - d, a - b_r) over the four quarters of u.
+        for m in 0..n2 {
+            self.v[m] = -u(n + n2 - 1 - m) - u(n + n2 + m);
+            self.v[n2 + m] = u(m) - u(n2 + n2 - 1 - m);
+        }
+        // DCT-IV via an n/2-point complex FFT.
+        self.z.clear();
+        for m in 0..n2 {
+            let wv = Cpx { re: self.v[2 * m], im: self.v[n - 1 - 2 * m] };
+            self.z.push(wv.mul(self.pre[m]));
+        }
+        self.fft.process(&mut self.z, &mut self.scratch);
+        for p in 0..n2 {
+            let y = self.z[p].mul(self.post[p]);
+            out[2 * p] = y.re * self.scale;
+            out[n - 1 - 2 * p] = -y.im * self.scale;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Direct MDCT definition X[k] = sum u[t] cos(pi/N (t + 1/2 + N/2)(k + 1/2)).
+    fn direct(block: &[f32], n: usize, window: &[f32; OVERLAP]) -> Vec<f64> {
+        let pad = (n - OVERLAP) / 2;
+        let mut u = vec![0f64; 2 * n];
+        for (j, &b) in block.iter().enumerate() {
+            let g = if j < OVERLAP {
+                window[j]
+            } else if j >= n {
+                window[OVERLAP - 1 - (j - n)]
+            } else {
+                1.0
+            };
+            u[pad + j] = (b * g) as f64;
+        }
+        (0..n)
+            .map(|k| {
+                (0..2 * n).map(|t| u[t] * (std::f64::consts::PI / n as f64 * (t as f64 + 0.5 + n as f64 / 2.0) * (k as f64 + 0.5)).cos()).sum::<f64>()
+                    * 2.0
+                    / n as f64
+            })
+            .collect()
+    }
+
+    #[test]
+    fn matches_direct_formula() {
+        for &n in &[240usize, 960] {
+            let block: Vec<f32> = (0..n + OVERLAP).map(|i| ((i * 37 % 101) as f32 - 50.0) / 7.0).collect();
+            let mut m = Mdct::new(n);
+            let mut out = vec![0f32; n];
+            m.forward(&block, &mut out);
+            let d = direct(&block, n, &m.window);
+            for k in 0..n {
+                assert!((out[k] as f64 - d[k]).abs() < 1e-2, "n={n} k={k}: {} vs {}", out[k], d[k]);
+            }
+        }
+    }
+
+    // ---- Replica of the RFC 6716 decoder inverse MDCT (as in FilmCraft's decoder) ----
+
+    fn imdct_backward(n_full: usize, input: &[f32], out: &mut [f32], window: &[f32]) {
+        let n2 = n_full >> 1;
+        let n4 = n_full >> 2;
+        let t: Vec<f32> = (0..n2).map(|i| (2.0 * std::f64::consts::PI * (i as f64 + 0.125) / n_full as f64).cos() as f32).collect();
+        let fft = Fft::new(n4);
+        let mut z = Vec::new();
+        for i in 0..n4 {
+            let x1 = input[2 * i];
+            let x2 = input[n2 - 1 - 2 * i];
+            let yr = x2 * t[i] + x1 * t[n4 + i];
+            let yi = x1 * t[i] - x2 * t[n4 + i];
+            z.push(Cpx { re: yi, im: yr });
+        }
+        fft.process(&mut z, &mut Vec::new());
+        let overlap = OVERLAP;
+        let base = overlap >> 1;
+        let y = &mut out[base..base + n2];
+        for i in 0..n4.div_ceil(2) {
+            let front = z[i];
+            let back = z[n4 - 1 - i];
+            let (re, im) = (front.im, front.re);
+            let (t0, t1) = (t[i], t[n4 + i]);
+            let yr0 = re * t0 + im * t1;
+            let yi0 = re * t1 - im * t0;
+            let (re, im) = (back.im, back.re);
+            let (t0, t1) = (t[n4 - i - 1], t[n2 - i - 1]);
+            let yr1 = re * t0 + im * t1;
+            let yi1 = re * t1 - im * t0;
+            y[2 * i] = yr0;
+            y[n2 - 1 - 2 * i] = yi0;
+            y[n2 - 2 - 2 * i] = yr1;
+            y[2 * i + 1] = yi1;
+        }
+        for i in 0..overlap / 2 {
+            let x1 = out[overlap - 1 - i];
+            let x2 = out[i];
+            let w1 = window[i];
+            let w2 = window[overlap - 1 - i];
+            out[i] = x2 * w2 - x1 * w1;
+            out[overlap - 1 - i] = x2 * w1 + x1 * w2;
+        }
+    }
+
+    /// MDCT analysis followed by the decoder's IMDCT + TDAC overlap-add reproduces the input
+    /// delayed by exactly `OVERLAP` samples.
+    #[test]
+    fn perfect_reconstruction_through_decoder_imdct() {
+        let n = 960;
+        let frames = 5;
+        let sig: Vec<f32> = (0..n * frames).map(|i| (i as f32 * 0.013).sin() * 1000.0 + ((i * 7919) % 211) as f32 - 105.0).collect();
+        let mut m = Mdct::new(n);
+        let mut hist = vec![0f32; OVERLAP];
+        // Decoder memory: [frame output n][folded tail OVERLAP/2] laid out like decode_mem.
+        let mut mem = vec![0f32; n + OVERLAP];
+        let mut decoded = Vec::new();
+        for f in 0..frames {
+            let mut block = hist.clone();
+            block.extend_from_slice(&sig[f * n..(f + 1) * n]);
+            hist.copy_from_slice(&block[n..]);
+            let mut coefs = vec![0f32; n];
+            m.forward(&block, &mut coefs);
+            // Shift: the previous folded tail (at n..n+OVERLAP/2) moves to 0..OVERLAP/2.
+            mem.copy_within(n..n + OVERLAP / 2, 0);
+            imdct_backward(2 * n, &coefs, &mut mem, &m.window);
+            decoded.extend_from_slice(&mem[..n]);
+        }
+        let mut err = 0f64;
+        let mut sum = 0f64;
+        for t in OVERLAP..n * frames {
+            let d = decoded[t] as f64 - sig[t - OVERLAP] as f64;
+            err += d * d;
+            sum += (sig[t - OVERLAP] as f64).powi(2);
+        }
+        let snr = 10.0 * (sum / err).log10();
+        assert!(snr > 80.0, "reconstruction SNR {snr:.1} dB");
+    }
+}
diff --git a/crates/audio/src/opus/encoder/mod.rs b/crates/audio/src/opus/encoder/mod.rs
new file mode 100644
index 000000000..cbb0d7984
--- /dev/null
+++ b/crates/audio/src/opus/encoder/mod.rs
@@ -0,0 +1,593 @@
+//! Clean-room pure-Rust Opus encoder (RFC 6716 SILK, hybrid and CELT modes; RFC 7845 `OpusHead`).
+//!
+//! Produces 20 ms Opus packets from 48 kHz float input, mono or stereo. The coding mode and
+//! audio bandwidth are chosen once per stream from the per-channel bitrate and the
+//! [`Application`] (see the crate README for the table):
+//!
+//! - **SILK** (narrowband/mediumband/wideband): linear-predictive speech coding at an internal
+//!   rate of 8/12/16 kHz; packet sizes vary around the target bitrate.
+//! - **Hybrid** (super-wideband/fullband): SILK wideband codes 0–8 kHz and CELT codes the bands
+//!   above in the same range-coded frame; constant packet size.
+//! - **CELT** (fullband): MDCT transform coding; constant packet size.
+//!
+//! From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429). Public items keep their
+//! names, so EffectCraft can re-export this module.
+//!
+//! ```
+//! # #[cfg(feature = "opus-encode")] {
+//! use craft_audio::opus::encoder::{Application, Mode, Encoder};
+//! let mut enc = Encoder::new(2, 128_000).unwrap();
+//! let pcm = vec![0.0f32; Encoder::FRAME_SIZE * 2];
+//! let packet = enc.encode_float(&pcm).unwrap();
+//! assert_eq!(packet[0] >> 3, 31); // CELT-only, fullband, 20 ms
+//! assert_eq!(enc.opus_head().len(), 19);
+//! let voip = Encoder::with_application(1, 16_000, Application::Voip).unwrap();
+//! assert_eq!(voip.mode(), Mode::Silk);
+//! # }
+//! ```
+
+// The bit-allocation code mirrors the normative integer arithmetic; keep C-like shift expressions.
+#![allow(clippy::precedence, clippy::int_plus_one)]
+
+mod bands;
+mod energy;
+mod mdct;
+mod range;
+mod rate;
+mod resample;
+mod silk;
+mod tables;
+
+use std::sync::OnceLock;
+
+use bands::{SPREAD_NORMAL, quant_all_bands};
+use energy::{quant_coarse_energy, quant_energy_finalise, quant_fine_energy};
+use mdct::Mdct;
+use range::{BITRES, RangeEncoder};
+use rate::{Mode as CeltMode, compute_allocation};
+use resample::Downsampler;
+use silk::SilkEncoder;
+use tables::{E_MEANS, EBANDS, NB_EBANDS, OVERLAP, PREEMPH, SPREAD_ICDF, TF_SELECT_TABLE, TRIM_ICDF};
+
+/// Samples per channel in one 20 ms frame at 48 kHz.
+const N: usize = 960;
+/// LM of a 20 ms frame (8 short blocks).
+const LM: usize = 3;
+/// Smallest CELT payload the encoder produces (bytes).
+const MIN_FRAME_BYTES: usize = 16;
+/// Largest payload allowed in one frame (RFC 6716 §3.4, R2).
+const MAX_FRAME_BYTES: usize = 1275;
+/// First CELT band coded in hybrid frames (8 kHz).
+const HYBRID_START_BAND: usize = 17;
+
+fn celt_mode() -> &'static CeltMode {
+    static MODE: OnceLock<CeltMode> = OnceLock::new();
+    MODE.get_or_init(CeltMode::new)
+}
+
+/// Why an encoder could not be created or a frame could not be encoded.
+#[non_exhaustive]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
+pub enum Error {
+    /// Opus family-0 streams have 1 or 2 channels.
+    #[error("Opus family-0 streams have 1 or 2 channels, not {0}")]
+    Channels(u8),
+    /// The mode cannot code that bandwidth.
+    #[error("unsupported mode/bandwidth combination {0:?}/{1:?}")]
+    ModeBandwidth(Mode, Bandwidth),
+    /// `encode_float` takes exactly `FRAME_SIZE * channels` samples.
+    #[error("a frame is {expected} interleaved samples, not {got}")]
+    FrameLength {
+        /// Interleaved samples a frame takes (`FRAME_SIZE * channels`).
+        expected: usize,
+        /// Interleaved samples passed.
+        got: usize,
+    },
+}
+
+/// Intended use of the stream; selects the mode/bandwidth table.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
+pub enum Application {
+    /// General audio (music, mixed content): CELT unless the bitrate is low.
+    #[default]
+    Audio,
+    /// Speech: SILK and hybrid over a wider bitrate range, narrower bandwidths at low rates.
+    Voip,
+}
+
+/// Opus coding mode (RFC 6716 §2).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum Mode {
+    /// MDCT transform coding only.
+    Celt,
+    /// Linear-prediction coding only.
+    Silk,
+    /// SILK below 8 kHz plus CELT above.
+    Hybrid,
+}
+
+pub use crate::opus::Bandwidth;
+
+/// Mode and bandwidth for a per-channel bitrate (bits per second per channel).
+fn choose_mode(app: Application, per_channel: u32) -> (Mode, Bandwidth) {
+    match app {
+        Application::Voip => match per_channel {
+            0..10_000 => (Mode::Silk, Bandwidth::Narrowband),
+            10_000..12_000 => (Mode::Silk, Bandwidth::Mediumband),
+            12_000..18_000 => (Mode::Silk, Bandwidth::Wideband),
+            18_000..28_000 => (Mode::Hybrid, Bandwidth::SuperWideband),
+            28_000..40_000 => (Mode::Hybrid, Bandwidth::Fullband),
+            _ => (Mode::Celt, Bandwidth::Fullband),
+        },
+        Application::Audio => match per_channel {
+            0..16_000 => (Mode::Silk, Bandwidth::Wideband),
+            16_000..36_000 => (Mode::Hybrid, Bandwidth::Fullband),
+            _ => (Mode::Celt, Bandwidth::Fullband),
+        },
+    }
+}
+
+/// SILK side of a SILK-only or hybrid stream.
+struct SilkPath {
+    enc: SilkEncoder,
+    down: Vec<Downsampler>,
+    /// Bits per frame aimed at (excluding the TOC byte in SILK-only mode).
+    target_bits: f64,
+    /// Bits saved (positive) or overspent by previous frames (SILK-only mode).
+    reservoir: f64,
+}
+
+/// The name EffectCraft's `effectcraft-opusenc` used, kept so it can re-export this module.
+#[doc(hidden)]
+pub type OpusEncoder = Encoder;
+
+/// Opus encoder for one mono or stereo stream at 48 kHz.
+pub struct Encoder {
+    channels: usize,
+    application: Application,
+    mode: Mode,
+    bandwidth: Bandwidth,
+    /// Requested bitrate (clamped), bits per second.
+    bitrate_bps: u32,
+    /// Payload bytes per packet in CELT and hybrid modes (the packet is one byte longer: the
+    /// TOC).
+    frame_bytes: usize,
+    mdct: Mdct,
+    /// Last input sample of each channel (pre-emphasis filter memory, ×32768).
+    preemph_mem: [f32; 2],
+    /// Last `OVERLAP` pre-emphasised samples of each channel.
+    hist: Vec<f32>,
+    /// Quantised band energies, exactly as the decoder holds them.
+    old_band_e: [f32; 2 * NB_EBANDS],
+    block: Vec<f32>,
+    freq: Vec<f32>,
+    silk: Option<SilkPath>,
+}
+
+impl Encoder {
+    /// Samples per channel per packet (20 ms at 48 kHz).
+    pub const FRAME_SIZE: usize = N;
+
+    /// Creates a general-audio encoder ([`Application::Audio`]) for `channels` (1 or 2)
+    /// channels of 48 kHz audio at `bitrate_bps` (total for all channels).
+    pub fn new(channels: u8, bitrate_bps: u32) -> Result<Self, Error> {
+        Self::with_application(channels, bitrate_bps, Application::Audio)
+    }
+
+    /// Creates an encoder for `channels` (1 or 2) channels of 48 kHz audio at `bitrate_bps`
+    /// (total for all channels; clamped to 6 kb/s per channel – 510 kb/s), choosing the mode
+    /// and bandwidth for `application`.
+    pub fn with_application(channels: u8, bitrate_bps: u32, application: Application) -> Result<Self, Error> {
+        // Checked before the clamp below, whose lower bound passes its upper one from 86 channels.
+        if channels != 1 && channels != 2 {
+            return Err(Error::Channels(channels));
+        }
+        let c = channels as u32;
+        let (mode, bandwidth) = choose_mode(application, bitrate_bps.clamp(6_000 * c, 510_000) / c);
+        Self::build(channels, bitrate_bps, application, mode, bandwidth)
+    }
+
+    /// Creates an encoder with an explicit mode and bandwidth instead of the application's
+    /// table. Valid combinations: SILK with narrowband, mediumband or wideband; hybrid with
+    /// super-wideband or fullband; CELT with fullband.
+    ///
+    /// Any other combination is [`Error::ModeBandwidth`]; `channels` other than 1 or 2 is
+    /// [`Error::Channels`].
+    pub fn with_mode(channels: u8, bitrate_bps: u32, mode: Mode, bandwidth: Bandwidth) -> Result<Self, Error> {
+        let ok = match mode {
+            Mode::Silk => bandwidth <= Bandwidth::Wideband,
+            Mode::Hybrid => bandwidth >= Bandwidth::SuperWideband,
+            Mode::Celt => bandwidth == Bandwidth::Fullband,
+        };
+        if !ok {
+            return Err(Error::ModeBandwidth(mode, bandwidth));
+        }
+        Self::build(channels, bitrate_bps, Application::Audio, mode, bandwidth)
+    }
+
+    fn build(channels: u8, bitrate_bps: u32, application: Application, mode: Mode, bandwidth: Bandwidth) -> Result<Self, Error> {
+        if channels != 1 && channels != 2 {
+            return Err(Error::Channels(channels));
+        }
+        let c = channels as usize;
+        let bitrate_bps = bitrate_bps.clamp(6_000 * c as u32, 510_000);
+        let packet_bytes = (bitrate_bps as usize).div_ceil(400);
+        let frame_bytes = packet_bytes.saturating_sub(1).clamp(MIN_FRAME_BYTES, MAX_FRAME_BYTES);
+        let silk = match mode {
+            Mode::Celt => None,
+            Mode::Silk | Mode::Hybrid => {
+                let fs_khz = match bandwidth {
+                    Bandwidth::Narrowband => 8,
+                    Bandwidth::Mediumband => 12,
+                    _ => 16,
+                };
+                let target_bits = if mode == Mode::Silk {
+                    bitrate_bps as f64 / 50.0 - 8.0
+                } else {
+                    // SILK gets most of a hybrid packet; CELT codes 8 kHz and up with the rest.
+                    let per = (bitrate_bps / c as u32) as f64;
+                    let share = if bandwidth == Bandwidth::SuperWideband { 0.72 } else { 0.62 };
+                    c as f64 * (per * share).min(per - 6_000.0).max(per * 0.5) / 50.0
+                };
+                Some(SilkPath {
+                    enc: SilkEncoder::new(fs_khz, c),
+                    down: (0..c).map(|_| Downsampler::new(fs_khz as u32 * 1000)).collect(),
+                    target_bits,
+                    reservoir: 0.0,
+                })
+            }
+        };
+        Ok(Encoder {
+            channels: c,
+            application,
+            mode,
+            bandwidth,
+            bitrate_bps,
+            frame_bytes,
+            mdct: Mdct::new(N),
+            preemph_mem: [0.0; 2],
+            hist: vec![0.0; c * OVERLAP],
+            old_band_e: [0.0; 2 * NB_EBANDS],
+            block: vec![0.0; N + OVERLAP],
+            freq: vec![0.0; c * N],
+            silk,
+        })
+    }
+
+    /// Number of channels.
+    pub fn channels(&self) -> u8 {
+        self.channels as u8
+    }
+
+    /// The application the encoder was created for.
+    pub fn application(&self) -> Application {
+        self.application
+    }
+
+    /// Coding mode of every packet of the stream.
+    pub fn mode(&self) -> Mode {
+        self.mode
+    }
+
+    /// Coded audio bandwidth of every packet of the stream.
+    pub fn bandwidth(&self) -> Bandwidth {
+        self.bandwidth
+    }
+
+    /// Bitrate in bits per second: the constant packet size × 50 packets per second in CELT
+    /// and hybrid modes, the (average) target in SILK mode.
+    pub fn bitrate(&self) -> u32 {
+        match self.mode {
+            Mode::Silk => self.bitrate_bps,
+            _ => ((self.frame_bytes + 1) * 8 * 50) as u32,
+        }
+    }
+
+    /// Samples at 48 kHz the decoder must discard from the start of the stream (the `OpusHead`
+    /// pre-skip): the encoder's total delay. CELT: the 120-sample MDCT overlap. SILK/hybrid:
+    /// the decimator (83 samples, 88 for narrowband) plus the decoder's SILK delay (one
+    /// internal-rate sample and the resampler delay of RFC 6716 Table 54), which also rounds
+    /// to 120 samples.
+    pub fn pre_skip(&self) -> u16 {
+        let (fs, table54_ms) = match (self.mode, self.bandwidth) {
+            (Mode::Celt, _) => return OVERLAP as u16,
+            (_, Bandwidth::Narrowband) => (8_000, 0.538),
+            (_, Bandwidth::Mediumband) => (12_000, 0.692),
+            _ => (16_000, 0.706),
+        };
+        (resample::delay(fs) as f64 + 48_000.0 / fs as f64 + table54_ms * 48.0).round() as u16
+    }
+
+    /// The 19-byte `OpusHead` identification header (RFC 7845 §5.1): version 1, channel count,
+    /// pre-skip, input sample rate 48000, output gain 0, channel mapping family 0.
+    pub fn opus_head(&self) -> Vec<u8> {
+        let mut h = Vec::with_capacity(19);
+        h.extend_from_slice(b"OpusHead");
+        h.push(1);
+        h.push(self.channels as u8);
+        h.extend_from_slice(&self.pre_skip().to_le_bytes());
+        h.extend_from_slice(&48_000u32.to_le_bytes());
+        h.extend_from_slice(&0i16.to_le_bytes());
+        h.push(0);
+        h
+    }
+
+    /// TOC byte (RFC 6716 §3.1, Table 2) of a 20 ms single-frame packet.
+    fn toc(&self) -> u8 {
+        let config: u8 = match (self.mode, self.bandwidth) {
+            (Mode::Silk, Bandwidth::Narrowband) => 1,
+            (Mode::Silk, Bandwidth::Mediumband) => 5,
+            (Mode::Silk, _) => 9,
+            (Mode::Hybrid, Bandwidth::SuperWideband) => 13,
+            (Mode::Hybrid, _) => 15,
+            (Mode::Celt, _) => 31,
+        };
+        (config << 3) | if self.channels == 2 { 4 } else { 0 }
+    }
+
+    /// Encodes one 20 ms frame of interleaved f32 samples in [-1, 1] (exactly
+    /// `FRAME_SIZE * channels` values) and returns one Opus packet, or
+    /// [`Error::FrameLength`] for any other length.
+    pub fn encode_float(&mut self, pcm: &[f32]) -> Result<Vec<u8>, Error> {
+        let c = self.channels;
+        if pcm.len() != N * c {
+            return Err(Error::FrameLength { expected: N * c, got: pcm.len() });
+        }
+        let mut packet = vec![self.toc()];
+        match self.mode {
+            Mode::Celt => {
+                let (log_e, silence) = self.celt_analysis(pcm);
+                let len = self.frame_bytes;
+                packet.extend_from_slice(&self.encode_celt(RangeEncoder::new(), len, 0, NB_EBANDS, &log_e, silence));
+            }
+            Mode::Silk => {
+                let x = self.silk_input(pcm);
+                // The SILK state exists whenever the mode uses SILK (set with the mode).
+                if let Some(sp) = self.silk.as_mut() {
+                    let target = sp.target_bits + 0.25 * sp.reservoir;
+                    let mut enc = RangeEncoder::new();
+                    sp.enc.encode(&x, target.max(24.0), (MAX_FRAME_BYTES * 8) as i32, &mut enc);
+                    let bytes = (enc.tell() as usize).div_ceil(8).max(2);
+                    let lim = 4.0 * sp.target_bits;
+                    sp.reservoir = (sp.reservoir + sp.target_bits - (bytes * 8) as f64).clamp(-lim, lim);
+                    packet.extend_from_slice(&enc.done(bytes));
+                }
+            }
+            Mode::Hybrid => {
+                let x = self.silk_input(pcm);
+                let len = self.frame_bytes;
+                let total = (len * 8) as i32;
+                let celt_min = (total / 5).max(80);
+                let mut enc = RangeEncoder::new();
+                if let Some(sp) = self.silk.as_mut() {
+                    sp.enc.encode(&x, sp.target_bits, total - celt_min, &mut enc);
+                }
+                // No redundancy (RFC 6716 §4.5.1); the flag is present when there is room.
+                if enc.tell() + 17 + 20 <= total {
+                    enc.bit_logp(false, 12);
+                }
+                let (log_e, _) = self.celt_analysis(pcm);
+                let end = if self.bandwidth == Bandwidth::SuperWideband { 19 } else { NB_EBANDS };
+                packet.extend_from_slice(&self.encode_celt(enc, len, HYBRID_START_BAND, end, &log_e, false));
+            }
+        }
+        Ok(packet)
+    }
+
+    /// Decimates the input to the SILK internal rate (16-bit scale), one vector per channel.
+    fn silk_input(&mut self, pcm: &[f32]) -> Vec<Vec<f32>> {
+        let c = self.channels;
+        let Some(sp) = self.silk.as_mut() else { return vec![vec![]; c] };
+        let mut out = Vec::with_capacity(c);
+        let mut tmp = vec![0f32; N];
+        for ch in 0..c {
+            for (j, t) in tmp.iter_mut().enumerate() {
+                let s = pcm[j * c + ch];
+                *t = if s.is_finite() { s.clamp(-1.0, 1.0) * 32768.0 } else { 0.0 };
+            }
+            let mut y = Vec::with_capacity(N / 3);
+            sp.down[ch].process(&tmp, &mut y);
+            out.push(y);
+        }
+        out
+    }
+
+    /// Pre-emphasis, the MDCT, band energies (log2, relative to `E_MEANS`) and normalised
+    /// bands; returns the energies and whether the frame is digital silence.
+    fn celt_analysis(&mut self, pcm: &[f32]) -> ([f32; 2 * NB_EBANDS], bool) {
+        let c = self.channels;
+        let mut log_e = [0f32; 2 * NB_EBANDS];
+        let mut peak = 0f32;
+        for ch in 0..c {
+            self.block[..OVERLAP].copy_from_slice(&self.hist[ch * OVERLAP..(ch + 1) * OVERLAP]);
+            let mut mem = self.preemph_mem[ch];
+            for j in 0..N {
+                let s = pcm[j * c + ch];
+                let s = if s.is_finite() { s.clamp(-2.0, 2.0) * 32768.0 } else { 0.0 };
+                let v = s - PREEMPH * mem;
+                mem = s;
+                self.block[OVERLAP + j] = v;
+            }
+            self.preemph_mem[ch] = mem;
+            self.hist[ch * OVERLAP..(ch + 1) * OVERLAP].copy_from_slice(&self.block[N..]);
+            peak = self.block.iter().fold(peak, |p, v| p.max(v.abs()));
+            let freq = &mut self.freq[ch * N..(ch + 1) * N];
+            self.mdct.forward(&self.block, freq);
+            for i in 0..NB_EBANDS {
+                let lo = (EBANDS[i] as usize) << LM;
+                let hi = (EBANDS[i + 1] as usize) << LM;
+                let e = (1e-27f32 + freq[lo..hi].iter().map(|v| v * v).sum::<f32>()).sqrt();
+                log_e[ch * NB_EBANDS + i] = e.log2() - E_MEANS[i];
+                let g = 1.0 / e;
+                for v in freq[lo..hi].iter_mut() {
+                    *v *= g;
+                }
+            }
+        }
+        (log_e, peak < 1e-4)
+    }
+
+    /// Codes one CELT frame (RFC 6716 §4.3, in bitstream order) of `len` bytes into `enc`
+    /// (which already holds the SILK frame in hybrid mode), coding bands `start..end`, and
+    /// finalises the frame.
+    #[allow(clippy::too_many_arguments)]
+    fn encode_celt(&mut self, mut enc: RangeEncoder, len: usize, start: usize, end: usize, log_e: &[f32; 2 * NB_EBANDS], silence: bool) -> Vec<u8> {
+        let m = celt_mode();
+        let c = self.channels;
+        if c == 1 {
+            for i in 0..NB_EBANDS {
+                self.old_band_e[i] = self.old_band_e[i].max(self.old_band_e[NB_EBANDS + i]);
+            }
+        }
+        if silence && start == 0 {
+            // The silence flag; the decoder treats every remaining bit as consumed.
+            enc.bit_logp(true, 15);
+            self.old_band_e = [-28.0; 2 * NB_EBANDS];
+            return enc.done(2);
+        }
+        let total_bits_raw = len as i32 * 8;
+        if enc.tell() == 1 {
+            enc.bit_logp(false, 15);
+        }
+        // No pitch post-filter (only signalled in CELT-only frames).
+        if start == 0 && enc.tell() + 16 <= total_bits_raw {
+            enc.bit_logp(false, 1);
+        }
+        // Long blocks only.
+        if enc.tell() + 3 <= total_bits_raw {
+            enc.bit_logp(false, 3);
+        }
+        // Coarse energy, choosing intra or inter prediction by trial (whichever is cheaper).
+        if enc.tell() + 3 <= total_bits_raw {
+            let mut enc_intra = enc.clone();
+            let mut old_intra = self.old_band_e;
+            enc_intra.bit_logp(true, 3);
+            quant_coarse_energy(start, end, log_e, &mut old_intra, true, &mut enc_intra, c, LM, total_bits_raw);
+            enc.bit_logp(false, 3);
+            let mut old_inter = self.old_band_e;
+            quant_coarse_energy(start, end, log_e, &mut old_inter, false, &mut enc, c, LM, total_bits_raw);
+            if enc_intra.tell_frac() < enc.tell_frac() {
+                enc = enc_intra;
+                self.old_band_e = old_intra;
+            } else {
+                self.old_band_e = old_inter;
+            }
+        } else {
+            quant_coarse_energy(start, end, log_e, &mut self.old_band_e, false, &mut enc, c, LM, total_bits_raw);
+        }
+        // TF resolution: no changes.
+        {
+            let mut budget = total_bits_raw;
+            let mut tell = enc.tell();
+            let mut logp = 4;
+            let tf_select_rsv = LM > 0 && tell + logp + 1 <= budget;
+            budget -= tf_select_rsv as i32;
+            for _ in start..end {
+                if tell + logp <= budget {
+                    enc.bit_logp(false, logp as u32);
+                    tell = enc.tell();
+                }
+                logp = 5;
+            }
+            if tf_select_rsv && TF_SELECT_TABLE[LM][0] != TF_SELECT_TABLE[LM][2] {
+                enc.bit_logp(false, 1);
+            }
+        }
+        if enc.tell() + 4 <= total_bits_raw {
+            enc.icdf(SPREAD_NORMAL, &SPREAD_ICDF, 5);
+        }
+        // Dynamic allocation: no boosts.
+        let cap = m.init_caps(LM, c);
+        let offsets = [0i32; NB_EBANDS];
+        let total_bits = total_bits_raw << BITRES;
+        let mut tellf = enc.tell_frac();
+        for &cp in cap.iter().take(end).skip(start) {
+            if tellf + (6 << BITRES) < total_bits && 0 < cp {
+                enc.bit_logp(false, 6);
+                tellf = enc.tell_frac();
+            }
+        }
+        let alloc_trim = 5;
+        if tellf + (6 << BITRES) <= total_bits {
+            enc.icdf(alloc_trim as usize, &TRIM_ICDF, 7);
+        }
+        let bits = (total_bits_raw << BITRES) - enc.tell_frac() - 1;
+        let alloc = compute_allocation(m, start, end, &offsets, &cap, alloc_trim, bits, c, LM, &mut enc);
+        quant_fine_energy(start, end, log_e, &mut self.old_band_e, &alloc.fine_quant, &mut enc, c);
+        quant_all_bands(
+            m,
+            start,
+            end,
+            &self.freq,
+            N,
+            c,
+            &alloc.pulses,
+            SPREAD_NORMAL,
+            alloc.dual_stereo,
+            alloc.intensity,
+            total_bits_raw << BITRES,
+            alloc.balance,
+            &mut enc,
+            LM,
+            alloc.coded_bands,
+        );
+        let bits_left = total_bits_raw - enc.tell();
+        quant_energy_finalise(start, end, log_e, &mut self.old_band_e, &alloc.fine_quant, &alloc.fine_priority, bits_left, &mut enc, c);
+        debug_assert!(enc.tell() <= total_bits_raw, "frame overflow: {} > {}", enc.tell(), total_bits_raw);
+        if c == 1 {
+            let (a, b) = self.old_band_e.split_at_mut(NB_EBANDS);
+            b.copy_from_slice(a);
+        }
+        // The decoder forgets the energies of bands it did not code.
+        for ch in 0..2 {
+            for i in (0..start).chain(end..NB_EBANDS) {
+                self.old_band_e[ch * NB_EBANDS + i] = 0.0;
+            }
+        }
+        enc.done(len)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn opus_head_layout() {
+        let e = Encoder::new(2, 96_000).unwrap();
+        let h = e.opus_head();
+        assert_eq!(&h[..8], b"OpusHead");
+        assert_eq!(h[8], 1);
+        assert_eq!(h[9], 2);
+        assert_eq!(u16::from_le_bytes([h[10], h[11]]), e.pre_skip());
+        assert_eq!(u32::from_le_bytes([h[12], h[13], h[14], h[15]]), 48_000);
+        assert_eq!(&h[16..], &[0, 0, 0]);
+    }
+
+    #[test]
+    fn packet_sizes_follow_bitrate() {
+        for (ch, rate) in [(1u8, 64_000u32), (2, 128_000), (2, 256_000)] {
+            let mut e = Encoder::new(ch, rate).unwrap();
+            let pcm: Vec<f32> = (0..N * ch as usize).map(|i| (i as f32 * 0.05).sin() * 0.5).collect();
+            let p = e.encode_float(&pcm).unwrap();
+            assert_eq!(p.len(), rate as usize / 400);
+            assert_eq!(p[0], 0xF8 | if ch == 2 { 4 } else { 0 });
+            assert_eq!(e.bitrate(), rate);
+        }
+    }
+
+    #[test]
+    fn silence_is_a_tiny_packet() {
+        let mut e = Encoder::new(1, 64_000).unwrap();
+        let p = e.encode_float(&vec![0.0; N]).unwrap();
+        assert_eq!(p.len(), 3);
+    }
+
+    #[test]
+    fn wrong_frame_length_is_an_error() {
+        let mut e = Encoder::new(2, 128_000).unwrap();
+        assert_eq!(e.encode_float(&vec![0.0; N]), Err(Error::FrameLength { expected: 2 * N, got: N }));
+        assert_eq!(e.encode_float(&[]), Err(Error::FrameLength { expected: 2 * N, got: 0 }));
+        assert!(e.encode_float(&vec![0.0; 2 * N]).is_ok());
+    }
+}
diff --git a/crates/audio/src/opus/encoder/range.rs b/crates/audio/src/opus/encoder/range.rs
new file mode 100644
index 000000000..daedd58ae
--- /dev/null
+++ b/crates/audio/src/opus/encoder/range.rs
@@ -0,0 +1,472 @@
+//! Range encoder (RFC 6716 §5.1), the exact inverse of the §4.1 range decoder.
+//!
+//! Range-coded symbols are written from the front of the buffer and raw bits from the back; the
+//! bit accounting ([`RangeEncoder::tell`], [`RangeEncoder::tell_frac`]) matches the decoder's, so
+//! every budget decision the decoder takes can be mirrored exactly.
+
+const SYM_BITS: u32 = 8;
+const CODE_BITS: u32 = 32;
+const SYM_MAX: u32 = (1 << SYM_BITS) - 1;
+const CODE_SHIFT: u32 = CODE_BITS - SYM_BITS - 1;
+const CODE_TOP: u32 = 1 << (CODE_BITS - 1);
+const CODE_BOT: u32 = CODE_TOP >> SYM_BITS;
+/// Bit resolution of [`RangeEncoder::tell_frac`] (1/8 bit).
+pub const BITRES: u32 = 3;
+
+/// Number of bits needed to represent `x` (0 for 0).
+#[inline]
+pub fn ilog(x: u32) -> i32 {
+    (32 - x.leading_zeros()) as i32
+}
+
+#[derive(Clone, Debug)]
+pub struct RangeEncoder {
+    out: Vec<u8>,
+    end: Vec<u8>,
+    end_window: u32,
+    nend_bits: i32,
+    nbits_total: i32,
+    rng: u32,
+    low: u32,
+    rem: i32,
+    ext: u32,
+}
+
+impl Default for RangeEncoder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl RangeEncoder {
+    pub fn new() -> Self {
+        RangeEncoder {
+            out: Vec::new(),
+            end: Vec::new(),
+            end_window: 0,
+            nend_bits: 0,
+            nbits_total: (CODE_BITS + 1) as i32,
+            rng: CODE_TOP,
+            low: 0,
+            rem: -1,
+            ext: 0,
+        }
+    }
+
+    /// Current range (equals the decoder's range after the same symbols).
+    #[cfg(test)]
+    pub fn rng(&self) -> u32 {
+        self.rng
+    }
+
+    fn carry_out(&mut self, c: u32) {
+        if c != SYM_MAX {
+            let carry = c >> SYM_BITS;
+            if self.rem >= 0 {
+                self.out.push((self.rem as u32 + carry) as u8);
+            }
+            if self.ext > 0 {
+                let sym = (SYM_MAX + carry) & SYM_MAX;
+                for _ in 0..self.ext {
+                    self.out.push(sym as u8);
+                }
+                self.ext = 0;
+            }
+            self.rem = (c & SYM_MAX) as i32;
+        } else {
+            self.ext += 1;
+        }
+    }
+
+    #[inline]
+    fn normalize(&mut self) {
+        while self.rng <= CODE_BOT {
+            self.carry_out(self.low >> CODE_SHIFT);
+            self.low = (self.low << SYM_BITS) & (CODE_TOP - 1);
+            self.rng <<= SYM_BITS;
+            self.nbits_total += SYM_BITS as i32;
+        }
+    }
+
+    /// Encodes the symbol with cumulative range `[fl, fh)` of total `ft`.
+    pub fn encode(&mut self, fl: u32, fh: u32, ft: u32) {
+        let r = self.rng / ft;
+        if fl > 0 {
+            self.low += self.rng - r * (ft - fl);
+            self.rng = r * (fh - fl);
+        } else {
+            self.rng -= r * (ft - fh);
+        }
+        self.normalize();
+    }
+
+    /// Like [`Self::encode`] with `ft = 1 << bits`.
+    pub fn encode_bin(&mut self, fl: u32, fh: u32, bits: u32) {
+        let r = self.rng >> bits;
+        let ft = 1u32 << bits;
+        if fl > 0 {
+            self.low += self.rng - r * (ft - fl);
+            self.rng = r * (fh - fl);
+        } else {
+            self.rng -= r * (ft - fh);
+        }
+        self.normalize();
+    }
+
+    /// Encodes a binary symbol whose probability of being 1 is `1/2^logp`.
+    pub fn bit_logp(&mut self, val: bool, logp: u32) {
+        let r = self.rng;
+        let s = r >> logp;
+        let r2 = r - s;
+        if val {
+            self.low += r2;
+            self.rng = s;
+        } else {
+            self.rng = r2;
+        }
+        self.normalize();
+    }
+
+    /// Encodes symbol `s` with an "inverse CDF" table (`ft = 1 << ftb`).
+    pub fn icdf(&mut self, s: usize, icdf: &[u8], ftb: u32) {
+        let r = self.rng >> ftb;
+        if s > 0 {
+            self.low += self.rng - r * icdf[s - 1] as u32;
+            self.rng = r * (icdf[s - 1] as u32 - icdf[s] as u32);
+        } else {
+            self.rng -= r * icdf[s] as u32;
+        }
+        self.normalize();
+    }
+
+    /// Encodes a uniformly distributed integer `fl` in `[0, ft)` (`ft >= 2`).
+    pub fn uint(&mut self, fl: u32, ft: u32) {
+        debug_assert!(ft > 1 && fl < ft);
+        let ft1 = ft - 1;
+        let ftb = ilog(ft1);
+        if ftb > 8 {
+            let ftb = (ftb - 8) as u32;
+            let top = (ft1 >> ftb) + 1;
+            let v = fl >> ftb;
+            self.encode(v, v + 1, top);
+            self.bits(fl & ((1 << ftb) - 1), ftb);
+        } else {
+            self.encode(fl, fl + 1, ft);
+        }
+    }
+
+    /// Writes `bits` raw bits (0..=25) to the end of the buffer.
+    pub fn bits(&mut self, val: u32, bits: u32) {
+        if bits == 0 {
+            return;
+        }
+        let mut window = self.end_window;
+        let mut used = self.nend_bits;
+        if used as u32 + bits > CODE_BITS {
+            while used >= SYM_BITS as i32 {
+                self.end.push((window & SYM_MAX) as u8);
+                window >>= SYM_BITS;
+                used -= SYM_BITS as i32;
+            }
+        }
+        window |= val << used;
+        used += bits as i32;
+        self.end_window = window;
+        self.nend_bits = used;
+        self.nbits_total += bits as i32;
+    }
+
+    /// Number of bits written so far (rounded up), identical to the decoder's `tell`.
+    #[inline]
+    pub fn tell(&self) -> i32 {
+        self.nbits_total - ilog(self.rng)
+    }
+
+    /// Number of 1/8 bits written so far (rounded up), identical to the decoder's `tell_frac`.
+    pub fn tell_frac(&self) -> i32 {
+        let nbits = (self.nbits_total as u32) << BITRES;
+        let mut l = ilog(self.rng) as u32;
+        let mut r = self.rng >> (l - 16);
+        for _ in 0..BITRES {
+            r = (r * r) >> 15;
+            let b = r >> 16;
+            l = (l << 1) | b;
+            r >>= b;
+        }
+        nbits.wrapping_sub(l) as i32
+    }
+
+    /// Finalises the stream into a buffer of exactly `size` bytes (range data at the front, raw
+    /// bits at the back, zero padding in between; a partial raw-bit byte is merged into the byte
+    /// just before the full raw-bit bytes).
+    pub fn done(mut self, size: usize) -> Vec<u8> {
+        let mut l = CODE_BITS as i32 - ilog(self.rng);
+        let mut msk = (CODE_TOP - 1) >> l;
+        let mut end = (self.low.wrapping_add(msk)) & !msk;
+        if (end | msk) >= self.low.wrapping_add(self.rng) {
+            l += 1;
+            msk >>= 1;
+            end = (self.low.wrapping_add(msk)) & !msk;
+        }
+        while l > 0 {
+            self.carry_out(end >> CODE_SHIFT);
+            end = (end << SYM_BITS) & (CODE_TOP - 1);
+            l -= SYM_BITS as i32;
+        }
+        if self.rem >= 0 || self.ext > 0 {
+            self.carry_out(0);
+        }
+        let mut window = self.end_window;
+        let mut used = self.nend_bits;
+        while used >= SYM_BITS as i32 {
+            self.end.push((window & SYM_MAX) as u8);
+            window >>= SYM_BITS;
+            used -= SYM_BITS as i32;
+        }
+        let mut buf = vec![0u8; size];
+        let full = self.end.len().min(size);
+        let room = size - full;
+        let n = self.out.len().min(room);
+        buf[..n].copy_from_slice(&self.out[..n]);
+        for (k, &b) in self.end.iter().take(full).enumerate() {
+            buf[size - 1 - k] = b;
+        }
+        if used > 0 && room > 0 {
+            buf[room - 1] |= window as u8;
+        }
+        buf
+    }
+}
+
+#[cfg(test)]
+pub(crate) mod dec {
+    //! Minimal range decoder (RFC 6716 §4.1) used to verify the encoder.
+    use super::*;
+    const CODE_EXTRA: u32 = (CODE_BITS - 2) % SYM_BITS + 1;
+
+    pub struct RangeDecoder<'a> {
+        buf: &'a [u8],
+        offs: usize,
+        end_offs: usize,
+        end_window: u32,
+        nend_bits: i32,
+        nbits_total: i32,
+        rng: u32,
+        val: u32,
+        rem: u32,
+    }
+
+    impl<'a> RangeDecoder<'a> {
+        pub fn new(buf: &'a [u8]) -> Self {
+            let mut d = RangeDecoder {
+                buf,
+                offs: 0,
+                end_offs: 0,
+                end_window: 0,
+                nend_bits: 0,
+                nbits_total: (CODE_BITS + 1 - ((CODE_BITS - CODE_EXTRA) / SYM_BITS) * SYM_BITS) as i32,
+                rng: 1 << CODE_EXTRA,
+                val: 0,
+                rem: 0,
+            };
+            d.rem = d.read_byte();
+            d.val = d.rng - 1 - (d.rem >> (SYM_BITS - CODE_EXTRA));
+            d.normalize();
+            d
+        }
+        fn read_byte(&mut self) -> u32 {
+            if self.offs < self.buf.len() {
+                self.offs += 1;
+                self.buf[self.offs - 1] as u32
+            } else {
+                0
+            }
+        }
+        fn read_byte_from_end(&mut self) -> u32 {
+            if self.end_offs < self.buf.len() {
+                self.end_offs += 1;
+                self.buf[self.buf.len() - self.end_offs] as u32
+            } else {
+                0
+            }
+        }
+        fn normalize(&mut self) {
+            while self.rng <= CODE_BOT {
+                self.nbits_total += SYM_BITS as i32;
+                self.rng <<= SYM_BITS;
+                let sym = self.rem;
+                self.rem = self.read_byte();
+                let sym = ((sym << SYM_BITS) | self.rem) >> (SYM_BITS - CODE_EXTRA);
+                self.val = ((self.val << SYM_BITS).wrapping_add(SYM_MAX & !sym)) & (CODE_TOP - 1);
+            }
+        }
+        pub fn rng(&self) -> u32 {
+            self.rng
+        }
+        pub fn decode(&mut self, ft: u32) -> u32 {
+            let ext = self.rng / ft;
+            let s = self.val / ext;
+            ft - (s + 1).min(ft)
+        }
+        pub fn update(&mut self, fl: u32, fh: u32, ft: u32) {
+            let ext = self.rng / ft;
+            let s = ext * (ft - fh);
+            self.val = self.val.wrapping_sub(s);
+            self.rng = if fl > 0 { ext * (fh - fl) } else { self.rng - s };
+            self.normalize();
+        }
+        pub fn bit_logp(&mut self, logp: u32) -> bool {
+            let r = self.rng;
+            let d = self.val;
+            let s = r >> logp;
+            let ret = d < s;
+            if !ret {
+                self.val = d - s;
+            }
+            self.rng = if ret { s } else { r - s };
+            self.normalize();
+            ret
+        }
+        pub fn icdf(&mut self, icdf: &[u8], ftb: u32) -> usize {
+            let mut s = self.rng;
+            let d = self.val;
+            let r = s >> ftb;
+            let mut ret = 0usize;
+            let mut t;
+            loop {
+                t = s;
+                s = r * icdf[ret] as u32;
+                if d >= s {
+                    break;
+                }
+                ret += 1;
+            }
+            self.val = d - s;
+            self.rng = t - s;
+            self.normalize();
+            ret
+        }
+        pub fn uint(&mut self, ft: u32) -> u32 {
+            let ft1 = ft - 1;
+            let ftb = ilog(ft1);
+            if ftb > 8 {
+                let ftb = (ftb - 8) as u32;
+                let top = (ft1 >> ftb) + 1;
+                let s = self.decode(top);
+                self.update(s, s + 1, top);
+                (s << ftb) | self.bits(ftb)
+            } else {
+                let s = self.decode(ft);
+                self.update(s, s + 1, ft);
+                s
+            }
+        }
+        pub fn bits(&mut self, bits: u32) -> u32 {
+            let mut window = self.end_window;
+            let mut available = self.nend_bits;
+            if (available as u32) < bits {
+                loop {
+                    window |= self.read_byte_from_end() << available;
+                    available += SYM_BITS as i32;
+                    if available > (CODE_BITS - SYM_BITS) as i32 {
+                        break;
+                    }
+                }
+            }
+            let ret = window & ((1u32 << bits) - 1);
+            self.end_window = window >> bits;
+            self.nend_bits = available - bits as i32;
+            self.nbits_total += bits as i32;
+            ret
+        }
+        pub fn tell(&self) -> i32 {
+            self.nbits_total - ilog(self.rng)
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::dec::RangeDecoder;
+    use super::*;
+
+    struct Lcg(u32);
+    impl Lcg {
+        fn next(&mut self) -> u32 {
+            self.0 = self.0.wrapping_mul(1664525).wrapping_add(1013904223);
+            self.0 >> 8
+        }
+    }
+
+    #[test]
+    fn starts_at_one_bit() {
+        let e = RangeEncoder::new();
+        assert_eq!(e.tell(), 1);
+        assert_eq!(e.tell_frac(), 8);
+    }
+
+    #[test]
+    fn roundtrip_mixed_symbols_and_tell_matches() {
+        let mut rng = Lcg(7);
+        let icdf: [u8; 4] = [200, 120, 30, 0];
+        for trial in 0..300 {
+            let n = 1 + (rng.next() % 300) as usize;
+            let mut ops = Vec::new();
+            for _ in 0..n {
+                match rng.next() % 5 {
+                    0 => {
+                        let ft = 2 + rng.next() % 1000;
+                        ops.push((0u8, rng.next() % ft, ft));
+                    }
+                    1 => {
+                        let logp = 1 + rng.next() % 15;
+                        ops.push((1, rng.next().is_multiple_of(5) as u32, logp));
+                    }
+                    2 => {
+                        let bits = 1 + rng.next() % 24;
+                        ops.push((2, rng.next() & ((1 << bits) - 1), bits));
+                    }
+                    3 => {
+                        let ft = 2 + rng.next() % 100_000_000;
+                        ops.push((3, rng.next() % ft, ft));
+                    }
+                    _ => ops.push((4, rng.next() % 4, 0)),
+                }
+            }
+            let mut e = RangeEncoder::new();
+            let mut tells = Vec::new();
+            for &(k, v, p) in &ops {
+                match k {
+                    0 => e.encode(v, v + 1, p),
+                    1 => e.bit_logp(v != 0, p),
+                    2 => e.bits(v, p),
+                    3 => e.uint(v, p),
+                    _ => e.icdf(v as usize, &icdf, 8),
+                }
+                tells.push(e.tell());
+            }
+            // Exactly the number of bytes `tell` says were used must suffice.
+            let size = (e.tell() as usize).div_ceil(8);
+            let final_rng = e.rng();
+            let buf = e.done(size);
+            assert_eq!(buf.len(), size);
+            let mut d = RangeDecoder::new(&buf);
+            for (i, &(k, v, p)) in ops.iter().enumerate() {
+                let got = match k {
+                    0 => {
+                        let s = d.decode(p);
+                        d.update(s, s + 1, p);
+                        s
+                    }
+                    1 => d.bit_logp(p) as u32,
+                    2 => d.bits(p),
+                    3 => d.uint(p),
+                    _ => d.icdf(&icdf, 8) as u32,
+                };
+                assert_eq!(got, v, "trial {trial} op {i} kind {k}");
+                assert_eq!(d.tell(), tells[i], "tell mismatch trial {trial} op {i}");
+            }
+            assert_eq!(d.rng(), final_rng);
+        }
+    }
+}
diff --git a/crates/audio/src/opus/encoder/rate.rs b/crates/audio/src/opus/encoder/rate.rs
new file mode 100644
index 000000000..c360f9da7
--- /dev/null
+++ b/crates/audio/src/opus/encoder/rate.rs
@@ -0,0 +1,561 @@
+//! Pulse cache and bit allocation (RFC 6716 §4.3.3, §4.3.4.1).
+//!
+//! The allocation must be bit-identical to the decoder's, so this mirrors FilmCraft's
+//! spec-derived `filmcraft-opus` decoder (first-party, MIT OR Apache-2.0) step by step; the only
+//! difference is that the encoder *writes* the band-skip, intensity and dual-stereo symbols.
+
+use crate::opus::encoder::range::{BITRES, RangeEncoder, ilog};
+use crate::opus::encoder::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS};
+
+const MAX_PSEUDO: i32 = 40;
+const LOG_MAX_PSEUDO: i32 = 6;
+pub const MAX_FINE_BITS: i32 = 8;
+const FINE_OFFSET: i32 = 21;
+pub const QTHETA_OFFSET: i32 = 4;
+pub const QTHETA_OFFSET_TWOPHASE: i32 = 16;
+const ALLOC_STEPS: i32 = 6;
+
+/// Number of pulses represented by pseudo-pulse index `i`.
+pub fn get_pulses(i: i32) -> i32 {
+    if i < 8 { i } else { (8 + (i & 7)) << ((i >> 3) - 1) }
+}
+
+/// Conservative (rounded up) log2 of `val` with `frac` fractional bits.
+pub fn log2_frac(mut val: u32, mut frac: u32) -> i32 {
+    let mut l = ilog(val);
+    if val & val.wrapping_sub(1) != 0 {
+        if l > 16 {
+            val = ((val - 1) >> (l - 16)) + 1;
+        } else {
+            val <<= 16 - l;
+        }
+        let mut l = (l - 1) << frac;
+        loop {
+            let b = (val >> 16) as i32;
+            l += b << frac;
+            val = (val + b as u32) >> b;
+            val = (val * val + 0x7FFF) >> 15;
+            if frac == 0 {
+                break;
+            }
+            frac -= 1;
+        }
+        l + (val > 0x8000) as i32
+    } else {
+        l -= 1;
+        l << frac
+    }
+}
+
+/// PVQ codebook size V(N, K) (saturating far above 2^32).
+pub fn pvq_v(n: usize, k: usize) -> u128 {
+    if k == 0 {
+        return 1;
+    }
+    if n == 0 {
+        return 0;
+    }
+    let mut row = vec![0u128; k + 1];
+    row[0] = 1;
+    for _ in 0..n {
+        let mut prev_diag = row[0];
+        for kk in 1..=k {
+            let up = row[kk];
+            let v = up.saturating_add(row[kk - 1]).saturating_add(prev_diag);
+            prev_diag = up;
+            row[kk] = v.min(u128::MAX >> 8);
+        }
+        row[0] = 1;
+    }
+    row[k]
+}
+
+fn fits_in32(n: usize, k: i32) -> bool {
+    pvq_v(n, k as usize) <= u32::MAX as u128
+}
+
+/// Precomputed per-mode data.
+pub struct Mode {
+    /// log2 of band width in 1/8 bits.
+    pub log_n: [i32; NB_EBANDS],
+    cache_index: Vec<i16>,
+    cache_bits: Vec<u8>,
+    caps: Vec<u8>,
+}
+
+impl Mode {
+    pub fn new() -> Mode {
+        let mut log_n = [0i32; NB_EBANDS];
+        for (i, l) in log_n.iter_mut().enumerate() {
+            *l = log2_frac((EBANDS[i + 1] - EBANDS[i]) as u32, BITRES);
+        }
+        let (cache_index, cache_bits) = compute_pulse_cache(MAX_LM as i32);
+        let mut m = Mode { log_n, cache_index, cache_bits, caps: Vec::new() };
+        m.caps = compute_caps(&m);
+        m
+    }
+
+    #[inline]
+    pub fn cache(&self, lm: i32, band: usize) -> &[u8] {
+        let idx = self.cache_index[((lm + 1) as usize) * NB_EBANDS + band];
+        &self.cache_bits[idx.max(0) as usize..]
+    }
+
+    pub fn bits2pulses(&self, band: usize, lm: i32, bits: i32) -> i32 {
+        let cache = self.cache(lm, band);
+        let mut lo = 0i32;
+        let mut hi = cache[0] as i32;
+        let bits = bits - 1;
+        for _ in 0..LOG_MAX_PSEUDO {
+            let mid = (lo + hi + 1) >> 1;
+            if cache[mid as usize] as i32 >= bits {
+                hi = mid;
+            } else {
+                lo = mid;
+            }
+        }
+        let lo_bits = if lo == 0 { -1 } else { cache[lo as usize] as i32 };
+        if bits - lo_bits <= cache[hi as usize] as i32 - bits { lo } else { hi }
+    }
+
+    pub fn pulses2bits(&self, band: usize, lm: i32, pulses: i32) -> i32 {
+        if pulses == 0 { 0 } else { self.cache(lm, band)[pulses as usize] as i32 + 1 }
+    }
+
+    /// Per-band allocation caps for this frame (`init_caps`).
+    pub fn init_caps(&self, lm: usize, c: usize) -> [i32; NB_EBANDS] {
+        let mut cap = [0i32; NB_EBANDS];
+        for (i, cp) in cap.iter_mut().enumerate() {
+            let n = (EBANDS[i + 1] - EBANDS[i]) << lm;
+            *cp = (self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n >> 2;
+        }
+        cap
+    }
+}
+
+fn compute_pulse_cache(lm_max: i32) -> (Vec<i16>, Vec<u8>) {
+    let nb = NB_EBANDS;
+    let rows = (lm_max + 2) as usize;
+    let mut index = vec![-1i16; nb * rows];
+    let mut entries: Vec<(usize, i32, usize)> = Vec::new();
+    let mut curr = 0usize;
+    for i in 0..rows {
+        for j in 0..nb {
+            let n = (((EBANDS[j + 1] - EBANDS[j]) << i) >> 1) as usize;
+            index[i * nb + j] = -1;
+            'search: for k in 0..=i {
+                for nn in 0..nb {
+                    if k == i && nn >= j {
+                        break;
+                    }
+                    if n == (((EBANDS[nn + 1] - EBANDS[nn]) << k) >> 1) as usize {
+                        index[i * nb + j] = index[k * nb + nn];
+                        break 'search;
+                    }
+                }
+            }
+            if index[i * nb + j] == -1 && n != 0 {
+                let mut k = 0;
+                while k < MAX_PSEUDO && fits_in32(n, get_pulses(k + 1)) {
+                    k += 1;
+                }
+                index[i * nb + j] = curr as i16;
+                entries.push((n, k, curr));
+                curr += (k + 1) as usize;
+            }
+        }
+    }
+    let mut bits = vec![0u8; curr];
+    for &(n, k, off) in &entries {
+        let maxk = get_pulses(k) as usize;
+        let tmp = required_bits(n, maxk, BITRES);
+        for j in 1..=k {
+            bits[off + j as usize] = (tmp[get_pulses(j) as usize] - 1) as u8;
+        }
+        bits[off] = k as u8;
+    }
+    (index, bits)
+}
+
+fn required_bits(n: usize, maxk: usize, frac: u32) -> Vec<i32> {
+    let mut out = vec![0i32; maxk + 1];
+    if n == 1 {
+        for o in out.iter_mut().skip(1) {
+            *o = 1 << frac;
+        }
+    } else {
+        for (k, o) in out.iter_mut().enumerate().skip(1) {
+            *o = log2_frac(pvq_v(n, k) as u32, frac);
+        }
+    }
+    out
+}
+
+fn compute_caps(m: &Mode) -> Vec<u8> {
+    let nb = NB_EBANDS;
+    let mut caps = vec![0u8; (MAX_LM + 1) * 2 * nb];
+    for i in 0..=MAX_LM as i32 {
+        for c in 1..=2i32 {
+            for j in 0..nb {
+                let mut n0 = EBANDS[j + 1] - EBANDS[j];
+
+                let max_bits = if n0 << i == 1 {
+                    c * (1 + MAX_FINE_BITS) << BITRES
+                } else {
+                    let mut lm0 = 0;
+                    if n0 > 2 {
+                        n0 >>= 1;
+                        lm0 -= 1;
+                    } else if n0 <= 1 {
+                        lm0 = i.min(1);
+                        n0 <<= lm0;
+                    }
+                    let pcache = m.cache(lm0, j);
+                    let mut mb = pcache[pcache[0] as usize] as i32 + 1;
+                    let mut n = n0;
+                    for k in 0..(i - lm0) {
+                        mb <<= 1;
+                        let offset = ((m.log_n[j] + ((lm0 + k) << BITRES)) >> 1) - QTHETA_OFFSET;
+                        let num = 459 * ((2 * n - 1) * offset + mb);
+                        let den = ((2 * n - 1) << 9) - 459;
+                        let qb = ((num + (den >> 1)) / den).min(57);
+                        mb += qb;
+                        n <<= 1;
+                    }
+                    if c == 2 {
+                        mb <<= 1;
+                        let offset = ((m.log_n[j] + (i << BITRES)) >> 1) - if n == 2 { QTHETA_OFFSET_TWOPHASE } else { QTHETA_OFFSET };
+                        let ndof = 2 * n - 1 - (n == 2) as i32;
+                        let p = if n == 2 { 512 } else { 487 };
+                        let num = p * (mb + ndof * offset);
+                        let den = (ndof << 9) - p;
+                        let qb = ((num + (den >> 1)) / den).min(if n == 2 { 64 } else { 61 });
+                        mb += qb;
+                    }
+                    let ndof = c * n + if c == 2 && n > 2 { 1 } else { 0 };
+                    let mut offset = ((m.log_n[j] + (i << BITRES)) >> 1) - FINE_OFFSET;
+                    if n == 2 {
+                        offset += (1 << BITRES) >> 2;
+                    }
+                    let num = mb + ndof * offset;
+                    let den = (ndof - 1) << BITRES;
+                    let qb = ((num + (den >> 1)) / den).min(MAX_FINE_BITS);
+                    mb += c * qb << BITRES;
+                    mb
+                };
+                let w = c * ((EBANDS[j + 1] - EBANDS[j]) << i);
+                let v = (4 * max_bits / w) - 64;
+                caps[((i * 2 + c - 1) as usize) * nb + j] = v.clamp(0, 255) as u8;
+            }
+        }
+    }
+    caps
+}
+
+/// Result of the allocation process.
+pub struct Allocation {
+    pub coded_bands: usize,
+    pub intensity: usize,
+    pub dual_stereo: bool,
+    pub balance: i32,
+    pub pulses: [i32; NB_EBANDS],
+    pub fine_quant: [i32; NB_EBANDS],
+    pub fine_priority: [i32; NB_EBANDS],
+}
+
+/// `clt_compute_allocation`, encoder side. Stereo frames are always coded as dual (L/R) stereo
+/// with no intensity bands, and no band is skipped voluntarily.
+#[allow(clippy::too_many_arguments)]
+pub fn compute_allocation(
+    m: &Mode,
+    start: usize,
+    end: usize,
+    offsets: &[i32; NB_EBANDS],
+    cap: &[i32; NB_EBANDS],
+    alloc_trim: i32,
+    total: i32,
+    c: usize,
+    lm: usize,
+    enc: &mut RangeEncoder,
+) -> Allocation {
+    let ci = c as i32;
+    let lmi = lm as i32;
+    let mut total = total.max(0);
+    let mut skip_start = start;
+    let skip_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
+    total -= skip_rsv;
+    let mut intensity_rsv = 0;
+    let mut dual_stereo_rsv = 0;
+    if c == 2 {
+        intensity_rsv = LOG2_FRAC_TABLE[end - start];
+        if intensity_rsv > total {
+            intensity_rsv = 0;
+        } else {
+            total -= intensity_rsv;
+            dual_stereo_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
+            total -= dual_stereo_rsv;
+        }
+    }
+    let mut bits1 = [0i32; NB_EBANDS];
+    let mut bits2 = [0i32; NB_EBANDS];
+    let mut thresh = [0i32; NB_EBANDS];
+    let mut trim_offset = [0i32; NB_EBANDS];
+    for j in start..end {
+        let w = EBANDS[j + 1] - EBANDS[j];
+        thresh[j] = (ci << BITRES).max((3 * w << lmi << BITRES) >> 4);
+        trim_offset[j] = ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32)) >> 6;
+        if w << lmi == 1 {
+            trim_offset[j] -= ci << BITRES;
+        }
+    }
+    let nb_alloc = ALLOC.len() as i32;
+    let mut lo = 1;
+    let mut hi = nb_alloc - 1;
+    loop {
+        let mut done = false;
+        let mut psum = 0;
+        let mid = (lo + hi) >> 1;
+        for j in (start..end).rev() {
+            let n = EBANDS[j + 1] - EBANDS[j];
+            let mut bitsj = ci * n * (ALLOC[mid as usize][j] as i32) << lmi >> 2;
+            if bitsj > 0 {
+                bitsj = (bitsj + trim_offset[j]).max(0);
+            }
+            bitsj += offsets[j];
+            if bitsj >= thresh[j] || done {
+                done = true;
+                psum += bitsj.min(cap[j]);
+            } else if bitsj >= ci << BITRES {
+                psum += ci << BITRES;
+            }
+        }
+        if psum > total {
+            hi = mid - 1;
+        } else {
+            lo = mid + 1;
+        }
+        if lo > hi {
+            break;
+        }
+    }
+    hi = lo;
+    lo -= 1;
+    for j in start..end {
+        let n = EBANDS[j + 1] - EBANDS[j];
+        let mut bits1j = ci * n * (ALLOC[lo as usize][j] as i32) << lmi >> 2;
+        let mut bits2j = if hi >= nb_alloc { cap[j] } else { ci * n * (ALLOC[hi as usize][j] as i32) << lmi >> 2 };
+        if bits1j > 0 {
+            bits1j = (bits1j + trim_offset[j]).max(0);
+        }
+        if bits2j > 0 {
+            bits2j = (bits2j + trim_offset[j]).max(0);
+        }
+        if lo > 0 {
+            bits1j += offsets[j];
+        }
+        bits2j += offsets[j];
+        if offsets[j] > 0 {
+            skip_start = j;
+        }
+        bits2j = (bits2j - bits1j).max(0);
+        bits1[j] = bits1j;
+        bits2[j] = bits2j;
+    }
+    interp_bits2pulses(m, start, end, skip_start, &bits1, &bits2, &thresh, cap, total, skip_rsv, intensity_rsv, dual_stereo_rsv, c, lm, enc)
+}
+
+#[allow(clippy::too_many_arguments)]
+fn interp_bits2pulses(
+    m: &Mode,
+    start: usize,
+    end: usize,
+    skip_start: usize,
+    bits1: &[i32; NB_EBANDS],
+    bits2: &[i32; NB_EBANDS],
+    thresh: &[i32; NB_EBANDS],
+    cap: &[i32; NB_EBANDS],
+    mut total: i32,
+    skip_rsv: i32,
+    mut intensity_rsv: i32,
+    mut dual_stereo_rsv: i32,
+    c: usize,
+    lm: usize,
+    enc: &mut RangeEncoder,
+) -> Allocation {
+    let ci = c as i32;
+    let alloc_floor = ci << BITRES;
+    let stereo = (c > 1) as i32;
+    let log_m = (lm as i32) << BITRES;
+    let mut lo = 0;
+    let mut hi = 1 << ALLOC_STEPS;
+    for _ in 0..ALLOC_STEPS {
+        let mid = (lo + hi) >> 1;
+        let mut psum = 0;
+        let mut done = false;
+        for j in (start..end).rev() {
+            let tmp = bits1[j] + (mid * bits2[j] >> ALLOC_STEPS);
+            if tmp >= thresh[j] || done {
+                done = true;
+                psum += tmp.min(cap[j]);
+            } else if tmp >= alloc_floor {
+                psum += alloc_floor;
+            }
+        }
+        if psum > total {
+            hi = mid;
+        } else {
+            lo = mid;
+        }
+    }
+    let mut bits = [0i32; NB_EBANDS];
+    let mut psum = 0;
+    let mut done = false;
+    for j in (start..end).rev() {
+        let mut tmp = bits1[j] + (lo * bits2[j] >> ALLOC_STEPS);
+        if tmp < thresh[j] && !done {
+            tmp = if tmp >= alloc_floor { alloc_floor } else { 0 };
+        } else {
+            done = true;
+        }
+        tmp = tmp.min(cap[j]);
+        bits[j] = tmp;
+        psum += tmp;
+    }
+    let s = start;
+    let mut coded_bands = end;
+    loop {
+        let j = coded_bands - 1;
+        if j <= skip_start {
+            total += skip_rsv;
+            break;
+        }
+        let mut left = total - psum;
+        let span = EBANDS[coded_bands] - EBANDS[s];
+        let percoeff = left / span;
+        left -= span * percoeff;
+        let rem = (left - (EBANDS[j] - EBANDS[s])).max(0);
+        let band_width = EBANDS[coded_bands] - EBANDS[j];
+        let band_bits = bits[j] + percoeff * band_width + rem;
+        if band_bits >= thresh[j].max(alloc_floor + (1 << BITRES)) {
+            // Keep this band (and every band below it).
+            enc.bit_logp(true, 1);
+            break;
+        }
+        psum -= bits[j] + intensity_rsv;
+        if intensity_rsv > 0 {
+            intensity_rsv = LOG2_FRAC_TABLE[j - s];
+        }
+        psum += intensity_rsv;
+        if band_bits >= alloc_floor {
+            psum += alloc_floor;
+            bits[j] = alloc_floor;
+        } else {
+            bits[j] = 0;
+        }
+        coded_bands -= 1;
+    }
+    let intensity = if intensity_rsv > 0 {
+        // No intensity stereo: every coded band is coded in full.
+        enc.uint((coded_bands - s) as u32, (coded_bands + 1 - s) as u32);
+        coded_bands
+    } else {
+        0
+    };
+    if intensity <= s {
+        total += dual_stereo_rsv;
+        dual_stereo_rsv = 0;
+    }
+    let dual_stereo = if dual_stereo_rsv > 0 {
+        enc.bit_logp(true, 1);
+        true
+    } else {
+        false
+    };
+    let mut left = total - psum;
+    let span = EBANDS[coded_bands] - EBANDS[s];
+    let percoeff = left / span;
+    left -= span * percoeff;
+    for j in s..coded_bands {
+        bits[j] += percoeff * (EBANDS[j + 1] - EBANDS[j]);
+    }
+    for j in s..coded_bands {
+        let tmp = left.min(EBANDS[j + 1] - EBANDS[j]);
+        bits[j] += tmp;
+        left -= tmp;
+    }
+    let mut ebits = [0i32; NB_EBANDS];
+    let mut fine_priority = [0i32; NB_EBANDS];
+    let mut balance = 0;
+    for j in s..coded_bands {
+        let n0 = EBANDS[j + 1] - EBANDS[j];
+        let n = n0 << lm;
+        let bit = bits[j] + balance;
+        let mut excess;
+        if n > 1 {
+            excess = (bit - cap[j]).max(0);
+            bits[j] = bit - excess;
+            let den = ci * n + if c == 2 && n > 2 && !dual_stereo && j < intensity { 1 } else { 0 };
+            let nclogn = den * (m.log_n[j] + log_m);
+            let mut offset = (nclogn >> 1) - den * FINE_OFFSET;
+            if n == 2 {
+                offset += (den << BITRES) >> 2;
+            }
+            if bits[j] + offset < den * 2 << BITRES {
+                offset += nclogn >> 2;
+            } else if bits[j] + offset < den * 3 << BITRES {
+                offset += nclogn >> 3;
+            }
+            let mut eb = (bits[j] + offset + (den << (BITRES - 1))).max(0);
+            eb = (eb / den) >> BITRES;
+            if ci * eb > (bits[j] >> BITRES) {
+                eb = bits[j] >> stereo >> BITRES;
+            }
+            eb = eb.min(MAX_FINE_BITS);
+            ebits[j] = eb;
+            fine_priority[j] = (eb * (den << BITRES) >= bits[j] + offset) as i32;
+            bits[j] -= ci * eb << BITRES;
+        } else {
+            excess = (bit - (ci << BITRES)).max(0);
+            bits[j] = bit - excess;
+            ebits[j] = 0;
+            fine_priority[j] = 1;
+        }
+        if excess > 0 {
+            let extra_fine = (excess >> (stereo + BITRES as i32)).min(MAX_FINE_BITS - ebits[j]);
+            ebits[j] += extra_fine;
+            let extra_bits = extra_fine * ci << BITRES;
+            fine_priority[j] = (extra_bits >= excess - balance) as i32;
+            excess -= extra_bits;
+        }
+        balance = excess;
+    }
+    for j in coded_bands..end {
+        ebits[j] = bits[j] >> stereo >> BITRES;
+        bits[j] = 0;
+        fine_priority[j] = (ebits[j] < 1) as i32;
+    }
+    Allocation { coded_bands, intensity, dual_stereo, balance, pulses: bits, fine_quant: ebits, fine_priority }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn caps_match_decoder_reference() {
+        let m = Mode::new();
+        let first_rows: [u8; 42] = [
+            224, 224, 224, 224, 224, 224, 224, 224, 160, 160, 160, 160, 185, 185, 185, 178, 178, 168, 134, 61, 37, 224, 224, 224, 224, 224, 224, 224,
+            224, 240, 240, 240, 240, 207, 207, 207, 198, 198, 183, 144, 66, 40,
+        ];
+        assert_eq!(&m.caps[..42], &first_rows[..]);
+    }
+
+    #[test]
+    fn pvq_counts() {
+        assert_eq!(pvq_v(5, 1), 10);
+        assert_eq!(pvq_v(1, 7), 2);
+        assert_eq!(pvq_v(2, 9), 36);
+        assert_eq!(pvq_v(3, 2), 18);
+    }
+}
diff --git a/crates/audio/src/opus/encoder/resample.rs b/crates/audio/src/opus/encoder/resample.rs
new file mode 100644
index 000000000..9045cb86d
--- /dev/null
+++ b/crates/audio/src/opus/encoder/resample.rs
@@ -0,0 +1,131 @@
+//! 48 kHz → 8/12/16 kHz decimator feeding the SILK layer (own design).
+//!
+//! A linear-phase low-pass FIR (Kaiser-windowed sinc at 48 kHz) evaluated only at the retained
+//! output phases. Its group delay ([`delay`]) is a whole number of 48 kHz samples, chosen so
+//! that the SILK path (this filter + the decoder's internal-rate delay and resampler, RFC 6716
+//! Table 54) lands within a fraction of a sample of the CELT path's 120-sample MDCT overlap.
+
+/// Group delay of the decimator to `fs_out` in 48 kHz samples (the filter has `2 * delay + 1`
+/// taps).
+pub fn delay(fs_out: u32) -> usize {
+    if fs_out == 8_000 { 88 } else { 83 }
+}
+
+/// Zeroth-order modified Bessel function of the first kind (power series).
+fn bessel_i0(x: f64) -> f64 {
+    let mut sum = 1.0;
+    let mut term = 1.0;
+    let q = x * x / 4.0;
+    for k in 1..64 {
+        term *= q / (k * k) as f64;
+        sum += term;
+        if term < sum * 1e-17 {
+            break;
+        }
+    }
+    sum
+}
+
+/// Windowed-sinc low-pass with cutoff `fc` (Hz at 48 kHz), unit DC gain.
+fn design(fc: f64, beta: f64, delay: usize) -> Vec<f32> {
+    let wc = 2.0 * std::f64::consts::PI * fc / 48_000.0;
+    let i0b = bessel_i0(beta);
+    let mut h: Vec<f64> = (0..2 * delay + 1)
+        .map(|k| {
+            let m = k as f64 - delay as f64;
+            let sinc = if m == 0.0 { wc / std::f64::consts::PI } else { (wc * m).sin() / (std::f64::consts::PI * m) };
+            let r = m / delay as f64;
+            sinc * bessel_i0(beta * (1.0 - r * r).max(0.0).sqrt()) / i0b
+        })
+        .collect();
+    let s: f64 = h.iter().sum();
+    for v in h.iter_mut() {
+        *v /= s;
+    }
+    h.iter().map(|&v| v as f32).collect()
+}
+
+/// Decimates one channel of 48 kHz audio by 3, 4 or 6.
+#[derive(Clone)]
+pub struct Downsampler {
+    factor: usize,
+    h: Vec<f32>,
+    taps: usize,
+    /// The last `taps - 1` input samples followed by the current frame.
+    buf: Vec<f32>,
+}
+
+impl Downsampler {
+    /// `fs_out` is 8000, 12000 or 16000.
+    pub fn new(fs_out: u32) -> Self {
+        let factor = (48_000 / fs_out) as usize;
+        // Cutoff at 95 % of the output Nyquist frequency (pass band to ~88 %, stop band from ~110 %).
+        let fc = 0.95 * fs_out as f64 / 2.0;
+        let d = delay(fs_out);
+        let taps = 2 * d + 1;
+        Downsampler { factor, h: design(fc, 6.5, d), taps, buf: vec![0.0; taps - 1] }
+    }
+
+    /// Decimates `input` (a multiple of the factor long), appending to `out`. Output sample `j`
+    /// is the filtered input at frame position `factor * j`, delayed by [`delay`].
+    pub fn process(&mut self, input: &[f32], out: &mut Vec<f32>) {
+        debug_assert!(input.len().is_multiple_of(self.factor));
+        let taps = self.taps;
+        self.buf.truncate(taps - 1);
+        self.buf.extend_from_slice(input);
+        for j in 0..input.len() / self.factor {
+            let t = taps - 1 + self.factor * j;
+            let win = &self.buf[t + 1 - taps..=t];
+            // h is symmetric, so the window can be taken in forward order.
+            out.push(win.iter().zip(&self.h).map(|(a, b)| a * b).sum());
+        }
+        let n = self.buf.len();
+        self.buf.copy_within(n - (taps - 1).., 0);
+        self.buf.truncate(taps - 1);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn tone(f: f64, n: usize) -> Vec<f32> {
+        (0..n).map(|i| (2.0 * std::f64::consts::PI * f * i as f64 / 48_000.0).sin() as f32).collect()
+    }
+
+    fn rms(x: &[f32]) -> f64 {
+        (x.iter().map(|&v| (v as f64).powi(2)).sum::<f64>() / x.len() as f64).sqrt()
+    }
+
+    #[test]
+    fn passes_band_and_rejects_aliases() {
+        for &(fs, pass, stop) in &[(16_000u32, 6_000.0, 8_600.0), (12_000, 4_500.0, 6_500.0), (8_000, 3_000.0, 4_500.0)] {
+            for &(f, want_pass) in &[(pass, true), (stop, false)] {
+                let mut d = Downsampler::new(fs);
+                let x = tone(f, 9600);
+                let mut y = Vec::new();
+                for c in x.chunks(960) {
+                    d.process(c, &mut y);
+                }
+                let r = rms(&y[y.len() / 2..]) * std::f64::consts::SQRT_2;
+                if want_pass {
+                    assert!((r - 1.0).abs() < 0.02, "{fs}: {f} Hz gain {r}");
+                } else {
+                    assert!(r < 0.01, "{fs}: {f} Hz leaks {r}");
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn delay_is_exact() {
+        let mut d = Downsampler::new(16_000);
+        let mut x = vec![0f32; 960];
+        x[300] = 1.0;
+        let mut y = Vec::new();
+        d.process(&x, &mut y);
+        // The impulse at 300 shows up centred at 48 kHz time 300 + 83 = 383 (output 127.67).
+        let peak = y.iter().enumerate().max_by(|a, b| a.1.total_cmp(b.1)).map(|(i, _)| i).unwrap_or(0);
+        assert!((peak as f64 - (300.0 + delay(16_000) as f64) / 3.0).abs() < 1.0, "peak at {peak}");
+    }
+}
diff --git a/crates/audio/src/opus/encoder/silk/analysis.rs b/crates/audio/src/opus/encoder/silk/analysis.rs
new file mode 100644
index 000000000..439331076
--- /dev/null
+++ b/crates/audio/src/opus/encoder/silk/analysis.rs
@@ -0,0 +1,322 @@
+//! Encoder-side signal analysis for SILK (own design): windowed autocorrelation LPC, LPC → NLSF
+//! conversion, open-loop pitch search and LTP codebook search.
+
+use super::tables::{CB_NB_20, CB_WB_20, LTP_FILTER, LTP_PERIODICITY, LTP_TAPS_0, LTP_TAPS_1, LTP_TAPS_2};
+
+/// Short-term prediction coefficients `a` (prediction `x[n] ≈ Σ a[j] x[n-1-j]`) from the
+/// windowed segment `x`, with a Gaussian lag window and white-noise correction.
+pub fn lpc(x: &[f32], order: usize, fs_khz: usize) -> Vec<f64> {
+    let n = x.len();
+    // Asymmetric window: sin² rise over the first half, flat, cos fall over the last 1/8.
+    let rise = n / 2;
+    let fall = n / 8;
+    let w = |i: usize| -> f64 {
+        if i < rise {
+            let s = (std::f64::consts::FRAC_PI_2 * (i as f64 + 0.5) / rise as f64).sin();
+            s * s
+        } else if i >= n - fall {
+            (std::f64::consts::FRAC_PI_2 * (i + fall - n) as f64 / fall as f64 + 0.0).cos()
+        } else {
+            1.0
+        }
+    };
+    let xw: Vec<f64> = x.iter().enumerate().map(|(i, &v)| v as f64 * w(i)).collect();
+    let mut r = vec![0f64; order + 1];
+    for (k, rk) in r.iter_mut().enumerate() {
+        *rk = xw[k..].iter().zip(&xw).map(|(a, b)| a * b).sum();
+    }
+    if r[0] <= 1e-6 {
+        return vec![0.0; order];
+    }
+    // White-noise correction (-40 dB) and a 50 Hz Gaussian lag window.
+    r[0] *= 1.0 + 1e-4;
+    let f0 = 2.0 * std::f64::consts::PI * 50.0 / (fs_khz as f64 * 1000.0);
+    for (k, rk) in r.iter_mut().enumerate().skip(1) {
+        *rk *= (-0.5 * (f0 * k as f64).powi(2)).exp();
+    }
+    let mut a = levinson(&r, order);
+    // Mild bandwidth expansion keeps the NLSFs apart.
+    let mut g = 1.0;
+    for v in a.iter_mut() {
+        g *= 0.996;
+        *v *= g;
+    }
+    a
+}
+
+/// Levinson-Durbin recursion on autocorrelation `r` (predictor convention as in [`lpc`]).
+pub fn levinson(r: &[f64], order: usize) -> Vec<f64> {
+    let mut a = vec![0f64; order];
+    let mut err = r[0];
+    let mut tmp = vec![0f64; order];
+    for i in 0..order {
+        let mut acc = r[i + 1];
+        for j in 0..i {
+            acc -= a[j] * r[i - j];
+        }
+        let k = (acc / err).clamp(-0.9999, 0.9999);
+        tmp[..i].copy_from_slice(&a[..i]);
+        for j in 0..i {
+            a[j] = tmp[j] - k * tmp[i - 1 - j];
+        }
+        a[i] = k;
+        err *= 1.0 - k * k;
+        if err <= 0.0 {
+            break;
+        }
+    }
+    a
+}
+
+/// Evaluates the symmetric polynomial `p` (length `d + 1`, `d` even) as the cosine series
+/// `e^{jωd/2} P(e^{jω})`.
+fn cos_series(p: &[f64], w: f64) -> f64 {
+    let h = (p.len() - 1) / 2;
+    let mut s = p[h];
+    for k in 0..h {
+        s += 2.0 * p[k] * ((h - k) as f64 * w).cos();
+    }
+    s
+}
+
+fn roots(p: &[f64], out: &mut Vec<f64>) {
+    const GRID: usize = 1024;
+    let mut w0 = 0.0;
+    let mut f0 = cos_series(p, w0);
+    for g in 1..=GRID {
+        let w1 = std::f64::consts::PI * g as f64 / GRID as f64;
+        let f1 = cos_series(p, w1);
+        if f0 == 0.0 {
+            out.push(w0);
+        } else if f0 * f1 < 0.0 {
+            let (mut lo, mut hi, mut flo) = (w0, w1, f0);
+            for _ in 0..40 {
+                let mid = 0.5 * (lo + hi);
+                let fm = cos_series(p, mid);
+                if fm * flo <= 0.0 {
+                    hi = mid;
+                } else {
+                    lo = mid;
+                    flo = fm;
+                }
+            }
+            out.push(0.5 * (lo + hi));
+        }
+        w0 = w1;
+        f0 = f1;
+    }
+}
+
+/// LPC → normalised line spectral frequencies in radians (ascending, `order` values), or `None`
+/// when the root search fails (unstable or degenerate filter).
+pub fn a2nlsf(a: &[f64]) -> Option<Vec<f64>> {
+    let d = a.len();
+    let mut c = vec![0f64; d + 2];
+    c[0] = 1.0;
+    for k in 0..d {
+        c[k + 1] = -a[k];
+    }
+    let mut p = vec![0f64; d + 2];
+    let mut q = vec![0f64; d + 2];
+    for k in 0..d + 2 {
+        p[k] = c[k] + c[d + 1 - k];
+        q[k] = c[k] - c[d + 1 - k];
+    }
+    // Remove the trivial roots at z = -1 (P) and z = +1 (Q).
+    let mut p1 = vec![0f64; d + 1];
+    let mut q1 = vec![0f64; d + 1];
+    p1[0] = p[0];
+    q1[0] = q[0];
+    for k in 1..=d {
+        p1[k] = p[k] - p1[k - 1];
+        q1[k] = q[k] + q1[k - 1];
+    }
+    let mut r = Vec::with_capacity(d);
+    roots(&p1, &mut r);
+    roots(&q1, &mut r);
+    if r.len() != d {
+        return None;
+    }
+    r.sort_by(f64::total_cmp);
+    Some(r)
+}
+
+/// Normalised cross-correlation of `x[n]` and `x[n - lag]` over `n` in `range`.
+fn ncorr(x: &[f32], range: std::ops::Range<usize>, lag: usize) -> f64 {
+    let (mut xy, mut xx, mut yy) = (0f64, 0f64, 0f64);
+    for n in range {
+        let a = x[n] as f64;
+        let b = x[n - lag] as f64;
+        xy += a * b;
+        xx += a * a;
+        yy += b * b;
+    }
+    if xy <= 0.0 { 0.0 } else { xy / (xx * yy + 1e-9).sqrt() }
+}
+
+pub struct Pitch {
+    pub lag_index: i32,
+    pub contour: usize,
+    pub lags: [i32; 4],
+    pub score: f64,
+}
+
+/// Open-loop pitch search on `x` (history followed by the frame starting at `start`, `len`
+/// samples, four subframes) at `fs_khz`.
+pub fn pitch_search(x: &[f32], start: usize, len: usize, fs_khz: usize) -> Pitch {
+    let fs = fs_khz as i32;
+    let min_lag = 2 * fs;
+    let max_lag = 18 * fs - 1;
+    let sub = len / 4;
+    let nl = (max_lag - min_lag + 1) as usize;
+    // Whole-frame score per lag.
+    let full: Vec<f64> = (0..nl).map(|i| ncorr(x, start..start + len, min_lag as usize + i)).collect();
+    let mut best = 0usize;
+    for i in 0..nl {
+        // Slight preference for shorter lags.
+        if full[i] * (1.0 - 0.0004 * i as f64) > full[best] * (1.0 - 0.0004 * best as f64) {
+            best = i;
+        }
+    }
+    let mut lag = min_lag + best as i32;
+    // Prefer a sub-multiple when it explains the signal almost as well (octave errors).
+    for div in [4, 3, 2] {
+        let cand = (lag as f64 / div as f64).round() as i32;
+        let mut cbest = (0.0, 0);
+        for c in cand - 1..=cand + 1 {
+            if c >= min_lag && c <= max_lag {
+                let s = full[(c - min_lag) as usize];
+                if s > cbest.0 {
+                    cbest = (s, c);
+                }
+            }
+        }
+        if cbest.1 != 0 && cbest.0 > 0.9 * full[(lag - min_lag) as usize] {
+            lag = cbest.1;
+            break;
+        }
+    }
+    let score = full[(lag - min_lag) as usize];
+    // Contour: per-subframe lag offsets around the chosen lag.
+    let cb: &[[i32; 4]] = if fs_khz == 8 { &CB_NB_20 } else { &CB_WB_20 };
+    let sub_score = |k: usize, l: i32| -> f64 {
+        let l = l.clamp(min_lag, 18 * fs);
+        ncorr(x, start + k * sub..start + (k + 1) * sub, l as usize)
+    };
+    let mut best = (f64::MIN, lag, 0usize);
+    for l0 in (lag - 2).max(min_lag)..=(lag + 2).min(max_lag) {
+        for (ci, offs) in cb.iter().enumerate() {
+            let s: f64 = (0..4).map(|k| sub_score(k, l0 + offs[k])).sum::<f64>() - 0.002 * ci as f64;
+            if s > best.0 {
+                best = (s, l0, ci);
+            }
+        }
+    }
+    let (_, l0, ci) = best;
+    let mut lags = [0i32; 4];
+    for k in 0..4 {
+        lags[k] = (l0 + cb[ci][k]).clamp(min_lag, 18 * fs);
+    }
+    Pitch { lag_index: l0 - min_lag, contour: ci, lags, score }
+}
+
+/// Result of the LTP codebook search.
+pub struct Ltp {
+    pub per_index: usize,
+    pub ltp_index: [usize; 4],
+    /// Residual energy after LTP prediction / before, per subframe.
+    pub err: [f64; 4],
+    pub energy: [f64; 4],
+}
+
+fn icdf_bits(icdf: &[u8], s: usize) -> f64 {
+    let hi = if s == 0 { 256 } else { icdf[s - 1] as u32 };
+    let p = (hi - icdf[s] as u32).max(1) as f64 / 256.0;
+    -p.log2()
+}
+
+/// Searches the three LTP codebooks (RFC 6716 Tables 39–42) for the taps that best predict the
+/// residual `r` (history + frame starting at `start`) from its past at the per-subframe `lags`.
+pub fn ltp_search(r: &[f64], start: usize, sub: usize, lags: &[i32; 4]) -> Ltp {
+    let mut rr = [[0f64; 25]; 4];
+    let mut cv = [[0f64; 5]; 4];
+    let mut e = [0f64; 4];
+    for k in 0..4 {
+        let s0 = start + k * sub;
+        let lag = lags[k] as usize;
+        for n in s0..s0 + sub {
+            let t = r[n];
+            e[k] += t * t;
+            let base = n + 2 - lag;
+            for i in 0..5 {
+                let vi = r[base - i];
+                cv[k][i] += t * vi;
+                for j in 0..5 {
+                    rr[k][i * 5 + j] += vi * r[base - j];
+                }
+            }
+        }
+    }
+    let books: [&[[i32; 5]]; 3] = [&LTP_TAPS_0, &LTP_TAPS_1, &LTP_TAPS_2];
+    let mut best = (f64::MAX, 0usize, [0usize; 4], [0f64; 4]);
+    for (p, book) in books.iter().enumerate() {
+        let mut total = icdf_bits(&LTP_PERIODICITY, p) * 1e-3 * e.iter().sum::<f64>() / 4.0;
+        let mut idx = [0usize; 4];
+        let mut errs = [0f64; 4];
+        for k in 0..4 {
+            let mut bk = (f64::MAX, 0usize, 0f64);
+            for (i, taps) in book.iter().enumerate() {
+                let b: [f64; 5] = std::array::from_fn(|j| taps[j] as f64 / 128.0);
+                let mut err = e[k];
+                for a in 0..5 {
+                    err -= 2.0 * b[a] * cv[k][a];
+                    for c in 0..5 {
+                        err += b[a] * b[c] * rr[k][a * 5 + c];
+                    }
+                }
+                let cost = err + icdf_bits(LTP_FILTER[p], i) * 1e-3 * e[k];
+                if cost < bk.0 {
+                    bk = (cost, i, err.max(0.0));
+                }
+            }
+            total += bk.0;
+            idx[k] = bk.1;
+            errs[k] = bk.2;
+        }
+        if total < best.0 {
+            best = (total, p, idx, errs);
+        }
+    }
+    Ltp { per_index: best.1, ltp_index: best.2, err: best.3, energy: e }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::lpc::nlsf2a;
+    use super::*;
+
+    #[test]
+    fn nlsf_roundtrip_through_decoder_conversion() {
+        // A resonant 10th/16th-order predictor from a synthetic signal.
+        for &(order, fs) in &[(10usize, 8usize), (16, 16)] {
+            let mut st = [0f64; 4];
+            let mut seed = 1u32;
+            let x: Vec<f32> = (0..400)
+                .map(|_| {
+                    seed = seed.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
+                    let w = (seed >> 9) as f64 / (1u32 << 23) as f64 - 1.0;
+                    let y = w + 1.6 * st[0] - 0.9 * st[1] + 0.3 * st[2] - 0.2 * st[3];
+                    st = [y, st[0], st[1], st[2]];
+                    (y * 1000.0) as f32
+                })
+                .collect();
+            let a = lpc(&x, order, fs);
+            let nlsf = a2nlsf(&a).expect("roots");
+            let q15: Vec<i32> = nlsf.iter().map(|w| (w / std::f64::consts::PI * 32768.0).round() as i32).collect();
+            let a_q12 = nlsf2a(&q15);
+            for j in 0..order {
+                assert!((a_q12[j] as f64 / 4096.0 - a[j]).abs() < 0.02, "order {order} coef {j}: {} vs {}", a_q12[j] as f64 / 4096.0, a[j]);
+            }
+        }
+    }
+}
diff --git a/crates/audio/src/opus/encoder/silk/lpc.rs b/crates/audio/src/opus/encoder/silk/lpc.rs
new file mode 100644
index 000000000..e4e9ae624
--- /dev/null
+++ b/crates/audio/src/opus/encoder/silk/lpc.rs
@@ -0,0 +1,370 @@
+//! Fixed-point NLSF decoding, NLSF→LPC conversion and filter stabilisation
+//! (RFC 6716 §4.2.7.5, with the RFC 8251 §6/§7 overflow fixes).
+//!
+//! This is the decoder's normative arithmetic, mirrored from FilmCraft's first-party,
+//! spec-derived `filmcraft-opus` decoder (MIT OR Apache-2.0): the encoder must reconstruct the
+//! quantised NLSFs and LPC coefficients bit-exactly as the decoder does.
+
+use super::tables::{
+    COS_Q12, LSF_ORDER_NBMB, LSF_ORDER_WB, NLSF_CB_NBMB, NLSF_CB_WB, NLSF_MIN_SPACING_NBMB, NLSF_MIN_SPACING_WB, NLSF_PRED_NBMB, NLSF_PRED_WB,
+    NLSF_PSEL_NBMB, NLSF_PSEL_WB,
+};
+
+pub const MAX_LPC_ORDER: usize = 16;
+
+#[inline]
+pub fn smulwb(a: i32, b: i32) -> i32 {
+    ((a as i64 * (b as i16) as i64) >> 16) as i32
+}
+#[inline]
+pub fn smlawb(a: i32, b: i32, c: i32) -> i32 {
+    a.wrapping_add(smulwb(b, c))
+}
+#[inline]
+pub fn smulww(a: i32, b: i32) -> i32 {
+    ((a as i64 * b as i64) >> 16) as i32
+}
+#[inline]
+pub fn smmul(a: i32, b: i32) -> i32 {
+    ((a as i64 * b as i64) >> 32) as i32
+}
+#[inline]
+pub fn rshift_round(a: i32, s: u32) -> i32 {
+    if s == 1 { (a >> 1) + (a & 1) } else { ((a >> (s - 1)) + 1) >> 1 }
+}
+#[inline]
+pub fn rshift_round64(a: i64, s: u32) -> i64 {
+    if s == 1 { (a >> 1) + (a & 1) } else { ((a >> (s - 1)) + 1) >> 1 }
+}
+#[inline]
+pub fn sat16(a: i32) -> i32 {
+    a.clamp(-32768, 32767)
+}
+
+/// `silk_INVERSE32_varQ`: approximation of `(1 << q_res) / b32`.
+pub fn inverse32_varq(b32: i32, q_res: i32) -> i32 {
+    let b_headrm = b32.unsigned_abs().leading_zeros() as i32 - 1;
+    let b32_nrm = b32.wrapping_shl(b_headrm as u32);
+    let b32_inv = (i32::MAX >> 2) / (b32_nrm >> 16);
+    let mut result = b32_inv << 16;
+    let err_q32 = ((1i32 << 29).wrapping_sub(smulwb(b32_nrm, b32_inv))).wrapping_shl(3);
+    result = result.wrapping_add(((err_q32 as i64 * b32_inv as i64) >> 16) as i32);
+    let lshift = 61 - b_headrm - q_res;
+    if lshift <= 0 {
+        let s = (-lshift) as u32;
+        let lim_hi = i32::MAX >> s;
+        let lim_lo = i32::MIN >> s;
+        result.clamp(lim_lo, lim_hi) << s
+    } else if lshift < 32 {
+        result >> lshift
+    } else {
+        0
+    }
+}
+
+/// `silk_DIV32_varQ`: approximation of `(a32 << q_res) / b32`.
+pub fn div32_varq(a32: i32, b32: i32, q_res: i32) -> i32 {
+    let a_headrm = a32.unsigned_abs().leading_zeros() as i32 - 1;
+    let a32_nrm = a32.wrapping_shl(a_headrm as u32);
+    let b_headrm = b32.unsigned_abs().leading_zeros() as i32 - 1;
+    let b32_nrm = b32.wrapping_shl(b_headrm as u32);
+    let b32_inv = (i32::MAX >> 2) / (b32_nrm >> 16);
+    let mut result = smulwb(a32_nrm, b32_inv);
+    let a32_nrm = a32_nrm.wrapping_sub(((smmul(b32_nrm, result) as i64) << 3) as i32);
+    result = smlawb(result, a32_nrm, b32_inv);
+    let lshift = 29 + a_headrm - b_headrm - q_res;
+    if lshift < 0 {
+        let s = (-lshift) as u32;
+        let lim_hi = i32::MAX >> s;
+        let lim_lo = i32::MIN >> s;
+        result.clamp(lim_lo, lim_hi) << s
+    } else if lshift < 32 {
+        result >> lshift
+    } else {
+        0
+    }
+}
+
+pub fn sqrt_approx(x: i32) -> i32 {
+    if x <= 0 {
+        return 0;
+    }
+    let lz = x.leading_zeros() as i32;
+    let frac = (x.rotate_right((24 - lz).rem_euclid(32) as u32)) & 0x7f;
+    let mut y = if lz & 1 != 0 { 32768 } else { 46214 };
+    y >>= lz >> 1;
+    smlawb(y, y, 213 * frac)
+}
+
+/// Decodes the stage-1/stage-2 indices into stabilised NLSFs (Q15).
+pub fn nlsf_decode(indices: &[i32], wb: bool) -> [i32; MAX_LPC_ORDER] {
+    let order = if wb { 16 } else { 10 };
+    let i1 = indices[0] as usize;
+    let cb1: &[i32] = if wb { &NLSF_CB_WB[i1] } else { &NLSF_CB_NBMB[i1] };
+    let qstep = if wb { 9830 } else { 11796 };
+    // Residual dequantisation with backwards prediction.
+    let mut res_q10 = [0i32; MAX_LPC_ORDER];
+    let mut out_q10 = 0i32;
+    for i in (0..order).rev() {
+        let pred = if i + 1 < order {
+            let sel = if wb { NLSF_PSEL_WB[i1][i] } else { NLSF_PSEL_NBMB[i1][i] } as usize;
+            let w = if wb { NLSF_PRED_WB[sel][i] } else { NLSF_PRED_NBMB[sel][i] };
+            (out_q10 * w) >> 8
+        } else {
+            0
+        };
+        let mut v = indices[i + 1] << 10;
+        if v > 0 {
+            v -= 102;
+        } else if v < 0 {
+            v += 102;
+        }
+        out_q10 = smlawb(pred, v, qstep);
+        res_q10[i] = out_q10;
+    }
+    // Laroia weights.
+    let mut nlsf = [0i32; MAX_LPC_ORDER];
+    for k in 0..order {
+        let prev = if k == 0 { 0 } else { cb1[k - 1] };
+        let next = if k + 1 == order { 256 } else { cb1[k + 1] };
+        let w = (1024 / (cb1[k] - prev).max(1) + 1024 / (next - cb1[k]).max(1)).min(32767);
+        let w_q9 = sqrt_approx(w << 16);
+        let v = (cb1[k] << 7) + (res_q10[k] << 14) / w_q9.max(1);
+        nlsf[k] = v.clamp(0, 32767);
+    }
+    let dmin: &[i32] = if wb { &NLSF_MIN_SPACING_WB } else { &NLSF_MIN_SPACING_NBMB };
+    nlsf_stabilize(&mut nlsf[..order], dmin);
+    nlsf
+}
+
+pub fn nlsf_stabilize(nlsf: &mut [i32], dmin: &[i32]) {
+    let l = nlsf.len();
+    for _ in 0..20 {
+        let mut min_diff = nlsf[0] - dmin[0];
+        let mut idx = 0;
+        for i in 1..l {
+            let d = nlsf[i] - (nlsf[i - 1] + dmin[i]);
+            if d < min_diff {
+                min_diff = d;
+                idx = i;
+            }
+        }
+        let d = 32768 - (nlsf[l - 1] + dmin[l]);
+        if d < min_diff {
+            min_diff = d;
+            idx = l;
+        }
+        if min_diff >= 0 {
+            return;
+        }
+        if idx == 0 {
+            nlsf[0] = dmin[0];
+        } else if idx == l {
+            nlsf[l - 1] = 32768 - dmin[l];
+        } else {
+            let mut min_center = dmin[..idx].iter().sum::<i32>();
+            min_center += dmin[idx] >> 1;
+            let mut max_center = 32768 - dmin[idx + 1..=l].iter().sum::<i32>();
+            max_center -= dmin[idx] >> 1;
+            let c = rshift_round(nlsf[idx - 1] + nlsf[idx], 1);
+            let c = if min_center > max_center { c.clamp(max_center, min_center) } else { c.clamp(min_center, max_center) };
+            nlsf[idx - 1] = c - (dmin[idx] >> 1);
+            nlsf[idx] = nlsf[idx - 1] + dmin[idx];
+        }
+    }
+    // Fallback.
+    nlsf.sort_unstable();
+    nlsf[0] = nlsf[0].max(dmin[0]);
+    for i in 1..l {
+        nlsf[i] = nlsf[i].max(sat16(nlsf[i - 1] + dmin[i]));
+    }
+    nlsf[l - 1] = nlsf[l - 1].min(32768 - dmin[l]);
+    for i in (0..l - 1).rev() {
+        nlsf[i] = nlsf[i].min(nlsf[i + 1] - dmin[i + 1]);
+    }
+}
+
+fn bwexpander_32(ar: &mut [i32], mut chirp_q16: i32) {
+    let d = ar.len();
+    let chirp_minus_one = chirp_q16 - 65536;
+    for v in ar.iter_mut().take(d - 1) {
+        *v = smulww(chirp_q16, *v);
+        chirp_q16 += rshift_round(chirp_q16.wrapping_mul(chirp_minus_one), 16);
+    }
+    ar[d - 1] = smulww(chirp_q16, ar[d - 1]);
+}
+
+fn lpc_inverse_pred_gain(a_q12: &[i32]) -> i32 {
+    const QA: u32 = 24;
+    const A_LIMIT: i32 = 16_773_022;
+    let order = a_q12.len();
+    let mut a = [0i32; MAX_LPC_ORDER];
+    let mut dc = 0;
+    for k in 0..order {
+        dc += a_q12[k];
+        a[k] = a_q12[k] << (QA - 12);
+    }
+    if dc >= 4096 {
+        return 0;
+    }
+    let mut inv_gain: i32 = 1 << 30;
+    let mul32_frac_q31 = |x: i32, y: i32| rshift_round64(x as i64 * y as i64, 31) as i32;
+    for k in (1..order).rev() {
+        if a[k] > A_LIMIT || a[k] < -A_LIMIT {
+            return 0;
+        }
+        let rc_q31 = -(a[k] << (31 - QA));
+        let rc_mult1 = (1i32 << 30) - smmul(rc_q31, rc_q31);
+        inv_gain = smmul(inv_gain, rc_mult1) << 2;
+        if inv_gain < 107_374 {
+            return 0;
+        }
+        let mult2q = 32 - rc_mult1.unsigned_abs().leading_zeros() as i32;
+        let rc_mult2 = inverse32_varq(rc_mult1, mult2q + 30);
+        for n in 0..(k + 1) >> 1 {
+            let t1 = a[n];
+            let t2 = a[k - n - 1];
+            let v1 = rshift_round64(t1.saturating_sub(mul32_frac_q31(t2, rc_q31)) as i64 * rc_mult2 as i64, mult2q as u32);
+            if v1 > i32::MAX as i64 || v1 < i32::MIN as i64 {
+                return 0;
+            }
+            let v2 = rshift_round64(t2.saturating_sub(mul32_frac_q31(t1, rc_q31)) as i64 * rc_mult2 as i64, mult2q as u32);
+            if v2 > i32::MAX as i64 || v2 < i32::MIN as i64 {
+                return 0;
+            }
+            a[n] = v1 as i32;
+            a[k - n - 1] = v2 as i32;
+        }
+    }
+    if a[0] > A_LIMIT || a[0] < -A_LIMIT {
+        return 0;
+    }
+    let rc_q31 = -(a[0] << (31 - QA));
+    let rc_mult1 = (1i32 << 30) - smmul(rc_q31, rc_q31);
+    inv_gain = smmul(inv_gain, rc_mult1) << 2;
+    if inv_gain < 107_374 {
+        return 0;
+    }
+    inv_gain
+}
+
+/// Converts NLSFs (Q15) to stable Q12 LPC coefficients (`silk_NLSF2A`).
+pub fn nlsf2a(nlsf: &[i32]) -> [i32; MAX_LPC_ORDER] {
+    let d = nlsf.len();
+    let ordering: &[usize] = if d == 16 { &LSF_ORDER_WB } else { &LSF_ORDER_NBMB };
+    let mut c_q17 = [0i32; MAX_LPC_ORDER];
+    for k in 0..d {
+        let i = (nlsf[k] >> 8) as usize;
+        let f = nlsf[k] & 255;
+        let c0 = COS_Q12[i];
+        let c1 = COS_Q12[(i + 1).min(128)];
+        c_q17[ordering[k]] = (c0 * 256 + (c1 - c0) * f + 4) >> 3;
+    }
+    let d2 = d / 2;
+    let find_poly = |off: usize| -> [i64; 10] {
+        let mut out = [0i64; 10];
+        out[0] = 1 << 16;
+        out[1] = -(c_q17[off] as i64);
+        for k in 1..d2 {
+            let ftmp = c_q17[2 * k + off] as i64;
+            out[k + 1] = 2 * out[k - 1] - ((ftmp * out[k] + 32768) >> 16);
+            for n in (2..=k).rev() {
+                out[n] += out[n - 2] - ((ftmp * out[n - 1] + 32768) >> 16);
+            }
+            out[1] -= ftmp;
+        }
+        out
+    };
+    let p = find_poly(0);
+    let q = find_poly(1);
+    let mut a32 = [0i32; MAX_LPC_ORDER];
+    for k in 0..d2 {
+        let ptmp = p[k + 1] + p[k];
+        let qtmp = q[k + 1] - q[k];
+        a32[k] = (-qtmp - ptmp) as i32;
+        a32[d - k - 1] = (qtmp - ptmp) as i32;
+    }
+    let a32 = &mut a32[..d];
+    // Limit the dynamic range (silk_LPC_fit with QIN = 17, QOUT = 12).
+    let mut a_q12 = [0i32; MAX_LPC_ORDER];
+    let mut i = 0;
+    while i < 10 {
+        let mut maxabs = 0i32;
+        let mut idx = 0;
+        for (k, &v) in a32.iter().enumerate() {
+            let av = v.saturating_abs();
+            if av > maxabs {
+                maxabs = av;
+                idx = k;
+            }
+        }
+        let maxabs = rshift_round(maxabs, 5);
+        if maxabs > 32767 {
+            let maxabs = maxabs.min(163_838);
+            let chirp = 65470 - ((maxabs - 32767) << 14) / ((maxabs * (idx as i32 + 1)) >> 2);
+            bwexpander_32(a32, chirp);
+        } else {
+            break;
+        }
+        i += 1;
+    }
+    if i == 10 {
+        for k in 0..d {
+            a_q12[k] = sat16(rshift_round(a32[k], 5));
+            a32[k] = a_q12[k] << 5;
+        }
+    } else {
+        for k in 0..d {
+            a_q12[k] = rshift_round(a32[k], 5);
+        }
+    }
+    for i in 0..16 {
+        if lpc_inverse_pred_gain(&a_q12[..d]) == 0 {
+            bwexpander_32(a32, 65536 - (2 << i));
+            for k in 0..d {
+                a_q12[k] = rshift_round(a32[k], 5);
+            }
+        } else {
+            break;
+        }
+    }
+    a_q12
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn flat_nlsf_gives_small_lpc() {
+        // Uniformly spaced NLSFs correspond to an (almost) flat spectrum.
+        let nlsf: Vec<i32> = (1..=16).map(|k| k * 32768 / 17).collect();
+        let a = nlsf2a(&nlsf);
+        assert!(a.iter().all(|v| v.abs() < 600), "{a:?}");
+        let nlsf: Vec<i32> = (1..=10).map(|k| k * 32768 / 11).collect();
+        let a = nlsf2a(&nlsf);
+        assert!(a[..10].iter().all(|v| v.abs() < 600), "{a:?}");
+    }
+
+    #[test]
+    fn stabilize_enforces_spacing() {
+        let mut v = [100, 90, 80, 30000, 30001, 30002, 31000, 32000, 32700, 32760];
+        nlsf_stabilize(&mut v, &NLSF_MIN_SPACING_NBMB);
+        assert!(v[0] >= NLSF_MIN_SPACING_NBMB[0]);
+        for i in 1..10 {
+            assert!(v[i] - v[i - 1] >= NLSF_MIN_SPACING_NBMB[i], "{v:?}");
+        }
+        assert!(32768 - v[9] >= NLSF_MIN_SPACING_NBMB[10]);
+    }
+
+    #[test]
+    fn inverse_approximations() {
+        for &b in &[65536, 100_000, 1 << 20, 81920, 1_686_110_208] {
+            let inv = inverse32_varq(b, 47) as f64;
+            let exact = 2f64.powi(47) / b as f64;
+            assert!((inv - exact).abs() / exact < 1e-3, "{b}");
+        }
+        let q = div32_varq(65536, 131072, 16) as f64;
+        assert!((q - 32768.0).abs() < 2.0);
+    }
+}
diff --git a/crates/audio/src/opus/encoder/silk/mod.rs b/crates/audio/src/opus/encoder/silk/mod.rs
new file mode 100644
index 000000000..d82e537e0
--- /dev/null
+++ b/crates/audio/src/opus/encoder/silk/mod.rs
@@ -0,0 +1,714 @@
+//! SILK layer encoder (RFC 6716 §4.2, encoder direction), 20 ms frames at 8, 12 or 16 kHz.
+//!
+//! Each frame is analysed (VAD, open-loop pitch, windowed-autocorrelation LPC, LTP codebook
+//! search), its NLSFs are quantised, and the excitation is chosen sample by sample by running
+//! the decoder's exact fixed-point reconstruction (LTP and LPC synthesis with the dequantised
+//! Q12/Q14 coefficients, quantisation offsets and the pseudo-random sign sequence), so the
+//! encoder always holds the decoder's state and there is no drift. A noise-feedback loop
+//! shapes the coding noise with a bandwidth-expanded LPC envelope, and a per-frame search over
+//! a gain offset hits the bit budget. Stereo input is coded as mid/side with the decoder's
+//! stereo prediction (§4.2.8). No LBRR, no NLSF interpolation.
+
+pub(crate) mod analysis;
+pub(crate) mod lpc;
+mod nlsf;
+mod pulses;
+#[allow(dead_code)]
+pub(crate) mod tables;
+
+use lpc::{MAX_LPC_ORDER, div32_varq, inverse32_varq, nlsf2a, rshift_round, sat16, smlawb, smulwb, smulww};
+use tables::{
+    DELTA_GAIN, GAIN_MSB, LTP_FILTER, LTP_PERIODICITY, LTP_SCALE, LTP_TAPS_0, LTP_TAPS_1, LTP_TAPS_2, MID_ONLY, NLSF_EXT, NLSF_INTERP, NLSF_SEL_NBMB,
+    NLSF_SEL_WB, NLSF_STAGE1, NLSF_STAGE2, PITCH_CONTOUR, PITCH_HIGH, PITCH_LOW, STEREO_PRED_JOINT, STEREO_WEIGHTS_Q13, TYPE_ACTIVE, TYPE_INACTIVE,
+    UNIFORM3, UNIFORM4, UNIFORM5, UNIFORM8,
+};
+
+use crate::opus::encoder::range::RangeEncoder;
+
+const MAX_FRAME: usize = 320;
+const LTP_ORDER: usize = 5;
+/// Frame RMS (16-bit scale) below which a frame is coded as inactive (VAD off).
+const VAD_RMS: f32 = 30.0;
+/// Normalised pitch correlation above which a frame is a voicing candidate.
+const VOICING_THRESHOLD: f64 = 0.45;
+/// Minimum LTP prediction gain (energy ratio) for a frame to be coded as voiced.
+const MIN_LTP_GAIN: f64 = 1.3;
+/// Rate penalty (squared pulse units per unit magnitude) of the excitation quantiser.
+const RD_LAMBDA: f64 = 0.15;
+/// Extra gain offset (log2) for inactive frames.
+const INACTIVE_OFFSET: f64 = 1.0;
+/// Noise feedback: the coding noise is shaped by `1 / A(z/γ)` (A the short-term predictor).
+/// γ = 0 leaves it white (closed-loop DPCM, best waveform SNR at high rates), γ = 1 shapes it
+/// like the spectral envelope (open-loop residual coding, needed at low rates). γ grows with the
+/// gain offset, i.e. as the quantisation gets coarser.
+fn nf_gamma(offset: f64) -> f64 {
+    (0.75 + 0.05 * offset).clamp(0.75, 0.9)
+}
+
+/// `silk_log2lin` (decoder arithmetic).
+fn log2lin(in_log_q7: i32) -> i32 {
+    if in_log_q7 < 0 {
+        return 0;
+    }
+    if in_log_q7 >= 3967 {
+        return i32::MAX;
+    }
+    let out = 1i32 << (in_log_q7 >> 7);
+    let frac = in_log_q7 & 0x7F;
+    if in_log_q7 < 2048 {
+        out + ((out * smlawb(frac, frac * (128 - frac), -174)) >> 7)
+    } else {
+        out + (out >> 7) * smlawb(frac, frac * (128 - frac), -174)
+    }
+}
+
+fn gain_q16(index: i32) -> i32 {
+    log2lin((smulwb(0x1D1C71, index) + 2090).min(3967))
+}
+
+/// The decoder's LPC analysis filter on 16-bit samples.
+fn lpc_analysis_filter(out: &mut [i16], input: &[i16], b: &[i32], d: usize) {
+    let len = out.len();
+    for ix in d..len {
+        let mut acc: i32 = 0;
+        for j in 0..d {
+            acc = acc.wrapping_add((input[ix - 1 - j] as i32).wrapping_mul(b[j]));
+        }
+        let v = ((input[ix] as i32) << 12).wrapping_sub(acc);
+        out[ix] = sat16(rshift_round(v, 12)) as i16;
+    }
+    for v in out.iter_mut().take(d.min(len)) {
+        *v = 0;
+    }
+}
+
+/// The part of the decoder's channel state that the reconstruction depends on.
+#[derive(Clone)]
+struct DecState {
+    prev_gain_q16: i32,
+    s_lpc_q14: [i32; MAX_LPC_ORDER],
+    out_buf: [i16; MAX_FRAME],
+    last_gain_index: i32,
+}
+
+impl DecState {
+    fn new() -> Self {
+        DecState { prev_gain_q16: 65536, s_lpc_q14: [0; MAX_LPC_ORDER], out_buf: [0; MAX_FRAME], last_gain_index: 10 }
+    }
+
+    /// The decoder's reset of the side channel when it is coded again after mid-only frames.
+    fn reset_side(&mut self) {
+        self.out_buf = [0; MAX_FRAME];
+        self.s_lpc_q14 = [0; MAX_LPC_ORDER];
+        self.last_gain_index = 10;
+    }
+}
+
+/// Coded parameters of one frame (everything except gains and pulses).
+#[derive(Clone, Default)]
+struct Params {
+    vad: bool,
+    signal_type: usize,
+    quant_offset_type: usize,
+    nlsf_ix: [i32; 17],
+    a_q12: [i32; MAX_LPC_ORDER],
+    lag_index: i32,
+    contour: usize,
+    per_index: usize,
+    ltp_index: [usize; 4],
+    pitch_l: [i32; 4],
+    /// RMS (16-bit scale) of the open-loop prediction residual per subframe.
+    res_rms: [f32; 4],
+}
+
+/// Gains, seed and pulses chosen by the quantiser.
+struct Coded {
+    gain_ix: [i32; 4],
+    gains_q16: [i32; 4],
+    seed: usize,
+    pulses: Vec<i32>,
+}
+
+#[derive(Clone)]
+struct Channel {
+    fs_khz: usize,
+    len: usize,
+    sub: usize,
+    order: usize,
+    dec: DecState,
+    /// The last two frames of input (internal rate, 16-bit scale).
+    hist: Vec<f32>,
+    /// Recent output errors (decoded − input), most recent first, for noise feedback.
+    nf: [f64; MAX_LPC_ORDER],
+}
+
+impl Channel {
+    fn new(fs_khz: usize) -> Self {
+        let len = 20 * fs_khz;
+        Channel {
+            fs_khz,
+            len,
+            sub: 5 * fs_khz,
+            order: if fs_khz == 16 { 16 } else { 10 },
+            dec: DecState::new(),
+            hist: vec![0.0; 2 * len],
+            nf: [0.0; MAX_LPC_ORDER],
+        }
+    }
+
+    fn push_history(&mut self, x: &[f32]) {
+        let l = self.len;
+        self.hist.copy_within(l.., 0);
+        self.hist[l..].copy_from_slice(x);
+    }
+
+    /// Frame analysis: VAD, signal type, pitch, LPC/NLSF quantisation and LTP taps.
+    fn analyze(&self, x: &[f32]) -> Params {
+        let l = self.len;
+        let sub = self.sub;
+        let order = self.order;
+        let wb = order == 16;
+        let mut buf = self.hist.clone();
+        buf.extend_from_slice(x);
+        let start = 2 * l;
+        let rms = (x.iter().map(|v| v * v).sum::<f32>() / l as f32).sqrt();
+        let vad = rms > VAD_RMS;
+        let pitch = if vad { Some(analysis::pitch_search(&buf, start, l, self.fs_khz)) } else { None };
+        let mut voiced = pitch.as_ref().is_some_and(|p| p.score > VOICING_THRESHOLD);
+
+        let a = analysis::lpc(&buf[start - l / 4..], order, self.fs_khz);
+        let target: Vec<f64> = match analysis::a2nlsf(&a) {
+            Some(w) => w.iter().map(|v| v / std::f64::consts::PI * 32768.0).collect(),
+            None => (1..=order).map(|k| k as f64 * 32768.0 / (order + 1) as f64).collect(),
+        };
+        let quant = |signal_type: usize| {
+            let (ix, nlsf) = nlsf::quantize(&target, signal_type, wb);
+            (ix, nlsf2a(&nlsf[..order]))
+        };
+        let mut p = Params { vad, ..Default::default() };
+        let (mut ix, mut a_q12) = quant(if voiced { 2 } else { 1 });
+        // Open-loop residual with the quantised predictor.
+        let mut r = vec![0f64; buf.len()];
+        for n in order..buf.len() {
+            let mut acc = buf[n] as f64;
+            for j in 0..order {
+                acc -= a_q12[j] as f64 / 4096.0 * buf[n - 1 - j] as f64;
+            }
+            r[n] = acc;
+        }
+        if voiced && let Some(pitch) = &pitch {
+            let ltp = analysis::ltp_search(&r, start, sub, &pitch.lags);
+            let gain = ltp.energy.iter().sum::<f64>() / ltp.err.iter().sum::<f64>().max(1e-9);
+            if gain >= MIN_LTP_GAIN {
+                p.lag_index = pitch.lag_index;
+                p.contour = pitch.contour;
+                p.pitch_l = pitch.lags;
+                p.per_index = ltp.per_index;
+                p.ltp_index = ltp.ltp_index;
+            } else {
+                voiced = false;
+                (ix, a_q12) = quant(1);
+            }
+        }
+        // Gains follow the short-term residual level (the long-term predictor then only
+        // reduces the number of pulses), which keeps the noise-to-signal ratio steady.
+        for k in 0..4 {
+            let e: f64 = r[start + k * sub..start + (k + 1) * sub].iter().map(|v| v * v).sum();
+            p.res_rms[k] = (e / sub as f64).sqrt() as f32;
+        }
+        p.signal_type = if !vad {
+            0
+        } else if voiced {
+            2
+        } else {
+            1
+        };
+        p.quant_offset_type = 0;
+        p.nlsf_ix = ix;
+        p.a_q12 = a_q12;
+        p
+    }
+
+    /// Chooses gains and pulses for target `x` by running the decoder's reconstruction, and
+    /// advances the mirrored decoder state. `offset` scales the gains (log2), `floor` gives
+    /// minimum gains (Q16) per subframe. Returns the coded values and the decoded frame.
+    fn quantize(&mut self, p: &Params, x: &[f32], offset: f64, floor: Option<&[i32; 4]>, seed: usize) -> (Coded, Vec<i16>) {
+        let l = self.len;
+        let sub = self.sub;
+        let order = self.order;
+        let st = &mut self.dec;
+        let nf = &mut self.nf;
+        let off = if p.signal_type == 0 { offset + INACTIVE_OFFSET } else { offset };
+        let gamma = nf_gamma(off);
+        let mut nf_c = [0f64; MAX_LPC_ORDER];
+        let mut gpow = 1.0;
+        for j in 0..order {
+            gpow *= gamma;
+            nf_c[j] = p.a_q12[j] as f64 / 4096.0 * gpow;
+        }
+        // Gains (independent coding of the first subframe, deltas for the rest).
+        let mut gain_ix = [0i32; 4];
+        let mut gains_q16 = [0i32; 4];
+        let mut prev = st.last_gain_index;
+        for k in 0..4 {
+            let mut g = p.res_rms[k] as f64 * off.exp2();
+            if let Some(f) = floor {
+                g = g.max(f[k] as f64 / 65536.0);
+            }
+            let want = (((g * 65536.0).max(1.0).log2() * 128.0 - 2090.0) / (1_907_825.0 / 65536.0)).round().clamp(0.0, 63.0) as i32;
+            if k == 0 {
+                gain_ix[0] = want;
+                prev = want.max(prev - 16).clamp(0, 63);
+            } else {
+                let mut best = (i32::MAX, 0i32, prev);
+                for ind in 0..41 {
+                    let tmp = ind - 4;
+                    let thr = 2 * 36 - 64 + prev;
+                    let d = if tmp > thr { prev + (tmp << 1) - thr } else { prev + tmp }.clamp(0, 63);
+                    let e = (d - want).abs();
+                    if e < best.0 {
+                        best = (e, ind, d);
+                    }
+                }
+                gain_ix[k] = best.1;
+                prev = best.2;
+            }
+            gains_q16[k] = gain_q16(prev);
+        }
+        st.last_gain_index = prev;
+
+        // Analysis-by-synthesis excitation quantisation through the decoder's exact synthesis.
+        let voiced = p.signal_type == 2;
+        let offset_q10 = [[100, 240], [32, 100]][p.signal_type >> 1][p.quant_offset_type];
+        let off16 = offset_q10 << 4;
+        let mut seed_v = seed as i32;
+        let mut pulses = vec![0i32; l];
+        let mut xq = vec![0i16; l];
+        let mut s_lpc = [0i32; MAX_FRAME / 4 + MAX_LPC_ORDER];
+        s_lpc[..MAX_LPC_ORDER].copy_from_slice(&st.s_lpc_q14);
+        let mut s_ltp = [0i16; MAX_FRAME];
+        let mut s_ltp_q15 = [0i32; 2 * MAX_FRAME];
+        let ltp_mem = l;
+        let mut ltp_buf_idx = ltp_mem;
+        let a_q12 = &p.a_q12;
+        let ltp_scale_q14 = 15565;
+        for k in 0..4 {
+            let mut b_q14 = [0i32; LTP_ORDER];
+            if voiced {
+                let ix = p.ltp_index[k];
+                let taps = match p.per_index {
+                    0 => LTP_TAPS_0[ix],
+                    1 => LTP_TAPS_1[ix],
+                    _ => LTP_TAPS_2[ix],
+                };
+                for i in 0..LTP_ORDER {
+                    b_q14[i] = taps[i] << 7;
+                }
+            }
+            let gain_q10 = gains_q16[k] >> 6;
+            let mut inv_gain_q31 = inverse32_varq(gains_q16[k], 47);
+            let gain_adj_q16 = if gains_q16[k] != st.prev_gain_q16 {
+                let g = div32_varq(st.prev_gain_q16, gains_q16[k], 16);
+                for v in s_lpc[..MAX_LPC_ORDER].iter_mut() {
+                    *v = smulww(g, *v);
+                }
+                g
+            } else {
+                1 << 16
+            };
+            st.prev_gain_q16 = gains_q16[k];
+            let lag = p.pitch_l[k];
+            if voiced {
+                let lag_u = lag as usize;
+                if k == 0 {
+                    let start_idx = (ltp_mem as isize - lag as isize - order as isize - (LTP_ORDER / 2) as isize).max(0) as usize;
+                    lpc_analysis_filter(&mut s_ltp[start_idx..ltp_mem], &st.out_buf[start_idx..ltp_mem], a_q12, order);
+                    inv_gain_q31 = smulwb(inv_gain_q31, ltp_scale_q14) << 2;
+                    for i in 0..(lag_u + LTP_ORDER / 2).min(ltp_mem) {
+                        s_ltp_q15[ltp_buf_idx - i - 1] = smulwb(inv_gain_q31, s_ltp[ltp_mem - i - 1] as i32);
+                    }
+                } else if gain_adj_q16 != 1 << 16 {
+                    for i in 0..(lag_u + LTP_ORDER / 2).min(ltp_buf_idx) {
+                        let q = ltp_buf_idx - i - 1;
+                        s_ltp_q15[q] = smulww(gain_adj_q16, s_ltp_q15[q]);
+                    }
+                }
+            }
+            let inv_g = 16_777_216.0 / gain_q10.max(1) as f64;
+            for i in 0..sub {
+                let n = k * sub + i;
+                seed_v = seed_v.wrapping_mul(196_314_165).wrapping_add(907_633_515);
+                let ltp_q14 = if voiced {
+                    let base = ltp_buf_idx as isize - lag as isize + (LTP_ORDER / 2) as isize;
+                    let g = |o: isize| -> i32 { if base - o >= 0 { s_ltp_q15[(base - o) as usize] } else { 0 } };
+                    let mut pred = 2i32;
+                    for o in 0..LTP_ORDER {
+                        pred = smlawb(pred, g(o as isize), b_q14[o]);
+                    }
+                    pred << 1
+                } else {
+                    0
+                };
+                let mut lpc_pred = (order >> 1) as i32;
+                for j in 0..order {
+                    lpc_pred = smlawb(lpc_pred, s_lpc[MAX_LPC_ORDER + i - 1 - j], a_q12[j]);
+                }
+                let lpc_q14 = lpc_pred.saturating_mul(16);
+                // Target excitation (Q14) for this sample.
+                let fb: f64 = (0..order).map(|j| nf_c[j] * nf[j]).sum();
+                let tgt = (x[n] as f64 + fb).clamp(-32768.0, 32767.0) * inv_g - lpc_q14 as f64 - ltp_q14 as f64;
+                let sgn = if seed_v < 0 { -1.0 } else { 1.0 };
+                let u = sgn * tgt;
+                let pf = (u - off16 as f64) / 16384.0;
+                let p0 = if pf > 0.0 { (pf + 0.078_125).round() } else { (pf - 0.078_125).round() } as i32;
+                let level = |q: i32| -> i32 {
+                    let mut e = q << 14;
+                    if e > 0 {
+                        e -= 80 << 4;
+                    } else if e < 0 {
+                        e += 80 << 4;
+                    }
+                    e + off16
+                };
+                let mut best = (f64::MAX, 0i32);
+                for q in [p0 - 1, p0, p0 + 1, 0] {
+                    let q = q.clamp(-pulses::MAX_PULSE, pulses::MAX_PULSE);
+                    let d = (level(q) as f64 - u) / 16384.0;
+                    let cost = d * d + RD_LAMBDA * q.abs() as f64;
+                    if cost < best.0 {
+                        best = (cost, q);
+                    }
+                }
+                let q = best.1;
+                pulses[n] = q;
+                let mut e = level(q);
+                if seed_v < 0 {
+                    e = -e;
+                }
+                seed_v = seed_v.wrapping_add(q);
+                let res = e.wrapping_add(ltp_q14);
+                if voiced {
+                    s_ltp_q15[ltp_buf_idx] = res << 1;
+                    ltp_buf_idx += 1;
+                }
+                let v = res.saturating_add(lpc_q14);
+                s_lpc[MAX_LPC_ORDER + i] = v;
+                xq[n] = sat16(rshift_round(smulww(v, gain_q10), 8)) as i16;
+                nf.copy_within(0..MAX_LPC_ORDER - 1, 1);
+                nf[0] = xq[n] as f64 - x[n] as f64;
+            }
+            s_lpc.copy_within(sub..sub + MAX_LPC_ORDER, 0);
+        }
+        st.s_lpc_q14.copy_from_slice(&s_lpc[..MAX_LPC_ORDER]);
+        st.out_buf[..l].copy_from_slice(&xq);
+        (Coded { gain_ix, gains_q16, seed, pulses }, xq)
+    }
+
+    /// Writes the frame's indices and pulses (`decode_indices` + `decode_pulses` order, coded
+    /// independently).
+    fn write(&self, enc: &mut RangeEncoder, p: &Params, c: &Coded) {
+        let ix = p.signal_type * 2 + p.quant_offset_type;
+        if p.vad {
+            enc.icdf(ix - 2, &TYPE_ACTIVE, 8);
+        } else {
+            enc.icdf(ix, &TYPE_INACTIVE, 8);
+        }
+        enc.icdf((c.gain_ix[0] >> 3) as usize, GAIN_MSB[p.signal_type], 8);
+        enc.icdf((c.gain_ix[0] & 7) as usize, &UNIFORM8, 8);
+        for k in 1..4 {
+            enc.icdf(c.gain_ix[k] as usize, &DELTA_GAIN, 8);
+        }
+        let wb = self.order == 16;
+        let i1 = p.nlsf_ix[0] as usize;
+        enc.icdf(i1, NLSF_STAGE1[(p.signal_type >> 1) + if wb { 2 } else { 0 }], 8);
+        for i in 0..self.order {
+            let cb = if wb { 8 + NLSF_SEL_WB[i1][i] as usize } else { NLSF_SEL_NBMB[i1][i] as usize };
+            let v = p.nlsf_ix[i + 1] + 4;
+            if v <= 0 {
+                enc.icdf(0, NLSF_STAGE2[cb], 8);
+                enc.icdf((-v) as usize, &NLSF_EXT, 8);
+            } else if v >= 8 {
+                enc.icdf(8, NLSF_STAGE2[cb], 8);
+                enc.icdf((v - 8) as usize, &NLSF_EXT, 8);
+            } else {
+                enc.icdf(v as usize, NLSF_STAGE2[cb], 8);
+            }
+        }
+        // No NLSF interpolation.
+        enc.icdf(4, &NLSF_INTERP, 8);
+        if p.signal_type == 2 {
+            let half = (self.fs_khz >> 1) as i32;
+            enc.icdf((p.lag_index / half) as usize, &PITCH_HIGH, 8);
+            let low = match self.fs_khz {
+                8 => PITCH_LOW[0],
+                12 => PITCH_LOW[1],
+                _ => PITCH_LOW[2],
+            };
+            enc.icdf((p.lag_index % half) as usize, low, 8);
+            enc.icdf(p.contour, if self.fs_khz == 8 { PITCH_CONTOUR[1] } else { PITCH_CONTOUR[3] }, 8);
+            enc.icdf(p.per_index, &LTP_PERIODICITY, 8);
+            for k in 0..4 {
+                enc.icdf(p.ltp_index[k], LTP_FILTER[p.per_index], 8);
+            }
+            // LTP scaling index 0 (15565 in Q14), matching `quantize`.
+            enc.icdf(0, &LTP_SCALE, 8);
+        }
+        enc.icdf(c.seed, &UNIFORM4, 8);
+        pulses::encode(enc, &c.pulses, p.signal_type, p.quant_offset_type);
+    }
+}
+
+/// Quantises a stereo prediction weight (Q13) to the decoder's grid (§4.2.7.1): returns the
+/// (UNIFORM3, UNIFORM5, joint) indices and the reconstructed value.
+fn quant_pred(w: f64) -> ([usize; 3], i32) {
+    let mut best = (f64::MAX, [0usize; 3], 0i32);
+    for i in 0..15 {
+        let low = STEREO_WEIGHTS_Q13[i];
+        let step = smulwb(STEREO_WEIGHTS_Q13[i + 1] - low, 6554);
+        for j in 0..5 {
+            let v = low + step * (2 * j as i32 + 1);
+            let e = (v as f64 - w).abs();
+            if e < best.0 {
+                best = (e, [i % 3, j, i / 3], v);
+            }
+        }
+    }
+    (best.1, best.2)
+}
+
+/// Per-frame preparation shared by every rate-loop trial.
+struct Prep {
+    x: [Vec<f32>; 2],
+    params: [Params; 2],
+    mid_only: bool,
+    pred_ix: [[usize; 3]; 2],
+    pred_q13: [i32; 2],
+}
+
+/// SILK encoder for one mono or stereo (mid/side) stream.
+#[derive(Clone)]
+pub struct SilkEncoder {
+    fs_khz: usize,
+    channels: usize,
+    ch: [Channel; 2],
+    pred_prev_q13: [i32; 2],
+    prev_mid_only: bool,
+    /// Last mid sample of the previous frame (for the stereo predictor's low-pass).
+    prev_mid: f32,
+    frame: usize,
+    /// Gain offset chosen for the previous frame (search starting point).
+    pub last_offset: f64,
+}
+
+impl SilkEncoder {
+    pub fn new(fs_khz: usize, channels: usize) -> Self {
+        SilkEncoder {
+            fs_khz,
+            channels,
+            ch: [Channel::new(fs_khz), Channel::new(fs_khz)],
+            pred_prev_q13: [0; 2],
+            prev_mid_only: false,
+            prev_mid: 0.0,
+            frame: 0,
+            last_offset: 1.0,
+        }
+    }
+
+    /// Samples per channel of one 20 ms frame at the internal rate.
+    pub fn frame_len(&self) -> usize {
+        20 * self.fs_khz
+    }
+
+    fn prepare(&self, input: &[Vec<f32>]) -> Prep {
+        let l = self.frame_len();
+        if self.channels == 1 {
+            let x = input[0].clone();
+            let p = self.ch[0].analyze(&x);
+            return Prep { x: [x, vec![0.0; l]], params: [p, Params::default()], mid_only: true, pred_ix: [[0; 3]; 2], pred_q13: [0; 2] };
+        }
+        let mid: Vec<f32> = (0..l).map(|i| 0.5 * (input[0][i] + input[1][i])).collect();
+        let side: Vec<f32> = (0..l).map(|i| 0.5 * (input[0][i] - input[1][i])).collect();
+        let lp = |j: usize| -> f64 {
+            let a = if j == 0 { self.prev_mid } else { mid[j - 1] };
+            let c = if j + 1 < l { mid[j + 1] } else { mid[l - 1] };
+            (a as f64 + 2.0 * mid[j] as f64 + c as f64) / 4.0
+        };
+        // Least-squares prediction of the side from the low-passed mid and the mid.
+        let (mut r00, mut r01, mut r11, mut c0, mut c1, mut ss, mut mm) = (0f64, 0f64, 0f64, 0f64, 0f64, 0f64, 0f64);
+        for j in 0..l {
+            let (a, b, s) = (lp(j), mid[j] as f64, side[j] as f64);
+            r00 += a * a;
+            r01 += a * b;
+            r11 += b * b;
+            c0 += a * s;
+            c1 += b * s;
+            ss += s * s;
+            mm += b * b;
+        }
+        // Ridge regularisation: the low-passed mid and the mid are nearly collinear.
+        let lam = 0.02 * 0.5 * (r00 + r11) + 1e-9;
+        let (a00, a11) = (r00 + lam, r11 + lam);
+        let det = a00 * a11 - r01 * r01;
+        let (p0, p1) = ((c0 * a11 - c1 * r01) / det, (c1 * a00 - c0 * r01) / det);
+        let lim = 13732.0;
+        let quant = |p0: f64, p1: f64| {
+            let (ix0, q0) = quant_pred(((p0 + p1) * 8192.0).clamp(-lim, lim));
+            let (ix1, q1) = quant_pred((p1 * 8192.0).clamp(-lim, lim));
+            ([ix0, ix1], [q0 - q1, q1])
+        };
+        // Side residual with the decoder's interpolated predictor.
+        let fs = self.fs_khz as i32;
+        let denom_q16 = (1 << 16) / (8 * fs);
+        let interp = 8 * self.fs_khz;
+        let residual = |pred_q13: [i32; 2]| -> Vec<f32> {
+            let d0 = rshift_round((pred_q13[0] - self.pred_prev_q13[0]) as i16 as i32 * denom_q16 as i16 as i32, 16);
+            let d1 = rshift_round((pred_q13[1] - self.pred_prev_q13[1]) as i16 as i32 * denom_q16 as i16 as i32, 16);
+            let (mut pp0, mut pp1) = (self.pred_prev_q13[0] + d0, self.pred_prev_q13[1] + d1);
+            (0..l)
+                .map(|j| {
+                    if j + 1 < interp {
+                        pp0 += d0;
+                        pp1 += d1;
+                    } else {
+                        pp0 = pred_q13[0];
+                        pp1 = pred_q13[1];
+                    }
+                    (side[j] as f64 - (pp0 as f64 * lp(j) + pp1 as f64 * mid[j] as f64) / 8192.0) as f32
+                })
+                .collect()
+        };
+        let energy = |v: &[f32]| -> f64 { v.iter().map(|&x| (x as f64).powi(2)).sum() };
+        let (mut pred_ix, mut pred_q13) = quant(p0, p1);
+        let mut res = residual(pred_q13);
+        let mut res_e = energy(&res);
+        // Never predict worse than not predicting at all.
+        if res_e > ss {
+            (pred_ix, pred_q13) = quant(0.0, 0.0);
+            res = residual(pred_q13);
+            res_e = energy(&res);
+        }
+        let res_rms = (res_e / l as f64).sqrt();
+        let mid_rms = (mm / l as f64).sqrt();
+        let mid_only = res_rms < 0.01 * mid_rms + 1.0;
+        let pm = self.ch[0].analyze(&mid);
+        let ps = if mid_only { Params::default() } else { self.ch[1].analyze(&res) };
+        Prep { x: [mid, res], params: [pm, ps], mid_only, pred_ix, pred_q13 }
+    }
+
+    /// Codes one frame into `enc` with gain offset `offset`.
+    fn code(&mut self, prep: &Prep, offset: f64, enc: &mut RangeEncoder) {
+        let stereo = self.channels == 2;
+        let side_vad = stereo && !prep.mid_only && prep.params[1].vad;
+        enc.bit_logp(prep.params[0].vad, 1);
+        enc.bit_logp(false, 1);
+        if stereo {
+            enc.bit_logp(side_vad, 1);
+            enc.bit_logp(false, 1);
+            let [a, b] = prep.pred_ix;
+            enc.icdf(5 * a[2] + b[2], &STEREO_PRED_JOINT, 8);
+            enc.icdf(a[0], &UNIFORM3, 8);
+            enc.icdf(a[1], &UNIFORM5, 8);
+            enc.icdf(b[0], &UNIFORM3, 8);
+            enc.icdf(b[1], &UNIFORM5, 8);
+            if !side_vad {
+                enc.icdf(prep.mid_only as usize, &MID_ONLY, 8);
+            }
+        }
+        let seed = self.frame & 3;
+        let (cm, _) = self.ch[0].quantize(&prep.params[0], &prep.x[0], offset, None, seed);
+        self.ch[0].write(enc, &prep.params[0], &cm);
+        if stereo {
+            if !prep.mid_only {
+                if self.prev_mid_only {
+                    self.ch[1].dec.reset_side();
+                }
+                let (cs, _) = self.ch[1].quantize(&prep.params[1], &prep.x[1], offset, Some(&cm.gains_q16), seed);
+                self.ch[1].write(enc, &prep.params[1], &cs);
+            }
+            self.pred_prev_q13 = prep.pred_q13;
+            self.prev_mid_only = prep.mid_only;
+        }
+    }
+
+    /// Encodes one 20 ms frame (`input`: one internal-rate, 16-bit-scale vector per channel)
+    /// into `enc`, aiming at `target_bits` total and never exceeding `max_bits`.
+    pub fn encode(&mut self, input: &[Vec<f32>], target_bits: f64, max_bits: i32, enc: &mut RangeEncoder) {
+        let prep = self.prepare(input);
+        let start_bits = enc.tell();
+        let trial = |s: &Self, o: f64| -> i32 {
+            let mut t = s.clone();
+            let mut e = enc.clone();
+            t.code(&prep, o, &mut e);
+            e.tell() - start_bits
+        };
+        // Bisection on the gain offset: the smallest offset (finest quantisation) within budget.
+        let target = target_bits.min(max_bits as f64);
+        // Bits are not strictly monotonic in the offset (very coarse quantisation feeds large
+        // errors back), so walk an integer grid from the previous frame's offset to find a
+        // bracket [infeasible, feasible], then bisect inside it.
+        const MIN_O: f64 = -3.0;
+        const MAX_O: f64 = 6.0;
+        let mut best_any = (i32::MAX, MAX_O);
+        let mut probe = |o: f64| -> bool {
+            let b = trial(self, o);
+            if b < best_any.0 {
+                best_any = (b, o);
+            }
+            b as f64 <= target
+        };
+        let g0 = self.last_offset.round().clamp(MIN_O, MAX_O);
+        let mut bracket = None;
+        if probe(g0) {
+            let mut hi = g0;
+            loop {
+                if hi - 1.0 < MIN_O {
+                    bracket = Some((None, hi));
+                    break;
+                }
+                if probe(hi - 1.0) {
+                    hi -= 1.0;
+                } else {
+                    bracket = Some((Some(hi - 1.0), hi));
+                    break;
+                }
+            }
+        } else {
+            let mut lo = g0;
+            while lo + 1.0 <= MAX_O {
+                if probe(lo + 1.0) {
+                    bracket = Some((Some(lo), lo + 1.0));
+                    break;
+                }
+                lo += 1.0;
+            }
+        }
+        let mut o = match bracket {
+            Some((Some(mut lo), mut hi)) => {
+                for _ in 0..4 {
+                    let m = 0.5 * (lo + hi);
+                    if probe(m) {
+                        hi = m;
+                    } else {
+                        lo = m;
+                    }
+                }
+                hi
+            }
+            Some((None, hi)) => hi,
+            None => best_any.1,
+        };
+        // Hard limit (hybrid packets must leave room for CELT).
+        while trial(self, o) > max_bits && o < 12.0 {
+            o += 1.0;
+        }
+        self.last_offset = o;
+        self.code(&prep, o, enc);
+        for ch in 0..self.channels {
+            self.ch[ch].push_history(&prep.x[ch]);
+        }
+        if self.channels == 2 {
+            self.prev_mid = prep.x[0][self.frame_len() - 1];
+        }
+        self.frame += 1;
+    }
+}
diff --git a/crates/audio/src/opus/encoder/silk/nlsf.rs b/crates/audio/src/opus/encoder/silk/nlsf.rs
new file mode 100644
index 000000000..59fca68cb
--- /dev/null
+++ b/crates/audio/src/opus/encoder/silk/nlsf.rs
@@ -0,0 +1,131 @@
+//! NLSF quantisation (encoder side of RFC 6716 §4.2.7.5): stage-1 vector codebook preselection
+//! and a backwards-predictive stage-2 scalar quantiser that reproduces the decoder's residual
+//! dequantisation exactly. The search strategy is our own.
+
+use super::lpc::{MAX_LPC_ORDER, nlsf_decode, smlawb, sqrt_approx};
+use super::tables::{
+    NLSF_CB_NBMB, NLSF_CB_WB, NLSF_EXT, NLSF_PRED_NBMB, NLSF_PRED_WB, NLSF_PSEL_NBMB, NLSF_PSEL_WB, NLSF_SEL_NBMB, NLSF_SEL_WB, NLSF_STAGE1,
+    NLSF_STAGE2,
+};
+
+/// Number of stage-1 candidates refined with stage 2.
+const SURVIVORS: usize = 8;
+/// Rate weight (weighted squared Q15 error per bit).
+const LAMBDA: f64 = 60.0;
+
+fn icdf_bits(icdf: &[u8], s: usize) -> f64 {
+    let hi = if s == 0 { 256 } else { icdf[s - 1] as u32 };
+    let p = (hi - icdf[s] as u32).max(1) as f64 / 256.0;
+    -p.log2()
+}
+
+/// Bits of a stage-2 index `q` (-10..=10) with stage-2 table `tab`.
+fn stage2_bits(tab: &[u8], q: i32) -> f64 {
+    let v = q + 4;
+    if v <= 0 {
+        icdf_bits(tab, 0) + icdf_bits(&NLSF_EXT, (-v) as usize)
+    } else if v >= 8 {
+        icdf_bits(tab, 8) + icdf_bits(&NLSF_EXT, (v - 8) as usize)
+    } else {
+        icdf_bits(tab, v as usize)
+    }
+}
+
+/// Quantises target NLSFs (`target`, Q15 as f64, ascending) and returns the 1 + order indices
+/// in the decoder's layout (`[stage1, stage2...]`) together with the reconstructed NLSFs.
+pub fn quantize(target: &[f64], signal_type: usize, wb: bool) -> ([i32; 17], [i32; MAX_LPC_ORDER]) {
+    let order = target.len();
+    // Laroia-style weights.
+    let w: Vec<f64> = (0..order)
+        .map(|k| {
+            let prev = if k == 0 { 0.0 } else { target[k - 1] };
+            let next = if k + 1 == order { 32768.0 } else { target[k + 1] };
+            1.0 / (target[k] - prev).max(50.0) + 1.0 / (next - target[k]).max(50.0)
+        })
+        .collect();
+    let s1_tab = NLSF_STAGE1[(signal_type >> 1) + if wb { 2 } else { 0 }];
+    let n_cb = 32;
+    let mut cands: Vec<(f64, usize)> = (0..n_cb)
+        .map(|i1| {
+            let cb: &[i32] = if wb { &NLSF_CB_WB[i1] } else { &NLSF_CB_NBMB[i1] };
+            let d: f64 = (0..order).map(|k| w[k] * ((cb[k] << 7) as f64 - target[k]).powi(2)).sum();
+            (d + LAMBDA * icdf_bits(s1_tab, i1), i1)
+        })
+        .collect();
+    cands.sort_by(|a, b| a.0.total_cmp(&b.0));
+    let qstep = if wb { 9830 } else { 11796 };
+    let mut best = (f64::MAX, [0i32; 17], [0i32; MAX_LPC_ORDER]);
+    for &(_, i1) in cands.iter().take(SURVIVORS) {
+        let cb1: &[i32] = if wb { &NLSF_CB_WB[i1] } else { &NLSF_CB_NBMB[i1] };
+        let mut ix = [0i32; 17];
+        ix[0] = i1 as i32;
+        let mut bits = icdf_bits(s1_tab, i1);
+        // Exact decoder weights per coefficient.
+        let w_q9: Vec<i32> = (0..order)
+            .map(|k| {
+                let prev = if k == 0 { 0 } else { cb1[k - 1] };
+                let next = if k + 1 == order { 256 } else { cb1[k + 1] };
+                let ww = (1024 / (cb1[k] - prev).max(1) + 1024 / (next - cb1[k]).max(1)).min(32767);
+                sqrt_approx(ww << 16).max(1)
+            })
+            .collect();
+        let mut out_q10 = 0i32;
+        for i in (0..order).rev() {
+            let pred = if i + 1 < order {
+                let sel = if wb { NLSF_PSEL_WB[i1][i] } else { NLSF_PSEL_NBMB[i1][i] } as usize;
+                let wp = if wb { NLSF_PRED_WB[sel][i] } else { NLSF_PRED_NBMB[sel][i] };
+                (out_q10 * wp) >> 8
+            } else {
+                0
+            };
+            let cb = if wb { 8 + NLSF_SEL_WB[i1][i] as usize } else { NLSF_SEL_NBMB[i1][i] as usize };
+            let tab = NLSF_STAGE2[cb];
+            let want_q10 = (target[i] - (cb1[i] << 7) as f64) * w_q9[i] as f64 / 16384.0;
+            let step = qstep as f64 * 1024.0 / 65536.0;
+            let q0 = ((want_q10 - pred as f64) / step).round() as i32;
+            let mut bq = (f64::MAX, 0i32, 0i32);
+            for q in (q0 - 1).max(-10)..=(q0 + 1).min(10) {
+                let mut v = q << 10;
+                if v > 0 {
+                    v -= 102;
+                } else if v < 0 {
+                    v += 102;
+                }
+                let o = smlawb(pred, v, qstep);
+                let nl = (cb1[i] << 7) as f64 + ((o << 14) / w_q9[i]) as f64;
+                let cost = w[i] * (nl - target[i]).powi(2) + LAMBDA * stage2_bits(tab, q);
+                if cost < bq.0 {
+                    bq = (cost, q, o);
+                }
+            }
+            ix[i + 1] = bq.1;
+            out_q10 = bq.2;
+            bits += stage2_bits(tab, bq.1);
+        }
+        let nlsf = nlsf_decode(&ix, wb);
+        let d: f64 = (0..order).map(|k| w[k] * (nlsf[k] as f64 - target[k]).powi(2)).sum();
+        let cost = d + LAMBDA * bits;
+        if cost < best.0 {
+            best = (cost, ix, nlsf);
+        }
+    }
+    (best.1, best.2)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn quantised_nlsfs_track_the_target() {
+        for wb in [false, true] {
+            let order = if wb { 16 } else { 10 };
+            // A smooth, plausible NLSF vector.
+            let target: Vec<f64> = (0..order).map(|k| 32768.0 * (k as f64 + 0.8 + 0.3 * (k as f64).sin()) / (order as f64 + 1.0)).collect();
+            let (ix, nlsf) = quantize(&target, 1, wb);
+            assert!(ix[1..=order].iter().all(|v| (-10..=10).contains(v)));
+            let max_err = (0..order).map(|k| (nlsf[k] as f64 - target[k]).abs()).fold(0.0, f64::max);
+            assert!(max_err < 1200.0, "wb={wb} max err {max_err}: {:?} vs {target:?}", &nlsf[..order]);
+        }
+    }
+}
diff --git a/crates/audio/src/opus/encoder/silk/pulses.rs b/crates/audio/src/opus/encoder/silk/pulses.rs
new file mode 100644
index 000000000..7ec4fa6bf
--- /dev/null
+++ b/crates/audio/src/opus/encoder/silk/pulses.rs
@@ -0,0 +1,113 @@
+//! Excitation coding (encoder side of RFC 6716 §4.2.7.8): rate level, per-block pulse counts
+//! with LSB escapes, the recursive shell code, LSBs and signs, written in exactly the order the
+//! decoder reads them.
+
+use super::tables::{EXC_LSB, EXC_SIGN, PULSE_COUNT, RATE_LEVEL, SHELL_2, SHELL_4, SHELL_8, SHELL_16};
+use crate::opus::encoder::range::RangeEncoder;
+
+/// Largest pulse magnitude the quantiser produces (keeps every 16-sample block codable).
+pub const MAX_PULSE: i32 = 500;
+
+pub fn icdf_bits(icdf: &[u8], s: usize) -> f32 {
+    let hi = if s == 0 { 256 } else { icdf[s - 1] as u32 };
+    let p = (hi - icdf[s] as u32).max(1) as f32 / 256.0;
+    -p.log2()
+}
+
+fn count_table(nls: usize) -> &'static [u8] {
+    if nls == 10 { PULSE_COUNT[10] } else { PULSE_COUNT[9] }
+}
+
+fn shell(enc: &mut RangeEncoder, v: &[i32], count: i32) {
+    let n = v.len();
+    if n == 1 || count == 0 {
+        return;
+    }
+    let tab = match n {
+        16 => SHELL_16[(count - 1) as usize],
+        8 => SHELL_8[(count - 1) as usize],
+        4 => SHELL_4[(count - 1) as usize],
+        _ => SHELL_2[(count - 1) as usize],
+    };
+    let (a, b) = v.split_at(n / 2);
+    let left: i32 = a.iter().sum();
+    enc.icdf(left as usize, tab, 8);
+    shell(enc, a, left);
+    shell(enc, b, count - left);
+}
+
+/// Codes the frame's pulses (`len` a multiple of 16).
+pub fn encode(enc: &mut RangeEncoder, pulses: &[i32], signal_type: usize, quant_offset_type: usize) {
+    let nblk = pulses.len() / 16;
+    let mut nls = vec![0usize; nblk];
+    let mut sums = vec![0i32; nblk];
+    let mut hi = vec![0i32; pulses.len()];
+    for b in 0..nblk {
+        let blk = &pulses[b * 16..(b + 1) * 16];
+        let mut s = 0usize;
+        loop {
+            let sum: i32 = blk.iter().map(|p| p.abs() >> s).sum();
+            if sum <= 16 || s == 10 {
+                sums[b] = sum.min(16);
+                break;
+            }
+            s += 1;
+        }
+        nls[b] = s;
+        for (h, p) in hi[b * 16..(b + 1) * 16].iter_mut().zip(blk) {
+            *h = p.abs() >> s;
+        }
+    }
+    // Rate level with the cheapest pulse-count symbols.
+    let rl_tab = RATE_LEVEL[signal_type >> 1];
+    let mut best = (f32::MAX, 0usize);
+    for rl in 0..9 {
+        let mut bits = icdf_bits(rl_tab, rl);
+        for b in 0..nblk {
+            bits += if nls[b] == 0 { icdf_bits(PULSE_COUNT[rl], sums[b] as usize) } else { icdf_bits(PULSE_COUNT[rl], 17) };
+        }
+        if bits < best.0 {
+            best = (bits, rl);
+        }
+    }
+    let rl = best.1;
+    enc.icdf(rl, rl_tab, 8);
+    for b in 0..nblk {
+        if nls[b] == 0 {
+            enc.icdf(sums[b] as usize, PULSE_COUNT[rl], 8);
+        } else {
+            enc.icdf(17, PULSE_COUNT[rl], 8);
+            for j in 1..nls[b] {
+                enc.icdf(17, count_table(j), 8);
+            }
+            enc.icdf(sums[b] as usize, count_table(nls[b]), 8);
+        }
+    }
+    for b in 0..nblk {
+        if sums[b] > 0 {
+            shell(enc, &hi[b * 16..(b + 1) * 16], sums[b]);
+        }
+    }
+    for b in 0..nblk {
+        if nls[b] > 0 {
+            for p in &pulses[b * 16..(b + 1) * 16] {
+                let a = p.abs();
+                for j in (0..nls[b]).rev() {
+                    enc.icdf(((a >> j) & 1) as usize, &EXC_LSB, 8);
+                }
+            }
+        }
+    }
+    let base = 7 * (quant_offset_type + (signal_type << 1));
+    for b in 0..nblk {
+        let p = sums[b] | ((nls[b] as i32) << 5);
+        if p > 0 {
+            let tab = EXC_SIGN[base + ((p & 0x1F) as usize).min(6)];
+            for &q in &pulses[b * 16..(b + 1) * 16] {
+                if q != 0 {
+                    enc.icdf((q > 0) as usize, tab, 8);
+                }
+            }
+        }
+    }
+}
diff --git a/crates/audio/src/opus/encoder/silk/tables.rs b/crates/audio/src/opus/encoder/silk/tables.rs
new file mode 100644
index 000000000..a4789a414
--- /dev/null
+++ b/crates/audio/src/opus/encoder/silk/tables.rs
@@ -0,0 +1,543 @@
+//! SILK probability tables and codebooks, transcribed from RFC 6716 §4.2 (Tables 4–53).
+//!
+//! PDFs are written as in the RFC (`{...}/256`) and converted at compile time to the inverse-CDF
+//! form consumed by the range coder.
+//!
+//! Copied from FilmCraft's first-party, spec-derived `filmcraft-opus` decoder (MIT OR
+//! Apache-2.0) so encoder and decoder share exactly the same values.
+
+/// Converts a PDF (summing to 256) into an inverse CDF (`256 - cdf[i+1]`).
+pub const fn icdf<const N: usize>(pdf: &[u8; N]) -> [u8; N] {
+    let mut out = [0u8; N];
+    let mut acc: u32 = 0;
+    let mut i = 0;
+    while i < N {
+        acc += pdf[i] as u32;
+        out[i] = (256 - acc) as u8;
+        i += 1;
+    }
+    out
+}
+
+pub const STEREO_PRED_JOINT: [u8; 25] = icdf(&[7, 2, 1, 1, 1, 10, 24, 8, 1, 1, 3, 23, 92, 23, 3, 1, 1, 8, 24, 10, 1, 1, 1, 2, 7]);
+pub const UNIFORM3: [u8; 3] = icdf(&[85, 86, 85]);
+pub const UNIFORM5: [u8; 5] = icdf(&[51, 51, 52, 51, 51]);
+pub const STEREO_WEIGHTS_Q13: [i32; 16] = [-13732, -10050, -8266, -7526, -6500, -5000, -2950, -820, 820, 2950, 5000, 6500, 7526, 8266, 10050, 13732];
+pub const MID_ONLY: [u8; 2] = icdf(&[192, 64]);
+pub const TYPE_INACTIVE: [u8; 2] = icdf(&[26, 230]);
+pub const TYPE_ACTIVE: [u8; 4] = icdf(&[24, 74, 148, 10]);
+pub const GAIN_MSB: [&[u8]; 3] =
+    [&icdf::<8>(&[32, 112, 68, 29, 12, 1, 1, 1]), &icdf::<8>(&[2, 17, 45, 60, 62, 47, 19, 4]), &icdf::<8>(&[1, 3, 26, 71, 94, 50, 9, 2])];
+pub const UNIFORM8: [u8; 8] = icdf(&[32, 32, 32, 32, 32, 32, 32, 32]);
+pub const DELTA_GAIN: [u8; 41] =
+    icdf(&[6, 5, 11, 31, 132, 21, 8, 4, 3, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]);
+pub const NLSF_STAGE1: [&[u8]; 4] = [
+    &icdf::<32>(&[44, 34, 30, 19, 21, 12, 11, 3, 3, 2, 16, 2, 2, 1, 5, 2, 1, 3, 3, 1, 1, 2, 2, 2, 3, 1, 9, 9, 2, 7, 2, 1]),
+    &icdf::<32>(&[1, 10, 1, 8, 3, 8, 8, 14, 13, 14, 1, 14, 12, 13, 11, 11, 12, 11, 10, 10, 11, 8, 9, 8, 7, 8, 1, 1, 6, 1, 6, 5]),
+    &icdf::<32>(&[31, 21, 3, 17, 1, 8, 17, 4, 1, 18, 16, 4, 2, 3, 1, 10, 1, 3, 16, 11, 16, 2, 2, 3, 2, 11, 1, 4, 9, 8, 7, 3]),
+    &icdf::<32>(&[1, 4, 16, 5, 18, 11, 5, 14, 15, 1, 3, 12, 13, 14, 14, 6, 14, 12, 2, 6, 1, 12, 12, 11, 10, 3, 10, 5, 1, 1, 1, 3]),
+];
+pub const NLSF_STAGE2: [&[u8]; 16] = [
+    &icdf::<9>(&[1, 1, 1, 15, 224, 11, 1, 1, 1]),
+    &icdf::<9>(&[1, 1, 2, 34, 183, 32, 1, 1, 1]),
+    &icdf::<9>(&[1, 1, 4, 42, 149, 55, 2, 1, 1]),
+    &icdf::<9>(&[1, 1, 8, 52, 123, 61, 8, 1, 1]),
+    &icdf::<9>(&[1, 3, 16, 53, 101, 74, 6, 1, 1]),
+    &icdf::<9>(&[1, 3, 17, 55, 90, 73, 15, 1, 1]),
+    &icdf::<9>(&[1, 7, 24, 53, 74, 67, 26, 3, 1]),
+    &icdf::<9>(&[1, 1, 18, 63, 78, 58, 30, 6, 1]),
+    &icdf::<9>(&[1, 1, 1, 9, 232, 9, 1, 1, 1]),
+    &icdf::<9>(&[1, 1, 2, 28, 186, 35, 1, 1, 1]),
+    &icdf::<9>(&[1, 1, 3, 42, 152, 53, 2, 1, 1]),
+    &icdf::<9>(&[1, 1, 10, 49, 126, 65, 2, 1, 1]),
+    &icdf::<9>(&[1, 4, 19, 48, 100, 77, 5, 1, 1]),
+    &icdf::<9>(&[1, 1, 14, 54, 100, 72, 12, 1, 1]),
+    &icdf::<9>(&[1, 1, 15, 61, 87, 61, 25, 4, 1]),
+    &icdf::<9>(&[1, 7, 21, 50, 77, 81, 17, 1, 1]),
+];
+pub const NLSF_SEL_NBMB: [[u8; 10]; 32] = [
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [1, 3, 1, 2, 2, 1, 2, 1, 1, 1],
+    [2, 1, 1, 1, 1, 1, 1, 1, 1, 1],
+    [1, 2, 2, 2, 2, 1, 2, 1, 1, 1],
+    [2, 3, 3, 3, 3, 2, 2, 2, 2, 2],
+    [0, 5, 3, 3, 2, 2, 2, 2, 1, 1],
+    [0, 2, 2, 2, 2, 2, 2, 2, 2, 1],
+    [2, 3, 6, 4, 4, 4, 5, 4, 5, 5],
+    [2, 4, 5, 5, 4, 5, 4, 6, 4, 4],
+    [2, 4, 4, 7, 4, 5, 4, 5, 5, 4],
+    [4, 3, 3, 3, 2, 3, 2, 2, 2, 2],
+    [1, 5, 5, 6, 4, 5, 4, 5, 5, 5],
+    [2, 7, 4, 6, 5, 5, 5, 5, 5, 5],
+    [2, 7, 5, 5, 5, 5, 5, 6, 5, 4],
+    [3, 3, 5, 4, 4, 5, 4, 5, 4, 4],
+    [2, 3, 3, 5, 5, 4, 4, 4, 4, 4],
+    [2, 4, 4, 6, 4, 5, 4, 5, 5, 5],
+    [2, 5, 4, 6, 5, 5, 5, 4, 5, 4],
+    [2, 7, 4, 5, 4, 5, 4, 5, 5, 5],
+    [2, 5, 4, 6, 7, 6, 5, 6, 5, 4],
+    [3, 6, 7, 4, 6, 5, 5, 6, 4, 5],
+    [2, 7, 6, 4, 4, 4, 5, 4, 5, 5],
+    [4, 5, 5, 4, 6, 6, 5, 6, 5, 4],
+    [2, 5, 5, 6, 5, 6, 4, 6, 4, 4],
+    [4, 5, 5, 5, 3, 7, 4, 5, 5, 4],
+    [2, 3, 4, 5, 5, 6, 4, 5, 5, 4],
+    [2, 3, 2, 3, 3, 4, 2, 3, 3, 3],
+    [1, 1, 2, 2, 2, 2, 2, 3, 2, 2],
+    [4, 5, 5, 6, 6, 6, 5, 6, 4, 5],
+    [3, 5, 5, 4, 4, 4, 4, 3, 3, 2],
+    [2, 5, 3, 7, 5, 5, 4, 4, 5, 4],
+    [4, 4, 5, 4, 5, 6, 5, 6, 5, 4],
+];
+pub const NLSF_SEL_WB: [[u8; 16]; 32] = [
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [2, 3, 3, 3, 3, 3, 2, 2, 2, 2, 2, 1, 1, 1, 0, 3],
+    [2, 5, 5, 3, 7, 4, 4, 5, 2, 5, 4, 5, 5, 4, 3, 3],
+    [0, 2, 1, 2, 2, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 1],
+    [0, 6, 5, 4, 6, 4, 7, 5, 4, 4, 4, 5, 5, 4, 4, 3],
+    [0, 3, 5, 5, 4, 3, 3, 5, 3, 3, 3, 3, 3, 3, 2, 4],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 2, 6, 3, 7, 2, 5, 3, 4, 5, 5, 4, 3, 3, 2, 3],
+    [0, 6, 2, 6, 6, 4, 5, 4, 6, 5, 4, 4, 5, 3, 3, 3],
+    [2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
+    [2, 2, 3, 4, 5, 3, 3, 3, 3, 3, 3, 3, 2, 2, 1, 3],
+    [2, 2, 3, 3, 4, 3, 3, 3, 3, 3, 3, 3, 3, 2, 1, 3],
+    [3, 4, 4, 4, 6, 4, 4, 5, 3, 5, 4, 4, 5, 4, 3, 4],
+    [0, 6, 4, 5, 4, 7, 5, 2, 6, 5, 7, 4, 4, 3, 5, 3],
+    [0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1, 0],
+    [1, 6, 5, 7, 5, 4, 5, 3, 4, 5, 4, 4, 4, 3, 3, 4],
+    [1, 3, 3, 4, 4, 3, 3, 5, 2, 3, 3, 5, 5, 5, 3, 4],
+    [2, 3, 3, 2, 2, 2, 3, 2, 1, 2, 1, 2, 1, 1, 1, 4],
+    [0, 2, 3, 5, 3, 3, 2, 2, 2, 1, 1, 0, 0, 0, 0, 0],
+    [3, 4, 3, 5, 3, 3, 2, 2, 1, 1, 1, 1, 1, 2, 2, 4],
+    [2, 6, 3, 7, 7, 4, 5, 4, 5, 3, 5, 3, 3, 2, 3, 3],
+    [2, 3, 5, 6, 6, 3, 5, 3, 4, 4, 3, 3, 3, 3, 2, 4],
+    [1, 3, 3, 4, 4, 4, 4, 3, 5, 5, 5, 3, 1, 1, 1, 1],
+    [2, 5, 3, 6, 6, 4, 7, 4, 4, 5, 3, 4, 4, 3, 3, 3],
+    [0, 6, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 6, 6, 3, 5, 2, 5, 5, 3, 4, 4, 7, 7, 4, 4, 4],
+    [3, 3, 7, 3, 5, 4, 3, 3, 3, 2, 2, 3, 3, 3, 2, 3],
+    [0, 0, 1, 0, 0, 0, 2, 1, 2, 1, 1, 2, 2, 2, 1, 1],
+    [0, 3, 2, 5, 3, 3, 2, 3, 2, 1, 0, 0, 1, 0, 0, 1],
+    [3, 5, 5, 4, 7, 5, 3, 3, 2, 3, 2, 2, 1, 0, 1, 0],
+    [2, 3, 5, 3, 4, 3, 3, 3, 2, 1, 2, 6, 4, 0, 0, 0],
+];
+pub const NLSF_EXT: [u8; 7] = icdf(&[156, 60, 24, 9, 4, 2, 1]);
+pub const NLSF_PRED_NBMB: [[i32; 9]; 2] = [[179, 138, 140, 148, 151, 149, 153, 151, 163], [116, 67, 82, 59, 92, 72, 100, 89, 92]];
+pub const NLSF_PRED_WB: [[i32; 15]; 2] = [
+    [175, 148, 160, 176, 178, 173, 174, 164, 177, 174, 196, 182, 198, 192, 182],
+    [68, 62, 66, 60, 72, 117, 85, 90, 118, 136, 151, 142, 160, 142, 155],
+];
+pub const NLSF_PSEL_NBMB: [[u8; 9]; 32] = [
+    [0, 1, 0, 0, 0, 0, 0, 0, 0],
+    [1, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [1, 1, 1, 0, 0, 0, 0, 1, 0],
+    [0, 1, 0, 0, 0, 0, 0, 0, 0],
+    [0, 1, 0, 0, 0, 0, 0, 0, 0],
+    [1, 0, 1, 1, 0, 0, 0, 1, 0],
+    [0, 1, 1, 0, 0, 1, 1, 0, 0],
+    [0, 0, 1, 1, 0, 1, 0, 1, 1],
+    [0, 0, 1, 1, 0, 0, 1, 1, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 1, 0, 1, 1, 1, 1, 1, 0],
+    [0, 1, 0, 1, 1, 1, 1, 1, 0],
+    [0, 1, 1, 1, 1, 1, 1, 1, 0],
+    [1, 0, 1, 1, 0, 1, 1, 1, 1],
+    [0, 1, 1, 1, 1, 1, 0, 1, 0],
+    [0, 0, 1, 1, 0, 1, 0, 1, 0],
+    [0, 0, 1, 1, 1, 0, 1, 1, 1],
+    [0, 1, 1, 0, 0, 1, 1, 1, 0],
+    [0, 0, 0, 1, 1, 1, 0, 1, 0],
+    [0, 1, 1, 0, 0, 1, 0, 1, 0],
+    [0, 1, 1, 0, 0, 0, 1, 1, 0],
+    [0, 0, 0, 0, 0, 1, 1, 1, 1],
+    [0, 0, 1, 1, 0, 0, 0, 1, 1],
+    [0, 0, 0, 1, 0, 1, 1, 1, 1],
+    [0, 1, 1, 1, 1, 1, 1, 1, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 1, 0, 1, 1, 0, 1, 0],
+    [1, 0, 0, 1, 0, 0, 0, 0, 0],
+    [0, 0, 0, 1, 1, 0, 1, 0, 1],
+    [1, 0, 1, 1, 0, 1, 1, 1, 1],
+];
+pub const NLSF_PSEL_WB: [[u8; 15]; 32] = [
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 1, 0, 0, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0],
+    [0, 1, 1, 0, 1, 0, 1, 1, 0, 1, 1, 1, 1, 1, 0],
+    [0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0],
+    [0, 1, 1, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1, 0, 1],
+    [0, 1, 0, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
+    [0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 0, 1, 0, 0],
+    [0, 0, 1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 0],
+    [0, 0, 0, 0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 0, 0],
+    [0, 1, 0, 0, 0, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1],
+    [0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0],
+    [0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 0, 0],
+    [0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 1, 0, 1, 0, 1, 1, 0, 1, 0, 1, 0, 1, 1, 0],
+    [0, 0, 1, 1, 1, 1, 0, 1, 1, 0, 0, 1, 1, 0, 0],
+    [0, 1, 1, 0, 1, 0, 1, 0, 1, 0, 0, 0, 0, 1, 0],
+    [0, 0, 0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
+    [0, 1, 1, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1, 1, 1],
+    [0, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1, 0, 1, 1, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
+    [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0],
+    [0, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0],
+];
+pub const NLSF_CB_NBMB: [[i32; 10]; 32] = [
+    [12, 35, 60, 83, 108, 132, 157, 180, 206, 228],
+    [15, 32, 55, 77, 101, 125, 151, 175, 201, 225],
+    [19, 42, 66, 89, 114, 137, 162, 184, 209, 230],
+    [12, 25, 50, 72, 97, 120, 147, 172, 200, 223],
+    [26, 44, 69, 90, 114, 135, 159, 180, 205, 225],
+    [13, 22, 53, 80, 106, 130, 156, 180, 205, 228],
+    [15, 25, 44, 64, 90, 115, 142, 168, 196, 222],
+    [19, 24, 62, 82, 100, 120, 145, 168, 190, 214],
+    [22, 31, 50, 79, 103, 120, 151, 170, 203, 227],
+    [21, 29, 45, 65, 106, 124, 150, 171, 196, 224],
+    [30, 49, 75, 97, 121, 142, 165, 186, 209, 229],
+    [19, 25, 52, 70, 93, 116, 143, 166, 192, 219],
+    [26, 34, 62, 75, 97, 118, 145, 167, 194, 217],
+    [25, 33, 56, 70, 91, 113, 143, 165, 196, 223],
+    [21, 34, 51, 72, 97, 117, 145, 171, 196, 222],
+    [20, 29, 50, 67, 90, 117, 144, 168, 197, 221],
+    [22, 31, 48, 66, 95, 117, 146, 168, 196, 222],
+    [24, 33, 51, 77, 116, 134, 158, 180, 200, 224],
+    [21, 28, 70, 87, 106, 124, 149, 170, 194, 217],
+    [26, 33, 53, 64, 83, 117, 152, 173, 204, 225],
+    [27, 34, 65, 95, 108, 129, 155, 174, 210, 225],
+    [20, 26, 72, 99, 113, 131, 154, 176, 200, 219],
+    [34, 43, 61, 78, 93, 114, 155, 177, 205, 229],
+    [23, 29, 54, 97, 124, 138, 163, 179, 209, 229],
+    [30, 38, 56, 89, 118, 129, 158, 178, 200, 231],
+    [21, 29, 49, 63, 85, 111, 142, 163, 193, 222],
+    [27, 48, 77, 103, 133, 158, 179, 196, 215, 232],
+    [29, 47, 74, 99, 124, 151, 176, 198, 220, 237],
+    [33, 42, 61, 76, 93, 121, 155, 174, 207, 225],
+    [29, 53, 87, 112, 136, 154, 170, 188, 208, 227],
+    [24, 30, 52, 84, 131, 150, 166, 186, 203, 229],
+    [37, 48, 64, 84, 104, 118, 156, 177, 201, 230],
+];
+pub const NLSF_CB_WB: [[i32; 16]; 32] = [
+    [7, 23, 38, 54, 69, 85, 100, 116, 131, 147, 162, 178, 193, 208, 223, 239],
+    [13, 25, 41, 55, 69, 83, 98, 112, 127, 142, 157, 171, 187, 203, 220, 236],
+    [15, 21, 34, 51, 61, 78, 92, 106, 126, 136, 152, 167, 185, 205, 225, 240],
+    [10, 21, 36, 50, 63, 79, 95, 110, 126, 141, 157, 173, 189, 205, 221, 237],
+    [17, 20, 37, 51, 59, 78, 89, 107, 123, 134, 150, 164, 184, 205, 224, 240],
+    [10, 15, 32, 51, 67, 81, 96, 112, 129, 142, 158, 173, 189, 204, 220, 236],
+    [8, 21, 37, 51, 65, 79, 98, 113, 126, 138, 155, 168, 179, 192, 209, 218],
+    [12, 15, 34, 55, 63, 78, 87, 108, 118, 131, 148, 167, 185, 203, 219, 236],
+    [16, 19, 32, 36, 56, 79, 91, 108, 118, 136, 154, 171, 186, 204, 220, 237],
+    [11, 28, 43, 58, 74, 89, 105, 120, 135, 150, 165, 180, 196, 211, 226, 241],
+    [6, 16, 33, 46, 60, 75, 92, 107, 123, 137, 156, 169, 185, 199, 214, 225],
+    [11, 19, 30, 44, 57, 74, 89, 105, 121, 135, 152, 169, 186, 202, 218, 234],
+    [12, 19, 29, 46, 57, 71, 88, 100, 120, 132, 148, 165, 182, 199, 216, 233],
+    [17, 23, 35, 46, 56, 77, 92, 106, 123, 134, 152, 167, 185, 204, 222, 237],
+    [14, 17, 45, 53, 63, 75, 89, 107, 115, 132, 151, 171, 188, 206, 221, 240],
+    [9, 16, 29, 40, 56, 71, 88, 103, 119, 137, 154, 171, 189, 205, 222, 237],
+    [16, 19, 36, 48, 57, 76, 87, 105, 118, 132, 150, 167, 185, 202, 218, 236],
+    [12, 17, 29, 54, 71, 81, 94, 104, 126, 136, 149, 164, 182, 201, 221, 237],
+    [15, 28, 47, 62, 79, 97, 115, 129, 142, 155, 168, 180, 194, 208, 223, 238],
+    [8, 14, 30, 45, 62, 78, 94, 111, 127, 143, 159, 175, 192, 207, 223, 239],
+    [17, 30, 49, 62, 79, 92, 107, 119, 132, 145, 160, 174, 190, 204, 220, 235],
+    [14, 19, 36, 45, 61, 76, 91, 108, 121, 138, 154, 172, 189, 205, 222, 238],
+    [12, 18, 31, 45, 60, 76, 91, 107, 123, 138, 154, 171, 187, 204, 221, 236],
+    [13, 17, 31, 43, 53, 70, 83, 103, 114, 131, 149, 167, 185, 203, 220, 237],
+    [17, 22, 35, 42, 58, 78, 93, 110, 125, 139, 155, 170, 188, 206, 224, 240],
+    [8, 15, 34, 50, 67, 83, 99, 115, 131, 146, 162, 178, 193, 209, 224, 239],
+    [13, 16, 41, 66, 73, 86, 95, 111, 128, 137, 150, 163, 183, 206, 225, 241],
+    [17, 25, 37, 52, 63, 75, 92, 102, 119, 132, 144, 160, 175, 191, 212, 231],
+    [19, 31, 49, 65, 83, 100, 117, 133, 147, 161, 174, 187, 200, 213, 227, 242],
+    [18, 31, 52, 68, 88, 103, 117, 126, 138, 149, 163, 177, 192, 207, 223, 239],
+    [16, 29, 47, 61, 76, 90, 106, 119, 133, 147, 161, 176, 193, 209, 224, 240],
+    [15, 21, 35, 50, 61, 73, 86, 97, 110, 119, 129, 141, 175, 198, 218, 237],
+];
+pub const NLSF_MIN_SPACING_NBMB: [i32; 11] = [250, 3, 6, 3, 3, 3, 4, 3, 3, 3, 461];
+pub const NLSF_MIN_SPACING_WB: [i32; 17] = [100, 3, 40, 3, 3, 3, 5, 14, 14, 10, 11, 3, 8, 9, 7, 3, 347];
+pub const NLSF_INTERP: [u8; 5] = icdf(&[13, 22, 29, 11, 181]);
+pub const LSF_ORDER_NBMB: [usize; 10] = [0, 9, 6, 3, 4, 5, 8, 1, 2, 7];
+pub const LSF_ORDER_WB: [usize; 16] = [0, 15, 8, 7, 4, 11, 12, 3, 2, 13, 10, 5, 6, 9, 14, 1];
+pub const COS_Q12: [i32; 129] = [
+    4096, 4095, 4091, 4085, 4076, 4065, 4052, 4036, 4017, 3997, 3973, 3948, 3920, 3889, 3857, 3822, 3784, 3745, 3703, 3659, 3613, 3564, 3513, 3461,
+    3406, 3349, 3290, 3229, 3166, 3102, 3035, 2967, 2896, 2824, 2751, 2676, 2599, 2520, 2440, 2359, 2276, 2191, 2106, 2019, 1931, 1842, 1751, 1660,
+    1568, 1474, 1380, 1285, 1189, 1093, 995, 897, 799, 700, 601, 501, 401, 301, 201, 101, 0, -101, -201, -301, -401, -501, -601, -700, -799, -897,
+    -995, -1093, -1189, -1285, -1380, -1474, -1568, -1660, -1751, -1842, -1931, -2019, -2106, -2191, -2276, -2359, -2440, -2520, -2599, -2676, -2751,
+    -2824, -2896, -2967, -3035, -3102, -3166, -3229, -3290, -3349, -3406, -3461, -3513, -3564, -3613, -3659, -3703, -3745, -3784, -3822, -3857,
+    -3889, -3920, -3948, -3973, -3997, -4017, -4036, -4052, -4065, -4076, -4085, -4091, -4095, -4096,
+];
+pub const PITCH_HIGH: [u8; 32] = icdf(&[3, 3, 6, 11, 21, 30, 32, 19, 11, 10, 12, 13, 13, 12, 11, 9, 8, 7, 6, 4, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1]);
+pub const PITCH_LOW: [&[u8]; 3] =
+    [&icdf::<4>(&[64, 64, 64, 64]), &icdf::<6>(&[43, 42, 43, 43, 42, 43]), &icdf::<8>(&[32, 32, 32, 32, 32, 32, 32, 32])];
+pub const PITCH_DELTA: [u8; 21] = icdf(&[46, 2, 2, 3, 4, 6, 10, 15, 26, 38, 30, 22, 15, 10, 7, 6, 4, 4, 2, 2, 2]);
+pub const PITCH_CONTOUR: [&[u8]; 4] = [
+    &icdf::<3>(&[143, 50, 63]),
+    &icdf::<11>(&[68, 12, 21, 17, 19, 22, 30, 24, 17, 16, 10]),
+    &icdf::<12>(&[91, 46, 39, 19, 14, 12, 8, 7, 6, 5, 5, 4]),
+    &icdf::<34>(&[33, 22, 18, 16, 15, 14, 14, 13, 13, 10, 9, 9, 8, 6, 6, 6, 5, 4, 4, 4, 3, 3, 3, 2, 2, 2, 2, 2, 2, 2, 1, 1, 1, 1]),
+];
+pub const CB_NB_10: [[i32; 2]; 3] = [[0, 0], [1, 0], [0, 1]];
+pub const CB_NB_20: [[i32; 4]; 11] = [
+    [0, 0, 0, 0],
+    [2, 1, 0, -1],
+    [-1, 0, 1, 2],
+    [-1, 0, 0, 1],
+    [-1, 0, 0, 0],
+    [0, 0, 0, 1],
+    [0, 0, 1, 1],
+    [1, 1, 0, 0],
+    [1, 0, 0, 0],
+    [0, 0, 0, -1],
+    [1, 0, 0, -1],
+];
+pub const CB_WB_10: [[i32; 2]; 12] = [[0, 0], [0, 1], [1, 0], [-1, 1], [1, -1], [-1, 2], [2, -1], [-2, 2], [2, -2], [-2, 3], [3, -2], [-3, 3]];
+pub const CB_WB_20: [[i32; 4]; 34] = [
+    [0, 0, 0, 0],
+    [0, 0, 1, 1],
+    [1, 1, 0, 0],
+    [-1, 0, 0, 0],
+    [0, 0, 0, 1],
+    [1, 0, 0, 0],
+    [-1, 0, 0, 1],
+    [0, 0, 0, -1],
+    [-1, 0, 1, 2],
+    [1, 0, 0, -1],
+    [-2, -1, 1, 2],
+    [2, 1, 0, -1],
+    [-2, 0, 0, 2],
+    [-2, 0, 1, 3],
+    [2, 1, -1, -2],
+    [-3, -1, 1, 3],
+    [2, 0, 0, -2],
+    [3, 1, 0, -2],
+    [-3, -1, 2, 4],
+    [-4, -1, 1, 4],
+    [3, 1, -1, -3],
+    [-4, -1, 2, 5],
+    [4, 2, -1, -3],
+    [4, 1, -1, -4],
+    [-5, -1, 2, 6],
+    [5, 2, -1, -4],
+    [-6, -2, 2, 6],
+    [-5, -2, 2, 5],
+    [6, 2, -1, -5],
+    [-7, -2, 3, 8],
+    [6, 2, -2, -6],
+    [5, 2, -2, -5],
+    [8, 3, -2, -7],
+    [-9, -3, 3, 9],
+];
+pub const LTP_PERIODICITY: [u8; 3] = icdf(&[77, 80, 99]);
+pub const LTP_FILTER: [&[u8]; 3] = [
+    &icdf::<8>(&[185, 15, 13, 13, 9, 9, 6, 6]),
+    &icdf::<16>(&[57, 34, 21, 20, 15, 13, 12, 13, 10, 10, 9, 10, 9, 8, 7, 8]),
+    &icdf::<32>(&[15, 16, 14, 12, 12, 12, 11, 11, 11, 10, 9, 9, 9, 9, 8, 8, 8, 8, 7, 7, 6, 6, 5, 4, 5, 4, 4, 4, 3, 4, 3, 2]),
+];
+pub const LTP_TAPS_0: [[i32; 5]; 8] = [
+    [4, 6, 24, 7, 5],
+    [0, 0, 2, 0, 0],
+    [12, 28, 41, 13, -4],
+    [-9, 15, 42, 25, 14],
+    [1, -2, 62, 41, -9],
+    [-10, 37, 65, -4, 3],
+    [-6, 4, 66, 7, -8],
+    [16, 14, 38, -3, 33],
+];
+pub const LTP_TAPS_1: [[i32; 5]; 16] = [
+    [13, 22, 39, 23, 12],
+    [-1, 36, 64, 27, -6],
+    [-7, 10, 55, 43, 17],
+    [1, 1, 8, 1, 1],
+    [6, -11, 74, 53, -9],
+    [-12, 55, 76, -12, 8],
+    [-3, 3, 93, 27, -4],
+    [26, 39, 59, 3, -8],
+    [2, 0, 77, 11, 9],
+    [-8, 22, 44, -6, 7],
+    [40, 9, 26, 3, 9],
+    [-7, 20, 101, -7, 4],
+    [3, -8, 42, 26, 0],
+    [-15, 33, 68, 2, 23],
+    [-2, 55, 46, -2, 15],
+    [3, -1, 21, 16, 41],
+];
+pub const LTP_TAPS_2: [[i32; 5]; 32] = [
+    [-6, 27, 61, 39, 5],
+    [-11, 42, 88, 4, 1],
+    [-2, 60, 65, 6, -4],
+    [-1, -5, 73, 56, 1],
+    [-9, 19, 94, 29, -9],
+    [0, 12, 99, 6, 4],
+    [8, -19, 102, 46, -13],
+    [3, 2, 13, 3, 2],
+    [9, -21, 84, 72, -18],
+    [-11, 46, 104, -22, 8],
+    [18, 38, 48, 23, 0],
+    [-16, 70, 83, -21, 11],
+    [5, -11, 117, 22, -8],
+    [-6, 23, 117, -12, 3],
+    [3, -8, 95, 28, 4],
+    [-10, 15, 77, 60, -15],
+    [-1, 4, 124, 2, -4],
+    [3, 38, 84, 24, -25],
+    [2, 13, 42, 13, 31],
+    [21, -4, 56, 46, -1],
+    [-1, 35, 79, -13, 19],
+    [-7, 65, 88, -9, -14],
+    [20, 4, 81, 49, -29],
+    [20, 0, 75, 3, -17],
+    [5, -9, 44, 92, -8],
+    [1, -3, 22, 69, 31],
+    [-6, 95, 41, -12, 5],
+    [39, 67, 16, -4, 1],
+    [0, -6, 120, 55, -36],
+    [-13, 44, 122, 4, -24],
+    [81, 5, 11, 3, 7],
+    [2, 0, 9, 10, 88],
+];
+pub const LTP_SCALE: [u8; 3] = icdf(&[128, 64, 64]);
+pub const UNIFORM4: [u8; 4] = icdf(&[64, 64, 64, 64]);
+pub const RATE_LEVEL: [&[u8]; 2] = [&icdf::<9>(&[15, 51, 12, 46, 45, 13, 33, 27, 14]), &icdf::<9>(&[33, 30, 36, 17, 34, 49, 18, 21, 18])];
+pub const PULSE_COUNT: [&[u8]; 11] = [
+    &icdf::<18>(&[131, 74, 25, 8, 3, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]),
+    &icdf::<18>(&[58, 93, 60, 23, 7, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]),
+    &icdf::<18>(&[43, 51, 46, 33, 24, 16, 11, 8, 6, 3, 3, 3, 2, 1, 1, 2, 1, 2]),
+    &icdf::<18>(&[17, 52, 71, 57, 31, 12, 5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]),
+    &icdf::<18>(&[6, 21, 41, 53, 49, 35, 21, 11, 6, 3, 2, 2, 1, 1, 1, 1, 1, 1]),
+    &icdf::<18>(&[7, 14, 22, 28, 29, 28, 25, 20, 17, 13, 11, 9, 7, 5, 4, 4, 3, 10]),
+    &icdf::<18>(&[2, 5, 14, 29, 42, 46, 41, 31, 19, 11, 6, 3, 2, 1, 1, 1, 1, 1]),
+    &icdf::<18>(&[1, 2, 4, 10, 19, 29, 35, 37, 34, 28, 20, 14, 8, 5, 4, 2, 2, 2]),
+    &icdf::<18>(&[1, 2, 2, 5, 9, 14, 20, 24, 27, 28, 26, 23, 20, 15, 11, 8, 6, 15]),
+    &icdf::<18>(&[1, 1, 1, 6, 27, 58, 56, 39, 25, 14, 10, 6, 3, 3, 2, 1, 1, 2]),
+    &icdf::<18>(&[2, 1, 6, 27, 58, 56, 39, 25, 14, 10, 6, 3, 3, 2, 1, 1, 2, 0]),
+];
+pub const SHELL_16: [&[u8]; 16] = [
+    &icdf::<2>(&[126, 130]),
+    &icdf::<3>(&[56, 142, 58]),
+    &icdf::<4>(&[25, 101, 104, 26]),
+    &icdf::<5>(&[12, 60, 108, 64, 12]),
+    &icdf::<6>(&[7, 35, 84, 87, 37, 6]),
+    &icdf::<7>(&[4, 20, 59, 86, 63, 21, 3]),
+    &icdf::<8>(&[3, 12, 38, 72, 75, 42, 12, 2]),
+    &icdf::<9>(&[2, 8, 25, 54, 73, 59, 27, 7, 1]),
+    &icdf::<10>(&[2, 5, 17, 39, 63, 65, 42, 18, 4, 1]),
+    &icdf::<11>(&[1, 4, 12, 28, 49, 63, 54, 30, 11, 3, 1]),
+    &icdf::<12>(&[1, 4, 8, 20, 37, 55, 57, 41, 22, 8, 2, 1]),
+    &icdf::<13>(&[1, 3, 7, 15, 28, 44, 53, 48, 33, 16, 6, 1, 1]),
+    &icdf::<14>(&[1, 2, 6, 12, 21, 35, 47, 48, 40, 25, 12, 5, 1, 1]),
+    &icdf::<15>(&[1, 1, 4, 10, 17, 27, 37, 47, 43, 33, 21, 9, 4, 1, 1]),
+    &icdf::<16>(&[1, 1, 1, 8, 14, 22, 33, 40, 43, 38, 28, 16, 8, 1, 1, 1]),
+    &icdf::<17>(&[1, 1, 1, 1, 13, 18, 27, 36, 41, 41, 34, 24, 14, 1, 1, 1, 1]),
+];
+pub const SHELL_8: [&[u8]; 16] = [
+    &icdf::<2>(&[127, 129]),
+    &icdf::<3>(&[53, 149, 54]),
+    &icdf::<4>(&[22, 105, 106, 23]),
+    &icdf::<5>(&[11, 61, 111, 63, 10]),
+    &icdf::<6>(&[6, 35, 86, 88, 36, 5]),
+    &icdf::<7>(&[4, 20, 59, 87, 62, 21, 3]),
+    &icdf::<8>(&[3, 13, 40, 71, 73, 41, 13, 2]),
+    &icdf::<9>(&[3, 9, 27, 53, 70, 56, 28, 9, 1]),
+    &icdf::<10>(&[3, 8, 19, 37, 57, 61, 44, 20, 6, 1]),
+    &icdf::<11>(&[3, 7, 15, 28, 44, 54, 49, 33, 17, 5, 1]),
+    &icdf::<12>(&[1, 7, 13, 22, 34, 46, 48, 38, 28, 14, 4, 1]),
+    &icdf::<13>(&[1, 1, 11, 22, 27, 35, 42, 47, 33, 25, 10, 1, 1]),
+    &icdf::<14>(&[1, 1, 6, 14, 26, 37, 43, 43, 37, 26, 14, 6, 1, 1]),
+    &icdf::<15>(&[1, 1, 4, 10, 20, 31, 40, 42, 40, 31, 20, 10, 4, 1, 1]),
+    &icdf::<16>(&[1, 1, 3, 8, 16, 26, 35, 38, 38, 35, 26, 16, 8, 3, 1, 1]),
+    &icdf::<17>(&[1, 1, 2, 6, 12, 21, 30, 36, 38, 36, 30, 21, 12, 6, 2, 1, 1]),
+];
+pub const SHELL_4: [&[u8]; 16] = [
+    &icdf::<2>(&[127, 129]),
+    &icdf::<3>(&[49, 157, 50]),
+    &icdf::<4>(&[20, 107, 109, 20]),
+    &icdf::<5>(&[11, 60, 113, 62, 10]),
+    &icdf::<6>(&[7, 36, 84, 87, 36, 6]),
+    &icdf::<7>(&[6, 24, 57, 82, 60, 23, 4]),
+    &icdf::<8>(&[5, 18, 39, 64, 68, 42, 16, 4]),
+    &icdf::<9>(&[6, 14, 29, 47, 61, 52, 30, 14, 3]),
+    &icdf::<10>(&[1, 15, 23, 35, 51, 50, 40, 30, 10, 1]),
+    &icdf::<11>(&[1, 1, 21, 32, 42, 52, 46, 41, 18, 1, 1]),
+    &icdf::<12>(&[1, 6, 16, 27, 36, 42, 42, 36, 27, 16, 6, 1]),
+    &icdf::<13>(&[1, 5, 12, 21, 31, 38, 40, 38, 31, 21, 12, 5, 1]),
+    &icdf::<14>(&[1, 3, 9, 17, 26, 34, 38, 38, 34, 26, 17, 9, 3, 1]),
+    &icdf::<15>(&[1, 3, 7, 14, 22, 29, 34, 36, 34, 29, 22, 14, 7, 3, 1]),
+    &icdf::<16>(&[1, 2, 5, 11, 18, 25, 31, 35, 35, 31, 25, 18, 11, 5, 2, 1]),
+    &icdf::<17>(&[1, 1, 4, 9, 15, 21, 28, 32, 34, 32, 28, 21, 15, 9, 4, 1, 1]),
+];
+pub const SHELL_2: [&[u8]; 16] = [
+    &icdf::<2>(&[128, 128]),
+    &icdf::<3>(&[42, 172, 42]),
+    &icdf::<4>(&[21, 107, 107, 21]),
+    &icdf::<5>(&[12, 60, 112, 61, 11]),
+    &icdf::<6>(&[8, 34, 86, 86, 35, 7]),
+    &icdf::<7>(&[8, 23, 55, 90, 55, 20, 5]),
+    &icdf::<8>(&[5, 15, 38, 72, 72, 36, 15, 3]),
+    &icdf::<9>(&[6, 12, 27, 52, 77, 47, 20, 10, 5]),
+    &icdf::<10>(&[6, 19, 28, 35, 40, 40, 35, 28, 19, 6]),
+    &icdf::<11>(&[4, 14, 22, 31, 37, 40, 37, 31, 22, 14, 4]),
+    &icdf::<12>(&[3, 10, 18, 26, 33, 38, 38, 33, 26, 18, 10, 3]),
+    &icdf::<13>(&[2, 8, 13, 21, 29, 36, 38, 36, 29, 21, 13, 8, 2]),
+    &icdf::<14>(&[1, 5, 10, 17, 25, 32, 38, 38, 32, 25, 17, 10, 5, 1]),
+    &icdf::<15>(&[1, 4, 7, 13, 21, 29, 35, 36, 35, 29, 21, 13, 7, 4, 1]),
+    &icdf::<16>(&[1, 2, 5, 10, 17, 25, 32, 36, 36, 32, 25, 17, 10, 5, 2, 1]),
+    &icdf::<17>(&[1, 2, 4, 7, 13, 21, 28, 34, 36, 34, 28, 21, 13, 7, 4, 2, 1]),
+];
+pub const EXC_LSB: [u8; 2] = icdf(&[136, 120]);
+pub const EXC_SIGN: [&[u8]; 42] = [
+    &icdf::<2>(&[2, 254]),
+    &icdf::<2>(&[207, 49]),
+    &icdf::<2>(&[189, 67]),
+    &icdf::<2>(&[179, 77]),
+    &icdf::<2>(&[174, 82]),
+    &icdf::<2>(&[163, 93]),
+    &icdf::<2>(&[157, 99]),
+    &icdf::<2>(&[58, 198]),
+    &icdf::<2>(&[245, 11]),
+    &icdf::<2>(&[238, 18]),
+    &icdf::<2>(&[232, 24]),
+    &icdf::<2>(&[225, 31]),
+    &icdf::<2>(&[220, 36]),
+    &icdf::<2>(&[211, 45]),
+    &icdf::<2>(&[1, 255]),
+    &icdf::<2>(&[210, 46]),
+    &icdf::<2>(&[190, 66]),
+    &icdf::<2>(&[178, 78]),
+    &icdf::<2>(&[169, 87]),
+    &icdf::<2>(&[162, 94]),
+    &icdf::<2>(&[152, 104]),
+    &icdf::<2>(&[48, 208]),
+    &icdf::<2>(&[242, 14]),
+    &icdf::<2>(&[235, 21]),
+    &icdf::<2>(&[224, 32]),
+    &icdf::<2>(&[214, 42]),
+    &icdf::<2>(&[205, 51]),
+    &icdf::<2>(&[190, 66]),
+    &icdf::<2>(&[1, 255]),
+    &icdf::<2>(&[162, 94]),
+    &icdf::<2>(&[152, 104]),
+    &icdf::<2>(&[147, 109]),
+    &icdf::<2>(&[144, 112]),
+    &icdf::<2>(&[141, 115]),
+    &icdf::<2>(&[138, 118]),
+    &icdf::<2>(&[8, 248]),
+    &icdf::<2>(&[203, 53]),
+    &icdf::<2>(&[187, 69]),
+    &icdf::<2>(&[176, 80]),
+    &icdf::<2>(&[168, 88]),
+    &icdf::<2>(&[161, 95]),
+    &icdf::<2>(&[154, 102]),
+];
+pub const LBRR_FLAGS: [&[u8]; 2] = [&icdf::<3>(&[53, 53, 150]), &icdf::<7>(&[41, 20, 29, 41, 15, 28, 82])];
diff --git a/crates/audio/src/opus/encoder/tables.rs b/crates/audio/src/opus/encoder/tables.rs
new file mode 100644
index 000000000..1985202cc
--- /dev/null
+++ b/crates/audio/src/opus/encoder/tables.rs
@@ -0,0 +1,123 @@
+//! Constant tables of the 48 kHz CELT mode (RFC 6716 §4.3, Tables 55–58 and §4.3.2).
+//!
+//! Transcribed from RFC 6716; copied from FilmCraft's spec-derived `filmcraft-opus` decoder
+//! (first-party, MIT OR Apache-2.0) so both sides share the exact same values.
+
+/// Number of energy bands.
+pub const NB_EBANDS: usize = 21;
+/// Band edges in units of 2.5 ms MDCT bins (Table 55).
+pub const EBANDS: [i32; NB_EBANDS + 1] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24, 28, 34, 40, 48, 60, 78, 100];
+/// Overlap of the low-overlap window (samples at 48 kHz).
+pub const OVERLAP: usize = 120;
+/// Largest LM (20 ms frames).
+pub const MAX_LM: usize = 3;
+/// Pre-emphasis coefficient.
+pub const PREEMPH: f32 = 0.850_006_1;
+
+/// Static allocation table (Table 57), indexed `[quality][band]`, in 1/32 bit per MDCT bin.
+pub const ALLOC: [[u8; NB_EBANDS]; 11] = transpose([
+    [0, 90, 110, 118, 126, 134, 144, 152, 162, 172, 200],
+    [0, 80, 100, 110, 119, 127, 137, 145, 155, 165, 200],
+    [0, 75, 90, 103, 112, 120, 130, 138, 148, 158, 200],
+    [0, 69, 84, 93, 104, 114, 124, 132, 142, 152, 200],
+    [0, 63, 78, 86, 95, 103, 113, 123, 133, 143, 200],
+    [0, 56, 71, 80, 89, 97, 107, 117, 127, 137, 200],
+    [0, 49, 65, 75, 83, 91, 101, 111, 121, 131, 200],
+    [0, 40, 58, 70, 78, 85, 95, 105, 115, 125, 200],
+    [0, 34, 51, 65, 72, 78, 88, 98, 108, 118, 198],
+    [0, 29, 45, 59, 66, 72, 82, 92, 102, 112, 193],
+    [0, 20, 39, 53, 60, 66, 76, 86, 96, 106, 188],
+    [0, 18, 32, 47, 54, 60, 70, 80, 90, 100, 183],
+    [0, 10, 26, 40, 47, 54, 64, 74, 84, 94, 178],
+    [0, 0, 20, 31, 39, 47, 57, 67, 77, 87, 173],
+    [0, 0, 12, 23, 32, 41, 51, 61, 71, 81, 168],
+    [0, 0, 0, 15, 25, 35, 45, 55, 65, 75, 163],
+    [0, 0, 0, 4, 17, 29, 39, 49, 59, 69, 158],
+    [0, 0, 0, 0, 12, 23, 33, 43, 53, 63, 153],
+    [0, 0, 0, 0, 1, 16, 26, 36, 46, 56, 148],
+    [0, 0, 0, 0, 0, 10, 15, 20, 30, 45, 129],
+    [0, 0, 0, 0, 0, 1, 1, 1, 1, 20, 104],
+]);
+
+const fn transpose(t: [[u8; 11]; NB_EBANDS]) -> [[u8; NB_EBANDS]; 11] {
+    let mut out = [[0u8; NB_EBANDS]; 11];
+    let mut b = 0;
+    while b < NB_EBANDS {
+        let mut q = 0;
+        while q < 11 {
+            out[q][b] = t[b][q];
+            q += 1;
+        }
+        b += 1;
+    }
+    out
+}
+
+/// Mean band energy (log2 domain) removed before coarse quantisation.
+pub const E_MEANS: [f32; 25] = [
+    6.4375, 6.25, 5.75, 5.3125, 5.0625, 4.8125, 4.5, 4.375, 4.875, 4.6875, 4.5625, 4.4375, 4.875, 4.625, 4.3125, 4.5, 4.375, 4.625, 4.75, 4.4375,
+    3.75, 3.75, 3.75, 3.75, 3.75,
+];
+
+/// Inter-frame prediction coefficient (alpha) per LM, Q15.
+pub const PRED_COEF: [f32; 4] = [29440.0 / 32768.0, 26112.0 / 32768.0, 21248.0 / 32768.0, 16384.0 / 32768.0];
+/// Inter-band prediction coefficient (beta) per LM for inter frames, Q15.
+pub const BETA_COEF: [f32; 4] = [30147.0 / 32768.0, 22282.0 / 32768.0, 12124.0 / 32768.0, 6554.0 / 32768.0];
+/// Beta for intra frames.
+pub const BETA_INTRA: f32 = 4915.0 / 32768.0;
+
+/// Laplace model parameters for coarse energy: `[LM][intra][2*band + {0: prob, 1: decay}]`.
+pub const E_PROB_MODEL: [[[u8; 42]; 2]; 4] = [
+    [
+        [
+            72, 127, 65, 129, 66, 128, 65, 128, 64, 128, 62, 128, 64, 128, 64, 128, 92, 78, 92, 79, 92, 78, 90, 79, 116, 41, 115, 40, 114, 40, 132,
+            26, 132, 26, 145, 17, 161, 12, 176, 10, 177, 11,
+        ],
+        [
+            24, 179, 48, 138, 54, 135, 54, 132, 53, 134, 56, 133, 55, 132, 55, 132, 61, 114, 70, 96, 74, 88, 75, 88, 87, 74, 89, 66, 91, 67, 100, 59,
+            108, 50, 120, 40, 122, 37, 97, 43, 78, 50,
+        ],
+    ],
+    [
+        [
+            83, 78, 84, 81, 88, 75, 86, 74, 87, 71, 90, 73, 93, 74, 93, 74, 109, 40, 114, 36, 117, 34, 117, 34, 143, 17, 145, 18, 146, 19, 162, 12,
+            165, 10, 178, 7, 189, 6, 190, 8, 177, 9,
+        ],
+        [
+            23, 178, 54, 115, 63, 102, 66, 98, 69, 99, 74, 89, 71, 91, 73, 91, 78, 89, 86, 80, 92, 66, 93, 64, 102, 59, 103, 60, 104, 60, 117, 52,
+            123, 44, 138, 35, 133, 31, 97, 38, 77, 45,
+        ],
+    ],
+    [
+        [
+            61, 90, 93, 60, 105, 42, 107, 41, 110, 45, 116, 38, 113, 38, 112, 38, 124, 26, 132, 27, 136, 19, 140, 20, 155, 14, 159, 16, 158, 18, 170,
+            13, 177, 10, 187, 8, 192, 6, 175, 9, 159, 10,
+        ],
+        [
+            21, 178, 59, 110, 71, 86, 75, 85, 84, 83, 91, 66, 88, 73, 87, 72, 92, 75, 98, 72, 105, 58, 107, 54, 115, 52, 114, 55, 112, 56, 129, 51,
+            132, 40, 150, 33, 140, 29, 98, 35, 77, 42,
+        ],
+    ],
+    [
+        [
+            42, 121, 96, 66, 108, 43, 111, 40, 117, 44, 123, 32, 120, 36, 119, 33, 127, 33, 134, 34, 139, 21, 147, 23, 152, 20, 158, 25, 154, 26,
+            166, 21, 173, 16, 184, 13, 184, 10, 150, 13, 139, 15,
+        ],
+        [
+            22, 178, 63, 114, 74, 82, 84, 83, 92, 82, 103, 62, 96, 72, 96, 67, 101, 73, 107, 72, 113, 55, 118, 52, 125, 52, 118, 52, 117, 55, 135,
+            49, 137, 39, 157, 32, 145, 29, 97, 33, 77, 40,
+        ],
+    ],
+];
+
+/// Inverse CDF for coarse energy when only a few bits remain.
+pub const SMALL_ENERGY_ICDF: [u8; 3] = [2, 1, 0];
+/// Conservative log2 in 1/8 bits of the number of coded bands (intensity reservation).
+pub const LOG2_FRAC_TABLE: [i32; 24] = [0, 8, 13, 16, 19, 21, 23, 24, 26, 27, 28, 29, 30, 31, 32, 32, 33, 34, 34, 35, 36, 36, 37, 37];
+/// TF resolution changes: `[LM][4*transient + 2*tf_select + tf_flag]`.
+pub const TF_SELECT_TABLE: [[i8; 8]; 4] =
+    [[0, -1, 0, -1, 0, -1, 0, -1], [0, -1, 0, -2, 1, 0, 1, -1], [0, -2, 0, -3, 2, 0, 1, -1], [0, -2, 0, -3, 3, 0, 1, -1]];
+/// Spreading decision `{7, 2, 21, 2}/32`.
+pub const SPREAD_ICDF: [u8; 4] = [25, 23, 2, 0];
+/// Allocation trim (Table 58).
+pub const TRIM_ICDF: [u8; 11] = [126, 124, 119, 109, 87, 41, 19, 9, 4, 2, 0];
diff --git a/crates/audio/src/opus/mod.rs b/crates/audio/src/opus/mod.rs
index cf2accd33..b67e1ef3d 100644
--- a/crates/audio/src/opus/mod.rs
+++ b/crates/audio/src/opus/mod.rs
@@ -1,20 +1,31 @@
 //! Clean-room pure-Rust Opus (RFC 6716, updated by RFC 8251; RFC 7845 `OpusHead`).
 //!
-//! Decoding (feature `opus-decode`): [`Decoder`] (multistream, surround), [`StreamDecoder`] (one
-//! elementary stream), [`OpusHead`] and the packet parser [`packet`]. From FilmCraft's
-//! `filmcraft-opus` (storytold/filmcraft@8fda2f2).
+//! - Decoding (feature `opus-decode`): [`Decoder`] (multistream, surround), [`StreamDecoder`] (one
+//!   elementary stream), [`OpusHead`] and the packet parser [`packet`]. From FilmCraft's
+//!   `filmcraft-opus` (storytold/filmcraft@8fda2f2).
+//! - Encoding (feature `opus-encode`): [`Encoder`] (in [`encoder`]) (SILK, hybrid and CELT modes, 48 kHz,
+//!   20 ms, mono or stereo). From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429).
 //!
-//! Public items keep their names, so FilmCraft can re-export this module.
+//! Public items keep their names, so FilmCraft and EffectCraft can re-export this module. The two
+//! halves come from separate crates and do not share code yet (each has its own range coder, MDCT
+//! and band tables). [`Bandwidth`] is one type for both (`encoder::Bandwidth` is the same type);
+//! the two `Mode` enums keep their apps' variant names and convert into each other.
 
-// Index loops and long argument lists follow the specification's pseudo-code (FilmCraft allows
-// these lints workspace-wide).
+// Index loops and long argument lists follow the specification's pseudo-code (FilmCraft and
+// EffectCraft allow these lints workspace-wide).
 #![allow(clippy::needless_range_loop, clippy::too_many_arguments)]
 
+#[cfg(feature = "opus-decode")]
 mod decode;
+#[cfg(feature = "opus-encode")]
+pub mod encoder;
 
+#[cfg(feature = "opus-decode")]
 pub use decode::{Decoder, Error, Mode, OpusHead, Packet, Result, SAMPLE_RATES, StreamDecoder, Toc, packet};
+#[cfg(feature = "opus-encode")]
+pub use encoder::Encoder;
 
-/// Coded audio bandwidth (RFC 6716 §2, Table 1).
+/// Coded audio bandwidth (RFC 6716 §2, Table 1), for the decoder and the encoder alike.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Bandwidth {
     /// 4 kHz (8 kHz sampling).
@@ -29,9 +40,32 @@ pub enum Bandwidth {
     Fullband,
 }
 
+#[cfg(all(feature = "opus-decode", feature = "opus-encode"))]
+impl From<Mode> for encoder::Mode {
+    fn from(m: Mode) -> Self {
+        match m {
+            Mode::SilkOnly => encoder::Mode::Silk,
+            Mode::Hybrid => encoder::Mode::Hybrid,
+            Mode::CeltOnly => encoder::Mode::Celt,
+        }
+    }
+}
+
+#[cfg(all(feature = "opus-decode", feature = "opus-encode"))]
+impl From<encoder::Mode> for Mode {
+    fn from(m: encoder::Mode) -> Self {
+        match m {
+            encoder::Mode::Silk => Mode::SilkOnly,
+            encoder::Mode::Hybrid => Mode::Hybrid,
+            encoder::Mode::Celt => Mode::CeltOnly,
+        }
+    }
+}
+
 /// Channel order for Vorbis-ordered surround (mapping family 1, RFC 7845 §5.1.1.2): output channel
 /// → decoded channel, giving the WAV/SMPTE order (L R C LFE back… side…) the rest of craft-audio
 /// uses. From FilmCraft's `filmcraft-codecs`.
+#[cfg(feature = "opus-decode")]
 pub fn wav_order(channels: usize) -> Option<&'static [usize]> {
     Some(match channels {
         3 => &[0, 2, 1],
diff --git a/crates/audio/src/track.rs b/crates/audio/src/track.rs
index 920f571ae..e522e6f68 100644
--- a/crates/audio/src/track.rs
+++ b/crates/audio/src/track.rs
@@ -24,8 +24,10 @@ pub const LOOKAHEAD_PACKETS: usize = 8;
 enum Inner {
     #[cfg(feature = "aac-decode")]
     Aac {
+        /// The decoder, with SBR on for HE-AAC.
         dec: Box<aac::Decoder>,
-        up: Option<aac::Upsample2x>,
+        /// HE-AAC: 2048 samples per access unit, at twice the core rate.
+        sbr: bool,
         order: Option<&'static [usize]>,
         /// The format ADTS packets must keep, when their headers gave the configuration.
         adts_format: Option<AdtsFormat>,
@@ -74,7 +76,7 @@ pub(crate) type PacketFrames = fn(&[u8], u64) -> Option<u64>;
 ///
 /// It takes the track's [`CodecParams`] (from `isobmff::Track::codec_params`,
 /// `matroska::Track::codec_params`, `ogg::Stream::codec_params`, or built by hand for another
-/// container) and decodes AAC (LC; HE-AAC as its upsampled LC core), ALAC, Opus, AC-3/E-AC-3,
+/// container) and decodes AAC (LC, and HE-AAC with its SBR high band), ALAC, Opus, AC-3/E-AC-3,
 /// MP1/MP2, MP3 and PCM. Container timing (AAC priming, Opus pre-skip, end trimming) is the caller's:
 /// every decoded sample is returned.
 ///
@@ -168,17 +170,18 @@ impl TrackDecoder {
                     params.extradata.clone()
                 };
                 let asc = asc.as_slice();
-                let dec = aac::Decoder::new(asc)?;
+                let mut dec = aac::Decoder::new(asc)?;
                 let out = aac::output_rate(asc, payloads.iter().copied()).unwrap_or(dec.sample_rate());
-                let up = (dec.sample_rate().checked_mul(2) == Some(out)).then(|| aac::Upsample2x::new(dec.channels()));
-                let codec = if up.is_some() { CodecId::HeAac } else { CodecId::Aac };
-                // Only twice the core rate is upsampled to; any other signalled rate plays the core.
-                let out = if up.is_some() { out } else { dec.sample_rate() };
+                let sbr = dec.sample_rate().checked_mul(2) == Some(out);
+                let codec = if sbr { CodecId::HeAac } else { CodecId::Aac };
+                // Only SBR at twice the core rate is decoded; any other signalled rate plays the core.
+                dec.set_sbr(sbr);
+                let out = dec.sample_rate();
                 // a program config element that spells out a configuration has its speakers
                 let cfg = aac::speaker_config(dec.config());
                 let layout = aac_layout(cfg, dec.channels());
                 let order = layout.is_ordered().then(|| aac::wav_order(cfg)).flatten();
-                (Inner::Aac { dec: Box::new(dec), up, order, adts_format }, codec, out, layout, SampleFormat::Compressed)
+                (Inner::Aac { dec: Box::new(dec), sbr, order, adts_format }, codec, out, layout, SampleFormat::Compressed)
             }
             #[cfg(feature = "alac-decode")]
             CodecId::Alac => {
@@ -320,7 +323,7 @@ impl TrackDecoder {
         let mut partial = false;
         let channels = match &mut self.inner {
             #[cfg(feature = "aac-decode")]
-            Inner::Aac { dec, up, order, adts_format } => {
+            Inner::Aac { dec, order, adts_format, .. } => {
                 let mut out: Vec<Vec<f32>> = Vec::new();
                 let units = match adts_frames(packet) {
                     Some(frames) => adts_units(frames, *adts_format)?,
@@ -328,17 +331,11 @@ impl TrackDecoder {
                 };
                 // A failed frame leaves the decoder as it was, so the frames before it in the
                 // packet must too: their audio is replaced by the packet's concealment.
-                let before = (units.len() > 1).then(|| (dec.clone(), up.clone()));
-                let decoded = units.into_iter().try_for_each(|unit| {
-                    let mut block = dec.decode(unit)?;
-                    if let Some(up) = up.as_mut() {
-                        block = up.process(block);
-                    }
-                    append(&mut out, block)
-                });
+                let before = (units.len() > 1).then(|| dec.clone());
+                let decoded = units.into_iter().try_for_each(|unit| append(&mut out, dec.decode(unit)?));
                 if let Err(e) = decoded {
                     if let Some(before) = before {
-                        (*dec, *up) = before;
+                        *dec = before;
                     }
                     return Err(e);
                 }
@@ -440,8 +437,8 @@ impl TrackDecoder {
                 None
             }
             #[cfg(feature = "aac-decode")]
-            Inner::Aac { up, .. } => {
-                let per_unit = aac::FRAME_LEN * if up.is_some() { 2 } else { 1 };
+            Inner::Aac { sbr, .. } => {
+                let per_unit = aac::FRAME_LEN * if *sbr { 2 } else { 1 };
                 match adts_frames(data) {
                     Some(f) => Some(f.iter().map(|(h, _)| usize::from(h.raw_data_blocks)).sum::<usize>().min(MAX_ADTS_FRAMES_PER_PACKET) * per_unit),
                     // A packet lost whole: as long as the last one, in a stream of multi-frame
@@ -488,7 +485,7 @@ impl TrackDecoder {
     pub fn frames_per_packet(&self) -> Option<usize> {
         match &self.inner {
             #[cfg(feature = "aac-decode")]
-            Inner::Aac { up, .. } => Some(aac::FRAME_LEN * if up.is_some() { 2 } else { 1 }),
+            Inner::Aac { sbr, .. } => Some(aac::FRAME_LEN * if *sbr { 2 } else { 1 }),
             #[cfg(feature = "alac-decode")]
             Inner::Alac { .. } => None,
             #[cfg(feature = "ac3-decode")]
@@ -544,7 +541,7 @@ impl TrackDecoder {
     pub fn preroll(&self) -> usize {
         match &self.inner {
             #[cfg(feature = "aac-decode")]
-            Inner::Aac { up, .. } => 2 * aac::FRAME_LEN * if up.is_some() { 2 } else { 1 },
+            Inner::Aac { sbr, .. } => 2 * aac::FRAME_LEN * if *sbr { 2 } else { 1 },
             #[cfg(feature = "alac-decode")]
             Inner::Alac { .. } => 0,
             #[cfg(feature = "ac3-decode")]
@@ -570,12 +567,7 @@ impl TrackDecoder {
         self.last_frames = 0;
         match &mut self.inner {
             #[cfg(feature = "aac-decode")]
-            Inner::Aac { dec, up, .. } => {
-                dec.reset();
-                if let Some(up) = up {
-                    up.reset();
-                }
-            }
+            Inner::Aac { dec, .. } => dec.reset(),
             #[cfg(feature = "alac-decode")]
             Inner::Alac { .. } => {}
             #[cfg(feature = "ac3-decode")]
diff --git a/crates/audio/tests/codecs/aac/he_aac_oracle.rs b/crates/audio/tests/codecs/aac/he_aac_oracle.rs
new file mode 100644
index 000000000..0eeba69c8
--- /dev/null
+++ b/crates/audio/tests/codecs/aac/he_aac_oracle.rs
@@ -0,0 +1,169 @@
+//! HE-AAC (SBR) decoding against ffmpeg's decoder, on streams from ffmpeg's AudioToolbox encoder
+//! (oracle only; skipped without ffmpeg or without `aac_at`, which only macOS builds have).
+
+use std::process::Command;
+
+use craft_audio::aac::{Decoder, split_adts};
+
+use super::common::*;
+
+/// ffmpeg, if it has the AudioToolbox AAC encoder.
+fn ffmpeg_with_aac_at() -> Option<std::path::PathBuf> {
+    let ff = ffmpeg()?;
+    let out = Command::new(&ff).args(["-hide_banner", "-encoders"]).output().ok()?;
+    if !String::from_utf8_lossy(&out.stdout).contains("aac_at") {
+        eprintln!("SKIPPED: ffmpeg has no aac_at encoder");
+        return None;
+    }
+    Some(ff)
+}
+
+fn input(rate: u32, channels: usize, secs: f32) -> Vec<Vec<f32>> {
+    let n = (rate as f32 * secs) as usize;
+    (0..channels)
+        .map(|c| {
+            let a = chords(rate, n, 0.004 * c as f32);
+            let s = speech(rate, n, 11 + c as u64);
+            let z = noise(n, 0.05, 3 + c as u64);
+            let k = clicks(rate, n);
+            a.iter().zip(&s).zip(&z).zip(&k).map(|(((a, s), z), k)| 0.4 * a + 0.4 * s * if c == 1 { -0.7 } else { 1.0 } + z + 0.3 * k).collect()
+        })
+        .collect()
+}
+
+/// ffmpeg's decode of a stream of `channels` channels. ffmpeg decodes mono HE-AAC as stereo (it
+/// allows for parametric stereo the stream may hold), with the same signal in both channels when
+/// there is none: of those, the first is taken (a downmix would scale it by -3 dB).
+fn ffmpeg_decode_as(ff: &std::path::Path, file: &std::path::Path, channels: usize) -> Vec<Vec<f32>> {
+    let mut planar = ffmpeg_decode_raw(ff, file, channels.max(2));
+    planar.truncate(channels);
+    planar
+}
+
+fn ffmpeg_decode_raw(ff: &std::path::Path, file: &std::path::Path, channels: usize) -> Vec<Vec<f32>> {
+    let out = Command::new(ff).args(["-v", "error", "-i"]).arg(file).args(["-ac", &channels.to_string(), "-f", "f32le", "-"]).output().unwrap();
+    assert!(out.status.success() && out.stderr.is_empty(), "{}", String::from_utf8_lossy(&out.stderr));
+    let samples: Vec<f32> = out.stdout.as_chunks::<4>().0.iter().map(|&b| f32::from_le_bytes(b)).collect();
+    (0..channels).map(|c| samples.iter().skip(c).step_by(channels).copied().collect()).collect()
+}
+
+/// Our decode of an ADTS stream, SBR on.
+fn decode_sbr(data: &[u8]) -> (Vec<Vec<f32>>, u32) {
+    let frames = split_adts(data).unwrap();
+    let mut dec = Decoder::from_adts(&frames[0].0).unwrap();
+    dec.set_sbr(true);
+    let mut out: Vec<Vec<f32>> = Vec::new();
+    for (_, au) in frames {
+        let pcm = dec.decode(au).unwrap();
+        out.resize(pcm.len(), Vec::new());
+        for (o, p) in out.iter_mut().zip(pcm) {
+            o.extend(p);
+        }
+    }
+    (out, dec.sample_rate())
+}
+
+/// The lag of `b` behind `a` (within ±`range`) that correlates best.
+fn best_lag(a: &[f32], b: &[f32], range: i64) -> i64 {
+    let n = a.len().min(b.len()) as i64;
+    let (from, to) = (range, n - range);
+    (-range..=range)
+        .max_by(|&x, &y| {
+            let c = |lag: i64| (from..to).step_by(3).map(|i| a[i as usize] as f64 * b[(i + lag) as usize] as f64).sum::<f64>();
+            c(x).total_cmp(&c(y))
+        })
+        .unwrap()
+}
+
+/// Energy in dB of `x[from..from + 2048]` within `lo..hi` Hz (Hann-windowed DFT).
+fn band_db(x: &[f32], from: usize, rate: f32, lo: f32, hi: f32) -> f64 {
+    let n = 2048;
+    let seg = &x[from..from + n];
+    let (b0, b1) = ((lo / rate * n as f32) as usize, (hi / rate * n as f32) as usize);
+    let mut e = 0f64;
+    for b in b0..b1.min(n / 2) {
+        let (mut re, mut im) = (0f64, 0f64);
+        for (i, &s) in seg.iter().enumerate() {
+            let w = 0.5 - 0.5 * (2.0 * std::f64::consts::PI * i as f64 / n as f64).cos();
+            let ph = 2.0 * std::f64::consts::PI * (b * i) as f64 / n as f64;
+            re += s as f64 * w * ph.cos();
+            im += s as f64 * w * ph.sin();
+        }
+        e += re * re + im * im;
+    }
+    10.0 * (e + 1e-12).log10()
+}
+
+struct Case {
+    name: &'static str,
+    rate: u32,
+    channels: usize,
+    bitrate: &'static str,
+}
+
+/// HE-AAC streams of 1 to 6 channels at 22.05 to 48 kHz decode as ffmpeg decodes them: the same
+/// timing, the low band to 55 dB and the rebuilt high band's level to 0.1 dB.
+#[test]
+fn matches_ffmpeg_he_aac_decoder() {
+    let Some(ff) = ffmpeg_with_aac_at() else { return };
+    let cases = [
+        Case { name: "he_stereo_44k_48k", rate: 44_100, channels: 2, bitrate: "48k" },
+        Case { name: "he_mono_44k_32k", rate: 44_100, channels: 1, bitrate: "32k" },
+        Case { name: "he_stereo_48k_64k", rate: 48_000, channels: 2, bitrate: "64k" },
+        Case { name: "he_stereo_32k_32k", rate: 32_000, channels: 2, bitrate: "32k" },
+        Case { name: "he_stereo_44k_24k", rate: 44_100, channels: 2, bitrate: "24k" },
+        Case { name: "he_stereo_22k_24k", rate: 22_050, channels: 2, bitrate: "24k" },
+        Case { name: "he_51_48k_160k", rate: 48_000, channels: 6, bitrate: "160k" },
+    ];
+    for case in &cases {
+        let path = fixtures().join(format!("{}.aac", case.name));
+        ffmpeg_encode(&ff, &input(case.rate, case.channels, 3.0), case.rate, &["-c:a", "aac_at", "-profile:a", "4", "-b:a", case.bitrate], &path);
+        let data = std::fs::read(&path).unwrap();
+        let refr = ffmpeg_decode_as(&ff, &path, case.channels);
+        let (ours, rate) = decode_sbr(&data);
+        // ffmpeg puts surround in WAV order, the decoder in AAC element order
+        let ours: Vec<Vec<f32>> = match (case.channels == 6).then(|| craft_audio::aac::wav_order(6)).flatten() {
+            Some(order) => order.iter().map(|&c| ours[c].clone()).collect(),
+            None => ours,
+        };
+        assert_eq!(rate, case.rate, "{}", case.name);
+        assert_eq!(ours.len(), case.channels);
+        // the same delay as ffmpeg's decoder: 962 samples
+        assert_eq!(best_lag(&refr[0], &ours[0], 2100), 0, "{}", case.name);
+        let core_nyquist = case.rate as f32 / 4.0;
+        for c in 0..case.channels {
+            let n = refr[c].len().min(ours[c].len()) - 4096;
+            let a: Vec<f32> = refr[c][2048..n].to_vec();
+            let b: Vec<f32> = ours[c][2048..n].to_vec();
+            let full = snr(&a, &b);
+            let (la, lb) = (lowpass(&a, core_nyquist * 0.8, case.rate as f32), lowpass(&b, core_nyquist * 0.8, case.rate as f32));
+            let low = snr(&la, &lb);
+            let mut diffs = Vec::new();
+            for from in (4096..a.len() - 4096).step_by(4096) {
+                for (lo, hi) in
+                    [(core_nyquist * 1.05, core_nyquist * 1.3), (core_nyquist * 1.3, core_nyquist * 1.7), (core_nyquist * 1.7, core_nyquist * 2.0)]
+                {
+                    let (ea, eb) = (band_db(&a, from, case.rate as f32, lo, hi), band_db(&b, from, case.rate as f32, lo, hi));
+                    if ea > 0.0 {
+                        diffs.push(eb - ea);
+                    }
+                }
+            }
+            // the LFE (WAV channel 3 of 5.1) has no SBR, so no high band; every other channel must
+            // have one to compare
+            let lfe = case.channels == 6 && c == 3;
+            assert!(lfe || !diffs.is_empty(), "{} ch{c}: no high band to compare", case.name);
+            let mean = diffs.iter().sum::<f64>() / diffs.len() as f64;
+            let mad = diffs.iter().map(|d| d.abs()).sum::<f64>() / diffs.len() as f64;
+            println!(
+                "{} ch{c}: full SNR {full:.1} dB, low band SNR {low:.1} dB, high band level {mean:+.2} dB (mean |Δ| {mad:.2} dB over {})",
+                case.name,
+                diffs.len()
+            );
+            // The low band differs by the core decoders' rounding; the high band's noise comes
+            // from the same table, so whole frames match too.
+            assert!(full > 45.0 && low > 55.0, "{} ch{c}: SNR {full:.1} / {low:.1} dB", case.name);
+            assert!(lfe || mad < 0.1, "{} ch{c}: high band off by {mad:.2} dB", case.name);
+        }
+    }
+}
diff --git a/crates/audio/tests/codecs/aac/mod.rs b/crates/audio/tests/codecs/aac/mod.rs
index 45e627242..7d55a7364 100644
--- a/crates/audio/tests/codecs/aac/mod.rs
+++ b/crates/audio/tests/codecs/aac/mod.rs
@@ -3,4 +3,5 @@
 mod common;
 mod decoder_oracle;
 mod encoder_oracle;
+mod he_aac_oracle;
 mod robustness;
diff --git a/crates/audio/tests/codecs/main.rs b/crates/audio/tests/codecs/main.rs
index 5db6af4b0..279246dc6 100644
--- a/crates/audio/tests/codecs/main.rs
+++ b/crates/audio/tests/codecs/main.rs
@@ -1,5 +1,5 @@
-//! Tests of the codecs ported from FilmCraft, built as one test binary: each file is a module, as
-//! in their original crates.
+//! Tests of the codecs ported from FilmCraft and EffectCraft, built as one test binary: each file
+//! is a module, as in their original crates.
 // Index loops follow the specifications, as in FilmCraft (which allows this lint workspace-wide).
 #![allow(clippy::needless_range_loop)]
 
@@ -16,5 +16,6 @@ mod mp3_decoder_oracle;
 mod mp3_encoder_oracle;
 mod mpa_oracle;
 mod opus;
+mod opusenc;
 mod routing_oracle;
 mod track_decoder;
diff --git a/crates/audio/tests/codecs/opusenc/common.rs b/crates/audio/tests/codecs/opusenc/common.rs
new file mode 100644
index 000000000..571c9826c
--- /dev/null
+++ b/crates/audio/tests/codecs/opusenc/common.rs
@@ -0,0 +1,286 @@
+//! Shared helpers for the SILK/hybrid round-trip tests: synthetic signals, encoding, decoding
+//! with FilmCraft's spec-derived decoder, delay-searched SNR and an Ogg Opus writer for ffmpeg.
+#![allow(dead_code)]
+
+use craft_audio::opus::encoder::OpusEncoder;
+
+pub const SR: f64 = 48_000.0;
+pub const FRAME: usize = OpusEncoder::FRAME_SIZE;
+
+/// Two-pole resonator state.
+struct Reson {
+    y1: f64,
+    y2: f64,
+}
+
+impl Reson {
+    fn run(&mut self, x: f64, f: f64, bw: f64) -> f64 {
+        let r = (-std::f64::consts::PI * bw / SR).exp();
+        let a1 = 2.0 * r * (2.0 * std::f64::consts::PI * f / SR).cos();
+        let a2 = -r * r;
+        let g = 1.0 - r;
+        let y = g * x + a1 * self.y1 + a2 * self.y2;
+        self.y2 = self.y1;
+        self.y1 = y;
+        y
+    }
+}
+
+/// Speech-like test signal: a glottal pulse train (100–200 Hz, gliding pitch) through three
+/// formant resonators whose frequencies change per syllable, with syllable envelopes, short
+/// pauses and a little aspiration noise.
+pub fn speech(len: usize, seed: u32) -> Vec<f32> {
+    let vowels: [[f64; 3]; 5] =
+        [[730.0, 1090.0, 2440.0], [270.0, 2290.0, 3010.0], [530.0, 1840.0, 2480.0], [570.0, 840.0, 2410.0], [300.0, 870.0, 2240.0]];
+    let syl = (0.24 * SR) as usize;
+    let mut out = Vec::with_capacity(len);
+    let mut res = [Reson { y1: 0.0, y2: 0.0 }, Reson { y1: 0.0, y2: 0.0 }, Reson { y1: 0.0, y2: 0.0 }];
+    let mut phase = 0.0f64;
+    let mut s = seed;
+    let mut prev_glottal = 0.0;
+    for n in 0..len {
+        let t = n as f64 / SR;
+        let k = n / syl;
+        let pos = (n % syl) as f64 / syl as f64;
+        // Every fourth syllable is a pause.
+        let pause = k % 4 == 3;
+        let env = if pause { 0.0 } else { (std::f64::consts::PI * pos).sin().powf(0.7) };
+        let f0 = 100.0 + 50.0 * (1.0 + (2.0 * std::f64::consts::PI * 0.9 * t).sin()) + 15.0 * ((k * 7) % 5) as f64 - 30.0 * pos;
+        phase += f0 / SR;
+        if phase >= 1.0 {
+            phase -= 1.0;
+        }
+        // Rosenberg-like glottal flow; its derivative excites the vocal tract.
+        let g = if phase < 0.4 {
+            0.5 * (1.0 - (std::f64::consts::PI * phase / 0.4).cos())
+        } else if phase < 0.56 {
+            (std::f64::consts::FRAC_PI_2 * (phase - 0.4) / 0.16).cos()
+        } else {
+            0.0
+        };
+        let dg = (g - prev_glottal) * 40.0;
+        prev_glottal = g;
+        s = s.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
+        let noise = ((s >> 8) as f64 / (1u32 << 24) as f64 - 0.5) * 0.02;
+        let v = vowels[(k * 3 + 1) % 5];
+        let w = vowels[(k * 3 + 4) % 5];
+        let mix = pos;
+        let mut x = dg + noise;
+        let mut y = 0.0;
+        for (i, r) in res.iter_mut().enumerate() {
+            let f = v[i] * (1.0 - mix) + w[i] * mix;
+            y += r.run(x, f, 60.0 + 40.0 * i as f64) * [1.0, 0.6, 0.3][i];
+        }
+        x = y * env * 1.2;
+        out.push(x as f32);
+    }
+    let peak = out.iter().fold(0f32, |m, v| m.max(v.abs()));
+    let g = 0.5 / peak.max(1e-9);
+    out.iter().map(|v| v * g).collect()
+}
+
+/// Music-like test signal: three-note chords of harmonic tones (six partials each), changing
+/// every half second with soft attacks and releases.
+pub fn music(len: usize) -> Vec<f32> {
+    let chords: [[f64; 3]; 4] = [[261.63, 329.63, 392.0], [220.0, 277.18, 329.63], [174.61, 220.0, 261.63], [196.0, 246.94, 293.66]];
+    let seg = (0.5 * SR) as usize;
+    (0..len)
+        .map(|n| {
+            let t = n as f64 / SR;
+            let k = n / seg;
+            let pos = (n % seg) as f64 / seg as f64;
+            let env = (pos * 20.0).min(1.0) * ((1.0 - pos) * 10.0).min(1.0);
+            let mut x = 0.0;
+            for (j, &f) in chords[k % 4].iter().enumerate() {
+                for h in 1..=6 {
+                    x += (2.0 * std::f64::consts::PI * f * h as f64 * t + j as f64).sin() / h as f64;
+                }
+            }
+            (0.12 * env * x) as f32
+        })
+        .collect()
+}
+
+pub fn interleave(planar: &[Vec<f32>]) -> Vec<f32> {
+    let c = planar.len();
+    let len = planar[0].len();
+    let mut pcm = vec![0f32; len * c];
+    for (ch, p) in planar.iter().enumerate() {
+        for (i, &v) in p.iter().enumerate() {
+            pcm[i * c + ch] = v;
+        }
+    }
+    pcm
+}
+
+/// Encodes planar input (padding the tail so the encoder delay is flushed).
+pub fn encode(mut enc: OpusEncoder, planar: &[Vec<f32>]) -> (OpusEncoder, Vec<Vec<u8>>) {
+    let c = planar.len();
+    let len = planar[0].len();
+    let total = len + enc.pre_skip() as usize + 16;
+    let frames = total.div_ceil(FRAME);
+    let mut pcm = interleave(planar);
+    pcm.resize(frames * FRAME * c, 0.0);
+    let packets = pcm.chunks(FRAME * c).map(|f| enc.encode_float(f).unwrap()).collect();
+    (enc, packets)
+}
+
+/// Decodes with filmcraft-opus, drops the pre-skip and returns planar channels (full length).
+pub fn decode(head: &[u8], packets: &[Vec<u8>]) -> Vec<Vec<f32>> {
+    let mut dec = craft_audio::opus::Decoder::new(head).expect("OpusHead");
+    dec.set_trim_pre_skip(true);
+    let mut out: Vec<Vec<f32>> = vec![Vec::new(); dec.channels()];
+    for p in packets {
+        let planes = dec.decode(Some(p)).expect("decode");
+        for (o, p) in out.iter_mut().zip(planes) {
+            o.extend_from_slice(&p);
+        }
+    }
+    out
+}
+
+/// Waveform SNR (dB) of `dec[i + shift]` against `orig[i]`, excluding the first and last 20 ms.
+pub fn snr_at(orig: &[f32], dec: &[f32], shift: isize) -> f64 {
+    let (mut s, mut e) = (0f64, 0f64);
+    for i in FRAME..orig.len() - FRAME {
+        let j = i as isize + shift;
+        let d = if j >= 0 && (j as usize) < dec.len() { dec[j as usize] as f64 } else { 0.0 };
+        s += (orig[i] as f64).powi(2);
+        e += (orig[i] as f64 - d).powi(2);
+    }
+    10.0 * (s / e.max(1e-30)).log10()
+}
+
+/// Best SNR over residual delays of ±`range` samples: (SNR dB, delay).
+pub fn snr_search(orig: &[f32], dec: &[f32], range: isize) -> (f64, isize) {
+    (-range..=range).map(|d| (snr_at(orig, dec, d), d)).fold((f64::MIN, 0), |a, b| if b.0 > a.0 { b } else { a })
+}
+
+/// Segmental SNR (dB): mean over 20 ms segments holding signal (each clamped to [-10, 40]).
+pub fn seg_snr(orig: &[f32], dec: &[f32], shift: isize) -> f64 {
+    let mut acc = 0f64;
+    let mut n = 0;
+    let mut i = FRAME;
+    while i + FRAME <= orig.len() - FRAME {
+        let (mut s, mut e) = (0f64, 0f64);
+        for k in i..i + FRAME {
+            let j = k as isize + shift;
+            let d = if j >= 0 && (j as usize) < dec.len() { dec[j as usize] as f64 } else { 0.0 };
+            s += (orig[k] as f64).powi(2);
+            e += (orig[k] as f64 - d).powi(2);
+        }
+        if s / FRAME as f64 > 1e-5 {
+            acc += (10.0 * (s / e.max(1e-30)).log10()).clamp(-10.0, 40.0);
+            n += 1;
+        }
+        i += FRAME;
+    }
+    acc / n.max(1) as f64
+}
+
+/// Average bitrate (bits per second) of a packet sequence of 20 ms packets.
+pub fn bitrate(packets: &[Vec<u8>]) -> f64 {
+    packets.iter().map(|p| p.len() * 8).sum::<usize>() as f64 / (packets.len() as f64 * 0.02)
+}
+
+/// Low-pass filtered copy (FFT brick wall) used to compare band-limited modes fairly.
+pub fn lowpass(x: &[f32], fc: f64) -> Vec<f32> {
+    let n = x.len().next_power_of_two();
+    let mut re: Vec<f64> = x.iter().map(|&v| v as f64).collect();
+    re.resize(n, 0.0);
+    let mut im = vec![0f64; n];
+    fft(&mut re, &mut im, false);
+    for k in 0..n {
+        let f = (k.min(n - k)) as f64 * SR / n as f64;
+        if f > fc {
+            re[k] = 0.0;
+            im[k] = 0.0;
+        }
+    }
+    fft(&mut re, &mut im, true);
+    re[..x.len()].iter().map(|&v| (v / n as f64) as f32).collect()
+}
+
+pub fn fft(re: &mut [f64], im: &mut [f64], inverse: bool) {
+    let n = re.len();
+    let mut j = 0;
+    for i in 1..n {
+        let mut bit = n >> 1;
+        while j & bit != 0 {
+            j ^= bit;
+            bit >>= 1;
+        }
+        j |= bit;
+        if i < j {
+            re.swap(i, j);
+            im.swap(i, j);
+        }
+    }
+    let mut len = 2;
+    while len <= n {
+        let ang = if inverse { 2.0 } else { -2.0 } * std::f64::consts::PI / len as f64;
+        for s in (0..n).step_by(len) {
+            for k in 0..len / 2 {
+                let (wr, wi) = ((ang * k as f64).cos(), (ang * k as f64).sin());
+                let (a, b) = (s + k, s + k + len / 2);
+                let tr = re[b] * wr - im[b] * wi;
+                let ti = re[b] * wi + im[b] * wr;
+                re[b] = re[a] - tr;
+                im[b] = im[a] - ti;
+                re[a] += tr;
+                im[a] += ti;
+            }
+        }
+        len <<= 1;
+    }
+}
+
+// ---- Ogg Opus (RFC 3533 + RFC 7845) for the ffmpeg oracle ----
+
+fn ogg_crc(data: &[u8]) -> u32 {
+    let mut crc = 0u32;
+    for &b in data {
+        crc ^= (b as u32) << 24;
+        for _ in 0..8 {
+            crc = if crc & 0x8000_0000 != 0 { (crc << 1) ^ 0x04C1_1DB7 } else { crc << 1 };
+        }
+    }
+    crc
+}
+
+fn ogg_page(out: &mut Vec<u8>, packet: &[u8], header_type: u8, granule: u64, seq: u32) {
+    let mut lacing = vec![255u8; packet.len() / 255];
+    lacing.push((packet.len() % 255) as u8);
+    let start = out.len();
+    out.extend_from_slice(b"OggS");
+    out.push(0);
+    out.push(header_type);
+    out.extend_from_slice(&granule.to_le_bytes());
+    out.extend_from_slice(&0x4543_4F50u32.to_le_bytes());
+    out.extend_from_slice(&seq.to_le_bytes());
+    out.extend_from_slice(&0u32.to_le_bytes());
+    out.push(lacing.len() as u8);
+    out.extend_from_slice(&lacing);
+    out.extend_from_slice(packet);
+    let crc = ogg_crc(&out[start..]);
+    out[start + 22..start + 26].copy_from_slice(&crc.to_le_bytes());
+}
+
+/// An Ogg Opus file holding `packets` for `len` samples of audio.
+pub fn ogg_opus(enc: &OpusEncoder, packets: &[Vec<u8>], len: usize) -> Vec<u8> {
+    let mut out = Vec::new();
+    ogg_page(&mut out, &enc.opus_head(), 0x02, 0, 0);
+    let vendor = b"effectcraft-opusenc";
+    let mut tags = b"OpusTags".to_vec();
+    tags.extend_from_slice(&(vendor.len() as u32).to_le_bytes());
+    tags.extend_from_slice(vendor);
+    tags.extend_from_slice(&0u32.to_le_bytes());
+    ogg_page(&mut out, &tags, 0, 0, 1);
+    let pre_skip = enc.pre_skip() as u64;
+    for (i, p) in packets.iter().enumerate() {
+        let last = i + 1 == packets.len();
+        let granule = if last { pre_skip + len as u64 } else { ((i + 1) * FRAME) as u64 };
+        ogg_page(&mut out, p, if last { 0x04 } else { 0 }, granule, i as u32 + 2);
+    }
+    out
+}
diff --git a/crates/audio/tests/codecs/opusenc/ffmpeg.rs b/crates/audio/tests/codecs/opusenc/ffmpeg.rs
new file mode 100644
index 000000000..41965be20
--- /dev/null
+++ b/crates/audio/tests/codecs/opusenc/ffmpeg.rs
@@ -0,0 +1,83 @@
+//! ffmpeg as a second, external oracle: every mode/bandwidth written as Ogg Opus must decode
+//! without errors with both ffmpeg's native `opus` decoder and `libopus`, honour the pre-skip
+//! and end granule, and reproduce the input. Skipped when ffmpeg is not installed.
+
+use super::common;
+
+use std::process::Command;
+
+use common::*;
+use craft_audio::opus::encoder::{Bandwidth, Mode, OpusEncoder};
+
+/// ffmpeg, found and skipped by craft-media's oracle rules (EffectCraft looked in Homebrew's
+/// directory, then `PATH`).
+fn ffmpeg() -> Option<std::path::PathBuf> {
+    crate::testkit::ffmpeg_or_skip("opus encoder ffmpeg oracle")
+}
+
+/// Decodes an Ogg Opus file with ffmpeg's decoder `codec`; returns interleaved f32 output.
+fn ffmpeg_decode(exe: &std::path::Path, codec: &str, file: &[u8], channels: usize, tag: &str) -> Option<Vec<f32>> {
+    let has = match Command::new(exe).args(["-hide_banner", "-decoders"]).output() {
+        Ok(out) => out,
+        Err(e) => return crate::common::skip(&format!("ffmpeg -decoders failed: {e}")),
+    };
+    if !String::from_utf8_lossy(&has.stdout).lines().any(|l| l.split_whitespace().nth(1) == Some(codec)) {
+        return crate::common::skip(&format!("ffmpeg has no {codec} decoder"));
+    }
+    let path = std::env::temp_dir().join(format!("effectcraft-opusenc-{}-{tag}.opus", std::process::id()));
+    std::fs::write(&path, file).unwrap();
+    let out = Command::new(exe)
+        .args(["-v", "error", "-c:a", codec, "-i"])
+        .arg(&path)
+        .args(["-f", "f32le", "-ac", &channels.to_string(), "-ar", "48000", "-"])
+        .output()
+        .expect("run ffmpeg");
+    let _ = std::fs::remove_file(&path);
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(out.status.success(), "ffmpeg ({codec}) failed: {stderr}");
+    // ffmpeg's native decoder also makes its raw-PCM muxer print a timestamp complaint for
+    // narrowband SILK streams written by libopus itself; that line is about ffmpeg's own
+    // timestamping, not the bitstream, so it is the one message tolerated.
+    let errors: Vec<&str> = stderr.lines().filter(|l| !l.trim().is_empty() && !l.contains("non monotonically increasing dts to muxer")).collect();
+    assert!(errors.is_empty(), "ffmpeg ({codec}) reported errors: {errors:?}");
+    Some(out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]])).collect())
+}
+
+#[test]
+fn ffmpeg_decodes_every_mode() {
+    let Some(exe) = ffmpeg() else {
+        eprintln!("ffmpeg not installed; skipping the oracle test");
+        return;
+    };
+    let len = 48_000;
+    let sp = speech(len + 30_000, 3);
+    let left = sp[..len].to_vec();
+    let right: Vec<f32> = sp[30_000..].iter().map(|v| v * 0.7).collect();
+    let cases = [
+        (1usize, Mode::Silk, Bandwidth::Narrowband, 8_000u32, 3_400.0, 8.0),
+        (1, Mode::Silk, Bandwidth::Mediumband, 11_000, 5_000.0, 10.0),
+        (1, Mode::Silk, Bandwidth::Wideband, 16_000, 7_000.0, 12.0),
+        (2, Mode::Silk, Bandwidth::Wideband, 32_000, 7_000.0, 12.0),
+        (1, Mode::Hybrid, Bandwidth::SuperWideband, 24_000, 24_000.0, 10.0),
+        (1, Mode::Hybrid, Bandwidth::Fullband, 32_000, 24_000.0, 10.0),
+        (2, Mode::Hybrid, Bandwidth::Fullband, 64_000, 24_000.0, 10.0),
+        (2, Mode::Celt, Bandwidth::Fullband, 96_000, 24_000.0, 10.0),
+    ];
+    for (c, mode, bw, rate, fc, min_snr) in cases {
+        let planar: Vec<Vec<f32>> = if c == 1 { vec![left.clone()] } else { vec![left.clone(), right.clone()] };
+        let (enc, packets) = encode(OpusEncoder::with_mode(c as u8, rate, mode, bw).unwrap(), &planar);
+        let file = ogg_opus(&enc, &packets, len);
+        for codec in ["opus", "libopus"] {
+            let Some(dec) = ffmpeg_decode(&exe, codec, &file, c, &format!("{mode:?}{bw:?}{c}{codec}")) else {
+                continue;
+            };
+            assert_eq!(dec.len(), len * c, "{codec}: pre-skip and end granule must be honoured");
+            for (ch, x) in planar.iter().enumerate() {
+                let d: Vec<f32> = (0..len).map(|i| dec[i * c + ch]).collect();
+                let (snr, delay) = snr_search(&lowpass(x, fc), &d, 6);
+                eprintln!("ffmpeg {codec:7} {mode:?}/{bw:?} {c} ch @ {} kb/s, channel {ch}: SNR {snr:.1} dB (residual delay {delay})", rate / 1000);
+                assert!(snr > min_snr, "{codec} {mode:?}/{bw:?}: SNR {snr:.1} dB");
+            }
+        }
+    }
+}
diff --git a/crates/audio/tests/codecs/opusenc/mod.rs b/crates/audio/tests/codecs/opusenc/mod.rs
new file mode 100644
index 000000000..f2a886463
--- /dev/null
+++ b/crates/audio/tests/codecs/opusenc/mod.rs
@@ -0,0 +1,5 @@
+//! EffectCraft's `effectcraft-opusenc` integration tests.
+
+mod common;
+mod ffmpeg;
+mod modes;
diff --git a/crates/audio/tests/codecs/opusenc/modes.rs b/crates/audio/tests/codecs/opusenc/modes.rs
new file mode 100644
index 000000000..263858560
--- /dev/null
+++ b/crates/audio/tests/codecs/opusenc/modes.rs
@@ -0,0 +1,292 @@
+//! SILK, hybrid and CELT round trips through FilmCraft's spec-derived Opus decoder: every
+//! mode/bandwidth decodes, waveform quality on speech-like and music-like signals, bitrate
+//! tracking, stereo, the application tables and delay alignment.
+
+use super::common;
+
+use common::*;
+use craft_audio::opus::encoder::{Application, Bandwidth, Error, Mode, OpusEncoder};
+
+struct Run {
+    snr: f64,
+    seg: f64,
+    delay: isize,
+    kbps: f64,
+    packets: Vec<Vec<u8>>,
+}
+
+/// Encodes `planar`, decodes, and measures each channel against `reference` (searching a
+/// residual delay of up to ±6 samples).
+fn run(enc: OpusEncoder, planar: &[Vec<f32>], reference: &[Vec<f32>]) -> Vec<Run> {
+    let (enc, packets) = encode(enc, planar);
+    let dec = decode(&enc.opus_head(), &packets);
+    let kbps = bitrate(&packets) / 1000.0;
+    reference
+        .iter()
+        .zip(&dec)
+        .map(|(r, d)| {
+            assert!(d.len() >= r.len(), "decoded {} < {}", d.len(), r.len());
+            assert!(d.iter().all(|v| v.is_finite()));
+            let (snr, delay) = snr_search(r, d, 6);
+            Run { snr, seg: seg_snr(r, d, delay), delay, kbps, packets: packets.clone() }
+        })
+        .collect()
+}
+
+fn mono(mode: Mode, bw: Bandwidth, rate: u32, x: &[f32], fc: f64) -> Run {
+    let reference = if fc < 20_000.0 { lowpass(x, fc) } else { x.to_vec() };
+    run(OpusEncoder::with_mode(1, rate, mode, bw).unwrap(), &[x.to_vec()], &[reference]).remove(0)
+}
+
+/// Upper edge of the band a SILK bandwidth keeps (for band-limited references).
+fn band_edge(bw: Bandwidth) -> f64 {
+    match bw {
+        Bandwidth::Narrowband => 3_400.0,
+        Bandwidth::Mediumband => 5_000.0,
+        Bandwidth::Wideband => 7_000.0,
+        _ => 24_000.0,
+    }
+}
+
+const LEN: usize = 96_000;
+
+#[test]
+fn every_mode_and_bandwidth_decodes() {
+    let sp = speech(LEN + 40_000, 11);
+    let left = sp[..LEN].to_vec();
+    let right: Vec<f32> = sp[40_000..].iter().map(|v| v * 0.6).collect();
+    for (mode, bw, config, rate) in [
+        (Mode::Silk, Bandwidth::Narrowband, 1u8, 8_000u32),
+        (Mode::Silk, Bandwidth::Mediumband, 5, 11_000),
+        (Mode::Silk, Bandwidth::Wideband, 9, 16_000),
+        (Mode::Hybrid, Bandwidth::SuperWideband, 13, 24_000),
+        (Mode::Hybrid, Bandwidth::Fullband, 15, 32_000),
+        (Mode::Celt, Bandwidth::Fullband, 31, 64_000),
+    ] {
+        for c in [1usize, 2] {
+            let planar = if c == 1 { vec![left.clone()] } else { vec![left.clone(), right.clone()] };
+            let reference: Vec<Vec<f32>> = planar.iter().map(|x| lowpass(x, band_edge(bw))).collect();
+            let enc = OpusEncoder::with_mode(c as u8, rate * c as u32, mode, bw).unwrap();
+            assert_eq!((enc.mode(), enc.bandwidth()), (mode, bw));
+            let res = run(enc, &planar, &reference);
+            for p in &res[0].packets {
+                assert_eq!(p[0], (config << 3) | if c == 2 { 4 } else { 0 }, "TOC of {mode:?}/{bw:?}");
+                assert!(p.len() >= 3 && p.len() <= 1276);
+            }
+            for (ch, r) in res.iter().enumerate() {
+                eprintln!(
+                    "{mode:?}/{bw:?} {c} ch @ {} kb/s: {:.1} kb/s, channel {ch} SNR {:.1} dB, segSNR {:.1} dB, residual delay {}",
+                    rate * c as u32 / 1000,
+                    r.kbps,
+                    r.snr,
+                    r.seg,
+                    r.delay
+                );
+                assert!(r.snr > 8.0, "{mode:?}/{bw:?} {c} ch channel {ch}: SNR {:.1} dB", r.snr);
+                assert!(r.delay.abs() <= 1, "{mode:?}/{bw:?}: residual delay {} (pre-skip mismatch)", r.delay);
+            }
+        }
+    }
+}
+
+#[test]
+fn silk_speech_quality() {
+    let x = speech(LEN, 7);
+    for (bw, rate, min_snr) in [
+        (Bandwidth::Narrowband, 8_000u32, 10.0),
+        (Bandwidth::Mediumband, 11_000, 14.0),
+        (Bandwidth::Wideband, 12_000, 14.0),
+        (Bandwidth::Wideband, 16_000, 18.0),
+        (Bandwidth::Wideband, 24_000, 24.0),
+    ] {
+        let r = mono(Mode::Silk, bw, rate, &x, band_edge(bw));
+        eprintln!("SILK {bw:?} speech @ {} kb/s: {:.1} kb/s, SNR {:.1} dB, segSNR {:.1} dB", rate / 1000, r.kbps, r.snr, r.seg);
+        assert!(r.snr > min_snr && r.seg > min_snr - 3.0, "SILK {bw:?} @ {rate}: SNR {:.1} / seg {:.1}", r.snr, r.seg);
+    }
+}
+
+#[test]
+fn silk_beats_celt_on_speech_at_low_rate() {
+    let x = speech(LEN, 5);
+    // Both measured against the full-band input.
+    let silk = mono(Mode::Silk, Bandwidth::Wideband, 12_000, &x, 24_000.0);
+    let celt = mono(Mode::Celt, Bandwidth::Fullband, 12_000, &x, 24_000.0);
+    eprintln!(
+        "12 kb/s mono speech: SILK WB {:.1} dB (seg {:.1}) at {:.1} kb/s vs CELT {:.1} dB (seg {:.1}) at {:.1} kb/s",
+        silk.snr, silk.seg, silk.kbps, celt.snr, celt.seg, celt.kbps
+    );
+    assert!(silk.snr > celt.snr + 3.0, "SILK {:.1} dB vs CELT {:.1} dB", silk.snr, celt.snr);
+    assert!(silk.seg > celt.seg + 3.0, "SILK seg {:.1} dB vs CELT seg {:.1} dB", silk.seg, celt.seg);
+}
+
+#[test]
+fn hybrid_quality() {
+    let sp = speech(LEN, 9);
+    let mu = music(LEN);
+    for (name, x, bw, rate, min_snr) in [
+        ("speech", &sp, Bandwidth::SuperWideband, 24_000u32, 18.0),
+        ("speech", &sp, Bandwidth::Fullband, 32_000, 20.0),
+        ("music", &mu, Bandwidth::SuperWideband, 24_000, 9.0),
+        ("music", &mu, Bandwidth::Fullband, 32_000, 10.0),
+    ] {
+        let r = mono(Mode::Hybrid, bw, rate, x, 24_000.0);
+        eprintln!("hybrid {bw:?} {name} @ {} kb/s: {:.1} kb/s, SNR {:.1} dB, segSNR {:.1} dB", rate / 1000, r.kbps, r.snr, r.seg);
+        assert!(r.snr > min_snr, "hybrid {bw:?} {name}: SNR {:.1} dB", r.snr);
+        // Constant packet size.
+        assert!(r.packets.iter().all(|p| p.len() == rate as usize / 400));
+    }
+}
+
+#[test]
+fn silk_music_quality() {
+    let x = music(LEN);
+    for (rate, min_snr) in [(12_000u32, 5.0), (16_000, 8.0), (24_000, 13.0)] {
+        let r = mono(Mode::Silk, Bandwidth::Wideband, rate, &x, 7_000.0);
+        eprintln!("SILK WB music @ {} kb/s: {:.1} kb/s, SNR {:.1} dB", rate / 1000, r.kbps, r.snr);
+        assert!(r.snr > min_snr, "SILK music @ {rate}: SNR {:.1} dB", r.snr);
+    }
+}
+
+#[test]
+fn bitrate_tracking() {
+    let sp = speech(LEN, 13);
+    let mu = music(LEN);
+    for (name, x) in [("speech", &sp), ("music", &mu)] {
+        for (mode, bw, rate) in [
+            (Mode::Silk, Bandwidth::Narrowband, 6_000u32),
+            (Mode::Silk, Bandwidth::Narrowband, 9_000),
+            (Mode::Silk, Bandwidth::Mediumband, 11_000),
+            (Mode::Silk, Bandwidth::Wideband, 12_000),
+            (Mode::Silk, Bandwidth::Wideband, 20_000),
+            (Mode::Silk, Bandwidth::Wideband, 32_000),
+            (Mode::Hybrid, Bandwidth::SuperWideband, 20_000),
+            (Mode::Hybrid, Bandwidth::Fullband, 36_000),
+        ] {
+            let r = mono(mode, bw, rate, x, band_edge(bw));
+            let ratio = r.kbps * 1000.0 / rate as f64;
+            eprintln!(
+                "{name} {mode:?}/{bw:?} target {} kb/s: actual {:.2} kb/s ({:+.0} %), SNR {:.1} dB",
+                rate / 1000,
+                r.kbps,
+                (ratio - 1.0) * 100.0,
+                r.snr
+            );
+            assert!((0.75..=1.25).contains(&ratio), "{name} {mode:?}/{bw:?} @ {rate}: {:.2} kb/s", r.kbps);
+        }
+    }
+}
+
+#[test]
+fn stereo_silk_and_hybrid() {
+    let sp = speech(LEN + 40_000, 21);
+    let a = sp[..LEN].to_vec();
+    let b: Vec<f32> = sp[40_000..].iter().map(|v| v * 0.7).collect();
+    let mu = music(LEN);
+    let cases: Vec<(&str, Vec<f32>, Vec<f32>)> = vec![
+        ("dual mono", a.clone(), a.clone()),
+        ("panned", a.iter().map(|v| v * 0.9).collect(), a.iter().map(|v| v * 0.35).collect()),
+        ("independent", a.clone(), b),
+        ("speech+music", a.iter().zip(&mu).map(|(x, y)| 0.8 * x + 0.3 * y).collect(), a.iter().zip(&mu).map(|(x, y)| 0.3 * x + 0.8 * y).collect()),
+    ];
+    for (name, l, r) in &cases {
+        for (mode, bw, rate, min_snr) in [(Mode::Silk, Bandwidth::Wideband, 32_000u32, 9.0), (Mode::Hybrid, Bandwidth::Fullband, 64_000, 9.0)] {
+            let fc = band_edge(bw);
+            let res = run(OpusEncoder::with_mode(2, rate, mode, bw).unwrap(), &[l.clone(), r.clone()], &[lowpass(l, fc), lowpass(r, fc)]);
+            eprintln!(
+                "stereo {name} {mode:?}/{bw:?} @ {} kb/s: {:.1} kb/s, L {:.1} dB, R {:.1} dB",
+                rate / 1000,
+                res[0].kbps,
+                res[0].snr,
+                res[1].snr
+            );
+            assert!(res[0].snr > min_snr && res[1].snr > min_snr, "stereo {name} {mode:?}: L {:.1} R {:.1}", res[0].snr, res[1].snr);
+        }
+    }
+}
+
+#[test]
+fn application_tables_and_pre_skip() {
+    let cases = [
+        (Application::Voip, 1u8, 8_000u32, Mode::Silk, Bandwidth::Narrowband),
+        (Application::Voip, 1, 11_000, Mode::Silk, Bandwidth::Mediumband),
+        (Application::Voip, 1, 16_000, Mode::Silk, Bandwidth::Wideband),
+        (Application::Voip, 1, 24_000, Mode::Hybrid, Bandwidth::SuperWideband),
+        (Application::Voip, 1, 32_000, Mode::Hybrid, Bandwidth::Fullband),
+        (Application::Voip, 1, 48_000, Mode::Celt, Bandwidth::Fullband),
+        (Application::Voip, 2, 32_000, Mode::Silk, Bandwidth::Wideband),
+        (Application::Audio, 1, 12_000, Mode::Silk, Bandwidth::Wideband),
+        (Application::Audio, 1, 24_000, Mode::Hybrid, Bandwidth::Fullband),
+        (Application::Audio, 2, 48_000, Mode::Hybrid, Bandwidth::Fullband),
+        (Application::Audio, 1, 64_000, Mode::Celt, Bandwidth::Fullband),
+        (Application::Audio, 2, 128_000, Mode::Celt, Bandwidth::Fullband),
+    ];
+    for (app, c, rate, mode, bw) in cases {
+        let e = OpusEncoder::with_application(c, rate, app).unwrap();
+        assert_eq!((e.mode(), e.bandwidth(), e.application()), (mode, bw, app), "{app:?} {c} ch @ {rate}");
+        assert_eq!(e.pre_skip(), 120, "every mode is aligned to a 120-sample delay");
+    }
+    assert_eq!(OpusEncoder::new(2, 128_000).unwrap().mode(), Mode::Celt);
+    assert_eq!(OpusEncoder::new(1, 12_000).unwrap().application(), Application::Audio);
+}
+
+/// EffectCraft's encoder panicked here; craft-audio returns an error (never crash).
+#[test]
+fn invalid_mode_bandwidth_is_an_error() {
+    assert_eq!(OpusEncoder::with_mode(1, 16_000, Mode::Silk, Bandwidth::Fullband).err(), Some(Error::ModeBandwidth(Mode::Silk, Bandwidth::Fullband)));
+    assert_eq!(OpusEncoder::new(3, 128_000).err(), Some(Error::Channels(3)));
+    assert_eq!(OpusEncoder::new(0, 128_000).err(), Some(Error::Channels(0)));
+    // From 86 channels the per-channel minimum bitrate passes the 510 kb/s cap.
+    for channels in [86, u8::MAX] {
+        assert_eq!(OpusEncoder::new(channels, 128_000).err(), Some(Error::Channels(channels)));
+        let app = OpusEncoder::with_application(channels, 128_000, Application::Voip).err();
+        assert_eq!(app, Some(Error::Channels(channels)));
+    }
+}
+
+#[test]
+fn extreme_inputs_stay_decodable() {
+    let len = 24_000;
+    let mut s = 1u32;
+    let noise: Vec<f32> = (0..len)
+        .map(|_| {
+            s = s.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
+            (s >> 8) as f32 / (1u32 << 23) as f32 - 1.0
+        })
+        .collect();
+    let square: Vec<f32> = (0..len).map(|i| if (i / 60) % 2 == 0 { 0.999 } else { -0.999 }).collect();
+    let clicks: Vec<f32> = (0..len).map(|i| if i % 4_801 == 0 { 1.0 } else { 0.0 }).collect();
+    let dc = vec![0.7f32; len];
+    let nan: Vec<f32> = (0..len).map(|i| if i % 1000 == 0 { f32::NAN } else { 0.1 * (i as f32 * 0.01).sin() }).collect();
+    for (name, x) in [("noise", &noise), ("square", &square), ("clicks", &clicks), ("dc", &dc), ("nan", &nan)] {
+        for (mode, bw, rate) in
+            [(Mode::Silk, Bandwidth::Narrowband, 6_000u32), (Mode::Silk, Bandwidth::Wideband, 40_000), (Mode::Hybrid, Bandwidth::Fullband, 24_000)]
+        {
+            for c in [1usize, 2] {
+                let planar: Vec<Vec<f32>> = if c == 1 { vec![x.clone()] } else { vec![x.clone(), x.iter().map(|v| -0.5 * v).collect()] };
+                let (enc, packets) = encode(OpusEncoder::with_mode(c as u8, rate * c as u32, mode, bw).unwrap(), &planar);
+                assert!(packets.iter().all(|p| p.len() >= 3 && p.len() <= 1276), "{name} {mode:?}: packet sizes");
+                let dec = decode(&enc.opus_head(), &packets);
+                let peak = dec.iter().flatten().fold(0f32, |m, v| m.max(v.abs()));
+                let snr = if name == "nan" { f64::NAN } else { snr_search(&planar[0], &dec[0], 2).0 };
+                eprintln!("{name} {mode:?}/{bw:?} {c} ch: peak {peak:.2}, SNR {snr:.1} dB, {:.1} kb/s", bitrate(&packets) / 1000.0);
+                assert!(dec.iter().all(|ch| ch.iter().all(|v| v.is_finite() && v.abs() <= 4.0)), "{name} {mode:?}/{bw:?} {c} ch: bad output");
+            }
+        }
+    }
+}
+
+#[test]
+fn silk_and_hybrid_silence() {
+    for (mode, bw, rate) in [(Mode::Silk, Bandwidth::Wideband, 16_000u32), (Mode::Hybrid, Bandwidth::Fullband, 32_000)] {
+        let x = vec![0f32; 48_000];
+        let (enc, packets) = encode(OpusEncoder::with_mode(1, rate, mode, bw).unwrap(), std::slice::from_ref(&x));
+        let dec = decode(&enc.opus_head(), &packets);
+        let peak = dec[0].iter().fold(0f32, |m, v| m.max(v.abs()));
+        let kbps = bitrate(&packets) / 1000.0;
+        eprintln!("{mode:?} silence: {kbps:.2} kb/s, decoded peak {peak:.2e}");
+        assert!(peak < 1e-3, "{mode:?} silence decodes to peak {peak}");
+        if mode == Mode::Silk {
+            assert!(kbps < 4.0, "SILK silence costs {kbps:.2} kb/s");
+        }
+    }
+}
diff --git a/crates/audio/tests/codecs/track_decoder.rs b/crates/audio/tests/codecs/track_decoder.rs
index 0607db4ac..fee8f1f97 100644
--- a/crates/audio/tests/codecs/track_decoder.rs
+++ b/crates/audio/tests/codecs/track_decoder.rs
@@ -1,7 +1,8 @@
 //! `TrackDecoder` on streams an app's own demuxer hands over without codec configuration:
-//! ADTS-framed AAC (MPEG-TS).
+//! ADTS-framed AAC (MPEG-TS) and Opus without an `OpusHead` (RTP).
 
 use craft_audio::aac::{Encoder as AacEncoder, EncoderConfig};
+use craft_audio::opus::Encoder as OpusEncoder;
 use craft_audio::{CodecId, CodecParams, TrackDecoder};
 
 fn tone(n: usize) -> Vec<f32> {
@@ -32,3 +33,20 @@ fn adts_aac_without_extradata() {
     let raw = &units[0][7..];
     assert!(TrackDecoder::new(&CodecParams::new(CodecId::Aac), &[raw]).is_err());
 }
+
+#[test]
+fn opus_without_opus_head() {
+    let mut enc = OpusEncoder::new(1, 64_000).unwrap();
+    let pcm = tone(OpusEncoder::FRAME_SIZE * 10);
+    let packets: Vec<Vec<u8>> = pcm.chunks(OpusEncoder::FRAME_SIZE).map(|f| enc.encode_float(f).unwrap()).collect();
+
+    let params = CodecParams::new(CodecId::Opus).with_channels(1).with_sample_rate(48_000);
+    let mut dec = TrackDecoder::new(&params, &[]).unwrap();
+    assert_eq!((dec.sample_rate(), dec.channels()), (48_000, 1));
+    for p in &packets {
+        assert_eq!(dec.decode(p).unwrap().frames(), OpusEncoder::FRAME_SIZE);
+    }
+
+    // More than two channels need the mapping an OpusHead carries.
+    assert!(TrackDecoder::new(&CodecParams::new(CodecId::Opus).with_channels(6), &[]).is_err());
+}
diff --git a/crates/csv/README.md b/crates/csv/README.md
index c677ec9eb..6369ce8b4 100644
--- a/crates/csv/README.md
+++ b/crates/csv/README.md
@@ -11,7 +11,7 @@ mapping a SYLK sheet onto a document are the caller's work.
 | Function | What it does |
 |---|---|
 | `decode_text(bytes)` | UTF-8 and UTF-16 byte order marks; without one, valid UTF-8 is kept; other bytes are Windows-1256 when they read as Arabic, else Windows-1252 |
-| `sniff_delimiter(text, quote)` | comma, semicolon or tab: the one with the most consistent count per line over the first 20 non-blank lines, outside quotes |
+| `sniff_delimiter(text, quote)` | comma, semicolon or tab: the one with the most consistent field count over the first 20 non-blank records in a 64 KiB sample; quote boundaries must be coherent, and ties prefer tab, comma, then semicolon |
 | `parse_records(text, delim, quote, max_fields, on_record)` | records of fields, one callback per record (return `false` to stop); CR, LF and CRLF line ends; quoted fields with doubled quotes and line breaks; a quote in the middle of a field is text |
 | `records(text, delim, quote, max_records, max_fields)` | the same, collected |
 | `push_field(out, field, delim)`, `field_len(field, delim)` | one field as written, quoted only when it holds the delimiter, a quote or a line break; its exact length, to enforce a size cap before writing |
diff --git a/crates/csv/src/decode.rs b/crates/csv/src/decode.rs
index 238f7f18e..63b4bb590 100644
--- a/crates/csv/src/decode.rs
+++ b/crates/csv/src/decode.rs
@@ -19,6 +19,16 @@ const CP1256: [u32; 128] = [
     0x200F, 0x06D2,
 ];
 
+/// Decode strictly as UTF-8, stripping a leading UTF-8 BOM when present.
+///
+/// Unlike [`decode_text`], this does not guess a legacy encoding or accept UTF-16. It is useful
+/// when a format or application contract requires UTF-8 and malformed bytes must be rejected.
+pub fn decode_utf8(bytes: &[u8]) -> Result<String, std::str::Utf8Error> {
+    let bytes = bytes.strip_prefix(&[0xEF, 0xBB, 0xBF]).unwrap_or(bytes);
+    let text = std::str::from_utf8(bytes)?;
+    Ok(text.strip_prefix('\u{FEFF}').unwrap_or(text).to_string())
+}
+
 /// Evidence that bytes which aren't UTF-8 are Windows-1256 Arabic rather than Windows-1252.
 #[derive(Default)]
 struct Cp1256Evidence {
@@ -165,6 +175,16 @@ mod tests {
         assert_eq!(decode_text(&[0xFF, 0xFE, 0x00, 0xD8]), "\u{FFFD}", "a lone surrogate");
     }
 
+    #[test]
+    fn strict_utf8_strips_bom_and_rejects_legacy_or_malformed_bytes() {
+        assert_eq!(decode_utf8(b"\xEF\xBB\xBFName,City\nAda,Town\n").unwrap(), "Name,City\nAda,Town\n");
+        assert_eq!(decode_utf8("café".as_bytes()).unwrap(), "café");
+        assert!(decode_utf8(&[0xFF, 0xFE, 0x00]).is_err());
+        assert!(decode_utf8(b"\xEF\xBB\xBF\xFF").is_err());
+        // The permissive text decoder still accepts legacy encodings for callers that want it.
+        assert_eq!(decode_text(&[0x80, b'a', 0xE9]), "€aé");
+    }
+
     #[test]
     fn windows_1256_table_matches_the_unicode_mapping() {
         let at = |b: u8| CP1256.get(usize::from(b - 0x80)).and_then(|&c| char::from_u32(c));
diff --git a/crates/csv/src/lib.rs b/crates/csv/src/lib.rs
index a773f066f..0aec971ac 100644
--- a/crates/csv/src/lib.rs
+++ b/crates/csv/src/lib.rs
@@ -3,6 +3,7 @@
 //!
 //! - [`decode_text`] turns a file's bytes into a string: byte order marks, UTF-8, else
 //!   Windows-1256 when the bytes read as Arabic and Windows-1252 otherwise.
+//! - [`decode_utf8`] requires valid UTF-8 and strips a leading UTF-8 byte order mark.
 //! - [`sniff_delimiter`] picks comma, semicolon or tab.
 //! - [`parse_records`] splits text into records of fields (RFC 4180 with the usual leniency),
 //!   handing each record to a callback, with a cap on the fields kept per record. [`records`]
@@ -27,46 +28,98 @@
 mod decode;
 pub mod sylk;
 
-pub use decode::decode_text;
+pub use decode::{decode_text, decode_utf8};
 
-/// Picks comma, semicolon or tab: the candidate with the most consistent count per line
-/// (outside quotes) over the first non-blank lines. A candidate must appear on every such line, otherwise comma wins.
+/// Picks comma, semicolon or tab by consistent field counts in the first non-blank records.
+/// Quotes start only at a candidate field boundary; candidates with incoherent quoted fields
+/// are discarded when another coherent candidate separates the records. Ties prefer tab,
+/// then comma, then semicolon. Comma is the fallback when no candidate separates the text.
 pub fn sniff_delimiter(text: &str, quote: char) -> u8 {
-    let mut best = (b',', 0usize, 0usize);
-    for d in [',', ';', '\t'] {
-        let mut counts = vec![];
-        let mut n = 0usize;
-        let mut in_q = false;
-        let mut blank = true;
-        for ch in text.chars().take(64 * 1024) {
-            if !in_q && ch == '\n' {
-                // Blank lines carry no delimiter evidence.
-                if !blank {
-                    counts.push(n);
-                }
-                n = 0;
-                blank = true;
-                if counts.len() >= 20 {
-                    break;
+    let mut candidates = [(b'\t', 0usize, 0usize, true), (b',', 0, 0, true), (b';', 0, 0, true)];
+    const SAMPLE_BYTES: usize = 64 * 1024;
+    let mut sample_end = text.len().min(SAMPLE_BYTES);
+    while !text.is_char_boundary(sample_end) {
+        sample_end -= 1;
+    }
+    let sample = &text[..sample_end];
+    let truncated = sample_end < text.len();
+    for (delimiter, min_count, total, coherent) in &mut candidates {
+        let mut counts = Vec::new();
+        let mut count = 0usize;
+        let mut quoted = false;
+        let mut after_quote = false;
+        let mut field_start = true;
+        let mut record_has_content = false;
+        let mut record_coherent = true;
+        let mut candidate_coherent = true;
+        let mut reached_record_limit = false;
+        let mut chars = sample.chars().peekable();
+        while let Some(ch) = chars.next() {
+            if quoted {
+                if ch == quote {
+                    if chars.peek() == Some(&quote) {
+                        chars.next();
+                        record_has_content = true;
+                    } else {
+                        quoted = false;
+                        after_quote = true;
+                    }
+                } else if !ch.is_whitespace() {
+                    record_has_content = true;
                 }
                 continue;
             }
-            if ch != '\r' {
-                blank = false;
+            if ch == '\r' || ch == '\n' {
+                if ch == '\r' && chars.peek() == Some(&'\n') {
+                    chars.next();
+                }
+                if record_has_content {
+                    counts.push(count);
+                    candidate_coherent &= record_coherent;
+                    if counts.len() >= 20 {
+                        reached_record_limit = true;
+                        break;
+                    }
+                }
+                count = 0;
+                quoted = false;
+                after_quote = false;
+                field_start = true;
+                record_has_content = false;
+                record_coherent = true;
+                continue;
             }
-            if ch == quote {
-                in_q = !in_q;
-            } else if !in_q && ch == d {
-                n += 1;
+            if ch == quote && field_start {
+                quoted = true;
+                field_start = false;
+                record_has_content = true;
+            } else if ch == char::from(*delimiter) {
+                count += 1;
+                field_start = true;
+                after_quote = false;
+            } else {
+                record_coherent &= !after_quote || ch.is_whitespace();
+                record_has_content |= !ch.is_whitespace();
+                field_start = false;
             }
         }
-        if !blank {
-            counts.push(n);
+        if !reached_record_limit && !truncated {
+            if quoted {
+                candidate_coherent = false;
+            } else if record_has_content {
+                candidate_coherent &= record_coherent;
+                counts.push(count);
+            }
         }
-        let min = counts.iter().copied().min().unwrap_or(0);
-        let total: usize = counts.iter().sum();
-        if min > 0 && (min, total) > (best.1, best.2) {
-            best = (d as u8, min, total);
+        *coherent &= candidate_coherent;
+        *min_count = counts.iter().copied().min().unwrap_or(0);
+        *total = counts.iter().sum();
+    }
+    let prefer_coherent = candidates.iter().any(|(_, min, _, coherent)| *min > 0 && *coherent);
+    let mut best = (b',', 0usize, 0usize);
+    for (delimiter, min, total, coherent) in candidates {
+        if min > 0 && (!prefer_coherent || coherent) && (min, total) > (best.1, best.2) {
+            best = (delimiter, min, total);
         }
     }
     best.0
@@ -204,6 +257,9 @@ mod tests {
         assert_eq!(sniff_delimiter("a\tb\n1\t2\n", '"'), b'\t');
         assert_eq!(sniff_delimiter("a,b\n\"x;y;z\",2\n", '"'), b',');
         assert_eq!(sniff_delimiter("single", '"'), b',');
+        assert_eq!(sniff_delimiter("a,b\tc\n1,2\td\n", '"'), b'\t');
+        assert_eq!(sniff_delimiter("a,b;c\n1,2;c\n", '"'), b',');
+        assert_eq!(sniff_delimiter("a;b\tc\n1;2\td\n", '"'), b'\t');
         // A delimiter missing from some lines is text, not a separator (single-column export round trip).
         assert_eq!(sniff_delimiter("alpha;beta\r\ngamma\r\n", '"'), b',');
         assert_eq!(sniff_delimiter("alpha\tbeta\r\ngamma\r\n", '"'), b',');
@@ -211,6 +267,48 @@ mod tests {
         assert_eq!(sniff_delimiter("x;y\n1,5;2", '"'), b';');
     }
 
+    #[test]
+    fn delimiter_sniffing_preserves_candidate_quote_boundaries() {
+        for ending in ["\n", "\r\n", "\r"] {
+            for (text, expected) in [
+                (format!("Name,\"preferred\tCity\"{ending}Ada\tLondon{ending}"), b'\t'),
+                (format!("\"Last, First\";City{ending}Ada;London{ending}"), b';'),
+                (format!("\"Name\";\"Last, First\"{ending}\"Ada\";\"Lovelace, Countess\"{ending}\"Grace\";\"Hopper, Admiral\"{ending}"), b';'),
+                (format!("\"Name\"suffix,Title\tCity{ending}\"Ada\"suffix,Analyst\tLondon\tignored{ending}"), b'\t'),
+                (format!("\r\n \r\n\"Name\";City{ending}Ada;London{ending}"), b';'),
+            ] {
+                assert_eq!(sniff_delimiter(&text, '"'), expected, "{text:?}");
+            }
+        }
+    }
+
+    #[test]
+    fn delimiter_sniffing_counts_empty_quoted_fields_and_ignores_whitespace_records() {
+        assert_eq!(sniff_delimiter("\"\";name\n\"\";Ada\n", '"'), b';');
+
+        let blank_rows = "\t \t\n".repeat(25);
+        assert_eq!(sniff_delimiter(&format!("{blank_rows}a;b\nc;d\n"), '"'), b';');
+    }
+
+    #[test]
+    fn delimiter_sniffing_does_not_count_the_twentieth_record_twice() {
+        let mut text = "a;b\tc\td\n".repeat(19);
+        text.push('a');
+        text.push_str(&";".repeat(19));
+        text.push_str("\tc\n");
+        assert_eq!(sniff_delimiter(&text, '"'), b'\t');
+    }
+
+    #[test]
+    fn delimiter_sniffing_discards_an_incomplete_record_at_the_sample_boundary() {
+        let complete = "a\tb\tc\n1\t2\t3\n";
+        let remaining = 64 * 1024 - complete.len();
+        let partial = format!("{}x\t\"unfinished", "z".repeat(remaining - 4));
+        assert!(partial.len() >= remaining);
+        let text = format!("{complete}{partial}\"\n");
+        assert_eq!(sniff_delimiter(&text, '"'), b'\t');
+    }
+
     #[test]
     fn parser_stops_collecting_fields_at_the_cap() {
         let (max, extra) = (16_384usize, 50);
diff --git a/crates/dav/src/lib.rs b/crates/dav/src/lib.rs
index 87040feae..db137a050 100644
--- a/crates/dav/src/lib.rs
+++ b/crates/dav/src/lib.rs
@@ -74,7 +74,14 @@ pub fn parse_multistatus(bytes: &[u8]) -> Result<El, Error> {
     if !text.chars().all(craft_xml::is_xml_char) {
         return Err(Error::Characters);
     }
-    let limits = Limits { max_input: MAX_BYTES, max_depth: MAX_DEPTH, max_nodes: MAX_NODES, max_attrs: MAX_ATTRS, max_attrs_total: MAX_ATTRS_TOTAL };
+    let limits = Limits {
+        max_input: MAX_BYTES,
+        max_depth: MAX_DEPTH,
+        max_nodes: MAX_NODES,
+        max_elements: MAX_NODES,
+        max_attrs: MAX_ATTRS,
+        max_attrs_total: MAX_ATTRS_TOTAL,
+    };
     let options = Options { doctype: Doctype::Reject, ..Options::canonical(&CANONICAL).strict().with_limits(limits) };
     let root = options.parse(bytes).map_err(Error::Xml)?;
     if root.name != "d:multistatus" {
diff --git a/crates/designcraft-format/Cargo.toml b/crates/designcraft-format/Cargo.toml
new file mode 100644
index 000000000..19557b7ae
--- /dev/null
+++ b/crates/designcraft-format/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+name = "craft-designcraft-format"
+description = "Versioned DesignCraft document JSON codec and legacy migrations over craft-document-bundle"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+craft-document-bundle = { workspace = true }
+craft-eps = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
diff --git a/crates/designcraft-format/src/lib.rs b/crates/designcraft-format/src/lib.rs
new file mode 100644
index 000000000..6256eab1c
--- /dev/null
+++ b/crates/designcraft-format/src/lib.rs
@@ -0,0 +1,251 @@
+//! Versioned JSON and bundle codec for DesignCraft's native document format.
+//!
+//! The application owns its document model. This crate owns the on-disk schema version,
+//! serialization, legacy JSON upgrades, version inference and the shared ZIP envelope.
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+#![forbid(unsafe_code)]
+
+use std::collections::{HashMap, HashSet};
+use std::io::{Read, Seek};
+
+pub use craft_document_bundle::Asset;
+use craft_document_bundle::Spec;
+use serde::{Serialize, de::DeserializeOwned};
+use serde_json::Value;
+
+pub const MIME: &str = "application/vnd.designcraft+zip";
+pub const VERSION: u32 = 4;
+pub const EXTENSION: &str = "designcraft";
+pub const PREVIEW: &str = "preview.png";
+pub const MAX_PREVIEW_BYTES: u64 = 4 << 20;
+
+const BUNDLE: Spec<'static> = Spec {
+    mimetype_entry: "mimetype",
+    mimetype: MIME,
+    metadata_entry: "meta.json",
+    document_entry: "document.json",
+    preview_entry: PREVIEW,
+    assets_directory: "assets",
+    format_name: "designcraft",
+    legacy_assets_field: Some("assetData"),
+};
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error("not a DesignCraft document: {0}")]
+    NotOurs(String),
+    #[error("document is from a newer DesignCraft (format {0}); please update")]
+    TooNew(u64),
+    #[error("{0}")]
+    Io(String),
+    #[error("document cannot be saved: {0}")]
+    Unsaveable(String),
+}
+
+impl From<craft_document_bundle::Error> for Error {
+    fn from(error: craft_document_bundle::Error) -> Self {
+        match error {
+            craft_document_bundle::Error::TooNew(version) => Error::TooNew(version),
+            craft_document_bundle::Error::NotBundle(message) => Error::NotOurs(message),
+            craft_document_bundle::Error::Read(message) | craft_document_bundle::Error::Write(message) => Error::Io(message),
+        }
+    }
+}
+
+/// A decoded native document and the separately stored embedded assets.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Loaded<T> {
+    pub document: T,
+    pub assets: Vec<(String, Vec<u8>)>,
+}
+
+/// The reader capability required by `document`, inferred from its neutral JSON schema and
+/// embedded assets. Traversal beyond 64 levels conservatively requires version 4.
+pub fn required_version(document: &Value, assets: &[Asset<'_>]) -> u32 {
+    if has_version_four_feature(document) {
+        return 4;
+    }
+    if assets.iter().any(|asset| craft_eps::is_eps(asset.data)) { 3 } else { 2 }
+}
+
+/// Serialize a document and its external assets as a `.designcraft` ZIP bundle.
+pub fn save<T: Serialize>(document: &T, generator: &str, preview: Option<&[u8]>, assets: &[Asset<'_>]) -> Result<Vec<u8>, Error> {
+    let value = serde_json::to_value(document).map_err(|error| Error::Io(error.to_string()))?;
+    let version = required_version(&value, assets);
+    let json = serde_json::to_vec_pretty(&value).map_err(|error| Error::Io(error.to_string()))?;
+    craft_document_bundle::write(&json, version, generator, preview, assets, BUNDLE).map_err(Into::into)
+}
+
+/// Read a `.designcraft` ZIP or legacy single-file JSON, applying all versioned schema migrations
+/// before deserializing the caller's model.
+pub fn load<T: DeserializeOwned>(bytes: &[u8]) -> Result<Loaded<T>, Error> {
+    let mut package = craft_document_bundle::read(bytes, VERSION, BUNDLE)?;
+    upgrade_legacy_json(&mut package.document, package.version);
+    let document = serde_json::from_value(package.document).map_err(|error| Error::NotOurs(error.to_string()))?;
+    Ok(Loaded { document, assets: package.assets })
+}
+
+/// Whether `bytes` are a native DesignCraft ZIP package.
+pub fn is_designcraft(bytes: &[u8]) -> bool {
+    craft_document_bundle::has_document(bytes, BUNDLE)
+}
+
+/// Whether `prefix` begins with this format's stored mimetype entry.
+pub fn starts_designcraft(prefix: &[u8]) -> bool {
+    craft_document_bundle::starts_with_mimetype(prefix, BUNDLE)
+}
+
+/// Read the first-page PNG preview from a ZIP package, with a fixed 4 MiB cap.
+pub fn read_preview<R: Read + Seek>(reader: R) -> Option<Vec<u8>> {
+    craft_document_bundle::read_preview_from(reader, PREVIEW)
+}
+
+fn has_version_four_feature(document: &Value) -> bool {
+    let mut stack = vec![(document, 0usize)];
+    let mut visited = 0usize;
+    while let Some((value, depth)) = stack.pop() {
+        if depth > 64 || visited >= 1_000_000 {
+            return true;
+        }
+        visited += 1;
+        match value {
+            Value::Object(object) => {
+                if object.get("layerOptions").is_some_and(|options| !options.is_null())
+                    || (object.get("pdfLayerOverride").and_then(Value::as_bool) == Some(true)
+                        && object.get("pdfHiddenLayers").and_then(Value::as_array).is_none_or(Vec::is_empty))
+                {
+                    return true;
+                }
+                stack.extend(object.values().map(|child| (child, depth + 1)));
+            }
+            Value::Array(children) => stack.extend(children.iter().map(|child| (child, depth + 1))),
+            _ => {}
+        }
+    }
+    false
+}
+
+fn upgrade_legacy_json(document: &mut Value, from: u64) {
+    let mut vertical = HashSet::new();
+    vertical_frames(document, &mut vertical, 0);
+    if let Some(stories) = document.get_mut("stories").and_then(Value::as_object_mut) {
+        for story in stories.values_mut() {
+            let first = story.get("frames").and_then(|frames| frames.get(0)).and_then(Value::as_u64);
+            if let (Some(frame), Some(story)) = (first, story.as_object_mut())
+                && vertical.contains(&frame)
+                && !story.contains_key("vertical")
+            {
+                story.insert("vertical".into(), Value::Bool(true));
+            }
+        }
+    }
+    if from < 2 {
+        pin_paragraph_defaults(document);
+    }
+}
+
+fn vertical_frames(value: &Value, out: &mut HashSet<u64>, depth: usize) {
+    if depth > 256 {
+        return;
+    }
+    match value {
+        Value::Object(object) => {
+            if let (Some(id), Some(content)) = (object.get("id").and_then(Value::as_u64), object.get("content"))
+                && content.get("type").and_then(Value::as_str) == Some("text")
+                && content.get("options").and_then(|options| options.get("vertical")).and_then(Value::as_bool) == Some(true)
+            {
+                out.insert(id);
+            }
+            for child in object.values() {
+                vertical_frames(child, out, depth + 1);
+            }
+        }
+        Value::Array(children) => {
+            for child in children {
+                vertical_frames(child, out, depth + 1);
+            }
+        }
+        _ => {}
+    }
+}
+
+fn pin_paragraph_defaults(document: &mut Value) {
+    const MAX_STYLE_DEPTH: usize = 64;
+    let styles = document.pointer("/styles/paragraph").and_then(Value::as_array).cloned().unwrap_or_default();
+    let mut by_name: HashMap<String, (Option<String>, bool, bool)> = HashMap::new();
+    for style in &styles {
+        let Some(name) = style.get("name").and_then(Value::as_str) else { continue };
+        let based_on = style.get("basedOn").and_then(Value::as_str).map(str::to_string);
+        let attrs = style.get("para");
+        let missing_keep = attrs.and_then(|attrs| attrs.get("keepAllLines")).is_none();
+        let missing_drop_cap = attrs.and_then(|attrs| attrs.get("dropCapAlignLeft")).is_none();
+        by_name.entry(name.to_string()).or_insert((based_on, missing_keep, missing_drop_cap));
+    }
+
+    let mut roots = HashSet::new();
+    for name in by_name.keys() {
+        let mut chain = Vec::new();
+        let mut seen = HashSet::new();
+        let mut current = Some(name.as_str());
+        while let Some(style_name) = current {
+            let Some((based_on, missing_keep, missing_drop_cap)) = by_name.get(style_name) else { break };
+            if chain.len() >= MAX_STYLE_DEPTH || !seen.insert(style_name.to_string()) {
+                break;
+            }
+            chain.push((style_name, *missing_keep, *missing_drop_cap));
+            current = based_on.as_deref();
+        }
+        if !chain.is_empty()
+            && chain.iter().all(|(_, keep, drop_cap)| *keep && *drop_cap)
+            && let Some((root, _, _)) = chain.last()
+        {
+            roots.insert((*root).to_string());
+        }
+    }
+    if let Some(styles) = document.pointer_mut("/styles/paragraph").and_then(Value::as_array_mut) {
+        for style in styles {
+            if let Some(style) = style.as_object_mut()
+                && style.get("name").and_then(Value::as_str).is_some_and(|name| roots.contains(name))
+            {
+                let attrs = style.entry("para").or_insert_with(|| Value::Object(Default::default()));
+                if let Some(attrs) = attrs.as_object_mut() {
+                    attrs.entry("keepAllLines").or_insert(Value::Bool(true));
+                    attrs.entry("dropCapAlignLeft").or_insert(Value::Bool(false));
+                }
+            }
+        }
+    }
+    let known_styles: HashSet<String> = by_name.into_keys().collect();
+    pin_unstyled_paragraphs(document, &known_styles, 0);
+}
+
+fn pin_unstyled_paragraphs(value: &mut Value, known_styles: &HashSet<String>, depth: usize) {
+    if depth > 256 {
+        return;
+    }
+    match value {
+        Value::Object(object) => {
+            if let Some(style) = object.get("style").and_then(Value::as_str)
+                && !known_styles.contains(style)
+            {
+                let attrs = object.entry("para").or_insert_with(|| Value::Object(Default::default()));
+                if let Some(attrs) = attrs.as_object_mut() {
+                    attrs.entry("keepAllLines").or_insert(Value::Bool(true));
+                    attrs.entry("dropCapAlignLeft").or_insert(Value::Bool(false));
+                }
+            }
+            for child in object.values_mut() {
+                pin_unstyled_paragraphs(child, known_styles, depth + 1);
+            }
+        }
+        Value::Array(children) => {
+            for child in children {
+                pin_unstyled_paragraphs(child, known_styles, depth + 1);
+            }
+        }
+        _ => {}
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/designcraft-format/src/tests.rs b/crates/designcraft-format/src/tests.rs
new file mode 100644
index 000000000..0ef2ca191
--- /dev/null
+++ b/crates/designcraft-format/src/tests.rs
@@ -0,0 +1,72 @@
+use super::*;
+use serde_json::json;
+
+#[test]
+fn native_bundle_roundtrips_document_assets_and_preview() -> Result<(), Box<dyn std::error::Error>> {
+    let document = json!({"title":"A page", "assets":{"7":{"mime":"image/png"}}});
+    let image = [1u8, 2, 3, 4];
+    let assets = [Asset { id: "7", mime: "image/png", data: &image }];
+    let preview = b"preview png";
+    let bytes = save(&document, "DesignCraft test", Some(preview), &assets)?;
+
+    assert!(is_designcraft(&bytes));
+    assert!(starts_designcraft(&bytes[..bytes.len().min(80)]));
+    let loaded = load::<Value>(&bytes)?;
+    assert_eq!(loaded.document, document);
+    assert_eq!(loaded.assets, [("7".to_owned(), image.to_vec())]);
+    assert_eq!(read_preview(std::io::Cursor::new(&bytes)).as_deref(), Some(&preview[..]));
+    Ok(())
+}
+
+#[test]
+fn preview_reader_rejects_an_entry_over_its_declared_read_budget() -> Result<(), Box<dyn std::error::Error>> {
+    let oversized = vec![0u8; usize::try_from(MAX_PREVIEW_BYTES + 1)?];
+    let bytes = save(&json!({}), "DesignCraft test", Some(&oversized), &[])?;
+    assert_eq!(read_preview(std::io::Cursor::new(bytes)), None);
+    Ok(())
+}
+
+#[test]
+fn required_version_preserves_the_reader_capability_contract() {
+    assert_eq!(required_version(&json!({"title":"plain"}), &[]), 2);
+    assert_eq!(required_version(&json!({}), &[Asset { id: "1", mime: "application/postscript", data: b"%!PS-Adobe-3.0 EPSF-3.0" }]), 3);
+    assert_eq!(required_version(&json!({"layerOptions":{}}), &[]), 4);
+    assert_eq!(required_version(&json!({"pdfLayerOverride":true,"pdfHiddenLayers":[]}), &[]), 4);
+    assert_eq!(required_version(&json!({"pdfLayerOverride":true,"pdfHiddenLayers":["guide"]}), &[]), 2);
+
+    let mut nested = json!(null);
+    for _ in 0..65 {
+        nested = json!([nested]);
+    }
+    assert_eq!(required_version(&nested, &[]), 4);
+}
+
+#[test]
+fn legacy_json_extracts_assets_and_applies_v1_migrations() -> Result<(), Box<dyn std::error::Error>> {
+    let legacy = json!({
+        "assetData":{"7":"AQID"},
+        "frames":[{"id":8,"content":{"type":"text","options":{"vertical":true}}}],
+        "stories":{"vertical":{"frames":[8]},"explicit":{"frames":[8],"vertical":false}},
+        "styles":{"paragraph":[{"name":"Base"},{"name":"Child","basedOn":"Base","para":{"keepAllLines":false}}]},
+        "paragraphs":[{"style":"Missing"}]
+    });
+    let loaded = load::<Value>(&serde_json::to_vec(&legacy)?)?;
+
+    assert_eq!(loaded.assets, [("7".to_owned(), vec![1, 2, 3])]);
+    assert_eq!(loaded.document.get("assetData"), None);
+    assert_eq!(loaded.document["stories"]["vertical"]["vertical"], true);
+    assert_eq!(loaded.document["stories"]["explicit"]["vertical"], false);
+    assert_eq!(loaded.document["styles"]["paragraph"][0]["para"]["keepAllLines"], true);
+    assert_eq!(loaded.document["styles"]["paragraph"][0]["para"]["dropCapAlignLeft"], false);
+    assert_eq!(loaded.document["styles"]["paragraph"][1]["para"]["keepAllLines"], false);
+    assert_eq!(loaded.document["paragraphs"][0]["para"]["keepAllLines"], true);
+    Ok(())
+}
+
+#[test]
+fn newer_metadata_precedes_malformed_document_json() -> Result<(), Box<dyn std::error::Error>> {
+    let bytes = craft_document_bundle::write(b"{", VERSION + 1, "future", None, &[], BUNDLE)?;
+    assert!(matches!(load::<Value>(&bytes), Err(Error::TooNew(version)) if version == u64::from(VERSION + 1)));
+    assert!(matches!(load::<Value>(b"not a package"), Err(Error::NotOurs(_))));
+    Ok(())
+}
diff --git a/crates/docx/src/xml.rs b/crates/docx/src/xml.rs
index ff953f43d..bb86755d9 100644
--- a/crates/docx/src/xml.rs
+++ b/crates/docx/src/xml.rs
@@ -373,6 +373,7 @@ fn parse_with(bytes: &[u8], extra: &[(&'static str, &str)], strict: bool) -> Res
         max_depth: MAX_DEPTH + 1,
         // Text stretches count as nodes too: two for each element.
         max_nodes: 2 * MAX_ELEMENTS,
+        max_elements: MAX_ELEMENTS,
         max_attrs: MAX_ATTRS,
         max_attrs_total: 2 * MAX_ELEMENTS,
     };
diff --git a/crates/dwg/Cargo.toml b/crates/dwg/Cargo.toml
new file mode 100644
index 000000000..d2bc8ffff
--- /dev/null
+++ b/crates/dwg/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "craft-dwg"
+description = "Bounded DWG↔DXF byte bridge with an optional child-process worker"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+# acadrust is used unmodified and only on targets supported by its 0.6.6 platform APIs.
+[target.'cfg(not(any(target_arch = "wasm32", all(target_os = "freebsd", target_arch = "aarch64"))))'.dependencies]
+acadrust = { workspace = true }
+log = { workspace = true }
diff --git a/crates/dwg/README.md b/crates/dwg/README.md
new file mode 100644
index 000000000..ed52bdcfc
--- /dev/null
+++ b/crates/dwg/README.md
@@ -0,0 +1,18 @@
+# craft-dwg
+
+A byte-level bridge between DWG and DXF. It does not expose `acadrust` types: callers pass bytes,
+choose limits, and receive converted bytes plus notes about data the conversion could not preserve.
+Application document mapping remains with the caller.
+
+The default limits reject DWG inputs over 512 MiB and stop DXF output over 1 GiB. The bridge
+also catches panics from the dependency and validates its conversion diagnostics. Because a small
+hostile file can declare very large internal sections, size checks alone cannot prevent an
+allocation failure inside the decoder. On native applications, call `use_own_worker()` during
+startup and call `serve_if_asked()` before normal argument handling. Subsequent `decode` and
+`encode_*` calls then run in a child process with a 30-minute timeout; a crash or stack overflow
+is contained to that child. The worker has no operating-system memory limit yet. Without a
+configured worker, conversions run in the current process.
+
+The bridge is not built for `wasm32` or FreeBSD/aarch64. Those targets retain the public API and
+return a clear unsupported-build error. The `acadrust` 0.6.6 dependency is used unmodified under
+MPL-2.0; its license and third-party notices are in `licenses/dwg/` at the workspace root.
diff --git a/crates/dwg/build.rs b/crates/dwg/build.rs
new file mode 100644
index 000000000..e97782ab4
--- /dev/null
+++ b/crates/dwg/build.rs
@@ -0,0 +1,12 @@
+//! Sets `no_dwg_bridge` on the targets built without acadrust (see Cargo.toml): the DWG functions
+//! there return an error that says to use DXF.
+
+fn main() {
+    println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo::rustc-check-cfg=cfg(no_dwg_bridge)");
+    let arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap_or_default();
+    let os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    if arch == "wasm32" || (os == "freebsd" && arch == "aarch64") {
+        println!("cargo::rustc-cfg=no_dwg_bridge");
+    }
+}
diff --git a/crates/dwg/src/lib.rs b/crates/dwg/src/lib.rs
new file mode 100644
index 000000000..2db7afeae
--- /dev/null
+++ b/crates/dwg/src/lib.rs
@@ -0,0 +1,2096 @@
+//! DWG support through a DXF bridge.
+//!
+//! DWG files are read with the `acadrust` crate (MPL-2.0, used unmodified as a dependency) and
+//! converted to DXF bytes for the caller's DXF reader; saving goes the other way. Keeping the
+//! dependency behind this byte-level API prevents its document types from leaking to consumers.
+//! Native targets only (the dependency memory-maps files).
+//!
+//! # Guardrails around the third-party decoder
+//!
+//! The decoder allocates tables and section buffers from sizes a (possibly damaged or hostile)
+//! file declares, and once it starts it cannot be interrupted (an allocation failure aborts the
+//! process, which `catch_unwind` cannot recover). Because the dependency is used unmodified, this
+//! crate guards it from the outside:
+//!
+//! - Both directions reject oversized input *before* the decoder runs ([`Limits::max_dwg_bytes`]
+//!   for DWG→DXF, [`Limits::max_dxf_bytes`] for DXF→DWG), and the DWG→DXF output is capped while
+//!   it is written (`CappedWriter`).
+//! - The reader and writer run inside `catch_unwind`, so a decode failure is reported instead of
+//!   crashing.
+//!
+//! These bound the input- and output-size variants. A small file that declares a huge internal
+//! table or section can still make the dependency allocate before any size is known, so the app
+//! runs both directions in a child process ([`worker`]): what that kills is the child.
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+#![forbid(unsafe_code)]
+
+/// DWG version codes we can write.
+pub const VERSIONS: &[(&str, &str)] =
+    &[("AC1015", "2000"), ("AC1018", "2004"), ("AC1021", "2007"), ("AC1024", "2010"), ("AC1027", "2013"), ("AC1032", "2018")];
+
+/// True when the bytes look like a DWG file (`AC10xx` magic).
+pub fn is_dwg(bytes: &[u8]) -> bool {
+    bytes.len() > 6 && bytes.starts_with(b"AC10") && bytes.get(4..6).is_some_and(|v| v.iter().all(u8::is_ascii_digit))
+}
+
+/// The DWG version code of a file (e.g. "AC1032").
+pub fn version(bytes: &[u8]) -> Option<String> {
+    is_dwg(bytes).then(|| String::from_utf8_lossy(bytes.get(0..6).unwrap_or_default()).to_string())
+}
+
+/// Size limits for reading a DWG file. DWG is compressed and the DXF text it converts to is
+/// several times larger (about 6x in our tests: a 10 MB DWG becomes about 60 MB of DXF), so
+/// the limits are generous for real drawings. They exist because a damaged file, or one the reader
+/// misreads, can make the DWG reader produce a drawing thousands of times larger than the file.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Limits {
+    /// Largest DWG file read at all (checked before reading starts).
+    pub max_dwg_bytes: usize,
+    /// Largest DXF rendition of a DWG (checked while it is written).
+    pub max_dxf_bytes: usize,
+}
+
+impl Limits {
+    /// 512 MB of DWG, 1 GB of DXF (more than the DXF reader's group-code limit fills).
+    pub const DEFAULT: Limits = Limits { max_dwg_bytes: 512 << 20, max_dxf_bytes: 1 << 30 };
+}
+
+/// A byte count in megabytes for messages ("9.9 MB", "1024 MB").
+#[cfg_attr(no_dwg_bridge, allow(dead_code))]
+fn mb(n: u64) -> String {
+    let m = n as f64 / f64::from(1u32 << 20);
+    if m >= 100.0 { format!("{m:.0} MB") } else { format!("{m:.1} MB") }
+}
+
+#[cfg(not(no_dwg_bridge))]
+pub mod worker;
+#[cfg(not(no_dwg_bridge))]
+pub use worker::{WORKER_ARG, crash_worker_for_test, decode, encode_as, encode_kept_noted, encode_noted, serve_if_asked, use_own_worker, use_worker};
+#[cfg(not(no_dwg_bridge))]
+mod proxy_transport;
+
+#[cfg(not(no_dwg_bridge))]
+mod native {
+    use std::io::{Cursor, Write};
+    use std::panic::AssertUnwindSafe;
+
+    use super::{Limits, mb};
+
+    /// Read DWG bytes and return an ASCII DXF rendition, within [`Limits::DEFAULT`].
+    pub fn dwg_to_dxf(bytes: &[u8]) -> Result<Vec<u8>, String> {
+        dwg_to_dxf_with(bytes, Limits::DEFAULT)
+    }
+
+    /// [`dwg_to_dxf`] with explicit limits. Both are checked before the expensive step they
+    /// guard: the input size before the DWG reader runs, the DXF size while it is written, so a
+    /// runaway conversion stops at the limit instead of filling memory first.
+    pub fn dwg_to_dxf_with(bytes: &[u8], limits: Limits) -> Result<Vec<u8>, String> {
+        dwg_to_dxf_noted(bytes, limits).map(|(dxf, _)| dxf)
+    }
+
+    /// [`dwg_to_dxf_with`], also returning notes on what the read left out. The reader runs in
+    /// failsafe mode: an object record it can't decode is skipped instead of failing the whole
+    /// file, and the notes say how many were skipped and of which types, so a partial read never
+    /// passes for a complete one.
+    pub fn dwg_to_dxf_noted(bytes: &[u8], limits: Limits) -> Result<(Vec<u8>, Vec<String>), String> {
+        if bytes.len() > limits.max_dwg_bytes {
+            return Err(format!(
+                "DWG: the file is {}, larger than the {} accepted by this bridge",
+                mb(bytes.len() as u64),
+                mb(limits.max_dwg_bytes as u64)
+            ));
+        }
+        let outcome = std::panic::catch_unwind(|| {
+            acadrust::DwgReader::from_stream_with_options(Cursor::new(bytes), acadrust::DwgReadOptions::failsafe()).read_with_stats()
+        })
+        .map_err(|_| "the DWG reader failed on this file".to_string())?
+        .map_err(|e| format!("DWG: {e}"))?;
+        // Failsafe skips records, not whole files: when the objects stream itself couldn't be
+        // read (a damaged header or section map, or not a DWG at all), nothing was read.
+        if !outcome.stats.record_stream_read {
+            let why = outcome.stats.diagnostics.first().map(|d| d.message.trim_start_matches("Failsafe: ").to_string());
+            return Err(format!("DWG: {}", why.unwrap_or_else(|| "the file's objects couldn't be read".to_string())));
+        }
+        let mut notes = read_notes(&outcome.stats);
+        let mut doc = outcome.document;
+        notes.extend(
+            guarded(AssertUnwindSafe(|| application_objects(&mut doc))).map_err(|_| "the DWG application object conversion failed".to_string())?,
+        );
+        // After application_objects, so the proxy objects it makes are numbered as the DXF's.
+        notes.extend(
+            guarded(AssertUnwindSafe(|| super::proxy_transport::prepare(&mut doc))).map_err(|_| "the DWG proxy conversion failed".to_string())?,
+        );
+        let orphans = guarded(AssertUnwindSafe(|| post_process(&mut doc))).map_err(|_| "the DWG post-processing failed on this file".to_string())?;
+        if orphans > 0 {
+            let (s, were) = if orphans == 1 { ("", "was") } else { ("s", "were") };
+            notes.push(format!("DWG: {orphans} DGN line style component{s} that no line style definition uses {were} left out"));
+        }
+        let mut out = CappedWriter { buf: Vec::new(), limit: limits.max_dxf_bytes, exceeded: false };
+        let written = std::panic::catch_unwind(AssertUnwindSafe(|| {
+            acadrust::DxfWriter::new(&doc).write_to_writer(&mut out)?;
+            mtext_contents(&doc, &mut out)
+        }))
+        .map_err(|_| "the DWG→DXF conversion failed on this file".to_string())?;
+        if out.exceeded {
+            return Err(format!(
+                "DWG: converting this {} file produced more than {} of drawing data (the limit); \
+                 the file is probably damaged, or uses objects the DWG reader misreads",
+                mb(bytes.len() as u64),
+                mb(limits.max_dxf_bytes as u64)
+            ));
+        }
+        written.map_err(|e| format!("DWG→DXF: {e}"))?;
+        Ok((add_header_vars(out.buf, &doc.header), notes))
+    }
+
+    /// acadrust 0.6.6's ASCII writer treats a caret followed by a literal space as already
+    /// escaped, and turns line feeds into paragraph codes. Serialize affected MTEXT contents
+    /// from the native values instead, using its lossless string writer. All other groups,
+    /// including embedded-object data, remain byte-for-byte as the DXF writer emitted them.
+    fn mtext_contents(doc: &acadrust::CadDocument, out: &mut CappedWriter) -> acadrust::Result<()> {
+        use acadrust::io::dxf::{DxfStreamWriter, DxfTextWriter};
+        let contents: std::collections::HashMap<_, _> = doc
+            .entities()
+            .filter_map(|e| match e {
+                acadrust::EntityType::MText(t) if t.value.contains(['^', '\t', '\n']) => Some((t.common.handle.value(), t.value.as_str())),
+                _ => None,
+            })
+            .collect();
+        if contents.is_empty() {
+            return Ok(());
+        }
+        let dxf = std::mem::take(&mut out.buf);
+        let mut lines = dxf.split_inclusive(|b| *b == b'\n');
+        let (mut mtext, mut text, mut written) = (false, None, false);
+        while let Some(code) = lines.next() {
+            let value = lines.next().ok_or_else(|| std::io::Error::other("incomplete DWG bridge DXF pair"))?;
+            match code.trim_ascii() {
+                b"0" => {
+                    mtext = value.trim_ascii() == b"MTEXT";
+                    text = None;
+                    written = false;
+                }
+                b"5" if mtext => {
+                    text = std::str::from_utf8(value.trim_ascii()).ok().and_then(|s| u64::from_str_radix(s, 16).ok()).and_then(|h| contents.get(&h));
+                }
+                b"101" => mtext = false,
+                b"1" | b"3" if mtext && text.is_some() => {
+                    if let Some(&text) = text
+                        && !written
+                    {
+                        let mut writer = DxfTextWriter::new(&mut *out);
+                        if doc.version < acadrust::DxfVersion::AC1021
+                            && let Some(encoding) = acadrust::io::dxf::code_page::encoding_from_code_page(&doc.header.code_page)
+                        {
+                            writer.set_encoding(encoding);
+                        }
+                        // Each character can expand to two caret-escape characters. Keep
+                        // those pairs together and each group within 250 characters.
+                        let mut rest = text;
+                        while let Some((end, _)) = rest.char_indices().nth(125) {
+                            let (chunk, tail) = rest.split_at(end);
+                            writer.write_xrecord_string(3, chunk)?;
+                            rest = tail;
+                        }
+                        writer.write_xrecord_string(1, rest)?;
+                        written = true;
+                    }
+                    continue;
+                }
+                _ => {}
+            }
+            out.write_all(code)?;
+            out.write_all(value)?;
+        }
+        Ok(())
+    }
+
+    #[cfg(test)]
+    #[test]
+    fn mtext_contents_keeps_other_groups_and_the_output_limit() -> acadrust::Result<()> {
+        for version in [acadrust::DxfVersion::AC1015, acadrust::DxfVersion::AC1032] {
+            let mut doc = acadrust::CadDocument::new();
+            doc.version = version;
+            doc.header.code_page = "ANSI_1252".into();
+            let mut t = acadrust::MText::with_value("é ^ C", acadrust::Vector3::ZERO);
+            t.common.handle = acadrust::Handle::new(0x10);
+            doc.add_entity(acadrust::EntityType::MText(Box::new(t)))?;
+            // Only the MTEXT's own 1/3 groups change. The embedded object's groups and the
+            // following TEXT record must survive byte-for-byte, including their spaces.
+            let prefix = b"  0\r\nMTEXT\r\n  5\r\n10\r\n  8\r\n0\r\n";
+            let suffix = b"101\r\nEmbedded Object\r\n  1\r\n^ embedded\r\n  3\r\n^ tail\r\n  0\r\nTEXT\r\n  1\r\n^ plain\r\n";
+            let raw = [prefix.as_slice(), b"  3\r\nold\r\n  1\r\ntext\r\n", suffix.as_slice()].concat();
+            let mut out = CappedWriter { buf: raw.clone(), limit: 4096, exceeded: false };
+            mtext_contents(&doc, &mut out)?;
+            let value: &[u8] = if version == acadrust::DxfVersion::AC1015 { b"\xe9 ^  C" } else { "é ^  C".as_bytes() };
+            assert_eq!(out.buf, [prefix.as_slice(), b"  1\r\n", value, b"\r\n", suffix.as_slice()].concat());
+            let mut limited = CappedWriter { buf: raw, limit: 1, exceeded: false };
+            assert!(mtext_contents(&doc, &mut limited).is_err());
+            assert!(limited.exceeded);
+        }
+        Ok(())
+    }
+
+    /// Most record types named in the skipped-records note.
+    const NOTE_TYPES: usize = 6;
+
+    /// The note on object records a failsafe read skipped: how many, and how many of each type
+    /// (most first), or nothing when the read was complete.
+    pub(crate) fn read_notes(stats: &acadrust::ReadStats) -> Vec<String> {
+        let skipped = stats.skipped_source_records;
+        if skipped == 0 {
+            return Vec::new();
+        }
+        let label = |t: Option<&str>| match t.map(str::parse::<i16>) {
+            Some(Ok(code)) => type_name(code).map_or_else(|| format!("type {code}"), str::to_string),
+            Some(Err(_)) => t.unwrap_or_default().to_string(),
+            None => "unknown".to_string(),
+        };
+        let mut by_type: std::collections::BTreeMap<String, usize> = std::collections::BTreeMap::new();
+        for d in stats.diagnostics.iter().filter(|d| d.record_handle.is_some()) {
+            *by_type.entry(label(d.record_type.as_deref())).or_default() += 1;
+        }
+        let mut types: Vec<(String, usize)> = by_type.into_iter().collect();
+        types.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
+        let mut list: Vec<String> = types.iter().take(NOTE_TYPES).map(|(t, n)| format!("{t} × {n}")).collect();
+        if types.len() > NOTE_TYPES {
+            list.push(format!("{} more types", types.len() - NOTE_TYPES));
+        }
+        let of = if stats.source_records > 0 { format!(" of {}", stats.source_records) } else { String::new() };
+        let records = if skipped == 1 && of.is_empty() { "object record" } else { "object records" };
+        let (were, them) = if skipped == 1 { ("was", "it") } else { ("were", "them") };
+        let which = if list.is_empty() { String::new() } else { format!(" ({})", list.join(", ")) };
+        vec![format!(
+            "DWG: {skipped}{of} {records} couldn't be read and {were} left out{which}; \
+             saving over the original file would lose {them}"
+        )]
+    }
+
+    /// The DXF name of a DWG object type code with a fixed number (classes, 500 and up, are
+    /// numbered per file).
+    fn type_name(code: i16) -> Option<&'static str> {
+        Some(match code {
+            1 => "TEXT",
+            2 => "ATTRIB",
+            3 => "ATTDEF",
+            4 => "BLOCK",
+            5 => "ENDBLK",
+            6 => "SEQEND",
+            7 => "INSERT",
+            8 => "MINSERT",
+            10..=14 => "VERTEX",
+            15 | 16 | 29 | 30 => "POLYLINE",
+            17 => "ARC",
+            18 => "CIRCLE",
+            19 => "LINE",
+            20..=26 => "DIMENSION",
+            27 => "POINT",
+            28 => "3DFACE",
+            31 => "SOLID",
+            32 => "TRACE",
+            33 => "SHAPE",
+            34 => "VIEWPORT",
+            35 => "ELLIPSE",
+            36 => "SPLINE",
+            37 => "REGION",
+            38 => "3DSOLID",
+            39 => "BODY",
+            40 => "RAY",
+            41 => "XLINE",
+            42 => "DICTIONARY",
+            43 => "OLEFRAME",
+            44 => "MTEXT",
+            45 => "LEADER",
+            46 => "TOLERANCE",
+            47 => "MLINE",
+            48 => "BLOCK_CONTROL",
+            49 => "BLOCK_RECORD",
+            50 => "LAYER_CONTROL",
+            51 => "LAYER",
+            52 => "STYLE_CONTROL",
+            53 => "STYLE",
+            56 => "LTYPE_CONTROL",
+            57 => "LTYPE",
+            60 => "VIEW_CONTROL",
+            61 => "VIEW",
+            62 => "UCS_CONTROL",
+            63 => "UCS",
+            64 => "VPORT_CONTROL",
+            65 => "VPORT",
+            66 => "APPID_CONTROL",
+            67 => "APPID",
+            68 => "DIMSTYLE_CONTROL",
+            69 => "DIMSTYLE",
+            70 => "VX_CONTROL",
+            71 => "VX_TABLE_RECORD",
+            72 => "GROUP",
+            73 => "MLINESTYLE",
+            74 => "OLE2FRAME",
+            77 => "LWPOLYLINE",
+            78 => "HATCH",
+            79 => "XRECORD",
+            80 => "ACDBPLACEHOLDER",
+            82 => "LAYOUT",
+            _ => return None,
+        })
+    }
+
+    /// Merged table cells onto the cells. acadrust 0.6.3 reads a 2010+ (AC1024+) DWG table's
+    /// merged cells into the table's `merged_ranges` only, while its DXF writer writes each cell's
+    /// own merge groups (173, 175, 176), so without this the merges would be lost. Tables whose
+    /// cells already carry merges are left alone. Each range's first cell gets the span; the
+    /// cells it covers are marked merged with no span of their own, as CADCraft's DXF writer does.
+    fn table_merges(doc: &mut acadrust::CadDocument) {
+        table_merges_within(doc, MAX_MERGE_CELLS);
+    }
+
+    /// The most table cells [`table_merges`] visits in one document: each range is capped, but
+    /// can cover rows × cols cells, so the total is bounded too.
+    const MAX_MERGE_CELLS: usize = 1 << 24;
+
+    /// A table cell's own text height only when the file says it overrides the table style's.
+    /// acadrust's DXF writer writes a cell style's height (group 140) whenever the cell has a
+    /// style record, even a default 0.18 with no override flag, and CADCraft reads a 140 as an
+    /// override (#2501). The override is the cell style's TEXT_HEIGHT property flag or the
+    /// content's format override bit 128; without either the height is cleared (0 is no
+    /// override), so the table style's height applies.
+    fn table_cell_heights(doc: &mut acadrust::CadDocument) {
+        use acadrust::entities::table::CellStylePropertyFlags;
+        const CONTENT_TEXT_HEIGHT: i32 = 128;
+        for e in doc.entities_mut() {
+            let acadrust::entities::EntityType::Table(t) = e else { continue };
+            for cell in t.rows.iter_mut().flat_map(|r| r.cells.iter_mut()) {
+                // The first content's own height (group 144) when its format override sets bit 128.
+                // CADCraft keeps one height for the cell's text, so a later content's override
+                // must not stand in for the first content's.
+                let content_height = cell
+                    .contents
+                    .first()
+                    .filter(|c| c.format_override_flags & CONTENT_TEXT_HEIGHT != 0)
+                    .map(|c| c.text_height)
+                    .filter(|h| h.is_finite() && *h > 0.0);
+                if let Some(h) = content_height {
+                    // CADCraft reads only the style's height (group 140), so carry it there.
+                    cell.style.get_or_insert_with(acadrust::entities::table::CellStyle::new).text_height = h;
+                    continue;
+                }
+                // A style overrides through its property flags or, in newer files, its override
+                // flags; anything else is the writer's default and is cleared.
+                if let Some(style) = cell.style.as_mut()
+                    && !style.property_flags.contains(CellStylePropertyFlags::TEXT_HEIGHT)
+                    && style.override_flags & CellStylePropertyFlags::TEXT_HEIGHT.bits() as i32 == 0
+                {
+                    style.text_height = 0.0;
+                }
+            }
+        }
+    }
+
+    /// The fix-ups made to a document after the DWG read, returning how many orphaned DGN
+    /// components were dropped. The document comes from a third-party reader and is hostile.
+    fn post_process(doc: &mut acadrust::CadDocument) -> usize {
+        super::fail_in_test("post_process");
+        current_style_names(doc);
+        table_merges(doc);
+        table_cell_heights(doc);
+        table_style_rows(doc, false);
+        keep_sort_handles(doc);
+        drop_orphaned_dgn_components(doc)
+    }
+
+    /// Runs `f`, turning a panic into an error (the reader and writer are guarded the same way).
+    fn guarded<R>(f: impl FnOnce() -> R + std::panic::UnwindSafe) -> Result<R, ()> {
+        std::panic::catch_unwind(f).map_err(|_| ())
+    }
+
+    /// The version a proxy record of a DWG of `version` names its format by (Open Design
+    /// Specification for .dwg, proxy objects): 19 for R13, 21 for R14, 23 for 2000, 25 for 2004,
+    /// 27 for 2007, 29 for 2010, 31 for 2013 and 33 for 2018; `None` for any other version.
+    pub(super) fn proxy_dwg_version(version: acadrust::DxfVersion) -> Option<i32> {
+        Some(match version.version_code() {
+            1012 => 19,
+            1014 => 21,
+            1015 => 23,
+            1018 => 25,
+            1021 => 27,
+            1024 => 29,
+            1027 => 31,
+            1032 => 33,
+            _ => return None,
+        })
+    }
+
+    /// Objects of another application's class that acadrust keeps only as their DWG record
+    /// (`ObjectType::Unknown`, which has no DXF form): its DXF writer left them out, and the
+    /// references to them went with them (a dimension's extension dictionary entry naming its
+    /// application data, say), with no note. Each is carried as a proxy object of its class instead
+    /// (DXF Reference, ACAD_PROXY_OBJECT), so the DXF keeps it and a DWG written from that DXF has it
+    /// again: its common object data (owner, reactors, extension dictionary) and the streams after
+    /// it (data bits, R2007+ strings, object references), as the Open Design Specification for .dwg
+    /// splits an object record. Objects of the drawing database's own classes are not turned into
+    /// another application's proxies. What is still without a DXF form is named in the notes, so a
+    /// save over the original is not mistaken for a complete one.
+    fn application_objects(doc: &mut acadrust::CadDocument) -> Vec<String> {
+        use acadrust::objects::{ObjectType, ProxyObject};
+        let classes: Vec<acadrust::classes::DxfClass> = doc.classes.iter().cloned().collect();
+        let source = doc.dwg_source_version.unwrap_or(doc.version);
+        if let Some(dwg_version) = proxy_dwg_version(source) {
+            let maintenance = i32::from(doc.maintenance_version);
+            for object in doc.objects.values_mut() {
+                let ObjectType::Unknown { handle, raw_dwg_data: Some(data), raw_dwg_handle_bits, raw_dwg_version: Some(version), type_name, .. } =
+                    &*object
+                else {
+                    continue;
+                };
+                if !application_class(&classes, type_name) {
+                    continue;
+                }
+                let raw = acadrust::entities::RawRecord { data: data.clone(), handle_bits: *raw_dwg_handle_bits, version: *version };
+                let handle = *handle;
+                // A record that doesn't split stays as it was, and is named below.
+                let Ok(Ok(record)) = std::panic::catch_unwind(AssertUnwindSafe(|| object_record(&raw, handle.value()))) else { continue };
+                let Some(class) = classes.iter().find(|c| c.class_number == record.kind && !c.is_an_entity) else { continue };
+                *object = ObjectType::ProxyObject(ProxyObject {
+                    handle,
+                    owner: record.owner,
+                    reactors: record.reactors,
+                    xdictionary_handle: record.xdictionary,
+                    proxy_id: 499,
+                    class_id: i32::from(class.class_number),
+                    dwg_version,
+                    maintenance_version: maintenance,
+                    version: (maintenance << 16) | dwg_version,
+                    payload: record.payload,
+                    text_payload: record.text_payload,
+                    object_ids: record.object_ids,
+                    ..Default::default()
+                });
+            }
+        }
+        let mut left: std::collections::BTreeMap<&str, usize> = std::collections::BTreeMap::new();
+        for object in doc.objects.values() {
+            if let ObjectType::Unknown { type_name, raw_dxf_codes: None, .. } = object {
+                let n = left.entry(type_name.as_str()).or_insert(0);
+                *n = n.saturating_add(1);
+            }
+        }
+        if left.is_empty() {
+            return Vec::new();
+        }
+        let total = left.values().fold(0usize, |a, n| a.saturating_add(*n));
+        let mut list: Vec<String> = left.iter().take(NOTE_TYPES).map(|(t, n)| format!("{t:.60} × {n}")).collect();
+        if left.len() > NOTE_TYPES {
+            list.push(format!("{} more types", left.len() - NOTE_TYPES));
+        }
+        vec![format!(
+            "DWG: {total} objects of types this bridge can't preserve were left out ({}); saving over the original file would lose them",
+            list.join(", ")
+        )]
+    }
+
+    /// Whether `name` is an object class of another application, which only that application
+    /// rebuilds: not one of the drawing database's own classes (`AcDb…`/`ACDB…`/`ACAD_…`), whose
+    /// leftovers the database regenerates itself.
+    fn application_class(classes: &[acadrust::classes::DxfClass], name: &str) -> bool {
+        classes.iter().any(|c| {
+            !c.is_an_entity
+                && c.dxf_name.eq_ignore_ascii_case(name)
+                && !c.cpp_class_name.starts_with("AcDb")
+                && !["ACDB", "ACAD_", "ACAD"].iter().any(|p| c.dxf_name.to_ascii_uppercase().starts_with(p))
+        })
+    }
+
+    /// An application object acadrust kept only as its record: the parts a proxy object carries.
+    struct ObjectRecord {
+        kind: i16,
+        owner: acadrust::types::Handle,
+        reactors: Vec<acadrust::types::Handle>,
+        xdictionary: Option<acadrust::types::Handle>,
+        payload: acadrust::objects::ProxyPayload,
+        text_payload: acadrust::objects::ProxyPayload,
+        object_ids: Vec<acadrust::objects::ProxyObjectReference>,
+    }
+
+    /// Split an object record into its common object data and the uninterpreted streams after it
+    /// (data bits, R2007+ strings and object references), as an application object's proxy holds
+    /// them (Open Design Specification for .dwg, common object data and proxy objects). The record
+    /// is hostile: sizes are checked against it, and acadrust's checked stream reader does the rest.
+    fn object_record(raw: &acadrust::entities::RawRecord, handle: u64) -> Result<ObjectRecord, String> {
+        use acadrust::io::dwg::{
+            DwgVersion, dwg_reference_type::DwgReferenceType, dwg_stream_readers::object_reader::DwgObjectReader,
+            dwg_stream_writers::bit_writer::DwgBitWriter,
+        };
+        use acadrust::objects::{ProxyObjectReference, ProxyPayload, ProxyReferenceKind};
+        use acadrust::types::{DxfVersion, Handle};
+        if raw.data.len() > 32 << 20 {
+            return Err("object record exceeds the transport limit".into());
+        }
+        let handle_bits = usize::try_from(raw.handle_bits).map_err(|_| "object has a negative handle stream size")?;
+        let total_bits = raw.data.len().checked_mul(8).ok_or("object record is too large")?;
+        if handle_bits > total_bits {
+            return Err("object handle stream exceeds its record".into());
+        }
+        let version = DwgVersion::from_dxf_version(raw.version).map_err(|e| e.to_string())?;
+        let mut frame = DwgBitWriter::new(version, raw.version);
+        frame.write_modular_short(raw.data.len());
+        if raw.version >= DxfVersion::AC1024 {
+            frame.write_modular_char(handle_bits);
+        }
+        frame.write_bytes(&raw.data);
+        let reader = DwgObjectReader::new(frame.into_bytes(), raw.version, std::collections::HashMap::new()).map_err(|e| e.to_string())?;
+        let (kind, mut streams) = reader.read_record_at(0).map_err(|e| e.to_string())?;
+        if kind < 500 {
+            return Err("object has no application class".into());
+        }
+        let common = reader.read_common_non_entity_data(&mut streams, kind);
+        streams.check_error().map_err(|e| e.to_string())?;
+        if common.common.handle != handle {
+            return Err("object record names another handle".into());
+        }
+        let read_bits = |count: usize, bit: &mut dyn FnMut() -> bool| -> Result<ProxyPayload, String> {
+            if count > total_bits {
+                return Err("object stream exceeds its record".into());
+            }
+            let n = u32::try_from(count).map_err(|_| "object stream is too large")?;
+            let mut bytes = vec![0u8; count.div_ceil(8)];
+            for index in 0..count {
+                if bit()
+                    && let Some(b) = bytes.get_mut(index / 8)
+                {
+                    *b |= 0x80 >> (index % 8);
+                }
+            }
+            Ok(ProxyPayload::from_bits(&bytes, n))
+        };
+        let main = usize::try_from(streams.main_remaining_bits()).map_err(|_| "object body has an invalid size")?;
+        let payload = read_bits(main, &mut || streams.read_bit())?;
+        let text_payload = if raw.version >= DxfVersion::AC1021 {
+            let bits = usize::try_from(streams.text_remaining_bits()).map_err(|_| "object has a negative string stream size")?;
+            read_bits(bits, &mut || streams.read_text_bit())?
+        } else {
+            ProxyPayload::default()
+        };
+        // Every reference to the end of the handle stream, null ones too: an object keeps a null pointer in its
+        // field's place, and the references after it are the next fields' (as acadrust reads a proxy's own). R2010+
+        // records give the stream's exact length; the bits of its last byte past it are padding.
+        let mut object_ids = Vec::new();
+        let mut left = if raw.version >= DxfVersion::AC1024 {
+            streams.get_handle_bits().max(0).min(streams.handle_remaining_bits())
+        } else {
+            streams.handle_remaining_bits()
+        };
+        while left >= 8 {
+            if object_ids.len() >= 100_000 {
+                return Err("object has too many references".into());
+            }
+            let before = streams.handle_remaining_bits();
+            let (target, reference) = streams.read_handle_reference(handle);
+            let used = before.saturating_sub(streams.handle_remaining_bits());
+            if used <= 0 || used > left {
+                break;
+            }
+            left -= used;
+            let kind = match reference {
+                DwgReferenceType::SoftOwnership => ProxyReferenceKind::SoftOwnership,
+                DwgReferenceType::HardOwnership => ProxyReferenceKind::HardOwnership,
+                DwgReferenceType::SoftPointer => ProxyReferenceKind::SoftPointer,
+                DwgReferenceType::HardPointer => ProxyReferenceKind::HardPointer,
+                DwgReferenceType::Undefined => ProxyReferenceKind::Undefined,
+            };
+            object_ids.push(ProxyObjectReference { handle: Handle::from(target), kind });
+        }
+        streams.check_error().map_err(|e| e.to_string())?;
+        Ok(ObjectRecord {
+            kind,
+            owner: Handle::from(common.owner_handle),
+            reactors: common.reactors.into_iter().map(Handle::from).collect(),
+            xdictionary: common.xdictionary_handle.map(Handle::from),
+            payload,
+            text_payload,
+            object_ids,
+        })
+    }
+
+    /// [`table_merges`] visiting at most `budget` cells in all; a range that would pass it is
+    /// left unmerged. Returns the cells visited.
+    fn table_merges_within(doc: &mut acadrust::CadDocument, budget: usize) -> usize {
+        let mut left = budget;
+        for e in doc.entities_mut() {
+            let acadrust::entities::EntityType::Table(t) = e else { continue };
+            if t.merged_ranges.is_empty() || t.rows.iter().flat_map(|r| &r.cells).any(|c| c.merge_width > 1 || c.merge_height > 1) {
+                continue;
+            }
+            let (rows, cols) = (t.rows.len(), t.columns.len());
+            // A real table has at most one merge per cell; more ranges than that come from a
+            // damaged file and would only make this rows × cols × ranges.
+            let max_ranges = rows.saturating_mul(cols).min(1 << 16);
+            for r in t.merged_ranges.iter().take(max_ranges).cloned().collect::<Vec<_>>() {
+                // Clamp to the table: the ranges come from the file.
+                let (bottom, right) = (r.bottom_row.min(rows.saturating_sub(1)), r.right_col.min(cols.saturating_sub(1)));
+                if r.top_row > bottom || r.left_col > right || rows == 0 || cols == 0 || (r.top_row, r.left_col) == (bottom, right) {
+                    continue;
+                }
+                let area = (bottom - r.top_row + 1).saturating_mul(right - r.left_col + 1);
+                if area > left {
+                    continue;
+                }
+                left -= area;
+                let span = |n: usize| i32::try_from(n + 1).unwrap_or(i32::MAX);
+                for (ri, row) in t.rows.iter_mut().enumerate().take(bottom + 1).skip(r.top_row) {
+                    for (ci, cell) in row.cells.iter_mut().enumerate().take(right + 1).skip(r.left_col) {
+                        cell.merged = 1;
+                        let first = (ri, ci) == (r.top_row, r.left_col);
+                        cell.merge_width = if first { span(right - r.left_col) } else { 0 };
+                        cell.merge_height = if first { span(bottom - r.top_row) } else { 0 };
+                    }
+                }
+            }
+        }
+        budget - left
+    }
+
+    /// Draw-order tables (SORTENTSTABLE) keep the sort handles the file gave them. acadrust's DXF
+    /// writer renumbers them past every entity handle, but an entity left out of a table sorts by
+    /// its own handle, so after renumbering it would draw below every listed entity (#2410). Giving
+    /// the table its codes verbatim makes the writer emit them unchanged.
+    fn keep_sort_handles(doc: &mut acadrust::CadDocument) {
+        use acadrust::objects::ObjectType;
+        let version = doc.version;
+        for o in doc.objects.values_mut() {
+            let ObjectType::SortEntitiesTable(t) = o else { continue };
+            let hex = |h: acadrust::types::Handle| format!("{:X}", h.value());
+            let mut codes =
+                vec![(5, hex(t.handle)), (330, hex(t.owner_handle)), (100, "AcDbSortentsTable".to_string()), (330, hex(t.block_owner_handle))];
+            for e in t.entries() {
+                codes.push((331, hex(e.entity_handle)));
+                codes.push((5, hex(e.sort_handle)));
+            }
+            t.raw_dxf_codes = Some(codes);
+            t.raw_dxf_version = Some(version);
+        }
+    }
+
+    /// Table styles' title and header suppression between the two places acadrust 0.6.3 keeps
+    /// it. 2010+ (AC1024+) DWG stores it only in the style's flags (title 1, header 2), while
+    /// acadrust's DXF reader and writer use the `title_suppressed`/`header_suppressed` fields
+    /// (groups 280, 281). `to_flags` copies the fields into the flags before a DWG is written;
+    /// otherwise the flags are copied into the fields after one is read. Older versions store
+    /// both and are left alone.
+    fn table_style_rows(doc: &mut acadrust::CadDocument, to_flags: bool) {
+        use acadrust::objects::{ObjectType, TableStyleFlags};
+        if doc.version < acadrust::DxfVersion::AC1024 {
+            return;
+        }
+        for o in doc.objects.values_mut() {
+            let ObjectType::TableStyle(s) = o else { continue };
+            for (bit, suppressed) in
+                [(TableStyleFlags::TITLE_SUPPRESSED, &mut s.title_suppressed), (TableStyleFlags::HEADER_SUPPRESSED, &mut s.header_suppressed)]
+            {
+                if to_flags {
+                    s.flags.set(bit, *suppressed);
+                } else {
+                    *suppressed = s.flags.contains(bit);
+                }
+            }
+        }
+    }
+
+    /// The DWG dimension flags byte. Its bit 1 is DXF group 70's bit 32 (ODA DWG specification,
+    /// common dimension data), which acadrust keeps no copy of from DXF: it is set here as
+    /// CADCraft's DXF writer always sets it (#1094). Bit 0, the opposite of group 70's bit 128,
+    /// acadrust 0.6.6 reads and writes itself.
+    fn dimension_flags(doc: &mut acadrust::CadDocument) {
+        for e in doc.entities_mut() {
+            let acadrust::entities::EntityType::Dimension(d) = e else { continue };
+            d.base_mut().dwg_flags_byte |= 0x02;
+        }
+    }
+
+    /// Leave out DGN line style components (`LS*COMPONENT`) that no line style definition uses
+    /// (#1482). A drawing that once came from MicroStation can carry hundreds of thousands of
+    /// them, orphaned copies piled up by earlier DGN imports and copy-pastes (AutoCAD's PURGE
+    /// removes them as orphaned data): in a real 83 MB site plan they were 888,483 of 889,053
+    /// components and made its DXF rendition 1.2 GB, over [`Limits::DEFAULT`], so the file
+    /// didn't open at all. No definition that was read refers to them (a definition the reader
+    /// skipped can't use them either) and CADCraft doesn't draw DGN line styles, so nothing
+    /// visible is lost.
+    /// Every component a definition reaches (directly, or through compound and point
+    /// components) is kept, as are the definitions; dictionary entries that named a dropped
+    /// component go with it. Returns how many were left out.
+    fn drop_orphaned_dgn_components(doc: &mut acadrust::CadDocument) -> usize {
+        use acadrust::objects::{DgnLineStyleData, ObjectType};
+        use std::collections::{HashMap, HashSet};
+        // Each component's references, and the definitions' root components to start from.
+        let mut refs: HashMap<acadrust::Handle, Vec<acadrust::Handle>> = HashMap::new();
+        let mut stack: Vec<acadrust::Handle> = Vec::new();
+        for (h, o) in &doc.objects {
+            let ObjectType::DgnLineStyle(ls) = o else { continue };
+            match &ls.data {
+                DgnLineStyleData::Definition { root_component, .. } => stack.push(*root_component),
+                DgnLineStyleData::Component { component, .. } => {
+                    refs.insert(*h, component.references());
+                }
+                DgnLineStyleData::Registered { .. } => {}
+            }
+        }
+        if refs.is_empty() {
+            return 0;
+        }
+        // Each component is visited once, so cycles and shared subtrees end.
+        let mut used: HashSet<acadrust::Handle> = HashSet::new();
+        while let Some(h) = stack.pop() {
+            if let Some(r) = refs.get(&h)
+                && used.insert(h)
+            {
+                stack.extend(r.iter().copied());
+            }
+        }
+        let orphans: HashSet<acadrust::Handle> = refs.into_keys().filter(|h| !used.contains(h)).collect();
+        if orphans.is_empty() {
+            return 0;
+        }
+        doc.objects.retain(|h, _| !orphans.contains(h));
+        doc.dgn_ls_components.retain(|h, _| !orphans.contains(h));
+        for o in doc.objects.values_mut() {
+            let ObjectType::Dictionary(d) = o else { continue };
+            if d.entries.iter().any(|(_, e)| orphans.contains(e)) {
+                d.entries.retain(|(_, e)| !orphans.contains(e));
+                let keys: HashSet<&str> = d.entries.iter().map(|(k, _)| k.as_str()).collect();
+                d.hard_owner_entries.retain(|k| keys.contains(k.as_str()));
+            }
+        }
+        orphans.len()
+    }
+
+    /// Leave out what acadrust can't write as this DWG version: other programs' custom entities
+    /// and objects without raw DWG data of that version. acadrust 0.6.4 refuses the whole file
+    /// for one of them (0.6.3 left them out); CADCraft already tells the user which entity types
+    /// a DWG doesn't keep (`not_saved`), so the rest of the drawing is written. Returns how many
+    /// records of each DXF type were left out, so a save can say so.
+    fn drop_unwritable(doc: &mut acadrust::CadDocument) -> super::Unwritten {
+        let version = doc.version;
+        let mut dropped = super::Unwritten::new();
+        let mut count = |name: &str| {
+            let n = dropped.entry(name.trim().to_ascii_uppercase()).or_insert(0);
+            *n = n.saturating_add(1);
+        };
+        let unwritable: Vec<acadrust::Handle> = doc
+            .entities()
+            .filter_map(|e| match e {
+                acadrust::entities::EntityType::Unknown(u)
+                    if u.raw_dwg_data.is_none() || u.dwg_source_version.is_some_and(|v| v != version) || version == acadrust::DxfVersion::AC1009 =>
+                {
+                    count(&u.dxf_name);
+                    Some(u.common.handle)
+                }
+                _ => None,
+            })
+            .collect();
+        for h in &unwritable {
+            doc.remove_entity(*h);
+        }
+        let objects: Vec<acadrust::Handle> = doc
+            .objects
+            .iter()
+            .filter_map(|(h, o)| match o {
+                acadrust::objects::ObjectType::Unknown { type_name, raw_dwg_data, raw_dwg_version, .. }
+                    if raw_dwg_data.is_none() || raw_dwg_version.is_some_and(|v| v != version) || version == acadrust::DxfVersion::AC1009 =>
+                {
+                    count(type_name);
+                    Some(*h)
+                }
+                _ => None,
+            })
+            .collect();
+        for h in &objects {
+            doc.objects.remove(h);
+        }
+        dropped
+    }
+
+    /// Header variables the DWG reader fills in but acadrust's DXF writer (0.6.3) leaves out of
+    /// the HEADER section: (name, group code, value).
+    fn unwritten_header_vars(h: &acadrust::document::HeaderVariables) -> [(&'static str, i32, String); 7] {
+        [
+            // DWG holds radians; `$ANGBASE` is in degrees.
+            ("$ANGBASE", 50, h.angle_base.to_degrees().to_string()),
+            ("$ANGDIR", 70, h.angle_direction.to_string()),
+            ("$FILLETRAD", 40, h.fillet_radius.to_string()),
+            ("$CHAMFERA", 40, h.chamfer_distance_a.to_string()),
+            ("$CHAMFERB", 40, h.chamfer_distance_b.to_string()),
+            ("$ELEVATION", 40, h.elevation.to_string()),
+            ("$THICKNESS", 40, h.thickness.to_string()),
+        ]
+    }
+
+    /// Add the [`unwritten_header_vars`] to the HEADER section of acadrust's DXF text, before its
+    /// ENDSEC; a variable the writer already wrote is left alone. Text of another layout than
+    /// acadrust's (`  0\r\nSECTION\r\n  2\r\nHEADER\r\n` … `  0\r\nENDSEC\r\n`) is returned unchanged.
+    fn add_header_vars(mut dxf: Vec<u8>, h: &acadrust::document::HeaderVariables) -> Vec<u8> {
+        const START: &[u8] = b"  0\r\nSECTION\r\n  2\r\nHEADER\r\n";
+        const END: &[u8] = b"\r\n  0\r\nENDSEC\r\n";
+        if !dxf.starts_with(START) {
+            return dxf;
+        }
+        let Some(end) = dxf.windows(END.len()).position(|w| w == END).map(|p| p + 2) else { return dxf };
+        let section = dxf.get(..end).unwrap_or_default();
+        let mut add = String::new();
+        for (name, code, value) in unwritten_header_vars(h) {
+            let written = section.windows(name.len() + 2).any(|w| w.starts_with(name.as_bytes()) && w.ends_with(b"\r\n"));
+            if !written && value.parse::<f64>().is_ok_and(f64::is_finite) {
+                add.push_str(&format!("  9\r\n{name}\r\n{code:>3}\r\n{value}\r\n"));
+            }
+        }
+        dxf.splice(end..end, add.into_bytes());
+        dxf
+    }
+
+    /// Collects the DXF text and fails the write once it would grow past `limit`.
+    struct CappedWriter {
+        buf: Vec<u8>,
+        limit: usize,
+        exceeded: bool,
+    }
+
+    impl Write for CappedWriter {
+        fn write(&mut self, b: &[u8]) -> std::io::Result<usize> {
+            // Sticky: once over, every later write fails too.
+            if self.exceeded || self.buf.len().saturating_add(b.len()) > self.limit {
+                self.exceeded = true;
+                return Err(std::io::Error::other("DXF size limit reached"));
+            }
+            self.buf.extend_from_slice(b);
+            Ok(b.len())
+        }
+        fn flush(&mut self) -> std::io::Result<()> {
+            Ok(())
+        }
+    }
+
+    /// Oldest DWG version written; older DXF input is written as this version.
+    const MIN_DWG_VERSION: acadrust::DxfVersion = acadrust::DxfVersion::AC1018;
+
+    /// Convert DXF bytes into a DWG file of the DXF's version, and at least AutoCAD 2004
+    /// (AC1018).
+    pub fn dxf_to_dwg(dxf: &[u8]) -> Result<Vec<u8>, String> {
+        convert(dxf, None, None).map(|(dwg, _)| dwg)
+    }
+
+    /// Convert DXF bytes into a DWG file of `version`, a code from [`super::VERSIONS`] ("AC1032"),
+    /// whatever version the DXF declares.
+    pub fn dxf_to_dwg_as(dxf: &[u8], version: &str) -> Result<Vec<u8>, String> {
+        dxf_to_dwg_noted(dxf, version).map(|(dwg, _)| dwg)
+    }
+
+    /// [`dxf_to_dwg_as`], also returning what the DWG writer left out: how many records of each
+    /// DXF type it can't write (other programs' custom entities and objects that the DWG reader
+    /// didn't read from a DWG of this version), empty when the DWG keeps everything.
+    pub fn dxf_to_dwg_noted(dxf: &[u8], version: &str) -> Result<(Vec<u8>, super::Unwritten), String> {
+        convert(dxf, Some(writable(version)?), None)
+    }
+
+    /// Like [`dxf_to_dwg_as`], for a DXF that declares an older version than the groups it carries
+    /// over from another file. CADCraft's R2000 DWG bridge holds the objects it keeps without
+    /// modelling them (render settings, fields, associative and dynamic block data) as they were
+    /// read from a file of version `kept` ("AC1032"), and acadrust reads several of those
+    /// differently by version: read as R2000, an AC1032 file's mental ray render settings came out
+    /// a class version too high, for which the ODA rejects the whole DWG, and a field lost its
+    /// cached value. So the DXF is read as `kept` declares. A `kept` version that is unknown, or
+    /// not newer than the DXF's own, changes nothing.
+    pub fn dxf_to_dwg_kept_as(dxf: &[u8], version: &str, kept: &str) -> Result<Vec<u8>, String> {
+        dxf_to_dwg_kept_noted(dxf, version, kept).map(|(dwg, _)| dwg)
+    }
+
+    /// [`dxf_to_dwg_kept_as`], also returning what the DWG writer left out, as
+    /// [`dxf_to_dwg_noted`] does.
+    pub fn dxf_to_dwg_kept_noted(dxf: &[u8], version: &str, kept: &str) -> Result<(Vec<u8>, super::Unwritten), String> {
+        let kept = acadrust::DxfVersion::from_version_string(kept.trim().to_ascii_uppercase().as_str());
+        let kept = (kept != acadrust::DxfVersion::Unknown).then_some(kept);
+        convert(dxf, Some(writable(version)?), kept)
+    }
+
+    /// The DWG version for a code from [`super::VERSIONS`].
+    fn writable(version: &str) -> Result<acadrust::DxfVersion, String> {
+        Ok(match version.trim().to_ascii_uppercase().as_str() {
+            "AC1015" => acadrust::DxfVersion::AC1015,
+            "AC1018" => acadrust::DxfVersion::AC1018,
+            "AC1021" => acadrust::DxfVersion::AC1021,
+            "AC1024" => acadrust::DxfVersion::AC1024,
+            "AC1027" => acadrust::DxfVersion::AC1027,
+            "AC1032" => acadrust::DxfVersion::AC1032,
+            _ => return Err(super::unsupported(version)),
+        })
+    }
+
+    /// The ASCII DXF with its `$ACADVER` set to `kept` when that is newer than the version it
+    /// declares, or `None` to read it as it is (binary, no `$ACADVER`, or non-ASCII text without a
+    /// `$DWGCODEPAGE` to decode it by). From AutoCAD 2007 (AC1021) a DXF is UTF-8, so other bytes
+    /// are first decoded with the code page the DXF declares; `\U+XXXX` escapes read the same in
+    /// every version, and CADCraft's R2000 DXF is ASCII with such escapes.
+    pub(super) fn declare_version(dxf: &[u8], kept: acadrust::DxfVersion) -> Option<Vec<u8>> {
+        if dxf.starts_with(b"AutoCAD Binary DXF") {
+            return None;
+        }
+        let (_, declared) = header_value(dxf, b"$ACADVER")?;
+        let declared = acadrust::DxfVersion::from_version_string(std::str::from_utf8(declared).ok()?);
+        if declared >= kept {
+            return None;
+        }
+        let text: std::borrow::Cow<'_, [u8]> = if dxf.is_ascii() || kept < acadrust::DxfVersion::AC1021 {
+            std::borrow::Cow::Borrowed(dxf)
+        } else {
+            // As acadrust decodes an older DXF: by its code page, Windows-1252 for one it doesn't
+            // know; a code page that names UTF-8 needs no decoding.
+            let (_, code_page) = header_value(dxf, b"$DWGCODEPAGE")?;
+            match acadrust::io::dxf::code_page::encoding_from_code_page(std::str::from_utf8(code_page).ok()?) {
+                Some(encoding) => {
+                    let (text, errors) = encoding.decode_without_bom_handling(dxf);
+                    if errors {
+                        return None;
+                    }
+                    std::borrow::Cow::Owned(text.into_owned().into_bytes())
+                }
+                None => std::borrow::Cow::Borrowed(std::str::from_utf8(dxf).ok()?.as_bytes()),
+            }
+        };
+        let (at, value) = header_value(&text, b"$ACADVER")?;
+        let code = kept.to_string();
+        let mut out = Vec::with_capacity(text.len().saturating_add(code.len()));
+        out.extend_from_slice(text.get(..at)?);
+        out.extend_from_slice(code.as_bytes());
+        out.extend_from_slice(text.get(at.checked_add(value.len())?..)?);
+        Some(out)
+    }
+
+    /// The byte offset and the trimmed value of header variable `name` in an ASCII DXF: the value
+    /// of the group that follows the `9` group naming it. The file is read as (group code,
+    /// value) line pairs, in one pass with no buffering, up to the first `0`/`ENDSEC`, the end
+    /// of the HEADER section: a large input without one costs time, not memory (a line index of
+    /// a 32 MiB file used 0.8 GB). Lines may end in `\r\n`.
+    pub(super) fn header_value<'a>(dxf: &'a [u8], name: &[u8]) -> Option<(usize, &'a [u8])> {
+        let mut offset = 0usize;
+        let mut lines = dxf.split(|b| *b == b'\n').map(|line| {
+            let at = offset.saturating_add(line.len() - line.trim_ascii_start().len());
+            offset = offset.saturating_add(line.len()).saturating_add(1);
+            (at, line.trim_ascii())
+        });
+        while let (Some((_, code)), Some((_, value))) = (lines.next(), lines.next()) {
+            if code == b"0" && value == b"ENDSEC" {
+                return None;
+            }
+            if code == b"9" && value == name {
+                let (_, code) = lines.next()?;
+                let (at, value) = lines.next()?;
+                return (code != b"0" && code != b"9").then_some((at, value));
+            }
+        }
+        None
+    }
+
+    /// The current dimension and text styles' names from their handles: a DWG stores the
+    /// handles, and the reader leaves the names at "Standard", so a drawing reopened from DWG
+    /// lost its current dimension style (#1051).
+    fn current_style_names(doc: &mut acadrust::CadDocument) {
+        let h = doc.header.current_dimstyle_handle;
+        if let Some(n) = doc.dim_styles.iter().find(|ds| ds.handle == h && !h.is_null()).map(|ds| ds.name.clone()) {
+            doc.header.current_dimstyle_name = n;
+        }
+        let h = doc.header.current_text_style_handle;
+        if let Some(n) = doc.text_styles.iter().find(|ts| ts.handle == h && !h.is_null()).map(|ts| ts.name.clone()) {
+            doc.header.current_text_style_name = n;
+        }
+    }
+
+    /// The current dimension style (`$DIMSTYLE`) by its name: the DXF gives the name, and the
+    /// handle read with it needn't be the style's in the document, in which case the DWG writer
+    /// fell back to Standard and AutoCAD opened the drawing with Standard current (#1051).
+    fn current_dimstyle(doc: &mut acadrust::CadDocument) {
+        let name = doc.header.current_dimstyle_name.clone();
+        if let Some(h) = doc.dim_styles.iter().find(|ds| ds.name.eq_ignore_ascii_case(&name)).map(|ds| ds.handle) {
+            doc.header.current_dimstyle_handle = h;
+        }
+    }
+
+    /// The current text style (`$TEXTSTYLE`) by its name, the same way as [`current_dimstyle`]:
+    /// the handle read with the DXF needn't be the style's in the document, in which case the DWG
+    /// writer fell back to Standard and AutoCAD opened the drawing with Standard current (#1650).
+    fn current_text_style(doc: &mut acadrust::CadDocument) {
+        let name = doc.header.current_text_style_name.clone();
+        if let Some(h) = doc.text_styles.iter().find(|ts| ts.name.eq_ignore_ascii_case(&name)).map(|ts| ts.handle) {
+            doc.header.current_text_style_handle = h;
+        }
+    }
+
+    /// The DXF names of an ASCII DXF's CLASS records, in CLASSES order: a proxy's class number
+    /// (group 91) is 500 plus its class's place here (DXF Reference, ACAD_PROXY_OBJECT). Empty for
+    /// one without a CLASSES section. `None` for a binary DXF, whose classes this doesn't read:
+    /// CADCraft's own bridge DXF is always ASCII, and only a binary DXF given to the public
+    /// conversion functions comes here.
+    pub(super) fn dxf_class_names(dxf: &[u8]) -> Option<Vec<String>> {
+        let pairs = super::proxy_transport::text_pairs(dxf)?;
+        let mut names = Vec::new();
+        let (mut section, mut in_classes, mut in_class) = (false, false, false);
+        for pair in pairs {
+            let (code, value) = pair?;
+            match (code, value.as_str()) {
+                (0, "ENDSEC") if in_classes => break,
+                (0, "SECTION") => section = true,
+                (2, name) if section => {
+                    in_classes = name == "CLASSES";
+                    section = false;
+                }
+                (0, kind) if in_classes => {
+                    in_class = kind == "CLASS";
+                    // Even an unnamed record keeps its place in the source class table.
+                    if in_class {
+                        names.push(String::new());
+                    }
+                }
+                (1, value) if in_class => {
+                    if let Some(last) = names.last_mut() {
+                        *last = value.to_string();
+                    }
+                    in_class = false;
+                }
+                _ => section = false,
+            }
+        }
+        Some(names)
+    }
+
+    /// Proxy objects' and entities' class numbers as the DWG numbers its classes. A DXF proxy
+    /// names its class by its place in the DXF's CLASSES (`classes`, from 500), but acadrust's
+    /// reader puts its own default classes first and numbers the DXF's after them, so the DXF
+    /// number named another class in the DWG: a 2018 drawing's piping proxies became
+    /// LARGE_RADIAL_DIMENSION and SECTIONOBJECT, and the ODA File Converter refused the file. A
+    /// proxy whose number names no class of the DXF is left out: kept as it is, its number would
+    /// name some other class of the DWG, for the same reason.
+    ///
+    /// Before 2013 (AC1027) acadrust writes only the classes it knows a pre-2013 DWG needs, and a
+    /// proxy's class is not one of them: the proxy would name a missing class (the ODA refuses
+    /// the file: "No ClassId") or, by its old number, some other class. Such a DWG leaves the
+    /// proxies out instead, as it does other programs' data it can't write (`not_saved` reports
+    /// the entities). So does a DXF whose classes are unknown (`classes` is `None`, a binary
+    /// DXF): its proxies' numbers can't be mapped, and kept as they are they would name the
+    /// wrong classes and the ODA would refuse the file. Returns the proxies left out, by DXF type, for
+    /// what the DWG writer left out ([`super::Unwritten`]).
+    fn proxy_classes(doc: &mut acadrust::CadDocument, classes: Option<&[String]>) -> super::Unwritten {
+        let classes = match classes {
+            Some(c) if doc.version >= acadrust::DxfVersion::AC1027 => c,
+            _ => {
+                let entities: Vec<acadrust::Handle> = doc
+                    .entities()
+                    .filter_map(|e| match e {
+                        acadrust::entities::EntityType::Extended(x) if matches!(x.data, acadrust::entities::ExtendedEntityData::Proxy(_)) => {
+                            Some(x.common.handle)
+                        }
+                        _ => None,
+                    })
+                    .collect();
+                let objects: Vec<acadrust::Handle> =
+                    doc.objects.iter().filter_map(|(h, o)| matches!(o, acadrust::objects::ObjectType::ProxyObject(_)).then_some(*h)).collect();
+                for h in &entities {
+                    doc.remove_entity(*h);
+                }
+                for h in &objects {
+                    doc.objects.remove(h);
+                }
+                return left_out(objects.len(), entities.len());
+            }
+        };
+        // Name matching cannot choose between different source classes with the same name.
+        // Count those proxies as unwritten rather than silently changing their class identity.
+        let mut unique = std::collections::HashMap::new();
+        for name in classes {
+            unique.entry(name.to_uppercase()).and_modify(|value| *value = false).or_insert(true);
+        }
+        let number = |id: i32| -> Option<i32> {
+            let name = classes.get(usize::try_from(id.checked_sub(500)?).ok()?)?;
+            if unique.get(&name.to_uppercase()) != Some(&true) {
+                return None;
+            }
+            doc.classes.get_by_name(name).map(|c| i32::from(c.class_number))
+        };
+        let objects: Vec<(acadrust::Handle, Option<i32>)> = doc
+            .objects
+            .iter()
+            .filter_map(|(h, o)| match o {
+                acadrust::objects::ObjectType::ProxyObject(p) => Some((*h, number(p.class_id))),
+                _ => None,
+            })
+            .collect();
+        let entities: Vec<(acadrust::Handle, Option<i32>)> = doc
+            .entities()
+            .filter_map(|e| match e {
+                acadrust::entities::EntityType::Extended(x) => match &x.data {
+                    acadrust::entities::ExtendedEntityData::Proxy(p) => Some((x.common.handle, number(p.class_id))),
+                    _ => None,
+                },
+                _ => None,
+            })
+            .collect();
+        let unmapped = |list: &[(acadrust::Handle, Option<i32>)]| list.iter().filter(|(_, n)| n.is_none()).map(|(h, _)| *h).collect::<Vec<_>>();
+        let (gone_objects, gone_entities) = (unmapped(&objects), unmapped(&entities));
+        for h in &gone_objects {
+            doc.objects.remove(h);
+        }
+        for h in &gone_entities {
+            doc.remove_entity(*h);
+        }
+        let objects = objects.into_iter().filter_map(|(h, n)| Some((h, n?)));
+        let entities = entities.into_iter().filter_map(|(h, n)| Some((h, n?)));
+        for (h, n) in objects {
+            if let Some(acadrust::objects::ObjectType::ProxyObject(p)) = doc.objects.get_mut(&h) {
+                p.class_id = n;
+            }
+        }
+        let entities: std::collections::HashMap<acadrust::Handle, i32> = entities.into_iter().collect();
+        for e in doc.entities_mut() {
+            if let acadrust::entities::EntityType::Extended(x) = e {
+                let Some(n) = entities.get(&x.common.handle).copied() else { continue };
+                if let acadrust::entities::ExtendedEntityData::Proxy(p) = &mut x.data {
+                    p.class_id = n;
+                }
+            }
+        }
+        left_out(gone_objects.len(), gone_entities.len())
+    }
+
+    /// Proxy objects and entities left out of the DWG, by their DXF types.
+    fn left_out(objects: usize, entities: usize) -> super::Unwritten {
+        [("ACAD_PROXY_OBJECT", objects), ("ACAD_PROXY_ENTITY", entities)]
+            .into_iter()
+            .filter(|(_, n)| *n > 0)
+            .map(|(t, n)| (t.to_string(), n))
+            .collect()
+    }
+
+    /// The current layer (`$CLAYER`) by its name, the same way as [`current_dimstyle`]: a DWG
+    /// stores the handle of the layer, and the one read with the DXF needn't be the layer's in
+    /// the document, so the drawing reopened with layer "0" current (#2252).
+    fn current_layer(doc: &mut acadrust::CadDocument) {
+        let name = doc.header.current_layer_name.clone();
+        // The table's own lookup compares Unicode case-insensitively ("Survey_Ä" = "Survey_ä").
+        if let Some(layer) = doc.layers.get(&name) {
+            doc.header.current_layer_handle = layer.handle;
+        }
+    }
+
+    /// `kept`: the version the DXF's carried-over groups were read from ([`dxf_to_dwg_kept_as`]).
+    fn convert(dxf: &[u8], version: Option<acadrust::DxfVersion>, kept: Option<acadrust::DxfVersion>) -> Result<(Vec<u8>, super::Unwritten), String> {
+        // Reject a pathologically large DXF before handing it to the third-party decoder, which
+        // allocates tables and section buffers from the input's declared sizes and cannot be
+        // interrupted once it starts (CWE-789). This bounds the large-input variant; the decoder
+        // runs inside `catch_unwind` so a decode failure is reported rather than crashing.
+        if dxf.len() > Limits::DEFAULT.max_dxf_bytes {
+            return Err(format!(
+                "DXF: the input is {}, larger than the {} accepted for DWG conversion",
+                mb(dxf.len() as u64),
+                mb(Limits::DEFAULT.max_dxf_bytes as u64)
+            ));
+        }
+        // Decoding a code page to UTF-8 can grow the text, so the limit applies again.
+        let data = match kept.and_then(|k| declare_version(dxf, k)) {
+            Some(d) if d.len() > Limits::DEFAULT.max_dxf_bytes => {
+                return Err(format!(
+                    "DXF: the input is {} as UTF-8, larger than the {} accepted for DWG conversion",
+                    mb(d.len() as u64),
+                    mb(Limits::DEFAULT.max_dxf_bytes as u64)
+                ));
+            }
+            Some(d) => d,
+            None => dxf.to_vec(),
+        };
+        let (classes, source) = guarded(AssertUnwindSafe(|| (dxf_class_names(&data), super::proxy_transport::source_classes(&data))))
+            .map_err(|_| "the DXF proxy class conversion failed".to_string())?;
+        let mut doc = std::panic::catch_unwind(move || acadrust::DxfReader::from_reader(Cursor::new(data)).and_then(|r| r.read()))
+            .map_err(|_| "the DXF→DWG conversion failed".to_string())?
+            .map_err(|e| format!("DXF: {e}"))?;
+        match version {
+            Some(v) => doc.version = v,
+            // Without a version asked for, write at least AutoCAD 2004 (AC1018) DWG: R2000 DWG
+            // has no true colours, transparency, table styles or gradients. The DXF stays R2000;
+            // only the DWG is newer.
+            None if doc.version < MIN_DWG_VERSION => doc.version = MIN_DWG_VERSION,
+            None => {}
+        }
+        // The fix-ups run on the third-party reader's document, so a panic in one is an error, not a crash.
+        let unwritten = guarded(AssertUnwindSafe(|| {
+            super::fail_in_test("convert");
+            // From 2013 the DWG takes the source classes as they are, duplicates and metadata
+            // included; otherwise (before 2013, a binary DXF, classes that can't be written back)
+            // proxies are matched to classes by name or left out.
+            let restored = match source {
+                Some(source) if doc.version >= acadrust::DxfVersion::AC1027 => super::proxy_transport::restore_classes(&mut doc, source),
+                _ => None,
+            };
+            let proxies = match restored {
+                Some((objects, entities)) => left_out(objects, entities),
+                None => proxy_classes(&mut doc, classes.as_deref()),
+            };
+            other_layout_owners(&mut doc);
+            table_style_rows(&mut doc, true);
+            dimension_flags(&mut doc);
+            let mut unwritten = drop_unwritable(&mut doc);
+            for (kind, n) in proxies {
+                let total = unwritten.entry(kind).or_insert(0);
+                *total = total.saturating_add(n);
+            }
+            current_dimstyle(&mut doc);
+            add_variable_dictionary(&mut doc);
+            current_text_style(&mut doc);
+            current_layer(&mut doc);
+            unwritten
+        }))
+        .map_err(|_| "the DXF to DWG conversion failed on this file".to_string())?;
+        let dwg = std::panic::catch_unwind(AssertUnwindSafe(|| acadrust::DwgWriter::write_to_vec(&doc)))
+            .map_err(|_| "the DWG writer failed on this drawing".to_string())?
+            .map_err(|e| format!("DWG write: {e}"))?;
+        Ok((dwg, unwritten))
+    }
+
+    /// AutoCAD's entry name for the drawing variables dictionary (the DXF Reference calls it the
+    /// ACDBVARIABLEDICTIONARY; dictionary keys are case-insensitive).
+    const VARIABLE_DICTIONARY: &str = "AcDbVariableDictionary";
+
+    /// A style or scale name, or `default` when the drawing has none.
+    fn name_or_default(name: &str, default: &str) -> String {
+        let name = name.trim();
+        if name.is_empty() { default.to_string() } else { name.to_string() }
+    }
+
+    /// A drawing variable's value as text, or `default` when the header holds a value the
+    /// variable doesn't accept (a hostile file can put any integer in it).
+    fn variable_value(value: i16, valid: &[i16], default: i16) -> String {
+        if valid.contains(&value) { value.to_string() } else { default.to_string() }
+    }
+
+    /// Add the drawing variables dictionary AutoCAD always writes into the named object
+    /// dictionary, with the variables it keeps there, when the drawing has none (#1813).
+    /// Vectric Aspire 10.5 reads a 2004 (AC1018) DWG without it as empty ("No data was imported
+    /// from the DXF / DWG file"), though it reads the same drawing as DXF — which has no such
+    /// dictionary either, as CADCraft's and ezdxf's writers don't make one. AutoCAD's AC1032 DWGs
+    /// read there without it, so newer output is left as it was, and a dictionary the drawing
+    /// does have keeps its own entries and values.
+    fn add_variable_dictionary(doc: &mut acadrust::CadDocument) {
+        use acadrust::objects::{Dictionary, DictionaryVariable, ObjectType};
+        if doc.version >= acadrust::DxfVersion::AC1032 {
+            return;
+        }
+        let root_handle = doc.header.named_objects_dict_handle;
+        match doc.objects.get(&root_handle) {
+            Some(ObjectType::Dictionary(root)) => {
+                if root.get(VARIABLE_DICTIONARY).is_some() {
+                    return;
+                }
+            }
+            _ => return,
+        }
+        // The variables AutoCAD writes for a drawing with default styles and a 1:1 annotation
+        // scale. DIMASSOC and HIDETEXT keep the drawing's own header values; LAYEREVAL and
+        // LAYERNOTIFY have no DXF header variable.
+        let variables = [
+            ("CMLEADERSTYLE", name_or_default(&doc.header.current_mleader_style_name, "Standard")),
+            ("CTABLESTYLE", name_or_default(&doc.header.current_table_style_name, "Standard")),
+            ("CANNOSCALE", name_or_default(&doc.header.current_annotation_scale, "1:1")),
+            ("DIMASSOC", variable_value(doc.header.dimension_associativity, &[0, 1, 2], 2)),
+            ("HIDETEXT", variable_value(doc.header.hide_text, &[0, 1], 1)),
+            ("LAYEREVAL", "0".to_string()),
+            ("LAYERNOTIFY", "0".to_string()),
+        ];
+        let dictionary_handle = doc.allocate_handle();
+        let mut dictionary = Dictionary::new();
+        dictionary.handle = dictionary_handle;
+        dictionary.owner = root_handle;
+        for (name, value) in variables {
+            let handle = doc.allocate_handle();
+            let mut variable = DictionaryVariable::new(name, &value);
+            variable.handle = handle;
+            variable.owner_handle = dictionary_handle;
+            dictionary.add_entry(name, handle);
+            doc.objects.insert(handle, ObjectType::DictionaryVariable(variable));
+        }
+        doc.objects.insert(dictionary_handle, ObjectType::Dictionary(dictionary));
+        if let Some(ObjectType::Dictionary(root)) = doc.objects.get_mut(&root_handle) {
+            root.add_entry(VARIABLE_DICTIONARY, dictionary_handle);
+        }
+    }
+
+    /// Entities of a layout other than the one in `*Paper_Space` are written owned by their block
+    /// (entity mode 0, with its handle). acadrust writes every paper-space entity with mode 1,
+    /// "paper space", which AutoCAD reads as the `*Paper_Space` block's: everything drawn on a
+    /// second layout landed on the first one, and the second stayed empty (#1057).
+    fn other_layout_owners(doc: &mut acadrust::CadDocument) {
+        let others: std::collections::HashSet<acadrust::Handle> = doc
+            .block_records
+            .iter()
+            .filter(|br| {
+                let n = br.name.to_ascii_uppercase();
+                n.len() > 12 && n.starts_with("*PAPER_SPACE") && n[12..].bytes().all(|b| b.is_ascii_digit())
+            })
+            .map(|br| br.handle)
+            .collect();
+        if others.is_empty() {
+            return;
+        }
+        for e in doc.entities_mut() {
+            let c = e.common_mut();
+            if others.contains(&c.owner_handle) {
+                c.entity_mode = Some(0);
+            }
+        }
+    }
+
+    #[cfg(test)]
+    mod post_tests {
+        use super::*;
+        use acadrust::entities::{CellRange, EntityType, Table};
+
+        fn doc_with_table(rows: usize, cols: usize, ranges: usize) -> acadrust::CadDocument {
+            let mut t = Table::new(acadrust::types::Vector3::new(0.0, 0.0, 0.0), rows, cols);
+            t.merged_ranges = (0..ranges).map(|_| CellRange::new(0, 0, rows - 1, cols - 1)).collect();
+            let mut doc = acadrust::CadDocument::new();
+            assert!(doc.add_entity(EntityType::Table(Box::new(t))).is_ok());
+            doc
+        }
+
+        /// Overlapping whole-table ranges can't make the merge pass visit more than its budget (#1934).
+        #[test]
+        fn merge_work_is_bounded_by_the_cell_budget() {
+            let mut doc = doc_with_table(10, 10, 50);
+            assert_eq!(table_merges_within(&mut doc, 250), 200, "two whole-table ranges fit, the rest are skipped");
+            let mut doc = doc_with_table(10, 10, 1);
+            assert_eq!(table_merges_within(&mut doc, usize::MAX), 100);
+        }
+
+        /// A height marked only in the style's override flags (as newer files store it) is kept,
+        /// and the same height with no flag at all is cleared (review on #2588). Tested on the
+        /// read document because acadrust's DWG writer doesn't write the override flags.
+        #[test]
+        fn a_style_override_flag_keeps_the_cell_height() {
+            use acadrust::entities::table::{CellStyle, CellStylePropertyFlags};
+            let height = |override_flags: i32| {
+                let mut doc = doc_with_table(1, 1, 0);
+                for e in doc.entities_mut() {
+                    if let EntityType::Table(t) = e {
+                        for cell in t.rows.iter_mut().flat_map(|r| r.cells.iter_mut()) {
+                            let mut s = CellStyle::new();
+                            s.text_height = 0.5;
+                            s.override_flags = override_flags;
+                            cell.style = Some(s);
+                        }
+                    }
+                }
+                table_cell_heights(&mut doc);
+                doc.entities().find_map(|e| match e {
+                    EntityType::Table(t) => t.rows.first()?.cells.first()?.style.as_ref().map(|s| s.text_height),
+                    _ => None,
+                })
+            };
+            assert_eq!(height(CellStylePropertyFlags::TEXT_HEIGHT.bits() as i32), Some(0.5));
+            assert_eq!(height(0), Some(0.0));
+        }
+
+        /// A panic in the post-read fix-ups is an error, not a crash (#1934).
+        #[test]
+        fn a_panic_in_post_processing_is_an_error() {
+            #[allow(clippy::panic)]
+            let r = guarded(AssertUnwindSafe(|| -> usize { panic!("boom") }));
+            assert!(r.is_err());
+            assert_eq!(guarded(|| 3), Ok(3));
+        }
+    }
+
+    #[cfg(test)]
+    mod application_object_tests {
+        use super::*;
+        use acadrust::CadDocument;
+        use acadrust::classes::DxfClass;
+        use acadrust::objects::{ObjectType, ProxyObjectReference, ProxyPayload, ProxyReferenceKind, RegisteredClassObject};
+        use acadrust::types::{DxfVersion, Handle};
+
+        /// An object of another application's class that acadrust keeps only as its record (a
+        /// vertical product's dimension data, say) is carried as that class's proxy object, with its
+        /// data bits, references, owner and extension dictionary, through DXF and back to DWG, twice.
+        #[test]
+        fn undecoded_application_object_is_kept_as_its_proxy() {
+            for version in [DxfVersion::AC1027, DxfVersion::AC1032] {
+                let mut source = CadDocument::new();
+                source.version = version;
+                source.classes.add_or_update(DxfClass::new("TESTCONTAINER", "xyzDbTestContainer"));
+                let handle = Handle::from(0x2Bu64);
+                let target = Handle::from(0x2Cu64);
+                let payload = ProxyPayload::from_bits(&[0x5A, 0x3C, 0xC0], 18);
+                // A null pointer between two references: it keeps its place, the one after it is not lost.
+                let references = vec![
+                    ProxyObjectReference { handle: target, kind: ProxyReferenceKind::HardPointer },
+                    ProxyObjectReference { handle: Handle::from(0u64), kind: ProxyReferenceKind::SoftPointer },
+                    ProxyObjectReference { handle: Handle::from(0x0Cu64), kind: ProxyReferenceKind::HardPointer },
+                ];
+                source.objects.insert(
+                    handle,
+                    ObjectType::RegisteredClass(RegisteredClassObject {
+                        handle,
+                        owner: Handle::from(0x0Cu64),
+                        dxf_name: "TESTCONTAINER".into(),
+                        cpp_class_name: "xyzDbTestContainer".into(),
+                        payload: payload.clone(),
+                        object_ids: references.clone(),
+                        ..Default::default()
+                    }),
+                );
+                let mut dwg = acadrust::DwgWriter::write_to_vec(&source).unwrap();
+                // acadrust has no model of it: read back, it is only its record.
+                let decoded = acadrust::DwgReader::from_stream(Cursor::new(dwg.clone())).read().unwrap();
+                assert!(matches!(decoded.objects.get(&handle), Some(ObjectType::Unknown { .. })), "{:?}", decoded.objects.get(&handle));
+                for generation in 0..2 {
+                    let (dxf, notes) = dwg_to_dxf_noted(&dwg, Limits::DEFAULT).unwrap();
+                    assert!(notes.is_empty(), "{version:?} {generation}: {notes:?}");
+                    // The DXF has the object, by its handle, as a proxy record.
+                    let text = String::from_utf8_lossy(&dxf);
+                    let lines: Vec<&str> = text.lines().map(str::trim).collect();
+                    let record = lines.windows(4).any(|w| w == ["0", "ACAD_PROXY_OBJECT", "5", "2B"]);
+                    assert!(record, "{version:?} {generation}: no proxy record for the object");
+                    dwg = dxf_to_dwg_as(&dxf, "AC1032").unwrap();
+                    let doc = acadrust::DwgReader::from_stream(Cursor::new(dwg.clone())).read().unwrap();
+                    let Some(ObjectType::ProxyObject(proxy)) = doc.objects.get(&handle) else { panic!("{version:?} {generation}: proxy object") };
+                    assert_eq!(proxy.payload.bit_count, payload.bit_count);
+                    assert_eq!(proxy.payload.data(), payload.data());
+                    assert_eq!(proxy.object_ids, references);
+                    let class = doc.classes.iter().find(|c| i32::from(c.class_number) == proxy.class_id).unwrap();
+                    assert_eq!(class.dxf_name, "TESTCONTAINER");
+                    assert!(!class.is_an_entity);
+                }
+            }
+        }
+
+        /// The database's own classes are not turned into another application's proxies; what is
+        /// left without a DXF form is said, not dropped silently.
+        #[test]
+        fn database_objects_without_a_form_are_reported() {
+            let mut doc = CadDocument::new();
+            doc.classes.add_or_update(DxfClass::new("BLOCKPROPERTIESTABLE", "AcDbBlockPropertiesTable"));
+            let handle = Handle::from(0x40u64);
+            doc.objects.insert(
+                handle,
+                ObjectType::Unknown {
+                    type_name: "BLOCKPROPERTIESTABLE".into(),
+                    handle,
+                    owner: Handle::from(0x0Cu64),
+                    raw_dxf_codes: None,
+                    raw_dwg_data: Some(vec![0; 8]),
+                    raw_dwg_handle_bits: 0,
+                    raw_dwg_version: Some(DxfVersion::AC1032),
+                },
+            );
+            let notes = application_objects(&mut doc);
+            assert!(matches!(doc.objects.get(&handle), Some(ObjectType::Unknown { .. })));
+            assert_eq!(
+                notes,
+                [
+                    "DWG: 1 objects of types this bridge can't preserve were left out (BLOCKPROPERTIESTABLE × 1); saving over the original file would lose them"
+                ]
+            );
+        }
+
+        /// A record that doesn't split stays as it was and is named, never guessed at.
+        #[test]
+        fn invalid_object_records_are_rejected() {
+            for handle_bits in [-1, 1000] {
+                let raw = acadrust::entities::RawRecord { data: vec![0; 8], handle_bits, version: DxfVersion::AC1032 };
+                assert!(object_record(&raw, 42).is_err());
+            }
+            let mut doc = CadDocument::new();
+            doc.classes.add_or_update(DxfClass::new("TESTCONTAINER", "xyzDbTestContainer"));
+            let handle = Handle::from(0x41u64);
+            doc.objects.insert(
+                handle,
+                ObjectType::Unknown {
+                    type_name: "TESTCONTAINER".into(),
+                    handle,
+                    owner: Handle::from(0x0Cu64),
+                    raw_dxf_codes: None,
+                    raw_dwg_data: Some(vec![0xFF; 4]),
+                    raw_dwg_handle_bits: 1000,
+                    raw_dwg_version: Some(DxfVersion::AC1032),
+                },
+            );
+            let notes = application_objects(&mut doc);
+            assert!(matches!(doc.objects.get(&handle), Some(ObjectType::Unknown { .. })));
+            assert!(notes.iter().any(|n| n.contains("(TESTCONTAINER × 1)")), "{notes:?}");
+        }
+    }
+}
+
+#[cfg(not(no_dwg_bridge))]
+pub use native::{
+    dwg_to_dxf, dwg_to_dxf_noted, dwg_to_dxf_with, dxf_to_dwg, dxf_to_dwg_as, dxf_to_dwg_kept_as, dxf_to_dwg_kept_noted, dxf_to_dwg_noted,
+};
+
+/// What saving as DWG left out: how many records of each DXF type (upper case) the DWG writer
+/// can't write.
+pub type Unwritten = std::collections::BTreeMap<String, usize>;
+
+// Test-only: the stage ("post_process" or "convert") whose guard the current test checks. The
+// stage then panics on entry, so a test through the public API shows whether it is guarded.
+#[cfg(all(test, not(no_dwg_bridge)))]
+thread_local! {
+    static PANIC_IN: std::cell::Cell<Option<&'static str>> = const { std::cell::Cell::new(None) };
+}
+
+/// Panics when a test asked for `stage` to fail (see [`PANIC_IN`]); does nothing otherwise.
+#[cfg(not(no_dwg_bridge))]
+#[allow(clippy::panic)]
+fn fail_in_test(_stage: &str) {
+    #[cfg(test)]
+    if PANIC_IN.with(|p| p.get()) == Some(_stage) {
+        panic!("test-forced panic in {_stage}");
+    }
+}
+
+/// The error for a DWG version this writer can't create.
+#[cfg_attr(no_dwg_bridge, allow(dead_code))]
+fn unsupported(version: &str) -> String {
+    let list: Vec<&str> = VERSIONS.iter().map(|(_, year)| *year).collect();
+    format!("DWG version `{version}` can't be written (this bridge writes {})", list.join(", "))
+}
+
+/// Which build has no DWG bridge, for the stubs' errors.
+#[cfg(no_dwg_bridge)]
+const NO_BRIDGE_BUILD: &str = if cfg!(target_arch = "wasm32") { "web" } else { "FreeBSD aarch64" };
+
+/// There's no worker without a bridge.
+#[cfg(no_dwg_bridge)]
+pub const WORKER_ARG: &str = "--dwg-worker";
+#[cfg(no_dwg_bridge)]
+pub fn serve_if_asked() -> Option<i32> {
+    None
+}
+#[cfg(no_dwg_bridge)]
+pub fn use_own_worker() {}
+#[cfg(no_dwg_bridge)]
+pub fn decode(bytes: &[u8], limits: Limits) -> Result<(Vec<u8>, Vec<String>), String> {
+    dwg_to_dxf_noted(bytes, limits)
+}
+#[cfg(no_dwg_bridge)]
+pub fn encode_as(dxf: &[u8], version: &str) -> Result<Vec<u8>, String> {
+    dxf_to_dwg_as(dxf, version)
+}
+#[cfg(no_dwg_bridge)]
+pub fn encode_noted(dxf: &[u8], version: &str) -> Result<(Vec<u8>, Unwritten), String> {
+    dxf_to_dwg_noted(dxf, version)
+}
+#[cfg(no_dwg_bridge)]
+pub fn encode_kept_noted(dxf: &[u8], version: &str, kept: Option<&str>) -> Result<(Vec<u8>, Unwritten), String> {
+    match kept {
+        Some(kept) => dxf_to_dwg_kept_noted(dxf, version, kept),
+        None => dxf_to_dwg_noted(dxf, version),
+    }
+}
+
+#[cfg(no_dwg_bridge)]
+pub fn dwg_to_dxf(_bytes: &[u8]) -> Result<Vec<u8>, String> {
+    Err(format!("DWG files can't be opened in the {NO_BRIDGE_BUILD} build yet; save as DXF"))
+}
+#[cfg(no_dwg_bridge)]
+pub fn dwg_to_dxf_noted(_bytes: &[u8], _limits: Limits) -> Result<(Vec<u8>, Vec<String>), String> {
+    Err(format!("DWG files can't be opened in the {NO_BRIDGE_BUILD} build yet; save as DXF"))
+}
+#[cfg(no_dwg_bridge)]
+pub fn dwg_to_dxf_with(_bytes: &[u8], _limits: Limits) -> Result<Vec<u8>, String> {
+    Err(format!("DWG files can't be opened in the {NO_BRIDGE_BUILD} build yet; save as DXF"))
+}
+#[cfg(no_dwg_bridge)]
+pub fn dxf_to_dwg(_dxf: &[u8]) -> Result<Vec<u8>, String> {
+    Err(format!("DWG files can't be written in the {NO_BRIDGE_BUILD} build yet; save as DXF"))
+}
+#[cfg(no_dwg_bridge)]
+pub fn dxf_to_dwg_as(_dxf: &[u8], _version: &str) -> Result<Vec<u8>, String> {
+    Err(format!("DWG files can't be written in the {NO_BRIDGE_BUILD} build yet; save as DXF"))
+}
+#[cfg(no_dwg_bridge)]
+pub fn dxf_to_dwg_noted(_dxf: &[u8], _version: &str) -> Result<(Vec<u8>, Unwritten), String> {
+    Err(format!("DWG files can't be written in the {NO_BRIDGE_BUILD} build yet; save as DXF"))
+}
+#[cfg(no_dwg_bridge)]
+pub fn dxf_to_dwg_kept_as(_dxf: &[u8], _version: &str, _kept: &str) -> Result<Vec<u8>, String> {
+    Err(format!("DWG files can't be written in the {NO_BRIDGE_BUILD} build yet; save as DXF"))
+}
+#[cfg(no_dwg_bridge)]
+pub fn dxf_to_dwg_kept_noted(_dxf: &[u8], _version: &str, _kept: &str) -> Result<(Vec<u8>, Unwritten), String> {
+    Err(format!("DWG files can't be written in the {NO_BRIDGE_BUILD} build yet; save as DXF"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The DXF of an empty drawing, enough for the bridge to make a small DWG.
+    #[cfg(not(no_dwg_bridge))]
+    const MINIMAL_DXF: &str = "  0\nSECTION\n  2\nHEADER\n  9\n$ACADVER\n  1\nAC1032\n  0\nENDSEC\n  0\nEOF\n";
+
+    /// Makes `stage` panic on the current thread until dropped.
+    #[cfg(not(no_dwg_bridge))]
+    struct PanicIn;
+
+    #[cfg(not(no_dwg_bridge))]
+    impl PanicIn {
+        fn at(stage: &'static str) -> Self {
+            PANIC_IN.with(|p| p.set(Some(stage)));
+            Self
+        }
+    }
+
+    #[cfg(not(no_dwg_bridge))]
+    impl Drop for PanicIn {
+        fn drop(&mut self) {
+            PANIC_IN.with(|p| p.set(None));
+        }
+    }
+
+    /// The public read reports a panic in the post-read fix-ups as an error: this fails if the
+    /// `guarded` call around `post_process` is taken out (#2402).
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn reading_a_dwg_survives_a_panic_in_post_processing() {
+        let dwg = dxf_to_dwg(MINIMAL_DXF.as_bytes()).unwrap();
+        assert!(dwg_to_dxf(&dwg).is_ok(), "the DWG reads without the forced panic");
+        let _panic = PanicIn::at("post_process");
+        let err = dwg_to_dxf(&dwg).unwrap_err();
+        assert!(err.contains("the DWG post-processing failed on this file"), "{err}");
+    }
+
+    /// The DXF to DWG conversion reports a panic in its fix-ups as an error, not a crash (#2402).
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn converting_to_dwg_survives_a_panic_in_the_fix_ups() {
+        let _panic = PanicIn::at("convert");
+        let err = dxf_to_dwg(MINIMAL_DXF.as_bytes()).unwrap_err();
+        assert!(err.contains("the DXF to DWG conversion failed on this file"), "{err}");
+    }
+
+    #[test]
+    fn detects_magic() {
+        assert!(is_dwg(b"AC1032\0\0\0\0"));
+        assert!(!is_dwg(b"  0\r\nSECTION"));
+        assert_eq!(version(b"AC1018xxxx").as_deref(), Some("AC1018"));
+    }
+
+    /// A DXF with ROMANS as `$TEXTSTYLE` gives a DWG whose current text style is ROMANS, not
+    /// Standard: the DXF names the style, and the handle read with it was Standard's (#1650).
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn current_text_style_reaches_the_dwg() {
+        let header = "  0\nSECTION\n  2\nHEADER\n  9\n$ACADVER\n  1\nAC1032\n  9\n$TEXTSTYLE\n  7\nROMANS\n  0\nENDSEC\n";
+        let style = "  0\nSTYLE\n  5\n1F0\n100\nAcDbSymbolTableRecord\n100\nAcDbTextStyleTableRecord\n  2\nROMANS\n 70\n0\n";
+        let style = format!("{style} 40\n0\n 41\n1\n 50\n0\n 71\n0\n 42\n2.5\n  3\nromans.shx\n  4\n\n");
+        let dxf = format!("{header}  0\nSECTION\n  2\nTABLES\n  0\nTABLE\n  2\nSTYLE\n 70\n1\n{style}  0\nENDTAB\n  0\nENDSEC\n  0\nEOF\n");
+        let dwg = dxf_to_dwg(dxf.as_bytes()).unwrap();
+        let doc = acadrust::DwgReader::from_stream(std::io::Cursor::new(&dwg)).read().unwrap();
+        let romans = doc.text_styles.iter().find(|ts| ts.name == "ROMANS").map(|ts| ts.handle);
+        assert!(romans.is_some(), "ROMANS is missing from the DWG");
+        assert_eq!(Some(doc.header.current_text_style_handle), romans);
+    }
+
+    #[test]
+    fn garbage_is_an_error_not_a_crash() {
+        assert!(dwg_to_dxf(b"AC1032 this is not a dwg file at all").is_err());
+        assert!(dwg_to_dxf(b"").is_err());
+    }
+
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn dxf_to_dwg_rejects_garbage_without_crashing() {
+        // The DXF→DWG path runs the third-party reader inside catch_unwind and reports failures
+        // rather than crashing (and rejects oversized input before decoding).
+        assert!(dxf_to_dwg(b"not a dxf file").is_err());
+        assert!(dxf_to_dwg(b"").is_err());
+    }
+
+    /// A DXF with one DIMENSION per (text, group 70, subclass, points) row.
+    #[cfg(not(no_dwg_bridge))]
+    type DimensionSpec<'a> = (&'a str, i64, &'a str, &'a [(i32, [f64; 2])]);
+
+    #[cfg(not(no_dwg_bridge))]
+    fn dims_dxf(dims: &[DimensionSpec<'_>]) -> String {
+        let mut s = String::from("  0\nSECTION\n  2\nHEADER\n  9\n$ACADVER\n  1\nAC1032\n  0\nENDSEC\n  0\nSECTION\n  2\nENTITIES\n");
+        for (text, flags, sub, pts) in dims {
+            s += "  0\nDIMENSION\n  8\n0\n100\nAcDbEntity\n100\nAcDbDimension\n 10\n0\n 20\n0\n 30\n0\n";
+            s += &format!(" 11\n50\n 21\n-20\n 31\n0\n 70\n{flags}\n  1\n{text}\n  3\nStandard\n100\n{sub}\n");
+            for (code, [x, y]) in pts.iter() {
+                s += &format!("{code:>3}\n{x}\n{:>3}\n{y}\n{:>3}\n0\n", code + 10, code + 20);
+            }
+        }
+        s + "  0\nENDSEC\n  0\nEOF\n"
+    }
+
+    /// DWG stores DXF group 70's bit 128 inverted, in bit 0 of the dimension flags byte (set:
+    /// the text is at its default position), and bit 32 in bit 1 (ODA DWG specification, common
+    /// dimension data). The bytes are read back raw, so a reader that inverts bit 0 the same way
+    /// as the writer can't hide a wrong byte.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn dimension_text_position_flags_reach_the_dwg_as_autocad_reads_them() {
+        let linear: &[(i32, [f64; 2])] = &[(13, [0.0, 0.0]), (14, [100.0, 0.0])];
+        let radius: &[(i32, [f64; 2])] = &[(15, [10.0, 0.0])];
+        let angular: &[(i32, [f64; 2])] = &[(13, [0.0, 0.0]), (14, [10.0, 0.0]), (15, [0.0, 0.0]), (16, [0.0, 10.0])];
+        let kinds = [
+            (0, "AcDbAlignedDimension", linear),
+            (1, "AcDbAlignedDimension", linear),
+            (4, "AcDbRadialDimension", radius),
+            (2, "AcDb2LineAngularDimension", angular),
+        ];
+        let mut dims = Vec::new();
+        for (ty, sub, pts) in kinds {
+            dims.push(("HOME", ty | 32, sub, pts));
+            dims.push(("MOVED", ty | 32 | 128, sub, pts));
+        }
+        let dwg = dxf_to_dwg(dims_dxf(&dims).as_bytes()).unwrap();
+        let doc = acadrust::DwgReader::from_stream(std::io::Cursor::new(&dwg)).read().unwrap();
+        let mut seen = Vec::new();
+        for e in doc.entities() {
+            let acadrust::entities::EntityType::Dimension(d) = e else { continue };
+            let (text, byte) = (d.base().text_override().unwrap_or_default(), d.base().dwg_flags_byte);
+            seen.push((text.to_string(), byte & 0x03));
+            assert_eq!(byte & 0x02, 0x02, "{text} {:?}: bit 32 of group 70 is lost (flags byte {byte:#04x})", d.base().dimension_type);
+            let default_pos = text == "HOME";
+            assert_eq!(byte & 0x01 != 0, default_pos, "{text} {:?}: flags byte {byte:#04x}", d.base().dimension_type);
+        }
+        for text in ["HOME", "MOVED"] {
+            assert_eq!(seen.iter().filter(|(t, _)| t == text).count(), 4, "{seen:?}");
+        }
+
+        // And CADCraft reads its own DWG back as it wrote it: 128 only on the moved texts.
+        let dxf = String::from_utf8(dwg_to_dxf(&dwg).unwrap()).unwrap();
+        let lines: Vec<&str> = dxf.lines().map(str::trim).collect();
+        let mut flags = Vec::new();
+        for rec in lines.chunks(2).collect::<Vec<_>>().split(|p| p.first() == Some(&"0")) {
+            let value = |code: &str| rec.iter().find(|p| p.first() == Some(&code)).and_then(|p| p.get(1).copied());
+            if let (Some(text @ ("HOME" | "MOVED")), Some(v)) = (value("1"), value("70")) {
+                flags.push((text, v.parse::<i64>().unwrap_or(-1) & 128));
+            }
+        }
+        assert_eq!(flags.len(), 8, "{flags:?}");
+        assert!(flags.iter().all(|(l, f)| (*f == 128) == (*l == "MOVED")), "{flags:?}");
+    }
+
+    /// The handles a DXF text refers to or gives its records (groups 5, 105 and 330–369).
+    #[cfg(not(no_dwg_bridge))]
+    fn dxf_handles(dxf: &str) -> std::collections::HashSet<u64> {
+        let lines: Vec<&str> = dxf.lines().collect();
+        lines
+            .chunks(2)
+            .filter_map(|p| match p {
+                [c, v] if matches!(c.trim().parse::<i32>(), Ok(5 | 105 | 330..=369)) => u64::from_str_radix(v.trim(), 16).ok(),
+                _ => None,
+            })
+            .collect()
+    }
+
+    /// Issue #1482: a DWG that once came from MicroStation can carry hundreds of thousands of DGN
+    /// line style components no definition uses (a real 83 MB site plan: 888,483 of 889,053, a
+    /// 1.2 GB DXF rendition over the limit, so it didn't open). They're left out with a note, and
+    /// their dictionary entries with them; the definition and every component it reaches —
+    /// through compound and point components, around a cycle — are kept.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn orphaned_dgn_line_style_components_are_left_out() {
+        use acadrust::objects::*;
+        let mut doc = acadrust::CadDocument::new();
+        let container = doc.allocate_handle();
+        let nod = doc.header.named_objects_dict_handle;
+        let Some(ObjectType::Dictionary(root)) = doc.objects.get_mut(&nod) else { panic!("no named object dictionary") };
+        root.entries.push(("ACAD_DGNLINESTYLECOMP".into(), container));
+        let pattern = || DgnLsStrokePattern {
+            has_iteration_limit: false,
+            is_single_segment: false,
+            iteration_limit: 0,
+            auto_phase: 0.0,
+            phase: 0.0,
+            phase_mode: DgnLsPhaseMode::Distance,
+            strokes: vec![DgnLsStroke {
+                is_dash: true,
+                bypass_corner: false,
+                can_be_scaled: true,
+                invert_at_origin: false,
+                invert_at_end: false,
+                length: 2.5,
+                start_width: 0.0,
+                end_width: 0.0,
+                width_mode: 0,
+                cap_mode: 0,
+            }],
+        };
+        let kind = |c: &DgnLsComponentData| match c {
+            DgnLsComponentData::Symbol(_) => DgnLsComponentType::Symbol,
+            DgnLsComponentData::Compound(_) => DgnLsComponentType::Compound,
+            DgnLsComponentData::Stroke(_) => DgnLsComponentType::Stroke,
+            DgnLsComponentData::Point(_) => DgnLsComponentType::Point,
+            DgnLsComponentData::Internal(_) => DgnLsComponentType::Internal,
+        };
+        let compound = |of: &[acadrust::Handle]| {
+            DgnLsComponentData::Compound(DgnLsCompoundComponent {
+                entries: of.iter().map(|&component| DgnLsCompoundEntry { component, offset: 0.0 }).collect(),
+            })
+        };
+        let mut entries = Vec::new();
+        let mut put = |doc: &mut acadrust::CadDocument, h: acadrust::Handle, data: DgnLineStyleData| {
+            entries.push((format!("{:X}", h.value()), h));
+            let reactors = vec![container];
+            doc.objects
+                .insert(h, ObjectType::DgnLineStyle(DgnLineStyleObject { handle: h, owner: container, reactors, xdictionary_handle: None, data }));
+        };
+        let component = |c: DgnLsComponentData| DgnLineStyleData::Component {
+            kind: kind(&c),
+            description: "dash".into(),
+            version: 1,
+            component_uid: [7; 16],
+            scale: 1.0,
+            property_flags: 0,
+            component: c,
+            properties: vec![],
+        };
+        let h: Vec<acadrust::Handle> = (0..9).map(|_| doc.allocate_handle()).collect();
+        let [def, root, stroke, point, back, orphan, orphan_cycle, internal, shared] = h[..] else { panic!("nine handles") };
+        put(
+            &mut doc,
+            def,
+            DgnLineStyleData::Definition {
+                description: "{ dash }".into(),
+                version: 1,
+                style_number: 1,
+                component_uid: [1; 16],
+                is_continuous: false,
+                unit_definition: 1.0,
+                unit_scale: 1.0,
+                units_type: 0,
+                is_element: false,
+                is_physical: false,
+                is_scale_independent: false,
+                is_snappable: false,
+                root_component: root,
+                properties: vec![],
+            },
+        );
+        // Used: def → root → {stroke, point → shared, back → root (a cycle)}.
+        put(&mut doc, root, component(compound(&[stroke, point, back])));
+        put(&mut doc, stroke, component(DgnLsComponentData::Stroke(pattern())));
+        put(&mut doc, point, component(DgnLsComponentData::Point(DgnLsPointComponent { stroke_component: shared, symbols: vec![] })));
+        put(&mut doc, back, component(compound(&[root])));
+        put(&mut doc, shared, component(DgnLsComponentData::Stroke(pattern())));
+        // Orphans: an internal component, and two compounds that refer to each other and to a
+        // used component (which stays).
+        let pattern_internal =
+            DgnLsInternalComponent { pattern: pattern(), internal_version: 0, hardware_style: 0, is_hardware_style: false, line_code: 0 };
+        put(&mut doc, internal, component(DgnLsComponentData::Internal(pattern_internal)));
+        put(&mut doc, orphan, component(compound(&[orphan_cycle, shared])));
+        put(&mut doc, orphan_cycle, component(compound(&[orphan])));
+        let mut dict = Dictionary::new();
+        dict.handle = container;
+        dict.owner = nod;
+        dict.entries = entries;
+        doc.objects.insert(container, ObjectType::Dictionary(dict));
+        let dwg = acadrust::DwgWriter::write_to_vec(&doc).unwrap();
+
+        let (dxf, notes) = dwg_to_dxf_noted(&dwg, Limits::DEFAULT).unwrap();
+        let dxf = String::from_utf8(dxf).unwrap();
+        let handles = dxf_handles(&dxf);
+        for kept in [def, root, stroke, point, back, shared] {
+            assert!(handles.contains(&kept.value()), "{:X} was left out", kept.value());
+        }
+        for gone in [internal, orphan, orphan_cycle] {
+            assert!(!handles.contains(&gone.value()), "{:X} was kept or is still referred to", gone.value());
+        }
+        let lines: Vec<&str> = dxf.lines().collect();
+        let ls: Vec<&str> = lines.chunks(2).filter_map(|p| p.get(1).filter(|_| p[0].trim() == "0" && p[1].starts_with("LS")).copied()).collect();
+        assert_eq!(ls.iter().filter(|t| t.ends_with("COMPONENT")).count(), 5, "{ls:?}");
+        assert!(ls.contains(&"LSDEFINITION") && !ls.contains(&"LSINTERNALCOMPONENT"), "{ls:?}");
+        assert_eq!(notes, ["DWG: 3 DGN line style components that no line style definition uses were left out"]);
+    }
+
+    /// An R2000 DXF header (`\r\n` lines, as CADCraft writes them) with `extra` after `$ACADVER`.
+    #[cfg(not(no_dwg_bridge))]
+    fn r2000(extra: &[u8]) -> Vec<u8> {
+        let mut dxf = b"  0\r\nSECTION\r\n  2\r\nHEADER\r\n  9\r\n$ACADVER\r\n  1\r\nAC1015\r\n  9\r\n$DWGCODEPAGE\r\n  3\r\nANSI_1252\r\n".to_vec();
+        dxf.extend_from_slice(b"  0\r\nENDSEC\r\n  0\r\nSECTION\r\n  2\r\nENTITIES\r\n  0\r\nTEXT\r\n  1\r\n");
+        dxf.extend_from_slice(extra);
+        dxf.extend_from_slice(b"\r\n  0\r\nENDSEC\r\n  0\r\nEOF\r\n");
+        dxf
+    }
+
+    /// The kept version replaces only the `$ACADVER` value; everything else stays byte for byte.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn declare_version_changes_only_acadver() {
+        let dxf = r2000(b"A\\U+00E7\\U+00E3o");
+        let out = native::declare_version(&dxf, acadrust::DxfVersion::AC1032).unwrap();
+        assert_eq!(String::from_utf8(out).unwrap(), String::from_utf8(dxf).unwrap().replacen("AC1015", "AC1032", 1));
+    }
+
+    /// A kept version not newer than the declared one, a binary DXF and a DXF without `$ACADVER`
+    /// are read as they are.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn declare_version_leaves_what_it_need_not_change() {
+        let dxf = r2000(b"x");
+        assert_eq!(native::declare_version(&dxf, acadrust::DxfVersion::AC1015), None);
+        assert_eq!(native::declare_version(&dxf, acadrust::DxfVersion::AC1009), None);
+        assert_eq!(native::declare_version(b"AutoCAD Binary DXF\r\n\x1a\0", acadrust::DxfVersion::AC1032), None);
+        let no_version = b"  0\r\nSECTION\r\n  2\r\nHEADER\r\n  0\r\nENDSEC\r\n  0\r\nEOF\r\n";
+        assert_eq!(native::declare_version(no_version, acadrust::DxfVersion::AC1032), None);
+        // A `$ACADVER` outside the HEADER section is not the file's version.
+        let late = b"  0\r\nSECTION\r\n  2\r\nHEADER\r\n  0\r\nENDSEC\r\n  9\r\n$ACADVER\r\n  1\r\nAC1015\r\n";
+        assert_eq!(native::declare_version(late, acadrust::DxfVersion::AC1032), None);
+    }
+
+    /// The header is read as group code and value pairs up to the first `0`/`ENDSEC`: a `$ACADVER`
+    /// name whose value would come after it, or a file that never ends its HEADER, is no version
+    /// to replace, and `\r\n` lines keep the value's offset right.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn declare_version_reads_the_header_in_pairs_up_to_endsec() {
+        let cut = b"  0\r\nSECTION\r\n  2\r\nHEADER\r\n  9\r\n$ACADVER\r\n  0\r\nENDSEC\r\n  1\r\nAC1015\r\n";
+        assert_eq!(native::declare_version(cut, acadrust::DxfVersion::AC1032), None);
+        let endless = vec![b'\n'; 1 << 20];
+        assert_eq!(native::declare_version(&endless, acadrust::DxfVersion::AC1032), None);
+        let crlf = b"  0\r\nSECTION\r\n  2\r\nHEADER\r\n  9\r\n$ACADVER\r\n  1\r\n  AC1015\r\n  0\r\nENDSEC\r\n";
+        let out = native::declare_version(crlf, acadrust::DxfVersion::AC1032).unwrap();
+        assert_eq!(out, b"  0\r\nSECTION\r\n  2\r\nHEADER\r\n  9\r\n$ACADVER\r\n  1\r\n  AC1032\r\n  0\r\nENDSEC\r\n");
+    }
+
+    /// Declared as 2007 or later, a DXF is UTF-8: code page text is decoded first. Declared as an
+    /// older version, the code page bytes stay as they are.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn declare_version_decodes_a_code_page_for_utf8_versions() {
+        let dxf = r2000(b"A\xe7\xe3o");
+        let utf8 = native::declare_version(&dxf, acadrust::DxfVersion::AC1032).unwrap();
+        let text = String::from_utf8(utf8).unwrap();
+        assert!(text.contains("\r\nAção\r\n") && text.contains("$ACADVER\r\n  1\r\nAC1032\r\n"), "{text}");
+        let legacy = native::declare_version(&dxf, acadrust::DxfVersion::AC1018).unwrap();
+        assert!(legacy.windows(4).any(|w| w == b"A\xe7\xe3o"), "the code page bytes stay");
+        assert!(legacy.windows(6).any(|w| w == b"AC1018"));
+        // A code page it doesn't know is read as Windows-1252, as acadrust reads an older DXF.
+        let at = dxf.windows(9).position(|w| w == b"ANSI_1252").unwrap();
+        let unknown = [&dxf[..at], b"NO_SUCH_CP".as_slice(), &dxf[at + 9..]].concat();
+        let text = String::from_utf8(native::declare_version(&unknown, acadrust::DxfVersion::AC1032).unwrap()).unwrap();
+        assert!(text.contains("\r\nAção\r\n"), "{text}");
+        // Without a `$DWGCODEPAGE` there is nothing to decode it by: it is read as it is.
+        let none = [&dxf[..at - 21], &dxf[at + 11..]].concat();
+        assert!(!none.windows(12).any(|w| w == b"$DWGCODEPAGE"), "{}", String::from_utf8_lossy(&none));
+        assert_eq!(native::declare_version(&none, acadrust::DxfVersion::AC1032), None);
+    }
+
+    /// An unknown kept version converts as [`dxf_to_dwg_as`] does.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn unknown_kept_version_converts_as_before() {
+        let dxf = r2000(b"x");
+        assert_eq!(dxf_to_dwg_kept_as(&dxf, "AC1032", "AC9999"), dxf_to_dwg_as(&dxf, "AC1032"));
+        assert!(dxf_to_dwg_kept_as(&dxf, "AC0000", "AC1032").is_err(), "an unwritable version is still an error");
+    }
+
+    /// The CLASS names in CLASSES order; nothing for a binary DXF or one without CLASSES.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn dxf_class_names_in_classes_order() {
+        let dxf = b"  0\r\nSECTION\r\n  2\r\nHEADER\r\n  0\r\nENDSEC\r\n  0\r\nSECTION\r\n  2\r\nCLASSES\r\n  0\r\nCLASS\r\n  1\r\nWIDGETA\r\n  2\r\nAcDbWidgetA\r\n  3\r\nApp\r\n  0\r\nCLASS\r\n  1\r\nWIDGETB\r\n  2\r\nAcDbWidgetB\r\n  0\r\nENDSEC\r\n  0\r\nSECTION\r\n  2\r\nENTITIES\r\n  0\r\nTEXT\r\n  1\r\nNOT_A_CLASS\r\n  0\r\nENDSEC\r\n  0\r\nEOF\r\n";
+        assert_eq!(native::dxf_class_names(dxf).unwrap(), ["WIDGETA", "WIDGETB"]);
+        // A CLASS record without a name keeps its place, so the classes after it keep theirs
+        // (#2837 review).
+        let unnamed = b"  0\r\nSECTION\r\n  2\r\nCLASSES\r\n  0\r\nCLASS\r\n  2\r\nAcDbNoName\r\n  0\r\nCLASS\r\n  1\r\nWIDGETB\r\n  0\r\nENDSEC\r\n  0\r\nEOF\r\n";
+        assert_eq!(native::dxf_class_names(unnamed).unwrap(), ["", "WIDGETB"]);
+        assert_eq!(native::dxf_class_names(b"  0\nSECTION\n  2\nHEADER\n  0\nENDSEC\n  0\nEOF\n"), Some(Vec::new()));
+        assert_eq!(native::dxf_class_names(b"AutoCAD Binary DXF\r\n\x1a\0"), None);
+    }
+
+    /// AutoCAD's DWG scale action (BLOCKSCALEACTION) ends with a byte after its three
+    /// connections that DXF doesn't carry. acadrust 0.6.4 neither read nor wrote it, so AutoCAD
+    /// read past the object and refused every DWG CADCraft wrote with a dynamic block that scales
+    /// ("Error Decrypting Data"); 0.6.5 added it and 0.6.6, which this uses, still keeps it (0.6.6 also
+    /// fixes multi-layout DWGs, #1463). The byte reaches the DWG, and a scale action
+    /// from DXF is written whole, with the byte AutoCAD writes (0).
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn scale_actions_keep_the_byte_autocad_reads_after_their_connections() {
+        use acadrust::objects::*;
+        let scale_action = |doc: &acadrust::CadDocument| {
+            doc.objects.values().find_map(|o| match o {
+                ObjectType::DynamicBlock(DynamicBlockObject { data: DynamicBlockData::ScaleAction(s), .. }) => Some(s.clone()),
+                _ => None,
+            })
+        };
+        let mut doc = acadrust::CadDocument::new();
+        let h = doc.allocate_handle();
+        let conn = |code, name: &str| BlockConnection { code, name: name.into() };
+        let mut action = DynamicBlockObject::new("BLOCKSCALEACTION", "AcDbBlockScaleAction");
+        action.handle = h;
+        action.owner = doc.header.named_objects_dict_handle;
+        let mut a = BlockBasePointAction::default();
+        a.action.action.element.name = "Scale".into();
+        a.action.connections = vec![conn(2, "UpdatedBaseX"), conn(2, "UpdatedBaseY")];
+        a.action.dependent = true;
+        a.connections = vec![conn(2, "Scale"), conn(2, "XScale"), conn(2, "YScale")];
+        a.dwg_tail_byte = 7;
+        action.data = DynamicBlockData::ScaleAction(a.clone());
+        doc.objects.insert(h, ObjectType::DynamicBlock(action));
+
+        let dwg = acadrust::DwgWriter::write_to_vec(&doc).unwrap();
+        let back = acadrust::DwgReader::from_stream(std::io::Cursor::new(dwg)).read().unwrap();
+        assert_eq!(scale_action(&back).map(|s| s.dwg_tail_byte), Some(7), "the byte isn't written");
+
+        let mut dxf = Vec::new();
+        acadrust::DxfWriter::new(&doc).write_to_writer(&mut dxf).unwrap();
+        for version in ["AC1018", "AC1032"] {
+            let dwg = dxf_to_dwg_as(&dxf, version).unwrap();
+            let back = acadrust::DwgReader::from_stream(std::io::Cursor::new(dwg)).read().unwrap();
+            let read = scale_action(&back).unwrap_or_else(|| panic!("{version}: the scale action wasn't written"));
+            assert_eq!(read.connections, a.connections, "{version}");
+            assert_eq!(read.action.connections, a.action.connections, "{version}");
+            assert_eq!(read.dwg_tail_byte, 0, "{version}");
+        }
+    }
+
+    /// Saving says what the DWG writer left out, per type: entities of types acadrust's DXF
+    /// reader doesn't model (another program's custom entity) can't be written; a drawing the DWG
+    /// keeps whole reports nothing.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn saving_lists_the_types_the_dwg_writer_leaves_out() {
+        let line = "  0\nLINE\n  8\n0\n100\nAcDbEntity\n100\nAcDbLine\n 10\n0.0\n 20\n0.0\n 30\n0.0\n 11\n10.0\n 21\n0.0\n 31\n0.0\n";
+        let widget = "  0\nACME_WIDGET\n  8\n0\n100\nAcDbEntity\n100\nAcmeWidget\n 10\n1.0\n 20\n2.0\n 30\n0.0\n";
+        let dxf = |body: &str| {
+            format!("  0\nSECTION\n  2\nHEADER\n  9\n$ACADVER\n  1\nAC1032\n  0\nENDSEC\n  0\nSECTION\n  2\nENTITIES\n{body}  0\nENDSEC\n  0\nEOF\n")
+        };
+        for version in ["AC1015", "AC1018", "AC1032"] {
+            let (dwg, unwritten) = dxf_to_dwg_noted(dxf(&format!("{line}{widget}{widget}")).as_bytes(), version).unwrap();
+            assert!(is_dwg(&dwg), "{version}");
+            assert_eq!(unwritten, [("ACME_WIDGET".to_string(), 2)].into_iter().collect::<Unwritten>(), "{version}");
+        }
+        let (_, unwritten) = dxf_to_dwg_noted(dxf(line).as_bytes(), "AC1032").unwrap();
+        assert!(unwritten.is_empty(), "{unwritten:?}");
+    }
+
+    /// An OLE2FRAME, which CADCraft keeps as its DXF groups without modelling it, is written to
+    /// the DWG with its data: it isn't in the list of what the writer left out.
+    #[cfg(not(no_dwg_bridge))]
+    #[test]
+    fn ole_frames_are_written_with_their_data() {
+        let ole = "  0\nOLE2FRAME\n  8\n0\n100\nAcDbEntity\n100\nAcDbOle2Frame\n 70\n2\n 10\n1.0\n 20\n9.0\n 30\n0.0\n 11\n8.0\n 21\n2.0\n 31\n0.0\n 71\n2\n 72\n0\n 73\n1\n 90\n4\n310\nDEADBEEF\n  1\nOLE\n";
+        let dxf =
+            format!("  0\nSECTION\n  2\nHEADER\n  9\n$ACADVER\n  1\nAC1032\n  0\nENDSEC\n  0\nSECTION\n  2\nENTITIES\n{ole}  0\nENDSEC\n  0\nEOF\n");
+        for version in ["AC1015", "AC1018", "AC1032"] {
+            let (dwg, unwritten) = dxf_to_dwg_noted(dxf.as_bytes(), version).unwrap();
+            assert!(unwritten.is_empty(), "{version} {unwritten:?}");
+            let back = acadrust::DwgReader::from_stream(std::io::Cursor::new(dwg)).read().unwrap();
+            let frames: Vec<Vec<u8>> = back
+                .entities()
+                .filter_map(|e| match e {
+                    acadrust::entities::EntityType::Ole2Frame(o) => Some(o.encoded_payload()),
+                    _ => None,
+                })
+                .collect();
+            assert_eq!(frames, [vec![0xDE, 0xAD, 0xBE, 0xEF]], "{version}");
+        }
+    }
+}
diff --git a/crates/dwg/src/proxy_transport.rs b/crates/dwg/src/proxy_transport.rs
new file mode 100644
index 000000000..db0b984ec
--- /dev/null
+++ b/crates/dwg/src/proxy_transport.rs
@@ -0,0 +1,632 @@
+//! Another application's entities and their classes through the DWG bridge: on reading a DWG,
+//! registered entities acadrust has no model for become proxy entities of their class; on writing
+//! one, the DWG gets the source DXF's classes in their places, so every proxy names its own class.
+
+use std::collections::{HashMap, HashSet};
+
+use acadrust::CadDocument;
+use acadrust::classes::{DxfClass, ProxyFlags};
+use acadrust::entities::{EntityType, ExtendedEntityData, ProxyEntityData};
+use acadrust::objects::{ObjectType, ProxyPayload};
+
+fn class_number(index: usize) -> Result<i16, String> {
+    index.checked_add(500).and_then(|n| i16::try_from(n).ok()).ok_or_else(|| "DXF: too many application classes".into())
+}
+
+/// After a DWG read: each registered entity of another application's class that acadrust keeps
+/// only as its record and opaque data (no decoded properties) becomes a proxy entity of that class
+/// (DXF Reference, ACAD_PROXY_ENTITY), with its graphics, data bits, R2007+ strings and object
+/// references, so the DXF keeps it; and every proxy's class number becomes 500 plus its class's
+/// place in the classes, as a DXF numbers it. A record that can't be converted (its class is
+/// missing or not unique) is left out and named in the notes; one with decoded properties stays as
+/// read, also named, as its opaque data has no DXF form beside them.
+pub(super) fn prepare(doc: &mut CadDocument) -> Vec<String> {
+    let classes: Vec<_> = doc.classes.iter().cloned().collect();
+    let mut numbers = HashMap::new();
+    let mut identities = HashMap::new();
+    for (index, class) in classes.iter().enumerate() {
+        let number = class_number(index).ok();
+        numbers.entry(i32::from(class.class_number)).and_modify(|v| *v = None).or_insert(number.map(i32::from));
+        let identity = (class.dxf_name.as_str(), class.cpp_class_name.as_str(), class.is_an_entity);
+        identities.entry(identity).and_modify(|v| *v = None).or_insert(number);
+    }
+    let identity = |dxf: &str, cpp: &str, entity: bool| {
+        identities
+            .get(&(dxf, cpp, entity))
+            .copied()
+            .flatten()
+            .map(i32::from)
+            .ok_or_else(|| format!("missing or ambiguous application CLASS for {dxf:.80} ({cpp:.80})"))
+    };
+    let Some(dwg_version) = super::native::proxy_dwg_version(doc.dwg_source_version.unwrap_or(doc.version)) else { return Vec::new() };
+    let maintenance = i32::from(doc.maintenance_version);
+    let remap = |id: i32| numbers.get(&id).copied().flatten().ok_or_else(|| format!("proxy names missing or ambiguous application class {id}"));
+    // Only mutate proxies: entities_mut invalidates the decoder's verbatim records for every entity.
+    let handles: Vec<_> = doc
+        .entities()
+        .filter_map(|e| match e {
+            EntityType::Extended(e) => match &e.data {
+                ExtendedEntityData::Proxy(_) => Some(e.common.handle),
+                ExtendedEntityData::RegisteredClass(data) if data.properties.is_empty() || data.payload.bit_count > 0 => Some(e.common.handle),
+                _ => None,
+            },
+            _ => None,
+        })
+        .collect();
+    let mut notes = Vec::new();
+    let mut entity_count = 0usize;
+    let mut object_count = 0usize;
+    let mut semantic = 0usize;
+    for handle in handles {
+        // Ok(None): not an application record; Ok(Some(None)): kept as read, with its properties.
+        let converted = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| -> Result<Option<Option<ExtendedEntityData>>, String> {
+            let Some(EntityType::Extended(entity)) = doc.get_entity(handle) else { return Ok(None) };
+            let data = match &entity.data {
+                ExtendedEntityData::Proxy(data) => {
+                    let mut proxy = data.clone();
+                    proxy.class_id = remap(proxy.class_id)?;
+                    ExtendedEntityData::Proxy(proxy)
+                }
+                ExtendedEntityData::RegisteredClass(data) => {
+                    if !data.properties.is_empty() {
+                        return Ok(Some(None));
+                    }
+                    let class_id = identity(&data.dxf_name, &data.cpp_class_name, true)?;
+                    let text_payload = entity.common.raw_record.as_deref().map(registered_text).transpose()?.unwrap_or_default();
+                    ExtendedEntityData::Proxy(ProxyEntityData {
+                        proxy_id: 498,
+                        class_id,
+                        dxf_subclass: String::new(),
+                        version: (maintenance << 16) | dwg_version,
+                        dwg_version,
+                        maintenance_version: maintenance,
+                        from_dxf: false,
+                        graphics: ProxyPayload::from_bytes(entity.common.graphic_data.as_deref().unwrap_or_default()),
+                        payload: data.payload.clone(),
+                        text_payload,
+                        object_ids: data.object_ids.clone(),
+                    })
+                }
+                _ => return Ok(None),
+            };
+            Ok(Some(Some(data)))
+        }))
+        .unwrap_or_else(|_| Err("application record conversion failed".into()));
+        match converted {
+            Ok(Some(Some(data))) => {
+                if let Some(EntityType::Extended(entity)) = doc.get_entity_mut(handle) {
+                    entity.data = data;
+                }
+            }
+            Ok(Some(None)) => semantic = semantic.saturating_add(1),
+            Ok(None) => {}
+            Err(why) => {
+                doc.remove_entity(handle);
+                entity_count = entity_count.saturating_add(1);
+                skipped_note(&mut notes, "entity", handle, &why);
+            }
+        }
+    }
+    doc.objects.retain(|handle, object| {
+        if let ObjectType::ProxyObject(proxy) = object {
+            match remap(proxy.class_id) {
+                Ok(id) => proxy.class_id = id,
+                Err(why) => {
+                    object_count = object_count.saturating_add(1);
+                    skipped_note(&mut notes, "object", *handle, &why);
+                    return false;
+                }
+            }
+        }
+        true
+    });
+    if entity_count > 0 || object_count > 0 {
+        notes.insert(0, format!("DWG: partial read; application proxy records left out (entities: {entity_count}, objects: {object_count})"));
+    }
+    if semantic > 0 {
+        notes.push(format!(
+            "DWG: {semantic} registered entities with decoded properties keep them, without their other data; saving over the original file would lose it"
+        ));
+    }
+    notes
+}
+
+fn skipped_note(notes: &mut Vec<String>, kind: &str, handle: acadrust::types::Handle, why: &str) {
+    if notes.len() < 6 {
+        let why: String = why.chars().take(256).collect();
+        notes.push(format!("DWG: proxy {kind} {handle} left out: {why}"));
+    }
+}
+
+/// The decoder's registered-class representation omits the separate R2007+ string stream.
+fn registered_text(raw: &acadrust::entities::RawRecord) -> Result<ProxyPayload, String> {
+    use acadrust::io::dwg::DwgVersion;
+    use acadrust::io::dwg::dwg_stream_readers::object_reader::DwgObjectReader;
+    use acadrust::io::dwg::dwg_stream_writers::bit_writer::DwgBitWriter;
+    use acadrust::types::DxfVersion;
+
+    if raw.version < DxfVersion::AC1021 {
+        return Ok(ProxyPayload::default());
+    }
+    let version = DwgVersion::from_dxf_version(raw.version).map_err(|e| format!("DWG proxy text: {e}"))?;
+    let handle_bits = usize::try_from(raw.handle_bits).map_err(|_| "DWG proxy text: negative handle stream size")?;
+    let total_bits = raw.data.len().checked_mul(8).ok_or("DWG proxy text: record too large")?;
+    if handle_bits > total_bits {
+        return Err("DWG proxy text: handle stream exceeds record".into());
+    }
+    // Frame the verbatim record for the dependency's checked object reader.
+    let mut frame = DwgBitWriter::new(version, raw.version);
+    frame.write_modular_short(raw.data.len());
+    if raw.version >= DxfVersion::AC1024 {
+        frame.write_modular_char(handle_bits);
+    }
+    frame.write_bytes(&raw.data);
+    let reader = DwgObjectReader::new(frame.into_bytes(), raw.version, HashMap::new()).map_err(|e| format!("DWG proxy text: {e}"))?;
+    let (kind, mut streams) = reader.read_record_at(0).map_err(|e| format!("DWG proxy text: {e}"))?;
+    reader.read_common_entity_data(&mut streams, kind);
+    if kind == 498 {
+        // An existing registered-class envelope is a proxy and carries its class name first.
+        streams.read_variable_text();
+    } else if kind < 500 {
+        return Err("DWG proxy text: registered entity has no application class".into());
+    }
+    streams.check_error().map_err(|e| format!("DWG proxy text: {e}"))?;
+    let bits = usize::try_from(streams.text_remaining_bits()).map_err(|_| "DWG proxy text: negative string stream size")?;
+    if bits > total_bits {
+        return Err("DWG proxy text: string stream exceeds record".into());
+    }
+    let count = u32::try_from(bits).map_err(|_| "DWG proxy text: string stream too large")?;
+    let mut bytes = vec![0; bits.div_ceil(8)];
+    for (index, byte) in bytes.iter_mut().enumerate() {
+        for bit in 0..8.min(bits.saturating_sub(index * 8)) {
+            if streams.read_text_bit() {
+                *byte |= 0x80 >> bit;
+            }
+        }
+    }
+    streams.check_error().map_err(|e| format!("DWG proxy text: {e}"))?;
+    Ok(ProxyPayload::from_bits(&bytes, count))
+}
+
+/// ASCII DXF pairs decoded with the bridge's public code-page and escape codecs. A malformed
+/// pair yields `None`, so both class scans fall back rather than guessing its identity.
+pub(super) fn text_pairs(dxf: &[u8]) -> Option<impl Iterator<Item = Option<(i32, String)>> + '_> {
+    use acadrust::io::dxf::code_page::{decode_legacy_escapes, encoding_from_code_page};
+
+    if dxf.starts_with(b"AutoCAD Binary DXF") {
+        return None;
+    }
+    let version =
+        super::native::header_value(dxf, b"$ACADVER").and_then(|(_, v)| std::str::from_utf8(v).ok()).map(acadrust::DxfVersion::from_version_string);
+    let unicode = version.is_some_and(|v| v >= acadrust::DxfVersion::AC1021);
+    let encoding = if version.is_some_and(|v| v < acadrust::DxfVersion::AC1021) {
+        super::native::header_value(dxf, b"$DWGCODEPAGE").and_then(|(_, page)| std::str::from_utf8(page).ok()).and_then(encoding_from_code_page)
+    } else {
+        None
+    };
+    let mut lines = dxf.split(|b| *b == b'\n').map(|line| line.strip_suffix(b"\r").unwrap_or(line));
+    Some(std::iter::from_fn(move || {
+        let code = lines.next()?;
+        let Some(value) = lines.next() else { return (!code.trim_ascii().is_empty()).then_some(None) };
+        let pair = || {
+            let code = std::str::from_utf8(code).ok()?.trim().parse().ok()?;
+            let text = if let Some(encoding) = encoding {
+                encoding.decode(value).0.into_owned()
+            } else if unicode {
+                String::from_utf8_lossy(value).into_owned()
+            } else {
+                // The decoder uses UTF-8 with Latin-1 fallback when no encoding was declared.
+                std::str::from_utf8(value).map_or_else(|_| value.iter().map(|&b| char::from(b)).collect(), str::to_string)
+            };
+            let text = decode_legacy_escapes(&text);
+            // DXF's escaped control characters are decoded after CIF/MIF, as in the bridge.
+            let text = text.replace("^J", "\n").replace("^M", "\r").replace("^I", "\t").replace("^ ", "^");
+            Some((code, text))
+        };
+        Some(pair())
+    }))
+}
+
+/// The CLASS records of an ASCII DXF, in CLASSES order and numbered by place from 500 (DXF
+/// Reference, CLASSES; a proxy's group 91 is that number). `None` for a binary DXF (the bridge's
+/// generated DXF is ASCII), and for one with a record that can't be written back as it is: no names,
+/// flags or instance count out of range, more classes than the numbers allow. Then
+/// `proxy_classes` matches the classes by name instead.
+pub(super) fn source_classes(dxf: &[u8]) -> Option<Vec<DxfClass>> {
+    let pairs = text_pairs(dxf)?;
+    let mut records: Vec<Vec<(i32, String)>> = Vec::new();
+    let (mut section, mut in_classes) = (false, false);
+    for pair in pairs {
+        let (code, value) = pair?;
+        match (code, value.as_str()) {
+            (0, "ENDSEC") if in_classes => break,
+            (0, "SECTION") => section = true,
+            (2, name) if section => {
+                in_classes = name == "CLASSES";
+                section = false;
+            }
+            (0, kind) if in_classes => {
+                if kind != "CLASS" {
+                    return None;
+                }
+                records.push(Vec::new());
+            }
+            (code, value) if in_classes => records.last_mut()?.push((code, value.to_string())),
+            _ => section = false,
+        }
+    }
+    records.iter().enumerate().map(|(index, groups)| source_class(groups, class_number(index).ok()?)).collect()
+}
+
+/// One CLASS record's groups as the class `number`, or `None` when it can't be written back.
+fn source_class(groups: &[(i32, String)], number: i16) -> Option<DxfClass> {
+    let text = |code| groups.iter().find(|(c, _)| *c == code).map(|(_, v)| v.clone()).unwrap_or_default();
+    let integer = |code| groups.iter().find(|(c, _)| *c == code).map_or(Some(0), |(_, v)| v.trim().parse::<i64>().ok());
+    let mut class = DxfClass::new(text(1), text(2));
+    if class.dxf_name.is_empty() || class.cpp_class_name.is_empty() {
+        return None;
+    }
+    class.application_name = text(3);
+    class.proxy_flags = ProxyFlags(u16::try_from(integer(90)?).ok()?);
+    class.instance_count = i32::try_from(integer(91)?).ok()?;
+    class.was_zombie = integer(280)? != 0;
+    class.is_an_entity = integer(281)? != 0;
+    class.item_class_id = if class.is_an_entity { 498 } else { 499 };
+    class.class_number = number;
+    Some(class)
+}
+
+/// Give a DWG of 2013 or later the source DXF's classes (`classes`, from [`source_classes`]) in
+/// their places, with their metadata and duplicate names, so each proxy's DXF class number names
+/// its own class; the decoder's default classes the source lacks follow them. A proxy whose number
+/// names no source class is left out, as `proxy_classes` leaves it out. Returns how many proxy objects and
+/// entities were left out; nothing changes when the drawing has no proxies. `None`, with nothing
+/// changed, when the classes would be more than the class numbers allow.
+pub(super) fn restore_classes(doc: &mut CadDocument, classes: Vec<DxfClass>) -> Option<(usize, usize)> {
+    let fits = |number: i32| number.checked_sub(500).and_then(|n| usize::try_from(n).ok()).is_some_and(|i| i < classes.len());
+    let mut any = false;
+    let mut entities = Vec::new();
+    for entity in doc.entities() {
+        if let EntityType::Extended(e) = entity
+            && let ExtendedEntityData::Proxy(p) = &e.data
+        {
+            any = true;
+            if !fits(p.class_id) {
+                entities.push(e.common.handle);
+            }
+        }
+    }
+    let mut objects = Vec::new();
+    for (handle, object) in &doc.objects {
+        if let ObjectType::ProxyObject(p) = object {
+            any = true;
+            if !fits(p.class_id) {
+                objects.push(*handle);
+            }
+        }
+    }
+    if !any {
+        return Some((0, 0));
+    }
+    let mut names: HashSet<_> = classes.iter().map(|c| c.dxf_name.to_uppercase()).collect();
+    let defaults: Vec<_> = doc.classes.iter().filter(|c| names.insert(c.dxf_name.to_uppercase())).cloned().collect();
+    if let Some(last) = classes.len().checked_add(defaults.len())?.checked_sub(1) {
+        class_number(last).ok()?;
+    }
+    for handle in &entities {
+        doc.remove_entity(*handle);
+    }
+    for handle in &objects {
+        doc.objects.remove(handle);
+    }
+    doc.classes.clear();
+    for (index, mut class) in classes.into_iter().chain(defaults).enumerate() {
+        class.class_number = class_number(index).ok()?;
+        doc.classes.push_preserving(class);
+    }
+    Some((objects.len(), entities.len()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use acadrust::entities::{EntityCommon, ExtendedEntity, RegisteredClassEntityData};
+    use acadrust::types::DxfVersion;
+
+    fn proxy_doc() -> CadDocument {
+        let mut doc = CadDocument::new();
+        doc.version = DxfVersion::AC1032;
+        doc.add_entity(EntityType::Extended(Box::new(ExtendedEntity {
+            common: EntityCommon::default(),
+            data: ExtendedEntityData::Proxy(ProxyEntityData {
+                proxy_id: 498,
+                class_id: 501,
+                dxf_subclass: String::new(),
+                version: 33,
+                dwg_version: 33,
+                maintenance_version: 0,
+                from_dxf: false,
+                graphics: ProxyPayload::default(),
+                payload: ProxyPayload::from_bits(&[0x80], 1),
+                text_payload: ProxyPayload::default(),
+                object_ids: vec![],
+            }),
+        })))
+        .unwrap();
+        doc
+    }
+
+    /// An ASCII DXF of `groups`, `(code, value)` per pair of lines.
+    fn dxf(groups: &[(i32, &str)]) -> Vec<u8> {
+        groups.iter().map(|(c, v)| format!("{c}\n{v}\n")).collect::<String>().into_bytes()
+    }
+
+    #[test]
+    fn source_classes_keep_duplicates_and_metadata_before_defaults() {
+        let bytes = dxf(&[
+            (0, "SECTION"),
+            (2, "HEADER"),
+            (9, "$DIMSTYLE"),
+            (2, "CLASSES"),
+            (0, "ENDSEC"),
+            (0, "SECTION"),
+            (2, "CLASSES"),
+            (0, "CLASS"),
+            (1, "Объект"),
+            (2, "First"),
+            (3, "Первый"),
+            (90, "1025"),
+            (91, "7"),
+            (280, "1"),
+            (281, "1"),
+            (0, "CLASS"),
+            (1, "Объект"),
+            (2, "Second"),
+            (3, "Второй"),
+            (90, "128"),
+            (281, "1"),
+            (0, "ENDSEC"),
+            (0, "EOF"),
+        ]);
+        let classes = source_classes(&bytes).unwrap();
+        assert_eq!(classes.len(), 2);
+        assert_eq!(classes[0].application_name, "Первый");
+        assert_eq!(classes[0].proxy_flags.0, 1025);
+        assert_eq!(classes[0].instance_count, 7);
+        assert!(classes[0].was_zombie);
+        assert_eq!((classes[0].class_number, classes[1].class_number), (500, 501));
+        assert_eq!(classes[1].cpp_class_name, "Second");
+        let mut doc = proxy_doc();
+        assert_eq!(restore_classes(&mut doc, classes.clone()), Some((0, 0)));
+        assert_eq!(doc.classes.iter().take(2).cloned().collect::<Vec<_>>(), classes);
+        // A binary DXF, and a CLASS record that can't be written back as it is, give no classes.
+        assert!(source_classes(b"AutoCAD Binary DXF\r\n\x1a\0").is_none());
+        for (code, value) in [(1, ""), (2, ""), (90, "65536"), (91, "9223372036854775807"), (281, "x")] {
+            let mut class = vec![(1, "A"), (2, "A")];
+            class.retain(|(c, _)| *c != code);
+            class.push((code, value));
+            let mut groups = vec![(0, "SECTION"), (2, "CLASSES"), (0, "CLASS")];
+            groups.extend(class);
+            groups.extend([(0, "ENDSEC"), (0, "EOF")]);
+            assert!(source_classes(&dxf(&groups)).is_none(), "{code} {value}");
+        }
+    }
+
+    #[test]
+    fn source_classes_decode_escapes_once_and_respect_legacy_code_pages() {
+        let body = "0\nCLASS\n1\n\\U+041E\\U+0431\\U+044A\\U+0435\\U+043A\\U+0442\n2\nClass\n3\nCaf\\U+00E9\\U+D83D\\U+DE42\\U+005CU+0041\n281\n1\n0\nENDSEC\n0\nEOF\n";
+        let text = format!("0\nSECTION\n2\nCLASSES\n{body}");
+        let classes = source_classes(text.as_bytes()).unwrap();
+        assert_eq!(classes[0].dxf_name, "Объект");
+        assert_eq!(classes[0].application_name, "Café🙂\\U+0041");
+
+        let prefix =
+            b"0\nSECTION\n2\nHEADER\n9\n$ACADVER\n1\nAC1015\n9\n$DWGCODEPAGE\n3\nANSI_1251\n0\nENDSEC\n0\nSECTION\n2\nCLASSES\n0\nCLASS\n1\n";
+        let encoded = [prefix.as_slice(), b"\xCF\xF0\xE8\xEC\xE5\xF0", b"\n2\nClass\n3\nApp\n281\n1\n0\nENDSEC\n0\nEOF\n"].concat();
+        assert_eq!(source_classes(&encoded).unwrap()[0].dxf_name, "Пример");
+        // R2007+ text is UTF-8 even with a legacy code-page declaration.
+        let modern = String::from_utf8_lossy(prefix).replace("AC1015", "AC1032") + "Пример\n2\nClass\n3\nApp\n281\n1\n0\nENDSEC\n0\nEOF\n";
+        assert_eq!(source_classes(modern.as_bytes()).unwrap()[0].dxf_name, "Пример");
+    }
+
+    #[test]
+    fn proxies_of_missing_classes_are_left_out() {
+        for id in [-1, 499, 501, i32::MAX] {
+            let mut doc = proxy_doc();
+            if let Some(EntityType::Extended(e)) = doc.entities_mut().next()
+                && let ExtendedEntityData::Proxy(p) = &mut e.data
+            {
+                p.class_id = id;
+            }
+            let mut class = DxfClass::new_entity("ENTITY", "Entity");
+            class.class_number = 500;
+            assert_eq!(restore_classes(&mut doc, vec![class]), Some((0, 1)), "{id}");
+            assert_eq!(doc.entities().count(), 0);
+        }
+        // Class 501 is there: the proxy keeps it, in its place.
+        let mut doc = proxy_doc();
+        assert_eq!(restore_classes(&mut doc, vec![DxfClass::new("A", "A"), DxfClass::new_entity("B", "B")]), Some((0, 0)));
+        assert_eq!(doc.entities().count(), 1);
+        assert_eq!(doc.classes.iter().nth(1).map(|c| (c.dxf_name.clone(), c.class_number)), Some(("B".to_string(), 501)));
+        // Without proxies the classes stay the decoder's.
+        let mut doc = CadDocument::new();
+        let before: Vec<_> = doc.classes.iter().cloned().collect();
+        assert_eq!(restore_classes(&mut doc, vec![DxfClass::new("A", "A")]), Some((0, 0)));
+        assert_eq!(doc.classes.iter().cloned().collect::<Vec<_>>(), before);
+    }
+
+    #[test]
+    fn unrepresentable_proxies_keep_other_geometry_and_bounded_diagnostics() {
+        use acadrust::entities::{Line, RawRecord};
+        use acadrust::objects::ProxyObject;
+        use acadrust::types::{Handle, Vector3};
+        for count in [1, 10] {
+            let mut doc = proxy_doc();
+            if let Some(EntityType::Extended(e)) = doc.entities_mut().next()
+                && let ExtendedEntityData::Proxy(p) = &mut e.data
+            {
+                p.class_id = i32::MAX;
+            }
+            let template = doc.entities().next().unwrap().clone();
+            for _ in 1..count {
+                let mut entity = template.clone();
+                entity.common_mut().handle = Handle::NULL;
+                doc.add_entity(entity).unwrap();
+            }
+            let object = Handle::new(u64::MAX - 1);
+            assert!(!doc.objects.contains_key(&object));
+            doc.objects.insert(object, ObjectType::ProxyObject(ProxyObject { handle: object, class_id: i32::MAX, ..Default::default() }));
+            let line = doc.add_entity(EntityType::Line(Line::from_points(Vector3::new(2.0, 3.0, 0.0), Vector3::new(12.0, 13.0, 0.0)))).unwrap();
+            let raw = RawRecord { data: vec![0xAA, 0x55], handle_bits: 0, version: DxfVersion::AC1032 };
+            doc.get_entity_mut(line).unwrap().common_mut().raw_record = Some(std::sync::Arc::new(raw.clone()));
+            let notes = prepare(&mut doc);
+            assert_eq!(notes.len(), (count + 1).min(6) + 1);
+            assert!(notes.iter().all(|n| n.starts_with("DWG:")));
+            assert!(notes[0].contains(&format!("entities: {count}, objects: 1")));
+            assert_eq!(doc.entities().count(), 1);
+            assert!(!doc.objects.contains_key(&object));
+            let Some(EntityType::Line(actual)) = doc.get_entity(line) else { panic!("readable line") };
+            assert_eq!(actual.start, Vector3::new(2.0, 3.0, 0.0));
+            assert_eq!(actual.end, Vector3::new(12.0, 13.0, 0.0));
+            assert_eq!(doc.get_entity(line).unwrap().common().raw_record.as_deref(), Some(&raw));
+        }
+    }
+    #[test]
+    fn opaque_registered_class_ambiguity_is_not_guessed() {
+        let mut doc = CadDocument::new();
+        doc.classes.push_preserving(DxfClass::new_entity("CUSTOM", "Custom"));
+        doc.classes.push_preserving(DxfClass::new_entity("CUSTOM", "Custom"));
+        doc.add_entity(EntityType::Extended(Box::new(ExtendedEntity {
+            common: EntityCommon::default(),
+            data: ExtendedEntityData::RegisteredClass(RegisteredClassEntityData {
+                dxf_name: "CUSTOM".into(),
+                cpp_class_name: "Custom".into(),
+                properties: vec![],
+                payload: ProxyPayload::from_bits(&[0x80], 1),
+                object_ids: vec![],
+            }),
+        })))
+        .unwrap();
+        assert!(prepare(&mut doc).iter().any(|n| n.contains("ambiguous")));
+        assert_eq!(doc.entities().count(), 0);
+        assert!(class_number(usize::MAX).is_err());
+    }
+    #[test]
+    fn semantic_records_keep_verbatim_data_and_mixed_payloads_are_reported() {
+        use acadrust::entities::RawRecord;
+        use acadrust::objects::{SemanticProperty, SemanticPropertyValue};
+        for payload in [ProxyPayload::default(), ProxyPayload::from_bits(&[0x80], 1)] {
+            let mut doc = CadDocument::new();
+            let raw = RawRecord { data: vec![0xAA], handle_bits: 0, version: DxfVersion::AC1032 };
+            let handle = doc
+                .add_entity(EntityType::Extended(Box::new(ExtendedEntity {
+                    common: EntityCommon::default(),
+                    data: ExtendedEntityData::RegisteredClass(RegisteredClassEntityData {
+                        dxf_name: "SEMANTIC".into(),
+                        cpp_class_name: "Semantic".into(),
+                        properties: vec![SemanticProperty {
+                            subclass: "Semantic".into(),
+                            code: 1,
+                            value: SemanticPropertyValue::Text("value".into()),
+                        }],
+                        payload: payload.clone(),
+                        object_ids: vec![],
+                    }),
+                })))
+                .unwrap();
+            doc.get_entity_mut(handle).unwrap().common_mut().raw_record = Some(std::sync::Arc::new(raw.clone()));
+            assert_eq!(doc.get_entity(handle).unwrap().common().raw_record.as_deref(), Some(&raw));
+            if payload.bit_count == 0 {
+                assert!(prepare(&mut doc).is_empty());
+                assert_eq!(doc.get_entity(handle).unwrap().common().raw_record.as_deref(), Some(&raw));
+            } else {
+                // Kept as read, and named: its opaque data has no DXF form beside the properties.
+                assert!(prepare(&mut doc).iter().any(|n| n.contains("decoded properties")));
+                assert_eq!(doc.get_entity(handle).unwrap().common().raw_record.as_deref(), Some(&raw));
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod string_stream_tests {
+    use super::*;
+    use acadrust::entities::{EntityCommon, ExtendedEntity, RawRecord, RegisteredClassEntityData};
+    use acadrust::types::DxfVersion;
+    use std::io::Cursor;
+
+    #[test]
+    fn registered_transport_recovers_separate_non_byte_aligned_strings() {
+        for version in [DxfVersion::AC1027, DxfVersion::AC1032] {
+            let mut source = CadDocument::new();
+            source.version = version;
+            source.classes.add_or_update(DxfClass::new_entity("CUSTOM_TEXT", "CustomText"));
+            let class_id = i32::from(source.classes.get_by_name("CUSTOM_TEXT").unwrap().class_number);
+            let text = ProxyPayload::from_bits(&[0xA5, 0xC7, 0xE0], 19);
+            let payload = ProxyPayload::from_bits(&[0x80], 1);
+            source
+                .add_entity(EntityType::Extended(Box::new(ExtendedEntity {
+                    common: EntityCommon::default(),
+                    data: ExtendedEntityData::Proxy(ProxyEntityData {
+                        proxy_id: 498,
+                        class_id,
+                        dxf_subclass: "CustomText".into(),
+                        version: 33,
+                        dwg_version: 33,
+                        maintenance_version: 0,
+                        from_dxf: false,
+                        graphics: ProxyPayload::default(),
+                        payload: payload.clone(),
+                        text_payload: text.clone(),
+                        object_ids: vec![],
+                    }),
+                })))
+                .unwrap();
+            let bytes = acadrust::DwgWriter::write_to_vec(&source).unwrap();
+            let mut decoded = acadrust::DwgReader::from_stream(Cursor::new(bytes)).read().unwrap();
+            let entity = decoded.entities().next().unwrap();
+            let handle = entity.common().handle;
+            let raw = entity.common().raw_record.clone().unwrap();
+            assert_eq!(registered_text(&raw).unwrap().data(), text.data());
+            assert_eq!(registered_text(&raw).unwrap().bit_count, 19);
+            let EntityType::Extended(entity) = decoded.get_entity_mut(handle).unwrap() else { panic!() };
+            entity.data = ExtendedEntityData::RegisteredClass(RegisteredClassEntityData {
+                dxf_name: "CUSTOM_TEXT".into(),
+                cpp_class_name: "CustomText".into(),
+                properties: vec![],
+                payload: payload.clone(),
+                object_ids: vec![],
+            });
+            entity.common.raw_record = Some(raw);
+            assert!(prepare(&mut decoded).is_empty());
+            for _ in 0..2 {
+                let mut dxf = Vec::new();
+                acadrust::DxfWriter::new(&decoded).write_to_writer(&mut dxf).unwrap();
+                let bytes = crate::dxf_to_dwg_as(&dxf, "AC1032").unwrap();
+                decoded = acadrust::DwgReader::from_stream(Cursor::new(bytes)).read().unwrap();
+                let p = decoded
+                    .entities()
+                    .find_map(|e| match e {
+                        EntityType::Extended(e) => match &e.data {
+                            ExtendedEntityData::Proxy(p) => Some(p),
+                            _ => None,
+                        },
+                        _ => None,
+                    })
+                    .unwrap();
+                assert_eq!(p.payload.bit_count, 1);
+                assert_eq!(p.payload.data(), payload.data());
+                assert_eq!(p.text_payload.bit_count, 19);
+                assert_eq!(p.text_payload.data(), text.data());
+            }
+        }
+    }
+
+    #[test]
+    fn invalid_string_stream_boundaries_return_errors() {
+        for handle_bits in [-1, 1000] {
+            let raw = RawRecord { data: vec![0; 8], handle_bits, version: DxfVersion::AC1032 };
+            assert!(registered_text(&raw).is_err());
+        }
+    }
+}
diff --git a/crates/dwg/src/worker.rs b/crates/dwg/src/worker.rs
new file mode 100644
index 000000000..0c273257b
--- /dev/null
+++ b/crates/dwg/src/worker.rs
@@ -0,0 +1,378 @@
+//! The DWG reader and writer in a child process.
+//!
+//! An allocation failure or stack overflow in the third-party code ends the process it runs in, and
+//! `catch_unwind` can't stop that. So the app runs them in a copy of itself: [`use_own_worker`] says
+//! how to start one, and [`serve_if_asked`], first thing in `main`, turns the copy into a worker
+//! that reads one request from standard input and writes one reply to standard output. A file that
+//! kills the worker then costs that one open or save, and every other open drawing stays safe.
+//!
+//! Without a worker (libraries, tests, a build that can't start one) [`decode`] and [`encode_as`]
+//! run in the calling process, as they always did. There's no memory limit on the worker yet: that
+//! takes per-platform system calls, which `unsafe_code = "forbid"` keeps out of this crate.
+//!
+//! A reply comes from a process that just handled a possibly hostile file, so it is parsed as
+//! untrusted input.
+
+use std::ffi::OsString;
+use std::io::{Read, Write};
+use std::path::PathBuf;
+use std::process::{Command, Stdio};
+use std::sync::Mutex;
+use std::sync::mpsc::{RecvTimeoutError, channel};
+use std::time::Duration;
+
+use super::Limits;
+
+/// The argument that makes the app a worker.
+pub const WORKER_ARG: &str = "--dwg-worker";
+/// Bumped when the messages change: an app updated while running may start a newer copy.
+const PROTOCOL: u8 = 2;
+const DECODE: u8 = 1;
+const ENCODE: u8 = 2;
+const CRASH: u8 = 0xff;
+/// How long one file may take before the worker is stopped. It can't be interrupted otherwise.
+const TIMEOUT: Duration = Duration::from_secs(30 * 60);
+/// Most bytes accepted for what a reply carries besides the drawing.
+const MAX_NOTES_BYTES: u64 = 64 << 20;
+/// Most bytes accepted as a written DWG.
+const MAX_DWG_REPLY: u64 = 2 << 30;
+/// Most bytes one request holds: the largest input, whichever the direction, and its header.
+const MAX_REQUEST: u64 = (2 << 30) + 256;
+
+struct Worker {
+    program: PathBuf,
+    args: Vec<OsString>,
+}
+
+static WORKER: Mutex<Option<Worker>> = Mutex::new(None);
+
+/// Start `program args` as the worker from now on. `program` must call [`serve_if_asked`].
+pub fn use_worker(program: PathBuf, args: Vec<OsString>) {
+    if let Ok(mut w) = WORKER.lock() {
+        *w = Some(Worker { program, args });
+    }
+}
+
+/// Use a copy of this program as the worker, started with [`WORKER_ARG`]. If its path can't be
+/// found, the reader and writer stay in this process.
+pub fn use_own_worker() {
+    match std::env::current_exe() {
+        Ok(program) => use_worker(program, vec![WORKER_ARG.into()]),
+        Err(e) => log::warn!("DWG worker: can't find this program: {e}"),
+    }
+}
+
+/// Serve one request and return the exit code if this process was started as a worker.
+pub fn serve_if_asked() -> Option<i32> {
+    (std::env::args_os().nth(1)? == WORKER_ARG).then(|| serve(std::io::stdin().lock(), std::io::stdout().lock()))
+}
+
+/// [`super::dwg_to_dxf_noted`] in the worker, when there is one.
+pub fn decode(bytes: &[u8], limits: Limits) -> Result<(Vec<u8>, Vec<String>), String> {
+    // Before starting a process, and so the same limit holds with or without one.
+    if bytes.len() > limits.max_dwg_bytes {
+        return super::dwg_to_dxf_noted(bytes, limits);
+    }
+    let reply_limit = (limits.max_dxf_bytes as u64).saturating_add(MAX_NOTES_BYTES);
+    match call(&request(DECODE, limits, ""), bytes, reply_limit, "reading this file") {
+        Some(reply) => reply?,
+        None => super::dwg_to_dxf_noted(bytes, limits),
+    }
+}
+
+/// [`super::dxf_to_dwg_as`] in the worker, when there is one.
+pub fn encode_as(dxf: &[u8], version: &str) -> Result<Vec<u8>, String> {
+    encode_noted(dxf, version).map(|(dwg, _)| dwg)
+}
+
+/// [`super::dxf_to_dwg_noted`] in the worker, when there is one. What the writer left out comes
+/// back as notes of `TYPE<tab>count`.
+pub fn encode_noted(dxf: &[u8], version: &str) -> Result<(Vec<u8>, super::Unwritten), String> {
+    encode_kept_noted(dxf, version, None)
+}
+
+/// [`encode_noted`] for a DXF whose carried-over groups were read from a file of version `kept`
+/// ([`super::dxf_to_dwg_kept_noted`]); `None` is [`encode_noted`].
+pub fn encode_kept_noted(dxf: &[u8], version: &str, kept: Option<&str>) -> Result<(Vec<u8>, super::Unwritten), String> {
+    if u8::try_from(version.len()).is_err() {
+        return Err(super::unsupported(version));
+    }
+    // A kept version too long to send is unsupported by this bridge and changes nothing.
+    let kept = kept.filter(|k| u8::try_from(k.len()).is_ok());
+    let mut header = request(ENCODE, Limits::DEFAULT, version);
+    push_str(&mut header, kept.unwrap_or(""));
+    match call(&header, dxf, MAX_DWG_REPLY, "writing this file") {
+        Some(reply) => reply?.map(|(dwg, notes)| (dwg, unwritten_from(&notes))),
+        None => encode_here(dxf, version, kept),
+    }
+}
+
+/// The conversion in this process.
+fn encode_here(dxf: &[u8], version: &str, kept: Option<&str>) -> Result<(Vec<u8>, super::Unwritten), String> {
+    match kept {
+        Some(kept) => super::dxf_to_dwg_kept_noted(dxf, version, kept),
+        None => super::dxf_to_dwg_noted(dxf, version),
+    }
+}
+
+fn unwritten_from(notes: &[String]) -> super::Unwritten {
+    notes.iter().filter_map(|n| n.split_once('\t')).filter_map(|(kind, n)| Some((kind.to_string(), n.parse::<usize>().ok()?))).fold(
+        super::Unwritten::new(),
+        |mut m, (kind, n)| {
+            *m.entry(kind).or_insert(0) = n;
+            m
+        },
+    )
+}
+
+/// Make the worker abort, as the third-party code can: what the tests prove isolation with.
+#[doc(hidden)]
+pub fn crash_worker_for_test() -> Result<(), String> {
+    call(&request(CRASH, Limits::DEFAULT, ""), &[], 1024, "testing").ok_or("no worker")??.map(|_| ())
+}
+
+fn request(op: u8, limits: Limits, version: &str) -> Vec<u8> {
+    let mut r = vec![PROTOCOL, op];
+    r.extend((limits.max_dwg_bytes as u64).to_le_bytes());
+    r.extend((limits.max_dxf_bytes as u64).to_le_bytes());
+    push_str(&mut r, version);
+    r
+}
+
+/// `text` with a one-byte length before it; callers keep it under 256 bytes.
+fn push_str(r: &mut Vec<u8>, text: &str) {
+    r.push(u8::try_from(text.len()).unwrap_or(0));
+    r.extend(text.as_bytes());
+}
+
+type Reply = Result<(Vec<u8>, Vec<String>), String>;
+
+/// Run one request in a worker. `None`: none could be started, so the caller does the work.
+/// `Err`: the worker went wrong, and `doing` says at what, for the user.
+fn call(header: &[u8], payload: &[u8], reply_limit: u64, doing: &str) -> Option<Result<Reply, String>> {
+    let mut command = {
+        let worker = WORKER.lock().ok()?;
+        let worker = worker.as_ref()?;
+        let mut c = Command::new(&worker.program);
+        c.args(&worker.args);
+        c
+    };
+    command.stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::null());
+    #[cfg(windows)]
+    {
+        use std::os::windows::process::CommandExt;
+        const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+        command.creation_flags(CREATE_NO_WINDOW);
+    }
+    let mut child = match command.spawn() {
+        Ok(c) => c,
+        Err(e) => {
+            log::warn!("DWG worker: can't start it: {e}");
+            return None;
+        }
+    };
+    let (Some(mut to_child), Some(from_child)) = (child.stdin.take(), child.stdout.take()) else {
+        let _ = child.kill();
+        let _ = child.wait();
+        return None;
+    };
+    let received = std::thread::scope(|scope| {
+        // Written beside the read: a worker that replies before it has read everything, or dies,
+        // must block neither side. A failed write shows up as the reply going wrong.
+        scope.spawn(move || {
+            let _ = to_child.write_all(header).and_then(|()| to_child.write_all(payload));
+        });
+        let (tx, rx) = channel();
+        scope.spawn(move || {
+            let mut reply = Vec::new();
+            let read = from_child.take(reply_limit).read_to_end(&mut reply);
+            let _ = tx.send(read.map(|_| reply));
+        });
+        let received = rx.recv_timeout(TIMEOUT);
+        if matches!(received, Err(RecvTimeoutError::Timeout)) {
+            let _ = child.kill();
+        }
+        received
+    });
+    let status = child.wait();
+    let stopped = || format!("the DWG worker stopped while {doing}; nothing else is affected");
+    Some(match (received, status) {
+        (Err(RecvTimeoutError::Timeout), _) => Err(format!("{doing} took too long, so the DWG worker was stopped; nothing else is affected")),
+        (Ok(Ok(reply)), Ok(status)) if status.success() => parse_reply(reply).ok_or_else(stopped),
+        _ => Err(stopped()),
+    })
+}
+
+/// Take `n` bytes off the front of `b`.
+fn take<'a>(b: &mut &'a [u8], n: usize) -> Option<&'a [u8]> {
+    let (head, tail) = b.split_at_checked(n)?;
+    *b = tail;
+    Some(head)
+}
+
+fn take_u32(b: &mut &[u8]) -> Option<usize> {
+    let bytes: [u8; 4] = take(b, 4)?.try_into().ok()?;
+    usize::try_from(u32::from_le_bytes(bytes)).ok()
+}
+
+fn take_u64(b: &mut &[u8]) -> Option<u64> {
+    Some(u64::from_le_bytes(take(b, 8)?.try_into().ok()?))
+}
+
+/// A reply: 0, the note count, each note with its length, then the bytes with their length; or 1
+/// and a message. `None` when it isn't one, whole. Takes the reply, because the bytes can be most
+/// of the memory the app may use: they are kept, not copied.
+fn parse_reply(mut reply: Vec<u8>) -> Option<Reply> {
+    let total = reply.len();
+    let mut b = &reply[..];
+    match *take(&mut b, 1)?.first()? {
+        0 => {
+            let count = take_u32(&mut b)?;
+            let mut notes = Vec::new();
+            for _ in 0..count {
+                let n = take_u32(&mut b)?;
+                notes.push(String::from_utf8_lossy(take(&mut b, n)?).into_owned());
+            }
+            let n = usize::try_from(take_u64(&mut b)?).ok()?;
+            if b.len() != n {
+                return None;
+            }
+            reply.drain(..total - n);
+            Some(Ok((reply, notes)))
+        }
+        1 => Some(Err(String::from_utf8_lossy(b).into_owned())),
+        _ => None,
+    }
+}
+
+fn write_reply(out: &mut impl Write, reply: Reply) -> std::io::Result<()> {
+    match reply {
+        Ok((bytes, notes)) => {
+            out.write_all(&[0])?;
+            out.write_all(&u32::try_from(notes.len()).unwrap_or(0).to_le_bytes())?;
+            for note in &notes {
+                out.write_all(&u32::try_from(note.len()).unwrap_or(0).to_le_bytes())?;
+                if u32::try_from(note.len()).is_ok() {
+                    out.write_all(note.as_bytes())?;
+                }
+            }
+            out.write_all(&(bytes.len() as u64).to_le_bytes())?;
+            out.write_all(&bytes)?;
+        }
+        Err(e) => {
+            out.write_all(&[1])?;
+            out.write_all(e.as_bytes())?;
+        }
+    }
+    out.flush()
+}
+
+/// What a request asks for, or why it can't be served.
+fn handle(mut b: &[u8]) -> Reply {
+    let bad = || "the DWG worker got a request it can't read (a different bridge version?)".to_string();
+    if take(&mut b, 1).and_then(<[u8]>::first) != Some(&PROTOCOL) {
+        return Err(bad());
+    }
+    let op = take(&mut b, 1).and_then(<[u8]>::first).copied().ok_or_else(bad)?;
+    let max_dwg_bytes = take_u64(&mut b).and_then(|n| usize::try_from(n).ok()).ok_or_else(bad)?;
+    let max_dxf_bytes = take_u64(&mut b).and_then(|n| usize::try_from(n).ok()).ok_or_else(bad)?;
+    let version_len = take(&mut b, 1).and_then(<[u8]>::first).copied().ok_or_else(bad)?;
+    let version = take(&mut b, usize::from(version_len)).and_then(|v| std::str::from_utf8(v).ok()).ok_or_else(bad)?;
+    match op {
+        DECODE => super::dwg_to_dxf_noted(b, Limits { max_dwg_bytes, max_dxf_bytes }),
+        ENCODE => {
+            // The version the DXF's carried-over groups were read from; empty for none.
+            let kept_len = take(&mut b, 1).and_then(<[u8]>::first).copied().ok_or_else(bad)?;
+            let kept = take(&mut b, usize::from(kept_len)).and_then(|v| std::str::from_utf8(v).ok()).ok_or_else(bad)?;
+            encode_here(b, version, (!kept.is_empty()).then_some(kept))
+                .map(|(dwg, left_out)| (dwg, left_out.iter().map(|(kind, n)| format!("{kind}\t{n}")).collect()))
+        }
+        CRASH => std::process::abort(),
+        _ => Err(bad()),
+    }
+}
+
+/// Serve the one request on `input`. The exit code is 0 unless the reply couldn't be sent.
+fn serve(input: impl Read, mut output: impl Write) -> i32 {
+    let mut request = Vec::new();
+    let reply = match input.take(MAX_REQUEST).read_to_end(&mut request) {
+        Ok(_) => handle(&request),
+        Err(e) => Err(format!("the DWG worker could not read its request: {e}")),
+    };
+    i32::from(write_reply(&mut output, reply).is_err())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn wire(reply: Reply) -> Vec<u8> {
+        let mut out = Vec::new();
+        write_reply(&mut out, reply).unwrap();
+        out
+    }
+
+    #[test]
+    fn what_the_writer_left_out_survives_the_reply() {
+        let notes = vec!["ACME_WIDGET\t2".to_string(), "not a count".to_string(), "X\tmany".to_string()];
+        assert_eq!(unwritten_from(&notes), [("ACME_WIDGET".to_string(), 2)].into_iter().collect());
+    }
+
+    #[test]
+    fn replies_round_trip() {
+        let ok: Reply = Ok((b"bytes".to_vec(), vec!["one".into(), "two é".into()]));
+        assert_eq!(parse_reply(wire(ok.clone())), Some(ok));
+        let failed: Reply = Err("DWG: no".into());
+        assert_eq!(parse_reply(wire(failed.clone())), Some(failed));
+    }
+
+    #[test]
+    fn a_reply_cut_short_or_made_up_is_refused() {
+        let whole = wire(Ok((b"bytes".to_vec(), vec!["note".into()])));
+        for n in 0..whole.len() {
+            assert_eq!(parse_reply(whole[..n].to_vec()), None, "cut at {n}");
+        }
+        assert_eq!(parse_reply(vec![7, 0, 0]), None);
+        // A note count far beyond what follows ends at the first missing note.
+        assert_eq!(parse_reply(vec![0, 0xff, 0xff, 0xff, 0xff]), None);
+        assert_eq!(parse_reply(vec![0, 1, 0, 0, 0, 0xff, 0xff, 0xff, 0xff]), None);
+    }
+
+    #[test]
+    fn a_request_it_cannot_read_is_an_error_not_a_crash() {
+        for request in [
+            &[][..],
+            &[PROTOCOL + 1, DECODE],
+            &[PROTOCOL],
+            &[PROTOCOL, DECODE, 1, 2, 3],
+            &[PROTOCOL, 9, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+        ] {
+            assert!(handle(request).is_err(), "{request:?}");
+        }
+    }
+
+    /// An encode request carries the kept version after the target one; a request without it is
+    /// one it can't read, and one with it reaches the converter.
+    #[test]
+    fn an_encode_request_carries_the_kept_version() {
+        let bad = "the DWG worker got a request it can't read (a different bridge version?)";
+        let short = self::request(ENCODE, Limits::DEFAULT, "AC1032");
+        assert_eq!(handle(&short).unwrap_err(), bad);
+        for kept in ["", "AC1032"] {
+            let mut request = self::request(ENCODE, Limits::DEFAULT, "AC1032");
+            push_str(&mut request, kept);
+            request.extend(b"not a drawing");
+            let err = handle(&request).unwrap_err();
+            assert_ne!(err, bad, "kept {kept:?}");
+        }
+    }
+
+    #[test]
+    fn serving_reports_a_decode_failure_as_a_reply() {
+        let mut request = self::request(DECODE, Limits::DEFAULT, "");
+        request.extend(b"AC1032 not really a drawing");
+        let mut out = Vec::new();
+        assert_eq!(serve(&request[..], &mut out), 0);
+        assert!(matches!(parse_reply(out.clone()), Some(Err(_))), "{out:?}");
+    }
+}
diff --git a/crates/dxf/Cargo.toml b/crates/dxf/Cargo.toml
index 70c4f1234..11de1c377 100644
--- a/crates/dxf/Cargo.toml
+++ b/crates/dxf/Cargo.toml
@@ -15,3 +15,4 @@ craft-codepage = { workspace = true }
 thiserror = { workspace = true }
 log = "0.4"
 encoding_rs = "0.8.35"
+kurbo = { workspace = true }
diff --git a/crates/dxf/src/lib.rs b/crates/dxf/src/lib.rs
index 0109e9040..4cf3e46e9 100644
--- a/crates/dxf/src/lib.rs
+++ b/crates/dxf/src/lib.rs
@@ -11,6 +11,7 @@
 use std::io::Write as _;
 
 pub mod model;
+pub mod paths;
 mod version;
 pub use version::Version;
 
diff --git a/crates/dxf/src/model/write.rs b/crates/dxf/src/model/write.rs
index 3ee234153..6d2879cd9 100644
--- a/crates/dxf/src/model/write.rs
+++ b/crates/dxf/src/model/write.rs
@@ -1478,6 +1478,13 @@ const MODEL: &str = "*Model_Space";
 const PAPER: &str = "*Paper_Space";
 
 impl Drawing<'_> {
+    /// Set `$LUNITS` without making callers construct low-level group tags.
+    pub fn with_linear_units(mut self, units: i64) -> Self {
+        self.header.retain(|(name, _)| !name.eq_ignore_ascii_case("$LUNITS"));
+        self.header.push(("$LUNITS".into(), vec![Tag::i(70, units)]));
+        self
+    }
+
     /// The whole file as tags, ending with `0 EOF`, and how many entities were left out
     /// ([`EntityKind::Other`], and a MULTILEADER before 2007 or an ACAD_TABLE before 2004, which it has no groups for: pass
     /// those in `raw_entities`).
diff --git a/crates/dxf/src/paths.rs b/crates/dxf/src/paths.rs
new file mode 100644
index 000000000..7e4f18f0f
--- /dev/null
+++ b/crates/dxf/src/paths.rs
@@ -0,0 +1,859 @@
+//! Bounded conversion of common planar DXF entities into neutral Bézier paths.
+//!
+//! This is geometry extraction, not a full CAD scene renderer: unsupported entities such as
+//! text, dimensions, meshes, and block inserts are reported as warnings and omitted.
+
+use kurbo::{BezPath, Point, Rect, Shape as _};
+
+/// Limits on the number of paths returned by [`import`]. Parsing also uses the crate's tag cap.
+pub const MAX_PATHS: usize = 200_000;
+/// Aggregate number of Bézier elements a drawing may generate during conversion.
+pub const MAX_PATH_ELEMENTS: usize = 2_000_000;
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error("DXF parse failed: {0}")]
+    Parse(#[from] crate::DxfError),
+    #[error("DXF contains more than {MAX_PATHS} paths")]
+    TooManyPaths,
+    #[error("DXF curve exceeds the subdivision limit")]
+    TooManySegments,
+    #[error("DXF contains a non-finite path coordinate")]
+    NonFinite,
+}
+
+/// Geometry in source DXF coordinates. `unit_to_mm` maps a source coordinate to millimetres;
+/// unitless drawings use `1.0`, as the coordinates are then interpreted as millimetres.
+#[derive(Debug, Clone)]
+pub struct Imported {
+    pub paths: Vec<BezPath>,
+    pub bounds: Option<Rect>,
+    pub unit_to_mm: f64,
+    pub warnings: Vec<String>,
+}
+
+/// Parse bounded DXF input and extract visible planar linework.
+pub fn import(bytes: &[u8]) -> Result<Imported, Error> {
+    let tags = crate::parse_with_limit(bytes, crate::max_tags())?;
+    let drawing = crate::model::Document::read(&tags);
+    let unit_to_mm = units_to_mm(drawing.header.insunits(), drawing.header.measurement());
+    let layer_visibility: std::collections::HashMap<_, _> =
+        drawing.layers().into_iter().map(|layer| (layer.name, layer.on && !layer.frozen)).collect();
+    let mut paths = Vec::new();
+    let mut warnings = Vec::new();
+    let mut unsupported = 0usize;
+    let mut elements = 0usize;
+    for record in &drawing.entities {
+        let entity = crate::model::Entity::read(record);
+        if !entity.common.visible || record.paper_space() || layer_visibility.get(&entity.common.layer) == Some(&false) {
+            continue;
+        }
+        if excessive_sweep(&entity.kind) {
+            return Err(Error::TooManySegments);
+        }
+        let remaining = MAX_PATH_ELEMENTS.saturating_sub(elements);
+        if estimated_elements(&entity.kind) > remaining {
+            return Err(Error::TooManySegments);
+        }
+        let converted = if let crate::model::EntityKind::Spline(spline) = &entity.kind {
+            spline_path(spline)?.into_iter().collect()
+        } else {
+            entity_paths(&entity.kind, entity.common.extrusion)
+        };
+        if converted.iter().flat_map(|path| path.elements()).any(|element| {
+            let finite = |p: Point| p.x.is_finite() && p.y.is_finite();
+            match *element {
+                kurbo::PathEl::MoveTo(p) | kurbo::PathEl::LineTo(p) => !finite(p),
+                kurbo::PathEl::QuadTo(a, b) => !finite(a) || !finite(b),
+                kurbo::PathEl::CurveTo(a, b, c) => !finite(a) || !finite(b) || !finite(c),
+                kurbo::PathEl::ClosePath => false,
+            }
+        }) {
+            return Err(Error::NonFinite);
+        }
+        if converted.is_empty() {
+            unsupported = unsupported.saturating_add(1);
+            continue;
+        }
+        elements = elements.saturating_add(converted.iter().map(|path| path.elements().len()).sum::<usize>());
+        if elements > MAX_PATH_ELEMENTS {
+            return Err(Error::TooManySegments);
+        }
+        if paths.len().saturating_add(converted.len()) > MAX_PATHS {
+            return Err(Error::TooManyPaths);
+        }
+        paths.extend(converted);
+    }
+    if unsupported > 0 {
+        warnings.push(format!("{unsupported} visible DXF entities are unsupported and were omitted"));
+    }
+    if drawing.skipped.iter().any(|(_, n)| *n > 0) {
+        warnings.push("some unsupported or stray DXF records were skipped".into());
+    }
+    let bounds = paths.iter().map(|path| path.bounding_box()).reduce(|a, b| a.union(b));
+    Ok(Imported { paths, bounds, unit_to_mm, warnings })
+}
+
+fn estimated_elements(kind: &crate::model::EntityKind) -> usize {
+    use crate::model::EntityKind as E;
+    let arc_count = |sweep: f64| (sweep.abs() / std::f64::consts::FRAC_PI_2).ceil().max(1.0) as usize;
+    let bulge_count = |bulge: f64| {
+        if bulge.is_finite() && bulge.abs() > 1e-12 { arc_count(4.0 * bulge.atan()) } else { 1 }
+    };
+    let polyline_count = |vertices: &[(Point, f64)], closed: bool| {
+        if vertices.is_empty() {
+            return 0;
+        }
+        let mut count = 1usize;
+        for pair in vertices.windows(2) {
+            count = count.saturating_add(bulge_count(pair[0].1));
+        }
+        if closed && vertices.len() > 1 {
+            count = count.saturating_add(bulge_count(vertices.last().map_or(0.0, |vertex| vertex.1)));
+            count = count.saturating_add(1);
+        }
+        count
+    };
+    match kind {
+        E::Line { .. } => 2,
+        E::Circle { .. } => 6,
+        E::Arc { start_angle, end_angle, .. } => 1usize.saturating_add(arc_count((end_angle - start_angle).to_radians())),
+        E::LwPolyline(poly) => {
+            let vertices: Vec<_> = poly.vertices.iter().map(|v| (Point::new(v.x, v.y), v.bulge)).collect();
+            polyline_count(&vertices, poly.closed)
+        }
+        E::Polyline(poly) if !poly.is_mesh() && !poly.is_polyface() => {
+            let vertices: Vec<_> = poly
+                .vertices
+                .iter()
+                .filter(|vertex| !vertex.is_face())
+                .map(|vertex| (Point::new(vertex.location[0], vertex.location[1]), vertex.bulge))
+                .collect();
+            polyline_count(&vertices, poly.closed())
+        }
+        E::Ellipse { start, end, .. } => 1usize.saturating_add(arc_count(end - start)),
+        // `spline_path` already caps subdivision at MAX_SPLINE_ELEMENTS. Its actual output is
+        // checked against the drawing-wide budget after conversion.
+        E::Spline(_) => 0,
+        _ => 0,
+    }
+}
+
+fn units_to_mm(code: i64, _measurement: Option<i64>) -> f64 {
+    match code {
+        0 => 1.0,
+        1 => 25.4,
+        2 => 304.8,
+        3 => 1_609_344.0,
+        5 => 10.0,
+        6 => 1_000.0,
+        7 => 1_000_000.0,
+        8 => 0.000_025_4,
+        9 => 0.0254,
+        10 => 914.4,
+        11 => 1e-7,
+        12 => 1e-6,
+        13 => 0.001,
+        14 => 100.0,
+        15 => 10_000.0,
+        16 => 100_000.0,
+        17 => 1e12,
+        18 => 149_597_870_700_000.0,
+        19 => 9.460_730_472_580_8e18,
+        20 => 3.085_677_581_491_367e19,
+        21 => 1200.0 / 3937.0 * 1000.0,
+        22 => 1200.0 / 3937.0 * 1000.0 / 12.0,
+        23 => 1200.0 / 3937.0 * 1000.0 * 3.0,
+        24 => 1200.0 / 3937.0 * 1000.0 * 5280.0,
+        _ => 1.0,
+    }
+}
+
+fn entity_paths(kind: &crate::model::EntityKind, normal: crate::model::Point) -> Vec<BezPath> {
+    use crate::model::EntityKind as E;
+    match kind {
+        E::Line { start, end } => vec![line(*start, *end)],
+        E::Circle { center, radius } if radius.is_finite() && *radius > 0.0 => {
+            vec![map_ocs_path(circle(Point::new(center[0], center[1]), *radius), normal, center[2])]
+        }
+        E::Arc { center, radius, start_angle, end_angle }
+            if radius.is_finite() && *radius > 0.0 && start_angle.is_finite() && end_angle.is_finite() =>
+        {
+            vec![map_ocs_path(arc(Point::new(center[0], center[1]), *radius, start_angle.to_radians(), end_angle.to_radians()), normal, center[2])]
+        }
+        E::LwPolyline(poly) => {
+            vec![map_ocs_path(polyline(poly.vertices.iter().map(|v| (Point::new(v.x, v.y), v.bulge)), poly.closed), normal, poly.elevation)]
+        }
+        E::Polyline(poly) if !poly.is_mesh() && !poly.is_polyface() => {
+            let is_3d = poly.flags & 8 != 0;
+            let z = if is_3d { 0.0 } else { poly.elevation };
+            let path =
+                polyline(poly.vertices.iter().filter(|v| !v.is_face()).map(|v| (Point::new(v.location[0], v.location[1]), v.bulge)), poly.closed());
+            vec![if is_3d { path } else { map_ocs_path(path, normal, z) }]
+        }
+        E::Ellipse { center, major, ratio, start, end } if ratio.is_finite() && *ratio > 0.0 => {
+            vec![ellipse(*center, *major, normal, *ratio, *start, *end)]
+        }
+        _ => Vec::new(),
+    }
+}
+
+const MAX_SPLINE_ELEMENTS: usize = 200_000;
+const SPLINE_TOLERANCE: f64 = 1e-6;
+const MAX_SPLINE_DEPTH: u32 = 12;
+const MAX_SPLINE_DEGREE: usize = 11;
+const MIN_RELATIVE_WEIGHT: f64 = 1e-100;
+
+#[derive(Clone, Copy)]
+struct Homogeneous {
+    x: f64,
+    y: f64,
+    w: f64,
+}
+
+impl Homogeneous {
+    fn lerp(self, other: Self, t: f64) -> Self {
+        let s = 1.0 - t;
+        Self { x: self.x * s + other.x * t, y: self.y * s + other.y * t, w: self.w * s + other.w * t }
+    }
+    fn point(self) -> Option<Point> {
+        (self.w.abs() > 1e-300).then(|| Point::new(self.x / self.w, self.y / self.w)).filter(|point| point.x.is_finite() && point.y.is_finite())
+    }
+}
+
+// Keep the NURBS conversion semantics of the previous importer: exact polynomial Bezier
+// spans through cubic degree, tolerance-bounded rational/high-degree spans, invalid-weight
+// fallback, and fit-point fallback when control data is malformed.
+fn spline_path(spline: &crate::model::Spline) -> Result<Option<BezPath>, Error> {
+    let weights = (spline.flags & 4 != 0 && spline.weights.len() == spline.control.len()).then_some(spline.weights.as_slice());
+    let mut limit_hit = false;
+    let converted = usize::try_from(spline.degree).ok().and_then(|degree| nurbs(degree, &spline.knots, &spline.control, weights, &mut limit_hit));
+    let path = converted
+        .map(|mut path| {
+            if spline.flags & 1 != 0 {
+                path.close_path();
+            }
+            path
+        })
+        .or_else(|| {
+            let closed = spline.flags & 1 != 0;
+            // `through` emits one move, n-1 (open) or n (closed) cubics, and
+            // an additional close element for closed paths. Check before allocating
+            // its converted point vector.
+            let max_points = MAX_SPLINE_ELEMENTS.saturating_sub(if closed { 2 } else { 0 });
+            if spline.fit.len() > max_points {
+                limit_hit = true;
+                return None;
+            }
+            through(&spline.fit.iter().map(|p| Point::new(p[0], p[1])).collect::<Vec<_>>(), closed)
+        });
+    if limit_hit {
+        return Err(Error::TooManySegments);
+    }
+    Ok(path)
+}
+
+fn nurbs(degree: usize, knots: &[f64], control: &[[f64; 3]], weights: Option<&[f64]>, limit_hit: &mut bool) -> Option<BezPath> {
+    let n = control.len();
+    if !(1..=MAX_SPLINE_DEGREE).contains(&degree)
+        || n <= degree
+        || knots.len() != n + degree + 1
+        || knots.windows(2).any(|w| w[1] < w[0])
+        || control.iter().any(|p| !p[0].is_finite() || !p[1].is_finite())
+        || knots.iter().any(|k| !k.is_finite())
+    {
+        return None;
+    }
+    let raw = |i: usize| weights.and_then(|w| w.get(i)).copied().filter(|w| *w > 0.0 && w.is_finite()).unwrap_or(1.0);
+    let max_w = (0..n).map(raw).fold(0.0, f64::max);
+    if max_w == 0.0 {
+        return None;
+    }
+    let weight = |i: usize| (raw(i) / max_w).max(MIN_RELATIVE_WEIGHT);
+    let rational = (0..n).any(|i| (weight(i) - weight(0)).abs() > 1e-12);
+    let (lo, hi) = control.iter().fold((Point::new(f64::MAX, f64::MAX), Point::new(f64::MIN, f64::MIN)), |(lo, hi), p| {
+        (Point::new(lo.x.min(p[0]), lo.y.min(p[1])), Point::new(hi.x.max(p[0]), hi.y.max(p[1])))
+    });
+    let tolerance = ((hi - lo).hypot() * SPLINE_TOLERANCE).max(1e-12);
+    let mut path = BezPath::new();
+    for span in degree..n {
+        let (Some(&t0), Some(&t1)) = (knots.get(span), knots.get(span + 1)) else { continue };
+        if t1 <= t0 {
+            continue;
+        }
+        let bezier: Vec<Homogeneous> = (0..=degree)
+            .map(|j| {
+                let args: Vec<_> = (0..degree).map(|k| if k < degree - j { t0 } else { t1 }).collect();
+                blossom(degree, knots, control, span, &args, &weight)
+            })
+            .collect::<Option<_>>()?;
+        let start = bezier.first()?.point()?;
+        let needs_new_subpath = path_endpoint(&path).is_none_or(|end| end.distance(start) > 1e-12 * (1.0 + start.to_vec2().hypot()));
+        if needs_new_subpath {
+            path.move_to(start);
+        }
+        // A rational degree-one span changes its parameterization with its weights, but its locus
+        // is still the straight segment between its endpoints. Preserve that exact geometry.
+        let polynomial: Option<Vec<Point>> = if rational && degree > 1 { None } else { bezier.iter().map(|p| p.point()).collect() };
+        match polynomial.as_deref() {
+            Some([_, p]) => path.line_to(*p),
+            Some([_, q, p]) => path.quad_to(*q, *p),
+            Some([_, a, b, p]) => path.curve_to(*a, *b, *p),
+            _ => fit_spline(&mut path, &bezier, tolerance, 0, limit_hit)?,
+        }
+        if path.elements().len() > MAX_SPLINE_ELEMENTS {
+            *limit_hit = true;
+            return None;
+        }
+    }
+    (path.elements().len() > 1).then_some(path)
+}
+
+fn path_endpoint(path: &BezPath) -> Option<Point> {
+    match path.elements().last()? {
+        kurbo::PathEl::MoveTo(p) | kurbo::PathEl::LineTo(p) => Some(*p),
+        kurbo::PathEl::QuadTo(_, p) => Some(*p),
+        kurbo::PathEl::CurveTo(_, _, p) => Some(*p),
+        kurbo::PathEl::ClosePath => None,
+    }
+}
+
+fn blossom(degree: usize, knots: &[f64], control: &[[f64; 3]], span: usize, args: &[f64], weight: &impl Fn(usize) -> f64) -> Option<Homogeneous> {
+    // Only the active degree+1 control points are needed for one span. Convert this small window
+    // here instead of making a second vector proportional to an untrusted entity's full controls.
+    let first = span.checked_sub(degree)?;
+    let mut points: Vec<_> = control
+        .get(first..=span)?
+        .iter()
+        .enumerate()
+        .map(|(offset, p)| {
+            let w = weight(first + offset);
+            Homogeneous { x: p[0] * w, y: p[1] * w, w }
+        })
+        .collect();
+    for r in 1..=degree {
+        let u = *args.get(r - 1)?;
+        for j in (r..=degree).rev() {
+            let i = span - degree + j;
+            let (a, b) = (*knots.get(i)?, *knots.get(i + degree + 1 - r)?);
+            let alpha = if b - a > 1e-300 { (u - a) / (b - a) } else { 0.0 };
+            let previous = *points.get(j - 1)?;
+            let current = points.get_mut(j)?;
+            *current = previous.lerp(*current, alpha);
+        }
+    }
+    points.get(degree).copied()
+}
+
+fn eval_spline_bezier(bezier: &[Homogeneous], t: f64) -> Option<(Point, kurbo::Vec2)> {
+    let mut points = bezier.to_vec();
+    let n = points.len().checked_sub(1)?;
+    for level in (1..=n).rev() {
+        if level == 1 {
+            let (a, b) = (*points.first()?, *points.get(1)?);
+            let p = a.lerp(b, t);
+            let point = p.point()?;
+            let k = n as f64;
+            let (dx, dy, dw) = (k * (b.x - a.x), k * (b.y - a.y), k * (b.w - a.w));
+            let w2 = p.w * p.w;
+            return Some((point, kurbo::Vec2::new((dx * p.w - p.x * dw) / w2, (dy * p.w - p.y * dw) / w2)));
+        }
+        for i in 0..level {
+            let next = *points.get(i + 1)?;
+            let current = points.get_mut(i)?;
+            *current = current.lerp(next, t);
+        }
+    }
+    Some((points.first()?.point()?, kurbo::Vec2::ZERO))
+}
+
+fn fit_spline(path: &mut BezPath, bezier: &[Homogeneous], tolerance: f64, depth: u32, limit_hit: &mut bool) -> Option<()> {
+    let (p0, d0) = eval_spline_bezier(bezier, 0.0)?;
+    let (p3, d3) = eval_spline_bezier(bezier, 1.0)?;
+    let (c1, c2) = (p0 + d0 / 3.0, p3 - d3 / 3.0);
+    if ![c1, c2].iter().all(|p| p.x.is_finite() && p.y.is_finite()) {
+        path.line_to(p3);
+        return Some(());
+    }
+    let candidate = [p0, c1, c2, p3];
+    if cubic_error_bound(bezier, &candidate).is_some_and(|error| error <= tolerance) {
+        if path.elements().len() >= MAX_SPLINE_ELEMENTS {
+            *limit_hit = true;
+            return None;
+        }
+        path.curve_to(c1, c2, p3);
+        return Some(());
+    }
+    if depth >= MAX_SPLINE_DEPTH || path.elements().len() >= MAX_SPLINE_ELEMENTS {
+        *limit_hit = true;
+        return None;
+    }
+    let (left, right) = split_homogeneous_bezier(bezier)?;
+    fit_spline(path, &left, tolerance, depth + 1, limit_hit)?;
+    fit_spline(path, &right, tolerance, depth + 1, limit_hit)
+}
+
+fn split_homogeneous_bezier(bezier: &[Homogeneous]) -> Option<(Vec<Homogeneous>, Vec<Homogeneous>)> {
+    let count = bezier.len();
+    if count < 2 {
+        return None;
+    }
+    let mut row = bezier.to_vec();
+    let mut left = vec![*bezier.first()?; count];
+    let mut right = vec![*bezier.last()?; count];
+    left[0] = row[0];
+    right[count - 1] = row[count - 1];
+    for level in 1..count {
+        for index in 0..count - level {
+            row[index] = row[index].lerp(row[index + 1], 0.5);
+        }
+        left[level] = row[0];
+        right[count - 1 - level] = row[count - 1 - level];
+    }
+    Some((left, right))
+}
+
+// Bound the rational curve/cubic difference over the whole parameter interval. In Bernstein
+// form, X(t)-W(t)C(t) has degree p+3, so its norm is bounded by the largest coefficient norm;
+// W(t) is a convex combination of positive weights and is at least their minimum.
+fn cubic_error_bound(bezier: &[Homogeneous], cubic: &[Point; 4]) -> Option<f64> {
+    let degree = bezier.len().checked_sub(1)?;
+    let total = degree.checked_add(3)?;
+    let min_weight = bezier.iter().map(|point| point.w).fold(f64::INFINITY, f64::min);
+    if !(min_weight > 0.0 && min_weight.is_finite()) {
+        return None;
+    }
+    let mut max_error_numerator: f64 = 0.0;
+    for k in 0..=total {
+        let mut x = 0.0;
+        let mut y = 0.0;
+        for (i, point) in bezier.iter().enumerate() {
+            let Some(j) = k.checked_sub(i).filter(|j| *j < 4) else { continue };
+            let factor = binomial(degree, i) * binomial(3, j) / binomial(total, k);
+            x += (point.x - point.w * cubic[j].x) * factor;
+            y += (point.y - point.w * cubic[j].y) * factor;
+        }
+        max_error_numerator = max_error_numerator.max(x.hypot(y));
+    }
+    Some(max_error_numerator / min_weight)
+}
+
+fn binomial(n: usize, k: usize) -> f64 {
+    if k > n {
+        return 0.0;
+    }
+    let k = k.min(n - k);
+    (1..=k).fold(1.0, |value, i| value * (n + 1 - i) as f64 / i as f64)
+}
+
+fn through(points: &[Point], closed: bool) -> Option<BezPath> {
+    let n = points.len();
+    let first = *points.first()?;
+    if n < 2 {
+        return None;
+    }
+    let at = |i: isize| {
+        let len = n as isize;
+        let j = if closed { i.rem_euclid(len) } else { i.clamp(0, len - 1) };
+        points.get(j as usize).copied().unwrap_or(first)
+    };
+    let mut path = BezPath::new();
+    path.move_to(first);
+    let segments = if closed { n } else { n - 1 };
+    for i in 0..segments as isize {
+        let (p0, p1, p2, p3) = (at(i - 1), at(i), at(i + 1), at(i + 2));
+        path.curve_to(p1 + (p2 - p0) / 6.0, p2 - (p3 - p1) / 6.0, p2);
+    }
+    if closed {
+        path.close_path();
+    }
+    Some(path)
+}
+
+fn map_ocs_path(path: BezPath, normal: crate::model::Point, z: f64) -> BezPath {
+    let [x, y, n] = crate::model::ocs_axes(normal);
+    let transform = kurbo::Affine::new([x[0], x[1], y[0], y[1], n[0] * z, n[1] * z]);
+    transform * path
+}
+
+fn excessive_sweep(kind: &crate::model::EntityKind) -> bool {
+    let cap = 4096.0 * std::f64::consts::FRAC_PI_2;
+    let over = |sweep: f64| !sweep.is_finite() || sweep.abs() > cap;
+    match kind {
+        crate::model::EntityKind::Arc { start_angle, end_angle, .. } => over((end_angle - start_angle).to_radians()),
+        crate::model::EntityKind::Ellipse { start, end, .. } => over(end - start),
+        _ => false,
+    }
+}
+
+fn line(start: crate::model::Point, end: crate::model::Point) -> BezPath {
+    let mut path = BezPath::new();
+    path.move_to((start[0], start[1]));
+    path.line_to((end[0], end[1]));
+    path
+}
+
+fn polyline(vertices: impl IntoIterator<Item = (Point, f64)>, closed: bool) -> BezPath {
+    let vertices = vertices.into_iter().collect::<Vec<_>>();
+    let mut path = BezPath::new();
+    let Some((first, _)) = vertices.first().copied() else { return path };
+    path.move_to(first);
+    for i in 1..vertices.len() {
+        let (a, bulge) = vertices[i - 1];
+        let (b, _) = vertices[i];
+        if bulge.is_finite() && bulge.abs() > 1e-12 {
+            append_bulge(&mut path, a, b, bulge);
+        } else {
+            path.line_to(b);
+        }
+    }
+    if closed && vertices.len() > 1 {
+        let (a, bulge) = *vertices.last().unwrap_or(&(first, 0.0));
+        if bulge.is_finite() && bulge.abs() > 1e-12 {
+            append_bulge(&mut path, a, first, bulge);
+        } else {
+            path.line_to(first);
+        }
+        path.close_path();
+    }
+    path
+}
+
+fn append_bulge(path: &mut BezPath, a: Point, b: Point, bulge: f64) {
+    let chord = b - a;
+    let length = chord.hypot();
+    if !(length.is_finite() && length > 0.0) {
+        path.line_to(b);
+        return;
+    }
+    let center = a + chord * 0.5 + kurbo::Vec2::new(-chord.y, chord.x) * ((1.0 - bulge * bulge) / (4.0 * bulge));
+    let start = (a.y - center.y).atan2(a.x - center.x);
+    let sweep = 4.0 * bulge.atan();
+    let radius = length * (1.0 + bulge * bulge) / (4.0 * bulge.abs());
+    arc_segments(path, center, start, sweep, radius);
+}
+
+fn circle(center: Point, radius: f64) -> BezPath {
+    let mut path = BezPath::new();
+    path.move_to((center.x + radius, center.y));
+    arc_segments(&mut path, center, 0.0, std::f64::consts::TAU, radius);
+    path.close_path();
+    path
+}
+
+fn arc(center: Point, radius: f64, start: f64, end: f64) -> BezPath {
+    let mut path = BezPath::new();
+    path.move_to((center.x + radius * start.cos(), center.y + radius * start.sin()));
+    let sweep = if end >= start { end - start } else { end - start + std::f64::consts::TAU };
+    arc_segments(&mut path, center, start, sweep, radius);
+    path
+}
+
+fn arc_segments(path: &mut BezPath, center: Point, start: f64, sweep: f64, radius: f64) {
+    let count = (sweep.abs() / (std::f64::consts::FRAC_PI_2)).ceil().max(1.0) as usize;
+    if count > 4096 {
+        return;
+    }
+    let step = sweep / count as f64;
+    for i in 0..count {
+        let a = start + step * i as f64;
+        let b = a + step;
+        let k = 4.0 / 3.0 * (step / 4.0).tan();
+        let p1 = Point::new(center.x + radius * (a.cos() - k * a.sin()), center.y + radius * (a.sin() + k * a.cos()));
+        let p2 = Point::new(center.x + radius * (b.cos() + k * b.sin()), center.y + radius * (b.sin() - k * b.cos()));
+        let p3 = Point::new(center.x + radius * b.cos(), center.y + radius * b.sin());
+        path.curve_to(p1, p2, p3);
+    }
+}
+
+fn ellipse(center: crate::model::Point, major: crate::model::Point, normal: crate::model::Point, ratio: f64, start: f64, end: f64) -> BezPath {
+    let minor = cross(normal, major);
+    let minor_len = minor.iter().map(|v| v * v).sum::<f64>().sqrt();
+    if !(minor_len.is_finite() && minor_len > 0.0) {
+        return BezPath::new();
+    }
+    let major_len = major.iter().map(|v| v * v).sum::<f64>().sqrt();
+    let bx = [minor[0] / minor_len * major_len * ratio, minor[1] / minor_len * major_len * ratio, minor[2] / minor_len * major_len * ratio];
+    let point = |t: f64| Point::new(center[0] + major[0] * t.cos() + bx[0] * t.sin(), center[1] + major[1] * t.cos() + bx[1] * t.sin());
+    let mut path = BezPath::new();
+    path.move_to(point(start));
+    let sweep = if end >= start { end - start } else { end - start + std::f64::consts::TAU };
+    let count = (sweep.abs() / std::f64::consts::FRAC_PI_2).ceil().max(1.0) as usize;
+    if count > 4096 {
+        return path;
+    }
+    let step = sweep / count as f64;
+    for i in 0..count {
+        let a = start + step * i as f64;
+        let b = a + step;
+        let k = 4.0 / 3.0 * (step / 4.0).tan();
+        let derivative = |t: f64| Point::new(-major[0] * t.sin() + bx[0] * t.cos(), -major[1] * t.sin() + bx[1] * t.cos());
+        let p1 = point(a) + derivative(a).to_vec2() * k;
+        let p2 = point(b) - derivative(b).to_vec2() * k;
+        path.curve_to(p1, p2, point(b));
+    }
+    path
+}
+
+fn cross(a: crate::model::Point, b: crate::model::Point) -> crate::model::Point {
+    [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]]
+}
+
+#[cfg(test)]
+mod spline_tests {
+    use super::*;
+    use crate::model::Spline;
+    use kurbo::ParamCurveNearest;
+
+    // The previous importer accepted cubic fits based on seven fixed probes, then bisected the
+    // parameter interval. Keep this test-only reference to compare real legacy output with the
+    // conservative fit used by craft-dxf.
+    fn prior_fit(path: &mut BezPath, bezier: &[Homogeneous], t0: f64, t1: f64, tolerance: f64, depth: u32) -> Option<()> {
+        let (p0, d0) = eval_spline_bezier(bezier, t0)?;
+        let (p3, d3) = eval_spline_bezier(bezier, t1)?;
+        let h = (t1 - t0) / 3.0;
+        let (c1, c2) = (p0 + d0 * h, p3 - d3 * h);
+        if ![c1, c2].iter().all(|point| point.x.is_finite() && point.y.is_finite()) {
+            path.line_to(p3);
+            return Some(());
+        }
+        let cubic = kurbo::CubicBez::new(p0, c1, c2, p3);
+        let close = (1..8).all(|i| {
+            let t = f64::from(i) / 8.0;
+            eval_spline_bezier(bezier, t0 + (t1 - t0) * t).is_some_and(|(point, _)| kurbo::ParamCurve::eval(&cubic, t).distance(point) <= tolerance)
+        });
+        if close || depth >= MAX_SPLINE_DEPTH || path.elements().len() >= MAX_SPLINE_ELEMENTS {
+            path.curve_to(c1, c2, p3);
+            return Some(());
+        }
+        let midpoint = (t0 + t1) / 2.0;
+        prior_fit(path, bezier, t0, midpoint, tolerance, depth + 1)?;
+        prior_fit(path, bezier, midpoint, t1, tolerance, depth + 1)
+    }
+
+    fn legacy_path(bezier: &[Homogeneous], tolerance: f64) -> BezPath {
+        let mut path = BezPath::new();
+        let start = eval_spline_bezier(bezier, 0.0).expect("legacy start point").0;
+        path.move_to(start);
+        prior_fit(&mut path, bezier, 0.0, 1.0, tolerance, 0).expect("legacy fit succeeds");
+        path
+    }
+
+    fn sampled_path_distance(from: &BezPath, to: &BezPath, tolerance: f64) -> f64 {
+        let target: Vec<_> = to.segments().collect();
+        from.segments()
+            .flat_map(|segment| (0..=32).map(move |i| kurbo::ParamCurve::eval(&segment, f64::from(i) / 32.0)))
+            .map(|point| target.iter().map(|segment| segment.nearest(point, tolerance / 100.0).distance_sq.sqrt()).fold(f64::INFINITY, f64::min))
+            .fold(0.0_f64, f64::max)
+    }
+
+    fn cubic() -> Spline {
+        Spline {
+            degree: 3,
+            flags: 8,
+            knots: vec![0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0],
+            control: vec![[0.0, 0.0, 0.0], [1.0, 2.0, 0.0], [2.0, 2.0, 0.0], [3.0, 0.0, 0.0]],
+            weights: Vec::new(),
+            fit: Vec::new(),
+            start_tangent: None,
+            end_tangent: None,
+            fit_tolerance: 0.0,
+        }
+    }
+
+    fn xyz(points: &[Point]) -> Vec<[f64; 3]> {
+        points.iter().map(|point| [point.x, point.y, 0.0]).collect()
+    }
+
+    #[test]
+    fn spline_path_follows_clamped_control_curve_and_bounds_work() {
+        let path = spline_path(&cubic()).unwrap().expect("valid cubic spline");
+        assert_eq!(path.elements().len(), 2);
+        assert!(matches!(path.elements()[0], kurbo::PathEl::MoveTo(p) if p == Point::new(0.0, 0.0)));
+        assert!(matches!(path.elements()[1], kurbo::PathEl::CurveTo(a, b, p)
+            if a == Point::new(1.0, 2.0) && b == Point::new(2.0, 2.0) && p == Point::new(3.0, 0.0)));
+        assert_eq!(estimated_elements(&crate::model::EntityKind::Spline(cubic())), 0);
+    }
+
+    #[test]
+    fn rational_closed_periodic_and_fit_point_splines_keep_compatibility() {
+        let mut rational_line = Spline {
+            degree: 1,
+            flags: 4,
+            knots: vec![0.0, 0.0, 1.0, 1.0],
+            control: vec![[2.0, 3.0, 0.0], [5.0, 7.0, 0.0]],
+            weights: vec![1.0, 100.0],
+            fit: Vec::new(),
+            start_tangent: None,
+            end_tangent: None,
+            fit_tolerance: 0.0,
+        };
+        rational_line.flags |= 8;
+        let line = spline_path(&rational_line).unwrap().expect("rational degree-one spline");
+        assert!(matches!(line.elements(), [kurbo::PathEl::MoveTo(a), kurbo::PathEl::LineTo(b)]
+            if *a == Point::new(2.0, 3.0) && *b == Point::new(5.0, 7.0)));
+
+        let mut rational = cubic();
+        rational.flags |= 4;
+        rational.weights = vec![1.0, 0.5, 0.5, 1.0];
+        let rational_path = spline_path(&rational).unwrap().expect("rational spline");
+        assert!(rational_path.elements().iter().any(|el| matches!(el, kurbo::PathEl::CurveTo(..))));
+
+        let mut closed = cubic();
+        closed.flags |= 1;
+        assert!(matches!(spline_path(&closed).unwrap().unwrap().elements().last(), Some(kurbo::PathEl::ClosePath)));
+        let mut periodic = cubic();
+        periodic.flags |= 2;
+        assert!(!matches!(spline_path(&periodic).unwrap().unwrap().elements().last(), Some(kurbo::PathEl::ClosePath)));
+
+        let mut fit = cubic();
+        fit.knots.clear();
+        fit.fit = vec![[0.0, 0.0, 0.0], [1.0, 2.0, 0.0], [3.0, 0.0, 0.0]];
+        let path = spline_path(&fit).unwrap().expect("fit-point fallback");
+        assert!(matches!(path.elements()[0], kurbo::PathEl::MoveTo(p) if p == Point::new(0.0,0.0)));
+        assert!(matches!(path.elements().last(), Some(kurbo::PathEl::CurveTo(_, _, p)) if *p == Point::new(3.0,0.0)));
+
+        let mut negative = cubic();
+        negative.degree = -1;
+        negative.fit = fit.fit;
+        assert!(spline_path(&negative).unwrap().is_some(), "invalid degree reaches the prior fit-point fallback");
+    }
+
+    #[test]
+    fn spline_path_rejects_malformed_knots_and_defaults_invalid_weights() {
+        let mut spline = cubic();
+        spline.knots[4] = f64::NAN;
+        assert!(spline_path(&spline).unwrap().is_none());
+        let mut spline = cubic();
+        spline.flags |= 4;
+        spline.weights = vec![1.0, 0.0, 1.0, 1.0];
+        assert!(spline_path(&spline).unwrap().is_some(), "invalid weights historically fall back to unit weights");
+    }
+
+    #[test]
+    fn ascii_document_import_keeps_spline_as_supported_geometry() {
+        let bytes = b"0\nSECTION\n2\nENTITIES\n0\nSPLINE\n8\n0\n70\n8\n71\n3\n72\n8\n73\n4\n40\n0\n40\n0\n40\n0\n40\n0\n40\n1\n40\n1\n40\n1\n40\n1\n10\n0\n20\n0\n10\n1\n20\n2\n10\n2\n20\n2\n10\n3\n20\n0\n0\nENDSEC\n0\nEOF\n";
+        let imported = import(bytes).expect("valid spline drawing");
+        assert_eq!(imported.paths.len(), 1);
+        assert!(imported.warnings.is_empty());
+        let bounds = imported.bounds.expect("spline bounds");
+        assert!((bounds.x0 - 0.0).abs() < 1e-12 && (bounds.x1 - 3.0).abs() < 1e-12);
+        assert!((bounds.y0 - 0.0).abs() < 1e-12 && (bounds.y1 - 1.5).abs() < 1e-12);
+    }
+
+    #[test]
+    fn discontinuous_nurbs_spans_remain_separate_subpaths() {
+        let mut limit_hit = false;
+        let path = nurbs(
+            1,
+            &[0.0, 0.0, 0.5, 0.5, 1.0, 1.0],
+            &xyz(&[Point::new(0.0, 0.0), Point::new(1.0, 0.0), Point::new(5.0, 5.0), Point::new(6.0, 5.0)]),
+            None,
+            &mut limit_hit,
+        )
+        .expect("piecewise linear spline");
+        assert!(!limit_hit);
+        assert!(matches!(path.elements(), [kurbo::PathEl::MoveTo(a), kurbo::PathEl::LineTo(b), kurbo::PathEl::MoveTo(c), kurbo::PathEl::LineTo(d)]
+            if *a == Point::new(0.0,0.0) && *b == Point::new(1.0,0.0) && *c == Point::new(5.0,5.0) && *d == Point::new(6.0,5.0)));
+    }
+
+    #[test]
+    fn positive_knot_spans_at_large_offsets_are_kept() {
+        let start = 1.0e12;
+        let delta = 1.0e-3;
+        let mut limit_hit = false;
+        let path = nurbs(1, &[start, start, start + delta, start + delta], &xyz(&[Point::new(2.0, 3.0), Point::new(5.0, 7.0)]), None, &mut limit_hit)
+            .expect("positive-width span");
+        assert!(!limit_hit);
+        assert!(matches!(path.elements(), [kurbo::PathEl::MoveTo(a), kurbo::PathEl::LineTo(b)]
+            if *a == Point::new(2.0, 3.0) && *b == Point::new(5.0, 7.0)));
+    }
+
+    #[test]
+    fn fit_point_fallback_checks_element_budget_before_collecting() {
+        let mut spline = cubic();
+        spline.degree = -1;
+        spline.fit = vec![[0.0, 0.0, 0.0]; MAX_SPLINE_ELEMENTS + 1];
+        assert!(matches!(spline_path(&spline), Err(Error::TooManySegments)));
+    }
+
+    #[test]
+    fn bernstein_error_bound_covers_rational_and_high_degree_deviations() {
+        for control in [
+            vec![Homogeneous { x: 0.0, y: 0.0, w: 1.0 }, Homogeneous { x: 0.2, y: 2.0, w: 0.5 }, Homogeneous { x: 1.0, y: 0.0, w: 1.0 }],
+            vec![
+                Homogeneous { x: 0.0, y: 0.0, w: 1.0 },
+                Homogeneous { x: 0.2, y: 2.0, w: 0.7 },
+                Homogeneous { x: 0.5, y: -2.0, w: 0.9 },
+                Homogeneous { x: 0.8, y: 2.0, w: 1.2 },
+                Homogeneous { x: 1.0, y: 0.0, w: 1.0 },
+            ],
+        ] {
+            let degree = control.len() - 1;
+            let bezier = [Point::new(0.0, 0.0), Point::new(0.25, 1.0), Point::new(0.75, 1.0), Point::new(1.0, 0.0)];
+            let bound = cubic_error_bound(&control, &bezier).unwrap();
+            let cubic = kurbo::CubicBez::new(bezier[0], bezier[1], bezier[2], bezier[3]);
+            for sample in 0..=1024 {
+                let t = sample as f64 / 1024.0;
+                let mut points = control.clone();
+                for level in (1..=degree).rev() {
+                    for i in 0..level {
+                        points[i] = points[i].lerp(points[i + 1], t);
+                    }
+                }
+                let source = points[0].point().unwrap();
+                let approximation = kurbo::ParamCurve::eval(&cubic, t);
+                assert!(source.distance(approximation) <= bound * (1.0 + 1e-12), "sample {t}: bound {bound}");
+            }
+        }
+    }
+
+    #[test]
+    fn rational_quadratic_circle_matches_the_prior_importer_tolerance() {
+        let weight = std::f64::consts::FRAC_1_SQRT_2;
+        let control = xyz(&[(1.0, 0.0), (1.0, 1.0), (0.0, 1.0), (-1.0, 1.0), (-1.0, 0.0), (-1.0, -1.0), (0.0, -1.0), (1.0, -1.0), (1.0, 0.0)]
+            .map(|(x, y)| Point::new(200.0 + x * 100.0, 200.0 + y * 100.0)));
+        let knots = [0.0, 0.0, 0.0, 1.0, 1.0, 2.0, 2.0, 3.0, 3.0, 4.0, 4.0, 4.0];
+        let weights = [1.0, weight, 1.0, weight, 1.0, weight, 1.0, weight, 1.0];
+        let mut limit_hit = false;
+        let path = nurbs(2, &knots, &control, Some(&weights), &mut limit_hit).expect("circle NURBS");
+        assert!(!limit_hit);
+        let center = Point::new(200.0, 200.0);
+        let max_radial_error = path
+            .segments()
+            .flat_map(|segment| (0..=32).map(move |i| kurbo::ParamCurve::eval(&segment, i as f64 / 32.0)))
+            .map(|point| (point.distance(center) - 100.0).abs())
+            .fold(0.0_f64, f64::max);
+        assert!(max_radial_error < 0.01, "prior importer tolerance was 0.01; got {max_radial_error}");
+    }
+
+    #[test]
+    fn bounded_spline_fit_matches_prior_rational_and_high_degree_geometry() {
+        let weight = std::f64::consts::FRAC_1_SQRT_2;
+        let curves = [
+            vec![Homogeneous { x: 1.0, y: 0.0, w: 1.0 }, Homogeneous { x: weight, y: weight, w: weight }, Homogeneous { x: 0.0, y: 1.0, w: 1.0 }],
+            vec![
+                Homogeneous { x: 0.0, y: 0.0, w: 1.0 },
+                Homogeneous { x: 0.2, y: 2.0, w: 0.7 },
+                Homogeneous { x: 0.5, y: -2.0, w: 0.9 },
+                Homogeneous { x: 0.8, y: 2.0, w: 1.2 },
+                Homogeneous { x: 1.0, y: 0.0, w: 1.0 },
+            ],
+        ];
+        for bezier in curves {
+            let points: Vec<_> = bezier.iter().map(|point| point.point().expect("finite source point")).collect();
+            let (lo, hi) = points.iter().fold((points[0], points[0]), |(lo, hi), point| {
+                (Point::new(lo.x.min(point.x), lo.y.min(point.y)), Point::new(hi.x.max(point.x), hi.y.max(point.y)))
+            });
+            let tolerance = ((hi - lo).hypot() * SPLINE_TOLERANCE).max(1e-12);
+            let mut current = BezPath::new();
+            current.move_to(points[0]);
+            let mut limit_hit = false;
+            fit_spline(&mut current, &bezier, tolerance, 0, &mut limit_hit).expect("bounded fit succeeds");
+            assert!(!limit_hit);
+            let prior = legacy_path(&bezier, tolerance);
+            let difference = sampled_path_distance(&prior, &current, tolerance).max(sampled_path_distance(&current, &prior, tolerance));
+            assert!(difference <= 2.1 * tolerance, "legacy/new Hausdorff sample distance {difference} exceeds 2.1 × tolerance {tolerance}");
+        }
+    }
+}
diff --git a/crates/dxf/tests/model_write.rs b/crates/dxf/tests/model_write.rs
index 1f1df5fcb..8ece9c5bb 100644
--- a/crates/dxf/tests/model_write.rs
+++ b/crates/dxf/tests/model_write.rs
@@ -596,7 +596,8 @@ fn the_file_around_the_content() {
         raw_objects: vec![Tag::s(0, "DICTIONARY"), Tag::s(5, "901"), Tag::s(330, "A")],
         raw_classes: vec![Tag::s(0, "CLASS"), Tag::s(1, "IMAGEDEF")],
         ..Drawing::default()
-    };
+    }
+    .with_linear_units(2);
     let (tags, skipped) = drawing.tags();
     assert_eq!(skipped, 1, "the entity with no groups to write");
     assert_eq!(tags.last().map(|t| (t.code, t.str())), Some((0, "EOF".to_string())));
@@ -617,6 +618,7 @@ fn the_file_around_the_content() {
     assert_eq!((d.header.acadver().as_deref(), d.header.ltscale(), d.header.insunits()), (Some("AC1032"), 2.0, 6));
     assert_eq!(d.header.vars.iter().filter(|(n, _)| *n == "$INSUNITS" || *n == "$ACADVER" || *n == "$HANDSEED").count(), 3);
     assert_eq!(d.header.point("$EXTMAX"), Some([100.0, 50.0, 0.0]));
+    assert_eq!(d.header.vars.iter().find(|(name, _)| *name == "$LUNITS").map(|(_, tags)| tags[0].i64()), Some(2));
     // Blocks, their records and the layouts that name them.
     let names = d.block_names();
     let block = d.block("DOOR").expect("the block");
diff --git a/crates/eps/Cargo.toml b/crates/eps/Cargo.toml
index fbe69c26f..6984fb576 100644
--- a/crates/eps/Cargo.toml
+++ b/crates/eps/Cargo.toml
@@ -11,3 +11,11 @@ repository.workspace = true
 workspace = true
 
 [dependencies]
+kurbo = { workspace = true, optional = true }
+vectorcraft-doc = { workspace = true, optional = true }
+vectorcraft-eps = { workspace = true, optional = true }
+thiserror = { workspace = true, optional = true }
+
+[features]
+default = []
+paths = ["dep:kurbo", "dep:thiserror", "dep:vectorcraft-doc", "dep:vectorcraft-eps"]
diff --git a/crates/eps/src/embedded.rs b/crates/eps/src/embedded.rs
new file mode 100644
index 000000000..8e2225993
--- /dev/null
+++ b/crates/eps/src/embedded.rs
@@ -0,0 +1,269 @@
+//! Embedded Type 1 and CFF font programs in PostScript / EPS source.
+
+/// A font program embedded in the PostScript source of an EPS file.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EmbeddedFontProgram {
+    /// The PostScript `/FontName` when one is present in the source. CFF `StartData` blocks store
+    /// their name inside the CFF Name INDEX, which the font parser reads from `program`.
+    pub name: Option<String>,
+    /// The bytes of the Type 1 program or CFF font set.
+    pub program: Vec<u8>,
+    /// Whether `program` is a CFF font set rather than a Type 1 program.
+    pub cff: bool,
+}
+
+/// Embedded font programs in a PostScript section, in source order within each format.
+///
+/// Type 1 programs are recognized from their `eexec` and `cleartomark` delimiters and are named
+/// by `/FontName`. CFF `StartData` blocks are returned without a name because the name is inside
+/// the binary CFF data. Malformed or truncated blocks are skipped, as in the original EPS reader.
+pub fn embedded_font_programs(ps: &[u8]) -> Vec<EmbeddedFontProgram> {
+    let mut out = Vec::new();
+    let mut heads = positions(ps, b"%!PS-AdobeFont");
+    heads.extend(positions(ps, b"%!FontType1"));
+    heads.sort_unstable();
+    let names = positions(ps, b"/FontName");
+    let mut from = 0;
+    let mut used = 0;
+    while let Some(ee) = find_eexec(ps, from) {
+        from = ee + 5;
+        let last_before = |v: &[usize]| v[..v.partition_point(|&p| p < ee)].last().copied().filter(|&p| p >= used);
+        // The fallback look-back stops at the previous font's end, so it cannot pick up its header.
+        let start = last_before(&heads).or_else(|| last_before(&names).map(|p| p.saturating_sub(512).max(used)));
+        let Some(start) = start else { continue };
+        let end = find_from(ps, b"cleartomark", ee).map_or(ps.len(), |p| p + 11);
+        if let Some(name) = name_after(&ps[start..ee], b"/FontName") {
+            out.push(EmbeddedFontProgram { name: Some(name), program: ps[start..end].to_vec(), cff: false });
+        }
+        from = end;
+        used = end;
+    }
+
+    let mut from = 0;
+    while let Some(sd) = find_from(ps, b"StartData", from) {
+        from = sd + 9;
+        let head = String::from_utf8_lossy(&ps[sd.saturating_sub(64)..sd]).into_owned();
+        let Some(len) = head.split_whitespace().last().and_then(|t| t.parse::<usize>().ok()) else { continue };
+        let s = sd + 10;
+        let Some(data) = ps.get(s..s.saturating_add(len)) else { continue };
+        out.push(EmbeddedFontProgram { name: None, program: data.to_vec(), cff: true });
+        from = s + len;
+    }
+    out
+}
+
+fn find_from(hay: &[u8], needle: &[u8], from: usize) -> Option<usize> {
+    hay.get(from..)?.windows(needle.len()).position(|w| w == needle).map(|p| p + from)
+}
+
+/// Find an executable `eexec` operator, ignoring comments, literal strings and names.
+fn find_eexec(ps: &[u8], from: usize) -> Option<usize> {
+    let mut pos = from.min(ps.len());
+    while pos < ps.len() {
+        let c = ps[pos];
+        if is_white(c) {
+            pos += 1;
+            continue;
+        }
+        if c == b'%' {
+            let start = pos;
+            while pos < ps.len() && !matches!(ps[pos], b'\n' | b'\r') {
+                pos += 1;
+            }
+            let line = &ps[start..pos];
+            let marker: Option<&[u8]> = if line.starts_with(b"%%BeginData:") {
+                Some(b"%%EndData")
+            } else if line.starts_with(b"%%BeginBinary:") {
+                Some(b"%%EndBinary")
+            } else if line.starts_with(b"%%BeginPreview") {
+                Some(b"%%EndPreview")
+            } else {
+                None
+            };
+            if let Some(marker) = marker {
+                let rest = ps.get(pos..)?;
+                pos = rest.windows(marker.len()).position(|window| window == marker).map_or(ps.len(), |offset| pos + offset);
+            }
+            continue;
+        }
+        if c == b'(' {
+            pos += 1;
+            let mut depth = 1usize;
+            while pos < ps.len() && depth > 0 {
+                match ps[pos] {
+                    b'\\' => pos = pos.saturating_add(2).min(ps.len()),
+                    b'(' => {
+                        depth = depth.saturating_add(1);
+                        pos += 1;
+                    }
+                    b')' => {
+                        depth -= 1;
+                        pos += 1;
+                    }
+                    _ => pos += 1,
+                }
+            }
+            continue;
+        }
+        if c == b'<' {
+            match ps.get(pos + 1) {
+                Some(b'<') => pos += 2,
+                Some(b'~') => {
+                    pos += 2;
+                    pos = ps
+                        .get(pos..)
+                        .and_then(|rest| {
+                            rest.windows(2).position(|window| window == b"~>").map(|offset| pos.saturating_add(offset).saturating_add(2))
+                        })
+                        .unwrap_or(ps.len());
+                }
+                _ => {
+                    pos += 1;
+                    while pos < ps.len() && ps[pos] != b'>' {
+                        pos += 1;
+                    }
+                    pos = pos.saturating_add(1).min(ps.len());
+                }
+            }
+            continue;
+        }
+        if c == b'/' {
+            pos += 1;
+            if ps.get(pos) == Some(&b'/') {
+                pos += 1;
+            }
+            while pos < ps.len() && !is_white(ps[pos]) && !is_delimiter(ps[pos]) {
+                pos += 1;
+            }
+            continue;
+        }
+        if is_delimiter(c) {
+            pos += 1;
+            continue;
+        }
+        let start = pos;
+        while pos < ps.len() && !is_white(ps[pos]) && !is_delimiter(ps[pos]) {
+            pos += 1;
+        }
+        if &ps[start..pos] == b"eexec" {
+            return Some(start);
+        }
+    }
+    None
+}
+
+fn is_white(c: u8) -> bool {
+    matches!(c, 0 | 9 | 10 | 12 | 13 | 32)
+}
+
+fn is_delimiter(c: u8) -> bool {
+    matches!(c, b'(' | b')' | b'<' | b'>' | b'[' | b']' | b'{' | b'}' | b'/' | b'%')
+}
+
+fn positions(hay: &[u8], needle: &[u8]) -> Vec<usize> {
+    let mut out = vec![];
+    let mut from = 0;
+    while let Some(p) = find_from(hay, needle, from) {
+        out.push(p);
+        from = p + needle.len();
+    }
+    out
+}
+
+fn name_after(b: &[u8], key: &[u8]) -> Option<String> {
+    let p = find_from(b, key, 0)? + key.len();
+    let rest = &b[p..];
+    let s = rest.iter().position(|c| *c == b'/')? + 1;
+    let e = rest[s..].iter().position(|c| is_white(*c) || is_delimiter(*c)).map_or(rest.len(), |q| s + q);
+    (e > s).then(|| String::from_utf8_lossy(&rest[s..e]).into_owned())
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+    use super::embedded_font_programs;
+
+    #[test]
+    fn finds_type1_font_programs_by_name() {
+        let ps = b"%!PS-Adobe-3.0 EPSF-3.0\n%!PS-AdobeFont-1.0: Test\n/FontName /Test def\ncurrentfile eexec\n0000\ncleartomark\n";
+        let fonts = embedded_font_programs(ps);
+        assert_eq!(fonts.len(), 1);
+        assert_eq!(fonts[0].name.as_deref(), Some("Test"));
+        assert!(!fonts[0].cff);
+        assert!(String::from_utf8_lossy(&fonts[0].program).contains("cleartomark"));
+    }
+
+    #[test]
+    fn finds_cff_startdata_without_interpreting_its_name_index() {
+        let ps = b"%!PS-Adobe-3.0 EPSF-3.0\n10 StartData\n0123456789\n";
+        let fonts = embedded_font_programs(ps);
+        assert_eq!(fonts.len(), 1);
+        assert_eq!(fonts[0].name, None);
+        assert!(fonts[0].cff);
+        assert_eq!(fonts[0].program, b"0123456789");
+    }
+
+    #[test]
+    fn ignores_truncated_startdata() {
+        let fonts = embedded_font_programs(b"%!PS-Adobe-3.0 EPSF-3.0\n100 StartData\nshort");
+        assert!(fonts.is_empty());
+    }
+
+    #[test]
+    fn many_headerless_eexec_words_do_not_hide_later_font() {
+        let mut ps = b"%!PS-Adobe-3.0 EPSF-3.0\n".to_vec();
+        ps.extend_from_slice(b"eexec ".repeat(20_000).as_slice());
+        ps.extend_from_slice(b"\n%!PS-AdobeFont-1.0: Real\n/FontName /Real def\ncurrentfile eexec\n0000\ncleartomark\n");
+        let fonts = embedded_font_programs(&ps);
+        assert_eq!(fonts.len(), 1);
+        assert_eq!(fonts[0].name.as_deref(), Some("Real"));
+    }
+
+    #[test]
+    fn headerless_font_does_not_reuse_previous_font_header() {
+        let first = b"%!PS-AdobeFont-1.0: A\n/FontName /A def\ncurrentfile eexec\n0000\ncleartomark\n";
+        let second = b"/FontName /B def\ncurrentfile eexec\n0000\ncleartomark\n";
+        let mut ps = b"%!PS-Adobe-3.0 EPSF-3.0\n".to_vec();
+        ps.extend_from_slice(first);
+        ps.extend_from_slice(second);
+        let fonts = embedded_font_programs(&ps);
+        assert_eq!(fonts.len(), 2);
+        let b = fonts.iter().find(|font| font.name.as_deref() == Some("B")).unwrap();
+        assert!(!String::from_utf8_lossy(&b.program).contains("AdobeFont"));
+    }
+
+    #[test]
+    fn eexec_in_comments_strings_names_and_font_names_is_not_an_operator() {
+        let ps = b"%!PS-Adobe-3.0 EPSF-3.0\n%!PS-AdobeFont-1.0: Test\n%% eexec in a comment\n%%BeginBinary: 10\neexec junk\n%%EndBinary\n/FontName /eexecTest def\n(nested (ignored eexec)) pop\n<6565786563> pop\n<~eexec~> pop\n/eexec def\ncurrentfile eexec\n0000\ncleartomark\n";
+        let fonts = embedded_font_programs(ps);
+        assert_eq!(fonts.len(), 1);
+        assert_eq!(fonts[0].name.as_deref(), Some("eexecTest"));
+    }
+
+    #[test]
+    fn font_name_stops_at_postscript_delimiters_and_comments() {
+        let ps = b"%!PS-AdobeFont-1.0: Test\n/FontName /Test%comment\n def\ncurrentfile eexec\n0000\ncleartomark\n";
+        let fonts = embedded_font_programs(ps);
+        assert_eq!(fonts.len(), 1);
+        assert_eq!(fonts[0].name.as_deref(), Some("Test"));
+    }
+
+    #[test]
+    fn font_names_stop_at_every_postscript_delimiter() {
+        for delimiter in b"()<>[]{}/%" {
+            let mut source = b"/FontName /Test".to_vec();
+            source.push(*delimiter);
+            source.extend_from_slice(b"ignored");
+            assert_eq!(super::name_after(&source, b"/FontName").as_deref(), Some("Test"));
+        }
+    }
+
+    #[test]
+    fn literal_name_backslash_does_not_escape_a_comment_delimiter() {
+        let ps = b"%!PS-AdobeFont-1.0: Test\n/FontName /Test def\n/unused\\%(\npop\ncurrentfile eexec\n0000\ncleartomark\n";
+        let fonts = embedded_font_programs(ps);
+        assert_eq!(fonts.len(), 1);
+        assert_eq!(fonts[0].name.as_deref(), Some("Test"));
+    }
+}
diff --git a/crates/eps/src/lib.rs b/crates/eps/src/lib.rs
index e48532349..c3878830b 100644
--- a/crates/eps/src/lib.rs
+++ b/crates/eps/src/lib.rs
@@ -18,11 +18,16 @@
 pub mod ascii85;
 mod container;
 mod dsc;
+mod embedded;
+#[cfg(feature = "paths")]
+pub mod paths;
+pub mod postscript;
 mod preview;
 mod rectangles;
 
 pub use container::{DOS_HEADER, DOS_MAGIC, Sections, sections, wrap};
 pub use dsc::{Comments, MAX_HEADER, MAX_TRAILER};
+pub use embedded::{EmbeddedFontProgram, embedded_font_programs};
 pub use preview::{Bitmap, MAX_EPSI, epsi};
 pub use rectangles::{MAX_SIMPLE_RECTANGLE_SAVE_DEPTH, MAX_SIMPLE_RECTANGLE_TOKENS, MAX_SIMPLE_RECTANGLES, Rectangle, simple_rectangles};
 
diff --git a/crates/eps/src/paths.rs b/crates/eps/src/paths.rs
new file mode 100644
index 000000000..271f905bd
--- /dev/null
+++ b/crates/eps/src/paths.rs
@@ -0,0 +1,108 @@
+//! Neutral path extraction for EPS and PostScript files.
+//!
+//! This facade keeps the PostScript interpreter and its format decisions in shared dependencies;
+//! applications receive Bézier paths, page bounds and warnings for their own document adapters.
+
+use kurbo::{BezPath, Rect};
+
+/// Limits on the extracted geometry. The interpreter has its own execution and allocation caps.
+#[derive(Debug, Clone, Copy)]
+pub struct Limits {
+    pub max_input_bytes: usize,
+    pub max_paths: usize,
+    pub max_path_elements: usize,
+}
+
+impl Default for Limits {
+    fn default() -> Self {
+        Self { max_input_bytes: 64 * 1024 * 1024, max_paths: 200_000, max_path_elements: 2_000_000 }
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error("PostScript input exceeds {limit} bytes")]
+    InputLimit { limit: usize },
+    #[error("PostScript import failed: {0}")]
+    Parse(String),
+    #[error("PostScript path output exceeds configured limit")]
+    OutputLimit,
+}
+
+/// First-page path geometry normalized to the top-left origin in PostScript points, plus notes.
+#[derive(Debug, Clone)]
+pub struct Imported {
+    pub paths: Vec<BezPath>,
+    /// Origin-zero page bounds in PostScript points, using the same accepted DSC box as the
+    /// interpreter.
+    pub page_bounds: Rect,
+    pub warnings: Vec<String>,
+    pub preview_fallback: bool,
+}
+
+/// Interpret EPS/PostScript bytes and return their editable vector path geometry.
+pub fn import(bytes: &[u8], limits: Limits) -> Result<Imported, Error> {
+    if bytes.len() > limits.max_input_bytes {
+        return Err(Error::InputLimit { limit: limits.max_input_bytes });
+    }
+    let source = vectorcraft_eps::import(bytes).map_err(Error::Parse)?;
+    let page_bounds = vectorcraft_eps::page(bytes).map_err(Error::Parse)?;
+    // Illustrator's editable copy is expressed in its art-box document coordinates. The page
+    // reader, in contrast, returns a page at the origin. Normalize extracted paths to match it.
+    let origin = source.document.artboards.first().map(|board| board.rect.origin()).unwrap_or_default();
+    let to_page = kurbo::Affine::translate((-origin.x, -origin.y));
+    let mut paths = Vec::new();
+    let mut total_elements = 0usize;
+    let mut clipped = false;
+    let mut omitted = false;
+    for layer in &source.document.layers {
+        collect(layer, &mut paths, &mut total_elements, limits, to_page, &mut clipped, &mut omitted)?;
+    }
+    let mut warnings = source.warnings;
+    if clipped {
+        warnings.push("EPS clipping groups are returned as unclipped artwork".into());
+    }
+    if omitted {
+        warnings.push("visible EPS text or image content is not returned as paths".into());
+    }
+    Ok(Imported { paths, page_bounds, warnings, preview_fallback: source.preview })
+}
+
+fn collect(
+    node: &vectorcraft_doc::Node,
+    paths: &mut Vec<BezPath>,
+    elements: &mut usize,
+    limits: Limits,
+    to_page: kurbo::Affine,
+    clipped: &mut bool,
+    omitted: &mut bool,
+) -> Result<(), Error> {
+    if !node.visible {
+        return Ok(());
+    }
+    if let Some(data) = node.path_data() {
+        if matches!(node.kind, vectorcraft_doc::NodeKind::Path { clipping: true, .. }) {
+            return Ok(());
+        }
+        let path = data.to_bezpath();
+        if !path.elements().is_empty() {
+            *elements = elements.saturating_add(path.elements().len());
+            if paths.len() >= limits.max_paths || *elements > limits.max_path_elements {
+                return Err(Error::OutputLimit);
+            }
+            paths.push(to_page * path);
+        }
+    } else if let Some(children) = node.children() {
+        let is_clip = matches!(node.kind, vectorcraft_doc::NodeKind::Group { clip: true, .. } | vectorcraft_doc::NodeKind::Layer { clip: true, .. });
+        *clipped |= is_clip;
+        for (index, child) in children.iter().enumerate() {
+            if is_clip && index == 0 {
+                continue;
+            }
+            collect(child, paths, elements, limits, to_page, clipped, omitted)?;
+        }
+    } else {
+        *omitted = true;
+    }
+    Ok(())
+}
diff --git a/crates/eps/src/postscript.rs b/crates/eps/src/postscript.rs
new file mode 100644
index 000000000..92ed2c06d
--- /dev/null
+++ b/crates/eps/src/postscript.rs
@@ -0,0 +1,695 @@
+//! Shared PostScript format primitives for EPS programs.
+//!
+//! [`Scanner`] handles bounded lexical parsing. [`OperandStack`] and [`ExecutionBudget`] provide
+//! reusable language-level VM behavior while leaving values, dictionaries, graphics state,
+//! rendering, and font policy to the host interpreter.
+
+/// Maximum nesting depth for executable procedures in a source token.
+pub const MAX_PROCEDURE_DEPTH: usize = 100;
+
+/// Maximum number of operand values an interpreter should retain by default.
+pub const MAX_OPERAND_STACK: usize = 100_000;
+
+/// Maximum nested executable procedure calls supported by the bounded VM.
+pub const MAX_CALL_DEPTH: usize = 256;
+
+/// PostScript operand-stack operators whose semantics do not depend on the value model.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StackOperator {
+    Pop,
+    Exchange,
+    Duplicate,
+    CopyTop(usize),
+    Index(usize),
+    Roll { count: usize, shift: i64 },
+    Clear,
+    Count,
+}
+
+/// Result of applying an operand-stack operator.
+#[derive(Debug, PartialEq, Eq)]
+pub enum StackOutcome<T> {
+    None,
+    Popped(Option<T>),
+    Count(usize),
+    Copied(bool),
+}
+
+/// A bounded PostScript operand stack.
+///
+/// The stack is deliberately generic: an interpreter owns the concrete PostScript values and
+/// graphics state, while this module provides the shared language-level stack operators. A push
+/// past `limit` is ignored, matching the bounded EPS interpreter's defensive behavior.
+#[derive(Clone, Debug)]
+pub struct OperandStack<T> {
+    values: Vec<T>,
+    limit: usize,
+}
+
+impl<T: Clone> OperandStack<T> {
+    /// Create an empty stack with a maximum number of values.
+    pub fn new(limit: usize) -> Self {
+        Self { values: Vec::new(), limit }
+    }
+
+    /// Number of values currently on the stack.
+    pub fn len(&self) -> usize {
+        self.values.len()
+    }
+
+    /// Whether the stack is empty.
+    pub fn is_empty(&self) -> bool {
+        self.values.is_empty()
+    }
+
+    /// Borrow all stack values mutably from bottom to top.
+    pub fn values_mut(&mut self) -> &mut [T] {
+        &mut self.values
+    }
+
+    /// Remove and return the top value, if present.
+    pub fn pop(&mut self) -> Option<T> {
+        self.values.pop()
+    }
+
+    /// Remove every value.
+    pub fn clear(&mut self) {
+        self.values.clear();
+    }
+
+    /// Remove values at and above `at`, returning them in bottom-to-top order. An index beyond
+    /// the stack length removes nothing.
+    pub fn split_off(&mut self, at: usize) -> Vec<T> {
+        let at = at.min(self.values.len());
+        self.values.split_off(at)
+    }
+
+    /// Push a value if the configured limit allows it; report whether it was pushed.
+    pub fn push(&mut self, value: T) -> bool {
+        if self.values.len() >= self.limit {
+            return false;
+        }
+        self.values.push(value);
+        true
+    }
+
+    /// Pop a value, or return the caller's language-specific underflow value.
+    pub fn pop_or(&mut self, underflow: T) -> T {
+        self.values.pop().unwrap_or(underflow)
+    }
+
+    /// Borrow the top value.
+    pub fn top(&self) -> Option<&T> {
+        self.values.last()
+    }
+
+    /// PostScript `dup`: duplicate the top value if one exists.
+    pub fn duplicate(&mut self) {
+        if let Some(value) = self.values.last().cloned() {
+            let _ = self.push(value);
+        }
+    }
+
+    /// PostScript `dup` with a caller-supplied underflow value.
+    pub fn duplicate_or(&mut self, underflow: T) {
+        let value = self.values.last().cloned().unwrap_or(underflow);
+        let _ = self.push(value);
+    }
+
+    /// PostScript `exch`: exchange the top two values when both exist.
+    pub fn exchange(&mut self) {
+        let len = self.values.len();
+        if len >= 2 {
+            self.values.swap(len - 1, len - 2);
+        }
+    }
+
+    /// PostScript `exch` with caller-supplied underflow values. Both operands are popped and
+    /// restored even if either pop underflows, matching interpreters that use a null sentinel.
+    pub fn exchange_or(&mut self, underflow: T) {
+        let b = self.pop_or(underflow.clone());
+        let a = self.pop_or(underflow);
+        let _ = self.push(b);
+        let _ = self.push(a);
+    }
+
+    /// PostScript `index`: copy the value `depth` below the top onto the stack.
+    ///
+    /// Invalid or negative depths are left to the caller to validate; an out-of-range depth is a
+    /// no-op. This keeps the helper bounded even for hostile numeric operands.
+    pub fn index(&mut self, depth: usize) {
+        let len = self.values.len();
+        if depth < len && len < self.limit {
+            let value = self.values[len - depth - 1].clone();
+            self.values.push(value);
+        }
+    }
+
+    /// PostScript `index` with a caller-supplied underflow value, pushed even when `depth` is out
+    /// of range. The configured stack limit still applies.
+    pub fn index_or(&mut self, depth: usize, underflow: T) {
+        let len = self.values.len();
+        let value = if depth < len { self.values[len - depth - 1].clone() } else { underflow };
+        let _ = self.push(value);
+    }
+
+    /// PostScript `n j roll`: rotate the top `count` values by signed `shift` places.
+    ///
+    /// Positive shifts move values toward the top; negative shifts move them toward the bottom.
+    /// Counts larger than the stack and empty rolls are ignored.
+    pub fn roll(&mut self, count: usize, shift: i64) {
+        let len = self.values.len();
+        if count == 0 || count > len {
+            return;
+        }
+        let places = (i128::from(shift).rem_euclid(count as i128)) as usize;
+        self.values[len - count..].rotate_right(places);
+    }
+
+    /// PostScript `copy` for an integer operand: append a copy of the top `count` values if it
+    /// fits. Returns false when the range is invalid or the configured limit would be exceeded.
+    pub fn copy_top(&mut self, count: usize) -> bool {
+        let len = self.values.len();
+        if count > len || len.saturating_add(count) > self.limit {
+            return false;
+        }
+        let copied = self.values[len - count..].to_vec();
+        self.values.extend(copied);
+        true
+    }
+
+    /// Borrow all stack values from bottom to top.
+    pub fn values(&self) -> &[T] {
+        &self.values
+    }
+
+    /// Apply a PostScript operand-stack operator. `underflow` is the interpreter's fallback value
+    /// for `exch`, `dup`, and `index`; the stack's configured limit remains in force.
+    pub fn execute(&mut self, operator: StackOperator, underflow: T) -> StackOutcome<T> {
+        match operator {
+            StackOperator::Pop => StackOutcome::Popped(self.pop()),
+            StackOperator::Exchange => {
+                self.exchange_or(underflow);
+                StackOutcome::None
+            }
+            StackOperator::Duplicate => {
+                self.duplicate_or(underflow);
+                StackOutcome::None
+            }
+            StackOperator::CopyTop(count) => StackOutcome::Copied(self.copy_top(count)),
+            StackOperator::Index(depth) => {
+                self.index_or(depth, underflow);
+                StackOutcome::None
+            }
+            StackOperator::Roll { count, shift } => {
+                self.roll(count, shift);
+                StackOutcome::None
+            }
+            StackOperator::Clear => {
+                self.clear();
+                StackOutcome::None
+            }
+            StackOperator::Count => StackOutcome::Count(self.len()),
+        }
+    }
+}
+
+/// Bounded execution accounting shared by PostScript interpreters.
+///
+/// EPS programs can recurse or repeatedly execute procedures. A host can use this counter to
+/// stop work before it consumes unbounded CPU, independently of its operator and graphics policy.
+#[derive(Clone, Debug)]
+pub struct ExecutionBudget {
+    remaining: usize,
+    call_depth: usize,
+    max_call_depth: usize,
+}
+
+impl ExecutionBudget {
+    /// Create a budget with an operation allowance and maximum nested procedure calls.
+    pub fn new(operations: usize, max_call_depth: usize) -> Self {
+        Self { remaining: operations, call_depth: 0, max_call_depth }
+    }
+
+    /// Units of work still available.
+    pub fn remaining(&self) -> usize {
+        self.remaining
+    }
+
+    /// Current nested procedure depth.
+    pub fn call_depth(&self) -> usize {
+        self.call_depth
+    }
+
+    /// Charge work atomically. On failure the remaining budget stays unchanged.
+    pub fn spend(&mut self, units: usize) -> bool {
+        let Some(remaining) = self.remaining.checked_sub(units) else {
+            return false;
+        };
+        self.remaining = remaining;
+        true
+    }
+
+    /// Charge work that is accounted lazily: saturate at zero so the caller's next strict
+    /// [`Self::spend`] stops execution. This supports work whose current operator preserves the
+    /// app's historical behavior after exhausting its budget.
+    pub fn charge(&mut self, units: usize) {
+        self.remaining = self.remaining.saturating_sub(units);
+    }
+
+    /// Enter a procedure call if it remains within the configured depth.
+    pub fn enter_call(&mut self) -> bool {
+        if self.call_depth >= self.max_call_depth {
+            return false;
+        }
+        self.call_depth += 1;
+        true
+    }
+
+    /// Leave a procedure call. Extra leaves are ignored to keep cleanup paths safe.
+    pub fn leave_call(&mut self) {
+        self.call_depth = self.call_depth.saturating_sub(1);
+    }
+}
+
+/// A lexical PostScript value. Names are left unevaluated for the caller's interpreter.
+#[derive(Clone, Debug, PartialEq)]
+pub enum Token {
+    /// A number accepted by the PostScript source reader.
+    Number(f64),
+    /// An executable name, including immediately evaluated `//name`.
+    Name(String),
+    /// A literal name such as `/name`.
+    LiteralName(String),
+    /// A parenthesized or hexadecimal byte string.
+    String(Vec<u8>),
+    /// The encoded bytes between `<~` and `~>` (including delimiters), not decoded data.
+    Ascii85(Vec<u8>),
+    /// A procedure whose nested values have already been tokenized.
+    Procedure(Vec<Token>),
+    /// A closing brace not consumed as part of a procedure, or another malformed delimiter.
+    Null,
+}
+
+/// PostScript source bytes and the current byte offset.
+pub struct Scanner<'a> {
+    /// Source bytes. Public so an interpreter can implement `currentfile` operators.
+    pub data: &'a [u8],
+    /// Current byte offset in [`Scanner::data`].
+    pub pos: usize,
+}
+
+impl<'a> Scanner<'a> {
+    /// Start scanning at a byte offset, clamped to the source length.
+    pub fn new(data: &'a [u8], pos: usize) -> Self {
+        Self { data, pos: pos.min(data.len()) }
+    }
+
+    /// The next token; `{ … }` is returned as one procedure token.
+    pub fn token(&mut self) -> Option<Token> {
+        self.token_at_depth(0)
+    }
+
+    fn token_at_depth(&mut self, depth: usize) -> Option<Token> {
+        self.skip_ws();
+        let c = *self.data.get(self.pos)?;
+        Some(match c {
+            b'{' => {
+                self.pos += 1;
+                let mut body = Vec::new();
+                loop {
+                    self.skip_ws();
+                    match self.data.get(self.pos) {
+                        None => break,
+                        Some(b'}') => {
+                            self.pos += 1;
+                            break;
+                        }
+                        _ if depth >= MAX_PROCEDURE_DEPTH => break,
+                        _ => match self.token_at_depth(depth + 1) {
+                            Some(t) => body.push(t),
+                            None => break,
+                        },
+                    }
+                }
+                Token::Procedure(body)
+            }
+            b'}' => {
+                self.pos += 1;
+                Token::Null
+            }
+            b'/' => {
+                self.pos += 1;
+                let immediately_evaluated = self.data.get(self.pos) == Some(&b'/');
+                if immediately_evaluated {
+                    self.pos += 1;
+                }
+                let name = String::from_utf8_lossy(self.word()).into_owned();
+                if immediately_evaluated { Token::Name(name) } else { Token::LiteralName(name) }
+            }
+            b'(' => Token::String(self.parenthesized()),
+            b'<' if self.data.get(self.pos + 1) == Some(&b'<') => {
+                self.pos += 2;
+                Token::Name("<<".to_owned())
+            }
+            b'>' if self.data.get(self.pos + 1) == Some(&b'>') => {
+                self.pos += 2;
+                Token::Name(">>".to_owned())
+            }
+            b'<' if self.data.get(self.pos + 1) == Some(&b'~') => self.ascii85(),
+            b'<' => Token::String(self.hex_string()),
+            b'[' | b']' => {
+                self.pos += 1;
+                Token::Name(char::from(c).to_string())
+            }
+            b')' | b'>' => {
+                self.pos += 1;
+                Token::Null
+            }
+            _ => {
+                let word = self.word();
+                if word.is_empty() {
+                    self.pos += 1;
+                    return Some(Token::Null);
+                }
+                match parse_number(word) {
+                    Some(n) => Token::Number(n),
+                    None => {
+                        let name = String::from_utf8_lossy(word).into_owned();
+                        if let Some((radix, digits)) = name.split_once('#') {
+                            let radix = radix.parse::<u32>().ok().filter(|r| (2..=36).contains(r));
+                            if let Some(number) = radix.and_then(|r| i64::from_str_radix(digits, r).ok()) {
+                                return Some(Token::Number(number as f64));
+                            }
+                        }
+                        Token::Name(name)
+                    }
+                }
+            }
+        })
+    }
+
+    /// Step over inline image data that follows an `image` operator reading `currentfile`.
+    pub fn skip_image_data(&mut self) {
+        self.skip_ws();
+        let rest = self.data.get(self.pos..).unwrap_or_default();
+        if rest.starts_with(b"<~") || self.data.get(self.pos).is_some_and(|c| (b'!'..=b'u').contains(c) && !c.is_ascii_hexdigit()) {
+            self.pos = match rest.windows(2).position(|w| w == b"~>") {
+                Some(p) => self.pos.saturating_add(p).saturating_add(2).min(self.data.len()),
+                None => self.data.len(),
+            };
+            return;
+        }
+        while self.pos < self.data.len() && (self.data[self.pos].is_ascii_hexdigit() || is_white(self.data[self.pos])) {
+            self.pos += 1;
+        }
+        if self.data.get(self.pos) == Some(&b'>') {
+            self.pos += 1;
+        }
+    }
+
+    fn skip_ws(&mut self) {
+        while self.pos < self.data.len() {
+            let c = self.data[self.pos];
+            if is_white(c) {
+                self.pos += 1;
+            } else if c == b'%' {
+                let start = self.pos;
+                while self.pos < self.data.len() && !matches!(self.data[self.pos], b'\n' | b'\r') {
+                    self.pos += 1;
+                }
+                let line = &self.data[start..self.pos];
+                let end_marker: Option<&[u8]> = if line.starts_with(b"%%BeginData:") {
+                    Some(b"%%EndData")
+                } else if line.starts_with(b"%%BeginBinary:") {
+                    Some(b"%%EndBinary")
+                } else if line.starts_with(b"%%BeginPreview") {
+                    Some(b"%%EndPreview")
+                } else {
+                    None
+                };
+                if let Some(marker) = end_marker {
+                    self.pos = match self.data.get(self.pos..).unwrap_or_default().windows(marker.len()).position(|w| w == marker) {
+                        Some(offset) => self.pos.saturating_add(offset).min(self.data.len()),
+                        None => self.data.len(),
+                    };
+                }
+            } else {
+                break;
+            }
+        }
+    }
+
+    fn word(&mut self) -> &[u8] {
+        let start = self.pos;
+        while self.pos < self.data.len() {
+            let c = self.data[self.pos];
+            if is_white(c) || matches!(c, b'(' | b')' | b'<' | b'>' | b'[' | b']' | b'{' | b'}' | b'/' | b'%') {
+                break;
+            }
+            self.pos += 1;
+        }
+        &self.data[start..self.pos]
+    }
+
+    fn parenthesized(&mut self) -> Vec<u8> {
+        self.pos += 1;
+        let mut out = Vec::new();
+        let mut nesting = 1usize;
+        while self.pos < self.data.len() {
+            let c = self.data[self.pos];
+            self.pos += 1;
+            match c {
+                b'\\' => {
+                    let e = self.data.get(self.pos).copied().unwrap_or(b'\\');
+                    self.pos = self.pos.saturating_add(1).min(self.data.len());
+                    match e {
+                        b'n' => out.push(b'\n'),
+                        b'r' => out.push(b'\r'),
+                        b't' => out.push(b'\t'),
+                        b'0'..=b'7' => {
+                            let mut value = u32::from(e - b'0');
+                            for _ in 0..2 {
+                                match self.data.get(self.pos) {
+                                    Some(d @ b'0'..=b'7') => {
+                                        value = value * 8 + u32::from(*d - b'0');
+                                        self.pos += 1;
+                                    }
+                                    _ => break,
+                                }
+                            }
+                            out.push(value as u8);
+                        }
+                        b'\n' | b'\r' => {}
+                        other => out.push(other),
+                    }
+                }
+                b'(' => {
+                    nesting = nesting.saturating_add(1);
+                    out.push(c);
+                }
+                b')' => {
+                    nesting = nesting.saturating_sub(1);
+                    if nesting == 0 {
+                        break;
+                    }
+                    out.push(c);
+                }
+                _ => out.push(c),
+            }
+        }
+        out
+    }
+
+    fn hex_string(&mut self) -> Vec<u8> {
+        self.pos += 1;
+        let mut hex = Vec::new();
+        while self.pos < self.data.len() && self.data[self.pos] != b'>' {
+            if self.data[self.pos].is_ascii_hexdigit() {
+                hex.push(self.data[self.pos]);
+            }
+            self.pos += 1;
+        }
+        if self.data.get(self.pos) == Some(&b'>') {
+            self.pos += 1;
+        }
+        if hex.len() % 2 == 1 {
+            hex.push(b'0');
+        }
+        hex.chunks(2).filter_map(|pair| Some((hex_value(*pair.first()?) << 4) | hex_value(*pair.get(1)?))).collect()
+    }
+
+    fn ascii85(&mut self) -> Token {
+        let start = self.pos;
+        self.pos = self.pos.saturating_add(2).min(self.data.len());
+        while self.pos + 1 < self.data.len() && !(self.data[self.pos] == b'~' && self.data[self.pos + 1] == b'>') {
+            self.pos += 1;
+        }
+        self.pos = self.pos.saturating_add(2).min(self.data.len());
+        Token::Ascii85(self.data[start..self.pos].to_vec())
+    }
+}
+
+fn is_white(c: u8) -> bool {
+    matches!(c, 0 | 9 | 10 | 12 | 13 | 32)
+}
+
+fn hex_value(c: u8) -> u8 {
+    (c as char).to_digit(16).unwrap_or(0) as u8
+}
+
+fn parse_number(word: &[u8]) -> Option<f64> {
+    if word.is_empty() || !word.iter().all(|c| c.is_ascii_digit() || matches!(c, b'+' | b'-' | b'.')) || !word.iter().any(u8::is_ascii_digit) {
+        return None;
+    }
+    let text = std::str::from_utf8(word).ok()?;
+    text.parse::<f64>()
+        .ok()
+        .or_else(|| text.trim_start_matches(['+', '-']).parse::<f64>().ok().map(|value| if text.starts_with('-') { -value } else { value }))
+}
+
+#[cfg(test)]
+mod stack_tests {
+    use super::{ExecutionBudget, OperandStack, StackOperator, StackOutcome};
+
+    #[test]
+    fn stack_operators_follow_postscript_order_and_respect_limit() {
+        let mut stack = OperandStack::new(8);
+        assert!(stack.push(1));
+        assert!(stack.push(2));
+        assert!(stack.push(3));
+        stack.exchange();
+        assert_eq!(stack.values(), &[1, 3, 2]);
+        stack.duplicate();
+        assert_eq!(stack.values(), &[1, 3, 2, 2]);
+        stack.roll(4, 1);
+        assert_eq!(stack.values(), &[2, 1, 3, 2]);
+        stack.roll(4, -1);
+        assert_eq!(stack.values(), &[1, 3, 2, 2]);
+        stack.index(2);
+        assert_eq!(stack.values(), &[1, 3, 2, 2, 3]);
+        assert!(stack.copy_top(2));
+        assert_eq!(stack.values(), &[1, 3, 2, 2, 3, 2, 3]);
+        stack.duplicate();
+        assert_eq!(stack.len(), 8);
+        assert!(!stack.push(7));
+    }
+
+    #[test]
+    fn stack_underflow_and_invalid_rolls_are_safe() {
+        let mut stack = OperandStack::new(2);
+        assert_eq!(stack.pop_or(99), 99);
+        stack.duplicate_or(99);
+        assert_eq!(stack.values(), &[99]);
+        stack.clear();
+        stack.exchange_or(99);
+        assert_eq!(stack.values(), &[99, 99]);
+        stack.clear();
+        stack.roll(1, i64::MAX);
+        stack.index(usize::MAX);
+        assert!(stack.is_empty());
+        assert!(stack.copy_top(0));
+        assert!(stack.is_empty());
+    }
+
+    #[test]
+    fn stack_mutation_and_underflow_index_are_bounded() {
+        let mut stack = OperandStack::new(4);
+        assert!(stack.push(10));
+        assert!(stack.push(20));
+        stack.index_or(1, -1);
+        stack.index_or(9, -1);
+        assert_eq!(stack.values(), &[10, 20, 10, -1]);
+        stack.index_or(0, -1);
+        assert_eq!(stack.values(), &[10, 20, 10, -1]); // full stack silently drops the push
+
+        assert_eq!(stack.top(), Some(&-1));
+        stack.values_mut()[3] = 40;
+        stack.roll(3, i64::MIN);
+        assert_eq!(stack.values(), &[10, 40, 20, 10]);
+        assert!(stack.split_off(usize::MAX).is_empty());
+        assert_eq!(stack.split_off(1), [40, 20, 10]);
+        assert_eq!(stack.values(), &[10]);
+        assert_eq!(stack.pop(), Some(10));
+        assert_eq!(stack.pop(), None);
+        stack.clear();
+        assert!(stack.is_empty());
+    }
+
+    #[test]
+    fn shared_stack_operator_dispatch_reports_only_value_results() {
+        let mut stack = OperandStack::new(4);
+        assert!(stack.push(1));
+        assert!(stack.push(2));
+        assert_eq!(stack.execute(StackOperator::Count, 0), StackOutcome::Count(2));
+        assert_eq!(stack.execute(StackOperator::Exchange, 0), StackOutcome::None);
+        assert_eq!(stack.values(), &[2, 1]);
+        assert_eq!(stack.execute(StackOperator::Duplicate, 0), StackOutcome::None);
+        assert_eq!(stack.execute(StackOperator::Index(2), 0), StackOutcome::None);
+        assert_eq!(stack.values(), &[2, 1, 1, 2]);
+        assert_eq!(stack.execute(StackOperator::Roll { count: 3, shift: 1 }, 0), StackOutcome::None);
+        assert_eq!(stack.values(), &[2, 2, 1, 1]);
+        assert_eq!(stack.execute(StackOperator::CopyTop(2), 0), StackOutcome::Copied(false));
+        assert_eq!(stack.execute(StackOperator::Pop, 0), StackOutcome::Popped(Some(1)));
+        assert_eq!(stack.execute(StackOperator::Clear, 0), StackOutcome::None);
+        assert!(stack.is_empty());
+    }
+
+    #[test]
+    fn execution_budget_charges_atomically_and_bounds_call_depth() {
+        let mut budget = ExecutionBudget::new(3, 1);
+        assert!(budget.spend(2));
+        assert_eq!(budget.remaining(), 1);
+        assert!(!budget.spend(2));
+        assert_eq!(budget.remaining(), 1);
+        budget.charge(2);
+        assert_eq!(budget.remaining(), 0);
+        assert!(!budget.spend(1));
+        assert!(budget.enter_call());
+        assert_eq!(budget.call_depth(), 1);
+        assert!(!budget.enter_call());
+        budget.leave_call();
+        budget.leave_call();
+        assert_eq!(budget.call_depth(), 0);
+        assert!(budget.enter_call());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{Scanner, Token};
+
+    fn scan(source: &[u8]) -> Vec<Token> {
+        let mut scanner = Scanner::new(source, 0);
+        let mut tokens = Vec::new();
+        while let Some(token) = scanner.token() {
+            tokens.push(token);
+        }
+        tokens
+    }
+
+    #[test]
+    fn scans_names_numbers_strings_and_procedures() {
+        assert_eq!(
+            scan(b"/x //y 16#ff { 2 (a\\n(b)) }"),
+            vec![
+                Token::LiteralName("x".into()),
+                Token::Name("y".into()),
+                Token::Number(255.0),
+                Token::Procedure(vec![Token::Number(2.0), Token::String(b"a\n(b)".to_vec())]),
+            ]
+        );
+    }
+
+    #[test]
+    fn skips_dsc_binary_data_and_preserves_inline_ascii85() {
+        assert_eq!(scan(b"%%BeginBinary: 4\nxxxx%%EndBinary\n<~z~>"), vec![Token::Ascii85(b"<~z~>".to_vec())]);
+    }
+
+    #[test]
+    fn malformed_delimiters_terminate_without_advancing_past_source() {
+        let mut scanner = Scanner::new(b"<deadbeef", 0);
+        assert_eq!(scanner.token(), Some(Token::String(vec![0xde, 0xad, 0xbe, 0xef])));
+        assert_eq!(scanner.pos, scanner.data.len());
+    }
+}
diff --git a/crates/exr/src/decode.rs b/crates/exr/src/decode.rs
index 2b47f42eb..ab21064ce 100644
--- a/crates/exr/src/decode.rs
+++ b/crates/exr/src/decode.rs
@@ -29,7 +29,7 @@ use exr::prelude::{
 };
 pub use half::f16;
 
-use crate::channels::color_channels;
+use crate::channels::{color_channels, part_channel_name};
 
 /// Why a file could not be read or written.
 #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
@@ -402,6 +402,228 @@ impl Part {
     }
 }
 
+/// A channel placed in its part's display window. Samples are `f32`; samples outside the data
+/// window are filled with the caller's per-channel value.
+#[derive(Debug, Clone, PartialEq)]
+pub struct DisplayChannel {
+    pub name: String,
+    pub samples: Vec<f32>,
+}
+
+/// A decoded part whose channels are placed in the display window.
+#[derive(Debug, Clone, PartialEq)]
+pub struct DisplayPart {
+    pub info: PartInfo,
+    pub channels: Vec<DisplayChannel>,
+}
+
+/// Decodes the kept flat channels of one part and places them in its display window.
+///
+/// Channels are decoded in their stored sample type, converted to `f32`, and clipped or padded
+/// according to their data and display windows. `keep` and `fill` receive the part-qualified name
+/// from [`part_channel_name`], which is also returned in [`DisplayChannel::name`]. Both decoded
+/// block data and display-window buffers are bounded by `limits` before allocation.
+pub fn decode_display_part(
+    bytes: &[u8],
+    index: usize,
+    keep: &dyn Fn(&str) -> bool,
+    fill: &dyn Fn(&str) -> f32,
+    limits: &Limits,
+) -> Result<DisplayPart> {
+    // Only the caller-selected display planes are allocated here. Keep the shared header and
+    // expansion-ratio checks, but do not charge ignored channel data against the output budget.
+    let mut header_limits = *limits;
+    header_limits.max_width = u32::MAX;
+    header_limits.max_height = u32::MAX;
+    header_limits.max_pixels = u64::MAX;
+    header_limits.max_bytes = u64::MAX;
+    let meta = read_meta(bytes, &header_limits)?;
+    let info = meta.headers.get(index).map(|header| part_info(index, header)).ok_or_else(|| malformed(format!("part {index}")))?;
+    if info.deep {
+        return Err(Error::Unsupported("deep data (use the deep reader)".into()));
+    }
+    let display = info.display_window;
+    let pixels = u64::from(display.width)
+        .checked_mul(u64::from(display.height))
+        .ok_or_else(|| Error::LimitExceeded("display window dimensions overflow".into()))?;
+    if pixels > limits.max_pixels {
+        return Err(Error::LimitExceeded(format!("display window of {pixels} pixels exceeds {}", limits.max_pixels)));
+    }
+    let kept = info.channels.iter().filter(|channel| keep(&part_channel_name(info.name.as_deref(), &channel.name))).count();
+    let bytes_needed = pixels
+        .checked_mul(4)
+        .and_then(|bytes_per_channel| bytes_per_channel.checked_mul(kept as u64))
+        .ok_or_else(|| Error::LimitExceeded("display window byte size overflow".into()))?;
+    if bytes_needed > limits.max_bytes || usize::try_from(bytes_needed).is_err() {
+        return Err(Error::LimitExceeded(format!("{bytes_needed} display-window bytes exceed {}", limits.max_bytes)));
+    }
+    let block_limit = std::cell::Cell::new(None);
+    let select = DisplaySelect { index, keep, fill, limits, seen: std::cell::Cell::new(0), block_limit: &block_limit };
+    let image = ReadImage::new(ReadAllLayers { read_channels: select }, |_| {})
+        .from_buffered(Cursor::new(bytes))
+        .map_err(|error| block_limit.take().map(Error::LimitExceeded).unwrap_or_else(|| map_exr(error)))?;
+    let channels = image
+        .layer_data
+        .into_iter()
+        .nth(index)
+        .ok_or_else(|| malformed("the part was not read"))?
+        .channel_data
+        .into_iter()
+        .flatten()
+        .map(|(name, samples)| DisplayChannel { name, samples })
+        .collect();
+    Ok(DisplayPart { info, channels })
+}
+
+/// Filtered channel reader that writes each decoded block directly into a bounded display plane.
+struct DisplaySelect<'a> {
+    index: usize,
+    keep: &'a dyn Fn(&str) -> bool,
+    fill: &'a dyn Fn(&str) -> f32,
+    limits: &'a Limits,
+    seen: std::cell::Cell<usize>,
+    block_limit: &'a std::cell::Cell<Option<String>>,
+}
+
+struct DisplaySelectReader {
+    planes: Vec<Option<(String, Vec<f32>)>>,
+    offset: (i64, i64),
+    layer: (usize, usize),
+    display: (usize, usize),
+    f16s: Vec<f16>,
+    f32s: Vec<f32>,
+    u32s: Vec<u32>,
+}
+
+impl<'s> ReadChannels<'s> for DisplaySelect<'_> {
+    type Reader = DisplaySelectReader;
+
+    fn create_channels_reader(&'s self, header: &Header) -> exr::error::Result<DisplaySelectReader> {
+        let part = self.seen.get();
+        self.seen.set(part.saturating_add(1));
+        let (layer_w, layer_h) = (header.layer_size.0, header.layer_size.1);
+        let display_window = header.shared_attributes.display_window;
+        let (display_w, display_h) = (display_window.size.0, display_window.size.1);
+        if part != self.index {
+            return Ok(DisplaySelectReader {
+                planes: header.channels.list.iter().map(|_| None).collect(),
+                offset: (0, 0),
+                layer: (layer_w, layer_h),
+                display: (display_w, display_h),
+                f16s: vec![],
+                f32s: vec![],
+                u32s: vec![],
+            });
+        }
+        // The EXR crate decompresses each accepted block before `read_block` can discard ignored
+        // channels. Bound that all-channel input separately from the selected output planes.
+        let Some(block_bytes) = layer_w
+            .checked_mul(layer_h)
+            .and_then(|pixels| pixels.checked_mul(header.channels.list.len().max(1)))
+            .and_then(|samples| samples.checked_mul(std::mem::size_of::<f32>()))
+        else {
+            self.block_limit.set(Some(format!("data-window block size exceeds {}", self.limits.max_bytes)));
+            return Err(exr::error::Error::Invalid("data-window block size overflow".into()));
+        };
+        if u64::try_from(block_bytes).map_or(true, |bytes| bytes > self.limits.max_bytes) || block_bytes > isize::MAX as usize {
+            self.block_limit.set(Some(format!("{block_bytes} data-window bytes exceed {}", self.limits.max_bytes)));
+            return Err(exr::error::Error::Invalid("data-window blocks exceed limit".into()));
+        }
+        let pixels = display_w.checked_mul(display_h).filter(|n| *n > 0).ok_or(exr::error::Error::Invalid("display window".into()))?;
+        let prefix = header.own_attributes.layer_name.as_ref().map(|name| name.to_string()).filter(|name| !name.is_empty());
+        let kept =
+            header.channels.list.iter().filter(|channel| (self.keep)(&part_channel_name(prefix.as_deref(), &channel.name.to_string()))).count();
+        let bytes = pixels
+            .checked_mul(4)
+            .and_then(|n| n.checked_mul(kept))
+            .ok_or_else(|| exr::error::Error::Invalid("display planes exceed limit".into()))?;
+        if pixels as u64 > self.limits.max_pixels || bytes as u64 > self.limits.max_bytes || bytes > isize::MAX as usize {
+            return Err(exr::error::Error::Invalid("display planes exceed limit".into()));
+        }
+        let mut planes = Vec::with_capacity(header.channels.list.len());
+        for channel in header.channels.list.iter() {
+            let name = part_channel_name(prefix.as_deref(), &channel.name.to_string());
+            let plane = if (self.keep)(&name) {
+                if channel.sampling.0 != 1 || channel.sampling.1 != 1 {
+                    return Err(exr::error::Error::NotSupported("subsampled channels".into()));
+                }
+                Some((name.clone(), vec![(self.fill)(&name); pixels]))
+            } else {
+                None
+            };
+            planes.push(plane);
+        }
+        let position = header.own_attributes.layer_position;
+        Ok(DisplaySelectReader {
+            planes,
+            offset: (i64::from(position.0) - i64::from(display_window.position.0), i64::from(position.1) - i64::from(display_window.position.1)),
+            layer: (layer_w, layer_h),
+            display: (display_w, display_h),
+            f16s: vec![],
+            f32s: vec![],
+            u32s: vec![],
+        })
+    }
+}
+
+impl ChannelsReader for DisplaySelectReader {
+    type Channels = Vec<Option<(String, Vec<f32>)>>;
+
+    fn filter_block(&self, tile: TileCoordinates) -> bool {
+        tile.is_largest_resolution_level() && self.planes.iter().any(Option::is_some)
+    }
+
+    fn read_block(&mut self, header: &Header, block: UncompressedBlock) -> exr::error::UnitResult {
+        let ((layer_w, layer_h), (display_w, display_h)) = (self.layer, self.display);
+        for line in block.lines(&header.channels) {
+            let Some(Some((_, dst_plane))) = self.planes.get_mut(line.location.channel) else { continue };
+            let (x, y, count) = (line.location.position.0, line.location.position.1, line.location.sample_count);
+            if y >= layer_h || x.checked_add(count).is_none_or(|end| end > layer_w) {
+                continue;
+            }
+            let Some(ty) = usize::try_from(y as i64 + self.offset.1).ok().filter(|ty| *ty < display_h) else { continue };
+            let tx0 = x as i64 + self.offset.0;
+            let skip = usize::try_from(-tx0).unwrap_or(0).min(count);
+            let tx = usize::try_from(tx0.max(0)).unwrap_or(usize::MAX);
+            let take = (count - skip).min(display_w.saturating_sub(tx));
+            if take == 0 {
+                continue;
+            }
+            let start = ty.checked_mul(display_w).and_then(|row| row.checked_add(tx));
+            let Some(dst) = start.and_then(|s| dst_plane.get_mut(s..s.checked_add(take)?)) else { continue };
+            match header.channels.list.get(line.location.channel).map(|c| c.sample_type) {
+                Some(ExrSample::F16) => {
+                    self.f16s.resize(count, f16::ZERO);
+                    line.read_samples_into_slice(&mut self.f16s)?;
+                    for (d, s) in dst.iter_mut().zip(self.f16s.iter().skip(skip)) {
+                        *d = s.to_f32();
+                    }
+                }
+                Some(ExrSample::F32) => {
+                    self.f32s.resize(count, 0.0);
+                    line.read_samples_into_slice(&mut self.f32s)?;
+                    for (d, s) in dst.iter_mut().zip(self.f32s.iter().skip(skip)) {
+                        *d = *s;
+                    }
+                }
+                Some(ExrSample::U32) => {
+                    self.u32s.resize(count, 0);
+                    line.read_samples_into_slice(&mut self.u32s)?;
+                    for (d, s) in dst.iter_mut().zip(self.u32s.iter().skip(skip)) {
+                        *d = *s as f32;
+                    }
+                }
+                None => continue,
+            }
+        }
+        Ok(())
+    }
+
+    fn into_channels(self) -> Self::Channels {
+        self.planes
+    }
+}
+
 /// Places a data-window plane in a display window: samples outside the display window are cut,
 /// the display window's pixels the data window does not cover are `fill`. `None` when the plane
 /// is not `data.width × data.height` samples or the display window has more than `max_pixels`
diff --git a/crates/exr/src/decode_tests.rs b/crates/exr/src/decode_tests.rs
index 69d8d07ac..54c28d9aa 100644
--- a/crates/exr/src/decode_tests.rs
+++ b/crates/exr/src/decode_tests.rs
@@ -118,6 +118,46 @@ fn display_window_placement() {
     assert_eq!(to_display_window(&[1.0, 2.0, 3.0, 4.0], far, display, 0.0, 100).unwrap(), [0.0; 6]);
 }
 
+#[test]
+fn decoded_display_part_places_selected_channels_and_checks_total_budget() {
+    let bytes = file(vec![layer(None, 2, 2, &["R", "G"], false, exr::prelude::Compression::ZIP1)], (3, 2));
+    let part = decode_display_part(&bytes, 0, &|name| name == "R", &|_| 9.0, &Limits::default()).unwrap();
+    assert_eq!(part.channels.len(), 1);
+    assert_eq!(part.channels[0].name, "R");
+    assert_eq!(part.channels[0].samples, [0.0, 1.0, 9.0, 2.0, 3.0, 9.0]);
+
+    let limits = Limits { max_bytes: 6 * 4 - 1, ..Limits::default() };
+    assert!(matches!(decode_display_part(&bytes, 0, &all, &|_| 0.0, &limits), Err(Error::LimitExceeded(_))));
+
+    // One selected display plane fits exactly, but the EXR decoder must decompress both data
+    // channels in its input block before discarding the ignored one.
+    let block_limits = Limits { max_bytes: 6 * 4, ..Limits::default() };
+    assert!(matches!(decode_display_part(&bytes, 0, &|name| name == "R", &|_| 0.0, &block_limits), Err(Error::LimitExceeded(_))));
+}
+
+#[test]
+fn decoded_display_part_clips_a_wide_data_window_to_the_small_display() {
+    let width = (Limits::default().max_width as usize) + 1;
+    let bytes = file(vec![layer(None, width, 1, &["R"], false, exr::prelude::Compression::ZIP1)], (1, 1));
+    let part = decode_display_part(&bytes, 0, &all, &|_| 9.0, &Limits::default()).unwrap();
+    assert_eq!(part.channels.len(), 1);
+    assert_eq!(part.channels[0].samples, [0.0]);
+}
+
+#[test]
+fn decoded_display_part_rejects_kept_subsampled_channels() {
+    let mut bytes = file(vec![layer(None, 4, 1, &["R"], false, exr::prelude::Compression::Uncompressed)], (4, 1));
+    // exr's writer doesn't emit subsampling yet, so patch the standard chlist sampling field in a
+    // valid uncompressed file. The reader must reject it before looking at the block payload.
+    let tag = b"channels\0chlist\0";
+    let attr = bytes.windows(tag.len()).position(|window| window == tag).unwrap();
+    let payload = attr + tag.len() + 4;
+    let name_end = payload + bytes[payload..].iter().position(|byte| *byte == 0).unwrap();
+    let x_sampling = name_end + 1 + 4 + 1 + 3;
+    bytes[x_sampling..x_sampling + 4].copy_from_slice(&2u32.to_le_bytes());
+    assert!(matches!(decode_display_part(&bytes, 0, &|name| name == "R", &|_| 0.0, &Limits::default()), Err(Error::Unsupported(_))));
+}
+
 /// A 2x2 single-part file whose layer carries a 2x1 preview.
 fn with_preview() -> Vec<u8> {
     let mut attrs = LayerAttributes::named("rgb");
diff --git a/crates/figcraft-format/Cargo.toml b/crates/figcraft-format/Cargo.toml
new file mode 100644
index 000000000..009e40c01
--- /dev/null
+++ b/crates/figcraft-format/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+name = "craft-figcraft-format"
+description = "The native FigCraft document JSON and archive contract."
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+craft-zip = { workspace = true }
+zip = { version = "9", default-features = false, features = ["deflate-flate2"] }
+thiserror = { workspace = true }
diff --git a/crates/figcraft-format/src/lib.rs b/crates/figcraft-format/src/lib.rs
new file mode 100644
index 000000000..7475c5e21
--- /dev/null
+++ b/crates/figcraft-format/src/lib.rs
@@ -0,0 +1,849 @@
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+//! The neutral JSON header and version contract for FigCraft's native project format.
+//! App-specific document fields remain a generic flattened payload.
+pub mod library;
+use serde::de::{IgnoredAny, MapAccess, Visitor};
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::Value;
+
+pub const EXTENSION: &str = "figcraft";
+pub const FORMAT: &str = "figcraft";
+pub const VERSION: u32 = 1;
+
+fn is_false(value: &bool) -> bool {
+    !value
+}
+
+/// One native version-history index entry. Invalid optional values decode to the same defaults as
+/// the historical lenient reader; the app applies document-specific validity and issue reporting.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+pub struct VersionEntry {
+    pub id: String,
+    pub name: String,
+    pub description: String,
+    pub time: u64,
+    #[serde(skip_serializing_if = "is_false")]
+    pub auto: bool,
+    pub images: Vec<String>,
+}
+
+impl<'de> Deserialize<'de> for VersionEntry {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = Value::deserialize(deserializer)?;
+        let string = |key: &str| value.get(key).and_then(Value::as_str).unwrap_or_default().to_owned();
+        let images = value.get("images").and_then(Value::as_array).into_iter().flatten().filter_map(Value::as_str).map(str::to_owned).collect();
+        Ok(Self {
+            id: string("id"),
+            name: string("name"),
+            description: string("description"),
+            time: value.get("time").and_then(Value::as_u64).unwrap_or(0),
+            auto: value.get("auto").and_then(Value::as_bool).unwrap_or(false),
+            images,
+        })
+    }
+}
+
+/// Native version-history index, oldest first.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+pub struct VersionIndex {
+    pub versions: Vec<VersionEntry>,
+}
+
+/// Encode the native version-history index using the FigCraft wire schema.
+pub fn write_version_index(index: &VersionIndex) -> Result<Vec<u8>, serde_json::Error> {
+    serde_json::to_vec(index)
+}
+
+/// Decode the native version-history index using the format's lenient optional-field defaults.
+pub fn read_version_index(bytes: &[u8]) -> Result<VersionIndex, serde_json::Error> {
+    serde_json::from_slice(bytes)
+}
+
+impl<'de> Deserialize<'de> for VersionIndex {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = Value::deserialize(deserializer)?;
+        let versions = value
+            .get("versions")
+            .and_then(Value::as_array)
+            .map(|entries| entries.iter().cloned().map(serde_json::from_value).collect::<Result<Vec<_>, _>>())
+            .transpose()
+            .map_err(serde::de::Error::custom)?
+            .unwrap_or_default();
+        Ok(Self { versions })
+    }
+}
+
+/// State stored on a native branch entry.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum BranchState {
+    #[default]
+    Active,
+    Merged,
+    Archived,
+}
+
+/// One native branch index entry.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BranchEntry {
+    pub id: String,
+    pub name: String,
+    pub time: u64,
+    pub client: u32,
+    pub state: BranchState,
+    pub base_images: Vec<String>,
+    pub head_images: Vec<String>,
+}
+
+impl<'de> Deserialize<'de> for BranchEntry {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = Value::deserialize(deserializer)?;
+        let string = |key: &str| value.get(key).and_then(Value::as_str).unwrap_or_default().to_owned();
+        let images =
+            |key: &str| value.get(key).and_then(Value::as_array).into_iter().flatten().filter_map(Value::as_str).map(str::to_owned).collect();
+        let state = value.get("state").cloned().and_then(|v| serde_json::from_value(v).ok()).unwrap_or_default();
+        let client = value.get("client").and_then(Value::as_u64).and_then(|v| u32::try_from(v).ok()).unwrap_or(0);
+        Ok(Self {
+            id: string("id"),
+            name: string("name"),
+            time: value.get("time").and_then(Value::as_u64).unwrap_or(0),
+            client,
+            state,
+            base_images: images("baseImages"),
+            head_images: images("headImages"),
+        })
+    }
+}
+
+/// Native branch index.
+#[derive(Clone, Debug, Default, PartialEq, Serialize)]
+pub struct BranchIndex {
+    pub branches: Vec<BranchEntry>,
+}
+
+/// Encode the native branch index using the FigCraft wire schema.
+pub fn write_branch_index(index: &BranchIndex) -> Result<Vec<u8>, serde_json::Error> {
+    serde_json::to_vec(index)
+}
+
+/// Decode the native branch index using the format's lenient optional-field defaults.
+pub fn read_branch_index(bytes: &[u8]) -> Result<BranchIndex, serde_json::Error> {
+    serde_json::from_slice(bytes)
+}
+
+impl<'de> Deserialize<'de> for BranchIndex {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = Value::deserialize(deserializer)?;
+        let branches = value
+            .get("branches")
+            .and_then(Value::as_array)
+            .map(|entries| entries.iter().cloned().map(serde_json::from_value).collect::<Result<Vec<_>, _>>())
+            .transpose()
+            .map_err(serde::de::Error::custom)?
+            .unwrap_or_default();
+        Ok(Self { branches })
+    }
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct Header {
+    pub version: Option<u64>,
+    pub images: Option<Vec<String>>,
+}
+
+pub fn read_header(text: &str) -> Result<Header, serde_json::Error> {
+    serde_json::from_str(text)
+}
+
+impl<'de> Deserialize<'de> for Header {
+    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+        struct V;
+        impl<'de> Visitor<'de> for V {
+            type Value = Header;
+            fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str("a FigCraft document object")
+            }
+            fn visit_map<A: MapAccess<'de>>(self, mut m: A) -> Result<Header, A::Error> {
+                let mut h = Header::default();
+                while let Some(k) = m.next_key::<String>()? {
+                    match k.as_str() {
+                        "version" => h.version = m.next_value::<Value>()?.as_u64(),
+                        "imageIndex" => {
+                            h.images = m
+                                .next_value::<Value>()?
+                                .as_array()
+                                .map(|a| a.iter().filter_map(|v| v.get("hash").and_then(Value::as_str).map(str::to_owned)).collect())
+                        }
+                        _ => {
+                            m.next_value::<IgnoredAny>()?;
+                        }
+                    }
+                }
+                Ok(h)
+            }
+        }
+        d.deserialize_map(V)
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
+#[error("this file was saved by a newer FigCraft (format version {0})")]
+pub struct NewerVersion(pub u32);
+
+/// Failure while reading the native document envelope or its app-supplied payload type.
+#[derive(Debug, thiserror::Error)]
+pub enum ReadDocumentError {
+    #[error(transparent)]
+    Json(#[from] serde_json::Error),
+    #[error(transparent)]
+    NewerVersion(#[from] NewerVersion),
+}
+
+/// Read a document payload after checking the native header and version first.
+///
+/// The payload type is supplied by the consumer, keeping app model conversion outside this crate.
+pub fn read_document_json<D: serde::de::DeserializeOwned>(text: &str) -> Result<(D, Header), ReadDocumentError> {
+    let header = read_header(text)?;
+    check_version(&header)?;
+    let document = serde_json::from_str(text)?;
+    Ok((document, header))
+}
+
+/// The native document fields needed to render a recent-file preview.
+#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
+pub struct PreviewDocument {
+    #[serde(default)]
+    pub pages: Vec<u64>,
+    #[serde(default)]
+    pub nodes: std::collections::BTreeMap<String, PreviewNode>,
+    #[serde(default)]
+    pub kind: PreviewKind,
+}
+
+/// Preview-relevant fields from one native document node.
+#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
+pub struct PreviewNode {
+    #[serde(default)]
+    pub background: Option<Value>,
+}
+
+/// The supported native document kinds as stored on disk.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum PreviewKind {
+    #[default]
+    Design,
+    Board,
+}
+
+/// Decode the preview-relevant subset of the native FigCraft document schema.
+pub fn read_preview_document(bytes: &[u8]) -> Result<PreviewDocument, serde_json::Error> {
+    serde_json::from_slice(bytes)
+}
+
+/// Largest `thumbnail.png` returned for a recent-file preview.
+pub const MAX_PREVIEW_THUMBNAIL_BYTES: u64 = 8 * 1024 * 1024;
+/// Largest `document.json` read to build a recent-file preview.
+pub const MAX_PREVIEW_DOCUMENT_BYTES: u64 = 64 * 1024 * 1024;
+
+/// Native `.figcraft` members needed by the recent-file preview.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct PreviewArchive {
+    /// Whether the archive has a `document.json` entry, even if it is damaged or oversized.
+    /// Consumers use this to distinguish a malformed native archive from other ZIP formats.
+    pub has_document: bool,
+    /// The thumbnail bytes, absent when missing, damaged, or above [`MAX_PREVIEW_THUMBNAIL_BYTES`].
+    pub thumbnail_png: Option<Vec<u8>>,
+    /// The first-page fields, absent when `document.json` is missing, damaged, or oversized.
+    pub document: Option<PreviewDocument>,
+}
+
+/// Read only the thumbnail member for a native archive-list thumbnail.
+///
+/// This avoids unpacking the document when a caller needs only the image. Missing, damaged,
+/// and oversized entries return None; an unreadable archive is an error.
+pub fn read_preview_thumbnail<R: std::io::Read + std::io::Seek>(reader: R) -> Result<Option<Vec<u8>>, FormatError> {
+    let mut archive = SeekArchive::open(reader, u64::MAX).map_err(|error| FormatError::Corrupt(error.to_string()))?;
+    Ok(archive.read("thumbnail.png", MAX_PREVIEW_THUMBNAIL_BYTES).ok().flatten())
+}
+
+/// Read the bounded native preview members of a `.figcraft` archive.
+///
+/// An unreadable archive is an error; a missing, damaged, or oversized member is represented by
+/// `None`, so the caller can still show the other part of the preview. The thumbnail and document
+/// retain the separate limits used by the app's recent-file preview.
+pub fn read_preview_archive<R: std::io::Read + std::io::Seek>(reader: R) -> Result<PreviewArchive, FormatError> {
+    let mut archive = SeekArchive::open(reader, u64::MAX).map_err(|error| FormatError::Corrupt(error.to_string()))?;
+    Ok(read_preview_archive_from(&mut archive))
+}
+
+/// Read bounded native preview members from an already-open shared archive reader.
+///
+/// This lets callers preserve fallback handling for other ZIP formats without implementing ZIP
+/// member access themselves.
+pub fn read_preview_archive_from(archive: &mut impl NativeArchive) -> PreviewArchive {
+    let has_document = archive.contains("document.json");
+    let thumbnail_png = archive.read_member("thumbnail.png", MAX_PREVIEW_THUMBNAIL_BYTES).ok().flatten();
+    let document = if has_document {
+        archive.read_member("document.json", MAX_PREVIEW_DOCUMENT_BYTES).ok().flatten().and_then(|bytes| read_preview_document(&bytes).ok())
+    } else {
+        None
+    };
+    PreviewArchive { has_document, thumbnail_png, document }
+}
+
+pub fn check_version(h: &Header) -> Result<(), NewerVersion> {
+    if let Some(v) = h.version
+        && v > u64::from(VERSION)
+    {
+        return Err(NewerVersion(u32::try_from(v).unwrap_or(u32::MAX)));
+    }
+    Ok(())
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct ImageIndexEntry {
+    pub hash: String,
+    pub width: u32,
+    pub height: u32,
+}
+
+pub fn write_document_json<D: Serialize, W: std::io::Write>(doc: &D, images: &[ImageIndexEntry], w: W) -> Result<(), serde_json::Error> {
+    #[derive(Serialize)]
+    struct Flat<'a, D: ?Sized> {
+        format: &'static str,
+        version: u32,
+        #[serde(rename = "imageIndex")]
+        images: &'a [ImageIndexEntry],
+        #[serde(flatten)]
+        document: &'a D,
+    }
+    Flat { format: FORMAT, version: VERSION, images, document: doc }.serialize(&mut serde_json::Serializer::new(w))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn preview_archive_reads_native_members_and_preserves_document_presence() {
+        let document = br#"{"pages":[7],"nodes":{"7":{"background":{"r":0.25}}},"kind":"board"}"#;
+        let bytes = write_archive([
+            Member { name: "thumbnail.png", bytes: b"png bytes", compression: Compression::Stored },
+            Member { name: "document.json", bytes: document, compression: Compression::Deflated },
+        ])
+        .unwrap();
+        assert_eq!(read_preview_thumbnail(std::io::Cursor::new(bytes.clone())).unwrap().as_deref(), Some(b"png bytes".as_slice()));
+        let mut archive = SeekArchive::open(std::io::Cursor::new(bytes.clone()), u64::MAX).unwrap();
+        assert!(read_preview_archive_from(&mut archive).has_document);
+        let preview = read_preview_archive(std::io::Cursor::new(bytes)).unwrap();
+        assert!(preview.has_document);
+        assert_eq!(preview.thumbnail_png.as_deref(), Some(b"png bytes".as_slice()));
+        let document = preview.document.unwrap();
+        assert_eq!(document.pages, [7]);
+        assert_eq!(document.kind, PreviewKind::Board);
+        assert_eq!(document.nodes["7"].background.as_ref().unwrap()["r"], 0.25);
+
+        // A malformed native document still identifies this as a FigCraft archive, allowing the
+        // app to retain its existing fallback instead of interpreting it as another ZIP format.
+        let bytes = write_archive([Member { name: "document.json", bytes: b"{", compression: Compression::Stored }]).unwrap();
+        let preview = read_preview_archive(std::io::Cursor::new(bytes)).unwrap();
+        assert!(preview.has_document);
+        assert!(preview.document.is_none());
+        assert!(preview.thumbnail_png.is_none());
+        assert!(read_preview_archive(std::io::Cursor::new(b"not a zip".as_slice())).is_err());
+    }
+
+    #[test]
+    fn preview_archive_keeps_thumbnail_and_document_size_limits_independent() {
+        let too_large_thumbnail = vec![0; MAX_PREVIEW_THUMBNAIL_BYTES as usize + 1];
+        let bytes = write_archive([
+            Member { name: "thumbnail.png", bytes: &too_large_thumbnail, compression: Compression::Deflated },
+            Member { name: "document.json", bytes: br#"{"pages":[3]}"#, compression: Compression::Stored },
+        ])
+        .unwrap();
+        let preview = read_preview_archive(std::io::Cursor::new(bytes)).unwrap();
+        assert!(preview.thumbnail_png.is_none());
+        assert_eq!(preview.document.unwrap().pages, [3]);
+
+        let too_large_document = vec![b' '; MAX_PREVIEW_DOCUMENT_BYTES as usize + 1];
+        let bytes = write_archive([Member { name: "document.json", bytes: &too_large_document, compression: Compression::Deflated }]).unwrap();
+        let preview = read_preview_archive(std::io::Cursor::new(bytes)).unwrap();
+        assert!(preview.has_document);
+        assert!(preview.document.is_none());
+    }
+
+    #[test]
+    fn header_skips_app_fields() {
+        let h = read_header(r#"{"version":1,"imageIndex":[{"hash":"abc"}],"nested":{"unused":true}}"#).unwrap();
+        assert_eq!(h.version, Some(1));
+        assert_eq!(h.images, Some(vec!["abc".into()]));
+    }
+
+    #[test]
+    fn version_index_preserves_lenient_defaults_and_writes_compact_auto_flag() {
+        let index = read_version_index(br#"{"extra":true,"versions":[{"id":"v1","time":7,"auto":false,"images":["a",3]},{}]}"#).unwrap();
+        assert_eq!(index.versions.len(), 2);
+        assert_eq!(index.versions[0].images, vec!["a"]);
+        assert_eq!(index.versions[1], VersionEntry::default());
+        let encoded: Value = serde_json::from_slice(&write_version_index(&index).unwrap()).unwrap();
+        assert!(encoded["versions"][0].get("auto").is_none());
+        assert_eq!(encoded["versions"][0]["time"], 7);
+    }
+
+    #[test]
+    fn branch_index_uses_native_camel_case_and_tolerates_invalid_optional_fields() {
+        let index =
+            read_branch_index(br#"{"branches":[{"id":"b1","client":4294967296,"state":"unknown","baseImages":["a",false],"headImages":["b"]},{}]}"#)
+                .unwrap();
+        let first = &index.branches[0];
+        assert_eq!(first.client, 0);
+        assert_eq!(first.state, BranchState::Active);
+        assert_eq!(first.base_images, vec!["a"]);
+        assert_eq!(first.head_images, vec!["b"]);
+        let encoded = serde_json::to_value(&index).unwrap();
+        assert_eq!(encoded["branches"][0]["baseImages"][0], "a");
+        assert!(encoded["branches"][0].get("base_images").is_none());
+    }
+
+    #[test]
+    fn document_limit_keeps_compressible_files_and_caps_expansion() {
+        const MB: u64 = 1024 * 1024;
+        assert_eq!(document_limit(0, 0), MAX_MEMBER);
+        assert_eq!(document_limit(MB, 2 * MB), MAX_MEMBER);
+        assert_eq!(document_limit(u64::MAX, MB), MAX_MEMBER);
+        assert_eq!(document_limit(MAX_DOCUMENT, MAX_DOCUMENT), MAX_DOCUMENT);
+        assert_eq!(document_limit(244_362_923, 260 * MB), 244_362_923 * DOCUMENT_RATIO);
+    }
+
+    #[test]
+    fn read_budget_enforces_member_and_archive_totals() {
+        let bytes = write_archive([
+            Member { name: "one", bytes: b"12345678", compression: Compression::Stored },
+            Member { name: "two", bytes: b"abcdefgh", compression: Compression::Stored },
+        ])
+        .unwrap();
+        let mut archive = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 128 }).unwrap();
+        let mut budget = ReadBudget::new(10);
+        assert_eq!(budget.read(&mut archive, "one", 16).unwrap(), b"12345678");
+        assert!(budget.exceeds_remaining(&mut archive, "two"));
+        assert!(budget.exhausted_message().contains("contents together pass 10 bytes"));
+        assert!(budget.read(&mut archive, "two", 16).unwrap_err().to_string().contains("contents together pass 10 bytes"));
+
+        let mut member_budget = ReadBudget::new(100);
+        assert!(member_budget.read(&mut archive, "two", 4).unwrap_err().to_string().contains("two is too large"));
+        assert_eq!(member_budget.read(&mut archive, "two", 16).unwrap(), b"abcdefgh");
+    }
+    #[test]
+    fn newer_version_is_reported_before_document_decode() {
+        assert_eq!(check_version(&Header { version: Some(2), images: None }), Err(NewerVersion(2)));
+        assert_eq!(check_version(&Header { version: Some(u64::MAX), images: None }), Err(NewerVersion(u32::MAX)));
+
+        #[derive(Deserialize)]
+        struct Payload {
+            document: u32,
+        }
+        let text = r#"{"version":2,"document":{"wrong":"type"}}"#;
+        assert!(matches!(read_document_json::<Payload>(text), Err(ReadDocumentError::NewerVersion(NewerVersion(2)))));
+        let (payload, header) = read_document_json::<Payload>(r#"{"version":1,"imageIndex":[{"hash":"a"}],"document":5}"#).unwrap();
+        assert_eq!(payload.document, 5);
+        assert_eq!(header.images, Some(vec!["a".into()]));
+    }
+    #[test]
+    fn writer_flattens_document_fields() {
+        let doc = serde_json::json!({"name":"example"});
+        let mut bytes = Vec::new();
+        write_document_json(&doc, &[], &mut bytes).unwrap();
+        let v: Value = serde_json::from_slice(&bytes).unwrap();
+        assert_eq!(v["format"], FORMAT);
+        assert_eq!(v["version"], VERSION);
+        assert_eq!(v["name"], "example");
+    }
+
+    #[test]
+    fn preview_document_reads_native_page_background_and_kind() {
+        let doc = read_preview_document(br#"{"pages":[7],"nodes":{"7":{"background":{"r":0.1}}},"kind":"board","unrelated":true}"#).unwrap();
+        assert_eq!(doc.pages, vec![7]);
+        assert_eq!(doc.nodes["7"].background.as_ref().and_then(|v| v.get("r")).and_then(Value::as_f64), Some(0.1));
+        assert_eq!(doc.kind, PreviewKind::Board);
+        assert_eq!(read_preview_document(b"{}").unwrap(), PreviewDocument::default());
+        assert!(read_preview_document(br#"{"kind":"unknown"}"#).is_err());
+    }
+}
+
+/// Limits for the native ZIP package reader.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct ArchiveLimits {
+    pub max_entries: u64,
+    pub max_total_bytes: u64,
+}
+
+/// A bounded reader for a native `.figcraft` ZIP package.
+pub struct Archive<'a> {
+    inner: craft_zip::Archive<'a>,
+}
+
+impl<'a> Archive<'a> {
+    pub fn open(bytes: &'a [u8], limits: ArchiveLimits) -> Result<Self, craft_zip::Error> {
+        let inner = craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: limits.max_entries, max_total_bytes: limits.max_total_bytes })?;
+        Ok(Self { inner })
+    }
+
+    pub fn names(&self) -> impl Iterator<Item = std::borrow::Cow<'_, str>> {
+        self.inner.names()
+    }
+
+    pub fn has_duplicate_names(&self) -> bool {
+        self.inner.has_duplicate_names()
+    }
+
+    pub fn contains(&self, name: &str) -> bool {
+        self.inner.contains(name)
+    }
+
+    pub fn declared_size(&mut self, name: &str) -> Option<u64> {
+        self.inner.declared_size(name)
+    }
+
+    pub fn compressed_size(&mut self, name: &str) -> Option<u64> {
+        self.inner.compressed_size(name)
+    }
+
+    pub fn read(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error> {
+        self.inner.read(name, max_bytes)
+    }
+
+    pub fn budget_used(&self) -> u64 {
+        self.inner.budget().used()
+    }
+}
+
+/// One member to write into a native ZIP package.
+#[derive(Clone, Copy, Debug)]
+pub struct Member<'a> {
+    pub name: &'a str,
+    pub bytes: &'a [u8],
+    pub compression: craft_zip::Compression,
+}
+
+/// Write a deterministic native ZIP package using the shared ZIP writer.
+pub fn write_archive<'a>(members: impl IntoIterator<Item = Member<'a>>) -> Result<Vec<u8>, craft_zip::Error> {
+    let mut writer = craft_zip::Writer::new();
+    for member in members {
+        writer.add(member.name, member.bytes, member.compression)?;
+    }
+    writer.finish()
+}
+
+#[cfg(test)]
+mod archive_tests {
+    use super::*;
+
+    #[test]
+    fn bounded_archive_reader_and_writer_round_trip_members() {
+        let bytes =
+            write_archive([Member { name: "document.json", bytes: br#"{"version":1}"#, compression: craft_zip::Compression::Deflated }]).unwrap();
+        let mut archive = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 128 }).unwrap();
+        assert!(archive.contains("document.json"));
+        assert_eq!(archive.read("document.json", 32).unwrap(), Some(br#"{"version":1}"#.to_vec()));
+        assert_eq!(archive.budget_used(), 13);
+    }
+
+    #[test]
+    fn archive_reader_enforces_entry_and_total_limits() {
+        let bytes = write_archive([Member { name: "document.json", bytes: b"123456789", compression: craft_zip::Compression::Deflated }]).unwrap();
+        let mut small_entry = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 100 }).unwrap();
+        assert!(small_entry.read("document.json", 8).is_err());
+        let mut small_total = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 8 }).unwrap();
+        assert!(small_total.read("document.json", 100).is_err());
+    }
+}
+
+/// A native archive writer that keeps the streaming document serializer out of the consumer.
+pub struct ArchiveWriter {
+    inner: craft_zip::Writer,
+}
+
+impl ArchiveWriter {
+    pub fn new() -> Self {
+        Self { inner: craft_zip::Writer::new() }
+    }
+
+    pub fn add(&mut self, name: &str, bytes: &[u8], compression: craft_zip::Compression) -> Result<(), craft_zip::Error> {
+        self.inner.add(name, bytes, compression)
+    }
+
+    pub fn add_document_json<D: Serialize>(&mut self, name: &str, document: &D, images: &[ImageIndexEntry]) -> Result<(), ArchiveWriteError> {
+        self.inner
+            .add_with(name, craft_zip::Compression::Level(3), |w| write_document_json(document, images, w).map_err(std::io::Error::other))
+            .map_err(ArchiveWriteError::Archive)
+    }
+
+    pub fn finish(self) -> Result<Vec<u8>, craft_zip::Error> {
+        self.inner.finish()
+    }
+}
+
+impl Default for ArchiveWriter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum ArchiveWriteError {
+    #[error("could not serialize native document JSON: {0}")]
+    Json(#[from] serde_json::Error),
+    #[error("could not write native archive: {0}")]
+    Archive(#[from] craft_zip::Error),
+}
+
+#[cfg(test)]
+mod streaming_writer_tests {
+    use super::*;
+
+    #[test]
+    fn native_writer_streams_flat_document_into_archive() {
+        let document = serde_json::json!({"name":"streamed"});
+        let mut writer = ArchiveWriter::new();
+        writer.add_document_json("document.json", &document, &[]).unwrap();
+        let bytes = writer.finish().unwrap();
+        let mut archive = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 4096 }).unwrap();
+        let json = archive.read("document.json", 1024).unwrap().unwrap();
+        let value: Value = serde_json::from_slice(&json).unwrap();
+        assert_eq!(value["name"], "streamed");
+        assert_eq!(value["format"], FORMAT);
+    }
+}
+
+/// ZIP compression modes for native archive members.
+pub use craft_zip::Compression;
+
+/// A native ZIP reader for seekable sources that should not be copied into memory first.
+pub struct SeekArchive<R: std::io::Read + std::io::Seek> {
+    inner: zip::ZipArchive<R>,
+}
+
+impl<R: std::io::Read + std::io::Seek> SeekArchive<R> {
+    pub fn open(reader: R, max_entries: u64) -> Result<Self, craft_zip::Error> {
+        let inner = zip::ZipArchive::new(reader).map_err(|e| craft_zip::Error::NotZip(e.to_string()))?;
+        let count = inner.len() as u64;
+        if count > max_entries {
+            return Err(craft_zip::Error::TooManyEntries { declared: count, limit: max_entries });
+        }
+        Ok(Self { inner })
+    }
+
+    pub fn contains(&self, name: &str) -> bool {
+        self.inner.index_for_name(name).is_some()
+    }
+
+    pub fn names(&self) -> Vec<String> {
+        self.inner.file_names().filter_map(Result::ok).map(|n| n.into_owned()).collect()
+    }
+
+    pub fn declared_size(&mut self, name: &str) -> Option<u64> {
+        self.inner.index_for_name(name).and_then(|i| self.inner.by_index_raw(i).ok().map(|f| f.size()))
+    }
+
+    pub fn read(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error> {
+        let Some(index) = self.inner.index_for_name(name) else { return Ok(None) };
+        let mut file = self.inner.by_index(index).map_err(|e| craft_zip::Error::Entry { name: name.to_owned(), msg: e.to_string() })?;
+        if file.size() > max_bytes {
+            return Err(craft_zip::Error::EntryTooLarge { name: name.to_owned(), limit: max_bytes });
+        }
+        let mut bytes = Vec::new();
+        let mut limited = std::io::Read::take(&mut file, max_bytes.saturating_add(1));
+        let read = std::io::Read::read_to_end(&mut limited, &mut bytes);
+        if let Err(error) = read {
+            return Err(craft_zip::Error::Entry { name: name.to_owned(), msg: error.to_string() });
+        }
+        if bytes.len() as u64 > max_bytes {
+            return Err(craft_zip::Error::EntryTooLarge { name: name.to_owned(), limit: max_bytes });
+        }
+        Ok(Some(bytes))
+    }
+}
+
+/// Shared access contract implemented by in-memory and seekable native archive readers.
+pub trait NativeArchive {
+    fn contains(&self, name: &str) -> bool;
+    fn names(&self) -> Vec<String>;
+    fn declared_size(&mut self, name: &str) -> Option<u64>;
+    fn compressed_size(&mut self, name: &str) -> Option<u64>;
+    fn read_member(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error>;
+}
+
+impl NativeArchive for Archive<'_> {
+    fn contains(&self, name: &str) -> bool {
+        Archive::contains(self, name)
+    }
+    fn names(&self) -> Vec<String> {
+        Archive::names(self).map(|n| n.into_owned()).collect()
+    }
+    fn declared_size(&mut self, name: &str) -> Option<u64> {
+        Archive::declared_size(self, name)
+    }
+    fn compressed_size(&mut self, name: &str) -> Option<u64> {
+        Archive::compressed_size(self, name)
+    }
+    fn read_member(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error> {
+        Archive::read(self, name, max_bytes)
+    }
+}
+
+impl<R: std::io::Read + std::io::Seek> NativeArchive for SeekArchive<R> {
+    fn contains(&self, name: &str) -> bool {
+        SeekArchive::contains(self, name)
+    }
+    fn names(&self) -> Vec<String> {
+        SeekArchive::names(self)
+    }
+    fn declared_size(&mut self, name: &str) -> Option<u64> {
+        SeekArchive::declared_size(self, name)
+    }
+    fn compressed_size(&mut self, name: &str) -> Option<u64> {
+        self.inner.index_for_name(name).and_then(|i| self.inner.by_index_raw(i).ok().map(|f| f.compressed_size()))
+    }
+    fn read_member(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error> {
+        SeekArchive::read(self, name, max_bytes)
+    }
+}
+
+#[cfg(test)]
+mod seek_archive_tests {
+    use super::*;
+
+    #[test]
+    fn seekable_reader_matches_bounded_in_memory_reader() {
+        let bytes = write_archive([Member { name: "document.json", bytes: b"payload", compression: Compression::Stored }]).unwrap();
+        let mut reader = SeekArchive::open(std::io::Cursor::new(bytes), 4).unwrap();
+        assert!(reader.contains("document.json"));
+        assert_eq!(reader.read_member("document.json", 16).unwrap(), Some(b"payload".to_vec()));
+        assert_eq!(reader.declared_size("document.json"), Some(7));
+        assert!(reader.read_member("document.json", 3).is_err());
+    }
+}
+
+/// Largest individual ZIP member read by the native format.
+pub const MAX_MEMBER: u64 = 512 * 1024 * 1024;
+/// The document expansion ratio that its compressed size may claim.
+pub const DOCUMENT_RATIO: u64 = 16;
+#[cfg(not(target_pointer_width = "32"))]
+pub const MAX_DOCUMENT: u64 = 4 * 1024 * 1024 * 1024;
+#[cfg(target_pointer_width = "32")]
+pub const MAX_DOCUMENT: u64 = 1024 * 1024 * 1024;
+
+/// Upper bound for the expanded document member based on both the archive and member policy.
+/// The floor preserves support for large but highly compressible documents; the ceiling prevents
+/// a tiny archive from claiming an unbounded expansion.
+pub fn document_limit(packed: u64, archive_bytes: u64) -> u64 {
+    packed.min(archive_bytes).saturating_mul(DOCUMENT_RATIO).clamp(MAX_MEMBER, MAX_DOCUMENT)
+}
+/// Most version snapshots kept on save and read on open.
+pub const MAX_VERSIONS: usize = 100;
+/// Maximum version and branch name lengths, in Unicode scalar values.
+pub const MAX_VERSION_NAME: usize = 200;
+pub const MAX_VERSION_DESCRIPTION: usize = 2000;
+/// Maximum bytes of an index and all version snapshots read.
+pub const MAX_VERSION_INDEX: u64 = 16 * 1024 * 1024;
+pub const MAX_VERSION_BYTES: u64 = 1024 * 1024 * 1024;
+/// Maximum images read and maximum combined image bytes.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct ImageBudget {
+    pub images: usize,
+    pub bytes: u64,
+}
+pub const IMAGE_BUDGET: ImageBudget = ImageBudget { images: 20_000, bytes: 4 * 1024 * 1024 * 1024 };
+/// Maximum branch histories kept.
+pub const MAX_BRANCHES: usize = 100;
+/// The branch index member.
+pub const BRANCH_INDEX: &str = "branches/index.json";
+/// Maximum uncompressed bytes read from one native archive in total.
+#[cfg(not(target_pointer_width = "32"))]
+pub const MAX_UNPACKED: u64 = 6 * 1024 * 1024 * 1024;
+#[cfg(target_pointer_width = "32")]
+pub const MAX_UNPACKED: u64 = 2 * 1024 * 1024 * 1024;
+
+/// Native-format errors shared with the consumer's document mapping.
+#[derive(Debug, PartialEq, Eq)]
+pub enum FormatError {
+    Io(String),
+    Corrupt(String),
+    Newer(u32),
+}
+
+impl std::fmt::Display for FormatError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Io(e) => write!(f, "{e}"),
+            Self::Corrupt(e) => write!(f, "not a valid FigCraft file: {e}"),
+            Self::Newer(v) => write!(f, "this file was saved by a newer FigCraft (format version {v})"),
+        }
+    }
+}
+
+impl std::error::Error for FormatError {}
+
+/// Tracks the total bytes unpacked from one native archive across its document, images, library,
+/// history, and branch members.
+#[derive(Clone, Debug)]
+pub struct ReadBudget {
+    left: u64,
+    total: u64,
+}
+
+impl ReadBudget {
+    pub fn new(total: u64) -> Self {
+        Self { left: total, total }
+    }
+
+    fn passed(&self) -> String {
+        match self.total / (1024 * 1024) {
+            0 => format!("too large: the file's contents together pass {} bytes", self.total),
+            mb => format!("too large: the file's contents together pass {mb} MB"),
+        }
+    }
+
+    /// Whether the member's declared uncompressed size exceeds what remains in this budget.
+    pub fn exceeds_remaining(&self, archive: &mut impl NativeArchive, name: &str) -> bool {
+        archive.declared_size(name).is_some_and(|size| size > self.left)
+    }
+
+    /// Human-readable reason for leaving out a member after the archive-wide limit is spent.
+    pub fn exhausted_message(&self) -> String {
+        self.passed()
+    }
+
+    /// Read one native member within its own size limit and the remaining archive-wide budget.
+    /// A failed read that consumed a member is charged at its declared size.
+    pub fn read(&mut self, archive: &mut impl NativeArchive, name: &str, limit: u64) -> Result<Vec<u8>, FormatError> {
+        let declared = archive.declared_size(name);
+        if declared.is_some_and(|size| size > self.left && size <= limit) {
+            return Err(FormatError::Corrupt(format!("{name}: {}", self.passed())));
+        }
+        let cap = limit.min(self.left);
+        let size = declared.unwrap_or(0);
+        let result = match archive.read_member(name, cap) {
+            Ok(Some(bytes)) => Ok(bytes),
+            Ok(None) => Err(FormatError::Corrupt(format!("{name}: not found"))),
+            Err(error) if error.is_limit() => Err(FormatError::Corrupt(format!("{name} is too large"))),
+            Err(error) => Err(FormatError::Corrupt(format!("{name}: {error}"))),
+        };
+        if size <= cap {
+            self.left = self.left.saturating_sub(result.as_ref().map_or(size, |bytes| bytes.len() as u64));
+        }
+        result
+    }
+}
+
+/// Whether `id` can name a version or branch: 1–64 ASCII letters, digits, `-` and `_`.
+pub fn is_valid_version_id(id: &str) -> bool {
+    (1..=64).contains(&id.len()) && id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
+}
+
+/// Clip text to at most `max` Unicode scalar values.
+pub fn clip(s: &str, max: usize) -> String {
+    s.chars().take(max).collect()
+}
diff --git a/crates/figcraft-format/src/library.rs b/crates/figcraft-format/src/library.rs
new file mode 100644
index 000000000..7cf6b5b2c
--- /dev/null
+++ b/crates/figcraft-format/src/library.rs
@@ -0,0 +1,205 @@
+//! Wire schema and member limits for published libraries embedded in a native project archive.
+use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, BTreeSet};
+
+pub const MANIFEST: &str = "library/manifest.json";
+pub const DOCUMENT: &str = "library/document.json";
+pub const IMAGES_PREFIX: &str = "library/images/";
+pub const MAX_MANIFEST_BYTES: u64 = 16 * 1024 * 1024;
+pub const MAX_IMAGE_BYTES: u64 = 1024 * 1024 * 1024;
+pub const MAX_ID_CHARS: usize = 64;
+pub const MAX_NAME_CHARS: usize = 200;
+pub const MAX_DESCRIPTION_CHARS: usize = 2000;
+
+/// Native library manifest, independent of the consumer's document model.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct Manifest {
+    pub id: String,
+    pub name: String,
+    pub version: u64,
+    pub description: String,
+    pub time: u64,
+    pub components: Vec<Component>,
+    pub styles: Vec<Style>,
+    pub collections: Vec<Collection>,
+    pub variables: Vec<Variable>,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct Component {
+    pub id: u64,
+    #[serde(default)]
+    pub name: String,
+    #[serde(default)]
+    pub set: bool,
+    #[serde(default)]
+    pub version: u64,
+    #[serde(default)]
+    pub published: bool,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct Style {
+    pub id: String,
+    pub name: String,
+    #[serde(rename = "type")]
+    pub kind: String,
+    pub version: u64,
+    pub published: bool,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct Collection {
+    pub id: String,
+    pub name: String,
+    pub version: u64,
+    pub published: bool,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct Variable {
+    pub id: String,
+    pub name: String,
+    pub collection: String,
+    #[serde(rename = "type")]
+    pub kind: String,
+    pub version: u64,
+    pub published: bool,
+}
+
+/// Decode the native published-library manifest.
+pub fn read_manifest(bytes: &[u8]) -> Result<Manifest, serde_json::Error> {
+    serde_json::from_slice(bytes)
+}
+
+/// Encode the native published-library manifest.
+pub fn write_manifest(manifest: &Manifest) -> Result<Vec<u8>, serde_json::Error> {
+    serde_json::to_vec(manifest)
+}
+
+/// Whether `id` is a valid stable library id in the native manifest.
+pub fn is_valid_id(id: &str) -> bool {
+    (1..=MAX_ID_CHARS).contains(&id.len()) && id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
+}
+
+/// Clip a library display string to its native-format scalar-value limit.
+pub fn clip_display(s: &str, max_chars: usize) -> String {
+    s.chars().take(max_chars).collect()
+}
+
+/// Write the complete published-library member group into a native archive. The consumer maps
+/// its document to the neutral manifest and image index; path layout, compression, and shared
+/// image reuse stay here.
+pub fn write_members<'a, D: Serialize>(
+    writer: &mut super::ArchiveWriter,
+    manifest: &Manifest,
+    document: &D,
+    image_index: &[super::ImageIndexEntry],
+    already_written: &BTreeSet<String>,
+    images: impl IntoIterator<Item = (&'a str, &'a [u8])>,
+) -> Result<(), super::ArchiveWriteError> {
+    let manifest_bytes = write_manifest(manifest)?;
+    writer.add(MANIFEST, &manifest_bytes, super::Compression::Level(3))?;
+    writer.add_document_json(DOCUMENT, document, image_index)?;
+    for (hash, bytes) in images {
+        if already_written.contains(hash) || !valid_image_key(hash) {
+            continue;
+        }
+        writer.add(&format!("{IMAGES_PREFIX}{hash}"), bytes, super::Compression::Stored)?;
+    }
+    Ok(())
+}
+
+/// Read only published-library image resources selected by the consumer's document model.
+/// Missing and oversized images are omitted, leaving the consumer to render its established
+/// placeholder. The shared layer handles path choice, safe member names, and byte accounting.
+pub fn read_image_resources(
+    archive: &mut impl super::NativeArchive,
+    hashes: impl IntoIterator<Item = String>,
+    already_available: &BTreeSet<String>,
+    unpacked: &mut super::ReadBudget,
+) -> BTreeMap<String, Vec<u8>> {
+    let mut remaining = MAX_IMAGE_BYTES;
+    let mut images = BTreeMap::new();
+    for hash in hashes {
+        if already_available.contains(&hash) || !valid_image_key(&hash) {
+            continue;
+        }
+        let preferred = format!("{IMAGES_PREFIX}{hash}");
+        let fallback = format!("images/{hash}");
+        let Some(name) = [preferred, fallback].into_iter().find(|name| archive.contains(name)) else { continue };
+        let Ok(bytes) = unpacked.read(archive, &name, remaining.min(super::MAX_MEMBER)) else { continue };
+        remaining = remaining.saturating_sub(bytes.len() as u64);
+        images.insert(hash, bytes);
+    }
+    images
+}
+
+fn valid_image_key(key: &str) -> bool {
+    (1..=128).contains(&key.len()) && key.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn manifest_wire_names_defaults_and_round_trip_match_native_contract() {
+        let json = r#"{"id":"lib-1","components":[{"id":12,"set":true}],"styles":[{"id":"s","type":"paint"}],"collections":[{"id":"c"}],"variables":[{"id":"v","collection":"c","type":"color"}]}"#;
+        let manifest = read_manifest(json.as_bytes()).unwrap();
+        assert_eq!(manifest.components[0].id, 12);
+        assert_eq!(manifest.styles[0].kind, "paint");
+        assert_eq!(manifest.variables[0].kind, "color");
+        let encoded: serde_json::Value = serde_json::from_slice(&write_manifest(&manifest).unwrap()).unwrap();
+        assert_eq!(encoded["styles"][0]["type"], "paint");
+        assert!(encoded["styles"][0].get("kind").is_none());
+        assert_eq!(encoded["variables"][0]["type"], "color");
+    }
+
+    #[test]
+    fn library_id_and_display_limits_are_format_level() {
+        assert!(is_valid_id(&"a".repeat(MAX_ID_CHARS)));
+        assert!(!is_valid_id(&"a".repeat(MAX_ID_CHARS + 1)));
+        assert!(!is_valid_id("../bad"));
+        assert_eq!(clip_display("aé🙂b", 2), "aé");
+    }
+
+    #[test]
+    fn library_member_writer_and_reader_own_resource_layout_and_budgets() {
+        let mut writer = super::super::ArchiveWriter::new();
+        let manifest = Manifest { id: "library-1".into(), ..Manifest::default() };
+        let already_written = BTreeSet::from(["existing".to_string()]);
+        write_members(
+            &mut writer,
+            &manifest,
+            &serde_json::json!({"name":"library snapshot"}),
+            &[],
+            &already_written,
+            [("stored", &b"library bytes"[..]), ("existing", &b"duplicate"[..]), ("../bad", &b"hostile"[..])],
+        )
+        .unwrap();
+        writer.add("images/fallback", b"fallback bytes", super::super::Compression::Stored).unwrap();
+        let bytes = writer.finish().unwrap();
+        let mut archive = super::super::Archive::open(&bytes, super::super::ArchiveLimits { max_entries: 8, max_total_bytes: 1024 }).unwrap();
+        assert!(archive.contains(MANIFEST));
+        assert!(archive.contains(DOCUMENT));
+        let manifest_bytes = archive.read(MANIFEST, MAX_MANIFEST_BYTES).unwrap().unwrap();
+        assert_eq!(read_manifest(&manifest_bytes).unwrap(), manifest);
+        assert!(archive.contains("library/images/stored"));
+        assert!(!archive.contains("library/images/existing"));
+        assert!(!archive.contains("library/images/../bad"));
+
+        let available = BTreeSet::from(["existing".to_string()]);
+        let mut budget = super::super::ReadBudget::new(1024);
+        let images =
+            read_image_resources(&mut archive, ["stored".into(), "existing".into(), "fallback".into(), "../bad".into()], &available, &mut budget);
+        assert_eq!(images["stored"], b"library bytes");
+        assert_eq!(images["fallback"], b"fallback bytes");
+        assert!(!images.contains_key("existing"));
+        assert!(!images.contains_key("../bad"));
+    }
+}
diff --git a/crates/file-import/Cargo.toml b/crates/file-import/Cargo.toml
new file mode 100644
index 000000000..011943521
--- /dev/null
+++ b/crates/file-import/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "craft-file-import"
+description = "Shared format registry and bounded neutral scene import dispatch"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+craft-file-formats = { workspace = true }
+craft-raster-codecs = { workspace = true }
+craft-svg = { workspace = true }
+craft-dxf = { workspace = true }
+craft-pdf = { workspace = true, features = ["paths", "write"] }
+craft-eps = { workspace = true, features = ["paths"] }
+kurbo = { workspace = true }
+thiserror = { workspace = true }
+vectorcraft-geom = { workspace = true }
+
+[lints]
+workspace = true
diff --git a/crates/file-import/src/lib.rs b/crates/file-import/src/lib.rs
new file mode 100644
index 000000000..195363da0
--- /dev/null
+++ b/crates/file-import/src/lib.rs
@@ -0,0 +1,405 @@
+//! Shared format selection and bounded decoding into neutral vector scenes or raster pixels.
+//!
+//! Applications own only the mapping from these generic results into their document models and
+//! product-specific placement options. Format detection, supported import capabilities, reader
+//! selection, unit normalization, and raster codec dispatch live here.
+
+use kurbo::{Affine, BezPath, PathEl, Point};
+
+pub mod write;
+pub use craft_file_formats::Format as DetectedFormat;
+
+/// The maximum encoded input accepted by the import facade.
+pub const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024;
+pub const MAX_SHAPES: usize = 200_000;
+const MM_PER_PT: f64 = 25.4 / 72.0;
+
+/// A product-neutral input family supported by this reader registry.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ImportFormat {
+    Svg,
+    Svgz,
+    Dxf,
+    Pdf,
+    Eps,
+    Raster,
+}
+
+/// Reader and writer capabilities for one family in the shared registry.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Capability {
+    pub format: ImportFormat,
+    pub detected_formats: &'static [craft_file_formats::Format],
+    pub extensions: &'static [&'static str],
+    pub write_extensions: &'static [&'static str],
+    pub mime_types: &'static [&'static str],
+    pub raster: bool,
+    pub vector: bool,
+}
+
+/// Format, reader and writer support for callers that build dialogs or query capabilities.
+pub const CAPABILITIES: &[Capability] = &[
+    Capability {
+        format: ImportFormat::Svg,
+        detected_formats: &[craft_file_formats::Format::Svg],
+        extensions: &["svg"],
+        write_extensions: &["svg"],
+        mime_types: &["image/svg+xml"],
+        raster: false,
+        vector: true,
+    },
+    Capability {
+        format: ImportFormat::Svgz,
+        detected_formats: &[craft_file_formats::Format::Svgz],
+        extensions: &["svgz"],
+        write_extensions: &["svgz"],
+        mime_types: &["image/svg+xml"],
+        raster: false,
+        vector: true,
+    },
+    Capability {
+        format: ImportFormat::Dxf,
+        detected_formats: &[craft_file_formats::Format::Dxf],
+        extensions: &["dxf"],
+        write_extensions: &["dxf"],
+        mime_types: &["image/vnd.dxf", "application/dxf"],
+        raster: false,
+        vector: true,
+    },
+    Capability {
+        format: ImportFormat::Pdf,
+        detected_formats: &[craft_file_formats::Format::Pdf],
+        extensions: &["pdf"],
+        write_extensions: &["pdf"],
+        mime_types: &["application/pdf"],
+        raster: false,
+        vector: true,
+    },
+    Capability {
+        format: ImportFormat::Eps,
+        detected_formats: &[craft_file_formats::Format::Eps, craft_file_formats::Format::PostScript, craft_file_formats::Format::Illustrator],
+        extensions: &["eps", "ps", "ai"],
+        write_extensions: &[],
+        mime_types: &["application/postscript"],
+        raster: false,
+        vector: true,
+    },
+    Capability {
+        format: ImportFormat::Raster,
+        detected_formats: &[
+            craft_file_formats::Format::Png,
+            craft_file_formats::Format::Jpeg,
+            craft_file_formats::Format::Bmp,
+            craft_file_formats::Format::Gif,
+            craft_file_formats::Format::Tiff,
+            craft_file_formats::Format::WebP,
+        ],
+        extensions: &["png", "jpg", "jpeg", "bmp", "gif", "tif", "tiff", "webp"],
+        write_extensions: &["png", "jpg", "jpeg"],
+        mime_types: &["image/png", "image/jpeg", "image/bmp", "image/gif", "image/tiff", "image/webp"],
+        raster: true,
+        vector: false,
+    },
+];
+
+/// A vector path with generic source metadata. `tag` and `layer` are source labels; applications
+/// may interpret their own conventions while the geometry and parsing stay shared.
+#[derive(Debug, Clone, PartialEq)]
+pub struct SceneShape {
+    pub path: BezPath,
+    pub tag: Option<String>,
+    pub class: Option<String>,
+    pub stroke: Option<String>,
+    /// Parsed RGB stroke color when the source stroke is a concrete CSS color.
+    pub stroke_rgb: Option<[u8; 3]>,
+    pub layer: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct VectorScene {
+    pub format: ImportFormat,
+    pub width_mm: f64,
+    pub height_mm: f64,
+    pub shapes: Vec<SceneShape>,
+    pub warnings: Vec<String>,
+    /// Additional warnings omitted by the SVG reader's bounded warning collection.
+    pub dropped_warnings: usize,
+}
+
+#[derive(Debug, Clone)]
+pub struct RasterImage {
+    pub format: ImportFormat,
+    pub width: u32,
+    pub height: u32,
+    /// Straight-alpha RGBA pixels, row-major.
+    pub rgba: Vec<u8>,
+}
+
+#[derive(Debug, Clone)]
+pub enum Imported {
+    Vector(VectorScene),
+    Raster(RasterImage),
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct Limits {
+    pub max_input_bytes: usize,
+    pub max_shapes: usize,
+    pub max_raster_width: u32,
+    pub max_raster_height: u32,
+    pub max_raster_pixels: u64,
+    pub max_raster_alloc_bytes: u64,
+}
+
+impl Default for Limits {
+    fn default() -> Self {
+        Self {
+            max_input_bytes: MAX_INPUT_BYTES,
+            max_shapes: MAX_SHAPES,
+            max_raster_width: 10_000,
+            max_raster_height: 10_000,
+            max_raster_pixels: 16_000_000,
+            max_raster_alloc_bytes: 256 * 1024 * 1024,
+        }
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error("unrecognized or unsupported import format")]
+    Unsupported,
+    #[error("input is {size} bytes; limit is {limit}")]
+    InputLimit { size: usize, limit: usize },
+    #[error("{0}")]
+    Decode(String),
+    #[error("import produced invalid or non-finite geometry")]
+    InvalidGeometry,
+    #[error("import exceeds the configured shape limit")]
+    ShapeLimit,
+    #[error("format writer failed: {0}")]
+    Write(String),
+}
+
+impl From<craft_pdf::write::WriteError> for Error {
+    fn from(error: craft_pdf::write::WriteError) -> Self {
+        Self::Write(error.to_string())
+    }
+}
+
+/// Resolve detected file kinds to this reader registry. Illustrator files with PDF content use
+/// the PDF path reader; PostScript-family files use the EPS/PostScript interpreter.
+pub fn format_for(name: &str, bytes: &[u8]) -> Option<ImportFormat> {
+    use craft_file_formats::Format as F;
+    match craft_file_formats::detect(name, bytes)? {
+        F::Svg => Some(ImportFormat::Svg),
+        F::Svgz => Some(ImportFormat::Svgz),
+        F::Dxf => Some(ImportFormat::Dxf),
+        F::Pdf => Some(ImportFormat::Pdf),
+        F::Illustrator if bytes.starts_with(b"%PDF-") => Some(ImportFormat::Pdf),
+        F::Eps | F::PostScript | F::Illustrator => Some(ImportFormat::Eps),
+        F::Png | F::Jpeg | F::Bmp | F::Gif | F::Tiff | F::WebP => Some(ImportFormat::Raster),
+        _ => None,
+    }
+}
+
+/// Return supported extensions in the same registry used by [`format_for`].
+pub fn supported_extensions() -> Vec<&'static str> {
+    CAPABILITIES.iter().flat_map(|capability| capability.extensions.iter().copied()).collect()
+}
+
+/// Raw detected kinds routed to one reader family, for app open-dialog and capability adapters.
+pub fn supported_formats(format: ImportFormat) -> &'static [craft_file_formats::Format] {
+    CAPABILITIES.iter().find(|capability| capability.format == format).map_or(&[], |capability| capability.detected_formats)
+}
+
+/// Whether the registry has a writer for an extension.
+pub fn supports_write_extension(extension: &str) -> bool {
+    let extension = extension.trim_start_matches('.');
+    CAPABILITIES.iter().any(|capability| capability.write_extensions.iter().any(|candidate| candidate.eq_ignore_ascii_case(extension)))
+}
+
+/// Whether a family has at least one output writer in the shared registry.
+pub fn supports_writer(format: ImportFormat) -> bool {
+    CAPABILITIES.iter().find(|capability| capability.format == format).is_some_and(|capability| !capability.write_extensions.is_empty())
+}
+
+/// Detect, select a reader, and decode the input into a neutral vector scene or RGBA image.
+pub fn import(name: &str, bytes: &[u8], limits: Limits) -> Result<Imported, Error> {
+    if bytes.len() > limits.max_input_bytes {
+        return Err(Error::InputLimit { size: bytes.len(), limit: limits.max_input_bytes });
+    }
+    let format = format_for(name, bytes).ok_or(Error::Unsupported)?;
+    let imported = match format {
+        ImportFormat::Svg | ImportFormat::Svgz => import_svg(name, bytes, format, limits),
+        ImportFormat::Dxf => import_dxf(bytes, format, limits),
+        ImportFormat::Pdf => import_pdf(bytes, format, limits),
+        ImportFormat::Eps => import_eps(bytes, format, limits),
+        ImportFormat::Raster => import_raster(bytes, format, limits),
+    }?;
+    if let Imported::Vector(scene) = &imported
+        && (!(scene.width_mm.is_finite() && scene.height_mm.is_finite() && scene.width_mm > 0.0 && scene.height_mm > 0.0)
+            || scene.shapes.iter().any(|shape| !path_is_finite(&shape.path)))
+    {
+        return Err(Error::InvalidGeometry);
+    }
+    Ok(imported)
+}
+
+#[derive(Debug, Clone, Default)]
+struct SvgTag {
+    data_kind: Option<String>,
+    class: Option<String>,
+}
+
+impl craft_svg::paths::Kind for SvgTag {
+    const PROPERTIES: &'static [&'static str] = &["data-kind"];
+
+    fn of(style: &craft_svg::paths::StyleMap, class: &str) -> Option<Self> {
+        let data_kind = style.get("data-kind").cloned();
+        let class = (!class.is_empty()).then(|| class.to_owned());
+        (data_kind.is_some() || class.is_some()).then_some(Self { data_kind, class })
+    }
+}
+
+fn import_svg(name: &str, bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
+    let text = craft_svg::svgz::text(bytes, limits.max_input_bytes).map_err(|error| Error::Decode(error.to_string()))?;
+    let imported = craft_svg::paths::import::<SvgTag>(&text, name).map_err(|error| Error::Decode(error.to_string()))?;
+    if imported.shapes.len() > limits.max_shapes {
+        return Err(Error::ShapeLimit);
+    }
+    let mut shapes = Vec::with_capacity(imported.shapes.len());
+    for shape in &imported.shapes {
+        let path = imported.clipped_path(shape).map_err(|error| Error::Decode(error.to_string()))?;
+        shapes.push(SceneShape {
+            path,
+            tag: shape.kind.data_kind.clone(),
+            class: shape.kind.class.clone(),
+            stroke: shape.stroke.clone(),
+            stroke_rgb: shape.stroke.as_deref().and_then(|value| craft_svg::color::parse_color(value).ok()).map(|color| [color.r, color.g, color.b]),
+            layer: shape.layer.clone(),
+        });
+    }
+    Ok(Imported::Vector(VectorScene {
+        format,
+        width_mm: imported.width_mm,
+        height_mm: imported.height_mm,
+        shapes,
+        warnings: imported.warnings,
+        dropped_warnings: imported.dropped_warnings,
+    }))
+}
+
+fn import_dxf(bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
+    let imported = craft_dxf::paths::import(bytes).map_err(|error| Error::Decode(error.to_string()))?;
+    if imported.paths.len() > limits.max_shapes {
+        return Err(Error::ShapeLimit);
+    }
+    let (width_mm, height_mm, transform) = match imported.bounds {
+        Some(bounds) => (
+            (bounds.width() * imported.unit_to_mm).max(1.0),
+            (bounds.height() * imported.unit_to_mm).max(1.0),
+            Affine::new([imported.unit_to_mm, 0.0, 0.0, -imported.unit_to_mm, -bounds.x0 * imported.unit_to_mm, bounds.y1 * imported.unit_to_mm]),
+        ),
+        None => (100.0, 150.0, Affine::IDENTITY),
+    };
+    let shapes = imported
+        .paths
+        .into_iter()
+        .map(|path| SceneShape { path: transform * path, tag: None, class: None, stroke: None, stroke_rgb: None, layer: None })
+        .collect();
+    Ok(Imported::Vector(VectorScene { format, width_mm, height_mm, shapes, warnings: imported.warnings, dropped_warnings: 0 }))
+}
+
+fn import_pdf(bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
+    let imported = craft_pdf::paths::import_page(
+        bytes,
+        0,
+        craft_pdf::paths::Limits { max_input_bytes: limits.max_input_bytes, max_paths: limits.max_shapes, ..Default::default() },
+    )
+    .map_err(|error| Error::Decode(error.to_string()))?;
+    let page = imported.pages.into_iter().next().ok_or_else(|| Error::Decode("PDF has no pages".into()))?;
+    let bounds = page.crop_box;
+    let mut warnings = imported.warnings;
+    if page.omitted_text > 0 || page.omitted_images > 0 {
+        warnings.push(format!("PDF omitted {} text and {} image items", page.omitted_text, page.omitted_images));
+    }
+    let shapes = page
+        .paths
+        .into_iter()
+        .map(|path| SceneShape { path: Affine::scale(MM_PER_PT) * path, tag: None, class: None, stroke: None, stroke_rgb: None, layer: None })
+        .collect();
+    Ok(Imported::Vector(VectorScene {
+        format,
+        width_mm: bounds.width() * MM_PER_PT,
+        height_mm: bounds.height() * MM_PER_PT,
+        shapes,
+        warnings,
+        dropped_warnings: 0,
+    }))
+}
+
+fn import_eps(bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
+    let imported = craft_eps::paths::import(
+        bytes,
+        craft_eps::paths::Limits { max_input_bytes: limits.max_input_bytes, max_paths: limits.max_shapes, ..Default::default() },
+    )
+    .map_err(|error| Error::Decode(error.to_string()))?;
+    let bounds = imported.page_bounds;
+    let transform = Affine::scale(MM_PER_PT);
+    let mut warnings = imported.warnings;
+    if imported.preview_fallback {
+        warnings.push("embedded raster preview was not imported as paths".into());
+    }
+    let shapes = imported
+        .paths
+        .into_iter()
+        .map(|path| SceneShape { path: transform * path, tag: None, class: None, stroke: None, stroke_rgb: None, layer: None })
+        .collect();
+    Ok(Imported::Vector(VectorScene {
+        format,
+        width_mm: (bounds.width() * MM_PER_PT).max(1.0),
+        height_mm: (bounds.height() * MM_PER_PT).max(1.0),
+        shapes,
+        warnings,
+        dropped_warnings: 0,
+    }))
+}
+
+fn import_raster(bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
+    let rgba = craft_raster_codecs::common::decode_rgba(
+        bytes,
+        craft_raster_codecs::common::DecodeLimits {
+            max_file_bytes: limits.max_input_bytes,
+            max_width: limits.max_raster_width,
+            max_height: limits.max_raster_height,
+            max_pixels: limits.max_raster_pixels,
+            max_alloc_bytes: limits.max_raster_alloc_bytes,
+        },
+    )
+    .map_err(|error| Error::Decode(error.to_string()))?;
+    let (width, height) = rgba.dimensions();
+    Ok(Imported::Raster(RasterImage { format, width, height, rgba: rgba.into_raw() }))
+}
+
+fn path_is_finite(path: &BezPath) -> bool {
+    path.elements().iter().all(|element| {
+        let finite = |point: Point| point.x.is_finite() && point.y.is_finite();
+        match *element {
+            PathEl::MoveTo(point) | PathEl::LineTo(point) => finite(point),
+            PathEl::QuadTo(a, b) => finite(a) && finite(b),
+            PathEl::CurveTo(a, b, c) => finite(a) && finite(b) && finite(c),
+            PathEl::ClosePath => true,
+        }
+    })
+}
+
+#[cfg(test)]
+mod format_tests {
+    use super::*;
+
+    #[test]
+    fn pdf_based_illustrator_is_routed_to_pdf_reader() {
+        let bytes = b"%PDF-1.7\n/AIPrivateData";
+        assert_eq!(format_for("illustration.ai", bytes), Some(ImportFormat::Pdf));
+    }
+}
diff --git a/crates/file-import/src/write.rs b/crates/file-import/src/write.rs
new file mode 100644
index 000000000..676206282
--- /dev/null
+++ b/crates/file-import/src/write.rs
@@ -0,0 +1,447 @@
+//! Shared writer selection and serialization for neutral scenes and pixels.
+
+use kurbo::{BezPath, PathEl, Point};
+
+use crate::{CAPABILITIES, Error, ImportFormat};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WriteFormat {
+    Svg,
+    Svgz,
+    Dxf,
+    Pdf,
+    Png,
+    Jpeg,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct OutputLayer {
+    /// Product-facing name. SVG stores it as `data-layer`.
+    pub name: String,
+    /// Already mapped/sanitized format name, supplied by the application adapter.
+    pub dxf_name: String,
+    pub visible: bool,
+    pub dxf_color_index: u8,
+    pub class: Option<String>,
+    pub data_kind: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct OutputPath {
+    pub path: BezPath,
+    pub layer: usize,
+    pub color_rgb: [u8; 3],
+    pub stroke_width_mm: f64,
+    pub class: Option<String>,
+    pub data_kind: Option<String>,
+    /// Close each open contour for formats that require closed cutting operations.
+    pub close_open_contours: bool,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct OutputScene {
+    pub width_mm: f64,
+    pub height_mm: f64,
+    pub view_box: [f64; 4],
+    pub layers: Vec<OutputLayer>,
+    pub paths: Vec<OutputPath>,
+}
+
+/// One page for the shared PDF path writer. Coordinates and stroke widths are millimetres.
+#[derive(Debug, Clone, PartialEq)]
+pub struct PdfPage {
+    pub width_mm: f64,
+    pub height_mm: f64,
+    pub view_box: [f64; 4],
+    pub paths: Vec<PdfPath>,
+}
+
+/// A PDF path with either a fill or a stroke. `None` fills the path; `Some(width)` strokes it.
+#[derive(Debug, Clone, PartialEq)]
+pub struct PdfPath {
+    pub path: BezPath,
+    pub color_rgb: [u8; 3],
+    pub stroke_width_mm: Option<f64>,
+}
+
+/// Match a target extension to the centralized writer registry.
+pub fn writer_format_for_extension(extension: &str) -> Option<WriteFormat> {
+    let family = writer_family_for_extension(extension)?;
+    let extension = extension.trim_start_matches('.');
+    Some(match family {
+        ImportFormat::Svg => WriteFormat::Svg,
+        ImportFormat::Svgz => WriteFormat::Svgz,
+        ImportFormat::Dxf => WriteFormat::Dxf,
+        ImportFormat::Pdf => WriteFormat::Pdf,
+        ImportFormat::Raster if extension.eq_ignore_ascii_case("png") => WriteFormat::Png,
+        ImportFormat::Raster => WriteFormat::Jpeg,
+        ImportFormat::Eps => return None,
+    })
+}
+
+/// Product handler family for a writer extension.
+pub fn writer_family_for_extension(extension: &str) -> Option<ImportFormat> {
+    let extension = extension.trim_start_matches('.');
+    for capability in CAPABILITIES {
+        if !capability.write_extensions.iter().any(|candidate| candidate.eq_ignore_ascii_case(extension)) {
+            continue;
+        }
+        return Some(capability.format);
+    }
+    None
+}
+
+/// Vector extensions the writer registry supports.
+pub fn supported_vector_write_extensions() -> Vec<&'static str> {
+    CAPABILITIES.iter().filter(|capability| capability.vector).flat_map(|capability| capability.write_extensions.iter().copied()).collect()
+}
+
+/// Serialize a neutral vector scene as SVG, SVGZ, DXF, or PDF according to the extension.
+pub fn write_vector(extension: &str, scene: &OutputScene) -> Result<Vec<u8>, Error> {
+    match writer_format_for_extension(extension).ok_or_else(|| Error::Write(format!("no writer for .{extension}")))? {
+        WriteFormat::Svg => write_svg(scene).map(String::into_bytes),
+        WriteFormat::Svgz => write_svg(scene).map(|svg| craft_svg::svgz::compress(svg.as_bytes())),
+        WriteFormat::Dxf => write_dxf(scene).map(String::into_bytes),
+        WriteFormat::Pdf => write_pdf(scene),
+        WriteFormat::Png | WriteFormat::Jpeg => Err(Error::Write("raster output requires pixels".into())),
+    }
+}
+
+/// Encode an RGBA image using the writer selected by its extension.
+pub fn write_raster(extension: &str, width: u32, height: u32, rgba: &[u8], jpeg_quality: u8) -> Result<Vec<u8>, Error> {
+    let pixels = craft_raster_codecs::common::Pixels::from_raw(width, height, rgba.to_vec()).ok_or(Error::InvalidGeometry)?;
+    match writer_format_for_extension(extension).ok_or_else(|| Error::Write(format!("no writer for .{extension}")))? {
+        WriteFormat::Png => craft_raster_codecs::common::encode_png(&pixels).map_err(|error| Error::Write(error.to_string())),
+        WriteFormat::Jpeg => craft_raster_codecs::common::encode_jpeg(&pixels, jpeg_quality).map_err(|error| Error::Write(error.to_string())),
+        _ => Err(Error::Write("vector output requires paths".into())),
+    }
+}
+
+fn write_svg(scene: &OutputScene) -> Result<String, Error> {
+    validate_scene(scene)?;
+    let view_scale = (scene.width_mm / scene.view_box[2]).min(scene.height_mm / scene.view_box[3]);
+    if !(view_scale.is_finite() && view_scale > 0.0) {
+        return Err(Error::InvalidGeometry);
+    }
+    let paths_by_layer = paths_by_layer(scene);
+    let elements = scene
+        .layers
+        .iter()
+        .enumerate()
+        .map(|(layer_index, layer)| {
+            let paths = paths_by_layer[layer_index]
+                .iter()
+                .map(|path| {
+                    let color = path.color_rgb;
+                    let mut attributes = vec![
+                        craft_svg::write::Attribute::text("fill", "none"),
+                        craft_svg::write::Attribute::text("stroke", format!("#{:02x}{:02x}{:02x}", color[0], color[1], color[2])),
+                        craft_svg::write::Attribute::text("stroke-width", format_float(path.stroke_width_mm / view_scale)),
+                    ];
+                    if let Some(class) = &path.class {
+                        attributes.push(craft_svg::write::Attribute::text("class", class.clone()));
+                    }
+                    if let Some(data_kind) = &path.data_kind {
+                        attributes.push(craft_svg::write::Attribute::text("data-kind", data_kind.clone()));
+                    }
+                    craft_svg::write::Element::Path { attributes, path: path.path.clone() }
+                })
+                .collect::<Vec<_>>();
+            let mut attributes = vec![
+                craft_svg::write::Attribute::text("data-layer", layer.name.clone()),
+                craft_svg::write::Attribute::text("style", if layer.visible { "display:inline" } else { "display:none" }),
+            ];
+            if let Some(class) = &layer.class {
+                attributes.push(craft_svg::write::Attribute::text("class", class.clone()));
+            }
+            if let Some(data_kind) = &layer.data_kind {
+                attributes.push(craft_svg::write::Attribute::text("data-kind", data_kind.clone()));
+            }
+            craft_svg::write::Element::Group { attributes, children: paths }
+        })
+        .collect();
+    Ok(craft_svg::write::Scene { width_mm: scene.width_mm, height_mm: scene.height_mm, view_box: scene.view_box, elements }.write())
+}
+
+fn write_pdf(scene: &OutputScene) -> Result<Vec<u8>, Error> {
+    validate_scene(scene)?;
+    let paths_by_layer = paths_by_layer(scene);
+    // Match SVG's painter order: layers in order, then paths in source order within each layer.
+    let paths = scene
+        .layers
+        .iter()
+        .enumerate()
+        .filter(|(_, layer)| layer.visible)
+        .flat_map(|(layer_index, _)| paths_by_layer[layer_index].iter().copied())
+        .map(|path| PdfPath { path: path.path.clone(), color_rgb: path.color_rgb, stroke_width_mm: Some(path.stroke_width_mm) })
+        .collect();
+    write_pdf_pages(&[PdfPage { width_mm: scene.width_mm, height_mm: scene.height_mm, view_box: scene.view_box, paths }])
+}
+
+/// Group the neutral paths once so writing does not rescan all paths for every layer.
+fn paths_by_layer(scene: &OutputScene) -> Vec<Vec<&OutputPath>> {
+    let mut grouped: Vec<Vec<&OutputPath>> = (0..scene.layers.len()).map(|_| Vec::new()).collect();
+    for path in &scene.paths {
+        if let Some(layer) = grouped.get_mut(path.layer) {
+            layer.push(path);
+        }
+    }
+    grouped
+}
+
+/// Encode a neutral list of laid-out pages with vector paths as PDF.
+pub fn write_pdf_pages(pages: &[PdfPage]) -> Result<Vec<u8>, Error> {
+    use craft_pdf::write::{Metadata, Writer, backend};
+    const PT_PER_MM: f64 = 72.0 / 25.4;
+    craft_pdf::write::guard(|| {
+        let settings = backend::SerializeSettings {
+            configuration: craft_pdf::write::configuration(backend::configure::PdfVersion::Pdf14, None)?,
+            ..Default::default()
+        };
+        let mut writer = Writer::new(settings, Metadata::default());
+        for source_page in pages {
+            let [view_x, view_y, view_width, view_height] = source_page.view_box;
+            if !(source_page.width_mm.is_finite()
+                && source_page.height_mm.is_finite()
+                && source_page.width_mm > 0.0
+                && source_page.height_mm > 0.0
+                && view_x.is_finite()
+                && view_y.is_finite()
+                && view_width.is_finite()
+                && view_height.is_finite()
+                && view_width > 0.0
+                && view_height > 0.0)
+            {
+                return Err(Error::InvalidGeometry);
+            }
+            let width = source_page.width_mm * PT_PER_MM;
+            let height = source_page.height_mm * PT_PER_MM;
+            if !(width.is_finite()
+                && height.is_finite()
+                && width > 0.0
+                && height > 0.0
+                && width <= f64::from(f32::MAX)
+                && height <= f64::from(f32::MAX))
+            {
+                return Err(Error::Write("page dimensions are outside the PDF range".into()));
+            }
+            let page_settings = backend::page::PageSettings::from_wh(width as f32, height as f32)
+                .ok_or_else(|| Error::Write("page dimensions are not finite or positive".into()))?;
+            let mut page = writer.document_mut().start_page_with(page_settings);
+            let mut surface = page.surface();
+            let view_scale = (source_page.width_mm / view_width).min(source_page.height_mm / view_height);
+            let offset_x = (source_page.width_mm - view_width * view_scale) / 2.0;
+            let offset_y = (source_page.height_mm - view_height * view_scale) / 2.0;
+            if !(view_scale.is_finite() && view_scale > 0.0 && offset_x.is_finite() && offset_y.is_finite()) {
+                return Err(Error::InvalidGeometry);
+            }
+            for source in &source_page.paths {
+                let mut path = backend::geom::PathBuilder::new();
+                for element in source.path.elements() {
+                    let point = |p: Point| -> Result<(f32, f32), Error> {
+                        let x = ((p.x - view_x) * view_scale + offset_x) * PT_PER_MM;
+                        let y = ((p.y - view_y) * view_scale + offset_y) * PT_PER_MM;
+                        if !(p.x.is_finite()
+                            && p.y.is_finite()
+                            && x.is_finite()
+                            && y.is_finite()
+                            && x.abs() <= f64::from(f32::MAX)
+                            && y.abs() <= f64::from(f32::MAX))
+                        {
+                            return Err(Error::Write("path coordinate is outside the PDF range".into()));
+                        }
+                        Ok((x as f32, y as f32))
+                    };
+                    match *element {
+                        PathEl::MoveTo(p) => {
+                            let (x, y) = point(p)?;
+                            path.move_to(x, y);
+                        }
+                        PathEl::LineTo(p) => {
+                            let (x, y) = point(p)?;
+                            path.line_to(x, y);
+                        }
+                        PathEl::QuadTo(a, b) => {
+                            let (x1, y1) = point(a)?;
+                            let (x, y) = point(b)?;
+                            path.quad_to(x1, y1, x, y);
+                        }
+                        PathEl::CurveTo(a, b, c) => {
+                            let (x1, y1) = point(a)?;
+                            let (x2, y2) = point(b)?;
+                            let (x, y) = point(c)?;
+                            path.cubic_to(x1, y1, x2, y2, x, y);
+                        }
+                        PathEl::ClosePath => path.close(),
+                    }
+                }
+                if let Some(path) = path.finish() {
+                    let color = backend::color::rgb::Color::new(source.color_rgb[0], source.color_rgb[1], source.color_rgb[2]);
+                    match source.stroke_width_mm {
+                        Some(width_mm) => {
+                            let width_pt = width_mm * PT_PER_MM;
+                            if !(width_mm.is_finite() && width_mm > 0.0 && width_pt.is_finite() && width_pt <= f64::from(f32::MAX)) {
+                                return Err(Error::Write("stroke width must be finite and positive".into()));
+                            }
+                            surface.set_fill(None);
+                            surface.set_stroke(Some(backend::paint::Stroke { paint: color.into(), width: width_pt as f32, ..Default::default() }));
+                        }
+                        None => {
+                            surface.set_stroke(None);
+                            surface.set_fill(Some(backend::paint::Fill { paint: color.into(), ..Default::default() }));
+                        }
+                    }
+                    surface.draw_path(&path);
+                }
+            }
+            surface.finish();
+            page.finish();
+        }
+        writer.finish().map_err(|error| Error::Write(error.to_string()))
+    })
+}
+
+fn write_dxf(scene: &OutputScene) -> Result<String, Error> {
+    validate_scene(scene)?;
+    let mut drawing = craft_dxf::model::write::Drawing::default();
+    drawing.format = craft_dxf::model::write::Format::R14;
+    drawing.insunits = 4;
+    drawing.metric = true;
+    drawing.extents = [0.0, 0.0, scene.width_mm, scene.height_mm];
+    drawing.limits = drawing.extents;
+    for layer in &scene.layers {
+        drawing.layers.push(craft_dxf::model::Layer {
+            handle: None,
+            name: layer.dxf_name.clone(),
+            color: craft_dxf::model::Color::Index(layer.dxf_color_index),
+            on: layer.visible,
+            frozen: false,
+            vp_freeze_new: false,
+            locked: false,
+            plot: true,
+            linetype: "Continuous".into(),
+            lineweight: craft_dxf::model::Lineweight::Default,
+            plot_style: None,
+            transparency: craft_dxf::model::Transparency::ByLayer,
+            description: None,
+        });
+    }
+    for output in &scene.paths {
+        let Some(layer) = scene.layers.get(output.layer) else {
+            return Err(Error::InvalidGeometry);
+        };
+        let view_scale = (scene.width_mm / scene.view_box[2]).min(scene.height_mm / scene.view_box[3]);
+        let offset_x = (scene.width_mm - scene.view_box[2] * view_scale) / 2.0;
+        let offset_y = (scene.height_mm - scene.view_box[3] * view_scale) / 2.0;
+        let mut page_path = output.path.clone();
+        page_path.apply_affine(kurbo::Affine::new([
+            view_scale,
+            0.0,
+            0.0,
+            view_scale,
+            offset_x - scene.view_box[0] * view_scale,
+            offset_y - scene.view_box[1] * view_scale,
+        ]));
+        for (points, closed) in flatten(&page_path)? {
+            if points.len() < 2 {
+                continue;
+            }
+            let mut vertices = Vec::with_capacity(points.len());
+            for point in points {
+                if !(point.x.is_finite() && point.y.is_finite()) {
+                    return Err(Error::InvalidGeometry);
+                }
+                vertices.push(craft_dxf::model::LwVertex { x: point.x, y: scene.height_mm - point.y, ..Default::default() });
+            }
+            drawing.entities.push(craft_dxf::model::Entity {
+                common: craft_dxf::model::Common {
+                    handle: None,
+                    owner: None,
+                    layer: layer.dxf_name.clone(),
+                    linetype: None,
+                    color: craft_dxf::model::Color::ByLayer,
+                    lineweight: craft_dxf::model::Lineweight::ByLayer,
+                    ltscale: 1.0,
+                    visible: true,
+                    paper_space: false,
+                    transparency: craft_dxf::model::Transparency::ByLayer,
+                    thickness: 0.0,
+                    extrusion: [0.0, 0.0, 1.0],
+                    plot_style: None,
+                },
+                kind: craft_dxf::model::EntityKind::LwPolyline(craft_dxf::model::LwPolyline {
+                    vertices,
+                    closed: closed || output.close_open_contours,
+                    plinegen: false,
+                    const_width: 0.0,
+                    elevation: 0.0,
+                }),
+            });
+        }
+    }
+    let (tags, skipped) = drawing.tags();
+    if skipped > 0 {
+        return Err(Error::Write(format!("DXF writer skipped {skipped} entities")));
+    }
+    Ok(craft_dxf::write_ascii(&tags))
+}
+
+fn flatten(path: &BezPath) -> Result<Vec<(Vec<Point>, bool)>, Error> {
+    const MAX_POINTS: usize = 2_000_000;
+    let mut contours: Vec<(Vec<Point>, bool)> = Vec::new();
+    let mut count = 0usize;
+    vectorcraft_geom::flatten(path.iter(), 0.05, |element| {
+        count = count.saturating_add(1);
+        if count > MAX_POINTS {
+            return;
+        }
+        match element {
+            PathEl::MoveTo(point) => contours.push((vec![point], false)),
+            PathEl::LineTo(point) => {
+                if let Some((points, _)) = contours.last_mut() {
+                    points.push(point);
+                }
+            }
+            PathEl::ClosePath => {
+                if let Some((_, closed)) = contours.last_mut() {
+                    *closed = true;
+                }
+            }
+            PathEl::QuadTo(..) | PathEl::CurveTo(..) => {}
+        }
+    });
+    if count > MAX_POINTS {
+        return Err(Error::Write("path exceeds the DXF flattening limit".into()));
+    }
+    Ok(contours)
+}
+
+fn validate_scene(scene: &OutputScene) -> Result<(), Error> {
+    if !(scene.width_mm.is_finite() && scene.height_mm.is_finite() && scene.width_mm > 0.0 && scene.height_mm > 0.0) {
+        return Err(Error::InvalidGeometry);
+    }
+    if !(scene.view_box.iter().all(|value| value.is_finite()) && scene.view_box[2] > 0.0 && scene.view_box[3] > 0.0)
+        || scene.paths.len() > crate::MAX_SHAPES
+        || scene.paths.iter().any(|path| {
+            path.layer >= scene.layers.len()
+                || !(path.stroke_width_mm.is_finite() && path.stroke_width_mm > 0.0)
+                || path.path.elements().iter().any(|element| match *element {
+                    PathEl::MoveTo(point) | PathEl::LineTo(point) => !point_is_finite(point),
+                    PathEl::QuadTo(a, b) => !point_is_finite(a) || !point_is_finite(b),
+                    PathEl::CurveTo(a, b, c) => !point_is_finite(a) || !point_is_finite(b) || !point_is_finite(c),
+                    PathEl::ClosePath => false,
+                })
+        })
+    {
+        return Err(Error::InvalidGeometry);
+    }
+    Ok(())
+}
+
+fn point_is_finite(point: Point) -> bool {
+    point.x.is_finite() && point.y.is_finite()
+}
+
+fn format_float(value: f64) -> String {
+    value.to_string()
+}
diff --git a/crates/gif/Cargo.toml b/crates/gif/Cargo.toml
index ac2b599d5..909d9b605 100644
--- a/crates/gif/Cargo.toml
+++ b/crates/gif/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "craft-gif"
-description = "GIF block reader: the logical screen, each frame's position, delay and transparency, the loop count and colour tables, without decompressing pixels."
+description = "GIF block reader, bounded frame decoder and animation writer."
 version.workspace = true
 edition.workspace = true
 license.workspace = true
@@ -15,8 +15,8 @@ workspace = true
 frames = ["dep:image"]
 
 [dependencies]
+gif = "0.14"
 image = { version = "0.25", default-features = false, features = ["gif"], optional = true }
 
 [dev-dependencies]
-# Writes the animated test files the scan is checked against; not a product dependency.
 image = { version = "0.25", default-features = false, features = ["gif"] }
diff --git a/crates/gif/src/frames.rs b/crates/gif/src/frames.rs
index fdaec81b7..12ae37dda 100644
--- a/crates/gif/src/frames.rs
+++ b/crates/gif/src/frames.rs
@@ -22,13 +22,18 @@ pub struct FrameLimits {
     pub max_bytes: u64,
     /// Largest canvas (logical screen) in bytes at 4 bytes a pixel. Default 512 MiB.
     pub max_canvas_bytes: u64,
+    /// Combined decoder working-allocation budget. The persistent canvas reserves budget before
+    /// the frame buffer. `None` uses twice `max_canvas_bytes`, matching the decoder's working
+    /// buffer allowance. Set this when an application has a tighter allocator budget. Default
+    /// `None`.
+    pub max_decode_bytes: Option<u64>,
     /// Merge a frame identical to the one before into it (its delay added). Default off.
     pub merge_identical: bool,
 }
 
 impl Default for FrameLimits {
     fn default() -> Self {
-        FrameLimits { max_frames: 100_000, max_bytes: 1 << 30, max_canvas_bytes: 512 << 20, merge_identical: false }
+        FrameLimits { max_frames: 100_000, max_bytes: 1 << 30, max_canvas_bytes: 512 << 20, max_decode_bytes: None, merge_identical: false }
     }
 }
 
@@ -87,12 +92,27 @@ impl std::error::Error for FrameError {}
 
 /// Decodes the frames of a GIF.
 pub fn read_frames(bytes: &[u8], limits: &FrameLimits) -> Result<Animation, FrameError> {
-    let info = crate::scan(bytes, 1).ok_or_else(|| FrameError::Malformed("not a GIF".into()))?;
+    if limits.max_frames == 0 {
+        return Err(FrameError::LimitExceeded("the frame limit is zero".into()));
+    }
+    let inspect_limit = limits.max_frames.saturating_add(1);
+    let info = crate::scan(bytes, inspect_limit).ok_or_else(|| FrameError::Malformed("not a GIF".into()))?;
+    let has_more = if info.frames.len() > limits.max_frames {
+        Some(true)
+    } else if info.complete {
+        Some(false)
+    } else {
+        None
+    };
     let (width, height) = (u32::from(info.width), u32::from(info.height));
     let canvas = u64::from(width) * u64::from(height) * 4;
     if canvas > limits.max_canvas_bytes {
         return Err(FrameError::LimitExceeded(format!("a {width}x{height} canvas is over {} bytes", limits.max_canvas_bytes)));
     }
+    let max_decode_bytes = limits.max_decode_bytes.unwrap_or_else(|| limits.max_canvas_bytes.saturating_mul(2));
+    if canvas > max_decode_bytes {
+        return Err(FrameError::LimitExceeded(format!("a {width}x{height} canvas is over the {max_decode_bytes} byte decode-allocation limit")));
+    }
     // The decoder sets up the whole logical screen before the first frame: the file must back it.
     if !crate::plausible(info.bytes_to_back(4, 1 << 28), bytes.len(), 1 << 14) {
         return Err(FrameError::LimitExceeded(format!("a {} byte file cannot hold a {width}x{height} picture", bytes.len())));
@@ -100,21 +120,43 @@ pub fn read_frames(bytes: &[u8], limits: &FrameLimits) -> Result<Animation, Fram
     let malformed = |e: image::ImageError| FrameError::Malformed(e.to_string());
     let mut decoder = GifDecoder::new(Cursor::new(bytes)).map_err(malformed)?;
     let mut il = image::Limits::default();
-    il.max_alloc = Some(limits.max_canvas_bytes.saturating_mul(2));
+    il.max_alloc = Some(max_decode_bytes);
     decoder.set_limits(il).map_err(malformed)?;
     let (width, height) = decoder.dimensions();
-    collect(width, height, decoder.into_frames(), limits)
+    collect(width, height, decoder.into_frames().take(limits.max_frames), limits, has_more)
+}
+
+/// Reads the optional ICC application extension without decoding frame pixels. As in the image
+/// decoder, a malformed optional profile is ignored and returned as `None`.
+pub fn icc_profile(bytes: &[u8]) -> Option<Vec<u8>> {
+    let mut decoder = GifDecoder::new(Cursor::new(bytes)).ok()?;
+    decoder.icc_profile().ok().flatten()
 }
 
 /// Keeps the frames `frames` yields under `limits`.
-fn collect(width: u32, height: u32, frames: image::Frames<'_>, limits: &FrameLimits) -> Result<Animation, FrameError> {
+fn collect(
+    width: u32,
+    height: u32,
+    frames: impl Iterator<Item = image::ImageResult<image::Frame>>,
+    limits: &FrameLimits,
+    has_more: Option<bool>,
+) -> Result<Animation, FrameError> {
     let frame_bytes = u64::from(width) * u64::from(height) * 4;
     let mut out: Vec<AnimFrame> = Vec::new();
+    let mut decoded_frames = 0;
     let mut stop = Stop::End;
     for frame in frames {
+        decoded_frames += 1;
         let frame = match frame {
             Ok(f) => f,
-            Err(e) if out.is_empty() => return Err(FrameError::Malformed(e.to_string())),
+            Err(e) if out.is_empty() => {
+                let message = e.to_string();
+                return Err(if matches!(e, image::ImageError::Limits(_)) {
+                    FrameError::LimitExceeded(message)
+                } else {
+                    FrameError::Malformed(message)
+                });
+            }
             Err(e) => {
                 stop = Stop::Damaged(e.to_string());
                 break;
@@ -140,6 +182,13 @@ fn collect(width: u32, height: u32, frames: image::Frames<'_>, limits: &FrameLim
         }
         out.push(AnimFrame { rgba, delay_ms });
     }
+    if stop == Stop::End && decoded_frames == limits.max_frames {
+        stop = match has_more {
+            Some(true) => Stop::FrameLimit,
+            Some(false) => Stop::End,
+            None => Stop::Damaged("could not inspect the blocks after the kept frames".into()),
+        };
+    }
     if out.is_empty() {
         return Err(FrameError::Malformed("no frame".into()));
     }
@@ -150,6 +199,7 @@ fn collect(width: u32, height: u32, frames: image::Frames<'_>, limits: &FrameLim
 mod tests {
     #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
     use super::*;
+    use std::borrow::Cow;
 
     /// An animated GIF of solid 3 × 2 frames, written by `image`: (red level, delay in hundredths).
     fn gif(frames: &[(u8, u32)]) -> Vec<u8> {
@@ -176,6 +226,63 @@ mod tests {
         assert!(a.frames.iter().all(|f| f.rgba.len() == 24));
     }
 
+    #[test]
+    fn first_frame_pixel_count_tracks_the_lzw_output() {
+        let mut gif = Vec::new();
+        let pixels = image::RgbaImage::from_fn(640, 480, |x, y| image::Rgba([(x / 4) as u8, (y / 3) as u8, 17, 255]));
+        image::codecs::gif::GifEncoder::new_with_speed(&mut gif, 30).encode_frame(image::Frame::new(pixels)).unwrap();
+        assert_eq!(crate::first_frame_decoded_pixels(&gif), Some(640 * 480));
+        assert_eq!(crate::first_frame_decoded_pixels(b"not a gif"), None);
+    }
+
+    #[test]
+    fn reads_the_optional_icc_application_extension() {
+        let mut bytes = gif(&[(10, 5)]);
+        let frame = crate::scan(&bytes, 1).unwrap().frames[0];
+        let profile = [1, 2, 3, 4, 5];
+        let mut extension = vec![0x21, 0xff, 0x0b];
+        extension.extend_from_slice(b"ICCRGBG1012");
+        extension.push(profile.len() as u8);
+        extension.extend_from_slice(&profile);
+        extension.push(0);
+        bytes.splice(frame.offset..frame.offset, extension);
+
+        assert_eq!(icc_profile(&bytes).as_deref(), Some(profile.as_slice()));
+    }
+
+    #[test]
+    fn partial_frames_composite_and_background_disposal_is_applied() {
+        let palette = [0, 0, 0, 255, 0, 0, 0, 0, 255, 0, 255, 0];
+        let (mut bytes, first, second, third) = (Vec::new(), [1], [2], [0]);
+        {
+            let mut encoder = gif::Encoder::new(&mut bytes, 2, 1, &palette).unwrap();
+            let a = gif::Frame { width: 1, height: 1, buffer: Cow::Borrowed(&first), transparent: Some(0), delay: 2, ..gif::Frame::default() };
+            encoder.write_frame(&a).unwrap();
+
+            let b = gif::Frame {
+                left: 1,
+                width: 1,
+                height: 1,
+                buffer: Cow::Borrowed(&second),
+                transparent: Some(0),
+                dispose: gif::DisposalMethod::Background,
+                delay: 3,
+                ..gif::Frame::default()
+            };
+            encoder.write_frame(&b).unwrap();
+
+            let c = gif::Frame { width: 1, height: 1, buffer: Cow::Borrowed(&third), transparent: Some(0), delay: 4, ..gif::Frame::default() };
+            encoder.write_frame(&c).unwrap();
+        }
+
+        let a = read_frames(&bytes, &FrameLimits::default()).unwrap();
+        assert_eq!((a.width, a.height, a.stop), (2, 1, Stop::End));
+        assert_eq!(a.frames.iter().map(|f| f.delay_ms).collect::<Vec<_>>(), [20, 30, 40]);
+        assert_eq!(a.frames[0].rgba, [255, 0, 0, 255, 0, 0, 0, 0]);
+        assert_eq!(a.frames[1].rgba, [255, 0, 0, 255, 0, 0, 255, 255]);
+        assert_eq!(a.frames[2].rgba, [255, 0, 0, 255, 0, 0, 0, 0]);
+    }
+
     #[test]
     fn identical_frames_merge_when_asked() {
         let bytes = gif(&[(10, 5), (10, 7), (200, 1), (200, 1), (10, 2)]);
@@ -195,6 +302,46 @@ mod tests {
         assert_eq!((a.frames.len(), a.stop), (2, Stop::ByteLimit));
         assert!(matches!(read_frames(&bytes, &FrameLimits { max_canvas_bytes: 23, ..FrameLimits::default() }), Err(FrameError::LimitExceeded(_))));
         assert!(read_frames(&bytes, &FrameLimits { max_canvas_bytes: 24, ..FrameLimits::default() }).is_ok());
+        // Canvas and frame buffer each need 24 bytes; decoder allocations share this budget.
+        assert!(matches!(
+            read_frames(&bytes, &FrameLimits { max_decode_bytes: Some(24), ..FrameLimits::default() }),
+            Err(FrameError::LimitExceeded(_))
+        ));
+        assert!(read_frames(&bytes, &FrameLimits { max_decode_bytes: Some(1), ..FrameLimits::default() }).is_err());
+        assert!(
+            matches!(read_frames(&bytes, &FrameLimits { max_frames: 0, ..FrameLimits::default() }), Err(FrameError::LimitExceeded(message)) if message.contains("frame limit is zero"))
+        );
+    }
+
+    #[test]
+    fn merged_frames_still_report_the_decode_frame_limit() {
+        let bytes = gif(&[(10, 5), (10, 7), (200, 1)]);
+        let animation = read_frames(&bytes, &FrameLimits { max_frames: 2, merge_identical: true, ..FrameLimits::default() }).unwrap();
+        assert_eq!(reds(&animation), [(10, 120)]);
+        assert_eq!(animation.stop, Stop::FrameLimit);
+    }
+
+    #[test]
+    fn a_frame_beyond_the_limit_is_not_decoded_or_allocated() {
+        let mut bytes = gif(&[(1, 1), (2, 1)]);
+        let info = crate::scan(&bytes, 2).unwrap();
+        let second = info.frames[1];
+        // The first frame and canvas fit in 24 bytes; the second frame must not be decoded.
+        bytes[second.offset + 5..second.offset + 9].copy_from_slice(&[0xff, 0xff, 0xff, 0xff]);
+        let limits = FrameLimits { max_frames: 1, max_bytes: 24, max_canvas_bytes: 24, max_decode_bytes: Some(1024), ..FrameLimits::default() };
+        let animation = read_frames(&bytes, &limits).unwrap();
+        assert_eq!(animation.frames.len(), 1);
+        assert_eq!(animation.stop, Stop::FrameLimit);
+    }
+
+    #[test]
+    fn decoder_allocation_limit_is_not_reported_as_malformed_input() {
+        let mut bytes = gif(&[(1, 1)]);
+        // The logical screen is 1×1, while the frame data still decodes to 3×2. The canvas
+        // passes the eight-byte decode cap, but the decoder's frame allocation does not.
+        bytes[6..10].copy_from_slice(&[1, 0, 1, 0]);
+        let limits = FrameLimits { max_canvas_bytes: 4, max_decode_bytes: Some(8), ..FrameLimits::default() };
+        assert!(matches!(read_frames(&bytes, &limits), Err(FrameError::LimitExceeded(_))));
     }
 
     #[test]
diff --git a/crates/gif/src/lib.rs b/crates/gif/src/lib.rs
index 33cdad53c..db9e830ab 100644
--- a/crates/gif/src/lib.rs
+++ b/crates/gif/src/lib.rs
@@ -1,7 +1,7 @@
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
-//! The blocks of a GIF, read without decompressing any pixels (GIF89a specification: Logical
-//! Screen Descriptor, Global and Local Color Tables, Graphic Control Extension, Application
-//! Extension, Image Descriptor).
+//! GIF reading and writing. The block reader reads without decompressing pixels (GIF89a
+//! specification: Logical Screen Descriptor, Global and Local Color Tables, Graphic Control
+//! Extension, Application Extension, Image Descriptor).
 //!
 //! [`scan`] walks the file once and reports what an importer needs before it decodes anything:
 //! the logical screen size, every frame's position, size, delay and transparent colour, whether
@@ -12,6 +12,10 @@
 //!
 //! With feature `frames`, [`frames::read_frames`] decodes every frame through the `image` crate's
 //! GIF decoder, after the checks [`scan`] makes possible, with bounded memory.
+//! [`write::animation`] writes full-canvas RGBA8 animation frames with GIF palette quantization,
+//! timing, loop and disposal metadata. Parallel producers can quantize frames with
+//! [`write::prepare_frame`] and pass the compact results to
+//! [`write::AnimationWriter::write_prepared_frame`].
 //!
 //! Input is treated as hostile: every read is bounds-checked, and the number of frames recorded
 //! is capped by the caller.
@@ -20,6 +24,8 @@
 pub mod frames;
 #[cfg(test)]
 mod tests;
+/// GIF image and animation encoding.
+pub mod write;
 
 /// One frame (image descriptor) of a GIF.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -188,6 +194,94 @@ pub fn palette(bytes: &[u8]) -> Option<(Vec<[u8; 3]>, Option<u8>)> {
     Some((colors, transparent))
 }
 
+/// Counts pixels emitted by the first GIF frame's LZW stream, up to its declared area.
+/// Returns `None` when the first frame or its LZW minimum code size is unreadable. This reads
+/// code lengths only; it does not allocate or materialize pixel values.
+pub fn first_frame_decoded_pixels(bytes: &[u8]) -> Option<u64> {
+    let parsed = scan(bytes, 1)?;
+    let frame = parsed.frames.first()?;
+    let packed = *bytes.get(frame.offset.checked_add(9)?)?;
+    let table_bytes = table_len(packed);
+    let code_size_at = frame.offset.checked_add(10)?.checked_add(table_bytes)?;
+    let min_size = *bytes.get(code_size_at)?;
+    if !(1..=11).contains(&min_size) {
+        return None;
+    }
+    let clear = 1usize << min_size;
+    let end = clear + 1;
+    let max = u64::from(frame.width) * u64::from(frame.height);
+    let mut lengths = [1u16; 4096];
+    let (mut width, mut next, mut previous) = (u32::from(min_size) + 1, end + 1, None::<usize>);
+    let (mut bits, mut held, mut pixels) = (0u32, 0u32, 0u64);
+    let mut pos = code_size_at.checked_add(1)?;
+    while let Some(&length) = bytes.get(pos) {
+        let start = pos.checked_add(1)?;
+        pos = start.checked_add(usize::from(length))?;
+        if length == 0 {
+            break;
+        }
+        for &byte in bytes.get(start..pos.min(bytes.len()))? {
+            bits |= u32::from(byte) << held;
+            held += 8;
+            while held >= width {
+                let code = (bits & ((1 << width) - 1)) as usize;
+                bits >>= width;
+                held -= width;
+                if code == clear {
+                    (width, next, previous) = (u32::from(min_size) + 1, end + 1, None);
+                    continue;
+                }
+                let string_len = match previous {
+                    _ if code == end => return Some(pixels),
+                    None if code < clear => 1,
+                    Some(_) if code < next => lengths.get(code).copied().unwrap_or(1),
+                    Some(prev) if code == next => lengths.get(prev).copied().unwrap_or(1).saturating_add(1),
+                    _ => return Some(pixels),
+                };
+                let defined_len = previous.map(|prev| lengths.get(prev).copied().unwrap_or(1).saturating_add(1));
+                if let Some(defined_len) = defined_len
+                    && let Some(slot) = lengths.get_mut(next)
+                {
+                    *slot = defined_len;
+                    next += 1;
+                    if next == 1 << width && width < 12 {
+                        width += 1;
+                    }
+                }
+                previous = Some(code);
+                pixels = pixels.saturating_add(u64::from(string_len));
+                if pixels >= max {
+                    return Some(max);
+                }
+            }
+        }
+    }
+    Some(pixels)
+}
+
+/// Counts compressed image-data bytes in the first frame's sub-blocks, excluding its LZW code-size
+/// byte and all later blocks. A truncated final sub-block contributes only the bytes present.
+pub fn first_frame_compressed_bytes(bytes: &[u8]) -> Option<usize> {
+    let parsed = scan(bytes, 1)?;
+    let frame = parsed.frames.first()?;
+    let packed = *bytes.get(frame.offset.checked_add(9)?)?;
+    let mut pos = frame.offset.checked_add(10)?.checked_add(table_len(packed))?.checked_add(1)?;
+    let mut total = 0usize;
+    loop {
+        let length = usize::from(*bytes.get(pos)?);
+        pos = pos.checked_add(1)?;
+        if length == 0 {
+            return Some(total);
+        }
+        let end = pos.checked_add(length)?;
+        total = total.checked_add(end.min(bytes.len()).saturating_sub(pos))?;
+        if end > bytes.len() {
+            return Some(total);
+        }
+        pos = end;
+    }
+}
+
 /// Whether a file of `file_len` bytes can plausibly hold `declared_bytes` of decoded picture: at
 /// most `max_ratio` decoded bytes for each file byte, plus 1 MiB. A decoder that sets up the whole
 /// logical screen before it reads a frame should be given only files that pass this.
diff --git a/crates/gif/src/tests.rs b/crates/gif/src/tests.rs
index a75743b19..6a776eb50 100644
--- a/crates/gif/src/tests.rs
+++ b/crates/gif/src/tests.rs
@@ -54,6 +54,15 @@ fn animated(delays_cs: &[u32], repeat: Option<image::codecs::gif::Repeat>) -> Ve
     out
 }
 
+#[test]
+fn first_frame_compressed_bytes_exclude_extensions_after_the_image_data() {
+    let mut bytes = gif(&[[1, 2, 3], [4, 5, 6]], None, None);
+    assert_eq!(first_frame_compressed_bytes(&bytes), Some(2));
+    bytes.splice(bytes.len() - 1..bytes.len() - 1, [0x21, 0xFE, 1, b'x', 0]);
+    assert_eq!(first_frame_compressed_bytes(&bytes), Some(2));
+    assert_eq!(first_frame_compressed_bytes(b"not a gif"), None);
+}
+
 #[test]
 fn the_first_frames_table_and_transparent_entry() {
     let g = [[255, 0, 0], [0, 255, 0], [0, 0, 255], [255, 255, 255]];
diff --git a/crates/gif/src/write.rs b/crates/gif/src/write.rs
new file mode 100644
index 000000000..bc8a4be97
--- /dev/null
+++ b/crates/gif/src/write.rs
@@ -0,0 +1,291 @@
+//! Bounded-shape GIF animation writing from full-canvas RGBA8 frames.
+//!
+//! Timing and frame production remain the caller's choice. This module owns the GIF-specific
+//! encoding rules: palette quantization, loop extension, transparency and disposal metadata.
+
+use std::io::Write;
+
+/// Disposal behavior to write for every frame.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Disposal {
+    /// Leave the encoded disposal method unspecified (`0`).
+    Unspecified,
+    /// Do not dispose of the current frame (`1`), matching `gif::Frame`'s default.
+    Keep,
+    /// Restore the logical screen to the background after each frame.
+    Background,
+}
+
+/// GIF encoding options.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Options {
+    /// Loop indefinitely. `false` uses `gif`'s `Finite(0)` setting (no repeat extension).
+    pub loop_forever: bool,
+    /// Disposal metadata to attach to each frame.
+    pub disposal: Disposal,
+    /// `gif` encoder palette quality (`1` is best, `30` is fastest). Default 10.
+    pub speed: i32,
+}
+
+impl Default for Options {
+    fn default() -> Self {
+        Self { loop_forever: true, disposal: Disposal::Keep, speed: 10 }
+    }
+}
+
+/// A full-canvas, straight-alpha RGBA8 frame. Delays are centiseconds, as stored in GIF.
+#[derive(Debug, Clone, Copy)]
+pub struct RgbaFrame<'a> {
+    pub pixels: &'a [u8],
+    pub delay_cs: u16,
+}
+
+/// Why the requested animation could not be encoded.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Error {
+    Dimensions { width: u32, height: u32 },
+    InvalidSpeed(i32),
+    FrameLength { index: usize, actual: usize, expected: usize },
+    PreparedDimensions { actual_width: u16, actual_height: u16, expected_width: u16, expected_height: u16 },
+    NoFrames,
+    Encode(String),
+}
+
+impl std::fmt::Display for Error {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Dimensions { width, height } => write!(f, "GIF dimensions {width}x{height} exceed the 65535 px limit"),
+            Self::InvalidSpeed(speed) => write!(f, "GIF quantization speed {speed} is outside 1–30"),
+            Self::FrameLength { index, actual, expected } => write!(f, "GIF frame {index} has {actual} bytes; expected {expected} RGBA bytes"),
+            Self::PreparedDimensions { actual_width, actual_height, expected_width, expected_height } => {
+                write!(f, "prepared GIF frame is {actual_width}x{actual_height}; expected {expected_width}x{expected_height}")
+            }
+            Self::NoFrames => f.write_str("GIF animation has no frames"),
+            Self::Encode(message) => write!(f, "GIF encode failed: {message}"),
+        }
+    }
+}
+
+impl std::error::Error for Error {}
+
+impl From<gif::EncodingError> for Error {
+    fn from(error: gif::EncodingError) -> Self {
+        Self::Encode(error.to_string())
+    }
+}
+
+/// A palette-quantized GIF frame ready for a writer.
+///
+/// Prepare these inside a parallel render batch to keep only indexed frame data in the batch,
+/// rather than retaining every source RGBA buffer until the writer reaches it.
+pub struct PreparedFrame {
+    width: u16,
+    height: u16,
+    frame: gif::Frame<'static>,
+}
+
+/// Quantize one owned full-canvas RGBA8 frame using the GIF encoder's speed setting.
+pub fn prepare_frame(width: u32, height: u32, mut pixels: Vec<u8>, speed: i32) -> Result<PreparedFrame, Error> {
+    let (width, height) = dimensions(width, height)?;
+    if !(1..=30).contains(&speed) {
+        return Err(Error::InvalidSpeed(speed));
+    }
+    let expected = rgba_len(width, height)?;
+    if pixels.len() != expected {
+        return Err(Error::FrameLength { index: 0, actual: pixels.len(), expected });
+    }
+    let frame = gif::Frame::from_rgba_speed(width, height, &mut pixels, speed);
+    Ok(PreparedFrame { width, height, frame })
+}
+
+fn rgba_len(width: u16, height: u16) -> Result<usize, Error> {
+    usize::from(width)
+        .checked_mul(usize::from(height))
+        .and_then(|pixels| pixels.checked_mul(4))
+        .ok_or(Error::Dimensions { width: u32::from(width), height: u32::from(height) })
+}
+
+fn dimensions(width: u32, height: u32) -> Result<(u16, u16), Error> {
+    if width == 0 || height == 0 || width > u32::from(u16::MAX) || height > u32::from(u16::MAX) {
+        return Err(Error::Dimensions { width, height });
+    }
+    Ok((width as u16, height as u16))
+}
+
+/// A writer that appends encoded frames to an output incrementally.
+pub struct AnimationWriter<W: Write> {
+    encoder: gif::Encoder<W>,
+    width: u16,
+    height: u16,
+    options: Options,
+    frames_written: usize,
+}
+
+impl<W: Write> AnimationWriter<W> {
+    /// Start an animation on `output`; subsequent calls write one frame at a time.
+    pub fn new(output: W, width: u32, height: u32, options: Options) -> Result<Self, Error> {
+        if width == 0 || height == 0 || width > u32::from(u16::MAX) || height > u32::from(u16::MAX) {
+            return Err(Error::Dimensions { width, height });
+        }
+        if !(1..=30).contains(&options.speed) {
+            return Err(Error::InvalidSpeed(options.speed));
+        }
+        let width = width as u16;
+        let height = height as u16;
+        let mut encoder = gif::Encoder::new(output, width, height, &[]).map_err(Error::from)?;
+        encoder.set_repeat(if options.loop_forever { gif::Repeat::Infinite } else { gif::Repeat::Finite(0) }).map_err(Error::from)?;
+        Ok(Self { encoder, width, height, options, frames_written: 0 })
+    }
+
+    /// Encode and append one full-canvas RGBA8 frame.
+    pub fn write_frame(&mut self, frame: RgbaFrame<'_>) -> Result<(), Error> {
+        let expected = rgba_len(self.width, self.height)?;
+        if frame.pixels.len() != expected {
+            return Err(Error::FrameLength { index: self.frames_written, actual: frame.pixels.len(), expected });
+        }
+        let prepared =
+            prepare_frame(u32::from(self.width), u32::from(self.height), frame.pixels.to_vec(), self.options.speed).map_err(|error| match error {
+                Error::FrameLength { actual, expected, .. } => Error::FrameLength { index: self.frames_written, actual, expected },
+                error => error,
+            })?;
+        self.write_prepared_frame(prepared, frame.delay_cs)
+    }
+
+    /// Append a previously quantized frame without copying its pixel buffer.
+    pub fn write_prepared_frame(&mut self, mut prepared: PreparedFrame, delay_cs: u16) -> Result<(), Error> {
+        if prepared.width != self.width || prepared.height != self.height {
+            return Err(Error::PreparedDimensions {
+                actual_width: prepared.width,
+                actual_height: prepared.height,
+                expected_width: self.width,
+                expected_height: self.height,
+            });
+        }
+        prepared.frame.delay = delay_cs;
+        prepared.frame.dispose = match self.options.disposal {
+            Disposal::Unspecified => gif::DisposalMethod::Any,
+            Disposal::Keep => gif::DisposalMethod::Keep,
+            Disposal::Background => gif::DisposalMethod::Background,
+        };
+        self.encoder.write_frame(&prepared.frame).map_err(Error::from)?;
+        self.frames_written = self.frames_written.saturating_add(1);
+        Ok(())
+    }
+
+    /// Finish the GIF and return the underlying output.
+    pub fn finish(self) -> Result<W, Error> {
+        self.encoder.into_inner().map_err(Error::from)
+    }
+}
+
+/// Encode an animation into a complete GIF file.
+///
+/// Every input frame must cover the whole canvas and contain exactly `width * height * 4` bytes.
+/// At most one mutable frame copy is made at a time for the quantizer. This is intentionally a
+/// streaming writer so callers can render and encode frames incrementally.
+pub fn animation(width: u32, height: u32, frames: &[RgbaFrame<'_>], options: Options) -> Result<Vec<u8>, Error> {
+    if frames.is_empty() {
+        return Err(Error::NoFrames);
+    }
+    let mut writer = AnimationWriter::new(Vec::new(), width, height, options)?;
+    for frame in frames {
+        writer.write_frame(*frame)?;
+    }
+    writer.finish()
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+
+    use super::{Disposal, Options, RgbaFrame, animation, prepare_frame};
+
+    #[test]
+    fn writes_repeat_delays_disposal_and_dimensions() {
+        let red = [255, 0, 0, 255];
+        let blue = [0, 0, 255, 255];
+        let bytes = animation(
+            1,
+            1,
+            &[RgbaFrame { pixels: &red, delay_cs: 4 }, RgbaFrame { pixels: &blue, delay_cs: 7 }],
+            Options { loop_forever: false, disposal: Disposal::Background, speed: 10 },
+        )
+        .unwrap();
+        let info = crate::scan(&bytes, 4).unwrap();
+        assert_eq!((info.width, info.height), (1, 1));
+        assert_eq!(info.loop_count, None);
+        assert_eq!(info.frames.iter().map(|f| f.delay_cs).collect::<Vec<_>>(), [4, 7]);
+        assert!(info.frames.iter().all(|f| f.disposal == 2));
+    }
+
+    #[test]
+    fn default_disposal_matches_gif_frame_default() {
+        let bytes = animation(1, 1, &[RgbaFrame { pixels: &[1, 2, 3, 255], delay_cs: 1 }], Options::default()).unwrap();
+        let info = crate::scan(&bytes, 1).unwrap();
+        assert_eq!(info.frames[0].disposal, 1);
+    }
+
+    #[test]
+    fn rejects_dimensions_empty_animation_and_wrong_pixel_lengths() {
+        assert!(matches!(animation(0, 1, &[RgbaFrame { pixels: &[0; 4], delay_cs: 1 }], Options::default()), Err(super::Error::Dimensions { .. })));
+        assert!(matches!(animation(1, 1, &[], Options::default()), Err(super::Error::NoFrames)));
+        assert!(matches!(animation(1, 1, &[RgbaFrame { pixels: &[0; 3], delay_cs: 1 }], Options::default()), Err(super::Error::FrameLength { .. })));
+        assert!(matches!(
+            animation(1, 1, &[RgbaFrame { pixels: &[0; 4], delay_cs: 1 }], Options { speed: 0, ..Options::default() }),
+            Err(super::Error::InvalidSpeed(0))
+        ));
+        assert!(matches!(
+            animation(1, 1, &[RgbaFrame { pixels: &[0; 4], delay_cs: 1 }, RgbaFrame { pixels: &[0; 3], delay_cs: 1 }], Options::default()),
+            Err(super::Error::FrameLength { index: 1, .. })
+        ));
+    }
+
+    #[test]
+    fn streaming_writer_preserves_empty_output_behavior() {
+        let bytes = super::AnimationWriter::new(Vec::new(), 1, 1, Options::default()).unwrap().finish().unwrap();
+        assert!(bytes.starts_with(b"GIF89a"));
+        assert_eq!(bytes.last(), Some(&b';'));
+    }
+
+    #[cfg(feature = "frames")]
+    #[test]
+    fn prepared_frames_stream_without_changing_decoded_pixels() {
+        let red = vec![255, 0, 0, 255];
+        let blue = vec![0, 0, 255, 255];
+        let mut writer = super::AnimationWriter::new(Vec::new(), 1, 1, Options::default()).unwrap();
+        writer.write_prepared_frame(prepare_frame(1, 1, red, 10).unwrap(), 3).unwrap();
+        writer.write_prepared_frame(prepare_frame(1, 1, blue, 10).unwrap(), 5).unwrap();
+        let bytes = writer.finish().unwrap();
+        let expected = animation(
+            1,
+            1,
+            &[RgbaFrame { pixels: &[255, 0, 0, 255], delay_cs: 3 }, RgbaFrame { pixels: &[0, 0, 255, 255], delay_cs: 5 }],
+            Options::default(),
+        )
+        .unwrap();
+        assert_eq!(bytes, expected);
+        let decoded = crate::frames::read_frames(&bytes, &crate::frames::FrameLimits::default()).unwrap();
+        assert_eq!(decoded.frames[0].rgba, [255, 0, 0, 255]);
+        assert_eq!(decoded.frames[1].rgba, [0, 0, 255, 255]);
+        assert_eq!(decoded.frames.iter().map(|frame| frame.delay_ms).collect::<Vec<_>>(), [30, 50]);
+    }
+
+    #[test]
+    fn rejects_prepared_frames_with_other_dimensions() {
+        let prepared = prepare_frame(2, 1, vec![0; 8], 10).unwrap();
+        let mut writer = super::AnimationWriter::new(Vec::new(), 1, 1, Options::default()).unwrap();
+        assert!(matches!(writer.write_prepared_frame(prepared, 1), Err(super::Error::PreparedDimensions { .. })));
+    }
+
+    #[cfg(feature = "frames")]
+    #[test]
+    fn encoded_frames_decode_to_the_requested_colors() {
+        let red = [255, 0, 0, 255];
+        let blue = [0, 0, 255, 255];
+        let bytes =
+            animation(1, 1, &[RgbaFrame { pixels: &red, delay_cs: 1 }, RgbaFrame { pixels: &blue, delay_cs: 2 }], Options::default()).unwrap();
+        let decoded = crate::frames::read_frames(&bytes, &crate::frames::FrameLimits::default()).unwrap();
+        assert_eq!(decoded.frames[0].rgba, red);
+        assert_eq!(decoded.frames[1].rgba, blue);
+    }
+}
diff --git a/crates/idml/src/part.rs b/crates/idml/src/part.rs
index f55ce4197..e8fd72d6b 100644
--- a/crates/idml/src/part.rs
+++ b/crates/idml/src/part.rs
@@ -4,8 +4,14 @@ use craft_xml::{DECL_STANDALONE, El, Local, Node, Options};
 
 use crate::{DOM_VERSION, PACKAGING_NS};
 
-pub(crate) const XML_LIMITS: craft_xml::Limits =
-    craft_xml::Limits { max_input: 512 << 20, max_depth: 256, max_nodes: 8_000_000, max_attrs: 1024, max_attrs_total: 32_000_000 };
+pub(crate) const XML_LIMITS: craft_xml::Limits = craft_xml::Limits {
+    max_input: 512 << 20,
+    max_depth: 256,
+    max_nodes: 8_000_000,
+    max_elements: 8_000_000,
+    max_attrs: 1024,
+    max_attrs_total: 32_000_000,
+};
 
 /// The XML limits a part is read with: 512 MiB of input, 256 levels of nesting (InDesign's
 /// packages stay under a few dozen), 8,000,000 nodes and 32,000,000 attributes in one part.
diff --git a/crates/jpeg/src/lib.rs b/crates/jpeg/src/lib.rs
index 783f19041..185bf3ec5 100644
--- a/crates/jpeg/src/lib.rs
+++ b/crates/jpeg/src/lib.rs
@@ -7,11 +7,11 @@
 //! - sequential DCT, Huffman coded, 8 or 12-bit samples (SOF0 and SOF1; SOF0 files that declare
 //!   12 bits are read as SOF1);
 //! - extended sequential DCT, arithmetic coded, 8 or 12-bit (SOF9);
+//! - progressive DCT, Huffman coded, 8 or 12-bit (SOF2);
 //! - progressive DCT, arithmetic coded, 8 or 12-bit (SOF10).
 //!
-//! Every other frame returns [`Error::Unsupported`]: progressive Huffman (SOF2), lossless (SOF3,
-//! SOF11) and hierarchical (SOF5–SOF7, SOF13–SOF15) files, and DCT precisions other than 8 and
-//! 12 bits.
+//! Every other frame returns [`Error::Unsupported`]: lossless (SOF3, SOF11) and hierarchical
+//! (SOF5–SOF7, SOF13–SOF15) files, and DCT precisions other than 8 and 12 bits.
 //!
 //! [`Bands`] decodes the common case, a sequential Huffman-coded 8-bit frame in one scan, a band
 //! of rows at a time, into the samples [`decode`] would give for those rows, so that images too
@@ -69,6 +69,65 @@ fn unsupported(m: impl Into<String>) -> Error {
     Error::Unsupported(m.into())
 }
 
+/// Annex K Huffman tables used by AVI1 Motion JPEG streams that omit DHT.
+const AVI1_DEFAULT_DHT: &[u8] = &[
+    0xFF, 0xC4, 0x01, 0xA2, 0x00, 0x00, 0x01, 0x05, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02,
+    0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x01, 0x00, 0x03, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x10, 0x00, 0x02, 0x01, 0x03, 0x03, 0x02, 0x04, 0x03, 0x05,
+    0x05, 0x04, 0x04, 0x00, 0x00, 0x01, 0x7D, 0x01, 0x02, 0x03, 0x00, 0x04, 0x11, 0x05, 0x12, 0x21, 0x31, 0x41, 0x06, 0x13, 0x51, 0x61, 0x07, 0x22,
+    0x71, 0x14, 0x32, 0x81, 0x91, 0xA1, 0x08, 0x23, 0x42, 0xB1, 0xC1, 0x15, 0x52, 0xD1, 0xF0, 0x24, 0x33, 0x62, 0x72, 0x82, 0x09, 0x0A, 0x16, 0x17,
+    0x18, 0x19, 0x1A, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A,
+    0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A,
+    0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8,
+    0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5,
+    0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE1, 0xE2, 0xE3, 0xE4, 0xE5, 0xE6, 0xE7, 0xE8, 0xE9, 0xEA, 0xF1, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8, 0xF9,
+    0xFA, 0x11, 0x00, 0x02, 0x01, 0x02, 0x04, 0x04, 0x03, 0x04, 0x07, 0x05, 0x04, 0x04, 0x00, 0x01, 0x02, 0x77, 0x00, 0x01, 0x02, 0x03, 0x11, 0x04,
+    0x05, 0x21, 0x31, 0x06, 0x12, 0x41, 0x51, 0x07, 0x61, 0x71, 0x13, 0x22, 0x32, 0x81, 0x08, 0x14, 0x42, 0x91, 0xA1, 0xB1, 0xC1, 0x09, 0x23, 0x33,
+    0x52, 0xF0, 0x15, 0x62, 0x72, 0xD1, 0x0A, 0x16, 0x24, 0x34, 0xE1, 0x25, 0xF1, 0x17, 0x18, 0x19, 0x1A, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x35, 0x36,
+    0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x63, 0x64, 0x65, 0x66,
+    0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x92, 0x93, 0x94,
+    0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA,
+    0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE2, 0xE3, 0xE4, 0xE5, 0xE6, 0xE7,
+    0xE8, 0xE9, 0xEA, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8, 0xF9, 0xFA,
+];
+
+/// Insert Annex K Huffman tables into an AVI1 MJPEG frame that omits DHT.
+///
+/// Frames that are not JPEG, already define DHT, or do not reach SOS are returned unchanged.
+/// The caller should use this only for an AVI1/MJPEG stream, since ordinary JPEG streams must
+/// provide their own tables.
+pub fn with_avi1_default_huffman(jpeg: &[u8]) -> std::borrow::Cow<'_, [u8]> {
+    use std::borrow::Cow;
+    if jpeg.get(..2) != Some(&[0xFF, 0xD8]) {
+        return Cow::Borrowed(jpeg);
+    }
+    let mut at = 2usize;
+    while at + 1 < jpeg.len() && jpeg[at] == 0xFF {
+        let marker = jpeg[at + 1];
+        match marker {
+            0xC4 => return Cow::Borrowed(jpeg),
+            0xDA => {
+                let mut out = Vec::with_capacity(jpeg.len().saturating_add(AVI1_DEFAULT_DHT.len()));
+                out.extend_from_slice(&jpeg[..at]);
+                out.extend_from_slice(AVI1_DEFAULT_DHT);
+                out.extend_from_slice(&jpeg[at..]);
+                return Cow::Owned(out);
+            }
+            0xD0..=0xD9 | 0x01 => at += 2,
+            0xFF => at += 1,
+            _ => {
+                let Some(len) = jpeg.get(at + 2..at + 4).map(|b| usize::from(u16::from_be_bytes([b[0], b[1]]))) else { break };
+                if len < 2 {
+                    break;
+                }
+                let Some(next) = at.checked_add(2 + len).filter(|&n| n <= jpeg.len()) else { break };
+                at = next;
+            }
+        }
+    }
+    Cow::Borrowed(jpeg)
+}
+
 /// Decompression-bomb guards, checked against the frame header before any image buffer is
 /// allocated.
 ///
@@ -422,7 +481,7 @@ fn parse_header(marker: u8, seg: &[u8]) -> Result<Header, Error> {
         0xC0 | 0xC1 => (false, false),
         0xC9 => (true, false),
         0xCA => (true, true),
-        0xC2 => return Err(unsupported("progressive Huffman-coded JPEG is not supported")),
+        0xC2 => (false, true),
         0xC3 | 0xCB => return Err(unsupported("lossless JPEG is not supported")),
         _ => return Err(unsupported("hierarchical JPEG is not supported")),
     };
@@ -857,6 +916,128 @@ impl ScanDecoder for HuffmanScan<'_> {
     }
 }
 
+/// Huffman-coded progressive scan state (G.1.2). EOB runs span blocks in a scan.
+struct ProgressiveHuffmanScan<'a> {
+    bits: Bits<'a>,
+    tables: Vec<(&'a Huffman, &'a Huffman)>,
+    mode: ArithMode,
+    ss: usize,
+    se: usize,
+    al: u8,
+    pred: [i32; 4],
+    eob_run: usize,
+}
+
+impl ScanDecoder for ProgressiveHuffmanScan<'_> {
+    fn restart(&mut self) {
+        self.bits.restart();
+        self.pred = [0; 4];
+        self.eob_run = 0;
+    }
+
+    fn block(&mut self, sc: usize, blk: &mut [i32; 64]) -> Result<(), Error> {
+        let &(dc, ac) = self.tables.get(sc).ok_or_else(|| err("bad scan component"))?;
+        let p1 = 1i32.checked_shl(u32::from(self.al)).ok_or_else(|| err("bad successive approximation"))?;
+        match self.mode {
+            ArithMode::DcFirst => {
+                let t = u32::from(dc.decode(&mut self.bits)?);
+                if t > 15 {
+                    return Err(err("bad DC difference category"));
+                }
+                let diff = extend(self.bits.get(t), t);
+                let pred = self.pred.get_mut(sc).ok_or_else(|| err("bad scan component"))?;
+                *pred = pred.wrapping_add(diff);
+                blk[0] = pred.wrapping_mul(p1);
+            }
+            ArithMode::DcRefine => {
+                if self.bits.get(1) != 0 {
+                    blk[0] = if blk[0] < 0 { blk[0].wrapping_sub(p1) } else { blk[0].wrapping_add(p1) };
+                }
+            }
+            ArithMode::AcFirst => {
+                if self.eob_run != 0 {
+                    self.eob_run -= 1;
+                } else {
+                    let mut k = self.ss;
+                    while k <= self.se {
+                        let rs = ac.decode(&mut self.bits)?;
+                        let (r, s) = (usize::from(rs >> 4), u32::from(rs & 15));
+                        if s == 0 {
+                            if r == 15 {
+                                k += 16;
+                                continue;
+                            }
+                            self.eob_run = (1usize << r).saturating_add(self.bits.get(r as u32) as usize).saturating_sub(1);
+                            break;
+                        }
+                        k = k.saturating_add(r);
+                        if k > self.se {
+                            return Err(err("AC coefficient past the end of the band"));
+                        }
+                        blk[k] = extend(self.bits.get(s), s).wrapping_mul(p1);
+                        k += 1;
+                    }
+                }
+            }
+            ArithMode::AcRefine => {
+                let mut k = self.ss;
+                if self.eob_run == 0 {
+                    while k <= self.se {
+                        let rs = ac.decode(&mut self.bits)?;
+                        let (mut r, s) = (usize::from(rs >> 4), rs & 15);
+                        let mut new_value = 0;
+                        if s == 0 {
+                            if r != 15 {
+                                self.eob_run = (1usize << r).saturating_add(self.bits.get(r as u32) as usize);
+                                break;
+                            }
+                            r = 16;
+                        } else {
+                            if s != 1 {
+                                return Err(err("bad AC refinement category"));
+                            }
+                            new_value = if self.bits.get(1) != 0 { p1 } else { -p1 };
+                        }
+                        while k <= self.se {
+                            if blk[k] != 0 {
+                                if self.bits.get(1) != 0 && (blk[k].unsigned_abs() & p1 as u32) == 0 {
+                                    blk[k] = if blk[k] < 0 { blk[k].wrapping_sub(p1) } else { blk[k].wrapping_add(p1) };
+                                }
+                            } else if r == 0 {
+                                break;
+                            } else {
+                                r -= 1;
+                            }
+                            k += 1;
+                        }
+                        if new_value != 0 {
+                            if k > self.se {
+                                return Err(err("AC refinement past the band"));
+                            }
+                            blk[k] = new_value;
+                        }
+                        k += 1;
+                    }
+                }
+                if self.eob_run != 0 {
+                    while k <= self.se {
+                        if blk[k] != 0 && self.bits.get(1) != 0 && (blk[k].unsigned_abs() & p1 as u32) == 0 {
+                            blk[k] = if blk[k] < 0 { blk[k].wrapping_sub(p1) } else { blk[k].wrapping_add(p1) };
+                        }
+                        k += 1;
+                    }
+                    self.eob_run -= 1;
+                }
+            }
+            ArithMode::Sequential => return Err(err("invalid progressive scan mode")),
+        }
+        if self.bits.exhausted {
+            return Err(err("entropy-coded data ends before the scan does"));
+        }
+        Ok(())
+    }
+}
+
 #[derive(Clone, Copy, PartialEq, Eq)]
 enum ArithMode {
     Sequential,
@@ -1164,12 +1345,31 @@ fn decode_scan(frame: &mut Frame, tables: &Tables, scan: &Scan, d: &[u8], at_mar
     } else {
         let mut sel = Vec::with_capacity(scan.comps.len());
         for &(_, td, ta) in &scan.comps {
-            let dc = tables.dc.get(td).and_then(Option::as_ref).ok_or_else(|| err("scan uses an undefined Huffman table"))?;
-            let ac = tables.ac.get(ta).and_then(Option::as_ref).ok_or_else(|| err("scan uses an undefined Huffman table"))?;
+            let dc = tables.dc.get(td).and_then(Option::as_ref);
+            let ac = tables.ac.get(ta).and_then(Option::as_ref);
+            let (dc, ac) = if frame.progressive && scan.ss != 0 {
+                let ac = ac.ok_or_else(|| err("scan uses an undefined AC Huffman table"))?;
+                (dc.unwrap_or(ac), ac)
+            } else {
+                let dc = dc.ok_or_else(|| err("scan uses an undefined DC Huffman table"))?;
+                (dc, ac.unwrap_or(dc))
+            };
             sel.push((dc, ac));
         }
-        let mut dec = HuffmanScan { bits: Bits::new(d), tables: sel, pred: [0; 4] };
-        walk_scan(frame, scan, tables.restart, &mut dec, done)
+        if frame.progressive {
+            let mode = match (scan.ss, scan.ah) {
+                (0, 0) => ArithMode::DcFirst,
+                (0, _) => ArithMode::DcRefine,
+                (_, 0) => ArithMode::AcFirst,
+                (_, _) => ArithMode::AcRefine,
+            };
+            let mut dec =
+                ProgressiveHuffmanScan { bits: Bits::new(d), tables: sel, mode, ss: scan.ss, se: scan.se, al: scan.al, pred: [0; 4], eob_run: 0 };
+            walk_scan(frame, scan, tables.restart, &mut dec, done)
+        } else {
+            let mut dec = HuffmanScan { bits: Bits::new(d), tables: sel, pred: [0; 4] };
+            walk_scan(frame, scan, tables.restart, &mut dec, done)
+        }
     }
 }
 
diff --git a/crates/jpeg/src/tests.rs b/crates/jpeg/src/tests.rs
index fcfb2e66e..27dfcbede 100644
--- a/crates/jpeg/src/tests.rs
+++ b/crates/jpeg/src/tests.rs
@@ -759,6 +759,52 @@ fn extended_huffman_matches_zune_on_baseline_data() {
     }
 }
 
+#[test]
+fn progressive_huffman_matches_zune() {
+    let bytes = include_bytes!("../tests/data/testorig-huffman-progressive.jpg");
+    let (reference, (w, h)) = zune_decode(bytes);
+    let ours = decode_default(bytes).unwrap();
+    assert_eq!((ours.width, ours.height, ours.components), (w, h, 3));
+    assert!(!ours.damaged);
+    let Samples::U8(samples) = ours.samples else { panic!("8-bit fixture decoded with another precision") };
+    let mad = samples.iter().zip(&reference).map(|(&a, &b)| f32::from(a.abs_diff(b))).sum::<f32>() / samples.len() as f32;
+    assert!(mad < 2.0, "mean absolute difference {mad}");
+}
+
+#[test]
+fn avi1_default_huffman_tables_restore_a_missing_dht() {
+    let fixture = include_bytes!("../tests/data/testorig.jpg");
+    let mut without = fixture[..2].to_vec();
+    let mut at = 2;
+    while at + 1 < fixture.len() {
+        if fixture[at] != 0xFF {
+            break;
+        }
+        let marker = fixture[at + 1];
+        if marker == 0xDA {
+            without.extend_from_slice(&fixture[at..]);
+            break;
+        }
+        if marker == 0xC4 {
+            let len = usize::from(u16::from_be_bytes([fixture[at + 2], fixture[at + 3]]));
+            at += 2 + len;
+        } else if (0xD0..=0xD9).contains(&marker) || marker == 0x01 {
+            without.extend_from_slice(&fixture[at..at + 2]);
+            at += 2;
+        } else {
+            let len = usize::from(u16::from_be_bytes([fixture[at + 2], fixture[at + 3]]));
+            without.extend_from_slice(&fixture[at..at + 2 + len]);
+            at += 2 + len;
+        }
+    }
+    assert!(matches!(with_avi1_default_huffman(&without), std::borrow::Cow::Owned(_)));
+    let restored = with_avi1_default_huffman(&without);
+    let decoded = decode_default(&restored).unwrap();
+    let expected = decode_default(fixture).unwrap();
+    assert_eq!(decoded, expected);
+    assert!(matches!(with_avi1_default_huffman(fixture), std::borrow::Cow::Borrowed(_)));
+}
+
 #[test]
 fn malformed_streams_return_errors_not_panics() {
     let blocks = coefficients(6, 5, 500);
diff --git a/crates/jpeg/tests/data/SHA256SUMS b/crates/jpeg/tests/data/SHA256SUMS
index 19c71c547..e7a582645 100644
--- a/crates/jpeg/tests/data/SHA256SUMS
+++ b/crates/jpeg/tests/data/SHA256SUMS
@@ -9,3 +9,4 @@ acc6ec555d41d15b368320edaa3b20958ee6fa97cb6e4a18d1213d5ae8bec73b  testorig.jpg
 cb0a2c60e6a89c68ef8cf48854dc09c77c26ffb27ac62e17d343d98f1424cc77  testorig-ari-progressive-restart.jpg
 c4942c4b704d20e27c4cd3e613c6ef975dd7cfe53a756e2c209fa3ad033d8b51  testorig12-ari.jpg
 18df0394115d9f8751939fb9f45a0d330df2ca849e9f8b07d0af76c09b90fcdb  testorig12-ari-progressive.jpg
+5fecfaa2e0f79a52d207b9b13b39f96f5d5bd2958ec80fcf585d82cd93f62bdd  testorig-huffman-progressive.jpg
diff --git a/crates/jpeg/tests/data/SOURCE.md b/crates/jpeg/tests/data/SOURCE.md
index bc15d764d..ba2b0c098 100644
--- a/crates/jpeg/tests/data/SOURCE.md
+++ b/crates/jpeg/tests/data/SOURCE.md
@@ -9,6 +9,7 @@ libjpeg-turbo's tools, as described below.
 | File | What it is |
 |---|---|
 | `testorig.jpg` | 227×149 YCbCr, 2×2 luma sampling, baseline Huffman (SOF0) |
+| `testorig-huffman-progressive.jpg` | `testorig.jpg` decoded to PPM with FFmpeg, then re-encoded with libjpeg-turbo `cjpeg -progressive -quality 88` (SOF2) |
 | `testimgari.jpg` | the same image, arithmetic coded (SOF9), one interleaved scan |
 | `testimgari-huffman.jpg` | `testimgari.jpg` losslessly transcoded to baseline Huffman (SOF0) |
 | `testorig12.jpg` | 227×149 YCbCr, 12-bit extended sequential Huffman (SOF1) |
diff --git a/crates/jpeg/tests/data/testorig-huffman-progressive.jpg b/crates/jpeg/tests/data/testorig-huffman-progressive.jpg
new file mode 100644
index 000000000..1dba9903c
Binary files /dev/null and b/crates/jpeg/tests/data/testorig-huffman-progressive.jpg differ
diff --git a/crates/jxl/Cargo.toml b/crates/jxl/Cargo.toml
new file mode 100644
index 000000000..45ed44f12
--- /dev/null
+++ b/crates/jxl/Cargo.toml
@@ -0,0 +1,26 @@
+[package]
+name = "craft-jxl"
+description = "JPEG XL image decoding and encoding with bounded input and allocation tracking."
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[features]
+default = ["decode", "encode"]
+decode = ["dep:jxl-oxide"]
+encode = ["dep:jixel"]
+
+[dependencies]
+jxl-oxide = { workspace = true, optional = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+craft-cms = { workspace = true }
+
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+jixel = { workspace = true, optional = true }
diff --git a/crates/jxl/README.md b/crates/jxl/README.md
new file mode 100644
index 000000000..a3a8c6fa4
--- /dev/null
+++ b/crates/jxl/README.md
@@ -0,0 +1,25 @@
+# craft-jxl
+
+JPEG XL decoding and encoding for still raster images.
+
+The decoder reads a codestream incrementally, checks its dimensions before loading the remainder,
+and applies a caller-selected compressed-input, pixel-count, and tracked-decoder-allocation budget.
+`jxl-oxide`'s allocation tracker cannot account for every allocation made by the decoder, and the
+input slice is already owned by the caller. The decoder returns the first frame as interleaved
+`f32` samples together with source and rendered color metadata. It does not perform an external
+ICC transform; callers that need color-managed output should use the returned profiles with their
+CMS. CMYK output is rejected because this crate does not bundle an external CMS.
+
+`decode_with_color` can request linear Rec. 2020 for enum-encoded images. XYB is rendered through
+linear sRGB and converted to Rec. 2020 to avoid the known wide-gamut XYB rendering issue in
+`jxl-oxide`. If a source embeds an ICC profile, the decoder keeps the source-profile samples and
+returns the profile; it does not claim to transform ICC data without a CMS. `decode` retains the
+decoder's default rendering target.
+
+The encoder accepts interleaved 8-bit, 16-bit, or HDR floating-point samples. Floating-point input
+is linear-light and is currently available only with the Rec. 2020 PQ option; one input unit maps
+to 203 cd/m². Gray input is expanded to RGB, and opaque alpha is omitted. ICC data is embedded in
+lossless output; Exif and XMP boxes are written when provided. Encoding is unavailable on
+`wasm32` targets.
+
+`jxl-oxide` is MIT OR Apache-2.0. `jixel` is BSD-3-Clause OR Apache-2.0.
diff --git a/crates/jxl/src/decode.rs b/crates/jxl/src/decode.rs
new file mode 100644
index 000000000..955774b23
--- /dev/null
+++ b/crates/jxl/src/decode.rs
@@ -0,0 +1,259 @@
+use std::panic::{AssertUnwindSafe, catch_unwind};
+
+use jxl_oxide::color::{ColourEncoding, ColourSpace, EnumColourEncoding, Primaries, RenderingIntent, TransferFunction, WhitePoint};
+use jxl_oxide::{AllocTracker, AuxBoxData, ExtraChannelType, InitializeResult, JxlImage};
+
+use crate::{DecodeLimits, Decoded, Error, Layout, Metadata, OutputColor, Result};
+
+const INPUT_CHUNK: usize = 4096;
+const TRACKED_BYTES_PER_PIXEL: u64 = 4 * 4 * 8;
+const MIN_TRACKED_BYTES: u64 = 64 << 20;
+
+/// Decode the first frame, keeping the decoder's tracked allocations within `limits`.
+///
+/// The allocator budget applies to allocations registered with `jxl-oxide`'s `AllocTracker`.
+/// The decoder may also make untracked allocations, including the input buffer supplied by the
+/// caller. Header data is fed in small chunks so the dimensions are checked before the rest of
+/// the codestream is loaded.
+pub fn decode(bytes: &[u8], limits: DecodeLimits) -> Result<Decoded> {
+    decode_with_color(bytes, limits, OutputColor::DecoderDefault)
+}
+
+/// Decode the first image frame using an explicit rendered-pixel color target.
+pub fn decode_with_color(bytes: &[u8], limits: DecodeLimits, output_color: OutputColor) -> Result<Decoded> {
+    catch_unwind(AssertUnwindSafe(|| decode_inner(bytes, limits, output_color)))
+        .unwrap_or_else(|_| Err(Error::Malformed("decoder failed while reading this file".into())))
+}
+
+fn decode_inner(bytes: &[u8], limits: DecodeLimits, output_color: OutputColor) -> Result<Decoded> {
+    if bytes.len() > limits.max_input_bytes {
+        return Err(Error::LimitExceeded(format!("{} input bytes exceed the {} byte input limit", bytes.len(), limits.max_input_bytes)));
+    }
+    let budget = limits.max_tracked_bytes.unwrap_or_else(|| limits.max_pixels.saturating_mul(TRACKED_BYTES_PER_PIXEL).max(MIN_TRACKED_BYTES));
+    let tracker = AllocTracker::with_limit(usize::try_from(budget).unwrap_or(usize::MAX));
+    let mut uninit = JxlImage::builder().alloc_tracker(tracker).build_uninit();
+    let mut rest = bytes;
+    let mut window = INPUT_CHUNK;
+    let mut image = loop {
+        let feed = rest.get(..window).unwrap_or(rest);
+        let consumed = uninit.feed_bytes(feed).map_err(decode_error)?;
+        rest = rest.get(consumed..).unwrap_or_default();
+        match uninit.try_init().map_err(decode_error)? {
+            InitializeResult::Initialized(image) => break image,
+            InitializeResult::NeedMoreData(next) => uninit = next,
+        }
+        if consumed == 0 {
+            if window >= rest.len() {
+                return Err(Error::Malformed("truncated JPEG XL header".into()));
+            }
+            window = window.saturating_mul(2);
+        }
+    };
+
+    let (width, height) = (image.width(), image.height());
+    if width == 0 || height == 0 {
+        return Err(Error::Malformed("zero image dimension".into()));
+    }
+    let pixels = u64::from(width).saturating_mul(u64::from(height));
+    if pixels > limits.max_pixels {
+        return Err(Error::PixelLimitExceeded { width, height, max_pixels: limits.max_pixels });
+    }
+
+    // `JxlImageBuilder::read` feeds the full input. Continue in bounded chunks so trailing frame
+    // data and boxes are not copied into an untracked buffer all at once.
+    while !image.is_loading_done() && !rest.is_empty() {
+        let consumed = image.feed_bytes(rest.get(..INPUT_CHUNK).unwrap_or(rest)).map_err(decode_error)?;
+        if consumed == 0 {
+            break;
+        }
+        rest = rest.get(consumed..).unwrap_or_default();
+    }
+    image.finalize().map_err(decode_error)?;
+
+    let (bit_depth, float_samples, grayscale, source_orientation, xyb_encoded, extra_channels, colour_encoding) = {
+        let metadata = &image.image_header().metadata;
+        (
+            metadata.bit_depth.bits_per_sample() as u8,
+            matches!(metadata.bit_depth, jxl_oxide::image::BitDepth::FloatSample { .. }),
+            metadata.grayscale(),
+            metadata.orientation,
+            metadata.xyb_encoded,
+            metadata.ec_info.iter().map(|info| info.ty).collect::<Vec<_>>(),
+            metadata.colour_encoding.clone(),
+        )
+    };
+    let source_icc = image.original_icc().map(ToOwned::to_owned);
+    let has_source_icc = source_icc.is_some();
+    if has_black_channel(&extra_channels) || image.pixel_format().has_black() {
+        return Err(Error::Unsupported("CMYK JPEG XL rendering requires an external color-management transform".into()));
+    }
+    let alpha_channel = first_alpha(&extra_channels);
+    let alpha_associated = alpha_channel.is_some_and(|(_, associated)| associated);
+    let via_srgb = output_color == OutputColor::LinearRec2020 && source_icc.is_none() && !grayscale && xyb_encoded;
+    // Associated samples must be divided while still in their coded nonlinear space. Leave these
+    // frames in their own encoding so the caller can apply its color transform after unpremultiplying.
+    // XYB and unsupported transfer curves stay on the renderer's linear target path; those cases
+    // are premultiplied after decoding instead.
+    let enum_source_has_supported_curve = matches!(
+        &colour_encoding,
+        ColourEncoding::Enum(encoding) if enum_encoding_has_supported_curve(encoding)
+    );
+    let preserve_source_encoding =
+        output_color == OutputColor::LinearRec2020 && alpha_associated && !xyb_encoded && (source_icc.is_some() || enum_source_has_supported_curve);
+    if output_color == OutputColor::LinearRec2020 && source_icc.is_none() && !preserve_source_encoding {
+        image.request_color_encoding(EnumColourEncoding {
+            colour_space: if grayscale { ColourSpace::Grey } else { ColourSpace::Rgb },
+            white_point: WhitePoint::D65,
+            primaries: if via_srgb { Primaries::Srgb } else { Primaries::Bt2100 },
+            tf: TransferFunction::Linear,
+            rendering_intent: RenderingIntent::Relative,
+        });
+    }
+    let colors = if grayscale { 1 } else { 3 };
+    let pixel_format = image.pixel_format();
+    if pixel_format.has_black() {
+        return Err(Error::Unsupported("CMYK JPEG XL rendering requires an external color-management transform".into()));
+    }
+    let has_alpha = alpha_channel.is_some();
+    let layout = match (grayscale, has_alpha) {
+        (true, false) => Layout::Gray,
+        (true, true) => Layout::GrayAlpha,
+        (false, false) => Layout::Rgb,
+        (false, true) => Layout::Rgba,
+    };
+    let keep = colors + usize::from(has_alpha);
+    let frame = image.render_frame(0).map_err(decode_error)?;
+    let buffer = frame.image_all_channels();
+    let channels = buffer.channels();
+    if channels < colors || (has_alpha && channels < keep) {
+        return Err(Error::Malformed("decoded frame has too few channels".into()));
+    }
+    let color_channels = channels
+        .checked_sub(extra_channels.len())
+        .filter(|&count| count >= colors)
+        .ok_or_else(|| Error::Malformed("decoded frame has too few color channels".into()))?;
+    let alpha_index = alpha_channel.map(|(index, _)| color_channels + index);
+    let (rendered_width, rendered_height) = (
+        u32::try_from(buffer.width()).map_err(|_| Error::LimitExceeded("rendered width exceeds 32-bit dimensions".into()))?,
+        u32::try_from(buffer.height()).map_err(|_| Error::LimitExceeded("rendered height exceeds 32-bit dimensions".into()))?,
+    );
+    let frame_pixels = u128::from(rendered_width) * u128::from(rendered_height);
+    if frame_pixels != u128::from(pixels) {
+        return Err(Error::Malformed("decoded frame dimensions do not match the image header".into()));
+    }
+    let sample_count = usize::try_from(frame_pixels.checked_mul(keep as u128).ok_or_else(|| Error::LimitExceeded("sample count overflows".into()))?)
+        .map_err(|_| Error::LimitExceeded("sample count exceeds addressable memory".into()))?;
+    let mut out = Vec::new();
+    out.try_reserve_exact(sample_count).map_err(|e| Error::LimitExceeded(format!("cannot reserve decoded pixels: {e}")))?;
+    for pixel in buffer.buf().chunks_exact(channels) {
+        let start = out.len();
+        out.extend_from_slice(&pixel[..colors]);
+        if let Some(index) = alpha_index {
+            let alpha_value = pixel.get(index).copied().ok_or_else(|| Error::Malformed("decoded frame is missing its alpha channel".into()))?;
+            if preserve_source_encoding && alpha_associated {
+                let divisor = alpha_value.clamp(0.0, 1.0);
+                if divisor > 0.0 {
+                    for channel in &mut out[start..] {
+                        *channel /= divisor;
+                    }
+                }
+            }
+            out.push(alpha_value);
+        }
+        if via_srgb {
+            let [r, g, b] = [out[start], out[start + 1], out[start + 2]];
+            out[start] = 0.627_403_9 * r + 0.329_283_04 * g + 0.043_313_067 * b;
+            out[start + 1] = 0.069_097_29 * r + 0.919_540_4 * g + 0.011_362_316 * b;
+            out[start + 2] = 0.016_391_44 * r + 0.088_013_31 * g + 0.895_595_25 * b;
+        }
+    }
+
+    let metadata = Metadata {
+        icc: source_icc,
+        exif: match image.aux_boxes().first_exif() {
+            Ok(AuxBoxData::Data(exif)) => {
+                usize::try_from(exif.tiff_header_offset()).ok().and_then(|offset| exif.payload().get(offset..)).map(ToOwned::to_owned)
+            }
+            _ => None,
+        },
+        xmp: match image.aux_boxes().first_xml() {
+            AuxBoxData::Data(xmp) => Some(xmp.to_vec()),
+            _ => None,
+        },
+    };
+    let pixels_linear_rec2020 = output_color == OutputColor::LinearRec2020 && !has_source_icc && !preserve_source_encoding;
+    Ok(Decoded {
+        width: rendered_width,
+        height: rendered_height,
+        layout,
+        bit_depth,
+        float_samples,
+        pixels: out,
+        metadata,
+        source_orientation,
+        rendered_cicp: image.rendered_cicp(),
+        rendered_icc: image.rendered_icc(),
+        xyb_encoded,
+        pixels_linear_rec2020,
+        pixels_premultiplied: alpha_associated && !preserve_source_encoding,
+    })
+}
+
+fn first_alpha(channels: &[ExtraChannelType]) -> Option<(usize, bool)> {
+    channels.iter().enumerate().find_map(|(index, channel)| match channel {
+        ExtraChannelType::Alpha { alpha_associated } => Some((index, *alpha_associated)),
+        _ => None,
+    })
+}
+
+fn has_black_channel(channels: &[ExtraChannelType]) -> bool {
+    channels.iter().any(|channel| matches!(channel, ExtraChannelType::Black))
+}
+
+fn enum_encoding_has_supported_curve(encoding: &EnumColourEncoding) -> bool {
+    matches!(encoding.colour_space, ColourSpace::Rgb | ColourSpace::Grey)
+        && match &encoding.tf {
+            TransferFunction::Linear | TransferFunction::Srgb | TransferFunction::Bt709 | TransferFunction::Dci => true,
+            TransferFunction::Gamma { g, .. } => *g > 0,
+            _ => false,
+        }
+}
+
+fn decode_error(error: impl std::fmt::Display) -> Error {
+    Error::Malformed(error.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const STRAIGHT: ExtraChannelType = ExtraChannelType::Alpha { alpha_associated: false };
+    const ASSOCIATED: ExtraChannelType = ExtraChannelType::Alpha { alpha_associated: true };
+    const SPOT: ExtraChannelType = ExtraChannelType::SpotColour { red: 1.0, green: 0.0, blue: 0.0, solidity: 1.0 };
+
+    #[test]
+    fn alpha_is_selected_by_type_and_order() {
+        assert_eq!(first_alpha(&[SPOT, STRAIGHT]), Some((1, false)));
+        assert_eq!(first_alpha(&[STRAIGHT, SPOT]), Some((0, false)));
+        assert_eq!(first_alpha(&[ExtraChannelType::Depth, ASSOCIATED, STRAIGHT]), Some((1, true)));
+        assert_eq!(first_alpha(&[ExtraChannelType::Black, SPOT, ExtraChannelType::Depth]), None);
+    }
+
+    #[test]
+    fn black_extra_channel_is_detected_by_type() {
+        assert!(has_black_channel(&[SPOT, ExtraChannelType::Black]));
+        assert!(!has_black_channel(&[SPOT, STRAIGHT]));
+    }
+
+    #[test]
+    fn only_modeled_nonlinear_enum_encodings_are_preserved_for_unpremultiplication() {
+        let mut encoding = EnumColourEncoding::srgb(RenderingIntent::Relative);
+        assert!(enum_encoding_has_supported_curve(&encoding));
+        encoding.tf = TransferFunction::Pq;
+        assert!(!enum_encoding_has_supported_curve(&encoding));
+        encoding.tf = TransferFunction::Linear;
+        assert!(enum_encoding_has_supported_curve(&encoding));
+        encoding.colour_space = ColourSpace::Xyb;
+        assert!(!enum_encoding_has_supported_curve(&encoding));
+    }
+}
diff --git a/crates/jxl/src/encode.rs b/crates/jxl/src/encode.rs
new file mode 100644
index 000000000..caf77957c
--- /dev/null
+++ b/crates/jxl/src/encode.rs
@@ -0,0 +1,236 @@
+#[cfg(not(target_arch = "wasm32"))]
+use std::panic::{AssertUnwindSafe, catch_unwind};
+
+#[cfg(not(target_arch = "wasm32"))]
+use crate::Layout;
+use crate::{Error, ImageRef, Metadata, Result, Samples};
+
+/// Encoder search effort.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum Effort {
+    /// Quickest search, with larger output files.
+    Fast,
+    /// Balanced search.
+    #[default]
+    Normal,
+}
+
+/// Color encoding declared by a JPEG XL image.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum JxlColour {
+    /// sRGB primaries and transfer curve.
+    #[default]
+    Srgb,
+    /// Display P3 primaries, D65, with the sRGB transfer curve.
+    DisplayP3,
+    /// Rec. 2020 primaries with the BT.709 transfer curve.
+    Rec2020,
+    /// Rec. 2020 primaries with the SMPTE ST 2084 PQ transfer curve.
+    Rec2020Pq,
+}
+
+/// JPEG XL encoder settings.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct EncodeOptions {
+    /// Lossy quality on a 1..=100 scale (90 is approximately visually lossless). Ignored for
+    /// mathematically lossless output.
+    pub quality: u8,
+    /// Use mathematically lossless Modular coding.
+    pub lossless: bool,
+    /// Encoder search effort.
+    pub effort: Effort,
+    /// Use progressive encoding; lossless output uses the Squeeze transform.
+    pub progressive: bool,
+    /// Color encoding to write.
+    pub colour: JxlColour,
+}
+
+impl Default for EncodeOptions {
+    fn default() -> Self {
+        Self { quality: 90, lossless: false, effort: Effort::Normal, progressive: false, colour: JxlColour::Srgb }
+    }
+}
+
+/// SDR reference white used when converting linear float input to HDR PQ, in cd/m².
+pub const HDR_REFERENCE_WHITE_NITS: f32 = 203.0;
+
+/// Encode a still image to JPEG XL.
+///
+/// Gray input is widened to RGB. Alpha is omitted when every sample is opaque. Float input is
+/// encoded only with `JxlColour::Rec2020Pq`; its linear values use SDR white at 203 cd/m².
+/// ICC data is embedded only for lossless output, where the explicit ICC profile takes precedence
+/// over the enum color encoding. Exif and XMP are embedded when supplied.
+pub fn encode(image: &ImageRef<'_>, options: EncodeOptions, metadata: &Metadata) -> Result<Vec<u8>> {
+    validate(image)?;
+    #[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+    {
+        let pixels = Pixels::from(image, options.colour)?;
+        catch_unwind(AssertUnwindSafe(|| run(&pixels, image.width as usize, image.height as usize, options, metadata)))
+            .unwrap_or_else(|_| Err(Error::Encode("encoder failed while writing this image".into())))
+    }
+    #[cfg(any(target_arch = "wasm32", not(feature = "encode")))]
+    {
+        let _ = (image, options, metadata);
+        Err(Error::Unsupported("JPEG XL encoding is unavailable on this target".into()))
+    }
+}
+
+fn validate(image: &ImageRef<'_>) -> Result<()> {
+    if image.width == 0 || image.height == 0 {
+        return Err(Error::InvalidImage("zero dimension".into()));
+    }
+    let pixels = u128::from(image.width) * u128::from(image.height);
+    let samples = pixels * image.layout.channels() as u128;
+    if samples > usize::MAX as u128 {
+        return Err(Error::InvalidImage("image sample count exceeds addressable memory".into()));
+    }
+    let have = match image.samples {
+        Samples::U8(data) => data.len(),
+        Samples::U16(data) => data.len(),
+        Samples::F32(data) => data.len(),
+    };
+    if have < samples as usize {
+        return Err(Error::InvalidImage(format!("sample buffer has {have} samples, expected at least {samples}")));
+    }
+    Ok(())
+}
+
+#[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+enum Pixels {
+    U8 { data: Vec<u8>, alpha: bool },
+    U16 { data: Vec<u16>, alpha: bool },
+}
+
+#[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+impl Pixels {
+    fn from(image: &ImageRef<'_>, colour: JxlColour) -> Result<Self> {
+        let n = usize::try_from(u64::from(image.width) * u64::from(image.height))
+            .map_err(|_| Error::InvalidImage("image pixel count exceeds addressable memory".into()))?;
+        Ok(match image.samples {
+            Samples::U8(samples) => {
+                let (data, alpha) = convert(samples, image.layout, n, |a| a == u8::MAX)?;
+                Pixels::U8 { data, alpha }
+            }
+            Samples::U16(samples) => {
+                let (data, alpha) = convert(samples, image.layout, n, |a| a == u16::MAX)?;
+                Pixels::U16 { data, alpha }
+            }
+            Samples::F32(samples) if colour == JxlColour::Rec2020Pq => {
+                let count = n.checked_mul(4).ok_or_else(|| Error::InvalidImage("pixel buffer size overflows".into()))?;
+                let mut encoded = Vec::new();
+                encoded.try_reserve_exact(count).map_err(|e| Error::InvalidImage(format!("cannot reserve pixel buffer: {e}")))?;
+                for pixel in samples.chunks_exact(image.layout.channels()).take(n) {
+                    let (rgb, alpha) = pixel_to_rgba(pixel, image.layout);
+                    for channel in rgb {
+                        encoded.push(pq_sample(channel));
+                    }
+                    encoded.push(alpha_sample(alpha));
+                }
+                let (data, alpha) = convert(&encoded, Layout::Rgba, n, |a| a == u16::MAX)?;
+                Pixels::U16 { data, alpha }
+            }
+            Samples::F32(_) => return Err(Error::InvalidImage("float samples require Rec. 2020 PQ encoding".into())),
+        })
+    }
+}
+
+#[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+fn convert<T: Copy>(samples: &[T], layout: Layout, pixels: usize, opaque: impl Fn(T) -> bool) -> Result<(Vec<T>, bool)> {
+    let channels = layout.channels();
+    let input = samples
+        .get(..pixels.checked_mul(channels).ok_or_else(|| Error::InvalidImage("sample count overflows".into()))?)
+        .ok_or_else(|| Error::InvalidImage("sample buffer is too short".into()))?;
+    let alpha = layout.has_alpha() && input.chunks_exact(channels).any(|p| p.last().is_some_and(|a| !opaque(*a)));
+    let output_channels = if alpha { 4 } else { 3 };
+    let output_count = pixels.checked_mul(output_channels).ok_or_else(|| Error::InvalidImage("converted sample count overflows".into()))?;
+    let mut out = Vec::new();
+    out.try_reserve_exact(output_count).map_err(|e| Error::InvalidImage(format!("cannot reserve converted samples: {e}")))?;
+    for pixel in input.chunks_exact(channels) {
+        match (layout, pixel) {
+            (Layout::Gray, [g]) => out.extend_from_slice(&[*g, *g, *g]),
+            (Layout::GrayAlpha, [g, a]) if alpha => out.extend_from_slice(&[*g, *g, *g, *a]),
+            (Layout::GrayAlpha, [g, _]) => out.extend_from_slice(&[*g, *g, *g]),
+            (Layout::Rgb, [r, g, b]) => out.extend_from_slice(&[*r, *g, *b]),
+            (Layout::Rgba, [r, g, b, a]) if alpha => out.extend_from_slice(&[*r, *g, *b, *a]),
+            (Layout::Rgba, [r, g, b, _]) => out.extend_from_slice(&[*r, *g, *b]),
+            _ => return Err(Error::InvalidImage("unsupported pixel layout".into())),
+        }
+    }
+    Ok((out, alpha))
+}
+
+#[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+fn pixel_to_rgba(pixel: &[f32], layout: Layout) -> ([f32; 3], f32) {
+    let finite = |v: f32| if v.is_finite() { v } else { 0.0 };
+    match (layout, pixel) {
+        (Layout::Gray, [g]) => ([finite(*g); 3], 1.0),
+        (Layout::GrayAlpha, [g, a]) => ([finite(*g); 3], finite(*a).clamp(0.0, 1.0)),
+        (Layout::Rgb, [r, g, b]) => ([finite(*r), finite(*g), finite(*b)], 1.0),
+        (Layout::Rgba, [r, g, b, a]) => ([finite(*r), finite(*g), finite(*b)], finite(*a).clamp(0.0, 1.0)),
+        _ => ([0.0; 3], 1.0),
+    }
+}
+
+#[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+fn pq_sample(value: f32) -> u16 {
+    let linear_nits = (if value.is_finite() { value.max(0.0) } else { 0.0 }) * HDR_REFERENCE_WHITE_NITS;
+    (pq_encode(linear_nits) * 65535.0).round().clamp(0.0, 65535.0) as u16
+}
+
+#[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+fn alpha_sample(value: f32) -> u16 {
+    ((if value.is_finite() { value.clamp(0.0, 1.0) } else { 1.0 }) * 65535.0).round() as u16
+}
+
+#[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+fn pq_encode(nits: f32) -> f32 {
+    const M1: f32 = 2610.0 / 16384.0;
+    const M2: f32 = 2523.0 / 4096.0 * 128.0;
+    const C1: f32 = 3424.0 / 4096.0;
+    const C2: f32 = 2413.0 / 4096.0 * 32.0;
+    const C3: f32 = 2392.0 / 4096.0 * 32.0;
+    let y = (nits / 10_000.0).clamp(0.0, 1.0).powf(M1);
+    ((C1 + C2 * y) / (1.0 + C3 * y)).powf(M2)
+}
+
+#[cfg(all(not(target_arch = "wasm32"), feature = "encode"))]
+fn run(pixels: &Pixels, width: usize, height: usize, options: EncodeOptions, metadata: &Metadata) -> Result<Vec<u8>> {
+    use jixel::{ColorEncoding, EncodeConfig, Primaries, Speed, TransferFunction};
+
+    let colour = match options.colour {
+        JxlColour::Srgb => ColorEncoding::srgb(),
+        JxlColour::DisplayP3 => ColorEncoding::display_p3(),
+        JxlColour::Rec2020 => ColorEncoding { primaries: Primaries::Bt2020, transfer: TransferFunction::Bt709, ..ColorEncoding::srgb() },
+        JxlColour::Rec2020Pq => ColorEncoding::bt2020_pq(),
+    };
+    let mut config = EncodeConfig::default()
+        .with_quality(f32::from(options.quality.clamp(1, 100)))
+        .with_color_encoding(colour)
+        .with_lossless(options.lossless)
+        .with_progressive(options.progressive)
+        .with_speed(match options.effort {
+            Effort::Fast => Speed::Fastest,
+            Effort::Normal => Speed::Fast,
+        });
+    if options.colour == JxlColour::Rec2020Pq {
+        config = config.with_intensity_target(10_000.0);
+    }
+    if options.lossless
+        && let Some(icc) = &metadata.icc
+    {
+        config = config.with_icc_profile(icc.clone());
+    }
+    if let Some(exif) = &metadata.exif {
+        config = config.with_exif(exif.clone());
+    }
+    if let Some(xmp) = &metadata.xmp {
+        config = config.with_xmp(xmp.clone());
+    }
+    let result = match pixels {
+        Pixels::U8 { data, alpha: false } => jixel::encode_image(data, width, height, &config),
+        Pixels::U8 { data, alpha: true } => jixel::encode_image_with_alpha(data, width, height, &config),
+        Pixels::U16 { data, alpha: false } => jixel::encode_image_16bit(data, width, height, &config),
+        Pixels::U16 { data, alpha: true } => jixel::encode_image_with_alpha_16bit(data, width, height, &config),
+    };
+    result.map_err(|error| Error::Encode(error.to_string()))
+}
diff --git a/crates/jxl/src/lib.rs b/crates/jxl/src/lib.rs
new file mode 100644
index 000000000..fcdd96199
--- /dev/null
+++ b/crates/jxl/src/lib.rs
@@ -0,0 +1,186 @@
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+#![forbid(unsafe_code)]
+#![warn(missing_docs)]
+//! JPEG XL image decoding and encoding.
+//!
+//! Decoding incrementally feeds the input, checks image dimensions before loading remaining
+//! frames, and applies a tracked-allocation budget. The allocation tracker covers allocations
+//! made through `jxl-oxide`; it cannot account for every allocation inside a decoder dependency.
+//! The first image frame is returned, with orientation already applied to its pixels.
+
+#[cfg(feature = "decode")]
+mod decode;
+#[cfg(feature = "encode")]
+mod encode;
+
+/// Pixel channel layout.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Layout {
+    /// One grayscale channel.
+    Gray,
+    /// Grayscale and straight alpha.
+    GrayAlpha,
+    /// Red, green, blue.
+    Rgb,
+    /// Red, green, blue and straight alpha.
+    Rgba,
+}
+
+/// Color encoding requested for rendered pixels.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum OutputColor {
+    /// Use `jxl-oxide`'s default rendering target and report its rendered profile.
+    #[default]
+    DecoderDefault,
+    /// For files with enum color encoding, render linear Rec. 2020. XYB files render to linear
+    /// sRGB first and are converted to Rec. 2020 to avoid a `jxl-oxide` wide-gamut XYB issue.
+    /// Files with an embedded ICC profile remain rendered in that profile's space; the source
+    /// ICC is returned in [`Metadata::icc`] because this crate does not bundle an ICC CMS.
+    LinearRec2020,
+}
+
+impl Layout {
+    /// Number of interleaved channels.
+    pub const fn channels(self) -> usize {
+        match self {
+            Layout::Gray => 1,
+            Layout::GrayAlpha => 2,
+            Layout::Rgb => 3,
+            Layout::Rgba => 4,
+        }
+    }
+
+    /// Whether this layout includes alpha.
+    pub const fn has_alpha(self) -> bool {
+        matches!(self, Layout::GrayAlpha | Layout::Rgba)
+    }
+}
+
+/// Sample data accepted by the encoder.
+#[derive(Clone, Copy, Debug)]
+pub enum Samples<'a> {
+    /// Unsigned 8-bit samples, already encoded using the selected color transfer curve.
+    U8(&'a [u8]),
+    /// Unsigned 16-bit samples, already encoded using the selected color transfer curve.
+    U16(&'a [u16]),
+    /// Floating point samples. These are accepted only for Rec. 2020 PQ encoding.
+    F32(&'a [f32]),
+}
+
+/// A borrowed image to encode. Samples are interleaved and alpha is straight.
+#[derive(Clone, Copy, Debug)]
+pub struct ImageRef<'a> {
+    /// Width in pixels.
+    pub width: u32,
+    /// Height in pixels.
+    pub height: u32,
+    /// Channel layout.
+    pub layout: Layout,
+    /// Interleaved sample data.
+    pub samples: Samples<'a>,
+}
+
+/// Metadata embedded in the JPEG XL container.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct Metadata {
+    /// ICC profile bytes, when present.
+    pub icc: Option<Vec<u8>>,
+    /// TIFF-structured Exif payload, without an `Exif\0\0` prefix.
+    pub exif: Option<Vec<u8>>,
+    /// XMP packet bytes.
+    pub xmp: Option<Vec<u8>>,
+}
+
+/// JPEG XL operation error.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    /// The image is malformed or cannot be decoded.
+    #[error("JPEG XL: malformed image: {0}")]
+    Malformed(String),
+    /// The image exceeds a caller supplied size or allocation limit.
+    #[error("JPEG XL: limit exceeded: {0}")]
+    LimitExceeded(String),
+    /// The encoded dimensions exceed the caller's pixel-count limit.
+    #[error("JPEG XL: image dimensions {width}×{height} exceed the {max_pixels} pixel limit")]
+    PixelLimitExceeded {
+        /// Encoded image width.
+        width: u32,
+        /// Encoded image height.
+        height: u32,
+        /// Maximum accepted pixel count.
+        max_pixels: u64,
+    },
+    /// The image layout or samples are unsupported.
+    #[error("JPEG XL: invalid image: {0}")]
+    InvalidImage(String),
+    /// Encoding failed.
+    #[error("JPEG XL: encode failed: {0}")]
+    Encode(String),
+    /// The requested operation is not available in this build.
+    #[error("JPEG XL: unsupported: {0}")]
+    Unsupported(String),
+}
+
+/// Result returned by this crate.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Decoded first frame and source metadata.
+#[cfg(feature = "decode")]
+#[derive(Clone, Debug)]
+pub struct Decoded {
+    /// Width after applying the codestream orientation.
+    pub width: u32,
+    /// Height after applying the codestream orientation.
+    pub height: u32,
+    /// Output channel layout.
+    pub layout: Layout,
+    /// Bits per sample signalled in the file.
+    pub bit_depth: u8,
+    /// Whether the source samples use a floating-point representation.
+    pub float_samples: bool,
+    /// Interleaved floating point samples in the decoder's rendered color encoding.
+    pub pixels: Vec<f32>,
+    /// Metadata from the source image.
+    pub metadata: Metadata,
+    /// Original orientation value. Pixels in `pixels` already have this orientation applied.
+    pub source_orientation: u32,
+    /// CICP value describing the rendered pixel encoding, when the decoder supplies one.
+    pub rendered_cicp: Option<[u8; 4]>,
+    /// ICC profile describing the rendered pixel encoding.
+    pub rendered_icc: Vec<u8>,
+    /// Whether the codestream uses XYB encoding.
+    pub xyb_encoded: bool,
+    /// Whether `pixels` are linear Rec. 2020. This is false when associated alpha requires keeping
+    /// a modeled nonlinear source encoding so the caller can unpremultiply before its color transform.
+    pub pixels_linear_rec2020: bool,
+    /// Whether color samples in `pixels` remain associated with alpha. When true, divide them by
+    /// alpha after any necessary transfer conversion; at zero alpha the color values are undefined.
+    pub pixels_premultiplied: bool,
+}
+
+/// Options for bounded decoding.
+#[cfg(feature = "decode")]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct DecodeLimits {
+    /// Largest accepted pixel count. Defaults to 1 gigapixel.
+    pub max_pixels: u64,
+    /// Maximum allocation budget passed to `jxl-oxide`'s tracked allocator. `None` scales the
+    /// budget from `max_pixels` and preserves fixed decoder overhead for small images.
+    pub max_tracked_bytes: Option<u64>,
+    /// Largest compressed input size. Defaults to `usize::MAX`.
+    pub max_input_bytes: usize,
+}
+
+#[cfg(feature = "decode")]
+impl Default for DecodeLimits {
+    fn default() -> Self {
+        Self { max_pixels: 1 << 30, max_tracked_bytes: None, max_input_bytes: usize::MAX }
+    }
+}
+
+/// Decode the first image frame.
+#[cfg(feature = "decode")]
+pub use decode::{decode, decode_with_color};
+/// Encode a JPEG XL image.
+#[cfg(feature = "encode")]
+pub use encode::{Effort, EncodeOptions, HDR_REFERENCE_WHITE_NITS, JxlColour, encode};
diff --git a/crates/jxl/tests/roundtrip.rs b/crates/jxl/tests/roundtrip.rs
new file mode 100644
index 000000000..2bc4cf8e1
--- /dev/null
+++ b/crates/jxl/tests/roundtrip.rs
@@ -0,0 +1,425 @@
+use craft_jxl::{
+    DecodeLimits, EncodeOptions, HDR_REFERENCE_WHITE_NITS, ImageRef, JxlColour, Layout, Metadata, OutputColor, Samples, decode, decode_with_color,
+    encode,
+};
+
+fn raw_codestream(bytes: &[u8]) -> Vec<u8> {
+    if bytes.starts_with(b"\xff\x0a") {
+        return bytes.to_vec();
+    }
+    let mut raw = Vec::new();
+    let mut at = 12_usize;
+    while at.checked_add(8).is_some_and(|end| end <= bytes.len()) {
+        let Some(size) = bytes.get(at..at + 4).and_then(|s| s.try_into().ok()).map(u32::from_be_bytes) else { break };
+        let end = if size == 0 { bytes.len() } else { at.saturating_add(size as usize) };
+        let Some(kind) = bytes.get(at + 4..at + 8) else { break };
+        if end < at + 8 || end > bytes.len() {
+            break;
+        }
+        let header = if kind == b"jxlp" { 12 } else { 8 };
+        if (kind == b"jxlc" || kind == b"jxlp")
+            && let Some(data) = bytes.get(at + header..end)
+        {
+            raw.extend_from_slice(data);
+        }
+        if end <= at {
+            break;
+        }
+        at = end;
+    }
+    raw
+}
+
+fn box_bytes(out: &mut Vec<u8>, kind: &[u8; 4], data: &[u8]) {
+    out.extend_from_slice(&u32::try_from(data.len() + 8).unwrap_or(u32::MAX).to_be_bytes());
+    out.extend_from_slice(kind);
+    out.extend_from_slice(data);
+}
+
+#[test]
+fn lossless_rgba_roundtrip_keeps_alpha_layout() {
+    let samples = [255, 0, 0, 255, 0, 255, 0, 64];
+    let image = ImageRef { width: 2, height: 1, layout: Layout::Rgba, samples: Samples::U8(&samples) };
+    let exif = b"II*\0\x08\0\0\0\x01\0\x12\x01\x03\0\x01\0\0\0\x01\0\0\0\0\0\0\0";
+    let xmp = b"<xmp/>";
+    let metadata = Metadata { exif: Some(exif.to_vec()), xmp: Some(xmp.to_vec()), ..Metadata::default() };
+    let encoded = encode(&image, EncodeOptions { lossless: true, ..EncodeOptions::default() }, &metadata);
+    assert!(encoded.is_ok(), "valid image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+    let decoded = decode(&encoded, DecodeLimits::default());
+    assert!(decoded.is_ok(), "encoded image should decode: {decoded:?}");
+    let Ok(decoded) = decoded else { return };
+
+    assert_eq!((decoded.width, decoded.height), (2, 1));
+    assert_eq!(decoded.layout, Layout::Rgba);
+    assert_eq!(decoded.pixels.len(), 8);
+    assert_eq!(decoded.pixels[3], 1.0);
+    assert!((decoded.pixels[7] - 64.0 / 255.0).abs() < 0.01);
+    assert_eq!(decoded.metadata.exif.as_deref(), Some(exif.as_slice()));
+    assert_eq!(decoded.metadata.xmp.as_deref(), Some(xmp.as_slice()));
+}
+
+#[test]
+fn exif_payload_starts_at_its_declared_tiff_header_offset() {
+    let image = ImageRef { width: 2, height: 1, layout: Layout::Rgb, samples: Samples::U8(&[10, 20, 30, 40, 50, 60]) };
+    let encoded = encode(&image, EncodeOptions { lossless: true, ..EncodeOptions::default() }, &Metadata::default());
+    assert!(encoded.is_ok(), "valid image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+    let raw = raw_codestream(&encoded);
+    let exif = b"II*\0\x08\0\0\0\0\0\0\0";
+
+    for offset in [0_u32, 6, 64] {
+        let mut exif_box = offset.to_be_bytes().to_vec();
+        exif_box.resize(4 + offset as usize, 0xab);
+        exif_box.extend_from_slice(exif);
+        let mut container = b"\0\0\0\x0cJXL \x0d\x0a\x87\x0a".to_vec();
+        box_bytes(&mut container, b"ftyp", b"jxl \0\0\0\0jxl ");
+        box_bytes(&mut container, b"jxlc", &raw);
+        box_bytes(&mut container, b"Exif", &exif_box);
+
+        let decoded = decode(&container, DecodeLimits::default());
+        assert!(decoded.is_ok(), "container with Exif offset {offset} should decode: {decoded:?}");
+        let Ok(decoded) = decoded else { return };
+        assert_eq!(decoded.metadata.exif.as_deref(), Some(exif.as_slice()), "TIFF header offset {offset}");
+    }
+}
+
+#[test]
+#[cfg(not(target_arch = "wasm32"))]
+fn associated_alpha_is_unpremultiplied_before_color_conversion() {
+    let straight = [[200_u8, 100, 50, 128], [30, 180, 240, 192], [100, 80, 60, 255], [220, 110, 40, 160]];
+    let mut premultiplied = Vec::with_capacity(straight.len() * 4);
+    for pixel in &straight {
+        let alpha = f32::from(pixel[3]) / 255.0;
+        premultiplied.extend(pixel[..3].iter().map(|channel| (f32::from(*channel) * alpha).round() as u8));
+        premultiplied.push(pixel[3]);
+    }
+    let metadata = jixel::FlMeta { alpha_premultiplied: true, ..jixel::FlMeta::srgb() };
+    let encoded = jixel::encode_fast_lossless(&premultiplied, 2, 2, jixel::ColorSpace::Rgb, true, &metadata);
+    assert!(encoded.is_ok(), "associated-alpha image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+
+    let decoded = decode_with_color(&encoded, DecodeLimits::default(), OutputColor::LinearRec2020);
+    assert!(decoded.is_ok(), "associated-alpha image should decode: {decoded:?}");
+    let Ok(decoded) = decoded else { return };
+    assert_eq!(decoded.layout, Layout::Rgba);
+    assert!(!decoded.pixels_linear_rec2020, "the source encoding is needed for the caller's color transform");
+    assert!(!decoded.pixels_premultiplied, "associated color samples must be divided before nonlinear conversion");
+
+    for (i, source) in straight.iter().enumerate() {
+        let alpha = f32::from(source[3]) / 255.0;
+        assert!((decoded.pixels[i * 4 + 3] - alpha).abs() < 1e-6);
+        for (channel, &value) in source[..3].iter().enumerate() {
+            let expected = f32::from(value) / 255.0;
+            assert!((decoded.pixels[i * 4 + channel] - expected).abs() < 0.01, "pixel {i}, channel {channel}");
+        }
+    }
+}
+
+#[test]
+fn decoder_enforces_input_and_pixel_limits() {
+    let samples = [10_u8, 20, 30];
+    let image = ImageRef { width: 1, height: 1, layout: Layout::Rgb, samples: Samples::U8(&samples) };
+    let encoded = encode(&image, EncodeOptions { lossless: true, ..EncodeOptions::default() }, &Metadata::default());
+    assert!(encoded.is_ok(), "valid image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+
+    let input_limit = DecodeLimits { max_input_bytes: encoded.len() - 1, ..DecodeLimits::default() };
+    assert!(matches!(decode(&encoded, input_limit), Err(craft_jxl::Error::LimitExceeded(_))));
+    let pixel_limit = DecodeLimits { max_pixels: 0, ..DecodeLimits::default() };
+    assert!(matches!(decode(&encoded, pixel_limit), Err(craft_jxl::Error::PixelLimitExceeded { width: 1, height: 1, max_pixels: 0 })));
+}
+
+#[test]
+fn malformed_input_returns_an_error() {
+    assert!(decode(b"not a JPEG XL file", DecodeLimits::default()).is_err());
+}
+
+#[test]
+fn encoder_rejects_short_sample_buffers() {
+    let image = ImageRef { width: 2, height: 1, layout: Layout::Rgb, samples: Samples::U8(&[1, 2, 3]) };
+    assert!(matches!(encode(&image, EncodeOptions::default(), &Metadata::default()), Err(craft_jxl::Error::InvalidImage(_))));
+}
+
+#[test]
+fn lossless_gray_input_is_expanded_to_rgb() {
+    let samples = [0, 40, 128, 255];
+    let image = ImageRef { width: 4, height: 1, layout: Layout::Gray, samples: Samples::U8(&samples) };
+    let encoded = encode(&image, EncodeOptions { lossless: true, ..EncodeOptions::default() }, &Metadata::default());
+    assert!(encoded.is_ok(), "valid grayscale image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+    let decoded = decode(&encoded, DecodeLimits::default());
+    assert!(decoded.is_ok(), "grayscale image should decode: {decoded:?}");
+    let Ok(decoded) = decoded else { return };
+    assert_eq!(decoded.layout, Layout::Rgb);
+    assert_eq!(decoded.pixels.len(), 4 * 3);
+    let (pixels, remainder) = decoded.pixels.as_chunks::<3>();
+    assert!(remainder.is_empty());
+    for (pixel, gray) in pixels.iter().zip(samples) {
+        let expected = f32::from(gray) / 255.0;
+        assert!(pixel.iter().all(|channel| (channel - expected).abs() < 0.01));
+    }
+}
+
+#[test]
+fn lossless_u16_samples_keep_their_bit_depth_and_values() {
+    let samples: Vec<u16> = (0..40 * 30 * 3).map(|i| (i as u32 * 2741 % 65536) as u16).collect();
+    let image = ImageRef { width: 40, height: 30, layout: Layout::Rgb, samples: Samples::U16(&samples) };
+    let encoded = encode(&image, EncodeOptions { lossless: true, ..EncodeOptions::default() }, &Metadata::default());
+    assert!(encoded.is_ok(), "valid 16-bit image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+    let decoded = decode(&encoded, DecodeLimits::default());
+    assert!(decoded.is_ok(), "16-bit image should decode: {decoded:?}");
+    let Ok(decoded) = decoded else { return };
+    assert_eq!(decoded.bit_depth, 16);
+    assert_eq!(decoded.layout, Layout::Rgb);
+    assert_eq!(decoded.pixels.len(), samples.len());
+    for (got, sample) in decoded.pixels.iter().zip(samples) {
+        let expected = f32::from(sample) / 65535.0;
+        assert!((got - expected).abs() < 1e-5, "16-bit value differs: {got} vs {expected}");
+    }
+}
+
+#[test]
+fn enum_encoded_pixels_can_be_rendered_as_linear_rec2020() {
+    let samples = [180, 40, 20, 10, 140, 60, 20, 80, 180];
+    let image = ImageRef { width: 3, height: 1, layout: Layout::Rgb, samples: Samples::U8(&samples) };
+    let encoded = encode(&image, EncodeOptions { lossless: true, colour: JxlColour::Rec2020, ..EncodeOptions::default() }, &Metadata::default());
+    assert!(encoded.is_ok(), "valid image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+    let decoded = decode_with_color(&encoded, DecodeLimits::default(), OutputColor::LinearRec2020);
+    assert!(decoded.is_ok(), "valid image should decode: {decoded:?}");
+    let Ok(decoded) = decoded else { return };
+
+    assert!(!decoded.xyb_encoded, "lossless enum encoding should use Modular coding");
+    assert_eq!(decoded.layout, Layout::Rgb);
+    assert_eq!((decoded.width, decoded.height), (3, 1));
+    assert!(decoded.pixels.iter().all(|sample| sample.is_finite()));
+    assert!(decoded.rendered_icc.len() > 128, "requested Rec. 2020 linear target has a rendered profile");
+}
+
+#[test]
+fn xybcoded_pixels_use_the_linear_srgb_workaround_before_rec2020() {
+    let samples = [
+        250, 5, 5, 128, 10, 240, 10, 255, 5, 10, 250, 255, 190, 130, 40, 255, 120, 20, 170, 255, 20, 160, 180, 255, 240, 230, 10, 255, 80, 90, 100,
+        255,
+    ];
+    let image = ImageRef { width: 4, height: 2, layout: Layout::Rgba, samples: Samples::U8(&samples) };
+    let encoded = encode(&image, EncodeOptions { quality: 95, colour: JxlColour::Srgb, ..EncodeOptions::default() }, &Metadata::default());
+    assert!(encoded.is_ok(), "valid image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+    let decoded = decode_with_color(&encoded, DecodeLimits::default(), OutputColor::LinearRec2020);
+    assert!(decoded.is_ok(), "valid image should decode: {decoded:?}");
+    let Ok(decoded) = decoded else { return };
+
+    assert!(decoded.xyb_encoded, "lossy RGB JPEG XL should use XYB");
+    assert_eq!(decoded.layout, Layout::Rgba);
+    assert_eq!(decoded.pixels.len(), 4 * 2 * 4);
+    let (decoded_pixels, decoded_remainder) = decoded.pixels.as_chunks::<4>();
+    assert!(decoded_remainder.is_empty());
+    assert!(decoded_pixels.iter().all(|pixel| (0.0..=1.0).contains(&pixel[3])));
+    assert!(decoded.pixels.iter().all(|sample| sample.is_finite()));
+
+    let reference = jxl_oxide::JxlImage::builder().read(encoded.as_slice());
+    assert!(reference.is_ok(), "reference decoder should accept the encoded image: {reference:?}");
+    let Ok(mut reference) = reference else { return };
+    reference.request_color_encoding(jxl_oxide::color::EnumColourEncoding {
+        colour_space: jxl_oxide::color::ColourSpace::Rgb,
+        white_point: jxl_oxide::color::WhitePoint::D65,
+        primaries: jxl_oxide::color::Primaries::Srgb,
+        tf: jxl_oxide::color::TransferFunction::Linear,
+        rendering_intent: jxl_oxide::color::RenderingIntent::Relative,
+    });
+    let reference_frame = reference.render_frame(0);
+    assert!(reference_frame.is_ok(), "reference frame should render: {reference_frame:?}");
+    let Ok(reference_frame) = reference_frame else { return };
+    let reference = reference_frame.image_all_channels();
+    assert_eq!(reference.channels(), 4);
+    let (actual_pixels, actual_remainder) = decoded.pixels.as_chunks::<4>();
+    let (reference_pixels, reference_remainder) = reference.buf().as_chunks::<4>();
+    assert!(actual_remainder.is_empty());
+    assert!(reference_remainder.is_empty());
+    for (actual, linear_srgb) in actual_pixels.iter().zip(reference_pixels) {
+        let [r, g, b] = [linear_srgb[0], linear_srgb[1], linear_srgb[2]];
+        let expected = [
+            0.627_403_9 * r + 0.329_283_04 * g + 0.043_313_067 * b,
+            0.069_097_29 * r + 0.919_540_4 * g + 0.011_362_316 * b,
+            0.016_391_44 * r + 0.088_013_31 * g + 0.895_595_25 * b,
+        ];
+        for (got, want) in actual[..3].iter().zip(expected) {
+            assert!((got - want).abs() < 1e-6, "linear Rec. 2020 channel differs: {got} vs {want}");
+        }
+        assert_eq!(actual[3], linear_srgb[3], "color conversion leaves alpha unchanged");
+    }
+}
+
+#[test]
+fn icc_encoded_pixels_keep_the_embedded_profile_under_linear_target_request() {
+    let samples = [180, 40, 20, 10, 140, 60, 20, 80, 180];
+    let image = ImageRef { width: 3, height: 1, layout: Layout::Rgb, samples: Samples::U8(&samples) };
+    let icc = craft_cms::Builtin::DisplayP3.profile().to_bytes();
+    let metadata = Metadata { icc: Some(icc.as_ref().clone()), ..Metadata::default() };
+    let encoded = encode(&image, EncodeOptions { lossless: true, colour: JxlColour::DisplayP3, ..EncodeOptions::default() }, &metadata);
+    assert!(encoded.is_ok(), "valid image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+    let decoder_default = decode(&encoded, DecodeLimits::default());
+    let linear_request = decode_with_color(&encoded, DecodeLimits::default(), OutputColor::LinearRec2020);
+    assert!(decoder_default.is_ok(), "ICC image should decode: {decoder_default:?}");
+    assert!(linear_request.is_ok(), "ICC image should decode: {linear_request:?}");
+    let (Ok(decoder_default), Ok(linear_request)) = (decoder_default, linear_request) else { return };
+
+    assert_eq!(decoder_default.metadata.icc.as_deref(), Some(icc.as_slice()));
+    assert_eq!(linear_request.metadata.icc.as_deref(), Some(icc.as_slice()));
+    assert_eq!(decoder_default.pixels, linear_request.pixels, "without a bundled CMS, the requested target preserves ICC-space samples");
+}
+
+#[test]
+fn lossy_quality_effort_and_progressive_options_produce_decodable_images() {
+    let (width, height) = (160_u32, 120_u32);
+    let mut samples = Vec::with_capacity(width as usize * height as usize * 4);
+    for y in 0..height {
+        for x in 0..width {
+            let fx = x as f32 / width as f32;
+            let fy = y as f32 / height as f32;
+            samples.extend_from_slice(&[(fx * 255.0) as u8, (fy * 255.0) as u8, ((1.0 - fx) * 200.0) as u8, (((fx + fy) * 0.5) * 255.0) as u8]);
+        }
+    }
+    let image = ImageRef { width, height, layout: Layout::Rgba, samples: Samples::U8(&samples) };
+    let encode_options = |quality, effort, progressive| EncodeOptions { quality, effort, progressive, ..EncodeOptions::default() };
+    let hi = encode(&image, encode_options(95, craft_jxl::Effort::Normal, false), &Metadata::default());
+    let lo = encode(&image, encode_options(40, craft_jxl::Effort::Normal, false), &Metadata::default());
+    assert!(hi.is_ok(), "high-quality image should encode: {hi:?}");
+    assert!(lo.is_ok(), "low-quality image should encode: {lo:?}");
+    let (Ok(hi), Ok(lo)) = (hi, lo) else { return };
+    assert!(lo.len() < hi.len(), "quality 40 output {} should be smaller than quality 95 output {}", lo.len(), hi.len());
+
+    for bytes in [&hi, &lo] {
+        let decoded = decode(bytes, DecodeLimits::default());
+        assert!(decoded.is_ok(), "encoded image should decode: {decoded:?}");
+        let Ok(decoded) = decoded else { return };
+        assert_eq!((decoded.width, decoded.height), (width, height));
+        assert_eq!(decoded.layout, Layout::Rgba);
+        let threshold = if bytes.len() == hi.len() { 38.0 } else { 28.0 };
+        let psnr = psnr8(&samples, &decoded.pixels, 4);
+        assert!(psnr > threshold, "PSNR {psnr:.2} dB must exceed {threshold:.1} dB");
+    }
+
+    for effort in [craft_jxl::Effort::Fast, craft_jxl::Effort::Normal] {
+        for progressive in [false, true] {
+            let encoded = encode(&image, encode_options(90, effort, progressive), &Metadata::default());
+            assert!(encoded.is_ok(), "{effort:?} progressive={progressive} should encode: {encoded:?}");
+            let Ok(encoded) = encoded else { return };
+            let decoded = decode(&encoded, DecodeLimits::default());
+            assert!(decoded.is_ok(), "{effort:?} progressive={progressive} should decode: {decoded:?}");
+            let Ok(decoded) = decoded else { return };
+            let psnr = psnr8(&samples, &decoded.pixels, 4);
+            assert!(psnr > 34.0, "{effort:?} progressive={progressive} PSNR {psnr:.2} dB");
+        }
+    }
+}
+
+fn psnr8(source: &[u8], decoded: &[f32], channels: usize) -> f64 {
+    let mut squared_error = 0.0;
+    for (source, decoded) in source.chunks_exact(channels).zip(decoded.chunks_exact(channels)) {
+        for channel in 0..3 {
+            let difference = f64::from(source[channel]) - f64::from(decoded[channel] * 255.0);
+            squared_error += difference * difference;
+        }
+    }
+    let samples = (source.len() / channels * 3) as f64;
+    let mse = squared_error / samples;
+    if mse == 0.0 { f64::INFINITY } else { 10.0 * (255.0 * 255.0 / mse).log10() }
+}
+
+#[test]
+fn rec2020_pq_float_samples_are_written_as_hdr() {
+    let (width, height) = (64_u32, 32_u32);
+    let samples: Vec<f32> =
+        (0..(width * height) as usize).flat_map(|i| [if i % (width as usize) < width as usize / 2 { 1.0 } else { 4.0 }; 3]).collect();
+    let image = ImageRef { width, height, layout: Layout::Rgb, samples: Samples::F32(&samples) };
+    for lossless in [false, true] {
+        let encoded =
+            encode(&image, EncodeOptions { lossless, quality: 95, colour: JxlColour::Rec2020Pq, ..EncodeOptions::default() }, &Metadata::default());
+        assert!(encoded.is_ok(), "HDR image should encode: {encoded:?}");
+        let Ok(encoded) = encoded else { return };
+        let decoded = jxl_oxide::JxlImage::builder().read(encoded.as_slice());
+        assert!(decoded.is_ok(), "reference decoder should read HDR output: {decoded:?}");
+        let Ok(decoded) = decoded else { return };
+        let metadata = &decoded.image_header().metadata;
+        assert_eq!(metadata.tone_mapping.intensity_target, 10_000.0);
+        assert!(format!("{:?}", metadata.colour_encoding).contains("Pq"), "{:?}", metadata.colour_encoding);
+        let frame = decoded.render_frame(0);
+        assert!(frame.is_ok(), "reference decoder should render HDR output: {frame:?}");
+        let Ok(frame) = frame else { return };
+        let buffer = frame.image_all_channels();
+        let channels = buffer.channels();
+        assert!(channels >= 3);
+        let sample_at = |x: usize| buffer.buf()[((height as usize / 2) * width as usize + x) * channels + 1];
+        for (x, nits) in [(width as usize / 4, HDR_REFERENCE_WHITE_NITS), (width as usize * 3 / 4, 4.0 * HDR_REFERENCE_WHITE_NITS)] {
+            let encoded_pq = pq_encode(nits);
+            let actual = sample_at(x);
+            assert!((actual - encoded_pq).abs() < 0.005, "lossless={lossless}: {nits} nits encoded as {actual}, expected {encoded_pq}");
+        }
+    }
+    assert!(matches!(encode(&image, EncodeOptions::default(), &Metadata::default()), Err(craft_jxl::Error::InvalidImage(_))));
+}
+
+fn pq_encode(nits: f32) -> f32 {
+    const M1: f32 = 2610.0 / 16384.0;
+    const M2: f32 = 2523.0 / 4096.0 * 128.0;
+    const C1: f32 = 3424.0 / 4096.0;
+    const C2: f32 = 2413.0 / 4096.0 * 32.0;
+    const C3: f32 = 2392.0 / 4096.0 * 32.0;
+    let y = (nits / 10_000.0).clamp(0.0, 1.0).powf(M1);
+    ((C1 + C2 * y) / (1.0 + C3 * y)).powf(M2)
+}
+
+#[test]
+fn bounded_feeds_keep_metadata_after_the_final_progressive_part() {
+    let samples: Vec<u8> = (0..8 * 8 * 4).map(|i| (i * 13 % 256) as u8).collect();
+    let image = ImageRef { width: 8, height: 8, layout: Layout::Rgba, samples: Samples::U8(&samples) };
+    let encoded = encode(&image, EncodeOptions { lossless: true, progressive: true, ..EncodeOptions::default() }, &Metadata::default());
+    assert!(encoded.is_ok(), "valid image should encode: {encoded:?}");
+    let Ok(encoded) = encoded else { return };
+    let raw = raw_codestream(&encoded);
+    assert!(raw.starts_with(b"\xff\x0a"), "extract the JXL codestream from the encoder output");
+
+    let mut bytes = b"\0\0\0\x0cJXL \x0d\x0a\x87\x0a".to_vec();
+    box_bytes(&mut bytes, b"ftyp", b"jxl \0\0\0\0jxl ");
+    let split = raw.len() / 2;
+    let mut part = 0_u32.to_be_bytes().to_vec();
+    part.extend_from_slice(&raw[..split]);
+    box_bytes(&mut bytes, b"jxlp", &part);
+    let padding = vec![0; 4096usize.saturating_sub(bytes.len() + 8)];
+    box_bytes(&mut bytes, b"free", &padding);
+    let mut part = 0x8000_0001_u32.to_be_bytes().to_vec();
+    part.extend_from_slice(&raw[split..]);
+    box_bytes(&mut bytes, b"jxlp", &part);
+    let exif = b"II*\0\x08\0\0\0\x01\0\x12\x01\x03\0\x01\0\0\0\x01\0\0\0\0\0\0\0";
+    let mut exif_box = vec![0; 4];
+    exif_box.extend_from_slice(exif);
+    box_bytes(&mut bytes, b"Exif", &exif_box);
+    let xmp = b"<xmp/>";
+    box_bytes(&mut bytes, b"xml ", xmp);
+    assert!(bytes.len() < 8192, "metadata fixture should fit in two decoder feeds");
+
+    let reference = jxl_oxide::JxlImage::builder().read(bytes.as_slice());
+    assert!(reference.is_ok(), "reference decoder should read the fixture: {reference:?}");
+    let Ok(reference) = reference else { return };
+    let reference_exif = match reference.aux_boxes().first_exif() {
+        Ok(jxl_oxide::AuxBoxData::Data(data)) => Some(data.payload().to_vec()),
+        _ => None,
+    };
+    let reference_xmp = match reference.aux_boxes().first_xml() {
+        jxl_oxide::AuxBoxData::Data(data) => Some(data.to_vec()),
+        _ => None,
+    };
+    assert!(reference_exif.is_some(), "reference decoder should preserve the Exif box");
+    assert!(reference_xmp.is_some(), "reference decoder should preserve the XMP box");
+    let (Some(reference_exif), Some(reference_xmp)) = (reference_exif, reference_xmp) else { return };
+    let decoded = decode(&bytes, DecodeLimits::default());
+    assert!(decoded.is_ok(), "shared decoder should read the fixture: {decoded:?}");
+    let Ok(decoded) = decoded else { return };
+    assert_eq!(decoded.metadata.exif.as_deref(), Some(reference_exif.as_slice()));
+    assert_eq!(decoded.metadata.xmp.as_deref(), Some(reference_xmp.as_slice()));
+}
diff --git a/crates/lottie/Cargo.toml b/crates/lottie/Cargo.toml
index 0d934843c..945be4d54 100644
--- a/crates/lottie/Cargo.toml
+++ b/crates/lottie/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "craft-lottie"
-description = "Lottie (Bodymovin) JSON: the lottie-spec 1.0 document model with a bounded reader and a writer, animated properties and their keyframes, ease tangents, bezier paths, gradients, value coercions and embedded image data URIs"
+description = "Lottie (Bodymovin) JSON and dotLottie ZIP containers: the lottie-spec 1.0 document model, bounded readers and writers, animated properties, keyframes, ease tangents, bezier paths, gradients, value coercions and embedded image data URIs"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
@@ -11,5 +11,6 @@ repository.workspace = true
 workspace = true
 
 [dependencies]
+craft-zip = { workspace = true }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
diff --git a/crates/lottie/src/lib.rs b/crates/lottie/src/lib.rs
index 569063ebf..16c1c6e07 100644
--- a/crates/lottie/src/lib.rs
+++ b/crates/lottie/src/lib.rs
@@ -15,8 +15,8 @@
 //! LottieFiles format documentation); no player or exporter source was used.
 //!
 //! Which layer, shape, effect and text feature maps to what in an application's document is the
-//! application's work. dotLottie (`.lottie`) is a ZIP archive around the same JSON and is not
-//! read here.
+//! application's work. [`zip`] reads and writes the stored-entry ZIP container used by dotLottie;
+//! selecting its manifest and mapping it to this document model remains the application's work.
 
 // The test documents are large `json!` literals.
 #![cfg_attr(test, recursion_limit = "512")]
@@ -28,6 +28,7 @@ pub mod model;
 mod path;
 mod prop;
 mod value;
+pub mod zip;
 
 pub use gradient::Gradient;
 pub use model::{Animated, Animation, Layer, LayerContent, Limits, Shape, ShapeKind};
diff --git a/crates/lottie/src/zip.rs b/crates/lottie/src/zip.rs
new file mode 100644
index 000000000..05ebe0b70
--- /dev/null
+++ b/crates/lottie/src/zip.rs
@@ -0,0 +1,151 @@
+//! Bounded ZIP handling for dotLottie archives.
+//!
+//! The ZIP implementation delegates to `craft-zip`; this module applies dotLottie's relative
+//! entry-name rule and caps archive expansion before returning entry bytes.
+
+use craft_zip::{Archive, Error, Writer};
+pub use craft_zip::{Compression, Limits};
+
+/// Largest entry count accepted from a dotLottie archive.
+pub const MAX_ENTRIES: u64 = 10_000;
+/// Largest combined uncompressed payload returned from a dotLottie archive.
+pub const MAX_TOTAL_BYTES: u64 = 1 << 30;
+
+/// Whether an entry name is a relative path inside the archive: not absolute (`/…`, `\\…`), no
+/// drive (`C:…`) and no `..` component.
+fn is_relative_name(name: &str) -> bool {
+    let drive = name.as_bytes().get(1) == Some(&b':');
+    !name.starts_with(['/', '\\']) && !drive && !name.split(['/', '\\']).any(|c| c == "..")
+}
+
+/// Read files from a dotLottie ZIP archive within [`MAX_ENTRIES`] and [`MAX_TOTAL_BYTES`].
+///
+/// Both stored and deflated entries are supported. Directories and names that escape the archive
+/// root are skipped. Duplicate names and overlapping payloads are rejected because a consumer
+/// must not guess which content a manifest or animation name identifies.
+pub fn read_entries(data: &[u8]) -> Result<Vec<(String, Vec<u8>)>, Error> {
+    read_entries_with_limits(data, Limits { max_entries: MAX_ENTRIES, max_total_bytes: MAX_TOTAL_BYTES })
+}
+
+/// Read a dotLottie archive under caller-provided entry and expansion limits.
+pub fn read_entries_with_limits(data: &[u8], limits: Limits) -> Result<Vec<(String, Vec<u8>)>, Error> {
+    let mut archive = Archive::open(data, limits)?;
+    if archive.has_duplicate_names() || archive.has_overlapping_files()? {
+        return Err(Error::NotZip("duplicate names or overlapping entry data".into()));
+    }
+    let mut out = Vec::new();
+    for index in 0..archive.len() {
+        let (Some(name), Some(is_dir)) = (archive.entry_name(index)?, archive.entry_is_dir(index)?) else { continue };
+        if is_dir || !is_relative_name(&name) {
+            continue;
+        }
+        if let Some(bytes) = archive.read(&name, limits.max_total_bytes)? {
+            out.push((name, bytes));
+        }
+    }
+    Ok(out)
+}
+
+/// Read the stored local-file entries in a ZIP written by [`store`]. This compatibility reader
+/// retains its original behavior: compressed entries are skipped, an incomplete trailing entry
+/// stops the walk while already-read entries are returned, and unsafe names are skipped. New code
+/// should use [`read_entries`] for central-directory validation and deflate support.
+pub fn read_stored(data: &[u8]) -> Vec<(String, Vec<u8>)> {
+    let u16_at = |p: usize| p.checked_add(2).and_then(|e| data.get(p..e)).map(|b| u16::from_le_bytes([b[0], b[1]]) as usize);
+    let u32_at = |p: usize| p.checked_add(4).and_then(|e| data.get(p..e)).map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]]) as usize);
+    let mut out = Vec::new();
+    let mut i = 0usize;
+    while u32_at(i) == Some(0x0403_4b50) {
+        let (Some(method), Some(size), Some(nlen), Some(xlen)) = (
+            i.checked_add(8).and_then(u16_at),
+            i.checked_add(18).and_then(u32_at),
+            i.checked_add(26).and_then(u16_at),
+            i.checked_add(28).and_then(u16_at),
+        ) else {
+            break;
+        };
+        let Some(name_start) = i.checked_add(30) else { break };
+        let Some(name_end) = name_start.checked_add(nlen) else { break };
+        let Some(body) = name_end.checked_add(xlen) else { break };
+        let Some(body_end) = body.checked_add(size) else { break };
+        let (Some(name), Some(bytes)) = (data.get(name_start..name_end), data.get(body..body_end)) else { break };
+        let name = String::from_utf8_lossy(name).to_string();
+        if method == 0 && is_relative_name(&name) {
+            out.push((name, bytes.to_vec()));
+        }
+        i = body_end;
+    }
+    out
+}
+
+/// Write ZIP entries uncompressed, preserving input order and the legacy deterministic timestamp.
+pub fn try_store(entries: &[(String, Vec<u8>)]) -> Result<Vec<u8>, Error> {
+    try_store_with_compression(entries, Compression::Stored)
+}
+
+/// Write entries using the selected shared ZIP compression mode.
+pub fn try_store_with_compression(entries: &[(String, Vec<u8>)], compression: Compression) -> Result<Vec<u8>, Error> {
+    let mut writer = Writer::legacy_utf8();
+    for (name, bytes) in entries {
+        writer.add(name, bytes, compression)?;
+    }
+    writer.finish()
+}
+
+/// Compatibility wrapper for the original infallible writer API. Use [`try_store`] when the
+/// caller needs an actionable error for an invalid or unrepresentable archive.
+pub fn store(entries: &[(String, Vec<u8>)]) -> Vec<u8> {
+    try_store(entries).unwrap_or_default()
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+    use super::*;
+
+    #[test]
+    fn stored_writer_roundtrips_and_keeps_entry_order() {
+        let entries = [("a.json".into(), b"{}".to_vec()), ("b/c.txt".into(), b"hello".to_vec())];
+        let bytes = try_store(&entries).unwrap();
+        assert_eq!(read_entries(&bytes).unwrap(), entries);
+        assert_eq!(bytes, store(&entries));
+    }
+
+    #[test]
+    fn deflated_entries_are_read_and_path_traversal_is_skipped() {
+        let mut writer = Writer::new();
+        writer.add("animations/main.json", br#"{"w":1,"h":1}"#, Compression::Deflated).unwrap();
+        writer.add("../outside.json", b"{}", Compression::Deflated).unwrap();
+        let bytes = writer.finish().unwrap();
+        assert_eq!(read_entries(&bytes).unwrap(), [("animations/main.json".into(), br#"{"w":1,"h":1}"#.to_vec())]);
+        assert!(read_entries_with_limits(&bytes, Limits { max_entries: 10, max_total_bytes: 4 }).is_err());
+    }
+
+    #[test]
+    fn malformed_and_truncated_archives_return_errors_without_panicking() {
+        let mut hostile = vec![0; 30];
+        hostile[..4].copy_from_slice(&0x0403_4b50u32.to_le_bytes());
+        hostile[8..10].copy_from_slice(&0u16.to_le_bytes());
+        hostile[18..22].copy_from_slice(&u32::MAX.to_le_bytes());
+        hostile[26..28].copy_from_slice(&u16::MAX.to_le_bytes());
+        hostile[28..30].copy_from_slice(&u16::MAX.to_le_bytes());
+        assert!(read_entries(&hostile).is_err());
+        for end in 0..hostile.len() {
+            let _ = read_entries(&hostile[..end]);
+        }
+    }
+
+    #[test]
+    fn legacy_stored_archive_bytes_and_partial_tail_are_compatible() {
+        const HEX: &str = "504b03041400000800000000210043bfa6a3020000000200000006000000612e6a736f6e7b7d504b03041400000800000000210086a61036050000000500000007000000622f632e74787468656c6c6f504b010214001400000800000000210043bfa6a30200000002000000060000000000000000000000000000000000612e6a736f6e504b010214001400000800000000210086a610360500000005000000070000000000000000000000000026000000622f632e747874504b0506000000000200020069000000500000000000";
+        let legacy: Vec<u8> = HEX.as_bytes().chunks(2).map(|pair| u8::from_str_radix(std::str::from_utf8(pair).unwrap(), 16).unwrap()).collect();
+        let entries = [("a.json".into(), b"{}".to_vec()), ("b/c.txt".into(), b"hello".to_vec())];
+        assert_eq!(read_stored(&legacy), entries);
+        assert_eq!(read_entries(&legacy).unwrap(), entries);
+        assert_eq!(try_store(&entries).unwrap(), legacy);
+        let partial = &legacy[..50];
+        assert_eq!(read_stored(partial), [("a.json".into(), b"{}".to_vec())]);
+        assert!(read_entries(partial).is_err());
+    }
+}
diff --git a/crates/materialx/src/lib.rs b/crates/materialx/src/lib.rs
index d60db3eef..72afc8ca1 100644
--- a/crates/materialx/src/lib.rs
+++ b/crates/materialx/src/lib.rs
@@ -183,7 +183,14 @@ const OPENPBR_WRITABLE: &[(&str, InputKind)] = &[
 impl Document {
     /// Parses a MaterialX document while enforcing size, nesting and node-count limits.
     pub fn parse(bytes: &[u8]) -> Result<Self, Error> {
-        let limits = Limits { max_input: MAX_BYTES, max_depth: MAX_DEPTH, max_nodes: MAX_NODES, max_attrs: 256, max_attrs_total: 400_000 };
+        let limits = Limits {
+            max_input: MAX_BYTES,
+            max_depth: MAX_DEPTH,
+            max_nodes: MAX_NODES,
+            max_elements: MAX_NODES,
+            max_attrs: 256,
+            max_attrs_total: 400_000,
+        };
         let options = Options {
             doctype: Doctype::Reject,
             unknown_entity: UnknownEntity::Error,
diff --git a/crates/media/Cargo.toml b/crates/media/Cargo.toml
index cdbf28349..4943b1771 100644
--- a/crates/media/Cargo.toml
+++ b/crates/media/Cargo.toml
@@ -18,7 +18,7 @@ default = ["isobmff"]
 bitstream = []
 isobmff = ["bitstream", "dep:thiserror"]
 matroska = []
-# AVI (RIFF) and OpenDML demuxer (`craft_media::avi`).
+# AVI (RIFF) and OpenDML demuxer and muxer (`craft_media::avi`).
 avi = []
 # MXF demuxer and writer (`craft_media::mxf`); the writer formats dates with chrono.
 mxf = ["dep:chrono"]
@@ -51,6 +51,10 @@ required-features = ["matroska"]
 name = "oracle_avi"
 required-features = ["avi"]
 
+[[test]]
+name = "oracle_avi_mux"
+required-features = ["avi"]
+
 [[test]]
 name = "oracle_demux"
 required-features = ["isobmff"]
diff --git a/crates/media/README.md b/crates/media/README.md
index 387ab8cdd..8eca6ecb5 100644
--- a/crates/media/README.md
+++ b/crates/media/README.md
@@ -1,8 +1,8 @@
 # craft-media
 
 Media containers and bit-level I/O for the Craft apps: an MSB-first bit reader and writer,
-clean-room ISO BMFF (MP4), QuickTime (MOV) and Matroska (MKV, WebM) and MXF demuxers and muxers, and
-Ogg, AVI and MPEG-2 Systems (transport and program stream) demuxers, written from the public specifications. No `unsafe`, no panics on malformed
+clean-room ISO BMFF (MP4), QuickTime (MOV), Matroska (MKV, WebM), MXF and AVI demuxers and muxers, and
+Ogg and MPEG-2 Systems (transport and program stream) demuxers, written from the public specifications. No `unsafe`, no panics on malformed
 input, builds for `wasm32-unknown-unknown`. Dependencies: `thiserror` (for `isobmff`), `chrono`
 (for `mxf`), `serde` (optional).
 
@@ -44,8 +44,7 @@ craft-media = { git = "https://github.com/storytold/craft-libs", rev = "<commit>
 - In scope: bit-level reading and writing, and container demuxing and muxing (boxes, sample
   tables, sample entries and codec configuration records) for audio and video tracks.
 - Out of scope: codecs. Audio codecs are in `craft-audio`; video codecs (H.264, HEVC, ProRes,
-  DNx, VP8, VP9, AV1) are in `craft-video`. Containers only FilmCraft reads (MXF,
-  MPEG-TS/PS, AVI) are not here yet.
+  DNx, VP8, VP9, AV1, MPEG-4 Part 2) are in `craft-video`.
 - Anything both the audio and the video codec crates need belongs here, so the two never depend
   on each other.
 
@@ -448,10 +447,10 @@ No muxer.
 
 ## `avi`
 
-A clean-room AVI demuxer from FilmCraft's `filmcraft-avi` (storytold/filmcraft@4bec22b), written
-from Microsoft's published AVI RIFF file reference and the OpenDML AVI File Format Extensions 1.02.
-No FFmpeg, libavformat or other AVI implementation was read; ffmpeg and ffprobe are test oracles
-only. No muxer.
+A clean-room AVI demuxer from FilmCraft's `filmcraft-avi` (storytold/filmcraft@4bec22b), and a
+muxer, both written from Microsoft's published AVI RIFF file reference and the OpenDML AVI File
+Format Extensions 1.02. No FFmpeg, libavformat or other AVI implementation was read; ffmpeg and
+ffprobe are test oracles only.
 
 ```rust
 use craft_media::avi::{open, StreamKind};
@@ -496,6 +495,44 @@ Tests: hand-built files for every index path, truncation, every single-byte muta
 multi-byte damage (never a panic). `tests/oracle_avi.rs` checks ffmpeg-made files (Motion JPEG,
 H.264 with B-frames, BGR24, YUY2; PCM and MP3) against ffprobe; the ignored `opendml_file_past_1_gb`
 checks a 1.16 GB OpenDML file with `AVIX` extensions.
+
+### Muxer
+
+```rust
+use craft_media::avi::{AudioSpec, AviWriter, MuxOptions, StreamSpec, VideoSpec};
+
+let video = VideoSpec::new(*b"XVID", 640, 360, 25, 1); // or VideoSpec::for_codec(&encoder.codec_params(), 25, 1)
+let audio = AudioSpec::pcm(48_000, 2, 16);
+let mut w = AviWriter::new(file, vec![StreamSpec::Video(video), StreamSpec::Audio(audio)], MuxOptions::default())?;
+w.write_chunk(0, &frame, keyframe)?; // chunks go in the order written: the caller interleaves
+w.write_chunk(1, &pcm, true)?;
+let file = w.finish()?; // Write + Seek: sizes and the header list are rewritten at the end
+```
+
+- Layout: `RIFF AVI ` with `hdrl` (`avih`; per stream `strh`, `strf`, `strn` and an OpenDML
+  `indx`; `odml`/`dmlh`), `LIST movi`, `idx1`. Chunks are `NNdc` (video) and `NNwb` (audio) with
+  decimal stream numbers, padded to even sizes. Empty video chunks (repeat the previous picture)
+  are allowed.
+- Large files: when a RIFF would pass `MuxOptions::riff_limit` (1 GiB by default, 16 KiB to
+  2 GiB) the file continues in a `RIFF AVIX`. Every RIFF ends its `movi` with an `ix##` standard
+  index per stream, listed in that stream's `indx`; `idx1` covers the first RIFF only, and
+  `avih` counts the first RIFF's frames while `dmlh` and `strh` count all of them, as OpenDML
+  asks. The `indx` has room for `MuxOptions::max_riffs` (256) RIFFs, reserved in the header.
+- Streams: video with any `BITMAPINFOHEADER` (`VideoSpec::for_codec` picks the FourCC of an
+  encoder's `CodecParams`: `FMP4`, `H264`, `HEVC`, `MJPG`, `MPG2`, `VP80`, `VP90`, `AV01`; `FMP4` and
+  not `XVID` for MPEG-4 Part 2, which decoders take to name the encoder), and audio
+  with any `WAVEFORMATEX`, timed by its bytes (`AudioTiming::Bytes`: PCM and other fixed-size
+  sample frames) or a packet a chunk (`AudioTiming::Packets`: MP3, AAC, AC-3). Up to 100 streams.
+- Errors, not panics: no streams, a zero rate, a chunk that does not fit in a RIFF, more RIFFs
+  than `max_riffs` (what was written still closes into a readable file).
+
+Tests: `mux_tests.rs` reads files back through the demuxer on every index path (OpenDML, `idx1`
+with the `AVIX` extensions scanned, a scan), with odd and empty chunks, several `AVIX`
+extensions, a file starting inside its output, packet-timed audio and the error cases.
+`tests/oracle_avi_mux.rs` muxes an ffmpeg-made MPEG-4 Part 2 stream and PCM, in one RIFF and
+across `AVIX` extensions: ffmpeg decodes the AVI to exactly the pictures and samples of the
+sources, seeking through the index lands on the right picture, and ffprobe reads the codec,
+FourCC, size, frame rate, packet count, audio format and duration.
 ## `mpegts`
 
 A clean-room MPEG-2 Systems demuxer from FilmCraft's `filmcraft-mpegts`
diff --git a/crates/media/src/avi/mod.rs b/crates/media/src/avi/mod.rs
index 592139cef..eaaa1bbe2 100644
--- a/crates/media/src/avi/mod.rs
+++ b/crates/media/src/avi/mod.rs
@@ -1,5 +1,5 @@
-//! Clean-room AVI demuxer, written from Microsoft's published AVI RIFF file reference and the
-//! OpenDML AVI File Format Extensions 1.02.
+//! Clean-room AVI demuxer and muxer ([`AviWriter`]), written from Microsoft's published AVI RIFF
+//! file reference and the OpenDML AVI File Format Extensions 1.02.
 //!
 //! [`open`] reads the `hdrl` header list (`avih`, and per stream `strh` / `strf` / `strn` /
 //! `indx`) of the first `RIFF AVI ` and builds a per-stream table of [`Chunk`]s from the best index
@@ -18,9 +18,14 @@
 
 #![warn(missing_docs)]
 
+mod mux;
+#[cfg(test)]
+mod mux_tests;
 #[cfg(test)]
 mod tests;
 
+pub use mux::{AudioSpec, AudioTiming, AviWriter, MuxOptions, StreamSpec, VideoSpec};
+
 pub use crate::source::{ByteSource, ReadSeekSource};
 
 use std::collections::HashSet;
diff --git a/crates/media/src/avi/mux.rs b/crates/media/src/avi/mux.rs
new file mode 100644
index 000000000..a6e03e174
--- /dev/null
+++ b/crates/media/src/avi/mux.rs
@@ -0,0 +1,617 @@
+//! Clean-room AVI muxer, written from Microsoft's published AVI RIFF file reference and the
+//! OpenDML AVI File Format Extensions 1.02.
+//!
+//! [`AviWriter`] writes one `RIFF AVI ` with the `hdrl` header list, a `movi` list of chunks in
+//! the order they are given, and the AVI 1.0 `idx1` index. A file that grows past
+//! [`MuxOptions::riff_limit`] (1 GiB) continues in `RIFF AVIX` extensions. Every RIFF ends its
+//! `movi` list with an OpenDML standard index (`ix##`) per stream, and each stream's `strl`
+//! holds a super index (`indx`) of them, so readers find the chunks past the first RIFF; `idx1`
+//! covers the first RIFF only, as OpenDML asks.
+//!
+//! The header list is written at the start with room reserved for the super indexes and
+//! rewritten with the final counts by [`AviWriter::finish`]: the output must be `Write + Seek`.
+
+use std::io::{Seek, SeekFrom, Write};
+
+use super::{BitmapInfo, Error, Result, WaveFormat};
+use crate::{CodecId, CodecParams};
+
+/// `AVIF_HASINDEX`: the file has an `idx1`.
+const AVIF_HASINDEX: u32 = 0x10;
+/// `AVIF_ISINTERLEAVED`: the chunks of the streams are interleaved.
+const AVIF_ISINTERLEAVED: u32 = 0x100;
+/// `AVIIF_KEYFRAME` in an `idx1` entry.
+const AVIIF_KEYFRAME: u32 = 0x10;
+/// Bit 31 of a standard index entry's size: not a key frame.
+const NOT_KEY: u32 = 0x8000_0000;
+/// `dmlh` is 248 bytes: `dwTotalFrames` and reserved space.
+const DMLH_SIZE: usize = 248;
+/// Chunk ids carry a two-digit decimal stream number.
+const MAX_STREAMS: usize = 100;
+/// The smallest RIFF size the writer accepts.
+const MIN_RIFF_LIMIT: u64 = 16 << 10;
+/// The largest: RIFF and chunk sizes are 32-bit, and OpenDML entries use bit 31 as a flag.
+const MAX_RIFF_LIMIT: u64 = 1 << 31;
+
+/// How the chunks of an audio stream measure time (`strh` `dwScale`, `dwRate`, `dwSampleSize`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum AudioTiming {
+    /// Chunks are runs of fixed-size sample frames of `block_align` bytes (PCM, A-law, constant
+    /// bitrate MP3 written as a byte stream): the stream is timed by its bytes.
+    Bytes,
+    /// Each chunk is one packet of `samples_per_packet` sample frames (1152 for MPEG audio Layer
+    /// II/III at 32 kHz and above, 1024 for AAC, 1536 for AC-3).
+    Packets {
+        /// Sample frames in a packet.
+        samples_per_packet: u32,
+    },
+}
+
+/// A video stream for [`AviWriter`].
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct VideoSpec {
+    /// The `BITMAPINFOHEADER` written as `strf`. `compression` is the FourCC (`XVID`, `MJPG`,
+    /// `H264`…), and `extra` follows the 40-byte header.
+    pub format: BitmapInfo,
+    /// `fccHandler`; the compression FourCC when `None`.
+    pub handler: Option<[u8; 4]>,
+    /// Frames per second is `rate / scale`.
+    pub rate: u32,
+    /// See `rate`.
+    pub scale: u32,
+    /// `strn`.
+    pub name: Option<String>,
+}
+
+impl VideoSpec {
+    /// A compressed stream of `fourcc` pictures, 24 bits per pixel in the header, at `rate / scale`
+    /// frames per second.
+    pub fn new(fourcc: [u8; 4], width: u32, height: u32, rate: u32, scale: u32) -> VideoSpec {
+        VideoSpec {
+            format: BitmapInfo {
+                width: i32::try_from(width).unwrap_or(i32::MAX),
+                height: i32::try_from(height).unwrap_or(i32::MAX),
+                bit_count: 24,
+                compression: fourcc,
+                size_image: width.saturating_mul(height).saturating_mul(3),
+                extra: Vec::new(),
+            },
+            handler: None,
+            rate,
+            scale,
+            name: None,
+        }
+    }
+
+    /// A stream for an encoder's track description: the usual AVI FourCC of its codec (`FMP4` for
+    /// MPEG-4 Part 2, `H264`, `HEVC`, `MJPG`, `MPG2`, `VP80`, `VP90`, `AV01`), its picture size
+    /// and its extradata after the header. MPEG-4 Part 2 gets `FMP4` rather than `XVID` or `DIVX`
+    /// because decoders read those as naming the encoder: ffmpeg, for one, decodes an `XVID`
+    /// stream with Xvid's own IDCT. Set `format.compression` for a player that wants another. `None` for a codec without a FourCC here or a
+    /// description without a size. H.264 and HEVC chunks must then be Annex B with an Annex B or
+    /// empty extradata, as AVI readers expect.
+    pub fn for_codec(params: &CodecParams, rate: u32, scale: u32) -> Option<VideoSpec> {
+        let fourcc = match params.codec {
+            CodecId::Mpeg4Video => *b"FMP4",
+            CodecId::H264 => *b"H264",
+            CodecId::Hevc => *b"HEVC",
+            CodecId::Mjpeg => *b"MJPG",
+            CodecId::Mpeg2Video => *b"MPG2",
+            CodecId::Vp8 => *b"VP80",
+            CodecId::Vp9 => *b"VP90",
+            CodecId::Av1 => *b"AV01",
+            _ => return None,
+        };
+        let mut v = VideoSpec::new(fourcc, params.width?, params.height?, rate, scale);
+        v.format.extra = params.extradata.clone();
+        Some(v)
+    }
+}
+
+/// An audio stream for [`AviWriter`].
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct AudioSpec {
+    /// The `WAVEFORMATEX` written as `strf`.
+    pub format: WaveFormat,
+    /// How its chunks measure time.
+    pub timing: AudioTiming,
+    /// `strn`.
+    pub name: Option<String>,
+}
+
+impl AudioSpec {
+    /// Interleaved little-endian integer PCM (`bits` 8, 16, 24 or 32), timed by its bytes.
+    pub fn pcm(sample_rate: u32, channels: u16, bits: u16) -> AudioSpec {
+        let block_align = channels.saturating_mul(bits.div_ceil(8));
+        AudioSpec {
+            format: WaveFormat {
+                format_tag: 1,
+                channels,
+                sample_rate,
+                avg_bytes_per_sec: sample_rate.saturating_mul(u32::from(block_align)),
+                block_align,
+                bits_per_sample: bits,
+                extra: Vec::new(),
+            },
+            timing: AudioTiming::Bytes,
+            name: None,
+        }
+    }
+}
+
+/// One stream of an AVI file.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum StreamSpec {
+    /// `vids`.
+    Video(VideoSpec),
+    /// `auds`.
+    Audio(AudioSpec),
+}
+
+/// Options for [`AviWriter`].
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct MuxOptions {
+    /// Largest size of one RIFF (the first, then each `AVIX` extension), 16 KiB to 2 GiB.
+    /// 1 GiB by default, which OpenDML recommends for the first RIFF so AVI 1.0 readers can use it.
+    pub riff_limit: u64,
+    /// RIFFs the super indexes have room for (each takes 16 bytes a stream in the header). 256 by
+    /// default: 256 GiB at the default `riff_limit`.
+    pub max_riffs: u32,
+}
+
+impl Default for MuxOptions {
+    fn default() -> Self {
+        MuxOptions { riff_limit: 1 << 30, max_riffs: 256 }
+    }
+}
+
+/// A chunk's entry in the standard index of its RIFF.
+#[derive(Clone, Copy, Debug)]
+struct Entry {
+    /// Offset of the data from the `movi` list's type id (the index's base).
+    offset: u32,
+    size: u32,
+    key: bool,
+}
+
+/// One `ix##` written: its position, its size and the stream time it covers.
+#[derive(Clone, Copy, Debug)]
+struct SuperEntry {
+    at: u64,
+    size: u32,
+    duration: u32,
+}
+
+/// The RIFF being written.
+#[derive(Clone, Copy, Debug)]
+struct Riff {
+    /// Position of `RIFF`.
+    start: u64,
+    /// Position of the `movi` list's `LIST`.
+    movi: u64,
+}
+
+#[derive(Debug)]
+struct StreamState {
+    spec: StreamSpec,
+    /// `00dc`, `01wb`…
+    id: [u8; 4],
+    chunks: u64,
+    bytes: u64,
+    largest: u32,
+    /// The chunks of the current RIFF.
+    entries: Vec<Entry>,
+    /// Stream time of the current RIFF's chunks.
+    duration: u64,
+    supers: Vec<SuperEntry>,
+}
+
+impl StreamState {
+    /// Stream time (`dwScale / dwRate` units) of a chunk of `len` bytes.
+    fn units(&self, len: u64) -> u64 {
+        match &self.spec {
+            StreamSpec::Audio(a) if a.timing == AudioTiming::Bytes => len / u64::from(a.format.block_align.max(1)),
+            _ => 1,
+        }
+    }
+
+    /// `(dwScale, dwRate, dwSampleSize)`.
+    fn time_base(&self) -> (u32, u32, u32) {
+        match &self.spec {
+            StreamSpec::Video(v) => (v.scale, v.rate, 0),
+            StreamSpec::Audio(a) => match a.timing {
+                AudioTiming::Bytes => (u32::from(a.format.block_align), a.format.avg_bytes_per_sec, u32::from(a.format.block_align)),
+                AudioTiming::Packets { samples_per_packet } => (samples_per_packet, a.format.sample_rate, 0),
+            },
+        }
+    }
+
+    /// The stream's length in its own units.
+    fn length(&self) -> u64 {
+        match &self.spec {
+            StreamSpec::Audio(a) if a.timing == AudioTiming::Bytes => self.bytes / u64::from(a.format.block_align.max(1)),
+            _ => self.chunks,
+        }
+    }
+
+    /// The stream's duration in seconds.
+    fn seconds(&self) -> f64 {
+        let (scale, rate, _) = self.time_base();
+        self.length() as f64 * f64::from(scale) / f64::from(rate.max(1))
+    }
+}
+
+fn le16(v: &mut Vec<u8>, x: u16) {
+    v.extend_from_slice(&x.to_le_bytes());
+}
+
+fn le32(v: &mut Vec<u8>, x: u32) {
+    v.extend_from_slice(&x.to_le_bytes());
+}
+
+fn sat32(x: u64) -> u32 {
+    u32::try_from(x).unwrap_or(u32::MAX)
+}
+
+/// A chunk: id, size, data, a pad byte to an even size.
+fn chunk(id: &[u8; 4], data: &[u8]) -> Vec<u8> {
+    let mut v = Vec::with_capacity(data.len() + 9);
+    v.extend_from_slice(id);
+    le32(&mut v, sat32(data.len() as u64));
+    v.extend_from_slice(data);
+    if data.len() % 2 == 1 {
+        v.push(0);
+    }
+    v
+}
+
+fn list(ltype: &[u8; 4], body: &[u8]) -> Vec<u8> {
+    chunk(b"LIST", &[ltype.as_slice(), body].concat())
+}
+
+fn invalid(msg: impl Into<String>) -> Error {
+    Error::Invalid(msg.into())
+}
+
+/// The `hdrl` list. Its length depends only on the stream descriptions and `max_riffs`, so the
+/// final one ([`AviWriter::finish`]) replaces the first in place.
+fn hdrl(streams: &[StreamState], main: Option<usize>, max_riffs: u32, first_frames: u32) -> Vec<u8> {
+    let video = main.and_then(|i| streams.get(i)).and_then(|s| match &s.spec {
+        StreamSpec::Video(v) => Some((v, s)),
+        StreamSpec::Audio(_) => None,
+    });
+    let seconds = streams.iter().map(StreamState::seconds).fold(0.0, f64::max);
+    let total: u64 = streams.iter().map(|s| s.bytes).sum();
+    let largest = streams.iter().map(|s| s.largest).max().unwrap_or(0);
+
+    let mut avih = Vec::with_capacity(56);
+    le32(&mut avih, video.map_or(0, |(v, _)| (1e6 * f64::from(v.scale) / f64::from(v.rate)).round() as u32));
+    le32(&mut avih, if seconds > 0.0 { (total as f64 / seconds).ceil() as u32 } else { 0 });
+    le32(&mut avih, 0); // dwPaddingGranularity
+    le32(&mut avih, AVIF_HASINDEX | AVIF_ISINTERLEAVED);
+    le32(&mut avih, first_frames);
+    le32(&mut avih, 0); // dwInitialFrames
+    le32(&mut avih, streams.len() as u32);
+    le32(&mut avih, largest.saturating_add(8));
+    le32(&mut avih, video.map_or(0, |(v, _)| v.format.width.unsigned_abs()));
+    le32(&mut avih, video.map_or(0, |(v, _)| v.format.height.unsigned_abs()));
+    avih.extend_from_slice(&[0; 16]);
+
+    let mut body = chunk(b"avih", &avih);
+    for s in streams {
+        let (scale, rate, sample_size) = s.time_base();
+        let mut strh = Vec::with_capacity(56);
+        let (fcc, handler, frame) = match &s.spec {
+            StreamSpec::Video(v) => (*b"vids", v.handler.unwrap_or(v.format.compression), (v.format.width, v.format.height.abs())),
+            StreamSpec::Audio(_) => (*b"auds", [0; 4], (0, 0)),
+        };
+        strh.extend_from_slice(&fcc);
+        strh.extend_from_slice(&handler);
+        le32(&mut strh, 0); // dwFlags
+        le16(&mut strh, 0); // wPriority
+        le16(&mut strh, 0); // wLanguage
+        le32(&mut strh, 0); // dwInitialFrames
+        le32(&mut strh, scale);
+        le32(&mut strh, rate);
+        le32(&mut strh, 0); // dwStart
+        le32(&mut strh, sat32(s.length()));
+        le32(&mut strh, s.largest);
+        le32(&mut strh, u32::MAX); // dwQuality: default
+        le32(&mut strh, sample_size);
+        for v in [0, 0, frame.0, frame.1] {
+            le16(&mut strh, i16::try_from(v).unwrap_or(i16::MAX) as u16);
+        }
+
+        let mut strf = Vec::new();
+        match &s.spec {
+            StreamSpec::Video(v) => {
+                let f = &v.format;
+                le32(&mut strf, sat32(40 + f.extra.len() as u64));
+                le32(&mut strf, f.width as u32);
+                le32(&mut strf, f.height as u32);
+                le16(&mut strf, 1); // biPlanes
+                le16(&mut strf, f.bit_count);
+                strf.extend_from_slice(&f.compression);
+                le32(&mut strf, f.size_image);
+                strf.extend_from_slice(&[0; 16]); // pels per metre, colours used and important
+                strf.extend_from_slice(&f.extra);
+            }
+            StreamSpec::Audio(a) => {
+                let f = &a.format;
+                le16(&mut strf, f.format_tag);
+                le16(&mut strf, f.channels);
+                le32(&mut strf, f.sample_rate);
+                le32(&mut strf, f.avg_bytes_per_sec);
+                le16(&mut strf, f.block_align);
+                le16(&mut strf, f.bits_per_sample);
+                le16(&mut strf, u16::try_from(f.extra.len()).unwrap_or(u16::MAX));
+                strf.extend_from_slice(&f.extra[..f.extra.len().min(usize::from(u16::MAX))]);
+            }
+        }
+
+        // indx: AVI_INDEX_OF_INDEXES, room for `max_riffs` entries
+        let mut indx = Vec::with_capacity(24 + 16 * max_riffs as usize);
+        le16(&mut indx, 4); // wLongsPerEntry
+        indx.push(0); // bIndexSubType
+        indx.push(0); // bIndexType: AVI_INDEX_OF_INDEXES
+        le32(&mut indx, s.supers.len() as u32);
+        indx.extend_from_slice(&s.id);
+        indx.extend_from_slice(&[0; 12]);
+        for e in &s.supers {
+            indx.extend_from_slice(&e.at.to_le_bytes());
+            le32(&mut indx, e.size);
+            le32(&mut indx, e.duration);
+        }
+        indx.resize(24 + 16 * max_riffs as usize, 0);
+
+        let mut strl = chunk(b"strh", &strh);
+        strl.extend(chunk(b"strf", &strf));
+        let name = match &s.spec {
+            StreamSpec::Video(v) => v.name.as_deref(),
+            StreamSpec::Audio(a) => a.name.as_deref(),
+        };
+        if let Some(n) = name {
+            strl.extend(chunk(b"strn", &[n.as_bytes(), &[0]].concat()));
+        }
+        strl.extend(chunk(b"indx", &indx));
+        body.extend(list(b"strl", &strl));
+    }
+    let mut dmlh = vec![0u8; DMLH_SIZE];
+    let frames = video.map_or(0, |(_, s)| sat32(s.chunks));
+    dmlh[..4].copy_from_slice(&frames.to_le_bytes());
+    body.extend(list(b"odml", &chunk(b"dmlh", &dmlh)));
+    list(b"hdrl", &body)
+}
+
+/// Writes an AVI file chunk by chunk; see the [module documentation](self).
+#[derive(Debug)]
+pub struct AviWriter<W: Write + Seek> {
+    w: W,
+    /// Where the file starts in `w`.
+    base: u64,
+    opts: MuxOptions,
+    streams: Vec<StreamState>,
+    /// The stream whose frame period and size the main header gives (the first video stream).
+    main: Option<usize>,
+    /// The next byte to write, from the start of the file.
+    pos: u64,
+    /// Bytes of the `hdrl` list, fixed so it can be rewritten in place.
+    hdrl_len: usize,
+    riff: Riff,
+    /// RIFFs started so far.
+    riffs: u32,
+    /// `idx1` of the first RIFF (16 bytes an entry), while it is open.
+    idx1: Vec<[u8; 16]>,
+    /// Video frames in the first RIFF (`avih` `dwTotalFrames`).
+    first_frames: u32,
+}
+
+impl<W: Write + Seek> AviWriter<W> {
+    /// Start a file with `streams` (1 to 100) at the current position of `w`.
+    pub fn new(mut w: W, streams: Vec<StreamSpec>, opts: MuxOptions) -> Result<Self> {
+        if streams.is_empty() || streams.len() > MAX_STREAMS {
+            return Err(invalid(format!("{} streams (1 to {MAX_STREAMS})", streams.len())));
+        }
+        if !(MIN_RIFF_LIMIT..=MAX_RIFF_LIMIT).contains(&opts.riff_limit) {
+            return Err(invalid(format!("riff_limit {} is outside {MIN_RIFF_LIMIT}..={MAX_RIFF_LIMIT}", opts.riff_limit)));
+        }
+        if opts.max_riffs == 0 || opts.max_riffs > 1 << 16 {
+            return Err(invalid("max_riffs must be 1 to 65536"));
+        }
+        for (i, s) in streams.iter().enumerate() {
+            match s {
+                StreamSpec::Video(v) if v.rate == 0 || v.scale == 0 => return Err(invalid(format!("stream {i}: zero frame rate"))),
+                StreamSpec::Audio(a) if a.format.sample_rate == 0 => return Err(invalid(format!("stream {i}: zero sample rate"))),
+                StreamSpec::Audio(a) if a.timing == AudioTiming::Bytes && (a.format.block_align == 0 || a.format.avg_bytes_per_sec == 0) => {
+                    return Err(invalid(format!("stream {i}: byte-timed audio needs a block align and a byte rate")));
+                }
+                StreamSpec::Audio(AudioSpec { timing: AudioTiming::Packets { samples_per_packet: 0 }, .. }) => {
+                    return Err(invalid(format!("stream {i}: zero samples a packet")));
+                }
+                _ => {}
+            }
+        }
+        let main = streams.iter().position(|s| matches!(s, StreamSpec::Video(_)));
+        let streams: Vec<StreamState> = streams
+            .into_iter()
+            .enumerate()
+            .map(|(i, spec)| {
+                let kind = if matches!(spec, StreamSpec::Video(_)) { b"dc" } else { b"wb" };
+                StreamState {
+                    spec,
+                    id: [b'0' + (i / 10) as u8, b'0' + (i % 10) as u8, kind[0], kind[1]],
+                    chunks: 0,
+                    bytes: 0,
+                    largest: 0,
+                    entries: Vec::new(),
+                    duration: 0,
+                    supers: Vec::new(),
+                }
+            })
+            .collect();
+        let header = hdrl(&streams, main, opts.max_riffs, 0);
+        if (header.len() + 24) as u64 > opts.riff_limit / 2 {
+            return Err(invalid("the header list takes more than half of riff_limit"));
+        }
+        let base = w.stream_position()?;
+        let mut head = Vec::with_capacity(header.len() + 24);
+        head.extend_from_slice(b"RIFF");
+        le32(&mut head, 0);
+        head.extend_from_slice(b"AVI ");
+        head.extend_from_slice(&header);
+        let movi = head.len() as u64;
+        head.extend_from_slice(b"LIST");
+        le32(&mut head, 0);
+        head.extend_from_slice(b"movi");
+        w.write_all(&head)?;
+        Ok(AviWriter {
+            w,
+            base,
+            opts,
+            streams,
+            main,
+            pos: head.len() as u64,
+            hdrl_len: header.len(),
+            riff: Riff { start: 0, movi },
+            riffs: 1,
+            idx1: Vec::new(),
+            first_frames: 0,
+        })
+    }
+
+    /// Bytes the current RIFF would take if it were closed after one more chunk of `chunk_len`
+    /// bytes for `stream`: its chunks, the standard indexes and (first RIFF) `idx1`.
+    fn riff_size_with(&self, stream: usize, chunk_len: u64) -> u64 {
+        let ix: u64 = self.streams.iter().enumerate().map(|(i, s)| 32 + 8 * (s.entries.len() as u64 + u64::from(i == stream))).sum();
+        let idx1 = if self.riffs == 1 { 8 + 16 * (self.idx1.len() as u64 + 1) } else { 0 };
+        self.pos - self.riff.start + chunk_len + ix + idx1
+    }
+
+    /// Write one chunk of stream `stream`: a video frame (`key` for a key frame; an empty chunk
+    /// repeats the previous picture) or a run of audio. Chunks go into the file in call order,
+    /// so the caller interleaves the streams.
+    pub fn write_chunk(&mut self, stream: usize, data: &[u8], key: bool) -> Result<()> {
+        if stream >= self.streams.len() {
+            return Err(invalid(format!("no stream {stream}")));
+        }
+        let len = data.len() as u64;
+        let chunk_len = 8 + len + (len & 1);
+        if self.riff_size_with(stream, chunk_len) > self.opts.riff_limit && self.streams.iter().any(|s| !s.entries.is_empty()) {
+            self.next_riff()?;
+        }
+        if self.riff_size_with(stream, chunk_len) > self.opts.riff_limit {
+            return Err(invalid(format!("a {len}-byte chunk does not fit in a RIFF of riff_limit {} bytes", self.opts.riff_limit)));
+        }
+        let index_base = self.riff.movi + 8;
+        let s = &mut self.streams[stream];
+        let at = self.pos;
+        let mut head = Vec::with_capacity(8);
+        head.extend_from_slice(&s.id);
+        le32(&mut head, len as u32);
+        self.w.write_all(&head)?;
+        self.w.write_all(data)?;
+        if len & 1 == 1 {
+            self.w.write_all(&[0])?;
+        }
+        self.pos += chunk_len;
+        // riff_limit ≤ 2 GiB keeps every offset in the RIFF below 2^31
+        s.entries.push(Entry { offset: (at + 8 - index_base) as u32, size: len as u32, key });
+        s.duration += s.units(len);
+        s.chunks += 1;
+        s.bytes += len;
+        s.largest = s.largest.max(len as u32);
+        if self.riffs == 1 {
+            let mut e = [0u8; 16];
+            e[..4].copy_from_slice(&s.id);
+            e[4..8].copy_from_slice(&(if key { AVIIF_KEYFRAME } else { 0 }).to_le_bytes());
+            e[8..12].copy_from_slice(&((at - index_base) as u32).to_le_bytes());
+            e[12..].copy_from_slice(&(len as u32).to_le_bytes());
+            self.idx1.push(e);
+            if Some(stream) == self.main {
+                self.first_frames += 1;
+            }
+        }
+        Ok(())
+    }
+
+    fn patch(&mut self, at: u64, bytes: &[u8]) -> Result<()> {
+        self.w.seek(SeekFrom::Start(self.base + at))?;
+        self.w.write_all(bytes)?;
+        self.w.seek(SeekFrom::Start(self.base + self.pos))?;
+        Ok(())
+    }
+
+    fn put(&mut self, bytes: &[u8]) -> Result<()> {
+        self.w.write_all(bytes)?;
+        self.pos += bytes.len() as u64;
+        Ok(())
+    }
+
+    /// Close the current RIFF: the standard indexes at the end of its `movi`, the sizes, and
+    /// (first RIFF) `idx1`.
+    fn end_riff(&mut self) -> Result<()> {
+        let index_base = self.riff.movi + 8;
+        for i in 0..self.streams.len() {
+            let s = &mut self.streams[i];
+            let mut ix = Vec::with_capacity(24 + 8 * s.entries.len());
+            le16(&mut ix, 2); // wLongsPerEntry
+            ix.push(0); // bIndexSubType
+            ix.push(1); // bIndexType: AVI_INDEX_OF_CHUNKS
+            le32(&mut ix, s.entries.len() as u32);
+            ix.extend_from_slice(&s.id);
+            ix.extend_from_slice(&index_base.to_le_bytes());
+            le32(&mut ix, 0);
+            for e in s.entries.drain(..) {
+                le32(&mut ix, e.offset);
+                le32(&mut ix, e.size | if e.key { 0 } else { NOT_KEY });
+            }
+            let at = self.pos;
+            let id = [b'i', b'x', s.id[0], s.id[1]];
+            let c = chunk(&id, &ix);
+            s.supers.push(SuperEntry { at, size: c.len() as u32, duration: sat32(s.duration) });
+            s.duration = 0;
+            self.put(&c)?;
+        }
+        let movi_size = sat32(self.pos - self.riff.movi - 8);
+        self.patch(self.riff.movi + 4, &movi_size.to_le_bytes())?;
+        if self.riffs == 1 {
+            let idx1 = std::mem::take(&mut self.idx1).concat();
+            self.put(&chunk(b"idx1", &idx1))?;
+        }
+        let riff_size = sat32(self.pos - self.riff.start - 8);
+        self.patch(self.riff.start + 4, &riff_size.to_le_bytes())
+    }
+
+    /// Close the current RIFF and start a `RIFF AVIX` extension.
+    fn next_riff(&mut self) -> Result<()> {
+        if self.riffs >= self.opts.max_riffs {
+            return Err(invalid(format!("the file needs more than max_riffs ({}) RIFFs", self.opts.max_riffs)));
+        }
+        self.end_riff()?;
+        let start = self.pos;
+        let mut head = Vec::with_capacity(24);
+        head.extend_from_slice(b"RIFF");
+        le32(&mut head, 0);
+        head.extend_from_slice(b"AVIX");
+        head.extend_from_slice(b"LIST");
+        le32(&mut head, 0);
+        head.extend_from_slice(b"movi");
+        self.put(&head)?;
+        self.riff = Riff { start, movi: start + 12 };
+        self.riffs += 1;
+        Ok(())
+    }
+
+    /// Close the file: the last RIFF's indexes and sizes, then the header list with the final
+    /// counts. Returns the writer, positioned at the end of the file.
+    pub fn finish(mut self) -> Result<W> {
+        self.end_riff()?;
+        let header = hdrl(&self.streams, self.main, self.opts.max_riffs, self.first_frames);
+        if header.len() != self.hdrl_len {
+            return Err(invalid("the header list changed size"));
+        }
+        self.patch(12, &header)?;
+        self.w.flush()?;
+        Ok(self.w)
+    }
+}
diff --git a/crates/media/src/avi/mux_tests.rs b/crates/media/src/avi/mux_tests.rs
new file mode 100644
index 000000000..96f77a04c
--- /dev/null
+++ b/crates/media/src/avi/mux_tests.rs
@@ -0,0 +1,205 @@
+//! The AVI muxer read back by this module's demuxer, through every index it writes.
+
+use std::io::Cursor;
+
+use super::*;
+
+/// Chunk `i` of a test stream: sizes vary (odd, even, empty) and the bytes name the chunk.
+fn payload(stream: usize, i: usize) -> Vec<u8> {
+    let len = match i % 7 {
+        0 => 1500 + i * 3,
+        3 => 0,
+        5 => 1,
+        _ => 200 + (i * 37) % 900,
+    };
+    (0..len).map(|k| (k as u32 ^ (i as u32) << 3 ^ (stream as u32) << 7) as u8).collect()
+}
+
+fn video() -> VideoSpec {
+    let mut v = VideoSpec::new(*b"XVID", 320, 240, 30000, 1001);
+    v.format.extra = vec![0, 0, 1, 0xB0, 3];
+    v.name = Some("picture".into());
+    v
+}
+
+fn pcm() -> AudioSpec {
+    let mut a = AudioSpec::pcm(48_000, 2, 16);
+    a.name = Some("sound".into());
+    a
+}
+
+/// Each stream's chunks: bytes and key frame.
+type Written = [Vec<(Vec<u8>, bool)>; 2];
+
+/// Write `frames` video frames (every 12th a key frame) each followed by an audio chunk of 4·k
+/// bytes, returning the file and what was written per stream.
+fn write(frames: usize, opts: MuxOptions) -> (Vec<u8>, Written) {
+    let mut w = AviWriter::new(Cursor::new(Vec::new()), vec![StreamSpec::Video(video()), StreamSpec::Audio(pcm())], opts).unwrap();
+    let mut written: Written = [Vec::new(), Vec::new()];
+    for i in 0..frames {
+        let v = payload(0, i);
+        let key = i % 12 == 0;
+        w.write_chunk(0, &v, key).unwrap();
+        written[0].push((v, key));
+        let a: Vec<u8> = payload(1, i).into_iter().take(4 * (1 + i % 400)).collect();
+        let a = a[..a.len() / 4 * 4].to_vec();
+        w.write_chunk(1, &a, true).unwrap();
+        written[1].push((a, true));
+    }
+    (w.finish().unwrap().into_inner(), written)
+}
+
+fn tables(file: &[u8], f: &AviFile) -> Written {
+    std::array::from_fn(|s| (0..f.streams[s].chunks.len()).map(|i| (f.read_chunk(file, s, i).unwrap(), f.streams[s].chunks[i].key)).collect())
+}
+
+/// The top-level chunks of a file: (id, form, size).
+fn riffs(file: &[u8]) -> Vec<([u8; 4], [u8; 4], u64)> {
+    children(&file, 0, file.len() as u64).into_iter().map(|(id, size, data)| (id, fourcc(file, data as usize), size)).collect()
+}
+
+#[test]
+fn headers_round_trip() {
+    let (file, written) = write(30, MuxOptions::default());
+    let f = open(&file).unwrap();
+    assert_eq!(f.index, IndexSource::OpenDml);
+    assert_eq!(f.header, MainHeader { micro_sec_per_frame: 33367, flags: 0x110, total_frames: 30, streams: 2, width: 320, height: 240 });
+    let (v, a) = (&f.streams[0], &f.streams[1]);
+    assert_eq!((v.kind, v.handler, v.scale, v.rate, v.length, v.sample_size), (StreamKind::Video, *b"XVID", 1001, 30000, 30, 0));
+    assert_eq!(v.video.as_ref(), Some(&video().format));
+    assert_eq!(v.name.as_deref(), Some("picture"));
+    let audio_bytes: usize = written[1].iter().map(|c| c.0.len()).sum();
+    assert_eq!((a.kind, a.scale, a.rate, a.sample_size, a.length as usize), (StreamKind::Audio, 4, 192_000, 4, audio_bytes / 4));
+    assert_eq!(a.audio.as_ref(), Some(&pcm().format));
+    assert_eq!(a.name.as_deref(), Some("sound"));
+    assert_eq!(v.codec_params().codec, crate::CodecId::Mpeg4Video);
+    assert_eq!(a.codec_params().codec, crate::CodecId::Pcm);
+    // one RIFF: hdrl, movi, idx1
+    assert_eq!(riffs(&file).iter().map(|r| (r.0, r.1)).collect::<Vec<_>>(), [(*b"RIFF", *b"AVI ")]);
+    assert_eq!(riffs(&file)[0].2 + 8, file.len() as u64);
+}
+
+#[test]
+fn every_index_describes_the_same_chunks() {
+    let (file, written) = write(40, MuxOptions::default());
+    for (opts, source) in [
+        (OpenOptions::default(), IndexSource::OpenDml),
+        (OpenOptions { ignore_odml: true, ignore_idx1: false }, IndexSource::Idx1),
+        (OpenOptions { ignore_odml: true, ignore_idx1: true }, IndexSource::Scan),
+    ] {
+        let f = open_with(&file, opts).unwrap();
+        assert_eq!(f.index, source);
+        let got = tables(&file, &f);
+        assert_eq!(got[1], written[1], "{source:?}: audio");
+        if source == IndexSource::Scan {
+            // a scan cannot tell key frames
+            assert_eq!(got[0].iter().map(|c| &c.0).collect::<Vec<_>>(), written[0].iter().map(|c| &c.0).collect::<Vec<_>>());
+        } else {
+            assert_eq!(got[0], written[0], "{source:?}: video");
+        }
+    }
+}
+
+#[test]
+fn large_files_continue_in_avix_extensions() {
+    let opts = MuxOptions { riff_limit: 24 << 10, max_riffs: 64 };
+    let (file, written) = write(200, opts);
+    let r = riffs(&file);
+    assert!(r.len() > 3, "{} RIFFs", r.len());
+    assert_eq!((r[0].0, r[0].1), (*b"RIFF", *b"AVI "));
+    assert!(r[1..].iter().all(|x| (x.0, x.1) == (*b"RIFF", *b"AVIX")));
+    assert!(r.iter().all(|x| x.2 + 8 <= opts.riff_limit), "a RIFF is over the limit: {r:?}");
+    assert_eq!(r.iter().map(|x| x.2 + 8).sum::<u64>(), file.len() as u64);
+
+    let f = open(&file).unwrap();
+    assert_eq!(f.index, IndexSource::OpenDml);
+    assert_eq!(tables(&file, &f), written);
+    assert_eq!(f.streams[0].length, 200);
+    // avih counts the first RIFF's frames; strh the whole stream
+    let first = f.streams[0].chunks.iter().filter(|c| c.offset < r[0].2).count() as u32;
+    assert_eq!(f.header.total_frames, first);
+    assert!(first < 200);
+    // idx1 covers the first RIFF and the AVIX extensions are scanned
+    let f = open_with(&file, OpenOptions { ignore_odml: true, ignore_idx1: false }).unwrap();
+    assert_eq!(f.index, IndexSource::Idx1);
+    assert_eq!(tables(&file, &f)[1], written[1]);
+    assert_eq!(f.streams[0].chunks.len(), 200);
+}
+
+#[test]
+fn a_file_can_start_inside_the_output() {
+    let mut out = Cursor::new(b"prefix".to_vec());
+    out.set_position(6);
+    let mut w = AviWriter::new(out, vec![StreamSpec::Video(video())], MuxOptions::default()).unwrap();
+    w.write_chunk(0, &[1, 2, 3], true).unwrap();
+    let bytes = w.finish().unwrap().into_inner();
+    assert_eq!(&bytes[..6], b"prefix");
+    let file = &bytes[6..];
+    let f = open(&file).unwrap();
+    assert_eq!(f.read_chunk(&file, 0, 0).unwrap(), [1, 2, 3]);
+    assert_eq!(f.header.total_frames, 1);
+}
+
+#[test]
+fn packet_timed_audio_counts_chunks() {
+    let mut mp3 = AudioSpec::pcm(44_100, 2, 0);
+    mp3.format = WaveFormat {
+        format_tag: 0x55,
+        channels: 2,
+        sample_rate: 44_100,
+        avg_bytes_per_sec: 16_000,
+        block_align: 1,
+        bits_per_sample: 0,
+        extra: vec![0; 12],
+    };
+    mp3.timing = AudioTiming::Packets { samples_per_packet: 1152 };
+    let mut w = AviWriter::new(Cursor::new(Vec::new()), vec![StreamSpec::Audio(mp3)], MuxOptions::default()).unwrap();
+    for i in 0..10 {
+        w.write_chunk(0, &payload(0, i), true).unwrap();
+    }
+    let file = w.finish().unwrap().into_inner();
+    let f = open(&file).unwrap();
+    let a = &f.streams[0];
+    assert_eq!((a.scale, a.rate, a.sample_size, a.length), (1152, 44_100, 0, 10));
+    assert_eq!(a.codec_params().codec, crate::CodecId::Mp3);
+    assert_eq!(f.header.width, 0);
+}
+
+#[test]
+fn codec_descriptions_pick_their_fourcc() {
+    let p = crate::CodecParams::new(crate::CodecId::Mpeg4Video).with_size(640, 360).with_extradata(vec![0, 0, 1, 0xB0]);
+    let v = VideoSpec::for_codec(&p, 25, 1).unwrap();
+    assert_eq!((v.format.compression, v.format.width, v.format.height, &v.format.extra[..]), (*b"FMP4", 640, 360, &[0, 0, 1, 0xB0][..]));
+    assert!(VideoSpec::for_codec(&crate::CodecParams::new(crate::CodecId::H264), 25, 1).is_none(), "no size");
+    assert!(VideoSpec::for_codec(&crate::CodecParams::new(crate::CodecId::Aac).with_size(1, 1), 25, 1).is_none());
+}
+
+#[test]
+fn bad_input_is_an_error() {
+    let new = |streams: Vec<StreamSpec>, opts| AviWriter::new(Cursor::new(Vec::new()), streams, opts).err();
+    let d = MuxOptions::default();
+    assert!(new(Vec::new(), d).is_some());
+    assert!(new(vec![StreamSpec::Video(video()); 101], d).is_some());
+    assert!(new(vec![StreamSpec::Video(video())], MuxOptions { riff_limit: 1000, ..d }).is_some());
+    assert!(new(vec![StreamSpec::Video(video())], MuxOptions { riff_limit: 3 << 30, ..d }).is_some());
+    assert!(new(vec![StreamSpec::Video(video())], MuxOptions { max_riffs: 0, ..d }).is_some());
+    assert!(new(vec![StreamSpec::Video(VideoSpec::new(*b"XVID", 16, 16, 0, 1))], d).is_some());
+    let mut a = pcm();
+    a.format.block_align = 0;
+    assert!(new(vec![StreamSpec::Audio(a)], d).is_some());
+    let mut a = pcm();
+    a.timing = AudioTiming::Packets { samples_per_packet: 0 };
+    assert!(new(vec![StreamSpec::Audio(a)], d).is_some());
+    // max_riffs large enough that the header list cannot fit in half a small RIFF
+    assert!(new(vec![StreamSpec::Video(video())], MuxOptions { riff_limit: 16 << 10, max_riffs: 1000 }).is_some());
+
+    let mut w = AviWriter::new(Cursor::new(Vec::new()), vec![StreamSpec::Video(video())], MuxOptions { riff_limit: 16 << 10, max_riffs: 2 }).unwrap();
+    assert!(w.write_chunk(1, &[0], true).is_err(), "no such stream");
+    assert!(w.write_chunk(0, &vec![0; 20 << 10], true).is_err(), "larger than a RIFF");
+    w.write_chunk(0, &vec![0; 10 << 10], true).unwrap();
+    w.write_chunk(0, &vec![0; 10 << 10], true).unwrap(); // the second RIFF
+    assert!(w.write_chunk(0, &vec![0; 10 << 10], true).is_err(), "a third RIFF is past max_riffs");
+    // what was written still closes into a readable file
+    let file = w.finish().unwrap().into_inner();
+    assert_eq!(open(&file).unwrap().streams[0].chunks.len(), 2);
+}
diff --git a/crates/media/tests/oracle_avi_mux.rs b/crates/media/tests/oracle_avi_mux.rs
new file mode 100644
index 000000000..f78acc92d
--- /dev/null
+++ b/crates/media/tests/oracle_avi_mux.rs
@@ -0,0 +1,156 @@
+//! AVI files from [`AviWriter`] read by ffmpeg and ffprobe (skipped without them): ffmpeg makes
+//! an MPEG-4 Part 2 elementary stream and PCM, the muxer interleaves them, and ffmpeg must decode
+//! the AVI to exactly what it decodes from the sources, in one RIFF and across AVIX extensions.
+
+use std::io::Cursor;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use craft_media::avi::{AudioSpec, AviWriter, MuxOptions, StreamSpec, VideoSpec};
+
+const FRAMES: usize = 50;
+/// 25 frames a second of 48 kHz stereo 16-bit PCM: bytes of audio a frame.
+const AUDIO_PER_FRAME: usize = 48_000 / 25 * 4;
+
+fn tools() -> Option<(PathBuf, PathBuf)> {
+    let ff = craft_media_testkit::ffmpeg_or_skip("avi muxer oracle")?;
+    let probe = craft_media_testkit::ffprobe()?;
+    Some((ff, probe))
+}
+
+fn run(cmd: &mut Command) -> Vec<u8> {
+    let out = cmd.output().expect("run tool");
+    assert!(out.status.success(), "{:?}: {}", cmd, String::from_utf8_lossy(&out.stderr));
+    // A plain WAVEFORMATEX has no channel mask, so ffmpeg notes the layout it assumes for any
+    // stereo PCM in AVI, its own files included. Every other line is a failure.
+    let diag: Vec<String> =
+        String::from_utf8_lossy(&out.stderr).lines().filter(|l| !l.contains("Guessed Channel Layout: stereo")).map(str::to_owned).collect();
+    assert!(diag.is_empty(), "{cmd:?} reported: {}", diag.join("\n"));
+    out.stdout
+}
+
+/// The sources: an MPEG-4 Part 2 elementary stream (I-VOP every 12 frames, no B-VOPs) and raw
+/// PCM, both from ffmpeg.
+fn sources(ff: &Path, dir: &Path) -> (Vec<u8>, Vec<u8>) {
+    let m4v = dir.join("video.m4v");
+    run(Command::new(ff)
+        .args(["-v", "warning", "-y", "-f", "lavfi", "-i", "testsrc2=s=160x120:r=25"])
+        .args(["-frames:v", &FRAMES.to_string(), "-c:v", "mpeg4", "-threads", "1", "-q:v", "5", "-g", "12", "-bf", "0", "-f", "m4v"])
+        .arg(&m4v));
+    let pcm = run(Command::new(ff)
+        .args(["-v", "warning", "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000"])
+        .args(["-t", "2", "-ac", "2", "-f", "s16le", "-"]));
+    (std::fs::read(&m4v).expect("read m4v"), pcm)
+}
+
+/// The VOPs of an elementary stream: each runs from its start code (the first from the start of
+/// the stream, so it carries the configuration headers) to the next. An I-VOP is a key frame.
+fn vops(es: &[u8]) -> Vec<(&[u8], bool)> {
+    let starts: Vec<usize> = es.windows(4).enumerate().filter(|(_, w)| *w == [0, 0, 1, 0xB6]).map(|(i, _)| i).collect();
+    let mut out = Vec::new();
+    for (k, &s) in starts.iter().enumerate() {
+        let from = if k == 0 { 0 } else { s };
+        let to = starts.get(k + 1).copied().unwrap_or(es.len());
+        out.push((&es[from..to], es.get(s + 4).is_some_and(|b| b >> 6 == 0)));
+    }
+    out
+}
+
+fn mux(video: &[(&[u8], bool)], pcm: &[u8], opts: MuxOptions) -> Vec<u8> {
+    let streams = vec![StreamSpec::Video(VideoSpec::new(*b"XVID", 160, 120, 25, 1)), StreamSpec::Audio(AudioSpec::pcm(48_000, 2, 16))];
+    let mut w = AviWriter::new(Cursor::new(Vec::new()), streams, opts).expect("writer");
+    for (i, (vop, key)) in video.iter().enumerate() {
+        w.write_chunk(0, vop, *key).expect("video");
+        let a = pcm.get(i * AUDIO_PER_FRAME..((i + 1) * AUDIO_PER_FRAME).min(pcm.len())).unwrap_or_default();
+        w.write_chunk(1, a, true).expect("audio");
+    }
+    w.finish().expect("finish").into_inner()
+}
+
+fn decode(ff: &Path, input: &Path, format: Option<&str>, map: &str, out: &[&str]) -> Vec<u8> {
+    let mut c = Command::new(ff);
+    c.args(["-v", "warning", "-nostdin"]);
+    if let Some(f) = format {
+        c.args(["-f", f]);
+    }
+    c.arg("-i").arg(input).args(["-map", map]).args(out).arg("-");
+    run(&mut c)
+}
+
+#[test]
+fn ffmpeg_decodes_muxed_files_like_their_sources() {
+    let Some((ff, probe)) = tools() else { return };
+    let dir = craft_media_testkit::private_dir("avi-mux");
+    let (es, pcm) = sources(&ff, &dir);
+    let video = vops(&es);
+    assert_eq!(video.len(), FRAMES);
+    assert!(video.iter().filter(|v| v.1).count() >= 4);
+    let want_video = decode(&ff, &dir.join("video.m4v"), Some("m4v"), "0:v", &["-f", "rawvideo", "-pix_fmt", "yuv420p"]);
+
+    for (name, opts) in [("one_riff.avi", MuxOptions::default()), ("avix.avi", MuxOptions { riff_limit: 64 << 10, max_riffs: 64 })] {
+        let file = mux(&video, &pcm, opts);
+        let path = dir.join(name);
+        std::fs::write(&path, &file).expect("write avi");
+        if name == "avix.avi" {
+            assert!(file.windows(4).filter(|w| *w == b"AVIX").count() >= 3, "{name}: AVIX extensions");
+        }
+        let got_video = decode(&ff, &path, None, "0:v", &["-f", "rawvideo", "-pix_fmt", "yuv420p"]);
+        assert!(got_video == want_video, "{name}: decoded pictures differ from the elementary stream's");
+        // ffmpeg reads an interleaved file front to back; a seek goes through the index (OpenDML
+        // when the file has it). 1.0 s lands after key frame 24, so frame 25 comes out first.
+        for at in ["1.0", "1.6"] {
+            let frame = (at.parse::<f64>().unwrap_or(0.0) * 25.0).round() as usize;
+            let size = 160 * 120 * 3 / 2;
+            let mut c = Command::new(&ff);
+            c.args(["-v", "warning", "-nostdin", "-ss", at, "-i"]).arg(&path).args([
+                "-map",
+                "0:v",
+                "-frames:v",
+                "1",
+                "-f",
+                "rawvideo",
+                "-pix_fmt",
+                "yuv420p",
+                "-",
+            ]);
+            let got = run(&mut c);
+            assert!(got == want_video[frame * size..(frame + 1) * size], "{name}: seeking to {at} s gave another picture than frame {frame}");
+        }
+        let got_audio = decode(&ff, &path, None, "0:a", &["-f", "s16le"]);
+        assert!(got_audio == pcm, "{name}: decoded audio differs from the PCM ({} vs {} bytes)", got_audio.len(), pcm.len());
+
+        let info = String::from_utf8_lossy(&run(Command::new(&probe)
+            .args([
+                "-v",
+                "error",
+                "-count_packets",
+                "-show_entries",
+                "stream=codec_name,codec_tag_string,width,height,avg_frame_rate,nb_read_packets,sample_rate,channels",
+                "-of",
+                "default=nw=1",
+            ])
+            .arg(&path)))
+        .into_owned();
+        for want in [
+            "codec_name=mpeg4",
+            "codec_tag_string=XVID",
+            "width=160",
+            "height=120",
+            "avg_frame_rate=25/1",
+            "nb_read_packets=50",
+            "codec_name=pcm_s16le",
+            "sample_rate=48000",
+            "channels=2",
+        ] {
+            assert!(info.lines().any(|l| l == want), "{name}: ffprobe lacks {want}:\n{info}");
+        }
+        let duration = String::from_utf8_lossy(&run(Command::new(&probe)
+            .args(["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0"])
+            .arg(&path)))
+        .trim()
+        .parse::<f64>()
+        .unwrap_or(0.0);
+        assert!((duration - 2.0).abs() < 0.05, "{name}: duration {duration}");
+    }
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/odf/src/text/tests_more/lossless.rs b/crates/odf/src/text/tests_more/lossless.rs
index 645c0b918..7d05e3491 100644
--- a/crates/odf/src/text/tests_more/lossless.rs
+++ b/crates/odf/src/text/tests_more/lossless.rs
@@ -345,8 +345,14 @@ const SAMPLES: [Sample; 18] = [
 
 /// Whether `xml` is well-formed: every element closed, in order, once.
 fn well_formed(xml: &[u8]) -> bool {
-    let limits =
-        craft_xml::Limits { max_input: usize::MAX, max_depth: usize::MAX, max_nodes: usize::MAX, max_attrs: usize::MAX, max_attrs_total: usize::MAX };
+    let limits = craft_xml::Limits {
+        max_input: usize::MAX,
+        max_depth: usize::MAX,
+        max_nodes: usize::MAX,
+        max_elements: usize::MAX,
+        max_attrs: usize::MAX,
+        max_attrs_total: usize::MAX,
+    };
     craft_xml::Options::default().strict().with_limits(limits).parse(xml).is_ok()
 }
 
diff --git a/crates/odf/src/text/xml.rs b/crates/odf/src/text/xml.rs
index ef5a0e0d1..d96ee4917 100644
--- a/crates/odf/src/text/xml.rs
+++ b/crates/odf/src/text/xml.rs
@@ -45,8 +45,14 @@ pub(super) fn events(xml: &[u8], mut f: impl FnMut(Ev)) {
 pub(super) fn events_at(xml: &[u8], mut f: impl FnMut(Ev, (usize, usize))) {
     // Names and attributes as written; no limit but the input's own size (each part is at most a
     // package entry), and at most 128 attributes kept per element.
-    let limits =
-        craft_xml::Limits { max_input: usize::MAX, max_depth: usize::MAX, max_nodes: usize::MAX, max_attrs: usize::MAX, max_attrs_total: usize::MAX };
+    let limits = craft_xml::Limits {
+        max_input: usize::MAX,
+        max_depth: usize::MAX,
+        max_nodes: usize::MAX,
+        max_elements: usize::MAX,
+        max_attrs: usize::MAX,
+        max_attrs_total: usize::MAX,
+    };
     let opts = craft_xml::Options::default().with_limits(limits);
     let mut events = opts.events(xml);
     // Malformed XML ends the stream.
diff --git a/crates/pdf/Cargo.toml b/crates/pdf/Cargo.toml
index 193aeb9df..b370416ab 100644
--- a/crates/pdf/Cargo.toml
+++ b/crates/pdf/Cargo.toml
@@ -14,6 +14,7 @@ workspace = true
 default = []
 read = ["dep:hayro-syntax", "dep:thiserror"]
 interpret = ["read", "dep:hayro-interpret"]
+paths = ["interpret", "dep:kurbo"]
 raster = ["interpret", "dep:hayro", "dep:bytemuck"]
 write = ["dep:krilla", "dep:thiserror"]
 write-pdf = ["write", "krilla/pdf"]
@@ -40,6 +41,7 @@ stringprep = { version = "0.1", optional = true }
 zeroize = { version = "1", optional = true }
 # PDF date strings in the object layer (`cos`).
 chrono = { workspace = true, optional = true }
+kurbo = { workspace = true, optional = true }
 
 # On the web, a rewrite's fresh file identifier (`cos`) takes its entropy from the browser
 # (`crypto.getRandomValues`); native builds compile neither.
diff --git a/crates/pdf/src/lib.rs b/crates/pdf/src/lib.rs
index e052c7304..ed9f21a79 100644
--- a/crates/pdf/src/lib.rs
+++ b/crates/pdf/src/lib.rs
@@ -21,6 +21,8 @@ pub use link::safe_url;
 mod read;
 #[cfg(feature = "read")]
 pub use read::*;
+#[cfg(feature = "paths")]
+pub mod paths;
 #[cfg(feature = "raster")]
 pub mod raster;
 #[cfg(feature = "write")]
diff --git a/crates/pdf/src/paths.rs b/crates/pdf/src/paths.rs
new file mode 100644
index 000000000..0ed5dce8b
--- /dev/null
+++ b/crates/pdf/src/paths.rs
@@ -0,0 +1,196 @@
+//! Bounded extraction of page vector paths from PDF content streams.
+//!
+//! Paths are returned in page-oriented points with `/UserUnit`, rotation and crop origin applied.
+//! Text glyphs and raster images are counted as omitted content; clipping and paint are not applied.
+
+use hayro_interpret::font::Glyph;
+use hayro_interpret::{
+    BlendMode, ClipPath, Device, GlyphDrawMode, Image, InterpreterCache, InterpreterSettings, Paint, PathDrawMode, RectExt, SoftMask, TransformExt,
+};
+use kurbo::{Affine, BezPath, Rect};
+use std::sync::{
+    Arc,
+    atomic::{AtomicBool, Ordering},
+};
+
+/// Limits for vector path extraction. They bound the output model, not interpreter peak memory.
+#[derive(Debug, Clone, Copy)]
+pub struct Limits {
+    pub max_input_bytes: usize,
+    pub max_pages: usize,
+    pub max_paths: usize,
+    pub max_path_elements: usize,
+}
+
+impl Default for Limits {
+    fn default() -> Self {
+        Self { max_input_bytes: 64 * 1024 * 1024, max_pages: 1000, max_paths: 200_000, max_path_elements: 2_000_000 }
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error(transparent)]
+    Open(#[from] crate::read::OpenError),
+    #[error(transparent)]
+    Interpret(#[from] crate::read::ExecutionError),
+    #[error("PDF contains more than {limit} pages")]
+    Pages { limit: usize },
+    #[error("PDF has no page at index {index}")]
+    PageIndex { index: usize },
+    #[error("PDF path output exceeds configured limit")]
+    OutputLimit,
+}
+
+/// Extracted paths for one PDF page, normalized to an origin-zero page in physical points.
+#[derive(Debug, Clone)]
+pub struct Page {
+    pub crop_box: Rect,
+    pub paths: Vec<BezPath>,
+    pub omitted_text: usize,
+    pub omitted_images: usize,
+    pub clips_seen: usize,
+}
+
+/// Pages from one PDF. Paths from separate pages are never combined.
+#[derive(Debug, Clone)]
+pub struct Imported {
+    pub pages: Vec<Page>,
+    pub warnings: Vec<String>,
+}
+
+/// Open and interpret vector content using shared PDF parsing and interpreter APIs.
+pub fn import(bytes: &[u8], limits: Limits) -> Result<Imported, Error> {
+    import_selected(bytes, limits, None)
+}
+
+/// Interpret only the requested page and apply path and element limits to that page's output.
+pub fn import_page(bytes: &[u8], page_index: usize, limits: Limits) -> Result<Imported, Error> {
+    import_selected(bytes, limits, Some(page_index))
+}
+
+fn import_selected(bytes: &[u8], limits: Limits, selected: Option<usize>) -> Result<Imported, Error> {
+    let options = crate::read::OpenOptions { max_input_bytes: limits.max_input_bytes, ..Default::default() };
+    let pdf = crate::read::open_slice_with_options(bytes, None, &options)?;
+    if pdf.pages().len() > limits.max_pages {
+        return Err(Error::Pages { limit: limits.max_pages });
+    }
+    if selected.is_some_and(|index| index >= pdf.pages().len()) {
+        return Err(Error::PageIndex { index: selected.unwrap_or_default() });
+    }
+    let cache = InterpreterCache::new();
+    let truncated = Arc::new(AtomicBool::new(false));
+    let truncation_flag = truncated.clone();
+    let settings = InterpreterSettings {
+        warning_sink: Arc::new(move |warning| {
+            if matches!(warning, hayro_interpret::InterpreterWarning::ContentTruncated) {
+                truncation_flag.store(true, Ordering::Relaxed);
+            }
+        }),
+        ..InterpreterSettings::default()
+    };
+    let mut pages = Vec::with_capacity(pdf.pages().len());
+    let mut total_paths = 0usize;
+    let mut total_elements = 0usize;
+    for (page_index, page) in pdf.pages().iter().enumerate() {
+        if selected.is_some_and(|index| index != page_index) {
+            continue;
+        }
+        let source_crop_box = page.intersected_crop_box().to_kurbo();
+        let (width, height) = page.render_dimensions();
+        let crop_box = Rect::new(0.0, 0.0, f64::from(width), f64::from(height));
+        let initial_transform = page.initial_transform(true).to_kurbo();
+        let mut context = hayro_interpret::Context::new(initial_transform, source_crop_box, &cache, pdf.xref(), settings.clone());
+        let mut device = Collector {
+            max_paths: if selected.is_some() { limits.max_paths } else { limits.max_paths.saturating_sub(total_paths) },
+            max_elements: if selected.is_some() { limits.max_path_elements } else { limits.max_path_elements.saturating_sub(total_elements) },
+            ..Collector::default()
+        };
+        crate::read::interpret_page(page, &mut context, &mut device)?;
+        if device.exceeded {
+            return Err(Error::OutputLimit);
+        }
+        if device.paths.len() > limits.max_paths || device.paths.iter().map(|path| path.elements().len()).sum::<usize>() > limits.max_path_elements {
+            return Err(Error::OutputLimit);
+        }
+        total_paths = total_paths.saturating_add(device.paths.len());
+        total_elements = device.paths.iter().fold(total_elements, |count, path| count.saturating_add(path.elements().len()));
+        if total_paths > limits.max_paths || total_elements > limits.max_path_elements {
+            return Err(Error::OutputLimit);
+        }
+        pages.push(Page {
+            crop_box,
+            paths: device.paths,
+            omitted_text: device.omitted_text,
+            omitted_images: device.omitted_images,
+            clips_seen: device.clips_seen,
+        });
+    }
+    let mut warnings = Vec::new();
+    if pages.iter().any(|page| page.omitted_text > 0) {
+        warnings.push("text glyphs are not returned as paths".into());
+    }
+    if pages.iter().any(|page| page.omitted_images > 0) {
+        warnings.push("raster images are not returned as paths".into());
+    }
+    if pages.iter().any(|page| page.clips_seen > 0) {
+        warnings.push("clip paths are not applied to extracted geometry".into());
+    }
+    if truncated.load(Ordering::Relaxed) {
+        warnings.push("PDF content was truncated by the interpreter".into());
+    }
+    Ok(Imported { pages, warnings })
+}
+
+#[derive(Default)]
+struct Collector {
+    paths: Vec<BezPath>,
+    last_fill_path: Option<BezPath>,
+    omitted_text: usize,
+    omitted_images: usize,
+    clips_seen: usize,
+    max_paths: usize,
+    max_elements: usize,
+    elements: usize,
+    exceeded: bool,
+}
+
+impl Device<'_> for Collector {
+    fn set_soft_mask(&mut self, _: Option<SoftMask<'_>>) {}
+    fn set_blend_mode(&mut self, _: BlendMode) {}
+    fn draw_path(&mut self, path: &BezPath, transform: Affine, _: &Paint<'_>, mode: &PathDrawMode) {
+        if path.is_empty() {
+            return;
+        }
+        let path = transform * path.clone();
+        match mode {
+            PathDrawMode::Fill(_) => self.last_fill_path = Some(path.clone()),
+            PathDrawMode::Stroke(_) => {
+                if self.last_fill_path.take().as_ref() == Some(&path) {
+                    return;
+                }
+            }
+        }
+        let count = path.elements().len();
+        if self.paths.len() >= self.max_paths || self.elements.saturating_add(count) > self.max_elements {
+            self.exceeded = true;
+            return;
+        }
+        self.elements = self.elements.saturating_add(count);
+        self.paths.push(path);
+    }
+    fn push_clip_path(&mut self, _: &ClipPath) {
+        self.clips_seen = self.clips_seen.saturating_add(1);
+    }
+    fn push_transparency_group(&mut self, _: f32, _: Option<SoftMask<'_>>, _: BlendMode) {}
+    fn draw_glyph(&mut self, _: &Glyph<'_>, _: Affine, _: Affine, _: &Paint<'_>, _: &GlyphDrawMode) {
+        self.last_fill_path = None;
+        self.omitted_text = self.omitted_text.saturating_add(1);
+    }
+    fn draw_image(&mut self, _: Image<'_, '_>, _: Affine) {
+        self.last_fill_path = None;
+        self.omitted_images = self.omitted_images.saturating_add(1);
+    }
+    fn pop_clip_path(&mut self) {}
+    fn pop_transparency_group(&mut self) {}
+}
diff --git a/crates/scraft-format/Cargo.toml b/crates/scraft-format/Cargo.toml
new file mode 100644
index 000000000..9ec17cf9f
--- /dev/null
+++ b/crates/scraft-format/Cargo.toml
@@ -0,0 +1,24 @@
+[package]
+name = "craft-scraft-format"
+description = "SoundCraft's versioned native session document model and JSON schema"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+craft-audio = { workspace = true, features = ["lossless-encode", "peaks"] }
+craft-midi = { workspace = true, features = ["serde"] }
+craft-time.workspace = true
+craft-zip.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+craft-audio = { workspace = true, features = ["decode", "serde"] }
+proptest.workspace = true
diff --git a/crates/scraft-format/README.md b/crates/scraft-format/README.md
new file mode 100644
index 000000000..c2df56206
--- /dev/null
+++ b/crates/scraft-format/README.md
@@ -0,0 +1,15 @@
+# craft-scraft-format
+
+The native SoundCraft session document, `.scraft` JSON schema and typed reader/writer. `Session`
+and its nested types are the wire representation; the library checks `format_version` before
+parsing, deserializes the document directly (without building a `serde_json::Value` tree), then
+sanitizes and validates the resulting session. `Session::to_json` writes the same pretty JSON
+representation.
+
+The crate retains SoundCraft's serialized enum names, defaults, compatibility behavior for older
+fields, 256 MiB session byte limit, character limits, and duplicate/exhausted ID checks. Its time
+fields use `craft_time::soundcraft`, the exact sample-index time API retained by `craft-time`.
+MIDI sequence values use `craft-midi`'s serde representation.
+
+The application still maps sessions to UI state, engine state, media paths and audio pools. The
+session schema and its format-specific parsing, writing, sanitization and validation live here.
diff --git a/crates/scraft-format/src/automation.rs b/crates/scraft-format/src/automation.rs
new file mode 100644
index 000000000..6d597682e
--- /dev/null
+++ b/crates/scraft-format/src/automation.rs
@@ -0,0 +1,394 @@
+//! Automation lanes and modes.
+
+use crate::soundcraft_time::Samples;
+
+/// Automation modes (per track).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum AutomationMode {
+    Off,
+    #[default]
+    Read,
+    Touch,
+    Latch,
+    TouchLatch,
+    Write,
+    Trim,
+}
+
+impl AutomationMode {
+    pub const ALL: [AutomationMode; 7] = [
+        AutomationMode::Off,
+        AutomationMode::Read,
+        AutomationMode::Touch,
+        AutomationMode::Latch,
+        AutomationMode::TouchLatch,
+        AutomationMode::Write,
+        AutomationMode::Trim,
+    ];
+    pub fn label(self) -> &'static str {
+        match self {
+            AutomationMode::Off => "off",
+            AutomationMode::Read => "read",
+            AutomationMode::Touch => "touch",
+            AutomationMode::Latch => "latch",
+            AutomationMode::TouchLatch => "touch/latch",
+            AutomationMode::Write => "write",
+            AutomationMode::Trim => "trim",
+        }
+    }
+    pub fn from_id(s: &str) -> Option<AutomationMode> {
+        let s = s.to_ascii_lowercase();
+        AutomationMode::ALL.into_iter().find(|m| m.label() == s || m.label().replace('/', "_") == s || format!("{m:?}").to_ascii_lowercase() == s)
+    }
+    pub fn reads(self) -> bool {
+        !matches!(self, AutomationMode::Off)
+    }
+}
+
+/// Which parameter an automation lane controls.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize)]
+pub enum AutoParam {
+    /// Fader level, dB.
+    Volume,
+    /// Pan, -1..1 (index = which panner of a stereo track: 0 left, 1 right).
+    Pan(u8),
+    /// Mute (0/1).
+    Mute,
+    /// Send level, dB.
+    SendLevel(u8),
+    SendPan(u8),
+    SendMute(u8),
+    /// Insert slot + parameter id.
+    Plugin {
+        slot: u8,
+        param: String,
+    },
+}
+
+impl AutoParam {
+    pub fn label(&self) -> String {
+        match self {
+            AutoParam::Volume => "volume".into(),
+            AutoParam::Pan(0) => "pan".into(),
+            AutoParam::Pan(i) => format!("pan {}", u16::from(*i) + 1),
+            AutoParam::Mute => "mute".into(),
+            AutoParam::SendLevel(i) => format!("send {} level", slot_letter(*i)),
+            AutoParam::SendPan(i) => format!("send {} pan", slot_letter(*i)),
+            AutoParam::SendMute(i) => format!("send {} mute", slot_letter(*i)),
+            AutoParam::Plugin { slot, param } => format!("insert {} {param}", slot_letter(*slot)),
+        }
+    }
+    /// Parse ids like `volume`, `pan`, `pan2`, `mute`, `send_a_level`, `plugin:a:threshold`.
+    pub fn parse(s: &str) -> Option<AutoParam> {
+        let orig = s.trim();
+        let s = orig.to_ascii_lowercase();
+        match s.as_str() {
+            "volume" | "vol" => return Some(AutoParam::Volume),
+            "pan" | "pan1" => return Some(AutoParam::Pan(0)),
+            "pan2" => return Some(AutoParam::Pan(1)),
+            "mute" => return Some(AutoParam::Mute),
+            _ => {}
+        }
+        if let Some(rest) = s.strip_prefix("send_") {
+            let mut it = rest.splitn(2, '_');
+            let slot = letter_slot(it.next()?)?;
+            return match it.next()? {
+                "level" => Some(AutoParam::SendLevel(slot)),
+                "pan" => Some(AutoParam::SendPan(slot)),
+                "mute" => Some(AutoParam::SendMute(slot)),
+                _ => None,
+            };
+        }
+        if let Some(rest) = s.strip_prefix("plugin:") {
+            let (slot, param) = rest.split_once(':')?;
+            // ASCII lowercasing keeps byte offsets, so take the param from the original.
+            let param = orig.get(orig.len() - param.len()..)?;
+            return Some(AutoParam::Plugin { slot: letter_slot(slot)?, param: param.to_string() });
+        }
+        None
+    }
+    /// Value range and default.
+    pub fn range(&self) -> (f32, f32, f32) {
+        match self {
+            AutoParam::Volume | AutoParam::SendLevel(_) => (-144.0, 12.0, 0.0),
+            AutoParam::Pan(_) | AutoParam::SendPan(_) => (-1.0, 1.0, 0.0),
+            AutoParam::Mute | AutoParam::SendMute(_) => (0.0, 1.0, 0.0),
+            AutoParam::Plugin { .. } => (f32::MIN, f32::MAX, 0.0),
+        }
+    }
+}
+
+pub fn slot_letter(i: u8) -> char {
+    char::from(b'A'.saturating_add(i.min(25)))
+}
+
+fn letter_slot(s: &str) -> Option<u8> {
+    let c = s.chars().next()?.to_ascii_uppercase();
+    if s.len() == 1 && c.is_ascii_uppercase() { Some(c as u8 - b'A') } else { s.parse().ok() }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct AutomationPoint {
+    pub at: Samples,
+    pub value: f32,
+}
+
+/// A breakpoint automation lane. Points are kept sorted by time.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct AutomationLane {
+    pub param: AutoParam,
+    pub points: Vec<AutomationPoint>,
+    #[serde(default)]
+    pub enabled: bool,
+}
+
+impl AutomationLane {
+    pub fn new(param: AutoParam) -> Self {
+        AutomationLane { param, points: Vec::new(), enabled: true }
+    }
+
+    /// Value at `at` (linear interpolation; `default` when empty).
+    pub fn value_at(&self, at: Samples, default: f32) -> f32 {
+        let pts = &self.points;
+        let Some(first) = pts.first() else { return default };
+        if at <= first.at {
+            return first.value;
+        }
+        let idx = pts.partition_point(|p| p.at <= at);
+        match (pts.get(idx.wrapping_sub(1)), pts.get(idx)) {
+            (Some(a), Some(b)) if b.at > a.at => {
+                // Mute-like lanes step instead of ramping.
+                if matches!(self.param, AutoParam::Mute | AutoParam::SendMute(_)) {
+                    return a.value;
+                }
+                // Widen so far-apart breakpoints cannot overflow i64.
+                let span = i128::from(b.at) - i128::from(a.at);
+                let off = i128::from(at) - i128::from(a.at);
+                // Interpolate in f64: the f32 difference overflows for
+                // opposite-sign values near f32::MAX.
+                let (av, bv) = (f64::from(a.value), f64::from(b.value));
+                (av + (bv - av) * (off as f64 / span as f64)) as f32
+            }
+            (Some(a), _) => a.value,
+            _ => default,
+        }
+    }
+
+    /// Insert or replace a breakpoint.
+    pub fn set_point(&mut self, at: Samples, value: f32) {
+        let (lo, hi, _) = self.param.range();
+        let value = if value.is_nan() { 0.0 } else { value.clamp(lo, hi) };
+        match self.points.binary_search_by(|p| p.at.cmp(&at)) {
+            Ok(i) => {
+                if let Some(p) = self.points.get_mut(i) {
+                    p.value = value;
+                }
+            }
+            Err(i) => self.points.insert(i, AutomationPoint { at, value }),
+        }
+    }
+
+    /// Remove points in `[start, end)`.
+    pub fn clear_range(&mut self, start: Samples, end: Samples) -> usize {
+        let before = self.points.len();
+        self.points.retain(|p| p.at < start || p.at >= end);
+        before - self.points.len()
+    }
+
+    /// Write a constant value over a range, keeping the surrounding curve intact with anchor points.
+    pub fn write_range(&mut self, start: Samples, end: Samples, value: f32, default: f32) {
+        if end <= start {
+            return;
+        }
+        let before = self.value_at(start.saturating_sub(1), default);
+        let after = self.value_at(end, default);
+        self.clear_range(start, end.saturating_add(1));
+        if start > 0 {
+            self.set_point(start - 1, before);
+        }
+        self.set_point(start, value);
+        self.set_point(end, value);
+        let anchor = end.saturating_add(1);
+        // A real breakpoint already at `end + 1` keeps its own value.
+        if self.points.binary_search_by(|p| p.at.cmp(&anchor)).is_err() {
+            self.set_point(anchor, after);
+        }
+    }
+
+    /// Thin: remove points whose removal changes the curve by less than `tolerance`.
+    pub fn thin(&mut self, tolerance: f32) -> usize {
+        // Linear thinning would move the transitions of step lanes.
+        if matches!(self.param, AutoParam::Mute | AutoParam::SendMute(_)) || self.points.len() < 3 || tolerance.is_nan() {
+            return 0;
+        }
+        let tolerance = f64::from(tolerance);
+        let mut keep = vec![true; self.points.len()];
+        let mut last = 0usize;
+        // Slopes from the last kept point that keep every point removed since then within `tolerance`.
+        let (mut lo, mut hi) = (f64::NEG_INFINITY, f64::INFINITY);
+        for i in 1..self.points.len() - 1 {
+            let (Some(a), Some(b), Some(c)) = (self.points.get(last), self.points.get(i), self.points.get(i + 1)) else { continue };
+            let dt = b.at.saturating_sub(a.at) as f64;
+            let rise = f64::from(b.value) - f64::from(a.value);
+            lo = lo.max((rise - tolerance) / dt);
+            hi = hi.min((rise + tolerance) / dt);
+            let slope = (f64::from(c.value) - f64::from(a.value)) / c.at.saturating_sub(a.at) as f64;
+            if (lo..=hi).contains(&slope) {
+                if let Some(k) = keep.get_mut(i) {
+                    *k = false;
+                }
+            } else {
+                last = i;
+                (lo, hi) = (f64::NEG_INFINITY, f64::INFINITY);
+            }
+        }
+        let before = self.points.len();
+        let mut it = keep.iter();
+        self.points.retain(|_| it.next().copied().unwrap_or(true));
+        before - self.points.len()
+    }
+
+    /// Shift points at or after `from` by `delta` (Shuffle edits, Insert Time).
+    pub fn shift_from(&mut self, from: Samples, delta: Samples) {
+        for p in &mut self.points {
+            if p.at >= from {
+                p.at = p.at.saturating_add(delta).max(0);
+            }
+        }
+        self.points.sort_by_key(|p| p.at);
+        self.points.dedup_by_key(|p| p.at);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_keeps_plugin_param_case() {
+        let p = AutoParam::Plugin { slot: 0, param: "Cutoff".into() };
+        assert_eq!(AutoParam::parse("plugin:a:Cutoff"), Some(p));
+        assert_eq!(AutoParam::parse("Plugin:B:Mix"), Some(AutoParam::Plugin { slot: 1, param: "Mix".into() }));
+        assert_eq!(AutoParam::parse("Volume"), Some(AutoParam::Volume));
+        assert_eq!(AutoParam::parse("SEND_B_LEVEL"), Some(AutoParam::SendLevel(1)));
+    }
+
+    #[test]
+    fn value_at_far_apart_points_does_not_overflow() {
+        let mut l = AutomationLane::new(AutoParam::Volume);
+        l.set_point(-1, 0.0);
+        l.set_point(i64::MAX, -10.0);
+        let v = l.value_at(5, 0.0);
+        assert!(v.is_finite() && (-10.0..=0.0).contains(&v));
+        let w = l.value_at(i64::MAX - 1, 0.0);
+        assert!(w.is_finite() && (-10.0..=0.0).contains(&w));
+    }
+
+    #[test]
+    fn value_at_opposite_sign_extremes_stays_finite() {
+        let mut l = AutomationLane::new(AutoParam::Plugin { slot: 0, param: "Cutoff".into() });
+        l.set_point(0, -3.0e38);
+        l.set_point(1000, 3.0e38);
+        let v = l.value_at(500, 0.0);
+        assert!(v.is_finite() && v.abs() < 1.0e32, "mid value {v}");
+        let w = l.value_at(1, 0.0);
+        assert!(w.is_finite() && w < -2.9e38, "early value {w}");
+    }
+
+    #[test]
+    fn pan_label_max_does_not_overflow() {
+        assert_eq!(AutoParam::Pan(255).label(), "pan 256");
+    }
+
+    #[test]
+    fn interpolation_and_steps() {
+        let mut l = AutomationLane::new(AutoParam::Volume);
+        assert_eq!(l.value_at(10, -3.0), -3.0);
+        l.set_point(0, 0.0);
+        l.set_point(100, -10.0);
+        assert!((l.value_at(50, 0.0) + 5.0).abs() < 1e-6);
+        assert_eq!(l.value_at(1000, 0.0), -10.0);
+        let mut m = AutomationLane::new(AutoParam::Mute);
+        m.set_point(0, 0.0);
+        m.set_point(100, 1.0);
+        assert_eq!(m.value_at(99, 0.0), 0.0);
+        assert_eq!(m.value_at(100, 0.0), 1.0);
+    }
+
+    #[test]
+    fn write_range_keeps_point_right_after_end() {
+        let mut l = AutomationLane::new(AutoParam::Volume);
+        l.set_point(0, 0.0);
+        l.set_point(11, -100.0);
+        l.write_range(2, 10, -20.0, 0.0);
+        assert_eq!(l.value_at(11, 0.0), -100.0);
+    }
+
+    #[test]
+    fn write_range_preserves_outside() {
+        let mut l = AutomationLane::new(AutoParam::Volume);
+        l.set_point(0, 0.0);
+        l.set_point(1000, 0.0);
+        l.write_range(200, 400, -20.0, 0.0);
+        assert_eq!(l.value_at(100, 0.0), 0.0);
+        assert_eq!(l.value_at(300, 0.0), -20.0);
+        assert_eq!(l.value_at(600, 0.0), 0.0);
+    }
+
+    #[test]
+    fn thin_removes_collinear() {
+        let mut l = AutomationLane::new(AutoParam::Volume);
+        for i in 0..=10 {
+            l.set_point(i * 10, -(i as f32));
+        }
+        assert_eq!(l.thin(0.01), 9);
+        assert_eq!(l.points.len(), 2);
+    }
+
+    #[test]
+    fn thin_keeps_removed_points_within_tolerance() {
+        for direction in [1.0, -1.0] {
+            let mut lane = AutomationLane::new(AutoParam::Volume);
+            for (at, value) in [(0, 0.0), (100, 0.0), (200, 0.0), (300, 0.12), (400, 0.26)] {
+                lane.set_point(at, value * direction);
+            }
+            let original = lane.points.clone();
+            let tolerance = 0.1;
+            assert!(lane.thin(tolerance) > 0);
+            for point in original {
+                let error = (lane.value_at(point.at, 0.0) - point.value).abs();
+                assert!(error <= tolerance, "at {}: error {error} exceeds {tolerance}", point.at);
+            }
+        }
+    }
+
+    #[test]
+    fn thin_keeps_mute_changes_in_place() {
+        for param in [AutoParam::Mute, AutoParam::SendMute(0)] {
+            let mut lane = AutomationLane::new(param);
+            for (at, value) in [(0, 0.0), (9000, 1.0), (10000, 1.0)] {
+                lane.set_point(at, value);
+            }
+            lane.thin(0.1);
+            assert_eq!(lane.value_at(8999, 0.0), 0.0);
+            assert_eq!(lane.value_at(9000, 0.0), 1.0);
+        }
+    }
+
+    #[test]
+    fn param_ids() {
+        assert_eq!(AutoParam::parse("send_b_level"), Some(AutoParam::SendLevel(1)));
+        assert_eq!(AutoParam::parse("plugin:a:threshold"), Some(AutoParam::Plugin { slot: 0, param: "threshold".into() }));
+        assert_eq!(AutoParam::parse("nope"), None);
+        assert_eq!(AutomationMode::from_id("touch/latch"), Some(AutomationMode::TouchLatch));
+    }
+
+    #[test]
+    fn set_point_clamps_nan() {
+        let mut l = AutomationLane::new(AutoParam::Pan(0));
+        l.set_point(0, f32::NAN);
+        l.set_point(1, 5.0);
+        assert_eq!(l.points[0].value, 0.0);
+        assert_eq!(l.points[1].value, 1.0);
+    }
+}
diff --git a/crates/scraft-format/src/b64.rs b/crates/scraft-format/src/b64.rs
new file mode 100644
index 000000000..100a9a08f
--- /dev/null
+++ b/crates/scraft-format/src/b64.rs
@@ -0,0 +1,114 @@
+//! Standard base64 (RFC 4648, `+/` alphabet, `=` padding), used to keep opaque plugin state
+//! blobs in the JSON session file. Decoding treats its input as hostile: it rejects bad
+//! characters and bad padding, ignores ASCII whitespace, and caps the output size.
+
+/// Largest blob [`decode`] will produce (64 MiB): bigger session fields are rejected.
+pub const MAX_DECODED_BYTES: usize = 64 << 20;
+
+const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/// Encodes bytes as padded standard base64.
+pub fn encode(data: &[u8]) -> String {
+    let mut out = String::with_capacity(data.len().div_ceil(3).saturating_mul(4));
+    for chunk in data.chunks(3) {
+        let b = [chunk.first().copied().unwrap_or(0), chunk.get(1).copied().unwrap_or(0), chunk.get(2).copied().unwrap_or(0)];
+        let n = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
+        let sym = |shift: u32| char::from(ALPHABET.get(((n >> shift) & 63) as usize).copied().unwrap_or(b'A'));
+        out.push(sym(18));
+        out.push(sym(12));
+        out.push(if chunk.len() > 1 { sym(6) } else { '=' });
+        out.push(if chunk.len() > 2 { sym(0) } else { '=' });
+    }
+    out
+}
+
+fn value(c: u8) -> Option<u32> {
+    let v = match c {
+        b'A'..=b'Z' => c - b'A',
+        b'a'..=b'z' => c - b'a' + 26,
+        b'0'..=b'9' => c - b'0' + 52,
+        b'+' => 62,
+        b'/' => 63,
+        _ => return None,
+    };
+    Some(u32::from(v))
+}
+
+/// Decodes padded (or unpadded) standard base64. `None` for malformed input or a result larger
+/// than [`MAX_DECODED_BYTES`].
+pub fn decode(text: &str) -> Option<Vec<u8>> {
+    if text.bytes().filter(|c| !c.is_ascii_whitespace()).count() > MAX_DECODED_BYTES.div_ceil(3).saturating_mul(4) {
+        return None;
+    }
+    let syms: Vec<u8> = text.bytes().filter(|c| !c.is_ascii_whitespace()).collect();
+    let body = syms.strip_suffix(b"==").or_else(|| syms.strip_suffix(b"=")).unwrap_or(&syms);
+    if body.contains(&b'=') || (syms.len() != body.len() && !syms.len().is_multiple_of(4)) || body.len() % 4 == 1 {
+        return None;
+    }
+    let decoded_len = body.len() / 4 * 3 + body.len() % 4 * 3 / 4;
+    if decoded_len > MAX_DECODED_BYTES {
+        return None;
+    }
+    let mut out = Vec::with_capacity(decoded_len);
+    for chunk in body.chunks(4) {
+        let mut n = 0u32;
+        for (i, &c) in chunk.iter().enumerate() {
+            n |= value(c)? << (18 - 6 * i as u32);
+        }
+        let bytes = [(n >> 16) as u8, (n >> 8) as u8, n as u8];
+        out.extend_from_slice(bytes.get(..chunk.len() - 1)?);
+    }
+    Some(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rfc4648_vectors_round_trip() {
+        for (plain, enc) in
+            [("", ""), ("f", "Zg=="), ("fo", "Zm8="), ("foo", "Zm9v"), ("foob", "Zm9vYg=="), ("fooba", "Zm9vYmE="), ("foobar", "Zm9vYmFy")]
+        {
+            assert_eq!(encode(plain.as_bytes()), enc);
+            assert_eq!(decode(enc).unwrap(), plain.as_bytes());
+        }
+        let all: Vec<u8> = (0..=255).collect();
+        assert_eq!(decode(&encode(&all)).unwrap(), all);
+        assert_eq!(decode("Zm9v\nYmE=").unwrap(), b"fooba", "whitespace is ignored");
+        assert_eq!(decode("Zm9vYmE").unwrap(), b"fooba", "padding is optional");
+    }
+
+    #[test]
+    fn hostile_input_is_rejected() {
+        for bad in ["Z", "Zm9=v", "Zm9v!", "====", "Zg=", "é", "Zg===", "Z==="] {
+            assert!(decode(bad).is_none(), "{bad}");
+        }
+    }
+
+    #[test]
+    fn size_cap_counts_the_partial_quartet() {
+        fn encoded_zero_bytes(len: usize) -> String {
+            let groups = len / 3;
+            let mut encoded = "A".repeat(groups * 4);
+            match len % 3 {
+                1 => encoded.push_str("AA=="),
+                2 => encoded.push_str("AAA="),
+                _ => {}
+            }
+            encoded
+        }
+
+        // Build valid base64 directly instead of encoding a 64 MiB allocation on every case.
+        // This keeps the same decoded-size boundary checks while making the workspace gate much
+        // faster and using less temporary memory.
+        let exact = encoded_zero_bytes(MAX_DECODED_BYTES);
+        assert_eq!(decode(&exact).map(|bytes| bytes.len()), Some(MAX_DECODED_BYTES), "padded boundary");
+        assert_eq!(decode(exact.trim_end_matches('=')).map(|bytes| bytes.len()), Some(MAX_DECODED_BYTES), "unpadded boundary");
+
+        let too_large = encoded_zero_bytes(MAX_DECODED_BYTES + 1);
+        assert!(decode(&too_large).is_none(), "padded over boundary");
+        let spaced = format!("{}\n {}", &too_large[..8], &too_large[8..]);
+        assert!(decode(&spaced).is_none(), "whitespace over boundary");
+    }
+}
diff --git a/crates/scraft-format/src/bundle.rs b/crates/scraft-format/src/bundle.rs
new file mode 100644
index 000000000..6b4885003
--- /dev/null
+++ b/crates/scraft-format/src/bundle.rs
@@ -0,0 +1,248 @@
+//! The optional `.scraftz` ZIP container for a `.scraft` session and its embedded audio files.
+
+use crate::{FileFormat, MAX_SESSION_BYTES, SESSION_EXTENSION, Session};
+use craft_audio::{BitDepth, EncodeFormat, EncodeOptions, encode};
+use craft_zip::{Archive, Compression, Limits, Writer};
+use std::collections::{HashMap, HashSet};
+use std::ffi::OsStr;
+use std::path::Path;
+
+/// Extension of a ZIP bundle containing a `.scraft` session and its audio files.
+pub const BUNDLE_EXTENSION: &str = "scraftz";
+
+/// The limits applied to a bundle in both directions.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct BundleLimits {
+    /// Maximum ZIP entries, including directory entries.
+    pub entries: usize,
+    /// Maximum combined uncompressed size of entries.
+    pub bytes: u64,
+    /// Maximum size of the contained session JSON.
+    pub session_bytes: u64,
+}
+
+/// SoundCraft's current bundle defaults: 10,000 entries, 1 GiB expanded and 256 MiB per session.
+pub const DEFAULT_BUNDLE_LIMITS: BundleLimits = BundleLimits { entries: 10_000, bytes: 1 << 30, session_bytes: MAX_SESSION_BYTES };
+
+/// Errors while reading or writing a session bundle.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum BundleError {
+    /// The archive is malformed, exceeds a configured limit, or does not contain a session.
+    #[error("bundle: {0}")]
+    Invalid(String),
+    /// The session JSON cannot be serialized.
+    #[error("{0}")]
+    Session(String),
+    /// The embedded audio cannot be encoded as WAV.
+    #[error("{0}")]
+    Audio(String),
+}
+
+/// Write a session and its decoded audio as a deterministic `.scraftz` ZIP bundle.
+///
+/// Audio entries use the same float WAV representation as SoundCraft's desktop bundle writer.
+/// The returned session has each included source's path rewritten to `Audio Files/<name>.wav`,
+/// its format set to `Wav`, and `unsaved` cleared.
+pub fn write_bundle(session: &Session, limits: BundleLimits) -> Result<(Vec<u8>, Session), BundleError> {
+    let mut fresh = session.clone();
+    let mut zip = Writer::new();
+    let mut names = HashSet::new();
+    let mut count = 0usize;
+    let mut total = 0u64;
+
+    for source in &mut fresh.sources {
+        let Some(audio) = fresh.pool.get(source.id) else { continue };
+        let bytes = encode(&audio.buffer, &EncodeOptions::new(EncodeFormat::Wav).with_bit_depth(BitDepth::Float32))
+            .map_err(|e| BundleError::Audio(e.to_string()))?;
+        let base = sanitize_name(&source.name);
+        let mut target = format!("Audio Files/{base}.wav");
+        let mut suffix = 1usize;
+        while names.contains(&target) && suffix <= 9_999 {
+            target = format!("Audio Files/{base}_{suffix:02}.wav");
+            suffix += 1;
+        }
+        account(&mut count, &mut total, bytes.len(), limits)?;
+        zip.add(&target, &bytes, Compression::Stored).map_err(|e| BundleError::Invalid(e.to_string()))?;
+        names.insert(target.clone());
+        source.path = target;
+        source.unsaved = false;
+        source.format = FileFormat::Wav;
+    }
+
+    let text = crate::write_session(&fresh, limits.session_bytes)?;
+    account(&mut count, &mut total, text.len(), limits)?;
+    let session_name = format!("{}.{}", sanitize_name(&fresh.name), SESSION_EXTENSION);
+    zip.add(&session_name, text.as_bytes(), Compression::Stored).map_err(|e| BundleError::Invalid(e.to_string()))?;
+    let bytes = zip.finish().map_err(|e| BundleError::Invalid(e.to_string()))?;
+    Ok((bytes, fresh))
+}
+
+/// Read the first root-level `.scraft` and retain other files by their archive path.
+///
+/// Duplicate entry names, non-text names and entries whose file data overlaps another entry are
+/// refused before payloads are copied. The session byte cap is checked against the ZIP's declared
+/// size before decompressing its JSON.
+pub fn read_bundle(bytes: &[u8], limits: BundleLimits) -> Result<(String, HashMap<String, Vec<u8>>), BundleError> {
+    let max_entries = u64::try_from(limits.entries).unwrap_or(u64::MAX);
+    let mut archive = Archive::open(bytes, Limits { max_entries, max_total_bytes: limits.bytes }).map_err(zip_error)?;
+    if archive.has_duplicate_names() {
+        return Err(BundleError::Invalid("files share a name".into()));
+    }
+    if archive.has_overlapping_files().map_err(zip_error)? {
+        return Err(BundleError::Invalid("files share data".into()));
+    }
+    let len = archive.len();
+    let mut session = None;
+    let mut files = HashMap::new();
+    for index in 0..len {
+        let is_dir = archive.entry_is_dir(index).map_err(zip_error)?.ok_or_else(|| BundleError::Invalid("missing entry".into()))?;
+        if is_dir {
+            continue;
+        }
+        let name = archive.entry_name(index).map_err(zip_error)?.ok_or_else(|| BundleError::Invalid("missing entry".into()))?;
+        let is_session = !name.contains('/') && Path::new(&name).extension().and_then(OsStr::to_str) == Some(SESSION_EXTENSION);
+        let size = archive.declared_size(&name).ok_or_else(|| BundleError::Invalid(format!("{name}: missing entry")))?;
+        if is_session && session.is_none() {
+            check_session_size(&name, size, limits.session_bytes, false).map_err(bundle_context)?;
+        }
+        let data = archive.read(&name, limits.bytes).map_err(zip_error)?.ok_or_else(|| BundleError::Invalid(format!("{name}: missing entry")))?;
+        if is_session && session.is_none() {
+            session = Some(String::from_utf8(data).map_err(|_| BundleError::Invalid(format!("{name} is not text")))?);
+        } else {
+            files.insert(name, data);
+        }
+    }
+    let session = session.ok_or_else(|| BundleError::Invalid("no .scraft session inside".into()))?;
+    Ok((session, files))
+}
+
+/// Refuse a session that cannot be opened again under the same byte cap.
+pub fn check_session_size(name: &str, len: u64, limit: u64, saving: bool) -> Result<(), BundleError> {
+    if len <= limit {
+        return Ok(());
+    }
+    let most = if limit >= 1 << 20 { format!("{} MiB", limit >> 20) } else { format!("{limit} bytes") };
+    let message = if saving {
+        format!("{name} is too large to save: over {most}, more than SoundCraft opens")
+    } else {
+        format!("{name} is too large to open (over {most})")
+    };
+    Err(BundleError::Session(message))
+}
+
+fn bundle_context(error: BundleError) -> BundleError {
+    match error {
+        BundleError::Session(message) => BundleError::Invalid(message),
+        other => other,
+    }
+}
+
+fn account(count: &mut usize, total: &mut u64, len: usize, limits: BundleLimits) -> Result<(), BundleError> {
+    *count = count.saturating_add(1);
+    *total = total.saturating_add(u64::try_from(len).unwrap_or(u64::MAX));
+    if *count > limits.entries || *total > limits.bytes {
+        return Err(BundleError::Invalid(format!(
+            "too large to save (a bundle holds at most {} files and {} MiB, or it can't be opened again)",
+            limits.entries,
+            limits.bytes >> 20
+        )));
+    }
+    Ok(())
+}
+
+fn zip_error(error: craft_zip::Error) -> BundleError {
+    match error {
+        craft_zip::Error::NotZip(message) => BundleError::Invalid(message),
+        craft_zip::Error::TooManyEntries { .. } => BundleError::Invalid("too many files".into()),
+        craft_zip::Error::EntryTooLarge { .. } | craft_zip::Error::BudgetSpent { .. } => BundleError::Invalid("too large".into()),
+        craft_zip::Error::Entry { name, msg } => BundleError::Invalid(format!("{name}: {msg}")),
+        other => BundleError::Invalid(other.to_string()),
+    }
+}
+
+fn sanitize_name(name: &str) -> String {
+    let text: String = name.chars().map(|c| if c.is_alphanumeric() || matches!(c, '-' | '_' | ' ' | '.') { c } else { '_' }).collect();
+    let text = text.trim().trim_start_matches('.').to_string();
+    if text.is_empty() { "untitled".into() } else { text.chars().take(100).collect() }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Session;
+
+    #[test]
+    fn bare_session_round_trips_in_a_bundle() {
+        let session = Session::default();
+        let (bytes, fresh) = write_bundle(&session, DEFAULT_BUNDLE_LIMITS).unwrap();
+        assert!(bytes.starts_with(b"PK\x03\x04"));
+        assert_eq!(fresh, session);
+        assert_eq!(write_bundle(&session, DEFAULT_BUNDLE_LIMITS).unwrap().0, bytes, "same input writes the same ZIP bytes");
+        let (text, files) = read_bundle(&bytes, DEFAULT_BUNDLE_LIMITS).unwrap();
+        assert!(files.is_empty());
+        assert_eq!(Session::from_json(&text).unwrap(), session);
+    }
+
+    #[test]
+    fn audio_is_stored_as_float_wav_and_the_session_path_is_rewritten() {
+        use crate::{FileFormat, Source, SourceAudio, SourceId};
+        use craft_audio::AudioBuffer;
+        use std::sync::Arc;
+
+        let id = SourceId(1);
+        let samples = [-2.0, -0.25, 0.5, 1.5];
+        let mut audio = AudioBuffer::new(48_000, 1, samples.len());
+        audio.channels[0].copy_from_slice(&samples);
+        let mut session = Session::default();
+        session.sources.push(Source {
+            id,
+            name: "Lead / take?".into(),
+            path: "elsewhere.wav".into(),
+            channels: 1,
+            frames: samples.len() as u64,
+            sample_rate: 48_000,
+            format: FileFormat::Other,
+            time_reference: 0,
+            unsaved: true,
+        });
+        session.pool.insert(id, Arc::new(SourceAudio::new(audio)));
+
+        let (bytes, fresh) = write_bundle(&session, DEFAULT_BUNDLE_LIMITS).unwrap();
+        let source = fresh.sources.first().unwrap();
+        assert_eq!(source.path, "Audio Files/Lead _ take_.wav");
+        assert_eq!(source.format, FileFormat::Wav);
+        assert!(!source.unsaved);
+
+        let (text, files) = read_bundle(&bytes, DEFAULT_BUNDLE_LIMITS).unwrap();
+        let parsed = Session::from_json(&text).unwrap();
+        assert_eq!(parsed.sources[0].path, source.path);
+        let wav = files.get(&source.path).unwrap();
+        let (_, decoded) = craft_audio::decode(wav, Some("wav")).unwrap();
+        assert_eq!(decoded.channels[0], samples);
+    }
+
+    #[test]
+    fn session_size_is_checked_in_both_directions() {
+        let too_big = check_session_size("a session", 11, 10, true).unwrap_err();
+        assert_eq!(too_big.to_string(), "a session is too large to save: over 10 bytes, more than SoundCraft opens");
+        let too_big = check_session_size("a session", 11, 10, false).unwrap_err();
+        assert_eq!(too_big.to_string(), "a session is too large to open (over 10 bytes)");
+    }
+
+    #[test]
+    fn a_bundle_without_a_session_is_refused() {
+        let mut zip = Writer::new();
+        zip.add("Audio Files/a.wav", b"audio", Compression::Stored).unwrap();
+        let bytes = zip.finish().unwrap();
+        assert_eq!(read_bundle(&bytes, DEFAULT_BUNDLE_LIMITS).unwrap_err().to_string(), "bundle: no .scraft session inside");
+    }
+
+    #[test]
+    fn every_truncation_of_a_bundle_is_an_error_not_a_panic() {
+        let (bytes, _) = write_bundle(&Session::default(), DEFAULT_BUNDLE_LIMITS).unwrap();
+        for cut in 0..bytes.len() {
+            assert!(read_bundle(&bytes[..cut], DEFAULT_BUNDLE_LIMITS).is_err(), "accepted truncation at {cut}");
+        }
+        assert!(read_bundle(&bytes, DEFAULT_BUNDLE_LIMITS).is_ok());
+    }
+}
diff --git a/crates/scraft-format/src/clip.rs b/crates/scraft-format/src/clip.rs
new file mode 100644
index 000000000..28e60b6d9
--- /dev/null
+++ b/crates/scraft-format/src/clip.rs
@@ -0,0 +1,544 @@
+//! Clips: windows onto audio sources or MIDI sequences, placed on a playlist.
+
+use crate::soundcraft_midi::Sequence;
+use crate::soundcraft_time::{MAX_POSITION, Range, Samples};
+use crate::{ClipId, MAX_NAME_CHARS, SourceId, truncate_chars};
+
+/// Fade curve shapes (Pro Tools offers standard, equal-power, S-curve and custom presets).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum FadeShape {
+    Linear,
+    #[default]
+    EqualPower,
+    SCurve,
+    Exponential,
+    Logarithmic,
+}
+
+impl FadeShape {
+    pub const ALL: [FadeShape; 5] = [FadeShape::Linear, FadeShape::EqualPower, FadeShape::SCurve, FadeShape::Exponential, FadeShape::Logarithmic];
+
+    /// Fade-in gain at `t` ∈ [0,1] (fade-outs use `gain(1 - t)`).
+    pub fn gain(self, t: f32) -> f32 {
+        let t = if t.is_nan() { 0.0 } else { t.clamp(0.0, 1.0) };
+        match self {
+            FadeShape::Linear => t,
+            FadeShape::EqualPower => (t * std::f32::consts::FRAC_PI_2).sin(),
+            FadeShape::SCurve => 0.5 - 0.5 * (t * std::f32::consts::PI).cos(),
+            FadeShape::Exponential => t * t * t,
+            FadeShape::Logarithmic => 1.0 - (1.0 - t) * (1.0 - t) * (1.0 - t),
+        }
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            FadeShape::Linear => "Linear",
+            FadeShape::EqualPower => "Equal Power",
+            FadeShape::SCurve => "S-Curve",
+            FadeShape::Exponential => "Exponential",
+            FadeShape::Logarithmic => "Logarithmic",
+        }
+    }
+
+    pub fn from_id(s: &str) -> Option<FadeShape> {
+        let s = s.to_ascii_lowercase().replace(['-', '_', ' '], "");
+        FadeShape::ALL.into_iter().find(|f| f.label().to_ascii_lowercase().replace(['-', ' '], "") == s)
+    }
+}
+
+/// A fade at a clip boundary, `len` samples long.
+#[derive(Debug, Clone, Copy, PartialEq, Default, serde::Serialize, serde::Deserialize)]
+pub struct Fade {
+    pub len: Samples,
+    pub shape: FadeShape,
+    /// Continuous bend (-1..1); zero preserves the original shape exactly.
+    #[serde(default)]
+    pub curvature: f32,
+}
+
+impl Fade {
+    /// The envelope used by both rendering and audio, with fixed zero/unity endpoints.
+    pub fn gain(self, t: f32) -> f32 {
+        let base = self.shape.gain(t);
+        let curvature = if self.curvature.is_finite() { self.curvature.clamp(-1.0, 1.0) } else { 0.0 };
+        if curvature == 0.0 || base <= 0.0 || base >= 1.0 {
+            return base;
+        }
+        let weighted = base * (curvature * 4.0).exp2();
+        weighted / (weighted + 1.0 - base)
+    }
+
+    /// Invert the bend at the midpoint so a vertical drag follows the pointer.
+    pub fn curvature_for_midpoint_gain(self, gain: f32) -> f32 {
+        let gain = if gain.is_finite() { gain.clamp(0.001, 0.999) } else { self.gain(0.5) };
+        let base = self.shape.gain(0.5);
+        (((gain / (1.0 - gain)).log2() - (base / (1.0 - base)).log2()) / 4.0).clamp(-1.0, 1.0)
+    }
+
+    pub fn sanitize(&mut self) {
+        self.curvature = if self.curvature.is_finite() { self.curvature.clamp(-1.0, 1.0) } else { 0.0 };
+    }
+}
+
+/// What a clip plays.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub enum ClipContent {
+    /// Audio from `source`, starting `offset` samples into the file.
+    Audio { source: SourceId, offset: Samples },
+    /// MIDI notes, with ticks relative to the clip start.
+    Midi { sequence: Sequence },
+    /// Picture from the movie `source` ([`crate::VideoSource`], `Session::videos`), starting
+    /// `offset` samples into the movie. Video clips carry no audio.
+    Video { source: SourceId, offset: Samples },
+}
+
+/// A clip on a playlist.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct Clip {
+    pub id: ClipId,
+    pub name: String,
+    /// Timeline start (samples).
+    pub start: Samples,
+    /// Length (samples, > 0).
+    pub length: Samples,
+    pub content: ClipContent,
+    /// Static clip gain in dB.
+    #[serde(default)]
+    pub gain_db: f32,
+    /// Clip gain envelope breakpoints: (offset from clip start, dB). Empty = flat `gain_db`.
+    #[serde(default)]
+    pub gain_env: Vec<(Samples, f32)>,
+    #[serde(default)]
+    pub fade_in: Fade,
+    #[serde(default)]
+    pub fade_out: Fade,
+    #[serde(default)]
+    pub muted: bool,
+    #[serde(default)]
+    pub edit_locked: bool,
+    #[serde(default)]
+    pub time_locked: bool,
+    #[serde(default)]
+    pub rating: u8,
+    /// Sync point offset from clip start.
+    #[serde(default)]
+    pub sync_point: Samples,
+    /// Optional colour override (RGB).
+    #[serde(default)]
+    pub color: Option<[u8; 3]>,
+    /// The key in [`crate::Session::auto_names`] of the names that editing gives the clips it
+    /// separates from this one (Clip List › Auto Rename). `None` keeps the clip's name.
+    #[serde(default)]
+    pub auto_name: Option<u64>,
+    /// Elastic / Vari-speed ratio (1.0 = none) — applied by rendered processing.
+    #[serde(default = "one")]
+    pub stretch: f64,
+    /// Reversed playback (AudioSuite Reverse renders into a new source; this is for previews).
+    #[serde(default)]
+    pub group: Option<u64>,
+    /// Marks the clips made by `clip.loop` (the origin and its copies share one id), so
+    /// `clip.unloop` still recognises the loop after the source's content is edited.
+    #[serde(default)]
+    pub loop_id: Option<u64>,
+}
+
+fn one() -> f64 {
+    1.0
+}
+
+impl Clip {
+    pub fn audio(id: ClipId, name: impl Into<String>, source: SourceId, offset: Samples, start: Samples, length: Samples) -> Clip {
+        Clip {
+            id,
+            name: name.into(),
+            start,
+            length: length.max(1),
+            content: ClipContent::Audio { source, offset },
+            gain_db: 0.0,
+            gain_env: Vec::new(),
+            fade_in: Fade::default(),
+            fade_out: Fade::default(),
+            muted: false,
+            edit_locked: false,
+            time_locked: false,
+            rating: 0,
+            sync_point: 0,
+            color: None,
+            auto_name: None,
+            stretch: 1.0,
+            group: None,
+            loop_id: None,
+        }
+    }
+
+    pub fn midi(id: ClipId, name: impl Into<String>, start: Samples, length: Samples, sequence: Sequence) -> Clip {
+        let mut c = Clip::audio(id, name, SourceId(0), 0, start, length);
+        c.content = ClipContent::Midi { sequence };
+        c
+    }
+
+    /// A clip showing the movie `source` from `offset` samples into it.
+    pub fn video(id: ClipId, name: impl Into<String>, source: SourceId, offset: Samples, start: Samples, length: Samples) -> Clip {
+        let mut c = Clip::audio(id, name, SourceId(0), 0, start, length);
+        c.content = ClipContent::Video { source, offset };
+        c
+    }
+
+    pub fn end(&self) -> Samples {
+        self.start.saturating_add(self.length)
+    }
+
+    pub fn range(&self) -> Range {
+        Range { start: self.start, end: self.end() }
+    }
+
+    pub fn is_audio(&self) -> bool {
+        matches!(self.content, ClipContent::Audio { .. })
+    }
+
+    pub fn is_video(&self) -> bool {
+        matches!(self.content, ClipContent::Video { .. })
+    }
+
+    /// The audio source this clip plays (None for MIDI and video clips).
+    pub fn source(&self) -> Option<SourceId> {
+        match self.content {
+            ClipContent::Audio { source, .. } => Some(source),
+            ClipContent::Midi { .. } | ClipContent::Video { .. } => None,
+        }
+    }
+
+    /// The movie this clip shows (video clips only).
+    pub fn video_source(&self) -> Option<SourceId> {
+        match self.content {
+            ClipContent::Video { source, .. } => Some(source),
+            ClipContent::Audio { .. } | ClipContent::Midi { .. } => None,
+        }
+    }
+
+    /// Offset into the audio file or movie (0 for MIDI).
+    pub fn source_offset(&self) -> Samples {
+        match self.content {
+            ClipContent::Audio { offset, .. } | ClipContent::Video { offset, .. } => offset,
+            ClipContent::Midi { .. } => 0,
+        }
+    }
+
+    /// Gain (linear) at `rel` samples from the clip start: clip gain × envelope × fades.
+    pub fn gain_at(&self, rel: Samples) -> f32 {
+        self.gain_at_with_fades(rel, self.fade_in, self.fade_out)
+    }
+
+    /// Evaluate temporary fades while retaining clip gain and its envelope.
+    /// UI previews can use this without modifying the clip or rebuilding media.
+    pub fn gain_at_with_fades(&self, rel: Samples, fade_in: Fade, fade_out: Fade) -> f32 {
+        let mut db = self.gain_db;
+        if !self.gain_env.is_empty() {
+            db += env_value(&self.gain_env, rel);
+        }
+        let mut g = db_to_gain(db);
+        if fade_in.len > 0 && rel < fade_in.len {
+            g *= fade_in.gain(rel as f32 / fade_in.len as f32);
+        }
+        let from_end = self.length.saturating_sub(rel);
+        if fade_out.len > 0 && from_end <= fade_out.len {
+            g *= fade_out.gain(from_end as f32 / fade_out.len as f32);
+        }
+        g
+    }
+
+    /// Gain envelope value in dB at `rel` samples from the clip start (0 without an envelope).
+    pub fn env_db_at(&self, rel: Samples) -> f32 {
+        env_value(&self.gain_env, rel)
+    }
+
+    /// Move the start edge to `new_start` keeping material anchored (trim start).
+    pub fn trim_start_to(&mut self, new_start: Samples) {
+        // #907: these are public APIs, so they have to survive arguments a command would never
+        // pass (commands clamp to `MAX_POSITION` first). `Samples` is `i64`, so an extreme
+        // `new_start` against an extreme `start` wrapped in release and panicked in debug.
+        // Never so far back that the length would pass `MAX_POSITION`: trimming the start keeps the end.
+        let end = self.end();
+        let new_start = new_start.max(end.saturating_sub(MAX_POSITION)).clamp(-MAX_POSITION, MAX_POSITION).min(end.saturating_sub(1));
+        let delta = new_start.saturating_sub(self.start);
+        // The mixer plays a stretched audio clip from `offset + rel / stretch`.
+        let stretch = if self.stretch.is_finite() && self.stretch > 0.0 { self.stretch } else { 1.0 };
+        match &mut self.content {
+            ClipContent::Audio { offset, .. } if (stretch - 1.0).abs() >= 1e-9 => {
+                *offset = offset.saturating_add((delta as f64 / stretch).round() as Samples);
+            }
+            ClipContent::Audio { offset, .. } | ClipContent::Video { offset, .. } => {
+                *offset = offset.saturating_add(delta);
+            }
+            ClipContent::Midi { .. } => {}
+        }
+        // MIDI note ticks are re-anchored by the engine, which knows the tempo map.
+        self.length = self.length.saturating_sub(delta).clamp(1, MAX_POSITION);
+        self.start = new_start;
+        if self.sync_point != 0 {
+            self.sync_point = self.sync_point.saturating_sub(delta);
+        }
+        self.drop_stray_sync();
+        self.clamp_fades();
+        // Keep the gain at the cut when earlier breakpoints are dropped.
+        if self.gain_env.iter().any(|&(t, _)| t < delta) && self.gain_env.iter().all(|&(t, _)| t != delta) {
+            self.gain_env.insert(0, (delta, env_value(&self.gain_env, delta)));
+        }
+        self.gain_env.retain(|&(t, _)| t >= delta);
+        self.gain_env.iter_mut().for_each(|(t, _)| *t = t.saturating_sub(delta));
+    }
+
+    /// Move the end edge to `new_end`.
+    pub fn trim_end_to(&mut self, new_end: Samples) {
+        // #907: saturating, like `trim_start_to`.
+        let new_end = new_end.clamp(-MAX_POSITION, MAX_POSITION).max(self.start.saturating_add(1));
+        self.length = new_end.saturating_sub(self.start).clamp(1, MAX_POSITION);
+        self.drop_stray_sync();
+        self.clamp_fades();
+    }
+
+    /// Keep both fades within the clip.
+    pub fn clamp_fades(&mut self) {
+        self.fade_in.len = self.fade_in.len.clamp(0, self.length);
+        self.fade_out.len = self.fade_out.len.clamp(0, self.length);
+    }
+
+    /// A sync point (0 means none) that a trim left outside the clip no longer marks anything.
+    fn drop_stray_sync(&mut self) {
+        if !(0..self.length).contains(&self.sync_point) {
+            self.sync_point = 0;
+        }
+    }
+
+    /// Repair a clip read from a file: positions and lengths within ±[`MAX_POSITION`], as commands
+    /// keep theirs, fades within the clip, a name that can be drawn, and a usable gain and stretch.
+    pub fn sanitize(&mut self) {
+        bound(&mut self.start);
+        self.length = self.length.clamp(1, MAX_POSITION);
+        bound(&mut self.sync_point);
+        self.gain_env.iter_mut().for_each(|(at, _)| bound(at));
+        match &mut self.content {
+            ClipContent::Audio { offset, .. } | ClipContent::Video { offset, .. } => bound(offset),
+            ClipContent::Midi { sequence } => bound_sequence(sequence),
+        }
+        self.clamp_fades();
+        self.fade_in.sanitize();
+        self.fade_out.sanitize();
+        truncate_chars(&mut self.name, MAX_NAME_CHARS);
+        if !self.gain_db.is_finite() {
+            self.gain_db = 0.0;
+        }
+        if !self.stretch.is_finite() || self.stretch <= 0.0 {
+            self.stretch = 1.0;
+        }
+    }
+}
+
+pub(crate) fn bound(at: &mut Samples) {
+    *at = (*at).clamp(-MAX_POSITION, MAX_POSITION);
+}
+
+pub(crate) fn bound_sequence(s: &mut Sequence) {
+    for n in &mut s.notes {
+        bound(&mut n.start);
+        n.length = n.length.clamp(1, MAX_POSITION);
+    }
+    s.ctrls.iter_mut().for_each(|c| bound(&mut c.tick));
+}
+
+fn env_value(env: &[(Samples, f32)], at: Samples) -> f32 {
+    let mut prev: Option<(Samples, f32)> = None;
+    for &(t, v) in env {
+        if t >= at {
+            return match prev {
+                Some((pt, pv)) if t > pt => {
+                    let elapsed = i128::from(at).saturating_sub(i128::from(pt));
+                    let span = i128::from(t).saturating_sub(i128::from(pt));
+                    pv + (v - pv) * (elapsed as f32 / span as f32)
+                }
+                _ => v,
+            };
+        }
+        prev = Some((t, v));
+    }
+    prev.map_or(0.0, |(_, v)| v)
+}
+
+pub(crate) fn db_to_gain(db: f32) -> f32 {
+    if db.is_nan() || db <= -144.0 { 0.0 } else { 10f32.powf(db.min(48.0) / 20.0) }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fade_shapes_hit_endpoints() {
+        for s in FadeShape::ALL {
+            assert!(s.gain(0.0).abs() < 1e-6, "{s:?}");
+            assert!((s.gain(1.0) - 1.0).abs() < 1e-6, "{s:?}");
+            assert_eq!(s.gain(f32::NAN), 0.0);
+            assert_eq!(FadeShape::from_id(s.label()), Some(s));
+        }
+    }
+
+    #[test]
+    fn fade_curvature_is_bounded_monotonic_and_inverts_at_the_midpoint() {
+        for shape in FadeShape::ALL {
+            let original = Fade { len: 1000, shape, curvature: 0.0 };
+            for i in 0..=128 {
+                let t = i as f32 / 128.0;
+                assert_eq!(original.gain(t), shape.gain(t), "legacy curves must be unchanged");
+            }
+            for curvature in [-1.0, -0.5, 0.0, 0.5, 1.0] {
+                let fade = Fade { curvature, ..original };
+                assert_eq!(fade.gain(0.0), 0.0);
+                assert_eq!(fade.gain(1.0), 1.0);
+                let mut previous = 0.0;
+                for i in 0..=128 {
+                    let gain = fade.gain(i as f32 / 128.0);
+                    assert!(gain.is_finite() && (0.0..=1.0).contains(&gain));
+                    assert!(gain >= previous, "{shape:?}, {curvature}");
+                    previous = gain;
+                }
+                assert!((fade.curvature_for_midpoint_gain(fade.gain(0.5)) - curvature).abs() < 1e-5);
+            }
+            assert!((Fade { curvature: 0.5, ..original }).gain(0.5) > original.gain(0.5));
+            assert!((Fade { curvature: -0.5, ..original }).gain(0.5) < original.gain(0.5));
+        }
+    }
+
+    #[test]
+    fn fade_curvature_loads_legacy_data_and_sanitizes_hostile_values() {
+        let fade: Fade = serde_json::from_str(r#"{"len":100,"shape":"SCurve"}"#).unwrap();
+        assert_eq!(fade.curvature, 0.0);
+        for curvature in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY, -10.0, 10.0] {
+            let mut fade = Fade { curvature, ..fade };
+            assert!(fade.gain(0.5).is_finite());
+            fade.sanitize();
+            assert!(fade.curvature.is_finite() && (-1.0..=1.0).contains(&fade.curvature));
+            let roundtrip: Fade = serde_json::from_str(&serde_json::to_string(&fade).unwrap()).unwrap();
+            assert_eq!(roundtrip, fade);
+        }
+    }
+
+    #[test]
+    fn temporary_fades_keep_clip_gain_and_envelope_without_mutating_the_clip() {
+        let mut clip = Clip::audio(ClipId(1), "preview", SourceId(1), 0, 0, 1000);
+        clip.gain_db = -6.0;
+        clip.gain_env = vec![(0, 0.0), (1000, 6.0)];
+        clip.fade_in = Fade { len: 100, shape: FadeShape::SCurve, curvature: 0.25 };
+        clip.fade_out = Fade { len: 100, shape: FadeShape::Logarithmic, curvature: -0.1 };
+        let before = clip.clone();
+        let fade_in = Fade { len: 1000, shape: FadeShape::Linear, curvature: 0.5 };
+        let fade_out = Fade { len: 1000, shape: FadeShape::Linear, curvature: -0.5 };
+        assert!((clip.gain_at_with_fades(500, fade_in, fade_out) - db_to_gain(-3.0) * 0.16).abs() < 1e-6);
+        let mut committed = clip.clone();
+        committed.fade_in = fade_in;
+        committed.fade_out = fade_out;
+        for rel in [0, 50, 500, 999, 1000] {
+            assert_eq!(clip.gain_at_with_fades(rel, fade_in, fade_out), committed.gain_at(rel));
+        }
+        for rel in [i64::MIN, i64::MAX] {
+            assert!(clip.gain_at(rel).is_finite());
+            assert!(clip.gain_at_with_fades(rel, fade_in, fade_out).is_finite());
+        }
+        assert_eq!(clip, before);
+        clip.gain_env = vec![(i64::MIN, 0.0), (i64::MAX, 6.0)];
+        assert!((clip.gain_at(500) - db_to_gain(-3.0)).abs() < 1e-6);
+        assert!((clip.gain_at_with_fades(500, fade_in, fade_out) - db_to_gain(-3.0) * 0.16).abs() < 1e-6);
+    }
+
+    #[test]
+    fn gain_with_fades() {
+        let mut c = Clip::audio(ClipId(1), "a", SourceId(1), 0, 100, 1000);
+        c.fade_in = Fade { len: 100, shape: FadeShape::Linear, curvature: 0.0 };
+        c.fade_out = Fade { len: 100, shape: FadeShape::Linear, curvature: 0.0 };
+        assert!(c.gain_at(0).abs() < 1e-6);
+        assert!((c.gain_at(50) - 0.5).abs() < 1e-6);
+        assert!((c.gain_at(500) - 1.0).abs() < 1e-6);
+        assert!((c.gain_at(950) - 0.5).abs() < 1e-6);
+    }
+
+    #[test]
+    fn gain_envelope_interpolates() {
+        let mut c = Clip::audio(ClipId(1), "a", SourceId(1), 0, 0, 1000);
+        c.gain_env = vec![(0, 0.0), (1000, -20.0)];
+        assert!((c.gain_at(500) - db_to_gain(-10.0)).abs() < 1e-4);
+    }
+
+    #[test]
+    fn trim_start_keeps_gain_envelope_at_cut() {
+        for (env, cut, expected) in [
+            (vec![(0, 0.0), (1000, -20.0)], 500, vec![(0, -10.0), (500, -20.0)]),
+            (vec![(0, 0.0), (100, -20.0)], 500, vec![(0, -20.0)]),
+            (vec![(0, 0.0), (500, -10.0), (1000, -20.0)], 500, vec![(0, -10.0), (500, -20.0)]),
+            (vec![], 500, vec![]),
+            (vec![(100, -3.0)], 0, vec![(100, -3.0)]),
+            (vec![(100, -3.0)], -100, vec![(200, -3.0)]),
+        ] {
+            let mut clip = Clip::audio(ClipId(1), "a", SourceId(1), 100, 0, 1000);
+            clip.gain_env = env;
+            let gain_at_cut = clip.gain_at(cut);
+            clip.trim_start_to(cut);
+            assert_eq!(clip.gain_env, expected);
+            if cut > 0 {
+                assert!((clip.gain_at(0) - gain_at_cut).abs() < 1e-6);
+            }
+        }
+    }
+
+    #[test]
+    fn trims_keep_material_anchored() {
+        let mut c = Clip::audio(ClipId(1), "a", SourceId(1), 1000, 100, 1000);
+        c.trim_start_to(300);
+        assert_eq!((c.start, c.length, c.source_offset()), (300, 800, 1200));
+        c.trim_end_to(500);
+        assert_eq!(c.length, 200);
+        c.trim_end_to(-50);
+        assert_eq!(c.length, 1);
+        // Regression: trimming the start must not leave a fade-out longer than the clip.
+        let mut c = Clip::audio(ClipId(2), "b", SourceId(1), 0, 0, 1000);
+        c.fade_out = Fade { len: 800, shape: FadeShape::Linear, curvature: 0.0 };
+        c.trim_start_to(900);
+        assert!(c.fade_out.len <= c.length);
+    }
+
+    /// #907: `trim_start_to` / `trim_end_to` are public APIs, so they have to survive arguments a
+    /// command would never pass. `Samples` is `i64`, so an extreme `new_start` against an extreme
+    /// `start` wrapped in release and panicked in debug. Every position stays within
+    /// `±MAX_POSITION` and every length within `1..=MAX_POSITION`.
+    #[test]
+    fn trims_saturate_on_extreme_arguments() {
+        for &new_start in &[Samples::MIN, -(MAX_POSITION * 2), -1, 0, MAX_POSITION, MAX_POSITION * 2, Samples::MAX] {
+            let mut c = Clip::audio(ClipId(1), "a", SourceId(1), 1000, MAX_POSITION / 2, 1000);
+            c.trim_start_to(new_start);
+            assert!((-(MAX_POSITION as i128)..=(MAX_POSITION as i128)).contains(&(c.start as i128)), "start {new_start}: {}", c.start);
+            assert!((1..=MAX_POSITION).contains(&c.length), "start {new_start}: length {}", c.length);
+            assert_eq!(c.end(), MAX_POSITION / 2 + 1000, "start {new_start} moved the end");
+        }
+        for &new_end in &[Samples::MIN, -(MAX_POSITION * 2), -1, 0, MAX_POSITION, MAX_POSITION * 2, Samples::MAX] {
+            let mut c = Clip::audio(ClipId(2), "b", SourceId(1), 1000, -(MAX_POSITION / 2), 1000);
+            c.trim_end_to(new_end);
+            assert!((1..=MAX_POSITION).contains(&c.length), "end {new_end}: length {}", c.length);
+            assert!(c.end() - c.start == c.length, "end {new_end}: start {} end {}", c.start, c.end());
+        }
+    }
+
+    #[test]
+    fn trim_start_of_stretched_audio_advances_offset_by_source_time() {
+        // The mixer plays source `offset + rel / stretch`, so a split at timeline 1000 of a 2x clip
+        // must start the right half at source sample 500.
+        let mut c = Clip::audio(ClipId(1), "a", SourceId(1), 0, 0, 2000);
+        c.stretch = 2.0;
+        c.trim_start_to(1000);
+        assert_eq!(c.source_offset(), 500);
+        let mut c = Clip::audio(ClipId(2), "b", SourceId(1), 0, 0, 2000);
+        c.stretch = 0.5;
+        c.trim_start_to(1000);
+        assert_eq!(c.source_offset(), 2000);
+        let mut c = Clip::audio(ClipId(3), "c", SourceId(1), 0, 0, 2000);
+        c.trim_start_to(1000);
+        assert_eq!(c.source_offset(), 1000);
+    }
+}
diff --git a/crates/scraft-format/src/ids.rs b/crates/scraft-format/src/ids.rs
new file mode 100644
index 000000000..441ced1ae
--- /dev/null
+++ b/crates/scraft-format/src/ids.rs
@@ -0,0 +1,21 @@
+//! Typed ids. All ids come from one session-wide counter so they never collide across kinds.
+
+macro_rules! id_type {
+    ($name:ident) => {
+        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default, serde::Serialize, serde::Deserialize)]
+        #[serde(transparent)]
+        pub struct $name(pub u64);
+        impl std::fmt::Display for $name {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                write!(f, "{}", self.0)
+            }
+        }
+    };
+}
+
+id_type!(TrackId);
+id_type!(ClipId);
+id_type!(SourceId);
+id_type!(BusId);
+id_type!(GroupId);
+id_type!(MarkerId);
diff --git a/crates/scraft-format/src/lib.rs b/crates/scraft-format/src/lib.rs
new file mode 100644
index 000000000..c54d7f934
--- /dev/null
+++ b/crates/scraft-format/src/lib.rs
@@ -0,0 +1,123 @@
+//! The SoundCraft session document.
+//!
+//! A [`Session`] is pure data: tracks with playlists of clips, the mixer (inserts, sends, routing,
+//! automation), tempo/meter, memory locations and groups. Audio sample data lives in
+//! [`SourcePool`] behind `Arc`s, so cloning a session for undo is cheap.
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+
+mod automation;
+pub mod b64;
+pub mod bundle;
+mod clip;
+mod ids;
+mod markers;
+mod mixer;
+mod session;
+mod source;
+mod track;
+
+pub use craft_midi as soundcraft_midi;
+pub use craft_time::soundcraft as soundcraft_time;
+
+pub use automation::{AutoParam, AutomationLane, AutomationMode, AutomationPoint};
+pub use bundle::{BUNDLE_EXTENSION, BundleError, BundleLimits, DEFAULT_BUNDLE_LIMITS, check_session_size, read_bundle, write_bundle};
+pub use clip::{Clip, ClipContent, Fade, FadeShape};
+pub use ids::{BusId, ClipId, GroupId, MarkerId, SourceId, TrackId};
+pub use markers::{Group, MarkerKind, MemoryLocation};
+pub use mixer::{
+    Bus, ChannelFormat, INSERT_SLOTS, Insert, Mixer, OutputPath, Route, SEND_SLOTS, SendSlot, Speaker, SurroundPan, fader_db_to_pos, fader_pos_to_db,
+};
+pub use session::{
+    AutoName, BitDepthSetting, EditMode, EditState, FEET_FRAMES_START, MAX_COMMENT_CHARS, MAX_NAME_CHARS, SESSION_EXTENSION, Session, SessionError,
+    Tool, TrackView, ZoomState, ZoomToggle, truncate_chars,
+};
+pub use source::{FileFormat, Source, SourceAudio, SourcePool, VideoSource};
+pub use track::{Playlist, TRACK_COLORS, Track, TrackHeight, TrackKind};
+
+pub use soundcraft_time as time;
+
+/// Largest `.scraft` session opened or written by SoundCraft.
+pub const MAX_SESSION_BYTES: u64 = 256 << 20;
+
+/// Read a bare `.scraft` file after enforcing the caller's byte limit.
+pub fn read_session_bytes(name: &str, bytes: &[u8], limit: u64) -> Result<String, BundleError> {
+    check_session_size(name, u64::try_from(bytes.len()).unwrap_or(u64::MAX), limit, false)?;
+    read_session_data(name, bytes.to_vec(), limit)
+}
+
+/// Turn already-read `.scraft` bytes into text without making another copy.
+pub fn read_session_data(name: &str, bytes: Vec<u8>, limit: u64) -> Result<String, BundleError> {
+    check_session_size(name, u64::try_from(bytes.len()).unwrap_or(u64::MAX), limit, false)?;
+    String::from_utf8(bytes).map_err(|_| BundleError::Session(format!("{name}: not a SoundCraft session")))
+}
+
+/// The size of pretty JSON for `session`, measured without retaining the serialized document.
+pub fn session_json_len(session: &Session) -> Result<u64, BundleError> {
+    struct Count(u64);
+    impl std::io::Write for Count {
+        fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
+            self.0 = self.0.saturating_add(u64::try_from(bytes.len()).unwrap_or(u64::MAX));
+            Ok(bytes.len())
+        }
+        fn flush(&mut self) -> std::io::Result<()> {
+            Ok(())
+        }
+    }
+    let mut count = Count(0);
+    serde_json::to_writer_pretty(&mut count, session).map_err(|error| BundleError::Session(error.to_string()))?;
+    Ok(count.0)
+}
+
+/// Serialize a `.scraft` session, refusing output larger than the caller's read limit while
+/// keeping the temporary allocation within that limit.
+pub fn write_session(session: &Session, limit: u64) -> Result<String, BundleError> {
+    write_session_named(session, "the session", limit)
+}
+
+/// [`write_session`] with the path or label used for the session-size error.
+pub fn write_session_named(session: &Session, name: &str, limit: u64) -> Result<String, BundleError> {
+    struct Bounded(Vec<u8>, u64, bool);
+    impl std::io::Write for Bounded {
+        fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
+            let remaining = self.1.saturating_sub(u64::try_from(self.0.len()).unwrap_or(u64::MAX));
+            let count = usize::try_from(remaining).unwrap_or(usize::MAX).min(bytes.len());
+            self.0.extend_from_slice(&bytes[..count]);
+            self.2 |= count < bytes.len();
+            Ok(count)
+        }
+        fn flush(&mut self) -> std::io::Result<()> {
+            Ok(())
+        }
+    }
+    let capacity = usize::try_from(limit).unwrap_or(usize::MAX);
+    let mut output = Bounded(Vec::with_capacity(capacity.min(1024 * 1024)), limit, false);
+    let serialized = serde_json::to_writer_pretty(&mut output, session);
+    if output.2 {
+        check_session_size(name, limit.saturating_add(1), limit, true)?;
+    }
+    serialized.map_err(|error| BundleError::Session(error.to_string()))?;
+    String::from_utf8(output.0).map_err(|error| BundleError::Session(error.to_string()))
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used, clippy::expect_used)]
+mod session_io_tests {
+    use super::*;
+
+    #[test]
+    fn bounded_writer_matches_canonical_session_json_and_refuses_one_byte_under() {
+        let session = Session::default();
+        let canonical = session.to_json().unwrap();
+        let len = u64::try_from(canonical.len()).unwrap();
+        assert_eq!(session_json_len(&session).unwrap(), len);
+        assert_eq!(write_session(&session, len).unwrap(), canonical);
+        assert!(write_session(&session, len - 1).is_err());
+    }
+
+    #[test]
+    fn bare_session_reader_checks_size_and_utf8() {
+        assert!(read_session_bytes("song.scraft", b"{}", 1).is_err());
+        assert!(read_session_bytes("song.scraft", &[0xff], 10).is_err());
+        assert_eq!(read_session_bytes("song.scraft", b"{}", 2).unwrap(), "{}");
+    }
+}
diff --git a/crates/scraft-format/src/markers.rs b/crates/scraft-format/src/markers.rs
new file mode 100644
index 000000000..eaa517dd2
--- /dev/null
+++ b/crates/scraft-format/src/markers.rs
@@ -0,0 +1,58 @@
+//! Memory locations (markers and stored selections) and mix/edit groups.
+
+use crate::soundcraft_time::Samples;
+use crate::{GroupId, MarkerId, TrackId};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum MarkerKind {
+    /// A point marker on a ruler.
+    #[default]
+    Marker,
+    /// A stored selection range.
+    Selection,
+    /// A location that only recalls view settings.
+    None,
+}
+
+/// A memory location (Window › Memory Locations).
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct MemoryLocation {
+    pub id: MarkerId,
+    /// User-visible number (1-based, unique).
+    pub number: u32,
+    pub name: String,
+    pub kind: MarkerKind,
+    pub start: Samples,
+    pub end: Samples,
+    #[serde(default)]
+    pub comments: String,
+    #[serde(default)]
+    pub color: Option<[u8; 3]>,
+    /// Marker ruler lane 1..5.
+    #[serde(default = "one")]
+    pub ruler: u8,
+    /// Track-lane marker on this track, if any.
+    #[serde(default)]
+    pub track: Option<TrackId>,
+}
+
+fn one() -> u8 {
+    1
+}
+
+/// A track group (Track › Group…).
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct Group {
+    pub id: GroupId,
+    pub name: String,
+    /// Group letter id shown in the Groups list ("a", "b", …).
+    pub letter: char,
+    pub members: Vec<TrackId>,
+    pub edit: bool,
+    pub mix: bool,
+    pub active: bool,
+    pub color: [u8; 3],
+    /// Shared attributes linked by the group (volume, mute, solo, rec, etc.).
+    #[serde(default)]
+    pub attributes: Vec<String>,
+}
diff --git a/crates/scraft-format/src/mixer.rs b/crates/scraft-format/src/mixer.rs
new file mode 100644
index 000000000..efdaf2d17
--- /dev/null
+++ b/crates/scraft-format/src/mixer.rs
@@ -0,0 +1,714 @@
+//! Per-track mixer state: inserts, sends, routing, fader, pan, mute/solo.
+
+use crate::{AutomationMode, BusId, SourceId};
+use std::collections::BTreeMap;
+
+pub const INSERT_SLOTS: usize = 10;
+pub const SEND_SLOTS: usize = 10;
+
+/// Channel formats (track widths).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum ChannelFormat {
+    #[default]
+    Mono,
+    Stereo,
+    Lcr,
+    Quad,
+    Lcrs,
+    Surround50,
+    Surround51,
+    Surround60,
+    Surround61,
+    Sdds70,
+    Sdds71,
+    Surround70,
+    Surround71,
+    Atmos702,
+    Atmos712,
+    Atmos502,
+    Atmos512,
+    Atmos504,
+    Atmos514,
+    Atmos704,
+    Atmos714,
+    Atmos706,
+    Atmos716,
+    Atmos904,
+    Atmos914,
+    Atmos906,
+    Atmos916,
+    /// Ambisonics of order 1..=7 ((n+1)² channels).
+    Ambisonics(u8),
+}
+
+impl ChannelFormat {
+    pub const ALL: [ChannelFormat; 34] = [
+        ChannelFormat::Mono,
+        ChannelFormat::Stereo,
+        ChannelFormat::Lcr,
+        ChannelFormat::Quad,
+        ChannelFormat::Lcrs,
+        ChannelFormat::Surround50,
+        ChannelFormat::Surround51,
+        ChannelFormat::Surround60,
+        ChannelFormat::Surround61,
+        ChannelFormat::Sdds70,
+        ChannelFormat::Sdds71,
+        ChannelFormat::Surround70,
+        ChannelFormat::Surround71,
+        ChannelFormat::Atmos702,
+        ChannelFormat::Atmos712,
+        ChannelFormat::Ambisonics(1),
+        ChannelFormat::Ambisonics(2),
+        ChannelFormat::Ambisonics(3),
+        ChannelFormat::Ambisonics(4),
+        ChannelFormat::Ambisonics(5),
+        ChannelFormat::Ambisonics(6),
+        ChannelFormat::Ambisonics(7),
+        ChannelFormat::Atmos502,
+        ChannelFormat::Atmos512,
+        ChannelFormat::Atmos504,
+        ChannelFormat::Atmos514,
+        ChannelFormat::Atmos704,
+        ChannelFormat::Atmos714,
+        ChannelFormat::Atmos706,
+        ChannelFormat::Atmos716,
+        ChannelFormat::Atmos904,
+        ChannelFormat::Atmos914,
+        ChannelFormat::Atmos906,
+        ChannelFormat::Atmos916,
+    ];
+    pub fn channels(self) -> usize {
+        match self {
+            ChannelFormat::Mono => 1,
+            ChannelFormat::Stereo => 2,
+            ChannelFormat::Lcr => 3,
+            ChannelFormat::Quad | ChannelFormat::Lcrs => 4,
+            ChannelFormat::Surround50 => 5,
+            ChannelFormat::Surround51 | ChannelFormat::Surround60 => 6,
+            ChannelFormat::Surround61 | ChannelFormat::Sdds70 | ChannelFormat::Surround70 | ChannelFormat::Atmos502 => 7,
+            ChannelFormat::Sdds71 | ChannelFormat::Surround71 | ChannelFormat::Atmos512 => 8,
+            ChannelFormat::Atmos702 | ChannelFormat::Atmos504 => 9,
+            ChannelFormat::Atmos712 | ChannelFormat::Atmos514 => 10,
+            ChannelFormat::Atmos704 => 11,
+            ChannelFormat::Atmos714 => 12,
+            ChannelFormat::Atmos706 | ChannelFormat::Atmos904 => 13,
+            ChannelFormat::Atmos716 | ChannelFormat::Atmos914 => 14,
+            ChannelFormat::Atmos906 => 15,
+            ChannelFormat::Atmos916 => 16,
+            ChannelFormat::Ambisonics(n) => {
+                let n = usize::from(n.clamp(1, 7)) + 1;
+                n * n
+            }
+        }
+    }
+    pub fn label(self) -> &'static str {
+        match self {
+            ChannelFormat::Mono => "Mono",
+            ChannelFormat::Stereo => "Stereo",
+            ChannelFormat::Lcr => "LCR",
+            ChannelFormat::Quad => "Quad",
+            ChannelFormat::Lcrs => "LCRS",
+            ChannelFormat::Surround50 => "5.0",
+            ChannelFormat::Surround51 => "5.1",
+            ChannelFormat::Surround60 => "6.0",
+            ChannelFormat::Surround61 => "6.1",
+            ChannelFormat::Sdds70 => "7.0 SDDS",
+            ChannelFormat::Sdds71 => "7.1 SDDS",
+            ChannelFormat::Surround70 => "7.0",
+            ChannelFormat::Surround71 => "7.1",
+            ChannelFormat::Atmos702 => "7.0.2",
+            ChannelFormat::Atmos712 => "7.1.2",
+            ChannelFormat::Atmos502 => "5.0.2",
+            ChannelFormat::Atmos512 => "5.1.2",
+            ChannelFormat::Atmos504 => "5.0.4",
+            ChannelFormat::Atmos514 => "5.1.4",
+            ChannelFormat::Atmos704 => "7.0.4",
+            ChannelFormat::Atmos714 => "7.1.4",
+            ChannelFormat::Atmos706 => "7.0.6",
+            ChannelFormat::Atmos716 => "7.1.6",
+            ChannelFormat::Atmos904 => "9.0.4",
+            ChannelFormat::Atmos914 => "9.1.4",
+            ChannelFormat::Atmos906 => "9.0.6",
+            ChannelFormat::Atmos916 => "9.1.6",
+            ChannelFormat::Ambisonics(1) => "1st Order Ambisonics",
+            ChannelFormat::Ambisonics(2) => "2nd Order Ambisonics",
+            ChannelFormat::Ambisonics(3) => "3rd Order Ambisonics",
+            ChannelFormat::Ambisonics(4) => "4th Order Ambisonics",
+            ChannelFormat::Ambisonics(5) => "5th Order Ambisonics",
+            ChannelFormat::Ambisonics(6) => "6th Order Ambisonics",
+            ChannelFormat::Ambisonics(_) => "7th Order Ambisonics",
+        }
+    }
+    pub fn from_id(s: &str) -> Option<ChannelFormat> {
+        ChannelFormat::ALL.into_iter().find(|f| f.label().eq_ignore_ascii_case(s.trim()))
+    }
+    /// Speakers in channel order, or empty for Ambisonics (ACN order, SN3D).
+    ///
+    /// Channel order is SMPTE / WAV order: speakers with a WAVE_FORMAT_EXTENSIBLE mask bit come in
+    /// ascending bit order (L R C LFE Ls Rs Lc Rc Cs Lss Rss Ltf Rtf Ltr Rtr; 7.x puts the rear
+    /// surrounds Lrs/Rrs on the "back" bits before the sides Lss/Rss), followed by speakers WAV
+    /// cannot name (the top-middle pair of .6 layouts). E.g. 5.1 = L R C LFE Ls Rs,
+    /// 7.1 = L R C LFE Lrs Rrs Lss Rss, 7.1.4 = L R C LFE Lrs Rrs Lss Rss Ltf Rtf Ltr Rtr.
+    pub fn speakers(self) -> &'static [Speaker] {
+        use Speaker::*;
+        match self {
+            ChannelFormat::Mono => &[C],
+            ChannelFormat::Stereo => &[L, R],
+            ChannelFormat::Lcr => &[L, R, C],
+            ChannelFormat::Quad => &[L, R, Ls, Rs],
+            ChannelFormat::Lcrs => &[L, R, C, Cs],
+            ChannelFormat::Surround50 => &[L, R, C, Ls, Rs],
+            ChannelFormat::Surround51 => &[L, R, C, Lfe, Ls, Rs],
+            ChannelFormat::Surround60 => &[L, R, C, Ls, Rs, Cs],
+            ChannelFormat::Surround61 => &[L, R, C, Lfe, Ls, Rs, Cs],
+            ChannelFormat::Sdds70 => &[L, R, C, Ls, Rs, Lc, Rc],
+            ChannelFormat::Sdds71 => &[L, R, C, Lfe, Ls, Rs, Lc, Rc],
+            ChannelFormat::Surround70 => &[L, R, C, Lrs, Rrs, Lss, Rss],
+            ChannelFormat::Surround71 => &[L, R, C, Lfe, Lrs, Rrs, Lss, Rss],
+            ChannelFormat::Atmos702 => &[L, R, C, Lrs, Rrs, Lss, Rss, Ltm, Rtm],
+            ChannelFormat::Atmos712 => &[L, R, C, Lfe, Lrs, Rrs, Lss, Rss, Ltm, Rtm],
+            ChannelFormat::Atmos502 => &[L, R, C, Ls, Rs, Ltm, Rtm],
+            ChannelFormat::Atmos512 => &[L, R, C, Lfe, Ls, Rs, Ltm, Rtm],
+            ChannelFormat::Atmos504 => &[L, R, C, Ls, Rs, Ltf, Rtf, Ltr, Rtr],
+            ChannelFormat::Atmos514 => &[L, R, C, Lfe, Ls, Rs, Ltf, Rtf, Ltr, Rtr],
+            ChannelFormat::Atmos704 => &[L, R, C, Lrs, Rrs, Lss, Rss, Ltf, Rtf, Ltr, Rtr],
+            ChannelFormat::Atmos714 => &[L, R, C, Lfe, Lrs, Rrs, Lss, Rss, Ltf, Rtf, Ltr, Rtr],
+            ChannelFormat::Atmos706 => &[L, R, C, Lrs, Rrs, Lss, Rss, Ltf, Rtf, Ltr, Rtr, Ltm, Rtm],
+            ChannelFormat::Atmos716 => &[L, R, C, Lfe, Lrs, Rrs, Lss, Rss, Ltf, Rtf, Ltr, Rtr, Ltm, Rtm],
+            ChannelFormat::Atmos904 => &[L, R, C, Lrs, Rrs, Lw, Rw, Lss, Rss, Ltf, Rtf, Ltr, Rtr],
+            ChannelFormat::Atmos914 => &[L, R, C, Lfe, Lrs, Rrs, Lw, Rw, Lss, Rss, Ltf, Rtf, Ltr, Rtr],
+            ChannelFormat::Atmos906 => &[L, R, C, Lrs, Rrs, Lw, Rw, Lss, Rss, Ltf, Rtf, Ltr, Rtr, Ltm, Rtm],
+            ChannelFormat::Atmos916 => &[L, R, C, Lfe, Lrs, Rrs, Lw, Rw, Lss, Rss, Ltf, Rtf, Ltr, Rtr, Ltm, Rtm],
+            ChannelFormat::Ambisonics(_) => &[],
+        }
+    }
+    pub fn is_ambisonic(self) -> bool {
+        matches!(self, ChannelFormat::Ambisonics(_))
+    }
+    pub fn has_lfe(self) -> bool {
+        self.speakers().contains(&Speaker::Lfe)
+    }
+    pub fn has_height(self) -> bool {
+        self.speakers().iter().any(|s| s.is_height())
+    }
+    /// Short per-channel labels for meters (`W Y Z X 5…` for Ambisonics).
+    pub fn channel_label(self, ch: usize) -> String {
+        match self.speakers().get(ch) {
+            Some(s) => s.label().to_string(),
+            None if self.is_ambisonic() => ["W", "Y", "Z", "X"].get(ch).map_or_else(|| format!("{}", ch + 1), ToString::to_string),
+            None => format!("{}", ch + 1),
+        }
+    }
+    /// WAVE_FORMAT_EXTENSIBLE channel mask (0 = no positions, e.g. Ambisonics). Speakers that WAV
+    /// cannot name (top middle) borrow the top-front bits when the layout has no top fronts.
+    pub fn channel_mask(self) -> u32 {
+        let sp = self.speakers();
+        let has_tf = sp.contains(&Speaker::Ltf);
+        sp.iter().fold(0u32, |m, s| match s {
+            Speaker::Ltm if !has_tf => m | 0x1000,
+            Speaker::Rtm if !has_tf => m | 0x4000,
+            s => m | s.wave_bit(),
+        })
+    }
+    /// Best format for a channel count.
+    pub fn for_channels(n: usize) -> ChannelFormat {
+        [
+            ChannelFormat::Mono,
+            ChannelFormat::Stereo,
+            ChannelFormat::Lcr,
+            ChannelFormat::Quad,
+            ChannelFormat::Surround50,
+            ChannelFormat::Surround51,
+            ChannelFormat::Surround70,
+            ChannelFormat::Surround71,
+        ]
+        .into_iter()
+        .find(|f| f.channels() == n)
+        .unwrap_or(if n <= 1 { ChannelFormat::Mono } else { ChannelFormat::Stereo })
+    }
+}
+
+/// A loudspeaker position in a channel format.
+///
+/// Angles follow ITU-R BS.775 / Dolby conventions: azimuth in degrees, 0 = front centre, positive
+/// = to the right; elevation in degrees above the listener plane.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum Speaker {
+    L,
+    R,
+    C,
+    Lfe,
+    /// 5.x surrounds (±110°).
+    Ls,
+    Rs,
+    /// SDDS inner fronts (±15°).
+    Lc,
+    Rc,
+    /// Centre surround (180°).
+    Cs,
+    /// 7.x side surrounds (±90°).
+    Lss,
+    Rss,
+    /// 7.x rear surrounds (±150°).
+    Lrs,
+    Rrs,
+    /// 9.x front wides (±60°).
+    Lw,
+    Rw,
+    /// Top front (±45°, elevation 45°).
+    Ltf,
+    Rtf,
+    /// Top middle (±90°, elevation 45°).
+    Ltm,
+    Rtm,
+    /// Top rear (±135°, elevation 45°).
+    Ltr,
+    Rtr,
+}
+
+impl Speaker {
+    pub fn azimuth(self) -> f32 {
+        match self {
+            Speaker::L => -30.0,
+            Speaker::R => 30.0,
+            Speaker::C | Speaker::Lfe => 0.0,
+            Speaker::Ls => -110.0,
+            Speaker::Rs => 110.0,
+            Speaker::Lc => -15.0,
+            Speaker::Rc => 15.0,
+            Speaker::Cs => 180.0,
+            Speaker::Lss => -90.0,
+            Speaker::Rss => 90.0,
+            Speaker::Lrs => -150.0,
+            Speaker::Rrs => 150.0,
+            Speaker::Lw => -60.0,
+            Speaker::Rw => 60.0,
+            Speaker::Ltf => -45.0,
+            Speaker::Rtf => 45.0,
+            Speaker::Ltm => -90.0,
+            Speaker::Rtm => 90.0,
+            Speaker::Ltr => -135.0,
+            Speaker::Rtr => 135.0,
+        }
+    }
+    pub fn elevation(self) -> f32 {
+        if self.is_height() { 45.0 } else { 0.0 }
+    }
+    pub fn is_height(self) -> bool {
+        matches!(self, Speaker::Ltf | Speaker::Rtf | Speaker::Ltm | Speaker::Rtm | Speaker::Ltr | Speaker::Rtr)
+    }
+    pub fn is_lfe(self) -> bool {
+        self == Speaker::Lfe
+    }
+    pub fn label(self) -> &'static str {
+        match self {
+            Speaker::L => "L",
+            Speaker::R => "R",
+            Speaker::C => "C",
+            Speaker::Lfe => "LFE",
+            Speaker::Ls => "Ls",
+            Speaker::Rs => "Rs",
+            Speaker::Lc => "Lc",
+            Speaker::Rc => "Rc",
+            Speaker::Cs => "Cs",
+            Speaker::Lss => "Lss",
+            Speaker::Rss => "Rss",
+            Speaker::Lrs => "Lrs",
+            Speaker::Rrs => "Rrs",
+            Speaker::Lw => "Lw",
+            Speaker::Rw => "Rw",
+            Speaker::Ltf => "Ltf",
+            Speaker::Rtf => "Rtf",
+            Speaker::Ltm => "Ltm",
+            Speaker::Rtm => "Rtm",
+            Speaker::Ltr => "Ltr",
+            Speaker::Rtr => "Rtr",
+        }
+    }
+    /// WAVE_FORMAT_EXTENSIBLE `dwChannelMask` bit (0 for speakers WAV cannot name).
+    pub fn wave_bit(self) -> u32 {
+        match self {
+            Speaker::L => 0x1,
+            Speaker::R => 0x2,
+            Speaker::C => 0x4,
+            Speaker::Lfe => 0x8,
+            Speaker::Ls | Speaker::Lrs => 0x10,
+            Speaker::Rs | Speaker::Rrs => 0x20,
+            Speaker::Lc | Speaker::Lw => 0x40,
+            Speaker::Rc | Speaker::Rw => 0x80,
+            Speaker::Cs => 0x100,
+            Speaker::Lss => 0x200,
+            Speaker::Rss => 0x400,
+            Speaker::Ltf => 0x1000,
+            Speaker::Rtf => 0x4000,
+            Speaker::Ltr => 0x8000,
+            Speaker::Rtr => 0x2_0000,
+            Speaker::Ltm | Speaker::Rtm => 0,
+        }
+    }
+}
+
+/// Surround panner position (Pro Tools-style X/Y puck). `None` on a mixer means "use the stereo
+/// pan", which keeps sessions made before surround mixing sounding exactly as they did.
+#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
+#[serde(default)]
+pub struct SurroundPan {
+    /// -1 (left) ..= 1 (right).
+    pub x: f32,
+    /// -1 (back) ..= 1 (front).
+    pub y: f32,
+    /// Elevation 0 (ear level) ..= 1 (overhead), used by height formats.
+    pub z: f32,
+    /// 0 = point source ..= 1 = spread over every speaker.
+    pub divergence: f32,
+    /// Centre speaker share of front-centre images, 0..=100 % (0 = phantom centre on L/R).
+    pub center: f32,
+    /// LFE send level, dB (-144 = off).
+    pub lfe_db: f32,
+}
+
+impl Default for SurroundPan {
+    fn default() -> Self {
+        SurroundPan { x: 0.0, y: 1.0, z: 0.0, divergence: 0.0, center: 100.0, lfe_db: -144.0 }
+    }
+}
+
+impl SurroundPan {
+    /// Puck at the stereo pan position (front edge).
+    pub fn from_stereo(pan: f32) -> Self {
+        SurroundPan { x: finite_or(pan, 0.0).clamp(-1.0, 1.0), ..SurroundPan::default() }
+    }
+    /// Clamp into range (NaN → defaults).
+    pub fn sanitize(&mut self) {
+        let d = SurroundPan::default();
+        self.x = finite_or(self.x, d.x).clamp(-1.0, 1.0);
+        self.y = finite_or(self.y, d.y).clamp(-1.0, 1.0);
+        self.z = finite_or(self.z, d.z).clamp(0.0, 1.0);
+        self.divergence = finite_or(self.divergence, d.divergence).clamp(0.0, 1.0);
+        self.center = finite_or(self.center, d.center).clamp(0.0, 100.0);
+        self.lfe_db = finite_or(self.lfe_db, d.lfe_db).clamp(-144.0, 12.0);
+    }
+}
+
+/// An internal mix bus (Pro Tools "bus" paths).
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct Bus {
+    pub id: BusId,
+    pub name: String,
+    pub format: ChannelFormat,
+}
+
+/// Physical output paths (from the I/O setup).
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct OutputPath {
+    pub name: String,
+    /// First hardware channel (0-based).
+    pub first_channel: u16,
+    pub format: ChannelFormat,
+}
+
+/// Where a signal goes or comes from.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum Route {
+    #[default]
+    None,
+    /// The main output (hardware outputs 1-2, or the bounce source).
+    Main,
+    Bus(BusId),
+    /// Hardware input/output by path name.
+    Hardware(String),
+}
+
+/// A plugin instance on an insert slot.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct Insert {
+    /// Registry id from `soundcraft-dsp` (e.g. `eq7`, `comp`).
+    pub plugin: String,
+    #[serde(default, deserialize_with = "finite_params")]
+    pub params: BTreeMap<String, f32>,
+    #[serde(default)]
+    pub bypass: bool,
+    #[serde(default = "yes")]
+    pub active: bool,
+    /// Preset name shown in the plugin window header.
+    #[serde(default)]
+    pub preset: String,
+    /// Opaque plugin state (third-party plugins: CLAP state / VST3 component + controller
+    /// state), standard base64. Restored into a new instance before it first processes.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state: Option<String>,
+    /// The session audio source a sample-playing instrument (the built-in Sampler) plays.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sample: Option<SourceId>,
+}
+
+fn yes() -> bool {
+    true
+}
+
+impl Insert {
+    pub fn new(plugin: impl Into<String>) -> Self {
+        Insert {
+            plugin: plugin.into(),
+            params: BTreeMap::new(),
+            bypass: false,
+            active: true,
+            preset: String::from("<factory default>"),
+            state: None,
+            sample: None,
+        }
+    }
+
+    /// The decoded plugin state (`None` when absent or malformed).
+    pub fn state_bytes(&self) -> Option<Vec<u8>> {
+        self.state.as_deref().and_then(crate::b64::decode)
+    }
+
+    /// Stores a plugin state blob (base64-encoded); an empty blob clears it.
+    pub fn set_state_bytes(&mut self, data: &[u8]) {
+        self.state = (!data.is_empty()).then(|| crate::b64::encode(data));
+    }
+}
+
+/// A send to a bus.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct SendSlot {
+    pub target: Route,
+    pub level_db: f32,
+    pub pan: f32,
+    pub mute: bool,
+    pub pre_fader: bool,
+    #[serde(default = "yes")]
+    pub follow_main_pan: bool,
+    /// Surround position into a multichannel bus (None = follow the track / stereo pan).
+    #[serde(default)]
+    pub surround: Option<SurroundPan>,
+}
+
+impl SendSlot {
+    pub fn new(target: Route) -> Self {
+        SendSlot { target, level_db: -144.0, pan: 0.0, mute: false, pre_fader: false, follow_main_pan: true, surround: None }
+    }
+}
+
+/// The channel strip.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct Mixer {
+    pub volume_db: f32,
+    /// One panner per source channel for mono/stereo (stereo tracks: two panners, default hard L/R).
+    pub pan: Vec<f32>,
+    pub mute: bool,
+    pub solo: bool,
+    #[serde(default)]
+    pub solo_safe: bool,
+    /// Live record-enable state. Runtime-only: opening a session must never arm an input.
+    #[serde(skip)]
+    pub record_arm: bool,
+    /// Live input-monitor state. Runtime-only: opening a session must never enable monitoring.
+    #[serde(skip)]
+    pub input_monitor: bool,
+    #[serde(default)]
+    pub phase_invert: bool,
+    pub input: Route,
+    pub output: Route,
+    pub inserts: Vec<Option<Insert>>,
+    pub sends: Vec<Option<SendSlot>>,
+    pub automation_mode: AutomationMode,
+    /// Input gain / trim, dB.
+    #[serde(default)]
+    pub trim_db: f32,
+    /// VCA master that controls this track, if any (track id of the VCA).
+    #[serde(default)]
+    pub vca: Option<u64>,
+    /// Surround panner, used when the output is multichannel (None = the stereo pan to L/R).
+    #[serde(default)]
+    pub surround: Option<SurroundPan>,
+}
+
+impl Mixer {
+    pub fn new(format: ChannelFormat) -> Self {
+        let pan = match format {
+            ChannelFormat::Mono => vec![0.0],
+            ChannelFormat::Stereo => vec![-1.0, 1.0],
+            _ => Vec::new(),
+        };
+        Mixer {
+            volume_db: 0.0,
+            pan,
+            mute: false,
+            solo: false,
+            solo_safe: false,
+            record_arm: false,
+            input_monitor: false,
+            phase_invert: false,
+            input: Route::None,
+            output: Route::Main,
+            inserts: vec![None; INSERT_SLOTS],
+            sends: vec![None; SEND_SLOTS],
+            automation_mode: AutomationMode::Read,
+            trim_db: 0.0,
+            vca: None,
+            surround: None,
+        }
+    }
+
+    /// Clamp everything into range (after deserialising untrusted files).
+    pub fn sanitize(&mut self) {
+        self.volume_db = finite_or(self.volume_db, 0.0).clamp(-144.0, 12.0);
+        for p in &mut self.pan {
+            *p = finite_or(*p, 0.0).clamp(-1.0, 1.0);
+        }
+        self.inserts.resize(INSERT_SLOTS, None);
+        self.sends.resize(SEND_SLOTS, None);
+        for s in self.sends.iter_mut().flatten() {
+            s.level_db = finite_or(s.level_db, -144.0).clamp(-144.0, 12.0);
+            s.pan = finite_or(s.pan, 0.0).clamp(-1.0, 1.0);
+            if let Some(sp) = &mut s.surround {
+                sp.sanitize();
+            }
+        }
+        if let Some(sp) = &mut self.surround {
+            sp.sanitize();
+        }
+        self.trim_db = finite_or(self.trim_db, 0.0).clamp(-144.0, 24.0);
+    }
+}
+
+impl crate::Session {
+    /// The main mix format: the format of the first (main) output path, at least stereo and at
+    /// most 16 channels (wider formats fall back to stereo).
+    pub fn main_format(&self) -> ChannelFormat {
+        match self.outputs.first().map(|o| o.format) {
+            Some(f) if (2..=16).contains(&f.channels()) => f,
+            _ => ChannelFormat::Stereo,
+        }
+    }
+}
+
+pub(crate) fn finite_or(v: f32, d: f32) -> f32 {
+    if v.is_finite() { v } else { d }
+}
+
+/// Parameters saved as `null` (how JSON writes NaN and infinity) or beyond `f32` are dropped, so
+/// they keep their defaults instead of failing the whole session.
+fn finite_params<'de, D: serde::Deserializer<'de>>(d: D) -> Result<BTreeMap<String, f32>, D::Error> {
+    let params: BTreeMap<String, Option<f64>> = serde::Deserialize::deserialize(d)?;
+    Ok(params.into_iter().filter_map(|(k, v)| Some((k, v.map(|v| v as f32).filter(|v| v.is_finite())?))).collect())
+}
+
+/// Fader taper used by Pro Tools-style faders: position 0..1 ↔ dB (-inf..+12).
+pub fn fader_pos_to_db(pos: f32) -> f32 {
+    let p = finite_or(pos, 0.0).clamp(0.0, 1.0);
+    if p <= 0.0 {
+        return -144.0;
+    }
+    // Piecewise: top 75 % covers -24..+12 linearly-ish, the bottom compresses to -inf.
+    if p >= 0.25 { -24.0 + (p - 0.25) / 0.75 * 36.0 } else { -24.0 - (1.0 - p / 0.25).powf(1.5) * 120.0 }
+}
+
+pub fn fader_db_to_pos(db: f32) -> f32 {
+    let db = finite_or(db, -144.0);
+    if db <= -144.0 {
+        return 0.0;
+    }
+    if db >= -24.0 {
+        (0.25 + (db.min(12.0) + 24.0) / 36.0 * 0.75).min(1.0)
+    } else {
+        let x = ((-24.0 - db) / 120.0).clamp(0.0, 1.0).powf(1.0 / 1.5);
+        ((1.0 - x) * 0.25).max(0.0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn insert_state_round_trips_through_json() {
+        let mut i = Insert::new("vst3:00");
+        assert_eq!(i.state_bytes(), None);
+        let blob: Vec<u8> = (0..=255u8).cycle().take(1000).collect();
+        i.set_state_bytes(&blob);
+        let json = serde_json::to_string(&i).unwrap();
+        let back: Insert = serde_json::from_str(&json).unwrap();
+        assert_eq!(back.state_bytes().unwrap(), blob);
+        i.set_state_bytes(&[]);
+        assert_eq!(i.state, None);
+        // Old sessions have no `state`; stateless inserts don't write one.
+        let old: Insert = serde_json::from_str(r#"{"plugin":"eq_7band"}"#).unwrap();
+        assert_eq!(old.state, None);
+        assert!(!serde_json::to_string(&old).unwrap().contains("state"));
+        // A hostile state string decodes to nothing rather than failing the load.
+        let bad: Insert = serde_json::from_str(r#"{"plugin":"x","state":"!!!"}"#).unwrap();
+        assert_eq!(bad.state_bytes(), None);
+    }
+
+    #[test]
+    fn params_saved_as_null_or_out_of_range_are_dropped() {
+        let mut i = Insert::new("eq_7band");
+        i.params.extend([("gain".to_string(), f32::NAN), ("q".to_string(), 0.7)]);
+        let back: Insert = serde_json::from_str(&serde_json::to_string(&i).unwrap()).unwrap();
+        assert_eq!(back.params, BTreeMap::from([("q".to_string(), 0.7)]));
+        let big: Insert = serde_json::from_str(r#"{"plugin":"x","params":{"gain":1e39,"q":0.5}}"#).unwrap();
+        assert_eq!(big.params, BTreeMap::from([("q".to_string(), 0.5)]));
+    }
+
+    #[test]
+    fn fader_taper_round_trips() {
+        for db in [-100.0f32, -60.0, -24.0, -10.0, 0.0, 6.0, 12.0] {
+            let p = fader_db_to_pos(db);
+            assert!((fader_pos_to_db(p) - db).abs() < 0.05, "{db} → {p}");
+        }
+        assert_eq!(fader_pos_to_db(0.0), -144.0);
+        assert_eq!(fader_db_to_pos(f32::NAN), 0.0);
+    }
+
+    #[test]
+    fn mixer_defaults_and_sanitize() {
+        let mut m = Mixer::new(ChannelFormat::Stereo);
+        assert_eq!(m.pan, vec![-1.0, 1.0]);
+        m.volume_db = f32::INFINITY;
+        m.inserts.truncate(2);
+        m.sanitize();
+        assert_eq!(m.volume_db, 0.0);
+        assert_eq!(m.inserts.len(), INSERT_SLOTS);
+    }
+
+    #[test]
+    fn speaker_layouts_match_channel_counts_and_masks() {
+        for f in ChannelFormat::ALL {
+            if !f.is_ambisonic() {
+                assert_eq!(f.speakers().len(), f.channels(), "{f:?}");
+                // Mask bits are unique and in ascending channel order.
+                let bits: Vec<u32> = f.speakers().iter().map(|s| s.wave_bit()).filter(|b| *b != 0).collect();
+                assert!(bits.windows(2).all(|w| w[0] < w[1]), "{f:?} not in WAV order");
+            }
+        }
+        assert_eq!(ChannelFormat::Surround51.channel_mask(), 0x3F);
+        assert_eq!(ChannelFormat::Surround71.channel_mask(), 0x63F);
+        assert_eq!(ChannelFormat::Atmos714.channel_mask(), 0x2_D63F);
+        assert_eq!(ChannelFormat::Ambisonics(1).channel_mask(), 0);
+    }
+
+    #[test]
+    fn surround_pan_defaults_and_old_sessions() {
+        let m = Mixer::new(ChannelFormat::Mono);
+        assert_eq!(m.surround, None);
+        // A mixer saved before surround existed still loads.
+        let mut v = serde_json::to_value(&m).unwrap();
+        v.as_object_mut().unwrap().remove("surround");
+        let back: Mixer = serde_json::from_value(v).unwrap();
+        assert_eq!(back.surround, None);
+        let mut sp: SurroundPan = serde_json::from_str(r#"{"x": 5.0}"#).unwrap();
+        sp.sanitize();
+        assert_eq!(sp.x, 1.0);
+        assert_eq!(sp.center, 100.0);
+    }
+
+    #[test]
+    fn formats() {
+        assert_eq!(ChannelFormat::for_channels(6), ChannelFormat::Surround51);
+        assert_eq!(ChannelFormat::from_id("stereo"), Some(ChannelFormat::Stereo));
+    }
+}
diff --git a/crates/scraft-format/src/session.rs b/crates/scraft-format/src/session.rs
new file mode 100644
index 000000000..021cab8bc
--- /dev/null
+++ b/crates/scraft-format/src/session.rs
@@ -0,0 +1,1331 @@
+//! The session: the whole document.
+
+use crate::clip::{bound, bound_sequence};
+use crate::soundcraft_time::{FrameRate, GridScale, GridValue, Range, SampleRate, Samples, TempoMap, TimeFormat};
+use crate::{
+    Bus, BusId, ChannelFormat, Clip, ClipId, Group, GroupId, MarkerId, MarkerKind, MemoryLocation, OutputPath, Source, SourceId, SourcePool,
+    TRACK_COLORS, Track, TrackId, TrackKind, VideoSource,
+};
+
+/// Native session file extension.
+pub const SESSION_EXTENSION: &str = "scraft";
+
+/// `EditState::values` key holding the feet+frames reading of sample 0, in frames.
+pub const FEET_FRAMES_START: &str = "feet_frames.start";
+
+#[derive(Debug, Clone, PartialEq, thiserror::Error)]
+pub enum SessionError {
+    #[error("not a SoundCraft session: {0}")]
+    Format(String),
+    #[error("session file version {0} is newer than this SoundCraft supports")]
+    Version(u32),
+    #[error("{0}")]
+    Invalid(String),
+}
+
+/// Session bit depth for recording/rendering.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum BitDepthSetting {
+    Int16,
+    #[default]
+    Int24,
+    Float32,
+}
+
+/// Edit modes.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum EditMode {
+    Shuffle,
+    #[default]
+    Slip,
+    Spot,
+    Grid,
+    /// Relative grid: moves keep their offset from the grid.
+    GridRelative,
+}
+
+impl EditMode {
+    pub fn label(self) -> &'static str {
+        match self {
+            EditMode::Shuffle => "SHUFFLE",
+            EditMode::Slip => "SLIP",
+            EditMode::Spot => "SPOT",
+            EditMode::Grid => "GRID",
+            EditMode::GridRelative => "REL GRID",
+        }
+    }
+    pub fn from_id(s: &str) -> Option<EditMode> {
+        match s.to_ascii_lowercase().as_str() {
+            "shuffle" => Some(EditMode::Shuffle),
+            "slip" => Some(EditMode::Slip),
+            "spot" => Some(EditMode::Spot),
+            "grid" | "absolute_grid" => Some(EditMode::Grid),
+            "relative_grid" | "rel_grid" | "grid_relative" => Some(EditMode::GridRelative),
+            _ => None,
+        }
+    }
+    pub fn is_grid(self) -> bool {
+        matches!(self, EditMode::Grid | EditMode::GridRelative)
+    }
+}
+
+/// Edit tools.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum Tool {
+    Zoom,
+    Trim,
+    #[default]
+    Selector,
+    Grabber,
+    Scrubber,
+    Pencil,
+    Smart,
+}
+
+impl Tool {
+    pub const ALL: [Tool; 7] = [Tool::Zoom, Tool::Trim, Tool::Selector, Tool::Grabber, Tool::Scrubber, Tool::Pencil, Tool::Smart];
+    pub fn id(self) -> &'static str {
+        match self {
+            Tool::Zoom => "zoom",
+            Tool::Trim => "trim",
+            Tool::Selector => "selector",
+            Tool::Grabber => "grabber",
+            Tool::Scrubber => "scrubber",
+            Tool::Pencil => "pencil",
+            Tool::Smart => "smart",
+        }
+    }
+    pub fn label(self) -> &'static str {
+        match self {
+            Tool::Zoom => "Zoomer",
+            Tool::Trim => "Trim",
+            Tool::Selector => "Selector",
+            Tool::Grabber => "Grabber",
+            Tool::Scrubber => "Scrubber",
+            Tool::Pencil => "Pencil",
+            Tool::Smart => "Smart Tool",
+        }
+    }
+    pub fn from_id(s: &str) -> Option<Tool> {
+        Tool::ALL.into_iter().find(|t| t.id() == s.to_ascii_lowercase())
+    }
+    /// F-key shortcut (F5..F10) like the incumbent.
+    pub fn fkey(self) -> Option<&'static str> {
+        match self {
+            Tool::Zoom => Some("F5"),
+            Tool::Trim => Some("F6"),
+            Tool::Selector => Some("F7"),
+            Tool::Grabber => Some("F8"),
+            Tool::Scrubber => Some("F9"),
+            Tool::Pencil => Some("F10"),
+            Tool::Smart => None,
+        }
+    }
+}
+
+/// Track view lanes.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum TrackView {
+    Waveform,
+    Blocks,
+    Volume,
+    Pan,
+    Mute,
+}
+
+/// Horizontal zoom + scroll.
+#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct ZoomState {
+    /// Samples per pixel (point).
+    pub samples_per_px: f64,
+    /// Left edge of the visible timeline.
+    pub scroll: Samples,
+    /// Waveform vertical zoom factor.
+    pub waveform_zoom: f32,
+    /// Zoom preset memories 1..5.
+    pub presets: [f64; 5],
+}
+
+impl Default for ZoomState {
+    /// Starts with a practical overview zoom and five reusable preset levels.
+    fn default() -> Self {
+        ZoomState { samples_per_px: 1024.0, scroll: 0, waveform_zoom: 1.0, presets: [64.0, 256.0, 1024.0, 4096.0, 16384.0] }
+    }
+}
+
+/// The view Zoom Toggle goes back to.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct ZoomToggle {
+    pub samples_per_px: f64,
+    pub scroll: Samples,
+    pub heights: Vec<(TrackId, crate::TrackHeight)>,
+}
+
+/// Edit-window state saved with the session (selection, tools, modes, view settings).
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct EditState {
+    pub tool: Tool,
+    pub edit_mode: EditMode,
+    /// The edit selection (a point = insertion position).
+    pub selection: Range,
+    /// Tracks in the edit selection.
+    pub selected_tracks: Vec<TrackId>,
+    /// Clips explicitly selected (Grabber selection).
+    #[serde(default)]
+    pub selected_clips: Vec<ClipId>,
+    /// Audio files selected in the Clip List.
+    #[serde(default)]
+    pub selected_sources: Vec<SourceId>,
+    /// Playhead position when stopped.
+    pub playhead: Samples,
+    pub grid: GridValue,
+    pub nudge: GridValue,
+    /// Grid/Nudge time scales follow the main counter when enabled.
+    #[serde(default)]
+    pub grid_follow_main: bool,
+    #[serde(default)]
+    pub nudge_follow_main: bool,
+    /// Grid lines and snapping use visible clip boundaries and memory locations while the numeric
+    /// Grid value is retained for when this mode is left.
+    #[serde(default)]
+    pub grid_clips_markers: bool,
+    #[serde(default = "yes")]
+    pub grid_lines: bool,
+    pub main_counter: TimeFormat,
+    pub sub_counter: Option<TimeFormat>,
+    pub zoom: ZoomState,
+    /// Set while Zoom Toggle is on.
+    pub zoom_toggle: Option<ZoomToggle>,
+    /// Visible rulers.
+    pub rulers: Vec<String>,
+    pub link_timeline_edit: bool,
+    pub link_track_edit: bool,
+    pub insertion_follows_playback: bool,
+    pub loop_playback: bool,
+    pub pre_post_roll: bool,
+    pub pre_roll: Samples,
+    pub post_roll: Samples,
+    pub tab_to_transient: bool,
+    pub automation_follows_edit: bool,
+    pub markers_follow_edit: bool,
+    pub layered_editing: bool,
+    pub mirrored_midi: bool,
+    pub click: bool,
+    pub countoff: bool,
+    pub countoff_bars: u32,
+    pub midi_merge: bool,
+    pub record_mode: String,
+    pub loop_record: bool,
+    pub quickpunch: bool,
+    pub scrolling: String,
+    pub solo_mode: String,
+    pub pre_fader_metering: bool,
+    pub delay_compensation: bool,
+    pub keyboard_focus: String,
+    /// Timeline selection when it is unlinked from the edit selection.
+    pub timeline_selection: Range,
+    /// Generic on/off view and option flags keyed by id (e.g. `view.clip.name`, `waveform.rectified`,
+    /// `options.midi_thru`). Saved with the session so every view setting persists.
+    #[serde(default)]
+    pub flags: std::collections::BTreeSet<String>,
+    /// Numeric settings keyed by id (e.g. `click.volume_db`, `engine.buffer_size`).
+    #[serde(default)]
+    pub values: std::collections::BTreeMap<String, f64>,
+}
+
+impl EditState {
+    pub fn flag(&self, id: &str) -> bool {
+        self.flags.contains(id)
+    }
+    pub fn set_flag(&mut self, id: &str, on: bool) {
+        if on {
+            self.flags.insert(id.to_string());
+        } else {
+            self.flags.remove(id);
+        }
+    }
+    pub fn value(&self, id: &str, default: f64) -> f64 {
+        self.values.get(id).copied().filter(|v| v.is_finite()).unwrap_or(default)
+    }
+}
+
+fn yes() -> bool {
+    true
+}
+
+impl Default for EditState {
+    /// Starts the Edit window in Slip mode with independent Grid and Nudge scales.
+    fn default() -> Self {
+        EditState {
+            tool: Tool::Smart,
+            edit_mode: EditMode::Slip,
+            selection: Range::default(),
+            selected_tracks: Vec::new(),
+            selected_clips: Vec::new(),
+            selected_sources: Vec::new(),
+            playhead: 0,
+            grid: GridValue::default(),
+            nudge: GridValue::Seconds(1.0),
+            grid_follow_main: false,
+            nudge_follow_main: false,
+            grid_clips_markers: false,
+            grid_lines: true,
+            main_counter: TimeFormat::MinSecs,
+            sub_counter: Some(TimeFormat::Samples),
+            zoom: ZoomState::default(),
+            zoom_toggle: None,
+            rulers: vec!["bars_beats".into(), "min_secs".into(), "tempo".into(), "meter".into(), "markers".into()],
+            link_timeline_edit: true,
+            link_track_edit: false,
+            insertion_follows_playback: false,
+            loop_playback: false,
+            pre_post_roll: false,
+            pre_roll: 96_000,
+            post_roll: 96_000,
+            tab_to_transient: false,
+            automation_follows_edit: true,
+            markers_follow_edit: false,
+            layered_editing: false,
+            mirrored_midi: false,
+            click: false,
+            countoff: false,
+            countoff_bars: 2,
+            midi_merge: false,
+            record_mode: "normal".into(),
+            loop_record: false,
+            quickpunch: false,
+            scrolling: "page".into(),
+            solo_mode: "sip".into(),
+            pre_fader_metering: false,
+            delay_compensation: true,
+            keyboard_focus: "commands".into(),
+            timeline_selection: Range::default(),
+            flags: ["view.clip.name", "view.clip.gain_line", "waveform.peak", "view.clip.overlap_shadows", "view.marker.ruler_lines"]
+                .iter()
+                .map(ToString::to_string)
+                .collect(),
+            values: std::collections::BTreeMap::new(),
+        }
+    }
+}
+
+/// Clip List › Auto Rename: the names that editing gives the clips it separates from a clip.
+/// Each new clip is named `name`, then `zeros` zeros, then `number`, then `suffix`, and `number`
+/// counts up by one for the next clip.
+#[derive(Debug, Clone, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
+pub struct AutoName {
+    pub name: String,
+    /// The number the next new clip gets.
+    pub number: u64,
+    pub zeros: usize,
+    pub suffix: String,
+    /// Tells this scheme from another one under the same key after an undo or in another session,
+    /// for pastes from the clipboard. 0 matches no scheme.
+    #[serde(default)]
+    pub id: u64,
+}
+
+impl AutoName {
+    /// The largest starting number.
+    pub const MAX_NUMBER: u64 = 999_999_999;
+    /// The most zeros before the number.
+    pub const MAX_ZEROS: usize = 9;
+
+    /// Room for `name` and `suffix` together: 29 characters stay free for 9 zeros and the 20
+    /// digits of a u64, so a clip name never loses its number to [`MAX_NAME_CHARS`].
+    pub const MAX_TEXT_CHARS: usize = MAX_NAME_CHARS - 29;
+
+    /// Repair a scheme read from a file: names that can be drawn and at most [`Self::MAX_ZEROS`] zeros.
+    pub fn sanitize(&mut self) {
+        truncate_chars(&mut self.name, Self::MAX_TEXT_CHARS);
+        truncate_chars(&mut self.suffix, Self::MAX_TEXT_CHARS - self.name.chars().count());
+        self.zeros = self.zeros.min(Self::MAX_ZEROS);
+    }
+}
+
+/// The document.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct Session {
+    pub format_version: u32,
+    pub name: String,
+    #[serde(deserialize_with = "sample_rate_or_default")]
+    pub sample_rate: SampleRate,
+    pub bit_depth: BitDepthSetting,
+    pub frame_rate: FrameRate,
+    /// Timecode of sample 0 (session start), as a sample count.
+    pub timecode_start: Samples,
+    pub tempo: TempoMap,
+    #[serde(default)]
+    pub key_signatures: Vec<(Samples, String)>,
+    pub tracks: Vec<Track>,
+    pub sources: Vec<Source>,
+    /// Movies referenced by Video track clips.
+    #[serde(default)]
+    pub videos: Vec<VideoSource>,
+    pub busses: Vec<Bus>,
+    pub outputs: Vec<OutputPath>,
+    pub markers: Vec<MemoryLocation>,
+    pub groups: Vec<Group>,
+    /// Clip List › Auto Rename schemes, keyed by the ids in [`Clip::auto_name`]. The clips separated
+    /// from one clip share its scheme, so they count up one number sequence.
+    #[serde(default)]
+    pub auto_names: std::collections::BTreeMap<u64, crate::AutoName>,
+    pub edit: EditState,
+    pub next_id: u64,
+    #[serde(default)]
+    pub comments: String,
+    /// Original MIDI performances keyed by clip id (Event › MIDI Operations › Restore/Flatten
+    /// Performance). Independent of undo so a restore survives later edits.
+    #[serde(default)]
+    pub midi_originals: std::collections::BTreeMap<u64, crate::soundcraft_midi::Sequence>,
+    #[serde(skip)]
+    pub pool: SourcePool,
+    /// The folder relative source paths point into: where the session was opened or last saved.
+    #[serde(skip)]
+    pub folder: Option<std::path::PathBuf>,
+}
+
+/// Older SoundCraft builds repaired an in-range but invalid sample rate after reading a session.
+/// `craft-time` validates `SampleRate` during serde, so keep that file compatibility at this
+/// domain boundary while retaining strict serde validation for direct `SampleRate` use.
+fn sample_rate_or_default<'de, D>(deserializer: D) -> Result<SampleRate, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    let hz = <u32 as serde::Deserialize>::deserialize(deserializer)?;
+    Ok(SampleRate::new(hz).unwrap_or_default())
+}
+
+impl Default for Session {
+    fn default() -> Self {
+        Session::new("Untitled", SampleRate::HZ_48000)
+    }
+}
+
+impl Session {
+    pub const FORMAT_VERSION: u32 = 1;
+
+    pub fn new(name: impl Into<String>, sample_rate: SampleRate) -> Self {
+        let mut s = Session {
+            format_version: Self::FORMAT_VERSION,
+            name: name.into(),
+            sample_rate,
+            bit_depth: BitDepthSetting::Int24,
+            frame_rate: FrameRate::Fps30,
+            timecode_start: 0,
+            tempo: TempoMap::default(),
+            key_signatures: Vec::new(),
+            tracks: Vec::new(),
+            sources: Vec::new(),
+            videos: Vec::new(),
+            busses: Vec::new(),
+            outputs: vec![OutputPath { name: "Out 1-2".into(), first_channel: 0, format: ChannelFormat::Stereo }],
+            markers: Vec::new(),
+            groups: Vec::new(),
+            auto_names: std::collections::BTreeMap::new(),
+            edit: EditState::default(),
+            next_id: 1,
+            comments: String::new(),
+            midi_originals: std::collections::BTreeMap::new(),
+            pool: SourcePool::default(),
+            folder: None,
+        };
+        s.edit.pre_roll = sample_rate.samples(2.0);
+        s.edit.post_roll = sample_rate.samples(2.0);
+        s
+    }
+
+    /// Allocate a fresh id.
+    pub fn alloc(&mut self) -> u64 {
+        let id = self.next_id.max(1);
+        self.next_id = id.saturating_add(1);
+        id
+    }
+
+    // ---- lookups -------------------------------------------------------------------------
+
+    pub fn track(&self, id: TrackId) -> Option<&Track> {
+        self.tracks.iter().find(|t| t.id == id)
+    }
+    pub fn track_mut(&mut self, id: TrackId) -> Option<&mut Track> {
+        self.tracks.iter_mut().find(|t| t.id == id)
+    }
+    pub fn track_index(&self, id: TrackId) -> Option<usize> {
+        self.tracks.iter().position(|t| t.id == id)
+    }
+    pub fn track_by_name(&self, name: &str) -> Option<&Track> {
+        self.tracks.iter().find(|t| t.name == name).or_else(|| self.tracks.iter().find(|t| t.name.eq_ignore_ascii_case(name)))
+    }
+    pub fn master(&self) -> Option<&Track> {
+        self.tracks.iter().find(|t| t.kind == TrackKind::Master)
+    }
+    pub fn source(&self, id: SourceId) -> Option<&Source> {
+        self.sources.iter().find(|s| s.id == id)
+    }
+    pub fn video(&self, id: SourceId) -> Option<&VideoSource> {
+        self.videos.iter().find(|v| v.id == id)
+    }
+    pub fn bus(&self, id: BusId) -> Option<&Bus> {
+        self.busses.iter().find(|b| b.id == id)
+    }
+    pub fn bus_by_name(&self, name: &str) -> Option<&Bus> {
+        self.busses.iter().find(|b| b.name.eq_ignore_ascii_case(name))
+    }
+    pub fn group(&self, id: GroupId) -> Option<&Group> {
+        self.groups.iter().find(|g| g.id == id)
+    }
+    pub fn marker(&self, id: MarkerId) -> Option<&MemoryLocation> {
+        self.markers.iter().find(|m| m.id == id)
+    }
+
+    /// Find a clip anywhere (active playlists).
+    pub fn find_clip(&self, id: ClipId) -> Option<(TrackId, &Clip)> {
+        self.tracks.iter().find_map(|t| t.clips().iter().find(|c| c.id == id).map(|c| (t.id, c)))
+    }
+
+    pub fn find_clip_mut(&mut self, id: ClipId) -> Option<&mut Clip> {
+        self.tracks.iter_mut().find_map(|t| t.playlist_mut().and_then(|p| p.clip_mut(id)))
+    }
+
+    /// Clips on every playlist, alternates included.
+    pub fn all_clips(&self) -> impl Iterator<Item = &Clip> {
+        self.tracks.iter().flat_map(|t| t.playlists.iter().flat_map(|p| &p.clips))
+    }
+
+    pub fn clips_using(&self, src: SourceId) -> impl Iterator<Item = &Clip> {
+        self.all_clips().filter(move |c| c.source() == Some(src))
+    }
+
+    /// End of the last clip on any track (session length).
+    pub fn content_end(&self) -> Samples {
+        self.tracks.iter().filter_map(|t| t.playlist().map(|p| p.end())).max().unwrap_or(0)
+    }
+
+    /// Feet+frames reading of sample 0, in frames (Setup › Current Feet+Frames Position).
+    pub fn feet_frames_start(&self) -> i64 {
+        self.edit.value(FEET_FRAMES_START, 0.0) as i64
+    }
+
+    /// Format a position against this session's timecode and feet+frames references.
+    pub fn format_position(&self, at: Samples, fmt: TimeFormat) -> String {
+        crate::soundcraft_time::format_position(
+            at,
+            fmt,
+            self.sample_rate,
+            &self.tempo,
+            self.frame_rate,
+            self.timecode_start,
+            self.feet_frames_start(),
+        )
+    }
+
+    /// Parse a position typed in `fmt` against this session's references.
+    pub fn parse_position(&self, text: &str, fmt: TimeFormat) -> Result<Samples, crate::soundcraft_time::TimeError> {
+        crate::soundcraft_time::parse_position(
+            text,
+            fmt,
+            self.sample_rate,
+            &self.tempo,
+            self.frame_rate,
+            self.timecode_start,
+            self.feet_frames_start(),
+        )
+    }
+
+    /// Whether the Edit window shows a track: unhidden, with every parent folder open.
+    pub fn track_shown(&self, track: &Track) -> bool {
+        if track.hidden {
+            return false;
+        }
+        let mut folder = track.folder;
+        for _ in 0..64 {
+            let Some(parent) = folder.and_then(|id| self.track(id)) else { return true };
+            if !parent.folder_open {
+                return false;
+            }
+            folder = parent.folder;
+        }
+        false
+    }
+
+    /// Collects unique visible active-playlist clip boundaries and memory-location boundaries.
+    fn clip_marker_grid_points(&self, keep: impl Fn(Samples) -> bool, excluded: &[ClipId], include_zero: bool) -> Vec<Samples> {
+        let mut points = Vec::new();
+        let excluded: std::collections::HashSet<ClipId> = excluded.iter().copied().collect();
+        if include_zero && keep(0) {
+            points.push(0);
+        }
+        for clip in
+            self.tracks.iter().filter(|track| self.track_shown(track)).flat_map(|track| track.clips()).filter(|clip| !excluded.contains(&clip.id))
+        {
+            points.extend([clip.start, clip.end()].into_iter().filter(|point| keep(*point)));
+        }
+        for marker in &self.markers {
+            if keep(marker.start) {
+                points.push(marker.start);
+            }
+            if marker.end != marker.start && keep(marker.end) {
+                points.push(marker.end);
+            }
+        }
+        points.sort_unstable();
+        points.dedup();
+        points
+    }
+
+    /// Sample-domain Timecode reference; Feet+Frames applies its origin in frames separately.
+    fn grid_origin(&self) -> Samples {
+        match self.edit.grid.scale() {
+            GridScale::Timecode => self.timecode_start,
+            _ => 0,
+        }
+    }
+
+    /// Grid lines for the current Grid value, including clip and marker boundaries.
+    pub fn grid_lines(&self, start: Samples, end: Samples, max: usize) -> Vec<Samples> {
+        if !self.edit.grid_clips_markers {
+            if let GridValue::FeetFrames(value) = self.edit.grid {
+                return value.lines(start, end, self.sample_rate, self.frame_rate, self.feet_frames_start(), max);
+            }
+            let origin = self.grid_origin();
+            return self
+                .edit
+                .grid
+                .lines(start.saturating_add(origin), end.saturating_add(origin), self.sample_rate, &self.tempo, self.frame_rate, max)
+                .into_iter()
+                .map(|point| point.saturating_sub(origin))
+                .collect();
+        }
+        let points = self.clip_marker_grid_points(|point| point >= start && point < end, &[], true);
+        if points.len() <= max {
+            return points;
+        }
+        match max {
+            0 => Vec::new(),
+            1 => points.first().copied().into_iter().collect(),
+            _ => {
+                let span = i128::from(end).saturating_sub(i128::from(start)).max(1);
+                let mut bucket = None;
+                points
+                    .into_iter()
+                    .filter(|point| {
+                        let next = i128::from(*point).saturating_sub(i128::from(start)).saturating_mul(max as i128) / span;
+                        if bucket == Some(next) {
+                            false
+                        } else {
+                            bucket = Some(next);
+                            true
+                        }
+                    })
+                    .collect()
+            }
+        }
+    }
+
+    /// The current Grid line at or before `position`.
+    pub fn grid_line_at_or_before(&self, position: Samples) -> Samples {
+        self.grid_line_at_or_before_excluding(position, &[])
+    }
+
+    /// Find the current Grid line at or before `position` without boundaries of `excluded` clips.
+    pub fn grid_line_at_or_before_excluding(&self, position: Samples, excluded: &[ClipId]) -> Samples {
+        if !self.edit.grid_clips_markers {
+            if let GridValue::FeetFrames(value) = self.edit.grid {
+                return value.line_at_or_before(position, self.sample_rate, self.frame_rate, self.feet_frames_start());
+            }
+            let origin = self.grid_origin();
+            return self
+                .edit
+                .grid
+                .line_at_or_before(position.saturating_add(origin), self.sample_rate, &self.tempo, self.frame_rate)
+                .saturating_sub(origin);
+        }
+        self.clip_marker_grid_points(|_| true, excluded, true).into_iter().take_while(|point| *point <= position).last().unwrap_or(position)
+    }
+
+    /// Snap to the nearest line in the current Grid.
+    pub fn snap_to_grid(&self, position: Samples) -> Samples {
+        self.snap_to_grid_excluding(position, &[])
+    }
+
+    /// Snap to the nearest current Grid line without using boundaries of `excluded` clips.
+    pub fn snap_to_grid_excluding(&self, position: Samples, excluded: &[ClipId]) -> Samples {
+        if !self.edit.grid_clips_markers {
+            if let GridValue::FeetFrames(value) = self.edit.grid {
+                return value.snap(position, self.sample_rate, self.frame_rate, self.feet_frames_start());
+            }
+            let origin = self.grid_origin();
+            return self.edit.grid.snap(position.saturating_add(origin), self.sample_rate, &self.tempo, self.frame_rate).saturating_sub(origin);
+        }
+        let mut points = self.clip_marker_grid_points(|_| true, excluded, false);
+        if !points.is_empty() {
+            points.push(0);
+        }
+        points.into_iter().min_by_key(|point| i128::from(*point).saturating_sub(i128::from(position)).abs()).unwrap_or(position)
+    }
+
+    pub fn next_track_color(&self) -> [u8; 3] {
+        let n = self.tracks.iter().filter(|t| t.kind != TrackKind::Master).count();
+        TRACK_COLORS.get(n % TRACK_COLORS.len()).copied().unwrap_or([128, 128, 128])
+    }
+
+    /// A unique track name: `base`, or `base 1`, `base 2` … like the incumbent ("Audio 1").
+    pub fn unique_track_name(&self, base: &str) -> String {
+        let taken = |n: &str| self.tracks.iter().any(|t| t.name == n);
+        if !base.is_empty() && !taken(base) && !matches!(base, "Audio" | "Aux" | "MIDI" | "Inst" | "VCA" | "Folder" | "Master") {
+            return base.to_string();
+        }
+        let prefix = format!("{base} ");
+        let used: std::collections::HashSet<u64> = self
+            .tracks
+            .iter()
+            .filter_map(|t| t.name.strip_prefix(&prefix))
+            .filter_map(|n| n.parse().ok().filter(|i: &u64| i.to_string() == n))
+            .collect();
+        let i = (1..).find(|i| !used.contains(i)).unwrap_or(1);
+        format!("{base} {i}")
+    }
+
+    /// Add a track with defaults; returns its id.
+    pub fn add_track(&mut self, kind: TrackKind, format: ChannelFormat, name: Option<&str>) -> TrackId {
+        let id = TrackId(self.alloc());
+        let name = self.unique_track_name(name.unwrap_or(kind.default_name()));
+        let color = if kind == TrackKind::Master { [140, 140, 140] } else { self.next_track_color() };
+        let mut t = Track::new(id, name, kind, format, color);
+        if kind == TrackKind::Master {
+            t.mixer.output = crate::Route::Main;
+            t.mixer.input = crate::Route::Main;
+        }
+        // Master faders sit at the bottom like the incumbent; others go before any master.
+        let pos = if kind == TrackKind::Master {
+            self.tracks.len()
+        } else {
+            self.tracks.iter().position(|t| t.kind == TrackKind::Master).unwrap_or(self.tracks.len())
+        };
+        self.tracks.insert(pos, t);
+        id
+    }
+
+    pub fn add_bus(&mut self, name: &str, format: ChannelFormat) -> BusId {
+        if let Some(b) = self.bus_by_name(name) {
+            return b.id;
+        }
+        let id = BusId(self.alloc());
+        self.busses.push(Bus { id, name: name.to_string(), format });
+        id
+    }
+
+    /// Add a memory location; returns its id.
+    pub fn add_marker(&mut self, name: &str, kind: MarkerKind, start: Samples, end: Samples) -> MarkerId {
+        let id = MarkerId(self.alloc());
+        let number = self.markers.iter().map(|m| m.number).max().unwrap_or(0).saturating_add(1);
+        self.markers.push(MemoryLocation {
+            id,
+            number,
+            name: name.to_string(),
+            kind,
+            start,
+            end: end.max(start),
+            comments: String::new(),
+            color: None,
+            ruler: 1,
+            track: None,
+        });
+        self.markers.sort_by_key(|m| m.start);
+        id
+    }
+
+    pub fn new_clip_id(&mut self) -> ClipId {
+        ClipId(self.alloc())
+    }
+
+    /// Drop the Auto Rename schemes that no clip on any playlist uses.
+    pub fn prune_auto_names(&mut self) {
+        let used: std::collections::BTreeSet<u64> = self.all_clips().filter_map(|c| c.auto_name).collect();
+        self.auto_names.retain(|k, _| used.contains(k));
+    }
+
+    // ---- persistence ---------------------------------------------------------------------
+
+    pub fn to_json(&self) -> Result<String, SessionError> {
+        serde_json::to_string_pretty(self).map_err(|e| SessionError::Format(e.to_string()))
+    }
+
+    /// Parse a session; decoded audio must be attached separately (`pool`).
+    ///
+    /// The text is parsed straight into the document, never into a `serde_json::Value` tree
+    /// first (which takes many times the file's size). Only the version is read before that.
+    /// A field of the document given twice in one object is refused (`duplicate field`), as no
+    /// writer repeats one. Keys of maps (plugin params, edit values, Auto Rename schemes, MIDI
+    /// originals) and unknown keys keep the last value given, as before.
+    pub fn from_json(text: &str) -> Result<Session, SessionError> {
+        /// The version alone: every other field is skipped, not kept.
+        #[derive(serde::Deserialize)]
+        struct Head {
+            format_version: Option<serde_json::Number>,
+        }
+        // `Head` would also take a JSON array as its fields in order: only an object has a version.
+        let object = text.trim_start_matches([' ', '\t', '\n', '\r']).starts_with('{');
+        let version = match object.then(|| serde_json::from_str::<Head>(text)) {
+            Some(Ok(head)) => head.format_version,
+            // A version given twice is that error, not a missing version.
+            Some(Err(e)) if e.to_string().starts_with("duplicate field") => return Err(SessionError::Format(e.to_string())),
+            // Valid JSON of another shape (not an object, or a version that is not a number)
+            // has no version; anything else is not JSON.
+            _ => {
+                serde_json::from_str::<serde::de::IgnoredAny>(text).map_err(|e| SessionError::Format(e.to_string()))?;
+                None
+            }
+        };
+        let ver = version.and_then(|v| v.as_u64()).ok_or_else(|| SessionError::Format("missing format_version".into()))?;
+        if ver > u64::from(Self::FORMAT_VERSION) {
+            return Err(SessionError::Version(u32::try_from(ver).unwrap_or(u32::MAX)));
+        }
+        let mut s: Session = serde_json::from_str(text).map_err(|e| SessionError::Format(e.to_string()))?;
+        s.sanitize();
+        s.validate()?;
+        Ok(s)
+    }
+
+    /// Repair invariants after loading untrusted data.
+    pub fn sanitize(&mut self) {
+        let max_id = self
+            .tracks
+            .iter()
+            .map(|t| t.id.0)
+            .chain(self.tracks.iter().flat_map(|t| t.playlists.iter().flat_map(|p| p.clips.iter().map(|c| c.id.0))))
+            .chain(self.sources.iter().map(|s| s.id.0))
+            .chain(self.auto_names.keys().copied())
+            .chain(self.videos.iter().map(|v| v.id.0))
+            .chain(self.busses.iter().map(|b| b.id.0))
+            .chain(self.markers.iter().map(|m| m.id.0))
+            .chain(self.groups.iter().map(|g| g.id.0))
+            .max()
+            .unwrap_or(0);
+        self.next_id = self.next_id.max(max_id.saturating_add(1));
+        truncate_chars(&mut self.name, MAX_NAME_CHARS);
+        truncate_chars(&mut self.comments, MAX_COMMENT_CHARS);
+        for t in &mut self.tracks {
+            t.mixer.sanitize();
+            truncate_chars(&mut t.name, MAX_NAME_CHARS);
+            truncate_chars(&mut t.comments, MAX_COMMENT_CHARS);
+            if t.playlists.is_empty() {
+                t.playlists.push(crate::Playlist::new(t.name.clone()));
+            }
+            if t.active_playlist >= t.playlists.len() {
+                t.active_playlist = 0;
+            }
+            for p in &mut t.playlists {
+                truncate_chars(&mut p.name, MAX_NAME_CHARS);
+                p.clips.retain(|c| c.length > 0);
+                p.clips.iter_mut().for_each(Clip::sanitize);
+                p.sort();
+            }
+            for l in &mut t.automation {
+                l.points.retain(|p| p.value.is_finite());
+                let (lo, hi, _) = l.param.range();
+                l.points.iter_mut().for_each(|p| p.value = p.value.clamp(lo, hi));
+                l.points.iter_mut().for_each(|p| bound(&mut p.at));
+                l.points.sort_by_key(|p| p.at);
+            }
+        }
+        for m in &mut self.markers {
+            bound(&mut m.start);
+            bound(&mut m.end);
+            truncate_chars(&mut m.name, MAX_NAME_CHARS);
+            truncate_chars(&mut m.comments, MAX_COMMENT_CHARS);
+        }
+        for (at, key) in &mut self.key_signatures {
+            bound(at);
+            truncate_chars(key, MAX_NAME_CHARS);
+        }
+        self.midi_originals.values_mut().for_each(bound_sequence);
+        let e = &mut self.edit;
+        for at in [
+            &mut e.selection.start,
+            &mut e.selection.end,
+            &mut e.timeline_selection.start,
+            &mut e.timeline_selection.end,
+            &mut e.playhead,
+            &mut e.pre_roll,
+            &mut e.post_roll,
+            &mut e.zoom.scroll,
+            &mut self.timecode_start,
+        ] {
+            bound(at);
+        }
+        for v in &mut self.videos {
+            if !v.frame_rate.is_finite() || v.frame_rate < 0.0 {
+                v.frame_rate = 0.0;
+            }
+            if !v.duration.is_finite() || v.duration < 0.0 {
+                v.duration = 0.0;
+            }
+            truncate_chars(&mut v.name, MAX_NAME_CHARS);
+        }
+        self.busses.iter_mut().for_each(|b| truncate_chars(&mut b.name, MAX_NAME_CHARS));
+        self.outputs.iter_mut().for_each(|o| truncate_chars(&mut o.name, MAX_NAME_CHARS));
+        self.groups.iter_mut().for_each(|g| truncate_chars(&mut g.name, MAX_NAME_CHARS));
+        self.sources.iter_mut().for_each(|s| truncate_chars(&mut s.name, MAX_NAME_CHARS));
+        // Drop performances whose clip no longer exists anywhere (any playlist).
+        let clip_ids: std::collections::BTreeSet<u64> =
+            self.tracks.iter().flat_map(|t| t.playlists.iter().flat_map(|p| p.clips.iter().map(|c| c.id.0))).collect();
+        self.midi_originals.retain(|id, _| clip_ids.contains(id));
+        self.prune_auto_names();
+        self.auto_names.values_mut().for_each(crate::AutoName::sanitize);
+        if !self.edit.zoom.samples_per_px.is_finite() || self.edit.zoom.samples_per_px <= 0.0 {
+            self.edit.zoom.samples_per_px = 1024.0;
+        }
+        if SampleRate::new(self.sample_rate.hz()).is_err() {
+            self.sample_rate = SampleRate::default();
+        }
+        self.tempo.sanitize();
+    }
+
+    /// Reject a document whose ids are ambiguous or exhausted, run after [`Session::sanitize`] on
+    /// untrusted data. Duplicate ids in a namespace make commands, selections and source
+    /// associations act on an arbitrary one of the objects; a maximal `next_id` -- or a maximal
+    /// existing id, which `sanitize` folds into `next_id` -- makes every later allocation return
+    /// `u64::MAX` and repeat itself.
+    fn validate(&self) -> Result<(), SessionError> {
+        if self.next_id == u64::MAX {
+            return Err(SessionError::Invalid("the session id space is exhausted".into()));
+        }
+        distinct("track", self.tracks.iter().map(|t| t.id.0))?;
+        distinct("clip", self.tracks.iter().flat_map(|t| t.playlists.iter().flat_map(|p| p.clips.iter().map(|c| c.id.0))))?;
+        distinct("source", self.sources.iter().map(|s| s.id.0))?;
+        distinct("video", self.videos.iter().map(|v| v.id.0))?;
+        distinct("bus", self.busses.iter().map(|b| b.id.0))?;
+        distinct("marker", self.markers.iter().map(|m| m.id.0))?;
+        distinct("group", self.groups.iter().map(|g| g.id.0))?;
+        Ok(())
+    }
+}
+
+/// The most characters kept of a name read from a file: longer ones can't be shown, and drawing
+/// a name of a million characters overflows the renderer's buffers.
+pub const MAX_NAME_CHARS: usize = 256;
+/// The most characters kept of a comment read from a file.
+pub const MAX_COMMENT_CHARS: usize = 4096;
+
+/// Cut `s` to at most `max` characters.
+pub fn truncate_chars(s: &mut String, max: usize) {
+    if let Some((end, _)) = s.char_indices().nth(max) {
+        s.truncate(end);
+    }
+}
+
+/// Every id in `ids` distinct, or an error naming the namespace and the repeated id.
+fn distinct(kind: &str, ids: impl Iterator<Item = u64>) -> Result<(), SessionError> {
+    let mut seen = std::collections::HashSet::new();
+    for id in ids {
+        if !seen.insert(id) {
+            return Err(SessionError::Invalid(format!("duplicate {kind} id {id}")));
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn add_tracks_names_and_order() {
+        let mut s = Session::default();
+        let m = s.add_track(TrackKind::Master, ChannelFormat::Stereo, None);
+        let a = s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        let b = s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        let v = s.add_track(TrackKind::Audio, ChannelFormat::Stereo, Some("Vocal"));
+        assert_eq!(s.track(a).map(|t| t.name.as_str()), Some("Audio 1"));
+        assert_eq!(s.track(b).map(|t| t.name.as_str()), Some("Audio 2"));
+        assert_eq!(s.track(v).map(|t| t.name.as_str()), Some("Vocal"));
+        assert_eq!(s.tracks.last().map(|t| t.id), Some(m));
+        let v2 = s.add_track(TrackKind::Audio, ChannelFormat::Stereo, Some("Vocal"));
+        assert_eq!(s.track(v2).map(|t| t.name.as_str()), Some("Vocal 1"));
+    }
+
+    #[test]
+    fn json_round_trip() {
+        let mut s = Session::default();
+        let t = s.add_track(TrackKind::Audio, ChannelFormat::Stereo, None);
+        let cid = s.new_clip_id();
+        if let Some(p) = s.track_mut(t).and_then(Track::playlist_mut) {
+            p.clips.push(Clip::audio(cid, "c", SourceId(99), 0, 10, 100));
+        }
+        s.add_marker("Verse", MarkerKind::Marker, 48_000, 48_000);
+        let text = s.to_json().unwrap();
+        let back = Session::from_json(&text).unwrap();
+        assert_eq!(back, s);
+    }
+
+    /// Clips/Markers mode snaps and draws at clip and memory-location boundaries.
+    #[test]
+    fn clips_markers_grid_uses_visible_clip_edges_and_memory_locations() {
+        let mut s = Session::default();
+        let track = s.add_track(TrackKind::Midi, ChannelFormat::Mono, None);
+        let clip = Clip::midi(s.new_clip_id(), "Notes", 1_000, 2_000, crate::soundcraft_midi::Sequence::default());
+        let clip_id = clip.id;
+        s.track_mut(track).and_then(Track::playlist_mut).unwrap().clips.push(clip);
+        let hidden = s.add_track(TrackKind::Midi, ChannelFormat::Mono, None);
+        let hidden_clip = Clip::midi(s.new_clip_id(), "Hidden", 3_200, 100, crate::soundcraft_midi::Sequence::default());
+        if let Some(track) = s.track_mut(hidden) {
+            track.hidden = true;
+            track.playlist_mut().unwrap().clips.push(hidden_clip);
+        }
+        s.add_marker("Cue", MarkerKind::Marker, 2_500, 2_500);
+        s.add_marker("Selection", MarkerKind::Selection, 4_000, 4_500);
+        s.edit.grid_clips_markers = true;
+
+        assert_eq!(s.grid_lines(0, 5_000, 20), [0, 1_000, 2_500, 3_000, 4_000, 4_500]);
+        assert_eq!(s.grid_line_at_or_before(2_800), 2_500);
+        assert_eq!(s.snap_to_grid(2_800), 3_000);
+        assert_eq!(s.snap_to_grid(3_700), 4_000);
+        assert_eq!(s.grid_lines(2_400, 4_100, 2), [2_500, 4_000]);
+        assert_eq!(s.snap_to_grid(3_200), 3_000);
+        assert_eq!(s.snap_to_grid_excluding(2_800, &[clip_id]), 2_500);
+
+        let folder = s.add_track(TrackKind::Folder, ChannelFormat::Stereo, None);
+        s.track_mut(track).unwrap().folder = Some(folder);
+        s.track_mut(folder).unwrap().folder_open = false;
+        assert_eq!(s.grid_lines(0, 5_000, 20), [0, 2_500, 4_000, 4_500]);
+    }
+
+    /// Open hidden folders keep their visible descendants eligible for lines and snapping.
+    #[test]
+    fn clips_markers_grid_keeps_visible_children_of_hidden_open_folders() {
+        let mut s = Session::default();
+        let outer = s.add_track(TrackKind::Folder, ChannelFormat::Stereo, None);
+        let inner = s.add_track(TrackKind::Folder, ChannelFormat::Stereo, None);
+        let child = s.add_track(TrackKind::Midi, ChannelFormat::Mono, None);
+        let clip = Clip::midi(s.new_clip_id(), "Visible", 1_000, 2_000, crate::soundcraft_midi::Sequence::default());
+        s.track_mut(inner).unwrap().folder = Some(outer);
+        s.track_mut(inner).unwrap().hidden = true;
+        s.track_mut(child).unwrap().folder = Some(inner);
+        s.track_mut(child).unwrap().playlist_mut().unwrap().clips.push(clip);
+        s.edit.grid_clips_markers = true;
+
+        assert_eq!(s.grid_lines(0, 5_000, 20), [0, 1_000, 3_000]);
+        assert_eq!(s.snap_to_grid(2_800), 3_000);
+        assert_eq!(s.grid_line_at_or_before(2_800), 1_000);
+
+        s.track_mut(child).unwrap().hidden = true;
+        assert_eq!(s.grid_lines(0, 5_000, 20), [0]);
+        assert_eq!(s.snap_to_grid(2_800), 2_800);
+        s.track_mut(child).unwrap().hidden = false;
+        s.track_mut(inner).unwrap().folder_open = false;
+        assert_eq!(s.grid_lines(0, 5_000, 20), [0]);
+        s.track_mut(inner).unwrap().folder_open = true;
+        s.track_mut(outer).unwrap().folder_open = false;
+        assert_eq!(s.grid_lines(0, 5_000, 20), [0]);
+    }
+
+    /// With no real Clips/Markers boundaries, snapping leaves the position alone while drawing
+    /// retains the session-start line.
+    #[test]
+    fn empty_clips_markers_grid_does_not_snap_everything_to_zero() {
+        let mut s = Session::default();
+        s.edit.grid_clips_markers = true;
+        assert_eq!(s.grid_lines(0, 1_000, 10), [0]);
+        assert_eq!(s.snap_to_grid(678), 678);
+    }
+
+    /// Frame-based grids share the same references as their displayed counters.
+    #[test]
+    fn frame_grids_apply_session_counter_origins() {
+        let mut s = Session { sample_rate: SampleRate::HZ_48000, frame_rate: FrameRate::Fps30, timecode_start: 1_600, ..Session::default() };
+        s.edit.grid = GridValue::Timecode(crate::soundcraft_time::TimecodeValue::Second);
+        assert_eq!(s.grid_line_at_or_before(47_000), 46_400);
+        assert_eq!(s.snap_to_grid(46_400), 46_400);
+
+        s.edit.grid = GridValue::FeetFrames(crate::soundcraft_time::FeetFramesValue::Foot);
+        s.edit.values.insert(FEET_FRAMES_START.into(), 1.0);
+        assert_eq!(s.grid_line_at_or_before(25_000), 24_000);
+        assert_eq!(s.snap_to_grid(24_000), 24_000);
+    }
+
+    /// Every Feet+Frames increment shares the parser's single rounding at fractional frame rates.
+    #[test]
+    fn feet_frames_grid_matches_parsed_positions_with_signed_frame_origins() {
+        use crate::soundcraft_time::FeetFramesValue;
+        for rate in [FrameRate::Fps23_976, FrameRate::Fps29_97, FrameRate::Fps29_97Drop, FrameRate::Fps59_94Drop] {
+            let mut s = Session { sample_rate: SampleRate::HZ_48000, frame_rate: rate, ..Session::default() };
+            for origin in [-17, -1, 1, 17] {
+                s.edit.values.insert(FEET_FRAMES_START.into(), origin as f64);
+                for value in FeetFramesValue::ALL {
+                    s.edit.grid = GridValue::FeetFrames(value);
+                    for feet in [-64, -2, 0, 1, 2, 4, 7, 12, 128] {
+                        let at = s.parse_position(&format!("{feet}+00"), TimeFormat::FeetFrames).unwrap();
+                        assert_eq!(s.grid_line_at_or_before(at), at, "{rate:?} {value:?} origin {origin}, foot {feet}");
+                        assert_eq!(s.snap_to_grid(at), at);
+                        assert_eq!(s.grid_lines(at - 1, at + 2, 4), [at]);
+                    }
+                }
+            }
+        }
+        let mut s = Session { sample_rate: SampleRate::HZ_48000, frame_rate: FrameRate::Fps29_97, ..Session::default() };
+        s.edit.values.insert(FEET_FRAMES_START.into(), 1.0);
+        s.edit.grid = GridValue::FeetFrames(FeetFramesValue::Foot);
+        assert_eq!(s.snap_to_grid(49_649), 49_650);
+        assert_eq!(s.format_position(49_650, TimeFormat::FeetFrames), "2+00");
+    }
+
+    /// Drop-frame minute boundaries keep their counter alignment with signed session origins.
+    #[test]
+    fn drop_frame_grids_apply_session_origins_at_minute_boundaries() {
+        for (rate, minute_frame) in [(FrameRate::Fps29_97Drop, 1_800), (FrameRate::Fps59_94Drop, 3_600)] {
+            for origin_frame in [-1, 1] {
+                let sr = SampleRate::HZ_48000;
+                let origin = rate.samples_at_frame(origin_frame, sr);
+                let mut s = Session { sample_rate: sr, frame_rate: rate, timecode_start: origin, ..Session::default() };
+                s.edit.grid = GridValue::Timecode(crate::soundcraft_time::TimecodeValue::Second);
+                for boundary in [-minute_frame, minute_frame] {
+                    let at = rate.samples_at_frame(boundary, sr) - origin;
+                    assert_eq!(s.grid_line_at_or_before(at), at, "{rate:?}, origin {origin_frame}");
+                    assert_eq!(s.snap_to_grid(at + 1), at, "{rate:?}, origin {origin_frame}");
+                    assert_eq!(s.grid_lines(at - 1, at + 2, 10), [at]);
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn session_with_legacy_fit_height_loads() {
+        let mut s = Session::default();
+        let t = s.add_track(TrackKind::Audio, ChannelFormat::Stereo, None);
+        if let Some(track) = s.track_mut(t) {
+            track.height = crate::TrackHeight::Large;
+        }
+        let text = s.to_json().unwrap().replace("\"height\": \"Large\"", "\"height\": \"Fit\"");
+        assert!(text.contains("\"height\": \"Fit\""));
+        let back = Session::from_json(&text).unwrap();
+        assert_eq!(back.track(t).map(|tr| tr.height), Some(crate::TrackHeight::Medium));
+    }
+
+    /// Session JSON omits live flags and ignores their values in legacy documents.
+    #[test]
+    fn live_input_states_are_never_saved_or_restored() {
+        let mut s = Session::default();
+        let t = s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        let track = s.track_mut(t).unwrap();
+        track.mixer.mute = true;
+        track.mixer.record_arm = true;
+        track.mixer.input_monitor = true;
+
+        let mut value = serde_json::to_value(&s).unwrap();
+        let mixer = value["tracks"][0]["mixer"].as_object_mut().unwrap();
+        assert!(!mixer.contains_key("record_arm"));
+        assert!(!mixer.contains_key("input_monitor"));
+
+        // Files written by older versions may still contain these keys; ignore them on input.
+        mixer.insert("record_arm".into(), serde_json::Value::Bool(true));
+        mixer.insert("input_monitor".into(), serde_json::Value::Bool(true));
+        let loaded = Session::from_json(&value.to_string()).unwrap();
+        let track = loaded.track(t).unwrap();
+        assert!(track.mixer.mute, "persistent mixer state still loads");
+        assert!(!track.mixer.record_arm);
+        assert!(!track.mixer.input_monitor);
+    }
+
+    #[test]
+    fn video_clip_round_trips_and_old_sessions_load() {
+        let mut s = Session::default();
+        let t = s.add_track(TrackKind::Video, ChannelFormat::Mono, None);
+        let vid = SourceId(s.alloc());
+        s.videos.push(VideoSource {
+            id: vid,
+            name: "cut.mov".into(),
+            path: "/films/cut.mov".into(),
+            width: 1920,
+            height: 1080,
+            frame_rate: 23.976,
+            duration: 12.5,
+            codec: "prores".into(),
+            offline: None,
+        });
+        let cid = s.new_clip_id();
+        if let Some(p) = s.track_mut(t).and_then(Track::playlist_mut) {
+            p.clips.push(Clip::video(cid, "cut", vid, 480, 0, 600_000));
+        }
+        let back = Session::from_json(&s.to_json().unwrap()).unwrap();
+        assert_eq!(back, s);
+        let c = &back.track(t).unwrap().clips()[0];
+        assert_eq!((c.video_source(), c.source(), c.source_offset(), c.is_audio()), (Some(vid), None, 480, false));
+        assert_eq!(back.track(t).unwrap().kind.label(), "Video Track");
+        assert!(back.video(vid).is_some());
+        // A session written before video support has no `videos` key.
+        let mut v = serde_json::to_value(Session::default()).unwrap();
+        v.as_object_mut().unwrap().remove("videos");
+        assert!(Session::from_json(&v.to_string()).unwrap().videos.is_empty());
+        // Trimming the start keeps the picture anchored.
+        let mut c = c.clone();
+        c.trim_start_to(100);
+        assert_eq!(c.source_offset(), 580);
+    }
+
+    #[test]
+    fn unique_track_names_take_the_first_free_number() {
+        let mut s = Session::default();
+        for name in ["Piano", "Piano 1", "Piano 3", "Piano 02", "Pianos 2"] {
+            s.add_track(TrackKind::Audio, ChannelFormat::Mono, Some(name));
+        }
+        assert_eq!(s.unique_track_name("Piano"), "Piano 2");
+        assert_eq!(s.unique_track_name("Organ"), "Organ");
+        assert_eq!(s.unique_track_name("Audio"), "Audio 1");
+    }
+
+    #[test]
+    fn names_from_a_file_are_cut_to_a_length_that_can_be_drawn() {
+        let mut s = Session::default();
+        let t = s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        if let Some(tr) = s.track_mut(t) {
+            tr.name = "é".repeat(1_000);
+        }
+        s.comments = "c".repeat(10_000);
+        let back = Session::from_json(&s.to_json().unwrap()).unwrap();
+        assert_eq!(back.track(t).map(|tr| tr.name.chars().count()), Some(MAX_NAME_CHARS));
+        assert_eq!(back.comments.len(), MAX_COMMENT_CHARS);
+    }
+
+    #[test]
+    fn a_bad_sample_rate_or_tempo_is_repaired_on_load() {
+        let mut v = serde_json::to_value(Session::default()).unwrap();
+        v["sample_rate"] = serde_json::json!(0);
+        v["tempo"]["tempos"] = serde_json::json!([{"tick": 0, "bpm": 4e9}]);
+        let s = Session::from_json(&v.to_string()).unwrap();
+        assert_eq!((s.sample_rate, s.tempo), (SampleRate::HZ_48000, TempoMap::default()));
+    }
+
+    #[test]
+    fn a_meter_change_far_beyond_the_position_range_is_dropped_on_load() {
+        let mut v = serde_json::to_value(Session::default()).unwrap();
+        v["tempo"]["meters"] = serde_json::json!([
+            {"tick": 0, "numerator": 4, "denominator": 4},
+            {"tick": i64::MAX, "numerator": 3, "denominator": 4}
+        ]);
+        let s = Session::from_json(&v.to_string()).unwrap();
+        assert_eq!(s.parse_position("2|1|000", TimeFormat::BarsBeats), Ok(96_000));
+    }
+
+    #[test]
+    fn rejects_garbage_and_future_versions() {
+        assert!(Session::from_json("not json").is_err());
+        assert!(Session::from_json("{}").is_err());
+        let mut v = serde_json::to_value(Session::default()).unwrap();
+        v["format_version"] = serde_json::json!(999);
+        assert!(matches!(Session::from_json(&v.to_string()), Err(SessionError::Version(999))));
+    }
+
+    #[test]
+    fn the_version_is_checked_as_before() {
+        // #892: the version is read without building the whole document as a tree; the errors
+        // stay what they were.
+        let format = |t: &str| match Session::from_json(t) {
+            Err(SessionError::Format(m)) => m,
+            other => panic!("{t}: {other:?}"),
+        };
+        for t in [
+            "{}",
+            "[]",
+            "[5]",
+            " \n[1, {}]",
+            "\"x\"",
+            "5",
+            "null",
+            r#"{"format_version":"1"}"#,
+            r#"{"format_version":-1}"#,
+            r#"{"format_version":1.5}"#,
+            r#"{"format_version":null}"#,
+            r#"{"format_version":[0,0,0]}"#,
+            r#"{"name":"x","other":{"format_version":1}}"#,
+        ] {
+            assert_eq!(format(t), "missing format_version", "{t}");
+        }
+        for t in ["not json", r#"{"format_version":1"#, r#"{"format_version":1} x"#, r#"{"format_version":"1", ]"#] {
+            let want = serde_json::from_str::<serde_json::Value>(t).unwrap_err().to_string();
+            assert_eq!(format(t), want, "{t}");
+        }
+        let mut v = serde_json::to_value(Session::default()).unwrap();
+        for (ver, want) in [(serde_json::json!(2), 2), (serde_json::json!(1u64 << 40), u32::MAX)] {
+            v["format_version"] = ver;
+            assert_eq!(Session::from_json(&v.to_string()), Err(SessionError::Version(want)));
+        }
+        // A field given twice is refused by name, the version too.
+        let twice = |key: &str| format(&format!(r#"{{"format_version":1,"{key}":"a","{key}":"b"}}"#));
+        assert!(twice("name").starts_with("duplicate field `name` at line 1 column "), "{}", twice("name"));
+        assert!(twice("format_version").starts_with("duplicate field `format_version` at line 1 column "), "{}", twice("format_version"));
+        // A newer version is refused even when the rest would not parse.
+        assert_eq!(Session::from_json(r#"{"format_version":7,"tracks":5}"#), Err(SessionError::Version(7)));
+        // An older or the current version loads as it did.
+        for ver in [0, 1] {
+            v["format_version"] = serde_json::json!(ver);
+            assert_eq!(Session::from_json(&v.to_string()).map(|s| s.format_version), Ok(ver));
+        }
+    }
+
+    #[test]
+    fn duplicate_ids_are_rejected_on_load() {
+        let mut s = Session::default();
+        s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        let mut v = serde_json::to_value(&s).unwrap();
+        v["tracks"][1]["id"] = v["tracks"][0]["id"].clone();
+        let err = Session::from_json(&v.to_string()).unwrap_err();
+        assert!(matches!(&err, SessionError::Invalid(m) if m.contains("duplicate track id")), "{err}");
+    }
+
+    #[test]
+    fn an_exhausted_id_space_is_rejected_on_load() {
+        let mut s = Session::default();
+        s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        let mut v = serde_json::to_value(&s).unwrap();
+        v["next_id"] = serde_json::json!(u64::MAX);
+        let err = Session::from_json(&v.to_string()).unwrap_err();
+        assert!(matches!(&err, SessionError::Invalid(m) if m.contains("exhausted")), "{err}");
+        // A maximal existing id is exhausted too, however `next_id` was written: every later
+        // allocation would return `u64::MAX` again.
+        let mut v = serde_json::to_value(&s).unwrap();
+        v["tracks"][0]["id"] = serde_json::json!(u64::MAX);
+        let err = Session::from_json(&v.to_string()).unwrap_err();
+        assert!(matches!(&err, SessionError::Invalid(m) if m.contains("exhausted")), "{err}");
+    }
+
+    #[test]
+    fn sanitize_repairs() {
+        let mut s = Session::default();
+        let t = s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        if let Some(tr) = s.track_mut(t) {
+            tr.active_playlist = 7;
+            tr.mixer.volume_db = f32::NAN;
+        }
+        s.next_id = 0;
+        s.sanitize();
+        let tr = s.track(t).unwrap();
+        assert_eq!(tr.active_playlist, 0);
+        assert_eq!(tr.mixer.volume_db, 0.0);
+        assert!(s.next_id > t.0);
+    }
+
+    #[test]
+    fn loaded_automation_is_clamped_to_its_range() {
+        // #884: a session file can carry points outside a lane's range; load clamps them.
+        let mut s = Session::default();
+        let t = s.add_track(TrackKind::Audio, ChannelFormat::Mono, None);
+        let tr = s.track_mut(t).unwrap();
+        for p in [crate::AutoParam::Volume, crate::AutoParam::SendLevel(0)] {
+            tr.lane_mut(&p).points.push(crate::AutomationPoint { at: 0, value: 500.0 });
+        }
+        let s = Session::from_json(&serde_json::to_string(&s).unwrap()).unwrap();
+        let tr = s.track(t).unwrap();
+        for p in [crate::AutoParam::Volume, crate::AutoParam::SendLevel(0)] {
+            assert_eq!(tr.lane(&p).unwrap().points[0].value, 12.0, "{p:?}");
+        }
+    }
+
+    #[test]
+    fn a_loaded_auto_name_scheme_leaves_room_for_its_number() {
+        let mut scheme = crate::AutoName { name: "n".repeat(300), suffix: "s".repeat(300), ..Default::default() };
+        scheme.sanitize();
+        assert_eq!(scheme.name.chars().count() + scheme.suffix.chars().count(), crate::AutoName::MAX_TEXT_CHARS);
+    }
+}
diff --git a/crates/scraft-format/src/source.rs b/crates/scraft-format/src/source.rs
new file mode 100644
index 000000000..7013d0031
--- /dev/null
+++ b/crates/scraft-format/src/source.rs
@@ -0,0 +1,204 @@
+//! Audio sources (files in the session's Audio Files folder) and their decoded data, and the
+//! movies video clips reference.
+
+use crate::SourceId;
+use craft_audio::{AudioBuffer, AudioInfo, CodecId, Container, peaks::Peaks};
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+/// The kind of file a source came from, as session files store it in [`Source::format`]. The
+/// variant names are part of the session format: craft-audio's `Container` and `CodecId` name
+/// more formats under other names, so this stays here and maps from them.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub enum FileFormat {
+    Wav,
+    Aiff,
+    Flac,
+    Mp3,
+    Ogg,
+    Aac,
+    Alac,
+    Caf,
+    /// Anything else that decodes: Matroska, WebM, raw AC-3.
+    Other,
+}
+
+impl FileFormat {
+    /// The kind of the file `info` describes.
+    pub fn of(info: &AudioInfo) -> FileFormat {
+        match info.container {
+            Container::Wav => FileFormat::Wav,
+            Container::Aiff => FileFormat::Aiff,
+            Container::Flac => FileFormat::Flac,
+            Container::MpegAudio => FileFormat::Mp3,
+            Container::Ogg => FileFormat::Ogg,
+            Container::Caf => FileFormat::Caf,
+            Container::Adts => FileFormat::Aac,
+            // MP4 and QuickTime hold many codecs: the codec names the kind.
+            Container::Mp4 | Container::QuickTime => match info.codec {
+                CodecId::Alac => FileFormat::Alac,
+                CodecId::Aac | CodecId::HeAac => FileFormat::Aac,
+                _ => FileFormat::Other,
+            },
+            _ => FileFormat::Other,
+        }
+    }
+}
+
+/// Metadata for an audio file used by the session (serialised).
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct Source {
+    pub id: SourceId,
+    pub name: String,
+    /// Path relative to the session folder (or absolute for referenced media).
+    pub path: String,
+    pub channels: u16,
+    pub frames: u64,
+    pub sample_rate: u32,
+    pub format: FileFormat,
+    /// Original BWF time stamp (samples), if any.
+    #[serde(default)]
+    pub time_reference: u64,
+    /// True when the file has not been written to disk yet (recorded/rendered this session).
+    #[serde(default)]
+    pub unsaved: bool,
+}
+
+/// A movie used by Video track clips (serialised). The pictures themselves are never stored in
+/// the session: the UI opens the movie from `path` and decodes frames on demand.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct VideoSource {
+    pub id: SourceId,
+    pub name: String,
+    /// Absolute path of the movie (referenced, never copied into the session folder).
+    pub path: String,
+    #[serde(default)]
+    pub width: u32,
+    #[serde(default)]
+    pub height: u32,
+    /// Frames per second (0 = unknown).
+    #[serde(default)]
+    pub frame_rate: f64,
+    /// Picture length in seconds.
+    #[serde(default)]
+    pub duration: f64,
+    /// Codec id (`h264`, `prores`, `mjpeg`, `hevc`, …).
+    #[serde(default)]
+    pub codec: String,
+    /// Why the movie is not opened, when its stored path was refused on opening the session.
+    #[serde(skip)]
+    pub offline: Option<String>,
+}
+
+impl VideoSource {
+    /// Display aspect ratio (width / height), 16:9 when unknown.
+    pub fn aspect(&self) -> f64 {
+        if self.width == 0 || self.height == 0 { 16.0 / 9.0 } else { f64::from(self.width) / f64::from(self.height) }
+    }
+}
+
+/// Decoded audio plus waveform overviews (not serialised).
+#[derive(Debug)]
+pub struct SourceAudio {
+    pub buffer: AudioBuffer,
+    pub peaks: Vec<Peaks>,
+}
+
+impl SourceAudio {
+    pub fn new(buffer: AudioBuffer) -> Self {
+        let peaks = buffer.channels.iter().map(|c| Peaks::build(c)).collect();
+        SourceAudio { buffer, peaks }
+    }
+    pub fn frames(&self) -> usize {
+        self.buffer.frames()
+    }
+    pub fn channel(&self, ch: usize) -> Option<&[f32]> {
+        self.buffer.channels.get(ch).map(Vec::as_slice)
+    }
+}
+
+/// Shared decoded audio, keyed by source id.
+#[derive(Debug, Clone, Default)]
+pub struct SourcePool {
+    map: BTreeMap<SourceId, Arc<SourceAudio>>,
+}
+
+impl SourcePool {
+    pub fn insert(&mut self, id: SourceId, audio: Arc<SourceAudio>) {
+        self.map.insert(id, audio);
+    }
+    pub fn get(&self, id: SourceId) -> Option<&Arc<SourceAudio>> {
+        self.map.get(&id)
+    }
+    pub fn remove(&mut self, id: SourceId) -> Option<Arc<SourceAudio>> {
+        self.map.remove(&id)
+    }
+    pub fn contains(&self, id: SourceId) -> bool {
+        self.map.contains_key(&id)
+    }
+    pub fn len(&self) -> usize {
+        self.map.len()
+    }
+    pub fn is_empty(&self) -> bool {
+        self.map.is_empty()
+    }
+    pub fn ids(&self) -> impl Iterator<Item = SourceId> + '_ {
+        self.map.keys().copied()
+    }
+}
+
+impl PartialEq for SourcePool {
+    fn eq(&self, other: &Self) -> bool {
+        self.map.len() == other.map.len() && self.map.iter().zip(other.map.iter()).all(|((a, x), (b, y))| a == b && Arc::ptr_eq(x, y))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::FileFormat;
+    use craft_audio::{AudioBuffer, EncodeFormat, EncodeOptions, encode, probe};
+
+    /// Sessions written before the format code moved to craft-audio name a source's format with
+    /// these words; they must keep reading, and new sessions must keep writing them.
+    #[test]
+    fn the_format_names_in_session_files_do_not_change() {
+        use FileFormat::{Aac, Aiff, Alac, Caf, Flac, Mp3, Ogg, Other, Wav};
+        let names = ["Wav", "Aiff", "Flac", "Mp3", "Ogg", "Aac", "Alac", "Caf", "Other"];
+        for (format, name) in [Wav, Aiff, Flac, Mp3, Ogg, Aac, Alac, Caf, Other].into_iter().zip(names) {
+            assert_eq!(serde_json::to_string(&format).unwrap(), format!("\"{name}\""));
+            assert_eq!(serde_json::from_str::<FileFormat>(&format!("\"{name}\"")).unwrap(), format);
+        }
+    }
+
+    /// An MP4 is AAC only when its audio is: Opus, AC-3 or PCM in MP4 is not.
+    #[test]
+    fn an_mp4_is_named_by_its_codec() {
+        let wav = encode(&AudioBuffer::new(48_000, 1, 480), &EncodeOptions::default()).unwrap();
+        let mut info = serde_json::to_value(probe(&wav, None).unwrap()).unwrap();
+        for (container, codec, format) in [
+            ("Mp4", "Aac", FileFormat::Aac),
+            ("Mp4", "HeAac", FileFormat::Aac),
+            ("QuickTime", "Alac", FileFormat::Alac),
+            ("Mp4", "Opus", FileFormat::Other),
+            ("Mp4", "Ac3", FileFormat::Other),
+            ("QuickTime", "Pcm", FileFormat::Other),
+            ("Adts", "Aac", FileFormat::Aac),
+        ] {
+            info["container"] = container.into();
+            info["codec"] = codec.into();
+            let info: craft_audio::AudioInfo = serde_json::from_value(info.clone()).unwrap();
+            assert_eq!(FileFormat::of(&info), format, "{codec} in {container}");
+        }
+    }
+
+    #[test]
+    fn a_probed_file_maps_to_its_format() {
+        let buf = AudioBuffer::new(48_000, 1, 480);
+        for (written, format) in
+            [(EncodeFormat::Wav, FileFormat::Wav), (EncodeFormat::Aiff, FileFormat::Aiff), (EncodeFormat::Flac, FileFormat::Flac)]
+        {
+            let info = probe(&encode(&buf, &EncodeOptions::new(written)).unwrap(), None).unwrap();
+            assert_eq!(FileFormat::of(&info), format);
+        }
+    }
+}
diff --git a/crates/scraft-format/src/track.rs b/crates/scraft-format/src/track.rs
new file mode 100644
index 000000000..d31bc5912
--- /dev/null
+++ b/crates/scraft-format/src/track.rs
@@ -0,0 +1,477 @@
+//! Tracks and playlists.
+
+use crate::soundcraft_time::{Range, Samples};
+use crate::{AutoParam, AutomationLane, ChannelFormat, Clip, ClipId, Mixer, TrackId};
+
+/// Track types (Track › New).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum TrackKind {
+    #[default]
+    Audio,
+    Aux,
+    Master,
+    Midi,
+    Instrument,
+    Vca,
+    Folder,
+    /// Picture: clips reference a movie ([`crate::VideoSource`]); no audio path.
+    Video,
+}
+
+impl TrackKind {
+    pub const ALL: [TrackKind; 8] = [
+        TrackKind::Audio,
+        TrackKind::Aux,
+        TrackKind::Master,
+        TrackKind::Midi,
+        TrackKind::Instrument,
+        TrackKind::Vca,
+        TrackKind::Folder,
+        TrackKind::Video,
+    ];
+    pub fn label(self) -> &'static str {
+        match self {
+            TrackKind::Audio => "Audio Track",
+            TrackKind::Aux => "Aux Input",
+            TrackKind::Master => "Master Fader",
+            TrackKind::Midi => "MIDI Track",
+            TrackKind::Instrument => "Instrument Track",
+            TrackKind::Vca => "VCA Master",
+            TrackKind::Folder => "Routing Folder Track",
+            TrackKind::Video => "Video Track",
+        }
+    }
+    pub fn default_name(self) -> &'static str {
+        match self {
+            TrackKind::Audio => "Audio",
+            TrackKind::Aux => "Aux",
+            TrackKind::Master => "Master",
+            TrackKind::Midi => "MIDI",
+            TrackKind::Instrument => "Inst",
+            TrackKind::Vca => "VCA",
+            TrackKind::Folder => "Folder",
+            TrackKind::Video => "Video",
+        }
+    }
+    pub fn id(self) -> &'static str {
+        match self {
+            TrackKind::Audio => "audio",
+            TrackKind::Aux => "aux",
+            TrackKind::Master => "master",
+            TrackKind::Midi => "midi",
+            TrackKind::Instrument => "instrument",
+            TrackKind::Vca => "vca",
+            TrackKind::Folder => "folder",
+            TrackKind::Video => "video",
+        }
+    }
+    pub fn from_id(s: &str) -> Option<TrackKind> {
+        let s = s.to_ascii_lowercase();
+        TrackKind::ALL.into_iter().find(|k| k.id() == s || k.label().eq_ignore_ascii_case(&s))
+    }
+    /// Track kinds that hold clips on a timeline.
+    pub fn has_playlist(self) -> bool {
+        matches!(self, TrackKind::Audio | TrackKind::Midi | TrackKind::Instrument | TrackKind::Video)
+    }
+    pub fn is_midi(self) -> bool {
+        matches!(self, TrackKind::Midi | TrackKind::Instrument)
+    }
+    /// Kinds that pass audio through the mixer.
+    pub fn is_audio_path(self) -> bool {
+        matches!(self, TrackKind::Audio | TrackKind::Aux | TrackKind::Master | TrackKind::Instrument | TrackKind::Folder)
+    }
+}
+
+/// Track heights (View › Track Height presets).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize)]
+pub enum TrackHeight {
+    /// Any height from Micro to Extreme, in points.
+    Custom(u16),
+    Micro,
+    Mini,
+    Small,
+    #[default]
+    Medium,
+    Large,
+    Jumbo,
+    Extreme,
+    /// Fit To Window: this many points.
+    Fit(u16),
+}
+
+/// A saved track height: `"Micro"` … `"Extreme"` (or `{"Micro": null}` …), `{"Custom": points}`,
+/// `{"Fit": points}`, or the bare `"Fit"` older sessions used. Read as it comes, never buffered (as an
+/// untagged enum would), so anything else in a session file is refused at its first token.
+impl<'de> serde::Deserialize<'de> for TrackHeight {
+    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+        d.deserialize_any(HeightVisitor)
+    }
+}
+
+const HEIGHT_VARIANTS: &[&str] = &["Custom", "Micro", "Mini", "Small", "Medium", "Large", "Jumbo", "Extreme", "Fit"];
+
+struct HeightVisitor;
+
+impl HeightVisitor {
+    /// The height a variant without a size names.
+    fn preset(name: &str) -> Option<TrackHeight> {
+        Some(match name {
+            "Micro" => TrackHeight::Micro,
+            "Mini" => TrackHeight::Mini,
+            "Small" => TrackHeight::Small,
+            "Medium" => TrackHeight::Medium,
+            "Large" => TrackHeight::Large,
+            "Jumbo" => TrackHeight::Jumbo,
+            "Extreme" => TrackHeight::Extreme,
+            _ => return None,
+        })
+    }
+}
+
+impl<'de> serde::de::Visitor<'de> for HeightVisitor {
+    type Value = TrackHeight;
+
+    fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+        f.write_str("a track height")
+    }
+
+    fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<TrackHeight, E> {
+        match v {
+            // Older sessions stored Fit with no size, drawn 88 points tall: the default Medium height.
+            "Fit" => Ok(TrackHeight::Medium),
+            "Custom" => Err(E::invalid_type(serde::de::Unexpected::UnitVariant, &"a height in points")),
+            other => Self::preset(other).ok_or_else(|| E::unknown_variant(other, HEIGHT_VARIANTS)),
+        }
+    }
+
+    fn visit_map<A: serde::de::MapAccess<'de>>(self, mut map: A) -> Result<TrackHeight, A::Error> {
+        use serde::de::Error as _;
+        let Some(key) = map.next_key::<String>()? else { return Err(A::Error::invalid_length(0, &"one variant")) };
+        let h = match key.as_str() {
+            "Custom" => TrackHeight::Custom(map.next_value()?),
+            // `{"Fit": null}` is the old size-less Fit too, as above.
+            "Fit" => map.next_value::<Option<u16>>()?.map_or(TrackHeight::Medium, TrackHeight::Fit),
+            other => {
+                let h = Self::preset(other).ok_or_else(|| A::Error::unknown_variant(other, HEIGHT_VARIANTS))?;
+                map.next_value::<()>()?;
+                h
+            }
+        };
+        if map.next_key::<serde::de::IgnoredAny>()?.is_some() {
+            return Err(A::Error::invalid_length(2, &"one variant"));
+        }
+        Ok(h)
+    }
+}
+
+impl TrackHeight {
+    pub const ALL: [TrackHeight; 7] = [
+        TrackHeight::Micro,
+        TrackHeight::Mini,
+        TrackHeight::Small,
+        TrackHeight::Medium,
+        TrackHeight::Large,
+        TrackHeight::Jumbo,
+        TrackHeight::Extreme,
+    ];
+    pub fn points(self) -> f32 {
+        match self {
+            TrackHeight::Custom(points) => f32::from(points).clamp(TrackHeight::Micro.points(), TrackHeight::Extreme.points()),
+            TrackHeight::Micro => 16.0,
+            TrackHeight::Mini => 24.0,
+            TrackHeight::Small => 46.0,
+            TrackHeight::Medium => 88.0,
+            TrackHeight::Large => 132.0,
+            TrackHeight::Jumbo => 220.0,
+            TrackHeight::Extreme => 440.0,
+            TrackHeight::Fit(points) => f32::from(points.max(16)),
+        }
+    }
+    pub fn label(self) -> &'static str {
+        match self {
+            TrackHeight::Custom(_) => "custom",
+            TrackHeight::Micro => "micro",
+            TrackHeight::Mini => "mini",
+            TrackHeight::Small => "small",
+            TrackHeight::Medium => "medium",
+            TrackHeight::Large => "large",
+            TrackHeight::Jumbo => "jumbo",
+            TrackHeight::Extreme => "extreme",
+            TrackHeight::Fit(_) => "fit to window",
+        }
+    }
+    pub fn from_id(s: &str) -> Option<TrackHeight> {
+        TrackHeight::ALL.into_iter().find(|h| h.label().eq_ignore_ascii_case(s))
+    }
+    /// The preset this many points tall, else a custom height clamped to Micro..Extreme.
+    pub fn from_points(points: f32) -> TrackHeight {
+        let p = points.max(TrackHeight::Micro.points()).min(TrackHeight::Extreme.points()).round() as u16;
+        TrackHeight::ALL.into_iter().find(|h| h.points() == f32::from(p)).unwrap_or(TrackHeight::Custom(p))
+    }
+    /// The next preset taller (or shorter) than this height; Extreme (or Micro) stays.
+    pub fn step(self, taller: bool) -> TrackHeight {
+        let p = self.points();
+        let next =
+            if taller { TrackHeight::ALL.into_iter().find(|h| h.points() > p) } else { TrackHeight::ALL.into_iter().rev().find(|h| h.points() < p) };
+        next.unwrap_or(self)
+    }
+}
+
+/// The default track colour palette (original, chosen for SoundCraft).
+pub const TRACK_COLORS: [[u8; 3]; 16] = [
+    [86, 132, 214],
+    [94, 170, 214],
+    [80, 190, 168],
+    [104, 186, 98],
+    [168, 196, 76],
+    [222, 196, 72],
+    [230, 152, 62],
+    [222, 104, 72],
+    [214, 82, 110],
+    [196, 86, 168],
+    [150, 98, 206],
+    [110, 104, 214],
+    [130, 150, 170],
+    [178, 140, 110],
+    [120, 170, 140],
+    [190, 120, 150],
+];
+
+/// A playlist: an alternative take of a track's clips.
+#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
+pub struct Playlist {
+    pub name: String,
+    /// Clips sorted by start; non-overlapping except at crossfades.
+    pub clips: Vec<Clip>,
+}
+
+impl Playlist {
+    pub fn new(name: impl Into<String>) -> Self {
+        Playlist { name: name.into(), clips: Vec::new() }
+    }
+    pub fn sort(&mut self) {
+        self.clips.sort_by_key(|c| (c.start, c.id.0));
+    }
+    pub fn clip(&self, id: ClipId) -> Option<&Clip> {
+        self.clips.iter().find(|c| c.id == id)
+    }
+    pub fn clip_mut(&mut self, id: ClipId) -> Option<&mut Clip> {
+        self.clips.iter_mut().find(|c| c.id == id)
+    }
+    pub fn clips_in(&self, r: Range) -> impl Iterator<Item = &Clip> {
+        self.clips.iter().filter(move |c| c.range().overlaps(&r))
+    }
+    pub fn clip_at(&self, at: Samples) -> Option<&Clip> {
+        self.clips.iter().rev().find(|c| c.range().contains(at))
+    }
+    pub fn end(&self) -> Samples {
+        self.clips.iter().map(Clip::end).max().unwrap_or(0)
+    }
+}
+
+/// A track.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct Track {
+    pub id: TrackId,
+    pub name: String,
+    pub kind: TrackKind,
+    pub format: ChannelFormat,
+    pub color: [u8; 3],
+    pub height: TrackHeight,
+    pub playlists: Vec<Playlist>,
+    pub active_playlist: usize,
+    pub mixer: Mixer,
+    pub automation: Vec<AutomationLane>,
+    /// Which lane the track shows: `waveform`/`blocks`/`notes`/`regions` or an automation param id.
+    pub view: String,
+    #[serde(default)]
+    pub hidden: bool,
+    #[serde(default)]
+    pub inactive: bool,
+    #[serde(default)]
+    pub frozen: bool,
+    #[serde(default)]
+    pub comments: String,
+    /// Folder that contains this track.
+    #[serde(default)]
+    pub folder: Option<TrackId>,
+    #[serde(default = "yes")]
+    pub folder_open: bool,
+    /// Instrument plugin (instrument tracks) — registry id.
+    #[serde(default)]
+    pub instrument: Option<crate::Insert>,
+    /// Ticks (musical) or samples timebase for clips.
+    #[serde(default)]
+    pub ticks_timebase: bool,
+    /// Elastic Audio algorithm, if enabled.
+    #[serde(default)]
+    pub elastic: Option<String>,
+    /// Pinned to top in the Edit window.
+    #[serde(default)]
+    pub pinned: bool,
+}
+
+fn yes() -> bool {
+    true
+}
+
+impl Track {
+    pub fn new(id: TrackId, name: impl Into<String>, kind: TrackKind, format: ChannelFormat, color: [u8; 3]) -> Self {
+        let name = name.into();
+        let format = if kind.is_midi() && kind == TrackKind::Midi { ChannelFormat::Mono } else { format };
+        let view = if kind.is_midi() {
+            "notes"
+        } else if kind.has_playlist() {
+            "waveform"
+        } else {
+            "volume"
+        };
+        Track {
+            id,
+            playlists: vec![Playlist::new(name.clone())],
+            name,
+            kind,
+            format,
+            color,
+            height: TrackHeight::Medium,
+            active_playlist: 0,
+            mixer: Mixer::new(format),
+            automation: Vec::new(),
+            view: view.into(),
+            hidden: false,
+            inactive: false,
+            frozen: false,
+            comments: String::new(),
+            folder: None,
+            folder_open: true,
+            instrument: None,
+            ticks_timebase: kind.is_midi(),
+            elastic: None,
+            pinned: false,
+        }
+    }
+
+    pub fn channels(&self) -> usize {
+        self.format.channels()
+    }
+
+    pub fn playlist(&self) -> Option<&Playlist> {
+        self.playlists.get(self.active_playlist)
+    }
+
+    pub fn playlist_mut(&mut self) -> Option<&mut Playlist> {
+        self.playlists.get_mut(self.active_playlist)
+    }
+
+    pub fn clips(&self) -> &[Clip] {
+        self.playlist().map_or(&[], |p| p.clips.as_slice())
+    }
+
+    pub fn lane(&self, p: &AutoParam) -> Option<&AutomationLane> {
+        self.automation.iter().find(|l| &l.param == p)
+    }
+
+    pub fn lane_mut(&mut self, p: &AutoParam) -> &mut AutomationLane {
+        let idx = match self.automation.iter().position(|l| &l.param == p) {
+            Some(i) => i,
+            None => {
+                self.automation.push(AutomationLane::new(p.clone()));
+                self.automation.len() - 1
+            }
+        };
+        let len = self.automation.len();
+        // `idx` is in range: it came from `position` or is the index of the element just pushed.
+        &mut self.automation[idx.min(len - 1)]
+    }
+
+    pub fn is_folder(&self) -> bool {
+        self.kind == TrackKind::Folder
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn legacy_fit_string_loads_as_default_height() {
+        assert_eq!(serde_json::from_str::<TrackHeight>("\"Fit\"").unwrap(), TrackHeight::Medium);
+        assert_eq!(serde_json::from_str::<TrackHeight>("{\"Fit\":120}").unwrap(), TrackHeight::Fit(120));
+        assert_eq!(serde_json::to_string(&TrackHeight::Fit(120)).unwrap(), "{\"Fit\":120}");
+        assert_eq!(serde_json::from_str::<TrackHeight>("\"Large\"").unwrap(), TrackHeight::Large);
+        assert_eq!(serde_json::from_str::<TrackHeight>("{\"Custom\":50}").unwrap(), TrackHeight::Custom(50));
+    }
+
+    #[test]
+    fn every_saved_height_form_loads_and_nothing_else() {
+        for h in TrackHeight::ALL.into_iter().chain([TrackHeight::Custom(50), TrackHeight::Fit(120)]) {
+            assert_eq!(serde_json::from_str::<TrackHeight>(&serde_json::to_string(&h).unwrap()).unwrap(), h);
+            assert_eq!(serde_json::from_value::<TrackHeight>(serde_json::to_value(h).unwrap()).unwrap(), h);
+        }
+        for h in TrackHeight::ALL {
+            let null = format!("{{{}:null}}", serde_json::to_string(&h).unwrap());
+            assert_eq!(serde_json::from_str::<TrackHeight>(&null).unwrap(), h, "{null}");
+        }
+        assert_eq!(serde_json::from_str::<TrackHeight>(r#"{"Fit":null}"#).unwrap(), TrackHeight::Medium);
+        assert!(serde_json::from_str::<TrackHeight>(r#"{"Custom":null}"#).is_err());
+        for bad in
+            [r#""Custom""#, r#""Huge""#, "7", "[]", "null", "{}", r#"{"Fit":"x"}"#, r#"{"Fit":70000}"#, r#"{"Large":1}"#, r#"{"Fit":1,"Fit":2}"#]
+        {
+            assert!(serde_json::from_str::<TrackHeight>(bad).is_err(), "{bad}");
+        }
+    }
+
+    #[test]
+    fn a_huge_height_is_refused_at_its_first_token() {
+        // #892: the height was read through an untagged enum, which buffers the whole value
+        // first; a session could hold a huge array there. It is refused where it starts.
+        for (open, rest) in [("[", "0,".repeat(100_000) + "0]"), (r#"{"Fit":["#, "0,".repeat(100_000) + "0]}")] {
+            let text = format!("{open}{rest}");
+            let err = serde_json::from_str::<TrackHeight>(&text).unwrap_err();
+            assert!(err.is_data() && err.line() == 1 && err.column() <= open.len() + 1, "{open}: {err}");
+        }
+    }
+
+    #[test]
+    fn new_track_defaults() {
+        let t = Track::new(TrackId(1), "Gtr", TrackKind::Audio, ChannelFormat::Stereo, TRACK_COLORS[0]);
+        assert_eq!(t.channels(), 2);
+        assert_eq!(t.view, "waveform");
+        assert_eq!(t.playlists.len(), 1);
+        let m = Track::new(TrackId(2), "Keys", TrackKind::Midi, ChannelFormat::Stereo, TRACK_COLORS[0]);
+        assert_eq!(m.format, ChannelFormat::Mono);
+        assert_eq!(m.view, "notes");
+    }
+
+    #[test]
+    fn lane_mut_creates_once() {
+        let mut t = Track::new(TrackId(1), "Gtr", TrackKind::Audio, ChannelFormat::Mono, TRACK_COLORS[0]);
+        t.lane_mut(&AutoParam::Volume).set_point(0, -3.0);
+        t.lane_mut(&AutoParam::Volume).set_point(10, -6.0);
+        assert_eq!(t.automation.len(), 1);
+        assert_eq!(t.lane(&AutoParam::Volume).map(|l| l.points.len()), Some(2));
+    }
+
+    #[test]
+    fn kind_ids() {
+        for k in TrackKind::ALL {
+            assert_eq!(TrackKind::from_id(k.id()), Some(k));
+        }
+    }
+
+    #[test]
+    fn custom_heights_round_to_presets_and_step_through_them() {
+        assert_eq!(TrackHeight::from_points(88.0), TrackHeight::Medium);
+        assert_eq!(TrackHeight::from_points(57.4), TrackHeight::Custom(57));
+        assert_eq!(TrackHeight::from_points(9999.0), TrackHeight::Extreme);
+        assert_eq!(TrackHeight::from_points(f32::NAN), TrackHeight::Micro);
+        assert_eq!(TrackHeight::Custom(u16::MAX).points(), 440.0);
+        assert_eq!(TrackHeight::Custom(57).step(true), TrackHeight::Medium);
+        assert_eq!(TrackHeight::Custom(57).step(false), TrackHeight::Small);
+        assert_eq!(TrackHeight::Extreme.step(true), TrackHeight::Extreme);
+        assert_eq!(TrackHeight::Micro.step(false), TrackHeight::Micro);
+        let json = serde_json::to_string(&TrackHeight::Custom(57)).unwrap();
+        assert_eq!(serde_json::from_str::<TrackHeight>(&json).unwrap(), TrackHeight::Custom(57));
+        assert_eq!(serde_json::from_str::<TrackHeight>("\"Large\"").unwrap(), TrackHeight::Large);
+    }
+}
diff --git a/crates/stencilcraft-document/Cargo.toml b/crates/stencilcraft-document/Cargo.toml
new file mode 100644
index 000000000..6d5ff6b25
--- /dev/null
+++ b/crates/stencilcraft-document/Cargo.toml
@@ -0,0 +1,20 @@
+[package]
+name = "craft-stencilcraft-document"
+description = "StencilCraft document model, validation, geometry, and native file codec"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+craft-atomic = { workspace = true }
+craft-stencilcraft-format = { workspace = true }
+craft-svg = { workspace = true }
+kurbo = { workspace = true, features = ["serde"] }
+serde = { workspace = true, features = ["rc"] }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
diff --git a/crates/stencilcraft-document/README.md b/crates/stencilcraft-document/README.md
new file mode 100644
index 000000000..d286c5789
--- /dev/null
+++ b/crates/stencilcraft-document/README.md
@@ -0,0 +1,9 @@
+# craft-stencilcraft-document
+
+Shared StencilCraft document model, validation, geometry helpers, and native file codec.
+Applications re-export these model types rather than defining a second set of serializable
+document types. The `.stencilcraft` header and typed wire schema are provided by
+`craft-stencilcraft-format`.
+
+The crate's `Document::load_json` and `Document::save_json` APIs read and write the versioned
+native format. File path I/O helpers preserve application paths in errors and use atomic writes.
diff --git a/crates/stencilcraft-document/src/canvas.rs b/crates/stencilcraft-document/src/canvas.rs
new file mode 100644
index 000000000..69878cb5e
--- /dev/null
+++ b/crates/stencilcraft-document/src/canvas.rs
@@ -0,0 +1,580 @@
+//! Canvas model beyond shapes: pages (artboards), page presets, ruler guides, grid and
+//! snap settings, document metadata and groups. Everything here is plain data stored in
+//! the `.stencilcraft` file; behaviour lives in the engine.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde::{Deserialize, Serialize};
+
+use crate::{Board, DocError, Document, Shape};
+
+/// Most pages a document may hold (the main board included).
+pub const MAX_PAGES: usize = 100;
+/// Most ruler guides a document may hold.
+pub const MAX_GUIDES: usize = 1000;
+/// Most groups a document may hold.
+pub const MAX_GROUPS: usize = 100_000;
+/// Deepest group nesting accepted.
+pub const MAX_GROUP_DEPTH: usize = 64;
+/// Longest title, page/layer/group name, colour or mat label, in bytes.
+pub const MAX_NAME_BYTES: usize = 1024;
+/// Longest notes text, in bytes.
+pub const MAX_NOTES_BYTES: usize = 64 * 1024;
+/// Largest stored thumbnail, in bytes.
+pub const MAX_THUMBNAIL_BYTES: usize = 256 * 1024;
+
+const INCH_MM: f64 = 25.4;
+
+/// Labels that describe a page beyond its size: the mat it sits on, the media loaded and
+/// the page colour shown on the canvas. All optional; empty means "not set".
+#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
+pub struct PageSetup {
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub name: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mat: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub media: Option<String>,
+    /// Page colour, `#rrggbb`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub color: Option<String>,
+    /// Cut mirrored (heat-transfer material is cut face down).
+    #[serde(default, skip_serializing_if = "crate::is_false")]
+    pub mirror: bool,
+    /// The page is printed with registration marks for Print & Cut.
+    #[serde(default, skip_serializing_if = "crate::is_false")]
+    pub registration_marks: bool,
+}
+
+impl PageSetup {
+    pub fn is_empty(&self) -> bool {
+        self == &PageSetup::default()
+    }
+}
+
+/// An extra page (artboard) placed on the document plane. The main board is page 0 at the
+/// origin; extra pages sit beside it, and a shape belongs to the page under its centre.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Page {
+    pub x_mm: f64,
+    pub y_mm: f64,
+    pub width_mm: f64,
+    pub height_mm: f64,
+    #[serde(flatten)]
+    pub setup: PageSetup,
+}
+
+impl Page {
+    pub fn rect(&self) -> kurbo::Rect {
+        kurbo::Rect::new(self.x_mm, self.y_mm, self.x_mm + self.width_mm, self.y_mm + self.height_mm)
+    }
+}
+
+/// Common page and mat sizes. Sizes are portrait (width ≤ height); see [`Orientation`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PagePreset {
+    #[serde(rename = "letter")]
+    Letter,
+    #[serde(rename = "a4")]
+    A4,
+    #[serde(rename = "mat-12x12")]
+    Mat12x12,
+    #[serde(rename = "mat-12x24")]
+    Mat12x24,
+    #[serde(rename = "joy-mat-4.5x6.5")]
+    JoyMat4_5x6_5,
+    #[serde(rename = "joy-mat-4.5x12")]
+    JoyMat4_5x12,
+    #[serde(rename = "joy-xtra-mat-8.5x12")]
+    JoyXtraMat8_5x12,
+    /// Width and height are given explicitly.
+    #[serde(rename = "custom")]
+    Custom,
+}
+
+impl PagePreset {
+    /// Portrait size in millimetres; `None` for `Custom`.
+    pub fn size_mm(self) -> Option<(f64, f64)> {
+        let inches = |w: f64, h: f64| Some((w * INCH_MM, h * INCH_MM));
+        match self {
+            PagePreset::Letter => inches(8.5, 11.0),
+            PagePreset::A4 => Some((210.0, 297.0)),
+            PagePreset::Mat12x12 => inches(12.0, 12.0),
+            PagePreset::Mat12x24 => inches(12.0, 24.0),
+            PagePreset::JoyMat4_5x6_5 => inches(4.5, 6.5),
+            PagePreset::JoyMat4_5x12 => inches(4.5, 12.0),
+            PagePreset::JoyXtraMat8_5x12 => inches(8.5, 12.0),
+            PagePreset::Custom => None,
+        }
+    }
+
+    /// The mat label a mat preset implies (`None` for paper sizes and custom).
+    pub fn mat_label(self) -> Option<&'static str> {
+        match self {
+            PagePreset::Mat12x12 => Some("12x12"),
+            PagePreset::Mat12x24 => Some("12x24"),
+            PagePreset::JoyMat4_5x6_5 => Some("joy-4.5x6.5"),
+            PagePreset::JoyMat4_5x12 => Some("joy-4.5x12"),
+            PagePreset::JoyXtraMat8_5x12 => Some("joy-xtra-8.5x12"),
+            _ => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Orientation {
+    Portrait,
+    Landscape,
+}
+
+impl Orientation {
+    /// `(w, h)` ordered for this orientation.
+    pub fn apply(self, (w, h): (f64, f64)) -> (f64, f64) {
+        let (short, long) = if w <= h { (w, h) } else { (h, w) };
+        match self {
+            Orientation::Portrait => (short, long),
+            Orientation::Landscape => (long, short),
+        }
+    }
+}
+
+/// Which way a ruler guide runs. A horizontal guide is the line `y = position`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GuideAxis {
+    Horizontal,
+    Vertical,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Guide {
+    pub axis: GuideAxis,
+    pub position_mm: f64,
+    #[serde(default, skip_serializing_if = "crate::is_false")]
+    pub locked: bool,
+}
+
+/// The background grid: major lines every `spacing_mm`, split into `subdivisions`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Grid {
+    pub spacing_mm: f64,
+    pub subdivisions: u32,
+    #[serde(default)]
+    pub visible: bool,
+}
+
+impl Default for Grid {
+    fn default() -> Self {
+        Self { spacing_mm: 10.0, subdivisions: 1, visible: false }
+    }
+}
+
+impl Grid {
+    /// Distance between snap lines: spacing over subdivisions.
+    pub fn step_mm(&self) -> f64 {
+        self.spacing_mm / f64::from(self.subdivisions.max(1))
+    }
+}
+
+/// Which targets the snapping service considers, and how close counts.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct SnapSettings {
+    #[serde(default)]
+    pub grid: bool,
+    #[serde(default = "crate::yes")]
+    pub guides: bool,
+    /// Edges and centres of other shapes and of pages.
+    #[serde(default = "crate::yes")]
+    pub objects: bool,
+    /// Smart guides: equal spacing between neighbours.
+    #[serde(default = "crate::yes")]
+    pub spacing: bool,
+    /// Snap to point: shapes' anchor points (Illustrator's View › Snap to Point).
+    #[serde(default)]
+    pub points: bool,
+    #[serde(default = "default_tolerance")]
+    pub tolerance_mm: f64,
+}
+
+fn default_tolerance() -> f64 {
+    2.0
+}
+
+impl Default for SnapSettings {
+    fn default() -> Self {
+        Self { grid: false, guides: true, objects: true, spacing: true, points: false, tolerance_mm: default_tolerance() }
+    }
+}
+
+/// Title, notes and a small preview, stored in the file for file browsers and recovery.
+#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
+pub struct Metadata {
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub title: String,
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub notes: String,
+    /// A small standalone SVG of the design (see `Document::render_thumbnail`).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub thumbnail_svg: Option<String>,
+}
+
+impl Metadata {
+    pub fn is_empty(&self) -> bool {
+        self == &Metadata::default()
+    }
+}
+
+/// A member of a group: a shape or another group.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GroupChild {
+    Shape(u64),
+    Group(u64),
+}
+
+/// Shapes and groups that move and select together. Grouping never changes how shapes
+/// cut, nor their stacking order, which stays with their layers.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Group {
+    pub id: u64,
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub name: String,
+    pub children: Vec<GroupChild>,
+}
+
+/// `#rrggbb` (or `#rgb`) to RGB; `None` for anything else.
+pub fn parse_hex_color(text: &str) -> Option<[u8; 3]> {
+    let hex = text.strip_prefix('#')?;
+    let digit = |i: usize| u8::from_str_radix(hex.get(i..i + 1)?, 16).ok();
+    match hex.len() {
+        6 => {
+            let byte = |i: usize| u8::from_str_radix(hex.get(i..i + 2)?, 16).ok();
+            Some([byte(0)?, byte(2)?, byte(4)?])
+        }
+        3 => Some([digit(0)? * 17, digit(1)? * 17, digit(2)? * 17]),
+        _ => None,
+    }
+}
+
+/// Canonical lowercase `#rrggbb`.
+pub fn format_hex_color([r, g, b]: [u8; 3]) -> String {
+    format!("#{r:02x}{g:02x}{b:02x}")
+}
+
+/// Euclidean RGB distance (0 to about 441.7).
+pub fn color_distance(a: [u8; 3], b: [u8; 3]) -> f64 {
+    a.iter().zip(b).map(|(x, y)| (f64::from(*x) - f64::from(y)).powi(2)).sum::<f64>().sqrt()
+}
+
+fn check_name(text: &str, what: &str) -> Result<(), DocError> {
+    if text.len() > MAX_NAME_BYTES {
+        return Err(DocError::Model(format!("{what}: longer than {MAX_NAME_BYTES} bytes")));
+    }
+    Ok(())
+}
+
+fn check_color(color: Option<&str>, what: &str) -> Result<(), DocError> {
+    match color {
+        Some(c) if parse_hex_color(c).is_none() => {
+            Err(DocError::Model(format!("{what}: `{}` is not a #rrggbb colour", c.chars().take(16).collect::<String>())))
+        }
+        _ => Ok(()),
+    }
+}
+
+fn check_setup(setup: &PageSetup, what: &str) -> Result<(), DocError> {
+    check_name(&setup.name, what)?;
+    for label in [&setup.mat, &setup.media].into_iter().flatten() {
+        check_name(label, what)?;
+    }
+    check_color(setup.color.as_deref(), what)
+}
+
+impl Document {
+    /// Pages, guides, grid, snapping, colours, metadata and groups: finite, within caps,
+    /// and groups form a forest (unknown shape members are allowed: they are pruned).
+    pub(crate) fn validate_canvas(&self) -> Result<(), DocError> {
+        let bad = |message: String| Err(DocError::Model(message));
+        if self.pages.len() >= MAX_PAGES {
+            return bad(format!("pages: more than {MAX_PAGES}"));
+        }
+        check_setup(&self.board_setup, "board")?;
+        for (i, page) in self.pages.iter().enumerate() {
+            let finite = [page.x_mm, page.y_mm, page.width_mm, page.height_mm].iter().all(|v| v.is_finite() && v.abs() < 1e7);
+            if !finite || page.width_mm <= 0.0 || page.height_mm <= 0.0 {
+                return bad(format!("page {}: position and size must be finite, size positive", i + 1));
+            }
+            check_setup(&page.setup, "page")?;
+        }
+        if self.guides.len() > MAX_GUIDES {
+            return bad(format!("guides: more than {MAX_GUIDES}"));
+        }
+        if self.guides.iter().any(|g| !g.position_mm.is_finite()) {
+            return bad("guides: positions must be finite".to_string());
+        }
+        if !(self.grid.spacing_mm.is_finite() && (0.01..=10_000.0).contains(&self.grid.spacing_mm) && (1..=100).contains(&self.grid.subdivisions)) {
+            return bad("grid: spacing must be 0.01-10000 mm, subdivisions 1-100".to_string());
+        }
+        if !(0.0..=1000.0).contains(&self.snap.tolerance_mm) {
+            return bad("snap: tolerance must be 0-1000 mm".to_string());
+        }
+        for layer in &self.layers {
+            check_name(&layer.name, "layer name")?;
+            check_color(layer.color.as_deref(), "layer colour")?;
+        }
+        check_name(&self.meta.title, "title")?;
+        if self.meta.notes.len() > MAX_NOTES_BYTES {
+            return bad(format!("notes: longer than {MAX_NOTES_BYTES} bytes"));
+        }
+        if self.meta.thumbnail_svg.as_ref().is_some_and(|t| t.len() > MAX_THUMBNAIL_BYTES) {
+            return bad(format!("thumbnail: larger than {MAX_THUMBNAIL_BYTES} bytes"));
+        }
+        self.validate_groups()
+    }
+
+    fn validate_groups(&self) -> Result<(), DocError> {
+        let bad = |message: String| Err(DocError::Model(message));
+        if self.groups.len() > MAX_GROUPS {
+            return bad(format!("groups: more than {MAX_GROUPS}"));
+        }
+        let ids: BTreeSet<u64> = self.groups.iter().map(|g| g.id).collect();
+        if ids.len() != self.groups.len() {
+            return bad("groups: ids must be unique".to_string());
+        }
+        let mut parents: BTreeMap<GroupChild, u64> = BTreeMap::new();
+        for group in &self.groups {
+            check_name(&group.name, "group name")?;
+            for child in &group.children {
+                if let GroupChild::Group(id) = child
+                    && !ids.contains(id)
+                {
+                    return bad(format!("group {}: member group {id} does not exist", group.id));
+                }
+                if parents.insert(*child, group.id).is_some() {
+                    return bad(format!("groups: {child:?} belongs to two groups"));
+                }
+            }
+        }
+        // With one parent each, a cycle is a walk up that never reaches a root.
+        for id in &ids {
+            let mut current = GroupChild::Group(*id);
+            let mut depth = 0;
+            while let Some(parent) = parents.get(&current) {
+                depth += 1;
+                if depth > MAX_GROUP_DEPTH {
+                    return bad(format!("groups: nesting deeper than {MAX_GROUP_DEPTH}, or a cycle, at group {id}"));
+                }
+                current = GroupChild::Group(*parent);
+            }
+        }
+        Ok(())
+    }
+
+    /// Whether shape `id` may not be edited: the shape or its layer is locked.
+    pub fn shape_locked(&self, id: u64) -> bool {
+        self.layers.iter().any(|layer| layer.shapes.iter().any(|s| s.id == id && (s.locked || layer.locked)))
+    }
+
+    /// Index of the layer holding shape `id`.
+    pub fn layer_of_shape(&self, id: u64) -> Option<usize> {
+        self.layers.iter().position(|layer| layer.shapes.iter().any(|s| s.id == id))
+    }
+
+    pub fn group(&self, id: u64) -> Option<&Group> {
+        self.groups.iter().find(|g| g.id == id)
+    }
+
+    /// The group directly holding `child`.
+    pub fn group_parent(&self, child: GroupChild) -> Option<u64> {
+        self.groups.iter().find(|g| g.children.contains(&child)).map(|g| g.id)
+    }
+
+    /// Each group member's direct parent group; build once for many [`group_chain_in`] calls.
+    pub fn group_parent_map(&self) -> BTreeMap<GroupChild, u64> {
+        self.groups.iter().flat_map(|g| g.children.iter().map(move |c| (*c, g.id))).collect()
+    }
+
+    /// Groups holding `child`, outermost first.
+    pub fn group_chain(&self, child: GroupChild) -> Vec<u64> {
+        group_chain_in(&self.group_parent_map(), child)
+    }
+
+    /// Every existing shape inside group `id`, nested groups included, in document order.
+    pub fn group_shapes(&self, id: u64) -> Vec<u64> {
+        let mut members = BTreeSet::new();
+        let mut seen = BTreeSet::new();
+        let mut stack = vec![id];
+        while let Some(gid) = stack.pop() {
+            if !seen.insert(gid) {
+                continue;
+            }
+            for child in self.group(gid).map_or(&[][..], |g| &g.children) {
+                match child {
+                    GroupChild::Shape(s) => {
+                        members.insert(*s);
+                    }
+                    GroupChild::Group(g) => stack.push(*g),
+                }
+            }
+        }
+        self.shapes().map(|(_, s)| s.id).filter(|s| members.contains(s)).collect()
+    }
+
+    /// The groups without members that no longer exist; groups left empty go too.
+    pub fn pruned_groups(&self) -> Vec<Group> {
+        let shapes: BTreeSet<u64> = self.shapes().map(|(_, s)| s.id).collect();
+        let mut groups = self.groups.clone();
+        loop {
+            let before: usize = groups.iter().map(|g| g.children.len() + 1).sum();
+            let live: BTreeSet<u64> = groups.iter().map(|g| g.id).collect();
+            for group in &mut groups {
+                group.children.retain(|child| match child {
+                    GroupChild::Shape(id) => shapes.contains(id),
+                    GroupChild::Group(id) => live.contains(id),
+                });
+            }
+            groups.retain(|g| !g.children.is_empty());
+            let after: usize = groups.iter().map(|g| g.children.len() + 1).sum();
+            if after == before {
+                return groups;
+            }
+        }
+    }
+
+    /// A free group id.
+    pub fn next_group_id(&self) -> u64 {
+        self.groups.iter().map(|g| g.id).max().map_or(1, |m| m.saturating_add(1))
+    }
+
+    /// All pages: the main board (index 0, at the origin) then the extra pages.
+    pub fn all_pages(&self) -> Vec<Page> {
+        let mut pages =
+            vec![Page { x_mm: 0.0, y_mm: 0.0, width_mm: self.board.width_mm, height_mm: self.board.height_mm, setup: self.board_setup.clone() }];
+        pages.extend(self.pages.iter().cloned());
+        pages
+    }
+
+    /// The page a shape belongs to: the first extra page under its bounds centre, else 0.
+    pub fn page_of_shape(&self, shape: &Shape) -> usize {
+        let Some(center) = shape.bounds().map(|b| b.center()) else {
+            return 0;
+        };
+        self.pages.iter().position(|p| p.rect().contains(center)).map_or(0, |i| i + 1)
+    }
+
+    /// One page as its own document, ready to export or cut: the board is the page, and
+    /// the shapes on that page are moved to its origin. `None` for an unknown page.
+    pub fn page_document(&self, index: usize) -> Option<Document> {
+        let page = self.all_pages().get(index)?.clone();
+        let mut out = self.clone();
+        out.board = Board { width_mm: page.width_mm, height_mm: page.height_mm };
+        out.board_setup = page.setup.clone();
+        out.pages.clear();
+        out.guides.clear();
+        let shift = kurbo::Affine::translate((-page.x_mm, -page.y_mm));
+        for layer in &mut out.layers {
+            layer.shapes.retain(|s| self.page_of_shape(s) == index);
+            for shape in &mut layer.shapes {
+                shape.path.apply_affine(shift);
+            }
+        }
+        out.groups = out.pruned_groups();
+        Some(out)
+    }
+
+    /// A small standalone SVG preview of the board's output shapes, at most `max_bytes`
+    /// long: shapes past the budget are left out. Coordinates keep two decimals.
+    pub fn render_thumbnail(&self, max_bytes: usize) -> String {
+        let (w, h) = (self.board.width_mm, self.board.height_mm);
+        // Documents are y-up; flip into SVG's y-down space. The shared SVG writer owns markup,
+        // escaping, numeric formatting, and path-data formatting.
+        let mut svg = thumbnail_writer(w, h);
+        let mut empty = svg.clone();
+        empty.line(1);
+        empty.close();
+        empty.line(0);
+        empty.close();
+        let empty_len = empty.finish().len();
+        if empty_len > max_bytes {
+            return String::new();
+        }
+        let mut remaining = max_bytes - empty_len;
+        'layers: for layer in self.layers.iter().filter(|l| l.is_output()) {
+            for shape in layer.shapes.iter().filter(|s| !s.hidden) {
+                let mut element = craft_svg::write::SvgWriter::fragment();
+                element.line(2);
+                element.tag("path").attr("d", craft_svg::write::path_data_fixed(&shape.path, 2)).empty();
+                let element = element.finish();
+                if element.len() > remaining {
+                    break 'layers;
+                }
+                remaining -= element.len();
+                svg.raw(&element);
+            }
+        }
+        svg.line(1);
+        svg.close();
+        svg.line(0);
+        svg.close();
+        svg.finish()
+    }
+}
+
+fn thumbnail_writer(width_mm: f64, height_mm: f64) -> craft_svg::write::SvgWriter {
+    use craft_svg::write::{SvgWriter, num};
+
+    let mut writer = SvgWriter::fragment();
+    writer.root().attr("viewBox", format!("0 0 {} {}", num(width_mm, 2), num(height_mm, 2))).open();
+    writer
+        .tag("g")
+        .attr("transform", format!("matrix(1 0 0 -1 0 {})", num(height_mm, 2)))
+        .attr("fill", "none")
+        .attr("stroke", "#000")
+        .attr("stroke-width", num((width_mm.max(height_mm) / 200.0).max(0.01), 2))
+        .open();
+    writer
+}
+
+/// Groups holding `child` according to `parents` ([`Document::group_parent_map`]),
+/// outermost first. Stops at a cycle or past the depth cap.
+pub fn group_chain_in(parents: &BTreeMap<GroupChild, u64>, child: GroupChild) -> Vec<u64> {
+    let mut chain = Vec::new();
+    let mut current = child;
+    while let Some(parent) = parents.get(&current) {
+        if chain.contains(parent) || chain.len() > MAX_GROUP_DEPTH {
+            break;
+        }
+        chain.push(*parent);
+        current = GroupChild::Group(*parent);
+    }
+    chain.reverse();
+    chain
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn presets_and_orientation() {
+        let (w, h) = PagePreset::Letter.size_mm().unwrap();
+        assert!((w - 215.9).abs() < 1e-9 && (h - 279.4).abs() < 1e-9);
+        assert_eq!(Orientation::Landscape.apply((210.0, 297.0)), (297.0, 210.0));
+        assert_eq!(Orientation::Portrait.apply((297.0, 210.0)), (210.0, 297.0));
+        assert!(PagePreset::Custom.size_mm().is_none());
+        let json = serde_json::to_string(&PagePreset::JoyMat4_5x6_5).unwrap();
+        assert_eq!(json, "\"joy-mat-4.5x6.5\"");
+    }
+
+    #[test]
+    fn hex_colors() {
+        assert_eq!(parse_hex_color("#FF0080"), Some([255, 0, 128]));
+        assert_eq!(parse_hex_color("#f08"), Some([255, 0, 136]));
+        assert_eq!(parse_hex_color("ff0080"), None);
+        assert_eq!(parse_hex_color("#ff00"), None);
+        assert_eq!(parse_hex_color("#é0000"), None);
+        assert_eq!(format_hex_color([1, 2, 255]), "#0102ff");
+        assert!(color_distance([0, 0, 0], [3, 4, 0]) - 5.0 < 1e-9);
+    }
+}
diff --git a/crates/stencilcraft-document/src/geom.rs b/crates/stencilcraft-document/src/geom.rs
new file mode 100644
index 000000000..e569afeec
--- /dev/null
+++ b/crates/stencilcraft-document/src/geom.rs
@@ -0,0 +1,305 @@
+//! Geometry primitives for StencilCraft: kurbo re-exports, millimetre helpers,
+//! path flattening.
+//!
+//! The bottom layer of the workspace (L1 in `docs/architecture.md`): nothing here
+//! depends on the document model, kerf, exports or the engine. All coordinates are
+//! millimetres; coordinate-axis orientation is defined at each format boundary.
+
+pub use kurbo::{Affine, BezPath, Circle, CubicBez, Ellipse, Line, ParamCurve, Point, QuadBez, Rect, Shape, Vec2};
+
+#[derive(Debug, thiserror::Error)]
+#[error("geometry: {0}")]
+pub struct GeomError(String);
+
+pub type Result<T> = std::result::Result<T, GeomError>;
+
+/// The smallest length that can meaningfully exist on an artboard; below this a
+/// value is treated as zero. Values above this but non-finite are always an error.
+pub const MM_EPSILON: f64 = 1e-9;
+
+/// Millimetres per inch: the one inch/mm conversion factor (inch-based mats and page sizes).
+pub const MM_PER_INCH: f64 = 25.4;
+
+/// Converts inches at an input boundary to document millimetres.
+pub const fn inches_to_mm(inches: f64) -> f64 {
+    inches * MM_PER_INCH
+}
+
+/// Converts document millimetres to inches at a display boundary.
+pub const fn mm_to_inches(mm: f64) -> f64 {
+    mm / MM_PER_INCH
+}
+
+/// Map an artboard's downward-growing Y coordinate to a Cartesian Y coordinate.
+///
+/// The board's top is `height_mm` and its bottom is zero in the resulting space.
+/// Values outside the board remain outside; non-finite inputs or results are rejected.
+pub fn artboard_y_to_cartesian(y_mm: f64, height_mm: f64) -> Result<f64> {
+    check_finite_mm(y_mm, "artboard y")?;
+    check_finite_mm(height_mm, "artboard height")?;
+    check_finite_mm(height_mm - y_mm, "cartesian y")
+}
+
+/// Rejects a non-finite millimetre length before it can poison a document.
+pub fn check_finite_mm(value: f64, what: &'static str) -> Result<f64> {
+    if !value.is_finite() {
+        return Err(GeomError(format!("{what}: not a finite length")));
+    }
+    let _ = MM_EPSILON;
+    Ok(value)
+}
+
+/// A flattened subpath: the raw points of a contour, plus whether the source path
+/// closed it. Used by kerf (offsetting) and every polyline-based exporter.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Polyline {
+    pub points: Vec<Point>,
+    pub closed: bool,
+}
+
+impl Polyline {
+    pub fn from_path(path: &BezPath) -> Vec<Polyline> {
+        path_to_polylines(path, DEFAULT_FLATTEN_STEPS)
+    }
+}
+
+/// Flattening resolution: samples per Bézier segment. 32 steps at artboard scale
+/// keeps chord error far below a typical kerf width.
+pub const DEFAULT_FLATTEN_STEPS: usize = 32;
+
+/// Convert a path into polylines by sampling Bézier segments (`steps` samples per
+/// segment). Closed subpaths produce `closed: true` polylines that do not repeat
+/// the start point.
+pub fn path_to_polylines(path: &BezPath, steps: usize) -> Vec<Polyline> {
+    let steps = steps.max(2);
+    let mut out: Vec<Polyline> = Vec::new();
+    let mut current: Option<Polyline> = None;
+    let mut start = Point::ZERO;
+    let mut cursor = Point::ZERO;
+
+    for elem in path.elements() {
+        match *elem {
+            kurbo::PathEl::MoveTo(p) => {
+                if let Some(done) = current.take() {
+                    out.push(done);
+                }
+                start = p;
+                cursor = p;
+                current = Some(Polyline { points: vec![p], closed: false });
+            }
+            kurbo::PathEl::LineTo(p) => {
+                if let Some(pl) = current.as_mut() {
+                    pl.points.push(p);
+                }
+                cursor = p;
+            }
+            kurbo::PathEl::ClosePath => {
+                if let Some(pl) = current.as_mut() {
+                    pl.closed = true;
+                }
+                cursor = start;
+            }
+            kurbo::PathEl::QuadTo(c, p) => {
+                if let Some(pl) = current.as_mut() {
+                    let quad = QuadBez::new(cursor, c, p);
+                    for i in 1..steps {
+                        let t = i as f64 / steps as f64;
+                        pl.points.push(quad.eval(t));
+                    }
+                }
+                cursor = p;
+            }
+            kurbo::PathEl::CurveTo(c1, c2, p) => {
+                if let Some(pl) = current.as_mut() {
+                    let cubic = CubicBez::new(cursor, c1, c2, p);
+                    for i in 1..steps {
+                        let t = i as f64 / steps as f64;
+                        pl.points.push(cubic.eval(t));
+                    }
+                }
+                cursor = p;
+            }
+        }
+    }
+    if let Some(done) = current.take() {
+        out.push(done);
+    }
+    out
+}
+
+/// Signed area of a closed polyline (shoelace): positive when wound
+/// counter-clockwise with y up. An open polyline contributes 0.
+pub fn signed_area(points: &[Point]) -> f64 {
+    if points.len() < 3 {
+        return 0.0;
+    }
+    let mut sum = 0.0;
+    for i in 0..points.len() {
+        let a = points[i];
+        let b = points[(i + 1) % points.len()];
+        sum += a.x * b.y - b.x * a.y;
+    }
+    sum / 2.0
+}
+
+/// Bounds of a set of points, or `None` when empty.
+pub fn bounds_of_points(points: &[Point]) -> Option<Rect> {
+    let mut it = points.iter();
+    let first = *it.next()?;
+    let mut acc = Rect::from_points(first, first);
+    for p in it {
+        acc = acc.union(Rect::from_points(*p, *p));
+    }
+    Some(acc)
+}
+
+/// Axis-aligned bounds of every point of every polyline.
+pub fn bounds_of_polylines(lines: &[Polyline]) -> Option<Rect> {
+    let mut acc: Option<Rect> = None;
+    for pl in lines {
+        if let Some(r) = bounds_of_points(&pl.points) {
+            acc = Some(match acc {
+                Some(prev) => prev.union(r),
+                None => r,
+            });
+        }
+    }
+    acc
+}
+
+/// Exact (non-flattened) control-point bounds of a path through kurbo.
+pub fn bounds_of_shape(path: &BezPath) -> Option<Rect> {
+    path.bounding_box().as_rect()
+}
+
+/// Display units. The document is always millimetres; convert only where a value meets
+/// the user (fields, rulers, callouts), through these helpers.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Unit {
+    #[default]
+    Mm,
+    Cm,
+    In,
+    Pt,
+}
+
+impl Unit {
+    pub const ALL: [Unit; 4] = [Unit::Mm, Unit::Cm, Unit::In, Unit::Pt];
+
+    /// Millimetres in one of this unit.
+    pub fn mm_per_unit(self) -> f64 {
+        match self {
+            Unit::Mm => 1.0,
+            Unit::Cm => 10.0,
+            Unit::In => 25.4,
+            Unit::Pt => 25.4 / 72.0,
+        }
+    }
+
+    pub fn to_mm(self, value: f64) -> f64 {
+        value * self.mm_per_unit()
+    }
+
+    pub fn from_mm(self, mm: f64) -> f64 {
+        mm / self.mm_per_unit()
+    }
+
+    pub fn suffix(self) -> &'static str {
+        match self {
+            Unit::Mm => "mm",
+            Unit::Cm => "cm",
+            Unit::In => "in",
+            Unit::Pt => "pt",
+        }
+    }
+
+    /// `mm` shown in this unit with `decimals` places and the suffix, e.g. `1.000 in`.
+    pub fn format(self, mm: f64, decimals: usize) -> String {
+        format!("{:.*} {}", decimals.min(9), self.from_mm(mm), self.suffix())
+    }
+
+    /// Parses `12.5`, `12.5mm`, `1 in`, `3cm`, `72 pt` or `2"` into millimetres; a bare
+    /// number is in this unit. `None` for anything else or a non-finite result.
+    pub fn parse_to_mm(self, text: &str) -> Option<f64> {
+        let text = text.trim();
+        let (number, unit) = Unit::ALL
+            .iter()
+            .find_map(|u| text.strip_suffix(u.suffix()).map(|n| (n, *u)))
+            .or_else(|| text.strip_suffix('"').map(|n| (n, Unit::In)))
+            .unwrap_or((text, self));
+        let value: f64 = number.trim().parse().ok()?;
+        let mm = unit.to_mm(value);
+        mm.is_finite().then_some(mm)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn units_convert_format_and_parse() {
+        assert_eq!(Unit::In.to_mm(1.0), 25.4);
+        assert!((Unit::Pt.from_mm(25.4) - 72.0).abs() < 1e-12);
+        assert_eq!(Unit::Cm.from_mm(15.0), 1.5);
+        assert_eq!(Unit::In.format(25.4, 3), "1.000 in");
+        assert_eq!(Unit::Mm.parse_to_mm("12.5"), Some(12.5));
+        assert_eq!(Unit::In.parse_to_mm("2"), Some(50.8));
+        assert_eq!(Unit::Mm.parse_to_mm(" 1 in "), Some(25.4));
+        assert_eq!(Unit::Mm.parse_to_mm("2\""), Some(50.8));
+        assert_eq!(Unit::Mm.parse_to_mm("3cm"), Some(30.0));
+        assert_eq!(Unit::Mm.parse_to_mm("abc"), None);
+        assert_eq!(Unit::Mm.parse_to_mm("1e400"), None);
+        for unit in Unit::ALL {
+            assert!((unit.to_mm(unit.from_mm(123.4)) - 123.4).abs() < 1e-9);
+        }
+    }
+
+    fn square(side: f64) -> BezPath {
+        let mut p = BezPath::new();
+        p.move_to(Point::ZERO);
+        p.line_to(Point::new(side, 0.0));
+        p.line_to(Point::new(side, side));
+        p.line_to(Point::new(0.0, side));
+        p.close_path();
+        p
+    }
+
+    #[test]
+    fn flatten_square_closes() {
+        let lines = path_to_polylines(&square(10.0), 4);
+        assert_eq!(lines.len(), 1);
+        let pl = &lines[0];
+        assert!(pl.closed);
+        assert_eq!(pl.points.len(), 4);
+        assert_eq!(pl.points[0], Point::ZERO);
+        assert_eq!(pl.points[2], Point::new(10.0, 10.0));
+    }
+
+    #[test]
+    fn area_sign_of_square() {
+        let lines = path_to_polylines(&square(10.0), 4);
+        let area = signed_area(&lines[0].points);
+        assert!((area - 100.0).abs() < 1e-9, "got {area}");
+    }
+
+    #[test]
+    fn cubic_flattens_to_steps_per_segment() {
+        let mut p = BezPath::new();
+        p.move_to(Point::ZERO);
+        p.curve_to(Point::new(10.0, 0.0), Point::new(20.0, 10.0), Point::new(0.0, 20.0));
+        p.close_path();
+        let lines = path_to_polylines(&p, 8);
+        assert_eq!(lines.len(), 1);
+        // The move plus 7 interior samples; the segment's endpoint is the move origin
+        // after close, so it is not repeated.
+        assert_eq!(lines[0].points.len(), 8);
+    }
+
+    #[test]
+    fn bounds_union_works() {
+        let lines = path_to_polylines(&square(10.0), 4);
+        let b = bounds_of_polylines(&lines).unwrap();
+        assert_eq!(b, Rect::new(0.0, 0.0, 10.0, 10.0));
+    }
+}
diff --git a/crates/stencilcraft-document/src/lib.rs b/crates/stencilcraft-document/src/lib.rs
new file mode 100644
index 000000000..6e04be5b5
--- /dev/null
+++ b/crates/stencilcraft-document/src/lib.rs
@@ -0,0 +1,846 @@
+//! StencilCraft document model and domain validation.
+//!
+//! A document holds an artboard in millimetres, kerf settings and layers of shapes.
+//! Every read path returns `Result` with a calm, printable error: a malformed file
+//! must never crash (`AGENTS.md` › "Never crash"), because it is untrusted input.
+
+pub mod canvas;
+pub mod geom;
+pub mod metadata;
+
+use crate::geom::{GeomError, bounds_of_shape, check_finite_mm};
+pub use canvas::{Grid, Group, GroupChild, Guide, GuideAxis, Metadata, Orientation, Page, PagePreset, PageSetup, SnapSettings};
+use kurbo::BezPath;
+use serde::{Deserialize, Serialize};
+
+pub mod production;
+pub use metadata::{LibraryIndex, LibraryTrashEntry, MAX_RECENT_FILES, RecentFiles};
+pub use production::{CombineOp, GroupKind, Operation, SendAssign, ShapeProduction, SourceGroup};
+
+/// Native format identity and supported version, defined by the shared wire-format crate.
+pub use craft_stencilcraft_format::{FORMAT_NAME, FORMAT_VERSION};
+
+#[derive(Debug, thiserror::Error)]
+pub enum DocError {
+    #[error("{path}: {source}")]
+    Io { path: String, source: std::io::Error },
+
+    #[error("{path}: not a stencilcraft file")]
+    NotAStencilcraftFile { path: String },
+
+    #[error("{path}: format version {found}, this build reads {expected}")]
+    FormatVersion { path: String, found: u64, expected: u64 },
+
+    #[error("{path}: {source}")]
+    Parse { path: String, source: serde_json::Error },
+
+    #[error("{path}: {message}")]
+    Structure { path: String, message: String },
+
+    #[error("document: {0}")]
+    Model(String),
+
+    #[error(transparent)]
+    Geom(#[from] GeomError),
+}
+
+/// How a shape is physically produced on a machine.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum CutStyle {
+    /// Trace the closed outline with the cutting tool.
+    Cut,
+    /// Trace without cutting: scoring, engraving outlines, marking.
+    Engrave,
+}
+
+/// Kerf settings held in the document; applying them is `stencilcraft-kerf`'s job.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KerfSettings {
+    /// Nominal kerf (material removed by the tool), in millimetres. Compensation
+    /// offsets contours by `width_mm / 2`.
+    pub width_mm: f64,
+    /// Whether exports should carry compensated contours already.
+    pub apply_to_exports: bool,
+}
+
+impl Default for KerfSettings {
+    fn default() -> Self {
+        Self { width_mm: 0.0, apply_to_exports: false }
+    }
+}
+
+/// The cutting sheet: artboard size in millimetres.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Board {
+    pub width_mm: f64,
+    pub height_mm: f64,
+}
+
+impl Default for Board {
+    fn default() -> Self {
+        // A default sheet for vinyl work: 100 × 150 mm.
+        Self { width_mm: 100.0, height_mm: 150.0 }
+    }
+}
+
+/// One layer of the document: a group of shapes with a production style and a
+/// visibility flag.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Layer {
+    pub name: String,
+    pub kind: CutStyle,
+    pub visible: bool,
+    pub shapes: Vec<Shape>,
+    /// A locked layer's shapes cannot be selected or edited.
+    #[serde(default, skip_serializing_if = "is_false")]
+    pub locked: bool,
+    /// A template (guide) layer is shown on the canvas but never exported or cut.
+    #[serde(default, skip_serializing_if = "is_false")]
+    pub template: bool,
+    /// Material colour label, `#rrggbb`; Color Sync merges similar ones.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub color: Option<String>,
+}
+
+impl Layer {
+    pub fn new(name: impl Into<String>, kind: CutStyle) -> Self {
+        Self { name: name.into(), kind, visible: true, shapes: Vec::new(), locked: false, template: false, color: None }
+    }
+
+    /// Whether exports and cuts include this layer: visible and not a template.
+    pub fn is_output(&self) -> bool {
+        self.visible && !self.template
+    }
+
+    /// Whether newly created shapes may land here: not locked, not a template.
+    pub fn takes_new_shapes(&self) -> bool {
+        !self.locked && !self.template
+    }
+
+    /// Sum of per-shape bounds; `None` when the layer has no shapes or only empty
+    /// paths.
+    pub fn bounds(&self) -> Option<kurbo::Rect> {
+        let mut acc: Option<kurbo::Rect> = None;
+        for shape in &self.shapes {
+            if let Some(r) = shape.bounds() {
+                acc = Some(match acc {
+                    Some(prev) => prev.union(r),
+                    None => r,
+                });
+            }
+        }
+        acc
+    }
+}
+
+/// A path plus its production style. kurbo's `BezPath` serialises with the
+/// workspace's `serde` feature on — no wrapper needed.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Shape {
+    pub id: u64,
+    pub path: BezPath,
+    pub style: CutStyle,
+    /// Hidden shapes are not drawn, selected or exported.
+    #[serde(default, skip_serializing_if = "is_false")]
+    pub hidden: bool,
+    /// Locked shapes cannot be selected or edited until unlocked.
+    #[serde(default, skip_serializing_if = "is_false")]
+    pub locked: bool,
+    /// Live text: the parameters `path` was laid out from, so the text stays editable
+    /// (`text.edit` lays it out again). Absent for plain paths and in older files.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text: Option<Box<TextSpec>>,
+    /// A tool-specific operation for this path (score, emboss, engrave, foil, punch);
+    /// `None` is a plain cut or engrave pass by `style`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tool: Option<ToolOp>,
+    /// Production metadata (operation, colours, attach, contours, combine sources).
+    #[serde(default, skip_serializing_if = "ShapeProduction::is_default")]
+    pub production: ShapeProduction,
+}
+
+/// Score and emboss tool tip.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Tip {
+    #[default]
+    Fine,
+    Wide,
+}
+
+fn one_pass() -> u32 {
+    1
+}
+
+/// A tool-specific operation a machine backend runs instead of a plain cut/engrave pass.
+/// Paths tagged with one live on an engrave layer (they must never be cut through), except
+/// `punch`, whose path is the hole outline for display and fallback cutting.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "op", rename_all = "kebab-case")]
+pub enum ToolOp {
+    /// Crease along the path (scoring stylus/wheel).
+    Score {
+        #[serde(default)]
+        tip: Tip,
+        #[serde(default = "one_pass")]
+        passes: u32,
+    },
+    /// Press the path into the material (emboss, or deboss from the other side).
+    Emboss {
+        #[serde(default)]
+        tip: Tip,
+        #[serde(default = "one_pass")]
+        passes: u32,
+        #[serde(default)]
+        deboss: bool,
+    },
+    /// Rotary/power engraving tool following the path.
+    PowerEngrave,
+    /// Heat pen pressing foil along the path.
+    HeatPen,
+    /// One punch per contour, at the contour's bounds centre: a backend with a punch tool
+    /// plunges there instead of cutting the circle.
+    Punch { diameter_mm: f64 },
+}
+
+fn is_false(value: &bool) -> bool {
+    !*value
+}
+
+/// A live text object's parameters. The shape's `path` always holds the laid-out outlines,
+/// so readers that ignore `text` (older builds, every export) still cut the right thing.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TextSpec {
+    pub text: String,
+    pub font: FontSpec,
+    /// Em size in points (1 pt = 25.4/72 mm).
+    pub size: f64,
+    /// Anchor in mm: the first line's baseline at the alignment point.
+    pub x: f64,
+    pub y: f64,
+    #[serde(default)]
+    pub alignment: TextAlign,
+    /// Space added between letters, in percent of the em (0 = the font's own spacing).
+    #[serde(default)]
+    pub letter_spacing: f64,
+    /// Distance between lines in percent of the normal line distance (100 = normal).
+    #[serde(default = "hundred")]
+    pub line_spacing: f64,
+    /// Pair kerning from the font's tables.
+    #[serde(default = "yes")]
+    pub kerning: bool,
+    /// Top-to-bottom columns instead of left-to-right lines.
+    #[serde(default, skip_serializing_if = "is_false")]
+    pub vertical: bool,
+    /// Merge overlapping letter outlines into one cut path (script fonts).
+    #[serde(default, skip_serializing_if = "is_false")]
+    pub weld: bool,
+    #[serde(default, skip_serializing_if = "TextFlow::is_straight")]
+    pub flow: TextFlow,
+    /// Per-letter nudges, by character index into `text` (newlines count).
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub letters: Vec<LetterOffset>,
+    /// Affine `[a, b, c, d, e, f]` applied after layout: the moves, turns and scales made to
+    /// the shape since its text was laid out.
+    #[serde(default = "identity", skip_serializing_if = "is_identity")]
+    pub transform: [f64; 6],
+}
+
+/// A font by family and style, optionally from a font file.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct FontSpec {
+    pub family: String,
+    #[serde(default = "regular")]
+    pub style: String,
+    /// The font file the family came from, loaded again when the text is laid out again.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub file: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum TextAlign {
+    #[default]
+    Left,
+    #[serde(alias = "center", alias = "centre")]
+    Centre,
+    Right,
+    /// Every line but the last is stretched to the widest line.
+    Justify,
+}
+
+/// How the text runs: straight lines, one line bent round a circle, or one line along a path.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "kebab-case")]
+pub enum TextFlow {
+    #[default]
+    Straight,
+    /// One line bent into an arc of this diameter in mm: positive arches up, negative dips.
+    Curve { diameter_mm: f64 },
+    /// One line along `path` (mm). `start` is where the anchor sits, as a fraction of the
+    /// path's length; `offset_mm` lifts the letters off the path; `flip` runs the text the
+    /// other way round, on the other side. `shape` names the shape the path was copied from.
+    OnPath {
+        #[serde(default)]
+        path: BezPath,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        shape: Option<u64>,
+        #[serde(default)]
+        start: f64,
+        #[serde(default)]
+        offset_mm: f64,
+        #[serde(default)]
+        flip: bool,
+    },
+}
+
+impl TextFlow {
+    pub fn is_straight(&self) -> bool {
+        matches!(self, TextFlow::Straight)
+    }
+}
+
+/// A nudge to one letter: moved by `dx_mm`, `dy_mm` and turned `rotate_deg` about its origin.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
+pub struct LetterOffset {
+    pub index: usize,
+    #[serde(default)]
+    pub dx_mm: f64,
+    #[serde(default)]
+    pub dy_mm: f64,
+    #[serde(default)]
+    pub rotate_deg: f64,
+}
+
+fn hundred() -> f64 {
+    100.0
+}
+
+fn yes() -> bool {
+    true
+}
+
+fn regular() -> String {
+    "Regular".to_string()
+}
+
+/// The identity affine in `TextSpec::transform` form.
+pub const IDENTITY_TRANSFORM: [f64; 6] = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0];
+
+fn identity() -> [f64; 6] {
+    IDENTITY_TRANSFORM
+}
+
+fn is_identity(xf: &[f64; 6]) -> bool {
+    *xf == IDENTITY_TRANSFORM
+}
+
+impl Shape {
+    pub fn bounds(&self) -> Option<kurbo::Rect> {
+        bounds_of_shape(&self.path)
+    }
+}
+
+/// Most placed raster images one document may hold.
+pub const MAX_IMAGES: usize = 256;
+/// Most base64 PNG bytes one placed image may carry (about 96 MiB of PNG).
+pub const MAX_IMAGE_DATA: usize = 128 * 1024 * 1024;
+
+/// A placed raster image (a trace source, never cut). Pixels are PNG, base64-encoded so
+/// the document stays JSON; `Arc` keeps undo snapshots from copying the bytes.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct RasterImage {
+    /// Shares the shape id counter, so an id names one object in the document.
+    pub id: u64,
+    pub name: String,
+    pub x_mm: f64,
+    pub y_mm: f64,
+    pub width_mm: f64,
+    pub height_mm: f64,
+    pub width_px: u32,
+    pub height_px: u32,
+    pub png_base64: std::sync::Arc<str>,
+}
+
+impl RasterImage {
+    fn validate(&self) -> Result<(), DocError> {
+        for (value, what) in [(self.x_mm, "image x"), (self.y_mm, "image y"), (self.width_mm, "image width"), (self.height_mm, "image height")] {
+            check_finite_mm(value, what)?;
+        }
+        if self.width_mm <= 0.0 || self.height_mm <= 0.0 || self.width_px == 0 || self.height_px == 0 {
+            return Err(DocError::Model(format!("image {}: width and height must be positive", self.id)));
+        }
+        if self.png_base64.len() > MAX_IMAGE_DATA {
+            return Err(DocError::Model(format!("image {}: pixel data exceeds the 128 MiB limit", self.id)));
+        }
+        Ok(())
+    }
+}
+
+/// A StencilCraft document: artboard, kerf configuration, layers.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Document {
+    pub board: Board,
+    pub kerf: KerfSettings,
+    pub layers: Vec<Layer>,
+    /// Next free shape id; maintained by whoever mutates the document.
+    #[serde(default)]
+    pub next_shape_id: u64,
+    /// Placed raster images, bottom first, drawn under the cut layers.
+    #[serde(default)]
+    pub images: Vec<RasterImage>,
+    /// Mat, media, colour and name of the main board (page 0).
+    #[serde(default)]
+    pub board_setup: PageSetup,
+    /// Extra pages beside the main board.
+    #[serde(default)]
+    pub pages: Vec<Page>,
+    #[serde(default)]
+    pub guides: Vec<Guide>,
+    #[serde(default)]
+    pub grid: Grid,
+    #[serde(default)]
+    pub snap: SnapSettings,
+    /// Groups; members that no longer exist are ignored and dropped on save.
+    #[serde(default)]
+    pub groups: Vec<Group>,
+    #[serde(default)]
+    pub meta: Metadata,
+}
+
+/// Typed fields in the native wire format. Field names and version-1 defaults are owned by
+/// `craft-stencilcraft-format`; this alias supplies only StencilCraft's domain types.
+type NativeFileFields = craft_stencilcraft_format::DocumentFields<
+    Board,
+    KerfSettings,
+    Vec<Layer>,
+    RasterImage,
+    PageSetup,
+    Vec<Page>,
+    Vec<Guide>,
+    Grid,
+    SnapSettings,
+    Vec<Group>,
+    Metadata,
+>;
+
+impl Default for Document {
+    fn default() -> Self {
+        Self {
+            board: Board::default(),
+            kerf: KerfSettings::default(),
+            layers: vec![Layer::new("cut", CutStyle::Cut)],
+            next_shape_id: 1,
+            images: Vec::new(),
+            board_setup: PageSetup::default(),
+            pages: Vec::new(),
+            guides: Vec::new(),
+            grid: Grid::default(),
+            snap: SnapSettings::default(),
+            groups: Vec::new(),
+            meta: Metadata::default(),
+        }
+    }
+}
+
+impl Document {
+    /// Shapes across all layers, in order, paired with their layer index.
+    pub fn shapes(&self) -> impl Iterator<Item = (usize, &Shape)> {
+        self.layers.iter().enumerate().flat_map(|(li, l)| l.shapes.iter().map(move |s| (li, s)))
+    }
+
+    pub fn shape_count(&self) -> usize {
+        self.layers.iter().map(|l| l.shapes.len()).sum()
+    }
+
+    pub fn get_shape(&self, id: u64) -> Option<&Shape> {
+        self.shapes().map(|(_, s)| s).find(|s| s.id == id)
+    }
+
+    pub fn get_shape_mut(&mut self, id: u64) -> Option<&mut Shape> {
+        self.layers.iter_mut().flat_map(|l| l.shapes.iter_mut()).find(|s| s.id == id)
+    }
+
+    /// Allocates the next shape id and records the shape in `layer_index`.
+    /// Errors come out printable: messages name the layer and the fault.
+    pub fn push_shape(&mut self, layer_index: usize, path: BezPath, style: CutStyle) -> Result<Shape, DocError> {
+        if layer_index >= self.layers.len() {
+            return Err(DocError::Model(format!("layer {layer_index}: no such layer (document has {})", self.layers.len())));
+        }
+        let Some(layer) = self.layers.get_mut(layer_index) else {
+            return Err(DocError::Model(format!("layer {layer_index}: disappeared")));
+        };
+        let id = self.next_shape_id;
+        self.next_shape_id = self.next_shape_id.checked_add(1).ok_or_else(|| DocError::Model("shape ids exhausted".to_string()))?;
+        let shape = Shape { id, path, style, hidden: false, locked: false, tool: None, text: None, production: ShapeProduction::default() };
+        layer.shapes.push(shape.clone());
+        Ok(shape)
+    }
+
+    /// Places a raster image with the next object id and returns that id.
+    pub fn push_image(&mut self, mut image: RasterImage) -> Result<u64, DocError> {
+        if self.images.len() >= MAX_IMAGES {
+            return Err(DocError::Model(format!("a document holds at most {MAX_IMAGES} images")));
+        }
+        image.id = self.next_shape_id;
+        image.validate()?;
+        self.next_shape_id = self.next_shape_id.checked_add(1).ok_or_else(|| DocError::Model("shape ids exhausted".to_string()))?;
+        let id = image.id;
+        self.images.push(image);
+        Ok(id)
+    }
+
+    pub fn get_image(&self, id: u64) -> Option<&RasterImage> {
+        self.images.iter().find(|image| image.id == id)
+    }
+
+    /// Checks the board is a sane sheet: positive, finite dimensions.
+    pub fn validate(&self) -> Result<(), DocError> {
+        check_finite_mm(self.board.width_mm, "board width")?;
+        check_finite_mm(self.board.height_mm, "board height")?;
+        check_finite_mm(self.kerf.width_mm, "kerf width")?;
+        if self.board.width_mm <= 0.0 || self.board.height_mm <= 0.0 {
+            return Err(DocError::Model("board: width and height must be positive".to_string()));
+        }
+        if self.kerf.width_mm < 0.0 {
+            return Err(DocError::Model("kerf: width cannot be negative".to_string()));
+        }
+        if self.images.len() > MAX_IMAGES {
+            return Err(DocError::Model(format!("a document holds at most {MAX_IMAGES} images")));
+        }
+        self.images.iter().try_for_each(RasterImage::validate)?;
+        self.validate_canvas()
+    }
+
+    /// Serialises with the format header. The header wraps the document so a reader
+    /// knows what it is before reading the rest. Canvas fields are written only when
+    /// set, so a plain document saves exactly as it did before they existed.
+    pub fn save_json(&self) -> Result<String, DocError> {
+        self.validate()?;
+        let fields = NativeFileFields {
+            board: self.board.clone(),
+            kerf: self.kerf.clone(),
+            layers: self.layers.clone(),
+            next_shape_id: self.next_shape_id,
+            images: self.images.clone(),
+            board_setup: self.board_setup.clone(),
+            pages: self.pages.clone(),
+            guides: self.guides.clone(),
+            grid: self.grid.clone(),
+            snap: self.snap.clone(),
+            groups: self.pruned_groups(),
+            meta: self.meta.clone(),
+        };
+        craft_stencilcraft_format::File::<NativeFileFields>::new(fields)
+            .to_json_pretty()
+            .map_err(|e| DocError::Structure { path: "output".to_string(), message: e.to_string() })
+    }
+
+    /// Parses a document from JSON with calm, positioned error messages.
+    pub fn load_json(json: &str) -> Result<Document, DocError> {
+        load_json_named(json, "input")
+    }
+}
+
+fn load_json_named(json: &str, path: &str) -> Result<Document, DocError> {
+    let file = craft_stencilcraft_format::File::<NativeFileFields>::read_typed(json).map_err(|e| match e {
+        craft_stencilcraft_format::Error::Json(source) => DocError::Parse { path: path.to_string(), source },
+        craft_stencilcraft_format::Error::NotStencilCraft => DocError::NotAStencilcraftFile { path: path.to_string() },
+        craft_stencilcraft_format::Error::Version { found, supported } => {
+            DocError::FormatVersion { path: path.to_string(), found, expected: supported }
+        }
+        craft_stencilcraft_format::Error::Document { source } => structure_err(path, &source),
+        _ => DocError::NotAStencilcraftFile { path: path.to_string() },
+    })?;
+    let fields = file.document;
+    let mut doc = Document {
+        board: fields.board,
+        kerf: fields.kerf,
+        layers: fields.layers,
+        next_shape_id: fields.next_shape_id,
+        images: fields.images,
+        board_setup: fields.board_setup,
+        pages: fields.pages,
+        guides: fields.guides,
+        grid: fields.grid,
+        snap: fields.snap,
+        groups: fields.groups,
+        meta: fields.meta,
+    };
+    doc.validate()?;
+    doc.groups = doc.pruned_groups();
+    Ok(doc)
+}
+
+fn structure_err(path: &str, e: &serde_json::Error) -> DocError {
+    DocError::Structure { path: path.to_string(), message: e.to_string() }
+}
+
+/// File helpers: errors keep the path so the message names the file.
+pub fn save_to(doc: &Document, path: &str) -> Result<(), DocError> {
+    let json = doc.save_json()?;
+    craft_atomic::atomic_write(std::path::Path::new(path), json.as_bytes()).map_err(|source| DocError::Io { path: path.to_string(), source })
+}
+
+pub fn load_from(path: &str) -> Result<Document, DocError> {
+    let json = std::fs::read_to_string(path).map_err(|source| DocError::Io { path: path.to_string(), source })?;
+    load_json_named(&json, path)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::geom::Point;
+
+    fn rect_path(x: f64, y: f64, w: f64, h: f64) -> BezPath {
+        let mut p = BezPath::new();
+        p.move_to(Point::new(x, y));
+        p.line_to(Point::new(x + w, y));
+        p.line_to(Point::new(x + w, y + h));
+        p.line_to(Point::new(x, y + h));
+        p.close_path();
+        p
+    }
+
+    fn sample() -> Document {
+        let mut doc = Document::default();
+        doc.kerf.width_mm = 0.2;
+        doc.push_shape(0, rect_path(10.0, 20.0, 30.0, 40.0), CutStyle::Cut).unwrap();
+        doc
+    }
+
+    #[test]
+    fn round_trip() {
+        let doc = sample();
+        let json = doc.save_json().unwrap();
+        let back = Document::load_json(&json).unwrap();
+        assert_eq!(doc, back);
+    }
+
+    #[test]
+    fn flags_round_trip_and_default_off() {
+        let mut doc = sample();
+        let plain = doc.save_json().unwrap();
+        assert!(!plain.contains("hidden") && !plain.contains("locked"));
+        doc.layers[0].shapes[0].hidden = true;
+        doc.layers[0].shapes[0].locked = true;
+        let back = Document::load_json(&doc.save_json().unwrap()).unwrap();
+        assert_eq!(doc, back);
+    }
+
+    #[test]
+    fn text_round_trips_and_minimal_text_loads() {
+        let mut doc = sample();
+        let plain = doc.save_json().unwrap();
+        assert!(!plain.contains("\"text\""));
+        doc.layers[0].shapes[0].text = Some(Box::new(TextSpec {
+            text: "Hi".into(),
+            font: FontSpec { family: "Sans".into(), style: "Bold".into(), file: None },
+            size: 72.0,
+            x: 1.0,
+            y: 2.0,
+            alignment: TextAlign::Centre,
+            letter_spacing: -5.0,
+            line_spacing: 120.0,
+            kerning: false,
+            vertical: false,
+            weld: true,
+            flow: TextFlow::Curve { diameter_mm: 50.0 },
+            letters: vec![LetterOffset { index: 1, dx_mm: 1.0, ..LetterOffset::default() }],
+            transform: IDENTITY_TRANSFORM,
+        }));
+        let back = Document::load_json(&doc.save_json().unwrap()).unwrap();
+        assert_eq!(doc, back);
+        // A minimal hand-written text object fills in the defaults.
+        let json = plain.replace(
+            "\"style\": \"cut\"",
+            "\"style\": \"cut\", \"text\": {\"text\": \"A\", \"font\": {\"family\": \"X\"}, \"size\": 12, \"x\": 0, \"y\": 0}",
+        );
+        let spec = Document::load_json(&json).unwrap().layers[0].shapes[0].text.clone().unwrap();
+        assert_eq!(spec.line_spacing, 100.0);
+        assert!(spec.kerning && spec.flow.is_straight());
+        assert_eq!(spec.font.style, "Regular");
+    }
+
+    #[test]
+    fn header_written() {
+        let json = sample().save_json().unwrap();
+        let v: serde_json::Value = serde_json::from_str(&json).unwrap();
+        let h = &v["stencilcraft"];
+        assert_eq!(h["name"].as_str(), Some(FORMAT_NAME));
+        assert_eq!(h["version"].as_u64(), Some(FORMAT_VERSION));
+    }
+
+    #[test]
+    fn junk_is_an_error_not_a_crash() {
+        assert!(Document::load_json("not json at all").is_err());
+        assert!(matches!(Document::load_json("{}"), Err(DocError::NotAStencilcraftFile { .. })));
+    }
+
+    #[test]
+    fn future_version_is_rejected_calmly() {
+        let json = r#"{"stencilcraft": {"name": "stencilcraft", "version": 99}}"#;
+        assert!(matches!(Document::load_json(json), Err(DocError::FormatVersion { found: 99, expected: 1, .. })));
+    }
+
+    #[test]
+    fn missing_field_has_structure_error() {
+        let json = r#"{"stencilcraft": {"name": "stencilcraft", "version": 1},
+            "board": {"width_mm": 1, "height_mm": 1}}"#;
+        assert!(matches!(
+            Document::load_json(json),
+            Err(DocError::Structure { ref message, .. }) if message.contains("kerf")
+        ));
+    }
+
+    #[test]
+    fn images_round_trip_and_share_the_id_counter() {
+        let mut doc = canvas_sample();
+        let id = doc
+            .push_image(RasterImage {
+                id: 0,
+                name: "photo".to_string(),
+                x_mm: 0.0,
+                y_mm: 0.0,
+                width_mm: 10.0,
+                height_mm: 5.0,
+                width_px: 2,
+                height_px: 1,
+                png_base64: "AAAA".into(),
+            })
+            .unwrap();
+        assert_eq!(id, 3);
+        let back = Document::load_json(&doc.save_json().unwrap()).unwrap();
+        assert_eq!(back, doc);
+        let mut bad = doc.clone();
+        bad.images[0].width_mm = -1.0;
+        assert!(bad.validate().is_err());
+    }
+
+    #[test]
+    fn push_shape_assigns_ids() {
+        let mut doc = Document::default();
+        let s = doc.push_shape(0, rect_path(0.0, 0.0, 5.0, 5.0), CutStyle::Cut).unwrap();
+        assert_eq!(s.id, 1);
+        let s2 = doc.push_shape(0, rect_path(5.0, 5.0, 5.0, 5.0), CutStyle::Cut).unwrap();
+        assert_eq!(s2.id, 2);
+        assert!(matches!(doc.push_shape(9, rect_path(0.0, 0.0, 1.0, 1.0), CutStyle::Cut), Err(DocError::Model(_))));
+    }
+
+    fn canvas_sample() -> Document {
+        let mut doc = sample();
+        doc.push_shape(0, rect_path(50.0, 50.0, 5.0, 5.0), CutStyle::Cut).unwrap();
+        doc.board_setup.mat = Some("12x12".to_string());
+        doc.pages.push(Page {
+            x_mm: 120.0,
+            y_mm: 0.0,
+            width_mm: 210.0,
+            height_mm: 297.0,
+            setup: PageSetup { name: "A4".to_string(), color: Some("#ffeedd".to_string()), ..PageSetup::default() },
+        });
+        doc.guides.push(Guide { axis: GuideAxis::Vertical, position_mm: 12.5, locked: true });
+        doc.grid.spacing_mm = 5.0;
+        doc.grid.subdivisions = 4;
+        doc.snap.grid = true;
+        doc.layers[0].color = Some("#112233".to_string());
+        doc.layers.push(Layer { template: true, locked: true, ..Layer::new("guide", CutStyle::Cut) });
+        doc.groups = vec![
+            Group { id: 1, name: "inner".to_string(), children: vec![GroupChild::Shape(1)] },
+            Group { id: 2, name: String::new(), children: vec![GroupChild::Group(1), GroupChild::Shape(2)] },
+        ];
+        doc.meta.title = "Card".to_string();
+        doc.meta.notes = "for mum".to_string();
+        doc.meta.thumbnail_svg = Some(doc.render_thumbnail(4096));
+        doc
+    }
+
+    #[test]
+    fn canvas_fields_round_trip() {
+        let doc = canvas_sample();
+        let back = Document::load_json(&doc.save_json().unwrap()).unwrap();
+        assert_eq!(doc, back);
+        assert_eq!(back.group_chain(GroupChild::Shape(1)), vec![2, 1]);
+        assert_eq!(back.group_shapes(2), vec![1, 2]);
+    }
+
+    #[test]
+    fn plain_documents_save_without_canvas_keys() {
+        let json = sample().save_json().unwrap();
+        for key in ["pages", "guides", "grid", "snap", "groups", "meta", "board-setup", "template"] {
+            assert!(!json.contains(key), "{key} written for a plain document");
+        }
+    }
+
+    #[test]
+    fn version_1_files_without_canvas_fields_still_load() {
+        for json in [
+            include_str!("../tests/fixtures/starter.stencilcraft"),
+            include_str!("../tests/fixtures/poster.stencilcraft"),
+            include_str!("../tests/fixtures/stencil-frame.stencilcraft"),
+        ] {
+            let doc = Document::load_json(json).unwrap();
+            assert!(doc.pages.is_empty() && doc.groups.is_empty() && doc.guides.is_empty());
+            assert_eq!(doc.grid, Grid::default());
+            assert!(doc.layers.iter().all(|l| !l.template && !l.locked));
+        }
+    }
+
+    #[test]
+    fn dangling_group_members_are_pruned_not_fatal() {
+        let mut doc = canvas_sample();
+        doc.layers[0].shapes.retain(|s| s.id != 1);
+        // Group 1 loses its only member and disappears; group 2 keeps shape 2.
+        let back = Document::load_json(&doc.save_json().unwrap()).unwrap();
+        assert_eq!(back.groups.len(), 1);
+        assert_eq!(back.groups[0].children, vec![GroupChild::Shape(2)]);
+    }
+
+    #[test]
+    fn bad_canvas_data_is_rejected_calmly() {
+        type DocumentMutation = Box<dyn Fn(&mut Document)>;
+        let cases: Vec<DocumentMutation> = vec![
+            Box::new(|d| d.groups[0].children.push(GroupChild::Group(2))),
+            Box::new(|d| d.groups[1].children.push(GroupChild::Shape(1))),
+            Box::new(|d| d.groups[0].id = 2),
+            Box::new(|d| d.pages[0].width_mm = f64::NAN),
+            Box::new(|d| d.guides[0].position_mm = f64::INFINITY),
+            Box::new(|d| d.grid.subdivisions = 0),
+            Box::new(|d| d.layers[0].color = Some("red".to_string())),
+            Box::new(|d| d.meta.notes = "x".repeat(canvas::MAX_NOTES_BYTES + 1)),
+            Box::new(|d| d.snap.tolerance_mm = f64::NAN),
+        ];
+        for (i, corrupt) in cases.iter().enumerate() {
+            let mut doc = canvas_sample();
+            corrupt(&mut doc);
+            assert!(doc.validate().is_err(), "case {i} validated");
+            assert!(doc.save_json().is_err(), "case {i} saved");
+        }
+        // The same faults in a file are load errors.
+        let json = canvas_sample().save_json().unwrap().replace("#112233", "#zz");
+        assert!(Document::load_json(&json).is_err());
+    }
+
+    #[test]
+    fn page_document_takes_the_shapes_on_that_page() {
+        let mut doc = canvas_sample();
+        doc.push_shape(0, rect_path(130.0, 10.0, 10.0, 10.0), CutStyle::Cut).unwrap();
+        let page = doc.page_document(1).unwrap();
+        assert_eq!((page.board.width_mm, page.board.height_mm), (210.0, 297.0));
+        assert_eq!(page.shape_count(), 1);
+        let b = page.layers[0].shapes[0].bounds().unwrap();
+        assert!((b.x0 - 10.0).abs() < 1e-9 && (b.y0 - 10.0).abs() < 1e-9);
+        assert_eq!(doc.page_document(0).unwrap().shape_count(), 2);
+        assert!(doc.page_document(5).is_none());
+    }
+
+    #[test]
+    fn thumbnail_respects_its_budget() {
+        let doc = canvas_sample();
+        let full = doc.render_thumbnail(64 * 1024);
+        assert!(full.starts_with("<svg") && full.ends_with("</svg>"));
+        assert_eq!(full.matches("<path").count(), 2);
+        let small = doc.render_thumbnail(full.len() - 1);
+        assert!(small.len() < full.len() && small.ends_with("</svg>"));
+    }
+}
diff --git a/crates/stencilcraft-document/src/metadata.rs b/crates/stencilcraft-document/src/metadata.rs
new file mode 100644
index 000000000..04fb24d83
--- /dev/null
+++ b/crates/stencilcraft-document/src/metadata.rs
@@ -0,0 +1,85 @@
+//! Small JSON records used by StencilCraft's local library and recent-files list.
+//!
+//! These records are separate from a document, but their on-disk field names, defaults and
+//! JSON encoding are part of StencilCraft's supported persisted data.
+
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+
+use crate::DocError;
+
+/// One item in the local library recycle bin.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct LibraryTrashEntry {
+    /// File name inside the bin.
+    pub name: String,
+    /// Where it was, for restoring.
+    pub original: String,
+}
+
+/// The `.library.json` record stored at the root of a StencilCraft library.
+#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
+pub struct LibraryIndex {
+    #[serde(default)]
+    pub favourites: Vec<String>,
+    #[serde(default)]
+    pub trash: Vec<LibraryTrashEntry>,
+}
+
+impl LibraryIndex {
+    /// Parse the library index, applying defaults for fields absent in older indexes.
+    pub fn from_json(json: &str) -> Result<Self, serde_json::Error> {
+        serde_json::from_str(json)
+    }
+
+    /// Serialize the library index using the canonical pretty JSON representation.
+    pub fn to_json_pretty(&self) -> Result<String, serde_json::Error> {
+        serde_json::to_string_pretty(self)
+    }
+}
+
+/// Maximum number of paths retained in the recent-files record.
+pub const MAX_RECENT_FILES: usize = 10;
+
+/// Most recently used document paths, newest first, without duplicates.
+#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
+pub struct RecentFiles {
+    #[serde(default)]
+    pub paths: Vec<String>,
+}
+
+impl RecentFiles {
+    /// Parse recent files from their persisted JSON representation.
+    pub fn from_json(json: &str) -> Result<Self, serde_json::Error> {
+        serde_json::from_str(json)
+    }
+
+    /// Serialize recent files using the canonical pretty JSON representation.
+    pub fn to_json_pretty(&self) -> Result<String, serde_json::Error> {
+        serde_json::to_string_pretty(self)
+    }
+
+    /// Moves `path` to the front, keeping at most [`MAX_RECENT_FILES`].
+    pub fn push(&mut self, path: &str) {
+        self.paths.retain(|p| p != path);
+        self.paths.insert(0, path.to_string());
+        self.paths.truncate(MAX_RECENT_FILES);
+    }
+
+    pub fn remove(&mut self, path: &str) {
+        self.paths.retain(|p| p != path);
+    }
+
+    /// Reads the list; a missing or damaged file gives an empty list.
+    pub fn load(file: &Path) -> Self {
+        let mut list = std::fs::read_to_string(file).ok().and_then(|text| Self::from_json(&text).ok()).unwrap_or_default();
+        list.paths.truncate(MAX_RECENT_FILES);
+        list
+    }
+
+    pub fn save(&self, file: &Path) -> Result<(), DocError> {
+        let json = self.to_json_pretty().map_err(|e| DocError::Structure { path: file.display().to_string(), message: e.to_string() })?;
+        craft_atomic::atomic_write(file, json.as_bytes()).map_err(|source| DocError::Io { path: file.display().to_string(), source })
+    }
+}
diff --git a/crates/stencilcraft-document/src/production.rs b/crates/stencilcraft-document/src/production.rs
new file mode 100644
index 000000000..c03717c0b
--- /dev/null
+++ b/crates/stencilcraft-document/src/production.rs
@@ -0,0 +1,206 @@
+//! Per-shape production metadata: what the machine does with a shape (operation, colour and
+//! material keys for mats and cut groups), Attach groups, hidden contours, a manual mat, and the
+//! retained source shapes of a non-destructive Combine or a Flatten. Everything defaults to
+//! "unset" and is skipped when saving, so older files and files without production data are
+//! unchanged.
+
+use kurbo::{Affine, BezPath, PathEl};
+use serde::{Deserialize, Serialize};
+
+use crate::Shape;
+
+/// What the machine does with a shape. `None` on a shape means "follow its cut/engrave style".
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Operation {
+    /// Cut the outline (the default for cut shapes).
+    Cut,
+    /// Sticker kiss cut: through the face material only, the backing stays whole.
+    KissCut,
+    /// Sticker die cut: through the face material and the backing.
+    DieCut,
+    /// Draw the outline with a pen.
+    Draw,
+    /// Crease a fold line.
+    Score,
+    /// Engrave the line (the default for engrave shapes).
+    Engrave,
+    /// A dashed tear line.
+    Perforate,
+    /// Print on a home printer, then cut around the print using registration marks.
+    PrintThenCut,
+    /// Shown on the canvas only, never sent to the machine or printer.
+    Guide,
+}
+
+/// A per-shape tool assignment from the send preview, overriding the group settings.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum SendAssign {
+    /// Every line of the shape with tool 1.
+    Tool1,
+    /// Only the shape's outer outline with tool 1 (inner contours are skipped).
+    Tool1Outline,
+    Tool2,
+    Tool2Outline,
+    /// Leave the shape out of the job.
+    Ignore,
+}
+
+/// A Combine's shape operation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum CombineOp {
+    Unite,
+    /// The back-most member minus every other member.
+    Subtract,
+    Intersect,
+    /// Area covered by an odd number of members.
+    Exclude,
+}
+
+/// Why a shape keeps its sources.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case", tag = "kind", content = "operation")]
+pub enum GroupKind {
+    /// Non-destructive Combine: the path is the operation's result; Uncombine restores the
+    /// members.
+    Combine(CombineOp),
+    /// Flatten: the members are the print artwork, the path is its cut outline.
+    Flatten,
+}
+
+/// The shapes a Combine or Flatten replaced, kept so the action can be undone later.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct SourceGroup {
+    pub kind: GroupKind,
+    pub members: Vec<Shape>,
+    /// The grouped shape's path when the group was made. Comparing it with the current path
+    /// tells how the group was moved, rotated or scaled since, so the members follow.
+    pub path: BezPath,
+}
+
+impl SourceGroup {
+    /// The members moved the way the grouped shape moved since grouping (`current` is its
+    /// path now). An edit that is not an affine map of the old outline (node edits) falls back
+    /// to mapping the old bounds onto the new ones.
+    pub fn members_now(&self, current: &BezPath) -> Vec<Shape> {
+        let map = fit_affine(&self.path, current).unwrap_or_else(|| bounds_map(&self.path, current));
+        self.members
+            .iter()
+            .map(|m| {
+                let mut m = m.clone();
+                m.path = map * m.path;
+                m
+            })
+            .collect()
+    }
+}
+
+fn endpoints(path: &BezPath) -> Vec<kurbo::Point> {
+    path.elements().iter().filter_map(|el| el.end_point()).collect()
+}
+
+/// The affine map taking `old` onto `new` point for point, when the two have the same
+/// structure and one exists (within 0.01 mm).
+fn fit_affine(old: &BezPath, new: &BezPath) -> Option<Affine> {
+    let (a, b) = (endpoints(old), endpoints(new));
+    if a.len() != b.len() || a.len() < 3 {
+        return None;
+    }
+    let p0 = *a.first()?;
+    // The point farthest from p0, then the one making the largest triangle.
+    let i = (0..a.len()).max_by(|&i, &j| (a[i] - p0).hypot2().total_cmp(&(a[j] - p0).hypot2()))?;
+    let j = (0..a.len()).max_by(|&j, &k| (a[i] - p0).cross(a[j] - p0).abs().total_cmp(&(a[i] - p0).cross(a[k] - p0).abs()))?;
+    let (u, v) = (a[i] - p0, a[j] - p0);
+    let det = u.cross(v);
+    if det.abs() < 1e-9 {
+        // Collinear outline (or no movement information): a pure translation still works.
+        let t = Affine::translate(*b.first()? - p0);
+        return a.iter().zip(&b).all(|(p, q)| (t * *p - *q).hypot() < 0.01).then_some(t);
+    }
+    let q0 = *b.first()?;
+    let (s, t) = (b[i] - q0, b[j] - q0);
+    // M maps u→s and v→t: M = [s t]·[u v]⁻¹.
+    let inv = [v.y / det, -v.x / det, -u.y / det, u.x / det];
+    let m = [s.x * inv[0] + t.x * inv[2], s.y * inv[0] + t.y * inv[2], s.x * inv[1] + t.x * inv[3], s.y * inv[1] + t.y * inv[3]];
+    let linear = Affine::new([m[0], m[1], m[2], m[3], 0.0, 0.0]);
+    let map = Affine::translate(q0.to_vec2()) * linear * Affine::translate(-p0.to_vec2());
+    a.iter().zip(&b).all(|(p, q)| (map * *p - *q).hypot() < 0.01).then_some(map)
+}
+
+fn bounds_map(old: &BezPath, new: &BezPath) -> Affine {
+    use kurbo::Shape as _;
+    let (a, b) = (old.bounding_box(), new.bounding_box());
+    let sx = if a.width() > 1e-9 { b.width() / a.width() } else { 1.0 };
+    let sy = if a.height() > 1e-9 { b.height() / a.height() } else { 1.0 };
+    Affine::translate((b.x0, b.y0)) * Affine::scale_non_uniform(sx, sy) * Affine::translate((-a.x0, -a.y0))
+}
+
+/// Production metadata of one shape. Every field is optional.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ShapeProduction {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub operation: Option<Operation>,
+    /// Canonical `#rrggbb` line colour: the cut-by-line-colour key.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub line_color: Option<String>,
+    /// Canonical `#rrggbb` fill colour: the print colour and cut-by-fill-colour key.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub fill_color: Option<String>,
+    /// Material name; shapes on different materials go on different mats.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub material: Option<String>,
+    /// Attach group: shapes sharing it keep their relative positions on one mat.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub attach: Option<u64>,
+    /// Manual mat: the piece goes on this mat index instead of its automatic one.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mat: Option<u32>,
+    /// Tool assignment from the send preview.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub send: Option<SendAssign>,
+    /// Contours (subpath indices) hidden by Contour: kept in the path, left out of exports.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub hidden_contours: Vec<usize>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub group: Option<Box<SourceGroup>>,
+}
+
+impl ShapeProduction {
+    pub fn is_default(&self) -> bool {
+        *self == Self::default()
+    }
+}
+
+impl Shape {
+    /// The path the machine sees: the shape's path without the contours Contour hid.
+    pub fn cut_path(&self) -> std::borrow::Cow<'_, BezPath> {
+        if self.production.hidden_contours.is_empty() {
+            return std::borrow::Cow::Borrowed(&self.path);
+        }
+        let mut out = BezPath::new();
+        let mut contour = 0usize;
+        let mut started = false;
+        for el in self.path.elements() {
+            if matches!(el, PathEl::MoveTo(_)) {
+                if started {
+                    contour += 1;
+                }
+                started = true;
+            }
+            if !self.production.hidden_contours.contains(&contour) {
+                out.push(*el);
+            }
+        }
+        std::borrow::Cow::Owned(out)
+    }
+
+    /// The shape's operation, falling back to its cut/engrave style.
+    pub fn operation(&self) -> Operation {
+        self.production.operation.unwrap_or(match self.style {
+            crate::CutStyle::Cut => Operation::Cut,
+            crate::CutStyle::Engrave => Operation::Engrave,
+        })
+    }
+}
diff --git a/crates/stencilcraft-document/tests/fixtures/poster.stencilcraft b/crates/stencilcraft-document/tests/fixtures/poster.stencilcraft
new file mode 100644
index 000000000..4de690925
--- /dev/null
+++ b/crates/stencilcraft-document/tests/fixtures/poster.stencilcraft
@@ -0,0 +1,98 @@
+{
+  "board": {
+    "height_mm": 400.0,
+    "width_mm": 500.0
+  },
+  "kerf": {
+    "apply_to_exports": false,
+    "width_mm": 0.0
+  },
+  "layers": [
+    {
+      "kind": "cut",
+      "name": "cut",
+      "shapes": [
+        {
+          "id": 1,
+          "path": [
+            {
+              "MoveTo": {
+                "x": 10.0,
+                "y": 20.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 70.0,
+                "y": 20.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 70.0,
+                "y": 80.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 10.0,
+                "y": 80.0
+              }
+            },
+            "ClosePath"
+          ],
+          "style": "cut"
+        },
+        {
+          "id": 2,
+          "path": [
+            {
+              "MoveTo": {
+                "x": 10.0,
+                "y": 390.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 490.0,
+                "y": 10.0
+              }
+            }
+          ],
+          "style": "cut"
+        }
+      ],
+      "visible": true
+    },
+    {
+      "kind": "engrave",
+      "name": "engrave",
+      "shapes": [
+        {
+          "id": 3,
+          "path": [
+            {
+              "MoveTo": {
+                "x": 100.0,
+                "y": 200.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 400.0,
+                "y": 200.0
+              }
+            }
+          ],
+          "style": "engrave"
+        }
+      ],
+      "visible": true
+    }
+  ],
+  "next-shape-id": 4,
+  "stencilcraft": {
+    "name": "stencilcraft",
+    "version": 1
+  }
+}
diff --git a/crates/stencilcraft-document/tests/fixtures/starter.stencilcraft b/crates/stencilcraft-document/tests/fixtures/starter.stencilcraft
new file mode 100644
index 000000000..2a18fbb11
--- /dev/null
+++ b/crates/stencilcraft-document/tests/fixtures/starter.stencilcraft
@@ -0,0 +1,111 @@
+{
+  "board": {
+    "height_mm": 150.0,
+    "width_mm": 100.0
+  },
+  "kerf": {
+    "apply_to_exports": false,
+    "width_mm": 0.0
+  },
+  "layers": [
+    {
+      "kind": "cut",
+      "name": "cut",
+      "shapes": [
+        {
+          "id": 1,
+          "path": [
+            {
+              "MoveTo": {
+                "x": 10.0,
+                "y": 10.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 60.0,
+                "y": 10.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 60.0,
+                "y": 60.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 10.0,
+                "y": 60.0
+              }
+            },
+            "ClosePath"
+          ],
+          "style": "cut"
+        },
+        {
+          "id": 2,
+          "path": [
+            {
+              "MoveTo": {
+                "x": 70.0,
+                "y": 20.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 85.0,
+                "y": 20.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 85.0,
+                "y": 60.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 70.0,
+                "y": 60.0
+              }
+            },
+            "ClosePath"
+          ],
+          "style": "cut"
+        }
+      ],
+      "visible": true
+    },
+    {
+      "kind": "engrave",
+      "name": "engrave",
+      "shapes": [
+        {
+          "id": 3,
+          "path": [
+            {
+              "MoveTo": {
+                "x": 10.0,
+                "y": 90.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 90.0,
+                "y": 90.0
+              }
+            }
+          ],
+          "style": "engrave"
+        }
+      ],
+      "visible": true
+    }
+  ],
+  "next-shape-id": 4,
+  "stencilcraft": {
+    "name": "stencilcraft",
+    "version": 1
+  }
+}
\ No newline at end of file
diff --git a/crates/stencilcraft-document/tests/fixtures/stencil-frame.stencilcraft b/crates/stencilcraft-document/tests/fixtures/stencil-frame.stencilcraft
new file mode 100644
index 000000000..3e0a77ed8
--- /dev/null
+++ b/crates/stencilcraft-document/tests/fixtures/stencil-frame.stencilcraft
@@ -0,0 +1,86 @@
+{
+  "board": {
+    "height_mm": 150.0,
+    "width_mm": 120.0
+  },
+  "kerf": {
+    "apply_to_exports": true,
+    "width_mm": 0.2
+  },
+  "layers": [
+    {
+      "kind": "cut",
+      "name": "cut",
+      "shapes": [
+        {
+          "id": 1,
+          "path": [
+            {
+              "MoveTo": {
+                "x": 0.0,
+                "y": 0.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 100.0,
+                "y": 0.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 100.0,
+                "y": 100.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 0.0,
+                "y": 100.0
+              }
+            },
+            "ClosePath"
+          ],
+          "style": "cut"
+        },
+        {
+          "id": 2,
+          "path": [
+            {
+              "MoveTo": {
+                "x": 30.0,
+                "y": 30.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 70.0,
+                "y": 30.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 70.0,
+                "y": 70.0
+              }
+            },
+            {
+              "LineTo": {
+                "x": 30.0,
+                "y": 70.0
+              }
+            },
+            "ClosePath"
+          ],
+          "style": "cut"
+        }
+      ],
+      "visible": true
+    }
+  ],
+  "next-shape-id": 3,
+  "stencilcraft": {
+    "name": "stencilcraft",
+    "version": 1
+  }
+}
diff --git a/crates/stencilcraft-format/README.md b/crates/stencilcraft-format/README.md
index 2391d3c56..c5b32582d 100644
--- a/crates/stencilcraft-format/README.md
+++ b/crates/stencilcraft-format/README.md
@@ -3,8 +3,10 @@
 Reader and writer for the versioned `.stencilcraft` JSON file. The JSON header is
 `{"stencilcraft":{"name":"stencilcraft","version":1}}`; the document fields share the
 top-level object with the header. `DocumentFields` owns field names, flattening, required fields,
-version 1 defaults, and omitted optional members. Its values remain JSON so the consuming app
-owns the domain model, geometry validation, and field-to-model mapping.
+version 1 defaults, and omission of default canvas members. Its type parameters let consumers use
+their typed model fields directly; `File::<DocumentFields<...>>::read_typed` and
+`to_json_pretty` handle the shared schema and JSON conversion. StencilCraft's typed model and
+domain validation live in `craft-stencilcraft-document`.
 
 The crate does not open files or set a file-size policy. Callers perform bounded file I/O before
 calling `File::read`.
@@ -13,10 +15,11 @@ calling `File::read`.
 craft-stencilcraft-format = { git = "https://github.com/storytold/craft-libs", rev = "<commit>" }
 ```
 
-`File::read` parses JSON, validates the name and exact supported version, reads `DocumentFields`,
-and ignores unknown members for version 1 compatibility. `File::new` and `to_json_pretty` write
-the current header and flattened fields. Absent `next-shape-id` defaults to 1 and absent `images`
-defaults to an empty list, matching early version 1 files.
+`File::read` parses JSON into the default JSON-valued schema. For typed models, use
+`File::<DocumentFields<...>>::read_typed`; both readers validate the name and exact supported
+version and ignore unknown members for version 1 compatibility. `File::new` and `to_json_pretty`
+write the current header and flattened fields. Absent `next-shape-id` defaults to 1 and absent
+`images` defaults to an empty list, matching early version 1 files.
 
 `cargo test -p craft-stencilcraft-format` covers round-trip wire shape, version 1 defaults,
 unknown members, wrong and missing headers, unsupported versions, malformed JSON, and missing
diff --git a/crates/stencilcraft-format/src/lib.rs b/crates/stencilcraft-format/src/lib.rs
index 709bf7ac7..1ff64af59 100644
--- a/crates/stencilcraft-format/src/lib.rs
+++ b/crates/stencilcraft-format/src/lib.rs
@@ -16,10 +16,9 @@
 //! ```
 //!
 //! [`DocumentFields`] owns the JSON field names, required and defaulted fields, and the
-//! flattening rule. Its values are JSON because the consuming app owns the document model,
-//! domain validation, and conversion between that model and the wire fields. The crate does not
-//! open files or set a file-size policy; callers handle bounded file I/O. [`File::read_from`]
-//! lets callers parse from a reader without first buffering source bytes in a string.
+//! flattening rule. Its generic form lets an application use its typed domain values directly,
+//! while keeping the wire schema and JSON encoding here. The crate does not open files or set a
+//! file-size policy; callers handle bounded file I/O. [`File::read_from`] parses from a reader.
 
 use serde::de::{self, IgnoredAny, MapAccess, SeqAccess, Visitor};
 use serde::{Deserialize, Deserializer, Serialize};
@@ -37,62 +36,96 @@ pub const FORMAT_VERSION: u64 = 1;
 pub const HEADER_KEY: &str = "stencilcraft";
 
 /// Wire fields in the flattened native document object.
+///
+/// The type parameters are the consuming app's typed model values. Field names, required fields,
+/// version-1 defaults, and omission of default canvas values remain owned by this crate.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-pub struct DocumentFields {
+#[serde(bound(
+    serialize = "Board: Serialize, Kerf: Serialize, Layers: Serialize, Image: Serialize, BoardSetup: Serialize + Default + PartialEq, Pages: Serialize + Default + PartialEq, Guides: Serialize + Default + PartialEq, Grid: Serialize + Default + PartialEq, Snap: Serialize + Default + PartialEq, Groups: Serialize + Default + PartialEq, Meta: Serialize + Default + PartialEq",
+    deserialize = "Board: Deserialize<'de>, Kerf: Deserialize<'de>, Layers: Deserialize<'de>, Image: Deserialize<'de>, BoardSetup: Deserialize<'de> + Default, Pages: Deserialize<'de> + Default, Guides: Deserialize<'de> + Default, Grid: Deserialize<'de> + Default, Snap: Deserialize<'de> + Default, Groups: Deserialize<'de> + Default, Meta: Deserialize<'de> + Default"
+))]
+pub struct DocumentFields<
+    Board = Value,
+    Kerf = Value,
+    Layers = Value,
+    Image = Value,
+    BoardSetup = Option<Value>,
+    Pages = Option<Value>,
+    Guides = Option<Value>,
+    Grid = Option<Value>,
+    Snap = Option<Value>,
+    Groups = Option<Value>,
+    Meta = Option<Value>,
+> {
     /// Required millimetre artboard dimensions.
-    pub board: Value,
+    pub board: Board,
     /// Required kerf settings.
-    pub kerf: Value,
+    pub kerf: Kerf,
     /// Required drawing layers.
-    pub layers: Value,
+    pub layers: Layers,
     /// Next document object id; absent in early version 1 files, where it defaults to 1.
     #[serde(rename = "next-shape-id", default = "default_next_shape_id")]
     pub next_shape_id: u64,
     /// Embedded raster images; absent in early version 1 files, where it defaults to empty.
     #[serde(default)]
-    pub images: Vec<Value>,
+    pub images: Vec<Image>,
     /// Optional canvas page setup, omitted when absent.
-    #[serde(rename = "board-setup", default, skip_serializing_if = "Option::is_none")]
-    pub board_setup: Option<Value>,
+    #[serde(rename = "board-setup", default, skip_serializing_if = "is_default")]
+    pub board_setup: BoardSetup,
     /// Optional pages, omitted when absent.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub pages: Option<Value>,
+    #[serde(default, skip_serializing_if = "is_default")]
+    pub pages: Pages,
     /// Optional guides, omitted when absent.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub guides: Option<Value>,
+    #[serde(default, skip_serializing_if = "is_default")]
+    pub guides: Guides,
     /// Optional grid settings, omitted when absent.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub grid: Option<Value>,
+    #[serde(default, skip_serializing_if = "is_default")]
+    pub grid: Grid,
     /// Optional snap settings, omitted when absent.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub snap: Option<Value>,
+    #[serde(default, skip_serializing_if = "is_default")]
+    pub snap: Snap,
     /// Optional groups, omitted when absent.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub groups: Option<Value>,
+    #[serde(default, skip_serializing_if = "is_default")]
+    pub groups: Groups,
     /// Optional user metadata, omitted when absent.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub meta: Option<Value>,
+    #[serde(default, skip_serializing_if = "is_default")]
+    pub meta: Meta,
+}
+
+fn is_default<T: Default + PartialEq>(value: &T) -> bool {
+    value == &T::default()
 }
 
 fn default_next_shape_id() -> u64 {
     1
 }
 
-/// A native document and its flattened wire fields.
+/// A native document and its flattened, typed wire fields.
 #[derive(Debug, Clone, PartialEq)]
-pub struct File {
-    /// The fields after the header have been parsed, with app-domain objects still encoded as
-    /// JSON values.
-    pub document: DocumentFields,
+pub struct File<T = DocumentFields> {
+    /// Typed document fields after the shared codec has checked the header and schema.
+    pub document: T,
 }
 
-impl File {
+impl<T> File<T> {
     /// Builds a native document from its wire fields.
-    pub fn new(document: DocumentFields) -> Self {
+    pub fn new(document: T) -> Self {
         Self { document }
     }
 
-    /// Parses JSON, validates the format header and version, then reads the wire fields.
+    /// Writes the current format header and flattened wire fields as indented JSON.
+    pub fn to_json_pretty(&self) -> Result<String, Error>
+    where
+        T: Serialize,
+    {
+        let raw = RawFileRef { header: HeaderRef { name: FORMAT_NAME, version: FORMAT_VERSION }, document: &self.document };
+        let value = serde_json::to_value(raw).map_err(Error::Json)?;
+        serde_json::to_string_pretty(&value).map_err(Error::Json)
+    }
+}
+
+impl File<DocumentFields> {
+    /// Parses JSON, validates the format header and version, then reads the untyped wire fields.
     pub fn read(text: &str) -> Result<Self, Error> {
         let wire: RawWire = serde_json::from_str(text).map_err(Error::Json)?;
         Self::from_wire(wire)
@@ -118,15 +151,40 @@ impl File {
         if version != FORMAT_VERSION {
             return Err(Error::Version { found: version, supported: FORMAT_VERSION });
         }
-        let raw: RawFile = serde_json::from_value(Value::Object(wire.fields)).map_err(|source| Error::Document { source })?;
+        let raw: RawFile<DocumentFields> = serde_json::from_value(Value::Object(wire.fields)).map_err(|source| Error::Document { source })?;
         Ok(Self { document: raw.document })
     }
+}
 
-    /// Writes the current format header and flattened wire fields as indented JSON.
-    pub fn to_json_pretty(&self) -> Result<String, Error> {
-        let raw = RawFileRef { header: HeaderRef { name: FORMAT_NAME, version: FORMAT_VERSION }, document: &self.document };
-        let value = serde_json::to_value(raw).map_err(Error::Json)?;
-        serde_json::to_string_pretty(&value).map_err(Error::Json)
+impl<T> File<T>
+where
+    T: for<'de> Deserialize<'de>,
+{
+    /// Parses JSON into a typed document model after validating the shared format header.
+    pub fn read_typed(text: &str) -> Result<Self, Error> {
+        let wire: RawWire = serde_json::from_str(text).map_err(Error::Json)?;
+        Self::from_typed_wire(wire)
+    }
+
+    /// Parses JSON from a reader into a typed document model.
+    pub fn read_typed_from(reader: impl Read) -> Result<Self, Error> {
+        let wire: RawWire = serde_json::from_reader(reader).map_err(Error::Json)?;
+        Self::from_typed_wire(wire)
+    }
+
+    fn from_typed_wire(wire: RawWire) -> Result<Self, Error> {
+        let header = wire.fields.get(HEADER_KEY).and_then(Value::as_object).ok_or(Error::NotStencilCraft)?;
+        if header.get("name").and_then(Value::as_str) != Some(FORMAT_NAME) {
+            return Err(Error::NotStencilCraft);
+        }
+        let Some(version) = header.get("version").and_then(Value::as_u64) else {
+            return Err(Error::NotStencilCraft);
+        };
+        if version != FORMAT_VERSION {
+            return Err(Error::Version { found: version, supported: FORMAT_VERSION });
+        }
+        let raw: RawFile<T> = serde_json::from_value(Value::Object(wire.fields)).map_err(|source| Error::Document { source })?;
+        Ok(Self { document: raw.document })
     }
 }
 
@@ -137,11 +195,11 @@ struct Header {
 }
 
 #[derive(Debug, Deserialize)]
-struct RawFile {
+struct RawFile<T = DocumentFields> {
     #[serde(rename = "stencilcraft")]
     _header: Header,
     #[serde(flatten)]
-    document: DocumentFields,
+    document: T,
 }
 
 /// A top-level streaming visitor that stores only fields owned by this wire schema.
@@ -277,11 +335,11 @@ struct HeaderRef<'a> {
 }
 
 #[derive(Serialize)]
-struct RawFileRef<'a> {
+struct RawFileRef<'a, T> {
     #[serde(rename = "stencilcraft")]
     header: HeaderRef<'a>,
     #[serde(flatten)]
-    document: &'a DocumentFields,
+    document: &'a T,
 }
 
 /// A file was malformed, belongs to another format, or uses an unsupported version.
@@ -306,6 +364,7 @@ pub enum Error {
 mod tests {
     use std::io::{self, Cursor, Read};
 
+    use serde::{Deserialize, Serialize};
     use serde_json::{Value, json};
 
     use super::{DocumentFields, Error, FORMAT_VERSION, File};
@@ -411,4 +470,43 @@ mod tests {
         assert!(matches!(File::read("{"), Err(Error::Json(_))));
         assert!(matches!(File::read(r#"{"stencilcraft":{"name":"stencilcraft","version":1}}"#), Err(Error::Document { .. })));
     }
+
+    #[derive(Debug, PartialEq, Serialize, Deserialize)]
+    struct TypedBoard {
+        width_mm: f64,
+        height_mm: f64,
+    }
+
+    #[derive(Debug, PartialEq, Serialize, Deserialize)]
+    struct TypedFields {
+        board: TypedBoard,
+        #[serde(default, rename = "board-setup", skip_serializing_if = "Option::is_none")]
+        board_setup: Option<TypedBoard>,
+    }
+
+    fn typed_fields() -> TypedFields {
+        TypedFields { board: TypedBoard { width_mm: 100.0, height_mm: 150.0 }, board_setup: None }
+    }
+
+    #[test]
+    fn typed_readers_round_trip_typed_fields_and_preserve_header_errors() -> Result<(), Error> {
+        let file = File::new(typed_fields());
+        let text = file.to_json_pretty()?;
+        assert!(!text.contains("board-setup"));
+        assert_eq!(File::read_typed(&text)?, file);
+        assert_eq!(File::read_typed_from(Cursor::new(text.as_bytes()))?, file);
+
+        let malformed = r#"{"stencilcraft":{"name":"stencilcraft","version":1},"board":"wrong"}"#;
+        assert!(matches!(File::<TypedFields>::read_typed(malformed), Err(Error::Document { .. })));
+        assert!(matches!(File::<TypedFields>::read_typed_from(Cursor::new(malformed)), Err(Error::Document { .. })));
+
+        let wrong_header = r#"{"stencilcraft":{"name":"other","version":1},"board":{}}"#;
+        assert!(matches!(File::<TypedFields>::read_typed(wrong_header), Err(Error::NotStencilCraft)));
+        assert!(matches!(File::<TypedFields>::read_typed_from(Cursor::new(wrong_header)), Err(Error::NotStencilCraft)));
+
+        let future_version = r#"{"stencilcraft":{"name":"stencilcraft","version":2},"board":{}}"#;
+        assert!(matches!(File::<TypedFields>::read_typed(future_version), Err(Error::Version { found: 2, supported: 1 })));
+        assert!(matches!(File::<TypedFields>::read_typed_from(Cursor::new(future_version)), Err(Error::Version { found: 2, supported: 1 })));
+        Ok(())
+    }
 }
diff --git a/crates/svg/Cargo.toml b/crates/svg/Cargo.toml
index 49b22e213..e296fe625 100644
--- a/crates/svg/Cargo.toml
+++ b/crates/svg/Cargo.toml
@@ -17,6 +17,8 @@ flate2 = { version = "1", default-features = false, features = ["rust_backend"]
 kurbo = { workspace = true }
 roxmltree = "0.21.2"
 thiserror = { workspace = true }
+vectorcraft-geom = { workspace = true }
+vectorcraft-pathops = { workspace = true }
 # The full SVG parser (Apache-2.0 OR MIT). The one version every Craft app uses: apps depend on
 # craft-svg's `tree` feature and take usvg from its re-export, never directly.
 usvg = { version = "=0.48.1", default-features = false, optional = true }
diff --git a/crates/svg/src/paths.rs b/crates/svg/src/paths.rs
index e909283fd..504a1dd1b 100644
--- a/crates/svg/src/paths.rs
+++ b/crates/svg/src/paths.rs
@@ -6,12 +6,11 @@
 //! millimetres, with its stroke paint and the clip regions that apply to it. The caller tags
 //! shapes through [`Kind`] (cut or engrave, layer, pen…) from each element's computed style and
 //! class. Input is treated as hostile: size, node, depth and instance limits, and cyclic
-//! references, are errors.
-//!
-//! Geometry only. Boolean operations (applying [`Clip`]s) are left to the caller. Stroke paint
-//! is returned as written; [`crate::color::parse_color`] reads it as a CSS colour.
+//! references, are errors. [`Imported::clipped_path`] applies the collected clip regions with
+//! their SVG fill rules. Stroke paint is returned as written; [`crate::color::parse_color`]
+//! reads it as a CSS colour.
 
-use kurbo::BezPath;
+use kurbo::{BezPath, PathEl, Point, Shape as _};
 
 /// Why an SVG could not be read; the message starts with the name given to [`import`].
 #[derive(Debug, thiserror::Error)]
@@ -60,7 +59,7 @@ pub struct Clip {
     pub pieces: Vec<(BezPath, FillRule)>,
 }
 
-/// One drawable element, transformed into the document's millimetre space and not yet clipped.
+/// One drawable element, transformed into the document's millimetre space.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Shape<K> {
     pub path: BezPath,
@@ -70,6 +69,12 @@ pub struct Shape<K> {
     /// The stroke colour as written (`currentColor` and paint-server fallbacks resolved), or
     /// `None` without a stroke.
     pub stroke: Option<String>,
+    /// Whether the computed style paints the path interior (`fill` defaults to black).
+    pub has_fill: bool,
+    /// Whether the computed style paints a stroke.
+    pub has_stroke: bool,
+    /// The computed `fill-rule`, defaulting to SVG's `nonzero` rule.
+    pub fill_rule: FillRule,
     /// The regions the shape is clipped by, as indices into [`Imported::clips`], outermost first.
     pub clips: Vec<usize>,
     /// The name of the innermost Inkscape layer the element is in: a `<g>` with
@@ -96,6 +101,275 @@ pub struct Imported<K> {
     pub dropped_warnings: usize,
 }
 
+impl<K> Imported<K> {
+    /// Return one imported shape with every applicable SVG `clip-path` applied.
+    ///
+    /// Clip geometry is evaluated here so applications can map the resulting path into their own
+    /// document model without reimplementing SVG fill rules or boolean clipping.
+    pub fn clipped_path(&self, shape: &Shape<K>) -> Result<BezPath, Error> {
+        let mut path = shape.path.clone();
+        let mut work_left = MAX_CLIP_WORK;
+        let mut output_left = MAX_CLIPPED_POINTS;
+        for &clip_index in &shape.clips {
+            let clip = self.clips.get(clip_index).ok_or_else(|| Error("SVG shape refers to a missing clip region".into()))?;
+            path = apply_clip(&path, clip, shape.has_fill, shape.has_stroke, shape.fill_rule, &mut work_left, &mut output_left)?;
+        }
+        Ok(path)
+    }
+}
+
+fn apply_clip(
+    path: &BezPath,
+    clip: &Clip,
+    has_fill: bool,
+    has_stroke: bool,
+    fill_rule: FillRule,
+    work_left: &mut usize,
+    output_left: &mut usize,
+) -> Result<BezPath, Error> {
+    if clip.pieces.is_empty() {
+        return Ok(BezPath::new());
+    }
+    let pieces: Vec<_> = clip
+        .pieces
+        .iter()
+        .map(|(path, rule)| {
+            (
+                vectorcraft_geom::PathData::from_bezpath(path),
+                match rule {
+                    FillRule::EvenOdd => vectorcraft_geom::FillRule::EvenOdd,
+                    FillRule::NonZero => vectorcraft_geom::FillRule::NonZero,
+                },
+            )
+        })
+        .collect();
+    let inputs: Vec<_> = pieces.iter().map(|(path, rule)| (path, *rule)).collect();
+    let region = vectorcraft_pathops::try_boolean_n(&inputs, |inside: &[bool]| inside.iter().any(|v| *v))
+        .map_err(|e| Error(format!("SVG clip-path: {e}")))?
+        .to_bezpath();
+    clip_path_to_region(path, &region, has_fill, has_stroke, fill_rule, work_left, output_left).map_err(|e| Error(format!("SVG clip-path: {e}")))
+}
+
+fn clip_path_to_region(
+    path: &BezPath,
+    region: &BezPath,
+    has_fill: bool,
+    has_stroke: bool,
+    fill_rule: FillRule,
+    work_left: &mut usize,
+    output_left: &mut usize,
+) -> Result<BezPath, String> {
+    if region.elements().is_empty() {
+        return Ok(BezPath::new());
+    }
+    let mut out = BezPath::new();
+    if has_fill {
+        let kept = vectorcraft_pathops::try_boolean(
+            &vectorcraft_geom::PathData::from_bezpath(path),
+            match fill_rule {
+                FillRule::EvenOdd => vectorcraft_geom::FillRule::EvenOdd,
+                FillRule::NonZero => vectorcraft_geom::FillRule::NonZero,
+            },
+            &vectorcraft_geom::PathData::from_bezpath(region),
+            vectorcraft_geom::FillRule::NonZero,
+            vectorcraft_pathops::BoolOp::Intersect,
+            0.001,
+        )
+        .map_err(|e| e.to_string())?;
+        out.extend(kept.to_bezpath());
+    }
+    // Some callers deliberately retain geometry even when the source has no paint. Keep that
+    // geometry clip-able as linework instead of silently deleting it.
+    if has_stroke || (!has_fill && !has_stroke) {
+        let polygons: Vec<Vec<Point>> =
+            flatten_contours(region)?.into_iter().filter(|(points, closed)| *closed && points.len() >= 3).map(|(points, _)| points).collect();
+        for (mut points, closed) in flatten_contours(path)? {
+            if closed
+                && points.len() > 1
+                && points.first().zip(points.last()).is_some_and(|(first, last)| first.distance(*last) > 1e-9)
+                && let Some(first) = points.first().copied()
+            {
+                points.push(first);
+            }
+            for piece in clip_polyline(&points, &polygons, work_left, output_left)? {
+                let Some((&first, rest)) = piece.split_first() else {
+                    continue;
+                };
+                out.move_to(first);
+                for &point in rest {
+                    out.line_to(point);
+                }
+            }
+        }
+    }
+    Ok(out)
+}
+
+const MAX_CLIPPED_POINTS: usize = 500_000;
+const MAX_CLIP_WORK: usize = 5_000_000;
+
+fn flatten_contours(path: &BezPath) -> Result<Vec<(Vec<Point>, bool)>, String> {
+    flatten_contours_with_limits(path, MAX_SVG_SEGMENTS, MAX_CLIPPED_POINTS)
+}
+
+fn flatten_contours_with_limits(path: &BezPath, max_segments: usize, max_points: usize) -> Result<Vec<(Vec<Point>, bool)>, String> {
+    if path.elements().len() > max_segments {
+        return Err("path exceeds the SVG segment limit".into());
+    }
+    let bounds = path.bounding_box();
+    let tolerance = (bounds.width().max(bounds.height()) * 2e-4).max(1e-3);
+    let mut contours: Vec<(Vec<Point>, bool)> = Vec::new();
+    let mut total = 0usize;
+    vectorcraft_geom::flatten(path.iter(), tolerance, |el| {
+        total = total.saturating_add(1);
+        if total > max_points {
+            return;
+        }
+        match el {
+            PathEl::MoveTo(point) => contours.push((vec![point], false)),
+            PathEl::LineTo(point) => {
+                if let Some((points, _)) = contours.last_mut() {
+                    points.push(point);
+                }
+            }
+            PathEl::ClosePath => {
+                let start = if let Some((points, closed)) = contours.last_mut() {
+                    if let Some(first) = points.first().copied()
+                        && points.last().is_some_and(|last| last.distance(first) > 1e-9)
+                    {
+                        points.push(first);
+                    }
+                    *closed = true;
+                    points.first().copied()
+                } else {
+                    None
+                };
+                if let Some(start) = start {
+                    contours.push((vec![start], false));
+                }
+            }
+            PathEl::QuadTo(..) | PathEl::CurveTo(..) => {}
+        }
+    });
+    if total > max_points {
+        return Err(format!("path is too detailed (over {max_points} points)"));
+    }
+    for (points, _) in &mut contours {
+        points.dedup_by(|a, b| a.distance(*b) < 1e-9);
+    }
+    contours.retain(|(points, _)| points.len() > 1);
+    Ok(contours)
+}
+
+fn clip_polyline(points: &[Point], polygons: &[Vec<Point>], work_left: &mut usize, output_left: &mut usize) -> Result<Vec<Vec<Point>>, String> {
+    let mut out: Vec<Vec<Point>> = Vec::new();
+    let mut current: Vec<Point> = Vec::new();
+    let mut ts = Vec::new();
+    for segment in points.windows(2) {
+        let (a, b) = (segment[0], segment[1]);
+        ts.clear();
+        ts.push(0.0);
+        crossings(polygons, a, b, &mut ts, work_left)?;
+        ts.push(1.0);
+        ts.sort_by(f64::total_cmp);
+        for pair in ts.windows(2) {
+            let (t0, t1) = (pair[0], pair[1]);
+            if t1 - t0 < 1e-12 {
+                continue;
+            }
+            if inside_even_odd(polygons, a.lerp(b, (t0 + t1) / 2.0), work_left)? {
+                let (p0, p1) = (a.lerp(b, t0), a.lerp(b, t1));
+                if current.last().is_none_or(|last| last.distance(p0) > 1e-9) {
+                    if current.len() > 1 {
+                        out.push(std::mem::take(&mut current));
+                    }
+                    current.clear();
+                    push_clip_point(&mut current, p0, output_left)?;
+                }
+                push_clip_point(&mut current, p1, output_left)?;
+            } else if current.len() > 1 {
+                out.push(std::mem::take(&mut current));
+            } else {
+                current.clear();
+            }
+        }
+    }
+    if current.len() > 1 {
+        out.push(current);
+    }
+    Ok(out)
+}
+
+fn crossings(polygons: &[Vec<Point>], a: Point, b: Point, out: &mut Vec<f64>, work_left: &mut usize) -> Result<(), String> {
+    let direction = b - a;
+    for polygon in polygons {
+        for index in 0..polygon.len() {
+            charge_clip_work(work_left)?;
+            let (Some(p), Some(q)) = (polygon.get(index), polygon.get((index + 1) % polygon.len())) else {
+                continue;
+            };
+            let edge = *q - *p;
+            let denominator = direction.cross(edge);
+            if denominator.abs() < 1e-15 {
+                continue;
+            }
+            let offset = *p - a;
+            let t = offset.cross(edge) / denominator;
+            let u = offset.cross(direction) / denominator;
+            if t > 0.0 && t < 1.0 && (0.0..1.0).contains(&u) {
+                out.push(t);
+            }
+        }
+    }
+    Ok(())
+}
+
+fn inside_even_odd(polygons: &[Vec<Point>], point: Point, work_left: &mut usize) -> Result<bool, String> {
+    let mut odd = false;
+    for polygon in polygons {
+        for index in 0..polygon.len() {
+            charge_clip_work(work_left)?;
+            let (Some(a), Some(b)) = (polygon.get(index), polygon.get((index + 1) % polygon.len())) else {
+                continue;
+            };
+            let edge = *b - *a;
+            let relative = point - *a;
+            let length_squared = edge.dot(edge);
+            let edge_length = length_squared.sqrt();
+            if edge_length <= f64::EPSILON {
+                if relative.x.hypot(relative.y) <= 1e-9 {
+                    return Ok(true);
+                }
+                continue;
+            }
+            let tolerance = 1e-9 * edge_length.max(1.0);
+            let projection = relative.dot(edge);
+            let projection_tolerance = tolerance * edge_length;
+            if edge.cross(relative).abs() <= projection_tolerance
+                && projection >= -projection_tolerance
+                && projection <= length_squared + projection_tolerance
+            {
+                return Ok(true);
+            }
+            if (a.y > point.y) != (b.y > point.y) && point.x < a.x + (point.y - a.y) / (b.y - a.y) * (b.x - a.x) {
+                odd = !odd;
+            }
+        }
+    }
+    Ok(odd)
+}
+
+fn charge_clip_work(work_left: &mut usize) -> Result<(), String> {
+    *work_left = work_left.checked_sub(1).ok_or_else(|| "clip-path work limit exceeded".to_string())?;
+    Ok(())
+}
+
+fn push_clip_point(points: &mut Vec<Point>, point: Point, output_left: &mut usize) -> Result<(), String> {
+    *output_left = output_left.checked_sub(1).ok_or_else(|| "clip-path output point limit exceeded".to_string())?;
+    points.push(point);
+    Ok(())
+}
+
 pub const MAX_SVG_BYTES: usize = 16 * 1024 * 1024;
 pub const MAX_SVG_NODES: usize = 100_000;
 pub const MAX_SVG_DEPTH: usize = 128;
@@ -151,7 +425,7 @@ pub(crate) const MAX_CSS_SELECTOR_CHECKS: usize = 5_000_000;
 /// presentation-property cascade. Curves stay curves: nothing is flattened.
 ///
 /// Each shape carries its stroke paint as written and the `clip-path` regions that apply to it;
-/// parsing the colour and cutting the shape down to its clips are the caller's.
+/// [`Imported::clipped_path`] returns its geometry with those clips applied.
 ///
 /// What cannot be represented is skipped with a line in [`Imported::warnings`]: `<text>` (no
 /// fonts here), masks and filters (the art comes unmasked and unfiltered), ignored CSS at-rules
@@ -420,6 +694,9 @@ fn import_node<'a, 'input, K: Kind>(
             kind: state.kind.clone(),
             label: label(node),
             stroke: stroke_paint(&style),
+            has_fill: style.get("fill").is_none_or(|value| value != "none"),
+            has_stroke: style.get("stroke").is_some_and(|value| value != "none"),
+            fill_rule: if style.get("fill-rule").is_some_and(|value| value == "evenodd") { FillRule::EvenOdd } else { FillRule::NonZero },
             clips: state.clips.clone(),
             layer: state.layer.as_deref().map(str::to_string),
         });
@@ -854,7 +1131,8 @@ fn ellipse_path(cx: f64, cy: f64, rx: f64, ry: f64) -> BezPath {
 pub const MAX_CSS_BYTES: usize = 1024 * 1024;
 const MAX_CSS_RULES: usize = 10_000;
 const MAX_CSS_PROPERTIES: usize = 32;
-const SUPPORTED_STYLE_PROPERTIES: &[&str] = &["display", "visibility", "fill", "stroke", "stroke-width", "color", "clip-path", "mask", "filter"];
+const SUPPORTED_STYLE_PROPERTIES: &[&str] =
+    &["display", "visibility", "fill", "fill-rule", "stroke", "stroke-width", "color", "clip-path", "mask", "filter"];
 
 /// Whether the cascade tracks `property`: the properties above and [`Kind::PROPERTIES`].
 fn supported(extra: &[&str], property: &str) -> bool {
@@ -1644,7 +1922,6 @@ fn svg_error(path_name: &str, message: &str) -> Error {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use kurbo::Shape as _;
 
     /// A cutter's two kinds, set by `data-kind` or by class.
     #[derive(Debug, Clone, Copy, Default, PartialEq)]
@@ -1967,6 +2244,64 @@ mod tests {
         assert!(got.shapes[4].clips.is_empty());
     }
 
+    #[test]
+    fn clipped_paths_apply_piece_unions_fill_rules_and_nested_regions() {
+        let got = read(
+            r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+          <defs>
+            <clipPath id="pieces"><rect width="5" height="10"/><rect x="10" width="5" height="10"/></clipPath>
+            <clipPath id="ring"><path d="M0 0H20V20H0Z M5 5H15V15H5Z" clip-rule="evenodd"/></clipPath>
+            <clipPath id="left"><rect width="15" height="10"/></clipPath>
+            <clipPath id="right"><rect x="10" width="10" height="10"/></clipPath>
+            <clipPath id="empty"/>
+          </defs>
+          <rect id="piece-union" width="20" height="10" clip-path="url(#pieces)"/>
+          <rect id="evenodd-ring" width="20" height="20" clip-path="url(#ring)"/>
+          <g clip-path="url(#left)"><line id="nested-open" x1="0" y1="5" x2="20" y2="5" stroke="black" clip-path="url(#right)"/></g>
+          <line id="open" x1="0" y1="5" x2="20" y2="5" stroke="black" clip-path="url(#left)"/>
+          <line id="boundary" x1="15" y1="2" x2="15" y2="8" stroke="black" clip-path="url(#pieces)"/>
+          <path id="unpainted" d="M0 5H20" data-kind="engrave" fill="none" stroke="none" clip-path="url(#left)"/>
+          <rect id="empty-result" width="20" height="10" clip-path="url(#empty)"/>
+        </svg>"##,
+        );
+
+        let clipped = |label: &str| {
+            let shape = got.shapes.iter().find(|shape| shape.label == label).unwrap();
+            got.clipped_path(shape).unwrap()
+        };
+        let union = clipped(r#"<rect id="piece-union">"#);
+        assert_eq!(union.bounding_box(), kurbo::Rect::new(0.0, 0.0, 15.0, 10.0));
+        assert_eq!(union.elements().iter().filter(|el| matches!(el, PathEl::ClosePath)).count(), 2);
+
+        let ring = clipped(r#"<rect id="evenodd-ring">"#);
+        assert_eq!(ring.bounding_box(), kurbo::Rect::new(0.0, 0.0, 20.0, 20.0));
+        assert_eq!(ring.elements().iter().filter(|el| matches!(el, PathEl::ClosePath)).count(), 2);
+
+        let nested = clipped(r#"<line id="nested-open">"#);
+        assert!(near(nested.bounding_box().x0, 10.0) && near(nested.bounding_box().x1, 15.0));
+        let open = clipped(r#"<line id="open">"#);
+        assert!(near(open.bounding_box().x0, 0.0) && near(open.bounding_box().x1, 15.0));
+        let boundary = clipped(r#"<line id="boundary">"#);
+        assert!(near(boundary.bounding_box().x0, 15.0) && near(boundary.bounding_box().x1, 15.0));
+        let unpainted = clipped(r#"<path id="unpainted">"#);
+        assert!(near(unpainted.bounding_box().x0, 0.0) && near(unpainted.bounding_box().x1, 15.0));
+        assert!(clipped(r#"<rect id="empty-result">"#).elements().is_empty());
+
+        let mut invalid = got.clone();
+        invalid.shapes[0].clips.push(usize::MAX);
+        assert!(invalid.clipped_path(&invalid.shapes[0]).is_err());
+    }
+
+    #[test]
+    fn clipped_path_flattening_enforces_segment_and_point_bounds() {
+        let mut path = kurbo::BezPath::new();
+        path.move_to(kurbo::Point::ZERO);
+        path.line_to(kurbo::Point::new(1.0, 0.0));
+        path.line_to(kurbo::Point::new(2.0, 0.0));
+        assert!(flatten_contours_with_limits(&path, 2, 100).is_err());
+        assert!(flatten_contours_with_limits(&path, 100, 2).is_err());
+    }
+
     #[test]
     fn clip_paths_that_cannot_be_applied_warn_and_leave_the_shape_unclipped() {
         for (svg, needle) in [
diff --git a/crates/svg/src/write.rs b/crates/svg/src/write.rs
index 614642de5..469a4f8fa 100644
--- a/crates/svg/src/write.rs
+++ b/crates/svg/src/write.rs
@@ -30,6 +30,161 @@ use kurbo::{BezPath, PathEl, Point};
 /// The SVG namespace.
 pub const SVG_NS: &str = "http://www.w3.org/2000/svg";
 
+/// A structured SVG scene. Applications provide geometry, styles and attributes; this module
+/// owns the SVG element tree and serializes it with XML escaping.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Scene {
+    pub width_mm: f64,
+    pub height_mm: f64,
+    pub view_box: [f64; 4],
+    pub elements: Vec<Element>,
+}
+
+/// Structured SVG elements supported by the path-document writer.
+#[derive(Clone, Debug, PartialEq)]
+pub enum Element {
+    Group { attributes: Vec<Attribute>, children: Vec<Element> },
+    Path { attributes: Vec<Attribute>, path: BezPath },
+    Rect { attributes: Vec<Attribute>, x: f64, y: f64, width: f64, height: f64 },
+    Text { attributes: Vec<Attribute>, x: f64, y: f64, text: String },
+    Title(String),
+    Style(String),
+    NestedSvg { attributes: Vec<Attribute>, children: Vec<Element> },
+}
+
+/// An escaped SVG attribute. Element names and attribute names are API constants and must be
+/// valid XML names; values are always escaped by the shared writer.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Attribute {
+    pub name: String,
+    pub value: Value,
+}
+
+/// Attribute values written by the shared serializer.
+#[derive(Clone, Debug, PartialEq)]
+pub enum Value {
+    Text(String),
+    Number(f64),
+    Millimetres(f64),
+    ViewBox([f64; 4]),
+    TranslateScale { x: f64, y: f64, scale_x: f64, scale_y: f64 },
+}
+
+impl Attribute {
+    pub fn text(name: impl Into<String>, value: impl Into<String>) -> Self {
+        Self { name: name.into(), value: Value::Text(value.into()) }
+    }
+    pub fn number(name: impl Into<String>, value: f64) -> Self {
+        Self { name: name.into(), value: Value::Number(value) }
+    }
+    pub fn millimetres(name: impl Into<String>, value: f64) -> Self {
+        Self { name: name.into(), value: Value::Millimetres(value) }
+    }
+    pub fn view_box(bounds: [f64; 4]) -> Self {
+        Self { name: "viewBox".into(), value: Value::ViewBox(bounds) }
+    }
+    pub fn translate_scale(x: f64, y: f64, scale_x: f64, scale_y: f64) -> Self {
+        Self { name: "transform".into(), value: Value::TranslateScale { x, y, scale_x, scale_y } }
+    }
+}
+
+impl Scene {
+    /// Serialize the scene as an SVG 1.1 document.
+    pub fn write(&self) -> String {
+        let mut writer = SvgWriter::new();
+        writer
+            .root()
+            .attr("version", "1.1")
+            .attr("width", format!("{}mm", num(self.width_mm, 3)))
+            .attr("height", format!("{}mm", num(self.height_mm, 3)))
+            .attr("viewBox", view_box_data(self.view_box))
+            .open();
+        write_elements(&mut writer, &self.elements, 1);
+        writer.line(0);
+        writer.close();
+        writer.finish()
+    }
+}
+
+fn write_attributes<'a>(mut tag: craft_xml::Tag<'a>, attributes: &'a [Attribute]) -> craft_xml::Tag<'a> {
+    // SVG consumers disagree about duplicate attributes; make the last supplied value win.
+    for (index, attribute) in attributes.iter().enumerate() {
+        if attributes[index + 1..].iter().any(|later| later.name == attribute.name) {
+            continue;
+        }
+        tag = match &attribute.value {
+            Value::Text(value) => tag.attr(&attribute.name, value),
+            Value::Number(value) => tag.attr(&attribute.name, num(*value, 3)),
+            Value::Millimetres(value) => tag.attr(&attribute.name, format!("{}mm", num(*value, 3))),
+            Value::ViewBox(bounds) => tag.attr(&attribute.name, view_box_data(*bounds)),
+            Value::TranslateScale { x, y, scale_x, scale_y } => {
+                tag.attr(&attribute.name, format!("translate({} {}) scale({} {})", num(*x, 3), num(*y, 3), shortest(*scale_x), shortest(*scale_y)))
+            }
+        };
+    }
+    tag
+}
+
+fn shortest(value: f64) -> String {
+    if value.is_finite() { value.to_string() } else { "0".into() }
+}
+
+fn write_elements(writer: &mut SvgWriter, elements: &[Element], depth: usize) {
+    for element in elements {
+        writer.line(depth);
+        match element {
+            Element::Group { attributes, children } => {
+                write_attributes(writer.tag("g"), attributes).open();
+                write_elements(writer, children, depth + 1);
+                writer.line(depth);
+                writer.close();
+            }
+            Element::Path { attributes, path } => {
+                let mut attrs = vec![Attribute::text("d", path_data(path))];
+                attrs.extend(attributes.iter().cloned());
+                write_attributes(writer.tag("path"), &attrs).empty();
+            }
+            Element::Rect { attributes, x, y, width, height } => {
+                let mut attrs = vec![
+                    Attribute::number("x", *x),
+                    Attribute::number("y", *y),
+                    Attribute::number("width", *width),
+                    Attribute::number("height", *height),
+                ];
+                attrs.extend(attributes.iter().cloned());
+                write_attributes(writer.tag("rect"), &attrs).empty();
+            }
+            Element::Text { attributes, x, y, text } => {
+                let mut attrs = vec![Attribute::number("x", *x), Attribute::number("y", *y)];
+                attrs.extend(attributes.iter().cloned());
+                write_attributes(writer.tag("text"), &attrs).open();
+                writer.text(text);
+                writer.close();
+            }
+            Element::Title(text) => {
+                writer.tag("title").open();
+                writer.text(text);
+                writer.close();
+            }
+            Element::Style(css) => {
+                writer.tag("style").open();
+                writer.text(css);
+                writer.close();
+            }
+            Element::NestedSvg { attributes, children } => {
+                write_attributes(writer.tag("svg"), attributes).open();
+                write_elements(writer, children, depth + 1);
+                writer.line(depth);
+                writer.close();
+            }
+        }
+    }
+}
+
+fn view_box_data(bounds: [f64; 4]) -> String {
+    format!("{} {} {} {}", shortest(bounds[0]), shortest(bounds[1]), shortest(bounds[2]), shortest(bounds[3]))
+}
+
 /// A number written with a fixed count of decimals. A value that is not finite is written as
 /// zero, because SVG has no spelling for it.
 #[derive(Debug, Clone, Copy, PartialEq)]
diff --git a/crates/time/Cargo.toml b/crates/time/Cargo.toml
new file mode 100644
index 000000000..5ef614bdc
--- /dev/null
+++ b/crates/time/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+name = "craft-time"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+description = "Exact media time, frame rate rational math, and SMPTE timecode for the Craft suite"
+
+[lints]
+workspace = true
+
+[dependencies]
+serde = { workspace = true }
+thiserror.workspace = true
+
+[dev-dependencies]
+serde_json = { workspace = true }
+proptest = "1.4"
diff --git a/crates/time/README.md b/crates/time/README.md
new file mode 100644
index 000000000..9c85b0219
--- /dev/null
+++ b/crates/time/README.md
@@ -0,0 +1,119 @@
+# Craft Time
+
+`craft-time` provides exact, drift-free media time representation, rational frame-rate mathematics, SMPTE timecode formatting/parsing, and film footage calculations for the Craft suite.
+
+Extracted from the common time engine in **FilmCraft** and **EffectCraft** (refs #2), it is designed for NLEs, motion graphics compositors, audio workstations, and media transcoders.
+
+## Core Concepts
+
+### Exact Ticks (`TICKS_PER_SECOND`)
+
+All media time is tracked as an integer number of clock ticks at:
+
+$$\text{TICKS\_PER\_SECOND} = 254{,}016{,}000{,}000 \text{ ticks/s}$$
+
+This rate was chosen because it divides evenly into every broadcast and cinematic frame rate, as well as every standard professional audio sample rate:
+
+- **Frame Rates**: 23.976, 24, 25, 29.97, 30, 48, 50, 59.94, 60, 119.88, 120 fps.
+- **Audio Sample Rates**: 32 kHz, 44.1 kHz, 48 kHz, 88.2 kHz, 96 kHz, 192 kHz.
+
+Edits, clip slicing, frame stepping, and audio/video alignment never suffer cumulative floating-point drift.
+
+```rust
+use craft_time::{Tick, TICKS_PER_SECOND};
+
+// Convert from seconds or sample units
+let one_sec = Tick::from_seconds_f64(1.0);
+assert_eq!(one_sec.0, TICKS_PER_SECOND);
+
+let audio_sample = Tick::from_units(48000, 48000);
+assert_eq!(audio_sample, one_sec);
+```
+
+### Rational Frame Rates (`FrameRate`)
+
+Frame rates are represented as exact fractions (`num / den`):
+
+```rust
+use craft_time::{FrameRate, Tick};
+
+// Standard NTSC and PAL rates
+let ntsc_24 = FrameRate::FPS_23_976; // 24000 / 1001
+let pal_25 = FrameRate::FPS_25;      // 25 / 1
+let ntsc_30 = FrameRate::FPS_29_97;  // 30000 / 1001
+
+// Start tick of frame 100
+let start_tick = ntsc_30.tick_of(100);
+
+// Frame containing a tick (floored)
+let frame = ntsc_30.frame_at(start_tick);
+assert_eq!(frame, 100);
+
+// Snap to exact frame boundaries
+let snapped = ntsc_30.snap(start_tick + Tick(5));
+assert_eq!(snapped, start_tick);
+```
+
+### SMPTE Timecode (`format_timecode_frames` / `parse_timecode`)
+
+Full support for SMPTE standard drop-frame (semicolon `;` separator) and non-drop frame (colon `:` separator) timecode:
+
+```rust
+use craft_time::{FrameRate, format_timecode_frames, parse_timecode};
+
+let r = FrameRate::FPS_29_97;
+
+// Format frame count to drop-frame timecode
+let tc = format_timecode_frames(1800, r, true);
+assert_eq!(tc, "00;01;00;02"); // Frames 00 and 01 dropped at minute mark
+
+// Parse user-entered timecode (supports relative offsets like +15 or -1.00)
+let parsed = parse_timecode("00;01;00;02", r, true, 0).unwrap();
+assert_eq!(parsed, 1800);
+```
+
+### Film Footage (`format_feet_frames` / `parse_feet_frames`)
+
+Calculates 35mm (16 frames/foot) and 16mm (40 frames/foot) film footage counts:
+
+```rust
+use craft_time::{format_feet_frames, parse_feet_frames};
+
+// 35mm (16 frames per foot)
+assert_eq!(format_feet_frames(199, 16), "0012+07");
+assert_eq!(parse_feet_frames("12+07", 16, 0), Ok(199));
+
+// 16mm (40 frames per foot)
+assert_eq!(format_feet_frames(95, 40), "0002+15");
+assert_eq!(parse_feet_frames("2+15", 40, 0), Ok(95));
+```
+
+## SoundCraft Sample-Time Compatibility
+
+The `soundcraft` module carries SoundCraft's existing sample-index clock (`i64` samples at the
+session sample rate), `SampleRate`, `TempoMap`, grid calculations and five timebase parsers and
+formatters. It keeps the serialized representation and existing saturation, sanitization and
+rounding behavior intact while the rest of the suite can use exact `Tick` values. SoundCraft's
+session model imports these types from `craft_time::soundcraft`; the APIs in that module retain
+the original SoundCraft names and meanings.
+
+## EffectCraft & FilmCraft Compatibility Differences
+
+`craft-time` unifies time representation across the Craft suite while explicitly documenting application-specific design choices:
+
+1. **After Effects Display Formatting**:
+   FilmCraft uses standard broadcast SMPTE zero-padded hours (`00:00:02:15` via `format_timecode_frames`).
+   EffectCraft / After Effects displays hours without leading zeroes (`0:00:02:15` via `format_timecode_ae`). Both functions are provided.
+2. **Oversized Timecode Saturation**:
+   In `craft-time`, `parse_timecode` employs saturating arithmetic (`saturating_mul`, `saturating_add`) when frame calculations exceed 64-bit limits, saturating to `i64::MAX` or `i64::MIN` to keep operations total without unrecoverable errors. In contrast, EffectCraft returns `Err(ParseError("timecode too large"))`.
+3. **Degenerate `{0, 0}` Frame Rates**:
+   In `craft-time`, `FrameRate::sane()` normalizes non-positive or zero rates (such as `{ num: 0, den: 0 }` or negative denominators) to `FrameRate::FPS_23_976` (nominal timecode base 24), maintaining standard broadcast defaults. In contrast, EffectCraft falls back to a timecode base of 1.
+4. **Monotonic Operator Division**:
+   Operator division on `Tick` (`Tick / i64`) and `Tick::saturating_div` saturate on overflow (`Tick(i64::MIN) / -1 -> Tick(i64::MAX)`), preserving strict mathematical monotonicity across the entire signed 64-bit range without inflection.
+
+## Guarantees & Doctrines
+
+- **Zero App Code**: Zero dependencies on application crates.
+- **Never Crash**: `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]`.
+- **Total Arithmetic**: Division by zero or hostile rates from damaged projects return well-defined fallback states rather than panicking. Arithmetic saturates at 64-bit limits with 128-bit intermediate checks.
+- **Forbid Unsafe**: `#![forbid(unsafe_code)]`.
diff --git a/crates/time/src/lib.rs b/crates/time/src/lib.rs
new file mode 100644
index 000000000..4a3af58df
--- /dev/null
+++ b/crates/time/src/lib.rs
@@ -0,0 +1,918 @@
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+
+//! Exact media time for the Craft suite.
+//!
+//! All time is an integer number of [`Tick`]s at [`TICKS_PER_SECOND`] = 254 016 000 000/s. That
+//! rate divides evenly into every broadcast frame duration (23.976, 24, 25, 29.97, 30, 48, 50,
+//! 59.94, 60, 119.88, 120 fps) and standard audio sample rates (44.1 kHz, 48 kHz, and their
+//! multiples), so edits, frame math, audio alignment, and visual effects never drift.
+//!
+//! Timecode (SMPTE drop/non-drop, frames, feet+frames, audio samples) is a display representation
+//! of ticks. Every conversion is total: invalid, zero, or negative rates produce well-defined defaults
+//! rather than division-by-zero panics.
+
+use serde::{Deserialize, Serialize};
+use std::fmt;
+use std::ops::{Add, AddAssign, Div, Mul, Neg, Rem, Sub, SubAssign};
+
+/// SoundCraft's sample-index, tempo-map, grid, and display-time API, retained verbatim for
+/// session-format compatibility while sharing the broader Craft time primitives above.
+pub mod soundcraft;
+
+/// Clock ticks per second: 254 016 000 000.
+pub const TICKS_PER_SECOND: i64 = 254_016_000_000;
+
+/// A point or duration in time, in ticks.
+/// Arithmetic saturates at storage limits; representable results remain exact.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct Tick(pub i64);
+
+impl Tick {
+    pub const ZERO: Tick = Tick(0);
+    pub const MAX: Tick = Tick(i64::MAX / 4);
+    pub const MIN: Tick = Tick(i64::MIN / 4);
+
+    /// Seconds to ticks, clamped to [`Tick::MIN`]..=[`Tick::MAX`].
+    pub fn from_seconds_f64(s: f64) -> Tick {
+        Tick((s * TICKS_PER_SECOND as f64).round() as i64)
+    }
+
+    pub fn seconds(self) -> f64 {
+        self.0 as f64 / TICKS_PER_SECOND as f64
+    }
+
+    /// Exact conversion from a count of `units` at `per_second` (e.g. samples at 48 000).
+    pub fn from_units(units: i64, per_second: i64) -> Tick {
+        Tick(clamp_i64((units as i128 * TICKS_PER_SECOND as i128).checked_div(per_second as i128).unwrap_or(0)))
+    }
+
+    /// Floor conversion to a count of units at `per_second`.
+    pub fn to_units_floor(self, per_second: i64) -> i64 {
+        clamp_i64((self.0 as i128 * per_second as i128).div_euclid(TICKS_PER_SECOND as i128))
+    }
+
+    /// Conversion from a rational timestamp `pts * num / den` seconds (container timebases).
+    pub fn from_rational(pts: i64, num: i64, den: i64) -> Tick {
+        if den == 0 {
+            return Tick::ZERO;
+        }
+        let Some(t) = (pts as i128 * num as i128).checked_mul(TICKS_PER_SECOND as i128) else {
+            return Tick(if (pts < 0) ^ (num < 0) ^ (den < 0) { i64::MIN } else { i64::MAX });
+        };
+        Tick(clamp_i64(t.div_euclid(den as i128)))
+    }
+
+    /// Inverse of [`Tick::from_rational`], floored to the timebase.
+    pub fn to_rational_floor(self, num: i64, den: i64) -> i64 {
+        clamp_i64((self.0 as i128 * den as i128).checked_div_euclid(num as i128 * TICKS_PER_SECOND as i128).unwrap_or(0))
+    }
+
+    /// Inverse of [`Tick::from_rational`], rounded to the nearest timebase unit (halves up).
+    pub fn to_rational_round(self, num: i64, den: i64) -> i64 {
+        let n = self.0 as i128 * den as i128;
+        let unit = num as i128 * TICKS_PER_SECOND as i128;
+        let (n, unit) = if unit < 0 { (-n, -unit) } else { (n, unit) };
+        let (Some(q), Some(r)) = (n.checked_div_euclid(unit), n.checked_rem_euclid(unit)) else { return 0 };
+        clamp_i64(if r * 2 >= unit { q + 1 } else { q })
+    }
+
+    pub fn abs(self) -> Tick {
+        Tick(self.0.saturating_abs())
+    }
+
+    pub fn signum(self) -> i64 {
+        self.0.signum()
+    }
+
+    pub fn min(self, o: Tick) -> Tick {
+        Tick(self.0.min(o.0))
+    }
+
+    pub fn max(self, o: Tick) -> Tick {
+        Tick(self.0.max(o.0))
+    }
+
+    pub fn clamp(self, lo: Tick, hi: Tick) -> Tick {
+        Tick(self.0.max(lo.0).min(hi.0))
+    }
+
+    /// Scale by a rational factor (`num/den`), flooring.
+    pub fn mul_ratio(self, num: i64, den: i64) -> Tick {
+        Tick(clamp_i64((self.0 as i128 * num as i128).checked_div_euclid(den as i128).unwrap_or(0)))
+    }
+
+    /// Divide by a rational factor (`num/den`), flooring.
+    pub fn div_ratio(self, num: i64, den: i64) -> Tick {
+        self.mul_ratio(den, num)
+    }
+
+    /// Checked addition. Returns `None` if overflow occurred.
+    pub fn checked_add(self, rhs: Tick) -> Option<Tick> {
+        self.0.checked_add(rhs.0).map(Tick)
+    }
+
+    /// Checked subtraction. Returns `None` if overflow occurred.
+    pub fn checked_sub(self, rhs: Tick) -> Option<Tick> {
+        self.0.checked_sub(rhs.0).map(Tick)
+    }
+
+    /// Checked multiplication. Returns `None` if overflow occurred.
+    pub fn checked_mul(self, rhs: i64) -> Option<Tick> {
+        self.0.checked_mul(rhs).map(Tick)
+    }
+
+    /// Checked division. Returns `None` if `rhs == 0` or if overflow occurred (`Tick(i64::MIN) / -1`).
+    pub fn checked_div(self, rhs: i64) -> Option<Tick> {
+        self.0.checked_div(rhs).map(Tick)
+    }
+
+    /// Checked remainder. Returns `None` if `rhs.0 == 0` or if overflow occurred (`Tick(i64::MIN) % Tick(-1)`).
+    pub fn checked_rem(self, rhs: Tick) -> Option<Tick> {
+        self.0.checked_rem(rhs.0).map(Tick)
+    }
+
+    /// Saturating addition.
+    pub fn saturating_add(self, rhs: Tick) -> Tick {
+        Tick(self.0.saturating_add(rhs.0))
+    }
+
+    /// Saturating subtraction.
+    pub fn saturating_sub(self, rhs: Tick) -> Tick {
+        Tick(self.0.saturating_sub(rhs.0))
+    }
+
+    /// Saturating multiplication.
+    pub fn saturating_mul(self, rhs: i64) -> Tick {
+        Tick(self.0.saturating_mul(rhs))
+    }
+
+    /// Saturating division. Returns `None` if `rhs == 0`, and saturates on overflow (`Tick(i64::MIN) / -1 -> Tick(i64::MAX)`).
+    pub fn saturating_div(self, rhs: i64) -> Option<Tick> {
+        if rhs == 0 { None } else { Some(Tick(self.0.saturating_div(rhs))) }
+    }
+}
+
+impl Add for Tick {
+    type Output = Tick;
+    fn add(self, o: Tick) -> Tick {
+        Tick(self.0.saturating_add(o.0))
+    }
+}
+
+impl Sub for Tick {
+    type Output = Tick;
+    fn sub(self, o: Tick) -> Tick {
+        Tick(self.0.saturating_sub(o.0))
+    }
+}
+
+impl Neg for Tick {
+    type Output = Tick;
+    fn neg(self) -> Tick {
+        Tick(self.0.saturating_neg())
+    }
+}
+
+impl AddAssign for Tick {
+    fn add_assign(&mut self, o: Tick) {
+        self.0 = self.0.saturating_add(o.0);
+    }
+}
+
+impl SubAssign for Tick {
+    fn sub_assign(&mut self, o: Tick) {
+        self.0 = self.0.saturating_sub(o.0);
+    }
+}
+
+impl Mul<i64> for Tick {
+    type Output = Tick;
+    fn mul(self, rhs: i64) -> Tick {
+        Tick(self.0.saturating_mul(rhs))
+    }
+}
+
+impl Div<i64> for Tick {
+    type Output = Tick;
+    fn div(self, rhs: i64) -> Tick {
+        // Operator division policy: Div saturates on overflow (e.g. Tick(i64::MIN) / -1 -> Tick(i64::MAX))
+        // using self.0.saturating_div(rhs) to preserve monotonicity across the full range.
+        // Division by zero yields Tick::ZERO. For fallible division that detects zero divisors,
+        // use Tick::checked_div().
+        if rhs == 0 { Tick::ZERO } else { Tick(self.0.saturating_div(rhs)) }
+    }
+}
+
+impl Rem<Tick> for Tick {
+    type Output = Tick;
+    fn rem(self, rhs: Tick) -> Tick {
+        // Operator remainder policy: Rem produces exact remainder where defined,
+        // and Tick::ZERO for zero divisor or Tick(i64::MIN) % Tick(-1) (which is mathematically 0).
+        // For fallible remainder, use Tick::checked_rem().
+        if rhs.0 == 0 || (self.0 == i64::MIN && rhs.0 == -1) { Tick::ZERO } else { Tick(self.0 % rhs.0) }
+    }
+}
+
+impl fmt::Display for Tick {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{} ticks", self.0)
+    }
+}
+
+/// A half-open time range `[start, start + duration)`.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct TimeRange {
+    pub start: Tick,
+    pub duration: Tick,
+}
+
+impl TimeRange {
+    pub fn new(start: Tick, duration: Tick) -> Self {
+        Self { start, duration }
+    }
+
+    pub fn from_bounds(start: Tick, end: Tick) -> Self {
+        Self { start, duration: end - start }
+    }
+
+    pub fn end(&self) -> Tick {
+        self.start + self.duration
+    }
+
+    pub fn contains(&self, t: Tick) -> bool {
+        t >= self.start && t < self.end()
+    }
+
+    pub fn overlaps(&self, o: &TimeRange) -> bool {
+        !self.is_empty() && !o.is_empty() && self.start < o.end() && o.start < self.end()
+    }
+
+    pub fn intersect(&self, o: &TimeRange) -> Option<TimeRange> {
+        let s = self.start.max(o.start);
+        let e = self.end().min(o.end());
+        (e > s).then(|| TimeRange::from_bounds(s, e))
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.duration.0 <= 0
+    }
+}
+
+/// A frame rate as an exact rational (`num / den` frames per second).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct FrameRate {
+    pub num: i64,
+    pub den: i64,
+}
+
+impl Default for FrameRate {
+    fn default() -> Self {
+        FrameRate::FPS_23_976
+    }
+}
+
+impl FrameRate {
+    pub const FPS_23_976: FrameRate = FrameRate { num: 24000, den: 1001 };
+    pub const FPS_24: FrameRate = FrameRate { num: 24, den: 1 };
+    pub const FPS_25: FrameRate = FrameRate { num: 25, den: 1 };
+    pub const FPS_29_97: FrameRate = FrameRate { num: 30000, den: 1001 };
+    pub const FPS_30: FrameRate = FrameRate { num: 30, den: 1 };
+    pub const FPS_48: FrameRate = FrameRate { num: 48, den: 1 };
+    pub const FPS_50: FrameRate = FrameRate { num: 50, den: 1 };
+    pub const FPS_59_94: FrameRate = FrameRate { num: 60000, den: 1001 };
+    pub const FPS_60: FrameRate = FrameRate { num: 60, den: 1 };
+    pub const FPS_119_88: FrameRate = FrameRate { num: 120000, den: 1001 };
+    pub const FPS_120: FrameRate = FrameRate { num: 120, den: 1 };
+
+    /// Standard broadcast and cinematic rates.
+    pub const COMMON: [FrameRate; 11] = [
+        Self::FPS_23_976,
+        Self::FPS_24,
+        Self::FPS_25,
+        Self::FPS_29_97,
+        Self::FPS_30,
+        Self::FPS_48,
+        Self::FPS_50,
+        Self::FPS_59_94,
+        Self::FPS_60,
+        Self::FPS_119_88,
+        Self::FPS_120,
+    ];
+
+    pub fn new(num: i64, den: i64) -> Self {
+        let g = i128::from(gcd(num.unsigned_abs(), den.unsigned_abs()).max(1));
+        FrameRate { num: (i128::from(num) / g) as i64, den: (i128::from(den) / g) as i64 }
+    }
+
+    /// Closest standard rate for a floating-point frame rate.
+    pub fn from_f64(fps: f64) -> Self {
+        for r in Self::COMMON {
+            if (r.as_f64() - fps).abs() < 0.005 {
+                return r;
+            }
+        }
+        FrameRate::new((fps * 1000.0).round() as i64, 1000)
+    }
+
+    /// Closest standard rate when `fps` is within `tolerance` of it, otherwise the nearest
+    /// 1/1000 rate. This retains the timeline API's coarse-timebase compatibility behavior.
+    pub fn from_f64_within(fps: f64, tolerance: f64) -> Self {
+        let mut best: Option<(f64, FrameRate)> = None;
+        for rate in Self::COMMON {
+            let off = (rate.as_f64() - fps).abs();
+            if off <= tolerance * rate.as_f64() && best.is_none_or(|(closest, _)| off < closest) {
+                best = Some((off, rate));
+            }
+        }
+        best.map_or_else(|| Self::from_f64(fps), |(_, rate)| rate)
+    }
+
+    /// Returns this frame rate if positive, or the default rate ([`FrameRate::FPS_23_976`]).
+    ///
+    /// ### Application Compatibility Note
+    /// For non-positive or zero rates (e.g. `{0, 0}`), `craft-time` falls back to
+    /// [`FrameRate::FPS_23_976`] (timecode base 24), providing a standard broadcast default.
+    /// In contrast, EffectCraft falls back to timecode base 1.
+    pub fn sane(self) -> FrameRate {
+        if self.num > 0 && self.den > 0 { self } else { FrameRate::default() }
+    }
+
+    pub fn as_f64(self) -> f64 {
+        self.num as f64 / self.den as f64
+    }
+
+    /// Exact duration of one frame (floored for exotic rates).
+    pub fn frame_duration(self) -> Tick {
+        let r = self.sane();
+        Tick(clamp_i64((TICKS_PER_SECOND as i128 * r.den as i128) / r.num as i128))
+    }
+
+    /// Index of the frame containing `t` (floor).
+    pub fn frame_at(self, t: Tick) -> i64 {
+        clamp_i64(frame_index(self.sane(), t))
+    }
+
+    /// Frames from `start` to `end`, counted between their frame indices.
+    pub fn frames_between(self, start: Tick, end: Tick) -> i64 {
+        self.frame_at(end).saturating_sub(self.frame_at(start))
+    }
+
+    /// Start tick of frame `f` (ceiling division).
+    pub fn tick_of(self, f: i64) -> Tick {
+        Tick(clamp_i64(frame_boundary(self.sane(), i128::from(f))))
+    }
+
+    /// Snap `t` down to a frame boundary.
+    pub fn snap(self, t: Tick) -> Tick {
+        let r = self.sane();
+        Tick(clamp_i64(frame_boundary(r, frame_index(r, t))))
+    }
+
+    /// Snap `t` to the nearest frame boundary.
+    pub fn snap_nearest(self, t: Tick) -> Tick {
+        let r = self.sane();
+        let f = frame_index(r, t);
+        let a = frame_boundary(r, f);
+        let b = frame_boundary(r, f.saturating_add(1));
+        let t = i128::from(t.0);
+        Tick(clamp_i64(if t - a <= b - t { a } else { b }))
+    }
+
+    /// Timecode base (nominal frames per second): 30 for 29.97, 24 for 23.976.
+    pub fn timecode_base(self) -> i64 {
+        let r = self.sane();
+        (r.num / r.den).saturating_add(i64::from(r.num % r.den != 0)).max(1)
+    }
+
+    pub fn is_ntsc(self) -> bool {
+        self.den == 1001
+    }
+
+    pub fn supports_drop_frame(self) -> bool {
+        self.is_ntsc() && self.timecode_base() % 30 == 0
+    }
+
+    pub fn label(self) -> String {
+        if self.den == 1 {
+            format!("{}", self.num)
+        } else {
+            let v = self.as_f64();
+            let s = format!("{v:.3}");
+            s.trim_end_matches('0').trim_end_matches('.').to_string()
+        }
+    }
+}
+
+impl fmt::Display for FrameRate {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{} fps", self.label())
+    }
+}
+
+fn clamp_i64(value: i128) -> i64 {
+    value.clamp(i128::from(i64::MIN), i128::from(i64::MAX)) as i64
+}
+
+fn frame_index(rate: FrameRate, t: Tick) -> i128 {
+    (i128::from(t.0) * i128::from(rate.num)).div_euclid(i128::from(TICKS_PER_SECOND) * i128::from(rate.den))
+}
+
+fn frame_boundary(rate: FrameRate, frame: i128) -> i128 {
+    let Some(n) = frame.checked_mul(i128::from(TICKS_PER_SECOND)).and_then(|n| n.checked_mul(i128::from(rate.den))) else {
+        return if frame < 0 { i128::MIN } else { i128::MAX };
+    };
+    let d = i128::from(rate.num);
+    n.div_euclid(d) + i128::from(n.rem_euclid(d) != 0)
+}
+
+fn gcd(mut a: u64, mut b: u64) -> u64 {
+    while b != 0 {
+        (a, b) = (b, a % b);
+    }
+    a
+}
+
+/// How time is formatted for display.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum TimeDisplay {
+    #[default]
+    Timecode,
+    Frames,
+    Feet16,
+    Feet35,
+    AudioSamples,
+    Seconds,
+}
+
+impl TimeDisplay {
+    pub const ALL: [TimeDisplay; 6] =
+        [TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames, TimeDisplay::AudioSamples, TimeDisplay::Seconds];
+
+    /// The video display formats (Sequence Settings ▸ Display Format, the burn-in's Time Format).
+    pub const VIDEO: [TimeDisplay; 4] = [TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames];
+
+    pub fn label(self) -> &'static str {
+        match self {
+            TimeDisplay::Timecode => "Timecode",
+            TimeDisplay::Frames => "Frames",
+            TimeDisplay::Feet16 => "Feet + Frames 16mm",
+            TimeDisplay::Feet35 => "Feet + Frames 35mm",
+            TimeDisplay::AudioSamples => "Audio Samples",
+            TimeDisplay::Seconds => "Seconds",
+        }
+    }
+
+    /// Stable id used by commands and the UI.
+    pub fn id(self) -> &'static str {
+        match self {
+            TimeDisplay::Timecode => "timecode",
+            TimeDisplay::Frames => "frames",
+            TimeDisplay::Feet16 => "feet16",
+            TimeDisplay::Feet35 => "feet35",
+            TimeDisplay::AudioSamples => "samples",
+            TimeDisplay::Seconds => "seconds",
+        }
+    }
+
+    /// The display with this [`id`](Self::id), ignoring case.
+    pub fn from_id(id: &str) -> Option<TimeDisplay> {
+        TimeDisplay::ALL.into_iter().find(|display| display.id().eq_ignore_ascii_case(id))
+    }
+
+    /// Frames per foot for the Feet + Frames displays.
+    pub fn frames_per_foot(self) -> Option<i64> {
+        match self {
+            TimeDisplay::Feet35 => Some(16),
+            TimeDisplay::Feet16 => Some(40),
+            _ => None,
+        }
+    }
+}
+
+fn df_params(rate: FrameRate) -> (i64, i64) {
+    let base = rate.timecode_base();
+    (base / 15, base)
+}
+
+/// Convert a frame count to SMPTE fields `(negative, h, m, s, f)`.
+pub fn frames_to_fields(frame: i64, rate: FrameRate, drop_frame: bool) -> (bool, i64, i64, i64, i64) {
+    let neg = frame < 0;
+    let mut n = i128::from(frame).abs();
+    let (drop, base) = df_params(rate);
+    let (drop, base) = (i128::from(drop), i128::from(base));
+    if drop_frame && rate.supports_drop_frame() {
+        let per_min = base * 60 - drop;
+        let per_10 = per_min * 10 + drop;
+        let d = n / per_10;
+        let m = n % per_10;
+        n = n.saturating_add(drop * 9 * d);
+        if m > drop {
+            n = n.saturating_add(drop * ((m - drop) / per_min));
+        }
+    }
+    let f = n % base;
+    let s = (n / base) % 60;
+    let mi = (n / (base * 60)) % 60;
+    let h = n / (base * 3600);
+    (neg, clamp_i64(h), clamp_i64(mi), clamp_i64(s), clamp_i64(f))
+}
+
+/// Convert SMPTE fields back to a frame count.
+pub fn fields_to_frames(h: i64, m: i64, s: i64, f: i64, rate: FrameRate, drop_frame: bool) -> i64 {
+    let (drop, base) = df_params(rate);
+    let seconds = i128::from(h) * 3600 + i128::from(m) * 60 + i128::from(s);
+    let mut n = seconds.saturating_mul(i128::from(base)).saturating_add(i128::from(f));
+    if drop_frame && rate.supports_drop_frame() {
+        let total_min = i128::from(h) * 60 + i128::from(m);
+        n = n.saturating_sub(i128::from(drop) * (total_min - total_min / 10));
+    }
+    clamp_i64(n)
+}
+
+/// Format a frame count as SMPTE timecode (`HH:MM:SS:FF`, or `HH;MM;SS;FF` for drop-frame).
+pub fn format_timecode_frames(frame: i64, rate: FrameRate, drop_frame: bool) -> String {
+    let df = drop_frame && rate.supports_drop_frame();
+    let (neg, h, m, s, f) = frames_to_fields(frame, rate, df);
+    let sep = if df { ';' } else { ':' };
+    let fw = if rate.timecode_base() >= 100 { 3 } else { 2 };
+    format!("{}{h:02}{sep}{m:02}{sep}{s:02}{sep}{f:0fw$}", if neg { "-" } else { "" })
+}
+
+/// Format a frame count the way After Effects / EffectCraft displays the current time: hours not zero-padded
+/// (`0:00:02:15`, or `0;00;02;15` for drop-frame).
+pub fn format_timecode_ae(frame: i64, rate: FrameRate, drop_frame: bool) -> String {
+    let df = drop_frame && rate.supports_drop_frame();
+    let (neg, h, m, s, f) = frames_to_fields(frame, rate, df);
+    let sep = if df { ';' } else { ':' };
+    let fw = if rate.timecode_base() >= 100 { 3 } else { 2 };
+    format!("{}{h}{sep}{m:02}{sep}{s:02}{sep}{f:0fw$}", if neg { "-" } else { "" })
+}
+
+/// Format a tick according to a display mode.
+pub fn format_time(t: Tick, rate: FrameRate, drop_frame: bool, display: TimeDisplay, sample_rate: i64) -> String {
+    let frame = rate.frame_at(t);
+    match display {
+        TimeDisplay::Timecode => format_timecode_frames(frame, rate, drop_frame),
+        TimeDisplay::Frames => format!("{frame}"),
+        TimeDisplay::Feet35 | TimeDisplay::Feet16 => format_feet_frames(frame, display.frames_per_foot().unwrap_or(16)),
+        TimeDisplay::AudioSamples => {
+            let neg = t.0 < 0;
+            let abs_ticks = t.0.unsigned_abs();
+            let total_secs = abs_ticks / (TICKS_PER_SECOND as u64);
+            let rem_ticks = abs_ticks % (TICKS_PER_SECOND as u64);
+            let rem_samples = Tick(rem_ticks as i64).to_units_floor(sample_rate.max(0));
+            let h = total_secs / 3600;
+            let m = (total_secs / 60) % 60;
+            let s = total_secs % 60;
+            format!("{}{:02}:{:02}:{:02}:{:05}", if neg { "-" } else { "" }, h, m, s, rem_samples)
+        }
+        TimeDisplay::Seconds => {
+            let seconds = format!("{:.3}", t.seconds());
+            if seconds == "-0.000" { "0.000".into() } else { seconds }
+        }
+    }
+}
+
+/// Format a frame count as Feet + Frames (film footage counting).
+pub fn format_feet_frames(frame: i64, per_foot: i64) -> String {
+    let per_foot = per_foot.max(1);
+    let sign = if frame < 0 { "-" } else { "" };
+    let frames = frame.unsigned_abs();
+    let per_foot = per_foot as u64;
+    let width = if per_foot > 100 { 3 } else { 2 };
+    format!("{sign}{:04}+{:0width$}", frames / per_foot, frames % per_foot)
+}
+
+/// Error from timecode parsing.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ParseError(pub String);
+
+impl fmt::Display for ParseError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+impl std::error::Error for ParseError {}
+
+/// Parse user-typed timecode into a frame count.
+///
+/// Supports standard formats (`HH:MM:SS:FF`, `HH;MM;SS;FF`), short entry (`1000` -> `00:00:10:00`),
+/// and relative offsets (`+15`, `-1.00`).
+///
+/// ### Application Compatibility Note
+/// For oversized timecodes whose frame calculations exceed 64-bit limits, `craft-time`
+/// saturates to `i64::MAX` (or `i64::MIN`) to keep calculations total without errors.
+/// In contrast, EffectCraft returns `Err(ParseError("timecode too large"))`.
+pub fn parse_timecode(input: &str, rate: FrameRate, drop_frame: bool, current: i64) -> Result<i64, ParseError> {
+    parse_timecode_with_negative_policy(input, rate, drop_frame, current, true)
+}
+
+/// Parse timecode with the relative-negative policy used by the historical timeline API.
+/// A leading minus offsets from `current`, including a complete four-field timecode.
+pub fn parse_timecode_relative(input: &str, rate: FrameRate, drop_frame: bool, current: i64) -> Result<i64, ParseError> {
+    parse_timecode_with_negative_policy(input, rate, drop_frame, current, false)
+}
+
+fn parse_timecode_with_negative_policy(
+    input: &str,
+    rate: FrameRate,
+    drop_frame: bool,
+    current: i64,
+    full_negative_is_absolute: bool,
+) -> Result<i64, ParseError> {
+    let s = input.trim();
+    if s.is_empty() {
+        return Err(ParseError("empty timecode".into()));
+    }
+    if s.len() > 80 {
+        return Err(ParseError("timecode is too long".into()));
+    }
+    let (sign_char, body) = match s.as_bytes()[0] {
+        b'+' => (Some('+'), &s[1..]),
+        b'-' => (Some('-'), &s[1..]),
+        _ => (None, s),
+    };
+    // Four fields is the complete timecode grammar. Check limits before allocating split vectors.
+    let separators = body.bytes().filter(|b| matches!(b, b':' | b';' | b'.' | b',')).count();
+    if separators > 3 {
+        return Err(ParseError("too many timecode fields".into()));
+    }
+    if separators == 0 && body.len() > if sign_char.is_some() { 19 } else { 8 } {
+        return Err(ParseError("timecode is too long".into()));
+    }
+    let parts: Vec<&str> = body.split([':', ';', '.', ',']).collect();
+    let nums: Vec<i64> = if parts.len() == 1 {
+        let digits = parts[0];
+        if digits.is_empty() || !digits.bytes().all(|b| b.is_ascii_digit()) {
+            return Err(ParseError(format!("not a timecode: `{input}`")));
+        }
+        if sign_char.is_some() {
+            vec![digits.parse().map_err(|_| ParseError("number too large".into()))?]
+        } else {
+            let mut v = Vec::new();
+            let b = digits.as_bytes();
+            let mut end = b.len();
+            while end > 0 {
+                let start = end.saturating_sub(2);
+                v.push(digits[start..end].parse::<i64>().unwrap_or(0));
+                end = start;
+            }
+            v.reverse();
+            v
+        }
+    } else {
+        parts
+            .iter()
+            .map(|p| {
+                if p.is_empty() {
+                    Ok(0)
+                } else {
+                    if !p.bytes().all(|b| b.is_ascii_digit()) {
+                        return Err(ParseError(format!("bad field `{p}`")));
+                    }
+                    p.parse::<i64>().map_err(|_| ParseError(format!("bad field `{p}`")))
+                }
+            })
+            .collect::<Result<_, _>>()?
+    };
+    if nums.len() > 4 {
+        return Err(ParseError("too many timecode fields".into()));
+    }
+    let mut f4 = [0i64; 4];
+    let off = 4 - nums.len();
+    f4[off..].copy_from_slice(&nums);
+    let [h, m, sec, fr] = f4;
+    let base = rate.timecode_base();
+    let frames = if nums.len() == 1 && sign_char.is_some() {
+        fr
+    } else if drop_frame && rate.supports_drop_frame() {
+        let (sec, fr) = (sec.saturating_add(fr / base), fr % base);
+        let (m, sec) = (m.saturating_add(sec / 60), sec % 60);
+        let (h, m) = (h.saturating_add(m / 60), m % 60);
+        fields_to_frames(h, m, sec, fr, rate, true)
+    } else {
+        h.saturating_mul(3600).saturating_add(m.saturating_mul(60)).saturating_add(sec).saturating_mul(base).saturating_add(fr)
+    };
+
+    match sign_char {
+        Some('+') => Ok(current.saturating_add(frames)),
+        Some('-') if full_negative_is_absolute && nums.len() == 4 => Ok(-frames),
+        Some('-') => {
+            // A full 4-field timecode with leading '-' represents an absolute negative timecode (e.g. preroll).
+            // The timeline compatibility path treats every leading minus as an offset instead.
+            Ok(current.saturating_sub(frames))
+        }
+        None | Some(_) => Ok(frames),
+    }
+}
+
+/// Parse a Feet + Frames field into a frame count.
+pub fn parse_feet_frames(input: &str, per_foot: i64, current: i64) -> Result<i64, ParseError> {
+    let s = input.trim();
+    let bad = || ParseError(format!("not feet+frames: `{input}`"));
+    let num = |t: &str| -> Result<i64, ParseError> {
+        let t = t.trim();
+        if t.is_empty() {
+            return Ok(0);
+        }
+        if !t.bytes().all(|b| b.is_ascii_digit()) {
+            return Err(bad());
+        }
+        t.parse::<i64>().map_err(|_| ParseError("number too large".into()))
+    };
+    if s.is_empty() {
+        return Err(ParseError("empty feet+frames".into()));
+    }
+    let (sign, body) = match s.as_bytes()[0] {
+        b'-' => (-1, &s[1..]),
+        b'+' => (1, &s[1..]),
+        _ => (0, s),
+    };
+    match body.rfind('+') {
+        Some(i) => {
+            let (feet, frames) = (num(&body[..i])?, num(&body[i + 1..])?);
+            let v = feet.checked_mul(per_foot.max(1)).and_then(|v| v.checked_add(frames)).ok_or_else(|| ParseError("number too large".into()))?;
+            Ok(if sign < 0 { -v } else { v })
+        }
+        None => {
+            let v = num(body)?;
+            Ok(match sign {
+                0 => v,
+                -1 => current.saturating_sub(v),
+                _ => current.saturating_add(v),
+            })
+        }
+    }
+}
+
+/// Parse text using a [`TimeDisplay`] representation.
+pub fn parse_time_display(input: &str, rate: FrameRate, drop_frame: bool, display: TimeDisplay, current: i64) -> Result<i64, ParseError> {
+    parse_time_display_with_negative_policy(input, rate, drop_frame, display, current, true)
+}
+
+/// Parse text using a [`TimeDisplay`] representation and the historical timeline relative-minus rule.
+pub fn parse_time_display_relative(input: &str, rate: FrameRate, drop_frame: bool, display: TimeDisplay, current: i64) -> Result<i64, ParseError> {
+    parse_time_display_with_negative_policy(input, rate, drop_frame, display, current, false)
+}
+
+fn parse_time_display_with_negative_policy(
+    input: &str,
+    rate: FrameRate,
+    drop_frame: bool,
+    display: TimeDisplay,
+    current: i64,
+    full_negative_is_absolute: bool,
+) -> Result<i64, ParseError> {
+    let per_foot = match display {
+        TimeDisplay::Frames => 1,
+        TimeDisplay::Feet35 | TimeDisplay::Feet16 => display.frames_per_foot().unwrap_or(16),
+        _ => {
+            return if full_negative_is_absolute {
+                parse_timecode(input, rate, drop_frame, current)
+            } else {
+                parse_timecode_relative(input, rate, drop_frame, current)
+            };
+        }
+    };
+    let text = input.trim();
+    if text.is_empty() {
+        return Err(ParseError("empty time".into()));
+    }
+    let (relative, body) = match text.as_bytes()[0] {
+        b'+' => (Some(1), &text[1..]),
+        b'-' => (Some(-1), &text[1..]),
+        _ => (None, text),
+    };
+    let field = |part: &str| -> Result<i64, ParseError> {
+        if part.is_empty() {
+            Ok(0)
+        } else if !part.bytes().all(|byte| byte.is_ascii_digit()) {
+            Err(ParseError(format!("not a time: `{input}`")))
+        } else {
+            part.parse::<i64>().map_err(|_| ParseError("number too large".into()))
+        }
+    };
+    let parts: Vec<&str> = body.split(['+', ':', ';', '.', ',']).collect();
+    let frames = match parts.as_slice() {
+        [number] => field(number)?,
+        [feet, frames] if per_foot > 1 => field(feet)?.saturating_mul(per_foot).saturating_add(field(frames)?),
+        _ => return Err(ParseError(format!("not a time: `{input}`"))),
+    };
+    Ok(match relative {
+        Some(sign) => current.saturating_add(frames.saturating_mul(sign)),
+        None => frames,
+    })
+}
+
+/// Common audio sample rates offered in sequence settings.
+pub const SAMPLE_RATES: [i64; 6] = [32_000, 44_100, 48_000, 88_200, 96_000, 192_000];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_tick_conversions() {
+        assert_eq!(Tick::from_seconds_f64(1.0).0, TICKS_PER_SECOND);
+        assert_eq!(Tick::from_units(48000, 48000).0, TICKS_PER_SECOND);
+        assert_eq!(Tick(TICKS_PER_SECOND).to_units_floor(48000), 48000);
+        assert_eq!(Tick::from_rational(1, 1, 1).0, TICKS_PER_SECOND);
+        assert_eq!(Tick(TICKS_PER_SECOND).to_rational_floor(1, 1), 1);
+        assert_eq!(Tick(TICKS_PER_SECOND).to_rational_round(1, 1), 1);
+    }
+
+    #[test]
+    fn test_hostile_rates_never_panic() {
+        let zero = FrameRate { num: 0, den: 0 };
+        for r in [zero, FrameRate { num: 0, den: 1 }, FrameRate { num: 25, den: 0 }, FrameRate { num: -30, den: 1 }] {
+            assert_eq!(r.tick_of(10), FrameRate::default().tick_of(10));
+            assert_eq!(r.frame_at(Tick(TICKS_PER_SECOND)), FrameRate::default().frame_at(Tick(TICKS_PER_SECOND)));
+            assert!(r.frame_duration() > Tick::ZERO);
+            assert!(r.timecode_base() >= 1);
+            let _ = r.snap_nearest(Tick(12345));
+            let _ = format_time(Tick(TICKS_PER_SECOND), r, true, TimeDisplay::Timecode, 48_000);
+        }
+    }
+
+    #[test]
+    fn timecode_parser_rejects_oversized_inputs_before_field_collection() {
+        let too_many_fields = ":".repeat(100_000);
+        assert!(parse_timecode(&too_many_fields, FrameRate::FPS_30, false, 0).is_err());
+        let compact = "1".repeat(9);
+        assert!(parse_timecode(&compact, FrameRate::FPS_30, false, 0).is_err());
+        assert!(parse_timecode_relative("+12345678901234567890", FrameRate::FPS_30, false, 0).is_err());
+    }
+
+    #[test]
+    fn test_broadcast_frame_rates() {
+        for r in FrameRate::COMMON {
+            assert_eq!(r.frame_at(r.tick_of(100)), 100);
+            assert_eq!(r.snap(r.tick_of(50)), r.tick_of(50));
+            assert_eq!(r.snap_nearest(r.tick_of(50)), r.tick_of(50));
+        }
+    }
+
+    #[test]
+    fn test_smpte_timecode_roundtrip() {
+        for r in [FrameRate::FPS_24, FrameRate::FPS_25, FrameRate::FPS_30, FrameRate::FPS_29_97] {
+            for f in [0, 1, 24, 25, 30, 100, 1800, 54000] {
+                let df = r.supports_drop_frame();
+                let tc = format_timecode_frames(f, r, df);
+                let parsed = parse_timecode(&tc, r, df, 0);
+                assert_eq!(parsed, Ok(f), "rate: {}, frame: {}, tc: {}", r, f, tc);
+            }
+        }
+    }
+
+    #[test]
+    fn test_audio_samples_formatting_negative_ticks() {
+        let r = FrameRate::FPS_24;
+        let neg_1s = Tick(-TICKS_PER_SECOND);
+        assert_eq!(format_time(neg_1s, r, false, TimeDisplay::AudioSamples, 48_000), "-00:00:01:00000");
+
+        let pos_1s = Tick(TICKS_PER_SECOND);
+        assert_eq!(format_time(pos_1s, r, false, TimeDisplay::AudioSamples, 48_000), "00:00:01:00000");
+
+        let neg_complex = Tick(-3661 * TICKS_PER_SECOND);
+        assert_eq!(format_time(neg_complex, r, false, TimeDisplay::AudioSamples, 48_000), "-01:01:01:00000");
+
+        let zero = Tick::ZERO;
+        assert_eq!(format_time(Tick(2), r, false, TimeDisplay::AudioSamples, -1), "00:00:00:00000");
+        assert_eq!(format_time(zero, r, false, TimeDisplay::AudioSamples, 48_000), "00:00:00:00000");
+    }
+
+    #[test]
+    fn test_parse_timecode_negative_absolute_independent_of_current() {
+        let r = FrameRate::FPS_29_97;
+        // Negative full 4-field timecode must parse as absolute negative frames, not offset from current
+        assert_eq!(parse_timecode("-00;01;00;02", r, true, 5000), Ok(-1800));
+        assert_eq!(parse_timecode("-00;01;00;02", r, true, 0), Ok(-1800));
+
+        let r24 = FrameRate::FPS_24;
+        assert_eq!(parse_timecode("-01:00:00:00", r24, false, 9999), Ok(-86400));
+
+        // Single-number relative entries must offset from current
+        assert_eq!(parse_timecode("-15", r24, false, 5000), Ok(4985));
+        assert_eq!(parse_timecode("+15", r24, false, 5000), Ok(5015));
+    }
+
+    #[test]
+    fn test_parse_timecode_rejects_signed_inner_fields() {
+        let r = FrameRate::FPS_24;
+        assert!(parse_timecode("00:-30:00:00", r, false, 0).is_err());
+        assert!(parse_timecode("01:+5:00:00", r, false, 0).is_err());
+        assert!(parse_timecode("00:00:-01:00", r, false, 0).is_err());
+    }
+
+    #[test]
+    fn test_feet_frames_roundtrip() {
+        for pf in [16, 40] {
+            for f in [0, 1, 15, 16, 95, 199, 1234] {
+                let s = format_feet_frames(f, pf);
+                let parsed = parse_feet_frames(&s, pf, 0);
+                assert_eq!(parsed, Ok(f));
+            }
+        }
+    }
+}
diff --git a/crates/time/src/soundcraft/format.rs b/crates/time/src/soundcraft/format.rs
new file mode 100644
index 000000000..b16511006
--- /dev/null
+++ b/crates/time/src/soundcraft/format.rs
@@ -0,0 +1,241 @@
+//! Formatting and parsing positions in the five timebases.
+
+use super::{BarBeat, FrameRate, SampleRate, Samples, TempoMap, TimeError, Timecode, timecode::feet_frames};
+
+/// The counters' and rulers' timebases.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum TimeFormat {
+    BarsBeats,
+    #[default]
+    MinSecs,
+    Timecode,
+    FeetFrames,
+    Samples,
+}
+
+impl TimeFormat {
+    pub const ALL: [TimeFormat; 5] = [TimeFormat::BarsBeats, TimeFormat::MinSecs, TimeFormat::Timecode, TimeFormat::FeetFrames, TimeFormat::Samples];
+
+    pub fn label(self) -> &'static str {
+        match self {
+            TimeFormat::BarsBeats => "Bars|Beats",
+            TimeFormat::MinSecs => "Min:Secs",
+            TimeFormat::Timecode => "Timecode",
+            TimeFormat::FeetFrames => "Feet+Frames",
+            TimeFormat::Samples => "Samples",
+        }
+    }
+
+    pub fn id(self) -> &'static str {
+        match self {
+            TimeFormat::BarsBeats => "bars_beats",
+            TimeFormat::MinSecs => "min_secs",
+            TimeFormat::Timecode => "timecode",
+            TimeFormat::FeetFrames => "feet_frames",
+            TimeFormat::Samples => "samples",
+        }
+    }
+
+    pub fn from_id(id: &str) -> Option<TimeFormat> {
+        TimeFormat::ALL.into_iter().find(|f| f.id() == id || f.label().eq_ignore_ascii_case(id))
+    }
+}
+
+fn min_secs(s: Samples, sr: SampleRate) -> String {
+    let neg = s < 0;
+    // Integer maths: a float `seconds * 1000` lands just below exact millisecond positions.
+    let ms_total = i64::try_from(i128::from(s).abs() * 1000 / i128::from(sr.hz().max(1))).unwrap_or(i64::MAX);
+    let mins = ms_total / 60_000;
+    let secs = (ms_total / 1000) % 60;
+    let ms = ms_total % 1000;
+    format!("{}{mins}:{secs:02}.{ms:03}", if neg { "-" } else { "" })
+}
+
+/// Format an absolute position. `tc_start` is the timecode of sample 0 in samples, `ff_start` the
+/// feet+frames reading of sample 0 in frames.
+pub fn format_position(s: Samples, fmt: TimeFormat, sr: SampleRate, map: &TempoMap, rate: FrameRate, tc_start: Samples, ff_start: i64) -> String {
+    match fmt {
+        TimeFormat::Samples => s.to_string(),
+        TimeFormat::MinSecs => min_secs(s, sr),
+        TimeFormat::Timecode => Timecode::from_samples(s.saturating_add(tc_start), rate, sr).format(rate),
+        TimeFormat::FeetFrames => {
+            let (ft, fr) = feet_frames(s, rate, sr, ff_start);
+            format!("{ft}+{fr:02}")
+        }
+        TimeFormat::BarsBeats => {
+            let bb = map.bar_beat_at(s, sr);
+            format!("{}| {}| {:03}", bb.bar, bb.beat, bb.tick)
+        }
+    }
+}
+
+/// Format a length starting at `start` (Bars|Beats lengths count from 0|0|000).
+pub fn format_length(start: Samples, len: Samples, fmt: TimeFormat, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> String {
+    match fmt {
+        TimeFormat::BarsBeats => {
+            let t0 = map.samples_to_ticks(start, sr);
+            let t1 = map.samples_to_ticks(start.saturating_add(len), sr);
+            let m = map.meter_at_tick(t0);
+            let d = t1.saturating_sub(t0).max(0);
+            let bars = d / m.ticks_per_bar().max(1);
+            let rem = d % m.ticks_per_bar().max(1);
+            format!("{bars}| {}| {:03}", rem / m.ticks_per_beat().max(1), rem % m.ticks_per_beat().max(1))
+        }
+        TimeFormat::Timecode => Timecode::from_samples(len, rate, sr).format(rate),
+        other => format_position(len, other, sr, map, rate, 0, 0),
+    }
+}
+
+/// Parse a position typed into a counter or dialog.
+pub fn parse_position(
+    text: &str,
+    fmt: TimeFormat,
+    sr: SampleRate,
+    map: &TempoMap,
+    rate: FrameRate,
+    tc_start: Samples,
+    ff_start: i64,
+) -> Result<Samples, TimeError> {
+    let t = text.trim();
+    let err = || TimeError::Parse(t.to_string(), fmt.label());
+    match fmt {
+        TimeFormat::Samples => t.replace([',', '_'], "").parse::<i64>().map_err(|_| err()),
+        TimeFormat::MinSecs => {
+            let (neg, body) = match t.strip_prefix('-') {
+                Some(r) => (true, r),
+                None => (false, t),
+            };
+            let (m, s) = match body.split_once(':') {
+                Some((m, s)) => (m.trim().parse::<f64>().map_err(|_| err())?, s.trim().parse::<f64>().map_err(|_| err())?),
+                None => (0.0, body.parse::<f64>().map_err(|_| err())?),
+            };
+            if !m.is_finite() || !s.is_finite() || m < 0.0 || s < 0.0 {
+                return Err(err());
+            }
+            let v = sr.samples(m * 60.0 + s);
+            Ok(if neg { -v } else { v })
+        }
+        TimeFormat::Timecode => {
+            let tc = Timecode::parse(t)?;
+            if tc.minutes >= 60 || tc.seconds >= 60 || tc.frames >= rate.nominal().max(1) {
+                return Err(err());
+            }
+            if rate.is_drop() && tc.seconds == 0 && tc.minutes % 10 != 0 {
+                let dropped = if rate.nominal() >= 60 { 4 } else { 2 };
+                if tc.frames < dropped {
+                    return Err(err());
+                }
+            }
+            Ok(tc.to_samples(rate, sr).saturating_sub(tc_start))
+        }
+        TimeFormat::FeetFrames => {
+            let (ft, fr) = t.split_once('+').ok_or_else(err)?;
+            let ft: i64 = ft.trim().parse().map_err(|_| err())?;
+            let fr: i64 = fr.trim().parse().map_err(|_| err())?;
+            Ok(rate.samples_at_frame(ft.saturating_mul(16).saturating_add(fr).saturating_sub(ff_start), sr))
+        }
+        TimeFormat::BarsBeats => {
+            let parts: Vec<i64> =
+                t.split(['|', '.', ' ']).filter(|p| !p.is_empty()).map(str::parse::<i64>).collect::<Result<_, _>>().map_err(|_| err())?;
+            let bb = BarBeat {
+                bar: *parts.first().ok_or_else(err)?,
+                beat: parts.get(1).copied().unwrap_or(1).max(1),
+                tick: parts.get(2).copied().unwrap_or(0).max(0),
+            };
+            Ok(map.samples_at_bar_beat(bb, sr))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn ctx() -> (SampleRate, TempoMap, FrameRate) {
+        (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps30)
+    }
+
+    #[test]
+    fn huge_typed_positions_parse_without_overflowing() {
+        let (sr, map, rate) = ctx();
+        for (text, fmt) in [
+            ("999999999999999999:0", TimeFormat::Timecode),
+            ("100000000000000:00:00:00", TimeFormat::Timecode),
+            ("-9223372036854775808", TimeFormat::BarsBeats),
+        ] {
+            let _ = parse_position(text, fmt, sr, &map, rate, 0, 0);
+        }
+    }
+
+    #[test]
+    fn formats_like_pro_tools_counters() {
+        let (sr, map, rate) = ctx();
+        assert_eq!(format_position(0, TimeFormat::MinSecs, sr, &map, rate, 0, 0), "0:00.000");
+        assert_eq!(format_position(48_000 * 75 + 24_000, TimeFormat::MinSecs, sr, &map, rate, 0, 0), "1:15.500");
+        assert_eq!(format_position(0, TimeFormat::BarsBeats, sr, &map, rate, 0, 0), "1| 1| 000");
+        assert_eq!(format_position(48_000, TimeFormat::Timecode, sr, &map, rate, 0, 0), "00:00:01:00");
+        assert_eq!(format_position(12345, TimeFormat::Samples, sr, &map, rate, 0, 0), "12345");
+    }
+
+    #[test]
+    fn minimum_bar_parses_without_overflow() {
+        let (sr, map, rate) = ctx();
+        let p = |t: &str| parse_position(t, TimeFormat::BarsBeats, sr, &map, rate, 0, 0);
+        assert!(p("-9223372036854775808|01|000").is_ok_and(|s| s < 0));
+        assert_eq!(p("2|3|000").ok(), Some(144_000));
+        assert_eq!(p("0|1|000").ok(), Some(-96_000));
+    }
+
+    #[test]
+    fn parse_round_trips() {
+        let (sr, map, rate) = ctx();
+        for fmt in TimeFormat::ALL {
+            for s in [0i64, 48_000, 96_000 * 3, 1_440_000] {
+                let text = format_position(s, fmt, sr, &map, rate, 0, 0);
+                let back = parse_position(&text, fmt, sr, &map, rate, 0, 0).unwrap();
+                assert!((back - s).abs() <= 48, "{fmt:?} {s} → {text} → {back}");
+            }
+        }
+    }
+
+    #[test]
+    fn parse_round_trips_timecode_negative() {
+        let (sr, map, _) = ctx();
+        let rate = FrameRate::Fps25;
+        for fmt in [TimeFormat::Timecode, TimeFormat::FeetFrames] {
+            for s in [-48_000i64, -96_000 * 3, -1_440_000] {
+                let text = format_position(s, fmt, sr, &map, rate, 0, 0);
+                let back = parse_position(&text, fmt, sr, &map, rate, 0, 0).unwrap();
+                assert_eq!(back, s, "{fmt:?} {s} → {text} → {back}");
+            }
+        }
+    }
+
+    #[test]
+    fn parse_rejects_garbage() {
+        let (sr, map, rate) = ctx();
+        assert!(parse_position("abc", TimeFormat::Samples, sr, &map, rate, 0, 0).is_err());
+        assert!(parse_position("1:x", TimeFormat::MinSecs, sr, &map, rate, 0, 0).is_err());
+        assert!(parse_position("", TimeFormat::BarsBeats, sr, &map, rate, 0, 0).is_err());
+    }
+
+    #[test]
+    fn drop_frame_skipped_labels_are_rejected() {
+        let (sr, map, _) = ctx();
+        for (rate, skipped) in [
+            (FrameRate::Fps29_97Drop, &["00:01:00;00", "00:01:00;01"][..]),
+            (FrameRate::Fps59_94Drop, &["00:01:00;00", "00:01:00;01", "00:01:00;02", "00:01:00;03"][..]),
+        ] {
+            for text in skipped {
+                assert!(parse_position(text, TimeFormat::Timecode, sr, &map, rate, 0, 0).is_err(), "accepted skipped label {text} at {rate:?}");
+            }
+            assert!(parse_position("00:10:00;00", TimeFormat::Timecode, sr, &map, rate, 0, 0).is_ok());
+        }
+    }
+
+    #[test]
+    fn bar_lengths() {
+        let (sr, map, rate) = ctx();
+        assert_eq!(format_length(0, 96_000 + 24_000, TimeFormat::BarsBeats, sr, &map, rate), "1| 1| 000");
+    }
+}
diff --git a/crates/time/src/soundcraft/grid.rs b/crates/time/src/soundcraft/grid.rs
new file mode 100644
index 000000000..9055340ba
--- /dev/null
+++ b/crates/time/src/soundcraft/grid.rs
@@ -0,0 +1,858 @@
+//! Grid and Nudge values: musical or absolute step sizes, grid lines and snapping.
+
+use super::{FrameRate, SampleRate, Samples, TICKS_PER_QUARTER, TempoMap, Timecode, to_samples};
+
+/// Note values for Bars|Beats grids.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum NoteValue {
+    Bar,
+    Whole,
+    Half,
+    Quarter,
+    Eighth,
+    Sixteenth,
+    ThirtySecond,
+    SixtyFourth,
+}
+
+impl NoteValue {
+    /// Every musical increment in menu order, from largest to smallest.
+    pub const ALL: [NoteValue; 8] = [
+        NoteValue::Bar,
+        NoteValue::Whole,
+        NoteValue::Half,
+        NoteValue::Quarter,
+        NoteValue::Eighth,
+        NoteValue::Sixteenth,
+        NoteValue::ThirtySecond,
+        NoteValue::SixtyFourth,
+    ];
+    /// Returns the nominal tick length; bars are adjusted for the active meter when used.
+    pub fn ticks(self) -> i64 {
+        match self {
+            NoteValue::Bar => TICKS_PER_QUARTER * 4,
+            NoteValue::Whole => TICKS_PER_QUARTER * 4,
+            NoteValue::Half => TICKS_PER_QUARTER * 2,
+            NoteValue::Quarter => TICKS_PER_QUARTER,
+            NoteValue::Eighth => TICKS_PER_QUARTER / 2,
+            NoteValue::Sixteenth => TICKS_PER_QUARTER / 4,
+            NoteValue::ThirtySecond => TICKS_PER_QUARTER / 8,
+            NoteValue::SixtyFourth => TICKS_PER_QUARTER / 16,
+        }
+    }
+    /// Returns the menu label for this musical increment.
+    pub fn label(self) -> &'static str {
+        match self {
+            NoteValue::Bar => "1 bar",
+            NoteValue::Whole => "Whole note",
+            NoteValue::Half => "1/2 note",
+            NoteValue::Quarter => "1/4 note",
+            NoteValue::Eighth => "1/8 note",
+            NoteValue::Sixteenth => "1/16 note",
+            NoteValue::ThirtySecond => "1/32 note",
+            NoteValue::SixtyFourth => "1/64 note",
+        }
+    }
+}
+
+/// The time scale used by a Grid or Nudge value.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum GridScale {
+    BarsBeats,
+    MinSecs,
+    Timecode,
+    FeetFrames,
+    Samples,
+    ClipsMarkers,
+}
+
+impl GridScale {
+    /// Numeric time scales shared by Grid and Nudge.
+    pub const TIME: [GridScale; 5] = [GridScale::BarsBeats, GridScale::MinSecs, GridScale::Timecode, GridScale::FeetFrames, GridScale::Samples];
+
+    /// Returns the user-facing scale label.
+    pub fn label(self) -> &'static str {
+        match self {
+            GridScale::BarsBeats => "Bars|Beats",
+            GridScale::MinSecs => "Min:Secs",
+            GridScale::Timecode => "Timecode",
+            GridScale::FeetFrames => "Feet+Frames",
+            GridScale::Samples => "Samples",
+            GridScale::ClipsMarkers => "Clips/Markers",
+        }
+    }
+
+    /// Returns the stable command and session identifier.
+    pub fn id(self) -> &'static str {
+        match self {
+            GridScale::BarsBeats => "bars_beats",
+            GridScale::MinSecs => "min_secs",
+            GridScale::Timecode => "timecode",
+            GridScale::FeetFrames => "feet_frames",
+            GridScale::Samples => "samples",
+            GridScale::ClipsMarkers => "clips_markers",
+        }
+    }
+
+    /// Parses a stable identifier or user-facing label.
+    pub fn from_id(id: &str) -> Option<GridScale> {
+        Self::TIME.into_iter().chain([GridScale::ClipsMarkers]).find(|scale| scale.id() == id || scale.label().eq_ignore_ascii_case(id))
+    }
+}
+
+/// Timecode Grid/Nudge increments, ordered independently of the session frame rate.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum TimecodeValue {
+    Second,
+    /// Five physical frames, independent of skipped drop-frame labels.
+    FiveFrames,
+    Frame,
+    HalfFrame,
+    QuarterFrame,
+    SubFrame,
+}
+
+impl TimecodeValue {
+    /// Every Timecode increment in menu order, from largest to smallest.
+    pub const ALL: [TimecodeValue; 6] = [
+        TimecodeValue::Second,
+        TimecodeValue::FiveFrames,
+        TimecodeValue::Frame,
+        TimecodeValue::HalfFrame,
+        TimecodeValue::QuarterFrame,
+        TimecodeValue::SubFrame,
+    ];
+
+    /// Returns the user-facing increment label.
+    pub fn label(self) -> &'static str {
+        match self {
+            TimecodeValue::Second => "1 second",
+            TimecodeValue::FiveFrames => "5 frames",
+            TimecodeValue::Frame => "1 frame",
+            TimecodeValue::HalfFrame => "1/2 frame",
+            TimecodeValue::QuarterFrame => "1/4 frame",
+            TimecodeValue::SubFrame => "1 subframe",
+        }
+    }
+
+    /// Returns the stable command and session identifier.
+    pub fn id(self) -> &'static str {
+        match self {
+            TimecodeValue::Second => "second",
+            TimecodeValue::FiveFrames => "5_frames",
+            TimecodeValue::Frame => "frame",
+            TimecodeValue::HalfFrame => "half_frame",
+            TimecodeValue::QuarterFrame => "quarter_frame",
+            TimecodeValue::SubFrame => "subframe",
+        }
+    }
+
+    /// Parses a stable identifier or user-facing label.
+    pub fn from_id(id: &str) -> Option<TimecodeValue> {
+        Self::ALL.into_iter().find(|value| value.id() == id || value.label().eq_ignore_ascii_case(id))
+    }
+
+    /// Returns the increment length in frames at the session rate.
+    fn frames(self, rate: FrameRate) -> f64 {
+        match self {
+            TimecodeValue::Second => rate.nominal() as f64,
+            TimecodeValue::FiveFrames => 5.0,
+            TimecodeValue::Frame => 1.0,
+            TimecodeValue::HalfFrame => 0.5,
+            TimecodeValue::QuarterFrame => 0.25,
+            TimecodeValue::SubFrame => 0.01,
+        }
+    }
+}
+
+/// Feet+Frames Grid/Nudge increments in physical frames, independent of drop-frame label skips.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum FeetFramesValue {
+    Foot,
+    Frame,
+    QuarterFrame,
+    SubFrame,
+}
+
+impl FeetFramesValue {
+    /// Every Feet+Frames increment in menu order, from largest to smallest.
+    pub const ALL: [FeetFramesValue; 4] = [FeetFramesValue::Foot, FeetFramesValue::Frame, FeetFramesValue::QuarterFrame, FeetFramesValue::SubFrame];
+
+    /// Returns the user-facing increment label.
+    pub fn label(self) -> &'static str {
+        match self {
+            FeetFramesValue::Foot => "1 foot",
+            FeetFramesValue::Frame => "1 frame",
+            FeetFramesValue::QuarterFrame => "1/4 frame",
+            FeetFramesValue::SubFrame => "1 subframe",
+        }
+    }
+
+    /// Returns the stable command and session identifier.
+    pub fn id(self) -> &'static str {
+        match self {
+            FeetFramesValue::Foot => "foot",
+            FeetFramesValue::Frame => "frame",
+            FeetFramesValue::QuarterFrame => "quarter_frame",
+            FeetFramesValue::SubFrame => "subframe",
+        }
+    }
+
+    /// Parses a stable identifier or user-facing label.
+    pub fn from_id(id: &str) -> Option<FeetFramesValue> {
+        Self::ALL.into_iter().find(|value| value.id() == id || value.label().eq_ignore_ascii_case(id))
+    }
+
+    /// Returns the increment length in frames.
+    fn frames(self) -> f64 {
+        let (num, den) = self.frame_ratio();
+        num as f64 / den as f64
+    }
+
+    /// Exact numerator and denominator of the increment in physical frames.
+    fn frame_ratio(self) -> (i128, i128) {
+        match self {
+            Self::Foot => (16, 1),
+            Self::Frame => (1, 1),
+            Self::QuarterFrame => (1, 4),
+            Self::SubFrame => (1, 100),
+        }
+    }
+
+    /// Apply the counter origin in frames before rounding once to the first sample at the frame
+    /// boundary. This matches `FrameRate::samples_at_frame` and typed Feet+Frames positions.
+    fn sample_line(self, index: i128, sr: SampleRate, rate: FrameRate, origin: i64) -> Samples {
+        let (num, den) = self.frame_ratio();
+        let (rate_num, rate_den) = rate.rational();
+        let frames = index * num - i128::from(origin) * den;
+        let samples = frames * i128::from(sr.hz().max(1)) * i128::from(rate_den);
+        let divisor = den * i128::from(rate_num);
+        let rounded = samples.div_euclid(divisor) + i128::from(samples.rem_euclid(divisor) != 0);
+        i64::try_from(rounded).unwrap_or(if rounded < 0 { i64::MIN } else { i64::MAX })
+    }
+
+    /// Find a line index using exact frame arithmetic, allowing for whole-sample rounding.
+    fn line_index(self, position: Samples, sr: SampleRate, rate: FrameRate, origin: i64) -> i128 {
+        let (num, den) = self.frame_ratio();
+        let (rate_num, rate_den) = rate.rational();
+        let scale = i128::from(sr.hz().max(1)) * i128::from(rate_den);
+        let frames = i128::from(position) * i128::from(rate_num) + i128::from(origin) * scale;
+        let mut index = (frames * den).div_euclid(scale * num);
+        if self.sample_line(index + 1, sr, rate, origin) <= position {
+            index += 1;
+        }
+        index
+    }
+
+    /// The Feet+Frames line at or before a sample, relative to the counter's frame origin.
+    pub fn line_at_or_before(self, position: Samples, sr: SampleRate, rate: FrameRate, origin: i64) -> Samples {
+        self.sample_line(self.line_index(position, sr, rate, origin), sr, rate, origin)
+    }
+
+    /// The next distinct sample line; subframe increments may share a sample at low sample rates.
+    fn next_line(self, position: Samples, sr: SampleRate, rate: FrameRate, origin: i64) -> Samples {
+        self.sample_line(self.line_index(position, sr, rate, origin) + 1, sr, rate, origin).max(position.saturating_add(1))
+    }
+
+    /// Snap against frame-origin lines, choosing the earlier line when distances are equal.
+    pub fn snap(self, position: Samples, sr: SampleRate, rate: FrameRate, origin: i64) -> Samples {
+        let lo = self.line_at_or_before(position, sr, rate, origin);
+        let hi = self.next_line(lo, sr, rate, origin);
+        if i128::from(position) - i128::from(lo) <= i128::from(hi) - i128::from(position) { lo } else { hi }
+    }
+
+    /// Distinct Feet+Frames sample lines within `[start, end)`, capped at `max`.
+    pub fn lines(self, start: Samples, end: Samples, sr: SampleRate, rate: FrameRate, origin: i64, max: usize) -> Vec<Samples> {
+        let mut out = Vec::new();
+        let mut line = self.line_at_or_before(start, sr, rate, origin);
+        while line < end && out.len() < max {
+            if line >= start {
+                out.push(line);
+            }
+            let next = self.next_line(line, sr, rate, origin);
+            if next <= line {
+                break;
+            }
+            line = next;
+        }
+        out
+    }
+}
+
+/// A grid or nudge step.
+#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
+pub enum GridValue {
+    /// Musical: note value, optionally dotted or triplet.
+    Note { value: NoteValue, dotted: bool, triplet: bool },
+    /// Absolute seconds (Min:Secs grids: 0.001 … 1 s).
+    Seconds(f64),
+    /// Frames at the session timecode rate.
+    /// Kept for sessions and commands written before named timecode increments were added.
+    Frames(i64),
+    /// A named Timecode increment, including fractional frames and one second.
+    Timecode(TimecodeValue),
+    /// A Feet+Frames increment (one foot is 16 frames).
+    FeetFrames(FeetFramesValue),
+    /// Raw samples.
+    Samples(i64),
+}
+
+impl Default for GridValue {
+    /// Starts on a straight sixteenth-note Bars|Beats grid.
+    fn default() -> Self {
+        GridValue::Note { value: NoteValue::Sixteenth, dotted: false, triplet: false }
+    }
+}
+
+impl GridValue {
+    /// Returns the user-facing label for this increment.
+    pub fn label(&self) -> String {
+        match self {
+            GridValue::Note { value, dotted, triplet } => {
+                let mut s = value.label().to_string();
+                if *dotted {
+                    s.push_str(" dotted");
+                }
+                if *triplet {
+                    s.push_str(" triplet");
+                }
+                s
+            }
+            GridValue::Seconds(s) => {
+                if *s >= 1.0 {
+                    format!("{s} second{}", if *s == 1.0 { "" } else { "s" })
+                } else {
+                    format!("{} ms", (s * 1000.0).round() as i64)
+                }
+            }
+            GridValue::Frames(f) => format!("{f} frame{}", if *f == 1 { "" } else { "s" }),
+            GridValue::Timecode(value) => value.label().to_string(),
+            GridValue::FeetFrames(value) => value.label().to_string(),
+            GridValue::Samples(n) => format!("{n} sample{}", if *n == 1 { "" } else { "s" }),
+        }
+    }
+
+    /// Returns the time scale to which this increment belongs.
+    pub fn scale(self) -> GridScale {
+        match self {
+            GridValue::Note { .. } => GridScale::BarsBeats,
+            GridValue::Seconds(_) => GridScale::MinSecs,
+            GridValue::Frames(_) | GridValue::Timecode(_) => GridScale::Timecode,
+            GridValue::FeetFrames(_) => GridScale::FeetFrames,
+            GridValue::Samples(_) => GridScale::Samples,
+        }
+    }
+
+    /// Returns the default increment for a newly selected time scale.
+    pub fn for_scale(scale: GridScale) -> GridValue {
+        match scale {
+            GridScale::BarsBeats => GridValue::default(),
+            GridScale::MinSecs => GridValue::Seconds(1.0),
+            GridScale::Timecode => GridValue::Timecode(TimecodeValue::Frame),
+            GridScale::FeetFrames => GridValue::FeetFrames(FeetFramesValue::Frame),
+            GridScale::Samples => GridValue::Samples(100),
+            GridScale::ClipsMarkers => GridValue::default(),
+        }
+    }
+
+    /// The next larger or smaller menu value of the same kind, or `self` at either end. Note values keep
+    /// their dot or triplet modifier.
+    pub fn stepped(self, larger: bool) -> GridValue {
+        /// Finds the next value in a numeric increment ladder without wrapping.
+        fn next<T: PartialOrd + Copy>(ladder: &[T], v: T, larger: bool) -> Option<T> {
+            if larger { ladder.iter().copied().find(|x| *x > v) } else { ladder.iter().rev().copied().find(|x| *x < v) }
+        }
+        match self {
+            GridValue::Note { value, dotted, triplet } => {
+                let i = NoteValue::ALL.iter().position(|v| *v == value).unwrap_or(0);
+                let j = if larger { i.checked_sub(1) } else { i.checked_add(1) };
+                j.and_then(|j| NoteValue::ALL.get(j)).map_or(self, |&value| GridValue::Note { value, dotted, triplet })
+            }
+            GridValue::Seconds(s) => next(&[0.001, 0.01, 0.1, 0.5, 1.0], s, larger).map_or(self, GridValue::Seconds),
+            GridValue::Frames(f) => next(&[1, 10, 100], f, larger).map_or(self, GridValue::Frames),
+            GridValue::Timecode(value) => step_enum(&TimecodeValue::ALL, value, larger).map_or(self, GridValue::Timecode),
+            GridValue::FeetFrames(value) => step_enum(&FeetFramesValue::ALL, value, larger).map_or(self, GridValue::FeetFrames),
+            GridValue::Samples(n) => next(&[1, 2, 10, 100, 1_000, 10_000], n, larger).map_or(self, GridValue::Samples),
+        }
+    }
+
+    fn note_ticks(value: NoteValue, dotted: bool, triplet: bool, map: &TempoMap, at_tick: i64) -> i64 {
+        let base = if value == NoteValue::Bar { map.meter_at_tick(at_tick).ticks_per_bar() } else { value.ticks() };
+        let mut t = base;
+        if dotted {
+            t = t * 3 / 2;
+        }
+        if triplet {
+            t = t * 2 / 3;
+        }
+        t.max(1)
+    }
+
+    /// The step in samples at position `at` (musical steps depend on tempo).
+    pub fn step_samples(&self, at: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> Samples {
+        match *self {
+            GridValue::Note { value, dotted, triplet } => {
+                let t0 = map.samples_to_ticks(at, sr);
+                let dt = Self::note_ticks(value, dotted, triplet, map, t0);
+                (map.tick_to_samples(t0.saturating_add(dt), sr).saturating_sub(map.tick_to_samples(t0, sr))).max(1)
+            }
+            GridValue::Seconds(s) => sr.samples(s.clamp(0.000_01, 3600.0)).max(1),
+            GridValue::Frames(f) => to_samples(rate.samples_per_frame(sr) * f.clamp(1, 1_000_000) as f64).max(1),
+            GridValue::Timecode(value) => to_samples(rate.samples_per_frame(sr) * value.frames(rate)).max(1),
+            GridValue::FeetFrames(value) => to_samples(rate.samples_per_frame(sr) * value.frames()).max(1),
+            GridValue::Samples(n) => n.max(1),
+        }
+    }
+
+    /// Nearest grid line to `pos`.
+    pub fn snap(&self, pos: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> Samples {
+        if let Self::FeetFrames(value) = *self {
+            return value.snap(pos, sr, rate, 0);
+        }
+        let lo = self.line_at_or_before(pos, sr, map, rate);
+        let hi = self.next_line(lo, sr, map, rate);
+        if (pos - lo) <= (hi - pos) { lo } else { hi }
+    }
+
+    /// The grid line at or before `pos`.
+    pub fn line_at_or_before(&self, pos: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> Samples {
+        match *self {
+            Self::FeetFrames(value) => value.line_at_or_before(pos, sr, rate, 0),
+            GridValue::Note { value, dotted, triplet } => {
+                // Float ticks can land a hair either side of a line's own tick.
+                let mut t = map.samples_to_ticks_f(pos, sr).floor() as i64;
+                if map.tick_to_samples(t, sr) > pos {
+                    t = t.saturating_sub(1);
+                } else if map.tick_to_samples(t.saturating_add(1), sr) <= pos {
+                    t = t.saturating_add(1);
+                }
+                // Sub-bar values restart at each bar so odd meters stay aligned. A whole note is
+                // always four quarter notes and therefore keeps a continuous tick origin.
+                let bb = map.bar_beat_at_tick(t);
+                let bar_tick = map.bar_start_tick(bb.bar);
+                let origin = if value == NoteValue::Whole || (value == NoteValue::Bar && dotted) { 0 } else { bar_tick };
+                let step = Self::note_ticks(value, dotted, triplet, map, origin);
+                let k = (t - origin).div_euclid(step);
+                map.tick_to_samples(origin + k * step, sr)
+            }
+            _ => self.abs_line(self.abs_index_at_or_before(pos, sr, rate), sr, rate),
+        }
+    }
+
+    /// Position of absolute grid line `k` (Seconds, Frames, Samples), at an exact multiple of the step
+    /// rounded once, so rounding never accumulates from line to line.
+    fn abs_line(&self, k: i64, sr: SampleRate, rate: FrameRate) -> Samples {
+        if let Self::FeetFrames(value) = *self {
+            return value.sample_line(i128::from(k), sr, rate, 0);
+        }
+        if matches!(self, GridValue::Timecode(TimecodeValue::Second)) && rate.is_drop() {
+            return rate.samples_at_frame(Self::drop_second_frame(k, rate), sr);
+        }
+        if let Some(frames) = self.frame_step(rate) {
+            let whole = frames.round();
+            if frames == whole {
+                return rate.samples_at_frame(k.saturating_mul(whole as i64), sr);
+            }
+            let step = (rate.samples_per_frame(sr) * frames).max(1.0);
+            return to_samples(k as f64 * step);
+        }
+        match *self {
+            GridValue::Seconds(s) => to_samples(k as f64 * Self::seconds_step(s, sr)),
+            GridValue::Samples(n) => k.saturating_mul(n.max(1)),
+            GridValue::Note { .. } => 0,
+            GridValue::Frames(_) | GridValue::Timecode(_) | GridValue::FeetFrames(_) => 0,
+        }
+    }
+
+    /// Index of the absolute grid line at or before `pos`.
+    fn abs_index_at_or_before(&self, pos: Samples, sr: SampleRate, rate: FrameRate) -> i64 {
+        if matches!(self, GridValue::Timecode(TimecodeValue::Second)) && rate.is_drop() {
+            let tc = Timecode::from_frames(rate.frames_at(pos, sr), rate);
+            let magnitude = tc.hours.saturating_mul(3600).saturating_add(tc.minutes.saturating_mul(60)).saturating_add(tc.seconds);
+            let mut k = if tc.negative { magnitude.saturating_neg() } else { magnitude };
+            while self.abs_line(k, sr, rate) > pos {
+                let previous = k.saturating_sub(1);
+                if previous == k {
+                    break;
+                }
+                k = previous;
+            }
+            while self.abs_line(k.saturating_add(1), sr, rate) <= pos {
+                let next = k.saturating_add(1);
+                if next == k {
+                    break;
+                }
+                k = next;
+            }
+            return k;
+        }
+        let mut k = if let Some(frames) = self.frame_step(rate) {
+            let step = (rate.samples_per_frame(sr) * frames).max(1.0);
+            (pos as f64 / step).floor() as i64
+        } else {
+            match *self {
+                GridValue::Seconds(s) => (pos as f64 / Self::seconds_step(s, sr)).floor() as i64,
+                GridValue::Samples(n) => return pos.div_euclid(n.max(1)),
+                GridValue::Note { .. } => return 0,
+                GridValue::Frames(_) | GridValue::Timecode(_) | GridValue::FeetFrames(_) => return 0,
+            }
+        };
+        // Lines are rounded to whole samples, so the floored index can be one off either way.
+        if self.abs_line(k, sr, rate) > pos {
+            k = k.saturating_sub(1);
+        } else if self.abs_line(k.saturating_add(1), sr, rate) <= pos {
+            k = k.saturating_add(1);
+        }
+        k
+    }
+
+    /// The exact (fractional) Seconds step in samples, at least one sample.
+    fn seconds_step(s: f64, sr: SampleRate) -> f64 {
+        (s.clamp(0.000_01, 3600.0) * sr.as_f64()).max(1.0)
+    }
+
+    /// Maps a signed whole-second timecode label to its physical frame at a drop-frame rate.
+    fn drop_second_frame(index: i64, rate: FrameRate) -> i64 {
+        let seconds = index.unsigned_abs();
+        let total_minutes = seconds / 60;
+        let frames = if seconds.is_multiple_of(60) && !total_minutes.is_multiple_of(10) { if rate.nominal() >= 60 { 4 } else { 2 } } else { 0 };
+        Timecode {
+            negative: index < 0,
+            hours: i64::try_from(seconds / 3600).unwrap_or(i64::MAX),
+            minutes: i64::try_from((seconds / 60) % 60).unwrap_or(0),
+            seconds: i64::try_from(seconds % 60).unwrap_or(0),
+            frames,
+        }
+        .to_frames(rate)
+    }
+
+    /// A frame-based increment as a possibly fractional number of frames.
+    fn frame_step(&self, rate: FrameRate) -> Option<f64> {
+        match *self {
+            GridValue::Frames(frames) => Some(frames.clamp(1, 1_000_000) as f64),
+            GridValue::Timecode(value) => Some(value.frames(rate)),
+            GridValue::FeetFrames(value) => Some(value.frames()),
+            _ => None,
+        }
+    }
+
+    /// The first grid line strictly after `line`.
+    pub fn next_line(&self, line: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> Samples {
+        if let Self::FeetFrames(value) = *self {
+            return value.next_line(line, sr, rate, 0);
+        }
+        if !matches!(self, GridValue::Note { .. }) {
+            let next = self.abs_line(self.abs_index_at_or_before(line, sr, rate).saturating_add(1), sr, rate);
+            return if next > line { next } else { line.saturating_add(1) };
+        }
+        let step = self.step_samples(line, sr, map, rate);
+        let candidate = self.line_at_or_before(line.saturating_add(step), sr, map, rate);
+        let next = if candidate > line { candidate } else { line.saturating_add(step) };
+        if matches!(self, GridValue::Note { value: NoteValue::Bar, .. }) {
+            return next;
+        }
+        let tick = map.samples_to_ticks(line, sr);
+        let bar = map.bar_beat_at_tick(tick).bar;
+        let next_bar = map.tick_to_samples(map.bar_start_tick(bar.saturating_add(1)), sr);
+        if next_bar > line { next.min(next_bar) } else { next }
+    }
+
+    /// All grid lines within `[start, end)`, capped at `max` lines.
+    pub fn lines(&self, start: Samples, end: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate, max: usize) -> Vec<Samples> {
+        if let Self::FeetFrames(value) = *self {
+            return value.lines(start, end, sr, rate, 0, max);
+        }
+        let mut out = Vec::new();
+        let mut p = self.line_at_or_before(start, sr, map, rate);
+        while p < end && out.len() < max {
+            if p >= start {
+                out.push(p);
+            }
+            let n = self.next_line(p, sr, map, rate);
+            if n <= p {
+                break;
+            }
+            p = n;
+        }
+        out
+    }
+}
+
+/// Moves one position through an ordered increment menu without wrapping.
+fn step_enum<T: Copy + PartialEq>(values: &[T], value: T, larger: bool) -> Option<T> {
+    let index = values.iter().position(|candidate| *candidate == value)?;
+    let next = if larger { index.checked_sub(1) } else { index.checked_add(1) }?;
+    values.get(next).copied()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::soundcraft::TimeFormat;
+
+    /// Frame origins are subtracted before rounding whole frames, quarter frames and subframes.
+    #[test]
+    fn feet_frames_origins_round_only_after_applying_the_frame_offset() {
+        let (sr, rate) = (SampleRate::HZ_48000, FrameRate::Fps29_97);
+        for at in [49_650, 100_901, 177_778] {
+            assert_eq!(FeetFramesValue::Foot.line_at_or_before(at, sr, rate, 1), at);
+            assert_eq!(FeetFramesValue::Foot.snap(at - 1, sr, rate, 1), at);
+        }
+        assert_eq!(FeetFramesValue::QuarterFrame.snap(50_049, sr, rate, 1), 50_050);
+        assert_eq!(FeetFramesValue::SubFrame.lines(49_665, 49_667, sr, rate, 1, 4), [49_666]);
+    }
+
+    /// Grid lines use the same ceil-rounded sample boundary as typed positions at fractional rates.
+    #[test]
+    fn feet_frames_grid_lines_match_typed_positions_at_fractional_rates() {
+        let sr = SampleRate::HZ_48000;
+        let map = TempoMap::default();
+        for rate in [FrameRate::Fps23_976, FrameRate::Fps29_97, FrameRate::Fps29_97Drop, FrameRate::Fps59_94Drop] {
+            for origin in [-17, -1, 1, 17] {
+                for feet in [-64, -2, 0, 1, 2, 4, 7, 12, 128] {
+                    let text = format!("{feet}+00");
+                    let at = crate::soundcraft::format::parse_position(&text, TimeFormat::FeetFrames, sr, &map, rate, 0, origin).unwrap();
+                    for value in FeetFramesValue::ALL {
+                        assert_eq!(value.line_at_or_before(at, sr, rate, origin), at, "{rate:?} {value:?} origin {origin}, {text}");
+                    }
+                }
+            }
+        }
+    }
+
+    /// Dense subframes retain distinct sample lines and remain bounded with extreme signed origins.
+    #[test]
+    fn feet_frames_subframes_handle_dense_steps_and_extreme_origins() {
+        let sr = SampleRate::new(8_000).unwrap();
+        let rate = FrameRate::Fps120;
+        for origin in [i64::MIN, -1, 0, 1, i64::MAX] {
+            assert_eq!(FeetFramesValue::SubFrame.lines(-3, 4, sr, rate, origin, 20), [-3, -2, -1, 0, 1, 2, 3]);
+            for at in [i64::MIN, -1, 0, 1, i64::MAX] {
+                assert_eq!(FeetFramesValue::SubFrame.line_at_or_before(at, sr, rate, origin), at);
+                assert_eq!(FeetFramesValue::SubFrame.snap(at, sr, rate, origin), at);
+            }
+        }
+    }
+
+    #[test]
+    fn grid_lines_are_their_own_line_at_odd_tempos() {
+        let (g, sr, rate) = (GridValue::default(), SampleRate::HZ_48000, FrameRate::Fps30);
+        for bpm in [90.0, 95.0, 110.0, 130.0, 140.0] {
+            let map = TempoMap::new(bpm, 4, 4).unwrap();
+            let mut line = 0;
+            for _ in 0..64 {
+                assert_eq!(g.line_at_or_before(line, sr, &map, rate), line, "{bpm} bpm");
+                line = g.next_line(line, sr, &map, rate);
+            }
+        }
+    }
+
+    /// Musical boundaries stay exact across a tempo change while absolute scales remain
+    /// independent of the tempo map.
+    #[test]
+    fn grids_stay_aligned_across_a_tempo_change() {
+        let (sr, rate) = (SampleRate::HZ_48000, FrameRate::Fps29_97Drop);
+        let mut map = TempoMap::default();
+        map.set_tempo(TICKS_PER_QUARTER * 4, 90.0).unwrap();
+        let musical = GridValue::Note { value: NoteValue::Quarter, dotted: false, triplet: false };
+        for tick in [0, TICKS_PER_QUARTER * 3, TICKS_PER_QUARTER * 4, TICKS_PER_QUARTER * 5] {
+            let line = map.tick_to_samples(tick, sr);
+            assert_eq!(musical.line_at_or_before(line, sr, &map, rate), line);
+        }
+        for absolute in [
+            GridValue::Seconds(0.5),
+            GridValue::Timecode(TimecodeValue::Second),
+            GridValue::FeetFrames(FeetFramesValue::Foot),
+            GridValue::Samples(1_000),
+        ] {
+            let line = absolute.next_line(absolute.line_at_or_before(100_000, sr, &map, rate), sr, &map, rate);
+            assert_eq!(absolute.line_at_or_before(line, sr, &map, rate), line, "{absolute:?}");
+        }
+    }
+
+    #[test]
+    fn sixteenth_grid_at_120() {
+        let g = GridValue::default();
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps30);
+        assert_eq!(g.step_samples(0, sr, &map, rate), 6000);
+        assert_eq!(g.snap(2900, sr, &map, rate), 0);
+        assert_eq!(g.snap(3100, sr, &map, rate), 6000);
+        assert_eq!(g.lines(0, 24_000, sr, &map, rate, 100), vec![0, 6000, 12000, 18000]);
+    }
+
+    /// Absolute increments report their expected sample lengths at a fixed rate.
+    #[test]
+    fn absolute_grids() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps25);
+        assert_eq!(GridValue::Seconds(1.0).snap(70_000, sr, &map, rate), 48_000);
+        assert_eq!(GridValue::Frames(1).step_samples(0, sr, &map, rate), 1920);
+        assert_eq!(GridValue::Timecode(TimecodeValue::Second).step_samples(0, sr, &map, rate), 48_000);
+        assert_eq!(GridValue::Timecode(TimecodeValue::FiveFrames).step_samples(0, sr, &map, rate), 9_600);
+        assert_eq!(GridValue::Timecode(TimecodeValue::HalfFrame).step_samples(0, sr, &map, rate), 960);
+        assert_eq!(GridValue::Timecode(TimecodeValue::QuarterFrame).step_samples(0, sr, &map, rate), 480);
+        assert_eq!(GridValue::Timecode(TimecodeValue::SubFrame).step_samples(0, sr, &map, rate), 19);
+        assert_eq!(GridValue::FeetFrames(FeetFramesValue::Foot).step_samples(0, sr, &map, rate), 30_720);
+        assert_eq!(GridValue::Samples(0).step_samples(0, sr, &map, rate), 1);
+    }
+
+    /// Bar length follows the meter while a whole note always spans four quarter notes.
+    #[test]
+    fn a_bar_and_a_whole_note_differ_in_three_four() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::new(120.0, 3, 4).unwrap(), FrameRate::Fps25);
+        let note = |value| GridValue::Note { value, dotted: false, triplet: false };
+        assert_eq!(note(NoteValue::Bar).step_samples(0, sr, &map, rate), 72_000);
+        assert_eq!(note(NoteValue::Whole).step_samples(0, sr, &map, rate), 96_000);
+        assert_eq!(note(NoteValue::Bar).line_at_or_before(96_000, sr, &map, rate), 72_000);
+        assert_eq!(note(NoteValue::Whole).line_at_or_before(96_000, sr, &map, rate), 96_000);
+        assert_eq!(note(NoteValue::Half).lines(0, 150_000, sr, &map, rate, 10), [0, 48_000, 72_000, 120_000, 144_000]);
+    }
+
+    #[test]
+    fn dotted_bar_grid_keeps_its_spacing_across_bars() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps25);
+        let grid = GridValue::Note { value: NoteValue::Bar, dotted: true, triplet: false };
+        assert_eq!(grid.line_at_or_before(143_999, sr, &map, rate), 0);
+        assert_eq!(grid.line_at_or_before(144_000, sr, &map, rate), 144_000);
+        assert_eq!(grid.next_line(0, sr, &map, rate), 144_000);
+    }
+
+    #[test]
+    fn dotted_note_does_not_skip_a_meter_change_boundary() {
+        let sr = SampleRate::HZ_48000;
+        let mut map = TempoMap::default();
+        map.set_meter(TICKS_PER_QUARTER * 4, 2, 4).unwrap();
+        let rate = FrameRate::Fps25;
+        let grid = GridValue::Note { value: NoteValue::Half, dotted: true, triplet: false };
+        assert_eq!(grid.next_line(72_000, sr, &map, rate), 96_000);
+        assert!(grid.lines(72_000, 120_000, sr, &map, rate, 10).contains(&96_000));
+        assert_eq!(grid.snap(90_000, sr, &map, rate), 96_000);
+    }
+
+    #[test]
+    fn seconds_grid_lines_land_on_whole_seconds() {
+        let (sr, map, rate) = (SampleRate::HZ_44100, TempoMap::default(), FrameRate::Fps30);
+        for g in [GridValue::Seconds(0.001), GridValue::Seconds(0.01)] {
+            for n in 0..20 {
+                let s = n * 44_100;
+                assert_eq!(g.snap(s, sr, &map, rate), s, "{g:?} at {n} s");
+                assert_eq!(g.line_at_or_before(s, sr, &map, rate), s, "{g:?} at {n} s");
+            }
+        }
+    }
+
+    /// Legacy frame grids stay aligned to exact frame starts at fractional rates.
+    #[test]
+    fn frame_grid_lines_land_on_frame_starts() {
+        let sr = SampleRate::HZ_48000;
+        let map = TempoMap::default();
+        for rate in [FrameRate::Fps29_97, FrameRate::Fps23_976] {
+            for f in [1, 10] {
+                let g = GridValue::Frames(f);
+                for k in (0..5000).step_by(37) {
+                    let s = rate.samples_at_frame(k, sr);
+                    let line = rate.samples_at_frame(k.div_euclid(f) * f, sr);
+                    assert_eq!(g.line_at_or_before(s, sr, &map, rate), line, "{rate:?} {f} frames at frame {k}");
+                    if k % f == 0 {
+                        assert_eq!(g.snap(s, sr, &map, rate), s, "{rate:?} {f} frames at frame {k}");
+                    }
+                }
+                let start = rate.samples_at_frame(4000, sr);
+                let end = rate.samples_at_frame(4000 + 20 * f, sr);
+                let want: Vec<_> = (0..20).map(|i| rate.samples_at_frame(4000 + i * f, sr)).collect();
+                assert_eq!(g.lines(start, end, sr, &map, rate, 100), want, "{rate:?} {f} frames");
+            }
+        }
+    }
+
+    /// Named whole- and sub-frame grids retain the exact-multiple calculation used by legacy frame grids.
+    #[test]
+    fn named_frame_grids_land_on_exact_subdivisions() {
+        let sr = SampleRate::HZ_48000;
+        let map = TempoMap::default();
+        let grids = TimecodeValue::ALL.into_iter().map(GridValue::Timecode).chain(FeetFramesValue::ALL.into_iter().map(GridValue::FeetFrames));
+        for rate in [FrameRate::Fps29_97, FrameRate::Fps23_976] {
+            for grid in grids.clone() {
+                for index in 0..200 {
+                    let line = grid.abs_line(index, sr, rate);
+                    assert_eq!(grid.line_at_or_before(line, sr, &map, rate), line, "{grid:?} {rate:?} line {index}");
+                    assert_eq!(grid.next_line(line, sr, &map, rate), grid.abs_line(index + 1, sr, rate), "{grid:?} {rate:?} line {index}");
+                }
+            }
+        }
+    }
+
+    /// Drop-frame second grids follow labelled second boundaries in both timeline directions.
+    #[test]
+    fn drop_frame_second_grids_follow_timecode_labels() {
+        let sr = SampleRate::HZ_48000;
+        let map = TempoMap::default();
+        let grid = GridValue::Timecode(TimecodeValue::Second);
+        for rate in [FrameRate::Fps29_97Drop, FrameRate::Fps59_94Drop] {
+            for seconds in [0, 59, 60, 61, 600, 601, 3600] {
+                let frame = GridValue::drop_second_frame(seconds, rate);
+                let line = rate.samples_at_frame(frame, sr);
+                assert_eq!(grid.line_at_or_before(line, sr, &map, rate), line, "{rate:?} second {seconds}");
+                let negative_line = rate.samples_at_frame(-frame, sr);
+                assert_eq!(grid.line_at_or_before(negative_line, sr, &map, rate), negative_line, "{rate:?} second -{seconds}");
+                for offset in -2..=rate.nominal() + 2 {
+                    let position = rate.samples_at_frame(frame.saturating_add(offset), sr);
+                    let before = grid.line_at_or_before(position, sr, &map, rate);
+                    assert!(before <= position, "{rate:?} second {seconds}, frame offset {offset}");
+                    assert!(grid.next_line(before, sr, &map, rate) > position, "{rate:?} second {seconds}, frame offset {offset}");
+                }
+            }
+            let labelled = Timecode { negative: false, hours: 0, minutes: 1, seconds: 1, frames: 0 }.to_samples(rate, sr);
+            assert_eq!(grid.snap(labelled, sr, &map, rate), labelled);
+        }
+
+        for (rate, minute_frame) in [(FrameRate::Fps29_97Drop, 1800), (FrameRate::Fps59_94Drop, 3600)] {
+            let boundary = rate.samples_at_frame(minute_frame, sr);
+            assert_eq!(grid.line_at_or_before(boundary, sr, &map, rate), boundary, "{rate:?} positive minute boundary");
+            assert_eq!(grid.snap(boundary, sr, &map, rate), boundary, "{rate:?} positive minute snap");
+            let negative_boundary = rate.samples_at_frame(-minute_frame, sr);
+            assert_eq!(grid.line_at_or_before(negative_boundary, sr, &map, rate), negative_boundary, "{rate:?} negative minute boundary");
+            assert_eq!(grid.snap(negative_boundary, sr, &map, rate), negative_boundary, "{rate:?} negative minute snap");
+        }
+    }
+
+    #[test]
+    fn lines_are_capped() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps25);
+        assert_eq!(GridValue::Samples(1).lines(0, 1_000_000, sr, &map, rate, 50).len(), 50);
+    }
+
+    #[test]
+    fn triplets_and_dots() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps25);
+        let t = GridValue::Note { value: NoteValue::Quarter, dotted: false, triplet: true };
+        assert_eq!(t.step_samples(0, sr, &map, rate), 16_000);
+        let d = GridValue::Note { value: NoteValue::Quarter, dotted: true, triplet: false };
+        assert_eq!(d.step_samples(0, sr, &map, rate), 36_000);
+    }
+
+    /// Stepping follows each menu ladder and stops at its endpoints.
+    #[test]
+    fn values_step_to_the_next_larger_or_smaller() {
+        let note = |value, triplet| GridValue::Note { value, dotted: false, triplet };
+        assert_eq!(note(NoteValue::Sixteenth, false).stepped(true), note(NoteValue::Eighth, false));
+        assert_eq!(note(NoteValue::Eighth, true).stepped(false), note(NoteValue::Sixteenth, true));
+        assert_eq!(note(NoteValue::Bar, false).stepped(true), note(NoteValue::Bar, false));
+        assert_eq!(note(NoteValue::SixtyFourth, false).stepped(false), note(NoteValue::SixtyFourth, false));
+        assert_eq!(GridValue::Seconds(0.01).stepped(true), GridValue::Seconds(0.1));
+        assert_eq!(GridValue::Seconds(0.5).stepped(false), GridValue::Seconds(0.1));
+        assert_eq!(GridValue::Seconds(1.0).stepped(true), GridValue::Seconds(1.0));
+        assert_eq!(GridValue::Frames(1).stepped(true), GridValue::Frames(10));
+        assert_eq!(GridValue::Timecode(TimecodeValue::Frame).stepped(false), GridValue::Timecode(TimecodeValue::HalfFrame));
+        assert_eq!(GridValue::FeetFrames(FeetFramesValue::Frame).stepped(true), GridValue::FeetFrames(FeetFramesValue::Foot));
+        assert_eq!(GridValue::Samples(100).stepped(false), GridValue::Samples(10));
+        assert_eq!(GridValue::Samples(1).stepped(true), GridValue::Samples(2));
+        assert_eq!(GridValue::Samples(1).stepped(false), GridValue::Samples(1));
+    }
+
+    #[test]
+    fn snap_at_extreme_position_does_not_overflow() {
+        let sr = SampleRate::new(8000).unwrap();
+        let map = TempoMap::new(1000.0, 4, 4).unwrap();
+        let _ = GridValue::default().snap(i64::MAX, sr, &map, FrameRate::Fps30);
+    }
+}
diff --git a/crates/time/src/soundcraft/mod.rs b/crates/time/src/soundcraft/mod.rs
new file mode 100644
index 000000000..075a2ade7
--- /dev/null
+++ b/crates/time/src/soundcraft/mod.rs
@@ -0,0 +1,186 @@
+//! SoundCraft timebases.
+//!
+//! Every position in a session is an absolute sample index (`i64`) at the session sample rate.
+//! This crate converts those positions to and from the five Pro Tools-style timebases
+//! (Bars|Beats, Min:Secs, Timecode, Feet+Frames, Samples) through a [`TempoMap`], and computes
+//! grid lines and snapping for the Grid / Nudge values.
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+
+mod format;
+mod grid;
+mod tempo;
+mod timecode;
+
+pub use format::{TimeFormat, format_length, format_position, parse_position};
+pub use grid::{FeetFramesValue, GridScale, GridValue, NoteValue, TimecodeValue};
+pub use tempo::{BarBeat, MeterEvent, TICKS_PER_QUARTER, TempoEvent, TempoMap};
+pub use timecode::{FrameRate, Timecode};
+
+/// A position or length in samples.
+pub type Samples = i64;
+
+/// Largest position accepted from parameters and files: 2^40 samples (about 265 days at 48 kHz).
+/// Clamping there keeps every later addition and subtraction on positions far away from overflow.
+pub const MAX_POSITION: Samples = 1 << 40;
+
+/// Errors from parsing or converting time values.
+#[derive(Debug, Clone, PartialEq, thiserror::Error)]
+pub enum TimeError {
+    #[error("cannot parse `{0}` as a {1} value")]
+    Parse(String, &'static str),
+    #[error("invalid sample rate {0}")]
+    SampleRate(u32),
+    #[error("invalid tempo {0}")]
+    Tempo(f64),
+    #[error("invalid meter {0}/{1}")]
+    Meter(u32, u32),
+}
+
+/// Session sample rate stored as the original wire value.
+///
+/// `new` validates values created by the application. Deserialization remains
+/// permissive so legacy or damaged sessions retain their original value and
+/// can be diagnosed by the application instead of failing before recovery.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub struct SampleRate(u32);
+
+impl SampleRate {
+    pub const HZ_44100: SampleRate = SampleRate(44_100);
+    pub const HZ_48000: SampleRate = SampleRate(48_000);
+    pub const COMMON: [u32; 8] = [44_100, 48_000, 88_200, 96_000, 176_400, 192_000, 352_800, 384_000];
+
+    pub fn new(hz: u32) -> Result<Self, TimeError> {
+        if (8_000..=768_000).contains(&hz) { Ok(SampleRate(hz)) } else { Err(TimeError::SampleRate(hz)) }
+    }
+    pub fn hz(self) -> u32 {
+        self.0
+    }
+    /// Whether this wire value is supported for normal session operation.
+    pub fn is_supported(self) -> bool {
+        (8_000..=768_000).contains(&self.0)
+    }
+    pub fn as_f64(self) -> f64 {
+        f64::from(self.0)
+    }
+    /// Samples → seconds.
+    pub fn seconds(self, s: Samples) -> f64 {
+        s as f64 / self.as_f64()
+    }
+    /// Seconds → samples, rounded to nearest and saturated.
+    pub fn samples(self, seconds: f64) -> Samples {
+        to_samples(seconds * self.as_f64())
+    }
+}
+
+impl Default for SampleRate {
+    fn default() -> Self {
+        SampleRate::HZ_48000
+    }
+}
+
+/// Round a float sample count to `i64`, mapping NaN to 0 and saturating infinities.
+pub fn to_samples(v: f64) -> Samples {
+    if v.is_nan() {
+        0
+    } else if v >= i64::MAX as f64 {
+        i64::MAX
+    } else if v <= i64::MIN as f64 {
+        i64::MIN
+    } else {
+        v.round() as i64
+    }
+}
+
+/// A half-open sample range `[start, end)`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub struct Range {
+    pub start: Samples,
+    pub end: Samples,
+}
+
+impl Range {
+    pub fn new(a: Samples, b: Samples) -> Self {
+        if a <= b { Range { start: a, end: b } } else { Range { start: b, end: a } }
+    }
+    pub fn point(at: Samples) -> Self {
+        Range { start: at, end: at }
+    }
+    pub fn len(&self) -> Samples {
+        self.end.saturating_sub(self.start)
+    }
+    pub fn is_empty(&self) -> bool {
+        self.end <= self.start
+    }
+    pub fn contains(&self, s: Samples) -> bool {
+        s >= self.start && s < self.end
+    }
+    pub fn overlaps(&self, o: &Range) -> bool {
+        !self.is_empty() && !o.is_empty() && self.start < o.end && o.start < self.end
+    }
+    pub fn intersect(&self, o: &Range) -> Option<Range> {
+        let s = self.start.max(o.start);
+        let e = self.end.min(o.end);
+        (s < e).then_some(Range { start: s, end: e })
+    }
+    pub fn shifted(&self, by: Samples) -> Range {
+        Range { start: self.start.saturating_add(by), end: self.end.saturating_add(by) }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sample_rate_serde_preserves_unsupported_wire_values_for_recovery() {
+        for wire in [0, 7_999, 768_001, u32::MAX] {
+            let rate: SampleRate = serde_json::from_value(serde_json::json!(wire)).unwrap();
+            assert_eq!(rate.hz(), wire);
+            assert!(!rate.is_supported());
+            assert_eq!(serde_json::to_value(rate).unwrap(), serde_json::json!(wire));
+        }
+        let rate = SampleRate::new(48_000).unwrap();
+        assert_eq!(serde_json::to_string(&rate).unwrap(), "48000");
+        assert_eq!(serde_json::from_str::<SampleRate>("48000").unwrap(), rate);
+        assert!(rate.is_supported());
+    }
+
+    #[test]
+    fn empty_ranges_never_overlap() {
+        let point = Range::point(5);
+        let span = Range::new(0, 10);
+        assert!(!point.overlaps(&span));
+        assert!(!span.overlaps(&point));
+        assert!(Range::new(0, 5).overlaps(&span));
+    }
+
+    #[test]
+    fn sample_rate_bounds() {
+        assert!(SampleRate::new(48_000).is_ok());
+        assert!(SampleRate::new(0).is_err());
+        assert!(SampleRate::new(10_000_000).is_err());
+    }
+
+    #[test]
+    fn seconds_round_trip() {
+        let sr = SampleRate::HZ_44100;
+        assert_eq!(sr.samples(1.0), 44_100);
+        assert!((sr.seconds(22_050) - 0.5).abs() < 1e-12);
+    }
+
+    #[test]
+    fn to_samples_is_total() {
+        assert_eq!(to_samples(f64::NAN), 0);
+        assert_eq!(to_samples(f64::INFINITY), i64::MAX);
+        assert_eq!(to_samples(f64::NEG_INFINITY), i64::MIN);
+    }
+
+    #[test]
+    fn range_ops() {
+        let a = Range::new(10, 0);
+        assert_eq!(a, Range { start: 0, end: 10 });
+        assert_eq!(a.intersect(&Range::new(5, 20)), Some(Range::new(5, 10)));
+        assert_eq!(a.intersect(&Range::new(10, 20)), None);
+        assert!(a.contains(9) && !a.contains(10));
+    }
+}
diff --git a/crates/time/src/soundcraft/tempo.rs b/crates/time/src/soundcraft/tempo.rs
new file mode 100644
index 000000000..10f44b8dc
--- /dev/null
+++ b/crates/time/src/soundcraft/tempo.rs
@@ -0,0 +1,622 @@
+//! Tempo and meter maps: the conversion between musical time (ticks) and samples.
+
+use super::{MAX_POSITION, SampleRate, Samples, TimeError, to_samples};
+
+/// Ticks per quarter note (Pro Tools' resolution).
+pub const TICKS_PER_QUARTER: i64 = 960;
+
+/// A tempo change at a tick position. `bpm` is quarter notes per minute.
+#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct TempoEvent {
+    pub tick: i64,
+    pub bpm: f64,
+}
+
+/// A meter (time signature) change at a tick position, which must fall on a bar line.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct MeterEvent {
+    pub tick: i64,
+    pub numerator: u32,
+    pub denominator: u32,
+}
+
+impl MeterEvent {
+    pub fn ticks_per_beat(&self) -> i64 {
+        let d = i64::from(self.denominator.max(1));
+        (TICKS_PER_QUARTER * 4 / d).max(1)
+    }
+    pub fn ticks_per_bar(&self) -> i64 {
+        self.ticks_per_beat().saturating_mul(i64::from(self.numerator.max(1)))
+    }
+}
+
+/// A musical position: 1-based bar and beat plus ticks within the beat.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct BarBeat {
+    pub bar: i64,
+    pub beat: i64,
+    pub tick: i64,
+}
+
+/// Tempo and meter changes for a session. Always has at least one of each, at tick 0.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+#[serde(from = "TempoMapData")]
+pub struct TempoMap {
+    tempos: Vec<TempoEvent>,
+    meters: Vec<MeterEvent>,
+    /// For each tempo event, the elapsed time at its tick in quarter-note minutes (ticks / bpm,
+    /// summed over the earlier segments). Lets tick/sample conversions binary-search the segment
+    /// instead of walking every earlier tempo change, so converting many positions against a large
+    /// tempo map stays O(log n) each. Rebuilt whenever `tempos` changes.
+    #[serde(skip)]
+    elapsed: Vec<f64>,
+}
+
+/// The serialized form of [`TempoMap`], without the derived lookup table.
+#[derive(serde::Deserialize)]
+struct TempoMapData {
+    tempos: Vec<TempoEvent>,
+    meters: Vec<MeterEvent>,
+}
+
+impl From<TempoMapData> for TempoMap {
+    fn from(d: TempoMapData) -> Self {
+        TempoMap::from_parts(d.tempos, d.meters)
+    }
+}
+
+impl Default for TempoMap {
+    fn default() -> Self {
+        TempoMap::from_parts(vec![TempoEvent { tick: 0, bpm: 120.0 }], vec![MeterEvent { tick: 0, numerator: 4, denominator: 4 }])
+    }
+}
+
+fn valid_bpm(bpm: f64) -> Result<f64, TimeError> {
+    if bpm.is_finite() && (5.0..=1000.0).contains(&bpm) { Ok(bpm) } else { Err(TimeError::Tempo(bpm)) }
+}
+
+fn valid_meter(numerator: u32, denominator: u32) -> bool {
+    (1..=64).contains(&numerator) && [1, 2, 4, 8, 16, 32, 64].contains(&denominator)
+}
+
+impl TempoMap {
+    fn from_parts(tempos: Vec<TempoEvent>, meters: Vec<MeterEvent>) -> Self {
+        let mut m = TempoMap { tempos, meters, elapsed: Vec::new() };
+        m.reindex();
+        m
+    }
+
+    /// Rebuild `elapsed` from `tempos`. The first segment runs from tick 0 at the first tempo.
+    fn reindex(&mut self) {
+        let mut elapsed = Vec::with_capacity(self.tempos.len());
+        let mut acc = 0.0;
+        let mut seg_tick = 0i64;
+        let mut bpm = self.tempos.first().map_or(120.0, |e| e.bpm);
+        for (i, e) in self.tempos.iter().enumerate() {
+            if i > 0 {
+                // Saturating: a file's ticks are indexed before `sanitize` orders them.
+                acc += e.tick.saturating_sub(seg_tick) as f64 / bpm;
+                seg_tick = e.tick;
+                bpm = e.bpm;
+            }
+            elapsed.push(acc);
+        }
+        self.elapsed = elapsed;
+    }
+
+    /// Samples per quarter-note minute (the unit of `elapsed`) at `sr`.
+    fn samples_per_elapsed(sr: SampleRate) -> f64 {
+        sr.as_f64() * 60.0 / TICKS_PER_QUARTER as f64
+    }
+
+    /// The tempo segment `i` (an index into `tempos`, 0 when it is empty): its start tick (0 for
+    /// the first), bpm and elapsed time at its start.
+    fn segment(&self, i: usize) -> (i64, f64, f64) {
+        let bpm = self.tempos.get(i).or(self.tempos.first()).map_or(120.0, |e| e.bpm);
+        let tick = if i == 0 { 0 } else { self.tempos.get(i).map_or(0, |e| e.tick) };
+        (tick, bpm, self.elapsed.get(i).copied().unwrap_or(0.0))
+    }
+
+    pub fn new(bpm: f64, numerator: u32, denominator: u32) -> Result<Self, TimeError> {
+        let mut m = TempoMap::default();
+        m.set_tempo(0, bpm)?;
+        m.set_meter(0, numerator, denominator)?;
+        Ok(m)
+    }
+
+    pub fn tempos(&self) -> &[TempoEvent] {
+        &self.tempos
+    }
+    pub fn meters(&self) -> &[MeterEvent] {
+        &self.meters
+    }
+
+    /// Repair a map read from a file: only valid tempos and meters within `0..=MAX_POSITION` ticks, in
+    /// tick order, with one of each at tick 0.
+    pub fn sanitize(&mut self) {
+        self.tempos.retain(|e| (0..=MAX_POSITION).contains(&e.tick) && valid_bpm(e.bpm).is_ok());
+        self.tempos.sort_by_key(|e| e.tick);
+        self.tempos.dedup_by_key(|e| e.tick);
+        if self.tempos.first().is_none_or(|e| e.tick > 0) {
+            let bpm = self.tempos.first().map_or(120.0, |e| e.bpm);
+            self.tempos.insert(0, TempoEvent { tick: 0, bpm });
+        }
+        self.meters.retain(|m| (0..=MAX_POSITION).contains(&m.tick) && valid_meter(m.numerator, m.denominator));
+        self.meters.sort_by_key(|m| m.tick);
+        self.meters.dedup_by_key(|m| m.tick);
+        if self.meters.first().is_none_or(|m| m.tick > 0) {
+            let (numerator, denominator) = self.meters.first().map_or((4, 4), |m| (m.numerator, m.denominator));
+            self.meters.insert(0, MeterEvent { tick: 0, numerator, denominator });
+        }
+        self.reindex();
+    }
+
+    /// Insert or replace the tempo at `tick`.
+    pub fn set_tempo(&mut self, tick: i64, bpm: f64) -> Result<(), TimeError> {
+        let bpm = valid_bpm(bpm)?;
+        let tick = tick.max(0);
+        match self.tempos.binary_search_by(|e| e.tick.cmp(&tick)) {
+            Ok(i) => {
+                if let Some(e) = self.tempos.get_mut(i) {
+                    e.bpm = bpm;
+                }
+            }
+            Err(i) => self.tempos.insert(i, TempoEvent { tick, bpm }),
+        }
+        self.reindex();
+        Ok(())
+    }
+
+    /// Remove a tempo event (the one at tick 0 is kept).
+    pub fn remove_tempo(&mut self, tick: i64) -> bool {
+        if tick == 0 {
+            return false;
+        }
+        let before = self.tempos.len();
+        self.tempos.retain(|e| e.tick != tick);
+        self.reindex();
+        before != self.tempos.len()
+    }
+
+    /// Insert or replace the meter at `tick` (snapped to the bar line at or before it).
+    /// Later meter changes keep their bar numbers, so they stay on bar lines.
+    pub fn set_meter(&mut self, tick: i64, numerator: u32, denominator: u32) -> Result<(), TimeError> {
+        if !valid_meter(numerator, denominator) {
+            return Err(TimeError::Meter(numerator, denominator));
+        }
+        let tick = if tick <= 0 { 0 } else { self.bar_start_tick(self.bar_beat_at_tick(tick).bar) };
+        let later = self.take_meters_after(tick);
+        self.put_meter(MeterEvent { tick, numerator, denominator });
+        self.restore_meters_at_bars(later);
+        Ok(())
+    }
+
+    /// Remove a meter event (the one at tick 0 is kept). Later meter changes keep their bar numbers.
+    pub fn remove_meter(&mut self, tick: i64) -> bool {
+        if tick == 0 || !self.meters.iter().any(|e| e.tick == tick) {
+            return false;
+        }
+        let later = self.take_meters_after(tick);
+        self.meters.retain(|e| e.tick != tick);
+        self.restore_meters_at_bars(later);
+        true
+    }
+
+    fn put_meter(&mut self, ev: MeterEvent) {
+        match self.meters.binary_search_by(|e| e.tick.cmp(&ev.tick)) {
+            Ok(i) => {
+                if let Some(e) = self.meters.get_mut(i) {
+                    *e = ev;
+                }
+            }
+            Err(i) => self.meters.insert(i, ev),
+        }
+    }
+
+    /// Remove the meters after `tick`, returning each with the bar it starts: the bar
+    /// [`Self::bar_beat_at_tick`] gives its tick, counted in one pass over the map rather than one
+    /// walk per meter, so a session with many meter changes edits in linear time.
+    fn take_meters_after(&mut self, tick: i64) -> Vec<(i64, MeterEvent)> {
+        let mut later = Vec::new();
+        let (mut bar, mut seg_tick) = (1i64, 0i64);
+        for (i, m) in self.meters.iter().enumerate() {
+            let tpb = m.ticks_per_bar();
+            if m.tick > tick {
+                later.push((bar.saturating_add(m.tick.saturating_sub(seg_tick) / tpb), *m));
+            }
+            if let Some(n) = self.meters.get(i + 1) {
+                bar = bar.saturating_add(ceil_div(n.tick.saturating_sub(seg_tick), tpb));
+                seg_tick = n.tick;
+            }
+        }
+        self.meters.retain(|e| e.tick <= tick);
+        later
+    }
+
+    /// The bar and tick of the last meter's segment, where [`Self::bar_start_tick`]'s walk ends.
+    fn last_segment(&self) -> (i64, i64) {
+        let (mut cur_bar, mut cur_tick) = (1i64, 0i64);
+        for (i, m) in self.meters.iter().enumerate() {
+            if let Some(n) = self.meters.get(i + 1) {
+                cur_bar = cur_bar.saturating_add(ceil_div(n.tick.saturating_sub(cur_tick), m.ticks_per_bar()));
+                cur_tick = n.tick;
+            }
+        }
+        (cur_bar, cur_tick)
+    }
+
+    /// Put meters back at the start of their bars under the current earlier meters, in bar order.
+    /// Each lands at or past the last meter, so the walk to its bar resumes from there; a bar
+    /// before it (meters off their bar lines) takes the full walk.
+    fn restore_meters_at_bars(&mut self, later: Vec<(i64, MeterEvent)>) {
+        let (mut cur_bar, mut cur_tick) = self.last_segment();
+        for (bar, ev) in later {
+            let tick = if bar >= cur_bar {
+                let tpb = self.meters.last().map_or(MeterEvent { tick: 0, numerator: 4, denominator: 4 }, |m| *m).ticks_per_bar();
+                cur_tick.saturating_add(bar.saturating_sub(cur_bar).saturating_mul(tpb))
+            } else {
+                self.bar_start_tick(bar)
+            };
+            self.put_meter(MeterEvent { tick, ..ev });
+            (cur_bar, cur_tick) = if bar >= cur_bar { (bar, tick) } else { self.last_segment() };
+        }
+    }
+
+    /// Tempo in effect at `tick`.
+    pub fn tempo_at_tick(&self, tick: i64) -> f64 {
+        let mut bpm = self.tempos.first().map_or(120.0, |e| e.bpm);
+        for e in &self.tempos {
+            if e.tick <= tick {
+                bpm = e.bpm;
+            } else {
+                break;
+            }
+        }
+        bpm
+    }
+
+    /// Meter in effect at `tick`.
+    pub fn meter_at_tick(&self, tick: i64) -> MeterEvent {
+        let mut m = self.meters.first().copied().unwrap_or(MeterEvent { tick: 0, numerator: 4, denominator: 4 });
+        for e in &self.meters {
+            if e.tick <= tick {
+                m = *e;
+            } else {
+                break;
+            }
+        }
+        m
+    }
+
+    fn samples_per_tick(bpm: f64, sr: SampleRate) -> f64 {
+        sr.as_f64() * 60.0 / (bpm * TICKS_PER_QUARTER as f64)
+    }
+
+    /// Ticks → samples (exact for constant-tempo segments).
+    pub fn tick_to_samples(&self, tick: i64, sr: SampleRate) -> Samples {
+        to_samples(self.tick_to_samples_f(tick, sr))
+    }
+
+    fn tick_to_samples_f(&self, tick: i64, sr: SampleRate) -> f64 {
+        // Tempo events after the first that start before `tick` (the segments it has passed).
+        let passed = self.tempos.get(1..).map_or(0, |rest| rest.partition_point(|e| e.tick < tick));
+        let (seg_tick, bpm, elapsed) = self.segment(passed);
+        elapsed * Self::samples_per_elapsed(sr) + (tick - seg_tick) as f64 * Self::samples_per_tick(bpm, sr)
+    }
+
+    /// Samples → ticks (fractional).
+    pub fn samples_to_ticks_f(&self, s: Samples, sr: SampleRate) -> f64 {
+        let s = s as f64;
+        let scale = Self::samples_per_elapsed(sr);
+        // Tempo events after the first that start at or before `s`.
+        let passed = self.elapsed.get(1..).map_or(0, |rest| rest.partition_point(|e| e * scale <= s));
+        let (seg_tick, bpm, elapsed) = self.segment(passed);
+        seg_tick as f64 + (s - elapsed * scale) / Self::samples_per_tick(bpm, sr)
+    }
+
+    pub fn samples_to_ticks(&self, s: Samples, sr: SampleRate) -> i64 {
+        to_samples(self.samples_to_ticks_f(s, sr))
+    }
+
+    /// Tick of the first beat of `bar` (1-based; bars before 1 extend the first meter backwards).
+    pub fn bar_start_tick(&self, bar: i64) -> i64 {
+        let mut cur_bar = 1i64;
+        let mut cur_tick = 0i64;
+        let first = self.meter_at_tick(0);
+        if bar < 1 {
+            return bar.saturating_sub(1).saturating_mul(first.ticks_per_bar());
+        }
+        for (i, m) in self.meters.iter().enumerate() {
+            let next_tick = self.meters.get(i + 1).map(|n| n.tick);
+            let tpb = m.ticks_per_bar();
+            let bars_in_seg = next_tick.map(|nt| ceil_div(nt.saturating_sub(cur_tick), tpb));
+            match bars_in_seg {
+                Some(n) if bar >= cur_bar.saturating_add(n) => {
+                    cur_bar = cur_bar.saturating_add(n);
+                    cur_tick = next_tick.unwrap_or(cur_tick);
+                }
+                _ => return cur_tick.saturating_add((bar - cur_bar).saturating_mul(tpb)),
+            }
+        }
+        cur_tick
+    }
+
+    /// Bar|beat|tick at `tick`.
+    pub fn bar_beat_at_tick(&self, tick: i64) -> BarBeat {
+        let first = self.meter_at_tick(0);
+        if tick < 0 {
+            let tpb = first.ticks_per_bar();
+            let abs = tick.unsigned_abs();
+            let tpb_u = tpb.unsigned_abs();
+            let bars_back_u = abs / tpb_u + u64::from(!abs.is_multiple_of(tpb_u));
+            let bars_back = i64::try_from(bars_back_u).unwrap_or(i64::MAX);
+            // Offset of `tick` inside its bar, without negating `i64::MIN`.
+            let within = ((tpb_u - abs % tpb_u) % tpb_u) as i64;
+            let beat_t = first.ticks_per_beat();
+            return BarBeat { bar: 1 - bars_back, beat: within / beat_t + 1, tick: within % beat_t };
+        }
+        let mut bar = 1i64;
+        let mut seg_tick = 0i64;
+        for (i, m) in self.meters.iter().enumerate() {
+            let tpb = m.ticks_per_bar();
+            if let Some(n) = self.meters.get(i + 1)
+                && tick >= n.tick
+            {
+                bar = bar.saturating_add(ceil_div(n.tick.saturating_sub(seg_tick), tpb));
+                seg_tick = n.tick;
+                continue;
+            }
+            let rel = tick - seg_tick;
+            let bars = rel / tpb;
+            let within = rel % tpb;
+            let beat_t = m.ticks_per_beat();
+            return BarBeat { bar: bar + bars, beat: within / beat_t + 1, tick: within % beat_t };
+        }
+        BarBeat { bar, beat: 1, tick: 0 }
+    }
+
+    /// Bar|beat|tick → tick.
+    pub fn tick_at_bar_beat(&self, bb: BarBeat) -> i64 {
+        let start = self.bar_start_tick(bb.bar);
+        let m = self.meter_at_tick(start);
+        start.saturating_add(bb.beat.saturating_sub(1).max(0).saturating_mul(m.ticks_per_beat())).saturating_add(bb.tick)
+    }
+
+    pub fn bar_beat_at(&self, s: Samples, sr: SampleRate) -> BarBeat {
+        self.bar_beat_at_tick(self.samples_to_ticks(s, sr))
+    }
+
+    pub fn samples_at_bar_beat(&self, bb: BarBeat, sr: SampleRate) -> Samples {
+        self.tick_to_samples(self.tick_at_bar_beat(bb), sr)
+    }
+
+    /// Scale every tempo by `factor` (Tempo Operations › Scale).
+    pub fn scale_tempos(&mut self, factor: f64) -> Result<(), TimeError> {
+        let mut out = self.tempos.clone();
+        for e in &mut out {
+            e.bpm = valid_bpm(e.bpm * factor)?;
+        }
+        self.tempos = out;
+        self.reindex();
+        Ok(())
+    }
+}
+
+/// Ceiling division for a non-negative `num` and positive `den`, without overflow.
+fn ceil_div(num: i64, den: i64) -> i64 {
+    num / den + i64::from(num % den != 0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_map_is_120_4_4() {
+        let m = TempoMap::default();
+        let sr = SampleRate::HZ_48000;
+        // One bar of 4/4 at 120 bpm = 2 seconds.
+        assert_eq!(m.samples_at_bar_beat(BarBeat { bar: 2, beat: 1, tick: 0 }, sr), 96_000);
+        assert_eq!(m.bar_beat_at(96_000, sr), BarBeat { bar: 2, beat: 1, tick: 0 });
+        assert_eq!(m.bar_beat_at(24_000, sr), BarBeat { bar: 1, beat: 2, tick: 0 });
+    }
+
+    #[test]
+    fn meter_near_max_tick_does_not_overflow() {
+        let mut m = TempoMap::default();
+        m.set_meter(i64::MAX, 7, 8).unwrap();
+        let bb = m.bar_beat_at_tick(i64::MAX);
+        assert!(bb.bar > 1);
+        assert!(m.bar_start_tick(bb.bar) > 0);
+        assert!(m.bar_start_tick(i64::MAX) > 0);
+    }
+
+    #[test]
+    fn minimum_bar_saturates_instead_of_overflowing() {
+        let m = TempoMap::default();
+        assert_eq!(m.bar_start_tick(i64::MIN), i64::MIN);
+        assert_eq!(m.bar_start_tick(0), -TICKS_PER_QUARTER * 4);
+    }
+
+    #[test]
+    fn minimum_beat_is_clamped_without_overflow() {
+        let m = TempoMap::default();
+        assert_eq!(m.tick_at_bar_beat(BarBeat { bar: 1, beat: i64::MIN, tick: 0 }), 0);
+    }
+
+    #[test]
+    fn bar_beat_at_min_tick_does_not_overflow() {
+        let m = TempoMap::default();
+        let bb = m.bar_beat_at_tick(i64::MIN);
+        assert!(bb.bar < 1);
+        assert!(bb.beat >= 1 && bb.tick >= 0);
+        assert_eq!(m.bar_beat_at_tick(-1).bar, 0);
+    }
+
+    #[test]
+    fn tempo_change_is_integrated() {
+        let mut m = TempoMap::default();
+        let sr = SampleRate::HZ_48000;
+        m.set_tempo(TICKS_PER_QUARTER * 4, 60.0).unwrap();
+        // Bar 1 at 120 = 96000 samples; bar 2 at 60 = 192000 samples.
+        assert_eq!(m.tick_to_samples(TICKS_PER_QUARTER * 8, sr), 96_000 + 192_000);
+        assert_eq!(m.samples_to_ticks(96_000 + 192_000, sr), TICKS_PER_QUARTER * 8);
+    }
+
+    #[test]
+    fn meter_change_counts_bars() {
+        let mut m = TempoMap::default();
+        // 2 bars of 4/4 then 3/4.
+        m.set_meter(TICKS_PER_QUARTER * 8, 3, 4).unwrap();
+        assert_eq!(m.bar_beat_at_tick(TICKS_PER_QUARTER * 8), BarBeat { bar: 3, beat: 1, tick: 0 });
+        assert_eq!(m.bar_beat_at_tick(TICKS_PER_QUARTER * 11), BarBeat { bar: 4, beat: 1, tick: 0 });
+        assert_eq!(m.bar_start_tick(4), TICKS_PER_QUARTER * 11);
+        let bb = BarBeat { bar: 4, beat: 2, tick: 10 };
+        assert_eq!(m.bar_beat_at_tick(m.tick_at_bar_beat(bb)), bb);
+    }
+
+    #[test]
+    fn editing_an_early_meter_keeps_later_bars_and_scales_linearly() {
+        // 200 000 meter changes, one per bar, built directly: a walk per meter would take
+        // minutes to edit here, and even to build through `set_meter`.
+        let mut m = TempoMap::new(120.0, 4, 4).unwrap();
+        let mut tick = 0;
+        for bar in 1..200_000i64 {
+            let numerator = 3 + (bar % 2) as u32;
+            tick += m.meters.last().map_or(0, MeterEvent::ticks_per_bar);
+            m.meters.push(MeterEvent { tick, numerator, denominator: 4 });
+        }
+        let sample = [1usize, 1_000, 199_998];
+        let bars = |m: &TempoMap| sample.map(|i| m.bar_beat_at_tick(m.meters[i].tick).bar);
+        assert_eq!(bars(&m), [2, 1_001, 199_999]);
+        m.set_meter(0, 7, 8).unwrap();
+        assert_eq!(bars(&m), [2, 1_001, 199_999], "later meters keep their bar numbers");
+        assert_eq!(m.meters.len(), 200_000);
+        assert!(m.meters.windows(2).all(|w| w[0].tick < w[1].tick));
+        assert!(m.remove_meter(m.meters[1].tick));
+        assert_eq!([1usize, 999, 199_997].map(|i| m.bar_beat_at_tick(m.meters[i].tick).bar), [3, 1_001, 199_999]);
+        // Meters off their bar lines (counted as bars 2 and 4) land where they always did: on
+        // bar 2 of the new meter, then two bars of their own later.
+        let mut off = TempoMap::new(120.0, 4, 4).unwrap();
+        off.meters.push(MeterEvent { tick: 100, numerator: 3, denominator: 4 });
+        off.meters.push(MeterEvent { tick: 5_000, numerator: 5, denominator: 4 });
+        off.set_meter(0, 2, 4).unwrap();
+        let placed: Vec<(i64, u32)> = off.meters.iter().map(|e| (e.tick, e.numerator)).collect();
+        assert_eq!(placed, vec![(0, 2), (2 * TICKS_PER_QUARTER, 3), (8 * TICKS_PER_QUARTER, 5)]);
+    }
+
+    #[test]
+    fn eighth_note_meters() {
+        let m = TempoMap::new(120.0, 6, 8).unwrap();
+        assert_eq!(m.bar_beat_at_tick(TICKS_PER_QUARTER * 3), BarBeat { bar: 2, beat: 1, tick: 0 });
+        assert_eq!(m.bar_beat_at_tick(TICKS_PER_QUARTER / 2), BarBeat { bar: 1, beat: 2, tick: 0 });
+    }
+
+    #[test]
+    fn sanitize_keeps_what_the_setters_accept() {
+        let tempo = |tick, bpm| TempoEvent { tick, bpm };
+        let meter = |tick, numerator, denominator| MeterEvent { tick, numerator, denominator };
+        let mut m = TempoMap::from_parts(
+            vec![tempo(960, 4e9), tempo(3840, 90.0), tempo(-5, 100.0), tempo(1920, 60.0), tempo(1920, 70.0)],
+            vec![meter(0, 0, 4), meter(3840, 3, 4)],
+        );
+        m.sanitize();
+        assert_eq!(m.tempos(), [tempo(0, 60.0), tempo(1920, 60.0), tempo(3840, 90.0)]);
+        assert_eq!(m.meters(), [meter(0, 3, 4), meter(3840, 3, 4)]);
+        let mut empty = TempoMap::from_parts(Vec::new(), Vec::new());
+        empty.sanitize();
+        assert_eq!(empty, TempoMap::default());
+    }
+
+    #[test]
+    fn sanitize_drops_events_beyond_the_position_range() {
+        let mut m = TempoMap::from_parts(
+            vec![TempoEvent { tick: 0, bpm: 120.0 }, TempoEvent { tick: i64::MAX, bpm: 90.0 }],
+            vec![MeterEvent { tick: 0, numerator: 4, denominator: 4 }, MeterEvent { tick: i64::MAX, numerator: 3, denominator: 4 }],
+        );
+        m.sanitize();
+        assert_eq!(m, TempoMap::default());
+        assert_eq!(m.bar_start_tick(2), TICKS_PER_QUARTER * 4);
+    }
+
+    #[test]
+    fn rejects_bad_values() {
+        let mut m = TempoMap::default();
+        assert!(m.set_tempo(0, f64::NAN).is_err());
+        assert!(m.set_tempo(0, 0.0).is_err());
+        assert!(m.set_meter(0, 0, 4).is_err());
+        assert!(m.set_meter(0, 4, 3).is_err());
+        assert!(!m.remove_tempo(0));
+    }
+
+    #[test]
+    fn negative_positions() {
+        let m = TempoMap::default();
+        assert_eq!(m.bar_beat_at_tick(-TICKS_PER_QUARTER * 4), BarBeat { bar: 0, beat: 1, tick: 0 });
+        assert_eq!(m.bar_beat_at_tick(-TICKS_PER_QUARTER), BarBeat { bar: 0, beat: 4, tick: 0 });
+    }
+
+    /// The segment walk the indexed conversions replaced, kept as the reference they must match.
+    fn linear_tick_to_samples(m: &TempoMap, tick: i64, sr: SampleRate) -> i64 {
+        let mut acc = 0.0;
+        let mut seg_tick = 0i64;
+        let mut bpm = m.tempos[0].bpm;
+        for e in m.tempos.iter().skip(1) {
+            if e.tick >= tick {
+                break;
+            }
+            acc += (e.tick - seg_tick) as f64 * TempoMap::samples_per_tick(bpm, sr);
+            seg_tick = e.tick;
+            bpm = e.bpm;
+        }
+        to_samples(acc + (tick - seg_tick) as f64 * TempoMap::samples_per_tick(bpm, sr))
+    }
+
+    #[test]
+    fn indexed_conversions_match_the_segment_walk() {
+        let sr = SampleRate::HZ_48000;
+        let mut m = TempoMap::default();
+        for i in 1..200i64 {
+            m.set_tempo(i * 487, 40.0 + ((i * 37) % 300) as f64).unwrap();
+        }
+        assert!(m.remove_tempo(487 * 50));
+        for tick in (-1000..200 * 487 + 5000).step_by(113) {
+            let s = m.tick_to_samples(tick, sr);
+            assert_eq!(s, linear_tick_to_samples(&m, tick, sr), "tick {tick}");
+            assert!((m.samples_to_ticks(s, sr) - tick).abs() <= 1, "tick {tick}");
+        }
+        let json = serde_json::to_string(&m).unwrap();
+        assert!(!json.contains("elapsed"));
+        let back: TempoMap = serde_json::from_str(&json).unwrap();
+        assert_eq!(back, m);
+        assert_eq!(back.tick_to_samples(150 * 487 + 3, sr), m.tick_to_samples(150 * 487 + 3, sr));
+    }
+
+    #[test]
+    fn a_file_with_wild_ticks_is_indexed_without_overflow() {
+        let json = r#"{"tempos":[{"tick":0,"bpm":120.0},{"tick":-9223372036854775808,"bpm":100.0},{"tick":9223372036854775807,"bpm":90.0}],"meters":[{"tick":0,"numerator":4,"denominator":4}]}"#;
+        let mut m: TempoMap = serde_json::from_str(json).unwrap();
+        m.sanitize();
+        assert_eq!(m.tempos().first().map(|e| e.tick), Some(0));
+        assert_eq!(m.elapsed.len(), m.tempos().len());
+    }
+
+    #[test]
+    fn conversions_against_a_large_tempo_map_stay_fast() {
+        // 200k tempo changes, then 200k conversions each way: quadratic if every conversion walks
+        // the earlier segments, well under a second when it binary-searches them.
+        let sr = SampleRate::HZ_48000;
+        let n = 200_000i64;
+        let tempos = (0..n).map(|i| TempoEvent { tick: i * 10, bpm: 60.0 + (i % 7) as f64 }).collect();
+        let mut m = TempoMap::from_parts(tempos, vec![MeterEvent { tick: 0, numerator: 4, denominator: 4 }]);
+        m.sanitize();
+        let start = std::time::Instant::now();
+        let mut sum = 0i64;
+        for i in 0..n {
+            let s = m.tick_to_samples(i * 10 + 5, sr);
+            sum = sum.wrapping_add(s).wrapping_add(m.samples_to_ticks(s, sr));
+        }
+        assert!(sum != 0);
+        assert!(start.elapsed() < std::time::Duration::from_secs(5), "{:?}", start.elapsed());
+    }
+}
diff --git a/crates/time/src/soundcraft/timecode.rs b/crates/time/src/soundcraft/timecode.rs
new file mode 100644
index 000000000..d09458e5c
--- /dev/null
+++ b/crates/time/src/soundcraft/timecode.rs
@@ -0,0 +1,320 @@
+//! SMPTE timecode and Feet+Frames.
+
+use super::{SampleRate, Samples, TimeError};
+
+/// Session timecode rates.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum FrameRate {
+    Fps23_976,
+    #[default]
+    Fps24,
+    Fps25,
+    Fps29_97,
+    Fps29_97Drop,
+    Fps30,
+    Fps47_952,
+    Fps48,
+    Fps50,
+    Fps59_94,
+    Fps59_94Drop,
+    Fps60,
+    Fps100,
+    Fps119_88,
+    Fps120,
+}
+
+impl FrameRate {
+    pub const ALL: [FrameRate; 15] = [
+        FrameRate::Fps23_976,
+        FrameRate::Fps24,
+        FrameRate::Fps25,
+        FrameRate::Fps29_97,
+        FrameRate::Fps29_97Drop,
+        FrameRate::Fps30,
+        FrameRate::Fps47_952,
+        FrameRate::Fps48,
+        FrameRate::Fps50,
+        FrameRate::Fps59_94,
+        FrameRate::Fps59_94Drop,
+        FrameRate::Fps60,
+        FrameRate::Fps100,
+        FrameRate::Fps119_88,
+        FrameRate::Fps120,
+    ];
+
+    /// Real frames per second as a rational (num, den).
+    pub fn rational(self) -> (i64, i64) {
+        match self {
+            FrameRate::Fps23_976 => (24_000, 1001),
+            FrameRate::Fps24 => (24, 1),
+            FrameRate::Fps25 => (25, 1),
+            FrameRate::Fps29_97 | FrameRate::Fps29_97Drop => (30_000, 1001),
+            FrameRate::Fps30 => (30, 1),
+            FrameRate::Fps47_952 => (48_000, 1001),
+            FrameRate::Fps48 => (48, 1),
+            FrameRate::Fps50 => (50, 1),
+            FrameRate::Fps59_94 | FrameRate::Fps59_94Drop => (60_000, 1001),
+            FrameRate::Fps60 => (60, 1),
+            FrameRate::Fps100 => (100, 1),
+            FrameRate::Fps119_88 => (120_000, 1001),
+            FrameRate::Fps120 => (120, 1),
+        }
+    }
+
+    /// Frames per labelled second (the counting base).
+    pub fn nominal(self) -> i64 {
+        let (n, d) = self.rational();
+        (n + d / 2) / d
+    }
+
+    pub fn is_drop(self) -> bool {
+        matches!(self, FrameRate::Fps29_97Drop | FrameRate::Fps59_94Drop)
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            FrameRate::Fps23_976 => "23.976",
+            FrameRate::Fps24 => "24",
+            FrameRate::Fps25 => "25",
+            FrameRate::Fps29_97 => "29.97",
+            FrameRate::Fps29_97Drop => "29.97 Drop",
+            FrameRate::Fps30 => "30",
+            FrameRate::Fps47_952 => "47.952",
+            FrameRate::Fps48 => "48",
+            FrameRate::Fps50 => "50",
+            FrameRate::Fps59_94 => "59.94",
+            FrameRate::Fps59_94Drop => "59.94 Drop",
+            FrameRate::Fps60 => "60",
+            FrameRate::Fps100 => "100",
+            FrameRate::Fps119_88 => "119.88",
+            FrameRate::Fps120 => "120",
+        }
+    }
+
+    /// Whole frame index at a sample position (floored).
+    pub fn frames_at(self, s: Samples, sr: SampleRate) -> i64 {
+        let (n, d) = self.rational();
+        let num = i128::from(s) * i128::from(n);
+        let den = i128::from(sr.hz()) * i128::from(d);
+        if den == 0 {
+            return 0;
+        }
+        i64::try_from(num.div_euclid(den)).unwrap_or(0)
+    }
+
+    /// Sample position of the start of frame `f`.
+    pub fn samples_at_frame(self, f: i64, sr: SampleRate) -> Samples {
+        let (n, d) = self.rational();
+        if n == 0 {
+            return 0;
+        }
+        // Use the first integer sample whose floored frame lookup is `f`; nearest rounding
+        // can put fractional-rate frame starts just before their own lookup interval.
+        let numerator = i128::from(f) * i128::from(sr.hz()) * i128::from(d);
+        let denominator = i128::from(n);
+        let floor = numerator.div_euclid(denominator);
+        let v = floor + i128::from(numerator.rem_euclid(denominator) != 0);
+        i64::try_from(v).unwrap_or(if v < 0 { i64::MIN } else { i64::MAX })
+    }
+
+    /// Samples per frame (fractional).
+    pub fn samples_per_frame(self, sr: SampleRate) -> f64 {
+        let (n, d) = self.rational();
+        sr.as_f64() * d as f64 / n as f64
+    }
+}
+
+/// A timecode label.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct Timecode {
+    pub negative: bool,
+    pub hours: i64,
+    pub minutes: i64,
+    pub seconds: i64,
+    pub frames: i64,
+}
+
+impl Timecode {
+    /// Label for an absolute frame count.
+    pub fn from_frames(frames: i64, rate: FrameRate) -> Timecode {
+        let negative = frames < 0;
+        // Drop-frame labels can exceed i64::MAX even when the frame count fits. Widen before
+        // taking the magnitude so i64::MIN is represented exactly too.
+        let mut f = i128::from(frames).abs();
+        let base = i128::from(rate.nominal().max(1));
+        if rate.is_drop() {
+            // Drop 2 (or 4) labels each minute except every tenth.
+            let drop = if base >= 60 { 4 } else { 2 };
+            let per_10min = base * 600 - drop * 9;
+            let per_min = base * 60 - drop;
+            let tens = f / per_10min;
+            let rem = f % per_10min;
+            let extra = if rem > drop { drop * 9 * tens + drop * ((rem - drop) / per_min) } else { drop * 9 * tens };
+            f += extra;
+        }
+        let frames_l = f % base;
+        let total_secs = f / base;
+        Timecode {
+            negative,
+            hours: i64::try_from(total_secs / 3600).unwrap_or(i64::MAX),
+            minutes: i64::try_from((total_secs / 60) % 60).unwrap_or(0),
+            seconds: i64::try_from(total_secs % 60).unwrap_or(0),
+            frames: i64::try_from(frames_l).unwrap_or(0),
+        }
+    }
+
+    /// Absolute frame count of this label.
+    pub fn to_frames(&self, rate: FrameRate) -> i64 {
+        let base = rate.nominal().max(1);
+        let total_min = i128::from(self.hours) * 60 + i128::from(self.minutes);
+        let mut f = (total_min * 60 + i128::from(self.seconds)) * i128::from(base) + i128::from(self.frames);
+        if rate.is_drop() {
+            let drop = if base >= 60 { 4 } else { 2 };
+            f -= drop * (total_min - total_min / 10);
+        }
+        let f = if self.negative { -f } else { f };
+        i64::try_from(f).unwrap_or(if f < 0 { i64::MIN } else { i64::MAX })
+    }
+
+    pub fn from_samples(s: Samples, rate: FrameRate, sr: SampleRate) -> Timecode {
+        Timecode::from_frames(rate.frames_at(s, sr), rate)
+    }
+
+    pub fn to_samples(&self, rate: FrameRate, sr: SampleRate) -> Samples {
+        rate.samples_at_frame(self.to_frames(rate), sr)
+    }
+
+    pub fn format(&self, rate: FrameRate) -> String {
+        let sep = if rate.is_drop() { ';' } else { ':' };
+        let sign = if self.negative { "-" } else { "" };
+        format!("{sign}{:02}:{:02}:{:02}{sep}{:02}", self.hours, self.minutes, self.seconds, self.frames)
+    }
+
+    /// Parse `HH:MM:SS:FF` (also `;` / `.` separators and fewer fields, right-aligned).
+    pub fn parse(text: &str) -> Result<Timecode, TimeError> {
+        let t = text.trim();
+        let (negative, t) = match t.strip_prefix('-') {
+            Some(r) => (true, r),
+            None => (false, t),
+        };
+        if t.len() > 80 {
+            return Err(TimeError::Parse("timecode is too long".into(), "timecode"));
+        }
+        if t.bytes().filter(|b| matches!(b, b':' | b';' | b'.')).count() > 3 {
+            return Err(TimeError::Parse(text.to_string(), "timecode"));
+        }
+        let parts: Vec<&str> = t.split([':', ';', '.']).collect();
+        if parts.is_empty() || parts.len() > 4 {
+            return Err(TimeError::Parse(text.to_string(), "timecode"));
+        }
+        let mut nums = [0i64; 4];
+        let offset = 4 - parts.len();
+        for (i, p) in parts.iter().enumerate() {
+            let v: i64 = p.trim().parse().map_err(|_| TimeError::Parse(text.to_string(), "timecode"))?;
+            if v < 0 {
+                return Err(TimeError::Parse(text.to_string(), "timecode"));
+            }
+            if let Some(slot) = nums.get_mut(offset + i) {
+                *slot = v;
+            }
+        }
+        Ok(Timecode { negative, hours: nums[0], minutes: nums[1], seconds: nums[2], frames: nums[3] })
+    }
+}
+
+/// Feet+Frames for 35 mm film (16 frames per foot), `start` frames in at sample 0.
+pub fn feet_frames(s: Samples, rate: FrameRate, sr: SampleRate, start: i64) -> (i64, i64) {
+    let f = rate.frames_at(s, sr).saturating_add(start);
+    (f.div_euclid(16), f.rem_euclid(16))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn non_drop_round_trip() {
+        let sr = SampleRate::HZ_48000;
+        let tc = Timecode::from_samples(48_000 * 3661, FrameRate::Fps25, sr);
+        assert_eq!(tc.format(FrameRate::Fps25), "01:01:01:00");
+        assert_eq!(tc.to_samples(FrameRate::Fps25, sr), 48_000 * 3661);
+    }
+
+    #[test]
+    fn fractional_frame_starts_match_floored_lookup_on_both_sides_of_zero() {
+        let sr = SampleRate::HZ_48000;
+        let tc = Timecode::parse("-00:00:01:00").unwrap();
+        assert_eq!(tc.to_samples(FrameRate::Fps25, sr), -48_000);
+        for r in [FrameRate::Fps25, FrameRate::Fps29_97, FrameRate::Fps29_97Drop, FrameRate::Fps23_976] {
+            for f in [-107_892i64, -25, -7, -1, 0, 1, 2, 7, 25, 1799, 107_892] {
+                assert_eq!(r.frames_at(r.samples_at_frame(f, sr), sr), f, "{r:?} frame {f}");
+            }
+        }
+        assert_eq!(FrameRate::Fps29_97.frames_at(FrameRate::Fps29_97.samples_at_frame(2, sr), sr), 2);
+    }
+
+    #[test]
+    fn drop_frame_labels() {
+        let r = FrameRate::Fps29_97Drop;
+        // Frame 1800 is the first frame of minute 1 → labelled 00:01:00;02.
+        assert_eq!(Timecode::from_frames(1800, r).format(r), "00:01:00;02");
+        assert_eq!(Timecode::from_frames(1799, r).format(r), "00:00:59;29");
+        // Minute 10 keeps its labels.
+        assert_eq!(Timecode::from_frames(17_982, r).format(r), "00:10:00;00");
+        for f in [0, 1, 1799, 1800, 1801, 17_981, 17_982, 107_892, 500_000] {
+            assert_eq!(Timecode::from_frames(f, r).to_frames(r), f, "frame {f}");
+        }
+    }
+
+    #[test]
+    fn huge_timecode_saturates_instead_of_overflowing() {
+        let sr = SampleRate::HZ_48000;
+        for r in [FrameRate::Fps30, FrameRate::Fps29_97Drop] {
+            let tc = Timecode::parse("9223372036854775807:00:00:00").unwrap();
+            assert_eq!(tc.to_samples(r, sr), i64::MAX);
+            let tc = Timecode::parse("-9223372036854775807:00:00:00").unwrap();
+            assert_eq!(tc.to_samples(r, sr), i64::MIN);
+        }
+        let tc = Timecode::parse("01:02:03:04").unwrap();
+        assert_eq!(tc.to_samples(FrameRate::Fps30, sr), 178_710_400);
+    }
+
+    #[test]
+    fn extreme_frame_counts_round_trip_at_every_rate() {
+        for rate in FrameRate::ALL {
+            for frames in [i64::MIN, i64::MIN + 1, -1, 0, 1, i64::MAX - 1, i64::MAX] {
+                let tc = Timecode::from_frames(frames, rate);
+                assert_eq!(tc.to_frames(rate), frames, "{rate:?}: {frames}");
+                assert_eq!(tc.negative, frames < 0);
+                assert!((0..60).contains(&tc.minutes));
+                assert!((0..60).contains(&tc.seconds));
+                assert!((0..rate.nominal()).contains(&tc.frames));
+                assert_eq!(Timecode::parse(&tc.format(rate)).unwrap(), tc);
+            }
+        }
+    }
+
+    #[test]
+    fn extreme_drop_frame_labels_do_not_overflow() {
+        for rate in [FrameRate::Fps29_97Drop, FrameRate::Fps59_94Drop] {
+            assert_eq!(Timecode::from_frames(i64::MAX, rate).to_frames(rate), i64::MAX);
+        }
+    }
+
+    #[test]
+    fn parse_variants() {
+        let tc = Timecode::parse("01:02:03:04").unwrap();
+        assert_eq!((tc.hours, tc.minutes, tc.seconds, tc.frames), (1, 2, 3, 4));
+        let tc = Timecode::parse("3:04").unwrap();
+        assert_eq!((tc.seconds, tc.frames), (3, 4));
+        assert!(Timecode::parse("a:b").is_err());
+        assert!(Timecode::parse("1:2:3:4:5").is_err());
+        assert!(Timecode::parse(&format!("{}:", "1".repeat(100_000))).is_err());
+    }
+
+    #[test]
+    fn feet_and_frames() {
+        let sr = SampleRate::HZ_48000;
+        assert_eq!(feet_frames(48_000, FrameRate::Fps24, sr, 0), (1, 8));
+    }
+}
diff --git a/crates/time/tests/differential.rs b/crates/time/tests/differential.rs
new file mode 100644
index 000000000..f4634c230
--- /dev/null
+++ b/crates/time/tests/differential.rs
@@ -0,0 +1,315 @@
+use craft_time::{
+    FrameRate, SAMPLE_RATES, TICKS_PER_SECOND, Tick, TimeDisplay, TimeRange, format_feet_frames, format_time, format_timecode_ae,
+    format_timecode_frames, frames_to_fields, parse_feet_frames, parse_timecode,
+};
+use proptest::prelude::*;
+
+#[test]
+fn ticks_per_second_divides_all_standard_rates_evenly() {
+    assert_eq!(TICKS_PER_SECOND, 254_016_000_000);
+
+    // Divisible by all standard frame rate numerators and denominators
+    for r in FrameRate::COMMON {
+        let den = r.den as i128;
+        let num = r.num as i128;
+        let product = TICKS_PER_SECOND as i128 * den;
+        assert_eq!(product % num, 0, "Rate {} ({} / {}) does not divide TICKS_PER_SECOND evenly", r.label(), r.num, r.den);
+    }
+
+    // Audio sample rates
+    for &sr in &SAMPLE_RATES {
+        assert_eq!(TICKS_PER_SECOND % sr, 0, "Sample rate {sr} does not divide TICKS_PER_SECOND evenly");
+    }
+}
+
+#[test]
+fn frame_roundtrip_all_common_rates() {
+    for r in FrameRate::COMMON {
+        for f in -10_000..=10_000 {
+            let t = r.tick_of(f);
+            let back = r.frame_at(t);
+            assert_eq!(back, f, "Roundtrip failed for {} at frame {}", r.label(), f);
+            assert_eq!(r.snap(t), t, "Snap of exact boundary should be identity");
+            assert_eq!(r.snap_nearest(t), t, "Snap nearest of exact boundary should be identity");
+        }
+    }
+}
+
+#[test]
+fn time_range_invariants() {
+    let r1 = TimeRange::new(Tick(100), Tick(50));
+    assert_eq!(r1.end(), Tick(150));
+    assert!(r1.contains(Tick(100)));
+    assert!(r1.contains(Tick(149)));
+    assert!(!r1.contains(Tick(150)));
+
+    let r2 = TimeRange::new(Tick(120), Tick(40));
+    assert!(r1.overlaps(&r2));
+    let inter = r1.intersect(&r2);
+    assert_eq!(inter, Some(TimeRange::new(Tick(120), Tick(30))));
+
+    let empty = TimeRange::new(Tick(100), Tick(0));
+    assert!(empty.is_empty());
+}
+
+#[test]
+fn tick_checked_and_saturating_arithmetic_contract() {
+    // 1. Division overflow: i64::MIN / -1
+    let min_tick = Tick(i64::MIN);
+    assert_eq!(min_tick.checked_div(-1), None, "checked_div must return None on i64::MIN / -1");
+    assert_eq!(min_tick.saturating_div(-1), Some(Tick(i64::MAX)), "saturating_div must saturate to Tick(i64::MAX)");
+    assert_eq!(min_tick / -1, Tick(i64::MAX), "Operator Div must saturate i64::MIN / -1 to Tick(i64::MAX) without panicking");
+    assert_eq!(Tick(i64::MIN + 1) / -1, Tick(i64::MAX));
+    assert_eq!(Tick(i64::MIN + 2) / -1, Tick(i64::MAX - 1));
+
+    // 2. Division by zero
+    let ten = Tick(10);
+    assert_eq!(ten.checked_div(0), None, "checked_div must return None on division by zero");
+    assert_eq!(ten.saturating_div(0), None, "saturating_div must return None on division by zero");
+    assert_eq!(ten / 0, Tick::ZERO, "Operator Div fallback returns Tick::ZERO on zero divisor");
+
+    // 3. Remainder overflow & zero divisor
+    assert_eq!(min_tick.checked_rem(Tick(-1)), None, "checked_rem must return None on i64::MIN % -1");
+    assert_eq!(ten.checked_rem(Tick(0)), None, "checked_rem must return None on zero divisor");
+    assert_eq!(min_tick % Tick(-1), Tick::ZERO, "Operator Rem on i64::MIN % -1 produces Tick::ZERO");
+    assert_eq!(ten % Tick(0), Tick::ZERO, "Operator Rem on zero divisor produces Tick::ZERO");
+
+    // 4. Checked Add / Sub / Mul
+    assert_eq!(Tick(i64::MAX).checked_add(Tick(1)), None);
+    assert_eq!(Tick(i64::MIN).checked_sub(Tick(1)), None);
+    assert_eq!(Tick(i64::MAX).checked_mul(2), None);
+    assert_eq!(Tick(100).checked_add(Tick(50)), Some(Tick(150)));
+    assert_eq!(Tick(100).checked_sub(Tick(50)), Some(Tick(50)));
+    assert_eq!(Tick(100).checked_mul(5), Some(Tick(500)));
+
+    // 5. Saturating Add / Sub / Mul
+    assert_eq!(Tick(i64::MAX).saturating_add(Tick(1)), Tick(i64::MAX));
+    assert_eq!(Tick(i64::MIN).saturating_sub(Tick(1)), Tick(i64::MIN));
+    assert_eq!(Tick(i64::MAX).saturating_mul(2), Tick(i64::MAX));
+}
+
+#[test]
+fn hostile_rates_and_timecodes_never_panic() {
+    let zero = FrameRate { num: 0, den: 0 };
+    for r in [
+        zero,
+        FrameRate { num: 0, den: 1 },
+        FrameRate { num: 25, den: 0 },
+        FrameRate { num: -30, den: 1 },
+        FrameRate::from_f64(0.0),
+        FrameRate::from_f64(f64::NAN),
+    ] {
+        assert_eq!(r.tick_of(10), FrameRate::default().tick_of(10));
+        assert_eq!(r.frame_at(Tick(TICKS_PER_SECOND)), FrameRate::default().frame_at(Tick(TICKS_PER_SECOND)));
+        assert!(r.frame_duration() > Tick::ZERO);
+        assert!(r.timecode_base() >= 1);
+        let _ = r.snap_nearest(Tick(12345));
+        let _ = format_time(Tick(TICKS_PER_SECOND), r, true, TimeDisplay::Timecode, 48_000);
+    }
+    assert_eq!(Tick::from_rational(100, 1, 0), Tick::ZERO);
+    assert_eq!(Tick::from_units(100, 0), Tick::ZERO);
+    assert_eq!(Tick(5).to_rational_floor(0, 1), 0);
+    assert_eq!(Tick(5).to_rational_round(0, 1), 0);
+    for t in [i64::MIN, -1, 0, 1, i64::MAX] {
+        for (n, d) in [(i64::MIN, 1), (-1, 1000), (1, i64::MAX), (i64::MAX, i64::MIN), (1, 0)] {
+            let _ = Tick(t).to_rational_round(n, d);
+        }
+    }
+    assert_eq!(Tick(5).mul_ratio(1, 0), Tick::ZERO);
+    assert_eq!(Tick(5).clamp(Tick(10), Tick(0)), Tick(0));
+    let _ = format_timecode_frames(i64::MIN, FrameRate::FPS_29_97, true);
+    for tc in ["99999999999:99:99:99", "9223372036854775807", "+9223372036854775807", "99999999999;59;59;29"] {
+        let _ = parse_timecode(tc, FrameRate::FPS_29_97, true, i64::MAX);
+        let _ = parse_timecode(tc, FrameRate::FPS_25, false, i64::MIN);
+    }
+}
+
+#[test]
+fn boundary_rates_saturate_without_wrapping_and_keep_representable_values_exact() {
+    let slow = FrameRate { num: 1, den: i64::MAX };
+    assert_eq!(slow.frame_duration(), Tick(i64::MAX));
+    assert_eq!(slow.tick_of(i64::MAX), Tick(i64::MAX));
+    assert_eq!(slow.tick_of(i64::MIN), Tick(i64::MIN));
+    assert_eq!(slow.snap_nearest(Tick(i64::MAX)), Tick::ZERO, "compare the real boundary before saturating");
+    assert_eq!(slow.snap_nearest(Tick(i64::MIN)), Tick::ZERO);
+
+    let fast = FrameRate { num: i64::MAX, den: 1 };
+    assert_eq!(fast.tick_of(i64::MAX), Tick(TICKS_PER_SECOND), "large factors can cancel exactly");
+    assert_eq!(fast.tick_of(-i64::MAX), Tick(-TICKS_PER_SECOND));
+    assert_eq!(fast.frame_at(Tick(TICKS_PER_SECOND)), i64::MAX);
+    assert_eq!(fast.frame_at(Tick(i64::MAX)), i64::MAX);
+    assert_eq!(fast.frame_at(Tick(i64::MIN)), i64::MIN);
+    assert_eq!(fast.timecode_base(), i64::MAX);
+
+    for t in [i64::MIN, -TICKS_PER_SECOND, -1, 0, 1, TICKS_PER_SECOND, i64::MAX] {
+        assert_eq!(fast.snap(Tick(t)), Tick(t), "sub-tick frames include every integer tick");
+        assert_eq!(fast.snap_nearest(Tick(t)), Tick(t));
+    }
+
+    let balanced = FrameRate { num: i64::MAX, den: i64::MAX };
+    assert_eq!(balanced.frame_duration(), Tick(TICKS_PER_SECOND));
+    assert_eq!(balanced.tick_of(2), Tick(2 * TICKS_PER_SECOND));
+    assert_eq!(balanced.frame_at(Tick(2 * TICKS_PER_SECOND)), 2);
+    assert_eq!(balanced.timecode_base(), 1);
+    assert_eq!(FrameRate::new(i64::MIN, i64::MIN), FrameRate { num: -1, den: -1 });
+    assert_eq!(FrameRate::new(i64::MIN, 0), FrameRate { num: -1, den: 0 });
+    assert_eq!(FrameRate::new(i64::MIN, 1), FrameRate { num: i64::MIN, den: 1 });
+}
+
+#[test]
+fn scalar_time_conversions_saturate_at_storage_limits() {
+    assert_eq!(Tick::from_units(i64::MAX, 1), Tick(i64::MAX));
+    assert_eq!(Tick::from_units(i64::MIN, 1), Tick(i64::MIN));
+    assert_eq!(Tick(i64::MAX).to_units_floor(i64::MAX), i64::MAX);
+    assert_eq!(Tick(i64::MIN).to_units_floor(i64::MAX), i64::MIN);
+    assert_eq!(Tick::from_rational(i64::MAX, i64::MAX, 1), Tick(i64::MAX));
+    assert_eq!(Tick::from_rational(i64::MIN, i64::MAX, 1), Tick(i64::MIN));
+    assert_eq!(Tick::from_rational(i64::MIN, i64::MAX, -1), Tick(i64::MAX));
+    assert_eq!(Tick::from_rational(i64::MAX, i64::MAX, 0), Tick::ZERO);
+    assert_eq!(Tick(i64::MAX).to_rational_floor(1, i64::MAX), i64::MAX);
+    assert_eq!(Tick(i64::MIN).to_rational_round(1, i64::MAX), i64::MIN);
+    assert_eq!(Tick(i64::MAX).mul_ratio(i64::MAX, 1), Tick(i64::MAX));
+    assert_eq!(Tick(i64::MIN).abs(), Tick(i64::MAX));
+}
+
+#[test]
+fn smpte_drop_frame_exact_counts_and_negative_boundaries() {
+    let r = FrameRate::FPS_29_97;
+    assert!(r.supports_drop_frame());
+
+    // 10 minutes at 29.97: 10 * 60 * 30 - 9 * 2 = 17982 frames
+    let ten_min_frames = 17982;
+    let tc = format_timecode_frames(ten_min_frames, r, true);
+    assert_eq!(tc, "00;10;00;00");
+    assert_eq!(parse_timecode(&tc, r, true, 0), Ok(ten_min_frames));
+
+    // 1 minute drop-frame boundary: frame 1800 is 00;01;00;02
+    let one_min_frame = 1800;
+    let tc_1m = format_timecode_frames(one_min_frame, r, true);
+    assert_eq!(tc_1m, "00;01;00;02");
+    assert_eq!(parse_timecode(&tc_1m, r, true, 0), Ok(one_min_frame));
+
+    // Negative drop-frame boundaries
+    let neg_1m = -1800;
+    let neg_tc = format_timecode_frames(neg_1m, r, true);
+    assert_eq!(neg_tc, "-00;01;00;02");
+    assert_eq!(parse_timecode(&neg_tc, r, true, 0), Ok(neg_1m));
+
+    let neg_10m = -17982;
+    let neg_10m_tc = format_timecode_frames(neg_10m, r, true);
+    assert_eq!(neg_10m_tc, "-00;10;00;00");
+    assert_eq!(parse_timecode(&neg_10m_tc, r, true, 0), Ok(neg_10m));
+
+    let neg_1h = -107892;
+    let neg_1h_tc = format_timecode_frames(neg_1h, r, true);
+    assert_eq!(neg_1h_tc, "-01;00;00;00");
+    assert_eq!(parse_timecode(&neg_1h_tc, r, true, 0), Ok(neg_1h));
+}
+
+#[test]
+fn effectcraft_ae_differential_formatting() {
+    let r30 = FrameRate::FPS_30;
+    let r_df = FrameRate::FPS_29_97;
+
+    // EffectCraft / After Effects formats hours without zero-padding
+    assert_eq!(format_timecode_ae(75, r30, false), "0:00:02:15");
+    assert_eq!(format_timecode_ae(75, r_df, true), "0;00;02;15");
+
+    // FilmCraft / Premiere formats hours with 2 zero-padded digits
+    assert_eq!(format_timecode_frames(75, r30, false), "00:00:02:15");
+    assert_eq!(format_timecode_frames(75, r_df, true), "00;00;02;15");
+
+    // Negative frames in AE style
+    assert_eq!(format_timecode_ae(-75, r30, false), "-0:00:02:15");
+    assert_eq!(format_timecode_ae(-1800, r_df, true), "-0;01;00;02");
+
+    // Multi-hour parity
+    assert_eq!(format_timecode_ae(3600 * 30 * 12, r30, false), "12:00:00:00");
+    assert_eq!(format_timecode_frames(3600 * 30 * 12, r30, false), "12:00:00:00");
+}
+
+#[test]
+fn feet_and_frames_film_standards() {
+    // 35mm: 16 frames per foot
+    assert_eq!(format_feet_frames(0, 16), "0000+00");
+    assert_eq!(format_feet_frames(199, 16), "0012+07");
+    assert_eq!(parse_feet_frames("12+07", 16, 0), Ok(199));
+    assert_eq!(parse_feet_frames("0012+07", 16, 0), Ok(199));
+    assert_eq!(format_feet_frames(-199, 16), "-0012+07");
+    assert_eq!(parse_feet_frames("-0012+07", 16, 0), Ok(-199));
+
+    // 16mm: 40 frames per foot
+    assert_eq!(format_feet_frames(95, 40), "0002+15");
+    assert_eq!(parse_feet_frames("2+15", 40, 0), Ok(95));
+}
+
+#[test]
+fn exotic_frame_rate_durations() {
+    let r = FrameRate::from_f64(37.516);
+    assert_eq!(r.frame_duration().0, 6_770_871_094);
+
+    // Standard rates must remain exact
+    assert_eq!(FrameRate::FPS_23_976.frame_duration().0, 10_594_584_000);
+    assert_eq!(FrameRate::FPS_24.frame_duration().0, 10_584_000_000);
+    assert_eq!(FrameRate::FPS_25.frame_duration().0, 10_160_640_000);
+    assert_eq!(FrameRate::FPS_29_97.frame_duration().0, 8_475_667_200);
+    assert_eq!(FrameRate::FPS_30.frame_duration().0, 8_467_200_000);
+    assert_eq!(FrameRate::FPS_60.frame_duration().0, 4_233_600_000);
+}
+
+proptest! {
+    #[test]
+    fn prop_monotonic_frame_math(
+        frame in -100_000i64..100_000,
+        rate_idx in 0usize..FrameRate::COMMON.len(),
+    ) {
+        let r = FrameRate::COMMON[rate_idx];
+        let t1 = r.tick_of(frame);
+        let t2 = r.tick_of(frame + 1);
+        prop_assert!(t1 < t2, "tick_of must be strictly increasing");
+        prop_assert_eq!(r.frame_at(t1), frame);
+        prop_assert_eq!(r.frame_at(t2 - Tick(1)), frame);
+    }
+
+    #[test]
+    fn prop_feet_frames_roundtrip(
+        frame in -50_000i64..50_000,
+        per_foot in 1i64..120,
+    ) {
+        let s = format_feet_frames(frame, per_foot);
+        let parsed = parse_feet_frames(&s, per_foot, 0);
+        prop_assert_eq!(parsed, Ok(frame));
+    }
+
+    #[test]
+    fn prop_drop_frame_bijection(f in 0i64..(24 * 107_892)) {
+        let r = FrameRate::FPS_29_97;
+        let (_, _h, m, s, fr) = frames_to_fields(f, r, true);
+        // dropped labels never appear
+        prop_assert!(!(s == 0 && fr < 2 && m % 10 != 0));
+        let txt = format_timecode_frames(f, r, true);
+        prop_assert_eq!(parse_timecode(&txt, r, true, 0).unwrap(), f);
+    }
+
+    #[test]
+    fn prop_ndf_parse_roundtrip(f in -500_000i64..500_000, ri in 0usize..11) {
+        let r = FrameRate::COMMON[ri];
+        let txt = format_timecode_frames(f, r, false);
+        prop_assert_eq!(parse_timecode(&txt, r, false, 0).unwrap(), f);
+    }
+
+    #[test]
+    fn prop_tick_div_monotonicity(
+        a in any::<i64>(),
+        b in any::<i64>(),
+        d in any::<i64>().prop_filter("non-zero", |&x| x != 0),
+    ) {
+        if a <= b {
+            if d > 0 {
+                prop_assert!((Tick(a) / d) <= (Tick(b) / d));
+            } else {
+                prop_assert!((Tick(a) / d) >= (Tick(b) / d));
+            }
+        }
+    }
+}
diff --git a/crates/timeline/Cargo.toml b/crates/timeline/Cargo.toml
index 3eca9bc5c..9e73908e4 100644
--- a/crates/timeline/Cargo.toml
+++ b/crates/timeline/Cargo.toml
@@ -20,6 +20,7 @@ otio = ["dep:serde_json"]
 
 [dependencies]
 serde = { workspace = true, optional = true }
+craft-time.workspace = true
 craft-xml = { workspace = true, optional = true }
 serde_json = { workspace = true, optional = true }
 
diff --git a/crates/timeline/src/time.rs b/crates/timeline/src/time.rs
index f3f12f58d..2db3def5b 100644
--- a/crates/timeline/src/time.rs
+++ b/crates/timeline/src/time.rs
@@ -1,627 +1,27 @@
-//! Exact media time.
+//! Compatibility re-exports for timeline time primitives.
 //!
-//! All time is an integer number of [`Tick`]s at [`TICKS_PER_SECOND`] = 254 016 000 000/s. That
-//! rate divides evenly into every broadcast frame duration (23.976, 24, 25, 29.97, 30, 48, 50,
-//! 59.94, 60, 120 …) and every common audio sample duration (8 k … 192 kHz, including the 44.1 k
-//! family), so edits, frame math and audio alignment never drift.
-//!
-//! Timecode (SMPTE drop/non-drop, frames, feet+frames, samples) is only a *display* of ticks.
-//!
-//! Every conversion is total: a zero or negative rate (from a damaged file or project) gives
-//! zero instead of a division-by-zero panic, and an invalid [`FrameRate`] counts as the default.
+//! The implementation lives in `craft-time`; this module keeps the established
+//! `craft_timeline::time::*` paths available to downstream users.
 
-use std::fmt;
-use std::ops::{Add, AddAssign, Neg, Sub, SubAssign};
+pub use craft_time::{
+    FrameRate, ParseError, SAMPLE_RATES, TICKS_PER_SECOND, Tick, TimeDisplay, TimeRange, fields_to_frames, format_timecode_frames, frames_to_fields,
+    parse_time_display_relative as parse_time_display, parse_timecode_relative as parse_timecode,
+};
 
-/// Ticks per second.
-pub const TICKS_PER_SECOND: i64 = 254_016_000_000;
-
-/// A point or duration in time, in ticks.
-/// Arithmetic saturates at the i64 storage limits; representable results remain exact.
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
-#[cfg_attr(feature = "serde", serde(transparent))]
-pub struct Tick(pub i64);
-
-impl Tick {
-    pub const ZERO: Tick = Tick(0);
-    pub const MAX: Tick = Tick(i64::MAX / 4);
-    pub const MIN: Tick = Tick(i64::MIN / 4);
-
-    pub fn from_seconds_f64(s: f64) -> Tick {
-        Tick((s * TICKS_PER_SECOND as f64).round() as i64)
-    }
-    pub fn seconds(self) -> f64 {
-        self.0 as f64 / TICKS_PER_SECOND as f64
-    }
-    /// Exact conversion from a count of `units` at `per_second` (e.g. samples at 48 000).
-    pub fn from_units(units: i64, per_second: i64) -> Tick {
-        Tick(clamp_i64((units as i128 * TICKS_PER_SECOND as i128).checked_div(per_second as i128).unwrap_or(0)))
-    }
-    /// Floor conversion to a count of units at `per_second`.
-    pub fn to_units_floor(self, per_second: i64) -> i64 {
-        clamp_i64((self.0 as i128 * per_second as i128).div_euclid(TICKS_PER_SECOND as i128))
-    }
-    /// Conversion from a rational timestamp `pts * num / den` seconds (container timebases).
-    pub fn from_rational(pts: i64, num: i64, den: i64) -> Tick {
-        if den == 0 {
-            return Tick::ZERO;
-        }
-        let Some(t) = (pts as i128 * num as i128).checked_mul(TICKS_PER_SECOND as i128) else {
-            // A product beyond i128 divided by an i64 cannot fit back into i64.
-            return Tick(if (pts < 0) ^ (num < 0) ^ (den < 0) { i64::MIN } else { i64::MAX });
-        };
-        Tick(clamp_i64(t.div_euclid(den as i128)))
-    }
-    /// Inverse of [`Tick::from_rational`], floored to the timebase.
-    pub fn to_rational_floor(self, num: i64, den: i64) -> i64 {
-        clamp_i64((self.0 as i128 * den as i128).checked_div_euclid(num as i128 * TICKS_PER_SECOND as i128).unwrap_or(0))
-    }
-    /// Inverse of [`Tick::from_rational`], rounded to the nearest timebase unit (halves up).
-    ///
-    /// For finding a sample by its timestamp: containers store timestamps rounded to their
-    /// timebase (Matroska usually to 1 ms), so a stamp can sit up to half a unit after the true
-    /// time. Flooring the requested time misses every frame whose stamp was rounded up.
-    pub fn to_rational_round(self, num: i64, den: i64) -> i64 {
-        let n = self.0 as i128 * den as i128;
-        let unit = num as i128 * TICKS_PER_SECOND as i128;
-        let (n, unit) = if unit < 0 { (-n, -unit) } else { (n, unit) };
-        let (Some(q), Some(r)) = (n.checked_div_euclid(unit), n.checked_rem_euclid(unit)) else { return 0 };
-        // 0 <= r < unit: round up from the halfway point
-        clamp_i64(if r * 2 >= unit { q + 1 } else { q })
-    }
-    pub fn abs(self) -> Tick {
-        Tick(self.0.saturating_abs())
-    }
-    pub fn min(self, o: Tick) -> Tick {
-        Tick(self.0.min(o.0))
-    }
-    pub fn max(self, o: Tick) -> Tick {
-        Tick(self.0.max(o.0))
-    }
-    pub fn clamp(self, lo: Tick, hi: Tick) -> Tick {
-        // max/min rather than `clamp`, which panics when the bounds cross.
-        Tick(self.0.max(lo.0).min(hi.0))
-    }
-    /// Scale by a rational factor (`num/den`), flooring.
-    pub fn mul_ratio(self, num: i64, den: i64) -> Tick {
-        Tick(clamp_i64((self.0 as i128 * num as i128).checked_div_euclid(den as i128).unwrap_or(0)))
-    }
-}
-
-impl Add for Tick {
-    type Output = Tick;
-    fn add(self, o: Tick) -> Tick {
-        Tick(self.0.saturating_add(o.0))
-    }
-}
-impl Sub for Tick {
-    type Output = Tick;
-    fn sub(self, o: Tick) -> Tick {
-        Tick(self.0.saturating_sub(o.0))
-    }
-}
-impl Neg for Tick {
-    type Output = Tick;
-    fn neg(self) -> Tick {
-        Tick(self.0.saturating_neg())
-    }
-}
-impl AddAssign for Tick {
-    fn add_assign(&mut self, o: Tick) {
-        self.0 = self.0.saturating_add(o.0);
-    }
-}
-impl SubAssign for Tick {
-    fn sub_assign(&mut self, o: Tick) {
-        self.0 = self.0.saturating_sub(o.0);
-    }
-}
-
-/// A half-open time range `[start, start + duration)`.
-/// Zero or negative durations are empty and never overlap another range.
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
-pub struct TimeRange {
-    pub start: Tick,
-    pub duration: Tick,
-}
-
-impl TimeRange {
-    pub fn new(start: Tick, duration: Tick) -> Self {
-        Self { start, duration }
-    }
-    pub fn from_bounds(start: Tick, end: Tick) -> Self {
-        Self { start, duration: end - start }
-    }
-    pub fn end(&self) -> Tick {
-        self.start + self.duration
-    }
-    pub fn contains(&self, t: Tick) -> bool {
-        t >= self.start && t < self.end()
-    }
-    pub fn overlaps(&self, o: &TimeRange) -> bool {
-        !self.is_empty() && !o.is_empty() && self.start < o.end() && o.start < self.end()
-    }
-    pub fn intersect(&self, o: &TimeRange) -> Option<TimeRange> {
-        let s = self.start.max(o.start);
-        let e = self.end().min(o.end());
-        (e > s).then(|| TimeRange::from_bounds(s, e))
-    }
-    pub fn is_empty(&self) -> bool {
-        self.duration.0 <= 0
-    }
-}
-
-/// A frame rate as an exact rational (`num / den` frames per second).
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
-pub struct FrameRate {
-    pub num: i64,
-    pub den: i64,
-}
-
-impl Default for FrameRate {
-    fn default() -> Self {
-        FrameRate::FPS_23_976
-    }
-}
-
-impl FrameRate {
-    pub const FPS_23_976: FrameRate = FrameRate { num: 24000, den: 1001 };
-    pub const FPS_24: FrameRate = FrameRate { num: 24, den: 1 };
-    pub const FPS_25: FrameRate = FrameRate { num: 25, den: 1 };
-    pub const FPS_29_97: FrameRate = FrameRate { num: 30000, den: 1001 };
-    pub const FPS_30: FrameRate = FrameRate { num: 30, den: 1 };
-    pub const FPS_48: FrameRate = FrameRate { num: 48, den: 1 };
-    pub const FPS_50: FrameRate = FrameRate { num: 50, den: 1 };
-    pub const FPS_59_94: FrameRate = FrameRate { num: 60000, den: 1001 };
-    pub const FPS_60: FrameRate = FrameRate { num: 60, den: 1 };
-    pub const FPS_119_88: FrameRate = FrameRate { num: 120000, den: 1001 };
-    pub const FPS_120: FrameRate = FrameRate { num: 120, den: 1 };
-
-    /// Rates offered in sequence settings (Premiere's list).
-    pub const COMMON: [FrameRate; 11] = [
-        Self::FPS_23_976,
-        Self::FPS_24,
-        Self::FPS_25,
-        Self::FPS_29_97,
-        Self::FPS_30,
-        Self::FPS_48,
-        Self::FPS_50,
-        Self::FPS_59_94,
-        Self::FPS_60,
-        Self::FPS_119_88,
-        Self::FPS_120,
-    ];
-
-    pub fn new(num: i64, den: i64) -> Self {
-        let g = i128::from(gcd(num.unsigned_abs(), den.unsigned_abs()).max(1));
-        FrameRate { num: (i128::from(num) / g) as i64, den: (i128::from(den) / g) as i64 }
-    }
-
-    /// Closest standard rate for a float (e.g. from a container's average rate).
-    pub fn from_f64(fps: f64) -> Self {
-        for r in Self::COMMON {
-            if (r.as_f64() - fps).abs() < 0.005 {
-                return r;
-            }
-        }
-        FrameRate::new((fps * 1000.0).round() as i64, 1000)
-    }
-
-    /// Closest standard rate when `fps` is within `tolerance` of it, `tolerance` a fraction of the
-    /// rate (`0.005` is half a percent), else the nearest 1/1000 rate. A rate a container reports
-    /// from timestamps rounded to a coarse unit lands slightly off a standard rate: at 90 kHz,
-    /// whole milliseconds leave a 30 fps clip's average at 30.02 or 29.95 (#1700).
-    pub fn from_f64_within(fps: f64, tolerance: f64) -> Self {
-        let mut best: Option<(f64, FrameRate)> = None;
-        for r in Self::COMMON {
-            let off = (r.as_f64() - fps).abs();
-            if off <= tolerance * r.as_f64() && best.is_none_or(|(closest, _)| off < closest) {
-                best = Some((off, r));
-            }
-        }
-        best.map_or_else(|| Self::from_f64(fps), |(_, r)| r)
-    }
-
-    /// This rate if it is positive, else the default (a damaged file or project can carry a zero
-    /// or negative rate; every frame computation uses this so it can't divide by zero).
-    pub fn sane(self) -> FrameRate {
-        if self.num > 0 && self.den > 0 { self } else { FrameRate::default() }
-    }
-
-    pub fn as_f64(self) -> f64 {
-        self.num as f64 / self.den as f64
-    }
-
-    /// Exact duration of one frame (rounded down only for exotic rates).
-    /// Values outside the integer tick range saturate at its limit.
-    pub fn frame_duration(self) -> Tick {
-        let r = self.sane();
-        Tick(clamp_i64((TICKS_PER_SECOND as i128 * r.den as i128) / r.num as i128))
-    }
-
-    /// Index of the frame containing `t` (floor), saturated to the integer frame range.
-    pub fn frame_at(self, t: Tick) -> i64 {
-        clamp_i64(frame_index(self.sane(), t))
-    }
-
-    /// Frames from `start` to `end`, counted between their frame indices. `frame_at(end - start)`
-    /// can read one short when a frame is not a whole number of ticks: the ticks between two
-    /// boundaries can be one fewer than the exact length of those frames.
-    pub fn frames_between(self, start: Tick, end: Tick) -> i64 {
-        self.frame_at(end).saturating_sub(self.frame_at(start))
-    }
-
-    /// Start tick of frame `f` (ceiling division).
-    ///
-    /// Uses ceiling (not floor) so that `frame_at(tick_of(f)) == f` holds for every
-    /// representable frame boundary with at least one tick per frame, even when the frame duration is not an integer number of ticks
-    /// (exotic rates like 37.516 fps where `TICKS_PER_SECOND * den / num` has a
-    /// fractional remainder).  Floor division truncates the remainder, causing each
-    /// frame boundary to drift backward by one tick until `frame_at` returns `f - 1`
-    /// instead of `f` — frame stepping then stalls or moves backward.
-    /// Values outside the integer tick range saturate at its limit.
-    pub fn tick_of(self, f: i64) -> Tick {
-        Tick(clamp_i64(frame_boundary(self.sane(), i128::from(f))))
-    }
-
-    /// Snap `t` down to a frame boundary.
-    pub fn snap(self, t: Tick) -> Tick {
-        let r = self.sane();
-        Tick(clamp_i64(frame_boundary(r, frame_index(r, t))))
-    }
-
-    /// Snap `t` to the nearest frame boundary.
-    pub fn snap_nearest(self, t: Tick) -> Tick {
-        let r = self.sane();
-        // Keep the frame index and both boundaries wide until choosing the nearest. Saturating
-        // an unrepresentable upper boundary first would make it seem closer than it really is.
-        let f = frame_index(r, t);
-        let a = frame_boundary(r, f);
-        let b = frame_boundary(r, f.saturating_add(1));
-        let t = i128::from(t.0);
-        Tick(clamp_i64(if t - a <= b - t { a } else { b }))
-    }
-
-    /// Timecode base (frames counted per timecode second): 30 for 29.97, 24 for 23.976.
-    pub fn timecode_base(self) -> i64 {
-        let r = self.sane();
-        (r.num / r.den).saturating_add(i64::from(r.num % r.den != 0)).max(1)
-    }
-
-    /// NTSC (x/1001) rates can use drop-frame timecode.
-    pub fn is_ntsc(self) -> bool {
-        self.den == 1001
-    }
-
-    /// Whether drop-frame counting applies (29.97 / 59.94 / 119.88).
-    pub fn supports_drop_frame(self) -> bool {
-        self.is_ntsc() && self.timecode_base() % 30 == 0
-    }
-
-    pub fn label(self) -> String {
-        if self.den == 1 {
-            format!("{}", self.num)
-        } else {
-            let v = self.as_f64();
-            let s = format!("{v:.3}");
-            let s = s.trim_end_matches('0').trim_end_matches('.');
-            s.to_string()
-        }
-    }
-}
-
-impl fmt::Display for FrameRate {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "{} fps", self.label())
-    }
-}
-
-/// Narrow only after applying the storage bounds, never by a wrapping integer cast.
-fn clamp_i64(value: i128) -> i64 {
-    value.clamp(i128::from(i64::MIN), i128::from(i64::MAX)) as i64
-}
-
-/// Callers pass a positive rate. Products of two i64 values fit in i128.
-fn frame_index(rate: FrameRate, t: Tick) -> i128 {
-    (i128::from(t.0) * i128::from(rate.num)).div_euclid(i128::from(TICKS_PER_SECOND) * i128::from(rate.den))
-}
-
-/// Ceiling of the rational boundary. An overflowing numerator divided by an i64 rate cannot
-/// fit in an i64 tick, so saturating that intermediate preserves the public result. Boundaries
-/// derived from frame_index remain within i128 (at most one frame away from an i64 tick).
-fn frame_boundary(rate: FrameRate, frame: i128) -> i128 {
-    let Some(n) = frame.checked_mul(i128::from(TICKS_PER_SECOND)).and_then(|n| n.checked_mul(i128::from(rate.den))) else {
-        return if frame < 0 { i128::MIN } else { i128::MAX };
-    };
-    let d = i128::from(rate.num);
-    // Flooring a fractional boundary puts the tick in the preceding frame.
-    n.div_euclid(d) + i128::from(n.rem_euclid(d) != 0)
-}
-
-fn gcd(mut a: u64, mut b: u64) -> u64 {
-    while b != 0 {
-        (a, b) = (b, a % b);
-    }
-    a
-}
-
-/// How time is displayed (Premiere: Timecode, Feet+Frames 16mm/35mm, Frames, Audio Samples).
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
-pub enum TimeDisplay {
-    #[default]
-    Timecode,
-    Frames,
-    Feet16,
-    Feet35,
-    AudioSamples,
-    Seconds,
-}
-
-impl TimeDisplay {
-    pub const ALL: [TimeDisplay; 6] =
-        [TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames, TimeDisplay::AudioSamples, TimeDisplay::Seconds];
-    pub fn label(self) -> &'static str {
-        match self {
-            TimeDisplay::Timecode => "Timecode",
-            TimeDisplay::Frames => "Frames",
-            TimeDisplay::Feet16 => "Feet + Frames 16mm",
-            TimeDisplay::Feet35 => "Feet + Frames 35mm",
-            TimeDisplay::AudioSamples => "Audio Samples",
-            TimeDisplay::Seconds => "Seconds",
-        }
-    }
-}
-
-impl TimeDisplay {
-    /// The video display formats (Sequence Settings ▸ Display Format, the burn-in's Time Format).
-    pub const VIDEO: [TimeDisplay; 4] = [TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames];
-
-    /// Stable id used by commands and the UI: `timecode`, `feet35`, `feet16`, `frames`, `samples`, `seconds`.
-    pub fn id(self) -> &'static str {
-        match self {
-            TimeDisplay::Timecode => "timecode",
-            TimeDisplay::Frames => "frames",
-            TimeDisplay::Feet16 => "feet16",
-            TimeDisplay::Feet35 => "feet35",
-            TimeDisplay::AudioSamples => "samples",
-            TimeDisplay::Seconds => "seconds",
-        }
-    }
-
-    /// The display with this [`id`](Self::id), ignoring case.
-    pub fn from_id(id: &str) -> Option<TimeDisplay> {
-        TimeDisplay::ALL.into_iter().find(|d| d.id().eq_ignore_ascii_case(id))
-    }
-
-    /// Frames per foot of film for the Feet + Frames displays: 16 for 35mm 4-perf, 40 for 16mm.
-    pub fn frames_per_foot(self) -> Option<i64> {
-        match self {
-            TimeDisplay::Feet35 => Some(16),
-            TimeDisplay::Feet16 => Some(40),
-            _ => None,
-        }
-    }
-}
-
-/// Format a frame count as film feet + frames (`F+FF`, e.g. `2+08`; negative: `-2+08`).
-/// `frames_per_foot` below 1 is treated as 1 so a bad value never divides by zero.
+/// Format a timeline frame count as film feet + frames, retaining its established compact display.
 pub fn format_feet_frames(frame: i64, frames_per_foot: i64) -> String {
-    let per_ft = frames_per_foot.max(1).unsigned_abs();
-    let a = frame.unsigned_abs();
-    format!("{}{}+{:02}", if frame < 0 { "-" } else { "" }, a / per_ft, a % per_ft)
+    let per_foot = frames_per_foot.max(1).unsigned_abs();
+    let frames = frame.unsigned_abs();
+    format!("{}{}+{:02}", if frame < 0 { "-" } else { "" }, frames / per_foot, frames % per_foot)
 }
 
-/// Drop-frame parameters: frames dropped per minute and nominal base.
-fn df_params(rate: FrameRate) -> (i64, i64) {
-    let base = rate.timecode_base();
-    (base / 15, base) // 30 → 2, 60 → 4, 120 → 8
-}
-
-/// Convert a frame count to SMPTE fields `(negative, h, m, s, f)`.
-pub fn frames_to_fields(frame: i64, rate: FrameRate, drop_frame: bool) -> (bool, i64, i64, i64, i64) {
-    let neg = frame < 0;
-    let mut n = i128::from(frame).abs();
-    let (drop, base) = df_params(rate);
-    let (drop, base) = (i128::from(drop), i128::from(base));
-    if drop_frame && rate.supports_drop_frame() {
-        let per_min = base * 60 - drop;
-        let per_10 = per_min * 10 + drop;
-        let d = n / per_10;
-        let m = n % per_10;
-        n = n.saturating_add(drop * 9 * d);
-        if m > drop {
-            n = n.saturating_add(drop * ((m - drop) / per_min));
-        }
+/// Format time using the timeline's historical compact Feet + Frames display.
+pub fn format_time(tick: Tick, rate: FrameRate, drop_frame: bool, display: TimeDisplay, sample_rate: i64) -> String {
+    if let TimeDisplay::Feet35 | TimeDisplay::Feet16 = display {
+        return format_feet_frames(rate.frame_at(tick), display.frames_per_foot().unwrap_or(16));
     }
-    let f = n % base;
-    let s = (n / base) % 60;
-    let mi = (n / (base * 60)) % 60;
-    let h = n / (base * 3600);
-    (neg, clamp_i64(h), clamp_i64(mi), clamp_i64(s), clamp_i64(f))
+    craft_time::format_time(tick, rate, drop_frame, display, sample_rate)
 }
 
-/// Convert SMPTE fields back to a frame count.
-pub fn fields_to_frames(h: i64, m: i64, s: i64, f: i64, rate: FrameRate, drop_frame: bool) -> i64 {
-    let (drop, base) = df_params(rate);
-    let seconds = i128::from(h) * 3600 + i128::from(m) * 60 + i128::from(s);
-    // Nominal drop-frame labels can exceed i64 even when the final frame count fits.
-    let mut n = seconds.saturating_mul(i128::from(base)).saturating_add(i128::from(f));
-    if drop_frame && rate.supports_drop_frame() {
-        let total_min = i128::from(h) * 60 + i128::from(m);
-        n = n.saturating_sub(i128::from(drop) * (total_min - total_min / 10));
-    }
-    clamp_i64(n)
-}
-
-/// Format a frame count as SMPTE timecode (`HH:MM:SS:FF`, or `HH;MM;SS;FF` for drop-frame).
-pub fn format_timecode_frames(frame: i64, rate: FrameRate, drop_frame: bool) -> String {
-    let df = drop_frame && rate.supports_drop_frame();
-    let (neg, h, m, s, f) = frames_to_fields(frame, rate, df);
-    let sep = if df { ';' } else { ':' };
-    let fw = if rate.timecode_base() >= 100 { 3 } else { 2 };
-    format!("{}{h:02}{sep}{m:02}{sep}{s:02}{sep}{f:0fw$}", if neg { "-" } else { "" })
-}
-
-/// Format a tick according to a display mode.
-pub fn format_time(t: Tick, rate: FrameRate, drop_frame: bool, display: TimeDisplay, sample_rate: i64) -> String {
-    let frame = rate.frame_at(t);
-    match display {
-        TimeDisplay::Timecode => format_timecode_frames(frame, rate, drop_frame),
-        TimeDisplay::Frames => format!("{frame}"),
-        TimeDisplay::Feet35 | TimeDisplay::Feet16 => format_feet_frames(frame, display.frames_per_foot().unwrap_or(16)),
-        TimeDisplay::AudioSamples => {
-            let neg = t.0 < 0;
-            let a = t.0.unsigned_abs();
-            let tps = TICKS_PER_SECOND.unsigned_abs();
-            let secs = a / tps;
-            let rem = Tick((a % tps) as i64).to_units_floor(sample_rate);
-            format!("{}{:02}:{:02}:{:02}:{rem:05}", if neg { "-" } else { "" }, secs / 3600, (secs / 60) % 60, secs % 60)
-        }
-        TimeDisplay::Seconds => {
-            let s = format!("{:.3}", t.seconds());
-            // A tiny negative time rounds to zero but keeps its sign: drop it.
-            if s == "-0.000" { "0.000".to_string() } else { s }
-        }
-    }
-}
-
-/// Error from [`parse_timecode`].
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ParseError(pub String);
-
-impl fmt::Display for ParseError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(&self.0)
-    }
-}
-impl std::error::Error for ParseError {}
-
-/// Parse user-typed timecode into a frame count, the way Premiere's timecode fields do:
-/// - `01:02:03:04`, `01;02;03;04`, `1.2.3.4` (any of `:;.,` separators),
-/// - bare digits are read right-aligned as `HHMMSSFF` (`1000` = 00:00:10:00),
-/// - a leading `+`/`-` makes the value relative to `current` (`+15` = 15 frames later, `-1.00` = 1 s earlier).
-pub fn parse_timecode(input: &str, rate: FrameRate, drop_frame: bool, current: i64) -> Result<i64, ParseError> {
-    let s = input.trim();
-    if s.is_empty() {
-        return Err(ParseError("empty timecode".into()));
-    }
-    let (rel, body) = match s.as_bytes()[0] {
-        b'+' => (Some(1), &s[1..]),
-        b'-' => (Some(-1), &s[1..]),
-        _ => (None, s),
-    };
-    let parts: Vec<&str> = body.split([':', ';', '.', ',']).collect();
-    let nums: Vec<i64> = if parts.len() == 1 {
-        let digits = parts[0];
-        if digits.is_empty() || !digits.bytes().all(|b| b.is_ascii_digit()) {
-            return Err(ParseError(format!("not a timecode: `{input}`")));
-        }
-        // Right-aligned pairs: "12345" -> [1, 23, 45]; relative bare numbers are frames.
-        if rel.is_some() {
-            vec![digits.parse().map_err(|_| ParseError("number too large".into()))?]
-        } else {
-            let mut v = Vec::new();
-            let b = digits.as_bytes();
-            let mut end = b.len();
-            while end > 0 {
-                let start = end.saturating_sub(2);
-                v.push(digits[start..end].parse::<i64>().unwrap_or(0));
-                end = start;
-            }
-            v.reverse();
-            v
-        }
-    } else {
-        parts
-            .iter()
-            .map(|p| {
-                if p.is_empty() {
-                    Ok(0)
-                } else if !p.bytes().all(|b| b.is_ascii_digit()) {
-                    Err(ParseError(format!("bad field `{p}`")))
-                } else {
-                    p.parse::<i64>().map_err(|_| ParseError(format!("bad field `{p}`")))
-                }
-            })
-            .collect::<Result<_, _>>()?
-    };
-    if nums.len() > 4 {
-        return Err(ParseError("too many timecode fields".into()));
-    }
-    let mut f4 = [0i64; 4];
-    let off = 4 - nums.len();
-    f4[off..].copy_from_slice(&nums);
-    let [h, m, sec, fr] = f4;
-    // Overflowing fields (e.g. 90 frames) are allowed, as in Premiere.
-    let base = rate.timecode_base();
-    let frames = if nums.len() == 1 && rel.is_some() {
-        fr
-    } else if drop_frame && rate.supports_drop_frame() {
-        // overflowing fields carry into the next one first, then drop-frame counting applies
-        let (sec, fr) = (sec.saturating_add(fr / base), fr % base);
-        let (m, sec) = (m.saturating_add(sec / 60), sec % 60);
-        let (h, m) = (h.saturating_add(m / 60), m % 60);
-        fields_to_frames(h, m, sec, fr, rate, true)
-    } else {
-        // Saturating: typed or agent-sent timecodes can have absurdly large fields.
-        h.saturating_mul(3600).saturating_add(m.saturating_mul(60)).saturating_add(sec).saturating_mul(base).saturating_add(fr)
-    };
-    Ok(match rel {
-        Some(sign) => current.saturating_add(frames.saturating_mul(sign)),
-        None => frames,
-    })
-}
-
-/// Parse typed text in the given display format into a frame count.
-///
-/// - [`TimeDisplay::Frames`]: a plain frame count (`240`).
-/// - [`TimeDisplay::Feet35`] / [`TimeDisplay::Feet16`]: `F+FF` (`2+08`; `.`, `:`, `;` and `,` also
-///   separate); a bare number is a frame count. A frames field past the foot rolls over
-///   (`1+20` at 35mm is 36 frames), as the timecode parser does.
-/// - A leading `+` / `-` makes the value relative to `current` (a bare relative number is frames).
-/// - Every other display parses as timecode ([`parse_timecode`]).
-pub fn parse_time_display(input: &str, rate: FrameRate, drop_frame: bool, display: TimeDisplay, current: i64) -> Result<i64, ParseError> {
-    let per_ft = match display {
-        TimeDisplay::Frames => 1,
-        TimeDisplay::Feet35 | TimeDisplay::Feet16 => display.frames_per_foot().unwrap_or(16),
-        _ => return parse_timecode(input, rate, drop_frame, current),
-    };
-    let s = input.trim();
-    if s.is_empty() {
-        return Err(ParseError("empty time".into()));
-    }
-    let (rel, body) = match s.as_bytes()[0] {
-        b'+' => (Some(1), &s[1..]),
-        b'-' => (Some(-1), &s[1..]),
-        _ => (None, s),
-    };
-    let field = |p: &str| -> Result<i64, ParseError> {
-        if p.is_empty() {
-            Ok(0)
-        } else if !p.bytes().all(|b| b.is_ascii_digit()) {
-            Err(ParseError(format!("not a time: `{input}`")))
-        } else {
-            p.parse::<i64>().map_err(|_| ParseError("number too large".into()))
-        }
-    };
-    let parts: Vec<&str> = body.split(['+', ':', ';', '.', ',']).collect();
-    let frames = match parts.as_slice() {
-        [n] => field(n)?,
-        [feet, fr] if per_ft > 1 => field(feet)?.saturating_mul(per_ft).saturating_add(field(fr)?),
-        _ => return Err(ParseError(format!("not a time: `{input}`"))),
-    };
-    Ok(match rel {
-        Some(sign) => current.saturating_add(frames.saturating_mul(sign)),
-        None => frames,
-    })
-}
-
-/// Common audio sample rates offered in sequence settings.
-pub const SAMPLE_RATES: [i64; 6] = [32_000, 44_100, 48_000, 88_200, 96_000, 192_000];
-
 #[cfg(test)]
 mod tests;
diff --git a/crates/timeline/src/time/tests.rs b/crates/timeline/src/time/tests.rs
index e6aada244..40bea7624 100644
--- a/crates/timeline/src/time/tests.rs
+++ b/crates/timeline/src/time/tests.rs
@@ -1,6 +1,10 @@
 use super::*;
 use proptest::prelude::*;
 
+fn clamp_i64(value: i128) -> i64 {
+    value.clamp(i128::from(i64::MIN), i128::from(i64::MAX)) as i64
+}
+
 #[test]
 fn empty_time_ranges_never_overlap() {
     let clip = TimeRange::new(Tick(0), Tick(10));
diff --git a/crates/video/Cargo.toml b/crates/video/Cargo.toml
index 0e31f8e26..e5bbf1c94 100644
--- a/crates/video/Cargo.toml
+++ b/crates/video/Cargo.toml
@@ -25,8 +25,12 @@ apv-encode = ["craft-media/bitstream"]
 vp8 = ["vp8-decode", "vp8-encode"]
 vp8-decode = []
 vp8-encode = []
-# MPEG-2 video (ITU-T H.262) and MPEG-1 video (ISO/IEC 11172-2): decoder.
-mpeg2 = []
+# MPEG-2 video (ITU-T H.262) and MPEG-1 video (ISO/IEC 11172-2): decoder (`mpeg2-decode`) and
+# MPEG-2 encoder (`mpeg2-encode`). The encoder reuses the decoder's code tables, IDCT and motion
+# compensation, so it turns on the decoder too.
+mpeg2 = ["mpeg2-decode", "mpeg2-encode"]
+mpeg2-decode = []
+mpeg2-encode = ["mpeg2-decode"]
 # MPEG-4 Part 2 video (ISO/IEC 14496-2, the Xvid/DivX format): Simple profile encoder.
 mpeg4 = ["mpeg4-encode"]
 mpeg4-encode = ["craft-media/bitstream"]
@@ -58,6 +62,8 @@ rayon = { workspace = true, optional = true }
 
 [dev-dependencies]
 craft-media-testkit = { workspace = true }
+# The AVI muxer, for the MPEG-4 Part 2 encoder's end-to-end test.
+craft-media = { workspace = true, features = ["avi"] }
 
 [[test]]
 name = "dnx"
@@ -130,7 +136,7 @@ required-features = ["mpeg4-encode"]
 
 [[test]]
 name = "mpeg2"
-required-features = ["mpeg2"]
+required-features = ["mpeg2-decode"]
 
 [[test]]
 name = "prores"
diff --git a/crates/video/README.md b/crates/video/README.md
index 4aff9b8d0..74b8c6414 100644
--- a/crates/video/README.md
+++ b/crates/video/README.md
@@ -21,7 +21,7 @@ No codec feature is on by default.
 | `dnx` | [`dnx`](src/dnx/README.md) | Avid DNxHD / DNxHR (SMPTE ST 2019-1 VC-3): decoder and encoder |
 | `apv` | [`apv`](src/apv/README.md) | APV (Advanced Professional Video, RFC 9924): decoder (`apv-decode` alone) and encoder (`apv-encode` alone) |
 | `vp8` | `vp8` | VP8 (RFC 6386): decoder |
-| `mpeg2` | [`mpeg2`](src/mpeg2/README.md) | MPEG-2 video (ITU-T H.262) and MPEG-1 video (ISO/IEC 11172-2): decoder |
+| `mpeg2` | [`mpeg2`](src/mpeg2/README.md) | MPEG-2 video (ITU-T H.262) and MPEG-1 video (ISO/IEC 11172-2): decoder (`mpeg2-decode` alone); MPEG-2 encoder with I and P pictures (`mpeg2-encode`, which also turns on the decoder) |
 | `mpeg4` | [`mpeg4`](src/mpeg4/README.md) | MPEG-4 Part 2 video (ISO/IEC 14496-2, the Xvid/DivX format): Simple profile encoder (`mpeg4-encode`) |
 | `prores` | `prores` | Apple ProRes (SMPTE RDD 36): decoder and encoder |
 | `h264` | [`h264`](src/h264/decode/README.md) | ITU-T H.264 / AVC: decoder (`h264-decode` alone) and encoder (`h264-encode` alone) |
diff --git a/crates/video/src/h264/encode/mod.rs b/crates/video/src/h264/encode/mod.rs
index e13679431..f0c684e1e 100644
--- a/crates/video/src/h264/encode/mod.rs
+++ b/crates/video/src/h264/encode/mod.rs
@@ -418,7 +418,7 @@ impl<P: Pixel> Core<P> {
         )
     }
 
-    pub fn new(mut cfg: EncoderConfig) -> Result<Self, Error> {
+    fn new_with_extra_motion_search_starts(mut cfg: EncoderConfig, extra_motion_search_starts: bool) -> Result<Self, Error> {
         if cfg.width == 0
             || cfg.height == 0
             || !cfg.width.is_multiple_of(2)
@@ -468,6 +468,7 @@ impl<P: Pixel> Core<P> {
                 adaptive_t8: false,
                 always_intra: false,
                 cavlc_clamp: !cabac,
+                extra_motion_search_starts,
                 depth,
             },
             Preset::Balanced => EncParams {
@@ -487,6 +488,7 @@ impl<P: Pixel> Core<P> {
                 adaptive_t8: high,
                 always_intra: false,
                 cavlc_clamp: !cabac,
+                extra_motion_search_starts,
                 depth,
             },
             Preset::Quality => EncParams {
@@ -506,6 +508,7 @@ impl<P: Pixel> Core<P> {
                 adaptive_t8: high,
                 always_intra: true,
                 cavlc_clamp: !cabac,
+                extra_motion_search_starts,
                 depth,
             },
         };
@@ -1218,6 +1221,15 @@ pub struct Encoder {
     core: Cores,
 }
 
+/// Starting points considered by the integer motion search.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum MotionSearchStarts {
+    /// Include skip, zero and co-located vectors for 16x16 searches.
+    Extended,
+    /// Use only the skip seed and neighboring partition vector, matching the earlier FilmCraft encoder.
+    SeedAndNeighbour,
+}
+
 enum Cores {
     Eight(Box<Core<u8>>),
     Deep(Box<Core<u16>>),
@@ -1234,7 +1246,18 @@ macro_rules! core {
 
 impl Encoder {
     pub fn new(cfg: EncoderConfig) -> Result<Self, Error> {
-        let core = if cfg.bit_depth > 8 { Cores::Deep(Box::new(Core::new(cfg)?)) } else { Cores::Eight(Box::new(Core::new(cfg)?)) };
+        Self::new_with_motion_search_starts(cfg, MotionSearchStarts::Extended)
+    }
+
+    /// Construct an encoder with an explicit motion-search start policy. Existing callers should
+    /// use [`Encoder::new`], which selects [`MotionSearchStarts::Extended`].
+    pub fn new_with_motion_search_starts(cfg: EncoderConfig, starts: MotionSearchStarts) -> Result<Self, Error> {
+        let extra = starts == MotionSearchStarts::Extended;
+        let core = if cfg.bit_depth > 8 {
+            Cores::Deep(Box::new(Core::new_with_extra_motion_search_starts(cfg, extra)?))
+        } else {
+            Cores::Eight(Box::new(Core::new_with_extra_motion_search_starts(cfg, extra)?))
+        };
         Ok(Encoder { core })
     }
 
@@ -1450,7 +1473,7 @@ mod tests {
     /// A recycled `MbInfo` buffer must come back as all-default entries, whatever the previous picture left in it.
     #[test]
     fn recycled_mb_buffers_are_cleared() {
-        let mut core = Core::<u8>::new(EncoderConfig::new(64, 48, 30, 1)).unwrap();
+        let mut core = Core::<u8>::new_with_extra_motion_search_starts(EncoderConfig::new(64, 48, 30, 1), true).unwrap();
         let n = core.params.mbw * core.params.mbh;
         let mut m = core.new_mbs();
         assert_eq!(m.len(), n);
diff --git a/crates/video/src/h264/encode/slice.rs b/crates/video/src/h264/encode/slice.rs
index b8ad0f7a9..ffb46e19c 100644
--- a/crates/video/src/h264/encode/slice.rs
+++ b/crates/video/src/h264/encode/slice.rs
@@ -47,6 +47,8 @@ pub struct EncParams {
     pub always_intra: bool,
     /// Maximum CAVLC level magnitude (Baseline).
     pub cavlc_clamp: bool,
+    /// Whether the 16x16 motion search tries skip, zero and co-located starts.
+    pub extra_motion_search_starts: bool,
     pub depth: Depth,
 }
 
diff --git a/crates/video/src/h264/encode/slice/motion.rs b/crates/video/src/h264/encode/slice/motion.rs
index 1bc4bab02..24096d73c 100644
--- a/crates/video/src/h264/encode/slice/motion.rs
+++ b/crates/video/src/h264/encode/slice/motion.rs
@@ -296,10 +296,14 @@ impl<'a, 'b, P: Pixel> SliceEnc<'a, 'b, P> {
             skip_pred = Some((y, u, v));
         }
         // --- 16x16 search
-        let mut cands = vec![skip_mv, Mv::ZERO];
-        let colo = r.mbs[my * f.p.mbw + mx];
-        if colo.ref_idx[0][0] >= 0 {
-            cands.push(colo.mv[0][0]);
+        let mut cands = Vec::new();
+        if f.p.extra_motion_search_starts {
+            cands.push(skip_mv);
+            cands.push(Mv::ZERO);
+            let colo = r.mbs[my * f.p.mbw + mx];
+            if colo.ref_idx[0][0] >= 0 {
+                cands.push(colo.mv[0][0]);
+            }
         }
         let (mv16, mvp16, cost16) = {
             let (m, p, c) = self.search_part(r, &PartSearch { mx, my, part: Part::P16x16, list: 0, lam, seed: skip_mv }, src, &cands);
diff --git a/crates/video/src/lib.rs b/crates/video/src/lib.rs
index e8e9d8113..d9723a81d 100644
--- a/crates/video/src/lib.rs
+++ b/crates/video/src/lib.rs
@@ -8,7 +8,7 @@
 //! | `dnx` | [`dnx`] | Avid DNxHD / DNxHR (SMPTE ST 2019-1): decoder and encoder |
 //! | `apv` | [`apv`] | APV (RFC 9924): decoder (`apv-decode`) and encoder (`apv-encode`) |
 //! | `vp8` | [`vp8`] | VP8 (RFC 6386): decoder (`vp8-decode`) and key-frame encoder (`vp8-encode`) |
-//! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder |
+//! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder (`mpeg2-decode`) and MPEG-2 I/P encoder (`mpeg2-encode`) |
 //! | `mpeg4` | [`mpeg4`] | MPEG-4 Part 2 video (ISO/IEC 14496-2, Xvid/DivX): Simple profile encoder (`mpeg4-encode`) |
 //! | `prores` | [`prores`] | Apple ProRes (SMPTE RDD 36): decoder and encoder |
 //! | `h264` | [`h264`] | ITU-T H.264 / AVC: decoder (`h264-decode`) and encoder (`h264-encode`) |
@@ -35,7 +35,7 @@ pub mod dnx;
 #[cfg(any(feature = "vp8-decode", feature = "vp8-encode"))]
 pub mod vp8;
 
-#[cfg(feature = "mpeg2")]
+#[cfg(feature = "mpeg2-decode")]
 pub mod mpeg2;
 
 #[cfg(feature = "mpeg4-encode")]
diff --git a/crates/video/src/mpeg2/README.md b/crates/video/src/mpeg2/README.md
index 1c49d45cd..b68dc800b 100644
--- a/crates/video/src/mpeg2/README.md
+++ b/crates/video/src/mpeg2/README.md
@@ -1,6 +1,7 @@
-# MPEG-2 and MPEG-1 video decoder (`craft_video::mpeg2`, feature `mpeg2`)
+# MPEG-2 and MPEG-1 video decoder, MPEG-2 encoder (`craft_video::mpeg2`, features `mpeg2-decode`, `mpeg2-encode`)
 
-Clean-room MPEG-2 video and MPEG-1 video decoder in pure Rust. Depends only on
+Clean-room MPEG-2 video and MPEG-1 video decoder, and the first step of an MPEG-2 video encoder
+(I and P pictures, see "Encoder"), in pure Rust. Depends only on
 `thiserror` and (optional, feature `threads`) `rayon`. Builds for
 `wasm32-unknown-unknown`; no `unsafe`. No GPL/LGPL code (FFmpeg, libmpeg2, libavcodec) was
 consulted; FFmpeg is used only as an external fixture generator and test oracle.
@@ -11,6 +12,8 @@ consulted; FFmpeg is used only as an external fixture generator and test oracle.
 |---|---|---|
 | ITU-T H.262 \| ISO/IEC 13818-2 | 02/2000 (second edition, with Amd. 1 and Cor. 1/2 as incorporated in the 2000 text) | sequence / GOP / picture headers and extensions, slices, macroblocks, VLC tables (Annex B), inverse quantisation and mismatch control (§7.4), IDCT (Annex A), motion vectors and prediction (§7.6) |
 | ISO/IEC 11172-2 | 1993 | MPEG-1 video: slices spanning rows, MPEG-1 escape codes, oddification, full-pel vectors, D pictures |
+| ITU-T H.262 \| ISO/IEC 13818-2 §8 | 02/2000 | profile and level limits the encoder chooses from (Tables 8-8 to 8-13) |
+| MPEG-2 Test Model 5 (ISO/IEC JTC1/SC29/WG11/N0400) | April 1993 | encoder: target bit allocation and adaptive quantisation by activity (§5.2) |
 | IEEE Std 1180 | 1990 | IDCT accuracy test procedure (run as a unit test) |
 | ISO/IEC TR 13818-5 (MPEG Software Simulation Group decoder behaviour) | 1997 | two decoder behaviours the normative text leaves open (see "Interpretations") |
 
@@ -72,6 +75,58 @@ the synthetic-stream tests confirmed against FFmpeg:
   formula only when the prediction is out of range: a field vector's doubled vertical
   component predicting a following frame vector.
 
+## Encoder (feature `mpeg2-encode`)
+
+The encoder is the first step of MPEG-2 encoding in this crate, tracked in
+storytold/craft-libs#1133. It writes valid MPEG-2 elementary streams, but not yet DVD or
+broadcast deliverables: those need the later steps listed below.
+
+```rust
+use craft_video::mpeg2::{Encoder, EncoderConfig, RateControl, YuvFrame};
+
+let mut cfg = EncoderConfig::new(720, 576, 25, 1);
+cfg.rate = RateControl::Abr { kbps: 6000 };   // or RateControl::Quantiser(1..=31)
+cfg.gop_size = 12;                            // one I picture, then P pictures
+let mut enc = Encoder::new(cfg)?;
+for (i, f) in frames.iter().enumerate() {
+    let frame = YuvFrame { y: &f.y, cb: &f.cb, cr: &f.cr, y_stride: 720, c_stride: 360 };
+    for p in enc.encode(&frame, i as i64)? { /* p.data, p.pts, p.dts, p.keyframe, p.picture_type */ }
+}
+for p in enc.flush() { /* none yet: no B pictures */ }
+es.extend_from_slice(enc.end_of_sequence());
+```
+
+What it does:
+
+- Main Profile (4:2:0) at Low, Main, High-1440 and High Level, and 4:2:2 Profile at Main and
+  High Level. The lowest level that holds the size, frame rate and (average) bitrate is chosen;
+  sizes beyond High Level are refused. Any even picture size; edges are padded by repetition.
+- Progressive frame pictures, I and P, in closed GOPs. Every GOP starts with a sequence header,
+  sequence extension and GOP header (with a time code), so every I picture is a random access
+  point. Packets come out in decoding order, which equals display order without B pictures.
+- Forward DCT on the transpose of the decoder's IDCT basis; intra quantisation with a small
+  dead zone, non-intra quantisation by truncation; default or custom quantiser matrices
+  (sequence header); linear or non-linear quantiser scale; intra DC precision 8-10 bits;
+  intra VLC table B.15.
+- P pictures: integer pattern search (steps 8, 4, 2, 1) from candidate vectors (left neighbour,
+  predictor, the previous picture's vectors), then half-sample refinement; cost SAD + λ·bits.
+  Each macroblock is coded intra, motion-compensated with or without residual, "no MC" with
+  residual, or skipped. The search range sets f_code (1-4).
+- Adaptive quantisation by macroblock activity (Test Model 5 §5.2.3).
+- Rate control: a constant quantiser, or single-pass average bitrate with Test Model 5's
+  target bit allocation at picture level. Streams are signalled as variable bitrate
+  (`vbv_delay` 0xFFFF, the level's maximum bitrate and VBV size in the sequence header); the VBV
+  buffer is not modelled.
+- The reconstruction uses the decoder's own dequantisation, mismatch control, IDCT and motion
+  compensation, so this crate's decoder outputs exactly the encoder's reconstruction.
+- Slices (one per macroblock row) are coded in parallel on rayon with `threads`; the stream is
+  identical either way.
+
+Later steps (#1133): B pictures and reordering; CBR and VBR with a VBV guarantee; DVD presets
+(sizes, aspect, GOP length, 9.8 Mb/s, 23.976 soft telecine); interlaced coding (field/frame DCT,
+field prediction, alternate scan) and 4:2:2 High Level CBR for XDCAM HD422. MPEG-2 essence in the
+MXF writer and a program stream muxer belong to `craft-media`.
+
 ## Accuracy (vs FFmpeg as an external oracle)
 
 MPEG-2's IDCT is not bit-exact by definition (any IEEE 1180-accurate IDCT conforms, and the
@@ -131,3 +186,14 @@ fell to 77–150 fps). These are lower bounds.
   3000 random mutations never panic.
 - `synth_tests.rs`, `tests/mpeg2/oracle.rs`: see above (single-threaded decode identical to the
   threaded one).
+- `encode/`: every encoder code decodes to its value with the decoder's tables; motion vector
+  deltas survive the decoder's wrap for f_code 1-4; forward/inverse DCT and quantiser round trips;
+  rate control converges on its target. `encode/tests.rs`: our decoder outputs exactly the
+  encoder's reconstruction (intra only, a 30-picture P GOP, 4:2:2, linear and non-linear
+  quantisers, quantisers 1 and 31, DC precision 8 and 10, custom matrices, odd macroblock counts,
+  average bitrate); quality and size follow the quantiser; repeated pictures skip; levels and
+  aspect in the sequence header; bad configurations and short or inconsistent planes are refused.
+- `tests/mpeg2/encode.rs`: FFmpeg decodes our streams of `testsrc2` (CIF and 576-line 4:2:2)
+  without errors and within the decoder suite's tolerance of our reconstruction, ffprobe reports
+  the profile, level, pixel format and I/P picture types, and average bitrate lands within 10 % of
+  800 and 2500 kbit/s targets.
diff --git a/crates/video/src/mpeg2/encode/bitwriter.rs b/crates/video/src/mpeg2/encode/bitwriter.rs
new file mode 100644
index 000000000..75b363d47
--- /dev/null
+++ b/crates/video/src/mpeg2/encode/bitwriter.rs
@@ -0,0 +1,92 @@
+//! Big-endian bit writer for start-code units.
+
+pub(crate) struct BitWriter {
+    out: Vec<u8>,
+    acc: u64,
+    /// Bits held in `acc` (always below 8 between calls).
+    n: u32,
+}
+
+impl BitWriter {
+    pub fn new() -> Self {
+        Self { out: Vec::new(), acc: 0, n: 0 }
+    }
+
+    /// Append the low `bits` (0..=32) bits of `v`, most significant first.
+    #[inline(always)]
+    pub fn put(&mut self, v: u32, bits: u32) {
+        if bits == 0 {
+            return;
+        }
+        let mask = if bits == 32 { u32::MAX } else { (1u32 << bits) - 1 };
+        self.acc = (self.acc << bits) | u64::from(v & mask);
+        self.n += bits;
+        while self.n >= 8 {
+            self.n -= 8;
+            self.out.push((self.acc >> self.n) as u8);
+        }
+        self.acc &= (1u64 << self.n) - 1;
+    }
+
+    #[inline(always)]
+    pub fn bit(&mut self, b: bool) {
+        self.put(b as u32, 1);
+    }
+
+    /// Pad with zero bits to a byte boundary.
+    pub fn align(&mut self) {
+        if self.n > 0 {
+            self.put(0, 8 - self.n);
+        }
+    }
+
+    /// Byte-align and write the start code `00 00 01 code`.
+    pub fn start_code(&mut self, code: u8) {
+        self.align();
+        self.out.extend_from_slice(&[0, 0, 1, code]);
+    }
+
+    /// Bits written so far.
+    #[cfg(test)]
+    pub fn bits(&self) -> u64 {
+        self.out.len() as u64 * 8 + u64::from(self.n)
+    }
+
+    /// The bytes, padded to a byte boundary.
+    pub fn finish(mut self) -> Vec<u8> {
+        self.align();
+        self.out
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mpeg2::bits::Bits;
+
+    #[test]
+    fn round_trips_through_the_reader() {
+        let mut w = BitWriter::new();
+        w.put(0b101, 3);
+        w.put(0x1234_5678, 32);
+        w.bit(true);
+        w.put(0x3FF, 10);
+        assert_eq!(w.bits(), 46);
+        let d = w.finish();
+        assert_eq!(d.len(), 6);
+        let mut b = Bits::new(&d);
+        assert_eq!(b.read(3), 0b101);
+        assert_eq!(b.read(32), 0x1234_5678);
+        assert!(b.bit());
+        assert_eq!(b.read(10), 0x3FF);
+        assert_eq!(b.read(2), 0);
+    }
+
+    #[test]
+    fn start_codes_are_byte_aligned() {
+        let mut w = BitWriter::new();
+        w.put(1, 1);
+        w.start_code(0xB3);
+        assert_eq!(w.finish(), vec![0x80, 0, 0, 1, 0xB3]);
+    }
+}
diff --git a/crates/video/src/mpeg2/encode/mod.rs b/crates/video/src/mpeg2/encode/mod.rs
new file mode 100644
index 000000000..fcd1bd8d1
--- /dev/null
+++ b/crates/video/src/mpeg2/encode/mod.rs
@@ -0,0 +1,624 @@
+//! MPEG-2 video encoder (ITU-T H.262 | ISO/IEC 13818-2), feature `mpeg2-encode`.
+//!
+//! This is the first step of MPEG-2 encoding in this crate (storytold/craft-libs#1133): I and P
+//! pictures, progressive frame pictures, 4:2:0 (Main Profile) and 4:2:2 (4:2:2 Profile), closed
+//! GOPs, constant quantiser or single-pass average bitrate. B pictures, a VBV guarantee,
+//! interlaced coding and DVD / broadcast presets come later.
+//!
+//! ```no_run
+//! use craft_video::mpeg2::encode::{Encoder, EncoderConfig, RateControl, YuvFrame};
+//!
+//! let mut cfg = EncoderConfig::new(720, 576, 25, 1);
+//! cfg.rate = RateControl::Abr { kbps: 6000 };
+//! let mut enc = Encoder::new(cfg)?;
+//! let (y, c) = (vec![128u8; 720 * 576], vec![128u8; 360 * 288]);
+//! let mut es = Vec::new();
+//! for i in 0..50 {
+//!     let frame = YuvFrame { y: &y, cb: &c, cr: &c, y_stride: 720, c_stride: 360 };
+//!     for p in enc.encode(&frame, i)? {
+//!         es.extend_from_slice(&p.data);
+//!     }
+//! }
+//! for p in enc.flush() {
+//!     es.extend_from_slice(&p.data);
+//! }
+//! es.extend_from_slice(enc.end_of_sequence());
+//! # Ok::<(), craft_video::mpeg2::encode::EncodeError>(())
+//! ```
+
+mod bitwriter;
+mod motion;
+mod picture;
+mod rate;
+mod tables;
+mod transform;
+
+#[cfg(test)]
+mod tests;
+
+use crate::mpeg2::ChromaFormat;
+use crate::mpeg2::headers::{DEFAULT_INTRA, PictureType, SCAN};
+use crate::mpeg2::mc::Frame;
+
+use bitwriter::BitWriter;
+use picture::{PicCtx, RowOut, RowPlanes, encode_row, qcode_for, qscale};
+use rate::RateCtl;
+
+#[derive(Debug, thiserror::Error)]
+pub enum EncodeError {
+    #[error("unsupported MPEG-2 encoder configuration: {0}")]
+    Config(String),
+    #[error("bad input frame: {0}")]
+    BadFrame(String),
+}
+
+/// aspect_ratio_information (H.262 Table 6-3).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum AspectRatio {
+    /// Square samples.
+    Square,
+    /// 4:3 display.
+    Dar4x3,
+    /// 16:9 display.
+    Dar16x9,
+    /// 2.21:1 display.
+    Dar221x100,
+}
+
+impl AspectRatio {
+    fn code(self) -> u32 {
+        match self {
+            AspectRatio::Square => 1,
+            AspectRatio::Dar4x3 => 2,
+            AspectRatio::Dar16x9 => 3,
+            AspectRatio::Dar221x100 => 4,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum RateControl {
+    /// A constant quantiser_scale_code (1..=31; mapped through H.262 Table 7-6 with
+    /// `nonlinear_quant`). Adaptive quantisation still varies it per macroblock when enabled.
+    Quantiser(u8),
+    /// Single-pass average bitrate in kbit/s. The stream is signalled as variable bitrate and
+    /// is not checked against the VBV buffer.
+    Abr { kbps: u32 },
+}
+
+#[derive(Clone, Debug)]
+pub struct EncoderConfig {
+    /// Picture size: even, at most 1920×1152 (4:2:0) or 1920×1088 (4:2:2).
+    pub width: u32,
+    pub height: u32,
+    /// Frame rate: one of H.262 Table 6-4 (23.976, 24, 25, 29.97, 30, 50, 59.94, 60).
+    pub fps_num: u32,
+    pub fps_den: u32,
+    /// 4:2:0 (Main Profile) or 4:2:2 (4:2:2 Profile).
+    pub chroma: ChromaFormat,
+    pub aspect: AspectRatio,
+    /// Pictures per GOP: one I picture, then P pictures. 1 codes every picture as I. 1..=1023.
+    pub gop_size: u32,
+    pub rate: RateControl,
+    /// q_scale_type: the non-linear quantiser scale (finer steps at low quantisers).
+    pub nonlinear_quant: bool,
+    /// Vary the quantiser per macroblock with its activity (finer in flat areas).
+    pub adaptive_quant: bool,
+    /// Intra DC precision in bits: 8, 9 or 10.
+    pub intra_dc_bits: u8,
+    /// Quantiser matrices (raster order, values 1..=255); `None`: the defaults.
+    pub intra_matrix: Option<[u8; 64]>,
+    pub non_intra_matrix: Option<[u8; 64]>,
+    /// Largest motion vector searched, in luma samples (1..=63).
+    pub search_range: u32,
+    /// Code slices on the rayon pool (with the `threads` feature).
+    pub threads: bool,
+}
+
+impl EncoderConfig {
+    pub fn new(width: u32, height: u32, fps_num: u32, fps_den: u32) -> Self {
+        Self {
+            width,
+            height,
+            fps_num,
+            fps_den,
+            chroma: ChromaFormat::Yuv420,
+            aspect: AspectRatio::Square,
+            gop_size: 12,
+            rate: RateControl::Quantiser(4),
+            nonlinear_quant: true,
+            adaptive_quant: true,
+            intra_dc_bits: 9,
+            intra_matrix: None,
+            non_intra_matrix: None,
+            search_range: 31,
+            threads: cfg!(feature = "threads"),
+        }
+    }
+}
+
+/// Planar 8-bit input: luma `width × height`, chroma `width/2 × height/2` (4:2:0) or
+/// `width/2 × height` (4:2:2), rows `y_stride` / `c_stride` bytes apart.
+#[derive(Clone, Copy, Debug)]
+pub struct YuvFrame<'a> {
+    pub y: &'a [u8],
+    pub cb: &'a [u8],
+    pub cr: &'a [u8],
+    pub y_stride: usize,
+    pub c_stride: usize,
+}
+
+/// One coded picture, in decoding order.
+#[derive(Clone, Debug)]
+pub struct Packet {
+    /// Elementary stream bytes: the sequence header and GOP header before every I picture, then
+    /// the picture.
+    pub data: Vec<u8>,
+    pub pts: i64,
+    /// Decoding timestamp; equal to `pts` while there are no B pictures.
+    pub dts: i64,
+    /// An I picture starting a closed GOP (random access point).
+    pub keyframe: bool,
+    pub picture_type: PictureType,
+    /// Average quantiser_scale of the picture's macroblocks.
+    pub quantiser_scale: f32,
+}
+
+/// The encoder's reconstruction of a picture (what a decoder outputs), cropped.
+#[derive(Clone, Debug)]
+pub struct ReconFrame {
+    pub width: u32,
+    pub height: u32,
+    pub y: Vec<u8>,
+    pub cb: Vec<u8>,
+    pub cr: Vec<u8>,
+}
+
+/// The sequence_end_code.
+const SEQUENCE_END: [u8; 4] = [0, 0, 1, 0xB7];
+
+/// A profile and level (H.262 Tables 8-8 to 8-13): limits and profile_and_level_indication.
+#[derive(Clone, Copy, Debug)]
+struct Level {
+    indication: u8,
+    max_w: u32,
+    max_h: u32,
+    max_fps: u32,
+    luma_rate: u64,
+    bit_rate: u64,
+    vbv_bits: u64,
+}
+
+const MAIN_LEVELS: [Level; 4] = [
+    Level { indication: 0x4A, max_w: 352, max_h: 288, max_fps: 30, luma_rate: 3_041_280, bit_rate: 4_000_000, vbv_bits: 475_136 },
+    Level { indication: 0x48, max_w: 720, max_h: 576, max_fps: 30, luma_rate: 10_368_000, bit_rate: 15_000_000, vbv_bits: 1_835_008 },
+    Level { indication: 0x46, max_w: 1440, max_h: 1152, max_fps: 60, luma_rate: 47_001_600, bit_rate: 60_000_000, vbv_bits: 7_340_032 },
+    Level { indication: 0x44, max_w: 1920, max_h: 1152, max_fps: 60, luma_rate: 62_668_800, bit_rate: 80_000_000, vbv_bits: 9_781_248 },
+];
+
+const PROFILE_422_LEVELS: [Level; 2] = [
+    Level { indication: 0x85, max_w: 720, max_h: 608, max_fps: 30, luma_rate: 11_059_200, bit_rate: 50_000_000, vbv_bits: 9_437_184 },
+    Level { indication: 0x82, max_w: 1920, max_h: 1088, max_fps: 60, luma_rate: 62_668_800, bit_rate: 300_000_000, vbv_bits: 47_185_920 },
+];
+
+/// frame_rate_code for an exact frame rate (Table 6-4).
+fn frame_rate_code(num: u32, den: u32) -> Option<u32> {
+    if num == 0 || den == 0 {
+        return None;
+    }
+    let rates: [(u64, u64); 8] = [(24000, 1001), (24, 1), (25, 1), (30000, 1001), (30, 1), (50, 1), (60000, 1001), (60, 1)];
+    rates.iter().position(|&(n, d)| u64::from(num) * d == n * u64::from(den)).map(|i| i as u32 + 1)
+}
+
+/// The motion search's f_code: the smallest whose range [-8f, 8f-1] samples covers `range`.
+fn f_code_for(range: u32) -> u8 {
+    (1..=4u8).find(|&fc| 8 * (1u32 << (fc - 1)) > range).unwrap_or(4)
+}
+
+/// Pick the lowest level of the profile that holds the stream.
+fn choose_level(cfg: &EncoderConfig) -> Result<Level, EncodeError> {
+    let levels: &[Level] = match cfg.chroma {
+        ChromaFormat::Yuv420 => &MAIN_LEVELS,
+        ChromaFormat::Yuv422 => &PROFILE_422_LEVELS,
+        ChromaFormat::Yuv444 => return Err(EncodeError::Config("4:4:4 has no MPEG-2 profile in use".into())),
+    };
+    let fps = f64::from(cfg.fps_num) / f64::from(cfg.fps_den);
+    let luma_rate = f64::from(cfg.width) * f64::from(cfg.height) * fps;
+    let bps = match cfg.rate {
+        RateControl::Abr { kbps } => u64::from(kbps) * 1000,
+        RateControl::Quantiser(_) => 0,
+    };
+    levels
+        .iter()
+        .find(|l| {
+            cfg.width <= l.max_w
+                && cfg.height <= l.max_h
+                && fps <= f64::from(l.max_fps) + 0.01
+                && luma_rate <= l.luma_rate as f64
+                && bps <= l.bit_rate
+        })
+        .copied()
+        .ok_or_else(|| {
+            EncodeError::Config(format!(
+                "{}x{} at {:.3} fps{} is beyond every level of the profile",
+                cfg.width,
+                cfg.height,
+                fps,
+                if bps > 0 { format!(", {bps} bit/s") } else { String::new() }
+            ))
+        })
+}
+
+fn validate(cfg: &EncoderConfig) -> Result<(), EncodeError> {
+    let bad = |s: String| Err(EncodeError::Config(s));
+    if cfg.width == 0 || cfg.height == 0 || !cfg.width.is_multiple_of(2) || !cfg.height.is_multiple_of(2) {
+        return bad(format!("picture size {}x{} must be even and non-zero", cfg.width, cfg.height));
+    }
+    if frame_rate_code(cfg.fps_num, cfg.fps_den).is_none() {
+        return bad(format!("frame rate {}/{} is not one of H.262 Table 6-4", cfg.fps_num, cfg.fps_den));
+    }
+    if !(1..=1023).contains(&cfg.gop_size) {
+        return bad(format!("GOP size {} (1..=1023)", cfg.gop_size));
+    }
+    match cfg.rate {
+        RateControl::Quantiser(q) if !(1..=31).contains(&q) => return bad(format!("quantiser_scale_code {q} (1..=31)")),
+        RateControl::Abr { kbps: 0 } => return bad("bitrate 0".into()),
+        _ => {}
+    }
+    if !(8..=10).contains(&cfg.intra_dc_bits) {
+        return bad(format!("intra DC precision {} bits (8..=10)", cfg.intra_dc_bits));
+    }
+    if [cfg.intra_matrix, cfg.non_intra_matrix].iter().flatten().any(|m| m.contains(&0)) {
+        return bad("quantiser matrix with a zero entry".into());
+    }
+    if !(1..=63).contains(&cfg.search_range) {
+        return bad(format!("search range {} (1..=63)", cfg.search_range));
+    }
+    Ok(())
+}
+
+/// Write a quantiser matrix (raster order) in zigzag order.
+fn put_matrix(w: &mut BitWriter, m: &[u8; 64]) {
+    for &pos in &SCAN[0] {
+        w.put(u32::from(m[usize::from(pos)]), 8);
+    }
+}
+
+/// A stateful encoder. Feed pictures in display order; packets come out in decoding order.
+pub struct Encoder {
+    cfg: EncoderConfig,
+    level: Level,
+    mb_w: usize,
+    mb_h: usize,
+    shx: u32,
+    shy: u32,
+    f_code: u8,
+    intra_matrix: [u8; 64],
+    inter_matrix: [u8; 64],
+    /// Sequence header and sequence extension, sent before every GOP.
+    seq_header: Vec<u8>,
+    /// The reconstruction of the previous picture.
+    reference: Option<Frame>,
+    prev_mvs: Vec<[i32; 2]>,
+    /// Pictures coded so far.
+    count: u64,
+    /// Position of the next picture in its GOP.
+    gop_pos: u32,
+    rc: Option<RateCtl>,
+    recon_capture: bool,
+    recon: Vec<ReconFrame>,
+}
+
+impl Encoder {
+    pub fn new(cfg: EncoderConfig) -> Result<Self, EncodeError> {
+        validate(&cfg)?;
+        let level = choose_level(&cfg)?;
+        let (shx, shy) = if cfg.chroma == ChromaFormat::Yuv422 { (1, 0) } else { (1, 1) };
+        let nonlinear = cfg.nonlinear_quant;
+        let q_range = (f64::from(qscale(nonlinear, 1)), f64::from(qscale(nonlinear, 31)));
+        let rc = match cfg.rate {
+            RateControl::Abr { kbps } => Some(RateCtl::new(f64::from(kbps) * 1000.0, f64::from(cfg.fps_num) / f64::from(cfg.fps_den), q_range)),
+            RateControl::Quantiser(_) => None,
+        };
+        let mut enc = Encoder {
+            level,
+            mb_w: (cfg.width as usize).div_ceil(16),
+            mb_h: (cfg.height as usize).div_ceil(16),
+            shx,
+            shy,
+            f_code: f_code_for(cfg.search_range),
+            intra_matrix: cfg.intra_matrix.unwrap_or(DEFAULT_INTRA),
+            inter_matrix: cfg.non_intra_matrix.unwrap_or([16; 64]),
+            seq_header: Vec::new(),
+            reference: None,
+            prev_mvs: Vec::new(),
+            count: 0,
+            gop_pos: 0,
+            rc,
+            recon_capture: false,
+            recon: Vec::new(),
+            cfg,
+        };
+        enc.seq_header = enc.sequence_header_bytes();
+        Ok(enc)
+    }
+
+    pub fn config(&self) -> &EncoderConfig {
+        &self.cfg
+    }
+
+    /// profile_and_level_indication of the stream (e.g. 0x48 Main Profile @ Main Level).
+    pub fn profile_and_level(&self) -> u8 {
+        self.level.indication
+    }
+
+    /// The sequence header and sequence extension (for containers that store them apart).
+    pub fn sequence_header(&self) -> &[u8] {
+        &self.seq_header
+    }
+
+    /// The sequence_end_code to append after the last packet of an elementary stream.
+    pub fn end_of_sequence(&self) -> &'static [u8] {
+        &SEQUENCE_END
+    }
+
+    /// Keep each picture's reconstruction for [`Encoder::take_recon`].
+    pub fn set_recon_capture(&mut self, on: bool) {
+        self.recon_capture = on;
+    }
+
+    pub fn take_recon(&mut self) -> Vec<ReconFrame> {
+        std::mem::take(&mut self.recon)
+    }
+
+    /// Pictures held for reordering (none yet: there are no B pictures).
+    pub fn flush(&mut self) -> Vec<Packet> {
+        Vec::new()
+    }
+
+    fn sequence_header_bytes(&self) -> Vec<u8> {
+        let c = &self.cfg;
+        let mut w = BitWriter::new();
+        let bit_rate = self.level.bit_rate.div_ceil(400);
+        let vbv = self.level.vbv_bits / 16384;
+        w.start_code(0xB3);
+        w.put(c.width & 0xFFF, 12);
+        w.put(c.height & 0xFFF, 12);
+        w.put(c.aspect.code(), 4);
+        w.put(frame_rate_code(c.fps_num, c.fps_den).unwrap_or(3), 4);
+        w.put((bit_rate & 0x3FFFF) as u32, 18);
+        w.bit(true); // marker_bit
+        w.put((vbv & 0x3FF) as u32, 10);
+        w.bit(false); // constrained_parameters_flag
+        for m in [&c.intra_matrix, &c.non_intra_matrix] {
+            w.bit(m.is_some());
+            if let Some(m) = m {
+                put_matrix(&mut w, m);
+            }
+        }
+        w.start_code(0xB5);
+        w.put(1, 4); // sequence extension
+        w.put(u32::from(self.level.indication), 8);
+        w.bit(true); // progressive_sequence
+        w.put(if c.chroma == ChromaFormat::Yuv422 { 2 } else { 1 }, 2);
+        w.put(c.width >> 12, 2);
+        w.put(c.height >> 12, 2);
+        w.put((bit_rate >> 18) as u32 & 0xFFF, 12);
+        w.bit(true); // marker_bit
+        w.put((vbv >> 10) as u32 & 0xFF, 8);
+        w.bit(true); // low_delay: no B pictures
+        w.put(0, 2); // frame_rate_extension_n
+        w.put(0, 5); // frame_rate_extension_d
+        w.finish()
+    }
+
+    /// group_of_pictures_header with the time code of picture `self.count`.
+    fn gop_header(&self, w: &mut BitWriter) {
+        let fps = u64::from(self.cfg.fps_num.div_ceil(self.cfg.fps_den)).max(1);
+        let n = self.count;
+        let secs = n / fps;
+        w.start_code(0xB8);
+        w.bit(false); // drop_frame_flag
+        w.put(((secs / 3600) % 24) as u32, 5);
+        w.put(((secs / 60) % 60) as u32, 6);
+        w.bit(true); // marker_bit
+        w.put((secs % 60) as u32, 6);
+        w.put((n % fps) as u32, 6);
+        w.bit(true); // closed_gop
+        w.bit(false); // broken_link
+    }
+
+    fn picture_header(&self, w: &mut BitWriter, intra: bool) {
+        w.start_code(0x00);
+        w.put(self.gop_pos & 0x3FF, 10); // temporal_reference: display order within the GOP
+        w.put(if intra { 1 } else { 2 }, 3);
+        w.put(0xFFFF, 16); // vbv_delay: variable bitrate
+        if !intra {
+            w.bit(false); // full_pel_forward_vector
+            w.put(7, 3); // forward_f_code (MPEG-2: in the extension)
+        }
+        w.bit(false); // extra_bit_picture
+        w.start_code(0xB5);
+        w.put(8, 4); // picture coding extension
+        let fc = if intra { 15 } else { u32::from(self.f_code) };
+        for v in [fc, fc, 15, 15] {
+            w.put(v, 4);
+        }
+        w.put(u32::from(self.cfg.intra_dc_bits - 8), 2);
+        w.put(3, 2); // frame picture
+        w.bit(false); // top_field_first
+        w.bit(true); // frame_pred_frame_dct
+        w.bit(false); // concealment_motion_vectors
+        w.bit(self.cfg.nonlinear_quant); // q_scale_type
+        w.bit(true); // intra_vlc_format
+        w.bit(false); // alternate_scan
+        w.bit(false); // repeat_first_field
+        w.bit(self.cfg.chroma == ChromaFormat::Yuv420); // chroma_420_type = progressive_frame
+        w.bit(true); // progressive_frame
+        w.bit(false); // composite_display_flag
+    }
+
+    /// Copy the input into a macroblock-aligned frame, repeating the last column and row.
+    fn load(&self, f: &YuvFrame) -> Result<Frame, EncodeError> {
+        let (w, h) = (self.cfg.width as usize, self.cfg.height as usize);
+        let (cw, ch) = (w >> self.shx, h >> self.shy);
+        let (pw, ph) = (self.mb_w * 16, self.mb_h * 16);
+        let check = |name: &str, plane: &[u8], stride: usize, pw: usize, ph: usize| {
+            let need = stride.checked_mul(ph - 1).and_then(|n| n.checked_add(pw));
+            if stride < pw || need.is_none_or(|n| plane.len() < n) {
+                return Err(EncodeError::BadFrame(format!("{name}: {} bytes with stride {stride} for {pw}x{ph}", plane.len())));
+            }
+            Ok(())
+        };
+        check("luma", f.y, f.y_stride, w, h)?;
+        check("Cb", f.cb, f.c_stride, cw, ch)?;
+        check("Cr", f.cr, f.c_stride, cw, ch)?;
+        let mut out = Frame::new(pw, ph, pw >> self.shx, ph >> self.shy);
+        for (k, (src, stride, sw, sh)) in [(f.y, f.y_stride, w, h), (f.cb, f.c_stride, cw, ch), (f.cr, f.c_stride, cw, ch)].into_iter().enumerate() {
+            let dw = if k == 0 { pw } else { out.cw };
+            let dh = if k == 0 { ph } else { out.ch };
+            let dst = &mut out.planes[k];
+            for r in 0..dh {
+                let s = &src[r.min(sh - 1) * stride..][..sw];
+                let d = &mut dst[r * dw..(r + 1) * dw];
+                d[..sw].copy_from_slice(s);
+                let last = s[sw - 1];
+                d[sw..].fill(last);
+            }
+        }
+        Ok(out)
+    }
+
+    /// quantiser_scale_code per macroblock: `base` scaled by each macroblock's activity
+    /// (H.262 Test Model 5 §5.2.3) with adaptive quantisation.
+    fn mb_quant(&self, src: &Frame, base: f64) -> Vec<u8> {
+        let n = self.mb_w * self.mb_h;
+        let nl = self.cfg.nonlinear_quant;
+        if !self.cfg.adaptive_quant {
+            return vec![qcode_for(nl, base); n];
+        }
+        let acts: Vec<f64> = (0..n).map(|a| activity(src, a % self.mb_w, a / self.mb_w)).collect();
+        let avg = acts.iter().sum::<f64>() / n.max(1) as f64;
+        acts.iter().map(|&a| qcode_for(nl, base * (2.0 * a + avg) / (a + 2.0 * avg))).collect()
+    }
+
+    /// Encode one picture. Returns the packets that became ready (one per picture for now).
+    pub fn encode(&mut self, frame: &YuvFrame, pts: i64) -> Result<Vec<Packet>, EncodeError> {
+        let src = self.load(frame)?;
+        let reference = if self.gop_pos == 0 { None } else { self.reference.take() };
+        let intra = reference.is_none();
+        if intra {
+            self.gop_pos = 0;
+            if let Some(rc) = self.rc.as_mut() {
+                rc.start_gop(self.cfg.gop_size);
+            }
+        }
+        let base = match (&self.rc, self.cfg.rate) {
+            (Some(rc), _) => rc.qscale(intra),
+            (None, RateControl::Quantiser(q)) => f64::from(qscale(self.cfg.nonlinear_quant, q)),
+            (None, _) => 8.0,
+        };
+        let mb_qcode = self.mb_quant(&src, base);
+        let mut recon = Frame::new(src.w, src.h, src.cw, src.ch);
+        let ctx = PicCtx {
+            src: &src,
+            reference: reference.as_ref(),
+            prev_mvs: &self.prev_mvs,
+            mb_w: self.mb_w,
+            shx: self.shx,
+            shy: self.shy,
+            intra_matrix: &self.intra_matrix,
+            inter_matrix: &self.inter_matrix,
+            nonlinear: self.cfg.nonlinear_quant,
+            dc_prec: self.cfg.intra_dc_bits - 8,
+            f_code: self.f_code,
+            search: self.cfg.search_range as i32,
+            mb_qcode: &mb_qcode,
+        };
+        let rows = encode_rows(&ctx, &mut recon, self.cfg.threads);
+        let mut w = BitWriter::new();
+        if intra {
+            self.gop_header(&mut w);
+        }
+        self.picture_header(&mut w, intra);
+        let mut data = if intra { self.seq_header.clone() } else { Vec::new() };
+        data.extend_from_slice(&w.finish());
+        let mut qsum = 0u64;
+        let mut mvs = Vec::with_capacity(self.mb_w * self.mb_h);
+        for r in rows {
+            data.extend_from_slice(&r.bytes);
+            qsum += r.stats.qsum;
+            mvs.extend_from_slice(&r.mvs);
+        }
+        let avg_q = qsum as f64 / (self.mb_w * self.mb_h).max(1) as f64;
+        if let Some(rc) = self.rc.as_mut() {
+            rc.update(intra, data.len() as u64 * 8, avg_q);
+        }
+        if self.recon_capture {
+            self.recon.push(self.crop(&recon));
+        }
+        self.reference = Some(recon);
+        self.prev_mvs = mvs;
+        self.count += 1;
+        self.gop_pos = (self.gop_pos + 1) % self.cfg.gop_size;
+        let picture_type = if intra { PictureType::I } else { PictureType::P };
+        Ok(vec![Packet { data, pts, dts: pts, keyframe: intra, picture_type, quantiser_scale: avg_q as f32 }])
+    }
+
+    fn crop(&self, f: &Frame) -> ReconFrame {
+        let (w, h) = (self.cfg.width as usize, self.cfg.height as usize);
+        let (cw, ch) = (w >> self.shx, h >> self.shy);
+        let crop = |p: &[u8], stride: usize, w: usize, h: usize| (0..h).flat_map(|r| p[r * stride..r * stride + w].iter().copied()).collect();
+        ReconFrame {
+            width: w as u32,
+            height: h as u32,
+            y: crop(&f.planes[0], f.w, w, h),
+            cb: crop(&f.planes[1], f.cw, cw, ch),
+            cr: crop(&f.planes[2], f.cw, cw, ch),
+        }
+    }
+}
+
+/// Macroblock activity: one plus the smallest variance of its four luma blocks (TM5).
+fn activity(f: &Frame, mbx: usize, mby: usize) -> f64 {
+    let mut min = f64::MAX;
+    for b in 0..4 {
+        let (x0, y0) = (mbx * 16 + (b & 1) * 8, mby * 16 + (b >> 1) * 8);
+        let (mut s, mut s2) = (0u64, 0u64);
+        for r in 0..8 {
+            for &v in &f.planes[0][(y0 + r) * f.w + x0..][..8] {
+                s += u64::from(v);
+                s2 += u64::from(v) * u64::from(v);
+            }
+        }
+        let mean = s as f64 / 64.0;
+        min = min.min(s2 as f64 / 64.0 - mean * mean);
+    }
+    1.0 + min.max(0.0)
+}
+
+/// Code every macroblock row of the picture into `recon`, in parallel when allowed.
+fn encode_rows(ctx: &PicCtx, recon: &mut Frame, threads: bool) -> Vec<RowOut> {
+    let (w, cw) = (recon.w, recon.cw);
+    let clines = 16 >> ctx.shy;
+    let [y, cb, cr] = &mut recon.planes;
+    let run = |r: usize, y: &mut [u8], cb: &mut [u8], cr: &mut [u8]| encode_row(ctx, r, &mut RowPlanes { y, cb, cr });
+    #[cfg(feature = "threads")]
+    if threads {
+        use rayon::prelude::*;
+        return y
+            .par_chunks_mut(16 * w)
+            .zip(cb.par_chunks_mut(clines * cw))
+            .zip(cr.par_chunks_mut(clines * cw))
+            .enumerate()
+            .map(|(r, ((y, cb), cr))| run(r, y, cb, cr))
+            .collect();
+    }
+    let _ = threads;
+    y.chunks_mut(16 * w)
+        .zip(cb.chunks_mut(clines * cw))
+        .zip(cr.chunks_mut(clines * cw))
+        .enumerate()
+        .map(|(r, ((y, cb), cr))| run(r, y, cb, cr))
+        .collect()
+}
diff --git a/crates/video/src/mpeg2/encode/motion.rs b/crates/video/src/mpeg2/encode/motion.rs
new file mode 100644
index 000000000..a7bedc80b
--- /dev/null
+++ b/crates/video/src/mpeg2/encode/motion.rs
@@ -0,0 +1,191 @@
+//! Motion search for frame prediction: integer pattern search from predictor candidates, then
+//! half-sample refinement. Costs are SAD + λ·(motion vector bits).
+
+use crate::mpeg2::mc::{Block, Frame, predict};
+
+use super::tables::{enc_tables, wrap_delta};
+
+pub(crate) struct Search<'a> {
+    pub reference: &'a Frame,
+    /// The source macroblock's luma (16×16).
+    pub src: &'a [u8; 256],
+    pub mbx: usize,
+    pub mby: usize,
+    pub f_code: u8,
+    /// Largest integer displacement searched, in samples.
+    pub range: i32,
+    /// Motion vector predictor (half-sample units).
+    pub pmv: [i32; 2],
+    pub lambda: u32,
+}
+
+/// The chosen vector (half-sample units) and its SAD.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct Found {
+    pub mv: [i32; 2],
+    pub sad: u32,
+}
+
+/// Steps of the integer pattern search, coarse to fine.
+const STEPS: [i32; 4] = [8, 4, 2, 1];
+/// Moves per step before moving on (bounds the search on pathological content).
+const MAX_MOVES: usize = 16;
+
+impl Search<'_> {
+    fn origin(&self) -> (i32, i32) {
+        ((self.mbx * 16) as i32, (self.mby * 16) as i32)
+    }
+
+    /// Integer displacements allowed per axis: inside the reference and the f_code range.
+    fn bounds(&self) -> ([i32; 2], [i32; 2]) {
+        let f = 1i32 << self.f_code.saturating_sub(1);
+        let (ox, oy) = self.origin();
+        let (w, h) = (self.reference.w as i32, self.reference.h as i32);
+        let lo_lim = -(8 * f).min(self.range);
+        let hi_lim = (8 * f - 1).min(self.range);
+        ([lo_lim.max(-ox), lo_lim.max(-oy)], [hi_lim.min(w - 16 - ox), hi_lim.min(h - 16 - oy)])
+    }
+
+    /// A half-sample vector the bitstream can carry whose prediction stays inside the reference.
+    fn valid(&self, mv: [i32; 2]) -> bool {
+        let f = 1i32 << self.f_code.saturating_sub(1);
+        let (ox, oy) = self.origin();
+        let size = [self.reference.w as i32, self.reference.h as i32];
+        let o = [ox, oy];
+        (0..2).all(|c| {
+            let start = o[c] + (mv[c] >> 1);
+            mv[c] >= -16 * f && mv[c] < 16 * f && start >= 0 && start + 16 + (mv[c] & 1) <= size[c]
+        })
+    }
+
+    fn mv_cost(&self, mv: [i32; 2]) -> u32 {
+        let t = enc_tables();
+        let bits: u32 = (0..2).map(|c| t.motion_bits(wrap_delta(mv[c], self.pmv[c], self.f_code), self.f_code)).sum();
+        self.lambda * bits
+    }
+
+    fn sad_int(&self, d: [i32; 2]) -> u32 {
+        let (ox, oy) = self.origin();
+        let stride = self.reference.w;
+        let x = (ox + d[0]) as usize;
+        let y = (oy + d[1]) as usize;
+        let plane = &self.reference.planes[0];
+        let mut sad = 0u32;
+        for r in 0..16 {
+            let at = (y + r) * stride + x;
+            let Some(row) = plane.get(at..at + 16) else { return u32::MAX };
+            for (a, b) in row.iter().zip(&self.src[r * 16..r * 16 + 16]) {
+                sad += u32::from(a.abs_diff(*b));
+            }
+        }
+        sad
+    }
+
+    fn sad_half(&self, mv: [i32; 2]) -> u32 {
+        let (ox, oy) = self.origin();
+        let mut tmp = [0u8; 256];
+        let blk = Block { x: ox + (mv[0] >> 1), y: oy + (mv[1] >> 1), hx: mv[0] & 1 != 0, hy: mv[1] & 1 != 0, bw: 16, bh: 16 };
+        predict(&mut tmp, 0, 16, self.reference.plane(0, None), blk, false);
+        tmp.iter().zip(self.src.iter()).map(|(a, b)| u32::from(a.abs_diff(*b))).sum()
+    }
+
+    /// Best vector among the candidates (half-sample units), refined.
+    pub fn run(&self, candidates: &[[i32; 2]]) -> Found {
+        let (lo, hi) = self.bounds();
+        let clamp = |d: [i32; 2]| [d[0].clamp(lo[0], hi[0].max(lo[0])), d[1].clamp(lo[1], hi[1].max(lo[1]))];
+        let eval = |d: [i32; 2]| {
+            let sad = self.sad_int(d);
+            (sad.saturating_add(self.mv_cost([2 * d[0], 2 * d[1]])), sad)
+        };
+        let mut best_d = [0, 0];
+        let (mut best_cost, mut best_sad) = eval(best_d);
+        for c in candidates {
+            let d = clamp([c[0] >> 1, c[1] >> 1]);
+            if d != best_d {
+                let (cost, sad) = eval(d);
+                if cost < best_cost {
+                    (best_d, best_cost, best_sad) = (d, cost, sad);
+                }
+            }
+        }
+        for step in STEPS.into_iter().filter(|&s| s <= self.range.max(1)) {
+            for _ in 0..MAX_MOVES {
+                let mut moved = false;
+                for off in [[step, 0], [-step, 0], [0, step], [0, -step]] {
+                    let d = clamp([best_d[0] + off[0], best_d[1] + off[1]]);
+                    if d == best_d {
+                        continue;
+                    }
+                    let (cost, sad) = eval(d);
+                    if cost < best_cost {
+                        (best_d, best_cost, best_sad) = (d, cost, sad);
+                        moved = true;
+                    }
+                }
+                if !moved {
+                    break;
+                }
+            }
+        }
+        // half-sample refinement around the integer result
+        let centre = [2 * best_d[0], 2 * best_d[1]];
+        let mut best = Found { mv: centre, sad: best_sad };
+        for dy in -1..=1 {
+            for dx in -1..=1 {
+                let mv = [centre[0] + dx, centre[1] + dy];
+                if (dx == 0 && dy == 0) || !self.valid(mv) {
+                    continue;
+                }
+                let sad = self.sad_half(mv);
+                let cost = sad.saturating_add(self.mv_cost(mv));
+                if cost < best_cost {
+                    best_cost = cost;
+                    best = Found { mv, sad };
+                }
+            }
+        }
+        best
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A textured reference and a source macroblock cut from it at a known offset.
+    fn scene(dx: i32, dy: i32) -> (Frame, [u8; 256]) {
+        let mut f = Frame::new(64, 64, 32, 32);
+        for y in 0..64 {
+            for x in 0..64 {
+                let (x, y) = (x as f32, y as f32);
+                f.planes[0][y as usize * 64 + x as usize] =
+                    (128.0 + 60.0 * (x * 0.31).sin() * (y * 0.23).cos() + 30.0 * ((x + y) * 0.13).sin()) as u8;
+            }
+        }
+        let mut src = [0u8; 256];
+        for r in 0..16 {
+            for c in 0..16 {
+                src[r * 16 + c] = f.planes[0][(16 + dy + r as i32) as usize * 64 + (16 + dx + c as i32) as usize];
+            }
+        }
+        (f, src)
+    }
+
+    #[test]
+    fn finds_an_integer_displacement() {
+        let (f, src) = scene(3, -2);
+        let s = Search { reference: &f, src: &src, mbx: 1, mby: 1, f_code: 3, range: 15, pmv: [0, 0], lambda: 1 };
+        let found = s.run(&[]);
+        assert_eq!(found, Found { mv: [6, -4], sad: 0 });
+    }
+
+    #[test]
+    fn stays_inside_the_reference() {
+        let (f, src) = scene(0, 0);
+        for (mbx, mby) in [(0, 0), (3, 3), (0, 3)] {
+            let s = Search { reference: &f, src: &src, mbx, mby, f_code: 4, range: 63, pmv: [0, 0], lambda: 0 };
+            let found = s.run(&[[-200, -200], [200, 200]]);
+            assert!(s.valid(found.mv), "{found:?} at {mbx},{mby}");
+        }
+    }
+}
diff --git a/crates/video/src/mpeg2/encode/picture.rs b/crates/video/src/mpeg2/encode/picture.rs
new file mode 100644
index 000000000..e7bb84b7e
--- /dev/null
+++ b/crates/video/src/mpeg2/encode/picture.rs
@@ -0,0 +1,412 @@
+//! Slices and macroblocks of one frame picture (H.262 §6.2.4-§6.2.6), with a reconstruction
+//! that matches the decoder exactly. One slice per macroblock row; slices only depend on the
+//! reference picture, so rows can be coded in parallel.
+
+use crate::mpeg2::headers::SCAN;
+use crate::mpeg2::mc::{Block, Frame, predict};
+use crate::mpeg2::slice::NON_LINEAR_Q;
+use crate::mpeg2::vlc::{MB_FWD, MB_INTRA, MB_PATTERN, MB_QUANT};
+
+use super::bitwriter::BitWriter;
+use super::motion::Search;
+use super::tables::{EncTables, enc_tables, wrap_delta};
+use super::transform::{fdct, quant_inter, quant_intra, reconstruct};
+
+/// Intra coding is chosen when its cost (the luma's deviation from its block means) undercuts
+/// the best prediction's SAD by this much.
+const INTRA_BIAS: u32 = 256;
+
+/// quantiser_scale for quantiser_scale_code `code` (Table 7-6 when `nonlinear`).
+pub(crate) fn qscale(nonlinear: bool, code: u8) -> i32 {
+    if nonlinear { i32::from(NON_LINEAR_Q[usize::from(code & 31)]) } else { 2 * i32::from(code & 31) }
+}
+
+/// The quantiser_scale_code (1..=31) whose quantiser_scale is closest to `qs`.
+pub(crate) fn qcode_for(nonlinear: bool, qs: f64) -> u8 {
+    let mut best = (1u8, f64::MAX);
+    for code in 1..=31u8 {
+        let d = (f64::from(qscale(nonlinear, code)) - qs).abs();
+        if d < best.1 {
+            best = (code, d);
+        }
+    }
+    best.0
+}
+
+/// What every slice of one picture shares (read-only).
+pub(crate) struct PicCtx<'a> {
+    /// The padded source picture.
+    pub src: &'a Frame,
+    /// The reconstructed previous picture (P pictures); `None` codes an I picture.
+    pub reference: Option<&'a Frame>,
+    /// Vectors of the previous picture (motion search candidates), one per macroblock.
+    pub prev_mvs: &'a [[i32; 2]],
+    pub mb_w: usize,
+    pub shx: u32,
+    pub shy: u32,
+    pub intra_matrix: &'a [u8; 64],
+    pub inter_matrix: &'a [u8; 64],
+    pub nonlinear: bool,
+    /// intra_dc_precision (0..=2: 8..=10 bits).
+    pub dc_prec: u8,
+    pub f_code: u8,
+    pub search: i32,
+    /// quantiser_scale_code per macroblock.
+    pub mb_qcode: &'a [u8],
+}
+
+impl PicCtx<'_> {
+    fn cmb(&self) -> (usize, usize) {
+        (16 >> self.shx, 16 >> self.shy)
+    }
+    fn blocks(&self) -> usize {
+        if self.shy == 1 { 6 } else { 8 }
+    }
+    fn dc_reset(&self) -> i32 {
+        1 << (7 + self.dc_prec)
+    }
+}
+
+/// The part of the reconstructed picture one macroblock row covers.
+pub(crate) struct RowPlanes<'b> {
+    pub y: &'b mut [u8],
+    pub cb: &'b mut [u8],
+    pub cr: &'b mut [u8],
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+pub(crate) struct RowStats {
+    pub intra: u32,
+    pub skipped: u32,
+    /// Sum of the quantiser_scale of every macroblock.
+    pub qsum: u64,
+}
+
+pub(crate) struct RowOut {
+    /// The slice, from its start code, byte aligned.
+    pub bytes: Vec<u8>,
+    /// The vector each macroblock used (zero for intra and skipped ones).
+    pub mvs: Vec<[i32; 2]>,
+    pub stats: RowStats,
+}
+
+/// One macroblock's samples: luma 16×16, chroma rows of `16 >> shx`.
+#[derive(Clone)]
+struct MbPix {
+    y: [u8; 256],
+    c: [[u8; 256]; 2],
+}
+
+impl MbPix {
+    fn load(f: &Frame, mbx: usize, mby: usize, (cbw, cbh): (usize, usize)) -> MbPix {
+        let mut m = MbPix { y: [0; 256], c: [[0; 256]; 2] };
+        for r in 0..16 {
+            let at = (mby * 16 + r) * f.w + mbx * 16;
+            m.y[r * 16..r * 16 + 16].copy_from_slice(&f.planes[0][at..at + 16]);
+        }
+        for c in 0..2 {
+            for r in 0..cbh {
+                let at = (mby * cbh + r) * f.cw + mbx * cbw;
+                m.c[c][r * cbw..r * cbw + cbw].copy_from_slice(&f.planes[1 + c][at..at + cbw]);
+            }
+        }
+        m
+    }
+
+    /// Plane, offset and stride of block `i` (H.262 Figure 6-10 order: four luma blocks, then
+    /// Cb, Cr, and for 4:2:2 the lower Cb, Cr).
+    fn block_at(i: usize, cbw: usize) -> (usize, usize, usize) {
+        if i < 4 { (0, (i >> 1) * 8 * 16 + (i & 1) * 8, 16) } else { (1 + (i & 1), ((i - 4) >> 1) * 8 * cbw, cbw) }
+    }
+
+    fn plane(&self, p: usize) -> &[u8; 256] {
+        if p == 0 { &self.y } else { &self.c[p - 1] }
+    }
+
+    fn plane_mut(&mut self, p: usize) -> &mut [u8; 256] {
+        if p == 0 { &mut self.y } else { &mut self.c[p - 1] }
+    }
+
+    fn block(&self, i: usize, cbw: usize) -> [i32; 64] {
+        let (p, off, stride) = Self::block_at(i, cbw);
+        let d = self.plane(p);
+        std::array::from_fn(|k| i32::from(d[off + (k >> 3) * stride + (k & 7)]))
+    }
+
+    /// Write `v` (intra samples) or add it to what is there (inter residual), saturated.
+    fn store(&mut self, i: usize, cbw: usize, v: &[i32; 64], add: bool) {
+        let (p, off, stride) = Self::block_at(i, cbw);
+        let d = self.plane_mut(p);
+        for (k, &x) in v.iter().enumerate() {
+            let at = off + (k >> 3) * stride + (k & 7);
+            let base = if add { i32::from(d[at]) } else { 0 };
+            d[at] = (base + x).clamp(0, 255) as u8;
+        }
+    }
+
+    fn put(&self, out: &mut RowPlanes, mbx: usize, (cbw, cbh): (usize, usize), (w, cw): (usize, usize)) {
+        for r in 0..16 {
+            let at = r * w + mbx * 16;
+            if let Some(d) = out.y.get_mut(at..at + 16) {
+                d.copy_from_slice(&self.y[r * 16..r * 16 + 16]);
+            }
+        }
+        for (c, plane) in [&mut *out.cb, &mut *out.cr].into_iter().enumerate() {
+            for r in 0..cbh {
+                let at = r * cw + mbx * cbw;
+                if let Some(d) = plane.get_mut(at..at + cbw) {
+                    d.copy_from_slice(&self.c[c][r * cbw..r * cbw + cbw]);
+                }
+            }
+        }
+    }
+}
+
+/// Slice coding state (what the decoder tracks too).
+struct SliceSt {
+    qcode: u8,
+    dc: [i32; 3],
+    pmv: [i32; 2],
+    /// Skipped macroblocks not yet covered by an address increment.
+    skipped: usize,
+    /// The vector of the macroblock to the left (motion search candidate).
+    left_mv: [i32; 2],
+}
+
+/// One macroblock being coded.
+struct MbIn<'x> {
+    src: &'x MbPix,
+    mbx: usize,
+    mby: usize,
+    qcode: u8,
+}
+
+/// Code macroblock row `row` as one slice, writing its reconstruction into `out`.
+pub(crate) fn encode_row(ctx: &PicCtx, row: usize, out: &mut RowPlanes) -> RowOut {
+    let mut w = BitWriter::new();
+    w.start_code(1 + row as u8);
+    let q0 = ctx.mb_qcode.get(row * ctx.mb_w).copied().unwrap_or(1);
+    w.put(u32::from(q0), 5);
+    w.bit(false); // extra_bit_slice
+    let mut st = SliceSt { qcode: q0, dc: [ctx.dc_reset(); 3], pmv: [0; 2], skipped: 0, left_mv: [0; 2] };
+    let mut ro = RowOut { bytes: Vec::new(), mvs: vec![[0; 2]; ctx.mb_w], stats: RowStats::default() };
+    for mbx in 0..ctx.mb_w {
+        macroblock(ctx, &mut st, &mut w, (mbx, row), out, &mut ro);
+    }
+    ro.bytes = w.finish();
+    ro
+}
+
+fn macroblock(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, (mbx, mby): (usize, usize), out: &mut RowPlanes, ro: &mut RowOut) {
+    let addr = mby * ctx.mb_w + mbx;
+    let qcode = ctx.mb_qcode.get(addr).copied().unwrap_or(st.qcode);
+    let src = MbPix::load(ctx.src, mbx, mby, ctx.cmb());
+    let mb = MbIn { src: &src, mbx, mby, qcode };
+    let qs = qscale(ctx.nonlinear, qcode);
+    ro.stats.qsum += qs as u64;
+    let planes = (ctx.src.w, ctx.src.cw);
+    let Some(reference) = ctx.reference else {
+        intra_mb(ctx, st, w, &mb).put(out, mbx, ctx.cmb(), planes);
+        ro.stats.intra += 1;
+        return;
+    };
+    let mut candidates = vec![st.left_mv, st.pmv];
+    for a in [Some(addr), addr.checked_sub(ctx.mb_w), Some(addr + 1), Some(addr + ctx.mb_w)].into_iter().flatten() {
+        if let Some(&v) = ctx.prev_mvs.get(a) {
+            candidates.push(v);
+        }
+    }
+    let lambda = ((qs * 3 + 4) / 8).max(1) as u32;
+    let search = Search { reference, src: &src.y, mbx, mby, f_code: ctx.f_code, range: ctx.search, pmv: st.pmv, lambda };
+    let found = search.run(&candidates);
+    if intra_cost(&src.y).saturating_add(INTRA_BIAS) < found.sad {
+        intra_mb(ctx, st, w, &mb).put(out, mbx, ctx.cmb(), planes);
+        ro.stats.intra += 1;
+        st.left_mv = [0; 2];
+        return;
+    }
+    let (rec, skipped) = inter_mb(ctx, st, w, &mb, reference, found.mv);
+    rec.put(out, mbx, ctx.cmb(), planes);
+    ro.stats.skipped += skipped as u32;
+    ro.mvs[mbx] = found.mv;
+    st.left_mv = found.mv;
+}
+
+/// Σ |sample − block mean| over the four luma blocks: the cost of coding them intra.
+fn intra_cost(y: &[u8; 256]) -> u32 {
+    let mut cost = 0u32;
+    for b in 0..4 {
+        let off = (b >> 1) * 128 + (b & 1) * 8;
+        let at = |k: usize| u32::from(y[off + (k >> 3) * 16 + (k & 7)]);
+        let mean = ((0..64).map(at).sum::<u32>() + 32) / 64;
+        cost += (0..64).map(|k| at(k).abs_diff(mean)).sum::<u32>();
+    }
+    cost
+}
+
+fn put_increment(w: &mut BitWriter, t: &EncTables, mut n: usize) {
+    while n > 33 {
+        t.mba_escape.put(w);
+        n -= 33;
+    }
+    t.mba[n.max(1)].put(w);
+}
+
+/// Write the coefficients of a block (raster-order levels) in zigzag order from `start`, then
+/// end of block.
+fn put_coefficients(w: &mut BitWriter, t: &EncTables, levels: &[i32; 64], table: usize, start: usize) {
+    let mut run = 0;
+    let mut first = start == 0;
+    for &pos in &SCAN[0][start..] {
+        let l = levels[usize::from(pos)];
+        if l == 0 {
+            run += 1;
+            continue;
+        }
+        t.put_coefficient(w, table, run, l, first);
+        first = false;
+        run = 0;
+    }
+    t.dct_eob[table].put(w);
+}
+
+fn put_mb_type(w: &mut BitWriter, t: &EncTables, predicted: bool, flags: i16) {
+    let table = if predicted { &t.mbtype_p } else { &t.mbtype_i };
+    if let Some(c) = table.get(flags as usize).copied().flatten() {
+        c.put(w);
+    }
+}
+
+/// Code an intra macroblock; returns its reconstruction.
+fn intra_mb(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, mb: &MbIn) -> MbPix {
+    let t = enc_tables();
+    let quant = mb.qcode != st.qcode;
+    put_increment(w, t, st.skipped + 1);
+    st.skipped = 0;
+    put_mb_type(w, t, ctx.reference.is_some(), if quant { MB_INTRA | MB_QUANT } else { MB_INTRA });
+    if quant {
+        w.put(u32::from(mb.qcode), 5);
+        st.qcode = mb.qcode;
+    }
+    st.pmv = [0; 2];
+    let qs = qscale(ctx.nonlinear, st.qcode);
+    let dc_mult = 8 >> ctx.dc_prec;
+    let dc_max = (1 << (8 + ctx.dc_prec)) - 1;
+    let (cbw, _) = ctx.cmb();
+    let mut rec = mb.src.clone();
+    for i in 0..ctx.blocks() {
+        let cc = if i < 4 { 0 } else { 1 + (i & 1) };
+        let f = fdct(&mb.src.block(i, cbw));
+        let mut levels = [0i32; 64];
+        levels[0] = ((f[0] / dc_mult as f32).round() as i32).clamp(0, dc_max);
+        for pos in 1..64 {
+            levels[pos] = quant_intra(f[pos], ctx.intra_matrix[pos], qs);
+        }
+        let diff = levels[0] - st.dc[cc];
+        st.dc[cc] = levels[0];
+        let size = 32 - diff.unsigned_abs().leading_zeros();
+        let size_codes = if cc == 0 { &t.dc_luma } else { &t.dc_chroma };
+        size_codes[size as usize].put(w);
+        if size > 0 {
+            let v = if diff > 0 { diff } else { diff + (1 << size) - 1 };
+            w.put(v as u32, size);
+        }
+        put_coefficients(w, t, &levels, 1, 1);
+        rec.store(i, cbw, &reconstruct(&levels, ctx.intra_matrix, qs, true, dc_mult), false);
+    }
+    rec
+}
+
+/// Code a predicted macroblock with vector `mv` (or skip it); returns its reconstruction and
+/// whether it was skipped.
+fn inter_mb(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, mb: &MbIn, reference: &Frame, mv: [i32; 2]) -> (MbPix, bool) {
+    let t = enc_tables();
+    let mut rec = predict_mb(ctx, reference, mv, mb.mbx, mb.mby);
+    let qs = qscale(ctx.nonlinear, mb.qcode);
+    let (cbw, _) = ctx.cmb();
+    let n = ctx.blocks();
+    let mut levels = [[0i32; 64]; 8];
+    let mut cbp = 0u32;
+    for i in 0..n {
+        let (s, p) = (mb.src.block(i, cbw), rec.block(i, cbw));
+        let f = fdct(&std::array::from_fn(|k| s[k] - p[k]));
+        for pos in 0..64 {
+            levels[i][pos] = quant_inter(f[pos], ctx.inter_matrix[pos], qs);
+        }
+        if levels[i].iter().any(|&l| l != 0) {
+            cbp |= 1 << (n - 1 - i);
+        }
+    }
+    st.dc = [ctx.dc_reset(); 3];
+    // the first and last macroblock of a slice are always coded
+    let edge = mb.mbx == 0 || mb.mbx + 1 == ctx.mb_w;
+    if mv == [0, 0] && cbp == 0 && !edge {
+        st.skipped += 1;
+        st.pmv = [0; 2];
+        return (rec, true);
+    }
+    put_increment(w, t, st.skipped + 1);
+    st.skipped = 0;
+    let quant = cbp != 0 && mb.qcode != st.qcode;
+    let mut flags = if cbp == 0 {
+        MB_FWD
+    } else if mv == [0, 0] {
+        MB_PATTERN
+    } else {
+        MB_FWD | MB_PATTERN
+    };
+    if quant {
+        flags |= MB_QUANT;
+    }
+    put_mb_type(w, t, true, flags);
+    if quant {
+        w.put(u32::from(mb.qcode), 5);
+        st.qcode = mb.qcode;
+    }
+    if flags & MB_FWD != 0 {
+        for c in 0..2 {
+            t.put_motion(w, wrap_delta(mv[c], st.pmv[c], ctx.f_code), ctx.f_code);
+        }
+        st.pmv = mv;
+    } else {
+        st.pmv = [0; 2]; // "No MC" resets the predictors
+    }
+    if cbp != 0 {
+        if n == 8 {
+            t.cbp[(cbp >> 2) as usize].put(w);
+            w.put(cbp & 3, 2);
+        } else {
+            t.cbp[cbp as usize].put(w);
+        }
+        for i in 0..n {
+            if cbp & (1 << (n - 1 - i)) != 0 {
+                put_coefficients(w, t, &levels[i], 0, 0);
+                rec.store(i, cbw, &reconstruct(&levels[i], ctx.inter_matrix, qs, false, 0), true);
+            }
+        }
+    }
+    (rec, false)
+}
+
+/// The frame prediction of a macroblock from `f` with vector `mv`, formed as the decoder forms
+/// it (§7.6.4: chroma vectors are the luma ones halved towards zero).
+fn predict_mb(ctx: &PicCtx, f: &Frame, mv: [i32; 2], mbx: usize, mby: usize) -> MbPix {
+    let (cbw, cbh) = ctx.cmb();
+    let mut p = MbPix { y: [0; 256], c: [[0; 256]; 2] };
+    let blk =
+        Block { x: (mbx * 16) as i32 + (mv[0] >> 1), y: (mby * 16) as i32 + (mv[1] >> 1), hx: mv[0] & 1 != 0, hy: mv[1] & 1 != 0, bw: 16, bh: 16 };
+    predict(&mut p.y, 0, 16, f.plane(0, None), blk, false);
+    let cmv = [if ctx.shx == 1 { mv[0] / 2 } else { mv[0] }, if ctx.shy == 1 { mv[1] / 2 } else { mv[1] }];
+    let cb = Block {
+        x: (mbx * cbw) as i32 + (cmv[0] >> 1),
+        y: (mby * cbh) as i32 + (cmv[1] >> 1),
+        hx: cmv[0] & 1 != 0,
+        hy: cmv[1] & 1 != 0,
+        bw: cbw,
+        bh: cbh,
+    };
+    for c in 0..2 {
+        predict(&mut p.c[c], 0, cbw, f.plane(1 + c, None), cb, false);
+    }
+    p
+}
diff --git a/crates/video/src/mpeg2/encode/rate.rs b/crates/video/src/mpeg2/encode/rate.rs
new file mode 100644
index 000000000..65c23efc3
--- /dev/null
+++ b/crates/video/src/mpeg2/encode/rate.rs
@@ -0,0 +1,102 @@
+//! Single-pass average bitrate control at picture level, after the target bit allocation of the
+//! MPEG-2 Test Model 5: each picture type keeps a complexity `X = bits · average quantiser`, the
+//! bits left for the GOP are shared out by complexity, and a picture's quantiser is `X / target`.
+//! There is no VBV model: the average converges on the target, single pictures may not.
+
+pub(crate) struct RateCtl {
+    bps: f64,
+    fps: f64,
+    /// Complexity of I and P pictures.
+    xi: f64,
+    xp: f64,
+    /// Bits left for the current GOP (carries over between GOPs).
+    remaining: f64,
+    /// P pictures left in the current GOP.
+    np: u32,
+    /// Range of quantiser_scale values.
+    q_min: f64,
+    q_max: f64,
+}
+
+impl RateCtl {
+    pub fn new(bps: f64, fps: f64, q_range: (f64, f64)) -> Self {
+        // TM5's starting complexities
+        Self { bps, fps, xi: 160.0 * bps / 115.0, xp: 60.0 * bps / 115.0, remaining: 0.0, np: 0, q_min: q_range.0, q_max: q_range.1 }
+    }
+
+    /// A GOP of `pictures` pictures (one I, the rest P) starts.
+    pub fn start_gop(&mut self, pictures: u32) {
+        self.remaining += self.bps * f64::from(pictures) / self.fps;
+        self.np = pictures.saturating_sub(1);
+    }
+
+    /// quantiser_scale for the next picture.
+    pub fn qscale(&self, intra: bool) -> f64 {
+        let floor = self.bps / (8.0 * self.fps);
+        let (target, x) = if intra {
+            (self.remaining / (1.0 + f64::from(self.np) * self.xp / self.xi), self.xi)
+        } else {
+            (self.remaining / f64::from(self.np.max(1)), self.xp)
+        };
+        (x / target.max(floor)).clamp(self.q_min, self.q_max)
+    }
+
+    /// The picture used `bits` at average quantiser_scale `avg_q`.
+    pub fn update(&mut self, intra: bool, bits: u64, avg_q: f64) {
+        let x = bits as f64 * avg_q;
+        if intra {
+            self.xi = x.max(1.0);
+        } else {
+            self.xp = x.max(1.0);
+            self.np = self.np.saturating_sub(1);
+        }
+        self.remaining -= bits as f64;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A picture whose size is `complexity / q` (the model the controller assumes).
+    fn run(complexity_i: f64, complexity_p: f64, bps: f64, gops: u32) -> f64 {
+        let fps = 25.0;
+        let mut rc = RateCtl::new(bps, fps, (1.0, 112.0));
+        let mut total = 0.0;
+        for _ in 0..gops {
+            rc.start_gop(12);
+            for k in 0..12 {
+                let intra = k == 0;
+                let q = rc.qscale(intra);
+                let bits = (if intra { complexity_i } else { complexity_p }) / q;
+                rc.update(intra, bits as u64, q);
+                total += bits;
+            }
+        }
+        total * fps / (12.0 * f64::from(gops))
+    }
+
+    #[test]
+    fn converges_on_the_target() {
+        // complexities whose target quantiser is inside the allowed range
+        for (ci, cp) in [(4e7, 1e7), (8e7, 2e6), (1e7, 9e6)] {
+            let got = run(ci, cp, 4e6, 20);
+            assert!((got / 4e6 - 1.0).abs() < 0.03, "{ci} {cp}: {got}");
+        }
+    }
+
+    #[test]
+    fn the_quantiser_stays_in_range() {
+        let mut rc = RateCtl::new(1e6, 25.0, (2.0, 62.0));
+        rc.start_gop(2);
+        // a picture far larger than its budget pushes the next quantiser to the top
+        rc.update(true, 50_000_000, 10.0);
+        rc.start_gop(2);
+        assert_eq!(rc.qscale(true), 62.0);
+        // and a tiny one to the bottom
+        let mut rc = RateCtl::new(1e6, 25.0, (2.0, 62.0));
+        rc.start_gop(2);
+        rc.update(true, 10, 2.0);
+        assert_eq!(rc.qscale(true), 2.0);
+    }
+}
diff --git a/crates/video/src/mpeg2/encode/tables.rs b/crates/video/src/mpeg2/encode/tables.rs
new file mode 100644
index 000000000..b79dd92ea
--- /dev/null
+++ b/crates/video/src/mpeg2/encode/tables.rs
@@ -0,0 +1,264 @@
+//! Encoder-side variable-length codes, built from the decoder's code lists (H.262 Annex B) so the
+//! two cannot disagree.
+
+use std::sync::OnceLock;
+
+use crate::mpeg2::vlc::{
+    CBP, DC_CHROMA, DC_LUMA, DCT_EOB, DCT_ESCAPE, DCT_ONE, DCT_ZERO, DCT_ZERO_LONG, MBA, MBA_ESCAPE, MBTYPE_I, MBTYPE_P, MOTION, dct_table,
+    parse_code,
+};
+
+use super::bitwriter::BitWriter;
+
+/// A code: `len` bits of `bits`, most significant first.
+#[derive(Clone, Copy, Default, Debug, PartialEq, Eq)]
+pub(crate) struct Code {
+    pub bits: u32,
+    pub len: u8,
+}
+
+impl Code {
+    fn of(s: &str) -> Code {
+        let (bits, len) = parse_code(s);
+        Code { bits, len: len as u8 }
+    }
+
+    #[inline(always)]
+    pub fn put(self, w: &mut BitWriter) {
+        w.put(self.bits, u32::from(self.len));
+    }
+}
+
+/// Longest run with a table code (table zero and one: run 31 at level 1).
+const MAX_RUN: usize = 31;
+/// Largest level with a table code (run 0: level 40).
+const MAX_LEVEL: usize = 40;
+
+pub(crate) struct EncTables {
+    /// macroblock_address_increment 1..=33 (index 0 unused) and the escape.
+    pub mba: [Code; 34],
+    pub mba_escape: Code,
+    /// macroblock_type by flags: I pictures, P pictures (index: flags, 0..32).
+    pub mbtype_i: [Option<Code>; 32],
+    pub mbtype_p: [Option<Code>; 32],
+    /// coded_block_pattern_420 (the first six blocks).
+    pub cbp: [Code; 64],
+    /// motion_code -16..=16 at index code + 16.
+    pub motion: [Code; 33],
+    pub dc_luma: [Code; 12],
+    pub dc_chroma: [Code; 12],
+    /// DCT coefficients `[table][run][level]` without the sign bit (table 0: B.14, table 1: B.15).
+    pub dct: [Box<[[Option<Code>; MAX_LEVEL + 1]; MAX_RUN + 1]>; 2],
+    pub dct_eob: [Code; 2],
+    pub dct_escape: Code,
+}
+
+fn by_value<const N: usize>(list: &[(&str, i16)], offset: i16) -> [Code; N] {
+    let mut out = [Code::default(); N];
+    for &(s, v) in list {
+        if let Some(slot) = usize::try_from(v + offset).ok().and_then(|i| out.get_mut(i)) {
+            *slot = Code::of(s);
+        }
+    }
+    out
+}
+
+fn mb_types(list: &[(&str, i16)]) -> [Option<Code>; 32] {
+    let mut out = [None; 32];
+    for &(s, v) in list {
+        if let Some(slot) = usize::try_from(v).ok().and_then(|i| out.get_mut(i)) {
+            *slot = Some(Code::of(s));
+        }
+    }
+    out
+}
+
+fn dct(
+    short: &'static [(&'static str, i16)],
+    extra: &'static [(&'static str, i16)],
+) -> (Box<[[Option<Code>; MAX_LEVEL + 1]; MAX_RUN + 1]>, Code, Code) {
+    let mut t = Box::new([[None; MAX_LEVEL + 1]; MAX_RUN + 1]);
+    let (mut eob, mut esc) = (Code::default(), Code::default());
+    for (s, v) in dct_table(short, extra) {
+        match v {
+            DCT_EOB => eob = Code::of(s),
+            DCT_ESCAPE => esc = Code::of(s),
+            v => {
+                let (run, level) = ((v & 63) as usize, (v >> 6) as usize);
+                if let Some(slot) = t.get_mut(run).and_then(|r| r.get_mut(level)) {
+                    *slot = Some(Code::of(s));
+                }
+            }
+        }
+    }
+    (t, eob, esc)
+}
+
+pub(crate) fn enc_tables() -> &'static EncTables {
+    static T: OnceLock<EncTables> = OnceLock::new();
+    T.get_or_init(|| {
+        let (zero, eob0, esc) = dct(DCT_ZERO, DCT_ZERO_LONG);
+        let (one, eob1, _) = dct(DCT_ONE, &[]);
+        let mba_escape = MBA.iter().find(|e| e.1 == MBA_ESCAPE).map_or(Code::default(), |e| Code::of(e.0));
+        EncTables {
+            mba: by_value(MBA, 0),
+            mba_escape,
+            mbtype_i: mb_types(MBTYPE_I),
+            mbtype_p: mb_types(MBTYPE_P),
+            cbp: by_value(CBP, 0),
+            motion: by_value(MOTION, 16),
+            dc_luma: by_value(DC_LUMA, 0),
+            dc_chroma: by_value(DC_CHROMA, 0),
+            dct: [zero, one],
+            dct_eob: [eob0, eob1],
+            dct_escape: esc,
+        }
+    })
+}
+
+impl EncTables {
+    /// One DCT coefficient. `first_inter`: the first coefficient of a non-intra block, where
+    /// run 0 level ±1 is "1s".
+    #[inline]
+    pub fn put_coefficient(&self, w: &mut BitWriter, table: usize, run: usize, level: i32, first_inter: bool) {
+        let mag = level.unsigned_abs() as usize;
+        let neg = level < 0;
+        if first_inter && run == 0 && mag == 1 {
+            w.put(0b10 | neg as u32, 2);
+            return;
+        }
+        if let Some(c) = self.dct[table & 1].get(run).and_then(|r| r.get(mag)).copied().flatten() {
+            c.put(w);
+            w.bit(neg);
+            return;
+        }
+        // escape: 6-bit run, 12-bit two's complement level (-2047..=2047)
+        self.dct_escape.put(w);
+        w.put(run as u32, 6);
+        w.put((level.clamp(-2047, 2047) & 0xFFF) as u32, 12);
+    }
+
+    /// Bits of one motion vector component delta (`delta` already in the wrapped range).
+    #[inline]
+    pub fn motion_bits(&self, delta: i32, f_code: u8) -> u32 {
+        let r_size = u32::from(f_code.saturating_sub(1));
+        if delta == 0 {
+            return u32::from(self.motion[16].len);
+        }
+        let code = ((delta.abs() - 1) >> r_size) + 1;
+        let idx = (16 + code.min(16)) as usize;
+        u32::from(self.motion[idx].len) + r_size
+    }
+
+    /// Write one motion vector component delta (`delta` in the wrapped range).
+    #[inline]
+    pub fn put_motion(&self, w: &mut BitWriter, delta: i32, f_code: u8) {
+        let r_size = u32::from(f_code.saturating_sub(1));
+        if delta == 0 {
+            self.motion[16].put(w);
+            return;
+        }
+        let a = delta.abs() - 1;
+        let code = ((a >> r_size) + 1).min(16);
+        let idx = (16 + code * delta.signum()) as usize;
+        self.motion[idx].put(w);
+        w.put((a & ((1 << r_size) - 1)) as u32, r_size);
+    }
+}
+
+/// `mv - pred` brought into the range a motion code can carry ([-16f, 16f-1], §7.6.3.1).
+#[inline]
+pub(crate) fn wrap_delta(mv: i32, pred: i32, f_code: u8) -> i32 {
+    let f = 1i32 << f_code.saturating_sub(1);
+    let d = mv - pred;
+    if d > 16 * f - 1 {
+        d - 32 * f
+    } else if d < -16 * f {
+        d + 32 * f
+    } else {
+        d
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mpeg2::bits::Bits;
+    use crate::mpeg2::slice::wrap_vector;
+    use crate::mpeg2::vlc::{MB_FWD, MB_INTRA, MB_PATTERN, MB_QUANT, rl, tables};
+
+    /// Macroblock types the encoder sends (frame pictures, frame prediction, no B pictures).
+    const ENC_MB_TYPES: [i16; 7] =
+        [MB_INTRA, MB_INTRA | MB_QUANT, MB_FWD | MB_PATTERN, MB_PATTERN, MB_FWD, MB_QUANT | MB_FWD | MB_PATTERN, MB_QUANT | MB_PATTERN];
+
+    #[test]
+    fn every_code_decodes_to_its_value() {
+        let t = enc_tables();
+        let d = tables();
+        let check = |c: Code, vlc: &crate::mpeg2::vlc::Vlc, v: i16| {
+            let mut w = BitWriter::new();
+            c.put(&mut w);
+            let bytes = w.finish();
+            let mut b = Bits::new(&bytes);
+            assert_eq!(vlc.decode(&mut b), Some(v));
+        };
+        for n in 1..=33 {
+            check(t.mba[n], &d.mba, n as i16);
+        }
+        check(t.mba_escape, &d.mba, MBA_ESCAPE);
+        for v in 0..64 {
+            check(t.cbp[v], &d.cbp, v as i16);
+        }
+        for v in -16..=16i16 {
+            check(t.motion[(v + 16) as usize], &d.motion, v);
+        }
+        for s in 0..12 {
+            check(t.dc_luma[s], &d.dc_luma, s as i16);
+            check(t.dc_chroma[s], &d.dc_chroma, s as i16);
+        }
+        for f in ENC_MB_TYPES {
+            // the I table holds only the intra types
+            if let Some(c) = t.mbtype_i[f as usize] {
+                check(c, &d.mbtype[0], f);
+            }
+            check(t.mbtype_p[f as usize].unwrap_or_default(), &d.mbtype[1], f);
+        }
+        for (k, vlc) in [&d.dct_zero, &d.dct_one].into_iter().enumerate() {
+            for run in 0..=MAX_RUN {
+                for level in 1..=MAX_LEVEL {
+                    if let Some(c) = t.dct[k][run][level] {
+                        check(c, vlc, rl(run as i16, level as i16));
+                    }
+                }
+            }
+            check(t.dct_eob[k], vlc, DCT_EOB);
+        }
+    }
+
+    #[test]
+    fn motion_deltas_round_trip_through_the_decoder_wrap() {
+        let t = enc_tables();
+        let d = tables();
+        for f_code in 1..=4u8 {
+            let f = 1i32 << (f_code - 1);
+            for pred in [-16 * f, -3, 0, 5, 16 * f - 1] {
+                for mv in -16 * f..16 * f {
+                    let delta = wrap_delta(mv, pred, f_code);
+                    let mut w = BitWriter::new();
+                    t.put_motion(&mut w, delta, f_code);
+                    let bits = w.bits() as u32;
+                    assert_eq!(bits, t.motion_bits(delta, f_code));
+                    let bytes = w.finish();
+                    let mut b = Bits::new(&bytes);
+                    // the decoder's reading of motion_code and motion_residual
+                    let code = d.motion.decode(&mut b).unwrap_or(99) as i32;
+                    let r_size = (f_code - 1) as u32;
+                    let residual = if f_code != 1 && code != 0 { b.read(r_size) as i32 } else { 0 };
+                    let dd = if f == 1 || code == 0 { code } else { ((code.abs() - 1) * f + residual + 1) * code.signum() };
+                    assert_eq!(dd, delta);
+                    assert_eq!(wrap_vector(pred, dd, f), mv, "f_code {f_code} pred {pred} mv {mv}");
+                }
+            }
+        }
+    }
+}
diff --git a/crates/video/src/mpeg2/encode/tests.rs b/crates/video/src/mpeg2/encode/tests.rs
new file mode 100644
index 000000000..5352161b3
--- /dev/null
+++ b/crates/video/src/mpeg2/encode/tests.rs
@@ -0,0 +1,250 @@
+//! Encoder tests against this crate's decoder: the decoded pictures must equal the encoder's
+//! reconstruction exactly (any difference would drift along a GOP of P pictures). The ffmpeg
+//! comparison is in `tests/mpeg2/encode.rs`.
+
+use super::*;
+use crate::mpeg2::{Decoder, access_units, probe};
+
+/// A moving, textured test sequence: a gradient with a sharp pattern drifting by a fraction of a
+/// sample per picture, and a block moving across it.
+pub(crate) fn scene(w: usize, h: usize, cw: usize, ch: usize, t: usize) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
+    let tf = t as f32;
+    let mut y = vec![0u8; w * h];
+    for r in 0..h {
+        for c in 0..w {
+            let (x, yy) = (c as f32 + tf * 1.5, r as f32 + tf * 0.75);
+            let v = 60.0
+                + 0.3 * x
+                + 0.2 * yy
+                + 40.0 * ((x * 0.21).sin() * (yy * 0.17).cos())
+                + if ((x as i32 / 8) + (yy as i32 / 8)) % 2 == 0 { 25.0 } else { 0.0 };
+            y[r * w + c] = v.clamp(0.0, 255.0) as u8;
+        }
+    }
+    let (bx, by) = ((t * 3) % w.max(1), (t * 2) % h.max(1));
+    for r in by..(by + 12).min(h) {
+        for c in bx..(bx + 12).min(w) {
+            y[r * w + c] = 230;
+        }
+    }
+    let mut cb = vec![0u8; cw * ch];
+    let mut cr = vec![0u8; cw * ch];
+    for r in 0..ch {
+        for c in 0..cw {
+            cb[r * cw + c] = (128.0 + 50.0 * ((c as f32 + tf) * 0.13).sin()) as u8;
+            cr[r * cw + c] = (128.0 + 40.0 * ((r as f32 - tf) * 0.11).cos()) as u8;
+        }
+    }
+    (y, cb, cr)
+}
+
+/// Encode `frames` pictures of the scene; returns the stream and the reconstruction.
+fn encode(cfg: EncoderConfig, frames: usize) -> (Vec<u8>, Vec<ReconFrame>, Vec<Packet>) {
+    let (w, h) = (cfg.width as usize, cfg.height as usize);
+    let (cw, ch) = (w / 2, if cfg.chroma == ChromaFormat::Yuv422 { h } else { h / 2 });
+    let mut enc = Encoder::new(cfg).unwrap();
+    enc.set_recon_capture(true);
+    let mut es = Vec::new();
+    let mut packets = Vec::new();
+    for t in 0..frames {
+        let (y, cb, cr) = scene(w, h, cw, ch, t);
+        let f = YuvFrame { y: &y, cb: &cb, cr: &cr, y_stride: w, c_stride: cw };
+        for p in enc.encode(&f, t as i64).unwrap() {
+            es.extend_from_slice(&p.data);
+            packets.push(p);
+        }
+    }
+    packets.extend(enc.flush());
+    es.extend_from_slice(enc.end_of_sequence());
+    (es, enc.take_recon(), packets)
+}
+
+fn decode(es: &[u8]) -> Vec<crate::mpeg2::Picture> {
+    let mut d = Decoder::new();
+    let mut out = Vec::new();
+    for (i, r) in access_units(es).into_iter().enumerate() {
+        out.extend(d.decode(&es[r], i as i64).unwrap());
+    }
+    out.extend(d.flush());
+    assert_eq!(d.errors(), 0, "decoder errors: {:?}", d.last_error());
+    out
+}
+
+fn assert_decodes_to_recon(name: &str, cfg: EncoderConfig, frames: usize) -> Vec<Packet> {
+    let (es, recon, packets) = encode(cfg, frames);
+    let pics = decode(&es);
+    assert_eq!(pics.len(), frames, "{name}: picture count");
+    for (i, (p, r)) in pics.iter().zip(&recon).enumerate() {
+        assert_eq!(p.pts, i as i64, "{name}: display order");
+        for (plane, (a, b)) in [("Y", (&p.y, &r.y)), ("Cb", (&p.cb, &r.cb)), ("Cr", (&p.cr, &r.cr))] {
+            let first = a.iter().zip(b.iter()).position(|(x, y)| x != y);
+            assert!(first.is_none() && a.len() == b.len(), "{name}: picture {i} ({:?}) {plane} differs at {first:?}", p.picture_type);
+        }
+    }
+    packets
+}
+
+fn psnr(a: &[u8], b: &[u8]) -> f64 {
+    let sse: f64 = a.iter().zip(b).map(|(x, y)| (f64::from(*x) - f64::from(*y)).powi(2)).sum();
+    10.0 * (255.0f64.powi(2) * a.len() as f64 / sse.max(1e-9)).log10()
+}
+
+#[test]
+fn intra_only_decodes_to_the_reconstruction() {
+    let mut cfg = EncoderConfig::new(64, 48, 25, 1);
+    cfg.gop_size = 1;
+    let packets = assert_decodes_to_recon("intra", cfg, 3);
+    assert!(packets.iter().all(|p| p.keyframe && p.picture_type == PictureType::I));
+}
+
+#[test]
+fn long_p_gop_does_not_drift() {
+    let mut cfg = EncoderConfig::new(96, 64, 25, 1);
+    cfg.gop_size = 30;
+    let packets = assert_decodes_to_recon("long gop", cfg, 30);
+    assert_eq!(packets.iter().filter(|p| p.keyframe).count(), 1);
+    assert!(packets[1..].iter().all(|p| p.picture_type == PictureType::P));
+}
+
+#[test]
+fn every_coding_option_decodes_to_the_reconstruction() {
+    let base = EncoderConfig { gop_size: 6, ..EncoderConfig::new(80, 48, 30000, 1001) };
+    let mut matrix = [0u8; 64];
+    for (i, m) in matrix.iter_mut().enumerate() {
+        *m = (8 + i * 2) as u8;
+    }
+    let cases = [
+        ("422", EncoderConfig { chroma: ChromaFormat::Yuv422, ..base.clone() }),
+        ("linear q", EncoderConfig { nonlinear_quant: false, rate: RateControl::Quantiser(3), ..base.clone() }),
+        ("coarse", EncoderConfig { rate: RateControl::Quantiser(31), ..base.clone() }),
+        ("fine", EncoderConfig { rate: RateControl::Quantiser(1), adaptive_quant: false, ..base.clone() }),
+        ("dc 8 and 10", EncoderConfig { intra_dc_bits: 10, ..base.clone() }),
+        ("dc 8", EncoderConfig { intra_dc_bits: 8, ..base.clone() }),
+        ("matrices", EncoderConfig { intra_matrix: Some(matrix), non_intra_matrix: Some(matrix), ..base.clone() }),
+        ("small range", EncoderConfig { search_range: 3, ..base.clone() }),
+        ("abr", EncoderConfig { rate: RateControl::Abr { kbps: 300 }, ..base.clone() }),
+        ("odd size", EncoderConfig { width: 50, height: 34, ..base.clone() }),
+        ("422 odd size", EncoderConfig { width: 70, height: 30, chroma: ChromaFormat::Yuv422, ..base.clone() }),
+    ];
+    for (name, cfg) in cases {
+        assert_decodes_to_recon(name, cfg, 8);
+    }
+}
+
+#[cfg(feature = "threads")]
+#[test]
+fn threaded_slices_give_the_same_stream() {
+    let cfg = EncoderConfig { gop_size: 5, threads: false, ..EncoderConfig::new(96, 80, 25, 1) };
+    let (a, _, _) = encode(cfg.clone(), 6);
+    let (b, _, _) = encode(EncoderConfig { threads: true, ..cfg }, 6);
+    assert_eq!(a, b);
+}
+
+#[test]
+fn quality_follows_the_quantiser() {
+    let mut last = f64::MAX;
+    let mut last_size = usize::MAX;
+    for q in [1u8, 4, 12, 31] {
+        let cfg = EncoderConfig { rate: RateControl::Quantiser(q), gop_size: 4, ..EncoderConfig::new(96, 64, 25, 1) };
+        let (es, recon, _) = encode(cfg, 4);
+        let p: f64 = recon.iter().enumerate().map(|(t, r)| psnr(&scene(96, 64, 48, 32, t).0, &r.y)).sum::<f64>() / recon.len() as f64;
+        assert!(p < last && es.len() < last_size, "q {q}: {p:.2} dB, {} bytes", es.len());
+        if q == 1 {
+            assert!(p > 45.0, "q 1: {p:.2} dB");
+        }
+        if q == 4 {
+            assert!(p > 36.0, "q 4: {p:.2} dB");
+        }
+        (last, last_size) = (p, es.len());
+    }
+}
+
+#[test]
+fn p_pictures_are_smaller_and_static_content_skips() {
+    let cfg = EncoderConfig { gop_size: 8, ..EncoderConfig::new(128, 64, 25, 1) };
+    let mut enc = Encoder::new(cfg).unwrap();
+    let (y, cb, cr) = scene(128, 64, 64, 32, 0);
+    let f = YuvFrame { y: &y, cb: &cb, cr: &cr, y_stride: 128, c_stride: 64 };
+    let i = enc.encode(&f, 0).unwrap().remove(0);
+    let p1 = enc.encode(&f, 1).unwrap().remove(0);
+    let p2 = enc.encode(&f, 2).unwrap().remove(0);
+    assert_eq!(p1.picture_type, PictureType::P);
+    // the first P picture refines the I picture's reconstruction; the next repeat has almost
+    // nothing left to code and skips (every macroblock but the first and last of a slice)
+    assert!(p1.data.len() * 5 < i.data.len(), "I {} bytes, P {} bytes", i.data.len(), p1.data.len());
+    assert!(p2.data.len() * 20 < i.data.len(), "I {} bytes, second P {} bytes", i.data.len(), p2.data.len());
+}
+
+#[test]
+fn the_sequence_header_describes_the_stream() {
+    let cases = [
+        (EncoderConfig::new(352, 288, 25, 1), 0x4A, "Main@Low"),
+        (EncoderConfig::new(720, 576, 25, 1), 0x48, "Main@Main"),
+        (EncoderConfig::new(1440, 1080, 25, 1), 0x46, "Main@High-1440"),
+        (EncoderConfig::new(1920, 1080, 30000, 1001), 0x44, "Main@High"),
+        (EncoderConfig { chroma: ChromaFormat::Yuv422, ..EncoderConfig::new(720, 608, 25, 1) }, 0x85, "4:2:2@Main"),
+        (EncoderConfig { chroma: ChromaFormat::Yuv422, ..EncoderConfig::new(1920, 1080, 25, 1) }, 0x82, "4:2:2@High"),
+        (EncoderConfig { rate: RateControl::Abr { kbps: 20_000 }, ..EncoderConfig::new(720, 576, 25, 1) }, 0x46, "Main@High-1440"),
+    ];
+    for (cfg, pli, name) in cases {
+        let (w, h, aspect) = (cfg.width, cfg.height, cfg.aspect);
+        let enc = Encoder::new(cfg).unwrap();
+        assert_eq!(enc.profile_and_level(), pli, "{name}");
+        let info = probe(enc.sequence_header()).unwrap();
+        assert_eq!((info.width, info.height, info.mpeg2, info.progressive_sequence, info.low_delay), (w, h, true, true, true));
+        assert_eq!(info.codec_name(), format!("MPEG-2 Video ({name})"));
+        assert_eq!(aspect, AspectRatio::Square);
+        assert_eq!(info.sar, (1, 1));
+    }
+    let enc = Encoder::new(EncoderConfig { aspect: AspectRatio::Dar16x9, ..EncoderConfig::new(720, 576, 30000, 1001) }).unwrap();
+    let info = probe(enc.sequence_header()).unwrap();
+    assert_eq!((info.dar, info.frame_rate), (Some((16, 9)), Some((30000, 1001))));
+}
+
+#[test]
+fn bad_configurations_are_refused() {
+    let ok = EncoderConfig::new(64, 64, 25, 1);
+    let bad = [
+        EncoderConfig { width: 63, ..ok.clone() },
+        EncoderConfig { height: 0, ..ok.clone() },
+        EncoderConfig { width: 3840, height: 2160, ..ok.clone() },
+        EncoderConfig { chroma: ChromaFormat::Yuv444, ..ok.clone() },
+        EncoderConfig { chroma: ChromaFormat::Yuv422, width: 1920, height: 1152, ..ok.clone() },
+        EncoderConfig { fps_num: 26, ..ok.clone() },
+        EncoderConfig { fps_den: 0, ..ok.clone() },
+        EncoderConfig { gop_size: 0, ..ok.clone() },
+        EncoderConfig { gop_size: 1024, ..ok.clone() },
+        EncoderConfig { rate: RateControl::Quantiser(0), ..ok.clone() },
+        EncoderConfig { rate: RateControl::Quantiser(32), ..ok.clone() },
+        EncoderConfig { rate: RateControl::Abr { kbps: 0 }, ..ok.clone() },
+        EncoderConfig { rate: RateControl::Abr { kbps: 90_000 }, ..ok.clone() },
+        EncoderConfig { intra_dc_bits: 11, ..ok.clone() },
+        EncoderConfig { intra_matrix: Some([0; 64]), ..ok.clone() },
+        EncoderConfig { search_range: 0, ..ok.clone() },
+        EncoderConfig { search_range: 64, ..ok.clone() },
+    ];
+    for cfg in bad {
+        let desc = format!("{cfg:?}");
+        assert!(matches!(Encoder::new(cfg), Err(EncodeError::Config(_))), "{desc}");
+    }
+}
+
+#[test]
+fn short_or_inconsistent_planes_are_refused() {
+    let mut enc = Encoder::new(EncoderConfig::new(32, 32, 25, 1)).unwrap();
+    let (y, c) = (vec![0u8; 32 * 32], vec![0u8; 16 * 16]);
+    let ok = YuvFrame { y: &y, cb: &c, cr: &c, y_stride: 32, c_stride: 16 };
+    assert!(enc.encode(&ok, 0).is_ok());
+    let bad = [
+        YuvFrame { y: &y[..32 * 31], ..ok },
+        YuvFrame { cb: &c[..10], ..ok },
+        YuvFrame { y_stride: 31, ..ok },
+        YuvFrame { c_stride: usize::MAX, ..ok },
+        YuvFrame { y_stride: usize::MAX / 2, ..ok },
+    ];
+    for f in bad {
+        assert!(matches!(enc.encode(&f, 1), Err(EncodeError::BadFrame(_))));
+    }
+    // a refused frame leaves the encoder usable
+    assert_eq!(enc.encode(&ok, 1).unwrap()[0].picture_type, PictureType::P);
+}
diff --git a/crates/video/src/mpeg2/encode/transform.rs b/crates/video/src/mpeg2/encode/transform.rs
new file mode 100644
index 000000000..d3a6ce4d3
--- /dev/null
+++ b/crates/video/src/mpeg2/encode/transform.rs
@@ -0,0 +1,122 @@
+//! Forward DCT, quantisation and the decoder-exact reconstruction of one block.
+
+use crate::mpeg2::idct::{basis, idct};
+use crate::mpeg2::slice::dequant_mpeg2;
+
+/// Forward 8×8 DCT of `p` (raster order), the transpose of the decoder's IDCT basis:
+/// `F[v][u] = Σ_y Σ_x M[x][u] M[y][v] p[y][x]`, so a flat block of value `a` has `F[0][0] = 8a`.
+pub(crate) fn fdct(p: &[i32; 64]) -> [f32; 64] {
+    let m = basis();
+    let mut t = [0f32; 64];
+    for y in 0..8 {
+        let row: [f32; 8] = std::array::from_fn(|x| p[y * 8 + x] as f32);
+        for u in 0..8 {
+            let mut s = 0f32;
+            for x in 0..8 {
+                s += m[x][u] * row[x];
+            }
+            t[y * 8 + u] = s;
+        }
+    }
+    let mut out = [0f32; 64];
+    for v in 0..8 {
+        for u in 0..8 {
+            let mut s = 0f32;
+            for y in 0..8 {
+                s += m[y][v] * t[y * 8 + u];
+            }
+            out[v * 8 + u] = s;
+        }
+    }
+    out
+}
+
+/// Rounding offset of intra AC quantisation (in units of the quantiser step): below one half,
+/// a small dead zone.
+const INTRA_ROUND: f32 = 0.375;
+
+/// Quantise intra AC coefficient `f` with weight `w` and quantiser_scale `qs` (inverse of
+/// `F = 2·QF·w·qs / 32`).
+#[inline]
+pub(crate) fn quant_intra(f: f32, w: u8, qs: i32) -> i32 {
+    let y = 16.0 * f.abs() / (f32::from(w) * qs as f32);
+    let q = ((y + INTRA_ROUND).floor() as i32).min(2047);
+    if f < 0.0 { -q } else { q }
+}
+
+/// Quantise non-intra coefficient `f` (inverse of `F = (2·QF + sign)·w·qs / 32`): truncation,
+/// which leaves the usual wide dead zone around zero.
+#[inline]
+pub(crate) fn quant_inter(f: f32, w: u8, qs: i32) -> i32 {
+    let y = 16.0 * f.abs() / (f32::from(w) * qs as f32);
+    let q = (y.floor() as i32).min(2047);
+    if f < 0.0 { -q } else { q }
+}
+
+/// Reconstruct a block as the decoder does: dequantise `levels` (raster order; for intra blocks
+/// `levels[0]` is the quantised DC), mismatch control, IDCT. Returns the residual (inter) or
+/// the samples before clamping (intra).
+pub(crate) fn reconstruct(levels: &[i32; 64], matrix: &[u8; 64], qs: i32, intra: bool, dc_mult: i32) -> [i32; 64] {
+    let mut blk = [0i32; 64];
+    let mut sum = 0i32;
+    for (i, &l) in levels.iter().enumerate() {
+        if l == 0 {
+            continue;
+        }
+        let v = if intra && i == 0 { l * dc_mult } else { dequant_mpeg2(l, qs, i32::from(matrix[i]), intra) };
+        blk[i] = v;
+        sum += v;
+    }
+    if sum & 1 == 0 {
+        blk[63] ^= 1;
+    }
+    let dc_only = blk[1..].iter().all(|&v| v == 0);
+    idct(&mut blk, dc_only);
+    blk
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn flat_block_has_only_dc() {
+        let f = fdct(&[100; 64]);
+        assert!((f[0] - 800.0).abs() < 0.01);
+        assert!(f[1..].iter().all(|v| v.abs() < 0.01));
+    }
+
+    #[test]
+    fn forward_then_inverse_is_close() {
+        let p: [i32; 64] = std::array::from_fn(|i| ((i * 37 + i / 8 * 11) % 200) as i32 - 60);
+        let f = fdct(&p);
+        let mut b: [i32; 64] = std::array::from_fn(|i| f[i].round() as i32);
+        idct(&mut b, false);
+        for i in 0..64 {
+            assert!((b[i] - p[i]).abs() <= 1, "{i}: {} vs {}", b[i], p[i]);
+        }
+    }
+
+    #[test]
+    fn quantisers_invert_the_dequantiser() {
+        for qs in [1, 2, 8, 31, 62, 112] {
+            for w in [8u8, 16, 40, 83] {
+                // only where the dequantiser's integer division is exact
+                if (i32::from(w) * qs) % 32 != 0 {
+                    continue;
+                }
+                for level in [-40, -3, -1, 1, 2, 17] {
+                    let f = dequant_mpeg2(level, qs, i32::from(w), true) as f32;
+                    // without the clamp the intra quantiser returns the level it came from
+                    if f.abs() < 2047.0 {
+                        assert_eq!(quant_intra(f, w, qs), level, "intra qs {qs} w {w}");
+                    }
+                    let f = dequant_mpeg2(level, qs, i32::from(w), false) as f32;
+                    if f.abs() < 2047.0 {
+                        assert_eq!(quant_inter(f, w, qs), level, "inter qs {qs} w {w}");
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/crates/video/src/mpeg2/idct.rs b/crates/video/src/mpeg2/idct.rs
index f94b935f0..3828d05a6 100644
--- a/crates/video/src/mpeg2/idct.rs
+++ b/crates/video/src/mpeg2/idct.rs
@@ -6,7 +6,7 @@
 use std::sync::OnceLock;
 
 /// `M[x][u] = C(u)/2 · cos((2x+1)uπ/16)`, `C(0) = 1/√2`, `C(u>0) = 1`.
-fn basis() -> &'static [[f32; 8]; 8] {
+pub(crate) fn basis() -> &'static [[f32; 8]; 8] {
     static B: OnceLock<[[f32; 8]; 8]> = OnceLock::new();
     B.get_or_init(|| {
         let mut m = [[0f32; 8]; 8];
diff --git a/crates/video/src/mpeg2/mod.rs b/crates/video/src/mpeg2/mod.rs
index 5d88ea4e5..ae2bb1682 100644
--- a/crates/video/src/mpeg2/mod.rs
+++ b/crates/video/src/mpeg2/mod.rs
@@ -1,5 +1,6 @@
 //! Clean-room MPEG-2 video (ITU-T H.262 | ISO/IEC 13818-2) and MPEG-1 video (ISO/IEC 11172-2)
-//! decoder.
+//! decoder, and the start of an MPEG-2 encoder ([`encode`], feature `mpeg2-encode`: I and P
+//! pictures).
 //!
 //! - Main Profile at Low/Main/High-1440/High Level, 4:2:2 Profile (XDCAM HD422, IMX / D-10),
 //!   Simple Profile, and MPEG-1 (including D pictures and constrained-parameters streams).
@@ -26,12 +27,17 @@
 #![allow(clippy::needless_range_loop, clippy::type_complexity)]
 
 mod bits;
+#[cfg(feature = "mpeg2-encode")]
+pub mod encode;
 pub mod headers;
 mod idct;
 mod mc;
 mod slice;
 mod vlc;
 
+#[cfg(feature = "mpeg2-encode")]
+pub use encode::{AspectRatio, EncodeError, Encoder, EncoderConfig, Packet, RateControl, ReconFrame, YuvFrame};
+
 use std::sync::Arc;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
diff --git a/crates/video/src/mpeg2/slice.rs b/crates/video/src/mpeg2/slice.rs
index f7a6389f0..706439af4 100644
--- a/crates/video/src/mpeg2/slice.rs
+++ b/crates/video/src/mpeg2/slice.rs
@@ -519,8 +519,7 @@ pub(crate) fn wrap_vector(pred: i32, delta: i32, f: i32) -> i32 {
 #[inline(always)]
 fn dequant(p: &PicParams, level: i32, qs: i32, w: i32, intra: bool) -> i32 {
     if p.mpeg2 {
-        let k = if intra { 0 } else { level.signum() };
-        ((2 * level + k) * w * qs / 32).clamp(-2048, 2047)
+        dequant_mpeg2(level, qs, w, intra)
     } else {
         let mut v = if intra { 2 * level * qs * w / 16 } else { (2 * level + level.signum()) * qs * w / 16 };
         if v & 1 == 0 {
@@ -530,6 +529,14 @@ fn dequant(p: &PicParams, level: i32, qs: i32, w: i32, intra: bool) -> i32 {
     }
 }
 
+/// MPEG-2 inverse quantisation of one AC (or non-intra) coefficient (§7.4.2.3), saturated
+/// (§7.4.3). Shared with the encoder, whose reconstruction must match the decoder exactly.
+#[inline(always)]
+pub(crate) fn dequant_mpeg2(level: i32, qs: i32, w: i32, intra: bool) -> i32 {
+    let k = if intra { 0 } else { level.signum() };
+    ((2 * level + k) * w * qs / 32).clamp(-2048, 2047)
+}
+
 /// The reference field (or frame) for direction `s` and field `sel` (field prediction).
 fn reference<'a>(p: &PicParams<'a>, s: usize, sel: usize) -> Option<&'a Frame> {
     if s == 1 {
diff --git a/crates/video/src/mpeg2/vlc.rs b/crates/video/src/mpeg2/vlc.rs
index 192f86be0..3f8015bb5 100644
--- a/crates/video/src/mpeg2/vlc.rs
+++ b/crates/video/src/mpeg2/vlc.rs
@@ -22,7 +22,7 @@ pub(crate) struct Vlc {
     table: Vec<Entry>,
 }
 
-fn parse_code(s: &str) -> (u32, u32) {
+pub(crate) fn parse_code(s: &str) -> (u32, u32) {
     let mut v = 0u32;
     let mut n = 0u32;
     for c in s.chars() {
diff --git a/crates/video/tests/h264_encode/pinned_decisions.rs b/crates/video/tests/h264_encode/pinned_decisions.rs
index cccb6dac7..c547b54ff 100644
--- a/crates/video/tests/h264_encode/pinned_decisions.rs
+++ b/crates/video/tests/h264_encode/pinned_decisions.rs
@@ -7,8 +7,12 @@ use craft_video::h264::*;
 
 /// FNV-1a over the slice NAL units of `n` frames of [`synth`] encoded with `c`.
 fn slices_hash(c: EncoderConfig, n: usize) -> u64 {
+    slices_hash_with_starts(c, n, MotionSearchStarts::Extended)
+}
+
+fn slices_hash_with_starts(c: EncoderConfig, n: usize, starts: MotionSearchStarts) -> u64 {
     let (w, h) = (c.width as usize, c.height as usize);
-    let mut enc = Encoder::new(c).unwrap();
+    let mut enc = Encoder::new_with_motion_search_starts(c, starts).unwrap();
     let mut stream = Vec::new();
     for t in 0..n {
         let f = synth(w, h, t);
@@ -61,3 +65,27 @@ fn coded_slices_are_pinned() {
         assert_eq!(*got, *want, "{name}: the coded slices changed");
     }
 }
+
+#[test]
+fn filmcraft_writer_keeps_shared_search_decisions_pinned() {
+    let cases = [
+        ("high balanced crf", cfg(Profile::High, Preset::Balanced, RateControl::Crf(23.0)), 0x6223_db82_41eb_7da1u64),
+        ("high quality vbr", cfg(Profile::High, Preset::Quality, RateControl::Vbr { target_kbps: 800, max_kbps: 1200 }), 0x721d_6e68_3f96_5bf1),
+        ("main speed qp", cfg(Profile::Main, Preset::Speed, RateControl::Qp(30)), 0x7772_91d5_4c75_c320),
+        ("baseline balanced cbr", cfg(Profile::Baseline, Preset::Balanced, RateControl::Cbr { kbps: 600 }), 0x72ff_5e78_a3f0_e46e),
+    ];
+    let got: Vec<u64> = cases
+        .iter()
+        .map(|(_, c, _)| {
+            let mut c = c.clone();
+            c.writer = "filmcraft-h264enc 0.20.1".into();
+            slices_hash_with_starts(c, 20, MotionSearchStarts::SeedAndNeighbour)
+        })
+        .collect();
+    for ((name, _, _), got) in cases.iter().zip(&got) {
+        eprintln!("FilmCraft {name}: {got:#018x}");
+    }
+    for ((name, _, want), got) in cases.iter().zip(&got) {
+        assert_eq!(*got, *want, "{name}: FilmCraft's coded slices changed");
+    }
+}
diff --git a/crates/video/tests/mpeg2/encode.rs b/crates/video/tests/mpeg2/encode.rs
new file mode 100644
index 000000000..5cb2377dc
--- /dev/null
+++ b/crates/video/tests/mpeg2/encode.rs
@@ -0,0 +1,206 @@
+//! The MPEG-2 encoder against ffmpeg as an external decoder: ffmpeg must decode our streams
+//! without errors, to within the decoder suite's tolerance of the encoder's own reconstruction
+//! (ffmpeg's integer IDCT differs from ours), and report the profile, level and picture types
+//! we signal. Source pictures come from ffmpeg's `testsrc2`.
+
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+use craft_video::mpeg2::{ChromaFormat, Encoder, EncoderConfig, RateControl, ReconFrame, YuvFrame};
+
+use crate::common::{Stats, fixture_dir, pix_fmt_of};
+use crate::oracle::{MAX_DIFFERING, MIN_PSNR, TOL_MAX};
+
+/// Raw source frames from ffmpeg's `testsrc2`.
+fn source(ff: &Path, w: u32, h: u32, frames: usize, pix_fmt: &str) -> Vec<u8> {
+    let o = Command::new(ff)
+        .args([
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-f",
+            "lavfi",
+            "-i",
+            &format!("testsrc2=size={w}x{h}:rate=25"),
+            "-frames:v",
+            &frames.to_string(),
+        ])
+        .args(["-pix_fmt", pix_fmt, "-f", "rawvideo", "-"])
+        .stdin(Stdio::null())
+        .output()
+        .expect("run ffmpeg");
+    assert!(o.status.success(), "ffmpeg: {}", String::from_utf8_lossy(&o.stderr));
+    o.stdout
+}
+
+fn sizes(cfg: &EncoderConfig) -> (usize, usize, usize) {
+    let (w, h) = (cfg.width as usize, cfg.height as usize);
+    let ch = if cfg.chroma == ChromaFormat::Yuv422 { h } else { h / 2 };
+    (w * h, w / 2 * ch, w / 2)
+}
+
+/// Encode `raw` frames; returns the elementary stream and the reconstruction.
+fn encode(cfg: &EncoderConfig, raw: &[u8]) -> (Vec<u8>, Vec<ReconFrame>) {
+    let (ys, cs, cw) = sizes(cfg);
+    let fsize = ys + 2 * cs;
+    let mut enc = Encoder::new(cfg.clone()).expect("config");
+    enc.set_recon_capture(true);
+    let mut es = Vec::new();
+    for (i, f) in raw.chunks_exact(fsize).enumerate() {
+        let frame = YuvFrame { y: &f[..ys], cb: &f[ys..ys + cs], cr: &f[ys + cs..], y_stride: cfg.width as usize, c_stride: cw };
+        for p in enc.encode(&frame, i as i64).expect("encode") {
+            es.extend_from_slice(&p.data);
+        }
+    }
+    for p in enc.flush() {
+        es.extend_from_slice(&p.data);
+    }
+    es.extend_from_slice(enc.end_of_sequence());
+    (es, enc.take_recon())
+}
+
+/// ffmpeg's decode of `file`, failing on any decoding error.
+fn ffmpeg_decode(ff: &Path, file: &Path, pix_fmt: &str) -> Vec<u8> {
+    let o = Command::new(ff)
+        .args(["-hide_banner", "-loglevel", "error", "-xerror", "-err_detect", "explode", "-i"])
+        .arg(file)
+        .args(["-fps_mode", "passthrough", "-f", "rawvideo", "-pix_fmt", pix_fmt, "-"])
+        .stdin(Stdio::null())
+        .output()
+        .expect("run ffmpeg");
+    assert!(o.status.success() && o.stderr.is_empty(), "ffmpeg rejects {}: {}", file.display(), String::from_utf8_lossy(&o.stderr));
+    o.stdout
+}
+
+/// ffprobe's stream description and per-frame picture types.
+fn ffprobe(file: &Path) -> Option<(String, Vec<String>)> {
+    let fp = craft_media_testkit::ffprobe()?;
+    let stream = Command::new(&fp)
+        .args(["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=codec_name,profile,level,pix_fmt", "-of", "default=nw=1"])
+        .arg(file)
+        .output()
+        .ok()?;
+    let frames = Command::new(&fp)
+        .args(["-v", "error", "-select_streams", "v:0", "-show_entries", "frame=pict_type", "-of", "csv=p=0"])
+        .arg(file)
+        .output()
+        .ok()?;
+    let types = String::from_utf8_lossy(&frames.stdout).lines().map(|l| l.trim_end_matches(',').to_string()).filter(|l| !l.is_empty()).collect();
+    // "codec_name=…\nprofile=…" in ffprobe's order → "codec,profile,level,pix_fmt"
+    let text = String::from_utf8_lossy(&stream.stdout).to_string();
+    let field = |k: &str| text.lines().find_map(|l| l.strip_prefix(&format!("{k}="))).unwrap_or("").to_string();
+    Some((["codec_name", "profile", "level", "pix_fmt"].map(field).join(","), types))
+}
+
+fn write(name: &str, es: &[u8]) -> PathBuf {
+    let path = fixture_dir().join(format!("enc_{name}.m2v"));
+    std::fs::write(&path, es).expect("write stream");
+    path
+}
+
+fn psnr_y(recon: &[ReconFrame], raw: &[u8], ys: usize, fsize: usize) -> f64 {
+    let mut s = Stats::default();
+    for (r, f) in recon.iter().zip(raw.chunks_exact(fsize)) {
+        s.add(&r.y, &f[..ys]);
+    }
+    s.psnr()
+}
+
+struct Case {
+    name: &'static str,
+    cfg: EncoderConfig,
+    frames: usize,
+    /// ffprobe's "codec,profile,level,pix_fmt".
+    probe: &'static str,
+    /// Lowest luma PSNR against the source.
+    min_psnr: f64,
+}
+
+fn check(ff: &Path, c: &Case) -> (Vec<u8>, f64) {
+    let pix_fmt = pix_fmt_of(c.cfg.chroma);
+    let raw = source(ff, c.cfg.width, c.cfg.height, c.frames, pix_fmt);
+    let (ys, cs, _) = sizes(&c.cfg);
+    let fsize = ys + 2 * cs;
+    let (es, recon) = encode(&c.cfg, &raw);
+    let path = write(c.name, &es);
+    let decoded = ffmpeg_decode(ff, &path, pix_fmt);
+    assert_eq!(decoded.len(), c.frames * fsize, "{}: ffmpeg's frame count", c.name);
+    let mut all = Stats::default();
+    for (i, (r, f)) in recon.iter().zip(decoded.chunks_exact(fsize)).enumerate() {
+        let mut s = Stats::default();
+        s.add(&r.y, &f[..ys]);
+        s.add(&r.cb, &f[ys..ys + cs]);
+        s.add(&r.cr, &f[ys + cs..]);
+        assert!(s.max <= TOL_MAX && s.psnr() >= MIN_PSNR, "{} frame {i}: max {} psnr {:.2} against ffmpeg", c.name, s.max, s.psnr());
+        all.merge(&s);
+    }
+    assert!((all.diff as f64) / (all.n as f64) <= MAX_DIFFERING, "{}: {} of {} samples differ from ffmpeg", c.name, all.diff, all.n);
+    let quality = psnr_y(&recon, &raw, ys, fsize);
+    assert!(quality >= c.min_psnr, "{}: luma PSNR {quality:.2} dB against the source", c.name);
+    if let Some((stream, types)) = ffprobe(&path) {
+        assert_eq!(stream, c.probe, "{}: ffprobe", c.name);
+        let gop = c.cfg.gop_size as usize;
+        let want: Vec<&str> = (0..c.frames).map(|i| if i % gop == 0 { "I" } else { "P" }).collect();
+        assert_eq!(types, want, "{}: picture types", c.name);
+    }
+    let kbps = es.len() as f64 * 8.0 * 25.0 / c.frames as f64 / 1000.0;
+    println!(
+        "{}: {} frames, {kbps:.0} kbit/s, luma PSNR {quality:.2} dB, max diff to ffmpeg {}, {:.3}% differ",
+        c.name,
+        c.frames,
+        all.max,
+        100.0 * all.diff as f64 / all.n as f64
+    );
+    (es, kbps)
+}
+
+#[test]
+fn ffmpeg_decodes_our_streams() {
+    let Some(ff) = craft_media_testkit::ffmpeg_or_skip("mpeg2 encoder oracle") else { return };
+    let cif = EncoderConfig { gop_size: 12, ..EncoderConfig::new(352, 288, 25, 1) };
+    let cases = [
+        Case { name: "cif_q4", cfg: cif.clone(), frames: 25, probe: "mpeg2video,Main,10,yuv420p", min_psnr: 36.0 },
+        Case {
+            name: "cif_intra",
+            cfg: EncoderConfig { gop_size: 1, rate: RateControl::Quantiser(8), ..cif.clone() },
+            frames: 6,
+            probe: "mpeg2video,Main,10,yuv420p",
+            min_psnr: 32.0,
+        },
+        Case {
+            name: "cif_linear_coarse",
+            cfg: EncoderConfig { nonlinear_quant: false, adaptive_quant: false, rate: RateControl::Quantiser(20), gop_size: 15, ..cif.clone() },
+            frames: 20,
+            probe: "mpeg2video,Main,10,yuv420p",
+            min_psnr: 26.0,
+        },
+        Case {
+            name: "sd_422",
+            cfg: EncoderConfig { chroma: ChromaFormat::Yuv422, intra_dc_bits: 10, ..EncoderConfig::new(720, 576, 25, 1) },
+            frames: 8,
+            // 4:2:2@Main is indication 0x85; ffprobe prints its low four bits as the level
+            probe: "mpeg2video,4:2:2,5,yuv422p",
+            min_psnr: 36.0,
+        },
+    ];
+    for c in &cases {
+        check(&ff, c);
+    }
+}
+
+#[test]
+fn average_bitrate_reaches_its_target() {
+    let Some(ff) = craft_media_testkit::ffmpeg_or_skip("mpeg2 encoder bitrate") else { return };
+    for kbps in [800u32, 2500] {
+        let c = Case {
+            name: if kbps == 800 { "cif_abr_800" } else { "cif_abr_2500" },
+            cfg: EncoderConfig { rate: RateControl::Abr { kbps }, gop_size: 12, ..EncoderConfig::new(352, 288, 25, 1) },
+            frames: 72,
+            probe: "mpeg2video,Main,10,yuv420p",
+            min_psnr: 26.0,
+        };
+        let (_, got) = check(&ff, &c);
+        let err = got / f64::from(kbps) - 1.0;
+        assert!(err.abs() < 0.10, "{kbps} kbit/s target: got {got:.0} kbit/s ({:+.1}%)", 100.0 * err);
+    }
+}
diff --git a/crates/video/tests/mpeg2/main.rs b/crates/video/tests/mpeg2/main.rs
index 1864b4a22..acbbf662e 100644
--- a/crates/video/tests/mpeg2/main.rs
+++ b/crates/video/tests/mpeg2/main.rs
@@ -1,4 +1,6 @@
 mod common;
+#[cfg(feature = "mpeg2-encode")]
+mod encode;
 mod fuzz_hostile;
 mod hostile_dims;
 mod oracle;
diff --git a/crates/video/tests/mpeg4_encode/main.rs b/crates/video/tests/mpeg4_encode/main.rs
index 0b53c5caf..8185acbc0 100644
--- a/crates/video/tests/mpeg4_encode/main.rs
+++ b/crates/video/tests/mpeg4_encode/main.rs
@@ -322,3 +322,37 @@ fn extreme_content_at_the_finest_quantiser() {
         assert!(d >= 45.0, "frame {i}: {d:.1} dB from the reconstruction");
     }
 }
+
+/// The encoder's packets in an AVI (the track description through `VideoSpec::for_codec`) decode
+/// in ffmpeg to exactly what the raw stream decodes to. Tagged `XVID` they would not: ffmpeg then
+/// decodes with Xvid's IDCT.
+#[test]
+fn packets_play_from_an_avi_file() {
+    use craft_media::avi::{AviWriter, MuxOptions, StreamSpec, VideoSpec};
+    let Some(ff) = ffmpeg() else { return };
+    let mut cfg = EncoderConfig::new(160, 96, 25, 1);
+    cfg.keyint = 10;
+    let Encoded { enc, packets, .. } = encode(cfg, 30);
+    let spec = VideoSpec::for_codec(&enc.codec_params(), 25, 1).expect("an AVI FourCC for MPEG-4 Part 2");
+    assert_eq!(spec.format.compression, *b"FMP4");
+    let mut w = AviWriter::new(std::io::Cursor::new(Vec::new()), vec![StreamSpec::Video(spec)], MuxOptions::default()).expect("writer");
+    for p in &packets {
+        w.write_chunk(0, &p.data, p.keyframe).expect("chunk");
+    }
+    let avi = w.finish().expect("finish").into_inner();
+    let dir = out_dir("avi");
+    let (avi_path, es_path) = (dir.join("stream.avi"), dir.join("stream.m4v"));
+    std::fs::write(&avi_path, avi).expect("write avi");
+    write_stream(&es_path, &packets);
+    let (_, want) = ffmpeg_decode(&ff, &es_path);
+    let out = Command::new(&ff)
+        .args(["-hide_banner", "-nostdin", "-v", "warning", "-i"])
+        .arg(&avi_path)
+        .args(["-f", "rawvideo", "-pix_fmt", "yuv420p", "-"])
+        .output()
+        .expect("run ffmpeg");
+    let diag = String::from_utf8_lossy(&out.stderr);
+    assert!(out.status.success() && diag.trim().is_empty(), "{diag}");
+    assert_eq!(out.stdout.len(), 160 * 96 * 3 / 2 * 30);
+    assert!(out.stdout == want, "the AVI decodes differently from the raw stream");
+}
diff --git a/crates/webp/src/frames.rs b/crates/webp/src/frames.rs
index 8fa89962b..e97118482 100644
--- a/crates/webp/src/frames.rs
+++ b/crates/webp/src/frames.rs
@@ -24,7 +24,9 @@ pub struct FrameLimits {
     pub max_frames: usize,
     /// Most bytes of kept pictures (4 bytes a pixel each). Default 1 GiB.
     pub max_bytes: u64,
-    /// Largest canvas (logical screen) in bytes at 4 bytes a pixel. Default 512 MiB.
+    /// Largest canvas (logical screen) in bytes at 4 bytes a pixel. Default 512 MiB. This is a
+    /// pre-decode canvas check; image 0.25.10's WebP decoder does not enforce its working-buffer
+    /// allocations through the `ImageDecoder::set_limits` hook.
     pub max_canvas_bytes: u64,
     /// Merge a frame identical to the one before into it (its delay added). Default off.
     pub merge_identical: bool,
@@ -98,10 +100,7 @@ pub fn read_frames(bytes: &[u8], limits: &FrameLimits) -> Result<Animation, Fram
         return Err(FrameError::LimitExceeded(format!("a {}x{} canvas is over {} bytes", info.width, info.height, limits.max_canvas_bytes)));
     }
     let malformed = |e: image::ImageError| FrameError::Malformed(e.to_string());
-    let mut decoder = WebPDecoder::new(Cursor::new(bytes)).map_err(malformed)?;
-    let mut il = image::Limits::default();
-    il.max_alloc = Some(limits.max_canvas_bytes.saturating_mul(2));
-    decoder.set_limits(il).map_err(malformed)?;
+    let decoder = WebPDecoder::new(Cursor::new(bytes)).map_err(malformed)?;
     let (width, height) = decoder.dimensions();
     if !decoder.has_animation() {
         let mut rgba = vec![0u8; usize::try_from(canvas).map_err(|_| FrameError::LimitExceeded("canvas".into()))?];
diff --git a/crates/xfl/Cargo.toml b/crates/xfl/Cargo.toml
new file mode 100644
index 000000000..ddf2b3a36
--- /dev/null
+++ b/crates/xfl/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "craft-xfl"
+description = "Bounded XFL/FLA package reader and native shape-edge parser."
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+miniz_oxide = "0.8"
+thiserror = { workspace = true }
diff --git a/crates/xfl/src/edges.rs b/crates/xfl/src/edges.rs
new file mode 100644
index 000000000..e58602e9d
--- /dev/null
+++ b/crates/xfl/src/edges.rs
@@ -0,0 +1,152 @@
+//! XFL's compact shape-edge attribute grammar.
+//!
+//! An edge's `edges` attribute uses twips (1/20 pixel): `!x y` moves, `|x y` and `/x y` draw a
+//! line, `[cx cy x y` and `]cx cy x y` draw a quadratic curve, and `Sn` marks selection state.
+//! Coordinates may be decimal or signed 24.8 fixed-point hexadecimal (`#A.8` is 10.5).
+//!
+//! This module returns neutral points and segments so consumers can map them to their own
+//! geometry model. Like Animate files in the wild, a damaged suffix ends parsing while keeping
+//! the valid prefix. The segment cap bounds output allocation.
+
+/// Most segments parsed from one edge attribute.
+pub const MAX_EDGE_SEGMENTS: usize = 2_000_000;
+
+/// A point in XFL's edge geometry, expressed in pixels after twips conversion.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct Point {
+    pub x: f32,
+    pub y: f32,
+}
+
+/// One line (`control` is absent) or quadratic curve segment.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct Segment {
+    pub from: Point,
+    pub control: Option<Point>,
+    pub to: Point,
+}
+
+const TWIPS_PER_PIXEL: f32 = 20.0;
+
+fn number(input: &[u8], at: &mut usize) -> Option<f32> {
+    while input.get(*at).is_some_and(|b| b.is_ascii_whitespace()) {
+        *at += 1;
+    }
+    let start = *at;
+    if input.get(*at) == Some(&b'#') {
+        *at += 1;
+        let integer_start = *at;
+        while input.get(*at).is_some_and(u8::is_ascii_hexdigit) {
+            *at += 1;
+        }
+        let integer = std::str::from_utf8(input.get(integer_start..*at)?).ok()?;
+        let mut fraction = 0_u32;
+        if input.get(*at) == Some(&b'.') {
+            *at += 1;
+            let fraction_start = *at;
+            while input.get(*at).is_some_and(u8::is_ascii_hexdigit) && *at - fraction_start < 2 {
+                *at += 1;
+            }
+            let digits = std::str::from_utf8(input.get(fraction_start..*at)?).ok()?;
+            // A single hex digit is the high nibble of the 8-bit fractional part.
+            fraction = u32::from_str_radix(digits, 16).ok()? << if digits.len() == 1 { 4 } else { 0 };
+        }
+        let whole = u32::from_str_radix(if integer.is_empty() { "0" } else { integer }, 16).ok()?;
+        let fixed = whole.wrapping_shl(8) | fraction;
+        return Some((fixed as i32) as f32 / 256.0);
+    }
+    if matches!(input.get(*at), Some(b'-' | b'+')) {
+        *at += 1;
+    }
+    while input.get(*at).is_some_and(|b| b.is_ascii_digit() || matches!(b, b'.' | b'e' | b'E')) {
+        *at += 1;
+    }
+    std::str::from_utf8(input.get(start..*at)?).ok()?.parse::<f32>().ok().filter(|v| v.is_finite())
+}
+
+fn point(input: &[u8], at: &mut usize) -> Option<Point> {
+    Some(Point { x: number(input, at)? / TWIPS_PER_PIXEL, y: number(input, at)? / TWIPS_PER_PIXEL })
+}
+
+/// Parses an XFL `<Edge edges="…">` attribute into pixel-coordinate line and quadratic segments.
+///
+/// Stops at the first unknown or malformed command, preserving the valid prefix. The current
+/// point starts at the origin. Move and selection commands do not produce segments.
+pub fn parse_edge_segments(source: &str) -> Vec<Segment> {
+    let input = source.as_bytes();
+    let mut at = 0;
+    let mut current = Point::default();
+    let mut segments = Vec::new();
+    while let Some(&command) = input.get(at) {
+        at += 1;
+        match command {
+            b'!' => match point(input, &mut at) {
+                Some(p) => current = p,
+                None => break,
+            },
+            b'|' | b'/' => match point(input, &mut at) {
+                Some(to) => {
+                    segments.push(Segment { from: current, control: None, to });
+                    current = to;
+                }
+                None => break,
+            },
+            b'[' | b']' => match (point(input, &mut at), point(input, &mut at)) {
+                (Some(control), Some(to)) => {
+                    segments.push(Segment { from: current, control: Some(control), to });
+                    current = to;
+                }
+                _ => break,
+            },
+            b'S' => {
+                while input.get(at).is_some_and(u8::is_ascii_digit) {
+                    at += 1;
+                }
+            }
+            b if b.is_ascii_whitespace() => {}
+            _ => break,
+        }
+        if segments.len() >= MAX_EDGE_SEGMENTS {
+            break;
+        }
+    }
+    segments
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_line_quadratic_and_twips() {
+        let segments = parse_edge_segments("!0 0|200 0[400 0 400 200S2/0 200");
+        assert_eq!(segments.len(), 3);
+        assert_eq!(segments[0].to, Point { x: 10.0, y: 0.0 });
+        assert_eq!(segments[1].control, Some(Point { x: 20.0, y: 0.0 }));
+        assert_eq!(segments[2], Segment { from: Point { x: 20.0, y: 10.0 }, control: None, to: Point { x: 0.0, y: 10.0 } });
+    }
+
+    #[test]
+    fn parses_signed_24_8_fixed_hex_coordinates() {
+        let segments = parse_edge_segments("!#A.8 -20|#FFFFFF.80 0");
+        assert_eq!(segments.len(), 1);
+        assert_eq!(segments[0].from, Point { x: 0.525, y: -1.0 });
+        assert_eq!(segments[0].to, Point { x: -0.025, y: 0.0 });
+    }
+
+    #[test]
+    fn malformed_suffix_keeps_only_valid_prefix() {
+        let segments = parse_edge_segments("!0 0|200 0[400 0 nope 200");
+        assert_eq!(segments, [Segment { from: Point::default(), control: None, to: Point { x: 10.0, y: 0.0 } }]);
+        assert!(parse_edge_segments("!1 2|x").is_empty());
+        assert!(parse_edge_segments("!NaN 2|5 5").is_empty());
+    }
+
+    #[test]
+    fn oversized_coordinate_numbers_and_segment_lists_are_bounded() {
+        assert!(parse_edge_segments("!999999999999999999999999999999999999999999999999 0|1 1").is_empty());
+        let source = "|0 0".repeat(MAX_EDGE_SEGMENTS + 1);
+        let segments = parse_edge_segments(&source);
+        assert_eq!(segments.len(), MAX_EDGE_SEGMENTS);
+    }
+}
diff --git a/crates/xfl/src/lib.rs b/crates/xfl/src/lib.rs
new file mode 100644
index 000000000..6fd34d0be
--- /dev/null
+++ b/crates/xfl/src/lib.rs
@@ -0,0 +1,461 @@
+//! Reads the hostile ZIP package used by an Animate `.fla` (an archive of an XFL folder),
+//! including its XFL-specific path rules and resource limits.
+//!
+//! Implements the parts of the published ZIP format (PKWARE APPNOTE 6.3) that archive tools
+//! write: the end-of-central-directory record (and its ZIP64 form), central directory entries
+//! with ZIP64 sizes, local headers, data descriptors, "stored" and "deflate" entries (inflated
+//! by `miniz_oxide`), UTF-8 names (flag bit 11 or the Info-ZIP Unicode path field) and CP437
+//! names. Encryption, other compression methods and split archives are refused with a clear
+//! error.
+//!
+//! The archive is treated as hostile. Every offset and size is checked against the bytes it
+//! comes from; entries may not overlap each other or the central directory; a name that would
+//! leave the package (`..`, absolute or drive paths), is listed twice or is nested deeper than
+//! [`MAX_DEPTH`] refuses the archive; an entry may not claim more than deflate can produce from
+//! its bytes ([`MAX_RATIO`]), more than [`MAX_ENTRY`], or a size or checksum it doesn't have;
+//! and the archive hands out at most [`MAX_TOTAL`] bytes in all. Nothing is ever written to
+//! disk. Never panics.
+//!
+//! [`edges`] decodes native shape-edge attributes into neutral points and line/quadratic
+//! segments for consumers to map into their own geometry models.
+
+use std::cell::Cell;
+use std::collections::HashMap;
+
+/// XFL's edge-attribute grammar, independent of any consuming application's geometry types.
+pub mod edges;
+
+/// Largest single entry inflated (bytes).
+pub const MAX_ENTRY: usize = 256 * 1024 * 1024;
+/// Most bytes one archive hands out, over every read (the import's memory budget).
+pub const MAX_TOTAL: u64 = 1024 * 1024 * 1024;
+/// Most entries an archive may list (files and folders).
+pub const MAX_ENTRIES: usize = 100_000;
+/// Most folders a path may be inside (Animate's library nests a few deep).
+pub const MAX_DEPTH: usize = 32;
+/// Largest size-to-compressed-size ratio believed: deflate itself can't pass about 1032 : 1,
+/// so an entry claiming more is a zip bomb or a damaged size, refused before inflating.
+pub const MAX_RATIO: u64 = 1024;
+
+#[derive(Debug, Clone, thiserror::Error, PartialEq)]
+pub enum ZipError {
+    #[error("not a zip archive (no end-of-directory record)")]
+    NotZip,
+    #[error("the archive is damaged: {0}")]
+    Damaged(&'static str),
+    #[error("the archive is damaged: '{0}' {1}")]
+    DamagedEntry(String, &'static str),
+    #[error("the archive uses a zip feature this XFL reader can't read ({0})")]
+    UnsupportedArchive(&'static str),
+    #[error("'{0}' uses a zip feature this XFL reader can't read ({1})")]
+    Unsupported(String, &'static str),
+    #[error("'{0}' is too large to read")]
+    TooLarge(String),
+    #[error("the archive asks for more than {} MB in all", MAX_TOTAL / (1024 * 1024))]
+    TooMuch,
+    #[error("the archive lists more than {MAX_ENTRIES} files")]
+    TooMany,
+    #[error("'{0}' claims to expand more than compression allows (a zip bomb or a damaged archive)")]
+    Bomb(String),
+    #[error("'{0}' and '{1}' share bytes in the archive (a zip bomb or a damaged archive)")]
+    Overlap(String, String),
+    #[error("'{0}' points outside the document")]
+    Unsafe(String),
+    #[error("'{0}' is in the archive twice")]
+    Duplicate(String),
+    #[error("'{0}' is inside more than {MAX_DEPTH} folders")]
+    TooDeep(String),
+}
+
+#[derive(Debug, Clone)]
+struct Entry {
+    method: u16,
+    flags: u16,
+    crc: u32,
+    comp: usize,
+    size: usize,
+    /// Where its (compressed) bytes start.
+    data: usize,
+}
+
+pub struct Archive<'a> {
+    data: &'a [u8],
+    entries: HashMap<String, Entry>,
+    folders: usize,
+    /// Bytes still to hand out ([`MAX_TOTAL`] at first).
+    budget: Cell<u64>,
+}
+
+const END: u32 = 0x0605_4b50;
+const END64: u32 = 0x0606_4b50;
+const LOCATOR64: u32 = 0x0706_4b50;
+const CENTRAL: u32 = 0x0201_4b50;
+const LOCAL: u32 = 0x0403_4b50;
+
+fn get(d: &[u8], at: usize, len: usize) -> Option<&[u8]> {
+    d.get(at..at.checked_add(len)?)
+}
+fn u16_at(d: &[u8], i: usize) -> Option<u16> {
+    Some(u16::from_le_bytes(get(d, i, 2)?.try_into().ok()?))
+}
+fn u32_at(d: &[u8], i: usize) -> Option<u32> {
+    Some(u32::from_le_bytes(get(d, i, 4)?.try_into().ok()?))
+}
+fn u64_at(d: &[u8], i: usize) -> Option<u64> {
+    Some(u64::from_le_bytes(get(d, i, 8)?.try_into().ok()?))
+}
+
+/// The body of the extra field `id`, if `extra` has one.
+fn extra_field(mut extra: &[u8], id: u16) -> Option<&[u8]> {
+    while extra.len() >= 4 {
+        let (tag, len) = (u16_at(extra, 0)?, u16_at(extra, 2)? as usize);
+        let body = get(extra, 4, len)?;
+        if tag == id {
+            return Some(body);
+        }
+        extra = extra.get(4 + len..)?;
+    }
+    None
+}
+
+/// CRC-32 tables for eight bytes at a time ("slicing by 8"): `TABLES[0]` is the classic
+/// byte table, `TABLES[k][b]` the checksum of byte `b` followed by `k` zero bytes.
+const TABLES: [[u32; 256]; 8] = {
+    let mut t = [[0u32; 256]; 8];
+    let mut i = 0;
+    while i < 256 {
+        let mut c = i as u32;
+        let mut k = 0;
+        while k < 8 {
+            c = if c & 1 != 0 { 0xEDB8_8320 ^ (c >> 1) } else { c >> 1 };
+            k += 1;
+        }
+        t[0][i] = c;
+        i += 1;
+    }
+    let mut k = 1;
+    while k < 8 {
+        let mut i = 0;
+        while i < 256 {
+            let prev = t[k - 1][i];
+            t[k][i] = (prev >> 8) ^ t[0][(prev & 0xff) as usize];
+            i += 1;
+        }
+        k += 1;
+    }
+    t
+};
+
+/// CRC-32 (ISO-HDLC, the zip checksum), eight bytes at a time.
+pub fn crc32(data: &[u8]) -> u32 {
+    let t = &TABLES;
+    let mut c = !0u32;
+    let (blocks, rest) = data.as_chunks::<8>();
+    for b in blocks {
+        let lo = c ^ u32::from_le_bytes([b[0], b[1], b[2], b[3]]);
+        c = t[7][(lo & 0xff) as usize]
+            ^ t[6][((lo >> 8) & 0xff) as usize]
+            ^ t[5][((lo >> 16) & 0xff) as usize]
+            ^ t[4][(lo >> 24) as usize]
+            ^ t[3][b[4] as usize]
+            ^ t[2][b[5] as usize]
+            ^ t[1][b[6] as usize]
+            ^ t[0][b[7] as usize];
+    }
+    for &b in rest {
+        c = t[0][((c ^ b as u32) & 0xff) as usize] ^ (c >> 8);
+    }
+    !c
+}
+
+/// Code page 437, bytes 0x80 to 0xFF: the zip format's name encoding without the UTF-8 flag.
+const CP437: [char; 128] = [
+    'Ç', 'ü', 'é', 'â', 'ä', 'à', 'å', 'ç', 'ê', 'ë', 'è', 'ï', 'î', 'ì', 'Ä', 'Å', //
+    'É', 'æ', 'Æ', 'ô', 'ö', 'ò', 'û', 'ù', 'ÿ', 'Ö', 'Ü', '¢', '£', '¥', '₧', 'ƒ', //
+    'á', 'í', 'ó', 'ú', 'ñ', 'Ñ', 'ª', 'º', '¿', '⌐', '¬', '½', '¼', '¡', '«', '»', //
+    '░', '▒', '▓', '│', '┤', '╡', '╢', '╖', '╕', '╣', '║', '╗', '╝', '╜', '╛', '┐', //
+    '└', '┴', '┬', '├', '─', '┼', '╞', '╟', '╚', '╔', '╩', '╦', '╠', '═', '╬', '╧', //
+    '╨', '╤', '╥', '╙', '╘', '╒', '╓', '╫', '╪', '┘', '┌', '█', '▄', '▌', '▐', '▀', //
+    'α', 'ß', 'Γ', 'π', 'Σ', 'σ', 'µ', 'τ', 'Φ', 'Θ', 'Ω', 'δ', '∞', 'φ', 'ε', '∩', //
+    '≡', '±', '≥', '≤', '⌠', '⌡', '÷', '≈', '°', '∙', '·', '√', 'ⁿ', '²', '■', '\u{a0}',
+];
+
+/// An entry's name as text: the Info-ZIP Unicode path field when it matches the name, UTF-8
+/// when flag bit 11 says so, else CP437 as the format specifies. Many writers store UTF-8
+/// without setting the flag, so a name that is valid UTF-8 is read as UTF-8 (ASCII, which
+/// nearly every name is, reads the same either way).
+fn decode_name(raw: &[u8], utf8: bool, extra: &[u8]) -> Result<String, ZipError> {
+    if let Some(up) = extra_field(extra, 0x7075)
+        && up.first() == Some(&1)
+        && u32_at(up, 1) == Some(crc32(raw))
+        && let Some(Ok(s)) = up.get(5..).map(std::str::from_utf8)
+    {
+        return Ok(s.to_string());
+    }
+    match std::str::from_utf8(raw) {
+        Ok(s) => Ok(s.to_string()),
+        Err(_) if utf8 => Err(ZipError::Damaged("an entry's name is not the UTF-8 it says it is")),
+        Err(_) => Ok(raw.iter().map(|&b| if b < 0x80 { b as char } else { CP437.get((b - 0x80) as usize).copied().unwrap_or('\u{fffd}') }).collect()),
+    }
+}
+
+/// A name as a plain path inside the package: `\` read as `/`, empty and `.` parts dropped.
+/// Names that would leave the package are refused, though nothing is ever extracted: every
+/// lookup stays unambiguous, as the folder form's reader also refuses them.
+fn clean_path(name: &str) -> Result<String, ZipError> {
+    let unix = name.replace('\\', "/");
+    let shown = || name.chars().take(200).collect::<String>();
+    if unix.starts_with('/') || unix.contains('\0') {
+        return Err(ZipError::Unsafe(shown()));
+    }
+    let mut parts = Vec::new();
+    for part in unix.split('/') {
+        match part {
+            "" | "." => {}
+            ".." => return Err(ZipError::Unsafe(shown())),
+            // `C:`, `C:x`: a drive.
+            p if parts.is_empty() && p.contains(':') => return Err(ZipError::Unsafe(shown())),
+            p => parts.push(p),
+        }
+    }
+    if parts.len() > MAX_DEPTH + 1 {
+        return Err(ZipError::TooDeep(shown()));
+    }
+    Ok(parts.join("/"))
+}
+
+fn method_name(method: u16) -> &'static str {
+    match method {
+        9 => "Deflate64 compression",
+        12 => "bzip2 compression",
+        14 => "LZMA compression",
+        93 => "Zstandard compression",
+        95 => "XZ compression",
+        99 => "AES encryption",
+        _ => "an unknown compression method",
+    }
+}
+
+/// The end of the central directory: (entry count, its size, its offset, where it must end).
+fn find_end(data: &[u8]) -> Result<(u64, u64, u64, usize), ZipError> {
+    // The end record is in the last 22 + 65535 bytes (it may carry a comment).
+    let lo = data.len().saturating_sub(22 + 65_535);
+    let mut eocd = None;
+    let mut fallback = None;
+    for candidate in (lo..data.len().saturating_sub(21)).rev() {
+        if u32_at(data, candidate) != Some(END)
+            || !u16_at(data, candidate + 20)
+                .is_some_and(|comment| candidate.checked_add(22 + usize::from(comment)).is_some_and(|end| end <= data.len()))
+        {
+            continue;
+        }
+        // Keep the earliest bounds-valid candidate's eventual parse error if no structurally
+        // consistent candidate is found. This preserves useful damaged-ZIP diagnostics.
+        fallback = Some(candidate);
+
+        let size = u32_at(data, candidate + 12).unwrap_or(u32::MAX);
+        let offset = u32_at(data, candidate + 16).unwrap_or(u32::MAX);
+        if size == u32::MAX || offset == u32::MAX {
+            // ZIP64's directory must end exactly where the ZIP64 end record starts.
+            let locator = candidate.checked_sub(20).filter(|&at| u32_at(data, at) == Some(LOCATOR64));
+            let valid = locator
+                .and_then(|at| u64_at(data, at + 8))
+                .and_then(|at| usize::try_from(at).ok())
+                .filter(|&at| u32_at(data, at) == Some(END64))
+                .is_some_and(|at| {
+                    let dir_size = u64_at(data, at + 40).and_then(|n| usize::try_from(n).ok());
+                    let dir_offset = u64_at(data, at + 48).and_then(|n| usize::try_from(n).ok());
+                    dir_size.zip(dir_offset).is_some_and(|(size, offset)| offset.checked_add(size) == Some(at))
+                });
+            if !valid {
+                continue;
+            }
+        } else {
+            let end = usize::try_from(offset).ok().and_then(|offset| usize::try_from(size).ok().and_then(|size| offset.checked_add(size)));
+            if end != Some(candidate) {
+                continue;
+            }
+        }
+        eocd = Some(candidate);
+        break;
+    }
+    let eocd = eocd.or(fallback).ok_or(ZipError::NotZip)?;
+    let field16 = |o: usize| u16_at(data, eocd + o).ok_or(ZipError::Damaged("the end record is cut short"));
+    let field32 = |o: usize| u32_at(data, eocd + o).ok_or(ZipError::Damaged("the end record is cut short"));
+    let (disk, dir_disk, on_disk, count) = (field16(4)?, field16(6)?, field16(8)?, field16(10)?);
+    let (size, offset) = (field32(12)?, field32(16)?);
+    if count != 0xffff && size != 0xffff_ffff && offset != 0xffff_ffff {
+        if disk != 0 || dir_disk != 0 || on_disk != count {
+            return Err(ZipError::UnsupportedArchive("split across several files"));
+        }
+        return Ok((count.into(), size.into(), offset.into(), eocd));
+    }
+    // ZIP64: a locator just before the end record points at the ZIP64 end record.
+    let locator = eocd.checked_sub(20).filter(|&l| u32_at(data, l) == Some(LOCATOR64)).ok_or(ZipError::Damaged("the ZIP64 end record is missing"))?;
+    let missing = ZipError::Damaged("the ZIP64 end record is missing");
+    let at = u64_at(data, locator + 8).and_then(|a| usize::try_from(a).ok()).filter(|&a| a < locator).ok_or(missing.clone())?;
+    if u32_at(data, at) != Some(END64) {
+        return Err(missing);
+    }
+    let cut = ZipError::Damaged("the ZIP64 end record is cut short");
+    let (disk, dir_disk) = (u32_at(data, at + 16).ok_or(cut.clone())?, u32_at(data, at + 20).ok_or(cut.clone())?);
+    let (on_disk, count) = (u64_at(data, at + 24).ok_or(cut.clone())?, u64_at(data, at + 32).ok_or(cut.clone())?);
+    if disk != 0 || dir_disk != 0 || on_disk != count {
+        return Err(ZipError::UnsupportedArchive("split across several files"));
+    }
+    Ok((count, u64_at(data, at + 40).ok_or(cut.clone())?, u64_at(data, at + 48).ok_or(cut)?, at))
+}
+
+impl<'a> Archive<'a> {
+    pub fn open(data: &'a [u8]) -> Result<Archive<'a>, ZipError> {
+        let (count, dir_size, dir_at, dir_limit) = find_end(data)?;
+        let past = ZipError::Damaged("the central directory is outside the archive");
+        let dir_at = usize::try_from(dir_at).map_err(|_| past.clone())?;
+        let dir_end = usize::try_from(dir_size).ok().and_then(|s| dir_at.checked_add(s)).filter(|&e| e <= dir_limit).ok_or(past.clone())?;
+        let dir = data.get(dir_at..dir_end).ok_or(past)?;
+        if count > MAX_ENTRIES as u64 {
+            return Err(ZipError::TooMany);
+        }
+        let count = count as usize;
+        // Every central entry is at least 46 bytes.
+        let cut = ZipError::Damaged("the central directory is cut short");
+        if count.saturating_mul(46) > dir.len() {
+            return Err(cut);
+        }
+        let mut entries = HashMap::with_capacity(count);
+        let mut folders = 0;
+        // (start, end, name) of every entry's local header and data.
+        let mut spans: Vec<(usize, usize, String)> = Vec::with_capacity(count);
+        let mut i = 0usize;
+        for _ in 0..count {
+            if u32_at(dir, i) != Some(CENTRAL) {
+                return Err(cut);
+            }
+            let short = |o: usize| u16_at(dir, i + o).ok_or(cut.clone());
+            let long = |o: usize| u32_at(dir, i + o).ok_or(cut.clone());
+            let (flags, method) = (short(8)?, short(10)?);
+            let crc = long(16)?;
+            let (comp32, size32, offset32) = (long(20)?, long(24)?, long(42)?);
+            let (nlen, xlen, clen) = (short(28)? as usize, short(30)? as usize, short(32)? as usize);
+            let raw_name = get(dir, i + 46, nlen).ok_or(cut.clone())?;
+            let extra = get(dir, i + 46 + nlen, xlen).ok_or(cut.clone())?;
+            get(dir, i + 46 + nlen + xlen, clen).ok_or(cut.clone())?;
+            i += 46 + nlen + xlen + clen;
+
+            let name = decode_name(raw_name, flags & 0x0800 != 0, extra)?;
+            let shown = || name.chars().take(200).collect::<String>();
+            // ZIP64: each 32-bit field that overflowed is in the extra field, in this order.
+            let (mut size, mut comp, mut offset) = (u64::from(size32), u64::from(comp32), u64::from(offset32));
+            if size32 == u32::MAX || comp32 == u32::MAX || offset32 == u32::MAX {
+                let z = extra_field(extra, 0x0001).ok_or_else(|| ZipError::DamagedEntry(shown(), "has no ZIP64 sizes"))?;
+                let mut at = 0;
+                for (wide, value) in [(size32, &mut size), (comp32, &mut comp), (offset32, &mut offset)] {
+                    if wide == u32::MAX {
+                        *value = u64_at(z, at).ok_or_else(|| ZipError::DamagedEntry(shown(), "has its ZIP64 sizes cut short"))?;
+                        at += 8;
+                    }
+                }
+            }
+            let outside = || ZipError::DamagedEntry(shown(), "is outside the archive");
+            let offset = usize::try_from(offset).map_err(|_| outside())?;
+            let comp = usize::try_from(comp).map_err(|_| outside())?;
+            // An entry's size is checked when it is read: one too large to read may sit unused.
+            let size = usize::try_from(size).unwrap_or(usize::MAX);
+
+            // Its local header, then its data, all before the central directory.
+            if u32_at(data, offset) != Some(LOCAL) {
+                return Err(ZipError::DamagedEntry(shown(), "has no local header"));
+            }
+            let lnlen = u16_at(data, offset + 26).ok_or_else(outside)? as usize;
+            let lxlen = u16_at(data, offset + 28).ok_or_else(outside)? as usize;
+            let start = offset + 30 + lnlen + lxlen;
+            let end = start.checked_add(comp).filter(|&e| e <= dir_at).ok_or_else(outside)?;
+            spans.push((offset, end, shown()));
+
+            let folder = name.ends_with('/') || name.ends_with('\\');
+            let path = clean_path(&name)?;
+            if folder || path.is_empty() {
+                if size != 0 || comp > 2 {
+                    return Err(ZipError::DamagedEntry(shown(), "is a folder with data"));
+                }
+                folders += 1;
+                continue;
+            }
+            if method == 8 && size as u64 > (comp as u64).saturating_mul(MAX_RATIO).saturating_add(4096) {
+                return Err(ZipError::Bomb(shown()));
+            }
+            if method == 0 && flags & 0x41 == 0 && size != comp {
+                return Err(ZipError::DamagedEntry(shown(), "is stored with two different sizes"));
+            }
+            if entries.insert(path, Entry { method, flags, crc, comp, size, data: start }).is_some() {
+                return Err(ZipError::Duplicate(shown()));
+            }
+        }
+        if i != dir.len() {
+            return Err(ZipError::Damaged("the central directory has trailing data"));
+        }
+        // No two entries may share bytes (the overlapping-entries zip bomb).
+        spans.sort_unstable_by_key(|s| s.0);
+        if let Some(w) = spans.windows(2).find(|w| w[0].1 > w[1].0) {
+            return Err(ZipError::Overlap(w[0].2.clone(), w[1].2.clone()));
+        }
+        Ok(Archive { data, entries, folders, budget: Cell::new(MAX_TOTAL) })
+    }
+
+    /// The files' paths (`/`-separated, folders left out).
+    pub fn names(&self) -> impl Iterator<Item = &str> {
+        self.entries.keys().map(String::as_str)
+    }
+
+    /// How many files and folder entries the archive lists.
+    pub fn counts(&self) -> (usize, usize) {
+        (self.entries.len(), self.folders)
+    }
+
+    /// The bytes of entry `name` (path inside the archive, `/`-separated), checked against
+    /// its size and checksum.
+    pub fn read(&self, name: &str) -> Result<Option<Vec<u8>>, ZipError> {
+        let Some(e) = self.entries.get(name) else { return Ok(None) };
+        if e.flags & 0x41 != 0 {
+            return Err(ZipError::Unsupported(name.into(), "encryption"));
+        }
+        if !matches!(e.method, 0 | 8) {
+            return Err(ZipError::Unsupported(name.into(), method_name(e.method)));
+        }
+        if e.size > MAX_ENTRY || e.comp > MAX_ENTRY {
+            return Err(ZipError::TooLarge(name.into()));
+        }
+        let left = self.budget.get();
+        if e.size as u64 > left {
+            return Err(ZipError::TooMuch);
+        }
+        let raw = get(self.data, e.data, e.comp).ok_or_else(|| ZipError::DamagedEntry(name.into(), "is outside the archive"))?;
+        let out = match e.method {
+            0 => raw.to_vec(),
+            _ => miniz_oxide::inflate::decompress_to_vec_with_limit(raw, e.size.max(1)).map_err(|err| {
+                let why = if err.status == miniz_oxide::inflate::TINFLStatus::HasMoreOutput {
+                    "expands past the size it gives"
+                } else {
+                    "has damaged compressed data"
+                };
+                ZipError::DamagedEntry(name.into(), why)
+            })?,
+        };
+        if out.len() != e.size {
+            return Err(ZipError::DamagedEntry(name.into(), "is not the size it gives"));
+        }
+        if crc32(&out) != e.crc {
+            return Err(ZipError::DamagedEntry(name.into(), "fails its checksum"));
+        }
+        self.budget.set(left - e.size as u64);
+        Ok(Some(out))
+    }
+}
+
+#[cfg(test)]
+#[path = "../tests/support/fla.rs"]
+pub(crate) mod pack;
+
+#[cfg(test)]
+#[path = "tests.rs"]
+mod tests;
diff --git a/crates/xfl/src/tests.rs b/crates/xfl/src/tests.rs
new file mode 100644
index 000000000..9f9d5a13e
--- /dev/null
+++ b/crates/xfl/src/tests.rs
@@ -0,0 +1,344 @@
+//! The zip reader against the layouts writers produce and the archives an attacker would
+//! (ADR 0054). Archives are made by the independent writer in `tests/support/fla.rs`.
+
+use super::pack::{self, Raw, write};
+use super::*;
+
+fn zip(files: &[(&str, &[u8], bool)]) -> Vec<u8> {
+    write(&files.iter().map(|(n, b, d)| Raw::new(n, b, *d)).collect::<Vec<_>>(), false)
+}
+
+/// The error opening `z`, or reading every file in it.
+fn error(z: &[u8]) -> ZipError {
+    match Archive::open(z) {
+        Err(e) => e,
+        Ok(a) => {
+            let names: Vec<String> = a.names().map(str::to_string).collect();
+            names.iter().find_map(|n| a.read(n).err()).expect("an error")
+        }
+    }
+}
+
+#[test]
+fn reads_stored_and_deflated_entries() {
+    let z = zip(&[("DOMDocument.xml", b"<DOMDocument/>", true), ("LIBRARY\\Ball.xml", b"<DOMSymbolItem/>", false)]);
+    let a = Archive::open(&z).unwrap();
+    assert_eq!(a.read("DOMDocument.xml").unwrap().unwrap(), b"<DOMDocument/>");
+    assert_eq!(a.read("LIBRARY/Ball.xml").unwrap().unwrap(), b"<DOMSymbolItem/>", "backslashes normalised");
+    assert_eq!(a.read("missing").unwrap(), None);
+}
+
+#[test]
+fn the_checksum_matches_the_published_check_value() {
+    assert_eq!(crc32(b"123456789"), 0xCBF4_3926);
+    assert_eq!(crc32(b""), 0);
+    let bytes: Vec<u8> = (0..5000u32).map(|i| (i * 7 + i / 13) as u8).collect();
+    assert_eq!(crc32(&bytes), pack::crc32(&bytes), "the table matches the bitwise form");
+}
+
+#[test]
+fn every_layout_a_writer_uses_reads_the_same() {
+    let files: std::collections::BTreeMap<String, Vec<u8>> =
+        [("DOMDocument.xml", "<DOMDocument/>"), ("LIBRARY/Café/Ünïcödé ★.xml", "<DOMSymbolItem/>"), ("bin/M 1 1.dat", "data")]
+            .iter()
+            .map(|(p, b)| (p.to_string(), b.as_bytes().to_vec()))
+            .collect();
+    for v in pack::VARIANTS {
+        let z = pack::pack(&files, v);
+        let a = Archive::open(&z).unwrap_or_else(|e| panic!("{}: {e}", v.name));
+        assert_eq!(a.counts().0, 3 + usize::from(v.mimetype), "{}", v.name);
+        for (path, body) in &files {
+            assert_eq!(a.read(path).unwrap_or_else(|e| panic!("{}: {e}", v.name)).as_deref(), Some(body.as_slice()), "{}: {path}", v.name);
+        }
+    }
+}
+
+#[test]
+fn names_are_cp437_unless_flagged_or_utf8() {
+    // "Café.xml" in CP437 (é is 0x82), not valid UTF-8, without the flag.
+    let mut r = Raw::new("", b"x", false);
+    (r.name, r.utf8) = (b"LIBRARY/Caf\x82.xml".to_vec(), false);
+    let z = write(&[r.clone()], false);
+    assert_eq!(Archive::open(&z).unwrap().names().collect::<Vec<_>>(), ["LIBRARY/Café.xml"]);
+    assert_eq!(pack::cp437("LIBRARY/Café.xml").unwrap(), b"LIBRARY/Caf\x82.xml");
+    // Flagged as UTF-8 but isn't: refused, not guessed.
+    r.utf8 = true;
+    assert!(matches!(Archive::open(&write(&[r], false)).err(), Some(ZipError::Damaged(_))));
+    // A Unicode path field whose checksum doesn't match the name it stands in for is ignored.
+    let mut r = Raw::new("plain.xml", b"x", false);
+    r.utf8 = false;
+    r.extra = [0x75, 0x70, 9, 0, 1, 0, 0, 0, 0, b'o', b't', b'h', b'r'].to_vec();
+    assert_eq!(Archive::open(&write(&[r], false)).unwrap().names().collect::<Vec<_>>(), ["plain.xml"]);
+}
+
+#[test]
+fn damaged_archives_are_errors() {
+    assert_eq!(Archive::open(b"not a zip").err(), Some(ZipError::NotZip));
+    assert_eq!(Archive::open(b"").err(), Some(ZipError::NotZip));
+    let mut z = zip(&[("a", b"hello", true)]);
+    let n = z.len();
+    // Point the directory past the end.
+    z[n - 6] = 0xff;
+    assert!(Archive::open(&z).is_err());
+}
+
+#[test]
+fn a_truncated_central_directory_is_damaged() {
+    let z = zip(&[("DOMDocument.xml", b"<DOMDocument/>", true), ("b.xml", b"<b/>", true), ("c.xml", b"<c/>", false)]);
+    let dir_at = u32_at(&z, z.len() - 6).unwrap() as usize;
+    let end = z.len() - 22;
+    // Every cut inside the directory, keeping the end record (which still claims 3 entries).
+    for cut in dir_at..end {
+        let mut t = z[..cut].to_vec();
+        t.extend_from_slice(&z[end..]);
+        let e = Archive::open(&t).err().unwrap_or_else(|| panic!("cut at {cut} opened"));
+        assert!(!e.to_string().is_empty());
+    }
+    // The end record says more entries than there are.
+    let mut t = z.clone();
+    t[end + 8] = 9;
+    t[end + 10] = 9;
+    assert_eq!(Archive::open(&t).err(), Some(ZipError::Damaged("the central directory is cut short")));
+    // Cut short anywhere at all: an error, never a panic.
+    for cut in 0..z.len() {
+        let _ = Archive::open(&z[..cut]).map(|a| a.read("DOMDocument.xml"));
+    }
+}
+
+#[test]
+fn overlapping_entries_are_refused() {
+    // Two names for one local header (the overlapping-file zip bomb).
+    let mut b = Raw::new("b.xml", b"<a/>", true);
+    b.share = Some(0);
+    let z = write(&[Raw::new("a.xml", b"<a/>", true), b], false);
+    assert!(matches!(Archive::open(&z).err(), Some(ZipError::Overlap(..))), "{:?}", Archive::open(&z).err());
+    // An entry whose stated compressed size runs into the next one.
+    let mut z = zip(&[("a.xml", b"aaaaaaaaaa", false), ("b.xml", b"bbbbbbbbbb", false)]);
+    let dir_at = u32_at(&z, z.len() - 6).unwrap() as usize;
+    z[dir_at + 20] = 20; // a's compressed size, in its central record
+    z[dir_at + 24] = 20;
+    assert!(matches!(Archive::open(&z).err(), Some(ZipError::Overlap(..))));
+}
+
+#[test]
+fn entries_never_reach_past_their_data() {
+    // An entry's data running into the central directory, or past the end.
+    for size in [64u32, 0xffff_fff0] {
+        let mut z = zip(&[("a.xml", b"aaaaaaaaaa", false)]);
+        let dir_at = u32_at(&z, z.len() - 6).unwrap() as usize;
+        z[dir_at + 20..dir_at + 24].copy_from_slice(&size.to_le_bytes());
+        assert_eq!(Archive::open(&z).err(), Some(ZipError::DamagedEntry("a.xml".into(), "is outside the archive")));
+    }
+    // A local header offset past the end.
+    let mut z = zip(&[("a.xml", b"aaaaaaaaaa", false)]);
+    let dir_at = u32_at(&z, z.len() - 6).unwrap() as usize;
+    z[dir_at + 42..dir_at + 46].copy_from_slice(&0x7fff_0000u32.to_le_bytes());
+    assert_eq!(Archive::open(&z).err(), Some(ZipError::DamagedEntry("a.xml".into(), "has no local header")));
+}
+
+#[test]
+fn lying_sizes_and_checksums_are_damaged() {
+    // Says 100 bytes, inflates to 1000.
+    let body = vec![b'x'; 1000];
+    let mut r = Raw::new("a.xml", &body, true);
+    r.size = Some(100);
+    assert_eq!(error(&write(&[r], false)), ZipError::DamagedEntry("a.xml".into(), "expands past the size it gives"));
+    // Says 2000, inflates to 1000.
+    let mut r = Raw::new("a.xml", &body, true);
+    r.size = Some(2000);
+    assert_eq!(error(&write(&[r], false)), ZipError::DamagedEntry("a.xml".into(), "is not the size it gives"));
+    // A stored entry with two sizes.
+    let mut r = Raw::new("a.xml", &body, false);
+    r.size = Some(10);
+    assert_eq!(error(&write(&[r], false)), ZipError::DamagedEntry("a.xml".into(), "is stored with two different sizes"));
+    // The wrong checksum.
+    let mut r = Raw::new("a.xml", &body, true);
+    r.crc = Some(12345);
+    assert_eq!(error(&write(&[r], false)), ZipError::DamagedEntry("a.xml".into(), "fails its checksum"));
+    // Garbage instead of deflate data.
+    let mut r = Raw::new("a.xml", &body, true);
+    r.compressed = Some(vec![0xff; 40]);
+    assert_eq!(error(&write(&[r], false)), ZipError::DamagedEntry("a.xml".into(), "has damaged compressed data"));
+}
+
+#[test]
+fn compression_bombs_are_refused() {
+    // A real 64 MB of zeros deflates past the ratio cap: refused before inflating.
+    let zeros = vec![0u8; 64 << 20];
+    let z = zip(&[("bomb.xml", &zeros, true)]);
+    assert!(z.len() < 100_000, "{}", z.len());
+    assert_eq!(Archive::open(&z).err(), Some(ZipError::Bomb("bomb.xml".into())));
+    // A size claim no deflate stream of that length could meet.
+    let mut r = Raw::new("a.xml", &[7; 100], true);
+    r.size = Some(200 << 20);
+    assert_eq!(Archive::open(&write(&[r], false)).err(), Some(ZipError::Bomb("a.xml".into())));
+    // One entry larger than an entry may be, at a believable ratio: refused before inflating.
+    let mut r = Raw::new("big.dat", b"", true);
+    r.compressed = Some(vec![0; 300 << 10]);
+    r.size = Some(MAX_ENTRY as u64 + 1);
+    let z = write(&[r], false);
+    assert_eq!(error(&z), ZipError::TooLarge("big.dat".into()));
+}
+
+#[test]
+fn the_archive_hands_out_at_most_its_budget() {
+    let body = vec![b'a'; 4096];
+    let z = zip(&[("a.xml", &body, true)]);
+    let a = Archive::open(&z).unwrap();
+    a.budget.set(10_000);
+    assert!(a.read("a.xml").is_ok() && a.read("a.xml").is_ok());
+    assert_eq!(a.read("a.xml").err(), Some(ZipError::TooMuch), "a third read passes 10,000 bytes");
+}
+
+#[test]
+fn unsafe_paths_are_refused() {
+    for name in [
+        "../escape.xml",
+        "LIBRARY/../../escape.xml",
+        "/etc/passwd",
+        "\\Windows\\win.ini",
+        "C:\\Windows\\win.ini",
+        "C:escape.xml",
+        "LIBRARY\\..\\..\\x",
+        "a\0b",
+    ] {
+        let z = zip(&[("DOMDocument.xml", b"<DOMDocument/>", true), (name, b"x", false)]);
+        assert!(matches!(Archive::open(&z).err(), Some(ZipError::Unsafe(_))), "{name:?}: {:?}", Archive::open(&z).err());
+    }
+    // Harmless odd names are tidied, not refused.
+    let z = zip(&[("./LIBRARY//a.xml", b"x", false)]);
+    assert_eq!(Archive::open(&z).unwrap().names().collect::<Vec<_>>(), ["LIBRARY/a.xml"]);
+}
+
+#[test]
+fn duplicate_names_are_refused() {
+    let z = zip(&[("LIBRARY/a.xml", b"one", false), ("LIBRARY\\a.xml", b"two", false)]);
+    assert_eq!(Archive::open(&z).err(), Some(ZipError::Duplicate("LIBRARY\\a.xml".into())));
+    // Folders listed twice are harmless.
+    let z = zip(&[("LIBRARY/", b"", false), ("LIBRARY\\", b"", false), ("LIBRARY/a.xml", b"one", false)]);
+    assert_eq!(Archive::open(&z).unwrap().counts(), (1, 2));
+}
+
+#[test]
+fn drive_prefix_after_normalized_dot_segments_is_refused() {
+    for name in ["./C:/LIBRARY/a.xml", "./C:\\LIBRARY\\a.xml"] {
+        assert!(matches!(Archive::open(&zip(&[(name, b"x", false)])).err(), Some(ZipError::Unsafe(_))));
+    }
+    assert!(Archive::open(&zip(&[("./LIBRARY/a.xml", b"x", false)])).is_ok());
+}
+
+#[test]
+fn invalid_eocd_comment_candidate_does_not_mask_archive_end() {
+    let mut z = zip(&[("a.xml", b"x", false)]);
+    let end = z.len() - 22;
+    z[end + 20..end + 22].copy_from_slice(&22u16.to_le_bytes());
+    let fake = z.len();
+    z.extend_from_slice(&END.to_le_bytes());
+    z.extend_from_slice(&[0; 16]);
+    z.extend_from_slice(&u16::MAX.to_le_bytes());
+    assert!(Archive::open(&z).is_ok());
+    assert_eq!(fake + 22, z.len());
+}
+
+#[test]
+fn eocd_signature_inside_comment_is_not_an_empty_archive() {
+    let mut z = zip(&[("a.xml", b"x", false)]);
+    let end = z.len() - 22;
+    z[end + 20..end + 22].copy_from_slice(&22u16.to_le_bytes());
+    z.extend_from_slice(&END.to_le_bytes());
+    z.extend_from_slice(&[0; 18]);
+    let archive = Archive::open(&z).unwrap();
+    assert_eq!(archive.names().collect::<Vec<_>>(), ["a.xml"]);
+}
+
+#[test]
+fn central_directory_must_be_consumed_exactly() {
+    let mut z = zip(&[("a.xml", b"x", false)]);
+    let end = z.len() - 22;
+    let size = u32::from_le_bytes(z[end + 12..end + 16].try_into().unwrap());
+    z.insert(end, 0);
+    z[end + 12 + 1..end + 16 + 1].copy_from_slice(&(size + 1).to_le_bytes());
+    assert_eq!(Archive::open(&z).err(), Some(ZipError::Damaged("the central directory has trailing data")));
+}
+
+#[test]
+fn deeply_nested_folders_are_refused() {
+    let ok = format!("{}a.xml", "f/".repeat(MAX_DEPTH));
+    assert!(Archive::open(&zip(&[(&ok, b"x", false)])).is_ok());
+    let deep = format!("{}a.xml", "f/".repeat(MAX_DEPTH + 1));
+    assert!(matches!(Archive::open(&zip(&[(&deep, b"x", false)])).err(), Some(ZipError::TooDeep(_))));
+    // As deep as a name can be: refused quickly, not recursed into.
+    let deepest = "f/".repeat(30_000);
+    assert!(matches!(Archive::open(&zip(&[(&deepest, b"", false)])).err(), Some(ZipError::TooDeep(_))));
+}
+
+#[test]
+fn unsupported_features_say_what_they_are() {
+    assert_eq!(
+        ZipError::UnsupportedArchive("split across several files").to_string(),
+        "the archive uses a zip feature this XFL reader can't read (split across several files)"
+    );
+    assert_eq!(ZipError::Unsupported("a.xml".into(), "encryption").to_string(), "'a.xml' uses a zip feature this XFL reader can't read (encryption)");
+    let mut r = Raw::new("a.xml", b"secret", false);
+    r.flags = 1;
+    assert_eq!(error(&write(&[r], false)), ZipError::Unsupported("a.xml".into(), "encryption"));
+    let mut r = Raw::new("a.xml", b"x", false);
+    r.method = Some(14);
+    assert_eq!(error(&write(&[r], false)), ZipError::Unsupported("a.xml".into(), "LZMA compression"));
+    // Split archives.
+    let mut z = zip(&[("a.xml", b"x", false)]);
+    let end = z.len() - 22;
+    z[end + 4] = 1;
+    assert_eq!(Archive::open(&z).err(), Some(ZipError::UnsupportedArchive("split across several files")));
+    // Too many entries for the directory to hold, and more than the cap.
+    let mut z = zip(&[("a.xml", b"x", false)]);
+    let end = z.len() - 22;
+    z[end + 8..end + 12].copy_from_slice(&[0xfe, 0xff, 0xfe, 0xff]);
+    assert!(Archive::open(&z).is_err());
+}
+
+#[test]
+fn zip64_archives_open_and_their_damage_is_named() {
+    let mut a = Raw::new("a.xml", b"<a/>", true);
+    a.zip64 = true;
+    let mut b = Raw::new("b.xml", b"<b/>", false);
+    (b.zip64, b.descriptor) = (true, true);
+    let z = write(&[a.clone(), b], true);
+    let arch = Archive::open(&z).unwrap();
+    assert_eq!(arch.read("b.xml").unwrap().unwrap(), b"<b/>");
+    // The locator gone.
+    let mut t = z.clone();
+    let loc = t.len() - 22 - 20;
+    t[loc] = 0;
+    assert_eq!(Archive::open(&t).err(), Some(ZipError::Damaged("the ZIP64 end record is missing")));
+    // An entry that says ZIP64 without the extra field.
+    a.zip64 = false;
+    let mut t = write(&[a], false);
+    let dir_at = u32_at(&t, t.len() - 6).unwrap() as usize;
+    t[dir_at + 24..dir_at + 28].copy_from_slice(&u32::MAX.to_le_bytes());
+    assert_eq!(Archive::open(&t).err(), Some(ZipError::DamagedEntry("a.xml".into(), "has no ZIP64 sizes")));
+}
+
+#[test]
+fn errors_read_as_sentences() {
+    let all = [
+        ZipError::NotZip,
+        ZipError::Damaged("the central directory is cut short"),
+        ZipError::DamagedEntry("a.xml".into(), "fails its checksum"),
+        ZipError::UnsupportedArchive("split across several files"),
+        ZipError::Unsupported("a.xml".into(), "encryption"),
+        ZipError::TooLarge("a.xml".into()),
+        ZipError::TooMuch,
+        ZipError::TooMany,
+        ZipError::Bomb("a.xml".into()),
+        ZipError::Overlap("a.xml".into(), "b.xml".into()),
+        ZipError::Unsafe("../a.xml".into()),
+        ZipError::Duplicate("a.xml".into()),
+        ZipError::TooDeep("f/f/a.xml".into()),
+    ];
+    for e in all {
+        let s = e.to_string();
+        assert!(s.len() > 12 && !s.contains("{") && s.chars().next().is_some_and(|c| !c.is_uppercase() || c == 'A'), "{s}");
+    }
+    assert_eq!(ZipError::TooMuch.to_string(), "the archive asks for more than 1024 MB in all");
+}
diff --git a/crates/xfl/tests/support/fla.rs b/crates/xfl/tests/support/fla.rs
new file mode 100644
index 000000000..a3aee2952
--- /dev/null
+++ b/crates/xfl/tests/support/fla.rs
@@ -0,0 +1,347 @@
+//! Test support: packs an XFL package into `.fla` (zip) archives in memory, in each of the ways
+//! zip writers lay one out (ADR 0054), and writes hand-made entries for hostile archives.
+//!
+//! Written from the published format (PKWARE APPNOTE 6.3), independently of the reader in
+//! `src/zip.rs` (it has its own checksum), so a misreading in one is caught by the other.
+//! Shared by the xfl crate's unit and corpus tests and the engine's golden tests (`#[path]`).
+#![allow(dead_code)]
+
+use std::collections::BTreeMap;
+
+/// How a variant compresses its entries.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Compression {
+    Deflate,
+    Stored,
+    /// XML deflated, images stored (as most writers do), the rest alternating.
+    Mixed,
+}
+
+/// How a variant writes entry names.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Names {
+    /// UTF-8 with flag bit 11 set.
+    Utf8Flag,
+    /// UTF-8 without the flag (common, though the format says CP437).
+    Utf8Unflagged,
+    /// CP437 bytes without the flag, as the format specifies (names CP437 can't spell are
+    /// written as UTF-8 with the flag).
+    Cp437,
+    /// An ASCII stand-in name with the real one in the Info-ZIP Unicode path field.
+    UnicodeExtra,
+}
+
+/// One way of packing a package.
+#[derive(Clone, Copy, Debug)]
+pub struct Variant {
+    pub name: &'static str,
+    pub compression: Compression,
+    /// An entry for every folder, before the files in it.
+    pub folders: bool,
+    /// The `mimetype` entry first, stored, as Animate writes it.
+    pub mimetype: bool,
+    /// `\` between folders, as some Windows tools write.
+    pub backslashes: bool,
+    pub names: Names,
+    /// Sizes and checksums after the data (bit 3), as streaming writers do.
+    pub descriptors: bool,
+    /// ZIP64 sizes on every entry and a ZIP64 end record.
+    pub zip64: bool,
+}
+
+const BASE: Variant = Variant {
+    name: "",
+    compression: Compression::Deflate,
+    folders: false,
+    mimetype: false,
+    backslashes: false,
+    names: Names::Utf8Flag,
+    descriptors: false,
+    zip64: false,
+};
+
+/// Every variant each corpus package is checked in.
+pub const VARIANTS: &[Variant] = &[
+    Variant { name: "as Animate writes it (mimetype first, deflated)", mimetype: true, ..BASE },
+    Variant { name: "stored", compression: Compression::Stored, ..BASE },
+    Variant { name: "mixed, with folder entries", compression: Compression::Mixed, folders: true, mimetype: true, ..BASE },
+    Variant { name: "Windows separators, unflagged UTF-8 names", backslashes: true, folders: true, names: Names::Utf8Unflagged, ..BASE },
+    Variant { name: "CP437 names", names: Names::Cp437, compression: Compression::Mixed, ..BASE },
+    Variant { name: "Unicode path fields", names: Names::UnicodeExtra, ..BASE },
+    Variant { name: "data descriptors", descriptors: true, compression: Compression::Mixed, ..BASE },
+    Variant { name: "ZIP64", zip64: true, compression: Compression::Mixed, ..BASE },
+    Variant {
+        name: "everything at once",
+        compression: Compression::Mixed,
+        folders: true,
+        mimetype: true,
+        backslashes: true,
+        names: Names::Cp437,
+        descriptors: true,
+        zip64: true,
+    },
+];
+
+/// One entry as written. Fields a hostile test may change are public.
+#[derive(Clone, Debug, Default)]
+pub struct Raw {
+    /// The name's bytes as stored.
+    pub name: Vec<u8>,
+    /// The uncompressed bytes.
+    pub body: Vec<u8>,
+    pub deflate: bool,
+    /// General purpose flag bits besides 3 and 11 (bit 0: encrypted).
+    pub flags: u16,
+    pub utf8: bool,
+    pub descriptor: bool,
+    pub zip64: bool,
+    /// Overrides: the method, the uncompressed size and the checksum the headers give.
+    pub method: Option<u16>,
+    pub size: Option<u64>,
+    pub crc: Option<u32>,
+    /// Extra field bytes in the central directory (besides ZIP64's).
+    pub extra: Vec<u8>,
+    /// Points this entry's central record at entry `n`'s local header instead of its own.
+    pub share: Option<usize>,
+    /// Stored as compressed bytes: these instead of compressing `body`.
+    pub compressed: Option<Vec<u8>>,
+}
+
+impl Raw {
+    pub fn new(name: &str, body: &[u8], deflate: bool) -> Raw {
+        Raw { name: name.as_bytes().to_vec(), body: body.to_vec(), deflate, utf8: true, ..Raw::default() }
+    }
+}
+
+/// CRC-32 (ISO-HDLC), bit by bit.
+pub fn crc32(data: &[u8]) -> u32 {
+    let mut c = !0u32;
+    for &b in data {
+        c ^= u32::from(b);
+        for _ in 0..8 {
+            c = if c & 1 != 0 { (c >> 1) ^ 0xEDB8_8320 } else { c >> 1 };
+        }
+    }
+    !c
+}
+
+/// `s` in CP437, if every character is in it.
+pub fn cp437(s: &str) -> Option<Vec<u8>> {
+    const HIGH: &str =
+        "ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒáíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐└┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■\u{a0}";
+    s.chars().map(|c| if c.is_ascii() { Some(c as u8) } else { HIGH.chars().position(|h| h == c).map(|i| 0x80 + i as u8) }).collect()
+}
+
+fn le16(out: &mut Vec<u8>, v: u16) {
+    out.extend_from_slice(&v.to_le_bytes());
+}
+fn le32(out: &mut Vec<u8>, v: u32) {
+    out.extend_from_slice(&v.to_le_bytes());
+}
+fn le64(out: &mut Vec<u8>, v: u64) {
+    out.extend_from_slice(&v.to_le_bytes());
+}
+
+/// Writes `entries` as a zip archive, with a ZIP64 end record if `zip64_end`.
+pub fn write(entries: &[Raw], zip64_end: bool) -> Vec<u8> {
+    let mut out = Vec::new();
+    let mut central = Vec::new();
+    let mut offsets = Vec::new();
+    // (time, date): 2025-11-11 12:00.
+    let (time, date) = (0x6000u16, 0x5B6Bu16);
+    for e in entries {
+        let data = match &e.compressed {
+            Some(c) => c.clone(),
+            None if e.deflate => miniz_oxide::deflate::compress_to_vec(&e.body, 6),
+            None => e.body.clone(),
+        };
+        let method = e.method.unwrap_or(if e.deflate { 8 } else { 0 });
+        let crc = e.crc.unwrap_or_else(|| crc32(&e.body));
+        let size = e.size.unwrap_or(e.body.len() as u64);
+        let comp = data.len() as u64;
+        let flags = e.flags | if e.descriptor { 8 } else { 0 } | if e.utf8 { 0x800 } else { 0 };
+        let version: u16 = if e.zip64 { 45 } else { 20 };
+        let offset = out.len() as u64;
+        offsets.push(offset);
+        // The local header.
+        le32(&mut out, 0x0403_4b50);
+        le16(&mut out, version);
+        le16(&mut out, flags);
+        le16(&mut out, method);
+        le16(&mut out, time);
+        le16(&mut out, date);
+        let local_extra = if e.zip64 {
+            let mut x = Vec::new();
+            le16(&mut x, 1);
+            le16(&mut x, 16);
+            le64(&mut x, if e.descriptor { 0 } else { size });
+            le64(&mut x, if e.descriptor { 0 } else { comp });
+            x
+        } else {
+            Vec::new()
+        };
+        if e.descriptor {
+            out.extend_from_slice(&[0; 12]);
+        } else {
+            le32(&mut out, crc);
+            le32(&mut out, if e.zip64 { u32::MAX } else { comp as u32 });
+            le32(&mut out, if e.zip64 { u32::MAX } else { size as u32 });
+        }
+        le16(&mut out, e.name.len() as u16);
+        le16(&mut out, local_extra.len() as u16);
+        out.extend_from_slice(&e.name);
+        out.extend_from_slice(&local_extra);
+        out.extend_from_slice(&data);
+        if e.descriptor {
+            le32(&mut out, 0x0807_4b50);
+            le32(&mut out, crc);
+            if e.zip64 {
+                le64(&mut out, comp);
+                le64(&mut out, size);
+            } else {
+                le32(&mut out, comp as u32);
+                le32(&mut out, size as u32);
+            }
+        }
+        // Its central record.
+        let at = e.share.and_then(|n| offsets.get(n).copied()).unwrap_or(offset);
+        let mut extra = Vec::new();
+        if e.zip64 {
+            le16(&mut extra, 1);
+            le16(&mut extra, 24);
+            le64(&mut extra, size);
+            le64(&mut extra, comp);
+            le64(&mut extra, at);
+        }
+        extra.extend_from_slice(&e.extra);
+        le32(&mut central, 0x0201_4b50);
+        le16(&mut central, version);
+        le16(&mut central, version);
+        le16(&mut central, flags);
+        le16(&mut central, method);
+        le16(&mut central, time);
+        le16(&mut central, date);
+        le32(&mut central, crc);
+        le32(&mut central, if e.zip64 { u32::MAX } else { comp as u32 });
+        le32(&mut central, if e.zip64 { u32::MAX } else { size as u32 });
+        le16(&mut central, e.name.len() as u16);
+        le16(&mut central, extra.len() as u16);
+        le16(&mut central, 0); // comment
+        le16(&mut central, 0); // disk
+        le16(&mut central, 0); // internal attributes
+        let folder = e.name.last().is_some_and(|&c| c == b'/' || c == b'\\');
+        le32(&mut central, if folder { 0x10 } else { 0 });
+        le32(&mut central, if e.zip64 { u32::MAX } else { at as u32 });
+        central.extend_from_slice(&e.name);
+        central.extend_from_slice(&extra);
+    }
+    let dir_at = out.len() as u64;
+    out.extend_from_slice(&central);
+    let n = entries.len() as u64;
+    if zip64_end {
+        let record = out.len() as u64;
+        le32(&mut out, 0x0606_4b50);
+        le64(&mut out, 44);
+        le16(&mut out, 45);
+        le16(&mut out, 45);
+        le32(&mut out, 0);
+        le32(&mut out, 0);
+        le64(&mut out, n);
+        le64(&mut out, n);
+        le64(&mut out, central.len() as u64);
+        le64(&mut out, dir_at);
+        le32(&mut out, 0x0706_4b50);
+        le32(&mut out, 0);
+        le64(&mut out, record);
+        le32(&mut out, 1);
+    }
+    le32(&mut out, 0x0605_4b50);
+    le32(&mut out, 0); // disks
+    let (count, size, at) = if zip64_end { (u16::MAX, u32::MAX, u32::MAX) } else { (n as u16, central.len() as u32, dir_at as u32) };
+    le16(&mut out, count);
+    le16(&mut out, count);
+    le32(&mut out, size);
+    le32(&mut out, at);
+    le16(&mut out, 0);
+    out
+}
+
+/// The entries `files` (paths inside the package) become in `v`.
+pub fn entries(files: &BTreeMap<String, Vec<u8>>, v: &Variant) -> Vec<Raw> {
+    let mut out = Vec::new();
+    let named = |path: &str, body: &[u8], deflate: bool| {
+        let shown = if v.backslashes { path.replace('/', "\\") } else { path.to_string() };
+        let mut r = Raw::new(&shown, body, deflate);
+        r.descriptor = v.descriptors;
+        r.zip64 = v.zip64;
+        match v.names {
+            Names::Utf8Flag => {}
+            Names::Utf8Unflagged => r.utf8 = false,
+            Names::Cp437 => {
+                if let Some(b) = cp437(&shown) {
+                    (r.name, r.utf8) = (b, false);
+                }
+            }
+            Names::UnicodeExtra => {
+                let stand_in: Vec<u8> = shown.chars().map(|c| if c.is_ascii() { c as u8 } else { b'_' }).collect();
+                le16(&mut r.extra, 0x7075);
+                le16(&mut r.extra, (5 + shown.len()) as u16);
+                r.extra.push(1);
+                le32(&mut r.extra, crc32(&stand_in));
+                r.extra.extend_from_slice(shown.as_bytes());
+                (r.name, r.utf8) = (stand_in, false);
+            }
+        }
+        r
+    };
+    if v.mimetype {
+        out.push(named("mimetype", b"application/vnd.adobe.xfl", false));
+    }
+    let mut made = std::collections::BTreeSet::new();
+    for (i, (path, body)) in files.iter().enumerate() {
+        if v.folders {
+            let parts: Vec<&str> = path.split('/').collect();
+            for k in 1..parts.len() {
+                let folder = format!("{}/", parts[..k].join("/"));
+                if made.insert(folder.clone()) {
+                    out.push(named(&folder, b"", false));
+                }
+            }
+        }
+        let image = [".png", ".jpg", ".jpeg", ".gif"].iter().any(|x| path.to_ascii_lowercase().ends_with(x));
+        let deflate = match v.compression {
+            Compression::Deflate => true,
+            Compression::Stored => false,
+            Compression::Mixed => path.ends_with(".xml") || (!image && i % 2 == 0),
+        };
+        out.push(named(path, body, deflate));
+    }
+    out
+}
+
+/// `files` packed as a `.fla` in variant `v`.
+pub fn pack(files: &BTreeMap<String, Vec<u8>>, v: &Variant) -> Vec<u8> {
+    write(&entries(files, v), v.zip64)
+}
+
+/// A package folder's files by their path inside it, leaving out its `golden/` renders.
+pub fn package(dir: &std::path::Path) -> BTreeMap<String, Vec<u8>> {
+    fn walk(dir: &std::path::Path, prefix: &str, out: &mut BTreeMap<String, Vec<u8>>) {
+        let mut list: Vec<_> = std::fs::read_dir(dir).map(|r| r.flatten().collect()).unwrap_or_default();
+        list.sort_by_key(|e| e.file_name());
+        for e in list {
+            let name = e.file_name().to_string_lossy().into_owned();
+            let path = if prefix.is_empty() { name.clone() } else { format!("{prefix}/{name}") };
+            if e.path().is_dir() {
+                if path != "golden" {
+                    walk(&e.path(), &path, out);
+                }
+            } else if let Ok(b) = std::fs::read(e.path()) {
+                out.insert(path, b);
+            }
+        }
+    }
+    let mut out = BTreeMap::new();
+    walk(dir, "", &mut out);
+    out
+}
diff --git a/crates/xlsx/src/package.rs b/crates/xlsx/src/package.rs
index 1c133d0ad..e06619e27 100644
--- a/crates/xlsx/src/package.rs
+++ b/crates/xlsx/src/package.rs
@@ -188,9 +188,15 @@ impl<'a> Package<'a> {
             self.binary_strings = Some(strings.len());
             return Ok(strings);
         }
-        let Some(rel) = rels.first("sharedStrings").filter(|r| !r.external) else { return Ok(Vec::new()) };
-        let Some(bytes) = self.opc.read(&rel.target)? else {
-            self.warn(format!("missing part {}", rel.target));
+        let rel = rels.first("sharedStrings").filter(|r| !r.external);
+        // Some older spreadsheet writers omit the workbook relationship but still emit the
+        // conventional shared-string part. The pre-OPC reader accepted that layout, so retain
+        // compatibility by checking the standard part name only when the relationship is absent.
+        let target = rel.map_or("xl/sharedStrings.xml", |r| r.target.as_str());
+        let Some(bytes) = self.opc.read(target)? else {
+            if rel.is_some() {
+                self.warn(format!("missing part {target}"));
+            }
             return Ok(Vec::new());
         };
         let mut items = Vec::new();
diff --git a/crates/xlsx/tests/xlsx.rs b/crates/xlsx/tests/xlsx.rs
index c8355fd8c..ef932026e 100644
--- a/crates/xlsx/tests/xlsx.rs
+++ b/crates/xlsx/tests/xlsx.rs
@@ -168,6 +168,41 @@ fn a_missing_shared_strings_part_is_a_warning() {
     assert!(wb.warnings.iter().any(|w| w.contains("missing part xl/sharedStrings.xml")), "{:?}", wb.warnings);
 }
 
+#[test]
+fn shared_strings_at_the_conventional_path_work_without_a_relationship() {
+    const REL_NS: &str = "http://schemas.openxmlformats.org/package/2006/relationships";
+    const DOC_REL: &str = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+    const MAIN: &str = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+    let root_rels =
+        format!(r#"<Relationships xmlns="{REL_NS}"><Relationship Id="w" Type="{DOC_REL}/officeDocument" Target="xl/workbook.xml"/></Relationships>"#);
+    let workbook = format!(r#"<workbook xmlns="{MAIN}" xmlns:r="{DOC_REL}"><sheets><sheet name="S" sheetId="1" r:id="s"/></sheets></workbook>"#);
+    let workbook_rels = format!(
+        r#"<Relationships xmlns="{REL_NS}"><Relationship Id="s" Type="{DOC_REL}/worksheet" Target="worksheets/sheet1.xml"/></Relationships>"#
+    );
+    let worksheet = format!(r#"<worksheet xmlns="{MAIN}"><sheetData><row r="1"><c r="A1" t="s"><v>0</v></c></row></sheetData></worksheet>"#);
+    let strings = format!(r#"<sst xmlns="{MAIN}"><si><t>Tea</t></si></sst>"#);
+    let bytes = zip(&[
+        ("_rels/.rels", root_rels.as_bytes()),
+        ("xl/workbook.xml", workbook.as_bytes()),
+        ("xl/_rels/workbook.xml.rels", workbook_rels.as_bytes()),
+        ("xl/worksheets/sheet1.xml", worksheet.as_bytes()),
+        ("xl/sharedStrings.xml", strings.as_bytes()),
+    ]);
+
+    let mut package = Package::open(&bytes, &Limits::default()).unwrap();
+    let strings = package.shared_strings().unwrap();
+    assert_eq!(strings.iter().map(|item| item.text.as_ref()).collect::<Vec<_>>(), ["Tea"]);
+    let workbook = package.workbook().unwrap();
+    let mut values = Vec::new();
+    package
+        .sheet(&workbook.sheets[0], |row| {
+            values.extend(row.cells.into_iter().map(|cell| cell.value.resolve(&strings, false)));
+            Ok(())
+        })
+        .unwrap();
+    assert_eq!(values, [Value::text("Tea")]);
+}
+
 #[test]
 fn limits_are_errors() {
     let rows: String = (1..=2000).map(|r| format!(r#"<row r="{r}"><c r="A{r}"><v>{r}</v></c></row>"#)).collect();
diff --git a/crates/xml/src/lib.rs b/crates/xml/src/lib.rs
index b953690bf..5d3d40f27 100644
--- a/crates/xml/src/lib.rs
+++ b/crates/xml/src/lib.rs
@@ -49,6 +49,9 @@ pub enum Error {
     /// The tree would hold more than [`Limits::max_nodes`] nodes.
     #[error("the XML holds more than {0} nodes")]
     TooManyNodes(usize),
+    /// The tree would hold more than [`Limits::max_elements`] elements.
+    #[error("the XML holds more than {0} elements")]
+    TooManyElements(usize),
     /// One start tag has more than [`Limits::max_attrs`] attributes.
     #[error("an XML element has more than {0} attributes")]
     TooManyAttrs(usize),
@@ -76,6 +79,14 @@ pub enum Error {
 impl Error {
     /// Was a limit exceeded (as opposed to the markup being wrong)?
     pub fn is_limit(&self) -> bool {
-        matches!(self, Error::TooLarge(_) | Error::TooDeep(_) | Error::TooManyNodes(_) | Error::TooManyAttrs(_) | Error::TooManyAttrsTotal(_))
+        matches!(
+            self,
+            Error::TooLarge(_)
+                | Error::TooDeep(_)
+                | Error::TooManyNodes(_)
+                | Error::TooManyElements(_)
+                | Error::TooManyAttrs(_)
+                | Error::TooManyAttrsTotal(_)
+        )
     }
 }
diff --git a/crates/xml/src/read.rs b/crates/xml/src/read.rs
index e155099e8..a4cfdcd36 100644
--- a/crates/xml/src/read.rs
+++ b/crates/xml/src/read.rs
@@ -25,6 +25,10 @@ pub struct Limits {
     /// 2,000,000: a tree node costs about 72 bytes before its strings, and text lies between
     /// elements at most, so this is about a million elements of an indented document.
     pub max_nodes: usize,
+    /// Most elements kept in a tree at once, independent of text nodes. Elements handed to a
+    /// streaming callback leave the count with everything inside them. Default unlimited; the
+    /// node limit already bounds element count for callers using default limits.
+    pub max_elements: usize,
     /// Most attributes on one start tag, namespace declarations and malformed ones included.
     /// With [`Names::Canonical`] it is also the most namespace declarations in scope at once.
     /// Default 1024.
@@ -38,8 +42,14 @@ pub struct Limits {
 }
 
 impl Limits {
-    pub const DEFAULT: Limits =
-        Limits { max_input: 256 * 1024 * 1024, max_depth: 256, max_nodes: 2_000_000, max_attrs: 1024, max_attrs_total: 4_000_000 };
+    pub const DEFAULT: Limits = Limits {
+        max_input: 256 * 1024 * 1024,
+        max_depth: 256,
+        max_nodes: 2_000_000,
+        max_elements: usize::MAX,
+        max_attrs: 1024,
+        max_attrs_total: 4_000_000,
+    };
 }
 
 impl Default for Limits {
@@ -174,6 +184,11 @@ pub struct Options<'a> {
     /// malformed attribute is skipped, and bytes that are not UTF-8 become U+FFFD. Strict: each
     /// of those is an error, as are a second root element and text outside the root.
     pub strict: bool,
+    /// Require closing tags to match their opening tags, and reject unclosed elements at EOF,
+    /// while keeping the other lenient behaviors (including stopping after the first root).
+    /// This is useful when a format historically accepted a single-root prefix but rejected
+    /// malformed nesting.
+    pub strict_end_tags: bool,
     pub unknown_entity: UnknownEntity,
     pub doctype: Doctype,
     /// Keep CDATA sections as [`Node::CData`] instead of joining them to the text around them.
@@ -197,6 +212,7 @@ impl Default for Options<'_> {
             names: Names::AsWritten,
             ns_decls: true,
             strict: false,
+            strict_end_tags: false,
             unknown_entity: UnknownEntity::Drop,
             doctype: Doctype::Ignore,
             cdata: false,
@@ -271,7 +287,7 @@ impl<'a> Options<'a> {
         }
         let text = to_utf8(bytes);
         let mut events = Events::new(*self, &text, false);
-        let mut tree = Builder { opts: self, split, stack: Vec::new(), marks: Vec::new(), kept: 0, attrs: 0, root: None, at: 0 };
+        let mut tree = Builder { opts: self, split, stack: Vec::new(), marks: Vec::new(), kept: 0, elements: 0, attrs: 0, root: None, at: 0 };
         let mut err = tree.run(&mut events, &mut each).err();
         // What was open when the read stopped goes into its parent as it is.
         while let Some(el) = tree.stack.pop() {
@@ -443,9 +459,9 @@ impl<'o, 'i> Events<'o, 'i> {
             }
             Q::End(e) => {
                 let Some(top) = self.open.last() else {
-                    return if self.opts.strict { self.syntax("an end tag has no start tag") } else { Ok(None) };
+                    return if self.opts.strict || self.opts.strict_end_tags { self.syntax("an end tag has no start tag") } else { Ok(None) };
                 };
-                if self.opts.strict && top.raw != e.name().as_ref() {
+                if (self.opts.strict || self.opts.strict_end_tags) && top.raw != e.name().as_ref() {
                     return self.syntax(format!("the end tag `{}` does not match its start tag", String::from_utf8_lossy(e.name().as_ref())));
                 }
                 self.end()
@@ -485,7 +501,11 @@ impl<'o, 'i> Events<'o, 'i> {
             }
             Q::Decl(_) => return Ok(None),
             Q::Eof => {
-                return if self.opts.strict && !self.open.is_empty() { self.syntax("an element is not closed") } else { Ok(Some(None)) };
+                return if (self.opts.strict || self.opts.strict_end_tags) && !self.open.is_empty() {
+                    self.syntax("an element is not closed")
+                } else {
+                    Ok(Some(None))
+                };
             }
         };
         Ok(Some(Some(event)))
@@ -614,7 +634,7 @@ impl<'o, 'i> Events<'o, 'i> {
         let keep_name = self.end_names || canonical.is_some_and(|c| c.element.is_some());
         self.open.push(Open {
             scope,
-            raw: if self.opts.strict { raw.as_ref().to_vec() } else { Vec::new() },
+            raw: if self.opts.strict || self.opts.strict_end_tags { raw.as_ref().to_vec() } else { Vec::new() },
             name: if keep_name { name.clone() } else { String::new() },
         });
         Ok(Event::Start { name, attrs: out })
@@ -626,8 +646,9 @@ struct Builder<'b, 'o> {
     split: &'b [&'b str],
     stack: Vec<El>,
     /// The node and attribute counts when each open element started.
-    marks: Vec<(usize, usize)>,
+    marks: Vec<(usize, usize, usize)>,
     kept: usize,
+    elements: usize,
     /// Attributes in the elements built so far and not handed out.
     attrs: usize,
     root: Option<El>,
@@ -686,7 +707,11 @@ impl Builder<'_, '_> {
                 if self.root.is_some() {
                     return Err(Error::Syntax { at: self.at, msg: "more than one root element".into() }.into());
                 }
-                self.marks.push((self.kept, self.attrs));
+                self.marks.push((self.kept, self.attrs, self.elements));
+                self.elements = self.elements.saturating_add(1);
+                if self.elements > self.opts.limits.max_elements {
+                    return Err(Error::TooManyElements(self.opts.limits.max_elements).into());
+                }
                 self.attrs = self.attrs.saturating_add(attrs.len());
                 if self.attrs > self.opts.limits.max_attrs_total {
                     return Err(Error::TooManyAttrsTotal(self.opts.limits.max_attrs_total).into());
@@ -710,7 +735,7 @@ impl Builder<'_, '_> {
 
     /// Attaches a complete element to its parent, hands it out, or makes it the root.
     fn finish<E: From<Error>>(&mut self, mut el: El, each: &mut impl FnMut(El) -> Result<(), E>) -> Result<(), E> {
-        let (mark, attrs_mark) = self.marks.pop().unwrap_or((0, 0));
+        let (mark, attrs_mark, elements_mark) = self.marks.pop().unwrap_or((0, 0, 0));
         if self.opts.drop_blank_text && el.children.iter().any(|n| matches!(n, Node::El(_))) {
             let is_text = |n: &Node| matches!(n, Node::Text(_));
             if el.children.iter().all(|n| !is_text(n) || matches!(n, Node::Text(t) if t.trim().is_empty())) {
@@ -727,6 +752,7 @@ impl Builder<'_, '_> {
             each(el)?;
             // The element and everything inside it have left the tree.
             self.kept = mark;
+            self.elements = elements_mark;
             self.attrs = attrs_mark;
         } else {
             self.push(Node::El(el))?;
diff --git a/crates/xml/tests/hostile.rs b/crates/xml/tests/hostile.rs
index 8535d5835..2d387519b 100644
--- a/crates/xml/tests/hostile.rs
+++ b/crates/xml/tests/hostile.rs
@@ -22,14 +22,40 @@ fn text_len(e: &El) -> usize {
 fn the_defaults_are_the_documented_ones() {
     assert_eq!(
         Limits::default(),
-        Limits { max_input: 256 * 1024 * 1024, max_depth: 256, max_nodes: 2_000_000, max_attrs: 1024, max_attrs_total: 4_000_000 }
+        Limits {
+            max_input: 256 * 1024 * 1024,
+            max_depth: 256,
+            max_nodes: 2_000_000,
+            max_elements: usize::MAX,
+            max_attrs: 1024,
+            max_attrs_total: 4_000_000
+        }
     );
-    for e in [Error::TooLarge(1), Error::TooDeep(1), Error::TooManyNodes(1), Error::TooManyAttrs(1), Error::TooManyAttrsTotal(1)] {
+    for e in [
+        Error::TooLarge(1),
+        Error::TooDeep(1),
+        Error::TooManyNodes(1),
+        Error::TooManyElements(1),
+        Error::TooManyAttrs(1),
+        Error::TooManyAttrsTotal(1),
+    ] {
         assert!(e.is_limit(), "{e}");
     }
     assert!(!Error::NoRoot.is_limit() && !Error::Doctype.is_limit());
 }
 
+#[test]
+fn strict_end_tags_keep_first_root_and_entity_compatibility() {
+    let opts = Options { strict_end_tags: true, unknown_entity: UnknownEntity::Literal, doctype: Doctype::Ignore, ..Options::default() };
+    let root = opts.parse(b"<!DOCTYPE a [<!ENTITY ignored 'x'>]><a>&unknown;<b/></a><tail/>").unwrap();
+    assert_eq!(root.name, "a");
+    assert_eq!(root.text().as_ref(), "&unknown;");
+
+    for malformed in [b"<a><b></a>".as_slice(), b"<a><b/>".as_slice(), b"</a><b/>".as_slice()] {
+        assert!(opts.parse(malformed).is_err(), "{}", String::from_utf8_lossy(malformed));
+    }
+}
+
 #[test]
 fn a_depth_bomb_is_refused_at_the_limit() {
     let limits = Limits { max_depth: 8, ..Limits::DEFAULT };
@@ -412,6 +438,23 @@ fn a_node_count_charges_a_budget_shared_by_several_parts() {
     assert_eq!(short.parse(part.as_bytes()), Err(Error::TooManyNodes(200)));
 }
 
+#[test]
+fn element_limits_are_independent_and_streamed_rows_release_them() {
+    let limited = Options::default().with_limits(Limits { max_elements: 2, ..Limits::DEFAULT });
+    assert_eq!(limited.parse(b"<r><a/><b/></r>"), Err(Error::TooManyElements(2)));
+
+    let streaming = Options::default().with_limits(Limits { max_elements: 3, ..Limits::DEFAULT });
+    let mut rows = 0;
+    let root = streaming
+        .parse_streaming(b"<s><row><a/></row><row><b/></row></s>", &["row"], |_| {
+            rows += 1;
+            Ok::<(), Error>(())
+        })
+        .unwrap();
+    assert_eq!(rows, 2);
+    assert!(root.children.is_empty());
+}
+
 /// A part that cannot be read to its end still gives what came before the failure.
 #[test]
 fn a_failed_streaming_read_returns_what_it_had() {
diff --git a/crates/zip/src/archive.rs b/crates/zip/src/archive.rs
index 448e2220b..5739e830a 100644
--- a/crates/zip/src/archive.rs
+++ b/crates/zip/src/archive.rs
@@ -67,12 +67,38 @@ impl<'a> Archive<'a> {
         self.zip.is_empty()
     }
 
+    /// The name at `index`, copied on demand so callers can process hostile directories without
+    /// retaining a second copy of every potentially large name.
+    pub fn entry_name(&mut self, index: usize) -> Result<Option<String>, Error> {
+        if index >= self.zip.len() {
+            return Ok(None);
+        }
+        let file = self.zip.by_index_raw(index).map_err(|error| Error::NotZip(error.to_string()))?;
+        let name = file.name().map_err(|error| Error::NotZip(error.to_string()))?;
+        Ok(Some(name.into_owned()))
+    }
+
+    /// Whether the entry at `index` is a directory according to ZIP filename conventions.
+    pub fn entry_is_dir(&mut self, index: usize) -> Result<Option<bool>, Error> {
+        if index >= self.zip.len() {
+            return Ok(None);
+        }
+        let file = self.zip.by_index_raw(index).map_err(|error| Error::NotZip(error.to_string()))?;
+        Ok(Some(file.is_dir()))
+    }
+
     /// Do two entries share a name? `zip` then keeps one of them, and which one a writer meant
     /// is not known: a format that must not guess refuses the archive.
     pub fn has_duplicate_names(&self) -> bool {
         self.duplicates
     }
 
+    /// Do two entries' compressed data ranges overlap? A format that stores many files in one
+    /// archive can refuse aliases so one payload cannot be expanded and retained repeatedly.
+    pub fn has_overlapping_files(&mut self) -> Result<bool, Error> {
+        self.zip.has_overlapping_files().map_err(|e| Error::NotZip(e.to_string()))
+    }
+
     /// The entry names in the archive's order, folders included. A name that is not text is
     /// left out.
     pub fn names(&self) -> impl Iterator<Item = Cow<'_, str>> {
diff --git a/crates/zip/src/lib.rs b/crates/zip/src/lib.rs
index 4e802d795..452351ee3 100644
--- a/crates/zip/src/lib.rs
+++ b/crates/zip/src/lib.rs
@@ -203,4 +203,42 @@ mod tests {
         assert_eq!(budget.remaining(), 0);
         assert!(budget.charge(u64::MAX).is_err());
     }
+
+    #[test]
+    #[allow(clippy::unwrap_used, clippy::expect_used)]
+    fn archive_reports_entries_that_alias_the_same_payload() {
+        use std::io::Write as _;
+
+        let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
+        let opts = zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+        zip.start_file("first", opts).unwrap();
+        zip.write_all(b"payload").unwrap();
+        zip.shallow_copy_file("first", "alias").unwrap();
+        let bytes = zip.finish().unwrap().into_inner();
+
+        let mut archive = Archive::open(&bytes, Limits { max_entries: 2, max_total_bytes: 100 }).unwrap();
+        assert!(archive.has_overlapping_files().unwrap());
+    }
+
+    #[test]
+    #[allow(clippy::unwrap_used, clippy::expect_used)]
+    fn archive_can_copy_one_name_at_a_time_by_index() {
+        use std::io::Write as _;
+
+        let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
+        let opts = zip::write::SimpleFileOptions::default();
+        zip.start_file("first", opts).unwrap();
+        zip.write_all(b"1").unwrap();
+        zip.start_file("second", opts).unwrap();
+        zip.write_all(b"2").unwrap();
+        zip.start_file("folder\\", opts).unwrap();
+        let bytes = zip.finish().unwrap().into_inner();
+
+        let mut archive = Archive::open(&bytes, Limits { max_entries: 3, max_total_bytes: 10 }).unwrap();
+        assert_eq!(archive.entry_name(0).unwrap().as_deref(), Some("first"));
+        assert_eq!(archive.entry_name(1).unwrap().as_deref(), Some("second"));
+        assert_eq!(archive.entry_is_dir(2).unwrap(), Some(true));
+        assert_eq!(archive.entry_name(2).unwrap().as_deref(), Some("folder\\"));
+        assert_eq!(archive.entry_name(3).unwrap(), None);
+    }
 }
diff --git a/crates/zip/src/write.rs b/crates/zip/src/write.rs
index 2f5d7ca47..e1fdfad9e 100644
--- a/crates/zip/src/write.rs
+++ b/crates/zip/src/write.rs
@@ -20,11 +20,12 @@ pub enum Compression {
 /// timestamp on every entry. Entries are written in the order they are added.
 pub struct Writer {
     zip: zip::ZipWriter<Cursor<Vec<u8>>>,
+    legacy_utf8: bool,
 }
 
 impl Default for Writer {
     fn default() -> Writer {
-        Writer { zip: zip::ZipWriter::new(Cursor::new(Vec::new())) }
+        Writer { zip: zip::ZipWriter::new(Cursor::new(Vec::new())), legacy_utf8: false }
     }
 }
 
@@ -33,7 +34,15 @@ impl Writer {
         Writer::default()
     }
 
-    /// Adds an entry. A name the archive already has is an error.
+    /// Writes the UTF-8 flag and version fields used by the previous dotLottie writer.
+    ///
+    /// This keeps stored archives byte-for-byte stable for existing users while still using the
+    /// shared writer for entry encoding and validation.
+    pub fn legacy_utf8() -> Writer {
+        Writer { legacy_utf8: true, ..Writer::default() }
+    }
+
+    /// Adds an entry from a byte slice. A name the archive already has is an error.
     pub fn add(&mut self, name: &str, data: &[u8], compression: Compression) -> Result<(), Error> {
         let (method, level) = match compression {
             Compression::Stored => (zip::CompressionMethod::Stored, None),
@@ -44,15 +53,113 @@ impl Writer {
             .compression_method(method)
             .compression_level(level)
             .last_modified_time(zip::DateTime::default())
-            // Deflate can grow incompressible data a little, so ZIP64 well before 4 GiB.
             .large_file(data.len() as u64 >= u64::from(u32::MAX) / 2);
         let fail = |e: &dyn std::fmt::Display| Error::Write(format!("{name}: {e}"));
         self.zip.start_file(name, options).map_err(|e| fail(&e))?;
         self.zip.write_all(data).map_err(|e| fail(&e))
     }
 
+    /// Adds an entry by streaming it into the compressor, so large generated entries need not
+    /// first be buffered in memory. A name the archive already has is an error.
+    pub fn add_with(&mut self, name: &str, compression: Compression, write: impl FnOnce(&mut dyn Write) -> std::io::Result<()>) -> Result<(), Error> {
+        let (method, level) = match compression {
+            Compression::Stored => (zip::CompressionMethod::Stored, None),
+            Compression::Deflated => (zip::CompressionMethod::Deflated, Some(6)),
+            Compression::Level(l) => (zip::CompressionMethod::Deflated, Some(i64::from(l.min(9)))),
+        };
+        let options = zip::write::SimpleFileOptions::default()
+            .compression_method(method)
+            .compression_level(level)
+            .last_modified_time(zip::DateTime::default())
+            .large_file(true);
+        let fail = |e: &dyn std::fmt::Display| Error::Write(format!("{name}: {e}"));
+        self.zip.start_file(name, options).map_err(|e| fail(&e))?;
+        write(&mut self.zip).map_err(|e| fail(&e))
+    }
+
     /// The finished archive.
     pub fn finish(self) -> Result<Vec<u8>, Error> {
-        self.zip.finish().map(Cursor::into_inner).map_err(|e| Error::Write(e.to_string()))
+        let mut bytes = self.zip.finish().map(Cursor::into_inner).map_err(|e| Error::Write(e.to_string()))?;
+        if self.legacy_utf8 {
+            patch_legacy_utf8_headers(&mut bytes)?;
+        }
+        Ok(bytes)
     }
 }
+
+fn get_u16(bytes: &[u8], at: usize) -> Option<u16> {
+    Some(u16::from_le_bytes(bytes.get(at..at.checked_add(2)?)?.try_into().ok()?))
+}
+
+fn get_u32(bytes: &[u8], at: usize) -> Option<u32> {
+    Some(u32::from_le_bytes(bytes.get(at..at.checked_add(4)?)?.try_into().ok()?))
+}
+
+fn put_u32(bytes: &mut [u8], at: usize, value: u32) -> Result<(), Error> {
+    let dst = bytes
+        .get_mut(at..at.checked_add(4).ok_or_else(|| Error::Write("ZIP header offset overflow".into()))?)
+        .ok_or_else(|| Error::Write("short ZIP header".into()))?;
+    dst.copy_from_slice(&value.to_le_bytes());
+    Ok(())
+}
+
+fn put_u16(bytes: &mut [u8], at: usize, value: u16) -> Result<(), Error> {
+    let dst = bytes
+        .get_mut(at..at.checked_add(2).ok_or_else(|| Error::Write("ZIP header offset overflow".into()))?)
+        .ok_or_else(|| Error::Write("short ZIP header".into()))?;
+    dst.copy_from_slice(&value.to_le_bytes());
+    Ok(())
+}
+
+/// Patches the two header versions and UTF-8 bit to match the former dotLottie writer.
+fn patch_legacy_utf8_headers(bytes: &mut [u8]) -> Result<(), Error> {
+    const EOCD: u32 = 0x0605_4b50;
+    const CENTRAL: u32 = 0x0201_4b50;
+    const LOCAL: u32 = 0x0403_4b50;
+    let eocd = bytes
+        .windows(4)
+        .rposition(|window| u32::from_le_bytes([window[0], window[1], window[2], window[3]]) == EOCD)
+        .ok_or_else(|| Error::Write("missing ZIP end record".into()))?;
+    let central_start = usize::try_from(get_u32(bytes, eocd + 16).ok_or_else(|| Error::Write("short ZIP end record".into()))?)
+        .map_err(|_| Error::Write("ZIP central directory offset overflow".into()))?;
+    let central_size = usize::try_from(get_u32(bytes, eocd + 12).ok_or_else(|| Error::Write("short ZIP end record".into()))?)
+        .map_err(|_| Error::Write("ZIP central directory size overflow".into()))?;
+    let central_end =
+        central_start.checked_add(central_size).filter(|end| *end <= eocd).ok_or_else(|| Error::Write("invalid ZIP central directory".into()))?;
+    let mut at = central_start;
+    while at < central_end {
+        if get_u32(bytes, at) != Some(CENTRAL) {
+            return Err(Error::Write("invalid ZIP central directory entry".into()));
+        }
+        let name = usize::from(get_u16(bytes, at + 28).ok_or_else(|| Error::Write("short ZIP entry".into()))?);
+        let extra = usize::from(get_u16(bytes, at + 30).ok_or_else(|| Error::Write("short ZIP entry".into()))?);
+        let comment = usize::from(get_u16(bytes, at + 32).ok_or_else(|| Error::Write("short ZIP entry".into()))?);
+        let length = 46usize
+            .checked_add(name)
+            .and_then(|n| n.checked_add(extra))
+            .and_then(|n| n.checked_add(comment))
+            .ok_or_else(|| Error::Write("ZIP entry size overflow".into()))?;
+        let next = at.checked_add(length).filter(|next| *next <= central_end).ok_or_else(|| Error::Write("short ZIP entry".into()))?;
+        let local = usize::try_from(get_u32(bytes, at + 42).ok_or_else(|| Error::Write("short ZIP entry".into()))?)
+            .map_err(|_| Error::Write("ZIP local-header offset overflow".into()))?;
+        if get_u32(bytes, local) != Some(LOCAL) {
+            return Err(Error::Write("invalid ZIP local header".into()));
+        }
+        // Version 45 is required by ZIP64; retain it. Ordinary entries use 2.0 to match dotLottie.
+        if get_u16(bytes, at + 6).is_some_and(|version| version < 45) {
+            put_u16(bytes, at + 6, 20)?;
+            put_u16(bytes, local + 4, 20)?;
+        }
+        put_u16(bytes, at + 4, 20)?;
+        put_u32(bytes, at + 38, 0)?;
+        let central_flags = get_u16(bytes, at + 8).ok_or_else(|| Error::Write("short ZIP entry".into()))? | 0x0800;
+        let local_flags = get_u16(bytes, local + 6).ok_or_else(|| Error::Write("short ZIP local header".into()))? | 0x0800;
+        put_u16(bytes, at + 8, central_flags)?;
+        put_u16(bytes, local + 6, local_flags)?;
+        at = next;
+    }
+    if at != central_end {
+        return Err(Error::Write("invalid ZIP central directory size".into()));
+    }
+    Ok(())
+}
diff --git a/licenses/dwg/acadrust-MPL-2.0.txt b/licenses/dwg/acadrust-MPL-2.0.txt
new file mode 100644
index 000000000..16bfd9043
--- /dev/null
+++ b/licenses/dwg/acadrust-MPL-2.0.txt
@@ -0,0 +1,374 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under the name "LEGAL", and included in all Covered Software
+distributed in Source Code Form. Except to the extent prohibited by
+statute or regulation, such description must be sufficiently detailed
+for a recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or   *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.
diff --git a/licenses/dwg/acadrust-THIRD_PARTY_NOTICES.md b/licenses/dwg/acadrust-THIRD_PARTY_NOTICES.md
new file mode 100644
index 000000000..35fd822bb
--- /dev/null
+++ b/licenses/dwg/acadrust-THIRD_PARTY_NOTICES.md
@@ -0,0 +1,40 @@
+# Third-Party Notices
+
+## ACadSharp
+
+The DWG reader and writer include code ported and adapted from ACadSharp. The repository
+history's initial DWG support commit identifies the source classes explicitly, including
+`DwgStreamReaderBase`, `DwgLZ77AC21Decompressor`, `DwgFileHeaderWriterAC18`, and
+`DwgObjectWriter`. Their current Rust implementations are in `src/io/dwg`.
+
+Copyright (c) 2021 Albert Domenech
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## DWG Format References
+
+DWG field layouts and version behavior are based on the Open Design Alliance (ODA) DWG
+specification and reverse engineering, including comparison with drawings produced by CAD
+applications. LibreDWG is used as a secondary cross-check for selected field names and
+layouts. The Reed-Solomon tests cite numeric reference values from LibreDWG's
+`src/reedsolomon.c` to validate the Rust implementation; those values are test data, not
+translated routines. The repository history and source review found no LibreDWG routines
+ported into the implementation. The source comments identify the specific cross-checks.