openfig-cli 0.3.11

package/bin/commands/list-overrides.mjs

@@ -0,0 +1,66 @@
+/**
+ * list-overrides — List all editable override keys per symbol.
+ *
+ * Usage: node cli.mjs list-overrides <file.deck> [--symbol NAME|ID]
+ */
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+import { nid } from '../lib/core/node-helpers.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  if (!file) { console.error('Usage: list-overrides <file.deck>'); process.exit(1); }
+
+  const filterSym = flags.symbol || null;
+
+  const deck = file.endsWith('.fig')
+    ? FigDeck.fromFigFile(file)
+    : await FigDeck.fromDeckFile(file);
+
+  const symbols = deck.getSymbols();
+
+  for (const sym of symbols) {
+    const symId = nid(sym);
+    const symName = sym.name || '(unnamed)';
+
+    // Filter
+    if (filterSym && symName !== filterSym && symId !== filterSym) continue;
+
+    console.log(`\nSYMBOL "${symName}" (${symId})`);
+    console.log('─'.repeat(60));
+
+    // Walk children and find nodes with overrideKey
+    walkForOverrides(deck, symId, 1);
+  }
+}
+
+function walkForOverrides(deck, parentId, depth) {
+  const children = deck.getChildren(parentId);
+  for (const child of children) {
+    const id = nid(child);
+    const ok = child.overrideKey;
+
+    if (ok) {
+      const indent = '  '.repeat(depth);
+      const keyStr = `${ok.sessionID}:${ok.localID}`;
+      const type = child.type || '?';
+      const name = child.name || '';
+
+      let detail = '';
+      if (type === 'TEXT' && child.textData?.characters) {
+        const text = child.textData.characters;
+        const preview = text.length > 50 ? text.substring(0, 47) + '...' : text;
+        detail = ` → ${JSON.stringify(preview)}`;
+      } else if (type === 'ROUNDED_RECTANGLE' || type === 'RECTANGLE') {
+        const hasFill = child.fillPaints?.some(p => p.type === 'IMAGE');
+        detail = hasFill ? ' [IMAGE PLACEHOLDER]' : '';
+      } else if (type === 'INSTANCE') {
+        const sid = child.symbolData?.symbolID;
+        detail = sid ? ` sym=${sid.sessionID}:${sid.localID}` : '';
+      }
+
+      console.log(`${indent}${keyStr}  ${type} "${name}"${detail}`);
+    }
+
+    walkForOverrides(deck, id, depth + 1);
+  }
+}

package/bin/commands/list-text.mjs

@@ -0,0 +1,60 @@
+/**
+ * list-text — List all text content in the deck.
+ *
+ * Usage: node cli.mjs list-text <file.deck>
+ */
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+import { nid } from '../lib/core/node-helpers.mjs';
+import { hashToHex } from '../lib/core/image-helpers.mjs';
+
+export async function run(args) {
+  const file = args[0];
+  if (!file) { console.error('Usage: list-text <file.deck>'); process.exit(1); }
+
+  const deck = file.endsWith('.fig')
+    ? FigDeck.fromFigFile(file)
+    : await FigDeck.fromDeckFile(file);
+
+  // Direct text nodes
+  console.log('=== Direct text nodes ===\n');
+  for (const node of deck.message.nodeChanges) {
+    if (node.type === 'TEXT' && node.textData?.characters) {
+      const text = node.textData.characters;
+      const preview = text.length > 80 ? text.substring(0, 77) + '...' : text;
+      console.log(`[${nid(node)}] "${node.name || ''}" → ${JSON.stringify(preview)}`);
+    }
+  }
+
+  // Override text per slide
+  console.log('\n=== Override text (per slide instance) ===\n');
+  const slides = deck.getActiveSlides();
+
+  for (const slide of slides) {
+    const inst = deck.getSlideInstance(nid(slide));
+    if (!inst) continue;
+
+    const symId = inst.symbolData?.symbolID;
+    const symStr = symId ? `${symId.sessionID}:${symId.localID}` : '?';
+    console.log(`SLIDE "${slide.name || nid(slide)}" → INSTANCE (${nid(inst)}) sym=${symStr}`);
+
+    const overrides = inst.symbolData?.symbolOverrides || [];
+    for (const ov of overrides) {
+      const path = (ov.guidPath?.guids || [])
+        .map(g => `${g.sessionID}:${g.localID}`).join(' → ');
+
+      if (ov.textData?.characters) {
+        const text = ov.textData.characters;
+        const preview = text.length > 80 ? text.substring(0, 77) + '...' : text;
+        console.log(`  ${path}  TEXT: ${JSON.stringify(preview)}`);
+      }
+      if (ov.fillPaints?.length) {
+        const paint = ov.fillPaints[0];
+        if (paint.type === 'IMAGE' && paint.image?.hash) {
+          const hex = hashToHex(paint.image.hash);
+          console.log(`  ${path}  IMAGE: ${hex} (${paint.originalImageWidth}×${paint.originalImageHeight})`);
+        }
+      }
+    }
+    console.log('');
+  }
+}

