dsh-nerd-mode 0.4.6 → 0.5.2

package/lib/study-sessions.js

@@ -0,0 +1,283 @@
+/**
+ * The Study Sessions history index. It reads the session logs the host writes
+ * and caches the two facts the panel needs: whether Nerd Mode was ever on, and
+ * whether a completed `/study-plus` invocation appears. Kept free of host
+ * imports like `lib/fold.js`, so it runs under plain node. See ADR 0021.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { zstdDecompressSync } from 'node:zlib'
+
+const COMMAND = 'nerd-mode'
+const STUDY_PLUS = 'study-plus'
+const SESSION_FILE = 'session.v4.jsonl.zstd'
+const DEFAULT_INDEX_FILE = join(homedir(), '.dsh', 'study-sessions-index.json')
+const DEFAULT_SESSIONS_ROOT = join(homedir(), '.dsh', 'sessions')
+const DEFAULT_CHUNK_SIZE = 20
+const MAGIC = [0x28, 0xb5, 0x2f, 0xfd]
+// The token must stand alone: `not/study-plus` and `/study-plussed` are not
+// invocations. This is the same boundary the live command parser uses.
+const DIRECT_COMMAND = /(^|\s)\/study-plus(?=\s|$)/
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function messageText(message) {
+  const content = message?.content
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('\n')
+}
+
+function skillNameOf(argumentText) {
+  if (typeof argumentText !== 'string') return undefined
+  try {
+    return JSON.parse(argumentText)?.name
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Read the two history facts from one session's decoded events.
+ * @param events - decoded session log events, in log order
+ * @returns {{ nerd: boolean, studyPlus: boolean }} `nerd` means Nerd Mode was
+ * switched on at least once, `studyPlus` means a completed `/study-plus`
+ * invocation appears. Malformed events are ignored.
+ */
+export function classify(events) {
+  const successfulCommands = new Set()
+  const wantedCommands = new Set()
+  const skillCalls = new Set()
+  const completedCalls = new Set()
+  let studyPlus = false
+
+  for (const event of events) {
+    const data = event?.data
+    if (event?.type === 'command/run') {
+      if (data?.name !== COMMAND) continue
+      // A bare /nerd-mode means on, matching lib/fold.js.
+      const args = typeof data.args === 'string' ? data.args : ''
+      if (args.trim().toLowerCase() !== 'off' && typeof data.commandId === 'string') {
+        wantedCommands.add(data.commandId)
+      }
+    } else if (event?.type === 'command/done') {
+      if (data?.kind === 'success' && typeof data.commandId === 'string') {
+        successfulCommands.add(data.commandId)
+      }
+    } else if (event?.type === 'user/message') {
+      const source = data?.source
+      if (source?.kind === 'skill-invocation') {
+        if (source.name === STUDY_PLUS) studyPlus = true
+      } else if (source?.kind === 'user' && DIRECT_COMMAND.test(messageText(data))) {
+        studyPlus = true
+      }
+    } else if (event?.type === 'tool/call') {
+      if (data?.name === 'skill' && typeof data.callId === 'string' && skillNameOf(data.arguments) === STUDY_PLUS) {
+        skillCalls.add(data.callId)
+      }
+    } else if (event?.type === 'tool/result') {
+      const message = data?.message
+      if (message?.isError !== true && typeof message?.source?.callId === 'string') {
+        completedCalls.add(message.source.callId)
+      }
+    } else if (event?.type === 'tool/ptc-dispatch') {
+      // A skill load inside run_code arrives as a dispatch and carries its own outcome.
+      if (data?.name === 'skill' && data?.arguments?.name === STUDY_PLUS && data?.isError !== true) {
+        studyPlus = true
+      }
+    }
+  }
+
+  if (!studyPlus) {
+    studyPlus = [...skillCalls].some((callId) => completedCalls.has(callId))
+  }
+  return {
+    nerd: [...wantedCommands].some((commandId) => successfulCommands.has(commandId)),
+    studyPlus,
+  }
+}
+
+/**
+ * Decode a session log into events.
+ *
+ * The file is a chain of zstd frames, one per append batch. Whole-file
+ * decompression stops at the first frame, which holds only the header, so each
+ * frame is decoded on its own.
+ *
+ * @param file - path to a `session.v4.jsonl.zstd` file
+ * @returns the decoded events; malformed frames and lines are dropped
+ * @throws when the file itself cannot be read
+ */
+export function decodeSessionFile(file) {
+  const bytes = readFileSync(file)
+  const starts = []
+  for (let offset = 0; offset <= bytes.length - MAGIC.length; offset += 1) {
+    if (MAGIC.every((byte, index) => bytes[offset + index] === byte)) starts.push(offset)
+  }
+
+  const events = []
+  for (let index = 0; index < starts.length; index += 1) {
+    let text
+    try {
+      text = zstdDecompressSync(bytes.subarray(starts[index], starts[index + 1] ?? bytes.length)).toString('utf8')
+    } catch {
+      // A magic byte sequence can occur inside compressed data, so a failed
+      // slice is expected. See docs/agents/dsh-session-api.md.
+      continue
+    }
+    for (const line of text.split('\n')) {
+      if (line === '') continue
+      try {
+        events.push(JSON.parse(line))
+      } catch {
+        // A crash can leave a partial trailing line. One bad record must not
+        // hide the rest of the log.
+      }
+    }
+  }
+  return events
+}
+
+function readIndex(file) {
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {}
+    // A missing index is a first run. Any other failure reaches the panel.
+    throw error
+  }
+  try {
+    const index = JSON.parse(text)
+    return isRecord(index) ? index : {}
+  } catch {
+    // A corrupt cache is rebuilt from the logs, not reported as a failure.
+    return {}
+  }
+}
+
+function writeIndex(file, index) {
+  mkdirSync(dirname(file), { recursive: true })
+  const temp = `${file}.tmp`
+  writeFileSync(temp, JSON.stringify(index))
+  // Rename keeps the previous index readable if the process dies mid-write.
+  renameSync(temp, file)
+}
+
+function listSessionFiles(root) {
+  let workspaces
+  try {
+    workspaces = readdirSync(root, { withFileTypes: true })
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { files: [], complete: true }
+    throw error
+  }
+
+  const files = []
+  let complete = true
+  for (const workspace of workspaces) {
+    if (!workspace.isDirectory()) continue
+    let sessions
+    try {
+      sessions = readdirSync(join(root, workspace.name), { withFileTypes: true })
+    } catch {
+      // One locked workspace must not blank the others, and must not prune them.
+      complete = false
+      continue
+    }
+    for (const session of sessions) {
+      if (!session.isDirectory()) continue
+      const file = join(root, workspace.name, session.name, SESSION_FILE)
+      try {
+        const stat = statSync(file)
+        if (stat.isFile()) {
+          files.push({ id: session.name, file, mtimeMs: stat.mtimeMs, size: stat.size })
+        }
+      } catch {
+        // A session folder without a readable log is not a session yet.
+      }
+    }
+  }
+  files.sort((left, right) => (left.file < right.file ? -1 : left.file > right.file ? 1 : 0))
+  return { files, complete }
+}
+
+/**
+ * Classify one chunk of the session tree and persist the index.
+ *
+ * @param options
+ * @param options.cursor - index of the first file in the sorted session list to
+ * process; negative and non-integer values read as 0
+ * @param options.indexFile - index path; defaults to
+ * `~/.dsh/study-sessions-index.json`
+ * @param options.sessionsRoot - session tree; defaults to `~/.dsh/sessions`
+ * @param options.chunkSize - files to process per call; defaults to 20
+ * @param options.decode - decoder override for tests; defaults to
+ * `decodeSessionFile`
+ * @returns {{ phase: 'pending' | 'ready', cursor: number, done: number,
+ * total: number, sessions: Record<string, { studyPlus: boolean }> }} `cursor`
+ * is the next call's starting index and equals `total` once `phase` is
+ * `ready`. `done` counts files visited so far. A key in `sessions` means Nerd
+ * Mode was on at least once for that id.
+ * @throws when the index or the session tree cannot be read or written
+ */
+export function scan({
+  cursor = 0,
+  indexFile = DEFAULT_INDEX_FILE,
+  sessionsRoot = DEFAULT_SESSIONS_ROOT,
+  chunkSize = DEFAULT_CHUNK_SIZE,
+  decode = decodeSessionFile,
+} = {}) {
+  const { files, complete } = listSessionFiles(sessionsRoot)
+  const index = readIndex(indexFile)
+  if (complete) {
+    const live = new Set(files.map(({ id }) => id))
+    for (const id of Object.keys(index)) {
+      if (!live.has(id)) delete index[id]
+    }
+  }
+
+  const start = Number.isInteger(cursor) && cursor > 0 ? cursor : 0
+  const size = Number.isInteger(chunkSize) && chunkSize > 0 ? chunkSize : DEFAULT_CHUNK_SIZE
+  const end = Math.min(start + size, files.length)
+  for (let position = start; position < end; position += 1) {
+    const { id, file, mtimeMs, size: bytes } = files[position]
+    const previous = index[id]
+    if (previous?.mtimeMs === mtimeMs && previous?.size === bytes) continue
+
+    let flags
+    try {
+      flags = classify(decode(file))
+    } catch {
+      // An unreadable session keeps its previous record and retries next scan.
+      continue
+    }
+    index[id] = {
+      mtimeMs,
+      size: bytes,
+      // Compaction can drop the original event. A fact that disappeared from a
+      // rewritten log must not resurface as a missing session.
+      nerd: flags.nerd || previous?.nerd === true,
+      studyPlus: flags.studyPlus,
+    }
+  }
+  writeIndex(indexFile, index)
+
+  const sessions = {}
+  for (const [id, entry] of Object.entries(index)) {
+    if (entry?.nerd === true) sessions[id] = { studyPlus: entry.studyPlus === true }
+  }
+  return {
+    phase: end >= files.length ? 'ready' : 'pending',
+    cursor: end,
+    done: end,
+    total: files.length,
+    sessions,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-nerd-mode",
-  "version": "0.4.6",
+  "version": "0.5.2",
   "description": "A study switch and study skills for DeepSeek Harness.",
   "license": "MIT",
   "type": "module",
@@ -64,7 +64,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "eslint": "^10.13.0",
+    "eslint": "^9.39.5",
     "globals": "^17.13.0"
   }
 }

