@entropicwarrior/sdoc 0.2.14 → 0.2.16

package/docs/reference/sdoc-authoring.sdoc

@@ -384,8 +384,11 @@ Content of Section B.
                 \`\{!text!\}\` | Warning marker (orange)
                 \`\{-text-\}\` | Negative marker (red)
                 \`\{~text~\}\` | Highlight (yellow)
+                \`#1a73e8\` | Hex color swatch (auto-readable text)
             }
 
+            Hex color codes (\`#rgb\`, \`#rgba\`, \`#rrggbb\`, \`#rrggbbaa\`) render as inline swatches — a rounded box filled with the color and labelled with the code, with the text color chosen automatically (black or white) for legibility. They are detected in normal text, list items, table cells, and headings, but not inside \`\\\`inline code\\\`\` (which stays literal). A bare \`#\` at the start of a line is a heading; escape with \`\\#\` to keep a literal hash.
+
             Links: \`[Link text](https://example.com)\` or \`[Other doc](./other-file.sdoc)\`. Relative paths resolve from the document's directory.
 
             Images: \`![Alt text](path/to/image.png)\`

package/docs/reference/slide-authoring.sdoc

@@ -239,6 +239,84 @@
         }
     }
 
+    # Drilldown Slides @drilldown
+    {
+        A slide deck is normally a 1D spine: Right and Left move along it. A
+        spine slide can also have *vertical detail slides* — extra material
+        you can pull up on demand without cluttering the main flow. Mark a
+        child scope with the `:detail` annotation and it becomes a vertical
+        slide under its parent.
+
+        # Syntax @drilldown-syntax
+        {
+            ```
+            # ETHyR Mechanism @ethyr {
+                Main spine content.
+
+                # PCR primer @pcr :detail {
+                    Detail slide one.
+                }
+
+                # HCR primer @hcr :detail {
+                    Detail slide two.
+                }
+
+                # Notes @notes {
+                    Speaker notes still work alongside details.
+                }
+            }
+            ```
+
+            A detail slide is a regular slide. It can have its own `config:
+            center`, two-column layout, speaker `@notes`, and any other slide
+            content. Drilldowns do not nest further: a `:detail` inside a
+            `:detail` is treated as a plain nested scope.
+        }
+
+        # Navigation @drilldown-navigation
+        {
+            Right — advance one step. From a spine slide, move to the next
+            spine. From a detail slide, advance to the next detail in the
+            same column; at the last detail, return to the parent spine and
+            advance to the next spine (reveal.js convention).
+
+            Left — mirror of Right. From a detail, previous detail or back
+            to parent spine; from spine, previous spine.
+
+            Down — drill into the first detail of the current spine; from
+            within a column, advance to the next detail.
+
+            Up — return from a detail to its parent spine. No-op on a spine.
+
+            Swipe — horizontal swipes mirror Left / Right; vertical swipes
+            mirror Up / Down.
+
+            URL hash — spine slides use `#N`; detail K of spine N uses
+            `#N.K`.
+        }
+
+        # Visual Affordances @drilldown-visual
+        {
+            Spine slides that have detail children get the
+            `slide-has-details` class — the default theme shows a small
+            animated chevron at the bottom of the slide. Themes can replace
+            this rule to fit their own visual language.
+
+            Every slide also gets a `.slide-indicator` element in the
+            bottom-right corner: `5 / 14` on a spine, `5.2 / 14` on detail 2
+            of slide 5. The denominator is always the spine count, so the
+            indicator stays stable as you drill in.
+        }
+
+        # PDF Export @drilldown-pdf
+        {
+            PDF export flattens the deck: spine 1, its details in order,
+            spine 2, its details in order, and so on. This is the same order
+            slides appear in the HTML, so PDF export needs no special case —
+            every slide is just one page.
+        }
+    }
+
     # Theme System @themes
     {
         Themes control the visual appearance of slides. A theme is a directory
@@ -269,17 +347,23 @@
         {
             All themes include these controls by default:
 
-            Arrow right or Space — next slide.
+            Arrow right or Space — next slide (or next detail).
+
+            Arrow left — previous slide (or previous detail).
+
+            Arrow down — drill into details (if any).
 
-            Arrow left — previous slide.
+            Arrow up — return from details to the spine slide.
 
             Home — first slide.
 
-            End — last slide.
+            End — last spine slide.
 
-            Touch swipe left/right on mobile devices.
+            Touch swipe horizontal / vertical on mobile devices.
 
-            Slide counter shown in the bottom-right corner.
+            Slide counter (`.slide-indicator`) shown in the bottom-right
+            corner — `N / TOTAL` on spine slides, `N.K / TOTAL` on detail K
+            of spine N. See [Drilldown Slides](#drilldown) for details.
         }
     }
 

package/lexica/specification.sdoc

@@ -719,12 +719,15 @@ Content of Section B.
                 - Warning marker: `{!text!}` (orange highlight)
                 - Negative marker: `{-text-}` (red highlight)
                 - Highlight: `{~text~}` (yellow highlight)
+                - Hex color swatch: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` (e.g. `#9aa0a8`) renders as a filled inline box labelled with the code
                 - Citation reference: `[@key]` (numbered superscript link to citation entry)
                 - Multiple citation references: `[@key1, @key2]` (each individually linked)
             }
 
             Inline math requires non-whitespace immediately after the opening `$` and before the closing `$`. A plain `$` followed by a digit (e.g. `$100`) does not trigger math mode because there is no closing `$`.
 