package/bin/commands/remove-slide.mjs

@@ -0,0 +1,47 @@
+/**
+ * remove-slide — Mark slides as REMOVED.
+ *
+ * Usage: node cli.mjs remove-slide <file.deck> -o <output.deck> --slide <id|name> [--slide ...]
+ */
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+import { nid, removeNode } from '../lib/core/node-helpers.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+  const slideRefs = Array.isArray(flags.slide) ? flags.slide : (flags.slide ? [flags.slide] : []);
+
+  if (!file || !outPath || slideRefs.length === 0) {
+    console.error('Usage: remove-slide <file.deck> -o <out.deck> --slide <id|name> [--slide ...]');
+    process.exit(1);
+  }
+
+  const deck = await FigDeck.fromDeckFile(file);
+
+  let removed = 0;
+  for (const ref of slideRefs) {
+    const slide = findSlide(deck, ref);
+    if (!slide) { console.error(`Slide not found: ${ref}`); continue; }
+
+    removeNode(slide);
+    console.log(`  REMOVED slide "${slide.name || ''}" (${nid(slide)})`);
+
+    // Also remove child instances
+    for (const child of deck.getChildren(nid(slide))) {
+      removeNode(child);
+      console.log(`    REMOVED child ${child.type} (${nid(child)})`);
+    }
+    removed++;
+  }
+
+  console.log(`\nRemoved ${removed} slide(s)`);
+
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+}
+
+function findSlide(deck, ref) {
+  const byId = deck.getNode(ref);
+  if (byId?.type === 'SLIDE') return byId;
+  return deck.getActiveSlides().find(s => s.name === ref);
+}

package/bin/commands/roundtrip.mjs

@@ -0,0 +1,37 @@
+/**
+ * roundtrip — Decode and re-encode a deck with zero changes (pipeline validation).
+ *
+ * Usage: node cli.mjs roundtrip <file.deck> -o <output.deck>
+ */
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+
+  if (!file || !outPath) {
+    console.error('Usage: roundtrip <file.deck> -o <output.deck>');
+    process.exit(1);
+  }
+
+  console.log(`Reading: ${file}`);
+  const deck = await FigDeck.fromDeckFile(file);
+
+  const slides = deck.getSlides();
+  const active = deck.getActiveSlides();
+  const instances = deck.getInstances();
+  const symbols = deck.getSymbols();
+
+  console.log(`  Nodes: ${deck.message.nodeChanges.length}`);
+  console.log(`  Slides: ${active.length} active / ${slides.length} total`);
+  console.log(`  Instances: ${instances.length}`);
+  console.log(`  Symbols: ${symbols.length}`);
+  console.log(`  Blobs: ${deck.message.blobs?.length || 0}`);
+  console.log(`  Chunks: ${deck.rawFiles.length}`);
+  if (deck.deckMeta) console.log(`  Deck name: ${deck.deckMeta.file_name || '(unknown)'}`);
+
+  console.log(`\nEncoding...`);
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+  console.log(`\nRoundtrip complete. Open in Figma to verify.`);
+}

package/bin/commands/update-text.mjs

