rtf-codec 1.0.0 → 1.1.1

package/README.md

@@ -6,6 +6,8 @@
 
 **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.
@@ -23,7 +25,7 @@ graph TD
     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). Wiring it into `documents.js`'s conversion engine, `document-cli`, `document-mcp`, or the web UI is explicitly out of scope here, exactly as it was for [epub-codec](../epub-codec/README.md); see [Not yet wired into the conversion engine](#not-yet-wired-into-the-conversion-engine).
+`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
 
@@ -79,7 +81,7 @@ Five stages, each its own module, each testable on its own:
 | 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/diagnostics.ts` (the three-tier diagnostic policy).
+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
 
@@ -110,10 +112,15 @@ On the way out, **every non-ASCII character leaves as `\uN`** with a one-charact
 | `\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`                                                                                 |
+| `\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                                                                                  |
@@ -123,27 +130,32 @@ On the way out, **every non-ASCII character leaves as `\uN`** with a one-charact
 
 ### 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, a `heading N` style per distinct heading level, and a `\listtable`/`\listoverridetable` pair per distinct list. Output is deterministic (the same document produces byte-identical bytes) and pure 7-bit ASCII.
+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. |
-| Fidelity constructs (`constructStart`/`constructEnd`, run-level extents)                        | Neither read nor written. Bookmarks, tracked changes and content controls all have RTF spellings; mapping them onto the harmonised construct vocabulary is its own piece of work.                                  |
-| The residue channel (`source: { format, xml }`)                                                 | `document-schema.js`'s `SourceFormatSchema` is a closed enum with no `rtf` member, so this codec has no legal residue value to emit. Adding one is an additive change to that package, tracked separately.         |
-| 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.                                                                                                                                     |
-| Multiple sections                                                                               | `\sect` ends the paragraph but does not start a new `ContentSection`; a document reads as one section with the document-level page geometry.                                                                       |
-| Superscript/subscript (`\super`, `\sub`), character scaling, kerning, background colour         | No `ContentRun` field expresses them.                                                                                                                                                                              |
-| Table cell borders, shading, vertical merge                                                     | No RTF is emitted for `ContentTableCell.borders`/`background`, and `\clvmgf`/`\clvmrg` are not read into `rowSpan`.                                                                                                |
-| Right-to-left text (`\rtlch`, `\rtlpar`)                                                        | No `ContentDocument` field carries direction.                                                                                                                                                                      |
+| 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
 
@@ -161,6 +173,8 @@ const droppedPictures = diagnostics.filter(
 );
 ```
 
+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
@@ -177,9 +191,13 @@ Like every foundation and format-codec package in this family, `rtf-codec` is Wo
 
 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.
 
-## Not yet wired into the conversion engine
+## 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.
 
-This package is a standalone codec. It is not yet registered in `documents.js`'s `DOCUMENT_FORMAT_CODECS` registry or its format pathfinder, so `rtf` is not yet a source or target for `convertDocument`, the CLI, the MCP server, or the web UI. That wiring touches the format enum, the capability table, the pathfinder's own node table, and several exhaustive conversion-matrix tests, and is deliberately a separate change — exactly as `epub-codec`'s own engine wiring was. Tracked in [ExaDev/documents.js#847](https://github.com/ExaDev/documents.js/issues/847).
+**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
 

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;

package/dist/cell-format.d.cts

@@ -0,0 +1,25 @@
+import { Color, ContentBorder, ContentStrokeStyle } from "document-schema.js";
+//#region src/cell-format.d.ts
+type CellBorderSide = "top" | "left" | "bottom" | "right";
+declare const CELL_BORDER_SIDES: ReadonlyMap<string, CellBorderSide>;
+interface PendingBorder {
+  style: ContentStrokeStyle | undefined;
+  widthTwips: number | undefined;
+  colorIndex: number | undefined;
+  none: boolean;
+}
+interface PendingCell {
+  borders: Partial<Record<CellBorderSide, PendingBorder>>;
+  side: CellBorderSide | undefined;
+  backgroundIndex: number | undefined;
+  verticalMergeFirst: boolean;
+  verticalMergeContinuation: boolean;
+  horizontalMergeFirst: boolean;
+  horizontalMergeContinuation: boolean;
+}
+declare function newPendingCell(): PendingCell;
+declare function applyCellDefinitionControlWord(name: string, param: number | undefined, cell: PendingCell): boolean;
+declare function resolveBorder(pending: PendingBorder, colorAt: (index: number) => Color | undefined): ContentBorder | undefined;
+declare function borderControlWords(side: CellBorderSide, border: ContentBorder, colorIndex: number | undefined): string;
+//#endregion
+export { CELL_BORDER_SIDES, CellBorderSide, PendingBorder, PendingCell, applyCellDefinitionControlWord, borderControlWords, newPendingCell, resolveBorder };

package/dist/cell-format.d.ts

@@ -0,0 +1,25 @@
+import { Color, ContentBorder, ContentStrokeStyle } from "document-schema.js";
+//#region src/cell-format.d.ts
+type CellBorderSide = "top" | "left" | "bottom" | "right";
+declare const CELL_BORDER_SIDES: ReadonlyMap<string, CellBorderSide>;
+interface PendingBorder {
+  style: ContentStrokeStyle | undefined;
+  widthTwips: number | undefined;
+  colorIndex: number | undefined;
+  none: boolean;
+}
+interface PendingCell {
+  borders: Partial<Record<CellBorderSide, PendingBorder>>;
+  side: CellBorderSide | undefined;
+  backgroundIndex: number | undefined;
+  verticalMergeFirst: boolean;
+  verticalMergeContinuation: boolean;
+  horizontalMergeFirst: boolean;
+  horizontalMergeContinuation: boolean;
+}
+declare function newPendingCell(): PendingCell;
+declare function applyCellDefinitionControlWord(name: string, param: number | undefined, cell: PendingCell): boolean;
+declare function resolveBorder(pending: PendingBorder, colorAt: (index: number) => Color | undefined): ContentBorder | undefined;
+declare function borderControlWords(side: CellBorderSide, border: ContentBorder, colorIndex: number | undefined): string;
+//#endregion
+export { CELL_BORDER_SIDES, CellBorderSide, PendingBorder, PendingCell, applyCellDefinitionControlWord, borderControlWords, newPendingCell, resolveBorder };

package/dist/cell-format.js

@@ -0,0 +1,137 @@
+import { pointsToTwips, twipsToPoints } from "./units.js";
+//#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 = 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, 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
+export { CELL_BORDER_SIDES, applyCellDefinitionControlWord, borderControlWords, newPendingCell, resolveBorder };