yarramate 1.4.1 → 1.6.0

package/dist/workbook-read.js

@@ -0,0 +1,314 @@
+/**
+ * Reading an `.xlsx` back, without a dependency (#355).
+ *
+ * Asymmetric with the writer on purpose. Writing uses stored entries and stays
+ * synchronous; **reading cannot**, because a workbook that has been through
+ * Excel comes back deflated. Verified against a real consulting template
+ * rather than assumed: every part reports `Defl:N`, every cell is `t="s"`
+ * against a `sharedStrings` part, and there is not one inline string left. So
+ * the reader inflates through `DecompressionStream('deflate-raw')` - present
+ * on Workers, in browsers and in Node 18+ - and resolves shared strings as
+ * well as the inline ones this repository writes.
+ *
+ * Two details that are easy to miss and silently corrupt a row:
+ *
+ * - **Excel omits empty cells entirely.** A row is not a dense list, so a
+ *   cell's column comes from its `r` reference (`C7`) and nowhere else.
+ *   Reading positionally shifts every value after the first blank.
+ * - **A zip carries directory entries** with zero length. They are not parts.
+ */
+const decoder = new TextDecoder();
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+};
+export const decodeXmlText = (value) => value.replace(/&(#x?[0-9a-fA-F]+|[a-z]+);/g, (whole, entity) => {
+    if (entity.startsWith('#x') || entity.startsWith('#X')) {
+        return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+    }
+    if (entity.startsWith('#')) {
+        return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+    }
+    return ENTITIES[entity] ?? whole;
+});
+/** `C7` -> 2. The letters are base-26 with no zero. */
+export const columnIndexOf = (reference) => {
+    const letters = /^([A-Z]+)/.exec(reference)?.[1];
+    if (letters === undefined)
+        return 0;
+    let index = 0;
+    for (const letter of letters) {
+        index = index * 26 + (letter.charCodeAt(0) - 64);
+    }
+    return index - 1;
+};
+const inflateRaw = async (bytes) => {
+    // Fed through a stream rather than a Blob: `Blob` is not in the Node types
+    // this package builds against, and a one-chunk ReadableStream is available
+    // everywhere this has to run.
+    const source = new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+    // Cast at the seam: DOM lib types `DecompressionStream.writable` as
+    // `WritableStream<BufferSource>`, which does not unify with the
+    // `ReadableStream<Uint8Array>` above. The runtime contract is the one this
+    // relies on, and it is the same on Workers, in browsers and in Node.
+    const inflated = source.pipeThrough(new DecompressionStream('deflate-raw'));
+    const parts = [];
+    const reader = inflated.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value !== undefined)
+            parts.push(value);
+    }
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const part of parts) {
+        out.set(part, at);
+        at += part.length;
+    }
+    return out;
+};
+/**
+ * Every part in the archive, by path. Directory entries are skipped, and an
+ * unknown compression method is refused rather than guessed at: a part read
+ * wrongly would parse as an empty sheet, which is the silent failure this
+ * whole feature exists to avoid.
+ */
+export const unzipEntries = async (bytes) => {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let end = -1;
+    for (let at = bytes.length - 22; at >= 0; at -= 1) {
+        if (view.getUint32(at, true) === 0x06054b50) {
+            end = at;
+            break;
+        }
+    }
+    if (end < 0)
+        return { ok: false, reason: 'not a zip archive' };
+    const count = view.getUint16(end + 10, true);
+    let at = view.getUint32(end + 16, true);
+    const entries = new Map();
+    for (let index = 0; index < count; index += 1) {
+        if (view.getUint32(at, true) !== 0x02014b50) {
+            return { ok: false, reason: 'damaged central directory' };
+        }
+        const method = view.getUint16(at + 10, true);
+        const compressedSize = view.getUint32(at + 20, true);
+        const nameLength = view.getUint16(at + 28, true);
+        const extraLength = view.getUint16(at + 30, true);
+        const commentLength = view.getUint16(at + 32, true);
+        const localAt = view.getUint32(at + 42, true);
+        const name = decoder.decode(bytes.subarray(at + 46, at + 46 + nameLength));
+        at += 46 + nameLength + extraLength + commentLength;
+        // A directory, not a part.
+        if (name.endsWith('/'))
+            continue;
+        if (view.getUint32(localAt, true) !== 0x04034b50) {
+            return { ok: false, reason: `damaged entry ${name}` };
+        }
+        const localNameLength = view.getUint16(localAt + 26, true);
+        const localExtraLength = view.getUint16(localAt + 28, true);
+        const from = localAt + 30 + localNameLength + localExtraLength;
+        const raw = bytes.subarray(from, from + compressedSize);
+        if (method === 0) {
+            entries.set(name, raw);
+        }
+        else if (method === 8) {
+            entries.set(name, await inflateRaw(raw));
+        }
+        else {
+            return { ok: false, reason: `unsupported compression in ${name}` };
+        }
+    }
+    return { ok: true, entries };
+};
+/**
+ * A scanner for the shapes SpreadsheetML uses, rather than a general XML
+ * parser. OOXML is machine-generated and narrow, and a full parser is more
+ * code than this file needs.
+ */
+const scan = (xml, onTag, onText) => {
+    let at = 0;
+    while (at < xml.length) {
+        const open = xml.indexOf('<', at);
+        if (open < 0)
+            break;
+        if (open > at)
+            onText(xml.slice(at, open));
+        if (xml.startsWith('<!--', open)) {
+            const done = xml.indexOf('-->', open);
+            at = done < 0 ? xml.length : done + 3;
+            continue;
+        }
+        if (xml.startsWith('<?', open) || xml.startsWith('<!', open)) {
+            const done = xml.indexOf('>', open);
+            at = done < 0 ? xml.length : done + 1;
+            continue;
+        }
+        const close = xml.indexOf('>', open);
+        if (close < 0)
+            break;
+        const body = xml.slice(open + 1, close);
+        const closing = body.startsWith('/');
+        const selfClosing = body.endsWith('/');
+        const inner = body.slice(closing ? 1 : 0, selfClosing ? -1 : undefined);
+        const name = /^([^\s/>]+)/.exec(inner)?.[1] ?? '';
+        const attributes = {};
+        for (const match of inner
+            .slice(name.length)
+            .matchAll(/([\w:.-]+)\s*=\s*"([^"]*)"/g)) {
+            attributes[match[1]] = decodeXmlText(match[2]);
+        }
+        onTag({ name, attributes, selfClosing, closing });
+        at = close + 1;
+    }
+};
+const localName = (name) => {
+    const colon = name.indexOf(':');
+    return colon < 0 ? name : name.slice(colon + 1);
+};
+const sharedStringsOf = (xml) => {
+    const strings = [];
+    let inItem = false;
+    let inText = false;
+    let current = '';
+    scan(xml, (tag) => {
+        const name = localName(tag.name);
+        if (name === 'si') {
+            if (tag.closing) {
+                strings.push(current);
+                inItem = false;
+            }
+            else {
+                inItem = true;
+                current = '';
+                if (tag.selfClosing) {
+                    strings.push('');
+                    inItem = false;
+                }
+            }
+            return;
+        }
+        // A shared string can be split into runs; `t` inside `r` still counts.
+        if (name === 't')
+            inText = !tag.closing && !tag.selfClosing;
+    }, (text) => {
+        if (inItem && inText)
+            current += decodeXmlText(text);
+    });
+    return strings;
+};
+const rowsOf = (xml, shared) => {
+    const rows = [];
+    let row;
+    let column = 0;
+    let type = '';
+    let inValue = false;
+    let inInlineText = false;
+    let cell = '';
+    scan(xml, (tag) => {
+        const name = localName(tag.name);
+        if (name === 'row') {
+            if (tag.closing) {
+                if (row !== undefined)
+                    rows.push(row);
+                row = undefined;
+            }
+            else {
+                row = [];
+                if (tag.selfClosing) {
+                    rows.push(row);
+                    row = undefined;
+                }
+            }
+            return;
+        }
+        if (name === 'c') {
+            if (tag.closing || tag.selfClosing) {
+                if (row !== undefined) {
+                    const resolved = type === 's' ? (shared[Number.parseInt(cell, 10)] ?? '') : cell;
+                    while (row.length < column)
+                        row.push('');
+                    row[column] = resolved;
+                }
+                cell = '';
+                type = '';
+                return;
+            }
+            // Excel omits empty cells, so the column comes from `r` and nothing
+            // else. Reading positionally shifts every value after a blank.
+            column = tag.attributes.r === undefined ? row?.length ?? 0 : columnIndexOf(tag.attributes.r);
+            type = tag.attributes.t ?? '';
+            cell = '';
+            return;
+        }
+        if (name === 'v')
+            inValue = !tag.closing && !tag.selfClosing;
+        if (name === 't')
+            inInlineText = !tag.closing && !tag.selfClosing;
+    }, (text) => {
+        if (inValue || inInlineText)
+            cell += decodeXmlText(text);
+    });
+    return rows;
+};
+/** The workbook's sheets, by name. Async, because a saved workbook is deflated. */
+export const readWorkbook = async (bytes) => {
+    const archive = await unzipEntries(bytes);
+    if (!archive.ok)
+        return archive;
+    const { entries } = archive;
+    const workbookPart = entries.get('xl/workbook.xml');
+    if (workbookPart === undefined) {
+        return { ok: false, reason: 'no xl/workbook.xml: not a workbook' };
+    }
+    const relsPart = entries.get('xl/_rels/workbook.xml.rels');
+    const targets = new Map();
+    if (relsPart !== undefined) {
+        scan(decoder.decode(relsPart), (tag) => {
+            if (localName(tag.name) !== 'Relationship' || tag.closing)
+                return;
+            const id = tag.attributes.Id;
+            const target = tag.attributes.Target;
+            if (id !== undefined && target !== undefined)
+                targets.set(id, target);
+        }, () => { });
+    }
+    const sharedPart = entries.get('xl/sharedStrings.xml');
+    const shared = sharedPart === undefined ? [] : sharedStringsOf(decoder.decode(sharedPart));
+    const sheets = new Map();
+    const ordered = [];
+    scan(decoder.decode(workbookPart), (tag) => {
+        if (localName(tag.name) !== 'sheet' || tag.closing)
+            return;
+        const name = tag.attributes.name;
+        const relationship = tag.attributes['r:id'] ?? tag.attributes.id ?? tag.attributes['relId'];
+        if (name === undefined || relationship === undefined)
+            return;
+        const target = targets.get(relationship);
+        if (target !== undefined)
+            ordered.push({ name, target });
+    }, () => { });
+    for (const { name, target } of ordered) {
+        const path = target.startsWith('/')
+            ? target.slice(1)
+            : target.startsWith('xl/')
+                ? target
+                : `xl/${target}`;
+        const part = entries.get(path);
+        if (part === undefined)
+            continue;
+        sheets.set(name, rowsOf(decoder.decode(part), shared));
+    }
+    return { ok: true, sheets };
+};

