sdocs-dev 1.13.1 → 1.14.1

package/bin/sdocs-bridge.js

@@ -26,7 +26,7 @@ const fs     = require('fs');
 const path   = require('path');
 const crypto = require('crypto');
 const FormBlock = require('../shared/sdocs-form-block.js');
-const { isWrappedFile, wrapForDisplay } = require('../lib/cells-transclude');
+const { isWrappedFile, wrapForDisplay } = require('../lib/file-wrap');
 
 // ── Constants ─────────────────────────────────────────────
 

package/bin/sdocs-dev.js

@@ -47,6 +47,8 @@ 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('videos',   { handler: () => { console.log(helpText.VIDEOS_HELP);   process.exit(0); } });
+  r.register('video',    { handler: () => { console.log(helpText.VIDEOS_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).
@@ -54,6 +56,7 @@ function buildRouter() {
     if ((opts.file || '').toLowerCase() === 'verify') return cellsVerify.cellsVerifyCommand(opts);
     console.log(helpText.CELLS_HELP); process.exit(0);
   } });
+  r.register('code',     { handler: () => { console.log(helpText.CODE_HELP);     process.exit(0); } });
   r.register('comments', { handler: () => { console.log(helpText.COMMENTS_HELP); process.exit(0); } });
 
   // Setup / refresh / auto-update.

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 = 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_VERSION = 12;
+const AGENT_BLOCK_REASON  = 'Adds `sdoc code`: opening a source file (sdoc app.rb) or a ```lang fenced block as a syntax-highlighted listing - a light code viewer for reading code with the user away from the IDE - with source comments given a prominent lane, a fullscreen view that folds by method/class, a comment mode for the user to annotate a line or method, and agent annotations (sdoc app.py 22:"...") that pin markdown callouts to lines so an agent can walk the user through code without editing it. One bullet added after the cells line; the rest of the block is unchanged from v11.';
 
 const AGENT_BLOCK_BODY = `## SmallDocs
 
@@ -49,6 +49,7 @@ Each command below prints its reference when run with no arguments - run it befo
 - \`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. 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 code\` - opening a source file or a fenced code block as a syntax-highlighted listing: a light code viewer for reading code with the user away from the IDE. \`sdoc app.rb\` (or \`.js\`, \`.py\`, \`.go\`, \`.rs\`, \`.ts\`...) opens a file as a highlighted listing; a \`\`\`lang fenced block is highlighted inline. Comments in the source get a prominent lane so the code reads clearly top to bottom. The fullscreen view adds a line-number gutter and language-aware folding (collapse a whole method or class); a comment mode lets the user annotate a line or method with review notes, kept in the browser rather than the file. You can also pin your own explanations to lines as you open a file - \`sdoc app.py 22:"this method has the bug" 25-28:"wrong comparison here"\` - and they render as markdown callouts below those lines, a way to walk the user through code without editing the source. The file rides in the URL like any document; nothing is uploaded. Reach for it when reading or reviewing code with the user, not for prose.
 - \`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/bridge-commands.js

@@ -22,6 +22,8 @@ const { startBridge } = require('../bin/sdocs-bridge');
 const { DEFAULT_URL } = require('./constants');
 const { openBrowser } = require('./io');
 const { stripAndCompress } = require('./url');
+const { wrapForDisplay } = require('./file-wrap');
+const { isCodeFile } = require('./code-langs');
 
 function baseUrlFor(opts) {
   return opts.url || process.env.SDOCS_URL || DEFAULT_URL;
@@ -41,7 +43,20 @@ function bridgeSnapshot(file) {
   if (!file) return null;
   if (WRAPPED_EXT.has(path.extname(file).toLowerCase())) return null;
   try {
-    return stripAndCompress(fs.readFileSync(file, 'utf-8'));
+    const raw = fs.readFileSync(file, 'utf-8');
+    // A code file's renderable document is the file wrapped in a fence (the same
+    // transform the live bridge applies). The snapshot must embed THAT, not the
+    // raw source: otherwise the read-only fallback - which is what every page
+    // refresh renders until the socket reconnects - shows the file as markdown
+    // (docstrings as prose, indented bodies as stray code blocks) instead of the
+    // fullscreen code view with its folding and comments. Carry the filename in
+    // front matter so the snapshot is self-contained: the code view names it and
+    // auto-expands without depending on the bridge's `file=` param surviving.
+    if (isCodeFile(file)) {
+      const doc = '---\nfile: ' + path.basename(file) + '\n---\n' + wrapForDisplay(raw, file);
+      return stripAndCompress(doc);
+    }
+    return stripAndCompress(raw);
   } catch (_) {
     return null;
   }
@@ -166,6 +181,7 @@ function feedbackCommand(opts)  { return runBridge(opts, 'feedback', 'Feedback o
 module.exports = {
   runBridgedOpen,
   feedbackCommand,
-  buildBridgeUrl, // for tests
-  timeoutOpts,    // for tests
+  buildBridgeUrl,  // for tests
+  bridgeSnapshot,  // for tests
+  timeoutOpts,     // for tests
 };

package/lib/cells-transclude.js

@@ -86,29 +86,7 @@ function wrapCsvFile(csv, filename) {
     String(csv).replace(/\s+$/, '') + '\n```\n';
 }
 
