reamkit 1.20.0 → 1.22.0

package/dist/esm/core/bytes.d.ts

@@ -5,13 +5,31 @@
  */
 export declare function toBase64(bytes: Uint8Array): string;
 /**
- * Naive scan for an ASCII `needle` inside raw `haystack` bytes — used by reader
- * sniffs to spot OPC part names (e.g. `'word/document.xml'`) without unzipping.
+ * Whether the ZIP in `bytes` holds a part named `partName` — the name exactly,
+ * or anything under it when `partName` names a directory (ends with `/`).
+ *
+ * This is what a reader sniff should ask. A substring probe cannot tell a
+ * package from one EMBEDDED in it: a deck with a chart carries the chart's
+ * workbook as `ppt/embeddings/*.xlsx` STORED, uncompressed, so that workbook's
+ * own `xl/workbook.xml` sits in the outer file's bytes verbatim — and the xlsx
+ * sniff, which runs before the pptx one, claimed thirteen corpus presentations
+ * and then failed on them. The ZIP's central directory lists what is actually
+ * in this package, and walking that entry table is cheaper than scanning every
+ * byte for a needle.
+ *
+ * Names are compared without case, as OPC compares part names (§9.1.1.1) and
+ * as the package reader behind the sniff resolves them.
+ *
+ * @param bytes    The package bytes.
+ * @param partName The part name, or a `/`-terminated directory prefix.
+ * @returns Whether the package's directory names it.
  */
+export declare function packageHasPart(bytes: Uint8Array, partName: string): boolean;
 /**
  * Scan raw package bytes for an OPC part name (e.g. `'xl/workbook.xml'`)
- * without unzipping — the reader sniffs' cheap format probe. Accepts both the
- * spec's `/` separator and the `\` that Windows producers write.
+ * without unzipping. Prefer {@link packageHasPart}, which asks the archive
+ * what it holds instead of hoping the name appears nowhere else. Accepts both
+ * the spec's `/` separator and the `\` that Windows producers write.
  */
 export declare function bytesIncludePartName(haystack: Uint8Array, partName: string): boolean;
 /**

package/dist/esm/core/bytes.js

@@ -10,13 +10,81 @@ function toBase64(bytes) {
 	return btoa(bin);
 }
 /**
-* Naive scan for an ASCII `needle` inside raw `haystack` bytes — used by reader
-* sniffs to spot OPC part names (e.g. `'word/document.xml'`) without unzipping.
+* Whether the ZIP in `bytes` holds a part named `partName` — the name exactly,
+* or anything under it when `partName` names a directory (ends with `/`).
+*
+* This is what a reader sniff should ask. A substring probe cannot tell a
+* package from one EMBEDDED in it: a deck with a chart carries the chart's
+* workbook as `ppt/embeddings/*.xlsx` STORED, uncompressed, so that workbook's
+* own `xl/workbook.xml` sits in the outer file's bytes verbatim — and the xlsx
+* sniff, which runs before the pptx one, claimed thirteen corpus presentations
+* and then failed on them. The ZIP's central directory lists what is actually
+* in this package, and walking that entry table is cheaper than scanning every
+* byte for a needle.
+*
+* Names are compared without case, as OPC compares part names (§9.1.1.1) and
+* as the package reader behind the sniff resolves them.
+*
+* @param bytes    The package bytes.
+* @param partName The part name, or a `/`-terminated directory prefix.
+* @returns Whether the package's directory names it.
 */
