# Consumer contract
`CodeDocument::new(id, documentation, language, code)` represents exactly the authored `Documentation.md` bytes and one UTF-8 `Code.js`, `Code.html`, or `Code.css`. `id`, `documentation`, `language`, `code`, and `dependencies` are available through accessors. `to_source_package` creates the runtime projection; `from_source_package` accepts only the exact projection this version creates. `DocumentError` implements the standard error traits.
`Documentation.md` starts byte-for-byte with three LF-delimited lines: `<!-- k1-web/v1`, one canonical compact JSON object shaped as `{"dependencies":[{"authority":"...","name":"...","selector":"..."}]}`, and `-->`. Dependency objects have exactly those ordered, nonempty string fields. Unknown, missing, duplicate, noncanonical, or semantically invalid declarations are rejected. Authored documentation and code bytes, including a UTF-8 BOM, line endings, and final newline, are never normalized.
The runtime projection is canonical. Files are returned in path order. JavaScript has `Code.js`, `Documentation.md`, and `k1-web.json`; both manifest targets are `Code.js`, whose module must export async-compatible `runTests`. HTML and CSS have `Code.html` or `Code.css`, `Documentation.md`, `k1-entry.js`, `k1-tests.js`, and `k1-web.json`. HTML's fixed adapters load `Code.html` in a hidden same-origin frame and invoke `globalThis.runTests` in that window. CSS's fixed adapters load `Code.css`, force CSSOM access, and provide only that generated test; executable custom tests require HTML. Manifest dependencies are ordered lexically by authority, name, and selector. Generated JSON has no whitespace or trailing newline; generated adapters have the fixed bytes in this package and one final LF.
`chunk_ranges` returns continuous byte ranges whose slices concatenate to the exact code. Preferred JavaScript boundaries follow complete module statements/declarations and direct class members while lexical strings, templates, regular expressions, comments, and nested bodies remain intact. Preferred CSS boundaries follow complete rules and nested rule closures without cutting lexical values. HTML boundaries follow complete nodes or text spans; JavaScript and CSS raw elements use their lexical safety, and non-JavaScript raw scripts are indivisible. Unsupported or unbalanced input returns one complete range.
Packing selects the earliest preferred boundary at or after 800 Unicode scalar values only when the remainder is empty or has at least 800 scalars. Thus a short tail merges backward, a whole file below 800 scalars is one range, and an indivisible construct has no maximum. Empty code returns `0..0`. Work is unbenchmarked and linear in input apart from scalar-count packing across preferred boundaries.