-// A "wrapped" file is one whose renderable document is DERIVED from the file
-// (its contents inside a fenced block) rather than the file itself. The two
-// open paths (URL snapshot via readContent, live sync via the bridge) both
-// wrap these for display, and the bridge refuses to save the derived view
-// back - that would overwrite the .csv / .mmd with fence markup.
-function isWrappedFile(filePath) {
-  return /\.(csv|mmd|mermaid)$/i.test(String(filePath || ''));
-}
-
-// File contents -> renderable document. Wrapped types get their fence;
-// everything else (markdown) passes through untouched.
-function wrapForDisplay(raw, filePath) {
-  var name = String(filePath || '');
-  if (/\.(mmd|mermaid)$/i.test(name)) {
-    return '```mermaid\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
-  }
-  if (/\.csv$/i.test(name)) return wrapCsvFile(raw, name);
-  return String(raw);
-}
-
 module.exports = {
   transcludeCells: transcludeCells,
   wrapCsvFile: wrapCsvFile,
-  isWrappedFile: isWrappedFile,
-  wrapForDisplay: wrapForDisplay,
 };

package/lib/cells-verify.js

@@ -31,30 +31,44 @@ function scanCellsBlocks(md) {
   var blocks = [];
   var m;
   while ((m = re.exec(md))) {
-    blocks.push({ name: (m[2] || '').trim().replace(/"/g, ''), body: m[3] });
+    blocks.push({ info: (m[2] || '').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.
+// Parse + name + group every block into workbooks, mirroring the renderer.
+// Each block's fence info is split into a workbook id and a sheet name (the
+// first "/" separates them); a baked `workbook=` / `name=` directive is the
+// fallback. Blocks bucket by workbook id in first-seen order; within each
+// workbook a fence/directive name wins, else auto Sheet1/Sheet2..., and both
+// the auto counter and duplicate detection reset per workbook. recalcWorkbook
+// later resolves references only within one workbook, so a Sheet!A1 into
+// another workbook reads #REF! - the same isolation the browser enforces.
 function buildWorkbook(md) {
   var blocks = scanCellsBlocks(md);
-  var sheets = [];   // { name, model }
+  var order = [];     // workbook ids, first-seen order
+  var byWb = {};      // id -> [{ 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 });
+    var fence = CELLS.parseFenceInfo(blocks[i].info || '');
+    var wbId = fence.workbook || (model.workbook != null ? String(model.workbook) : '');
+    var explicitName = fence.name || (model.name && String(model.name).trim()) || '';
+    if (!byWb[wbId]) { byWb[wbId] = []; order.push(wbId); }
+    byWb[wbId].push({ name: explicitName, model: model });
   }
-  return { sheets: sheets, parseErrors: parseErrors };
+  var workbooks = order.map(function (id) {
+    var autoIdx = 0;
+    var sheets = byWb[id].map(function (s) {
+      return { name: s.name || ('Sheet' + (++autoIdx)), model: s.model };
+    });
+    return { id: id, sheets: sheets };
+  });
+  return { workbooks: workbooks, parseErrors: parseErrors };
 }
 
 // Render one sheet's computed grid to a 2D array of display strings: a formula
@@ -111,17 +125,24 @@ async function cellsVerifyCommand(opts) {
   }
 
   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] || []),
-    };
+  // Recalc each workbook in isolation, then flatten to a per-sheet view that
+  // remembers which workbook each sheet came from. --sheet filters it after.
+  var rendered = [];
+  wb.workbooks.forEach(function (book) {
+    var fxGrids = FX.recalcWorkbook(book.sheets.map(function (s) {
+      return { name: s.name, model: s.model };
+    }));
+    book.sheets.forEach(function (s, i) {
+      var errs = errorsFor(s.name, s.model, fxGrids[i] || []);
+      if (book.id) errs.forEach(function (e) { e.workbook = book.id; });
+      rendered.push({
+        workbook: book.id,
+        name: s.name,
+        values: valuesFor(s.model, fxGrids[i] || []),
+        errors: errs,
+      });
+    });
   });
 
   if (opts.sheetName) {
@@ -141,14 +162,19 @@ async function cellsVerifyCommand(opts) {
   if (opts.jsonFlag) {
     process.stdout.write(JSON.stringify({
       ok: ok,
-      sheets: rendered.map(function (r) { return { name: r.name, values: r.values }; }),
+      sheets: rendered.map(function (r) {
+        var o = { name: r.name, values: r.values };
+        if (r.workbook) o.workbook = r.workbook;
+        return o;
+      }),
       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);
+      var banner = r.workbook ? ('# workbook: ' + r.workbook + ' / sheet: ' + r.name) : ('# sheet: ' + r.name);
+      return banner + '\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); });

package/lib/code-langs.js

@@ -0,0 +1,85 @@
+// code-langs.js - map a source file's extension to a fenced code block.
+//
+// `sdoc app.rb` should open as a syntax-highlighted Ruby document, the same way
+// `sdoc chart.mmd` opens as a diagram. The CLI can't highlight anything itself;
+// it just wraps the file in a ```<lang> fence and the browser's highlight.js
+// does the colouring. So all this module decides is: which fence label?
+//
+// The label is the highlight.js language name (or one of its aliases), so the
+// fence the CLI writes is the same one a user would type by hand.
+
+var path = require('path');
+
+// Extension (no dot, lowercase) -> fence label. Markdown and plain text are
+// intentionally absent: those open as documents, not as code listings.
+var LANG_BY_EXT = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript',
+  ts: 'typescript', tsx: 'typescript',
+  py: 'python', pyw: 'python',
+  rb: 'ruby', rake: 'ruby',
+  go: 'go',
+  rs: 'rust',
+  java: 'java',
+  kt: 'kotlin', kts: 'kotlin',
+  swift: 'swift',
+  c: 'c', h: 'c',
+  cpp: 'cpp', cc: 'cpp', cxx: 'cpp', hpp: 'cpp', hh: 'cpp',
+  cs: 'csharp',
+  php: 'php',
+  scala: 'scala',
+  ex: 'elixir', exs: 'elixir',
+  erl: 'erlang',
+  clj: 'clojure', cljs: 'clojure',
+  hs: 'haskell',
+  lua: 'lua',
+  pl: 'perl', pm: 'perl',
+  r: 'r',
+  dart: 'dart',
+  sh: 'bash', bash: 'bash', zsh: 'bash',
+  ps1: 'powershell',
+  sql: 'sql',
+  yml: 'yaml', yaml: 'yaml',
+  toml: 'toml',
+  ini: 'ini', cfg: 'ini', conf: 'ini',
+  json: 'json',
+  xml: 'xml', svg: 'xml',
+  html: 'xml', htm: 'xml',
+  css: 'css',
+  scss: 'scss', sass: 'scss',
+  less: 'less',
+  dockerfile: 'dockerfile',
+  diff: 'diff', patch: 'diff',
+  graphql: 'graphql', gql: 'graphql',
+  proto: 'protobuf'
+};
+
+function extOf(filePath) {
+  var name = path.basename(String(filePath || '')).toLowerCase();
+  // Dotfiles named exactly like a known type, e.g. "Dockerfile".
+  if (name === 'dockerfile') return 'dockerfile';
+  var ext = path.extname(name);
+  return ext ? ext.slice(1) : '';
+}
+
+// The highlight.js language for a path, or '' if we don't wrap it as code.
+function langForFile(filePath) {
+  return LANG_BY_EXT[extOf(filePath)] || '';
+}
+
+function isCodeFile(filePath) {
+  return !!langForFile(filePath);
+}
+
+// File contents -> a fenced code document. Trailing whitespace is trimmed so a
+// file's final newline doesn't render as an empty last line in the block.
+function wrapCodeFile(raw, filePath) {
+  var lang = langForFile(filePath);
+  return '```' + lang + '\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
+}
+
+module.exports = {
+  LANG_BY_EXT: LANG_BY_EXT,
+  langForFile: langForFile,
+  isCodeFile: isCodeFile,
+  wrapCodeFile: wrapCodeFile
+};

package/lib/commands.js

@@ -36,11 +36,19 @@ async function prepareUrl(opts) {
   }
 
   // Inject `file:` into front matter (basename only — safe to share).
-  // Respects user-set file: if already present.
+  // Respects user-set file: if already present. Agent annotations
+  // (`sdoc app.py 22:"..."`) ride here too, in `annotations:`, so they travel
+  // with the link and through `sdoc share` (front matter rides in the body,
+  // unlike `local` which share strips).
   if (content && opts.file) {
     const parsed = SDocYaml.parseFrontMatter(content);
-    if (!parsed.meta.file) {
-      parsed.meta.file = path.basename(opts.file);
+    let changed = false;
+    if (!parsed.meta.file) { parsed.meta.file = path.basename(opts.file); changed = true; }
+    if (opts.annotations && opts.annotations.length) {
+      parsed.meta.annotations = opts.annotations;
+      changed = true;
+    }
+    if (changed) {
       content = SDocYaml.serializeFrontMatter(parsed.meta) + '\n' + parsed.body;
     }
   }

package/lib/file-wrap.js

@@ -0,0 +1,39 @@
+// file-wrap.js - turn a file's contents into a renderable document.
+//
+// Some file types don't open as themselves: a .csv opens as a sheet, a .mmd as
+// a diagram, a .rb as a highlighted listing. For those, the document SDocs
+// renders is DERIVED from the file (its contents inside a fenced block) rather
+// than the file itself. This module is the one dispatcher that decides which
+// wrapping applies. Markdown and plain text are not wrapped - they open as-is.
+//
+// Both open paths go through here: readContent (the URL-snapshot path, in
+// io.js) and the bridge (the live-sync path). The bridge also reads
+// isWrappedFile to refuse saving a derived view back over the source file -
+// that would overwrite the .csv / .mmd / .rb with fence markup.
+
+const { wrapCsvFile } = require('./cells-transclude');
+const codeLangs = require('./code-langs');
+
+// A "wrapped" file is one whose renderable document is derived from a fence
+// around its contents, not the raw file.
+function isWrappedFile(filePath) {
+  var name = String(filePath || '');
+  return /\.(csv|mmd|mermaid)$/i.test(name) || codeLangs.isCodeFile(name);
+}
+
+// File contents -> renderable document. Wrapped types get their fence;
+// everything else (markdown) passes through untouched.
+function wrapForDisplay(raw, filePath) {
+  var name = String(filePath || '');
+  if (/\.(mmd|mermaid)$/i.test(name)) {
+    return '```mermaid\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
+  }
+  if (/\.csv$/i.test(name)) return wrapCsvFile(raw, name);
+  if (codeLangs.isCodeFile(name)) return codeLangs.wrapCodeFile(raw, name);
+  return String(raw);
+}
+
+module.exports = {
+  isWrappedFile: isWrappedFile,
+  wrapForDisplay: wrapForDisplay,
+};

package/lib/help-text.js

@@ -1,5 +1,5 @@
 // Long help strings printed by `sdoc help`, `sdoc schema`, `sdoc charts`,
-// `sdoc diagrams`, `sdoc comments`. Kept as plain data with no logic.
+// `sdoc diagrams`, `sdoc code`, `sdoc comments`. Kept as plain data with no logic.
 
 const HELP = `
 SmallDocs CLI
@@ -21,7 +21,10 @@ USAGE
   sdoc schema                      Print the full styles schema
   sdoc charts                      Chart types, options, and styling guide
   sdoc diagrams                    Mermaid diagrams reference (\`\`\`mermaid blocks)
+  sdoc videos                      YouTube embed reference (\`\`\`video blocks)
   sdoc cells                       Inline spreadsheet reference (\`\`\`cells blocks)
+  sdoc code                        Syntax highlighting + code-viewer reference
+  sdoc app.rb / server.js / ...    Open a source file as a highlighted listing
   sdoc color-analysis <file>       Check custom colours for readable contrast
                                    (both themes). Run after styling a doc.
   sdoc comments                    Comment-format reference (for agents)
@@ -926,6 +929,55 @@ EXAMPLE
 `;
 
 
+const VIDEOS_HELP = `
+SmallDocs - Videos
+==================
+Embed a YouTube video in markdown using a \`\`\`video fenced code block.
+The body is a YouTube URL (any common shape) or a bare 11-character
+video id, with optional \`title:\` and \`start:\` lines.
+
+BASIC SYNTAX
+  \`\`\`video
+  https://www.youtube.com/watch?v=dQw4w9WgXcQ
+  \`\`\`
+
+  Bare id, short link, embed link and shorts link all work:
+  \`\`\`video
+  dQw4w9WgXcQ
+  \`\`\`
+
+WITH A TITLE AND START TIME
+  \`\`\`video
+  https://youtu.be/dQw4w9WgXcQ
+  title: Our launch walkthrough
+  start: 1:30
+  \`\`\`
+  \`start:\` accepts seconds (90), clock (1:30, 1:02:03) or 1m30s / 1h2m3s.
+  A \`t=\` parameter already on the URL is used when no \`start:\` is given.
+  \`title:\` sets the iframe title (accessibility) and a caption link.
+
+WHAT RENDERS
+  A responsive 16:9 player that scales with the body column. The embed
+  host is youtube-nocookie.com, so no tracking cookie is set until the
+  viewer presses play. \`rel=0\` is applied, which limits the end-screen
+  suggestions to the source channel (YouTube no longer allows fully
+  removing them from an embed).
+
+LIMITS
+  - Per-block source cap: 8 KB.
+  - Per-document video cap: 50 (excess rendered as plain code).
+
+SECURITY
+  No iframe ever travels through the document markup - SmallDocs still
+  strips iframes from ordinary markdown. The renderer reads only the
+  block text, extracts the 11-character video id, validates it against
+  \`[A-Za-z0-9_-]{11}\`, and builds the player from a src it constructs
+  itself. Anything that is not a recognised YouTube URL or a valid id
+  renders as an inline error, never an embed. Treat block source as
+  untrusted - it travels in the URL hash with the rest of the document.
+`;
+
+
 const CELLS_HELP = `
 SmallDocs - Cells (sheets)
 ======================
@@ -1047,6 +1099,32 @@ MULTIPLE TABS (SHEETS)
       tabs collapse into a single widget (a tab strip + one grid at a time),
       placed where the first tab sat.
 
+WORKBOOK GROUPS (independent tab sets in one document)
+  Name a workbook before the sheet to split a document into separate,
+  independent workbooks. The part before the first "/" is the workbook, the
+  part after is the sheet name:
+
+  \`\`\`cells financials/Model
+  Line,2025,2026
+  Revenue,=Drivers!B2,=Drivers!C2
+  \`\`\`
+
+  \`\`\`cells financials/Drivers
+  Driver,2025,2026
+  Seats,800,2500
+  \`\`\`
+
+  Blocks that share a workbook id form one workbook: their own tab strip (under
+  cells-tabs: tabbed), their own sheet-name namespace, and their own formula
+  scope. Two workbooks on a page render as two separate tab strips. A Sheet!A1
+  reference into another workbook reads #REF! - the isolation is total, so two
+  workbooks may reuse a sheet name without colliding. A block with no "/" stays
+  in the default workbook and behaves exactly as before.
+
+  In the fullscreen view a "Download workbook" button exports the whole
+  workbook as one .xlsx, every sheet and its cross-sheet formulas intact; the
+  per-sheet download on each grid still exports just that one sheet.
+
 VERIFYING (for agents)
   Check the computed values without a browser:
 
@@ -1060,9 +1138,11 @@ VERIFYING (for agents)
   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).
+  The default output banners each tab with "# sheet: <name>", or "# workbook:
+  <id> / sheet: <name>" when the sheet sits in a named workbook (each workbook
+  is verified in isolation). A data row could itself start with that text, so
+  for machine parsing use --json (its per-tab values array, and each tab's
+  optional workbook field, are unambiguous).
 
 SORTING
   Hover a column letter: an arrow appears on its right showing what a click
@@ -1815,7 +1895,8 @@ navigate.
   errors + the full slide source — for pasting back to an agent.
 
   Common errors:
-    - "shape extends outside grid WxH"   y+h > H (or x+w > W)
+    - "shape extends outside grid WxH"   bbox past an edge by >10% of the
+                                         grid (a little bleed is allowed)
     - \`unknown id "@name"\`               @-ref before the shape is declared
     - \`duplicate id "#name"\`             two shapes share an id
     - \`invalid attribute key\`            key must start with a letter
@@ -1939,6 +2020,37 @@ rather than as designed.
     default. Spend visual weight only on the one or two things the
     slide is about. Empty space is half the design.
 
+  Text alignment.
+    Except for slides with very few elements, or custom shapes with
+    very few words, prefer left-aligned text throughout a slide.
+    Left-aligning most elements - particularly any with more than
+    three words - creates a calm, confident slide that is easy to
+    follow.
+
+  An implicit grid.
+    Take inspiration from Josef Muller-Brockmann's work on grid
+    systems. Consistency of alignment between elements gives off the
+    feeling of considered, structured thinking. Unless you are
+    creating something specific from custom shapes, prefer to build
+    an implicit grid on the slide. A presentation feels even more
+    professional when that grid language flows from slide to slide.
+
+  Branding, borders and background.
+    Less is often more. Precise layouts are hard with custom shapes:
+    overlapping positions may not land where you expect, and you
+    cannot easily check how the slide feels. So when you give a slide
+    a mood through coloured background shapes, keep it relatively
+    simple. This should not stop you being bold, but design with a
+    few key shapes (which may overlap), not many overlapping ones.
+
+  Contrast and legibility.
+    Consider the colour of text against the colour of whatever falls
+    directly beneath it. Readers should be able to calmly take text
+    in from a slide, so ensure there is healthy contrast, at least,
+    between text and the colour beneath it. In general, try to
+    overlay text on a single patch of colour (or very closely
+    related colours) to keep it straightforwardly legible.
+
 ── SHAPE KINDS ───────────────────────────────────────
   r x y w h            rectangle  (x,y = top-left; w,h = size)
   i x y w h            image rect (sugar for \`r\` with \`image=\`; see IMAGES)
@@ -2039,6 +2151,12 @@ rather than as designed.
                                    so the layout doesn't reflow when
                                    icons swap in.
 
+  Pair an icon with its label as two separate shapes - the icon in
+  its own small box, the text in a shape beside or below it. Don't
+  put \`|\` text on an icon (it overlaps the glyph) or drop an icon
+  onto a text shape. Keep every icon in a set the same size (w = h)
+  on a shared row.
+
   Arrow geometry: the coordinates are the line's centerline. The head is
   symmetric around the line, extending up to 3 * strokeWidth perpendicular
   on each side. So a horizontal arrow at y=5.78 with strokeWidth=0.06
@@ -2249,6 +2367,18 @@ rather than as designed.
      The three cards then read as a parallel set rather than three
      improvisations.
 
+  5. Icons collide with text when they share a box.
+
+     The \`icon\` shape paints its glyph across its whole bbox, so
+     text in the same box - or a text shape the icon sits on top of
+     - overlaps it. Keep them as two shapes on one row:
+
+       icon 8 20 4 4 name=recycle color=#0165a5
+       r 13 20 26 4 text=body align=left valign=center | Repairable by design
+
+     Icon in its own 4x4 box; the label starts after it at x=13,
+     centred on the same y. Size every icon in a set the same.
+
 ── SHAPE ATTRIBUTES ──────────────────────────────────
   Between geometry and \`|\`:
 
@@ -2756,4 +2886,65 @@ COMMON QUESTIONS
      drop a \`.sdocsignore\` into the directory with the pattern.
 `;
 
-module.exports = { HELP, COMMENTS_HELP, SCHEMA, CHARTS_HELP, DIAGRAMS_HELP, CELLS_HELP, SLIDES_HELP, SLIDES_CUSTOM_SHAPES_HELP, LIBRARY_HELP };
+const CODE_HELP = `
+SDocs - Code (syntax highlighting)
+==================================
+Fenced code blocks are syntax-highlighted by language. Tag the fence with a
+language and the block is coloured in the browser; highlight.js is loaded from
+a CDN on first use, so a document with no code blocks pays nothing.
+
+BASIC SYNTAX
+  Tag the opening fence with a language name:
+
+  \`\`\`ruby
+  def greet(name)
+    # comments are styled to stand out, not fade away
+    puts "hello, #{name}"
+  end
+  \`\`\`
+
+  An untagged fence stays plain (no guessing). Blocks claimed by other
+  features - chart, mermaid, cells, form, math, slide - are never treated
+  as code.
+
+OPENING A SOURCE FILE
+  Point sdoc at a source file and it opens as a highlighted listing:
+
+    sdoc app.rb
+    sdoc server.js
+    sdoc main.go
+
+  The file travels in the URL like any document; nothing is uploaded. The
+  fence label is chosen from the extension (.rb -> ruby, .py -> python,
+  .ts -> typescript, and so on). Markdown and plain text open as documents,
+  not as code.
+
+ANNOTATIONS (walk someone through the code)
+  Pin a markdown explanation to a line as you open the file:
+
+    sdoc app.py 22:"this method is where the bug is"
+    sdoc app.py 25-28:"the equality check compares the **wrong** value"
+
+  Each note renders as a callout below its line (a range stripes the lines it
+  covers), with markdown inside - bold, inline code, links. They ride in the
+  link and through \`sdoc share\`, and never touch the source file. This is for
+  an agent explaining code to the reader; the in-browser comment mode
+  (--comment) is the reverse - the reader's own review notes.
+
+COMMENTS
+  Comments are deliberately prominent - italic, full-contrast colour, a faint
+  tint - rather than the usual muted grey, so the human explanation in a
+  listing is the easiest part to read.
+
+STYLING
+  Token colours track the light/dark theme. The block background follows the
+  same control as other code blocks (Blocks / Code in the style panel).
+
+SUPPORTED LANGUAGES
+  The common set ships in the core bundle (javascript, typescript, python,
+  ruby, go, rust, java, c, cpp, csharp, php, bash, sql, yaml, json, xml,
+  css, and more). Less common languages are fetched on demand the first time
+  they appear. An unknown language label renders as plain text.
+`;
+
+module.exports = { HELP, COMMENTS_HELP, SCHEMA, CHARTS_HELP, DIAGRAMS_HELP, VIDEOS_HELP, CELLS_HELP, CODE_HELP, SLIDES_HELP, SLIDES_CUSTOM_SHAPES_HELP, LIBRARY_HELP };

package/lib/io.js

@@ -3,11 +3,12 @@
 const fs   = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { transcludeCells, isWrappedFile, wrapForDisplay } = require('./cells-transclude');
+const { transcludeCells } = require('./cells-transclude');
+const { isWrappedFile, wrapForDisplay } = require('./file-wrap');
 
 const SUBCOMMANDS = new Set([
   'new', 'share', 'schema', 'defaults', 'help', 'version',
-  'charts', 'diagrams', 'cells', 'comments',
+  'charts', 'diagrams', 'videos', 'video', 'cells', 'code', 'comments',
   'setup', 'safe', 'auto-update', 'refresh', 'upgrade',
   'bridge', 'feedback',
   'slides', 'present',
@@ -20,6 +21,14 @@ const SUBCOMMANDS = new Set([
 // front matter is the only place SDocs stores tags.
 const TAG_ARG = /^\+[A-Za-z][\w-]{0,63}$/;
 
+// Agent annotation arguments: `N:"text"` or `N-M:"text"` (the shell removes the
+// quotes, so the token arrives as `22:this is the bug`). Line numbers are
+// 1-based, matching what the reader sees in the gutter. Collected into an
+// annotations list and written into the opened file's front matter so they
+// travel with the link. The part before the colon must be digits (an optional
+// range), so file paths like `app.py` never match.
+const ANNOTATION_ARG = /^(\d+)(?:-(\d+))?:([\s\S]+)$/;
+
 function parseArgs(argv) {
   const args = argv || process.argv.slice(2);
   let file = null;
@@ -46,6 +55,7 @@ function parseArgs(argv) {
   let dryRunFlag = false;
   let sheetName = null;
   const addTags = [];
+  const annotations = [];
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -108,6 +118,20 @@ function parseArgs(argv) {
     // front matter at open time.
     if (TAG_ARG.test(arg)) { addTags.push(arg.slice(1).toLowerCase()); continue; }
 
+    // Agent annotation: `N:"text"` / `N-M:"text"`. Captured before the file /
+    // extra slots so a `22:...` token is never mistaken for a path.
+    const ann = ANNOTATION_ARG.exec(arg);
+    if (ann) {
+      const start = parseInt(ann[1], 10);
+      const end = ann[2] ? parseInt(ann[2], 10) : start;
+      // Strip one layer of surrounding quotes if a shell preserved them.
+      const text = ann[3].replace(/^"([\s\S]*)"$/, '$1').replace(/^'([\s\S]*)'$/, '$1');
+      if (start >= 1 && end >= start && text.trim()) {
+        annotations.push({ line: start, endLine: end, text });
+      }
+      continue;
+    }
+
     if (!file) { file = arg; continue; }
     // Second positional is captured as `extra` so `sdoc slides icons heart`
     // gets {subcommand: 'slides', file: 'icons', extra: 'heart'}.
@@ -120,7 +144,7 @@ function parseArgs(argv) {
     messageText, connectTimeoutS, idleTimeoutS, reconnectGraceMs,
     keepOpenFlag, logFile,
     tagsFlag, helpFlag, yesFlag, dryRunFlag, sheetName,
-    addTags,
+    addTags, annotations,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs-dev",
-  "version": "1.13.1",
+  "version": "1.14.1",
   "description": "Open, share, and style markdown files from the terminal",
   "main": "bin/sdocs-dev.js",
   "bin": {
@@ -26,7 +26,7 @@
     "agents"
   ],
   "author": "Josh Summers",
-  "license": "MIT",
+  "license": "Elastic-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/espressoplease/smalldocs.git"

package/shared/sdocs-cells.js

@@ -112,6 +112,20 @@
     return meta;
   }
 
+  // Split a fence info string (everything after "cells ") into a workbook id
+  // and a sheet name. The first "/" separates them: "financials/Model" ->
+  // workbook "financials", name "Model". No slash -> default workbook "" and
+  // the whole string is the name. Everything after the first "/" is the name
+  // verbatim, so a sheet name may contain slashes; a workbook id may not. This
+  // is the one place both the browser renderer and the CLI split the fence, so
+  // the two never drift.
+  function parseFenceInfo(rest) {
+    var s = String(rest == null ? '' : rest).trim();
+    var slash = s.indexOf('/');
+    if (slash < 0) return { workbook: '', name: s };
+    return { workbook: s.slice(0, slash).trim(), name: s.slice(slash + 1).trim() };
+  }
+
   // 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
@@ -130,7 +144,7 @@
     // `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 source, range, formats, name, workbook;
     var lines = trimmed.split('\n');
     var idx = 0;
     var FORMAT_RE = /^format:\s*(.*)$/i;
@@ -141,7 +155,8 @@
         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 };
+        if (meta.workbook != null) workbook = meta.workbook;
+        if (meta.error) return { empty: false, error: meta.error, source: source, name: name, workbook: workbook };
         idx++; continue;
       }
       if (fm) { formats = parseFormats(fm[1]); idx++; continue; }
@@ -151,8 +166,8 @@
 
     // 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 };
+    if (ref) return { empty: false, unresolved: ref[1], formats: formats, name: name, workbook: workbook };
+    if (body === '') return { rows: 0, cols: 0, cells: [], empty: true, source: source, range: range, formats: formats, name: name, workbook: workbook };
 
     var raw = parseCsv(body);
     var cols = 0;
@@ -168,7 +183,7 @@
       }
       cells.push(out);
     }
-    return { rows: raw.length, cols: cols, cells: cells, empty: false, source: source, range: range, formats: formats, name: name };
+    return { rows: raw.length, cols: cols, cells: cells, empty: false, source: source, range: range, formats: formats, name: name, workbook: workbook };
   }
 
   // Serialize a 2D array of raw cell strings back to CSV (RFC 4180 quoting:
@@ -378,6 +393,7 @@
   exports.classify = classify;
   exports.parseCsv = parseCsv;
   exports.parseCells = parseCells;
+  exports.parseFenceInfo = parseFenceInfo;
   exports.serializeCsv = serializeCsv;
   exports.selectionStats = selectionStats;
   exports.formatNumber = formatNumber;