ppt-codec 1.2.13 → 1.4.0

package/README.md

@@ -57,7 +57,51 @@ for (const slide of slides) {
 }
 ```
 
-`readPptStreams(currentUserStream, powerPointDocumentStream)` is the same read one level down, for a caller that already holds the two streams — the compound file beneath them is `archive-codec`'s business, and separating the two is what lets every record-level behaviour be tested without a container around it.
+`readPptStreams(currentUserStream, powerPointDocumentStream, password)` is the same read one level down, for a caller that already holds the two streams — the compound file beneath them is `archive-codec`'s business, and separating the two is what lets every record-level behaviour be tested without a container around it.
+
+## Encryption
+
+A `.ppt` protected with a password to open uses [MS-OFFCRYPTO] 2.3.5 "RC4 CryptoAPI Encryption" — genuinely different from the MD5-based scheme `xls-codec` and `doc-codec` share (ExaDev/documents.js#1108/#1113): SHA-1-based key derivation with no intermediate-hash iteration, and re-keying per persist object rather than at a fixed byte interval. `readPpt`/`readPptContent`/`readPptStreams` take an optional `password`, ignored for an unencrypted presentation; a missing or incorrect password against an encrypted one throws `PptEncryptedError` rather than returning a partial or garbled document, and so does an encryption shape this package does not implement (anything other than RC4 CryptoAPI — [MS-PPT] itself never specifies any other scheme for the binary format).
+
+```ts
+import { readPptContent } from "ppt-codec";
+
+const { metadata, slides } = readPptContent(
+  pptBytes,
+  "correct horse battery staple",
+);
+```
+
+`archive-codec`'s `crypto/office-rc4-cryptoapi` module (ExaDev/documents.js#1116) carries the key derivation and password verification; this package's own `src/encryption.ts` carries the container-specific pieces, which differ from both xls-codec's and doc-codec's shared scheme in three real ways:
+
+- **Location.** There is no fixed-offset header at all. The `DocumentEncryptionAtom` (`RT_CryptSession10Container`, [MS-PPT]'s own name for record type 0x2F14) is just another persist object, reached only by walking the current `UserEditAtom.encryptSessionPersistIdRef` through the same persist directory every other record uses.
+- **Re-keying granularity.** Each top-level persist object gets its own RC4 key, derived from its own persist ID as the "block number" — not a running byte offset within one continuous stream, the way both `xls-codec`'s FilePass scheme and `doc-codec`'s own EncryptionHeader scheme re-key.
+- **Encrypted headers.** A persist object's own 8-byte record header is encrypted along with its data, unlike the never-encrypted headers the shared xls/doc scheme leaves alone — `decryptPptDocumentStream` decrypts a peek of those 8 bytes first, under the object's own key, to learn its real length before decrypting the object in full.
+
+Pictures in a separate `Pictures` stream are also RC4 CryptoAPI-encrypted per [MS-PPT], but this package does not read the `Pictures` stream at all today (see [Images, tables, and OLE embeddings](#what-it-does-not-read-yet)), so decrypting it is out of scope until something needs to.
+
+`writePptContent` never encrypts.
+
+## Master and colour inheritance
+
+A real `.ppt` deck overwhelmingly relies on master-inherited formatting rather than direct, per-run formatting: a title placeholder typically states its own text and nothing else, leaving size, typeface, weight, and colour entirely to its slide's own master. `readPptStreams`/`readPptContent`/`readPpt` resolve this cascade for every run, not just report the run's own direct formatting as before.
+
+```ts
+import { readPptContent } from "ppt-codec";
+
+const { slides } = readPptContent(pptBytes);
+// A run whose own TextCFException states neither bold nor colour still
+// reports both here, resolved against its master and the slide's own
+// colour scheme.
+slides[0]?.shapes[0]?.blocks[0]?.runs[0]?.bold;
+slides[0]?.shapes[0]?.blocks[0]?.runs[0]?.color;
+```
+
+**Text-formatting cascade** (`document/master.ts`): a run's own `TextPFException`/`TextCFException` field wins outright when it states one. For everything it leaves unstated, resolution walks the applicable `TextMasterStyleAtom` from the run's own (clamped) outline level down to level 0, then -- if the run's own `TextTypeEnum` is a variant with no cascade of its own (`CENTER_BODY`/`HALF_BODY`/`QUARTER_BODY` retry as plain `BODY`; `CENTER_TITLE` retries as plain `TITLE`) -- repeats the same walk against the fallback type. `NOTES` and `OTHER` have no further fallback. A `TextTypeEnum` a slide's own master carries no atom for falls back to the single document-wide default `TextMasterStyleAtom` [MS-PPT] 2.9.35 states lives inside `DocumentTextInfoContainer` (a child of `Environment`), the fallback of last resort for every type.
+
+**Multi-master resolution**: unlike this package's own writer, which only ever produces one `MainMasterContainer`, a real file can carry several (different design templates within one deck). Every slide's own `SlideAtom.masterIdRef` is read and resolved against the master list, not assumed to be the deck's only master.
+
+**Colour-scheme resolution** (`document/color-scheme.ts`) is a separate, simpler step: a `ColorIndexStruct` naming a colour-scheme slot (`0x00`-`0x07` -- background, text, shadow, title text, fill, Accent 1, Accent 2, Accent 3) resolves against the slide's own `SlideSchemeColorSchemeAtom` when it carries one, or its master's otherwise. Unlike text formatting, this never walks a master-level cascade: [MS-PPT] mandates every slide-shaped container carry its own complete colour scheme (a slide that visually "follows the master's scheme" does so by a real producer duplicating the master's own values into it), so a slide's own scheme is the only place this reader looks first.
 
 ## Writing a document
 
@@ -79,17 +123,19 @@ const bytes = writePptContent({ metadata: {}, slides });
 
 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.                                                                                                                                                                                                    |
-| Document        | `DocumentContainer` → `DocumentAtom` (slide size, in master units), `DocumentTextInfoContainer`'s `FontCollectionContainer`/`FontEntityAtom` typeface names, and `SlideListWithTextContainer` (distinguished from the master and notes lists by `recInstance`, which does not run in the order the names suggest).                                                                                                                                                                                                             |
-| Slides          | `SlidePersistAtom` → the persist directory → each `SlideContainer`, 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 when it is a literal sRGB value), 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. |
+| 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). |
 
 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.
 
@@ -97,10 +143,7 @@ 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:
 
-- **Encrypted documents.** Recognised and refused by name (`PptEncryptedError`) rather than misparsed, but not decrypted.
 - **`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.
