hwpkit-dev 0.0.1

package/src/safety/StyleBridge.ts

@@ -0,0 +1,106 @@
+import type { Align, StrokeKind, Stroke } from '../model/doc-props';
+
+// ─── 단위 변환 ─────────────────────────────────────────────
+export const Metric = {
+  // HWP 세계 (1 inch = 7200 HWPUNIT)
+  hwpToPt:     (v: number) => v / 100,
+  ptToHwp:     (v: number) => Math.round(v * 100),
+  hwpToDxa:    (v: number) => Math.round(v / 5),
+  dxaToHwp:    (v: number) => Math.round(v * 5),
+  hwpToEmu:    (v: number) => Math.round(v * 127),
+  emuToHwp:    (v: number) => Math.round(v / 127),
+
+  // DOCX 세계 (1 inch = 1440 dxa, 1 pt = 20 dxa)
+  dxaToPt:     (v: number) => v / 20,
+  ptToDxa:     (v: number) => Math.round(v * 20),
+  dxaToEmu:    (v: number) => Math.round(v * 635),
+  emuToDxa:    (v: number) => Math.round(v / 635),
+  emuToPt:     (v: number) => v / 12700,
+  ptToEmu:     (v: number) => Math.round(v * 12700),
+
+  // HWPX charPr height: 1000 = 10pt
+  hHeightToPt: (v: number) => v / 100,
+  ptToHHeight: (v: number) => Math.round(v * 100),
+
+  // DOCX half-point: 24 = 12pt
+  halfPtToPt:  (v: number) => v / 2,
+  ptToHalfPt:  (v: number) => Math.round(v * 2),
+} as const;
+
+// ─── 색상 정규화 ───────────────────────────────────────────
+export function safeHex(raw: string | number | null | undefined): string | undefined {
+  if (raw == null) return undefined;
+  if (typeof raw === 'number') {
+    if (raw <= 0) return '000000';
+    if (raw >= 0xFFFFFF) return undefined;
+    return raw.toString(16).padStart(6, '0').toUpperCase();
+  }
+  let s = String(raw).replace(/^#/, '').toUpperCase();
+  if (/^[0-9A-F]{3}$/.test(s)) s = s[0] + s[0] + s[1] + s[1] + s[2] + s[2];
+  if (/^[0-9A-F]{6}$/.test(s)) return s;
+  if (s === 'AUTO' || s === 'NONE' || s === 'TRANSPARENT') return undefined;
+  return undefined;
+}
+
+// ─── 정렬 정규화 ───────────────────────────────────────────
+const ALIGN_MAP: Record<string, Align> = {
+  LEFT: 'left', CENTER: 'center', RIGHT: 'right', JUSTIFY: 'justify',
+  BOTH: 'justify', DISTRIBUTE: 'justify',
+  left: 'left', center: 'center', right: 'right', both: 'justify',
+  start: 'left', end: 'right',
+};
+export function safeAlign(raw?: string): Align {
+  return ALIGN_MAP[raw ?? ''] ?? 'justify';
+}
+
+// ─── 테두리 정규화 ─────────────────────────────────────────
+const HWPX_STROKE: Record<string, StrokeKind> = {
+  SOLID: 'solid', NONE: 'none', DASH: 'dash', DOT: 'dot',
+  DOUBLE: 'double', LONG_DASH: 'dash', DASH_DOT: 'dash',
+};
+const DOCX_STROKE: Record<string, StrokeKind> = {
+  single: 'solid', none: 'none', nil: 'none', dashed: 'dash',
+  dotted: 'dot', double: 'double', wave: 'solid',
+};
+
+export function safeStrokeHwpx(type?: string, w?: number, c?: string): Stroke {
+  return {
+    kind: HWPX_STROKE[type ?? ''] ?? 'solid',
+    pt: w != null ? Metric.hwpToPt(w) : 0.5,
+    color: safeHex(c) ?? '000000',
+  };
+}
+
+export function safeStrokeDocx(val?: string, sz?: number, c?: string): Stroke {
+  return {
+    kind: DOCX_STROKE[val ?? ''] ?? 'solid',
+    pt: sz != null ? sz / 8 : 0.5,
+    color: safeHex(c) ?? '000000',
+  };
+}
+
+// ─── 폰트 정규화 ───────────────────────────────────────────
+const FONT_MAP: Record<string, string> = {
+  '맑은 고딕': 'Malgun Gothic',
+  '바탕': 'Batang',
+  '돋움': 'Dotum',
+  '굴림': 'Gulim',
+  '한컴바탕': 'Batang',
+  '한컴돋움': 'Malgun Gothic',
+  '함초롬바탕': 'Batang',
+  '함초롬돋움': 'Malgun Gothic',
+};
+export function safeFont(raw?: string): string {
+  return FONT_MAP[raw ?? ''] ?? raw ?? 'Malgun Gothic';
+}
+
+// Reverse mapping: English → Korean (for HWPX encoding)
+const FONT_MAP_KR: Record<string, string> = {
+  'Malgun Gothic': '맑은 고딕',
+  'Batang': '바탕',
+  'Dotum': '돋움',
+  'Gulim': '굴림',
+};
+export function safeFontToKr(raw?: string): string {
+  return FONT_MAP_KR[raw ?? ''] ?? raw ?? '맑은 고딕';
+}

package/src/toolkit/ArchiveKit.ts

@@ -0,0 +1,150 @@
+import pako from 'pako';
+
+interface ZipEntry {
+  name: string;
+  data: Uint8Array;
+}
+
+export const ArchiveKit = {
+  async inflate(compressed: Uint8Array): Promise<Uint8Array> {
+    return pako.inflate(compressed);
+  },
+
+  async deflate(data: Uint8Array): Promise<Uint8Array> {
+    return pako.deflate(data, { level: 6 });
+  },
+
+  async unzip(zipData: Uint8Array): Promise<Map<string, Uint8Array>> {
+    const files = new Map<string, Uint8Array>();
+    const view = new DataView(zipData.buffer, zipData.byteOffset, zipData.byteLength);
+
+    let offset = 0;
+    while (offset < zipData.length - 4) {
+      const sig = view.getUint32(offset, true);
+
+      if (sig === 0x04034b50) {
+        const compressionMethod = view.getUint16(offset + 8, true);
+        const compressedSize    = view.getUint32(offset + 18, true);
+        const uncompressedSize  = view.getUint32(offset + 22, true);
+        const fileNameLength    = view.getUint16(offset + 26, true);
+        const extraLength       = view.getUint16(offset + 28, true);
+
+        const nameBytes = zipData.subarray(offset + 30, offset + 30 + fileNameLength);
+        const name = new TextDecoder('utf-8').decode(nameBytes);
+
+        const dataOffset = offset + 30 + fileNameLength + extraLength;
+        let fileData: Uint8Array;
+
+        if (compressionMethod === 0) {
+          fileData = zipData.subarray(dataOffset, dataOffset + uncompressedSize);
+        } else if (compressionMethod === 8) {
+          const compressed = zipData.subarray(dataOffset, dataOffset + compressedSize);
+          fileData = pako.inflateRaw(compressed);
+        } else {
+          throw new Error(`Unsupported ZIP compression method: ${compressionMethod}`);
+        }
+
+        files.set(name, new Uint8Array(fileData));
+        offset = dataOffset + compressedSize;
+      } else if (sig === 0x02014b50 || sig === 0x06054b50) {
+        break;
+      } else {
+        offset++;
+      }
+    }
+
+    return files;
+  },
+
+  async zip(entries: ZipEntry[]): Promise<Uint8Array> {
+    const localHeaders: Uint8Array[] = [];
+    const centralHeaders: Uint8Array[] = [];
+    let localOffset = 0;
+
+    for (const entry of entries) {
+      const nameBytes = new TextEncoder().encode(entry.name);
+      const crc = crc32(entry.data);
+
+      // 'mimetype' and 'version.xml' must be stored uncompressed per HWPX spec
+      const store = entry.name === 'mimetype' || entry.name === 'version.xml';
+      const method = store ? 0 : 8;
+      const payload = store ? entry.data : pako.deflateRaw(entry.data, { level: 6 });
+
+      // Local file header (30 bytes + name + data)
+      const local = new Uint8Array(30 + nameBytes.length + payload.length);
+      const lv = new DataView(local.buffer);
+      lv.setUint32(0, 0x04034b50, true);
+      lv.setUint16(4, 20, true);
+      lv.setUint16(6, 0, true);
+      lv.setUint16(8, method, true);
+      lv.setUint16(10, 0, true);
+      lv.setUint16(12, 0x0021, true); // date (1980-01-01)
+      lv.setUint32(14, crc, true);
+      lv.setUint32(18, payload.length, true);
+      lv.setUint32(22, entry.data.length, true);
+      lv.setUint16(26, nameBytes.length, true);
+      lv.setUint16(28, 0, true);
+      local.set(nameBytes, 30);
+      local.set(payload, 30 + nameBytes.length);
+
+      // Central directory header (46 bytes + name)
+      const central = new Uint8Array(46 + nameBytes.length);
+      const cv = new DataView(central.buffer);
+      cv.setUint32(0, 0x02014b50, true);
+      cv.setUint16(4, 20, true);
+      cv.setUint16(6, 20, true);
+      cv.setUint16(8, 0, true);
+      cv.setUint16(10, method, true);
+      cv.setUint16(12, 0, true); // mod time
+      cv.setUint16(14, 0x0021, true); // mod date (1980-01-01)
+      cv.setUint32(16, crc, true);
+      cv.setUint32(20, payload.length, true);
+      cv.setUint32(24, entry.data.length, true);
+      cv.setUint16(28, nameBytes.length, true);
+      cv.setUint16(30, 0, true);
+      cv.setUint16(32, 0, true);
+      cv.setUint16(34, 0, true);
+      cv.setUint16(36, 0, true);
+      cv.setUint32(38, 0, true);
+      cv.setUint32(42, localOffset, true);
+      central.set(nameBytes, 46);
+
+      localHeaders.push(local);
+      centralHeaders.push(central);
+      localOffset += local.length;
+    }
+
+    const centralDir = concat(centralHeaders);
+    const eocd = new Uint8Array(22);
+    const ev = new DataView(eocd.buffer);
+    ev.setUint32(0, 0x06054b50, true);
+    ev.setUint16(4, 0, true);
+    ev.setUint16(6, 0, true);
+    ev.setUint16(8, entries.length, true);
+    ev.setUint16(10, entries.length, true);
+    ev.setUint32(12, centralDir.length, true);
+    ev.setUint32(16, localOffset, true);
+    ev.setUint16(20, 0, true);
+
+    return concat([...localHeaders, centralDir, eocd]);
+  },
+};
+
+function concat(arrays: Uint8Array[]): Uint8Array {
+  const total = arrays.reduce((s, a) => s + a.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const a of arrays) { out.set(a, offset); offset += a.length; }
+  return out;
+}
+
+function crc32(data: Uint8Array): number {
+  let crc = 0xFFFFFFFF;
+  for (const byte of data) {
+    crc ^= byte;
+    for (let i = 0; i < 8; i++) {
+      crc = (crc & 1) ? (crc >>> 1) ^ 0xEDB88320 : crc >>> 1;
+    }
+  }
+  return (crc ^ 0xFFFFFFFF) >>> 0;
+}

package/src/toolkit/BinaryKit.ts

@@ -0,0 +1,187 @@
+/**
+ * OLE2 Compound File Binary Format (CFB) parser.
+ * Used for legacy HWP 5.0 files.
+ */
+
+export const BinaryKit = {
+  readU16LE(buf: Uint8Array, offset: number): number {
+    return buf[offset] | (buf[offset + 1] << 8);
+  },
+
+  readU32LE(buf: Uint8Array, offset: number): number {
+    return (
+      (buf[offset] | (buf[offset + 1] << 8) | (buf[offset + 2] << 16)) >>> 0
+    ) + buf[offset + 3] * 0x1000000;
+  },
+
+  isOle2(data: Uint8Array): boolean {
+    return (
+      data.length >= 8 &&
+      data[0] === 0xD0 && data[1] === 0xCF &&
+      data[2] === 0x11 && data[3] === 0xE0 &&
+      data[4] === 0xA1 && data[5] === 0xB1 &&
+      data[6] === 0x1A && data[7] === 0xE1
+    );
+  },
+
+  parseCfb(data: Uint8Array): Map<string, Uint8Array> {
+    const streams = new Map<string, Uint8Array>();
+
+    if (!this.isOle2(data)) {
+      throw new Error('Not a valid OLE2 file');
+    }
+
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const sectorSize   = 1 << view.getUint16(30, true);
+    const miniSectorSz = 1 << view.getUint16(32, true);
+    const dirFirstSec  = view.getUint32(48, true);
+    const miniStreamCutoff = view.getUint32(56, true);
+    const miniFatFirst = view.getUint32(60, true);
+    const miniFatCnt   = view.getUint32(64, true);
+    const difatFirst   = view.getUint32(68, true);
+
+    const ENDOFCHAIN = 0xFFFFFFFE;
+    const FREESECT   = 0xFFFFFFFF;
+
+    const sectorAt = (sec: number): Uint8Array =>
+      data.subarray(512 + sec * sectorSize, 512 + (sec + 1) * sectorSize);
+
+    // Build FAT from DIFAT
+    const fatSecNums: number[] = [];
+    for (let i = 0; i < 109; i++) {
+      const s = view.getUint32(76 + i * 4, true);
+      if (s === FREESECT || s === ENDOFCHAIN) break;
+      fatSecNums.push(s);
+    }
+    if (difatFirst !== ENDOFCHAIN && difatFirst !== FREESECT) {
+      let difSec = difatFirst;
+      while (difSec !== ENDOFCHAIN && difSec !== FREESECT) {
+        const sec = sectorAt(difSec);
+        const sv = new DataView(sec.buffer, sec.byteOffset, sec.byteLength);
+        for (let i = 0; i < (sectorSize / 4) - 1; i++) {
+          const s = sv.getUint32(i * 4, true);
+          if (s === FREESECT || s === ENDOFCHAIN) break;
+          fatSecNums.push(s);
+        }
+        difSec = sv.getUint32(sectorSize - 4, true);
+      }
+    }
+
+    const fat: number[] = [];
+    for (const sec of fatSecNums) {
+      const s = sectorAt(sec);
+      const sv = new DataView(s.buffer, s.byteOffset, s.byteLength);
+      for (let i = 0; i < sectorSize / 4; i++) {
+        fat.push(sv.getUint32(i * 4, true));
+      }
+    }
+
+    const readChain = (startSec: number): Uint8Array => {
+      const chunks: Uint8Array[] = [];
+      let sec = startSec;
+      while (sec !== ENDOFCHAIN && sec !== FREESECT && sec < fat.length) {
+        chunks.push(sectorAt(sec));
+        sec = fat[sec];
+      }
+      return concatUint8(chunks);
+    };
+
+    // Directory entries
+    const dirData = readChain(dirFirstSec);
+    const dirView = new DataView(dirData.buffer, dirData.byteOffset, dirData.byteLength);
+    const dirCount = dirData.length / 128;
+
+    interface DirEntry {
+      name: string;
+      type: number;
+      startSec: number;
+      size: number;
+      childId: number;
+      siblingLeftId: number;
+      siblingRightId: number;
+    }
+
+    const dirEntries: DirEntry[] = [];
+    for (let i = 0; i < dirCount; i++) {
+      const base = i * 128;
+      const nameLen = dirView.getUint16(base + 64, true);
+      const nameBytes = dirData.subarray(base, base + Math.max(0, nameLen - 2));
+      const name = new TextDecoder('utf-16le').decode(nameBytes);
+      const type = dirData[base + 66];
+      const childId      = dirView.getInt32(base + 76, true);
+      const sibLeft       = dirView.getInt32(base + 68, true);
+      const sibRight      = dirView.getInt32(base + 72, true);
+      const startSec     = dirView.getUint32(base + 116, true);
+      const size         = dirView.getUint32(base + 120, true);
+      dirEntries.push({ name, type, startSec, size, childId, siblingLeftId: sibLeft, siblingRightId: sibRight });
+    }
+
+    // Mini stream
+    const rootEntry = dirEntries[0];
+    let miniStreamData: Uint8Array | null = null;
+    let miniFat: number[] = [];
+
+    if (rootEntry && rootEntry.startSec !== ENDOFCHAIN && rootEntry.startSec !== FREESECT) {
+      miniStreamData = readChain(rootEntry.startSec);
+    }
+
+    if (miniFatCnt > 0 && miniFatFirst !== ENDOFCHAIN && miniFatFirst !== FREESECT) {
+      const mfData = readChain(miniFatFirst);
+      const mfv = new DataView(mfData.buffer, mfData.byteOffset, mfData.byteLength);
+      for (let i = 0; i < mfData.length / 4; i++) {
+        miniFat.push(mfv.getUint32(i * 4, true));
+      }
+    }
+
+    const readMiniChain = (startSec: number, size: number): Uint8Array => {
+      if (!miniStreamData) return new Uint8Array(0);
+      const chunks: Uint8Array[] = [];
+      let sec = startSec;
+      let remaining = size;
+      while (sec !== ENDOFCHAIN && sec !== FREESECT && sec < miniFat.length && remaining > 0) {
+        const off = sec * miniSectorSz;
+        const chunk = miniStreamData.subarray(off, off + Math.min(miniSectorSz, remaining));
+        chunks.push(chunk);
+        remaining -= chunk.length;
+        sec = miniFat[sec];
+      }
+      return concatUint8(chunks).subarray(0, size);
+    };
+
+    // DFS traversal
+    const visit = (id: number, path: string): void => {
+      if (id < 0 || id >= dirEntries.length) return;
+      const entry = dirEntries[id];
+      const fullPath = path ? `${path}/${entry.name}` : entry.name;
+
+      if (entry.type === 2) {
+        let streamData: Uint8Array;
+        if (entry.size < miniStreamCutoff && miniStreamData) {
+          streamData = readMiniChain(entry.startSec, entry.size);
+        } else {
+          streamData = readChain(entry.startSec).subarray(0, entry.size);
+        }
+        streams.set(fullPath, streamData);
+        streams.set(entry.name, streamData);
+      }
+
+      if (entry.childId >= 0) visit(entry.childId, fullPath);
+      if (entry.siblingLeftId >= 0) visit(entry.siblingLeftId, path);
+      if (entry.siblingRightId >= 0) visit(entry.siblingRightId, path);
+    };
+
+    if (dirEntries.length > 0 && dirEntries[0].childId >= 0) {
+      visit(dirEntries[0].childId, '');
+    }
+
+    return streams;
+  },
+};
+
+function concatUint8(arrays: Uint8Array[]): Uint8Array {
+  const total = arrays.reduce((s, a) => s + a.length, 0);
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const a of arrays) { out.set(a, off); off += a.length; }
+  return out;
+}

