@entropicwarrior/sdoc 0.2.7 → 0.2.9

package/README.md

@@ -25,12 +25,23 @@ Markdown has no formal structure — section boundaries are ambiguous, extractio
 
 **PDF and HTML export** — export any document to A4 PDF via headless Chrome, or to standalone HTML. Available as both a CLI tool and a VS Code command.
 
-**A VS Code extension** — live preview, sticky scroll, code folding, document symbols, mermaid rendering, and commands for all the above.
+**A VS Code extension** — live preview, sticky scroll, code folding, document symbols, mermaid/SVG rendering, and commands for all the above.
 
 ## 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
@@ -159,6 +170,10 @@ Fenced with triple backticks, optional language tag for syntax highlighting. The
 
 Code blocks tagged `mermaid` render as SVG diagrams — flowcharts, sequence diagrams, class diagrams, state diagrams, and more.
 
+### SVG Diagrams
+
+Code blocks tagged `svg` render as inline SVG graphics, giving full control over shapes, layout, and styling. `<script>` and `<foreignObject>` tags are stripped for security.
+
 ### Images
 
 Markdown-style images with optional width and alignment:

package/docs/reference/sdoc-authoring.sdoc

@@ -408,6 +408,22 @@ Content of Section B.
             Mermaid supports flowcharts (\`graph\`), sequence diagrams (\`sequenceDiagram\`), class diagrams (\`classDiagram\`), state diagrams (\`stateDiagram-v2\`), and more. The Mermaid library is loaded from CDN only when a document contains mermaid blocks.
         }
 
+        # SVG Diagrams @svg
+        {
+            Code blocks with the \`svg\` language tag render as inline SVG graphics. This gives full control over shapes, layout, and styling for diagrams that need more precision than Mermaid offers:
+
+            ````
+            ```svg
+            <svg viewBox="0 0 200 60" xmlns="http://www.w3.org/2000/svg">
+              <rect x="10" y="10" width="80" height="40" rx="5" fill="#4a90d9" />
+              <text x="50" y="35" text-anchor="middle" fill="white" font-family="sans-serif" font-size="13">Hello</text>
+            </svg>
+            ```
+            ````
+
+            For security, \`<script>\` and \`<foreignObject>\` tags are stripped from the SVG content before rendering. All other SVG elements pass through as-is.
+        }
+
         # Math Blocks @math-blocks
         {
             Code blocks with the \`math\` language tag are rendered as display equations via KaTeX:

package/docs/reference/slide-authoring.sdoc

@@ -165,6 +165,7 @@
                 \`{[table]}\` | \`<table>\`
                 Code fence | \`<pre><code>\`
                 Mermaid code fence | \`<pre class="mermaid">\` (rendered as SVG)
+                SVG code fence | \`<div class="sdoc-svg-block">\` (inline SVG)
                 \`**bold**\` | \`<strong>\`
                 \`*italic*\` | \`<em>\`
                 \`\\\`code\\\`\` | \`<code>\`

package/lexica/specification.sdoc

@@ -10,8 +10,9 @@
     # About @about
     {
         The formal SDOC v0.2 specification. Defines syntax for scopes,
-        lists, tables, code blocks, inline formatting, references,
-        the meta scope, scope types, data blocks, and comments.
+        lists, tables (with formulas), code blocks, inline formatting,
+        references, autolinks (including bare email detection), the meta
+        scope, scope types, data blocks, comments, and collapsible scopes.
         Includes the formal EBNF grammar. Read for edge cases and
         parser behaviour questions. For a friendlier user-facing
         reference, see \`docs/reference/syntax.sdoc\`.
@@ -607,6 +608,9 @@ Content of Section B.
                 - Optional language tag after the opening fence
                 - The special language tag `math` renders the block as a display equation via KaTeX (no copy button)
                 - The special language tag `mermaid` renders the block as an SVG diagram via the Mermaid library
+                - The special language tag `svg` renders the block as an inline SVG graphic. Script and foreignObject tags are stripped for security.
+                - Fences may use more than three backticks (e.g. four or five) to nest code blocks that themselves contain triple backticks. The closing fence must match the opening fence length.
+                - Code blocks display a copy-to-clipboard button (visible on hover) in all rendered HTML output
             }
 
             # Include by Link @code-includes
@@ -819,9 +823,14 @@ Content of Section B.
                 {[.]
                     - Key matching is case-insensitive
                     - The pattern requires at least one space after the colon (`key: value`, not `key:value`)
-                    - Well-known keys: `style`, `styleappend`/`style-append`, `header`, `footer`, `sdoc-version`
+                    - Well-known keys: `style`, `styleappend`/`style-append`, `header`, `footer`, `sdoc-version`, `type`, `tags`, `uuid`, `company`, `confidential`
                     - `sdoc-version` identifies the SDOC format version the document targets (current: `0.2`). A parser warning is emitted when this key is missing.
-                    - All other keys are stored as custom properties (e.g., `author`, `date`, `version`, `status`, `tags`)
+                    - `type` classifies the document (e.g. `doc`, `skill`). Promoted to `meta.type`.
+                    - `tags` is a comma-separated list of keywords. Promoted to `meta.tags` (array).
+                    - `uuid` provides a stable unique identifier. Promoted to `meta.uuid`.
+                    - `company` sets the company name for footer display. Promoted to `meta.company`.
+                    - `confidential` marks the document as confidential. When set (any truthy value), a confidential notice banner is displayed at the top of the rendered output. Promoted to `meta.confidential`.
+                    - All other keys are stored as custom properties in `meta.properties` (e.g., `author`, `date`, `version`, `status`)
                     - Sub-scope syntax takes precedence: if both `# Style { path }` and `style: path` exist, the sub-scope value wins
                     - Key:value and sub-scope syntax can be mixed freely in the same meta scope
                     - Each key:value pair must be on its own paragraph line (separated by blank lines from other pairs)
@@ -832,7 +841,7 @@ Content of Section B.
 
     # Interactive Preview @interactive-preview
     {
-        The VSCode extension provides an interactive preview with the following features. These are preview-only behaviours and do not affect the SDOC format or static HTML export.
+        The VSCode extension provides an interactive preview. Some features (collapsible scopes, copy-to-clipboard) also work in all rendered HTML output. Click-to-navigate is preview-only.
 
         # Theme Support @theme-support
         {
@@ -843,8 +852,8 @@ Content of Section B.
                 - Dark mode overrides the \`--sdoc-*\` CSS custom properties and hardcoded \`rgba()\` colours (table headers, code blocks, confidential notices, error blocks)
                 - Mermaid diagrams use the \`dark\` theme when in a dark colour theme and \`neutral\` otherwise
                 - Theme changes take effect immediately (CSS-driven) and trigger a full preview rebuild (for Mermaid re-initialisation)
-                - Exported HTML follows the user's OS colour preference via \`@media (prefers-color-scheme: dark)\`. Print output always uses light theme colours
-                - Custom stylesheets (\`sdoc.config.json\` or \`@meta style\`) that use \`--sdoc-*\` variables inherit dark values automatically. Hardcoded colours in custom styles are not overridden
+                - Exported HTML follows the user's OS colour preference via `\@media (prefers-color-scheme: dark)`. Print output always uses light theme colours
+                - Custom stylesheets (`sdoc.config.json` or `\@meta style`) that use `--sdoc-*` variables inherit dark values automatically. Hardcoded colours in custom styles are not overridden
             }
         }
 
@@ -852,11 +861,14 @@ Content of Section B.
         {
             Scope headings that have children display a toggle triangle, visible on hover. Clicking the triangle collapses the scope's children (hides the content below the heading). Clicking again expands them.
 
+            Collapsible scopes work in all HTML output: the VS Code preview, exported HTML, Open in Browser, and the document server viewer. The toggle CSS and click handler are included in the default stylesheet and rendered HTML.
+
             {[.]
                 - The triangle points right when collapsed, down when expanded
-                - Collapse state is preserved across preview refreshes using webview state
+                - In the VS Code preview, collapse state is preserved across refreshes using webview state
                 - Scopes are identified by their `@id` if present, otherwise by source line number
                 - Only scopes with children show the toggle
+                - Toggles are hidden in print output and all sections are expanded
             }
         }
 
@@ -1011,9 +1023,10 @@ Content of Section A.
 
         code_block    = fence_open raw_text fence_close ;
         data_block    = data_fence_open raw_text fence_close ;
-        fence_open    = "```" [lang] [ws "src:" path] [ws "lines:" range] newline ;
-        data_fence_open = "```" lang ws ":data" newline ;
-        fence_close   = "```" newline ;
+        fence_open    = backticks [lang] [ws "src:" path] [ws "lines:" range] newline ;
+        data_fence_open = backticks lang ws ":data" newline ;
+        fence_close   = backticks newline ;  (* must match opening fence length *)
+        backticks     = "```" { "`" } ;      (* 3 or more backticks *)
 
         line_comment  = "//" { any_char } newline ;  (* discarded, not in AST *)
 

package/llms.txt

@@ -8,7 +8,7 @@ The authoring guide (`docs/reference/sdoc-authoring.sdoc`) is written as an AI a
 
 ## Docs
 
-- [SDOC Authoring Guide](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/sdoc-authoring.sdoc): Skill document — how to write correct SDOC files. Covers document structure, inline formatting, block types (lists, tables, code, blockquotes), mermaid diagrams, and common mistakes. Start here to learn the format.
+- [SDOC Authoring Guide](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/sdoc-authoring.sdoc): Skill document — how to write correct SDOC files. Covers document structure, inline formatting, block types (lists, tables, code, blockquotes), mermaid/SVG diagrams, and common mistakes. Start here to learn the format.
 - [SDOC Specification](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/specification.sdoc): Formal v0.1 specification with EBNF grammar. Defines syntax for scopes, lists, tables, code blocks, inline formatting, references, and the meta scope.
 - [Why SDOC Over Markdown](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/guide/why-sdoc.sdoc): The case for SDOC — structural problems with Markdown, why explicit scoping solves them, parsing safety as a security property, and the adoption path forward.
 

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.7",
-  "publisher": "entropicwarrior",
+  "version": "0.2.9",
+  "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/sdoc.js

@@ -1390,6 +1390,14 @@ function escapeHtml(value) {
     .replace(/"/g, """);
 }
 
+function sanitizeSvg(svg) {
+  return svg
+    .replace(/<script[\s>][\s\S]*?<\/script\s*>/gi, "")
+    .replace(/<script\s*\/>/gi, "")
+    .replace(/<foreignObject[\s>][\s\S]*?<\/foreignObject\s*>/gi, "")
+    .replace(/<foreignObject\s*\/>/gi, "");
+}
+
 function escapeAttr(value) {
   return escapeHtml(value).replace(/'/g, "&#39;");
 }
@@ -1928,6 +1936,9 @@ function renderNode(node, depth) {
       if (node.lang === "mermaid") {
         return `<pre class="mermaid"${dl}>${escapeHtml(node.text)}</pre>`;
       }
+      if (node.lang === "svg") {
+        return `<div class="sdoc-svg-block"${dl}>${sanitizeSvg(node.text)}</div>`;
+      }
       if (node.lang === "math") {
         return `<div class="sdoc-math sdoc-math-block"${dl}>${renderKatex(node.text, true)}</div>`;
       }
@@ -2371,6 +2382,16 @@ const DEFAULT_STYLE = `
     margin-left: 0.5%;
   }
 
+  .sdoc-svg-block {
+    margin: 0.6rem 0;
+    text-align: center;
+  }
+
+  .sdoc-svg-block svg {
+    max-width: 100%;
+    height: auto;
+  }
+
   .sdoc-code {
     background: rgba(22, 21, 19, 0.06);
     border: 1px solid var(--sdoc-border);
@@ -2416,6 +2437,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 +2516,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 +2548,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";
@@ -2524,7 +2600,7 @@ function hasMermaidBlocks(nodes) {
 
 function hasHighlightableCodeBlocks(nodes) {
   for (const node of nodes) {
-    if (node.type === "code" && node.lang && node.lang !== "mermaid" && node.lang !== "math") return true;
+    if (node.type === "code" && node.lang && node.lang !== "mermaid" && node.lang !== "math" && node.lang !== "svg") return true;
     if (node.children && hasHighlightableCodeBlocks(node.children)) return true;
     if (node.items) {
       for (const item of node.items) {
@@ -2574,7 +2650,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; }"});`
@@ -2791,8 +2868,9 @@ function getAllTaggedScopes(nodes) {
   const result = [];
   function walk(nodeList) {
     for (const node of nodeList) {
-      if (node.type === "scope") {
-        if (node.id && node.id.toLowerCase() !== "meta" && node.id.toLowerCase() !== "about") {
+      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);
@@ -3071,5 +3149,6 @@ module.exports = {
   parseInline,
   renderKatex,
   escapeHtml,
-  escapeAttr
+  escapeAttr,
+  sanitizeSvg
 };