@entropicwarrior/sdoc 0.2.6 → 0.2.8

package/README.md

@@ -29,8 +29,19 @@ Markdown has no formal structure — section boundaries are ambiguous, extractio
 
 ## Quick Start
 
+### Install from the VS Code Marketplace
+
+Search for **"SDOC - Docs for Human/Agent Teams"** by **Entropic Warrior MS Enfin** in the VS Code Extensions panel, or install from the command line:
+
+```bash
+code --install-extension entropicwarrior-msenfin.vscode-sdoc
+```
+
+This gives you automatic updates. If you previously installed from a `.vsix` file, uninstall that version first to avoid conflicts.
+
+### Build from source
+
 ```bash
-# Build and install the VS Code extension
 npm install
 npm run package
 code --install-extension dist/sdoc-*.vsix
@@ -74,7 +85,17 @@ Key resources for agents:
 | [`docs/reference/sdoc-authoring.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/sdoc-authoring.sdoc) | Skill document — drop into context to read/write SDOC immediately |
 | [`lexica/specification.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/specification.sdoc) | Formal spec with EBNF grammar |
 
-All `.sdoc` files are designed for progressive disclosure — read the `@about` scope first (~50 tokens), then scan headings, then load only the section you need.
+All `.sdoc` files are designed for progressive disclosure. The JavaScript API provides three functions that let agents navigate without loading entire files:
+
+```javascript
+const { extractAbout, listSections, extractSection } = require("@entropicwarrior/sdoc");
+
+extractAbout(text);              // ~50 tokens — what is this file about?
+listSections(text);              // ~50-100 tokens — what sections does it have?
+extractSection(text, "error-handling"); // ~200-1000 tokens — give me just this section
+```
+
+Total cost for a precise answer: ~750 tokens. The same lookup in Markdown requires loading the full file (5,000-50,000 tokens).
 
 ## Format at a Glance
 
@@ -159,7 +180,7 @@ Markdown-style images with optional width and alignment:
 
 ### Tables
 
-Pipe-delimited tables with optional flags for appearance (`borderless`, `headerless`), width (`auto`, `60%`, `400px`), and alignment (`left`, `center`, `right`). All flags compose freely.
+Pipe-delimited tables with optional flags for appearance (`borderless`, `headerless`), width (`auto`, `60%`, `400px`), and alignment (`left`, `center`, `right`). All flags compose freely. Cells starting with `=` are evaluated as formulas (`=SUM`, `=AVG`, `=COUNT`, arithmetic with A1 cell references).
 
 ### Lists
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@entropicwarrior/sdoc",
-  "displayName": "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.6",
-  "publisher": "entropicwarrior",
+  "version": "0.2.8",
+  "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/sdoc.js

@@ -2416,6 +2416,54 @@ const DEFAULT_STYLE = `
     pointer-events: none;
   }
 
+  /* Collapsible scope toggles */
+  .sdoc-heading:has(.sdoc-toggle) {
+    position: relative;
+  }
+
+  .sdoc-toggle {
+    position: absolute;
+    left: -1.4em;
+    top: 0;
+    bottom: 0;
+    width: 1.2em;
+    cursor: pointer;
+    opacity: 0;
+    transition: opacity 0.15s;
+  }
+
+  .sdoc-toggle::before {
+    content: '';
+    display: block;
+    width: 0.45em;
+    height: 0.45em;
+    border-right: 2px solid var(--sdoc-muted);
+    border-bottom: 2px solid var(--sdoc-muted);
+    transition: transform 0.15s;
+    transform: rotate(45deg);
+    position: absolute;
+    top: 0.18em;
+    left: 50%;
+    margin-left: -0.3em;
+  }
+
+  .sdoc-scope:hover > .sdoc-heading > .sdoc-toggle {
+    opacity: 1;
+  }
+
+  .sdoc-scope.sdoc-collapsed > .sdoc-heading > .sdoc-toggle {
+    opacity: 0.6;
+  }
+
+  .sdoc-scope.sdoc-collapsed > .sdoc-heading > .sdoc-toggle::before {
+    transform: rotate(-45deg);
+    margin-left: -0.15em;
+  }
+
+  .sdoc-scope.sdoc-collapsed > .sdoc-scope-children {
+    display: none;
+  }
+
 `;
 
 const PRINT_STYLE = `