+function packageHasPart(bytes, partName) {
+	const names = zipEntryNames(bytes);
+	if (names === void 0) return bytesIncludePartName(bytes, partName);
+	const wanted = partName.toLowerCase();
+	const isDir = wanted.endsWith("/");
+	return names.some((raw) => {
+		const name = raw.replace(/\\/g, "/").replace(/^\//u, "").toLowerCase();
+		return isDir ? name.startsWith(wanted) : name === wanted;
+	});
+}
+/**
+* The names in a ZIP's central directory (APPNOTE §4.3.12), or `undefined`
+* when it cannot be located or is malformed — including the ZIP64 spelling of
+* an archive with more than 65 534 entries.
+*/
+function zipEntryNames(bytes) {
+	if (bytes.length < 22) return void 0;
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const floor = Math.max(0, bytes.length - 22 - 65535);
+	let end = -1;
+	for (let i = bytes.length - 22; i >= floor; i--) if (view.getUint32(i, true) === 101010256) {
+		end = i;
+		break;
+	}
+	if (end < 0) return void 0;
+	let count = view.getUint16(end + 10, true);
+	let start = view.getUint32(end + 16, true);
+	if (count === 65535 || start === 4294967295) {
+		const locator = end - 20;
+		if (locator < 0 || view.getUint32(locator, true) !== 117853008) return void 0;
+		const z64 = Number(view.getBigUint64(locator + 8, true));
+		if (z64 + 56 > bytes.length || view.getUint32(z64, true) !== 101075792) return void 0;
+		count = Number(view.getBigUint64(z64 + 32, true));
+		start = Number(view.getBigUint64(z64 + 48, true));
+	}
+	const names = [];
+	let p = start;
+	for (let i = 0; i < count; i++) {
+		if (p + 46 > bytes.length || view.getUint32(p, true) !== 33639248) return void 0;
+		const nameLen = view.getUint16(p + 28, true);
+		if (p + 46 + nameLen > bytes.length) return void 0;
+		names.push(decodeUtf8(bytes.subarray(p + 46, p + 46 + nameLen)));
+		p += 46 + nameLen + view.getUint16(p + 30, true) + view.getUint16(p + 32, true);
+	}
+	return names;
+}
+var utf8 = new TextDecoder();
+/** An entry name as text. Names are UTF-8 or CP437; both decode ASCII alike. */
+function decodeUtf8(bytes) {
+	return utf8.decode(bytes);
+}
 /**
 * Scan raw package bytes for an OPC part name (e.g. `'xl/workbook.xml'`)
-* without unzipping — the reader sniffs' cheap format probe. Accepts both the
-* spec's `/` separator and the `\` that Windows producers write.
+* without unzipping. Prefer {@link packageHasPart}, which asks the archive
+* what it holds instead of hoping the name appears nowhere else. Accepts both
+* the spec's `/` separator and the `\` that Windows producers write.
 */
 function bytesIncludePartName(haystack, partName) {
 	if (bytesInclude(haystack, partName)) return true;
@@ -36,4 +104,4 @@ function bytesInclude(haystack, needle) {
 	return false;
 }
 //#endregion
-export { bytesInclude, bytesIncludePartName, toBase64 };
+export { bytesInclude, packageHasPart, toBase64 };

package/dist/esm/core/crypto/offcrypto.d.ts

@@ -1,5 +1,6 @@
 /** Thrown when the bytes are encrypted and the password does not open them. */
 export declare class WrongPasswordError extends Error {
+    /** @param message The message to carry; the default states the failure. */
     constructor(message?: string);
 }
 /** Whether the bytes are an OOXML package encrypted per ECMA-376 §2.3. */

package/dist/esm/core/crypto/offcrypto.js

@@ -3,6 +3,7 @@ import { aesCbcDecrypt, aesEcbDecrypt, sha1, sha256, sha384, sha512 } from "./pr
 //#region src/core/crypto/offcrypto.ts
 /** Thrown when the bytes are encrypted and the password does not open them. */
 var WrongPasswordError = class extends Error {
+	/** @param message The message to carry; the default states the failure. */
 	constructor(message = "Wrong password for this document") {
 		super(message);
 		this.name = "WrongPasswordError";
@@ -219,4 +220,4 @@ function b64(s) {
 	return out.subarray(0, at);
 }
 //#endregion
-export { decryptPackage, isEncryptedPackage };
+export { WrongPasswordError, decryptPackage, isEncryptedPackage };

package/dist/esm/core/document-model/types.d.ts

@@ -257,6 +257,17 @@ export interface InlineImage {
         readonly gain: number;
         readonly black: number;
     };
+    /**
+     * §20.1.8.16 `a:clrChange` — one colour of the picture replaced by another,
+     * or knocked out entirely when the destination states `a:alpha` at zero. A
+     * logo on a white card goes onto a dark slide that way (corpus: tdf113163,
+     * whose whole slide is a metafile with its white ground declared away).
+     */
+    readonly colorChange?: {
+        readonly fromHex: string;
+        readonly toHex: string;
+        readonly transparent: boolean;
+    };
     readonly width: Pt;
     readonly height: Pt;
     /** §20.1.8.55 `a:srcRect` — the part of the source the frame shows. */
@@ -915,6 +926,22 @@ export interface ImageBlock {
         readonly gain: number;
         readonly black: number;
     };
+    /**
+     * §20.1.8.4 `a:alphaModFix` — how opaque the picture is DRAWN, `0..1`; absent
+     * is opaque. A layout that lays a photograph behind its text sets it low
+     * (ArtisticEffectSample's cover shows one at 52%), and drawn full-strength
+     * the words on it are unreadable.
+     */
+    readonly alpha?: number;
+    /**
+     * §20.1.8.16 `a:clrChange` — one colour of the picture replaced by another,
+     * or knocked out entirely when the destination states `a:alpha` at zero.
+     */
+    readonly colorChange?: {
+        readonly fromHex: string;
+        readonly toHex: string;
+        readonly transparent: boolean;
+    };
     readonly width: Pt;
     readonly height: Pt;
     /** §20.1.8.55 `a:srcRect` — the part of the source the frame shows. */
@@ -1009,6 +1036,30 @@ export interface ShapeFill {
      * of the picture the box shows, as the fractions cut from each side.
      */
     readonly imageCrop?: ImageCrop;
+    /**
+     * §20.1.8.30 `a:stretch/a:fillRect` with POSITIVE insets — the part of the
+     * shape's box the picture is stretched into, as fractions of that box. A
+     * slide backed by a picture inset 55 % from the left shows it in the corner,
+     * not across the slide (corpus: tdf153466.pptx). Negative insets are the
+     * other case entirely — the picture zooming past the box — and read as a
+     * crop of the source.
+     */
+    /**
+     * §20.1.8.23 `a:duotone` — the picture recoloured into two tones: its dark
+     * end becomes the first colour, its light end the second. An Office theme
+     * that ships a photograph tints it this way, so a deck whose background is a
+     * brown ridged texture is stored as a grey one (corpus: themes.pptx).
+     */
+    readonly duotone?: {
+        readonly shadowHex: string;
+        readonly highlightHex: string;
+    };
+    readonly imageFillRect?: {
+        readonly left: number;
+        readonly top: number;
+        readonly right: number;
+        readonly bottom: number;
+    };
     /**
      * §20.1.2.3.1 `a:alpha` / §14.1.2.5 `@opacity` — how opaque the fill is,
      * `0..1`. Absent is opaque. The colour above is the fill's own, NOT composited
@@ -1315,6 +1366,15 @@ export interface Chart {
      * creates, and both references draw them.
      */
     readonly frameFillHex?: string;
+    /**
+     * §20.1.8.14 `a:blipFill` — the PICTURE the frame is filled with, when it is
+     * filled with one rather than a colour. chart-texture-bg.pptx papers its
+     * whole chart with a woven cloth, and a chart on white is a different chart.
+     */
+    readonly frameFillImage?: {
+        readonly resource: ResourceId;
+        readonly tiled?: boolean;
+    };
     readonly frameLineHex?: string;
     /** The frame rule's width and dash, when it states them. */
     readonly frameLineWidthPt?: number;

package/dist/esm/core/drawingml/chart-parser.d.ts

@@ -1,4 +1,5 @@
 import { Chart } from '../document-model/index.js';
+import { ResourceId } from '../ir/index.js';
 import { OpcPackage } from '../opc/index.js';
 import { ColorResolver } from './colors.js';
 /**
@@ -14,7 +15,7 @@ import { ColorResolver } from './colors.js';
  * @param resolveColor Maps a DrawingML colour reference to a 6-hex string.
  * @returns The parsed chart, or `null` when there is no `c:chart` / `c:plotArea`.
  */
-export declare function parseChart(chartXml: Uint8Array, resolveColor: ColorResolver): Chart | null;
+export declare function parseChart(chartXml: Uint8Array, resolveColor: ColorResolver, resolveImage?: (relId: string) => ResourceId | undefined): Chart | null;
 /**
  * MS-ODRAWXML chartColorStyle (charts/colorsN.xml): the top-level colour list is
  * the series cycle (`meth="cycle"` — the common case; variations are luminance

package/dist/esm/core/drawingml/chart-parser.js

@@ -37,7 +37,7 @@ var TYPE_OF_TAG = {
 * @param resolveColor Maps a DrawingML colour reference to a 6-hex string.
 * @returns The parsed chart, or `null` when there is no `c:chart` / `c:plotArea`.
 */
-function parseChart(chartXml, resolveColor) {
+function parseChart(chartXml, resolveColor, resolveImage) {
 	const tree = parser.parse(decoder.decode(chartXml));
 	const chart = poFindByPath(tree, ["c:chartSpace", "c:chart"]);
 	if (!chart) return null;
@@ -105,6 +105,7 @@ function parseChart(chartXml, resolveColor) {
 	const frameLine = spaceSpPr ? poChildren(spaceSpPr).find((c) => poIs(c, "a:ln")) : void 0;
 	const frameStyle = lineStyleOf(chartSpace, resolveColor);
 	const frameFillHex = spaceSpPr ? frameFillOf(spaceSpPr, resolveColor) : "FFFFFF";
+	const frameFillImage = spaceSpPr ? blipFillOf(spaceSpPr, resolveImage) : void 0;
 	const plotSpPr = poChildren(plotArea).find((c) => poIs(c, "c:spPr"));
 	const plotFillHex = plotSpPr ? frameFillOf(plotSpPr, resolveColor) : void 0;
 	const plotLine = lineStyleOf(plotArea, resolveColor);
@@ -142,6 +143,7 @@ function parseChart(chartXml, resolveColor) {
 		...valAxisMin !== void 0 ? { valAxisMin } : {},
 		...valAxisMax !== void 0 ? { valAxisMax } : {},
 		...frameFillHex ? { frameFillHex } : {},
+		...frameFillImage ? { frameFillImage } : {},
 		...frameLineHex ? { frameLineHex } : {},
 		...frameStyle?.widthPt !== void 0 ? { frameLineWidthPt: frameStyle.widthPt } : {},
 		...frameStyle?.dash ? { frameLineDash: frameStyle.dash } : {},
@@ -248,6 +250,26 @@ function dataPointColors(ser, resolveColor) {
 	return out;
 }
 /**
+* §20.1.8.14 `a:blipFill` — the picture a chart element is filled with, and
+* whether it TILES at its own size rather than stretching over the box.
+*
+* @param spPr         The element's `c:spPr`.
+* @param resolveImage The chart part's own blip resolver, when the caller has one.
+* @returns The stored picture, or `undefined` when the fill is not one.
+*/
+function blipFillOf(spPr, resolveImage) {
+	const blipFill = poChildren(spPr).find((c) => poIs(c, "a:blipFill"));
+	const blip = blipFill ? poChildren(blipFill).find((c) => poIs(c, "a:blip")) : void 0;
+	const relId = blip ? poAttr(blip, "embed") : void 0;
+	const resource = relId !== void 0 ? resolveImage?.(relId) : void 0;
+	if (resource === void 0 || !blipFill) return void 0;
+	const tiled = poChildren(blipFill).some((c) => poIs(c, "a:tile"));
+	return {
+		resource,
+		...tiled ? { tiled } : {}
+	};
+}
+/**
 * The BACKGROUND fill of a frame (the chart space, the plot rectangle): its own
 * `a:solidFill` and nothing else. Unlike a series, a frame that states
 * `<a:noFill/>` is not filled in the colour of its own rule —

package/dist/esm/core/drawingml/colors.d.ts

@@ -6,7 +6,7 @@ import { PoNode } from '../po-helpers.js';
  * (solid fills emit no transparency).
  */
 export interface ColorMod {
-    readonly kind: 'lumMod' | 'lumOff' | 'shade' | 'tint' | 'alpha' | 'satMod' | 'hueOff' | 'satOff';
+    readonly kind: 'lumMod' | 'lumOff' | 'shade' | 'tint' | 'alpha' | 'satMod' | 'hueMod' | 'hueOff' | 'satOff';
     readonly val: number;
 }
 /**
@@ -38,20 +38,44 @@ export declare function applyColorMods(hex: string, mods: ReadonlyArray<ColorMod
  * scheme slots when a document carries no custom theme part.
  */
 export declare const DEFAULT_THEME_PALETTE: ReadonlyMap<string, string>;
+/**
+ * Which theme slot each `schemeClr` name stands for. Only the text/background
+ * aliases are ever remapped; anything absent resolves under its own name.
+ */
+export type SchemeAliases = Readonly<Record<string, string>>;
+export declare const DEFAULT_SCHEME_ALIAS: SchemeAliases;
 /**
  * Resolve a `schemeClr` text/background alias (`tx1`/`bg1`/`tx2`/`bg2`,
  * §20.1.2.3.29) to its underlying `dk`/`lt` slot name; other names pass through.
+ *
+ * @param name  The `schemeClr` value.
+ * @param alias The mapping to read it under — a presentation states its own in
+ * the master's `p:clrMap` (§19.3.1.6), where `bg1` may well mean `dk2`.
+ * @returns The theme slot to look up.
  */
-export declare function resolveSchemeName(name: string): string;
+export declare function resolveSchemeName(name: string, alias?: SchemeAliases): string;
 /**
  * Build a {@link ColorResolver} over a scheme-name → hex `palette`. sRGB
  * references pass through verbatim (upper-cased); scheme references are aliased
  * (via {@link resolveSchemeName}) then looked up; colour transforms are applied.
  *
  * @param palette The scheme-name → RRGGBB map (e.g. {@link DEFAULT_THEME_PALETTE}).
+ * @param alias   How the bg/tx aliases map onto the theme's slots; the default
+ * is the fixed DrawingML one, which is what a document without a colour map of
+ * its own (docx, xlsx) uses.
  * @returns A resolver that maps a {@link RawColor} to a hex string or `undefined`.
  */
-export declare function makeColorResolver(palette: ReadonlyMap<string, string>): ColorResolver;
+export declare function makeColorResolver(palette: ReadonlyMap<string, string>, alias?: SchemeAliases): ColorResolver;
+/**
+ * §20.1.4.2.10 `phClr` — inside a theme's style list the colours are written as
+ * "the placeholder", and the reference that reaches the style says which colour
+ * that is. Everything else resolves as it always did.
+ *
+ * @param base  The document's own resolver.
+ * @param phHex The colour the reference carries (`a:fillRef`, `p:bgRef`, …).
+ * @returns A resolver that answers `phClr` with that colour, transforms and all.
+ */
+export declare function placeholderColors(base: ColorResolver, phHex: string): ColorResolver;
 /** A {@link ColorResolver} backed by the {@link DEFAULT_THEME_PALETTE}. */
 export declare const defaultColorResolver: ColorResolver;
 /**

package/dist/esm/core/drawingml/colors.js

@@ -103,6 +103,9 @@ function applyColorMods(hex, mods) {
 		const [h, s, l] = rgbToHsl(r, g, b);
 		const l2 = m.kind === "lumMod" ? l * m.val : clamp01(l + m.val);
 		[r, g, b] = hslToRgb(h, s, l2);
+	} else if (m.kind === "hueMod") {
+		const [h, sat, l] = rgbToHsl(r, g, b);
+		[r, g, b] = hslToRgb((h * m.val % 360 + 360) % 360, sat, l);
 	} else if (m.kind === "hueOff") {
 		const [h, sat, l] = rgbToHsl(r, g, b);
 		[r, g, b] = hslToRgb(((h + m.val) % 360 + 360) % 360, sat, l);
@@ -138,7 +141,7 @@ var DEFAULT_THEME_PALETTE = new Map([
 	["hlink", "0563C1"],
 	["folHlink", "954F72"]
 ]);
-var SCHEME_ALIAS = {
+var DEFAULT_SCHEME_ALIAS = {
 	tx1: "dk1",
 	bg1: "lt1",
 	tx2: "dk2",
@@ -147,9 +150,14 @@ var SCHEME_ALIAS = {
 /**
 * Resolve a `schemeClr` text/background alias (`tx1`/`bg1`/`tx2`/`bg2`,
 * §20.1.2.3.29) to its underlying `dk`/`lt` slot name; other names pass through.
+*
+* @param name  The `schemeClr` value.
+* @param alias The mapping to read it under — a presentation states its own in
+* the master's `p:clrMap` (§19.3.1.6), where `bg1` may well mean `dk2`.
+* @returns The theme slot to look up.
 */
-function resolveSchemeName(name) {
-	return SCHEME_ALIAS[name] ?? name;
+function resolveSchemeName(name, alias = DEFAULT_SCHEME_ALIAS) {
+	return alias[name] ?? name;
 }
 /**
 * Build a {@link ColorResolver} over a scheme-name → hex `palette`. sRGB
@@ -157,15 +165,30 @@ function resolveSchemeName(name) {
 * (via {@link resolveSchemeName}) then looked up; colour transforms are applied.
 *
 * @param palette The scheme-name → RRGGBB map (e.g. {@link DEFAULT_THEME_PALETTE}).
+* @param alias   How the bg/tx aliases map onto the theme's slots; the default
+* is the fixed DrawingML one, which is what a document without a colour map of
+* its own (docx, xlsx) uses.
 * @returns A resolver that maps a {@link RawColor} to a hex string or `undefined`.
 */
-function makeColorResolver(palette) {
+function makeColorResolver(palette, alias = DEFAULT_SCHEME_ALIAS) {
 	return (raw) => {
-		const base = "srgb" in raw ? raw.srgb.toUpperCase() : palette.get(resolveSchemeName(raw.scheme));
+		const base = "srgb" in raw ? raw.srgb.toUpperCase() : palette.get(resolveSchemeName(raw.scheme, alias));
 		if (base === void 0) return void 0;
 		return raw.mods && raw.mods.length > 0 ? applyColorMods(base, raw.mods) : base;
 	};
 }
+/**
+* §20.1.4.2.10 `phClr` — inside a theme's style list the colours are written as
+* "the placeholder", and the reference that reaches the style says which colour
+* that is. Everything else resolves as it always did.
+*
+* @param base  The document's own resolver.
+* @param phHex The colour the reference carries (`a:fillRef`, `p:bgRef`, …).
+* @returns A resolver that answers `phClr` with that colour, transforms and all.
+*/
+function placeholderColors(base, phHex) {
+	return (raw) => "scheme" in raw && raw.scheme === "phClr" ? applyColorMods(phHex, raw.mods ?? []) : base(raw);
+}
 /** A {@link ColorResolver} backed by the {@link DEFAULT_THEME_PALETTE}. */
 var defaultColorResolver = makeColorResolver(DEFAULT_THEME_PALETTE);
 var PRESET_COLORS = new Map([
@@ -198,6 +221,7 @@ function readColorMods(colorNode) {
 			"tint",
 			"alpha",
 			"satMod",
+			"hueMod",
 			"satOff"
 		]) if (poIs(c, `a:${kind}`)) {
 			const v = poIntAttr(c, "val");
@@ -266,4 +290,4 @@ function resolveColorNode(c, resolveColor) {
 	} : raw);
 }
 //#endregion
-export { DEFAULT_THEME_PALETTE, applyColorMods, defaultColorResolver, makeColorResolver, readColorMods, resolveColorNode };
+export { DEFAULT_SCHEME_ALIAS, DEFAULT_THEME_PALETTE, applyColorMods, defaultColorResolver, makeColorResolver, placeholderColors, readColorMods, resolveColorNode };