package/skills/convert-documents-to-markdown/SKILL.md

@@ -1,26 +1,26 @@
----
-name: convert-documents-to-markdown
-description: Convert Word (.doc, .docx), PowerPoint (.ppt, .pptx), Excel (.xls, .xlsx), OpenDocument (.odt, .ods, .odp), RTF, EPUB, CSV, and PDF files to GitHub-Flavored Markdown. Use when a task needs the contents of an office document, spreadsheet, presentation, ebook, or PDF you cannot read directly.
-license: MIT
-metadata:
-  author: firecrawl
----
-
-# Convert documents to Markdown
-
-Run the anydoc CLI. It needs Node 20+ and no install:
-
-```bash
-npx -y @firecrawl/anydoc <file>              # Markdown to stdout
-npx -y @firecrawl/anydoc <file> -o out.md    # write to a file
-npx -y @firecrawl/anydoc - --format csv < f  # read stdin
-```
-
-Rules:
-
-1. Supported inputs: `.doc`, `.docx`, `.docm`, `.odt`, `.rtf`, `.epub`, `.pdf`, `.ppt`, `.pps`, `.pot`, `.pptx`, `.pptm`, `.ppsx`, `.ppsm`, `.odp`, `.xls`, `.xlsx`, `.xlsm`, `.xlsb`, `.ods`, `.csv`.
-2. The format is detected from the file content. Pass `--format <name>` only when detection cannot work: CSV from stdin, or a missing or wrong extension.
-3. Exit codes: 0 success, 1 the document could not be converted, 2 usage error, 3 pages of a PDF need OCR. Failures print one `anydoc: <message>` line to stderr. The CLI never prompts.
-4. For a large document, write to a file with `-o` and read the parts you need instead of streaming everything into context.
-5. Scanned and image-only pages need OCR, which anydoc does not do, so the document exits 3. Rerun with `--ocr hosted` to send it to [Firecrawl Parse](https://firecrawl.dev/parse). No signup needed. Pass `--api-key` or set `FIRECRAWL_API_KEY` for higher limits.
-6. Inside a Node, Python, or Rust codebase, prefer the library over shelling out: `@firecrawl/anydoc` on npm, `firecrawl-anydoc` on PyPI, `anydoc` on crates.io. Each exposes the same `to_markdown` / `toMarkdown` API.
+---
+name: convert-documents-to-markdown
+description: Convert Word (.doc, .docx), PowerPoint (.ppt, .pptx), Excel (.xls, .xlsx), OpenDocument (.odt, .ods, .odp), RTF, EPUB, CSV, and PDF files to GitHub-Flavored Markdown. Use when a task needs the contents of an office document, spreadsheet, presentation, ebook, or PDF you cannot read directly.
+license: MIT
+metadata:
+  author: firecrawl
+---
+
+# Convert documents to Markdown
+
+Run the anydoc CLI. It needs Node 20+ and no install:
+
+```bash
+npx -y @firecrawl/anydoc <file>              # Markdown to stdout
+npx -y @firecrawl/anydoc <file> -o out.md    # write to a file
+npx -y @firecrawl/anydoc - --format csv < f  # read stdin
+```
+
+Rules:
+
+1. Supported inputs: `.doc`, `.docx`, `.docm`, `.odt`, `.rtf`, `.epub`, `.pdf`, `.ppt`, `.pps`, `.pot`, `.pptx`, `.pptm`, `.ppsx`, `.ppsm`, `.odp`, `.xls`, `.xlsx`, `.xlsm`, `.xlsb`, `.ods`, `.csv`.
+2. The format is detected from the file content. Pass `--format <name>` only when detection cannot work: CSV from stdin, or a missing or wrong extension.
+3. Exit codes: 0 success, 1 the document could not be converted, 2 usage error, 3 pages of a PDF need OCR. Failures print one `anydoc: <message>` line to stderr. The CLI never prompts.
+4. For a large document, write to a file with `-o` and read the parts you need instead of streaming everything into context.
+5. Scanned and image-only pages need OCR, which anydoc does not do, so the document exits 3. Rerun with `--ocr hosted` to send it to [Firecrawl Parse](https://firecrawl.dev/parse). No signup needed. Pass `--api-key` or set `FIRECRAWL_API_KEY` for higher limits.
+6. Inside a Node, Python, or Rust codebase, prefer the library over shelling out: `@firecrawl/anydoc` on npm, `firecrawl-anydoc` on PyPI, `anydoc` on crates.io. Each exposes the same `to_markdown` / `toMarkdown` API.

package/skills/diagram/SKILL.md

@@ -9,6 +9,14 @@ A picture earns its place when the reader has to hold two things at once: the pa
 
 Do not draw a list. If the content is a sequence of steps with no branching, a numbered list reads faster. One figure carries one idea; split rather than crowd.
 
+## Before you draw
+
+Name the one relation the figure must show, in one sentence. List the nodes and the arrows between them. If the list passes 12 nodes, split the figure.
+
+Pick the shape from the relation, not from the topic. Decide the one accent: which node or arrow is the point. Every accent class you use gets a role you can name; most figures need one, a comparison may need two.
+
+When the figure would need a second paragraph to explain, draw two figures.
+
 ## Pick the shape
 
 - **Flow**: what happens in order. Three to five boxes left to right, an arrow between each, a dashed return edge for the retry path.
@@ -31,17 +39,24 @@ Write the SVG file first, then talk about it.
 
 The Markdown path is resolved against the working directory and served from disk, so it must be a file that exists when the message renders. Write the file before the sentence that shows it. No query string, no fragment, no `data:` URL: the renderer rejects all three and shows the alt text instead. To revise a figure, overwrite the file; if the learner still sees the old picture, write a new name.
 
-## File contract
+## The floor
 
-The file must carry:
+Non-negotiable, every figure:
 
-- `xmlns="http://www.w3.org/2000/svg"`, `viewBox`, and `width`/`height` in pixels.
-- `role="img"` and an `aria-label` that states what the figure shows.
-- One `<style>` block with the palette classes below, so a dark background can override the light default.
-- `font-family="Segoe UI, Inter, system-ui, sans-serif"` on every text group.
-- Arrowheads as `<marker>` in `<defs>`, referenced with `marker-end`.
+- The canvas is 720 wide. The root carries `xmlns`, `viewBox`, `width` and `height` in pixels, `role="img"`, and a non-empty `aria-label`.
+- One `<style>` block holds the palette classes and the dark-mode override. No other style block.
+- `font-family="Segoe UI, Inter, system-ui, sans-serif"` sits on every text group.
+- Arrowheads are `<marker>` elements in `<defs>`, referenced with `marker-end`.
+- Colors come only from the palette classes. No raw hex or named color outside `<style>`. No gradients, shadows, 3D, icons, emoji, or decorative marks.
+- One accent class, one meaning, for the whole figure. At most four accent classes; most figures need one.
+- Every label fits its box: 13px, at most two lines. At 13px a Latin line runs about 7.2px per character and a CJK line about 13px. A box needs `7.2 × Latin characters + 13 × CJK characters + 36`.
+- Every arrow lands on a border with clearance. No wire crosses a label. No orphan node.
+- No relation the source does not state. No invented number, name, or arrow.
+- No `<script>`, `<foreignObject>`, external `href`, `@import`, animation, or LaTeX delimiter. Formulas are plain Unicode text inside `<text>`.
+- The `aria-label`, the Markdown alt text, and the caption sentence agree.
+- The figure says one thing.
 
-The file must not carry `<script>`, `<foreignObject>`, external `href` or `url(...)` fonts, LaTeX delimiters, or animation. A browser renders it as an isolated image: it inherits no page CSS and no page font, so every color and every glyph has to be stated in the file. Formulas become plain Unicode text inside `<text>`: `θ`, `∇f(x)`, `x²`, `≤`.
+A browser renders the file as an isolated image. It inherits no page CSS and no page font, so every color and every glyph has to be stated in the file.
 
 ## Layout budget
 
@@ -51,7 +66,7 @@ Work in a 720 wide canvas; height is whatever the content needs plus 40.
 - Title at 15px bold, baseline `y=40`, left margin 28.
 - Node: 60 tall, `rx="8"`, 42 to 50 of gap between nodes. Three across fit as 180 wide boxes at x=28, 270, 512.
 - Node label 13px, sub-label 12 to 13px in the muted color, both anchored `middle`.
-- Measure before you place: at 13px Segoe UI a line runs about 7.2px per character. A box must be at least `7.2 × characters + 36` wide, and a node holds at most two lines.
+- Measure before you place: at 13px Segoe UI a Latin line runs about 7.2px per character, a CJK line about 13px. A box must be at least `7.2 × Latin characters + 13 × CJK characters + 36` wide, and a node holds at most two lines.
 - Arrows land on a box edge with a few pixels of clearance, never inside the box.
 - Keep it under about 12 nodes. Past that the figure stops being readable at chat width.
 
@@ -67,6 +82,7 @@ Copy these classes verbatim and use them; they carry the dark-mode overrides.
   .sub { fill: #475569; }
   .note { fill: #64748b; }
   .wire { stroke: #94a3b8; }
+  .head { fill: #94a3b8; }
   .b1 { fill: #2563eb; fill-opacity: .08; stroke: #2563eb; }
   .b2 { fill: #b45309; fill-opacity: .08; stroke: #b45309; }
   .b3 { fill: #15803d; fill-opacity: .08; stroke: #15803d; }
@@ -87,7 +103,7 @@ Copy these classes verbatim and use them; they carry the dark-mode overrides.
 </style>
 ```
 
-Class `b1` to `b4` mark four distinct things. Give one class one meaning for the whole figure, and when the figure has a legend, build it from the same classes. `note` is for edge labels and footnotes; `wire` styles connectors.
+Class `b1` to `b4` mark four distinct things. Give one class one meaning for the whole figure, and when the figure has a legend, build it from the same classes. `note` is for edge labels and footnotes; `wire` styles connectors; `head` fills the arrowhead.
 
 ## Starter
 
@@ -96,7 +112,7 @@ Class `b1` to `b4` mark four distinct things. Give one class one meaning for the
   <style>…the palette above…</style>
   <defs>
     <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path class="head" d="M0 0 L10 5 L0 10 z" fill="#94a3b8"/>
+      <path class="head" d="M0 0 L10 5 L0 10 z"/>
     </marker>
   </defs>
   <rect class="panel" x="0.75" y="0.75" width="718.5" height="248.5" rx="12" stroke-width="1.5"/>
@@ -109,11 +125,11 @@ Class `b1` to `b4` mark four distinct things. Give one class one meaning for the
 
     <rect class="b2" x="270" y="72" width="180" height="60" rx="8" stroke-width="1.5"/>
     <text class="label" x="360" y="98" text-anchor="middle" font-weight="600">Name the gap</text>
-    <text class="sub" x="360" y="117" text-anchor="middle">without fixing it yet</text>
+    <text class="sub" x="360" y="117" text-anchor="middle">without fixing yet</text>
 
     <rect class="b3" x="512" y="72" width="180" height="60" rx="8" stroke-width="1.5"/>
     <text class="label" x="602" y="98" text-anchor="middle" font-weight="600">Explain again</text>
-    <text class="sub" x="602" y="117" text-anchor="middle">with the fix in place</text>
+    <text class="sub" x="602" y="117" text-anchor="middle">after the fix</text>
   </g>
 
   <g class="wire" stroke-width="1.5" fill="none">
@@ -125,10 +141,18 @@ Class `b1` to `b4` mark four distinct things. Give one class one meaning for the
 </svg>
 ```
 
-## Check before you send
+## Verify
 
-- Every arrow touches a border at both ends, and no label touches a border.
-- The `aria-label`, the Markdown alt text, and the caption sentence agree.
-- Colors come only from the palette classes, so the figure survives a theme switch.
-- The file path in the image line matches the file you wrote, character for character.
-- The figure says one thing. If it needs a second paragraph of explanation, draw two figures.
+Run the checker after writing the file:
+
+```text
+node <skill-dir>/scripts/check-svg.mjs diagrams/<name>.svg
+```
+
+`<skill-dir>` is the folder that holds this SKILL.md.
+
+Fix every FAIL and run it once more. A WARN is a question: fix it, or say why it is intentional.
+
+The checker measures text, not pixels. When a browser is available, open the SVG and look at it. Check it at 720 wide and at 360 wide: the whole figure scales by half, so a 13px label reads at 6.5px. If that is too small for the material, split the figure or draw a simpler one. Do not shrink the text below 13px at 720.
+
+A clean lint is not a good figure. The last check is the reader's: can they name the one thing the figure shows without reading the caption?

package/skills/diagram/scripts/check-svg.mjs

@@ -0,0 +1,184 @@
+// Lint a diagram SVG against the floor in SKILL.md. No dependencies.
+// The checker sees text, not pixels: it estimates label width and catches
+// contract breaks. A rendered look still decides the final figure.
+
+import { readFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+const CJK = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uac00-\ud7af]/
+const PALETTE = ['.panel', '.title', '.label', '.sub', '.note', '.wire', '.head', '.b1', '.b2', '.b3', '.b4']
+
+function attr(attrs, name) {
+  const match = attrs.match(new RegExp(`\\s${name}="([^"]*)"`))
+  return match ? match[1] : null
+}
+
+function visibleText(raw) {
+  return raw.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim()
+}
+
+function textWidth(text, size = 13) {
+  const latin = size * 0.554
+  let width = 0
+  for (const char of text) width += CJK.test(char) ? size : latin
+  return width
+}
+
+/**
+ * Check one SVG source against the diagram floor.
+ *
+ * Args:
+ *   source: the SVG file as text. It may be malformed; the checker reports that
+ *     as a finding instead of throwing.
+ *
+ * Returns:
+ *   { findings: Array<{ level: 'FAIL' | 'WARN', area: string, message: string }> }
+ *
+ * FAIL means the file breaks the contract. WARN means a style rule needs a
+ * human decision. The caller sets the exit code.
+ */
+export function checkSvg(source) {
+  const findings = []
+  const fail = (area, message) => findings.push({ level: 'FAIL', area, message })
+  const warn = (area, message) => findings.push({ level: 'WARN', area, message })
+
+  const svg = source.match(/<svg\b([^>]*)>/)
+  if (!svg) {
+    fail('root', 'no <svg> element')
+    return { findings }
+  }
+
+  const root = svg[1]
+  if (!/xmlns="http:\/\/www\.w3\.org\/2000\/svg"/.test(root)) fail('root', 'missing xmlns')
+  const viewBox = attr(root, 'viewBox')
+  const box = viewBox ? viewBox.trim().split(/[\s,]+/).map(Number) : []
+  if (box.length !== 4 || box.some(Number.isNaN)) {
+    fail('root', 'viewBox must hold four numbers')
+  } else if (box[2] !== 720) {
+    warn('root', `canvas is ${box[2]} wide; the budget is 720`)
+  }
+  const width = attr(root, 'width')
+  const height = attr(root, 'height')
+  if (!width || !height) {
+    fail('root', 'missing width or height')
+  } else if (box.length === 4 && (Number(width) !== box[2] || Number(height) !== box[3])) {
+    warn('root', 'width and height do not match the viewBox')
+  }
+  if (attr(root, 'role') !== 'img') fail('root', 'missing role="img"')
+  if (!attr(root, 'aria-label')) fail('root', 'missing or empty aria-label')
+
+  const style = source.match(/<style[^>]*>([\s\S]*?)<\/style>/)?.[1] ?? ''
+  if (!style) fail('style', 'missing <style> block')
+  const styleCount = (source.match(/<style\b/g) ?? []).length
+  if (styleCount > 1) fail('style', `${styleCount} <style> blocks; the floor allows one`)
+  const missing = PALETTE.filter((name) => !style.includes(name))
+  if (missing.length) fail('style', `missing palette classes: ${missing.join(', ')}`)
+  if (!/@media\s*\(\s*prefers-color-scheme:\s*dark\s*\)/.test(style)) {
+    fail('style', 'missing dark-mode block')
+  }
+
+  for (const [label, pattern] of [
+    ['script', /<script\b/i],
+    ['foreignObject', /<foreignObject\b/i],
+    ['external href', /\bhref="/],
+    ['@import', /@import\b/],
+    ['animation', /<animate\b|<set\b/i],
+  ]) {
+    if (pattern.test(source)) fail('forbidden', `${label} is not allowed`)
+  }
+  if (/url\((?!\s*#)/.test(source)) fail('forbidden', 'external url(...) is not allowed')
+  if (/\\\(|\\\[|\$\$/.test(source)) fail('forbidden', 'LaTeX delimiter; use plain Unicode text')
+
+  const outside = source.replace(/<style[^>]*>[\s\S]*?<\/style>/g, '')
+  for (const match of outside.matchAll(/\b(?:fill|stroke)="([^"]+)"/g)) {
+    const value = match[1]
+    if (value === 'none' || value === 'currentColor') continue
+    if (/^#[0-9a-fA-F]{3,8}$/.test(value)) fail('color', `raw hex outside <style>: ${value}`)
+    else fail('color', `paint "${value}" bypasses the palette classes`)
+  }
+  for (const match of outside.matchAll(/\bstyle="([^"]*)"/g)) {
+    if (/#[0-9a-fA-F]{3,8}|(?:fill|stroke|color)\s*:/.test(match[1])) {
+      fail('color', 'inline style carries paint; use the palette classes')
+    }
+  }
+
+  const elements = []
+  for (const match of source.matchAll(/<rect\b([^>]*?)\/?>/g)) {
+    elements.push({ type: 'rect', index: match.index, attrs: match[1] })
+  }
+  for (const match of source.matchAll(/<text\b([^>]*)>([\s\S]*?)<\/text>/g)) {
+    elements.push({ type: 'text', index: match.index, attrs: match[1], content: visibleText(match[2]) })
+  }
+  elements.sort((a, b) => a.index - b.index)
+
+  const rects = elements.filter((element) => element.type === 'rect')
+  const nodes = rects.filter((element) => !/\bpanel\b/.test(attr(element.attrs, 'class') ?? ''))
+  if (nodes.length > 12) warn('nodes', `${nodes.length} nodes; the budget is 12`)
+
+  for (const [index, element] of elements.entries()) {
+    if (element.type !== 'text' || !element.content) continue
+    const cls = attr(element.attrs, 'class') ?? ''
+    const size = Number(attr(element.attrs, 'font-size')) || (cls.includes('title') ? 15 : cls.includes('note') ? 12 : 13)
+    const needed = textWidth(element.content, size)
+    const x = Number(attr(element.attrs, 'x'))
+    const y = Number(attr(element.attrs, 'y'))
+    let available = 664
+    if (attr(element.attrs, 'text-anchor') === 'middle' && Number.isFinite(x) && Number.isFinite(y)) {
+      for (let i = index - 1; i >= 0; i -= 1) {
+        const rect = elements[i]
+        if (rect.type !== 'rect') continue
+        const rx = Number(attr(rect.attrs, 'x'))
+        const ry = Number(attr(rect.attrs, 'y'))
+        const rw = Number(attr(rect.attrs, 'width'))
+        const rh = Number(attr(rect.attrs, 'height'))
+        if ([rx, ry, rw, rh].every(Number.isFinite) && x >= rx && x <= rx + rw && y >= ry && y <= ry + rh) {
+          available = rw - 36
+          break
+        }
+      }
+    }
+    if (needed > available) {
+      fail('text', `"${element.content}" needs ${Math.ceil(needed)}px, box has ${Math.floor(available)}px`)
+    }
+  }
+
+  const stack = []
+  for (const match of source.matchAll(/<(\/?)(g|text)\b([^>]*)>/g)) {
+    const closing = match[1] === '/'
+    const tag = match[2]
+    const attrs = match[3]
+    if (tag === 'g') {
+      if (closing) stack.pop()
+      else stack.push(attr(attrs, 'font-family') ?? stack.at(-1) ?? null)
+      continue
+    }
+    if (!closing && !attr(attrs, 'font-family') && !stack.at(-1)) {
+      warn('font', 'a <text> element has no font-family')
+    }
+  }
+
+  const markers = [...source.matchAll(/marker-(?:start|mid|end)="url\(#([^)]+)\)"/g)].map((match) => match[1])
+  for (const id of new Set(markers)) {
+    if (!new RegExp(`<marker\\b[^>]*\\bid="${id}"`).test(source)) {
+      fail('marker', `missing <marker id="${id}">`)
+    }
+  }
+
+  return { findings }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const file = process.argv[2]
+  if (!file) {
+    console.error('usage: node check-svg.mjs <file.svg>')
+    process.exit(2)
+  }
+  const { findings } = checkSvg(readFileSync(file, 'utf8'))
+  for (const finding of findings) {
+    console.log(`${finding.level}  ${finding.area}: ${finding.message}`)
+  }
+  const fails = findings.filter((finding) => finding.level === 'FAIL').length
+  const warns = findings.length - fails
+  console.log(findings.length ? `${findings.length} findings (${fails} FAIL, ${warns} WARN)` : 'OK  no findings')
+  process.exitCode = fails ? 1 : 0
+}