@entropicwarrior/sdoc 0.1.9 → 0.1.10

package/README.md

@@ -107,4 +107,4 @@ Release branches merge to both `main` and `develop`. No direct pushes to `main`
 
 ## License
 
-[MIT](LICENSE) — 2026 Irreversible Inc.
+[MIT](LICENSE) — 2026 @entropicwarrior

package/lexica/sdoc-authoring.sdoc

@@ -3,6 +3,8 @@
     # Meta @meta
     {
         type: skill
+
+        sdoc-version: 0.1
     }
 
     # About @about
@@ -175,6 +177,13 @@
                 \`**text**\` | Strong
                 \`~~text~~\` | Strikethrough
                 \`\\\`code\\\`\` | Inline code
+                \`\$x^2\$\` | Inline math (KaTeX)
+                \`\$\$E = mc^2\$\$\` | Display math (centered)
+                \`\{+text+\}\` | Positive marker (green)
+                \`\{=text=\}\` | Neutral marker (blue)
+                \`\{!text!\}\` | Warning marker (amber)
+                \`\{-text-\}\` | Negative marker (red)
+                \`\{~text~\}\` | Highlight (yellow)
             }
 
             Links: \`[Link text](https://example.com)\`
@@ -192,6 +201,8 @@
             ```
 
             Autolinks: \`\<https://example.com\>\`
+
+            Math: Use \`\$...\$\` for inline math and \`\$\$...\$\$\` for display math. Use \`\\\`\\\`\\\`math\` code fences for multi-line equations. A plain \`\$\` followed by a digit (e.g. \`\$100\`) does not trigger math mode.
         }
 
         # References @references
@@ -252,6 +263,19 @@
             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.
         }
 
+        # Math Blocks @math-blocks
+        {
+            Code blocks with the \`math\` language tag are rendered as display equations via KaTeX:
+
+            ````
+            ```math
+            \\int_{-\\infty}^{\\infty} e^{-x^2} \\, dx = \\sqrt{\\pi}
+            ```
+            ````
+
+            Math blocks render as centered display equations with no copy button. The KaTeX CSS is loaded from CDN only when a document contains math content.
+        }
+
         # Blockquotes @blockquotes
         {
             ```
@@ -268,6 +292,8 @@
             @meta {
                 type: doc
 
+                sdoc-version: 0.1
+
                 company: Irreversible Inc.
 
                 confidential: true
@@ -305,6 +331,9 @@
             \`uuid: ...\` — unique identifier.
 
             \`tags: tag1, tag2\` — comma-separated tags.
+
+            \`sdoc-version: 0.1\` — SDOC format version. A parser warning is
+            emitted when this key is missing from \`@meta\`.
         }
 
         # About Scope @about-scope
@@ -324,9 +353,9 @@
         {
             Backslash escapes special characters: \`\\\\\` \`\\{\` \`\\}\` \`\\@\`
             \`\\[\` \`\\]\` \`\\(\` \`\\)\` \`\\*\` \`\\~\` \`\\#\` \`\\!\` \`\\\<\`
-            \`\\\>\`
+            \`\\\>\` \`\\\$\` \`\\+\` \`\\=\` \`\\-\`
 
-            A line starting with \`\\#\` renders as a literal \`#\` (not a heading).
+            A line starting with \`\\#\` renders as a literal \`#\` (not a heading). Use \`\\\$\` to prevent a dollar sign from starting math mode.
         }
     }
 

package/lexica/slide-authoring.sdoc

@@ -3,6 +3,8 @@
     # Meta @meta
     {
         type: skill
+
+        sdoc-version: 0.1
     }
 
     # About @about

package/lexica/specification.sdoc

@@ -3,6 +3,8 @@
     # Meta @meta
     {
         type: doc
+
+        sdoc-version: 0.1
     }
 
     # About @about
@@ -448,16 +450,25 @@ Content of Section B.
                 - Strong: `**strong**`
                 - Strikethrough: `~~strike~~`
                 - Inline code: `` `code` ``
+                - Inline math: `$x^2$` (rendered via KaTeX)
+                - Display math: `$$E = mc^2$$` (centered block)
+                - Positive marker: `{+text+}` (green highlight)
+                - Neutral marker: `{=text=}` (blue highlight)
+                - Warning marker: `{!text!}` (amber highlight)
+                - Negative marker: `{-text-}` (red highlight)
+                - Highlight: `{~text~}` (yellow highlight)
             }
+
+            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 `$`.
         }
 
         # Escaping @escaping
         {
-            In normal text (including headings and paragraphs), a backslash escapes: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` and `` \` ``.
+            In normal text (including headings and paragraphs), a backslash escapes: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` `\$` `\+` `\=` `\-` and `` \` ``.
 
             Escapes are processed before reference detection.
 
-            If a line begins with `\#`, it is treated as a normal paragraph line (rendered with a literal `#`). If a line begins with `\>`, it is treated as a normal paragraph line (rendered with a literal `>`).
+            If a line begins with `\#`, it is treated as a normal paragraph line (rendered with a literal `#`). If a line begins with `\>`, it is treated as a normal paragraph line (rendered with a literal `>`). Use `\$` to prevent a dollar sign from starting math mode.
         }
 
         # Code Blocks @code-blocks
