ppt-codec 1.5.0 → 1.7.0

package/README.md

@@ -8,7 +8,7 @@ Created for [documents.js#817](https://github.com/ExaDev/documents.js/issues/817
 
 ## Status
 
-**Under active development. The read path for slide text, geometry and speaker notes is built and tested. A narrower write path now exists too: one slide per input slide, with plain text-box shapes and their speaker notes (basic character formatting, no images/tables/layouts) — genuinely conformant [MS-PPT], verified by writing then reading every fixture back through this package's own reader, and, for speaker notes, against LibreOffice in both directions, but not full read/write parity.** What that means concretely is set out in [What it reads](#what-it-reads)/[What it does not read yet](#what-it-does-not-read-yet) and [What it writes](#what-it-writes)/[What it does not write yet](#what-it-does-not-write-yet) below — every one of those four lists is exhaustive rather than illustrative, so a caller can tell from this page alone whether the format's own feature it cares about is covered.
+**Under active development. The read path for slide text, geometry, pictures, tables, rotation and speaker notes is built and tested. A narrower write path now exists too: one slide per input slide, with text-box, picture, and table shapes (basic character formatting, rotation, no layouts) plus their speaker notes — genuinely conformant [MS-PPT], verified by writing then reading every fixture back through this package's own reader, and, for speaker notes, against LibreOffice in both directions, but not full read/write parity.** What that means concretely is set out in [What it reads](#what-it-reads)/[What it does not read yet](#what-it-does-not-read-yet) and [What it writes](#what-it-writes)/[What it does not write yet](#what-it-does-not-write-yet) below — every one of those four lists is exhaustive rather than illustrative, so a caller can tell from this page alone whether the format's own feature it cares about is covered.
 
 ## Why the format is shaped the way it is
 
@@ -111,31 +111,41 @@ import { writePpt, writePptContent } from "ppt-codec";
 // The tree form: a document-schema.js DocumentTree in, real .ppt bytes out.
 const pptBytes = writePpt(tree);
 
-// The flat form: metadata plus ContentSlide[] in -- title/author/dates are
-// written to a real "\x05SummaryInformation" stream when metadata carries
-// any of them (see Metadata).
-const bytes = writePptContent({ metadata: {}, slides });
+// The flat form: metadata plus ContentSlide[] in -- title/author/dates are written to a real "\x05SummaryInformation" stream when metadata carries any of them (see Metadata). An optional sink hears every block this writer had to drop (an unblippable image format, a second table on one shape, or an embeddedObject block with no serialiseEmbeddedObject port to turn its nested document into real bytes) instead of losing that information silently.
+const bytes = writePptContent(
+  { metadata: {}, slides },
+  { sink: (diagnostic) => console.warn(diagnostic.code, diagnostic.message) },
+);
 ```
 
-`writePptStreams(document)` is the same write one level down, returning the two [MS-PPT] streams without wrapping them in a compound file — the mirror of `readPptStreams`, for a caller assembling its own container. Every function throws `PptUnsupportedContentError` (not `PptFormatError`, which is reserved for malformed bytes on the read side) when asked to write content outside this writer's scope: a document that is not a presentation, or slides that do not all share one size (`[MS-PPT]`'s `DocumentAtom` states exactly one slide size for the whole presentation). A block kind this writer does not represent (an image, a table, a construct marker) is not an error — it is silently excluded from the written text body, the same documented-gap convention [What it does not read yet](#what-it-does-not-read-yet) already uses for the reader's own unsupported constructs.
+`writePptStreams(document)` is the same write one level down, returning the two [MS-PPT] streams without wrapping them in a compound file — the mirror of `readPptStreams`, for a caller assembling its own container. Every function throws `PptUnsupportedContentError` (not `PptFormatError`, which is reserved for malformed bytes on the read side) when asked to write content outside this writer's scope: a document that is not a presentation, or slides that do not all share one size (`[MS-PPT]`'s `DocumentAtom` states exactly one slide size for the whole presentation). A block kind this writer does not represent (a construct marker, an image in a format with no blip token, or an embeddedObject block whose nested document `serialiseEmbeddedObject` declines or was never supplied for) is, by default, not an error — it is dropped from the written text body with a diagnostic naming it (see [`src/diagnostics.ts`](src/diagnostics.ts)), the same documented-gap convention [What it does not read yet](#what-it-does-not-read-yet) already uses for the reader's own unsupported constructs. `WritePptOptions.onUnwritableBlock: 'throw'` turns exactly that drop into a thrown `PptUnsupportedContentError` instead — see [Silent drop, or a thrown error](#silent-drop-or-a-thrown-error) for why `'drop'` stays the default rather than converging on doc-codec's own throw-always convention.
+
+### Silent drop, or a thrown error
+
+`doc-codec` throws for a block kind its own writer cannot express; this package's writer, by default, drops the block and names it through the diagnostic sink instead — a real, deliberate divergence between two codecs in the same family, not an oversight ([ExaDev/documents.js#1188](https://github.com/ExaDev/documents.js/issues/1188), split into its own decision as [#1220](https://github.com/ExaDev/documents.js/issues/1220)). The two packages' own upstream differs in kind, not degree: `documents.js`'s PDF-to-ppt and odp-to-ppt reconstruction is this package's primary caller today, and it routinely hands this writer content the binary PPT format simply has no spelling for at all (an unrecognised alignment value, a construct marker, an OLE object with no serialiser port supplied) — not as a rare malformed-input edge case a bug would explain, but as the ordinary shape of reconstructing a narrower target format from a richer source. Converging on `doc-codec`'s own default would turn "this slide's chart degrades to geometry" into "the whole presentation fails to convert" for every one of those callers, a severe regression imposed on working code rather than a bug fixed in it.
+
+`WritePptOptions.onUnwritableBlock` is the caller's own choice between the two policies rather than a permanent split: `'drop'` (the default, and every existing caller's own unchanged behaviour) keeps writing the rest of the shape and names the drop through the sink; `'throw'` raises a `PptUnsupportedContentError` naming the identical block and reason the sink would otherwise merely report, for a caller that would rather fail the whole conversion than ship a file quietly missing content it was asked to carry. The option covers a genuine block-level omission only — `PptDiagnosticCodes.TABLE_SPAN_DROPPED` (a merged cell's `colSpan`/`rowSpan` narrowed to one column/row, since this format's own tables carry no merge record at all) is a lossy narrowing of content that is still written, not an omission of it, and always stays sink-only regardless of this option; conflating the two would make `'throw'` fail a conversion over a table that wrote completely, just with a merge visually flattened.
 
 ## What it reads
 
 The whole path from a file's first byte to a slide's text, record by record:
 
-| Layer           | Records                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Container       | The `Current User` and `PowerPoint Document` streams, read through `archive-codec`'s bounded [MS-CFB] reader.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Record framing  | The generic 8-byte `RecordHeader`, the container/atom distinction, sibling sequences, child walks, and typed-descendant search — shared with [MS-ODRAW]'s records, which carry the identical header.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Edit resolution | `CurrentUserAtom` (including its encrypted/plaintext `headerToken`), the `UserEditAtom` chain, `PersistDirectoryAtom`/`PersistDirectoryEntry`'s packed 20-bit/12-bit run form, and the oldest-first directory construction whose later entries supersede earlier ones — [MS-PPT] 2.1.2's own "live record" process, Part 1.                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| Encryption      | `DocumentEncryptionAtom` (`UserEditAtom.encryptSessionPersistIdRef` → the persist directory), [MS-OFFCRYPTO] 2.3.5's RC4 CryptoAPI scheme — see [Encryption](#encryption).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Document        | `DocumentContainer` → `DocumentAtom` (slide size, in master units), `DocumentTextInfoContainer`'s `FontCollectionContainer`/`FontEntityAtom` typeface names and its own document-default `TextMasterStyleAtom`, and `SlideListWithTextContainer` (distinguished from the master and notes lists by `recInstance`, which does not run in the order the names suggest).                                                                                                                                                                                                                                                                                                                                                                          |
-| Masters         | `MasterListWithTextContainer` → `MasterPersistAtom` → the persist directory → each `MainMasterContainer`'s own `TextMasterStyleAtom` items and `SlideSchemeColorSchemeAtom` — a real file can carry more than one master, and `SlideAtom.masterIdRef` decides which one a given slide actually follows.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Slides          | `SlidePersistAtom` → the persist directory → each `SlideContainer`'s own `SlideAtom` (`masterIdRef`, `notesIdRef`) and drawing, and the placeholder texts the slide list carries for it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| Speaker notes   | `NotesListWithTextContainer` (the third of the three containers sharing `RT_SlideListWithText`) → `NotesPersistAtom` → the persist directory → each `NotesContainer`, and the `NotesAtom.slideIdRef` naming the presentation slide those notes belong to. The text comes from the notes slide's own drawing, since the notes list — unlike the slide list — carries no texts for an `OutlineTextRefAtom` to reach into.                                                                                                                                                                                                                                                                                                                        |
-| Drawing         | `DrawingContainer` → `OfficeArtDgContainer` → the `OfficeArtSpgrContainer`/`OfficeArtSpContainer` tree, `OfficeArtFSP`'s group/patriarch/deleted flags, `OfficeArtClientAnchor` in both its 8-byte `SmallRectStruct` and 16-byte `RectStruct` spellings, and `OfficeArtChildAnchor` mapped through nested `OfficeArtFSPGR` group coordinate systems.                                                                                                                                                                                                                                                                                                                                                                                           |
-| Text            | `OfficeArtClientTextbox`, `TextHeaderAtom`, `TextCharsAtom` (UTF-16) and `TextBytesAtom` (one byte per character), `OutlineTextRefAtom` indirection into the slide list, and the paragraph split on the stored `\r`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Formatting      | `StyleTextPropAtom`: `TextPFRun`/`TextPFException` (indent level, alignment, line spacing, space before/after, left margin, and first-line indent) and `TextCFRun`/`TextCFException` (bold, italic, underline, shadow, emboss, typeface reference, size in points, and a `ColorIndexStruct` colour — literal sRGB or a colour-scheme slot reference), each read in the spec's **declared field order** rather than its mask-bit order — the two differ, and following the mask-bit order desynchronises every field after the first divergence. A field a run states neither directly nor at all resolves against the applicable master's own cascade and colour scheme — see [Master and colour inheritance](#master-and-colour-inheritance). |
+| Layer           | Records                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Container       | The `Current User` and `PowerPoint Document` streams, read through `archive-codec`'s bounded [MS-CFB] reader.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Record framing  | The generic 8-byte `RecordHeader`, the container/atom distinction, sibling sequences, child walks, and typed-descendant search — shared with [MS-ODRAW]'s records, which carry the identical header.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Edit resolution | `CurrentUserAtom` (including its encrypted/plaintext `headerToken`), the `UserEditAtom` chain, `PersistDirectoryAtom`/`PersistDirectoryEntry`'s packed 20-bit/12-bit run form, and the oldest-first directory construction whose later entries supersede earlier ones — [MS-PPT] 2.1.2's own "live record" process, Part 1.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Encryption      | `DocumentEncryptionAtom` (`UserEditAtom.encryptSessionPersistIdRef` → the persist directory), [MS-OFFCRYPTO] 2.3.5's RC4 CryptoAPI scheme — see [Encryption](#encryption).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Document        | `DocumentContainer` → `DocumentAtom` (slide size, in master units), `DocumentTextInfoContainer`'s `FontCollectionContainer`/`FontEntityAtom` typeface names and its own document-default `TextMasterStyleAtom`, and `SlideListWithTextContainer` (distinguished from the master and notes lists by `recInstance`, which does not run in the order the names suggest).                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Masters         | `MasterListWithTextContainer` → `MasterPersistAtom` → the persist directory → each `MainMasterContainer`'s own `TextMasterStyleAtom` items and `SlideSchemeColorSchemeAtom` — a real file can carry more than one master, and `SlideAtom.masterIdRef` decides which one a given slide actually follows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Slides          | `SlidePersistAtom` → the persist directory → each `SlideContainer`'s own `SlideAtom` (`masterIdRef`, `notesIdRef`) and drawing, and the placeholder texts the slide list carries for it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Speaker notes   | `NotesListWithTextContainer` (the third of the three containers sharing `RT_SlideListWithText`) → `NotesPersistAtom` → the persist directory → each `NotesContainer`, and the `NotesAtom.slideIdRef` naming the presentation slide those notes belong to. The text comes from the notes slide's own drawing, since the notes list — unlike the slide list — carries no texts for an `OutlineTextRefAtom` to reach into.                                                                                                                                                                                                                                                                                                                                                |
+| Drawing         | `DrawingContainer` → `OfficeArtDgContainer` → the `OfficeArtSpgrContainer`/`OfficeArtSpContainer` tree, `OfficeArtFSP`'s group/patriarch/deleted flags, `OfficeArtClientAnchor` in both its 8-byte `SmallRectStruct` and 16-byte `RectStruct` spellings, `OfficeArtChildAnchor` mapped through nested `OfficeArtFSPGR` group coordinate systems, a shape's own `OfficeArtFOPT` rotation property (`PROPERTY_ROTATION`, an [MS-OSHARED] 2.2.1.6 Fixed Point), and its four text-inset properties (`dxTextLeft`/`dyTextTop`/`dxTextRight`/`dyTextBottom`, each an EMU value read independently — a shape stating only one override still gets PowerPoint's own default on the other three).                                                                              |
+| Pictures        | The document-wide `OfficeArtBStoreContainer` (`OfficeArtFBSE` entries, each an inline or `Pictures`-stream-offset blip), resolved through a picture shape's own `pib` property; only the two `MSOBLIPTYPE` tokens `document-schema.js`'s `ContentImageBlock` can hold losslessly (`0x05` JPEG, `0x06` PNG) decode to an image block, sized to the shape's own frame. An unresolvable pib (past the store's end, an empty slot, or a WMF/EMF/TIFF/DIB blip this package does not decode) keeps the shape with empty content rather than dropping the shape.                                                                                                                                                                                                             |
+| Tables          | A table group's own grid, recovered from its cells' rectangles rather than from any row/column record — the format states none: row and column boundaries are the cells' own distinct tops and lefts, a cell lands at the intersection of its own top and left, and a real producer's degenerate zero-width/zero-height gridline shapes are excluded from the grid by that same geometry check rather than treated as cells.                                                                                                                                                                                                                                                                                                                                           |
+| OLE embeddings  | A shape's `OfficeArtClientData` → `ExObjRefAtom` → the document's `ExObjListContainer` → `ExOleEmbedContainer` (`ExOleObjAtom`'s own `persistIdRef`, and an optional `ProgIDAtom`) → the persist directory → an `ExOleObjStg` persist object, decompressed (zlib/[RFC1950]) when `rh.recInstance` says so — recovering the embedded object's own raw [MS-CFB] compound-file bytes with no further "Package"-stream wrapper. This package cannot decode those bytes into a real nested document itself (see [What it does not read yet](#what-it-does-not-read-yet)), so the recovery stops at the bytes/progId pair unless a caller injects `ReadPptOptions.decodeEmbeddedObject` — `documents.js` wires one from `doc-codec`/`xls-codec`/its own `ppt-codec` adapter. |
+| Text            | `OfficeArtClientTextbox`, `TextHeaderAtom`, `TextCharsAtom` (UTF-16) and `TextBytesAtom` (one byte per character), `OutlineTextRefAtom` indirection into the slide list, and the paragraph split on the stored `\r`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Formatting      | `StyleTextPropAtom`: `TextPFRun`/`TextPFException` (indent level, alignment, line spacing, space before/after, left margin, and first-line indent) and `TextCFRun`/`TextCFException` (bold, italic, underline, shadow, emboss, typeface reference, size in points, and a `ColorIndexStruct` colour — literal sRGB or a colour-scheme slot reference), each read in the spec's **declared field order** rather than its mask-bit order — the two differ, and following the mask-bit order desynchronises every field after the first divergence. A field a run states neither directly nor at all resolves against the applicable master's own cascade and colour scheme — see [Master and colour inheritance](#master-and-colour-inheritance).                         |
 
 Geometry is converted from master units (1/576 inch) to points on the way out, so a slide's `size` and every shape's `frame` are in the same unit the shared schema uses everywhere else.
 
@@ -144,8 +154,10 @@ Geometry is converted from master units (1/576 inch) to points on the way out, s
 Each of these is a real construct of the format that this package currently ignores or cannot represent — not a claim that it does not exist:
 
 - **`DocumentSummaryInformation`'s extended and user-defined properties** (company, manager, custom properties) — a genuinely different stream from the one [Metadata](#metadata) covers, not attempted at all.
-- **Per-shape text insets.** Every shape reports PowerPoint's own defaults (0.1 inch left and right, 0.05 inch top and bottom); a per-shape override lives in the shape's `OfficeArtFOPT` property table, which is not read.
-- **Images, tables, and OLE embeddings.** A picture shape, a table object, and an embedded or linked OLE object all read as a shape with geometry and no blocks. `ExObjListContainer` and the `ExOleObjStg` persist objects are not walked.
+- **A linked (as opposed to embedded) OLE object.** `ExOleLinkContainer` names an external file this package has no path to resolve independently of the host document, so a linked object's shape reads with geometry and no blocks — the identical "no recovery path, no entry" degrade an unresolvable persist reference already gets. An embedded OLE object's own linkage and storage recovery is real — see [OLE embeddings](#what-it-reads) in the table above.
+- **Decoding an OLE-embedded object's own nested content, without a caller-supplied port.** This package depends on no sibling format codec (`doc-codec`/`xls-codec`/itself, or `ooxml.js`), so it cannot turn an embedded object's recovered `[MS-CFB]` bytes into a real nested `ContentDocument` on its own — the same architectural boundary `ooxml.js`'s own embedded-object recovery states for a classic-binary `.bin` payload it finds no `Package` stream in. `readPptContent`/`readPpt`'s `ReadPptOptions.decodeEmbeddedObject` is the injected port a caller holding every codec — `documents.js` — supplies; without one, an OLE-embedded shape's blocks stay whatever its own picture/text already give it (the same degrade a decode failure, an unrecognised progId, or a missing persist entry all produce), never a document this package invented or guessed at.
+- **Image formats beyond PNG and JPEG.** A blip in any other `MSOBLIPTYPE` (WMF/EMF metafile, PICT, a raw DIB, TIFF) reads as no image at all, keeping the shape's geometry with empty content — the same convention an unresolvable pib already uses.
+- **Cell merges in a read table.** [MS-PPT]'s own table shapes are a strict grid of one shape per cell with no merge record at all (merged cells arrived only with the 2010 XML format), so a read table never states `colSpan`/`rowSpan`.
 - **Shapes with no anchor.** A shape carrying neither an `OfficeArtClientAnchor` nor an `OfficeArtChildAnchor` is dropped, because `ContentShape` has no way to say "positioned, but unknown where".
 - **Hyperlinks and bullets.** `InteractiveInfo`/`TextInteractiveInfoAtom` and `TextPFException`'s bullet fields are parsed past correctly but not surfaced.
 - **Animations, transitions, comments, headers and footers, and the metacharacter atoms** (slide number, date, header, footer).
@@ -157,18 +169,21 @@ Each of these is a real construct of the format that this package currently igno
 
 The whole path from a `ContentSlide[]` to a real `.ppt` file's bytes, mirroring the read-side table above in the opposite direction:
 
-| Layer           | Records                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Container       | The `Current User` and `PowerPoint Document` streams, wrapped in a real [MS-CFB] compound file through `archive-codec`'s conformant writer.                                                                                                                                                                                                                                                                                                                                                          |
-| Record framing  | The generic 8-byte `RecordHeader`, atom and container builders — `record/write.ts`, shared by every writer module below and by this package's own test fixtures.                                                                                                                                                                                                                                                                                                                                     |
-| Edit resolution | A single-edit persist layer: one `CurrentUserAtom` pointing at one `UserEditAtom` pointing at one `PersistDirectoryAtom` whose entries name the stream offset of the document container, the master, every slide container and every notes container — never an incremental append, since nothing about this writer's own output needs a second generation of any object.                                                                                                                            |
-| Document        | `DocumentContainer` → `DocumentAtom` (one slide size, in master units, taken from the input's own first slide and required to match every other slide — see below), an `Environment`/`FontCollectionContainer` built from every distinct `fontFamily` a run names, a `MasterListWithTextContainer` naming the one master, a `SlideListWithTextContainer` carrying one `SlidePersistAtom` per slide with no placeholder texts, and — only when some slide has notes — a `NotesListWithTextContainer`. |
-| Master          | One minimal `MainMasterContainer`: its own `SlideAtom`, the title/body/notes `TextMasterStyleAtom` items [MS-PPT] 2.5.3 requires (each stating `cLevels` 0, so every level falls through to the document's own text styles), the five `SL_TitleBody` placeholder shapes a main master must carry, and a default `SlideSchemeColorSchemeAtom`. It exists because speaker notes need it — see below.                                                                                                   |
-| Slides          | One `SlideContainer` per input slide, each opening with a `SlideAtom` that names the master it follows and, when the slide has notes, the notes slide holding them, then its own `DrawingContainer`.                                                                                                                                                                                                                                                                                                 |
-| Speaker notes   | One `NotesContainer` per slide that actually has notes — a `NotesAtom` naming that slide, then a `DrawingContainer` whose single text box carries the notes, one paragraph per line, then the `SlideSchemeColorSchemeAtom` [MS-PPT] 2.5.6 requires of one — the notes slide's own `NotesAtom.slideFlags` leaves `fMasterScheme` clear, so it inherits no scheme and has to state one. A slide with no notes gets no notes slide at all rather than an empty one.                                     |
-| Drawing         | `OfficeArtDgContainer` → one `OfficeArtSpgrContainer` (the patriarch group every real drawing carries) → one plain `OfficeArtSpContainer` per shape, each anchored in slide coordinates via a 32-bit `OfficeArtClientAnchor` (`RectStruct`, never the 16-bit `SmallRectStruct`) — no grouping, no `OfficeArtChildAnchor` nesting.                                                                                                                                                                    |
-| Text            | Every shape carries its own text directly on its `OfficeArtClientTextbox` (`TextHeaderAtom` + a UTF-16 `TextCharsAtom`) rather than through the `OutlineTextRefAtom` placeholder indirection into the slide list — a plain text box is all this writer produces, so there is no separate placeholder text to route through the document's own slide list.                                                                                                                                            |
-| Formatting      | `StyleTextPropAtom`: one `TextPFRun` per paragraph (indent level, alignment, line spacing, space before/after, left margin, and first-line indent) and one `TextCFRun` per character run (bold, italic, underline, a font-collection reference, size in points, and a literal sRGB `ColorIndexStruct` colour), fields written in the identical spec-declared order `readTextPFException`/`readTextCFException` parse them in.                                                                        |
+| Layer           | Records                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Container       | The `Current User` and `PowerPoint Document` streams, wrapped in a real [MS-CFB] compound file through `archive-codec`'s conformant writer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Record framing  | The generic 8-byte `RecordHeader`, atom and container builders — `record/write.ts`, shared by every writer module below and by this package's own test fixtures.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Edit resolution | A single-edit persist layer: one `CurrentUserAtom` pointing at one `UserEditAtom` pointing at one `PersistDirectoryAtom` whose entries name the stream offset of the document container, the master, every slide container and every notes container — never an incremental append, since nothing about this writer's own output needs a second generation of any object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Document        | `DocumentContainer` → `DocumentAtom` (one slide size, in master units, taken from the input's own first slide and required to match every other slide — see below), an `Environment`/`FontCollectionContainer` built from every distinct `fontFamily` a run names, a `MasterListWithTextContainer` naming the one master, a `SlideListWithTextContainer` carrying one `SlidePersistAtom` per slide with no placeholder texts, and — only when some slide has notes — a `NotesListWithTextContainer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Master          | One minimal `MainMasterContainer`: its own `SlideAtom`, the title/body/notes `TextMasterStyleAtom` items [MS-PPT] 2.5.3 requires (each stating `cLevels` 0, so every level falls through to the document's own text styles), the five `SL_TitleBody` placeholder shapes a main master must carry, and a default `SlideSchemeColorSchemeAtom`. It exists because speaker notes need it — see below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Slides          | One `SlideContainer` per input slide, each opening with a `SlideAtom` that names the master it follows and, when the slide has notes, the notes slide holding them, then its own `DrawingContainer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Speaker notes   | One `NotesContainer` per slide that actually has notes — a `NotesAtom` naming that slide, then a `DrawingContainer` whose single text box carries the notes, one paragraph per line, then the `SlideSchemeColorSchemeAtom` [MS-PPT] 2.5.6 requires of one — the notes slide's own `NotesAtom.slideFlags` leaves `fMasterScheme` clear, so it inherits no scheme and has to state one. A slide with no notes gets no notes slide at all rather than an empty one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Drawing         | `OfficeArtDgContainer` → one `OfficeArtSpgrContainer` (the patriarch group every real drawing carries) → one plain `OfficeArtSpContainer` per shape, each anchored in slide coordinates via a 32-bit `OfficeArtClientAnchor` (`RectStruct`, never the 16-bit `SmallRectStruct`), a shape's own `rotationDeg` as an `OfficeArtFOPT` `PROPERTY_ROTATION` entry, and whichever of its four text insets differ from the default its own picture-ness implies, each as its own `dxTextLeft`/`dyTextTop`/`dxTextRight`/`dyTextBottom` property — no grouping otherwise, beyond the table group below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Pictures        | The first `png`/`jpeg` image block on a shape becomes that shape's one blip-store reference (`blipIndexOf`, feeding the document-wide `OfficeArtBStoreContainer` every picture shares); an image in any other format, or a second image on a shape whose single blip reference an earlier one already claimed, is dropped with a diagnostic (`ppt/image-dropped`) rather than silently discarded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Tables          | A table block turns its whole shape into a table group in the spelling a real PowerPoint-authored file carries (confirmed against Microsoft Office PowerPoint's own output and Apache POI's `table_test.ppt` fixture): an `OfficeArtFSPGR` child coordinate system identical to the shape's own client anchor, `fIsTable`/`tableRowProperties` in the tertiary property table, and one plain text-box shape per cell at its own `OfficeArtChildAnchor` grid position — the same grid `tableBlockFor` reads back. A cell's `colSpan`/`rowSpan` is dropped with a diagnostic (`ppt/table-span-dropped`), since the format has no merge record to state it in.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| OLE embeddings  | A shape whose blocks carry an `embeddedObject` block gets a real `ExObjRefAtom` in its own `OfficeArtClientData`, naming a fresh entry in the document's own `ExObjListContainer` (`ExOleEmbedContainer`: `ExOleEmbedAtom`, `ExOleObjAtom`, and — for a `wordprocessing`/`spreadsheet` object kind, the two this package can name a real legacy-Office ProgID for — a `ProgIDAtom`) whose `persistIdRef` names a fresh `ExOleObjStgUncompressedAtom` persist object, only when `WritePptOptions.serialiseEmbeddedObject` (this package has no sibling-codec writer of its own to serialise the nested document with — the write-side mirror of the read-side decode port above) actually recovers `[MS-CFB]` bytes for that object's own nested document; a shape whose embed the port declines (no port supplied, or a document kind — `formula`/`drawing` — it cannot serialise) writes with no `clientData` at all, identical to a shape that never carried an embeddedObject block in the first place — the same silent-drop policy every other unwritable block already gets (see [What it does not write yet](#what-it-does-not-write-yet)). |
+| Text            | Every shape carries its own text directly on its `OfficeArtClientTextbox` (`TextHeaderAtom` + a UTF-16 `TextCharsAtom`) rather than through the `OutlineTextRefAtom` placeholder indirection into the slide list — a plain text box is all this writer produces, so there is no separate placeholder text to route through the document's own slide list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Formatting      | `StyleTextPropAtom`: one `TextPFRun` per paragraph (indent level, alignment, line spacing, space before/after, left margin, and first-line indent) and one `TextCFRun` per character run (bold, italic, underline, a font-collection reference, size in points, and a literal sRGB `ColorIndexStruct` colour), fields written in the identical spec-declared order `readTextPFException`/`readTextCFException` parse them in.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 
 Geometry is converted from points to master units on the way in, rounding to the nearest whole master unit (1/576 inch) — the format's own smallest unit of length.
 
@@ -194,10 +209,10 @@ The round trip above proves the reader and writer agree with each other. Speaker
 
 Each of these is either a real construct this writer deliberately does not attempt (a smaller, genuinely correct core rather than a larger, unreliable one — see the two tables above for exactly what it does write), or a `ContentShape`/`ContentParagraph`/`ContentRun` field this writer's own OfficeArt shape tree has nowhere to carry:
 
-- **Images, tables, and OLE embeddings.** A shape whose blocks include an `image`, `table`, or `embeddedObject` block silently drops that block from the written text body — see [Writing a document](#writing-a-document) — rather than attempting a picture, table, or OLE object shape.
+- **An OLE embedding's own nested content, without a caller-supplied serialiser.** This package cannot itself turn a nested `ContentDocument` back into `[MS-CFB]` bytes (it depends on no sibling format codec — the write-side mirror of the read-side decode gap above), so `WritePptOptions.serialiseEmbeddedObject` is the injected port a caller holding every codec supplies; without one, a shape's `embeddedObject` block writes with no `clientData` and no `ExOleObjStg` persist object, silently, matching every other block kind this writer cannot express (see [What it writes](#what-it-writes) for what a supplied port produces).
 - **Shapes with no text.** Written with a client anchor and no `OfficeArtClientTextbox` at all, matching how the reader represents one (`blocks: []`); nothing is lost, since there was nothing to write.
-- **Grouped shapes, rotation, and any coordinate system beyond a plain `OfficeArtClientAnchor`.** Every shape this writer emits is an ungrouped, unrotated rectangle in slide coordinates; `ContentShape.rotationDeg` is not written, and there is no `OfficeArtChildAnchor`/`OfficeArtFSPGR` group nesting.
-- **Per-shape text insets, autofit, and paint order.** `ContentShape.insetLeftPt`/`insetTopPt`/`insetRightPt`/`insetBottomPt`, `fontScale`, `lineSpacingReduction`, and `paintOrder` have no `OfficeArtFOPT` property table to land in, since this writer does not build one.
+- **Grouped shapes beyond a table, and any coordinate system beyond a plain `OfficeArtClientAnchor` or the table group's own `OfficeArtFSPGR`.** Every non-table shape this writer emits is an ungrouped rectangle in slide coordinates; there is no general `OfficeArtChildAnchor`/`OfficeArtFSPGR` group nesting outside the one a table block itself produces. `ContentShape.rotationDeg` is written (see [Drawing](#what-it-writes) in the table above).
+- **Autofit and paint order.** `ContentShape.fontScale`, `lineSpacingReduction`, and `paintOrder` have no `OfficeArtFOPT` property table entry this writer states (per-shape text insets are written — see [Drawing](#what-it-writes) in the table above).
 - **Master content, layouts, and scheme colours.** A `MainMasterContainer` and its `MasterListWithTextContainer` are written, but only as the minimum [MS-PPT] requires of one (see [Why a writer of plain text-box slides writes a master slide](#why-a-writer-of-plain-text-box-slides-writes-a-master-slide)): its five placeholder shapes carry no text, its `TextMasterStyleAtom` items state no style level of their own, and its `SlideSchemeColorSchemeAtom` is a fixed default rather than anything the input chose. There are still no slide layouts, and every character run's colour must already be a literal, since no scheme is there to resolve one against.
 - **Notes masters, and a notes page geometry of its own.** No `NotesContainer` is written for the notes master, and `DocumentAtom.notesMasterPersistIdRef` stays 0, so each notes slide inherits nothing (its `NotesAtom.slideFlags` is clear) and states the same fixed default `SlideSchemeColorSchemeAtom` the master does rather than a scheme of the input's choosing. The notes page is the same size as the slide, because `ContentSlide` carries no notes-page geometry to state a different one from, and the notes text box is placed in the lower half of it.
 - **Hyperlinks, bullets, and list numbering identity.** `ContentRun.hyperlink`, `ContentParagraph.list.numId`/`checked`/`itemId`, and `pageBreakBefore`/`pageBreakAfter` have no [MS-PPT] field this writer populates; `alignment`, `list.level` (as a `TextPFException` indent level), `spacingBeforePt`/`spacingAfterPt`/`lineSpacing`/`indentLeftPt`/`indentFirstLinePt` round-trip.
@@ -205,7 +220,7 @@ Each of these is either a real construct this writer deliberately does not attem
 - **Construct markers.** A `constructStart`/`constructEnd` pair (or any other non-`paragraph` block kind) is excluded from the written text body exactly like an image or table block, per [Writing a document](#writing-a-document).
 - **Alignment values the shared schema has no name for.** The mirror of the read-side gap: `Tx_ALIGNDistributed`, `Tx_ALIGNThaiDistributed`, and `Tx_ALIGNJustifyLow` are never written, since `Alignment` has no member naming them.
 - **Fractional character sizes.** `ContentRun.sizePt` is rounded to the nearest whole point, since `TextCFException`'s size field is a plain 16-bit integer.
-- **Fonts, tables, animations, transitions, comments, and the metacharacter atoms.** Nothing here is written for the same reason none of it is read yet — see the corresponding entries in [What it does not read yet](#what-it-does-not-read-yet).
+- **Fonts (custom embedding), animations, transitions, comments, and the metacharacter atoms.** Nothing here is written for the same reason none of it is read yet — see the corresponding entries in [What it does not read yet](#what-it-does-not-read-yet).
 
 ## Metadata
 
@@ -231,43 +246,44 @@ import { readRecordAt } from "ppt-codec/record/tree";
 import { readStyleTextPropAtom } from "ppt-codec/text/style";
 ```
 
-| Module                         | What it owns                                                                                                                                                                                                                                                                                                             |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `record/header`                | The generic 8-byte record header and the container/atom distinction.                                                                                                                                                                                                                                                     |
-| `record/types`                 | The `RecordType` values this reader dispatches on, plus the [MS-ODRAW] types the drawing walk crosses into.                                                                                                                                                                                                              |
-| `record/tree`                  | Offset-addressed records, sibling sequences, child walks, typed-descendant search.                                                                                                                                                                                                                                       |
-| `record/write`                 | Byte primitives and the atom/container builders every writer module below composes records from -- the write-side mirror of `record/header`/`record/tree`, and what this package's own test fixtures build on too.                                                                                                       |
-| `stream/current-user`          | `CurrentUserAtom`: where the live edit is, and whether the file is encrypted.                                                                                                                                                                                                                                            |
-| `stream/current-user-write`    | Writes a real `CurrentUserAtom` pointing at the single edit this writer always produces.                                                                                                                                                                                                                                 |
-| `stream/persist`               | `UserEditAtom`, `PersistDirectoryAtom`, and the persist directory the edit chain builds.                                                                                                                                                                                                                                 |
-| `stream/persist-write`         | Writes a single-edit `UserEditAtom`/`PersistDirectoryAtom` pair covering the document container and every slide container.                                                                                                                                                                                               |
-| `encryption`                   | `readDocumentEncryptionAtom`, `decryptPptDocumentStream` — [MS-OFFCRYPTO] 2.3.5 RC4 CryptoAPI decryption, wired against `archive-codec`'s own key derivation (see [Encryption](#encryption)).                                                                                                                            |
-| `document/document-atom`       | `DocumentAtom`: slide and notes sizes, master persist references.                                                                                                                                                                                                                                                        |
-| `document/document-atom-write` | Writes a `DocumentAtom` for the one slide size every slide must share.                                                                                                                                                                                                                                                   |
-| `document/fonts`               | The font collection, resolved to typeface names a `FontIndexRef` indexes.                                                                                                                                                                                                                                                |
-| `document/fonts-write`         | Writes an `Environment`/`FontCollectionContainer` from a document's own distinct font families.                                                                                                                                                                                                                          |
-| `document/slide-list`          | `SlideListWithTextContainer`: each slide's persist reference and its placeholder texts.                                                                                                                                                                                                                                  |
-| `document/slide-list-write`    | Writes a `SlideListWithTextContainer` naming each slide's persist reference, with no placeholder texts.                                                                                                                                                                                                                  |
-| `document/notes-list`          | `NotesListWithTextContainer`: each notes slide's persist reference and its notes identifier. Its own module rather than a parameter of `slide-list`, because the container holds no texts and `NotesPersistAtom` spends on a reserved field what `SlidePersistAtom` spends on `cTexts`.                                  |
-| `document/notes-list-write`    | Writes that container from the same `NotesPersist` shape the reader produces.                                                                                                                                                                                                                                            |
-| `document/notes`               | A `NotesContainer`: its `NotesAtom` (which slide the notes belong to) and the notes text its drawing carries.                                                                                                                                                                                                            |
-| `document/notes-write`         | Writes a `NotesContainer` for one slide's notes, through the same drawing writer a slide's own shapes go through.                                                                                                                                                                                                        |
-| `document/master`              | `readSlideAtom` (`masterIdRef`/`notesIdRef`), `buildMasterStyleTable`, and `resolveCharacterProperties`/`resolveParagraphProperties` — the master text-formatting cascade a run whose own fields are absent resolves against (see [Master and colour inheritance](#master-and-colour-inheritance)).                      |
-| `document/master-write`        | The minimal `MainMasterContainer` and `MasterListWithTextContainer`, plus the `SlideAtom` every slide needs in order to name that master and its own notes slide.                                                                                                                                                        |
-| `document/color-scheme`        | `readSlideSchemeColorSchemeAtom`, `resolveSchemeColor` — resolves a `ColorIndexStruct`'s scheme-slot reference against the slide's (or its master's) own colour scheme.                                                                                                                                                  |
-| `document/color-scheme-write`  | The `SlideSchemeColorSchemeAtom` [MS-PPT] 2.9.51 gives four different containers, two of which this writer produces — the main master and every notes slide — so it belongs to neither of them.                                                                                                                          |
-| `drawing/shapes`               | The OfficeArt shape tree, flattened, with every anchor resolved into slide coordinates through its enclosing groups.                                                                                                                                                                                                     |
-| `drawing/shapes-write`         | Writes the patriarch group and one plain, anchored `OfficeArtSpContainer` per shape.                                                                                                                                                                                                                                     |
-| `text/atoms`                   | The two text-body spellings, the text-type enumeration, and the paragraph split.                                                                                                                                                                                                                                         |
-| `text/style`                   | `StyleTextPropAtom`'s two run arrays and their mask-driven exception structures.                                                                                                                                                                                                                                         |
-| `text/style-write`             | Writes a `StyleTextPropAtom` from the same `StyleRun`/`ParagraphProperties`/`CharacterProperties` shapes `text/style` reads into.                                                                                                                                                                                        |
-| `content`                      | The mapping of PowerPoint's character-counted runs onto the schema's paragraph-owned runs.                                                                                                                                                                                                                               |
-| `content-write`                | The inverse: a shape's `ContentBlock[]` to the flat character-counted text body and `StyleTextProps` `text/style-write` needs.                                                                                                                                                                                           |
-| `metadata`                     | Wraps `archive-codec`'s own `SummaryInformationProperties` <-> `LayoutMetadata` mapping with this package's `createdIso`/`modifiedIso` date validation, throwing `PptUnsupportedContentError` for a malformed one rather than letting an opaque `RangeError` escape the FILETIME conversion (see [Metadata](#metadata)). |
-| `read`                         | The whole read pipeline, and the `readPpt`/`readPptContent`/`readPptStreams` surface.                                                                                                                                                                                                                                    |
-| `write`                        | The whole write pipeline, and the `writePpt`/`writePptContent`/`writePptStreams` surface.                                                                                                                                                                                                                                |
-| `units`                        | Master units to points, and points to master units.                                                                                                                                                                                                                                                                      |
-| `errors`                       | `PptFormatError` for malformed input, `PptEncryptedError` for encrypted input given no password, an incorrect one, or an encryption scheme this package does not implement (anything other than RC4 CryptoAPI), `PptUnsupportedContentError` for well-formed content this package's writer cannot express.               |
+| Module                         | What it owns                                                                                                                                                                                                                                                                                                               |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `record/header`                | The generic 8-byte record header and the container/atom distinction.                                                                                                                                                                                                                                                       |
+| `record/types`                 | The `RecordType` values this reader dispatches on, plus the [MS-ODRAW] types the drawing walk crosses into.                                                                                                                                                                                                                |
+| `record/tree`                  | Offset-addressed records, sibling sequences, child walks, typed-descendant search.                                                                                                                                                                                                                                         |
+| `record/write`                 | Byte primitives and the atom/container builders every writer module below composes records from -- the write-side mirror of `record/header`/`record/tree`, and what this package's own test fixtures build on too.                                                                                                         |
+| `stream/current-user`          | `CurrentUserAtom`: where the live edit is, and whether the file is encrypted.                                                                                                                                                                                                                                              |
+| `stream/current-user-write`    | Writes a real `CurrentUserAtom` pointing at the single edit this writer always produces.                                                                                                                                                                                                                                   |
+| `stream/persist`               | `UserEditAtom`, `PersistDirectoryAtom`, and the persist directory the edit chain builds.                                                                                                                                                                                                                                   |
+| `stream/persist-write`         | Writes a single-edit `UserEditAtom`/`PersistDirectoryAtom` pair covering the document container and every slide container.                                                                                                                                                                                                 |
+| `encryption`                   | `readDocumentEncryptionAtom`, `decryptPptDocumentStream` — [MS-OFFCRYPTO] 2.3.5 RC4 CryptoAPI decryption, wired against `archive-codec`'s own key derivation (see [Encryption](#encryption)).                                                                                                                              |
+| `document/document-atom`       | `DocumentAtom`: slide and notes sizes, master persist references.                                                                                                                                                                                                                                                          |
+| `document/document-atom-write` | Writes a `DocumentAtom` for the one slide size every slide must share.                                                                                                                                                                                                                                                     |
+| `document/fonts`               | The font collection, resolved to typeface names a `FontIndexRef` indexes.                                                                                                                                                                                                                                                  |
+| `document/fonts-write`         | Writes an `Environment`/`FontCollectionContainer` from a document's own distinct font families.                                                                                                                                                                                                                            |
+| `document/slide-list`          | `SlideListWithTextContainer`: each slide's persist reference and its placeholder texts.                                                                                                                                                                                                                                    |
+| `document/slide-list-write`    | Writes a `SlideListWithTextContainer` naming each slide's persist reference, with no placeholder texts.                                                                                                                                                                                                                    |
+| `document/notes-list`          | `NotesListWithTextContainer`: each notes slide's persist reference and its notes identifier. Its own module rather than a parameter of `slide-list`, because the container holds no texts and `NotesPersistAtom` spends on a reserved field what `SlidePersistAtom` spends on `cTexts`.                                    |
+| `document/notes-list-write`    | Writes that container from the same `NotesPersist` shape the reader produces.                                                                                                                                                                                                                                              |
+| `document/notes`               | A `NotesContainer`: its `NotesAtom` (which slide the notes belong to) and the notes text its drawing carries.                                                                                                                                                                                                              |
+| `document/notes-write`         | Writes a `NotesContainer` for one slide's notes, through the same drawing writer a slide's own shapes go through.                                                                                                                                                                                                          |
+| `document/master`              | `readSlideAtom` (`masterIdRef`/`notesIdRef`), `buildMasterStyleTable`, and `resolveCharacterProperties`/`resolveParagraphProperties` — the master text-formatting cascade a run whose own fields are absent resolves against (see [Master and colour inheritance](#master-and-colour-inheritance)).                        |
+| `document/master-write`        | The minimal `MainMasterContainer` and `MasterListWithTextContainer`, plus the `SlideAtom` every slide needs in order to name that master and its own notes slide.                                                                                                                                                          |
+| `document/color-scheme`        | `readSlideSchemeColorSchemeAtom`, `resolveSchemeColor` — resolves a `ColorIndexStruct`'s scheme-slot reference against the slide's (or its master's) own colour scheme.                                                                                                                                                    |
+| `document/color-scheme-write`  | The `SlideSchemeColorSchemeAtom` [MS-PPT] 2.9.51 gives four different containers, two of which this writer produces — the main master and every notes slide — so it belongs to neither of them.                                                                                                                            |
+| `drawing/shapes`               | The OfficeArt shape tree, flattened, with every anchor resolved into slide coordinates through its enclosing groups.                                                                                                                                                                                                       |
+| `drawing/shapes-write`         | Writes the patriarch group and one plain, anchored `OfficeArtSpContainer` per shape.                                                                                                                                                                                                                                       |
+| `text/atoms`                   | The two text-body spellings, the text-type enumeration, and the paragraph split.                                                                                                                                                                                                                                           |
+| `text/style`                   | `StyleTextPropAtom`'s two run arrays and their mask-driven exception structures.                                                                                                                                                                                                                                           |
+| `text/style-write`             | Writes a `StyleTextPropAtom` from the same `StyleRun`/`ParagraphProperties`/`CharacterProperties` shapes `text/style` reads into.                                                                                                                                                                                          |
+| `content`                      | The mapping of PowerPoint's character-counted runs onto the schema's paragraph-owned runs.                                                                                                                                                                                                                                 |
+| `content-write`                | The inverse: a shape's `ContentBlock[]` to the flat character-counted text body and `StyleTextProps` `text/style-write` needs.                                                                                                                                                                                             |
+| `metadata`                     | Wraps `archive-codec`'s own `SummaryInformationProperties` <-> `LayoutMetadata` mapping with this package's `createdIso`/`modifiedIso` date validation, throwing `PptUnsupportedContentError` for a malformed one rather than letting an opaque `RangeError` escape the FILETIME conversion (see [Metadata](#metadata)).   |
+| `read`                         | The whole read pipeline, and the `readPpt`/`readPptContent`/`readPptStreams` surface.                                                                                                                                                                                                                                      |
+| `write`                        | The whole write pipeline, and the `writePpt`/`writePptContent`/`writePptStreams` surface.                                                                                                                                                                                                                                  |
+| `units`                        | Master units to points, and points to master units.                                                                                                                                                                                                                                                                        |
+| `errors`                       | `PptFormatError` for malformed input, `PptEncryptedError` for encrypted input given no password, an incorrect one, or an encryption scheme this package does not implement (anything other than RC4 CryptoAPI), `PptUnsupportedContentError` for well-formed content this package's writer cannot express.                 |
+| `diagnostics`                  | `PptDiagnostic`/`PptDiagnosticSink`/`NOOP_PPT_DIAGNOSTIC_SINK` and the stable `PptDiagnosticCodes` a caller branches on — the write-side channel a dropped image, block, or table span fires through, matching the shape markdown-codec's, pdf-codec's, epub-codec's, and rtf-codec's own diagnostic channels already use. |
 
 ### Every fixture is built from the specification, not captured
 
@@ -281,7 +297,7 @@ The [MS-CFB] container beneath the format is the one piece not hand-written agai
 
 - Worker-isomorphic (see the [family-wide convention](../../README.md#conventions)): runtime `src/` must not import `node:*`, a bare Node builtin, or use the `Buffer` global — enforced by a `no-restricted-imports`/`no-restricted-globals` ESLint rule and exercised in CI by running a suite inside an actual `workerd` isolate (`pnpm test:workers`). Test files under `src/**/*.test.ts` and `src/test-support/` are exempt and may use Node APIs for fixtures.
 - Only `src/index.ts` may be named `index.*` — a custom ESLint rule (`local/no-non-barrel-index`) rejects any other module using an `index` basename, since that would be a hidden entry point the `exports` map in `package.json` doesn't advertise.
-- Every structural failure throws `PptFormatError` rather than degrading: a malformed file fails whole, never returning a partial slide list that looks complete. On the write side, content this writer cannot express throws `PptUnsupportedContentError` rather than silently substituting or dropping it — except a block kind outside this writer's scope (an image, a table, a construct marker), which is excluded from the written text body by design and documented as such, the same convention the reader already applies to its own unsupported constructs.
+- Every structural failure throws `PptFormatError` rather than degrading: a malformed file fails whole, never returning a partial slide list that looks complete. On the write side, content genuinely outside this writer's own scope (a document that is not a presentation, slides that disagree on size) throws `PptUnsupportedContentError`. A block kind this writer cannot represent at all (an image, a table, a construct marker) is different: by default it is excluded from the written text body with a diagnostic naming it, never approximated, and `WritePptOptions.onUnwritableBlock: 'throw'` lets a caller opt into raising `PptUnsupportedContentError` for that case too — see [Silent drop, or a thrown error](#silent-drop-or-a-thrown-error) for why the default stays a diagnosed drop rather than a throw.
 
 ## Specification references
 

package/dist/base64.cjs

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/base64.ts
+const TABLE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const DECODE = (() => {
+	const map = (/* @__PURE__ */ new Uint8Array(256)).fill(255);
+	for (let index = 0; index < 64; index += 1) map[TABLE.charCodeAt(index)] = index;
+	return map;
+})();
+function bytesToBase64(bytes) {
+	let out = "";
+	const len = bytes.length;
+	for (let index = 0; index < len; index += 3) {
+		const b0 = bytes[index] ?? 0;
+		const b1 = index + 1 < len ? bytes[index + 1] ?? 0 : 0;
+		const b2 = index + 2 < len ? bytes[index + 2] ?? 0 : 0;
+		out += TABLE.charAt(b0 >> 2);
+		out += TABLE.charAt((b0 & 3) << 4 | b1 >> 4);
+		out += index + 1 < len ? TABLE.charAt((b1 & 15) << 2 | b2 >> 6) : "=";
+		out += index + 2 < len ? TABLE.charAt(b2 & 63) : "=";
+	}
+	return out;
+}
+function base64ToBytes(base64) {
+	const clean = base64.replace(/[^A-Za-z0-9+/=]/g, "");
+	const len = clean.length;
+	const out = new Uint8Array(len * 3 / 4 | 0);
+	let position = 0;
+	for (let index = 0; index < len; index += 4) {
+		const c0 = DECODE[clean.charCodeAt(index)] ?? 255;
+		const c1 = DECODE[clean.charCodeAt(index + 1)] ?? 255;
+		const c2 = clean.charCodeAt(index + 2);
+		const c3 = clean.charCodeAt(index + 3);
+		if (c0 === 255 || c1 === 255) throw new Error("invalid base64 input");
+		out[position++] = c0 << 2 | c1 >> 4;
+		if (c2 !== 61) {
+			const d2 = DECODE[c2] ?? 255;
+			out[position++] = (c1 & 15) << 4 | d2 >> 2;
+			if (c3 !== 61) {
+				const d3 = DECODE[c3] ?? 255;
+				out[position++] = (d2 & 3) << 6 | d3;
+			}
+		}
+	}
+	return out.subarray(0, position);
+}
+//#endregion
+exports.base64ToBytes = base64ToBytes;
+exports.bytesToBase64 = bytesToBase64;

package/dist/base64.d.cts

@@ -0,0 +1,5 @@
+//#region src/base64.d.ts
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToBytes(base64: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { base64ToBytes, bytesToBase64 };

package/dist/base64.d.ts

@@ -0,0 +1,5 @@
+//#region src/base64.d.ts
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToBytes(base64: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { base64ToBytes, bytesToBase64 };

package/dist/base64.js

@@ -0,0 +1,46 @@
+//#region src/base64.ts
+const TABLE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const DECODE = (() => {
+	const map = (/* @__PURE__ */ new Uint8Array(256)).fill(255);
+	for (let index = 0; index < 64; index += 1) map[TABLE.charCodeAt(index)] = index;
+	return map;
+})();
+function bytesToBase64(bytes) {
+	let out = "";
+	const len = bytes.length;
+	for (let index = 0; index < len; index += 3) {
+		const b0 = bytes[index] ?? 0;
+		const b1 = index + 1 < len ? bytes[index + 1] ?? 0 : 0;
+		const b2 = index + 2 < len ? bytes[index + 2] ?? 0 : 0;
+		out += TABLE.charAt(b0 >> 2);
+		out += TABLE.charAt((b0 & 3) << 4 | b1 >> 4);
+		out += index + 1 < len ? TABLE.charAt((b1 & 15) << 2 | b2 >> 6) : "=";
+		out += index + 2 < len ? TABLE.charAt(b2 & 63) : "=";
+	}
+	return out;
+}
+function base64ToBytes(base64) {
+	const clean = base64.replace(/[^A-Za-z0-9+/=]/g, "");
+	const len = clean.length;
+	const out = new Uint8Array(len * 3 / 4 | 0);
+	let position = 0;
+	for (let index = 0; index < len; index += 4) {
+		const c0 = DECODE[clean.charCodeAt(index)] ?? 255;
+		const c1 = DECODE[clean.charCodeAt(index + 1)] ?? 255;
+		const c2 = clean.charCodeAt(index + 2);
+		const c3 = clean.charCodeAt(index + 3);
+		if (c0 === 255 || c1 === 255) throw new Error("invalid base64 input");
+		out[position++] = c0 << 2 | c1 >> 4;
+		if (c2 !== 61) {
+			const d2 = DECODE[c2] ?? 255;
+			out[position++] = (c1 & 15) << 4 | d2 >> 2;
+			if (c3 !== 61) {
+				const d3 = DECODE[c3] ?? 255;
+				out[position++] = (d2 & 3) << 6 | d3;
+			}
+		}
+	}
+	return out.subarray(0, position);
+}
+//#endregion
+export { base64ToBytes, bytesToBase64 };

package/dist/diagnostics-CqxAnubw.d.cts

@@ -0,0 +1,16 @@
+//#region src/diagnostics.d.ts
+type PptDiagnosticSeverity = "info" | "warning";
+interface PptDiagnostic {
+  readonly code: string;
+  readonly severity: PptDiagnosticSeverity;
+  readonly message: string;
+}
+type PptDiagnosticSink = (diagnostic: PptDiagnostic) => void;
+declare const NOOP_PPT_DIAGNOSTIC_SINK: PptDiagnosticSink;
+declare const PptDiagnosticCodes: {
+  readonly IMAGE_DROPPED: "ppt/image-dropped";
+  readonly BLOCK_DROPPED: "ppt/block-dropped";
+  readonly TABLE_SPAN_DROPPED: "ppt/table-span-dropped";
+};
+//#endregion
+export { PptDiagnosticSink as a, PptDiagnosticSeverity as i, PptDiagnostic as n, PptDiagnosticCodes as r, NOOP_PPT_DIAGNOSTIC_SINK as t };

package/dist/diagnostics-CqxAnubw.d.ts

@@ -0,0 +1,16 @@
+//#region src/diagnostics.d.ts
+type PptDiagnosticSeverity = "info" | "warning";
+interface PptDiagnostic {
+  readonly code: string;
+  readonly severity: PptDiagnosticSeverity;
+  readonly message: string;
+}
+type PptDiagnosticSink = (diagnostic: PptDiagnostic) => void;
+declare const NOOP_PPT_DIAGNOSTIC_SINK: PptDiagnosticSink;
+declare const PptDiagnosticCodes: {
+  readonly IMAGE_DROPPED: "ppt/image-dropped";
+  readonly BLOCK_DROPPED: "ppt/block-dropped";
+  readonly TABLE_SPAN_DROPPED: "ppt/table-span-dropped";
+};
+//#endregion
+export { PptDiagnosticSink as a, PptDiagnosticSeverity as i, PptDiagnostic as n, PptDiagnosticCodes as r, NOOP_PPT_DIAGNOSTIC_SINK as t };

package/dist/diagnostics.cjs

@@ -0,0 +1,11 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/diagnostics.ts
+const NOOP_PPT_DIAGNOSTIC_SINK = () => {};
+const PptDiagnosticCodes = {
+	IMAGE_DROPPED: "ppt/image-dropped",
+	BLOCK_DROPPED: "ppt/block-dropped",
+	TABLE_SPAN_DROPPED: "ppt/table-span-dropped"
+};
+//#endregion
+exports.NOOP_PPT_DIAGNOSTIC_SINK = NOOP_PPT_DIAGNOSTIC_SINK;
+exports.PptDiagnosticCodes = PptDiagnosticCodes;

package/dist/diagnostics.d.cts

@@ -0,0 +1,2 @@
+import { a as PptDiagnosticSink, i as PptDiagnosticSeverity, n as PptDiagnostic, r as PptDiagnosticCodes, t as NOOP_PPT_DIAGNOSTIC_SINK } from "./diagnostics-CqxAnubw.cjs";
+export { NOOP_PPT_DIAGNOSTIC_SINK, PptDiagnostic, PptDiagnosticCodes, PptDiagnosticSeverity, PptDiagnosticSink };

package/dist/diagnostics.d.ts

@@ -0,0 +1,2 @@
+import { a as PptDiagnosticSink, i as PptDiagnosticSeverity, n as PptDiagnostic, r as PptDiagnosticCodes, t as NOOP_PPT_DIAGNOSTIC_SINK } from "./diagnostics-CqxAnubw.js";
+export { NOOP_PPT_DIAGNOSTIC_SINK, PptDiagnostic, PptDiagnosticCodes, PptDiagnosticSeverity, PptDiagnosticSink };

package/dist/diagnostics.js

@@ -0,0 +1,9 @@
+//#region src/diagnostics.ts
+const NOOP_PPT_DIAGNOSTIC_SINK = () => {};
+const PptDiagnosticCodes = {
+	IMAGE_DROPPED: "ppt/image-dropped",
+	BLOCK_DROPPED: "ppt/block-dropped",
+	TABLE_SPAN_DROPPED: "ppt/table-span-dropped"
+};
+//#endregion
+export { NOOP_PPT_DIAGNOSTIC_SINK, PptDiagnosticCodes };

package/dist/document/color-scheme.cjs

@@ -32,6 +32,10 @@ function resolveSchemeColor(schemeIndex, colorScheme) {
 	if (color === void 0) throw new require_errors.PptFormatError(`colour scheme slot ${schemeIndex} has no entry in a ${colorScheme.length}-entry colour scheme`);
 	return color;
 }
+function findSlideSchemeColorSchemeAtom(records) {
+	return records.find((record) => record.header.recType === 2032 && record.header.recInstance === SLIDE_SCHEME_REC_INSTANCE);
+}
 //#endregion
+exports.findSlideSchemeColorSchemeAtom = findSlideSchemeColorSchemeAtom;
 exports.readSlideSchemeColorSchemeAtom = readSlideSchemeColorSchemeAtom;
 exports.resolveSchemeColor = resolveSchemeColor;

package/dist/document/color-scheme.d.cts

@@ -4,5 +4,6 @@ import { RgbColor } from "../text/style.cjs";
 declare function readSlideSchemeColorSchemeAtom(record: PptRecord): readonly RgbColor[];
 /** Resolves a scheme-slot index (0-7, see text/style.ts's own ColorIndexStruct table) against a resolved 8-entry colour scheme. Throws rather than returning undefined for an out-of-range index: readColorIndexStruct already rejects any index outside 0x00-0x07/0xFE/0xFF at parse time, so a RunColor of kind "scheme" reaching this function always carries a genuinely valid slot. */
 declare function resolveSchemeColor(schemeIndex: number, colorScheme: readonly RgbColor[]): RgbColor;
+declare function findSlideSchemeColorSchemeAtom(records: readonly PptRecord[]): PptRecord | undefined;
 //#endregion
-export { readSlideSchemeColorSchemeAtom, resolveSchemeColor };
+export { findSlideSchemeColorSchemeAtom, readSlideSchemeColorSchemeAtom, resolveSchemeColor };