@entropicwarrior/sdoc 0.2.15 → 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/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.15",
+  "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":