@entropicwarrior/sdoc 0.2.8 → 0.2.10

package/README.md

@@ -25,7 +25,7 @@ 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
 
@@ -170,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, the following are stripped before rendering: \`<script>\` tags, \`<foreignObject>\` tags, event-handler attributes (\`onload\`, \`onclick\`, etc.), and \`javascript:\` URLs. Content outside the \`<svg>\` root element is discarded. All other SVG elements and attributes 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 tags, foreignObject tags, event-handler attributes, and javascript: URLs 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, except for `math`, `mermaid`, and `svg` blocks which render without it
             }
 
             # 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

@@ -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.8",
+  "version": "0.2.10",
   "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -1390,6 +1390,35 @@ function escapeHtml(value) {
     .replace(/"/g, """);
 }
 
+function sanitizeSvg(svg) {
+  if (typeof svg !== "string") return "";
+
+  // Enforce a single <svg> root — discard anything outside it.
+  const openMatch = svg.match(/<svg[\s>]/i);
+  const closeMatch = svg.match(/<\/svg\s*>/i);
+  if (!openMatch || !closeMatch) return "";
+  const start = svg.indexOf(openMatch[0]);
+  const end = svg.indexOf(closeMatch[0], start) + closeMatch[0].length;
+  let s = svg.slice(start, end);
+
+  // Strip <script> and <foreignObject> elements (including self-closing).
+  s = s.replace(/<script[\s>][\s\S]*?<\/script\s*>/gi, "");
+  s = s.replace(/<script\b[^>]*\/\s*>/gi, "");
+  s = s.replace(/<foreignObject[\s>][\s\S]*?<\/foreignObject\s*>/gi, "");
+  s = s.replace(/<foreignObject\b[^>]*\/\s*>/gi, "");
+
+  // Strip event-handler attributes (onload, onclick, etc.).
+  s = s.replace(/\s+on[a-z]+\s*=\s*(".*?"|'.*?'|[^\s>]+)/gi, "");
+
+  // Neutralize javascript: URLs in href and xlink:href.
+  s = s.replace(
+    /(\s+(?:xlink:)?href\s*=\s*)(["'])(\s*javascript:)/gi,
+    function (_match, prefix, quote) { return prefix + quote + "#"; }
+  );
+
+  return s;
+}
+
 function escapeAttr(value) {
   return escapeHtml(value).replace(/'/g, "&#39;");
 }
@@ -1928,6 +1957,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 +2403,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);
@@ -2579,7 +2621,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) {
@@ -3128,5 +3170,6 @@ module.exports = {
   parseInline,
   renderKatex,
   escapeHtml,
-  escapeAttr
+  escapeAttr,
+  sanitizeSvg
 };

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 } = require("./sdoc");
+const { parseInline, renderKatex, escapeHtml, escapeAttr, sanitizeSvg } = require("./sdoc");
 
 // ---------------------------------------------------------------------------
 // Inline rendering — produces clean HTML without sdoc-* classes
@@ -71,6 +71,9 @@ function renderNode(node) {
       if (node.lang === "mermaid") {
         return `<pre class="mermaid">${escapeHtml(node.text)}</pre>`;
       }
+      if (node.lang === "svg") {
+        return `<div class="sdoc-svg-block">${sanitizeSvg(node.text)}</div>`;
+      }
       if (node.lang === "math") {
         return `<div class="sdoc-math sdoc-math-block">${renderKatex(node.text, true)}</div>`;
       }