@@ -0,0 +1,79 @@
+/**
+ * update-text — Apply text overrides to an instance on a slide.
+ *
+ * Usage: node cli.mjs update-text <file.deck> -o <output.deck> --slide <id|name> --set key=value [--set key=value ...]
+ */
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+import { nid, parseId } from '../lib/core/node-helpers.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+  const slideRef = flags.slide;
+  const sets = Array.isArray(flags.set) ? flags.set : (flags.set ? [flags.set] : []);
+
+  if (!file || !outPath || !slideRef || sets.length === 0) {
+    console.error('Usage: update-text <file.deck> -o <out.deck> --slide <id|name> --set key=value [--set ...]');
+    process.exit(1);
+  }
+
+  const deck = await FigDeck.fromDeckFile(file);
+
+  // Find slide by ID or name
+  const slide = findSlide(deck, slideRef);
+  if (!slide) { console.error(`Slide not found: ${slideRef}`); process.exit(1); }
+
+  const inst = deck.getSlideInstance(nid(slide));
+  if (!inst) { console.error(`No instance found on slide ${nid(slide)}`); process.exit(1); }
+
+  // Ensure symbolOverrides exists
+  if (!inst.symbolData) inst.symbolData = {};
+  if (!inst.symbolData.symbolOverrides) inst.symbolData.symbolOverrides = [];
+
+  let updated = 0;
+  for (const pair of sets) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx < 0) { console.error(`Invalid --set format: ${pair}`); continue; }
+    const keyStr = pair.substring(0, eqIdx);
+    let value = pair.substring(eqIdx + 1);
+
+    // Empty string → space (prevents Figma crash)
+    if (value === '') value = ' ';
+
+    const key = parseId(keyStr);
+    const overrides = inst.symbolData.symbolOverrides;
+
+    // Find existing override for this key
+    const existing = overrides.find(o =>
+      o.guidPath?.guids?.length === 1 &&
+      o.guidPath.guids[0].sessionID === key.sessionID &&
+      o.guidPath.guids[0].localID === key.localID &&
+      o.textData
+    );
+
+    if (existing) {
+      existing.textData.characters = value;
+    } else {
+      overrides.push({
+        guidPath: { guids: [key] },
+        textData: { characters: value },
+      });
+    }
+    updated++;
+    console.log(`  ${keyStr} → ${JSON.stringify(value.substring(0, 60))}`);
+  }
+
+  console.log(`Updated ${updated} text override(s) on slide "${slide.name || nid(slide)}"`);
+
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+}
+
+function findSlide(deck, ref) {
+  // Try as ID first
+  const byId = deck.getNode(ref);
+  if (byId?.type === 'SLIDE') return byId;
+
+  // Try as name
+  return deck.getActiveSlides().find(s => s.name === ref);
+}

package/lib/core/deep-clone.mjs

@@ -0,0 +1,16 @@
+/**
+ * Uint8Array-safe deep clone.
+ * JSON.parse(JSON.stringify()) corrupts Uint8Array → plain objects.
+ */
+export function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (obj instanceof Uint8Array) return obj.slice();
+  if (obj instanceof ArrayBuffer) return obj.slice(0);
+  if (obj instanceof Date) return new Date(obj);
+  if (Array.isArray(obj)) return obj.map(deepClone);
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    out[key] = deepClone(obj[key]);
+  }
+  return out;
+}

package/lib/core/fig-deck.mjs

