sdocs-dev 1.14.1 → 1.15.0

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 = 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_VERSION = 13;
+const AGENT_BLOCK_REASON  = 'Agent annotations now render as a guided code walkthrough: each note is a callout below its line with a Prev/Next stepper, walked in the order the notes are passed (not line order), and naming several files (sdoc app.py 5:"..." util.py 12:"..." app.py 9:"...") narrates across them as tabs the walk hops between. The `sdoc code` bullet gains this multi-file walkthrough description plus a trigger to build one when the user asks to be walked through code, an MR, a diff, or the current changes. Only the `sdoc code` bullet changed from v12.';
 
 const AGENT_BLOCK_BODY = `## SmallDocs
 
@@ -49,7 +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 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:"the bug is here" 25-28:"wrong comparison"\` - and the file opens as a guided walkthrough: each note is a markdown callout below its line with a Prev / Next stepper, walked in the order you pass the notes (not line order). Name several files to narrate across them - \`sdoc app.py 5:"entry point" util.py 12:"it calls into here" app.py 9:"back here"\` - and each becomes a tab the walkthrough hops between. When the user asks you to walk them through code, an MR, a diff, or the current changes, build one of these. 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/code-langs.js

@@ -72,9 +72,15 @@ function isCodeFile(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) {
+//
+// `label` (optional) is appended to the fence info string after the language,
+// e.g. wrapCodeFile(src, 'app.py', 'app.py') -> ```python app.py. A multi-file
+// code walkthrough uses this so the browser can name each tab; a plain single
+// `sdoc app.py` passes no label and the fence stays ```python.
+function wrapCodeFile(raw, filePath, label) {
   var lang = langForFile(filePath);
-  return '```' + lang + '\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
+  var info = label ? (lang + ' ' + String(label).trim()) : lang;
+  return '```' + info + '\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
 }
 
 module.exports = {

package/lib/commands.js

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 const SDocYaml = require('../shared/sdocs-yaml.js');
 
 const { DEFAULT_URL } = require('./constants');
-const { readContent, openBrowser } = require('./io');
+const { readContent, readCodewalkContent, openBrowser } = require('./io');
 const { loadDefaultStyles, applyDefaultStyles, showDefaults, resetDefaults } = require('./styles');
 const { buildUrl } = require('./url');
 const { buildShortUrl } = require('./short-link');
@@ -28,7 +28,78 @@ async function postCommandHooks() {
 // Load content (file or stdin), apply ~/.sdocs/styles.yaml defaults, inject
 // `file:` into front matter, and build either a hash URL or a short URL.
 // Returns { url, contentPresent }.
+// Build a hash URL (or short URL for `share --short`) from finished content.
+// Shared by the single-file and the code-walkthrough paths so both honour
+// `--short`, mode, theme, section, and present identically.
+async function finishUrl(opts, content, local, defaults) {
+  if (opts.shortFlag) {
+    if (opts.subcommand !== 'share') {
+      console.error('sdoc: --short is only valid with the `share` subcommand');
+      process.exit(1);
+    }
+    if (!content) {
+      console.error('sdoc: --short needs content (a file path or piped stdin)');
+      process.exit(1);
+    }
+    try {
+      const url = await buildShortUrl(content, {
+        url: opts.url, mode: opts.mode, theme: opts.theme, section: opts.section,
+      });
+      return { url, contentPresent: !!content };
+    } catch (e) {
+      console.error('sdoc: could not create short link -', e.message);
+      process.exit(1);
+    }
+  }
+  const url = buildUrl(content, {
+    url: opts.url,
+    mode: opts.mode,
+    theme: opts.theme,
+    defaultStyles: !content ? defaults : null,
+    section: opts.section,
+    local,
+    present: opts.present,
+  });
+  return { url, contentPresent: !!content };
+}
+
+// `sdoc file1.py 4:"..." file2.py 13:"..."` — two or more source files become
+// one code-walkthrough document: a tabbed multi-file view whose annotations
+// step in command order across the tabs. The browser keys off `codewalk: true`
+// in front matter. Front matter carries only basenames, so it is share-safe.
+async function prepareCodewalkUrl(opts) {
+  const { body, files } = readCodewalkContent(opts.files);
+
+  const meta = { codewalk: true, files };
+  const anns = (opts.annotations || []).map((a) => {
+    // Bind to the cursor file's basename; fall back to the first tab when an
+    // annotation was given before any file (or its file dropped out).
+    let base = a.file ? path.basename(a.file) : files[0];
+    if (files.indexOf(base) === -1) base = files[0];
+    return { file: base, line: a.line, endLine: a.endLine, text: a.text };
+  });
+  if (anns.length) meta.annotations = anns;
+
+  let content = SDocYaml.serializeFrontMatter(meta) + '\n' + body;
+  const defaults = loadDefaultStyles();
+  if (defaults) content = applyDefaultStyles(content);
+
+  // local (the edit-this-file affordance) is single-file today; the
+  // walkthrough renders entirely from the shared front matter for now.
+  return finishUrl(opts, content, null, defaults);
+}
+
 async function prepareUrl(opts) {
+  // Annotations render as a walkthrough: a tabbed tour for 2+ files, a single-
+  // tab stepper for one. A plain `sdoc app.py` with no annotations stays the
+  // ordinary single-file view. Walkthrough order is the order the annotations
+  // were given on the command line, not their line order.
+  const files = opts.files || [];
+  const anns = opts.annotations || [];
+  if (files.length > 1 || (files.length >= 1 && anns.length > 0)) {
+    return prepareCodewalkUrl(opts);
+  }
+
   let content = await readContent(opts.file);
   const defaults = loadDefaultStyles();
   if (content && defaults) {
@@ -45,7 +116,10 @@ async function prepareUrl(opts) {
     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;
+      // A single file needs no per-annotation `file` binding — drop it so the
+      // serialized shape stays {line, endLine, text}. (Multi-file keeps it, in
+      // prepareCodewalkUrl.)
+      parsed.meta.annotations = opts.annotations.map(({ file, ...rest }) => rest);
       changed = true;
     }
     if (changed) {
@@ -65,40 +139,7 @@ async function prepareUrl(opts) {
     }
   }
 
-  let url;
-  if (opts.shortFlag) {
-    if (opts.subcommand !== 'share') {
-      console.error('sdoc: --short is only valid with the `share` subcommand');
-      process.exit(1);
-    }
-    if (!content) {
-      console.error('sdoc: --short needs content (a file path or piped stdin)');
-      process.exit(1);
-    }
-    try {
-      url = await buildShortUrl(content, {
-        url: opts.url,
-        mode: opts.mode,
-        theme: opts.theme,
-        section: opts.section,
-      });
-    } catch (e) {
-      console.error('sdoc: could not create short link -', e.message);
-      process.exit(1);
-    }
-  } else {
-    url = buildUrl(content, {
-      url: opts.url,
-      mode: opts.mode,
-      theme: opts.theme,
-      defaultStyles: !content ? defaults : null,
-      section: opts.section,
-      local,
-      present: opts.present,
-    });
-  }
-
-  return { url, contentPresent: !!content };
+  return finishUrl(opts, content, local, defaults);
 }
 
 // Default flow: `sdoc <file>` or `sdoc` (no args, or piped stdin).

package/lib/help-text.js

@@ -1316,6 +1316,20 @@ navigate.
   template), keep these in mind - they're the difference between a
   deck that lands and one that doesn't.
 
+  Templates for scratch, custom layout for anything seen. The
+  built-in templates are the fast path: legible, consistent, and
+  well suited to fast information transfer - an internal review, a
+  working draft, a deck you will talk over. They are not built for
+  an audience that cares about feel, so a deck made only from them
+  reads as functional rather than designed. For anything
+  external-facing - a client, a conference, a launch, anything with
+  your name on it that you will not be in the room to narrate -
+  compose the deck from raw shapes instead. If you are not sure which
+  setting you are in, ask your user, explaining the trade-off:
+  templates are faster and uniform, raw shapes take longer but let
+  the deck carry a designed look. See \`sdoc slides custom-shapes\`
+  for the shape vocabulary and the design principles that go with it.
+
   Margins. Keep all content inside a 1-unit safe area on every side
   of a 16x9 grid (so x ∈ [1, 15], y ∈ [0.5, 8.5]). Nothing touches
   the slide edge except a deliberate full-bleed background (\`section\`
@@ -1366,9 +1380,54 @@ navigate.
   A bulleted paragraph is hiding the fact that you haven't decided
   what you're claiming.
 
-  When in doubt, \`@extends\` a built-in template instead of
-  composing from raw shapes. Run \`sdoc slides list\` to see the
-  registry.
+  When the deck is internal or you only need it to read clearly,
+  \`@extends\` a built-in template instead of composing from raw
+  shapes - run \`sdoc slides list\` to see the registry. Reach for
+  raw shapes when the deck will be seen by an audience and the
+  default beat is not enough; the guidelines above are what keep
+  that hand-built deck on the professional side of the line. If a
+  custom layout repeats across slides, define it once as your own
+  \`@template\` and \`@extends\` it - the consistency of a template
+  with a look you designed.
+
+\u2500\u2500 VERIFYING A DECK (OPTIONAL, BUT IT IS WHAT SEPARATES CLEAN FROM BROKEN) \u2500\u2500
+  You are authoring slides you cannot see. You place coordinates and
+  trust them, and the renderer does not warn you when a shape covers
+  text, when a label wraps to a line you did not intend, when text sits
+  on a fill it cannot be read against, or when an arrow lands in empty
+  space. Templates mostly avoid this; hand-placed raw shapes do not.
+  The single most effective check is to look at the rendered result and
+  fix what you see.
+
+  If you have a way to render a page to an image - a headless browser
+  you can drive (Playwright or Puppeteer in headless mode, a headless
+  system Chrome), or any screenshot tool in your environment - use it.
+  Open the deck, capture the slides, look, fix the DSL, and render
+  again. Two or three passes turns a deck with hidden text and clipped
+  labels into one that reads cleanly. When you render, check each slide
+  for:
+    - text covered by a shape drawn after it (source order is paint order)
+    - text with poor contrast against whatever is actually painted under it
+    - labels that wrap or overflow their box
+    - connectors (l / a) that float short of, or pierce, what they join
+    - a composition that sits low, high, or lopsided in the frame
+
+  The CLI does not bundle a browser - it has no runtime dependencies on
+  purpose - so this check is something you bring from your environment,
+  not something sdoc installs. If you do not have a headless browser and
+  you judge that rendering would catch real problems, you can ask your
+  user to install one (for example \`npx playwright install chromium\`, or
+  to point you at a browser already on the machine) and explain why: a
+  render check catches the text-overlap, contrast, and wrapping faults
+  that are invisible in the markdown source. Leave the decision to them;
+  it is their machine, and the subtleties of what is available are yours
+  to work out in context.
+
+  \`sdoc present <file>\` opens the deck fullscreen for a human to review,
+  which is the right check when a person is in the loop. If you cannot
+  render at all, keep each slide simple enough to verify by arithmetic -
+  list every text shape's box and confirm no later shape's fill overlaps
+  it - and prefer templates for anything you will not be able to see.
 
 \u2500\u2500 FENCE SYNTAX \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   Wrap shape DSL in a ~~~slide fenced block:
@@ -2051,6 +2110,18 @@ rather than as designed.
     overlay text on a single patch of colour (or very closely
     related colours) to keep it straightforwardly legible.
 
+  Attempt to verify what you cannot see.
+    The principles above guide the layout, but a hand-placed shape
+    can still cover text, a label can wrap, or an arrow can miss its
+    target, and none of it shows in the source. If you can drive a
+    headless browser or any screenshot tool in your environment,
+    render the deck and fix what you see before trusting it. If you
+    cannot, it is worth raising with your user - for example, "I
+    would like to use Playwright to verify the slides render
+    correctly, is that okay?" - since a quick render check catches
+    problems the markdown cannot show. See the VERIFYING A DECK
+    section of \`sdoc slides\` for what to look for.
+
 ── 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)
@@ -2931,6 +3002,23 @@ ANNOTATIONS (walk someone through the code)
   an agent explaining code to the reader; the in-browser comment mode
   (--comment) is the reverse - the reader's own review notes.
 
+  Annotations render as a WALKTHROUGH: the file opens in the fullscreen viewer
+  with each note carrying a Prev / Next stepper, so the reader is guided from
+  one note to the next (arrow keys work too; a restart button returns to the
+  start). The steps follow the ORDER YOU PASS THEM, not line order:
+
+    sdoc app.py 10:"start here" 5:"then jump back up here"
+
+  walks to line 10 first, then line 5.
+
+  Pass several files to narrate across them - each becomes a tab, and a step
+  in another file switches to its tab as you walk (a small "-> file" marker
+  shows when a step crosses files):
+
+    sdoc app.py 5:"entry point" util.py 12:"it calls into here" app.py 9:"back"
+
+  Naming a file twice gives one tab; the walk still hops between them in order.
+
 COMMENTS
   Comments are deliberately prominent - italic, full-contrast colour, a faint
   tint - rather than the usual muted grey, so the human explanation in a

package/lib/io.js

@@ -5,6 +5,7 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 const { transcludeCells } = require('./cells-transclude');
 const { isWrappedFile, wrapForDisplay } = require('./file-wrap');
+const codeLangs = require('./code-langs');
 
 const SUBCOMMANDS = new Set([
   'new', 'share', 'schema', 'defaults', 'help', 'version',
@@ -56,6 +57,13 @@ function parseArgs(argv) {
   let sheetName = null;
   const addTags = [];
   const annotations = [];
+  // Multi-file code walkthrough: every source-code positional is collected
+  // into `files`, in command order. `currentFile` is the cursor an annotation
+  // binds to, so `file1.py 4:"x" file2.py 13:"y"` ties line 4 to file1 and
+  // line 13 to file2. The first code file also fills the single-file `file`
+  // slot, so a one-file `sdoc app.py` is unchanged.
+  const files = [];
+  let currentFile = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -127,11 +135,24 @@ function parseArgs(argv) {
       // 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 });
+        // `file` binds the annotation to the most-recently-named code file
+        // (null if none yet — resolved to the only/first file downstream).
+        annotations.push({ line: start, endLine: end, text, file: currentFile });
       }
       continue;
     }
 
+    // A source-code positional (in the default flow, not under a subcommand):
+    // collect it as a walkthrough file and move the annotation cursor onto it.
+    // Subcommand sub-args (e.g. `slides icons`) are never code files, so they
+    // fall through to the file/extra slots below as before.
+    if (!subcommand && codeLangs.isCodeFile(arg)) {
+      files.push(arg);
+      currentFile = arg;
+      if (!file) file = arg;
+      continue;
+    }
+
     if (!file) { file = arg; continue; }
     // Second positional is captured as `extra` so `sdoc slides icons heart`
     // gets {subcommand: 'slides', file: 'icons', extra: 'heart'}.
@@ -144,7 +165,7 @@ function parseArgs(argv) {
     messageText, connectTimeoutS, idleTimeoutS, reconnectGraceMs,
     keepOpenFlag, logFile,
     tagsFlag, helpFlag, yesFlag, dryRunFlag, sheetName,
-    addTags, annotations,
+    addTags, annotations, files,
   };
 }
 
@@ -183,6 +204,38 @@ async function readContent(file) {
   return null; // no content — just open studio
 }
 
+// Read N source files into one code-walkthrough body: each unique file wrapped
+// in a ```<lang> <basename> fence, joined in command order. Returns the body
+// plus the de-duplicated basename list (the tab order). Tabs are keyed by
+// basename — a file named twice on the command line is one tab; two DIFFERENT
+// files sharing a basename is an error rather than a silent merge (and keeps
+// the shared front matter to safe basenames, matching the single-file `file:`).
+function readCodewalkContent(files) {
+  const parts = [];
+  const tabs = [];
+  const byBase = Object.create(null);
+  for (const f of files) {
+    const resolved = path.resolve(f);
+    const base = path.basename(f);
+    if (byBase[base]) {
+      if (byBase[base] !== resolved) {
+        console.error(`sdoc: a code walkthrough needs distinct file names — two files named "${base}"`);
+        process.exit(1);
+      }
+      continue; // same file referenced again → one tab
+    }
+    if (!fs.existsSync(resolved)) {
+      console.error(`sdoc: file not found: ${f}`);
+      process.exit(1);
+    }
+    byBase[base] = resolved;
+    tabs.push(base);
+    const raw = fs.readFileSync(resolved, 'utf-8');
+    parts.push(codeLangs.wrapCodeFile(raw, f, base));
+  }
+  return { body: parts.join('\n'), files: tabs };
+}
+
 function openBrowser(url) {
   try {
     if (process.platform === 'darwin')      execFileSync('open', [url]);
@@ -197,5 +250,6 @@ module.exports = {
   SUBCOMMANDS,
   parseArgs,
   readContent,
+  readCodewalkContent,
   openBrowser,
 };

package/package.json

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