@shbernal/ts-xlsx 3.0.0 → 3.1.0

package/dist/core/style.js

@@ -1,4 +1,7 @@
-import { tokenSet } from '../token-set.js';
+import { tokenSet, tokenSetOf } from '../token-set.js';
+import { cloneWith } from './clone.js';
+import { copyKeyIfPresent } from './containers.js';
+import { NAMED_STYLE_ID } from './internal.js';
 export const isNamedUnderlineStyle = tokenSet({
     none: true,
     single: true,
@@ -11,27 +14,50 @@ export function parseArgb(value) {
     const argb = hex.length === 6 ? `FF${hex}` : hex;
     return /^[0-9a-fA-F]{8}$/.test(argb) ? argb : undefined;
 }
-export const isFillPatternType = tokenSet({
-    none: true,
-    solid: true,
-    gray125: true,
-    darkGray: true,
-    mediumGray: true,
-    lightGray: true,
-    gray0625: true,
-    darkHorizontal: true,
-    darkVertical: true,
-    darkDown: true,
-    darkUp: true,
-    darkGrid: true,
-    darkTrellis: true,
-    lightHorizontal: true,
-    lightVertical: true,
-    lightDown: true,
-    lightUp: true,
-    lightGrid: true,
-    lightTrellis: true,
-});
+export const FILL_PATTERNS_IN_SCHEMA_ORDER = [
+    'none',
+    'solid',
+    'mediumGray',
+    'darkGray',
+    'lightGray',
+    'darkHorizontal',
+    'darkVertical',
+    'darkDown',
+    'darkUp',
+    'darkGrid',
+    'darkTrellis',
+    'lightHorizontal',
+    'lightVertical',
+    'lightDown',
+    'lightUp',
+    'lightGrid',
+    'lightTrellis',
+    'gray125',
+    'gray0625',
+];
+export const isFillPatternType = tokenSetOf(FILL_PATTERNS_IN_SCHEMA_ORDER);
+const GRADIENT_STOP_CLONE = { position: 'value', color: 'record' };
+const PATTERN_FILL_CLONE = {
+    type: 'value',
+    pattern: 'value',
+    fgColor: 'record',
+    bgColor: 'record',
+};
+const GRADIENT_FILL_CLONE = {
+    type: 'value',
+    gradient: 'value',
+    degree: 'value',
+    left: 'value',
+    right: 'value',
+    top: 'value',
+    bottom: 'value',
+    stops: (stops) => stops.map((stop) => cloneWith(stop, GRADIENT_STOP_CLONE)),
+};
+export function cloneFill(fill) {
+    return fill.type === 'gradient'
+        ? cloneWith(fill, GRADIENT_FILL_CLONE)
+        : cloneWith(fill, PATTERN_FILL_CLONE);
+}
 export const isBorderStyle = tokenSet({
     thin: true,
     medium: true,
@@ -47,11 +73,42 @@ export const isBorderStyle = tokenSet({
     mediumDashDotDot: true,
     slantDashDot: true,
 });
+const BORDER_EDGE_CLONE = { style: 'value', color: 'record' };
+const cloneBorderEdge = (edge) => cloneWith(edge, BORDER_EDGE_CLONE);
+const BORDER_CLONE = {
+    left: cloneBorderEdge,
+    right: cloneBorderEdge,
+    top: cloneBorderEdge,
+    bottom: cloneBorderEdge,
+    diagonal: cloneBorderEdge,
+    diagonalUp: 'value',
+    diagonalDown: 'value',
+};
+export function cloneBorder(border) {
+    return cloneWith(border, BORDER_CLONE);
+}
 export const isFontVerticalAlignment = tokenSet({
     superscript: true,
     subscript: true,
 });
 export const isFontScheme = tokenSet({ minor: true, major: true, none: true });
+const FONT_CLONE = {
+    name: 'value',
+    size: 'value',
+    family: 'value',
+    scheme: 'value',
+    charset: 'value',
+    color: 'record',
+    bold: 'value',
+    italic: 'value',
+    underline: 'value',
+    strike: 'value',
+    outline: 'value',
+    vertAlign: 'value',
+};
+export function cloneFont(font) {
+    return cloneWith(font, FONT_CLONE);
+}
 export const isHorizontalAlignment = tokenSet({
     general: true,
     left: true,
@@ -93,17 +150,24 @@ const CELL_STYLE_FACET_KEYS = {
     protection: true,
 };
 export const CELL_STYLE_FACETS = Object.keys(CELL_STYLE_FACET_KEYS);
+const CELL_CONTENT_ONLY_KEYS = {
+    quotePrefix: true,
+    [NAMED_STYLE_ID]: true,
+};
+export const CELL_CONTENT_FACETS = [
+    ...CELL_STYLE_FACETS,
+    ...Reflect.ownKeys(CELL_CONTENT_ONLY_KEYS),
+];
+export function assignContentFacets(target, source) {
+    for (const facet of CELL_CONTENT_FACETS)
+        copyKeyIfPresent(target, source, facet);
+}
 export function assignStyleFacets(target, source) {
     for (const facet of CELL_STYLE_FACETS)
-        copyFacet(target, source, facet);
+        copyKeyIfPresent(target, source, facet);
 }
 export function pickStyleFacets(source) {
     const facets = {};
     assignStyleFacets(facets, source);
     return facets;
 }
-function copyFacet(target, source, key) {
-    const value = source[key];
-    if (value !== undefined)
-        target[key] = value;
-}

package/dist/core/table-style.d.ts

@@ -1,4 +1,4 @@
-import type { DifferentialStyle } from './style.ts';
+import type { DifferentialStyle } from './workbook-styles.ts';
 /**
  * The regions a table style can format (`ST_TableStyleType`).
  *

package/dist/core/table-style.js

@@ -1,4 +1,4 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, invalidToken, quoted } from '../errors.js';
 export const TABLE_STYLE_ELEMENT_TYPES = [
     'wholeTable',
     'headerRow',
@@ -46,17 +46,17 @@ export function checkTableStyle(style) {
         if (element === undefined)
             continue;
         if (!isTableStyleElementType(type)) {
-            throw new AuthoringError(`Invalid table style element ${JSON.stringify(type)}: not a value the OOXML enumeration allows`);
+            throw invalidToken('table style element', type);
         }
         const { size } = element;
         if (size === undefined)
             continue;
         if (!STRIPE_ELEMENT_TYPES.has(type)) {
-            throw new AuthoringError(`table style element "${type}" cannot carry a size: band width applies only to ` +
+            throw new AuthoringError(`table style element ${quoted(type)} cannot carry a size: band width applies only to ` +
                 `${[...STRIPE_ELEMENT_TYPES].join(', ')}`);
         }
         if (!Number.isInteger(size) || size < 1) {
-            throw new RangeError(`Invalid table style band size ${size}: expected a positive integer`);
+            throw new RangeError(`invalid table style band size ${size}: expected a positive integer`);
         }
     }
 }

package/dist/core/table.d.ts

@@ -1,4 +1,7 @@
 import { type GridRect } from './address.ts';
+import { type ClonePlan } from './clone.ts';
+import { type AxisSplice } from './grid-shift.ts';
+import type { AssertNever } from './internal.ts';
 import type { CellStyle } from './style.ts';
 import type { CellValue } from './value.ts';
 /** A per-column cell format applied to a table's body cells: the facets Excel's table-column style
@@ -57,6 +60,16 @@ export interface TableStyleInfo {
     /** Band the columns (alternating fill). */
     readonly showColumnStripes?: boolean;
 }
+/** Copy a style, keeping only its defined fields off the literal so `exactOptionalPropertyTypes`
+ * never sees a fabricated `key: undefined`: an absent attribute must stay absent across a copy.
+ *
+ * The sentinel name `"None"` (Excel's table-style gallery entry for *no* style) is normalised to an
+ * absent name: OOXML expresses "unstyled" as a `<tableStyleInfo>` with no `name` attribute, so a
+ * literal `name="None"` would reference a style that does not exist and make the file suspect. The
+ * banding flags set alongside it are untouched. */
+declare const STYLE_INFO_CLONE: ClonePlan<TableStyleInfo>;
+/** The proof that {@link STYLE_INFO_CLONE} names every field of the style. */
+export type EveryTableStyleInfoFieldIsCloned = AssertNever<Exclude<keyof Required<TableStyleInfo>, keyof typeof STYLE_INFO_CLONE>>;
 /**
  * OOXML's totals-row function names (`ST_TotalsRowFunction`) to the `SUBTOTAL` first-argument code
  * Excel writes into a materialised totals cell. The `10x` band ignores manually hidden rows, the
@@ -158,20 +171,24 @@ export declare class Table {
      */
     addRow(values?: readonly CellValue[]): void;
     /**
-     * Re-pin the table through a row splice: `count` rows removed at the 1-based `start`, then rows
-     * inserted so surviving rows below shift by `delta`. A splice entirely above the table moves its
-     * whole range by `delta`; one landing inside grows or shrinks the data rows to absorb the change;
+     * Re-pin the table through a row splice. A splice entirely above the table moves its whole range
+     * by the splice's `delta`; one landing inside grows or shrinks the data rows to absorb the change;
      * one that deletes the table's every row removes it. Returns `false` when the table no longer has
      * a row to occupy (the caller drops it), `true` when it survives.
      */
-    shiftRows(start: number, count: number, delta: number): boolean;
+    shiftRows(splice: AxisSplice): boolean;
     /**
-     * Re-pin the table through a column splice. A splice entirely to the table's left moves its anchor
-     * by `delta`; one to its right leaves it untouched. A splice landing inside the table's columns is
-     * structural surgery on named columns with no unambiguous answer, so the table's columns are left
-     * as-is (anchor unchanged) rather than fabricated or dropped. Always returns `true`.
+     * Re-pin the table through a column splice, the mirror of {@link shiftRows}. A splice entirely to
+     * the table's left moves its anchor by the splice's `delta`; one to its right leaves it untouched;
+     * one that deletes the table's every column removes it. Returns `false` when the table no longer
+     * has a column to occupy (the caller drops it), `true` when it survives.
+     *
+     * A splice landing *inside* the table's columns is structural surgery on named columns with no
+     * unambiguous answer, so those columns are left as-is rather than fabricated or dropped. Whole-table
+     * deletion is not that case: a table left declared over whatever slid into its place, carrying the
+     * names of columns that no longer exist, is content the writer then emits.
      */
-    shiftColumns(start: number, count: number, delta: number): boolean;
+    shiftColumns(splice: AxisSplice): boolean;
     /**
      * The options that reconstruct this table: the anchor as a single-cell ref (not the derived
      * full range), the columns, and the data-row count with the header/totals flags. Feeding this
@@ -194,3 +211,4 @@ export declare class Table {
     /** The occupied rectangle, for conflict checks such as overlapping merges. */
     get region(): TableRegion;
 }
+export {};

package/dist/core/table.js

@@ -1,19 +1,20 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { decodeCellRef, encodeAddress } from './address.js';
+import { decodeCellRef, encodeAddress, encodeRect, MAX_COLUMN, MAX_ROW, numberToColumn, } from './address.js';
+import { cloneWith } from './clone.js';
 import { isDeletedSpan, shiftIndex } from './grid-shift.js';
+import { MAX_TABLE_NAME_LENGTH, TABLE_NAME_PATTERN } from './limits.js';
+const STYLE_INFO_CLONE = {
+    name: (name) => (name === 'None' ? undefined : name),
+    showFirstColumn: 'value',
+    showLastColumn: 'value',
+    showRowStripes: 'value',
+    showColumnStripes: 'value',
+};
 function cloneStyleInfo(style) {
-    const clone = {};
-    if (style.name !== undefined && style.name !== 'None')
-        clone.name = style.name;
-    if (style.showFirstColumn !== undefined)
-        clone.showFirstColumn = style.showFirstColumn;
-    if (style.showLastColumn !== undefined)
-        clone.showLastColumn = style.showLastColumn;
-    if (style.showRowStripes !== undefined)
-        clone.showRowStripes = style.showRowStripes;
-    if (style.showColumnStripes !== undefined)
-        clone.showColumnStripes = style.showColumnStripes;
+    const clone = cloneWith(style, STYLE_INFO_CLONE);
+    if (clone.name === undefined)
+        delete clone.name;
     return clone;
 }
 export const TOTALS_ROW_SUBTOTAL_CODE = {
@@ -38,7 +39,6 @@ export const isTotalsRowFunction = tokenSet({
     custom: true,
     none: true,
 });
-const IDENTIFIER = /^[\p{L}\\_][\p{L}\p{N}._]*$/u;
 function disambiguateColumnNames(columns) {
     const seen = new Set();
     return columns.map((column) => {
@@ -50,11 +50,11 @@ function disambiguateColumnNames(columns) {
     });
 }
 function validateTableName(name) {
-    if (name.length === 0 || name.length > 255) {
-        throw new RangeError(`table name ${JSON.stringify(name)} must be between 1 and 255 characters`);
+    if (name.length === 0 || name.length > MAX_TABLE_NAME_LENGTH) {
+        throw new RangeError(`table name ${quoted(name)} must be between 1 and ${MAX_TABLE_NAME_LENGTH} characters`);
     }
-    if (!IDENTIFIER.test(name)) {
-        throw new SyntaxError(`table name ${JSON.stringify(name)} is not a valid Excel identifier: it must start with a letter, ` +
+    if (!TABLE_NAME_PATTERN.test(name)) {
+        throw new SyntaxError(`table name ${quoted(name)} is not a valid Excel identifier: it must start with a letter, ` +
             'underscore, or backslash and contain only letters, digits, periods, and underscores');
     }
 }
@@ -74,17 +74,17 @@ export class Table {
     constructor(options, grid) {
         validateTableName(options.name);
         if (options.columns.length === 0) {
-            throw new AuthoringError(`table "${options.name}" must declare at least one column`);
+            throw new AuthoringError(`table ${quoted(options.name)} must declare at least one column`);
         }
         if (!Number.isInteger(options.rowCount) || options.rowCount < 0) {
-            throw new RangeError(`table "${options.name}" has an invalid data-row count (${options.rowCount})`);
+            throw new RangeError(`table ${quoted(options.name)} has an invalid data-row count (${options.rowCount})`);
         }
         let anchor;
         try {
             anchor = decodeCellRef(options.ref);
         }
         catch (cause) {
-            throw new SyntaxError(`table ref "${options.ref}" must anchor at a single cell (e.g. "A1")`, {
+            throw new SyntaxError(`table ref ${quoted(options.ref)} must anchor at a single cell (e.g. "A1")`, {
                 cause,
             });
         }
@@ -102,7 +102,15 @@ export class Table {
         this.#dataRowCount = options.rowCount;
         this.#grid = grid;
         if (this.#rowSpan < 1) {
-            throw new AuthoringError(`table "${this.name}" has no rows: it needs a header row or at least one data row`);
+            throw new AuthoringError(`table ${quoted(this.name)} has no rows: it needs a header row or at least one data row`);
+        }
+        if (this.#right > MAX_COLUMN) {
+            throw new RangeError(`table ${quoted(this.name)} spans ${this.columns.length} columns from ` +
+                `${numberToColumn(this.#anchorCol)}, past the last column (${numberToColumn(MAX_COLUMN)})`);
+        }
+        if (this.#bottom > MAX_ROW) {
+            throw new RangeError(`table ${quoted(this.name)} spans ${this.#rowSpan} rows from ${this.#anchorRow}, ` +
+                `past the last row (${MAX_ROW})`);
         }
         if (grid !== undefined)
             this.#materializeFrame(grid);
@@ -115,13 +123,13 @@ export class Table {
     }
     addRow(values = []) {
         if (values.length > this.columnCount) {
-            throw new RangeError(`row has ${values.length} values but table "${this.name}" has ${this.columnCount} columns`);
+            throw new RangeError(`row has ${values.length} values but table ${quoted(this.name)} has ${this.columnCount} columns`);
         }
         const target = this.#anchorRow + (this.headerRow ? 1 : 0) + this.#dataRowCount;
         const grid = this.#grid;
         if (this.totalsRow) {
             if (grid === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot relocate its totals row to append a data row`);
+                throw new AuthoringError(`table ${quoted(this.name)} is not attached to a worksheet: cannot relocate its totals row to append a data row`);
             }
             grid.insertRow(target);
             this.#writeRow(grid, target, values);
@@ -129,7 +137,7 @@ export class Table {
         }
         if (values.length > 0) {
             if (grid === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot write appended row values`);
+                throw new AuthoringError(`table ${quoted(this.name)} is not attached to a worksheet: cannot write appended row values`);
             }
             this.#writeRow(grid, target, values);
         }
@@ -174,11 +182,11 @@ export class Table {
             });
         }
     }
-    shiftRows(start, count, delta) {
-        if (isDeletedSpan(this.#anchorRow, this.#bottom, start, count))
+    shiftRows(splice) {
+        if (isDeletedSpan(this.#anchorRow, this.#bottom, splice))
             return false;
-        const top = shiftIndex(this.#anchorRow, start, count, delta, 'row');
-        const bottom = shiftIndex(this.#bottom, start, count, delta, 'row');
+        const top = shiftIndex(this.#anchorRow, splice);
+        const bottom = shiftIndex(this.#bottom, splice);
         const span = bottom - top + 1;
         const fixedRows = (this.headerRow ? 1 : 0) + (this.totalsRow ? 1 : 0);
         const dataRows = span - fixedRows;
@@ -188,9 +196,13 @@ export class Table {
         this.#dataRowCount = dataRows;
         return true;
     }
-    shiftColumns(start, count, delta) {
-        if (this.#anchorCol >= start + count)
-            this.#anchorCol += delta;
+    shiftColumns(splice) {
+        if (isDeletedSpan(this.#anchorCol, this.#right, splice))
+            return false;
+        const anchor = shiftIndex(this.#anchorCol, splice);
+        if (anchor + this.columns.length - 1 > MAX_COLUMN)
+            return false;
+        this.#anchorCol = anchor;
         return true;
     }
     get options() {
@@ -211,13 +223,18 @@ export class Table {
         return options;
     }
     get range() {
-        return `${encodeAddress(this.#anchorCol, this.#anchorRow)}:${encodeAddress(this.#right, this.#bottom)}`;
+        return encodeRect({
+            top: this.#anchorRow,
+            left: this.#anchorCol,
+            bottom: this.#bottom,
+            right: this.#right,
+        });
     }
     get autoFilterRef() {
         if (!this.autoFilter)
             return undefined;
         const bottom = this.#anchorRow + this.#dataRowCount;
-        return `${encodeAddress(this.#anchorCol, this.#anchorRow)}:${encodeAddress(this.#right, bottom)}`;
+        return encodeRect({ top: this.#anchorRow, left: this.#anchorCol, bottom, right: this.#right });
     }
     get region() {
         return { top: this.#anchorRow, left: this.#anchorCol, bottom: this.#bottom, right: this.#right };

package/dist/core/theme.js

@@ -1,3 +1,5 @@
+import { quoted } from '../errors.js';
+import { parseArgb } from './style.js';
 export const THEME_COLOR_SLOTS = [
     'lt1',
     'dk1',
@@ -36,10 +38,9 @@ export const DEFAULT_THEME_FONTS = {
     minor: OFFICE_BODY_FACE,
 };
 export function normalizeThemeColor(value) {
-    const hex = value.startsWith('#') ? value.slice(1) : value;
-    const rgb = hex.length === 8 ? hex.slice(2) : hex;
-    if (!/^[0-9a-fA-F]{6}$/.test(rgb)) {
-        throw new SyntaxError(`Invalid theme colour ${JSON.stringify(value)}: expected 6 hexadecimal digits (RRGGBB)`);
+    const argb = parseArgb(value);
+    if (argb === undefined) {
+        throw new SyntaxError(`invalid theme colour ${quoted(value)}: expected 6 hexadecimal digits (RRGGBB)`);
     }
-    return rgb.toUpperCase();
+    return argb.slice(2).toUpperCase();
 }

package/dist/core/value.d.ts

@@ -15,6 +15,15 @@ export type ValueType = (typeof ValueType)[keyof typeof ValueType];
 /** The canonical Excel error literals a cell (or formula result) can carry. */
 export declare const ERROR_CODES: readonly ['#N/A', '#REF!', '#NAME?', '#DIV/0!', '#NULL!', '#VALUE!', '#NUM!', '#SPILL!', '#CALC!', '#GETTING_DATA'];
 export type ErrorCode = (typeof ERROR_CODES)[number];
+/**
+ * The error a spreadsheet puts in place of a reference that has nowhere left to point.
+ *
+ * Named here rather than in the two formula codecs that produce it. Both of them -- the A1 renderer
+ * in `core/formula.ts` and the BIFF12 one in `io/xlsb/formula.ts` -- had a private literal of their
+ * own, spelled the same and named differently, for a value {@link ERROR_CODES} already publishes and
+ * `isErrorCode` already recognises.
+ */
+export declare const REF_ERROR: ErrorCode;
 /** An in-cell error, e.g. `{error: '#REF!'}`. */
 export interface ErrorValue {
     readonly error: ErrorCode;

package/dist/core/value.js

@@ -21,6 +21,7 @@ export const ERROR_CODES = [
     '#CALC!',
     '#GETTING_DATA',
 ];
+export const REF_ERROR = '#REF!';
 const ERROR_SET = new Set(ERROR_CODES);
 function hasKey(value, key) {
     return typeof value === 'object' && value !== null && key in value;
@@ -47,58 +48,59 @@ export function richTextToPlain(value) {
     return value.richText.map((run) => run.text).join('');
 }
 export function cellValueToText(value) {
-    if (value === null)
-        return '';
-    switch (typeof value) {
-        case 'number':
-            return String(value);
-        case 'string':
-            return value;
-        case 'boolean':
-            return value ? 'TRUE' : 'FALSE';
-        default:
-            break;
-    }
-    if (value instanceof Date)
-        return Number.isNaN(value.getTime()) ? '' : value.toISOString();
-    if (isHyperlinkValue(value)) {
-        return typeof value.text === 'string' ? value.text : richTextToPlain(value.text);
-    }
-    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
-        return value.result === undefined ? '' : cellValueToText(value.result);
-    }
-    if (isRichTextValue(value))
-        return richTextToPlain(value);
-    if (isErrorValue(value))
-        return value.error;
-    return unsupportedValue(value);
+    return classify(value, TO_TEXT);
 }
 export function detectValueType(value) {
+    return classify(value, TO_TYPE);
+}
+function classify(value, visit) {
     if (value === null)
-        return ValueType.Null;
+        return visit.null(value);
     switch (typeof value) {
         case 'number':
-            return ValueType.Number;
+            return visit.number(value);
         case 'string':
-            return ValueType.String;
+            return visit.string(value);
         case 'boolean':
-            return ValueType.Boolean;
+            return visit.boolean(value);
         default:
             break;
     }
     if (value instanceof Date)
-        return ValueType.Date;
+        return visit.date(value);
     if (isHyperlinkValue(value))
-        return ValueType.Hyperlink;
+        return visit.hyperlink(value);
     if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
-        return ValueType.Formula;
+        return visit.formula(value);
     }
     if (isRichTextValue(value))
-        return ValueType.RichText;
+        return visit.richText(value);
     if (isErrorValue(value))
-        return ValueType.Error;
+        return visit.error(value);
     return unsupportedValue(value);
 }
+const TO_TYPE = {
+    null: () => ValueType.Null,
+    number: () => ValueType.Number,
+    string: () => ValueType.String,
+    boolean: () => ValueType.Boolean,
+    date: () => ValueType.Date,
+    error: () => ValueType.Error,
+    formula: () => ValueType.Formula,
+    richText: () => ValueType.RichText,
+    hyperlink: () => ValueType.Hyperlink,
+};
+const TO_TEXT = {
+    null: () => '',
+    number: (value) => String(value),
+    string: (value) => value,
+    boolean: (value) => (value ? 'TRUE' : 'FALSE'),
+    date: (value) => (Number.isNaN(value.getTime()) ? '' : value.toISOString()),
+    error: (value) => value.error,
+    formula: (value) => (value.result === undefined ? '' : cellValueToText(value.result)),
+    richText: richTextToPlain,
+    hyperlink: (value) => (typeof value.text === 'string' ? value.text : richTextToPlain(value.text)),
+};
 function unsupportedValue(value) {
     throw new TypeError(`unsupported cell value: ${describe(value)}`);
 }

package/dist/core/workbook-media.d.ts

@@ -0,0 +1,34 @@
+import { type WorkbookImage } from './image.ts';
+export declare class WorkbookMedia {
+    #private;
+    /** The registered images, indexed by the id {@link register} returned. Live, not a copy. */
+    get all(): readonly WorkbookImage[];
+    /** Look up a registered image by its id, or `undefined` if no image carries that id. */
+    get(id: number): WorkbookImage | undefined;
+    /**
+     * {@link get} for a caller that has no answer for an absent id.
+     *
+     * An unregistered id is what a sheet belonging to *another* workbook looks like from here, which
+     * is why the message names the sheet rather than the id alone. Emitting a package with a drawing
+     * pointing at media nobody registered is the silently-broken-image failure this refuses to start.
+     *
+     * @throws {AuthoringError} if no image carries that id.
+     */
+    require(id: number, forSheetName: string): WorkbookImage;
+    /** Store a picture's bytes and return the id that names them. */
+    register(extension: string | undefined, buffer: Uint8Array): number;
+    /**
+     * Register a picture arriving from elsewhere, re-using an identical one already held.
+     *
+     * The extension is re-normalised rather than trusted: a hand-built {@link WorkbookImage} may carry
+     * `".PNG"` where the registry holds `"png"`, and two spellings of one kind must not read as two
+     * pictures.
+     *
+     * Through the content index rather than a scan. Comparing byte-by-byte against every held picture
+     * made importing n distinct images cost n squared byte comparisons: fifty 1 MB pictures carried
+     * between workbooks compared about 2.5 GB. The *rule* is unchanged, and `imageContentKey` states
+     * why identity here is content and never object identity. The index is built in reverse so the
+     * FIRST id registered under a key wins, which is the answer the scan gave.
+     */
+    registerExisting(image: WorkbookImage): number;
+}

package/dist/core/workbook-media.js

@@ -0,0 +1,44 @@
+import { AuthoringError, quoted } from '../errors.js';
+import { imageContentKey, normalizeImageExtension } from './image.js';
+export class WorkbookMedia {
+    #images = [];
+    #byContent;
+    get all() {
+        return this.#images;
+    }
+    get(id) {
+        return this.#images[id];
+    }
+    require(id, forSheetName) {
+        const image = this.#images[id];
+        if (image === undefined) {
+            throw new AuthoringError(`worksheet ${quoted(forSheetName)} shows image id ${id}, which is not registered on this ` +
+                "workbook: a sheet's images can only be exported by the workbook that holds them");
+        }
+        return image;
+    }
+    register(extension, buffer) {
+        const image = {
+            extension: normalizeImageExtension(extension, buffer),
+            data: buffer,
+        };
+        this.#images.push(image);
+        const id = this.#images.length - 1;
+        const index = this.#byContent;
+        if (index !== undefined) {
+            const key = imageContentKey(image);
+            if (!index.has(key))
+                index.set(key, id);
+        }
+        return id;
+    }
+    registerExisting(image) {
+        const candidate = {
+            extension: normalizeImageExtension(image.extension, image.data),
+            data: image.data,
+        };
+        this.#byContent ??= new Map(this.#images.map((held, id) => [imageContentKey(held), id]).reverse());
+        return (this.#byContent.get(imageContentKey(candidate)) ??
+            this.register(candidate.extension, candidate.data));
+    }
+}