@@ -0,0 +1,332 @@
+/**
+ * FigDeck — Core class for reading, modifying, and writing Figma .deck/.fig files.
+ *
+ * FORMAT RULES (hard-won):
+ * - .deck = ZIP containing canvas.fig, thumbnail.png, meta.json, images/
+ * - canvas.fig = prelude ("fig-deck" or "fig-kiwi") + version (uint32 LE)
+ *   + length-prefixed chunks
+ * - Chunk 0 = kiwi schema (deflateRaw compressed)
+ * - Chunk 1 = message data (MUST be zstd compressed — Figma rejects deflateRaw)
+ * - Chunk 2+ = optional additional data (pass through as-is)
+ */
+import { decodeBinarySchema, compileSchema, encodeBinarySchema } from 'kiwi-schema';
+import { decompress } from 'fzstd';
+import { inflateRaw, deflateRaw } from 'pako';
+import { ZstdCodec } from 'zstd-codec';
+import archiver from 'archiver';
+import { readFileSync, createWriteStream, existsSync, mkdtempSync } from 'fs';
+import { execSync } from 'child_process';
+import { join, resolve } from 'path';
+import { tmpdir } from 'os';
+import { nid } from './node-helpers.mjs';
+
+export class FigDeck {
+  constructor() {
+    this.header = null;       // { prelude, version }
+    this.schema = null;       // decoded kiwi binary schema
+    this.compiledSchema = null;
+    this.message = null;      // decoded message { nodeChanges, blobs, ... }
+    this.rawFiles = [];       // original compressed chunks (for passthrough)
+    this.nodeMap = new Map();  // "s:l" → node
+    this.childrenMap = new Map(); // "s:l" → [child nodes]
+    this.deckMeta = null;     // parsed meta.json (when loaded from .deck)
+    this.deckThumbnail = null; // raw thumbnail PNG bytes
+    this.imagesDir = null;    // path to extracted images directory
+    this._tempDir = null;     // temp dir for deck extraction
+  }
+
+  /**
+   * Load from a .deck file (ZIP archive).
+   */
+  static async fromDeckFile(deckPath) {
+    const deck = new FigDeck();
+    const absPath = resolve(deckPath);
+
+    // Extract to temp dir
+    const tmp = mkdtempSync(join(tmpdir(), 'openfig_'));
+    execSync(`unzip -o "${absPath}" -d "${tmp}"`, { stdio: 'pipe' });
+    deck._tempDir = tmp;
+
+    // Read canvas.fig
+    const figPath = join(tmp, 'canvas.fig');
+    if (!existsSync(figPath)) {
+      throw new Error('No canvas.fig found in deck archive');
+    }
+    deck._parseFig(readFileSync(figPath));
+
+    // Read meta.json
+    const metaPath = join(tmp, 'meta.json');
+    if (existsSync(metaPath)) {
+      deck.deckMeta = JSON.parse(readFileSync(metaPath, 'utf8'));
+    }
+
+    // Read thumbnail
+    const thumbPath = join(tmp, 'thumbnail.png');
+    if (existsSync(thumbPath)) {
+      deck.deckThumbnail = readFileSync(thumbPath);
+    }
+
+    // Record images dir
+    const imgDir = join(tmp, 'images');
+    if (existsSync(imgDir)) {
+      deck.imagesDir = imgDir;
+    }
+
+    return deck;
+  }
+
+  /**
+   * Load from a raw .fig file.
+   */
+  static fromFigFile(figPath) {
+    const deck = new FigDeck();
+    deck._parseFig(readFileSync(resolve(figPath)));
+    return deck;
+  }
+
+  /**
+   * Parse a canvas.fig buffer.
+   * Format: prelude (8 bytes ASCII) + version (uint32 LE) + N×(length uint32 LE + chunk bytes)
+   * Known preludes: "fig-kiwi", "fig-deck", "fig-jam."
+   */
+  _parseFig(buf) {
+    const data = new Uint8Array(buf.buffer ?? buf);
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+
+    // Read 8-byte prelude
+    const prelude = String.fromCharCode(...data.subarray(0, 8));
+    const version = view.getUint32(8, true);
+    this.header = { prelude, version };
+
+    // Read length-prefixed chunks
+    const files = [];
+    let off = 12;
+    while (off < data.byteLength) {
+      const len = view.getUint32(off, true);
+      off += 4;
+      files.push(data.subarray(off, off + len));
+      off += len;
+    }
+    this.rawFiles = files;
+
+    // Chunk 0: schema (always deflateRaw)
+    const schemaData = inflateRaw(files[0]);
+    this.schema = decodeBinarySchema(schemaData);
+    this.compiledSchema = compileSchema(this.schema);
+
+    // Chunk 1: message (zstd or deflateRaw — auto-detect)
+    let msgData;
+    if (files[1][0] === 0x28 && files[1][1] === 0xb5 &&
+        files[1][2] === 0x2f && files[1][3] === 0xfd) {
+      msgData = decompress(files[1]); // zstd
+    } else {
+      msgData = inflateRaw(files[1]); // deflateRaw fallback
+    }
+    this.message = this.compiledSchema.decodeMessage(msgData);
+
+    this.rebuildMaps();
+  }
+
+  /**
+   * Rebuild nodeMap and childrenMap from message.nodeChanges.
+   */
+  rebuildMaps() {
+    this.nodeMap.clear();
+    this.childrenMap.clear();
+
+    for (const node of this.message.nodeChanges) {
+      const id = nid(node);
+      if (id) this.nodeMap.set(id, node);
+    }
+
+    for (const node of this.message.nodeChanges) {
+      if (!node.parentIndex?.guid) continue;
+      const pid = `${node.parentIndex.guid.sessionID}:${node.parentIndex.guid.localID}`;
+      if (!this.childrenMap.has(pid)) this.childrenMap.set(pid, []);
+      this.childrenMap.get(pid).push(node);
+    }
+  }
+
+  /** Get node by string ID "s:l" */
+  getNode(id) {
+    return this.nodeMap.get(id);
+  }
+
+  /** Get children of a node by string ID */
+  getChildren(id) {
+    return this.childrenMap.get(id) || [];
+  }
+
+  /** Get all SLIDE nodes */
+  getSlides() {
+    return this.message.nodeChanges.filter(n => n.type === 'SLIDE');
+  }
+
+  /** Get only active (non-REMOVED) slides */
+  getActiveSlides() {
+    return this.getSlides().filter(n => n.phase !== 'REMOVED');
+  }
+
+  /** Get a single active slide by 1-based index. Slide 1 is the first slide. */
+  getSlide(n) {
+    const slides = this.getActiveSlides();
+    if (n < 1 || n > slides.length) {
+      throw new RangeError(`Slide ${n} out of range (1–${slides.length})`);
+    }
+    return slides[n - 1];
+  }
+
+  /** Get user-facing CANVAS nodes (pages), sorted by position. Excludes Figma's internal canvas. */
+  getPages() {
+    return this.message.nodeChanges
+      .filter(n => n.type === 'CANVAS' && n.phase !== 'REMOVED' && n.name !== 'Internal Only Canvas')
+      .sort((a, b) => (a.parentIndex?.position ?? '').localeCompare(b.parentIndex?.position ?? ''));
+  }
+
+  /** Get a single page by 1-based index. Page 1 is the first page. */
+  getPage(n) {
+    const pages = this.getPages();
+    if (n < 1 || n > pages.length) {
+      throw new RangeError(`Page ${n} out of range (1–${pages.length})`);
+    }
+    return pages[n - 1];
+  }
+
+  /** Get all INSTANCE nodes */
+  getInstances() {
+    return this.message.nodeChanges.filter(n => n.type === 'INSTANCE');
+  }
+
+  /** Get all SYMBOL nodes */
+  getSymbols() {
+    return this.message.nodeChanges.filter(n => n.type === 'SYMBOL');
+  }
+
+  /** Find the INSTANCE child of a SLIDE */
+  getSlideInstance(slideId) {
+    const children = this.getChildren(slideId);
+    return children.find(c => c.type === 'INSTANCE');
+  }
+
+  /** Highest localID in use (for generating new IDs) */
+  maxLocalID() {
+    let max = 0;
+    for (const node of this.message.nodeChanges) {
+      if (node.guid?.localID > max) max = node.guid.localID;
+    }
+    return max;
+  }
+
+  /**
+   * DFS walk from a root node.
+   * @param {string} rootId - "s:l" format
+   * @param {Function} visitor - (node, depth) => void
+   */
+  walkTree(rootId, visitor, depth = 0) {
+    const node = this.getNode(rootId);
+    if (!node) return;
+    visitor(node, depth);
+    for (const child of this.getChildren(rootId)) {
+      this.walkTree(nid(child), visitor, depth + 1);
+    }
+  }
+
+  /**
+   * Encode message to canvas.fig binary.
+   * Returns a Promise<Uint8Array> because zstd-codec uses callbacks.
+   */
+  encodeFig() {
+    return new Promise((resolve, reject) => {
+      ZstdCodec.run(zstd => {
+        try {
+          const z = new zstd.Simple();
+
+          const encodedMsg = this.compiledSchema.encodeMessage(this.message);
+          const compSchema = deflateRaw(encodeBinarySchema(this.schema));
+          const compMsg = z.compress(encodedMsg, 3);
+
+          const prelude = this.header.prelude;
+          const chunks = [compSchema, compMsg];
+          // Pass through any additional chunks (chunk 2+)
+          for (let i = 2; i < this.rawFiles.length; i++) {
+            chunks.push(this.rawFiles[i]);
+          }
+
+          const headerSize = prelude.length + 4;
+          const totalSize = chunks.reduce((sz, c) => sz + 4 + c.byteLength, headerSize);
+          const buf = new Uint8Array(totalSize);
+          const view = new DataView(buf.buffer);
+          const enc = new TextEncoder();
+
+          let off = 0;
+          off = enc.encodeInto(prelude, buf).written;
+          view.setUint32(off, this.header.version, true);
+          off += 4;
+
+          for (const chunk of chunks) {
+            view.setUint32(off, chunk.byteLength, true);
+            off += 4;
+            buf.set(chunk, off);
+            off += chunk.byteLength;
+          }
+
+          resolve(buf);
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+  }
+
+  /**
+   * Save as a .deck (ZIP archive).
+   * @param {string} outPath - Output file path
+   * @param {object} opts - { imagesDir, thumbnail, meta }
+   */
+  async saveDeck(outPath, opts = {}) {
+    const figBuf = await this.encodeFig();
+    const absOut = resolve(outPath);
+
+    return new Promise((resolveP, reject) => {
+      const output = createWriteStream(absOut);
+      const archive = archiver('zip', { store: true });
+
+      archive.on('error', reject);
+      output.on('close', () => resolveP(archive.pointer()));
+
+      archive.pipe(output);
+
+      // canvas.fig
+      archive.append(Buffer.from(figBuf), { name: 'canvas.fig' });
+
+      // thumbnail.png
+      const thumb = opts.thumbnail || this.deckThumbnail;
+      if (thumb) {
+        archive.append(Buffer.from(thumb), { name: 'thumbnail.png' });
+      }
+
+      // meta.json
+      const meta = opts.meta || this.deckMeta;
+      if (meta) {
+        archive.append(JSON.stringify(meta), { name: 'meta.json' });
+      }
+
+      // images/
+      const imgDir = opts.imagesDir || this.imagesDir;
+      if (imgDir && existsSync(imgDir)) {
+        archive.directory(imgDir, 'images');
+      }
+
+      archive.finalize();
+    });
+  }
+
+  /**
+   * Save just the canvas.fig binary.
+   */
+  async saveFig(outPath) {
+    const buf = await this.encodeFig();
+    const { writeFileSync } = await import('fs');
+    writeFileSync(resolve(outPath), buf);
+  }
+}

package/lib/core/image-helpers.mjs

@@ -0,0 +1,56 @@
+/**
+ * Image override utilities for Figma .deck files.
+ *
+ * CRITICAL RULES:
+ * - styleIdForFill with sentinel GUID (all 0xFFFFFFFF) is REQUIRED
+ * - imageThumbnail with real thumbnail hash (~320px PNG) is REQUIRED
+ * - thumbHash must be new Uint8Array(0), NOT {}
+ */
+
+/** Convert 40-char hex SHA-1 string to Uint8Array(20). */
+export function hexToHash(hex) {
+  const arr = new Uint8Array(20);
+  for (let i = 0; i < 20; i++) {
+    arr[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return arr;
+}
+
+/** Convert Uint8Array(20) hash back to 40-char hex string. */
+export function hashToHex(arr) {
+  return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Build a complete image fill override for symbolOverrides.
+ *
+ * @param {object} key - Override key { sessionID, localID }
+ * @param {string} hash - 40-char hex SHA-1 of the full image
+ * @param {string} thumbHash - 40-char hex SHA-1 of the thumbnail image
+ * @param {number} width - Original image width
+ * @param {number} height - Original image height
+ */
+export function imageOv(key, hash, thumbHash, width, height) {
+  return {
+    styleIdForFill: { guid: { sessionID: 4294967295, localID: 4294967295 } },
+    guidPath: { guids: [key] },
+    fillPaints: [{
+      type: 'IMAGE',
+      opacity: 1,
+      visible: true,
+      blendMode: 'NORMAL',
+      transform: { m00: 1, m01: 0, m02: 0, m10: 0, m11: 1, m12: 0 },
+      image: { hash: hexToHash(hash), name: hash },
+      imageThumbnail: { hash: hexToHash(thumbHash), name: hash },
+      animationFrame: 0,
+      imageScaleMode: 'FILL',
+      imageShouldColorManage: false,
+      rotation: 0,
+      scale: 0.5,
+      originalImageWidth: width,
+      originalImageHeight: height,
+      thumbHash: new Uint8Array(0),
+      altText: '',
+    }],
+  };
+}