+            Hex color swatches are detected only when the `#` is at the start of the inline text or preceded by a non-alphanumeric character, the digit run is exactly 3, 4, 6, or 8 hexadecimal digits, and it is not immediately followed by another letter, digit, or underscore. The background is the literal color and the text color (black or white) is chosen by perceptual brightness (YIQ); for `#rgba`/`#rrggbbaa` the alpha channel is ignored when choosing the text color. Hex inside `` `inline code` `` stays literal, and a `#` at the start of a line is parsed as a heading (escape with `\#`).
+
             Citation references (`[@key]`) are parsed before link syntax. `[@key]` is always a citation reference even if followed by `(url)`. Use `\[@key]` for a literal `[@key]` in text.
         }
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC - Docs for Human/Agent Teams",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -1414,6 +1414,21 @@ function parseInline(text) {
       }
     }
 
+    // Hex color codes (#rgb, #rgba, #rrggbb, #rrggbbaa) render as swatches.
+    // Require a non-word char before the # so we don't match inside identifiers,
+    // and a non-word char after the digits so partial/over-long runs are ignored.
+    if (ch === "#" && (i === 0 || !/[0-9A-Za-z]/.test(text[i - 1]))) {
+      const m = /^#([0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})(?![0-9A-Za-z_])/.exec(
+        text.slice(i)
+      );
+      if (m) {
+        flush();
+        nodes.push({ type: "color_swatch", value: m[0] });
+        i += m[0].length;
+        continue;
+      }
+    }
+
     if (ch === "{") {
       const mc = next;
       let mt = null;
@@ -1728,6 +1743,46 @@ function escapeAttr(value) {
   return escapeHtml(value).replace(/'/g, "'");
 }
 
+// Expand a #rgb/#rgba/#rrggbb/#rrggbbaa hex string to [r, g, b] (alpha ignored).
+function hexToRgb(hex) {
+  let h = hex.replace(/^#/, "");
+  if (h.length === 3 || h.length === 4) {
+    h = h.slice(0, 3).split("").map((c) => c + c).join("");
+  } else {
+    h = h.slice(0, 6);
+  }
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16),
+  ];
+}
+
+// Pick black or white text for legibility over the given background color
+// using the perceptual YIQ brightness threshold.
+function readableTextColor(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  const yiq = (r * 299 + g * 587 + b * 114) / 1000;
+  return yiq >= 128 ? "#000000" : "#ffffff";
+}
+
+// Render a hex color as a self-contained inline swatch: a rounded box filled
+// with the color, labelled with the hex code in a legible text color. Styling
+// is inline so it survives in slides, exports, and other CSS-free contexts.
+function colorSwatchHtml(value) {
+  const fg = readableTextColor(value);
+  // A soft neutral-grey outline on every swatch (the same for all of them) so
+  // the box edge stays visible even when the fill matches the page background.
+  // Semi-transparent grey reads on both light and dark backgrounds without the
+  // harsh contrast of a black/white border.
+  const style =
+    `background-color:${value};color:${fg};` +
+    "border:1px solid rgba(128,128,128,0.5);border-radius:4px;padding:0.15em 0.9em;" +
+    "font-family:'JetBrains Mono','Fira Code','Source Code Pro',monospace;font-size:0.95em;" +
+    "-webkit-print-color-adjust:exact;print-color-adjust:exact";
+  return `<span class="sdoc-color-swatch" style="${style}">${escapeHtml(value)}</span>`;
+}
+
 function renderInline(text) {
   const nodes = parseInline(text);
   return renderInlineNodes(nodes);
@@ -1766,6 +1821,8 @@ function renderInlineNodes(nodes) {
         }
         case "code":
           return `<code class="sdoc-inline-code">${escapeHtml(node.value)}</code>`;
+        case "color_swatch":
+          return colorSwatchHtml(node.value);
         case "em":
           return `<em>${renderInlineNodes(node.children)}</em>`;
         case "strong":
@@ -3773,5 +3830,7 @@ module.exports = {
   renderKatex,
   escapeHtml,
   escapeAttr,
-  sanitizeSvg
+  sanitizeSvg,
+  colorSwatchHtml,
+  readableTextColor
 };

package/src/slide-renderer.js

@@ -7,7 +7,7 @@
 //   const { nodes, meta } = extractMeta(parsed.nodes);
 //   const html = renderSlides(nodes, { meta, themeCss, themeJs });
 
-const { parseInline, renderKatex, escapeHtml, escapeAttr, sanitizeSvg } = require("./sdoc");
+const { parseInline, renderKatex, escapeHtml, escapeAttr, sanitizeSvg, colorSwatchHtml } = require("./sdoc");
 
 // ---------------------------------------------------------------------------
 // Inline rendering — produces clean HTML without sdoc-* classes
@@ -21,6 +21,8 @@ function renderInlineNodes(nodes) {
           return escapeHtml(node.value);
         case "code":
           return `<code>${escapeHtml(node.value)}</code>`;
+        case "color_swatch":
+          return colorSwatchHtml(node.value);
         case "em":
           return `<em>${renderInlineNodes(node.children)}</em>`;
         case "strong":
@@ -206,18 +208,45 @@ function extractNotes(children) {
   return { notes, contentNodes: rest };
 }
 
+// Separates :detail child scopes (drilldown / vertical slides) from other
+// children. Detail scopes are NOT removed from rendering; they are emitted as
+// sibling slides positioned vertically under the spine slide.
+function extractDetails(children) {
+  const details = [];
+  const rest = [];
+  for (const child of children) {
+    if (child.type === "scope" && child.scopeType === "detail") {
+      details.push(child);
+    } else {
+      rest.push(child);
+    }
+  }
+  return { details, contentNodes: rest };
+}
+
 // ---------------------------------------------------------------------------
 // Slide rendering
 // ---------------------------------------------------------------------------
 
-function renderSlide(scope, slideIndex, overlayHtml) {
-  const { config, contentNodes: afterConfig } = extractSlideConfig(scope.children);
+// position: { spine: 1-based spine index, detail: 0 for spine, 1..N for details,
+//             totalSpines: total number of spine slides, hasDetails: bool (spine only) }
+function renderSlide(scope, slideIndex, overlayHtml, position) {
+  // Pull :detail children out first so they don't appear inline in the spine
+  // slide's content; they're rendered as sibling vertical slides instead.
+  const { contentNodes: afterDetails } = extractDetails(scope.children);
+  const { config, contentNodes: afterConfig } = extractSlideConfig(afterDetails);
   const { notes, contentNodes } = extractNotes(afterConfig);
 
   const classes = ["slide"];
   if (config.layout) {
     classes.push(config.layout);
   }
+  if (position && position.detail === 0 && position.hasDetails) {
+    classes.push("slide-has-details");
+  }
+  if (position && position.detail > 0) {
+    classes.push("slide-detail");
+  }
 
   const title = scope.hasHeading !== false && scope.title
     ? `<h2>${renderInline(scope.title)}</h2>`
@@ -248,9 +277,25 @@ function renderSlide(scope, slideIndex, overlayHtml) {
     : "";
 
   const idAttr = scope.id ? ` id="${escapeAttr(scope.id)}"` : "";
-  const overlay = overlayHtml || "";
 
-  return `<div class="${classes.join(" ")}"${idAttr}>\n${title}\n${bodyHtml}${notesHtml}${overlay}\n</div>`;
+  // Drilldown metadata + slide indicator label (substituted into the footer)
+  let dataAttrs = "";
+  let indicatorLabel = "";
+  if (position) {
+    dataAttrs = ` data-spine="${position.spine}" data-detail="${position.detail}"`;
+    const denom = position.totalSpines;
+    indicatorLabel = position.detail === 0
+      ? `${position.spine} / ${denom}`
+      : `${position.spine}.${position.detail} / ${denom}`;
+  }
+  const overlay = (overlayHtml || "").replace("__SLIDE_INDICATOR__", escapeHtml(indicatorLabel));
+
+  // Wrap title + body in a scale container so PDF export can apply
+  // transform: scale() to fit the content onto a fixed page size.  In
+  // screen mode the wrapper is display:contents (invisible to layout); in
+  // print mode it becomes a real block that the beforeprint handler can
+  // measure and scale.
+  return `<div class="${classes.join(" ")}"${idAttr}${dataAttrs}>\n<div class="slide-content-scale">\n${title}\n${bodyHtml}\n</div>${notesHtml}${overlay}\n</div>`;
 }
 
 // ---------------------------------------------------------------------------
@@ -277,7 +322,11 @@ function renderSlides(nodes, options = {}) {
   // Filter to scope nodes only (skip stray paragraphs and :comment scopes)
   const slides = slideScopes.filter((n) => n.type === "scope" && n.scopeType !== "comment");
 
-  // Build per-slide footer: <  CONFIDENTIAL  ---gap---  Company  >
+  // Build per-slide footer:
+  //   <  CONFIDENTIAL  ---gap---  Company  N/Total  >
+  // The indicator slot is rendered as a literal token here and substituted
+  // per-slide inside renderSlide() so all the right-edge elements share one
+  // flexbox row (avoids the page number stacking on top of the company name).
   const footerParts = [];
   footerParts.push(`<span class="nav-prev">&lsaquo;</span>`);
   if (meta.confidential) {
@@ -292,11 +341,42 @@ function renderSlides(nodes, options = {}) {
   if (meta.company) {
     footerParts.push(`<span class="sdoc-company-footer">${escapeHtml(meta.company)}</span>`);
   }
+  footerParts.push(`<span class="slide-indicator">__SLIDE_INDICATOR__</span>`);
   footerParts.push(`<span class="nav-next">&rsaquo;</span>`);
   const overlayHtml = `\n<div class="slide-footer">${footerParts.join("")}</div>`;
 
-  const slidesHtml = slides
-    .map((scope, index) => renderSlide(scope, index, overlayHtml))
+  // Build a flat emission order: each spine slide, followed immediately by its
+  // :detail children in source order. The flat order matches what we want for
+  // PDF export, so PDF needs no special case.
+  const totalSpines = slides.length;
+  const emitted = [];
+  slides.forEach((scope, i) => {
+    const spineIndex = i + 1; // 1-based
+    const { details } = extractDetails(scope.children);
+    emitted.push({
+      scope,
+      position: {
+        spine: spineIndex,
+        detail: 0,
+        totalSpines,
+        hasDetails: details.length > 0
+      }
+    });
+    details.forEach((detail, j) => {
+      emitted.push({
+        scope: detail,
+        position: {
+          spine: spineIndex,
+          detail: j + 1,
+          totalSpines,
+          hasDetails: false
+        }
+      });
+    });
+  });
+
+  const slidesHtml = emitted
+    .map(({ scope, position }, index) => renderSlide(scope, index, overlayHtml, position))
     .join("\n\n");
 
   const title = meta.properties?.title
@@ -327,19 +407,39 @@ function renderSlides(nodes, options = {}) {
   color: rgba(160, 40, 40, 0.6);
   margin-left: 0.8em;
 }
+.slide-indicator {
+  font-size: 0.7em; color: rgba(0,0,0,0.35);
+  font-variant-numeric: tabular-nums;
+  letter-spacing: 0.04em;
+  pointer-events: none;
+  user-select: none;
+  margin-right: 0.6em;
+}
+/* Scale wrapper: invisible to layout in screen mode so existing slide
+   styles (flex centering, two-column grid, etc.) work as-is.  In print
+   mode it becomes a real block element whose transform is set by the
+   beforeprint handler to shrink overflowing content to fit the page. */
+.slide-content-scale { display: contents; }
+
 @media print {
   @page { size: 13.333in 7.5in; margin: 0; }
   body { overflow: visible; height: auto; }
   .slide {
-    display: flex !important;
+    display: block !important;
     position: relative !important;
     opacity: 1 !important;
     pointer-events: auto !important;
     page-break-after: always; break-after: page;
     width: 100vw; height: 100vh; max-width: none;
+    overflow: hidden;
     page-break-inside: avoid; break-inside: avoid;
   }
   .slide:last-child { page-break-after: auto; break-after: auto; }
+  .slide-content-scale {
+    display: block;
+    width: 100%;
+    transform-origin: top left;
+  }
   .nav-prev, .nav-next { display: none !important; }
   .notes { display: none; }
 }`;
@@ -359,6 +459,7 @@ blockquote p { color: #9d9d9d; }
 .nav-prev, .nav-next { color: rgba(255, 255, 255, 0.7); }
 .sdoc-company-footer { color: rgba(255, 255, 255, 0.35); }
 .sdoc-confidential-notice { color: rgba(235, 120, 120, 0.7); }
+.slide-indicator { color: rgba(255, 255, 255, 0.35); }
 ` : "";
 
   const cssTag = `<style>\n${structuralCss}\n${themeCss}\n${darkCss}</style>`;

package/tools/build-doc.js

@@ -135,7 +135,7 @@ async function buildHtml(filePath, options = {}) {
 
   const title = path.basename(resolvedPath, ".sdoc");
 
-  return renderHtmlDocumentFromParsed(
+  const html = renderHtmlDocumentFromParsed(
     { nodes: metaResult.nodes, errors: parsed.errors },
     title,
     {
@@ -146,6 +146,41 @@ async function buildHtml(filePath, options = {}) {
       includeAbout,
     }
   );
+
+  // Inline local images as data URIs so output is self-contained. PDF export
+  // renders from a temp directory, where relative image paths (e.g.
+  // diagrams/foo.svg) no longer resolve; inlining also makes HTML portable.
+  return inlineLocalImages(html, docDir);
+}
+
+const IMAGE_MIME = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+
+function inlineLocalImages(html, docDir) {
+  return html.replace(/(<img\b[^>]*?\bsrc=")([^"]*)(")/gi, (match, pre, src, post) => {
+    // Leave remote URLs and already-inlined data URIs untouched.
+    if (/^(https?:|data:|file:)/i.test(src)) return match;
+    const decoded = src.replace(/&amp;/g, "&");
+    const ext = path.extname(decoded).toLowerCase();
+    const mime = IMAGE_MIME[ext];
+    if (!mime) return match;
+    const abs = path.isAbsolute(decoded) ? decoded : path.join(docDir, decoded);
+    let data;
+    try {
+      data = fs.readFileSync(abs);
+    } catch {
+      console.error(`Warning: could not inline image (not found): ${decoded}`);
+      return match;
+    }
+    const uri = `data:${mime};base64,${data.toString("base64")}`;
+    return `${pre}${uri}${post}`;
+  });
 }
 
 async function main() {
@@ -197,6 +232,7 @@ async function main() {
       outputPath = resolvedInput.replace(/\.sdoc$/i, "") + ".pdf";
     }
     const resolvedOutput = path.resolve(outputPath);
+    fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true });
 
     // Write HTML to temp file for Chrome
     const tmpHtml = path.join(os.tmpdir(), "sdoc-doc-" + Date.now() + ".html");