interactive-markdown 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Thomas
+Copyright (c) 2026 Thomas Lo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,18 +1,22 @@
 # Interactive Markdown (IVM)
 
-**Interactive Markdown** is a small browser **editor + renderer** for plain `.md` files that include live **vector graphics** driven by sliders, timers, and a safe expression language.
+**Interactive Markdown** is a small browser **editor + renderer** for plain `.md` files that include live **vector graphics** driven by sliders, timers, and a safe expression language, plus a **graph editor** stored in the same fence.
 
-Write Markdown as usual. Add an `ivm` fenced block when you want interactive SVG. The format stays AI-friendly: readable text an agent can generate like normal Markdown.
+Write Markdown as usual. Add an `ivm` fenced block when you want interactive SVG or a directed graph you can edit in the preview. The format stays AI-friendly: readable text an agent can generate like normal Markdown.
 
 License: **MIT** (see [LICENSE](LICENSE)).
 
 ## Features
 
 - Split **editor** and **live preview**
+- **Graph editor** tab beside the source: prose renders as formatted text, and sliders, figures, and graphs stay editable blocks
 - Open / save `.md`, with a **localStorage** draft
 - IVM widgets: `@slider`, `@timer` (Play/Pause), `@input`, `@toggle`
-- Derived values with `@let` / `@calc`
+- Derived values with `@let` (agents should emit `@let`, not `@calc`)
 - SVG templates with `{{expr}}` bindings
+- Slim `@svg WxH` wrapper for compact markup
+- Visual **graph editor**: `@graph`, `@node`, and `@edge` (drag, connect, rename; edits write back into the fence)
+- Animated SVG: CSS `@keyframes`, SMIL, glow filters, and internal `<use>`
 - Whitelist expression evaluator (no `eval`)
 - SVG sanitizer (strips scripts, event handlers, external hrefs)
 
@@ -37,23 +41,24 @@ npx serve .
 
 > ES modules need HTTP — opening `index.html` as a `file://` URL will not work.
 
+## Graph editor tab
+
+The left pane has two tabs. **Source** is the markdown. **Graph editor** shows the same document with prose rendered as formatted text. Sliders, timers, text fields, toggles, formulas, shapes, and graphs stay as blocks. Select a block to edit its label, range, expression, or shape attributes. A shape attribute can be a number or `{{name}}`. The graph block is the canvas: drag, connect, and rename there. An animated graph marches dashes along each edge and sends a dot along the same path. Each change rewrites the source. The right pane is the rendered preview.
+
 ## IVM dialect (quick reference)
 
-Fence name: **`ivm`**.
+Fence name: **`ivm`**. Long control names are canonical; short aliases are accepted for compact AI generation.
+
+### Canonical exemplar
 
 ````markdown
 ```ivm
-@ns optionalSharedName
-@slider amp: 5..60 = 30 step=1 "Amplitude"
-@timer t: 0..100 = 0 speed=20 loop "Phase"
-@input title: "Hello" "Title"
-@toggle show: true "Show"
-@let y = 40 - amp * sin(t * pi / 50)
-@calc a = amp / 2
-@svg
-<svg viewBox="0 0 200 80" xmlns="http://www.w3.org/2000/svg">
-  <circle cx="100" cy="{{round(y, 2)}}" r="{{amp}}" fill="#38bdf8"/>
-</svg>
+@slider amp: 5..55 = 28
+@timer t: 0..100 = 0 speed=25
+@let y = 40 - amp * sind(t * 3.6)
+@svg 200x80
+  <rect width="200" height="80" fill="#0f172a"/>
+  <path d="M10 40 Q55 {{y}} 100 40 T190 40" fill="none" stroke="#38bdf8" stroke-width="3"/>
 ```
 ````
 
@@ -61,26 +66,78 @@ Fence name: **`ivm`**.
 
 | Line | Meaning |
 |------|---------|