package/dist/workbook-xlsx.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A minimal OPC/xlsx container, written by hand.
+ *
+ * An `.xlsx` file is a zip of XML parts, so this needs no dependency at all -
+ * which is the point. The workbook has to be produced inside a Cloudflare
+ * Worker (#355), where `fs` and Node streams do not exist and bundle size is a
+ * budget, and every xlsx library on npm is both larger than this file and
+ * built for Node.
+ *
+ * Entries are written with the **stored** method rather than deflated. Excel
+ * accepts stored entries, and it keeps writing SYNCHRONOUS: the only
+ * compressor available in a Worker is `CompressionStream`, which is async, and
+ * an async writer would infect every caller including ApertureX's synchronous
+ * `SourceStore` seam (ADR 0100). Reading is a different matter and is async,
+ * because Excel re-saves deflated.
+ *
+ * Timestamps are fixed rather than current, so identical input produces
+ * identical bytes. `export rtm` already holds that line - "the output carries
+ * no timestamp, so identical inputs produce identical bytes and CI can diff
+ * it" - and a workbook that differs on every run could not be reviewed.
+ */
+/** How a sheet appears in Excel's tab strip. */
+export type SheetState = 'visible' | 'hidden' | 'veryHidden';
+export interface WorkbookSheet {
+    readonly name: string;
+    /** Defaults to visible. `veryHidden` cannot be unhidden from Excel's UI. */
+    readonly state?: SheetState;
+    /** Rows of cells. Every value is written as an inline string. */
+    readonly rows: readonly (readonly string[])[];
+    /** Rows to keep on screen when scrolling, usually 1 for a header. */
+    readonly frozenRows?: number;
+}
+/**
+ * XML text escaping.
+ *
+ * Control characters are dropped rather than escaped: XML 1.0 cannot represent
+ * most of them at all, and a NUL reaching a spreadsheet is the failure mode
+ * that silently defeats every text tool downstream.
+ */
+export declare const escapeXml: (value: string) => string;
+/** `0 -> A`, `26 -> AA`, the spreadsheet column alphabet. */
+export declare const columnName: (index: number) => string;
+/**
+ * Excel forbids these in a sheet name, and caps it at 31 characters. A name
+ * that collides after truncation would produce a workbook Excel refuses to
+ * open, so callers keep their names short and distinct rather than relying on
+ * repair here.
+ */
+export declare const sheetNameIsLegal: (name: string) => boolean;
+/**
+ * The workbook, as bytes. Synchronous, dependency-free, and deterministic:
+ * the same sheets always produce the same bytes.
+ */
+export declare const writeXlsx: (sheets: readonly WorkbookSheet[]) => Uint8Array;

package/dist/workbook-xlsx.js

@@ -0,0 +1,228 @@
+/**
+ * A minimal OPC/xlsx container, written by hand.
+ *
+ * An `.xlsx` file is a zip of XML parts, so this needs no dependency at all -
+ * which is the point. The workbook has to be produced inside a Cloudflare
+ * Worker (#355), where `fs` and Node streams do not exist and bundle size is a
+ * budget, and every xlsx library on npm is both larger than this file and
+ * built for Node.
+ *
+ * Entries are written with the **stored** method rather than deflated. Excel
+ * accepts stored entries, and it keeps writing SYNCHRONOUS: the only
+ * compressor available in a Worker is `CompressionStream`, which is async, and
+ * an async writer would infect every caller including ApertureX's synchronous
+ * `SourceStore` seam (ADR 0100). Reading is a different matter and is async,
+ * because Excel re-saves deflated.
+ *
+ * Timestamps are fixed rather than current, so identical input produces
+ * identical bytes. `export rtm` already holds that line - "the output carries
+ * no timestamp, so identical inputs produce identical bytes and CI can diff
+ * it" - and a workbook that differs on every run could not be reviewed.
+ */
+const FIXED_DOS_TIME = 0;
+/** 1980-01-01, the zero of DOS date encoding. */
+const FIXED_DOS_DATE = 33;
+const encoder = new TextEncoder();
+const crcTable = (() => {
+    const table = new Uint32Array(256);
+    for (let index = 0; index < 256; index += 1) {
+        let value = index;
+        for (let bit = 0; bit < 8; bit += 1) {
+            value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+        }
+        table[index] = value >>> 0;
+    }
+    return table;
+})();
+const crc32 = (bytes) => {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc = crcTable[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+};
+/**
+ * XML text escaping.
+ *
+ * Control characters are dropped rather than escaped: XML 1.0 cannot represent
+ * most of them at all, and a NUL reaching a spreadsheet is the failure mode
+ * that silently defeats every text tool downstream.
+ */
+export const escapeXml = (value) => value
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+/** `0 -> A`, `26 -> AA`, the spreadsheet column alphabet. */
+export const columnName = (index) => {
+    let name = '';
+    let remaining = index;
+    for (;;) {
+        name = String.fromCharCode(65 + (remaining % 26)) + name;
+        if (remaining < 26)
+            return name;
+        remaining = Math.floor(remaining / 26) - 1;
+    }
+};
+/**
+ * Excel forbids these in a sheet name, and caps it at 31 characters. A name
+ * that collides after truncation would produce a workbook Excel refuses to
+ * open, so callers keep their names short and distinct rather than relying on
+ * repair here.
+ */
+export const sheetNameIsLegal = (name) => name.length > 0 && name.length <= 31 && !/[\\/?*[\]:]/.test(name);
+const sheetXml = (sheet) => {
+    const rows = sheet.rows
+        .map((cells, rowIndex) => {
+        const row = rowIndex + 1;
+        const written = cells
+            .map((value, columnIndex) => value === ''
+            ? ''
+            : `<c r="${columnName(columnIndex)}${row}" t="inlineStr">` +
+                `<is><t xml:space="preserve">${escapeXml(value)}</t></is></c>`)
+            .join('');
+        return `<row r="${row}">${written}</row>`;
+    })
+        .join('');
+    const pane = sheet.frozenRows === undefined || sheet.frozenRows <= 0
+        ? '<sheetView workbookViewId="0"/>'
+        : `<sheetView workbookViewId="0"><pane ySplit="${sheet.frozenRows}" ` +
+            `topLeftCell="A${sheet.frozenRows + 1}" activePane="bottomLeft" state="frozen"/></sheetView>`;
+    return ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+        '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">' +
+        `<sheetViews>${pane}</sheetViews>` +
+        `<sheetData>${rows}</sheetData>` +
+        '</worksheet>');
+};
+const workbookXml = (sheets) => {
+    const entries = sheets
+        .map((sheet, index) => {
+        const state = sheet.state === undefined || sheet.state === 'visible'
+            ? ''
+            : ` state="${sheet.state === 'veryHidden' ? 'veryHidden' : 'hidden'}"`;
+        return (`<sheet name="${escapeXml(sheet.name)}" sheetId="${index + 1}"` +
+            `${state} r:id="rId${index + 1}"/>`);
+    })
+        .join('');
+    return ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+        '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" ' +
+        'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">' +
+        `<sheets>${entries}</sheets>` +
+        '</workbook>');
+};
+const zip = (entries) => {
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = encoder.encode(entry.path);
+        const crc = crc32(entry.bytes);
+        const size = entry.bytes.length;
+        const local = new Uint8Array(30 + name.length + size);
+        const localView = new DataView(local.buffer);
+        localView.setUint32(0, 0x04034b50, true);
+        localView.setUint16(4, 20, true);
+        localView.setUint16(6, 0, true);
+        localView.setUint16(8, 0, true); // stored
+        localView.setUint16(10, FIXED_DOS_TIME, true);
+        localView.setUint16(12, FIXED_DOS_DATE, true);
+        localView.setUint32(14, crc, true);
+        localView.setUint32(18, size, true);
+        localView.setUint32(22, size, true);
+        localView.setUint16(26, name.length, true);
+        localView.setUint16(28, 0, true);
+        local.set(name, 30);
+        local.set(entry.bytes, 30 + name.length);
+        locals.push(local);
+        const central = new Uint8Array(46 + name.length);
+        const centralView = new DataView(central.buffer);
+        centralView.setUint32(0, 0x02014b50, true);
+        centralView.setUint16(4, 20, true);
+        centralView.setUint16(6, 20, true);
+        centralView.setUint16(8, 0, true);
+        centralView.setUint16(10, 0, true); // stored
+        centralView.setUint16(12, FIXED_DOS_TIME, true);
+        centralView.setUint16(14, FIXED_DOS_DATE, true);
+        centralView.setUint32(16, crc, true);
+        centralView.setUint32(20, size, true);
+        centralView.setUint32(24, size, true);
+        centralView.setUint16(28, name.length, true);
+        centralView.setUint16(30, 0, true);
+        centralView.setUint16(32, 0, true);
+        centralView.setUint16(34, 0, true);
+        centralView.setUint16(36, 0, true);
+        centralView.setUint32(38, 0, true);
+        centralView.setUint32(42, offset, true);
+        central.set(name, 46);
+        centrals.push(central);
+        offset += local.length;
+    }
+    const centralSize = centrals.reduce((total, part) => total + part.length, 0);
+    const end = new Uint8Array(22);
+    const endView = new DataView(end.buffer);
+    endView.setUint32(0, 0x06054b50, true);
+    endView.setUint16(8, entries.length, true);
+    endView.setUint16(10, entries.length, true);
+    endView.setUint32(12, centralSize, true);
+    endView.setUint32(16, offset, true);
+    const parts = [...locals, ...centrals, end];
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const part of parts) {
+        out.set(part, at);
+        at += part.length;
+    }
+    return out;
+};
+/**
+ * The workbook, as bytes. Synchronous, dependency-free, and deterministic:
+ * the same sheets always produce the same bytes.
+ */
+export const writeXlsx = (sheets) => {
+    if (sheets.length === 0) {
+        throw new Error('A workbook needs at least one sheet');
+    }
+    for (const sheet of sheets) {
+        if (!sheetNameIsLegal(sheet.name)) {
+            throw new Error(`Illegal sheet name: ${JSON.stringify(sheet.name)}`);
+        }
+    }
+    const names = new Set(sheets.map(({ name }) => name.toLowerCase()));
+    if (names.size !== sheets.length) {
+        throw new Error('Sheet names must be distinct, case-insensitively');
+    }
+    const contentTypes = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+        '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+        '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+        '<Default Extension="xml" ContentType="application/xml"/>' +
+        '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>' +
+        sheets
+            .map((_sheet, index) => `<Override PartName="/xl/worksheets/sheet${index + 1}.xml" ` +
+            'ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>')
+            .join('') +
+        '</Types>';
+    const rootRels = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+        '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+        '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>' +
+        '</Relationships>';
+    const workbookRels = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+        '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+        sheets
+            .map((_sheet, index) => `<Relationship Id="rId${index + 1}" ` +
+            'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" ' +
+            `Target="worksheets/sheet${index + 1}.xml"/>`)
+            .join('') +
+        '</Relationships>';
+    return zip([
+        { path: '[Content_Types].xml', bytes: encoder.encode(contentTypes) },
+        { path: '_rels/.rels', bytes: encoder.encode(rootRels) },
+        { path: 'xl/workbook.xml', bytes: encoder.encode(workbookXml(sheets)) },
+        { path: 'xl/_rels/workbook.xml.rels', bytes: encoder.encode(workbookRels) },
+        ...sheets.map((sheet, index) => ({
+            path: `xl/worksheets/sheet${index + 1}.xml`,
+            bytes: encoder.encode(sheetXml(sheet)),
+        })),
+    ]);
+};