-- **Master and layout inheritance.** A run that states no size, typeface, or weight inherits it from the master's `TextMasterStyleAtom`; this reader reports such a property as absent rather than resolving the cascade, so a run's formatting is what the slide itself states and no more.
-- **Scheme colours.** A `ColorIndexStruct` naming a colour-scheme slot (rather than a literal sRGB value) yields no colour, because resolving it needs the slide's `SlideSchemeColorSchemeAtom`.
 - **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.
 - **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".
@@ -198,6 +241,7 @@ import { readStyleTextPropAtom } from "ppt-codec/text/style";
 | `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.                                                                                                                                                                                                                                                |
@@ -208,7 +252,9 @@ import { readStyleTextPropAtom } from "ppt-codec/text/style";
 | `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-write`        | The minimal `MainMasterContainer` and `MasterListWithTextContainer`, plus the `SlideAtom` every slide needs in order to name that master and its own notes slide. Write-only: nothing reads a `SlideAtom` yet.                                                                                                           |
+| `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.                                                                                                                                                                                                                                     |
@@ -221,7 +267,7 @@ import { readStyleTextPropAtom } from "ppt-codec/text/style";
 | `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 well-formed input this package cannot decrypt, `PptUnsupportedContentError` for well-formed content this package's writer cannot express.                                                                                                                  |
+| `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.               |
 
 ### Every fixture is built from the specification, not captured
 

package/dist/content-write.cjs