-| `@slider name: min..max = default step=S "Label"` | Range input |
-| `@timer name: min..max = default speed=N loop` | Animated value + Play/Pause (`noloop` to stop at end) |
-| `@input name: "default" "Label"` | Text field |
-| `@toggle name: true\|false "Label"` | Checkbox |
-| `@let name = expression` | Computed value |
-| `@calc name = expression` | Alias of `@let` |
+| `@slider name: min..max = default [step=S] [deg\|rad] ["Label"]` | Range input (`@s` alias) |
+| `@timer name: min..max = default [speed=N] [step=S] [loop\|noloop] [deg\|rad] ["Label"]` | Animated value + Play/Pause (`@t` alias) |
+| `@input name: "default" ["Label"]` | Text field (`@i` alias) |
+| `@toggle name: true\|false ["Label"]` | Checkbox (`@b` alias) |
+| `@let name = expression` | Computed value (`@l` alias) |
+| `@calc name = expression` | Alias of `@let` (compat only; prefer `@let`) |
 | `@ns name` | Share variable state across IVM blocks with the same name |
-| `@svg` | Everything after this line is SVG markup |
+| `@svg` | Everything after this line is full SVG markup |
+| `@svg WxH` | Same, but wrap non-root markup in `<svg viewBox="0 0 W H" xmlns=…>` |
+| `@graph` | Start an editable directed graph. This is the first directive in that fence |
+| `@node id: "Label" x=N y=N kind=K` | Node. `kind` is `action` (default), `input`, `output`, or `decision` |
+| `@edge from -> to` | Directed edge. Add `from=top\|right\|bottom\|left` and `to=top\|right\|bottom\|left` to choose the sides. Defaults are `from=right` and `to=left` |
+| `@animate` | Play marching dashes and traveling dots on the graph canvas. Options: `path=ortho\|straight\|curve`, `quantity=N` (1–12), `direction=forward\|reverse`, `speed=seconds` |
+
+### Defaults (omit when unchanged)
+
+- `step` defaults to **1**
+- timer `loop` defaults to **true** (write `noloop` only when needed)
+- timer `speed` defaults to **30**
+- if `"Label"` is omitted, the UI shows the variable **name**
+
+### Short aliases (AI-compact)
+
+| Short | Long |
+|-------|------|
+| `@s` | `@slider` |
+| `@t` | `@timer` |
+| `@i` | `@input` |
+| `@b` | `@toggle` |
+| `@l` | `@let` |
+
+Humans and docs should use the long forms. Generators may emit short aliases; both parse.
+
+### Graph
+
+A fence that starts with `@graph` is a node-and-edge diagram. The preview is the editor: drag a node, drag a port on any side onto another node, double-click a label to rename, and press Delete to remove the selection. `@animate` runs the motion on that same canvas. Path, quantity, direction, and speed are edited there and written back onto the `@animate` line. Each committed edit replaces that fence in the source. Do not mix `@svg` or controls into the same fence.
+
+````markdown
+```ivm
+@graph
+@node start: "Start" x=40 y=48 kind=input
+@node step: "Step" x=280 y=48
+@edge start -> step
+```
+````
 
 ### Expressions (`{{…}}`)
 
-Placeholders use **double braces**: `{{expr}}`.
+Placeholders use **double braces** only: `{{expr}}`.
 
 Allowed operators include `+ - * / % ^ **`, comparisons, `&& || !`, and ternary `? :`.
 
-Functions include: `abs`, `sqrt`, `pow`, `exp`, `ln`, `log`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `round`, `floor`, `ceil`, `trunc`, `sign`, `min`, `max`, `clamp`, `mod`, `lerp`, `deg`, `rad`.
+Functions include: `abs`, `sqrt`, `pow`, `exp`, `ln`, `log`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `sind`, `cosd`, `tand`, `asind`, `acosd`, `atand`, `round`, `floor`, `ceil`, `trunc`, `sign`, `min`, `max`, `clamp`, `mod`, `lerp`, `deg`, `rad`.
 
 Constants: `pi`, `e`, `tau`.
 