package/dist/workbook.d.ts

@@ -0,0 +1,32 @@
+import type { ProjectionResult } from './projection.js';
+import { type WorkbookSheet } from './workbook-xlsx.js';
+/**
+ * The model as a workbook an architect can work in (#355).
+ *
+ * The shape is borrowed from a real consulting workbook rather than invented:
+ * identity is columnar and readability is derived. A stable id in column A,
+ * foreign keys inline, and an adjacent `(auto)` column carrying the referenced
+ * subject's NAME so a sheet reads without hunting across tabs. The id is what
+ * round-trips; the `(auto)` column is a convenience and is ignored on import.
+ *
+ * Losslessness does not depend on this file enumerating every predicate
+ * correctly. Well-known predicates become columns because a person needs them
+ * to be columns; **everything else lands in `07 Other Facts` verbatim**, so a
+ * predicate added to the compiler after this was written still survives a
+ * round trip. A mapping that silently dropped what it did not recognise is the
+ * failure this design exists to avoid.
+ */
+export declare const WORKBOOK_FORMAT = "yarramate/workbook/v1";
+export interface WorkbookProvenance {
+    readonly workspace: string;
+    readonly yarramateVersion: string;
+    /** What the graph was compiled from, the pin a later import checks. */
+    readonly sourceDigests: Readonly<Record<string, string>>;
+    /** Vocabulary for the dropdown lists, taken from the compiled profile. */
+    readonly conceptKinds: readonly string[];
+    readonly relationshipKinds: readonly string[];
+    readonly statuses: readonly string[];
+}
+export declare const buildWorkbookSheets: (result: ProjectionResult, provenance: WorkbookProvenance) => readonly WorkbookSheet[];
+/** The workbook, as bytes. Synchronous and deterministic. */
+export declare const workbookFrom: (result: ProjectionResult, provenance: WorkbookProvenance) => Uint8Array;