sdocs-dev 1.12.0 → 1.13.1

package/bin/sdocs-dev.js

@@ -31,6 +31,7 @@ const styles      = require('../lib/styles');
 const io          = require('../lib/io');
 const helpText    = require('../lib/help-text');
 const commands    = require('../lib/commands');
+const cellsVerify = require('../lib/cells-verify');
 const bridgeCommands = require('../lib/bridge-commands');
 const libraryCommands = require('../lib/library-commands');
 
@@ -46,11 +47,17 @@ function buildRouter() {
   r.register('schema',   { handler: () => { console.log(helpText.SCHEMA);        process.exit(0); } });
   r.register('charts',   { handler: () => { console.log(helpText.CHARTS_HELP);   process.exit(0); } });
   r.register('diagrams', { handler: () => { console.log(helpText.DIAGRAMS_HELP); process.exit(0); } });
-  r.register('cells',    { handler: () => { console.log(helpText.CELLS_HELP);    process.exit(0); } });
+  // `sdoc cells` prints the reference; `sdoc cells verify <file>` evaluates a
+  // document's tabs headlessly and prints the computed values (the handler
+  // calls process.exit with the 0/1/2 result code).
+  r.register('cells',    { handler: (opts) => {
+    if ((opts.file || '').toLowerCase() === 'verify') return cellsVerify.cellsVerifyCommand(opts);
+    console.log(helpText.CELLS_HELP); process.exit(0);
+  } });
   r.register('comments', { handler: () => { console.log(helpText.COMMENTS_HELP); process.exit(0); } });
 
   // Setup / refresh / auto-update.
-  r.register('setup',       { handler: async (opts) => { await setup.runSetup({ force: true, yes: !!opts.yesFlag }); process.exit(0); } });
+  r.register('setup',       { handler: async (opts) => { await setup.runSetup({ force: true, yes: !!opts.yesFlag, dryRun: !!opts.dryRunFlag }); process.exit(0); } });
   r.register('refresh',     { handler: async () => { await setup.runRefresh(); process.exit(0); } });
   r.register('auto-update', { handler: (opts) => {
     // Sub-arg lives in opts.file (positional). Accept on/off/empty.

package/lib/agent-block.js

@@ -18,8 +18,8 @@ const fs   = require('fs');
 const path = require('path');
 const { SETUP_CACHE } = require('./constants');
 
-const AGENT_BLOCK_VERSION = 10;
-const AGENT_BLOCK_REASON  = 'Documents `sdoc bridge file.md`: a live editing session for iterating on a file with the user (browser edits autosave to disk, file edits push to the page). Notes that it parks the terminal so it should run in the background, and that the browser asks for local-process / "Apps on device" permission the user must accept. Reframes plain `sdoc file.md` as the default way to open a file for comfortable reading or quick sharing. Renames the block heading from SDocs to SmallDocs, the project\'s new name and home, and spells out that "sdoc it" / "sdoc me the plan" / "make me a smalldoc" all mean: write the .md and open it with sdoc.';
+const AGENT_BLOCK_VERSION = 11;
+const AGENT_BLOCK_REASON  = 'Notes that cells blocks can be multi-tab: naming a block (```cells Expenses) builds a workbook of several sheets whose formulas reference each other across tabs (=Expenses!B4), and `sdoc cells verify file.md` computes the whole workbook headlessly so the agent can read the values back. The rest of the cells line is unchanged.';
 
 const AGENT_BLOCK_BODY = `## SmallDocs
 
@@ -48,7 +48,7 @@ Each command below prints its reference when run with no arguments - run it befo
 - \`sdoc charts\` - rendering inline charts (\`\`\`chart blocks)
 - \`sdoc diagrams\` - rendering inline Mermaid diagrams (\`\`\`mermaid blocks; has full-screen mode for zoom). Reach for this when drawing system or architectural diagrams (sequence, flow, component layout) - a diagram often communicates the shape of something faster than the equivalent prose.
 - \`sdoc slides\` - inline slide decks (\`\`\`slide / ~~~slide blocks; has full-screen presentation mode). Slides can be standalone exported as \`.pdf\` or \`.pptx\`. \`sdoc present file.md\` - open file directly in fullscreen presentation mode.
-- \`sdoc cells\` - rendering spreadsheets (\`\`\`cells blocks): CSV rows where plain values and =formulas (SUM, AVERAGE, IF, ROUND...) sit in the same grid and compute live. The reader can sort, select ranges for quick stats, edit a scratch copy fullscreen, and download the sheet as Excel (.xlsx) with the formulas still working. Reach for this when handing the user numbers they will want to check or play with - totals, budgets, projections. \`sdoc report.csv\` opens a CSV file directly as a sheet.
+- \`sdoc cells\` - rendering spreadsheets (\`\`\`cells blocks): CSV rows where plain values and =formulas (SUM, AVERAGE, IF, ROUND...) sit in the same grid and compute live. The reader can sort, select ranges for quick stats, edit a scratch copy fullscreen, and download the sheet as Excel (.xlsx) with the formulas still working. Name a block (\`\`\`cells Expenses) to build a workbook of several tabs whose formulas reference each other across sheets (\`=Expenses!B4\`); run \`sdoc cells verify file.md\` to compute the whole workbook headlessly and read the values back. Reach for this when handing the user numbers they will want to check or play with - totals, budgets, projections. \`sdoc report.csv\` opens a CSV file directly as a sheet.
 - \`sdoc schema\` - styling Markdown (fonts, colors, spacing). The default styles are already comfortable to read; reach for this only when they aren't enough - client-facing polish or a bit of fun.
 - \`sdoc feedback\` - rendering interactive elements (\`\`\`form blocks) to receive structured input from the user. Run \`sdoc feedback file.md\` and the user's submission lands as a JSON line on stdout. Good for eliciting complex/subtle feedback. All standard interactive HTML elements with prefilled (but editable) content of your choosing.
 `;

package/lib/cells-transclude.js

@@ -22,9 +22,11 @@
 const fs = require('fs');
 const path = require('path');
 
-// A ```cells fenced block (captures leading boundary + body). Tilde fences and
-// inline-data blocks are left untouched.
-const CELLS_BLOCK = /(^|\n)```cells[ \t]*\n([\s\S]*?)\n```/g;
+// A ```cells fenced block (captures leading boundary, optional fence name, and
+// body). The name (```cells Sales) is preserved on the baked block so a tab
+// loaded from a CSV keeps its identity. Tilde fences and inline-data blocks are
+// left untouched.
+const CELLS_BLOCK = /(^|\n)```cells[ \t]*([^\n]*)\n([\s\S]*?)\n```/g;
 const REFERENCE = /^\{\{\s*([^}]+?)\s*\}\}$/;
 // A trailing :range suffix like :B5:J32 or :B5 (a view hint; data is baked in
 // whole regardless, so we just strip it off the path for now).
@@ -34,12 +36,13 @@ function directiveValue(s) {
   return /\s|"/.test(s) ? JSON.stringify(s) : s;
 }
 
-function bakeBlock(boundary, ref, baseDir, readFile, preLines) {
+function bakeBlock(boundary, name, ref, baseDir, readFile, preLines) {
   var range = '';
   var filePath = ref;
   var rm = ref.match(RANGE_SUFFIX);
   if (rm) { range = rm[1]; filePath = ref.slice(0, ref.length - rm[0].length); }
 
+  var fence = '```cells' + (name ? ' ' + name : '');
   var base = path.basename(filePath);
   // Author format: lines (e.g. `format: B=$`) sit before the reference and are
   // preserved verbatim above the baked data.
@@ -48,13 +51,13 @@ function bakeBlock(boundary, ref, baseDir, readFile, preLines) {
   try {
     csv = readFile(path.resolve(baseDir, filePath));
   } catch (e) {
-    return boundary + '```cells\n' + head + 'sdoc-cells: error=' +
+    return boundary + fence + '\n' + head + 'sdoc-cells: error=' +
       directiveValue('Could not read ' + base) + '\n```';
   }
   csv = String(csv).replace(/\s+$/, '');
   var directive = 'sdoc-cells: source=' + directiveValue(base) +
     (range ? ' range=' + range : '');
-  return boundary + '```cells\n' + head + directive + '\n' + csv + '\n```';
+  return boundary + fence + '\n' + head + directive + '\n' + csv + '\n```';
 }
 
 // Replace every {{file.csv}} cells block in `content` with the baked data.
@@ -62,7 +65,7 @@ function bakeBlock(boundary, ref, baseDir, readFile, preLines) {
 function transcludeCells(content, baseDir, readFile) {
   if (typeof content !== 'string' || content.indexOf('```cells') === -1) return content;
   var read = readFile || function (p) { return fs.readFileSync(p, 'utf-8'); };
-  return content.replace(CELLS_BLOCK, function (whole, boundary, body) {
+  return content.replace(CELLS_BLOCK, function (whole, boundary, name, body) {
     // Peel any leading author `format:` lines, then require a sole {{ref}}.
     var lines = body.split('\n');
     var pre = [];
@@ -71,7 +74,7 @@ function transcludeCells(content, baseDir, readFile) {
     var rest = lines.slice(i).join('\n').trim();
     var m = rest.match(REFERENCE);
     if (!m) return whole;                    // inline data - leave alone
-    return bakeBlock(boundary, m[1], baseDir, read, pre);
+    return bakeBlock(boundary, (name || '').trim(), m[1], baseDir, read, pre);
   });
 }
 

package/lib/cells-verify.js

@@ -0,0 +1,165 @@
+// cells-verify.js - headless evaluation of a document's ```cells tabs.
+//
+// `sdoc cells verify <file.md>` parses every ```cells block, names the tabs
+// exactly as the browser does, recalculates them together as one workbook
+// (so cross-tab references like Sales!A1 resolve), and prints the COMPUTED
+// values. It is the agent's feedback loop: write formulas, run this, read the
+// numbers back - no browser, same engine the page runs (cli/shared/), so what
+// it prints is what ships.
+//
+// Output:
+//   default   CSV per tab, each under a "# sheet: <name>" banner. Human view;
+//             a data row could itself start with "# sheet:", so this form is
+//             documented as not machine-round-trippable - agents use --json.
+//   --json    { ok, sheets:[{name, values:[[...]]}], errors:[{sheet,cell,code}] }
+//   --sheet N only that tab (case-insensitive). Absent name -> exit 2.
+//
+// Exit: 0 = no cell errors in the emitted tabs; 1 = at least one cell error
+// (#REF!/#CIRC!/#DIV0!/...); 2 = bad usage (no file, --sheet names no tab).
+
+const path = require('path');
+const io = require('./io');
+const CELLS = require('../shared/sdocs-cells.js');
+const FX = require('../shared/sdocs-cells-formula.js');
+
+// Scan ```cells (or ~~~cells) fenced blocks, capturing the fence info string
+// as the tab name and the block body. Approximate vs marked (no nested-fence
+// awareness) but matches how agents author docs. The closing fence must be the
+// same run of fence characters (backreference) at a line start.
+function scanCellsBlocks(md) {
+  var re = /(?:^|\n)(```+|~~~+)cells[ \t]*([^\n]*)\n([\s\S]*?)\n\1[ \t]*(?=\n|$)/g;
+  var blocks = [];
+  var m;
+  while ((m = re.exec(md))) {
+    blocks.push({ name: (m[2] || '').trim().replace(/"/g, ''), body: m[3] });
+  }
+  return blocks;
+}
+
+// Parse + name every block into a workbook, mirroring the renderer: a fence
+// name wins, then an explicit `name=` directive, then auto Sheet1/Sheet2... by
+// order among the blocks that became real grids. Non-grid blocks (empty /
+// unresolved) are skipped; a parse error is recorded so the exit code reflects it.
+function buildWorkbook(md) {
+  var blocks = scanCellsBlocks(md);
+  var sheets = [];   // { name, model }
+  var parseErrors = [];
+  var autoIdx = 0;
+  for (var i = 0; i < blocks.length; i++) {
+    var model;
+    try { model = CELLS.parseCells(blocks[i].body); }
+    catch (e) { parseErrors.push((e && e.message) || 'parse error'); continue; }
+    if (model.error) { parseErrors.push(model.error); continue; }
+    if (model.unresolved || model.empty) continue;
+    var name = blocks[i].name || (model.name && String(model.name).trim()) || ('Sheet' + (++autoIdx));
+    sheets.push({ name: name, model: model });
+  }
+  return { sheets: sheets, parseErrors: parseErrors };
+}
+
+// Render one sheet's computed grid to a 2D array of display strings: a formula
+// cell shows its result (number, or the error code), every other cell shows its
+// literal text verbatim. fxGrid is this sheet's recalcWorkbook results.
+function valuesFor(model, fxGrid) {
+  var out = [];
+  for (var r = 0; r < model.cells.length; r++) {
+    var line = model.cells[r];
+    var row = [];
+    for (var c = 0; c < line.length; c++) {
+      var cell = line[c];
+      if (FX.isFormula(cell.raw)) {
+        var fx = (fxGrid[r] && fxGrid[r][c]) || { kind: 'empty' };
+        if (fx.kind === 'number') row.push(String(fx.value));
+        else if (fx.kind === 'error') row.push(fx.code);
+        else if (fx.kind === 'text') row.push(String(fx.value));
+        else row.push('');
+      } else {
+        row.push(cell.raw);
+      }
+    }
+    out.push(row);
+  }
+  return out;
+}
+
+// Collect cell errors across a sheet for the exit code + --json errors list.
+function errorsFor(name, model, fxGrid) {
+  var errs = [];
+  for (var r = 0; r < fxGrid.length; r++) {
+    var line = fxGrid[r] || [];
+    for (var c = 0; c < line.length; c++) {
+      var fx = line[c];
+      if (fx && fx.kind === 'error') {
+        errs.push({ sheet: name, cell: CELLS.colName(c) + (r + 1), code: fx.code });
+      }
+    }
+  }
+  return errs;
+}
+
+async function cellsVerifyCommand(opts) {
+  var file = opts.extra;   // `sdoc cells verify <file>` -> file lands in extra
+  if (!file) {
+    console.error('sdoc: cells verify needs a file - usage: sdoc cells verify <file.md> [--json] [--sheet <name>]');
+    process.exit(2);
+  }
+
+  var content = await io.readContent(file);   // same baking the browser receives
+  if (content == null) {
+    console.error('sdoc: nothing to read from ' + file);
+    process.exit(2);
+  }
+
+  var wb = buildWorkbook(content);
+  var fxGrids = FX.recalcWorkbook(wb.sheets.map(function (s) {
+    return { name: s.name, model: s.model };
+  }));
+
+  // Build the per-sheet view once; --sheet filters it afterwards.
+  var rendered = wb.sheets.map(function (s, i) {
+    return {
+      name: s.name,
+      values: valuesFor(s.model, fxGrids[i] || []),
+      errors: errorsFor(s.name, s.model, fxGrids[i] || []),
+    };
+  });
+
+  if (opts.sheetName) {
+    var want = String(opts.sheetName).toLowerCase();
+    var only = rendered.filter(function (r) { return r.name.toLowerCase() === want; });
+    if (!only.length) {
+      console.error('sdoc: no tab named "' + opts.sheetName + '" in ' + file);
+      process.exit(2);
+    }
+    rendered = only;
+  }
+
+  var allErrors = [];
+  rendered.forEach(function (r) { allErrors = allErrors.concat(r.errors); });
+  var ok = allErrors.length === 0 && wb.parseErrors.length === 0;
+
+  if (opts.jsonFlag) {
+    process.stdout.write(JSON.stringify({
+      ok: ok,
+      sheets: rendered.map(function (r) { return { name: r.name, values: r.values }; }),
+      errors: allErrors,
+      parseErrors: wb.parseErrors,
+    }, null, 2) + '\n');
+  } else {
+    if (!rendered.length) console.error('sdoc: no cells tabs found in ' + file);
+    var chunks = rendered.map(function (r) {
+      return '# sheet: ' + r.name + '\n' + CELLS.serializeCsv(r.values);
+    });
+    if (chunks.length) process.stdout.write(chunks.join('\n') + '\n');
+    wb.parseErrors.forEach(function (e) { console.error('sdoc: cells parse error - ' + e); });
+  }
+
+  process.exit(ok ? 0 : 1);
+}
+
+module.exports = {
+  cellsVerifyCommand: cellsVerifyCommand,
+  scanCellsBlocks: scanCellsBlocks,
+  buildWorkbook: buildWorkbook,
+  valuesFor: valuesFor,
+};

package/lib/help-text.js

@@ -1011,6 +1011,59 @@ FORMULAS
   name), #REF! (bad range), #VALUE! (e.g. text in arithmetic), #CIRC! (a
   circular reference). Formulas recalculate live while you edit.
 
+MULTIPLE TABS (SHEETS)
+  A document can hold several tabs that work together. Each tab is its own
+  \`\`\`cells block; name it in the fence, right after the word cells:
+
+  \`\`\`cells Expenses
+  Category,Jan,Feb,Mar
+  Rent,1200,1200,1200
+  Food,350,400,380
+  Total,=SUM(B2:B3),=SUM(C2:C3),=SUM(D2:D3)
+  \`\`\`
+
+  \`\`\`cells Summary
+  Metric,Value
+  Grand Total,=SUM(Expenses!B4:D4)
+  \`\`\`
+
+  A formula reads another tab with a Sheet!A1 reference: =Expenses!B4 reads
+  cell B4 of the Expenses tab, =SUM(Expenses!B4:D4) sums a range on it. A
+  bare reference (=B4) always means the current tab. Names are
+  case-insensitive; an unnamed block is Sheet1, Sheet2... by order; if two
+  tabs share a name the first one owns it for references.
+
+  Qualified ranges stay within one tab (Expenses!A1:C1). A range that names
+  two different tabs, a reference to a tab that does not exist, and a cycle
+  that runs between tabs are all reported as errors (#REF! / #CIRC!), never a
+  wrong number or a hang.
+
+  Two ways to view the tabs:
+    - Stacked (default): each tab renders where its block sits, named by a
+      small caption - good for a document with prose between the tabs.
+    - One pane (opt in): expanding ANY tab opens the whole workbook in one
+      window with a tab strip to switch sheets. For an in-document tabbed
+      pane, add  cells-tabs: tabbed  to the document's front matter and the
+      tabs collapse into a single widget (a tab strip + one grid at a time),
+      placed where the first tab sat.
+
+VERIFYING (for agents)
+  Check the computed values without a browser:
+
+    sdoc cells verify <file.md>            # values of every tab as CSV
+    sdoc cells verify <file.md> --json     # structured, lossless
+    sdoc cells verify <file.md> --sheet Summary   # one tab only
+
+  It runs the SAME engine the page does, so the numbers it prints are the
+  numbers the document will show. Formula cells print their result; an
+  errored cell prints its code (#REF! etc.) in place. The exit code is 0 when
+  every tab computes cleanly and 1 when any cell errors, so an agent can gate
+  on it. Write formulas, run verify, read the values back, fix, repeat.
+
+  The default output banners each tab with "# sheet: <name>". A data row
+  could itself start with that text, so for machine parsing use --json (its
+  per-tab values array is unambiguous).
+
 SORTING
   Hover a column letter: an arrow appears on its right showing what a click
   will do (up = sort ascending, down = descending, x = clear the sort). The

package/lib/io.js

@@ -43,6 +43,8 @@ function parseArgs(argv) {
   let tagsFlag = false;
   let helpFlag = false;
   let yesFlag = false;
+  let dryRunFlag = false;
+  let sheetName = null;
   const addTags = [];
 
   for (let i = 0; i < args.length; i++) {
@@ -93,6 +95,8 @@ function parseArgs(argv) {
     if (arg === '--log-file')                        { logFile          = args[++i]; continue; }
     if (arg === '--tags')                            { tagsFlag         = true; continue; }
     if (arg === '--yes' || arg === '-y')             { yesFlag          = true; continue; }
+    if (arg === '--dry-run')                         { dryRunFlag       = true; continue; }
+    if (arg === '--sheet')                           { sheetName        = args[++i]; continue; }
 
     if (!subcommand && SUBCOMMANDS.has(arg)) {
       subcommand = arg;
@@ -115,7 +119,7 @@ function parseArgs(argv) {
     resetFlag, shortFlag, jsonFlag, auditFlag, waitFlag,
     messageText, connectTimeoutS, idleTimeoutS, reconnectGraceMs,
     keepOpenFlag, logFile,
-    tagsFlag, helpFlag, yesFlag,
+    tagsFlag, helpFlag, yesFlag, dryRunFlag, sheetName,
     addTags,
   };
 }

package/lib/library-index.js

@@ -22,8 +22,13 @@ const MAX_EXCERPT = 400;
 
 function deriveTitle(meta, body) {
   if (meta && typeof meta.title === 'string' && meta.title.trim()) return meta.title.trim();
-  const m = (body || '').match(/^#\s+(.+?)\s*$/m);
-  if (m) return m[1];
+  const lines = (body || '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].trim()) continue;
+    const m = lines[i].match(/^#\s+(.+?)\s*$/);
+    if (m) return m[1];
+    break;
+  }
   return null;
 }
 

package/lib/setup.js

@@ -3,7 +3,8 @@
 // versions ship.
 //
 // runSetup: first-run interactive flow. Detects agent configs, writes
-//   the block into the ones the user agrees to.
+//   the block into the ones the user agrees to. Pass dryRun:true to
+//   preview what would be written without touching any file or state.
 // runRefresh: unconditional refresh of every agent file that already
 //   has a recognised block.
 // runAutoUpdateSubcommand: flips state.autoInstallUpdates.
@@ -17,6 +18,7 @@ const readline = require('readline');
 const {
   AGENT_BLOCK_VERSION,
   AGENT_BLOCK_BODY,
+  formatAgentBlock,
   compareVersions,
   readSetupState,
   writeSetupState,
@@ -69,7 +71,7 @@ async function askAutoRefreshConsent() {
   return !a || a === 'y' || a === 'yes';
 }
 
-async function runSetup({ force = false, yes = false } = {}) {
+async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
   if (!force) {
     if (!process.stdout.isTTY || !process.stdin.isTTY) return;
     if (process.env.CI || process.env.SDOCS_NO_SETUP) return;
@@ -84,6 +86,23 @@ async function runSetup({ force = false, yes = false } = {}) {
   // any number of times and the result is a current block in every detected
   // config, or a clean "nothing to do".
   if (yes) {
+    // ── --dry-run (preview only) path ─────────────────────────────────────
+    // Prints each file path and the block that would be written, then exits
+    // without touching any file or mutating setup state. Must return before
+    // the write steps below.
+    if (dryRun) {
+      const toWrite = detectAgents().filter(t => !fileHasBlock(t.filePath));
+      if (toWrite.length === 0) {
+        console.log('All SDocs agent blocks already at current version. Nothing to do.');
+        return;
+      }
+      for (const t of toWrite) {
+        console.log(`--- ${t.filePath} ---`);
+        console.log(formatAgentBlock(AGENT_BLOCK_VERSION, AGENT_BLOCK_BODY));
+      }
+      return;
+    }
+
     // Step 1: refresh any existing outdated / legacy blocks. This is what
     // closes the gap where re-running setup --yes used to silently no-op
     // on a stale install.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs-dev",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Open, share, and style markdown files from the terminal",
   "main": "bin/sdocs-dev.js",
   "bin": {

package/shared/sdocs-cells-formula.js

@@ -0,0 +1,485 @@
+// sdocs-cells-formula.js - a small spreadsheet formula engine.
+//
+// Pure, dependency-free, shared between the browser (window.SDocCellsFormula)
+// and Node tests (module.exports) via the UMD pattern used by the other cells
+// modules. It evaluates a single cell's formula string (anything whose raw
+// text starts with "=") against a grid of other cells, and recalc() resolves
+// a whole model at once with cycle detection.
+//
+// Supported, deliberately small but useful:
+//   numbers            12, 3.5, -2, 1e3
+//   operators          + - * / ^ %  and unary minus, with parentheses
+//   cell references    A1, B12  (column letters + 1-based row, like the UI)
+//   ranges             A1:B3    (only inside a function's arguments)
+//   functions          SUM AVERAGE/AVG MIN MAX COUNT COUNTA PRODUCT
+//                      ROUND ABS IF
+//   comparisons        = <> < <= > >=   (mainly for IF)
+//
+// Values: a referenced empty cell is 0 in arithmetic; referenced text is an
+// error (#VALUE!) in arithmetic but is counted by COUNTA and ignored by SUM.
+// Anything that goes wrong yields an error string (#VALUE!, #DIV/0!, #NAME?,
+// #REF!, #CIRC!) which the renderer shows in the cell, just like a real sheet.
+(function (exports) {
+  'use strict';
+
+  // Column letters -> 0-based index (mirror sdocs-cells.js so refs line up).
+  function colIndex(letters) {
+    var n = 0;
+    for (var i = 0; i < letters.length; i++) {
+      n = n * 26 + (letters.charCodeAt(i) - 64); // 'A' = 65 -> 1
+    }
+    return n - 1;
+  }
+
+  // 0-based index -> column letters (inverse of colIndex): 0 -> A, 26 -> AA.
+  function colName(index) {
+    var name = '';
+    var n = index + 1;
+    while (n > 0) {
+      var rem = (n - 1) % 26;
+      name = String.fromCharCode(65 + rem) + name;
+      n = Math.floor((n - 1) / 26);
+    }
+    return name;
+  }
+
+  function isFormula(raw) {
+    return typeof raw === 'string' && raw.charAt(0) === '=' && raw.length > 1;
+  }
+
+  function mkErr(code) { var e = new Error(code); e.isFormulaError = true; e.code = code; return e; }
+
+  // ── Tokenizer ────────────────────────────────────────────
+  function tokenize(src) {
+    var toks = [];
+    var i = 0, n = src.length;
+    function isDigit(c) { return c >= '0' && c <= '9'; }
+    function isAlpha(c) { return (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z'); }
+    while (i < n) {
+      var c = src[i];
+      if (c === ' ' || c === '\t') { i++; continue; }
+      if (isDigit(c) || (c === '.' && isDigit(src[i + 1]))) {
+        var num = '';
+        while (i < n && (isDigit(src[i]) || src[i] === '.')) num += src[i++];
+        if (i < n && (src[i] === 'e' || src[i] === 'E')) {
+          num += src[i++];
+          if (src[i] === '+' || src[i] === '-') num += src[i++];
+          while (i < n && isDigit(src[i])) num += src[i++];
+        }
+        toks.push({ t: 'num', v: parseFloat(num) });
+        continue;
+      }
+      if (isAlpha(c)) {
+        var word = '';
+        while (i < n && (isAlpha(src[i]) || isDigit(src[i]))) word += src[i++];
+        // A sheet-qualified reference: Sheet!A1. The word before '!' is the
+        // sheet name (any letters/digits run - Sales, Summary, Sheet1, Q1);
+        // the part after '!' must be a plain cell ref. Emitted as ONE ref
+        // token carrying `sheet`, so the parser's range branch (the next ':'
+        // check) keeps the sheet on the qualified endpoint.
+        if (src[i] === '!') {
+          var sheet = word;
+          i++; // consume '!'
+          var cellWord = '';
+          while (i < n && (isAlpha(src[i]) || isDigit(src[i]))) cellWord += src[i++];
+          var cm = /^([A-Za-z]+)([0-9]+)$/.exec(cellWord);
+          if (!cm) throw mkErr('#REF!');
+          toks.push({ t: 'ref', sheet: sheet, col: colIndex(cm[1].toUpperCase()), row: parseInt(cm[2], 10) - 1 });
+          continue;
+        }
+        var m = /^([A-Za-z]+)([0-9]+)$/.exec(word);
+        if (m && src[i] !== '(') {
+          toks.push({ t: 'ref', col: colIndex(m[1].toUpperCase()), row: parseInt(m[2], 10) - 1 });
+        } else {
+          toks.push({ t: 'name', v: word.toUpperCase() });
+        }
+        continue;
+      }
+      if (c === '<' || c === '>') {
+        var op = c; i++;
+        if (src[i] === '=' || (c === '<' && src[i] === '>')) op += src[i++];
+        toks.push({ t: 'op', v: op });
+        continue;
+      }
+      if ('+-*/^%(),:='.indexOf(c) !== -1) { toks.push({ t: 'op', v: c }); i++; continue; }
+      // A literal #REF! (left behind by shiftFormula when a reference was
+      // pushed off the sheet) evaluates to that error.
+      if (c === '#') throw mkErr(src.slice(i, i + 5).toUpperCase() === '#REF!' ? '#REF!' : '#NAME?');
+      throw mkErr('#NAME?');
+    }
+    return toks;
+  }
+
+  // ── Recursive-descent parser -> AST ──────────────────────
+  function parse(toks) {
+    var pos = 0;
+    function peek() { return toks[pos]; }
+    function next() { return toks[pos++]; }
+    function expectOp(v) { var t = next(); if (!t || t.t !== 'op' || t.v !== v) throw mkErr('#VALUE!'); }
+
+    function parseCompare() {
+      var left = parseAdd();
+      var t = peek();
+      if (t && t.t === 'op' && ['=', '<>', '<', '<=', '>', '>='].indexOf(t.v) !== -1) {
+        next();
+        return { k: 'cmp', op: t.v, a: left, b: parseAdd() };
+      }
+      return left;
+    }
+    function parseAdd() {
+      var node = parseMul();
+      while (peek() && peek().t === 'op' && (peek().v === '+' || peek().v === '-')) {
+        var op = next().v; node = { k: 'bin', op: op, a: node, b: parseMul() };
+      }
+      return node;
+    }
+    function parseMul() {
+      var node = parsePow();
+      while (peek() && peek().t === 'op' && (peek().v === '*' || peek().v === '/')) {
+        var op = next().v; node = { k: 'bin', op: op, a: node, b: parsePow() };
+      }
+      return node;
+    }
+    function parsePow() {
+      var node = parseUnary();
+      if (peek() && peek().t === 'op' && peek().v === '^') {
+        next(); return { k: 'bin', op: '^', a: node, b: parsePow() };
+      }
+      return node;
+    }
+    function parseUnary() {
+      var t = peek();
+      if (t && t.t === 'op' && (t.v === '-' || t.v === '+')) {
+        next(); return { k: 'unary', op: t.v, a: parseUnary() };
+      }
+      return parsePostfix();
+    }
+    function parsePostfix() {
+      var node = parsePrimary();
+      if (peek() && peek().t === 'op' && peek().v === '%') { next(); node = { k: 'percent', a: node }; }
+      return node;
+    }
+    function parsePrimary() {
+      var t = next();
+      if (!t) throw mkErr('#VALUE!');
+      if (t.t === 'num') return { k: 'num', v: t.v };
+      if (t.t === 'ref') {
+        if (peek() && peek().t === 'op' && peek().v === ':') {
+          next(); var end = next();
+          if (!end || end.t !== 'ref') throw mkErr('#REF!');
+          // A range stays within one sheet. A qualified start (Sales!A1:B3)
+          // applies its sheet to both ends; a range that names two different
+          // sheets (Sheet1!A1:Sheet2!B2) has no coherent rectangle -> #REF!.
+          var startKey = (t.sheet || '').toLowerCase();
+          var endKey = (end.sheet || '').toLowerCase();
+          if (end.sheet != null && endKey !== startKey) throw mkErr('#REF!');
+          return { k: 'range', sheet: t.sheet, c0: t.col, r0: t.row, c1: end.col, r1: end.row };
+        }
+        return { k: 'ref', col: t.col, row: t.row, sheet: t.sheet };
+      }
+      if (t.t === 'name') {
+        if (peek() && peek().t === 'op' && peek().v === '(') {
+          next();
+          var args = [];
+          if (!(peek() && peek().t === 'op' && peek().v === ')')) {
+            args.push(parseCompare());
+            while (peek() && peek().t === 'op' && peek().v === ',') { next(); args.push(parseCompare()); }
+          }
+          expectOp(')');
+          return { k: 'call', name: t.v, args: args };
+        }
+        if (t.v === 'TRUE') return { k: 'num', v: 1 };
+        if (t.v === 'FALSE') return { k: 'num', v: 0 };
+        throw mkErr('#NAME?');
+      }
+      if (t.t === 'op' && t.v === '(') { var e = parseCompare(); expectOp(')'); return e; }
+      throw mkErr('#VALUE!');
+    }
+
+    var ast = parseCompare();
+    if (pos !== toks.length) throw mkErr('#VALUE!');
+    return ast;
+  }
+
+  // ── Evaluator ────────────────────────────────────────────
+  function evalAst(node, ctx) {
+    switch (node.k) {
+      case 'num': return node.v;
+      case 'unary': { var v = num(evalAst(node.a, ctx)); return node.op === '-' ? -v : v; }
+      case 'percent': return num(evalAst(node.a, ctx)) / 100;
+      case 'bin': {
+        var a = num(evalAst(node.a, ctx)), b = num(evalAst(node.b, ctx));
+        switch (node.op) {
+          case '+': return a + b;
+          case '-': return a - b;
+          case '*': return a * b;
+          case '/': if (b === 0) throw mkErr('#DIV/0!'); return a / b;
+          case '^': return Math.pow(a, b);
+        }
+        throw mkErr('#VALUE!');
+      }
+      case 'cmp': {
+        var x = num(evalAst(node.a, ctx)), y = num(evalAst(node.b, ctx)), r;
+        switch (node.op) {
+          case '=': r = x === y; break;
+          case '<>': r = x !== y; break;
+          case '<': r = x < y; break;
+          case '<=': r = x <= y; break;
+          case '>': r = x > y; break;
+          case '>=': r = x >= y; break;
+          default: throw mkErr('#VALUE!');
+        }
+        return r ? 1 : 0;
+      }
+      case 'ref': return refValue(ctx.cell(node.col, node.row, node.sheet));
+      case 'range': throw mkErr('#VALUE!');
+      case 'call': return callFn(node, ctx);
+    }
+    throw mkErr('#VALUE!');
+  }
+
+  function refValue(cell) {
+    if (!cell || cell.kind === 'empty') return 0;
+    if (cell.kind === 'number') return cell.value;
+    if (cell.kind === 'error') throw mkErr(cell.code || '#VALUE!');
+    throw mkErr('#VALUE!');
+  }
+
+  function num(v) { if (typeof v !== 'number' || !isFinite(v)) throw mkErr('#VALUE!'); return v; }
+
+  function argCells(arg, ctx) {
+    if (arg.k === 'range') {
+      var out = [];
+      var r0 = Math.min(arg.r0, arg.r1), r1 = Math.max(arg.r0, arg.r1);
+      var c0 = Math.min(arg.c0, arg.c1), c1 = Math.max(arg.c0, arg.c1);
+      for (var r = r0; r <= r1; r++) {
+        for (var c = c0; c <= c1; c++) out.push(ctx.cell(c, r, arg.sheet));
+      }
+      return out;
+    }
+    return [{ kind: 'number', value: num(evalAst(arg, ctx)) }];
+  }
+
+  function callFn(node, ctx) {
+    var name = node.name, args = node.args;
+    switch (name) {
+      case 'SUM': case 'PRODUCT': case 'MIN': case 'MAX':
+      case 'AVERAGE': case 'AVG': case 'COUNT': case 'COUNTA': {
+        var nums = [], counted = 0, errored = null;
+        for (var i = 0; i < args.length; i++) {
+          var cells = argCells(args[i], ctx);
+          for (var j = 0; j < cells.length; j++) {
+            var cl = cells[j];
+            if (cl.kind === 'error') { errored = cl.code || '#VALUE!'; }
+            else if (cl.kind === 'number') { nums.push(cl.value); counted++; }
+            else if (cl.kind === 'text') { counted++; }
+          }
+        }
+        if (errored && name !== 'COUNTA') throw mkErr(errored);
+        if (name === 'COUNT') return nums.length;
+        if (name === 'COUNTA') return counted;
+        if (!nums.length) {
+          if (name === 'SUM') return 0;
+          if (name === 'PRODUCT') return 0;
+          throw mkErr('#DIV/0!');
+        }
+        if (name === 'SUM') return nums.reduce(function (a, b) { return a + b; }, 0);
+        if (name === 'PRODUCT') return nums.reduce(function (a, b) { return a * b; }, 1);
+        if (name === 'MIN') return Math.min.apply(null, nums);
+        if (name === 'MAX') return Math.max.apply(null, nums);
+        return nums.reduce(function (a, b) { return a + b; }, 0) / nums.length; // AVERAGE
+      }
+      case 'ROUND': {
+        if (args.length < 1) throw mkErr('#VALUE!');
+        var x = num(evalAst(args[0], ctx));
+        var d = args.length > 1 ? num(evalAst(args[1], ctx)) : 0;
+        var f = Math.pow(10, d);
+        return Math.round(x * f) / f;
+      }
+      case 'ABS':
+        if (args.length !== 1) throw mkErr('#VALUE!');
+        return Math.abs(num(evalAst(args[0], ctx)));
+      case 'IF': {
+        if (args.length < 2) throw mkErr('#VALUE!');
+        var cond = num(evalAst(args[0], ctx));
+        return cond !== 0 ? evalAst(args[1], ctx)
+          : (args.length > 2 ? evalAst(args[2], ctx) : 0);
+      }
+    }
+    throw mkErr('#NAME?');
+  }
+
+  // ── Relative reference shifting (fill handle / copy-paste) ──
+  // Rewrite every cell reference in a formula by (dr, dc) rows/columns:
+  // shiftFormula('=B2*C2', 1, 0) -> '=B3*C3'. Function names (SUM, IF...) are
+  // left alone - a word is only a reference when it is letters+digits and not
+  // followed by '('. A reference pushed past row 1 / column A becomes the
+  // literal #REF!, which evaluates to a #REF! error. Non-formula strings pass
+  // through unchanged.
+  function shiftFormula(formula, dr, dc) {
+    if (!isFormula(formula)) return formula;
+    var src = formula.slice(1);
+    var out = '';
+    var i = 0, n = src.length;
+    function isAlpha(ch) { return (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z'); }
+    function isDigit(ch) { return ch >= '0' && ch <= '9'; }
+    while (i < n) {
+      var c = src[i];
+      if (isAlpha(c)) {
+        var j = i;
+        while (j < n && (isAlpha(src[j]) || isDigit(src[j]))) j++;
+        var word = src.slice(i, j);
+        // A sheet qualifier (Sheet!A1) - emit the name + '!' untouched and let
+        // the next iteration shift the cell ref that follows. Without this a
+        // numeric-suffixed sheet name (Q1, Sheet1) would be shifted as if it
+        // were a cell reference.
+        if (src[j] === '!') {
+          out += word + '!';
+          i = j + 1;
+          continue;
+        }
+        var m = /^([A-Za-z]+)([0-9]+)$/.exec(word);
+        if (m && src[j] !== '(') {
+          var col = colIndex(m[1].toUpperCase()) + dc;
+          var row = parseInt(m[2], 10) - 1 + dr;
+          out += (col < 0 || row < 0) ? '#REF!' : colName(col) + (row + 1);
+        } else {
+          out += word;
+        }
+        i = j;
+        continue;
+      }
+      out += c;
+      i++;
+    }
+    return '=' + out;
+  }
+
+  // Evaluate one formula string against ctx. Returns { value } or { error }.
+  function evaluate(formula, ctx) {
+    try {
+      var src = formula.charAt(0) === '=' ? formula.slice(1) : formula;
+      var ast = parse(tokenize(src));
+      var v = evalAst(ast, ctx);
+      if (typeof v !== 'number' || !isFinite(v)) return { error: '#VALUE!' };
+      return { value: v };
+    } catch (e) {
+      return { error: e && e.isFormulaError ? e.code : '#VALUE!' };
+    }
+  }
+
+  // ── Whole-workbook recalc with cross-sheet cycle detection ──
+  //
+  // recalcWorkbook resolves a list of sheets at once so a formula in one
+  // sheet can read a cell in another via a qualified reference (Sheet!A1).
+  // One shared memo (`results`/`state`) is keyed by (sheetIndex, r, c): the
+  // in-progress guard that catches A1->A1 within a sheet then also catches a
+  // cycle that spans sheets. The cycle detector never learns about sheets,
+  // it just gets a wider address space.
+  //
+  //   sheets: [{ name, model }, ...]   name optional; '' for an anonymous
+  //                                    single sheet (see recalc below).
+  //
+  // Returns one results grid per sheet, same shape and order as the input:
+  //   [ results0, results1, ... ]   resultsN[r][c] = {kind, value/code}
+  //
+  // Sheet names resolve to a stable index up front (case-insensitive; on a
+  // name collision the FIRST sheet with that name wins). A qualified ref to a
+  // name that does not exist is reported as #REF! by the ctx and never enters
+  // resolve - so a missing sheet can neither hang nor bypass the cycle guard.
+  function recalcWorkbook(sheets) {
+    var n = sheets.length;
+    var results = [];   // results[s][r][c]
+    var state = [];     // state[s][r][c]: 1 = in progress, 2 = done
+    var nameToIndex = {};
+    for (var s = 0; s < n; s++) {
+      var sres = [], sstate = [];
+      var model0 = sheets[s].model;
+      var srows = model0 && model0.cells ? model0.cells.length : 0;
+      for (var r0 = 0; r0 < srows; r0++) { sres.push([]); sstate.push([]); }
+      results.push(sres); state.push(sstate);
+      var nm = sheets[s].name;
+      if (nm) {
+        var nkey = String(nm).toLowerCase();
+        if (!(nkey in nameToIndex)) nameToIndex[nkey] = s; // first wins
+      }
+    }
+
+    function rowsOf(si) {
+      var model = sheets[si].model;
+      return model && model.cells ? model.cells.length : 0;
+    }
+    function rawAt(si, c, r) {
+      var line = sheets[si].model.cells[r];
+      var cell = line && line[c];
+      return cell ? cell.raw : '';
+    }
+    function baseKind(si, c, r) {
+      var line = sheets[si].model.cells[r];
+      var cell = line && line[c];
+      if (!cell || cell.type === 'empty') return { kind: 'empty' };
+      if (cell.type === 'number') return { kind: 'number', value: cell.value };
+      return { kind: 'text', value: cell.raw };
+    }
+
+    // Resolve cell (c, r) within sheet index `si`. Bounds are checked against
+    // THIS sheet's row count (rowsOf(si)), not any caller's - a cross-sheet
+    // ref to a short sheet reads empty, not the wrong row.
+    function resolve(si, c, r) {
+      if (r < 0 || r >= rowsOf(si)) return { kind: 'empty' };
+      var rRes = results[si][r], rState = state[si][r];
+      if (rRes[c]) return rRes[c];
+      if (rState && rState[c] === 1) {
+        return (rRes[c] = { kind: 'error', code: '#CIRC!' });
+      }
+      var raw = rawAt(si, c, r);
+      if (!isFormula(raw)) return (rRes[c] = baseKind(si, c, r));
+      rState[c] = 1;
+      // ctx.cell(col, row, sheet): an undefined `sheet` means the formula's
+      // own sheet (si); a named sheet is looked up in nameToIndex; a name with
+      // no matching sheet is #REF! and never enters resolve.
+      var ctx = {
+        cell: function (cc, rr, sheetName) {
+          if (sheetName == null) return resolve(si, cc, rr);
+          var key = String(sheetName).toLowerCase();
+          if (!(key in nameToIndex)) return { kind: 'error', code: '#REF!' };
+          return resolve(nameToIndex[key], cc, rr);
+        },
+      };
+      var out = evaluate(raw, ctx);
+      rState[c] = 2;
+      return (rRes[c] = out.error
+        ? { kind: 'error', code: out.error }
+        : { kind: 'number', value: out.value });
+    }
+
+    for (var si2 = 0; si2 < n; si2++) {
+      var rows = rowsOf(si2);
+      for (var rr = 0; rr < rows; rr++) {
+        var line = sheets[si2].model.cells[rr];
+        var cols = line ? line.length : 0;
+        for (var cc = 0; cc < cols; cc++) resolve(si2, cc, rr);
+      }
+    }
+    return results;
+  }
+
+  // Whole-model recalc for a single sheet. A thin adapter over
+  // recalcWorkbook so every existing caller (renderer, editor, xlsx exporter,
+  // tests) keeps the same `recalc(model) -> results[r][c]` contract. With one
+  // anonymous sheet there are no qualified references to resolve, so the
+  // output is identical to the pre-workbook recalc.
+  function recalc(model) {
+    return recalcWorkbook([{ name: '', model: model }])[0];
+  }
+
+  exports.colIndex = colIndex;
+  exports.colName = colName;
+  exports.isFormula = isFormula;
+  exports.tokenize = tokenize;
+  exports.parse = parse;
+  exports.evaluate = evaluate;
+  exports.recalc = recalc;
+  exports.recalcWorkbook = recalcWorkbook;
+  exports.shiftFormula = shiftFormula;
+})(typeof module !== 'undefined' && module.exports ? module.exports : (window.SDocCellsFormula = {}));

package/shared/sdocs-cells.js

@@ -0,0 +1,389 @@
+// sdocs-cells.js - pure grid data model for ```cells fenced blocks.
+//
+// This is the BACKBONE of the cells/sheets feature. It is deliberately
+// just the model: parse a block body into an addressable grid of cells.
+// Every renderer (the inline grid, the future fullscreen sheet, the
+// future editor) and the exporter read FROM this model; none of them is
+// the source of truth. The DOM is always a view, never the data.
+//
+// A cell is two values from day one:
+//   { raw, value, type }
+//     raw   - exactly what the source held (a literal today, a formula
+//             string like "=B2-B3" tomorrow). Never rewritten.
+//     value - the computed display value. In v1 (no formula engine) this
+//             equals the parsed literal. When formulas land, only the
+//             compute step changes; raw already carries what it needs.
+//     type  - 'number' | 'text' | 'empty', drives alignment + display.
+//
+// The block body is CSV. That is on purpose: inline raw data and a future
+// {{file.csv}} transclusion then share one parser and one model, so those
+// two features are one code path rather than two with a seam between them.
+//
+// UMD so Node tests can require it directly; no DOM, no window.SDocs here.
+(function (exports) {
+  'use strict';
+
+  // Bijective base-26 spreadsheet column name. 0 -> A, 25 -> Z, 26 -> AA,
+  // 701 -> ZZ, 702 -> AAA. Matches how every spreadsheet labels columns.
+  function colName(index) {
+    var i = index + 1;
+    var s = '';
+    while (i > 0) {
+      var rem = (i - 1) % 26;
+      s = String.fromCharCode(65 + rem) + s;
+      i = Math.floor((i - 1) / 26);
+    }
+    return s;
+  }
+
+  // Inverse of colName: a column letter -> 0-based index ("A" -> 0, "AA" -> 26).
+  // Returns -1 for anything that isn't a run of A-Z letters.
+  function colIndex(letter) {
+    var s = String(letter).toUpperCase();
+    var n = 0;
+    for (var i = 0; i < s.length; i++) {
+      var c = s.charCodeAt(i) - 64;   // A -> 1
+      if (c < 1 || c > 26) return -1;
+      n = n * 26 + c;
+    }
+    return s.length ? n - 1 : -1;
+  }
+
+  // Strict literal number: optional sign, digits, optional single decimal.
+  // No thousands separators in v1 - a bare "1,000" is two CSV fields, and a
+  // quoted "1,000" stays text rather than guessing the user's locale.
+  var NUMBER_RE = /^-?\d+(?:\.\d+)?$/;
+
+  // Classify a raw field string into a cell record. The trimmed text drives
+  // type detection; `raw` is preserved verbatim for display and round-trip.
+  function classify(raw) {
+    var t = String(raw).trim();
+    if (t === '') return { raw: raw, value: '', type: 'empty' };
+    if (NUMBER_RE.test(t)) return { raw: raw, value: Number(t), type: 'number' };
+    return { raw: raw, value: t, type: 'text' };
+  }
+
+  // Parse a CSV string into an array of row arrays of field strings.
+  // Handles quoted fields with embedded commas / newlines and "" escapes.
+  // Lenient by design: there is no such thing as a malformed sheet, only a
+  // ragged one (which parseCells pads).
+  function parseCsv(src) {
+    var rows = [];
+    var row = [];
+    var field = '';
+    var inQuotes = false;
+    var i = 0;
+    var n = src.length;
+    while (i < n) {
+      var ch = src.charAt(i);
+      if (inQuotes) {
+        if (ch === '"') {
+          if (src.charAt(i + 1) === '"') { field += '"'; i += 2; continue; }
+          inQuotes = false; i++; continue;
+        }
+        field += ch; i++; continue;
+      }
+      if (ch === '"') { inQuotes = true; i++; continue; }
+      if (ch === ',') { row.push(field); field = ''; i++; continue; }
+      if (ch === '\r') { i++; continue; }
+      if (ch === '\n') { row.push(field); rows.push(row); row = []; field = ''; i++; continue; }
+      field += ch; i++;
+    }
+    row.push(field);
+    rows.push(row);
+    return rows;
+  }
+
+  // A bare {{path/to/file.csv}} reference (optionally with a :range suffix).
+  // Present only when a doc is opened WITHOUT the CLI (which otherwise bakes
+  // the data in); the renderer shows a "load it with sdoc" message.
+  var REFERENCE_RE = /^\{\{\s*([^}]+?)\s*\}\}$/;
+  // The machine-generated metadata line the CLI prepends to a baked block:
+  //   sdoc-cells: source=report.csv range=B5:J32
+  //   sdoc-cells: error="Could not read report.csv"
+  var DIRECTIVE_RE = /^sdoc-cells:\s*(.*)$/;
+
+  // Parse `key=value` / `key="quoted value"` pairs from a directive line.
+  function parseDirectives(str) {
+    var meta = {};
+    var re = /(\w+)=(?:"([^"]*)"|(\S+))/g;
+    var m;
+    while ((m = re.exec(str))) meta[m[1]] = m[2] !== undefined ? m[2] : m[3];
+    return meta;
+  }
+
+  // Build the grid model from a ```cells block body.
+  // Returns { rows, cols, cells, empty } where cells is row-major, every row
+  // padded to `cols` with empty cells so the grid is rectangular. May instead
+  // return { unresolved: <ref> } or { error: <msg> } for reference blocks.
+  function parseCells(src) {
+    var text = String(src == null ? '' : src);
+    // Drop leading blank lines and all trailing whitespace (incl. the final
+    // newline marked emits) but keep interior blank rows - a blank row is
+    // meaningful in a sheet.
+    var trimmed = text.replace(/^\n+/, '').replace(/\s+$/, '');
+    if (trimmed === '') return { rows: 0, cols: 0, cells: [], empty: true };
+
+    // Peel leading directive lines (in any order, machine or author):
+    //   sdoc-cells: source=... range=... error=... name=...  (baked metadata)
+    //   format: A=$ B=% C=plain                        (author column formats)
+    // `name` is the tab name. Authored as the fence info string (```cells
+    // Sales); the renderer + CLI normalise that into this directive so the
+    // name has one home in the model.
+    var source, range, formats, name;
+    var lines = trimmed.split('\n');
+    var idx = 0;
+    var FORMAT_RE = /^format:\s*(.*)$/i;
+    while (idx < lines.length) {
+      var dm = lines[idx].match(DIRECTIVE_RE);
+      var fm = lines[idx].match(FORMAT_RE);
+      if (dm) {
+        var meta = parseDirectives(dm[1]);
+        source = meta.source; range = meta.range;
+        if (meta.name != null) name = meta.name;
+        if (meta.error) return { empty: false, error: meta.error, source: source, name: name };
+        idx++; continue;
+      }
+      if (fm) { formats = parseFormats(fm[1]); idx++; continue; }
+      break;
+    }
+    var body = lines.slice(idx).join('\n').replace(/\s+$/, '');
+
+    // Unresolved reference (after directives): the CLI never baked it.
+    var ref = body.match(REFERENCE_RE);
+    if (ref) return { empty: false, unresolved: ref[1], formats: formats, name: name };
+    if (body === '') return { rows: 0, cols: 0, cells: [], empty: true, source: source, range: range, formats: formats, name: name };
+
+    var raw = parseCsv(body);
+    var cols = 0;
+    for (var r = 0; r < raw.length; r++) {
+      if (raw[r].length > cols) cols = raw[r].length;
+    }
+    var cells = [];
+    for (var r2 = 0; r2 < raw.length; r2++) {
+      var line = raw[r2];
+      var out = [];
+      for (var c = 0; c < cols; c++) {
+        out.push(classify(c < line.length ? line[c] : ''));
+      }
+      cells.push(out);
+    }
+    return { rows: raw.length, cols: cols, cells: cells, empty: false, source: source, range: range, formats: formats, name: name };
+  }
+
+  // Serialize a 2D array of raw cell strings back to CSV (RFC 4180 quoting:
+  // wrap in quotes and double any embedded quote when a field contains a
+  // comma, quote, or newline). The inverse of parseCsv for the copy actions.
+  function serializeCsv(rows) {
+    return rows.map(function (row) {
+      return row.map(function (v) {
+        var s = String(v == null ? '' : v);
+        return /[",\n\r]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+      }).join(',');
+    }).join('\n');
+  }
+
+  // Stats for a selected rectangle [r0..r1] x [c0..c1] of a model. Numbers
+  // drive sum/avg/min/max; count is every non-empty cell (Excel's "Count").
+  // Cells past the data (fullscreen padding) read as empty. fx (optional) is
+  // a recalc results grid aligned to this model's rows: a formula cell then
+  // contributes its computed value (errors count as non-empty, not numeric).
+  function selectionStats(model, r0, c0, r1, c1, fx) {
+    var count = 0, numericCount = 0, sum = 0, min = null, max = null;
+    for (var r = r0; r <= r1; r++) {
+      var line = model.cells[r];
+      for (var c = c0; c <= c1; c++) {
+        var cell = line && line[c];
+        if (!cell || cell.type === 'empty') continue;
+        count++;
+        var isNum = cell.type === 'number';
+        var v = cell.value;
+        // A formula cell's raw is "=..." text; its computed result decides.
+        if (fx && cell.raw && cell.raw.charAt(0) === '=') {
+          var fxCell = fx[r] && fx[r][c];
+          isNum = !!fxCell && fxCell.kind === 'number';
+          if (isNum) v = fxCell.value;
+        }
+        if (isNum) {
+          numericCount++;
+          sum += v;
+          if (min === null || v < min) min = v;
+          if (max === null || v > max) max = v;
+        }
+      }
+    }
+    return {
+      count: count,
+      numericCount: numericCount,
+      sum: sum,
+      avg: numericCount > 0 ? sum / numericCount : null,
+      min: min,
+      max: max,
+    };
+  }
+
+  // Heuristic: is row 0 a header? True when row 0 has no numbers and there is
+  // numeric data below it - so a sort can keep it pinned to the top.
+  function looksLikeHeader(model) {
+    if (!model || model.rows < 2) return false;
+    var row0 = model.cells[0];
+    for (var c = 0; c < model.cols; c++) {
+      if (row0[c] && row0[c].type === 'number') return false;
+    }
+    for (var r = 1; r < model.rows; r++) {
+      var line = model.cells[r];
+      for (var c2 = 0; c2 < model.cols; c2++) {
+        if (line[c2] && line[c2].type === 'number') return true;
+      }
+    }
+    return false;
+  }
+
+  // Sort key: numbers (rank 0) sort before text (rank 1); empty (rank 2) last.
+  // fxCell, when given, is the cell's computed formula result ({kind, value} /
+  // {kind: 'error', code}) and takes precedence: a formula sorts by the value
+  // the user sees, not by its "=..." source text. Errors sort with text.
+  function sortKey(cell, fxCell) {
+    if (fxCell && fxCell.kind === 'number') return { rank: 0, v: fxCell.value };
+    if (fxCell && fxCell.kind === 'error') return { rank: 1, v: String(fxCell.code || '').toLowerCase() };
+    if (!cell || cell.type === 'empty') return { rank: 2, v: 0 };
+    if (cell.type === 'number') return { rank: 0, v: cell.value };
+    return { rank: 1, v: String(cell.value).toLowerCase() };
+  }
+
+  // A summary row aggregates other rows: it holds at least one formula with a
+  // range spanning 2+ rows, e.g. =SUM(D2:D5). Per-row formulas (=B2*C2) refer
+  // to single cells and do not count. Used by sortRows to keep a trailing
+  // "Total" row pinned at the bottom instead of jumbling it into the data.
+  var ROW_RANGE_RE = /[A-Za-z]+([0-9]+)\s*:\s*[A-Za-z]+([0-9]+)/;
+  function isSummaryRow(row) {
+    if (!row) return false;
+    for (var i = 0; i < row.length; i++) {
+      var raw = row[i] && row[i].raw;
+      if (!raw || raw.charAt(0) !== '=') continue;
+      var m = ROW_RANGE_RE.exec(raw);
+      if (m && m[1] !== m[2]) return true;       // the range spans rows
+    }
+    return false;
+  }
+
+  // Return the row order (array of original indices) sorting the model by a
+  // column. A view reorder - the model itself is not changed. Empty cells stay
+  // last either direction; a header row (when hasHeader) stays pinned to row 0;
+  // trailing summary rows (see isSummaryRow) stay pinned at the bottom.
+  // fx (optional) is a recalc results grid indexed by SOURCE row: formula
+  // cells then sort by their computed value instead of their source text.
+  function sortRows(model, col, dir, hasHeader, fx) {
+    var order = [];
+    for (var r = 0; r < model.rows; r++) order.push(r);
+    var start = hasHeader ? 1 : 0;
+    // Trailing summary rows (a Total / Average footer) sit outside the sort,
+    // in their original order.
+    var end = model.rows;
+    while (end > start && isSummaryRow(model.cells[end - 1])) end--;
+    var head = order.slice(0, start);
+    var tail = order.slice(end);
+    var body = order.slice(start, end);
+    var sign = dir === 'desc' ? -1 : 1;
+    function fxFor(r, cell) {
+      if (!fx || !cell || !cell.raw || cell.raw.charAt(0) !== '=') return null;
+      return (fx[r] && fx[r][col]) || null;
+    }
+    body.sort(function (ra, rb) {
+      var ca = model.cells[ra] && model.cells[ra][col];
+      var cb = model.cells[rb] && model.cells[rb][col];
+      var a = sortKey(ca, fxFor(ra, ca));
+      var b = sortKey(cb, fxFor(rb, cb));
+      if (a.rank === 2 || b.rank === 2) return a.rank - b.rank;  // empty always last
+      if (a.rank !== b.rank) return (a.rank - b.rank) * sign;
+      if (a.v < b.v) return -1 * sign;
+      if (a.v > b.v) return 1 * sign;
+      return 0;
+    });
+    return head.concat(body).concat(tail);
+  }
+
+  // Display formatting for a numeric raw string: group the integer part with
+  // thousands separators, preserve the sign and the decimal part verbatim
+  // (so "1234.50" keeps its trailing zero). Display only - the model's raw is
+  // untouched, so copy / export still emit the original value.
+  function formatNumber(raw) {
+    var s = String(raw == null ? '' : raw).trim();
+    var neg = s.charAt(0) === '-';
+    if (neg) s = s.slice(1);
+    var dot = s.indexOf('.');
+    var intPart = dot === -1 ? s : s.slice(0, dot);
+    var rest = dot === -1 ? '' : s.slice(dot);
+    intPart = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    return (neg ? '-' : '') + intPart + rest;
+  }
+
+  // Parse one format token into a spec: { kind, symbol?, decimals? }.
+  // Tokens: $ / usd / currency, £ / gbp, € / eur, % / percent, , / comma /
+  // number, plain / text / raw, plus an optional trailing .N for decimals
+  // (e.g. "$.0", "%.1", ".2"). Unknown tokens return null.
+  function parseFmtToken(tok) {
+    var t = String(tok).trim();
+    var decimals = null;
+    var dm = t.match(/\.(\d+)$/);
+    if (dm) { decimals = parseInt(dm[1], 10); t = t.slice(0, t.length - dm[0].length); }
+    var lc = t.toLowerCase();
+    if (t === '$' || lc === 'usd' || lc === 'currency') return { kind: 'currency', symbol: '$', decimals: decimals == null ? 2 : decimals };
+    if (t === '£' || lc === 'gbp') return { kind: 'currency', symbol: '£', decimals: decimals == null ? 2 : decimals };
+    if (t === '€' || lc === 'eur') return { kind: 'currency', symbol: '€', decimals: decimals == null ? 2 : decimals };
+    if (t === '%' || lc === 'percent') { var p = { kind: 'percent' }; if (decimals != null) p.decimals = decimals; return p; }
+    if (t === ',' || lc === 'comma' || lc === 'number' || lc === 'num') { var nn = { kind: 'number' }; if (decimals != null) nn.decimals = decimals; return nn; }
+    if (lc === 'plain' || lc === 'text' || lc === 'raw') return { kind: 'plain' };
+    if (t === '' && decimals != null) return { kind: 'number', decimals: decimals };
+    return null;
+  }
+
+  // Parse a per-column format spec like "A=plain B=$ C=%.1" into a map
+  // { colIndex: fmt }. Keys are column letters; unknown tokens are skipped.
+  function parseFormats(spec) {
+    var out = {};
+    var re = /([A-Za-z]+)\s*=\s*(\S+)/g;
+    var m;
+    while ((m = re.exec(spec))) {
+      var col = colIndex(m[1]);
+      var fmt = parseFmtToken(m[2]);
+      if (col >= 0 && fmt) out[col] = fmt;
+    }
+    return out;
+  }
+
+  // Format a numeric cell's display per a column format. Returns null for
+  // non-number cells (the caller falls back to text rendering). Display only -
+  // the model's raw is untouched, so copy / export emit the original.
+  function formatValue(cell, fmt) {
+    if (!cell || cell.type !== 'number') return null;
+    var v = cell.value;
+    if (!fmt || fmt.kind === 'number') {
+      return (fmt && fmt.decimals != null) ? formatNumber(v.toFixed(fmt.decimals)) : formatNumber(cell.raw);
+    }
+    if (fmt.kind === 'plain') return cell.raw;
+    if (fmt.kind === 'currency') {
+      var d = fmt.decimals == null ? 2 : fmt.decimals;
+      return (v < 0 ? '-' : '') + fmt.symbol + formatNumber(Math.abs(v).toFixed(d));
+    }
+    if (fmt.kind === 'percent') {
+      var p = v * 100;
+      var str = fmt.decimals != null ? p.toFixed(fmt.decimals) : String(Math.round(p * 1e6) / 1e6);
+      return formatNumber(str) + '%';
+    }
+    return formatNumber(cell.raw);
+  }
+
+  exports.colName = colName;
+  exports.classify = classify;
+  exports.parseCsv = parseCsv;
+  exports.parseCells = parseCells;
+  exports.serializeCsv = serializeCsv;
+  exports.selectionStats = selectionStats;
+  exports.formatNumber = formatNumber;
+  exports.colIndex = colIndex;
+  exports.parseFormats = parseFormats;
+  exports.formatValue = formatValue;
+  exports.looksLikeHeader = looksLikeHeader;
+  exports.sortRows = sortRows;
+})(typeof module !== 'undefined' && module.exports ? module.exports : (window.SDocCells = {}));