-Angles for trig functions are in **radians** (use `deg` / `rad` helpers as needed).
+- `sin` / `cos` / `tan` take **radians**
+- `sind` / `cosd` / `tand` take **degrees** (prefer these when a control range is in degrees)
+- Optional `deg` / `rad` flag on a range line is stored as metadata (`units`) for authors/tools; trig still uses the helpers above
+
+### Animated SVG
+
+Everything after `@svg` can be a self-contained animated figure:
+
+- `<style>` with `@keyframes` (crossfades, pulses, marching dashes)
+- SMIL (`<animate>`, `<animateTransform>`, `<animateMotion>`)
+- Filters (`feGaussianBlur`, …) and paint servers such as `url(#id)`
+- `<use href="#symbol-id">` for icons defined in the same SVG
+
+Scripts, event handlers, and remote URLs are still removed. The figure is mounted in a shadow root so its CSS cannot restyle the editor. The SVG is rewritten only when the substituted markup changes, so those animations keep playing while sliders sit still.
+
+A block with only `@svg` (no controls) renders as a full-width figure.
 
 ### Fallback
 
@@ -92,18 +149,24 @@ Load from the toolbar **Examples…** menu, or open the files directly:
 
 - [`examples/amplitude.md`](examples/amplitude.md) — wave amplitude + phase timer
 - [`examples/circular-motion.md`](examples/circular-motion.md) — point on a circle with spin animation
+- [`examples/agent-loop.md`](examples/agent-loop.md) — agent loop drawn as an animated graph
+- [`examples/graph.md`](examples/graph.md) — directed graph you can edit in the preview
 
 ## Project layout
 
 ```
 index.html          Editor shell
 src/
+  index.js          Library entry
   app.js            UI wiring
+  document.js       Block model (parse and serialize)
+  document-editor.js  Preview block editor
   markdown.js       MD + IVM pipeline
   parse-ivm.js      Fence / control parser
   expr.js           Safe expression evaluator
   sanitize-svg.js   SVG sanitizer
   render.js         Controls + SVG binding
+  graph-editor.js   Graph model and canvas editor
 styles/app.css
 examples/
 test/               Node smoke tests
@@ -115,7 +178,7 @@ test/               Node smoke tests
 npm test
 ```
 
-Smoke tests cover the expression engine, IVM parser, SVG sanitizer, renderer, and Markdown pipeline (`linkedom` is used where a DOM is required).
+Smoke tests cover the expression engine, IVM parser, SVG sanitizer, renderer, Markdown pipeline, graph editor, and preview document builder (`linkedom` is used where a DOM is required).
 
 ## License
 

package/examples/agent-loop.md

@@ -0,0 +1,26 @@
+# Agent loop
+
+One pass through an agent: a trigger starts the loop, then think, act, and observe. Done either returns the output or sends the run back to think. Memory feeds think, and act can call tools. The dots travel those edges.
+
+```ivm
+@graph
+@animate path=ortho quantity=3 direction=forward speed=2.2
+@node trigger: "Trigger" x=16 y=16 kind=input
+@node output: "Output" x=688 y=16 kind=output
+@node think: "Think" x=16 y=148
+@node act: "Act" x=248 y=148
+@node observe: "Observe" x=480 y=148
+@node done: "Done?" x=480 y=292 kind=decision
+@node memory: "Memory" x=16 y=436
+@node tools: "Tools" x=248 y=436
+@edge trigger -> think from=bottom to=top
+@edge think -> act
+@edge act -> observe
+@edge observe -> done from=bottom to=top
+@edge done -> output from=right to=bottom
+@edge done -> think from=bottom to=left
+@edge memory -> think from=top to=bottom
+@edge act -> tools from=bottom to=top
+```
+
+Drag any side dot to reconnect a node. On the canvas, change the path, quantity, direction, or seconds and the source updates.

package/examples/amplitude.md

@@ -1,25 +1,22 @@
 # Wave amplitude
 