@@ -2447,9 +2495,12 @@ const PRINT_STYLE = `
     html {
       font-size: 80%;
     }
-    .sdoc-copy-btn {
+    .sdoc-copy-btn, .sdoc-toggle {
       display: none;
     }
+    .sdoc-scope.sdoc-collapsed > .sdoc-scope-children {
+      display: block;
+    }
     body {
       height: auto;
       overflow: visible;
@@ -2476,6 +2527,10 @@ const PRINT_STYLE = `
   }
 `;
 
+const COLLAPSE_SCRIPT = `document.addEventListener("click",function(e){if(!e.target.classList.contains("sdoc-toggle"))return;e.stopPropagation();var s=e.target.closest(".sdoc-scope");if(s)s.classList.toggle("sdoc-collapsed")});`;
+
+const COPY_SCRIPT = `document.addEventListener("click",function(e){if(!e.target.classList.contains("sdoc-copy-btn"))return;e.stopPropagation();e.preventDefault();var w=e.target.closest(".sdoc-code-wrap");if(!w)return;var c=w.querySelector("code");if(!c)return;var t=c.textContent;var b=e.target;if(navigator.clipboard){navigator.clipboard.writeText(t).then(function(){b.textContent="\\u2713";setTimeout(function(){b.textContent="\\u29C9"},1500)})}else{var a=document.createElement("textarea");a.value=t;a.style.position="fixed";a.style.opacity="0";document.body.appendChild(a);a.select();document.execCommand("copy");document.body.removeChild(a);b.textContent="\\u2713";setTimeout(function(){b.textContent="\\u29C9"},1500)}});`;
+
 const MERMAID_CDN = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js";
 const KATEX_CDN_CSS = "https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.css";
 const HLJS_CDN = "https://cdn.jsdelivr.net/npm/@highlightjs/cdn-assets@11.11.1/highlight.min.js";
@@ -2574,7 +2629,8 @@ function renderHtmlDocumentFromParsed(parsed, title, options = {}) {
 
   const cssBase = options.cssOverride ?? DEFAULT_STYLE;
   const cssAppend = options.cssAppend ? `\n${options.cssAppend}\n${PRINT_STYLE}` : `\n${PRINT_STYLE}`;
-  const scriptTag = options.script ? `\n<script>${options.script}</script>` : "";
+  const builtinScript = COLLAPSE_SCRIPT + COPY_SCRIPT;
+  const scriptTag = options.script ? `\n<script>${options.script}</script>` : `\n<script>${builtinScript}</script>`;
   const mermaidTheme = options.mermaidTheme ?? "neutral";
   const mermaidInit = mermaidTheme === "auto"
     ? `var isDark=window.matchMedia("(prefers-color-scheme:dark)").matches;mermaid.initialize({startOnLoad:true,theme:isDark?"dark":"neutral",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});`
@@ -2781,8 +2837,32 @@ function firstParagraphPreview(nodes, maxLen) {
   return "";
 }
 
+/**
+ * Recursively collect all tagged (has @id) scope nodes from the content tree.
+ * Skips @meta and @about. Used for deep section discovery — lets MCP clients
+ * find sections nested inside top-level scopes (e.g. @pass-terminology inside
+ * @pedantic-review inside @writing).
+ */
+function getAllTaggedScopes(nodes) {
+  const result = [];
+  function walk(nodeList) {
+    for (const node of nodeList) {
+      if (node.type === "scope" && node.hasHeading) {
+        const id = (node.id || "").toLowerCase();
+        if (id !== "meta" && id !== "about") {
+          result.push(node);
+        }
+        if (node.children) walk(node.children);
+      }
+    }
+  }
+  const doc = getDocumentScope(nodes);
+  walk(doc ? doc.children : nodes);
+  return result;
+}
+
 function listSections(nodes) {
-  return getContentScopes(nodes).map((node) => ({
+  return getAllTaggedScopes(nodes).map((node) => ({
     id: node.id || null,
     derivedId: slugify(node.title),
     title: node.title,
@@ -2802,7 +2882,7 @@ function collectDataBlocks(children) {
 }
 
 function extractSection(nodes, sectionId) {
-  const scopes = getContentScopes(nodes);
+  const scopes = getAllTaggedScopes(nodes);
 
   function buildResult(node) {
     const data = collectDataBlocks(node.children || []);