@@ -474,6 +485,8 @@ Content of Section B.
                 - The opening and closing fences must be on their own lines
                 - Anything inside is treated as raw text (no parsing, no escapes)
                 - 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
             }
 
             # Include by Link @code-includes
@@ -570,13 +583,15 @@ Content of Section B.
                     date: 2026-02-09
                     version: 1.0
                     status: Draft
+                    sdoc-version: 0.1
                 }
                 ```
 
                 {[.]
                     - 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`
+                    - Well-known keys: `style`, `styleappend`/`style-append`, `header`, `footer`, `sdoc-version`
+                    - `sdoc-version` identifies the SDOC format version the document targets (current: `0.1`). 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`)
                     - 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

package/package.json

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

package/src/notion-renderer.js

@@ -76,6 +76,7 @@ function richText(content, href, annotations) {
 function enforceContentLimit(richTexts, limit) {
   const result = [];
   for (const rt of richTexts) {
+    if (!rt.text) { result.push(rt); continue; }
     const content = rt.text.content;
     if (content.length <= limit) {
       result.push(rt);
@@ -128,6 +129,21 @@ function flattenInlineNodes(nodes, annotations, href) {
       case "image":
         // Images are extracted at the block level; skip here.
         break;
+      case "math_inline":
+      case "math_display":
+        result.push({
+          type: "equation",
+          equation: { expression: node.value },
+          annotations: ann
+        });
+        break;
+      case "mark_positive":
+      case "mark_neutral":
+      case "mark_warning":
+      case "mark_negative":
+      case "mark_highlight":
+        result.push(...flattenInlineNodes(node.children, ann, href));
+        break;
       default:
         break;
     }
@@ -160,7 +176,7 @@ function extractImagesFromInline(text) {
   }
 
   const rt = enforceContentLimit(flattenInlineNodes(textNodes), RICH_TEXT_LIMIT);
-  const hasText = rt.some((r) => r.text.content.trim() !== "");
+  const hasText = rt.some((r) => (r.text ? r.text.content.trim() !== "" : r.type === "equation"));
 
   const imageBlocks = [];
   for (const img of images) {
@@ -258,6 +274,9 @@ function renderNode(node, depth, nestLevel) {
     case "table":
       return renderTable(node);
     case "code":
+      if (node.lang === "math") {
+        return [{ type: "equation", equation: { expression: node.text || "" } }];
+      }
       return renderCode(node);
     case "blockquote":
       return renderBlockquote(node);

package/src/sdoc.js

@@ -1,3 +1,5 @@
+const SDOC_FORMAT_VERSION = "0.1";
+
 const COMMAND_HEADING = "#";
 const COMMAND_SCOPE_OPEN = "{";
 const COMMAND_SCOPE_CLOSE = "}";
@@ -6,7 +8,29 @@ const COMMAND_LIST_NUMBER = "{[#]";
 const COMMAND_TABLE = "{[table]";
 const COMMAND_CODE_FENCE = "```";
 