-Drag **Amplitude** or press **Play** on the phase timer. The path and marker update from `{{expr}}` bindings.
+Drag **amp** or press **Play** on the phase timer. The path and marker update from `{{expr}}` bindings.
 
 ```ivm
-@slider amp: 5..55 = 28 step=1 "Amplitude"
-@timer t: 0..100 = 0 speed=25 loop "Phase"
-@let y = 40 - amp * sin(t * pi / 50)
-@let y2 = 40 - (amp * 0.55) * sin(t * pi / 50 + 1.2)
-@svg
-<svg viewBox="0 0 200 80" width="100%" xmlns="http://www.w3.org/2000/svg">
-  <rect x="0" y="0" width="200" height="80" rx="4" fill="#0f172a"/>
+@slider amp: 5..55 = 28
+@timer t: 0..100 = 0 speed=25
+@let y = 40 - amp * sind(t * 3.6)
+@let y2 = 40 - (amp * 0.55) * sind(t * 3.6 + 68.75)
+@svg 200x80
+  <rect width="200" height="80" rx="4" fill="#0f172a"/>
   <line x1="10" y1="40" x2="190" y2="40" stroke="#334155" stroke-width="1"/>
-  <path d="M 10 40 Q 55 {{round(y,2)}} 100 40 T 190 40"
-        fill="none" stroke="#38bdf8" stroke-width="3"/>
-  <path d="M 10 40 Q 55 {{round(y2,2)}} 100 40 T 190 40"
-        fill="none" stroke="#a78bfa" stroke-width="2" opacity="0.85"/>
-  <circle cx="100" cy="{{round(y,2)}}" r="5" fill="#f472b6"/>
-</svg>
+  <path d="M10 40 Q55 {{y}} 100 40 T190 40" fill="none" stroke="#38bdf8" stroke-width="3"/>
+  <path d="M10 40 Q55 {{y2}} 100 40 T190 40" fill="none" stroke="#a78bfa" stroke-width="2" opacity="0.85"/>
+  <circle cx="100" cy="{{y}}" r="5" fill="#f472b6"/>
 ```
 
 ## Tips
 
 - `@timer` uses **Play / Pause** in the widget chrome.
 - `@let` values are recomputed whenever a slider or timer changes.
+- Prefer `sind` / `cosd` when angles are in degrees.

package/examples/circular-motion.md

@@ -3,23 +3,19 @@
 Adjust **radius** and **angle**, or animate with the timer. The moving point sits on the circle at angle `a`.
 
 ```ivm
-@slider radius: 10..80 = 50 step=1 "Radius"
-@slider angle: 0..360 = 45 step=1 "Angle (°)"
-@timer spin: 0..360 = 0 speed=40 loop "Spin"
-@calc a = angle + spin
-@let x = round(100 + radius * cos(a * pi / 180), 2)
-@let y = round(100 + radius * sin(a * pi / 180), 2)
-@svg
-<svg viewBox="0 0 200 200" width="100%" xmlns="http://www.w3.org/2000/svg">
-  <rect x="0" y="0" width="200" height="200" rx="6" fill="#0f172a"/>
+@slider radius: 10..80 = 50
+@slider angle: 0..360 = 45 deg
+@timer spin: 0..360 = 0 speed=40 deg
+@let a = angle + spin
+@let x = round(100 + radius * cosd(a), 2)
+@let y = round(100 + radius * sind(a), 2)
+@svg 200x200
+  <rect width="200" height="200" rx="6" fill="#0f172a"/>
   <circle cx="100" cy="100" r="{{radius}}" fill="none" stroke="#475569" stroke-width="2"/>
   <line x1="100" y1="100" x2="{{x}}" y2="{{y}}" stroke="#38bdf8" stroke-width="2"/>
   <circle cx="100" cy="100" r="3" fill="#94a3b8"/>
   <circle cx="{{x}}" cy="{{y}}" r="7" fill="#f472b6"/>
-  <text x="8" y="18" fill="#94a3b8" font-size="10" font-family="ui-monospace, monospace">
-    a={{round(a,1)}}°
-  </text>
-</svg>
+  <text x="8" y="18" fill="#94a3b8" font-size="10" font-family="ui-monospace, monospace">a={{round(a,1)}}°</text>
 ```
 
-Press **Play** on **Spin** to sweep the point around the circle while keeping your base angle offset.
+Press **Play** on **spin** to sweep the point around the circle while keeping your base angle offset.

package/examples/graph.md