package/src/toolkit/TextKit.ts

@@ -0,0 +1,57 @@
+export const TextKit = {
+  decode(data: Uint8Array, encoding = 'utf-8'): string {
+    try {
+      return new TextDecoder(encoding, { fatal: true }).decode(data);
+    } catch {
+      return new TextDecoder('utf-8', { fatal: false }).decode(data);
+    }
+  },
+
+  encode(text: string): Uint8Array {
+    return new TextEncoder().encode(text);
+  },
+
+  escapeXml(s: string): string {
+    return s
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  },
+
+  unescapeXml(s: string): string {
+    return s
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'");
+  },
+
+  normalizeWhitespace(s: string): string {
+    return s.replace(/\s+/g, ' ').trim();
+  },
+
+  stripControl(s: string): string {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+  },
+
+  base64Encode(data: Uint8Array): string {
+    let binary = '';
+    for (let i = 0; i < data.length; i++) {
+      binary += String.fromCharCode(data[i]);
+    }
+    return btoa(binary);
+  },
+
+  base64Decode(b64: string): Uint8Array {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  },
+};

package/src/toolkit/XmlKit.ts

@@ -0,0 +1,91 @@
+import { SaxesParser } from 'saxes';
+
+// Parses XML into an xml2js-compatible object structure:
+//   { tagName: [{ _attr: { k: v }, _text: '...', childTag: [...] }] }
+function parseXmlStrict(xml: string): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const parser = new SaxesParser({ xmlns: false });
+
+    interface Frame { tag: string; obj: Record<string, unknown> }
+    const stack: Frame[] = [];
+    let result: unknown = null;
+
+    parser.on('error', (err: Error) => reject(err));
+
+    parser.on('opentag', (node: any) => {
+      const obj: Record<string, unknown> = {};
+      const attrs = node.attributes as Record<string, string>;
+      if (attrs && Object.keys(attrs).length > 0) {
+        obj['_attr'] = { ...attrs };
+      }
+      stack.push({ tag: node.name as string, obj });
+    });
+
+    const appendText = (text: string) => {
+      if (stack.length > 0 && text) {
+        const frame = stack[stack.length - 1];
+        const cur = frame.obj['_text'];
+        frame.obj['_text'] = typeof cur === 'string' ? cur + text : text;
+      }
+    };
+
+    parser.on('text', (text: string) => appendText(text));
+    parser.on('cdata', (cdata: string) => appendText(cdata));
+
+    parser.on('closetag', () => {
+      const frame = stack.pop();
+      if (!frame) return;
+      const { tag, obj } = frame;
+
+      // Drop whitespace-only _text
+      if (typeof obj['_text'] === 'string' && !(obj['_text'] as string).trim()) {
+        delete obj['_text'];
+      }
+
+      if (stack.length === 0) {
+        result = { [tag]: [obj] };
+      } else {
+        const parent = stack[stack.length - 1].obj;
+        const existing = parent[tag];
+        if (Array.isArray(existing)) {
+          (existing as unknown[]).push(obj);
+        } else {
+          parent[tag] = [obj];
+        }
+        // Track child order for document-order iteration
+        if (!parent['_childOrder']) parent['_childOrder'] = [];
+        (parent['_childOrder'] as string[]).push(tag);
+      }
+    });
+
+    try {
+      parser.write(xml).close();
+      resolve(result);
+    } catch (e) {
+      reject(e);
+    }
+  });
+}
+
+export const XmlKit = {
+  /** @deprecated Use parseStrict instead */
+  async parse(xml: string): Promise<unknown> {
+    return parseXmlStrict(xml);
+  },
+
+  async parseStrict(xml: string): Promise<unknown> {
+    return parseXmlStrict(xml);
+  },
+
+  attr(node: Record<string, unknown>, key: string): string | undefined {
+    const a = node['_attr'] as Record<string, string> | undefined;
+    return a?.[key];
+  },
+
+  text(node: Record<string, unknown> | string | undefined): string {
+    if (node == null) return '';
+    if (typeof node === 'string') return node;
+    const t = node['_text'];
+    return typeof t === 'string' ? t : '';
+  },
+};