-const ESCAPABLE = new Set(["\\", "{", "}", "@", "[", "]", "(", ")", "*", "`", "#", "!", "~", "<", ">"]);
+const ESCAPABLE = new Set(["\\", "{", "}", "@", "[", "]", "(", ")", "*", "`", "#", "!", "~", "<", ">", "$", "+", "=", "-"]);
+
+let _katex = null;
+let _katexLoaded = false;
+
+function getKatex() {
+  if (!_katexLoaded) {
+    _katexLoaded = true;
+    try {
+      _katex = require(require("path").join(__dirname, "..", "vendor", "katex.min.js"));
+    } catch { _katex = null; }
+  }
+  return _katex;
+}
+
+function renderKatex(latex, displayMode) {
+  const katex = getKatex();
+  if (katex) {
+    return katex.renderToString(latex, { displayMode, throwOnError: false });
+  }
+  const cls = displayMode ? "sdoc-math-fallback sdoc-math-display-fallback" : "sdoc-math-fallback";
+  return `<code class="${cls}">${escapeHtml(latex)}</code>`;
+}
 
 function isTableCommand(text) {
   return /^\{\[table(?:\s+[^\]]*?)?\]$/.test(text);
@@ -1132,6 +1156,28 @@ function parseInline(text) {
       }
     }
 