@@ -0,0 +1,18 @@
+# A small graph
+
+This fence is a directed graph. Drag a node to move it, and drag a dot on its top, right, bottom, or left onto another node to connect them. The source on the left updates when you let go.
+
+```ivm
+@graph
+@node trigger: "Trigger" x=24 y=40 kind=input
+@node think: "Think" x=220 y=40
+@node act: "Act" x=220 y=188
+@node done: "Done?" x=430 y=40 kind=decision
+@node output: "Output" x=430 y=188 kind=output
+@edge trigger -> think
+@edge think -> done
+@edge think -> act
+@edge act -> output
+```
+
+Double-click a label to rename it. Choose a kind, then add a node, or change the kind of the node you have selected. Delete removes the selected node or edge.

package/index.html

@@ -21,6 +21,8 @@
           <option value="">Examples…</option>
           <option value="amplitude.md">amplitude.md</option>
           <option value="circular-motion.md">circular-motion.md</option>
+          <option value="agent-loop.md">agent-loop.md</option>
+          <option value="graph.md">graph.md</option>
         </select>
         <input id="file-input" type="file" accept=".md,text/markdown,text/plain" />
       </div>
@@ -29,8 +31,12 @@
 
     <main class="layout">
       <section class="pane" aria-label="Editor">
-        <div class="pane-title">Source (.md)</div>
+        <div class="pane-tabs" role="tablist" aria-label="Editor view">
+          <button type="button" id="tab-source" role="tab" aria-selected="true" aria-controls="editor">Source</button>
+          <button type="button" id="tab-graph" role="tab" aria-selected="false" aria-controls="graph-editor">Graph editor</button>
+        </div>
         <textarea id="editor" spellcheck="false" aria-label="Markdown source"></textarea>
+        <div id="graph-editor" hidden></div>
       </section>
       <section class="pane" aria-label="Preview">
         <div class="pane-title">Preview</div>

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "interactive-markdown",
-  "version": "0.1.0",
-  "description": "Interactive Markdown (IVM): plain .md with live SVG sliders and timers",
+  "version": "0.2.0",
+  "description": "Interactive Markdown (IVM): plain .md with live SVG, a preview block builder, and an editable graph",
   "main": "./src/index.js",