@@ -24,9 +24,12 @@ function pointsToParaSpacing(pt) {
 function mapColorToPpt(color) {
 	if (color === void 0) return;
 	return {
-		red: Math.round(color.r * BYTE_MAX),
-		green: Math.round(color.g * BYTE_MAX),
-		blue: Math.round(color.b * BYTE_MAX)
+		kind: "rgb",
+		rgb: {
+			red: Math.round(color.r * BYTE_MAX),
+			green: Math.round(color.g * BYTE_MAX),
+			blue: Math.round(color.b * BYTE_MAX)
+		}
 	};
 }
 function storedRunText(text) {

package/dist/content-write.js

@@ -23,9 +23,12 @@ function pointsToParaSpacing(pt) {
 function mapColorToPpt(color) {
 	if (color === void 0) return;
 	return {
-		red: Math.round(color.r * BYTE_MAX),
-		green: Math.round(color.g * BYTE_MAX),
-		blue: Math.round(color.b * BYTE_MAX)
+		kind: "rgb",
+		rgb: {
+			red: Math.round(color.r * BYTE_MAX),
+			green: Math.round(color.g * BYTE_MAX),
+			blue: Math.round(color.b * BYTE_MAX)
+		}
 	};
 }
 function storedRunText(text) {

package/dist/content.cjs

@@ -2,6 +2,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("./text/style.cjs");
 const require_text_atoms = require("./text/atoms.cjs");
 const require_units = require("./units.cjs");
+const require_document_color_scheme = require("./document/color-scheme.cjs");
+const require_document_master = require("./document/master.cjs");
 //#region src/content.ts
 const BYTE_MAX = 255;
 function mapAlignment(alignment) {
@@ -35,6 +37,10 @@ function mapColor(color) {
 		b: color.blue / BYTE_MAX
 	};
 }
+function resolveRunColor(color, colorScheme) {
+	if (color === void 0) return;
+	return color.kind === "rgb" ? color.rgb : require_document_color_scheme.resolveSchemeColor(color.schemeIndex, colorScheme);
+}
 function toExtents(runs) {
 	const extents = [];
 	let at = 0;
@@ -48,7 +54,7 @@ function toExtents(runs) {
 	}
 	return extents;
 }
-function runFrom(text, properties, fontNames) {
+function runFrom(text, properties, fontNames, colorScheme) {
 	return {
 		text,
 		bold: properties.bold,
@@ -56,35 +62,39 @@ function runFrom(text, properties, fontNames) {
 		underline: properties.underline,
 		fontFamily: properties.fontRef === void 0 ? void 0 : fontNames[properties.fontRef],
 		sizePt: properties.sizePt,
-		color: mapColor(properties.color)
+		color: mapColor(resolveRunColor(properties.color, colorScheme))
 	};
 }
-function buildParagraphs(text, style, fontNames) {
+function buildParagraphs(text, style, fontNames, masterStyles, textType, colorScheme) {
 	const paragraphExtents = toExtents(style.paragraphRuns);
 	const characterExtents = toExtents(style.characterRuns);
 	return require_text_atoms.splitParagraphs(text).map((paragraph) => {
 		const end = paragraph.start + paragraph.text.length;
-		const paragraphProperties = paragraphExtents.find((extent) => paragraph.start >= extent.start && paragraph.start < extent.end)?.properties;
+		const rawParagraphProperties = paragraphExtents.find((extent) => paragraph.start >= extent.start && paragraph.start < extent.end)?.properties;
+		const indentLevel = rawParagraphProperties?.indentLevel ?? 0;
+		const paragraphProperties = require_document_master.resolveParagraphProperties(rawParagraphProperties, masterStyles, textType, indentLevel);
 		const runs = [];
 		for (const extent of characterExtents) {
 			const from = Math.max(extent.start, paragraph.start);
 			const to = Math.min(extent.end, end);
 			if (from >= to) continue;
-			runs.push(runFrom(paragraph.text.slice(from - paragraph.start, to - paragraph.start), extent.properties, fontNames));
+			const resolvedCharacterProperties = require_document_master.resolveCharacterProperties(extent.properties, masterStyles, textType, indentLevel);
+			runs.push(runFrom(paragraph.text.slice(from - paragraph.start, to - paragraph.start), resolvedCharacterProperties, fontNames, colorScheme));
+		}
+		if (runs.length === 0 && paragraph.text.length > 0) {
+			const resolvedCharacterProperties = require_document_master.resolveCharacterProperties(void 0, masterStyles, textType, indentLevel);
+			runs.push(runFrom(paragraph.text, resolvedCharacterProperties, fontNames, colorScheme));
 		}
-		if (runs.length === 0 && paragraph.text.length > 0) runs.push({ text: paragraph.text });
-		const alignment = mapAlignment(paragraphProperties?.alignment);
-		const indentLevel = paragraphProperties?.indentLevel ?? 0;
 		return {
 			kind: "paragraph",
 			runs,
-			alignment,
+			alignment: mapAlignment(paragraphProperties.alignment),
 			list: indentLevel > 0 ? { level: indentLevel } : void 0,
-			spacingBeforePt: paraSpacingToPoints(paragraphProperties?.spaceBefore),
-			spacingAfterPt: paraSpacingToPoints(paragraphProperties?.spaceAfter),
-			lineSpacing: paraSpacingToLineSpacing(paragraphProperties?.lineSpacing),
-			indentLeftPt: marginOrIndentToPoints(paragraphProperties?.leftMargin),
-			indentFirstLinePt: marginOrIndentToPoints(paragraphProperties?.indent)
+			spacingBeforePt: paraSpacingToPoints(paragraphProperties.spaceBefore),
+			spacingAfterPt: paraSpacingToPoints(paragraphProperties.spaceAfter),
+			lineSpacing: paraSpacingToLineSpacing(paragraphProperties.lineSpacing),
+			indentLeftPt: marginOrIndentToPoints(paragraphProperties.leftMargin),
+			indentFirstLinePt: marginOrIndentToPoints(paragraphProperties.indent)
 		};
 	});
 }

package/dist/content.d.cts

@@ -1,6 +1,7 @@
-import { StyleTextProps } from "./text/style.cjs";
+import { RgbColor, StyleTextProps } from "./text/style.cjs";
+import { n as MasterStyleTable } from "./master-zlMRXyPU.cjs";
 import { ContentParagraph } from "document-schema.js";
 //#region src/content.d.ts
-declare function buildParagraphs(text: string, style: StyleTextProps, fontNames: readonly string[]): ContentParagraph[];
+declare function buildParagraphs(text: string, style: StyleTextProps, fontNames: readonly string[], masterStyles: MasterStyleTable, textType: number, colorScheme: readonly RgbColor[]): ContentParagraph[];
 //#endregion
 export { buildParagraphs };

package/dist/content.d.ts

@@ -1,6 +1,7 @@
-import { StyleTextProps } from "./text/style.js";
+import { RgbColor, StyleTextProps } from "./text/style.js";
+import { n as MasterStyleTable } from "./master-Cs_sDM1-.js";
 import { ContentParagraph } from "document-schema.js";
 //#region src/content.d.ts
-declare function buildParagraphs(text: string, style: StyleTextProps, fontNames: readonly string[]): ContentParagraph[];
+declare function buildParagraphs(text: string, style: StyleTextProps, fontNames: readonly string[], masterStyles: MasterStyleTable, textType: number, colorScheme: readonly RgbColor[]): ContentParagraph[];
 //#endregion
 export { buildParagraphs };

package/dist/content.js

@@ -1,6 +1,8 @@
 import "./text/style.js";
 import { splitParagraphs } from "./text/atoms.js";
 import { masterUnitsToPoints } from "./units.js";
+import { resolveSchemeColor } from "./document/color-scheme.js";
+import { resolveCharacterProperties, resolveParagraphProperties } from "./document/master.js";
 //#region src/content.ts
 const BYTE_MAX = 255;
 function mapAlignment(alignment) {
@@ -34,6 +36,10 @@ function mapColor(color) {
 		b: color.blue / BYTE_MAX
 	};
 }
+function resolveRunColor(color, colorScheme) {
+	if (color === void 0) return;
+	return color.kind === "rgb" ? color.rgb : resolveSchemeColor(color.schemeIndex, colorScheme);
+}
 function toExtents(runs) {
 	const extents = [];
 	let at = 0;
@@ -47,7 +53,7 @@ function toExtents(runs) {
 	}
 	return extents;
 }
-function runFrom(text, properties, fontNames) {
+function runFrom(text, properties, fontNames, colorScheme) {
 	return {
 		text,
 		bold: properties.bold,
@@ -55,35 +61,39 @@ function runFrom(text, properties, fontNames) {
 		underline: properties.underline,
 		fontFamily: properties.fontRef === void 0 ? void 0 : fontNames[properties.fontRef],
 		sizePt: properties.sizePt,
-		color: mapColor(properties.color)
+		color: mapColor(resolveRunColor(properties.color, colorScheme))
 	};
 }
-function buildParagraphs(text, style, fontNames) {
+function buildParagraphs(text, style, fontNames, masterStyles, textType, colorScheme) {
 	const paragraphExtents = toExtents(style.paragraphRuns);
 	const characterExtents = toExtents(style.characterRuns);
 	return splitParagraphs(text).map((paragraph) => {
 		const end = paragraph.start + paragraph.text.length;
-		const paragraphProperties = paragraphExtents.find((extent) => paragraph.start >= extent.start && paragraph.start < extent.end)?.properties;
+		const rawParagraphProperties = paragraphExtents.find((extent) => paragraph.start >= extent.start && paragraph.start < extent.end)?.properties;
+		const indentLevel = rawParagraphProperties?.indentLevel ?? 0;
+		const paragraphProperties = resolveParagraphProperties(rawParagraphProperties, masterStyles, textType, indentLevel);
 		const runs = [];
 		for (const extent of characterExtents) {
 			const from = Math.max(extent.start, paragraph.start);
 			const to = Math.min(extent.end, end);
 			if (from >= to) continue;
-			runs.push(runFrom(paragraph.text.slice(from - paragraph.start, to - paragraph.start), extent.properties, fontNames));
+			const resolvedCharacterProperties = resolveCharacterProperties(extent.properties, masterStyles, textType, indentLevel);
+			runs.push(runFrom(paragraph.text.slice(from - paragraph.start, to - paragraph.start), resolvedCharacterProperties, fontNames, colorScheme));
+		}
+		if (runs.length === 0 && paragraph.text.length > 0) {
+			const resolvedCharacterProperties = resolveCharacterProperties(void 0, masterStyles, textType, indentLevel);
+			runs.push(runFrom(paragraph.text, resolvedCharacterProperties, fontNames, colorScheme));
 		}
-		if (runs.length === 0 && paragraph.text.length > 0) runs.push({ text: paragraph.text });
-		const alignment = mapAlignment(paragraphProperties?.alignment);
-		const indentLevel = paragraphProperties?.indentLevel ?? 0;
 		return {
 			kind: "paragraph",
 			runs,
-			alignment,
+			alignment: mapAlignment(paragraphProperties.alignment),
 			list: indentLevel > 0 ? { level: indentLevel } : void 0,
-			spacingBeforePt: paraSpacingToPoints(paragraphProperties?.spaceBefore),
-			spacingAfterPt: paraSpacingToPoints(paragraphProperties?.spaceAfter),
-			lineSpacing: paraSpacingToLineSpacing(paragraphProperties?.lineSpacing),
-			indentLeftPt: marginOrIndentToPoints(paragraphProperties?.leftMargin),
-			indentFirstLinePt: marginOrIndentToPoints(paragraphProperties?.indent)
+			spacingBeforePt: paraSpacingToPoints(paragraphProperties.spaceBefore),
+			spacingAfterPt: paraSpacingToPoints(paragraphProperties.spaceAfter),
+			lineSpacing: paraSpacingToLineSpacing(paragraphProperties.lineSpacing),
+			indentLeftPt: marginOrIndentToPoints(paragraphProperties.leftMargin),
+			indentFirstLinePt: marginOrIndentToPoints(paragraphProperties.indent)
 		};
 	});
 }

package/dist/document/color-scheme.cjs

@@ -0,0 +1,37 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors.cjs");
+const require_record_types = require("../record/types.cjs");
+require("../text/style.cjs");
+//#region src/document/color-scheme.ts
+const SLIDE_SCHEME_REC_INSTANCE = 1;
+const COLOR_STRUCT_SIZE = 4;
+function readSlideSchemeColorSchemeAtom(record) {
+	if (record.header.recType !== 2032) throw new require_errors.PptFormatError(`expected RT_ColorSchemeAtom (0x${require_record_types.RT_ColorSchemeAtom.toString(16)}) at offset ${record.offset}, found record type 0x${record.header.recType.toString(16)}`);
+	if (record.header.recInstance !== SLIDE_SCHEME_REC_INSTANCE) throw new require_errors.PptFormatError(`ColorSchemeAtom at offset ${record.offset} declares recInstance 0x${record.header.recInstance.toString(16)}, not the SlideSchemeColorSchemeAtom's own 0x${SLIDE_SCHEME_REC_INSTANCE.toString(16)}`);
+	const expectedLength = 32;
+	if (record.data.length !== expectedLength) throw new require_errors.PptFormatError(`SlideSchemeColorSchemeAtom at offset ${record.offset} carries ${record.data.length} bytes, not the mandated ${expectedLength} (8 four-byte scheme slots)`);
+	const { data } = record;
+	const colors = [];
+	for (let slot = 0; slot < 8; slot += 1) {
+		const at = slot * COLOR_STRUCT_SIZE;
+		const red = data[at];
+		const green = data[at + 1];
+		const blue = data[at + 2];
+		if (red === void 0 || green === void 0 || blue === void 0) throw new require_errors.PptFormatError(`SlideSchemeColorSchemeAtom slot ${slot} at offset ${record.offset + at} is missing bytes`);
+		colors.push({
+			red,
+			green,
+			blue
+		});
+	}
+	return colors;
+}
+/** 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. */
+function resolveSchemeColor(schemeIndex, colorScheme) {
+	const color = colorScheme[schemeIndex];
+	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;
+}
+//#endregion
+exports.readSlideSchemeColorSchemeAtom = readSlideSchemeColorSchemeAtom;
+exports.resolveSchemeColor = resolveSchemeColor;

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

@@ -0,0 +1,8 @@
+import { t as PptRecord } from "../tree-Du_LXAF0.cjs";
+import { RgbColor } from "../text/style.cjs";
+//#region src/document/color-scheme.d.ts
+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;
+//#endregion
+export { readSlideSchemeColorSchemeAtom, resolveSchemeColor };

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

@@ -0,0 +1,8 @@
+import { t as PptRecord } from "../tree-PMcPNgd-.js";
+import { RgbColor } from "../text/style.js";
+//#region src/document/color-scheme.d.ts
+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;
+//#endregion
+export { readSlideSchemeColorSchemeAtom, resolveSchemeColor };

package/dist/document/color-scheme.js

@@ -0,0 +1,35 @@
+import { PptFormatError } from "../errors.js";
+import { RT_ColorSchemeAtom } from "../record/types.js";
+import "../text/style.js";
+//#region src/document/color-scheme.ts
+const SLIDE_SCHEME_REC_INSTANCE = 1;
+const COLOR_STRUCT_SIZE = 4;
+function readSlideSchemeColorSchemeAtom(record) {
+	if (record.header.recType !== 2032) throw new PptFormatError(`expected RT_ColorSchemeAtom (0x${RT_ColorSchemeAtom.toString(16)}) at offset ${record.offset}, found record type 0x${record.header.recType.toString(16)}`);
+	if (record.header.recInstance !== SLIDE_SCHEME_REC_INSTANCE) throw new PptFormatError(`ColorSchemeAtom at offset ${record.offset} declares recInstance 0x${record.header.recInstance.toString(16)}, not the SlideSchemeColorSchemeAtom's own 0x${SLIDE_SCHEME_REC_INSTANCE.toString(16)}`);
+	const expectedLength = 32;
+	if (record.data.length !== expectedLength) throw new PptFormatError(`SlideSchemeColorSchemeAtom at offset ${record.offset} carries ${record.data.length} bytes, not the mandated ${expectedLength} (8 four-byte scheme slots)`);
+	const { data } = record;
+	const colors = [];
+	for (let slot = 0; slot < 8; slot += 1) {
+		const at = slot * COLOR_STRUCT_SIZE;
+		const red = data[at];
+		const green = data[at + 1];
+		const blue = data[at + 2];
+		if (red === void 0 || green === void 0 || blue === void 0) throw new PptFormatError(`SlideSchemeColorSchemeAtom slot ${slot} at offset ${record.offset + at} is missing bytes`);
+		colors.push({
+			red,
+			green,
+			blue
+		});
+	}
+	return colors;
+}
+/** 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. */
+function resolveSchemeColor(schemeIndex, colorScheme) {
+	const color = colorScheme[schemeIndex];
+	if (color === void 0) throw new PptFormatError(`colour scheme slot ${schemeIndex} has no entry in a ${colorScheme.length}-entry colour scheme`);
+	return color;
+}
+//#endregion
+export { readSlideSchemeColorSchemeAtom, resolveSchemeColor };

package/dist/document/master.cjs

@@ -0,0 +1,82 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors.cjs");
+const require_record_types = require("../record/types.cjs");
+require("../text/atoms.cjs");
+//#region src/document/master.ts
+/** Builds one MainMasterContainer's own MasterStyleTable from its direct-child TextMasterStyleAtoms, falling back to the document-wide default (the single OTHER-typed TextMasterStyleAtom [MS-PPT] states lives in the DocumentTextInfoContainer inside Environment) for any TextTypeEnum member the master itself carries no atom for. A real master this package's own writer produces always states TITLE/BODY/NOTES explicitly (master-write.ts's own comment), so the document default is realistically only ever consulted for OTHER-typed runs or a third-party master that omits one of the three -- but [MS-PPT] 2.9.35 makes it the genuine fallback of last resort for every type, not a special case for OTHER alone. */
+function buildMasterStyleTable(masterAtoms, documentDefault) {
+	const byType = /* @__PURE__ */ new Map();
+	if (documentDefault !== void 0) byType.set(documentDefault.textType, documentDefault.levels);
+	for (const atom of masterAtoms) byType.set(atom.textType, atom.levels);
+	return { byType };
+}
+function typeFamilyFallback(textType) {
+	switch (textType) {
+		case 5:
+		case 7:
+		case 8: return 1;
+		case 6: return 0;
+		default: return;
+	}
+}
+function orderedMasterLevels(table, textType, indentLevel) {
+	const levelsFor = (type) => {
+		const levels = table.byType.get(type);
+		if (levels === void 0 || levels.length === 0) return [];
+		const clampedLevel = Math.min(indentLevel, levels.length - 1);
+		return levels.slice(0, clampedLevel + 1).reverse();
+	};
+	const fallbackType = typeFamilyFallback(textType);
+	return fallbackType === void 0 ? levelsFor(textType) : [...levelsFor(textType), ...levelsFor(fallbackType)];
+}
+function firstDefined(candidates, get) {
+	for (const candidate of candidates) {
+		if (candidate === void 0) continue;
+		const value = get(candidate);
+		if (value !== void 0) return value;
+	}
+}
+/** Resolves a run's own ParagraphProperties (possibly stating nothing at all, when the run's paragraph itself carries no TextPFException of its own) against the master cascade -- every field the run itself states wins outright; every field it doesn't falls through to the first master level that does. indentLevel is never itself resolved from the cascade: it is the run's own stated (or default-zero) outline depth, and is what selects which master levels apply in the first place. */
+function resolveParagraphProperties(run, table, textType, indentLevel) {
+	const candidates = [run, ...orderedMasterLevels(table, textType, indentLevel).map((level) => level.paragraph)];
+	return {
+		indentLevel,
+		alignment: firstDefined(candidates, (c) => c.alignment),
+		lineSpacing: firstDefined(candidates, (c) => c.lineSpacing),
+		spaceBefore: firstDefined(candidates, (c) => c.spaceBefore),
+		spaceAfter: firstDefined(candidates, (c) => c.spaceAfter),
+		leftMargin: firstDefined(candidates, (c) => c.leftMargin),
+		indent: firstDefined(candidates, (c) => c.indent)
+	};
+}
+/** The character-property counterpart of resolveParagraphProperties -- see that function's own comment for the cascade this implements. `color` resolves to whichever RunColor (literal or still-unresolved scheme reference) the cascade finds first; converting a scheme reference to an actual RgbColor is document/color-scheme.ts's own concern, deliberately kept separate since it needs the slide's colour scheme rather than anything the text-formatting cascade itself touches. */
+function resolveCharacterProperties(run, table, textType, indentLevel) {
+	const candidates = [run, ...orderedMasterLevels(table, textType, indentLevel).map((level) => level.character)];
+	return {
+		bold: firstDefined(candidates, (c) => c.bold),
+		italic: firstDefined(candidates, (c) => c.italic),
+		underline: firstDefined(candidates, (c) => c.underline),
+		shadow: firstDefined(candidates, (c) => c.shadow),
+		emboss: firstDefined(candidates, (c) => c.emboss),
+		fontRef: firstDefined(candidates, (c) => c.fontRef),
+		sizePt: firstDefined(candidates, (c) => c.sizePt),
+		color: firstDefined(candidates, (c) => c.color)
+	};
+}
+function readSlideAtom(record) {
+	if (record.header.recType !== 1007) throw new require_errors.PptFormatError(`expected RT_SlideAtom (0x${require_record_types.RT_SlideAtom.toString(16)}) at offset ${record.offset}, found record type 0x${record.header.recType.toString(16)}`);
+	const MASTER_ID_REF_OFFSET = 12;
+	const NOTES_ID_REF_OFFSET = 16;
+	if (record.data.length < 20) throw new require_errors.PptFormatError(`SlideAtom at offset ${record.offset} carries ${record.data.length} bytes, too few for its masterIdRef/notesIdRef fields`);
+	const { data } = record;
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	return {
+		masterIdRef: view.getUint32(MASTER_ID_REF_OFFSET, true),
+		notesIdRef: view.getUint32(NOTES_ID_REF_OFFSET, true)
+	};
+}
+//#endregion
+exports.buildMasterStyleTable = buildMasterStyleTable;
+exports.readSlideAtom = readSlideAtom;
+exports.resolveCharacterProperties = resolveCharacterProperties;
+exports.resolveParagraphProperties = resolveParagraphProperties;

package/dist/document/master.d.cts

@@ -0,0 +1,2 @@
+import { a as readSlideAtom, i as buildMasterStyleTable, n as MasterStyleTable, o as resolveCharacterProperties, r as SlideAtomInfo, s as resolveParagraphProperties, t as MasterInfo } from "../master-zlMRXyPU.cjs";
+export { MasterInfo, MasterStyleTable, SlideAtomInfo, buildMasterStyleTable, readSlideAtom, resolveCharacterProperties, resolveParagraphProperties };

package/dist/document/master.d.ts

@@ -0,0 +1,2 @@
+import { a as readSlideAtom, i as buildMasterStyleTable, n as MasterStyleTable, o as resolveCharacterProperties, r as SlideAtomInfo, s as resolveParagraphProperties, t as MasterInfo } from "../master-Cs_sDM1-.js";
+export { MasterInfo, MasterStyleTable, SlideAtomInfo, buildMasterStyleTable, readSlideAtom, resolveCharacterProperties, resolveParagraphProperties };