+    // Display math $$...$$ (must come before $ check)
+    if (text.startsWith("$$", i)) {
+      const end = findUnescaped(text, i + 2, "$$");
+      if (end !== -1 && end > i + 2) {
+        flush();
+        nodes.push({ type: "math_display", value: text.slice(i + 2, end) });
+        i = end + 2;
+        continue;
+      }
+    }
+
+    // Inline math $...$ (require non-whitespace after open and before close)
+    if (ch === "$" && next && next !== " " && next !== "\t" && next !== "$") {
+      const end = findUnescaped(text, i + 1, "$");
+      if (end !== -1 && end > i + 1 && text[end - 1] !== " " && text[end - 1] !== "\t") {
+        flush();
+        nodes.push({ type: "math_inline", value: text.slice(i + 1, end) });
+        i = end + 1;
+        continue;
+      }
+    }
+
     if (text.startsWith("**", i)) {
       const end = findUnescaped(text, i + 2, "**");
       if (end !== -1) {
@@ -1154,6 +1200,25 @@ function parseInline(text) {
       }
     }
 
+    if (ch === "{") {
+      const mc = next;
+      let mt = null;
+      if (mc === "+") mt = "mark_positive";
+      else if (mc === "=") mt = "mark_neutral";
+      else if (mc === "!") mt = "mark_warning";
+      else if (mc === "-") mt = "mark_negative";
+      else if (mc === "~") mt = "mark_highlight";
+      if (mt) {
+        const end = findUnescaped(text, i + 2, mc + "}");
+        if (end !== -1) {
+          flush();
+          nodes.push({ type: mt, children: parseInline(text.slice(i + 2, end)) });
+          i = end + 2;
+          continue;
+        }
+      }
+    }
+
     if (ch === "*") {
       const end = findUnescaped(text, i + 1, "*");
       if (end !== -1) {
@@ -1296,6 +1361,16 @@ function renderInlineNodes(nodes) {
           return `<strong>${renderInlineNodes(node.children)}</strong>`;
         case "strike":
           return `<del>${renderInlineNodes(node.children)}</del>`;
+        case "mark_positive":
+          return `<span class="sdoc-mark sdoc-mark-positive">${renderInlineNodes(node.children)}</span>`;
+        case "mark_neutral":
+          return `<span class="sdoc-mark sdoc-mark-neutral">${renderInlineNodes(node.children)}</span>`;
+        case "mark_warning":
+          return `<span class="sdoc-mark sdoc-mark-warning">${renderInlineNodes(node.children)}</span>`;
+        case "mark_negative":
+          return `<span class="sdoc-mark sdoc-mark-negative">${renderInlineNodes(node.children)}</span>`;
+        case "mark_highlight":
+          return `<mark class="sdoc-mark sdoc-mark-highlight">${renderInlineNodes(node.children)}</mark>`;
         case "link":
           return `<a class="sdoc-link" href="${escapeAttr(node.href)}" target="_blank" rel="noopener noreferrer">${renderInlineNodes(
             node.children
@@ -1309,6 +1384,10 @@ function renderInlineNodes(nodes) {
           const imgStyle = imgParts.length ? ` style="${imgParts.join(";")}"` : "";
           return `<img class="sdoc-image" src="${escapeAttr(node.src)}" alt="${escapeAttr(node.alt)}"${imgStyle} />`;
         }
+        case "math_inline":
+          return `<span class="sdoc-math sdoc-math-inline">${renderKatex(node.value, false)}</span>`;
+        case "math_display":
+          return `<span class="sdoc-math sdoc-math-display">${renderKatex(node.value, true)}</span>`;
         default:
           return "";
       }
@@ -1452,6 +1531,9 @@ function renderNode(node, depth) {
       if (node.lang === "mermaid") {
         return `<pre class="mermaid"${dl}>${escapeHtml(node.text)}</pre>`;
       }
+      if (node.lang === "math") {
+        return `<div class="sdoc-math sdoc-math-block"${dl}>${renderKatex(node.text, true)}</div>`;
+      }
       const langClass = node.lang ? ` class="language-${escapeAttr(node.lang)}"` : "";
       return `<div class="sdoc-code-wrap"${dl}><pre class="sdoc-code"><code${langClass}>${escapeHtml(node.text)}</code></pre><button class="sdoc-copy-btn" title="Copy code">\u29C9</button></div>`;
     }
@@ -1484,7 +1566,7 @@ function extractMeta(nodes) {
   }
 
   if (metaIndex === -1) {
-    return { nodes, meta: {} };
+    return { nodes, meta: {}, warnings: [] };
   }
 
   const metaNode = searchNodes[metaIndex];
@@ -1545,14 +1627,19 @@ function extractMeta(nodes) {
   meta.company = meta.properties.company || null;
   meta.confidential = meta.properties.confidential || null;
 
+  const warnings = [];
+  if (!meta.properties["sdoc-version"]) {
+    warnings.push("Missing sdoc-version in @meta (current format version is " + SDOC_FORMAT_VERSION + ")");
+  }
+
   if (doc) {
     // @meta was inside the document scope — strip it from children
     const filteredChildren = doc.children.filter((_, index) => index !== metaIndex);
     const stripped = { ...doc, children: filteredChildren };
-    return { nodes: [stripped], meta };
+    return { nodes: [stripped], meta, warnings };
   }
   const bodyNodes = nodes.filter((_, index) => index !== metaIndex);
-  return { nodes: bodyNodes, meta };
+  return { nodes: bodyNodes, meta, warnings };
 }
 
 function collectParagraphText(nodes) {
@@ -1834,6 +1921,17 @@ const DEFAULT_STYLE = `
     padding: 0 0.2em;
   }
 
+  .sdoc-mark {
+    border-radius: 3px;
+    padding: 0.05em 0.3em;
+    font-weight: 500;
+  }
+  .sdoc-mark-positive { background-color: rgba(34, 139, 34, 0.15); color: #166016; }
+  .sdoc-mark-neutral  { background-color: rgba(59, 130, 195, 0.15); color: #245d8a; }
+  .sdoc-mark-warning  { background-color: rgba(200, 150, 30, 0.18); color: #7a5f0e; }
+  .sdoc-mark-negative { background-color: rgba(187, 50, 50, 0.15); color: #911e1e; }
+  .sdoc-mark-highlight { background-color: rgba(255, 255, 0, 0.75); }
+
   .sdoc-image {
     display: inline-block;
     max-width: 100%;
@@ -1929,10 +2027,12 @@ const PRINT_STYLE = `
       white-space: pre-wrap;
       word-wrap: break-word;
     }
+    .sdoc-mark { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
   }
 `;
 
 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";
 
 function hasMermaidBlocks(nodes) {
   for (const node of nodes) {
@@ -1980,6 +2080,9 @@ function renderHtmlDocumentFromParsed(parsed, title, options = {}) {
   const mermaidScript = hasMermaidBlocks(parsed.nodes)
     ? `\n<script src="${MERMAID_CDN}"></script>\n<script>mermaid.initialize({startOnLoad:true,theme:"neutral",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});</script>`
     : "";
+  const katexCssTag = body.includes('class="katex"')
+    ? `\n<link rel="stylesheet" href="${KATEX_CDN_CSS}" />`
+    : "";
 
   return `<!DOCTYPE html>
 <html lang="en">
@@ -1989,7 +2092,7 @@ function renderHtmlDocumentFromParsed(parsed, title, options = {}) {
 <title>${escapeHtml(title)}</title>
 <style>
 ${cssBase}${cssAppend}
-</style>
+</style>${katexCssTag}
 </head>
 <body>
   <div class="sdoc-shell">
@@ -2236,6 +2339,7 @@ async function resolveIncludes(nodes, resolverFn) {
 }
 
 module.exports = {
+  SDOC_FORMAT_VERSION,
   parseSdoc,
   extractMeta,
   resolveIncludes,
@@ -2251,6 +2355,7 @@ module.exports = {
   extractAbout,
   // Low-level helpers for custom renderers (e.g. slide-renderer)
   parseInline,
+  renderKatex,
   escapeHtml,
   escapeAttr
 };

package/src/slide-renderer.js

@@ -7,7 +7,7 @@
 //   const { nodes, meta } = extractMeta(parsed.nodes);
 //   const html = renderSlides(nodes, { meta, themeCss, themeJs });
 
-const { parseInline, escapeHtml, escapeAttr } = require("./sdoc");
+const { parseInline, renderKatex, escapeHtml, escapeAttr } = require("./sdoc");
 
 // ---------------------------------------------------------------------------
 // Inline rendering — produces clean HTML without sdoc-* classes
@@ -40,6 +40,10 @@ function renderInlineNodes(nodes) {
         }
         case "ref":
           return `@${escapeHtml(node.id)}`;
+        case "math_inline":
+          return `<span class="sdoc-math sdoc-math-inline">${renderKatex(node.value, false)}</span>`;
+        case "math_display":
+          return `<span class="sdoc-math sdoc-math-display">${renderKatex(node.value, true)}</span>`;
         default:
           return "";
       }
@@ -67,6 +71,9 @@ function renderNode(node) {
       if (node.lang === "mermaid") {
         return `<pre class="mermaid">${escapeHtml(node.text)}</pre>`;
       }
+      if (node.lang === "math") {
+        return `<div class="sdoc-math sdoc-math-block">${renderKatex(node.text, true)}</div>`;
+      }
       const langClass = node.lang ? ` class="language-${escapeAttr(node.lang)}"` : "";
       return `<pre><code${langClass}>${escapeHtml(node.text)}</code></pre>`;
     }
@@ -324,6 +331,10 @@ function renderSlides(nodes, options = {}) {
   const mermaidTag = slidesHtml.includes('class="mermaid"')
     ? `\n<script src="${mermaidCdn}"></script>\n<script>mermaid.initialize({startOnLoad:true,theme:"neutral",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});</script>`
     : "";
+  const katexCssCdn = "https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.css";
+  const katexTag = slidesHtml.includes('class="katex"')
+    ? `\n<link rel="stylesheet" href="${katexCssCdn}" />`
+    : "";
 
   return `<!DOCTYPE html>
 <html lang="en">
@@ -331,7 +342,7 @@ function renderSlides(nodes, options = {}) {
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>${escapeHtml(title)}</title>
-${cssTag}
+${cssTag}${katexTag}
 </head>
 <body>
 ${slidesHtml}