package/src/walk/TreeWalker.ts

@@ -0,0 +1,42 @@
+import type { AnyNode, DocRoot } from '../model/doc-tree';
+
+export type WalkCallback = (node: AnyNode, parent: AnyNode | null, depth: number) => void | 'stop';
+
+export function walkNode(
+  node: AnyNode,
+  cb: WalkCallback,
+  parent: AnyNode | null = null,
+  depth = 0,
+): boolean {
+  const result = cb(node, parent, depth);
+  if (result === 'stop') return false;
+
+  if ('kids' in node && Array.isArray((node as any).kids)) {
+    for (const kid of (node as any).kids) {
+      if (!walkNode(kid as AnyNode, cb, node, depth + 1)) return false;
+    }
+  }
+  return true;
+}
+
+export class TreeWalker {
+  walk(root: DocRoot, cb: WalkCallback): void {
+    walkNode(root, cb);
+  }
+
+  findAll<T extends AnyNode>(root: DocRoot, predicate: (n: AnyNode) => n is T): T[] {
+    const results: T[] = [];
+    walkNode(root, (n) => { if (predicate(n)) results.push(n); });
+    return results;
+  }
+
+  extractText(root: DocRoot): string {
+    const parts: string[] = [];
+    walkNode(root, (n) => {
+      if (n.tag === 'txt') parts.push(n.content);
+      if (n.tag === 'br') parts.push('\n');
+      if (n.tag === 'pb') parts.push('\n\n');
+    });
+    return parts.join('');
+  }
+}

package/src/walk/tree-ops.ts

@@ -0,0 +1,26 @@
+import type { DocRoot, GridNode } from '../model/doc-tree';
+import { walkNode } from './TreeWalker';
+
+export function countNodes(root: DocRoot): Record<string, number> {
+  const counts: Record<string, number> = {};
+  walkNode(root, (n) => { counts[n.tag] = (counts[n.tag] ?? 0) + 1; });
+  return counts;
+}
+
+export function validateRoot(root: DocRoot): string[] {
+  const errors: string[] = [];
+  if (root.tag !== 'root') errors.push('Root node must have tag "root"');
+  if (!Array.isArray(root.kids)) errors.push('Root.kids must be an array');
+  if (root.kids.length === 0) errors.push('Document has no sheets');
+
+  walkNode(root, (n) => {
+    if (n.tag === 'cell' && n.kids.length === 0) {
+      errors.push('CellNode must have at least one ParaNode child');
+    }
+    if (n.tag === 'grid' && (n as GridNode).kids.length === 0) {
+      errors.push('GridNode must have at least one RowNode');
+    }
+  });
+
+  return errors;
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM"],
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}