rtf-codec 0.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Mearman
+
+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.

package/README.md

@@ -0,0 +1,226 @@
+# rtf-codec
+
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/rtf-codec) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/rtf-codec) [![npm version](https://img.shields.io/npm/v/rtf-codec)](https://www.npmjs.com/package/rtf-codec) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions)
+
+> A hand-written, dependency-minimal Rich Text Format codec: reads RTF into the shared [document-schema.js](../document-schema.js/README.md) content pivot, and writes deterministic, 7-bit-ASCII RTF back out. Built against Microsoft's own [RTF Specification, version 1.9.1](#the-specification) and [Zod 4](https://zod.dev), with no third-party RTF library.
+
+**Status: under active development.** The read and write paths described below are implemented and tested, but this package is new and has not yet been exercised against a real-world corpus. [Scope](#scope) states exactly what is handled and what is not; nothing in this README describes work that is planned rather than done.
+
+Every construct that remains unhandled is either a gap in `document-schema.js` rather than in this codec (superscript/subscript and text direction have no field to land in), or something RTF itself does not specify (it has no content-control equivalent at all) — see [Deliberately not handled](#deliberately-not-handled), which says which of the two each row is.
+
+RTF is the cleanest structural fit of any format this family did not already handle. It is a wordprocessing format through and through — paragraphs, runs, character properties, paragraph properties, tables, lists and pictures all have direct `ContentDocument` equivalents — and it can express more of the wordprocessing variant than markdown can, carrying colour, font family, font size and alignment natively. No `document-schema.js` model change was needed for it.
+
+What it is _not_ is another XML format. RTF is tokenised plain text with a brace-nested group and destination model, so none of the XML plumbing `ooxml.js` and `odf.js` share applies here: this package carries its own byte lexer, its own destination state machine, its own `\uN`/`\ucN` Unicode handling with code-page fallback, and its own parsers for the five header mini-formats. The closest relative in this workspace is `markdown-codec`, which is likewise a hand-written scanner and parser for a non-XML text format rather than a wrapper around a document library.
+
+```mermaid
+graph TD
+    schema("document-schema.js")
+    rtfcodec("rtf-codec")
+
+    schema --> rtfcodec
+
+    click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
+    click rtfcodec "https://github.com/ExaDev/documents.js/tree/main/packages/rtf-codec" "rtf-codec"
+
+    style rtfcodec fill:#f9a825,stroke:#333,stroke-width:3px
+```
+
+`rtf-codec` depends on nothing else in this family beyond `document-schema.js` — see [Dependency choices](#dependency-choices). It is reachable from [`documents.js`](../documents.js/README.md)'s conversion engine, and so from `document-cli`, `document-mcp`, and the web UI, as an ordinary source and target format.
+
+## Getting started
+
+```sh
+pnpm add rtf-codec
+```
+
+```ts
+import { readRtf, writeRtf, readRtfContent, writeRtfContent } from "rtf-codec";
+
+// The tree-form pair, over document-schema.js's DocumentTree -- what to reach for by default.
+const { documentPackage, diagnostics } = readRtf(await file.bytes());
+const bytes = writeRtf(documentPackage);
+
+// The flat pair, over its ContentDocument -- the shape the reader itself builds.
+const { document } = readRtfContent(await file.bytes());
+const flatBytes = writeRtfContent(document);
+```
+
+Every entry point takes **bytes**, not a string. RTF is defined over bytes: `\'hh` names a raw byte decoded through whichever code page the document declared, and `\binN` is followed by literally N arbitrary bytes. A caller who has already decoded a `.rtf` file as UTF-8 has destroyed exactly the information the code-page layer needs. For the one string form that genuinely still holds bytes — a file read with a latin-1/binary reader — `rtfBytesFromLatin1` converts it exactly, and throws above U+00FF rather than truncating.
+
+Both encodings are also available as [`z.codec()`](https://zod.dev) pairs, matching the convention `markdown-codec` and `pdf-codec` already follow:
+
+```ts
+import { rtfCodec, rtfContentCodec, RtfBytesSchema } from "rtf-codec";
+
+const documentPackage = rtfCodec.parse(bytes); // bytes -> DocumentTree
+const roundTripped = rtfCodec.encode(documentPackage); // DocumentTree -> bytes
+```
+
+`RtfBytesSchema` is a real magic-byte check — the `<File>` production requires an RTF document to begin `{\rtf`, so a caller handing the codec a docx or a PDF is refused at the schema boundary rather than deep inside the tokenizer.
+
+## The specification
+
+Everything here is implemented against Microsoft's own **Rich Text Format (RTF) Specification, Version 1.9.1** (March 2008, 278 pages) — the final revision, covering Word 2007. Each source module cites the section it implements by name.
+
+- Primary source: [`[MSFT-RTF].pdf`](https://officeprotocoldoc.z19.web.core.windows.net/files/Archive_References/%5BMSFT-RTF%5D.pdf), hosted in Microsoft's own Office protocol documentation archive.
+- Microsoft's original download page: <https://www.microsoft.com/en-us/download/details.aspx?id=10725> ([Wayback snapshot](https://web.archive.org/web/2024/https://www.microsoft.com/en-us/download/details.aspx?id=10725)).
+- The version history and the note that 1.9.1 is the final revision: [Rich Text Format on Wikipedia](https://en.wikipedia.org/wiki/Rich_Text_Format) ([Wayback snapshot](https://web.archive.org/web/2025/https://en.wikipedia.org/wiki/Rich_Text_Format)).
+- Format-preservation context: [Library of Congress, Sustainability of Digital Formats — RTF](https://www.loc.gov/preservation/digital/formats/fdd/fdd000473.shtml) ([Wayback snapshot](https://web.archive.org/web/2024/https://www.loc.gov/preservation/digital/formats/fdd/fdd000473.shtml)).
+
+The code-page tables in `src/codepage.ts` were **generated, not transcribed**: each is `bytes([b]).decode(codec)` over `0x80..0xFF` from Python's own codec library, verified byte-for-byte against it, because a hand-typed 128-entry table is exactly where one transposed character hides until a real document decodes wrong.
+
+## Architecture
+
+Five stages, each its own module, each testable on its own:
+
+| Stage  | Module            | What it does                                                                                                                                                                                                                                    |
+| ------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Lex    | `src/tokenize.ts` | Bytes to a flat token stream: control words (32-letter name cap, 10-digit signed parameter, one-space delimiter), control symbols (no delimiter at all), the `\'hh` hex byte as its own token kind, `\binN`'s raw byte run, and CR/LF handling. |
+| Group  | `src/group.ts`    | Brace matching and destination identification — the two structural facts every stage above the lexer needs.                                                                                                                                     |
+| Header | `src/header.ts`   | The five header mini-formats: `\fonttbl`, `\colortbl`, `\stylesheet`, `\listtable` and `\listoverridetable`, plus `\info` and the document properties, in one pass ahead of the body.                                                           |
+| Read   | `src/read.ts`     | The destination/group state machine that turns the token stream into a `ContentDocument`.                                                                                                                                                       |
+| Write  | `src/write.ts`    | The inverse: mints the header tables from what the document actually uses, then emits a body that references them by index.                                                                                                                     |
+
+Supporting modules: `src/codepage.ts` (byte-to-character tables and the `\ansicpgN`/`\fcharsetN`/`\cpgN` precedence), `src/base64.ts` (hex and base64 conversion for picture payloads), `src/units.ts` (twips, half-points, pixels), `src/list-id.ts` (the opaque `numId` grammar), `src/constructs.ts` (the fidelity-construct descriptor shapes and the DTTM bit field), `src/cell-format.ts` (the `<celldef>` border, shading, and merge production), `src/diagnostics.ts` (the three-tier diagnostic policy).
+
+### The reader is the specification's own model, literally
+
+"Conventions of an RTF Reader" states the model this reader implements exactly: an opening brace stores the current state on a stack, a closing brace retrieves it, a backslash collects a control word or symbol and dispatches on it, and anything else is text written "to the current destination using the current formatting properties". Four kinds of state ride that stack, as the spec enumerates them — destination, character properties, paragraph properties, table properties — plus the `\ucN` skip count, which the spec separately requires be stacked.
+
+The destination is not merely a label: it decides what happens to text. Body text becomes runs; a `\pict` destination's text is hex picture payload; a `\fldinst` destination's text is a field instruction to be parsed rather than shown; a `\listtext` destination's text is the flat rendering of a list number that "should be ignored by any reader that understands Word 97 through Word 2007 numbering"; an unrecognised `{\*` destination's text is discarded whole. That mapping is what lets the reader be a single pass with no lookahead beyond a group's own head.
+
+### Tables are paragraph properties, not a group
+
+"There is no RTF table group; instead, tables are specified as paragraph properties." A row is a run of `\intbl` paragraphs terminated by `\cell` marks and closed by `\row`, with the row's own `\trowd ... \cellxN` definition sitting before it, after it, or — for Word 2002 onward — both. The table builder is therefore driven by the `\cell`/`\row` marks in the text stream rather than by nesting, and a table closes when a non-table paragraph arrives.
+
+### Unicode
+
+`\uN` carries the character and is followed by an ANSI approximation a Unicode-aware reader must skip: "the reader should ignore the next N' characters, where N' corresponds to the last `\ucN'` value encountered", where "any RTF control word or symbol is considered a single character" and a brace ends the skippable run early. All three of those rules are implemented, including partial consumption of a text run — which is why the main loop carries a byte offset alongside its token index. `{\upr {ansi} {\*\ud unicode}}` pairs take the `\ud` half and discard the ANSI one.
+
+On the way out, **every non-ASCII character leaves as `\uN`** with a one-character `?` fallback under a single `\uc1`. The writer deliberately does not hunt for a code page that could carry a character as a `\'hh` byte: the output is then pure 7-bit ASCII whatever the input contained, which is what makes it safe to transmit and trivially diffable, and costs a conforming reader nothing.
+
+## Scope
+
+### Read: RTF → `ContentDocument`
+
+| Construct                                                | Handled                                                                                                                                             |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Groups, destinations, `{\*` ignorable destinations       | Yes — per the spec's own reader conventions                                                                                                         |
+| Control words, control symbols, `\'hh`, `\binN`          | Yes                                                                                                                                                 |
+| `\uN` / `\ucN` with ANSI fallback skipping, `\upr`/`\ud` | Yes                                                                                                                                                 |
+| Code pages                                               | `\ansi`/`\mac`/`\pc`/`\pca`, `\ansicpgN`, per-font `\cpgN`/`\fcharsetN`; the Windows, OEM and Macintosh single-byte pages, plus UTF-8               |
+| `\fonttbl`                                               | Face name, family keyword, per-font code page                                                                                                       |
+| `\colortbl`                                              | RGB, including a theme colour's own literal RGB; index 0 is the auto colour                                                                         |
+| `\stylesheet`                                            | Paragraph style names and heading levels (`\outlinelevelN` or a built-in `heading N` name)                                                          |
+| `\listtable` / `\listoverridetable`                      | `\lsN` → `\listidN` → the level's `\levelnfcN` and `\levelstartatN`, with each `\lfolevel`'s own start-at or whole-level override applied           |
+| `\*\revtbl`                                              | The revision authors `\revauthN` and its siblings index into                                                                                        |
+| Sections                                                 | `\sect`, `\sectd`, the `\pgwsxnN`/`\marg*sxnN` geometry family, and the `\sbk*` break vocabulary                                                    |
+| Paragraphs                                               | `\par`, `\pard`, alignment, indents, spacing, `\slN`/`\slmultN`, `\pagebb`                                                                          |
+| Runs                                                     | `\b`, `\i`, `\ul` (every variant), `\strike`, `\fN`, `\fsN`, `\cfN`, `\v` (dropped as hidden)                                                       |
+| Tables                                                   | `\trowd`, `\cellxN`, `\trleftN`, `\cell`, `\row`, multi-paragraph cells                                                                             |
+| Table cells                                              | `\clbrdrt`/`l`/`b`/`r` with the whole `<brdr>` production, `\clcbpatN` shading, and both merge families (`\clvmgf`/`\clvmrg`, `\clmgf`/`\clmrg`)    |
+| Bookmarks                                                | `\*\bkmkstart`/`\*\bkmkend` as `anchor` constructs, with `\bkmkcolfN`/`\bkmkcollN` quarantined as residue                                           |
+| Revision marks                                           | The whole `<chrev>` production as `provenance` constructs: `\revised`, `\deleted`, `\mvf`/`\mvt`, `\crauthN`, with authors and `\revdttmN` dates    |
+| Lists                                                    | `\lsN`, `\ilvlN`, with the marker type carried through the `numId` grammar                                                                          |
+| Pictures                                                 | `\pngblip` and `\jpegblip`, hex or `\binN` payload, `\picwgoalN`/`\pichgoalN` or `\picwN`/`\pichN`, `\picscalexN`/`\picscaleyN`                     |
+| Hyperlinks                                               | The `HYPERLINK` field production, including its `\l` anchor switch                                                                                  |
+| Special characters                                       | `\tab`, `\line`, `\emdash`, `\endash`, `\bullet`, the quotation marks, `\~`, `\-`, `\_`, `\\`, `\{`, `\}`, and the zero-width and directional marks |
+| Page breaks                                              | `\page`                                                                                                                                             |
+| `\info`                                                  | Title, author, subject, keywords                                                                                                                    |
+
+### Write: `ContentDocument` → RTF
+
+Everything in the read table above has a write path, with the header tables minted from what the document actually uses: a font table entry per distinct family, a colour table per distinct colour (runs' and cells' alike), a `heading N` style per distinct heading level, a `\listtable`/`\listoverridetable` pair per distinct list, and a `\*\revtbl` per distinct revision author. Output is deterministic (the same document produces byte-identical bytes) and pure 7-bit ASCII.
+
+Two places where the two models genuinely differ in shape, rather than merely in spelling:
+
+- **Page geometry is stated twice.** The document-level `\paperwN` family is written once in the header from the first section's own geometry, and the section-level `\pgwsxnN` family per section — so a reader that understands neither multiple sections nor the section family still lays the document out on the right paper.
+- **A horizontally merged cell is one cell here and several there.** `ContentTableCell` states a `colSpan` on one cell, while RTF states the same merge as several cells, the first carrying `\clmgf` and each continuation `\clmrg`. The writer expands one into the other, and the reader collapses it back. A _vertical_ merge is the opposite: RTF and the content model both keep a cell in each covered row, so `\clvmrg` reads as a cell with no blocks — the convention `ooxml.js` already follows for `w:vMerge`.
+
+### Deliberately not handled
+
+Each of these is reported through a diagnostic rather than dropped silently — see [Diagnostics](#diagnostics).
+
+| Construct                                                                                                                  | Why                                                                                                                                                                                                                                                                                                                                           |
+| -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Headers, footers, footnotes, endnotes, annotations                                                                         | `ContentDocument`'s flat form has no page-furniture or note position for them. A footnote's real home is `document-schema.js`'s tree-only `definitions` table, which a codec producing the flat form cannot reach.                                                                                                                            |
+| Content controls                                                                                                           | **RTF 1.9.1 specifies none.** It predates OOXML's `w:sdt`: its "Custom XML Tags" (`\xmlopen`/`\xmlclose`) are a bare namespace/name tag with no type, lock, alias or value, and `\*\datastore` is an opaque blob whose "format ... is unknown to RTF" by the spec's own words.                                                                |
+| Form fields (`\*\formfield`, with a `FORMTEXT`/`FORMCHECKBOX`/`FORMDROPDOWN` instruction)                                  | RTF's own nearest analogue to a content control, and a real `contentControl` mapping -- `ooxml.js` maps docx's legacy `w:ffData` twin onto exactly that kind. Not mapped yet: it needs the field machinery to hand the control its instruction and cached result.                                                                             |
+| East Asian DBCS code pages (932, 936, 949, 950, 1361)                                                                      | Each needs a ~20k-entry table and its own lead-byte state machine. A document declaring one decodes through cp1252 and says so.                                                                                                                                                                                                               |
+| Code page 42 (`SYMBOL_CHARSET`)                                                                                            | Not an encoding: its bytes are glyph indices into whichever symbol font the run names, so there is no correct Unicode for them without that font's own cmap.                                                                                                                                                                                  |
+| Metafile and bitmap pictures (`\wmetafileN`, `\emfblip`, `\dibitmapN`, `\wbitmapN`, `\macpict`)                            | `ContentImageBlock` carries PNG and JPEG only.                                                                                                                                                                                                                                                                                                |
+| A picture with no stated size                                                                                              | `ContentImageBlock` requires a positive width and height, and deriving them from the payload would need an image decoder this package deliberately does not carry.                                                                                                                                                                            |
+| Nested tables (`\nestcell`/`\nestrow`)                                                                                     | Read as ordinary cell content; the inner table's own structure is not reconstructed.                                                                                                                                                                                                                                                          |
+| Embedded objects (`\object`), drawing objects (`\do`, `\shp`)                                                              | Dropped. Writing one would need the OLE container this package does not build.                                                                                                                                                                                                                                                                |
+| Superscript/subscript (`\super`, `\sub`, `\upN`, `\dnN`), character scaling, kerning, background colour                    | **A schema gap, not an RTF one.** `ContentRun` carries no vertical-alignment field at all -- `epub-codec` reports the identical gap for its own `<sub>`/`<sup>`, and `ooxml.js`'s docx reader has no `w:vertAlign` handling either. Closing it is a change to `document-schema.js` and every codec that would then carry it, not to this one. |
+| Right-to-left text (`\rtlch`, `\ltrch`, `\rtlpar`, `\rtlrow`, `\rtldoc`)                                                   | The same shape of gap: no `ContentDocument` field carries text direction, at any of the four scopes RTF states it at.                                                                                                                                                                                                                         |
+| Cell vertical alignment (`\clvertalt`/`\clvertalc`/`\clvertalb`), diagonal cell borders (`\cldglu`/`\cldgll`), `\clshdngN` | `ContentTableCell` carries per-side borders and one background colour and nothing else -- a diagonal rule is not a side, and a shading percentage is a pattern rather than a colour.                                                                                                                                                          |
+| A bookmark whose two halves straddle a table cell wall                                                                     | `document-schema.js` ratifies this as a drop rather than a shape to repair: each block list is its own bracket scope, and pairing across two of them would need the marker ids its contract deliberately refuses.                                                                                                                             |
+
+## Diagnostics
+
+The same three-tier policy `markdown-codec` and `pdf-codec` use: **throw** for input that cannot be processed at all, **recover with a diagnostic** for input that is malformed in a way the spec's own robustness advice says to survive, and **degrade with a diagnostic** for a construct read correctly at the token level whose meaning the `ContentDocument` mapping does not carry.
+
+That third tier does more work here than in the XML formats. The spec _requires_ an unknown control word to be ignored and an unknown `{\*` destination to be skipped whole, so "I did not understand this" is the format's normal operating mode rather than an error condition — but a reader that silently drops a construct a caller cared about is indistinguishable from one that never saw it. Every drop this package makes deliberately therefore names itself through a code in `RtfDiagnosticCodes`.
+
+```ts
+import { readRtf, RtfDiagnosticCodes } from "rtf-codec";
+
+const { documentPackage, diagnostics } = readRtf(bytes);
+const droppedPictures = diagnostics.filter(
+  (diagnostic) =>
+    diagnostic.code === RtfDiagnosticCodes.UNSUPPORTED_PICTURE_FORMAT,
+);
+```
+
+A coverage suite proves every code in `RtfDiagnosticCodes` is reachable by producing each one from a real input, and fails if any has no fixture — so the table cannot grow an entry nothing can emit, and a construct that stops being dropped has its code removed rather than left behind as a promise the package no longer keeps.
+
+The throw tier is `RtfNotAnRtfDocumentError` (no `{\rtf` header), `RtfInputTooLargeError` and `RtfNestingLimitExceededError` (the two resource guards, both configurable through `ReadRtfOptions`), and `RtfUnsupportedDocumentKindError` on the write side, since RTF is a wordprocessing format and a presentation, spreadsheet, drawing or formula document has no RTF spelling.
+
+## Dependency choices
+
+`document-schema.js` and `zod`, and nothing else. Every third-party RTF library is banned **by name** in this package's own `eslint.config.ts` — `rtf-parser`, `rtf.js`, `rtf-stream-parser`, `node-rtf`, `jsrtf`, `@shelf/rtf-to-html` — the same bet `markdown-codec` makes against micromark/remark/marked and `pdf-codec` makes against pdf-lib/pdfjs-dist. Depending on one would defeat the reason this package exists.
+
+`iconv-lite` is banned for a second reason on top of that: it is Node-only (it is built on `Buffer`), so depending on it would break this package's Worker isomorphism. The code-page tables in `src/codepage.ts` exist instead.
+
+It deliberately does **not** depend on `byte-codec`, even though that package has the base64 and byte-writing primitives `src/base64.ts` reimplements. RTF's picture payload is hex-encoded ASCII inside a text format, not a binary container, so what is actually needed here is about sixty lines of hex and base64 conversion — considerably less than the coupling a dependency on a sibling's release cadence would cost. `epub-codec` made the same call for the same reason.
+
+## Worker isomorphism
+
+Like every foundation and format-codec package in this family, `rtf-codec` is Worker-isomorphic: its published `src/` imports no `node:*` module and uses no `Buffer`, so one artifact behaves identically in a Node host, a browser, and a Cloudflare Worker. The ban is enforced by `isomorphic: true` in this package's `eslint.config.ts`, and `pnpm test:workers` proves it at runtime by running the public surface inside workerd.
+
+Two places would have been tempting to write with a Node-only shortcut, and the workers suite exercises both: `src/base64.ts`'s hand-written encoders (`Buffer.from(bytes).toString("base64")` is the one-liner they exist instead of) and `src/codepage.ts`'s own tables.
+
+## Fidelity constructs and the residue channel
+
+Both of the channels `document-schema.js` defines are live here.
+
+**Channel 1, the harmonised construct vocabulary.** Bookmarks read and write as `anchor` descriptors, and the whole `<chrev>` revision-mark family as `provenance` descriptors. Which of the two flat encodings a construct takes is decided by what it actually spans, exactly as the schema requires: a bookmark opening and closing inside one paragraph is a `RunConstructExtent` on that paragraph, one spanning whole paragraphs is a `constructStart`/`constructEnd` marker pair, and a revision mark — being a character property — is always the former. Content controls are absent because RTF has none; see the gap table above.
+
+**Channel 2, the residue channel.** `SourceFormatSchema` gained its `rtf` member, so this codec can now quarantine what no semantic field carries. `\bkmkcolfN`/`\bkmkcollN` — a bookmark's table-column range — ride the anchor descriptor's own `source`, and the writer restores them verbatim inside its `{\*\bkmkstart …}` when the residue names `rtf` as its format, leaving another format's residue untouched. That decidability is the whole point of the `format` field.
+
+## Build, test, and lint
+
+```sh
+pnpm install
+pnpm build         # tsdown -> ESM + CJS + .d.ts in dist/
+pnpm typecheck     # tsc for the web program and the node program, plus attw --pack
+pnpm lint          # eslint . --fix --cache --max-warnings 0
+pnpm test          # vitest run --project unit
+pnpm test:workers  # the same code inside workerd, the real Cloudflare Workers runtime
+pnpm test:smoke    # rebuilds dist/ and exercises the built ESM and CJS artifacts
+```
+
+To run a single test file: `pnpm vitest run src/read.test.ts`.
+
+## Release and publishing
+
+Release, CI, and commit-message conventions are workspace-wide, not package-local — see the [monorepo root README](../../README.md#releases) for the mechanism.
+
+## Contributing
+
+Conventional Commits, enforced workspace-wide by commitlint through a root `commit-msg` hook. Work inside `packages/rtf-codec/`; see [CONTRIBUTING.md](../../CONTRIBUTING.md) for the shared git hooks and history conventions.
+
+## License
+
+MIT

package/dist/base64.cjs

@@ -0,0 +1,66 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/base64.ts
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const HEX_DIGITS = "0123456789abcdef";
+function bytesToBase64(input) {
+	let out = "";
+	for (let index = 0; index < input.length; index += 3) {
+		const first = input[index] ?? 0;
+		const second = input[index + 1];
+		const third = input[index + 2];
+		out += BASE64_ALPHABET.charAt(first >> 2);
+		out += BASE64_ALPHABET.charAt((first & 3) << 4 | (second ?? 0) >> 4);
+		out += second === void 0 ? "=" : BASE64_ALPHABET.charAt((second & 15) << 2 | (third ?? 0) >> 6);
+		out += third === void 0 ? "=" : BASE64_ALPHABET.charAt(third & 63);
+	}
+	return out;
+}
+function base64Value(character) {
+	const index = BASE64_ALPHABET.indexOf(character);
+	return index === -1 ? void 0 : index;
+}
+function base64ToBytes(input) {
+	const out = [];
+	let accumulator = 0;
+	let bits = 0;
+	for (const character of input) {
+		if (character === "=" || /\s/.test(character)) continue;
+		const value = base64Value(character);
+		if (value === void 0) return;
+		accumulator = accumulator << 6 | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out.push(accumulator >> bits & 255);
+		}
+	}
+	return Uint8Array.from(out);
+}
+function bytesToHex(input) {
+	let out = "";
+	for (const byte of input) {
+		out += HEX_DIGITS.charAt(byte >> 4);
+		out += HEX_DIGITS.charAt(byte & 15);
+	}
+	return out;
+}
+function hexToBytes(input) {
+	const out = [];
+	let high;
+	for (const character of input) {
+		const value = HEX_DIGITS.indexOf(character.toLowerCase());
+		if (value === -1) continue;
+		if (high === void 0) {
+			high = value;
+			continue;
+		}
+		out.push(high * 16 + value);
+		high = void 0;
+	}
+	return Uint8Array.from(out);
+}
+//#endregion
+exports.base64ToBytes = base64ToBytes;
+exports.bytesToBase64 = bytesToBase64;
+exports.bytesToHex = bytesToHex;
+exports.hexToBytes = hexToBytes;

package/dist/base64.d.cts

@@ -0,0 +1,7 @@
+//#region src/base64.d.ts
+declare function bytesToBase64(input: Uint8Array): string;
+declare function base64ToBytes(input: string): Uint8Array | undefined;
+declare function bytesToHex(input: Uint8Array): string;
+declare function hexToBytes(input: string): Uint8Array;
+//#endregion
+export { base64ToBytes, bytesToBase64, bytesToHex, hexToBytes };

package/dist/base64.d.ts

@@ -0,0 +1,7 @@
+//#region src/base64.d.ts
+declare function bytesToBase64(input: Uint8Array): string;
+declare function base64ToBytes(input: string): Uint8Array | undefined;
+declare function bytesToHex(input: Uint8Array): string;
+declare function hexToBytes(input: string): Uint8Array;
+//#endregion
+export { base64ToBytes, bytesToBase64, bytesToHex, hexToBytes };

package/dist/base64.js

@@ -0,0 +1,62 @@
+//#region src/base64.ts
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const HEX_DIGITS = "0123456789abcdef";
+function bytesToBase64(input) {
+	let out = "";
+	for (let index = 0; index < input.length; index += 3) {
+		const first = input[index] ?? 0;
+		const second = input[index + 1];
+		const third = input[index + 2];
+		out += BASE64_ALPHABET.charAt(first >> 2);
+		out += BASE64_ALPHABET.charAt((first & 3) << 4 | (second ?? 0) >> 4);
+		out += second === void 0 ? "=" : BASE64_ALPHABET.charAt((second & 15) << 2 | (third ?? 0) >> 6);
+		out += third === void 0 ? "=" : BASE64_ALPHABET.charAt(third & 63);
+	}
+	return out;
+}
+function base64Value(character) {
+	const index = BASE64_ALPHABET.indexOf(character);
+	return index === -1 ? void 0 : index;
+}
+function base64ToBytes(input) {
+	const out = [];
+	let accumulator = 0;
+	let bits = 0;
+	for (const character of input) {
+		if (character === "=" || /\s/.test(character)) continue;
+		const value = base64Value(character);
+		if (value === void 0) return;
+		accumulator = accumulator << 6 | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out.push(accumulator >> bits & 255);
+		}
+	}
+	return Uint8Array.from(out);
+}
+function bytesToHex(input) {
+	let out = "";
+	for (const byte of input) {
+		out += HEX_DIGITS.charAt(byte >> 4);
+		out += HEX_DIGITS.charAt(byte & 15);
+	}
+	return out;
+}
+function hexToBytes(input) {
+	const out = [];
+	let high;
+	for (const character of input) {
+		const value = HEX_DIGITS.indexOf(character.toLowerCase());
+		if (value === -1) continue;
+		if (high === void 0) {
+			high = value;
+			continue;
+		}
+		out.push(high * 16 + value);
+		high = void 0;
+	}
+	return Uint8Array.from(out);
+}
+//#endregion
+export { base64ToBytes, bytesToBase64, bytesToHex, hexToBytes };

package/dist/bytes.cjs

@@ -0,0 +1,25 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_diagnostics = require("./diagnostics.cjs");
+//#region src/bytes.ts
+const ASCII_CHUNK_SIZE = 8192;
+function asciiStringFromBytes(input) {
+	let out = "";
+	for (let start = 0; start < input.length; start += ASCII_CHUNK_SIZE) out += String.fromCharCode(...input.subarray(start, start + ASCII_CHUNK_SIZE));
+	return out;
+}
+function appendBytes(target, input) {
+	for (const byte of input) target.push(byte);
+}
+function rtfBytesFromLatin1(source) {
+	const out = new Uint8Array(source.length);
+	for (let index = 0; index < source.length; index += 1) {
+		const code = source.charCodeAt(index);
+		if (code > 255) throw new require_diagnostics.RtfParseError("rtf/not-byte-preserving-string", `character at index ${String(index)} is U+${code.toString(16).toUpperCase().padStart(4, "0")}, above U+00FF: this string was decoded through a multi-byte encoding and no longer holds the file's bytes. Read the .rtf file as bytes and pass the Uint8Array directly.`);
+		out[index] = code;
+	}
+	return out;
+}
+//#endregion
+exports.appendBytes = appendBytes;
+exports.asciiStringFromBytes = asciiStringFromBytes;
+exports.rtfBytesFromLatin1 = rtfBytesFromLatin1;

package/dist/bytes.d.cts

@@ -0,0 +1,6 @@
+//#region src/bytes.d.ts
+declare function asciiStringFromBytes(input: Uint8Array): string;
+declare function appendBytes(target: number[], input: Uint8Array): void;
+declare function rtfBytesFromLatin1(source: string): Uint8Array;
+//#endregion
+export { appendBytes, asciiStringFromBytes, rtfBytesFromLatin1 };

package/dist/bytes.d.ts

@@ -0,0 +1,6 @@
+//#region src/bytes.d.ts
+declare function asciiStringFromBytes(input: Uint8Array): string;
+declare function appendBytes(target: number[], input: Uint8Array): void;
+declare function rtfBytesFromLatin1(source: string): Uint8Array;
+//#endregion
+export { appendBytes, asciiStringFromBytes, rtfBytesFromLatin1 };

package/dist/bytes.js

@@ -0,0 +1,22 @@
+import { RtfParseError } from "./diagnostics.js";
+//#region src/bytes.ts
+const ASCII_CHUNK_SIZE = 8192;
+function asciiStringFromBytes(input) {
+	let out = "";
+	for (let start = 0; start < input.length; start += ASCII_CHUNK_SIZE) out += String.fromCharCode(...input.subarray(start, start + ASCII_CHUNK_SIZE));
+	return out;
+}
+function appendBytes(target, input) {
+	for (const byte of input) target.push(byte);
+}
+function rtfBytesFromLatin1(source) {
+	const out = new Uint8Array(source.length);
+	for (let index = 0; index < source.length; index += 1) {
+		const code = source.charCodeAt(index);
+		if (code > 255) throw new RtfParseError("rtf/not-byte-preserving-string", `character at index ${String(index)} is U+${code.toString(16).toUpperCase().padStart(4, "0")}, above U+00FF: this string was decoded through a multi-byte encoding and no longer holds the file's bytes. Read the .rtf file as bytes and pass the Uint8Array directly.`);
+		out[index] = code;
+	}
+	return out;
+}
+//#endregion
+export { appendBytes, asciiStringFromBytes, rtfBytesFromLatin1 };

package/dist/cell-format.cjs

@@ -0,0 +1,142 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_units = require("./units.cjs");
+//#region src/cell-format.ts
+const CELL_BORDER_SIDES = /* @__PURE__ */ new Map([
+	["clbrdrt", "top"],
+	["clbrdrl", "left"],
+	["clbrdrb", "bottom"],
+	["clbrdrr", "right"]
+]);
+const BORDER_STYLES = /* @__PURE__ */ new Map([
+	["brdrs", "solid"],
+	["brdrth", "solid"],
+	["brdrsh", "solid"],
+	["brdrhair", "solid"],
+	["brdrinset", "solid"],
+	["brdroutset", "solid"],
+	["brdrengrave", "solid"],
+	["brdremboss", "solid"],
+	["brdrdot", "dotted"],
+	["brdrdash", "dashed"],
+	["brdrdashsm", "dashed"],
+	["brdrdashd", "dashed"],
+	["brdrdashdd", "dashed"],
+	["brdrdashdot", "dashed"],
+	["brdrdashdotdot", "dashed"],
+	["brdrdashdotstr", "dashed"],
+	["brdrdb", "double"],
+	["brdrtriple", "double"],
+	["brdrwavydb", "double"],
+	["brdrtnthsg", "double"],
+	["brdrthtnsg", "double"],
+	["brdrtnthtnsg", "double"],
+	["brdrtnthmg", "double"],
+	["brdrthtnmg", "double"],
+	["brdrtnthtnmg", "double"],
+	["brdrtnthlg", "double"],
+	["brdrthtnlg", "double"],
+	["brdrtnthtnlg", "double"],
+	["brdrwavy", "solid"]
+]);
+const NO_BORDER_KEYWORDS = /* @__PURE__ */ new Set([
+	"brdrnone",
+	"brdrnil",
+	"brdrtbl"
+]);
+const DEFAULT_BORDER_WIDTH_TWIPS = 15;
+function newPendingCell() {
+	return {
+		borders: {},
+		side: void 0,
+		backgroundIndex: void 0,
+		verticalMergeFirst: false,
+		verticalMergeContinuation: false,
+		horizontalMergeFirst: false,
+		horizontalMergeContinuation: false
+	};
+}
+function applyCellDefinitionControlWord(name, param, cell) {
+	const side = CELL_BORDER_SIDES.get(name);
+	if (side !== void 0) {
+		cell.side = side;
+		cell.borders[side] = {
+			style: void 0,
+			widthTwips: void 0,
+			colorIndex: void 0,
+			none: false
+		};
+		return true;
+	}
+	switch (name) {
+		case "clvmgf":
+			cell.verticalMergeFirst = true;
+			return true;
+		case "clvmrg":
+			cell.verticalMergeContinuation = true;
+			return true;
+		case "clmgf":
+			cell.horizontalMergeFirst = true;
+			return true;
+		case "clmrg":
+			cell.horizontalMergeContinuation = true;
+			return true;
+		case "clcbpat":
+			cell.backgroundIndex = param;
+			return true;
+	}
+	const pending = cell.side === void 0 ? void 0 : cell.borders[cell.side];
+	if (pending === void 0) return false;
+	if (NO_BORDER_KEYWORDS.has(name)) {
+		pending.none = true;
+		return true;
+	}
+	const style = BORDER_STYLES.get(name);
+	if (style !== void 0) {
+		pending.style = style;
+		return true;
+	}
+	if (name === "brdrw") {
+		pending.widthTwips = param;
+		return true;
+	}
+	if (name === "brdrcf") {
+		pending.colorIndex = param;
+		return true;
+	}
+	return name.startsWith("brdr") || name.startsWith("brsp");
+}
+function resolveBorder(pending, colorAt) {
+	if (pending.none) return;
+	const widthPt = require_units.twipsToPoints(pending.widthTwips ?? DEFAULT_BORDER_WIDTH_TWIPS);
+	if (widthPt <= 0) return;
+	const color = pending.colorIndex === void 0 ? void 0 : colorAt(pending.colorIndex);
+	const style = pending.style;
+	return {
+		color: color ?? {
+			r: 0,
+			g: 0,
+			b: 0
+		},
+		widthPt,
+		...style === void 0 || style === "solid" ? {} : { style }
+	};
+}
+function borderControlWords(side, border, colorIndex) {
+	const sideWord = [...CELL_BORDER_SIDES].find(([, value]) => value === side)?.[0];
+	if (sideWord === void 0) return "";
+	const style = BORDER_STYLE_CONTROL_WORDS[border.style ?? "solid"];
+	const width = Math.max(1, require_units.pointsToTwips(border.widthPt));
+	return `\\${sideWord}\\${style}\\brdrw${String(width)}` + (colorIndex === void 0 ? "" : `\\brdrcf${String(colorIndex)}`);
+}
+const BORDER_STYLE_CONTROL_WORDS = {
+	solid: "brdrs",
+	dashed: "brdrdash",
+	dotted: "brdrdot",
+	double: "brdrdb"
+};
+//#endregion
+exports.CELL_BORDER_SIDES = CELL_BORDER_SIDES;
+exports.applyCellDefinitionControlWord = applyCellDefinitionControlWord;
+exports.borderControlWords = borderControlWords;
+exports.newPendingCell = newPendingCell;
+exports.resolveBorder = resolveBorder;