+  "directories": {
+    "example": "examples",
+    "test": "test"
+  },
   "scripts": {
     "start": "serve .",
-    "test": "node test/smoke-expr.mjs && node test/smoke-parse-ivm.mjs && node test/smoke-sanitize-svg.mjs && node test/smoke-render.mjs && node test/smoke-markdown.mjs",
+    "test": "node test/smoke-expr.mjs && node test/smoke-parse-ivm.mjs && node test/smoke-sanitize-svg.mjs && node test/smoke-render.mjs && node test/smoke-markdown.mjs && node test/smoke-graph.mjs && node test/smoke-document.mjs",
     "test:expr": "node test/smoke-expr.mjs",
     "test:parse": "node test/smoke-parse-ivm.mjs",
     "test:sanitize": "node test/smoke-sanitize-svg.mjs",
     "test:render": "node test/smoke-render.mjs",
-    "test:markdown": "node test/smoke-markdown.mjs"
+    "test:markdown": "node test/smoke-markdown.mjs",
+    "test:graph": "node test/smoke-graph.mjs",
+    "test:document": "node test/smoke-document.mjs"
   },
   "repository": {
     "type": "git",

package/src/app.js

@@ -2,11 +2,14 @@
  * Interactive Markdown — editor + live preview shell.
  */
 
+import { mountDocumentEditor } from "./document-editor.js";
 import { renderDocument } from "./markdown.js";
+import { replaceIvmFence } from "./parse-ivm.js";
 
 const STORAGE_KEY = "interactive-markdown-draft-v1";
 
 const editor = document.getElementById("editor");
+const graphEditorEl = document.getElementById("graph-editor");
 const preview = document.getElementById("preview");
 const statusEl = document.getElementById("status");
 const btnOpen = document.getElementById("btn-open");
@@ -14,9 +17,13 @@ const btnSave = document.getElementById("btn-save");
 const btnClear = document.getElementById("btn-clear");
 const fileInput = document.getElementById("file-input");
 const exampleSelect = document.getElementById("example-select");
+const tabSource = document.getElementById("tab-source");
+const tabGraph = document.getElementById("tab-graph");
 
 /** @type {{ destroy: () => void } | null} */
-let currentMount = null;
+let previewMount = null;
+/** @type {{ destroy: () => void } | null} */
+let graphMount = null;
 let debounceTimer = 0;
 let dirty = false;
 
@@ -24,19 +31,85 @@ function setStatus(msg) {
   if (statusEl) statusEl.textContent = msg;
 }
 
+function persistDraft() {
+  dirty = true;
+  try {
+    localStorage.setItem(STORAGE_KEY, editor.value);
+  } catch (_) {
+    /* ignore quota */
+  }
+}
+
+function showPreviewError(err) {
+  preview.innerHTML = `<div class="im-errors">${escapeHtml(err.message || String(err))}</div>`;
+  setStatus("Render error");
+  console.error(err);
+}
+
+function renderPreview() {
+  if (previewMount) {
+    previewMount.destroy();
+    previewMount = null;
+  }
+  previewMount = renderDocument(preview, editor.value, {
+    onGraphChange(fenceIndex, body) {
+      editor.value = replaceIvmFence(editor.value, fenceIndex, body);
+      persistDraft();
+      setStatus("Graph updated");
+      refreshGraphEditor();
+    },
+  });
+}
+
+function refreshGraphEditor() {
+  if (!graphEditorEl) return;
+  if (graphMount) {
+    graphMount.destroy();
+    graphMount = null;
+  }
+  graphMount = mountDocumentEditor(graphEditorEl, editor.value, {
+    onChange(markdown) {
+      editor.value = markdown;
+      persistDraft();
+      setStatus("Document updated");
+      try {
+        renderPreview();
+      } catch (err) {
+        showPreviewError(err);
+      }
+    },
+    onStatus(msg) {
+      setStatus(msg);
+    },
+  });
+}
+
 function renderNow() {
-  if (currentMount) {
-    currentMount.destroy();
-    currentMount = null;
+  let previewOk = false;
+  try {
+    renderPreview();
+    previewOk = true;
+  } catch (err) {
+    showPreviewError(err);
   }
   try {
-    currentMount = renderDocument(preview, editor.value);
-    setStatus(dirty ? "Edited · preview updated" : "Preview updated");
+    refreshGraphEditor();
   } catch (err) {
-    preview.innerHTML = `<div class="im-errors">${escapeHtml(err.message || String(err))}</div>`;
+    if (graphEditorEl) {
+      graphEditorEl.innerHTML = `<div class="im-errors">${escapeHtml(err.message || String(err))}</div>`;
+    }
     setStatus("Render error");
     console.error(err);
   }
+  if (previewOk) setStatus(dirty ? "Edited · preview updated" : "Preview updated");
+}
+
+function showEditorTab(name) {
+  const source = name !== "graph";
+  if (editor) editor.hidden = !source;
+  if (graphEditorEl) graphEditorEl.hidden = source;
+  tabSource?.setAttribute("aria-selected", source ? "true" : "false");
+  tabGraph?.setAttribute("aria-selected", source ? "false" : "true");
 }
 
 function scheduleRender() {
@@ -90,7 +163,7 @@ async function loadExample(name) {
 
 const DEFAULT_DOC = `# Interactive Markdown
 
-Edit the left pane. The preview updates as you type.
+Edit the source, or open the Graph editor tab. The preview on the right updates as you go.
 
 Use an \`\`\`ivm\`\`\` fence for sliders, timers, and live SVG.
 
@@ -113,6 +186,7 @@ Use an \`\`\`ivm\`\`\` fence for sliders, timers, and live SVG.
 - \`@timer name: min..max = default speed=N loop\`
 - \`@let name = expression\` (or \`@calc\`)
 - \`@svg\` then SVG with \`{{expr}}\` placeholders
+- \`@graph\` with \`@node\` and \`@edge\` for a visual graph editor
 
 Open a \`.md\` file, or save your draft from the toolbar.
 `;
@@ -131,6 +205,9 @@ function init() {
 
   editor.value = start;
   editor.addEventListener("input", scheduleRender);
+  tabSource?.addEventListener("click", () => showEditorTab("source"));
+  tabGraph?.addEventListener("click", () => showEditorTab("graph"));
+  showEditorTab("source");
 
   btnOpen?.addEventListener("click", () => fileInput?.click());
   fileInput?.addEventListener("change", async () => {