interactive-markdown 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# Interactive Markdown (IVM)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**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.
+
+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.
+
+License: **MIT** (see [LICENSE](LICENSE)).
+
+## Features
+
+- Split **editor** and **live preview**
+- Open / save `.md`, with a **localStorage** draft
+- IVM widgets: `@slider`, `@timer` (Play/Pause), `@input`, `@toggle`
+- Derived values with `@let` / `@calc`
+- SVG templates with `{{expr}}` bindings
+- Whitelist expression evaluator (no `eval`)
+- SVG sanitizer (strips scripts, event handlers, external hrefs)
+
+## Quick start
+
+Requires Node.js 18+.
+
+```bash
+git clone https://github.com/Thomas2032/interactive-markdown.git
+cd interactive-markdown
+npm install
+npm start
+```
+
+Then open the URL printed by the static server (typically `http://localhost:3000`).
+
+Equivalent without the npm script:
+
+```bash
+npx serve .
+```
+
+> ES modules need HTTP — opening `index.html` as a `file://` URL will not work.
+
+## IVM dialect (quick reference)
+
+Fence name: **`ivm`**.
+
+````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>
+```
+````
+
+### Controls
+
+| 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` |
+| `@ns name` | Share variable state across IVM blocks with the same name |
+| `@svg` | Everything after this line is SVG markup |
+
+### Expressions (`{{…}}`)
+
+Placeholders use **double braces**: `{{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`.
+
+Constants: `pi`, `e`, `tau`.
+
+Angles for trig functions are in **radians** (use `deg` / `rad` helpers as needed).
+
+### Fallback
+
+In a normal Markdown viewer, an `ivm` fence shows up as a plain code block — still readable, just not interactive.
+
+## Examples
+
+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
+
+## Project layout
+
+```
+index.html          Editor shell
+src/
+  app.js            UI wiring
+  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
+styles/app.css
+examples/
+test/               Node smoke tests
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+Smoke tests cover the expression engine, IVM parser, SVG sanitizer, renderer, and Markdown pipeline (`linkedom` is used where a DOM is required).
+
+## License
+
+[MIT](LICENSE) © 2026 Thomas / Thomas2032

package/examples/amplitude.md

@@ -0,0 +1,25 @@
+# Wave amplitude
+
+Drag **Amplitude** 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"/>
+  <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>
+```
+
+## Tips
+
+- `@timer` uses **Play / Pause** in the widget chrome.
+- `@let` values are recomputed whenever a slider or timer changes.

package/examples/circular-motion.md

@@ -0,0 +1,25 @@
+# Circular motion
+
+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"/>
+  <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>
+```
+
+Press **Play** on **Spin** to sweep the point around the circle while keeping your base angle offset.

package/index.html

@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Interactive Markdown</title>
+    <link rel="stylesheet" href="styles/app.css" />
+    <script src="https://cdn.jsdelivr.net/npm/marked@15.0.7/marked.min.js"></script>
+  </head>
+  <body>
+    <header class="app-header">
+      <div class="brand">
+        <h1>Interactive Markdown</h1>
+        <span>Editor + live IVM preview</span>
+      </div>
+      <div class="toolbar">
+        <button type="button" id="btn-open">Open…</button>
+        <button type="button" id="btn-save" class="primary">Save .md</button>
+        <button type="button" id="btn-clear">Reset</button>
+        <select id="example-select" aria-label="Load example">
+          <option value="">Examples…</option>
+          <option value="amplitude.md">amplitude.md</option>
+          <option value="circular-motion.md">circular-motion.md</option>
+        </select>
+        <input id="file-input" type="file" accept=".md,text/markdown,text/plain" />
+      </div>
+      <div id="status">Loading…</div>
+    </header>
+
+    <main class="layout">
+      <section class="pane" aria-label="Editor">
+        <div class="pane-title">Source (.md)</div>
+        <textarea id="editor" spellcheck="false" aria-label="Markdown source"></textarea>
+      </section>
+      <section class="pane" aria-label="Preview">
+        <div class="pane-title">Preview</div>
+        <div id="preview"></div>
+      </section>
+    </main>
+
+    <script type="module" src="src/app.js"></script>
+  </body>
+</html>

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "interactive-markdown",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Interactive Markdown (IVM): plain .md with live SVG sliders and timers",
+  "main": "./src/index.js",
+  "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: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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Thomas2032/interactive-markdown.git"
+  },
+  "keywords": [
+    "markdown",
+    "svg",
+    "interactive",
+    "ivm",
+    "editor"
+  ],
+  "author": "Thomas Lo",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Thomas2032/interactive-markdown/issues"
+  },
+  "homepage": "https://github.com/Thomas2032/interactive-markdown#readme",
+  "devDependencies": {
+    "linkedom": "^0.18.13",
+    "serve": "^14.2.6"
+  },
+  "type": "module",
+  "dependencies": {
+    "marked": "^18.1.0"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./expr": "./src/expr.js",
+    "./parse-ivm": "./src/parse-ivm.js",
+    "./sanitize-svg": "./src/sanitize-svg.js",
+    "./render": "./src/render.js",
+    "./markdown": "./src/markdown.js"
+  },
+  "files": [
+    "src",
+    "examples",
+    "styles",
+    "index.html",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/app.js

@@ -0,0 +1,184 @@
+/**
+ * Interactive Markdown — editor + live preview shell.
+ */
+
+import { renderDocument } from "./markdown.js";
+
+const STORAGE_KEY = "interactive-markdown-draft-v1";
+
+const editor = document.getElementById("editor");
+const preview = document.getElementById("preview");
+const statusEl = document.getElementById("status");
+const btnOpen = document.getElementById("btn-open");
+const btnSave = document.getElementById("btn-save");
+const btnClear = document.getElementById("btn-clear");
+const fileInput = document.getElementById("file-input");
+const exampleSelect = document.getElementById("example-select");
+
+/** @type {{ destroy: () => void } | null} */
+let currentMount = null;
+let debounceTimer = 0;
+let dirty = false;
+
+function setStatus(msg) {
+  if (statusEl) statusEl.textContent = msg;
+}
+
+function renderNow() {
+  if (currentMount) {
+    currentMount.destroy();
+    currentMount = null;
+  }
+  try {
+    currentMount = renderDocument(preview, editor.value);
+    setStatus(dirty ? "Edited · preview updated" : "Preview updated");
+  } catch (err) {
+    preview.innerHTML = `<div class="im-errors">${escapeHtml(err.message || String(err))}</div>`;
+    setStatus("Render error");
+    console.error(err);
+  }
+}
+
+function scheduleRender() {
+  dirty = true;
+  try {
+    localStorage.setItem(STORAGE_KEY, editor.value);
+  } catch (_) {
+    /* ignore quota */
+  }
+  clearTimeout(debounceTimer);
+  debounceTimer = window.setTimeout(renderNow, 180);
+}
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function downloadMd(filename, text) {
+  const blob = new Blob([text], { type: "text/markdown;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename || "document.md";
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
+
+async function loadExample(name) {
+  if (!name) return;
+  try {
+    const res = await fetch(`examples/${name}`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const text = await res.text();
+    editor.value = text;
+    dirty = false;
+    try {
+      localStorage.setItem(STORAGE_KEY, text);
+    } catch (_) {}
+    renderNow();
+    setStatus(`Loaded examples/${name}`);
+  } catch (err) {
+    setStatus(`Failed to load example: ${err.message}`);
+  }
+}
+
+const DEFAULT_DOC = `# Interactive Markdown
+
+Edit the left pane. The preview updates as you type.
+
+Use an \`\`\`ivm\`\`\` fence for sliders, timers, and live SVG.
+
+\`\`\`ivm
+@slider amp: 5..60 = 30 step=1 "Amplitude"
+@timer t: 0..100 = 0 speed=20 loop "Phase"
+@let y = 40 - amp * sin(t * pi / 50)
+@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" fill="#0f172a"/>
+  <path d="M 10 40 Q 55 {{round(y,2)}} 100 40 T 190 40"
+        fill="none" stroke="#38bdf8" stroke-width="3"/>
+  <circle cx="100" cy="{{round(y,2)}}" r="4" fill="#f472b6"/>
+</svg>
+\`\`\`
+
+**Quick dialect**
+
+- \`@slider name: min..max = default step=S "Label"\`
+- \`@timer name: min..max = default speed=N loop\`
+- \`@let name = expression\` (or \`@calc\`)
+- \`@svg\` then SVG with \`{{expr}}\` placeholders
+
+Open a \`.md\` file, or save your draft from the toolbar.
+`;
+
+function init() {
+  if (!editor || !preview) {
+    console.error("Missing #editor or #preview");
+    return;
+  }
+
+  let start = DEFAULT_DOC;
+  try {
+    const saved = localStorage.getItem(STORAGE_KEY);
+    if (saved && saved.trim()) start = saved;
+  } catch (_) {}
+
+  editor.value = start;
+  editor.addEventListener("input", scheduleRender);
+
+  btnOpen?.addEventListener("click", () => fileInput?.click());
+  fileInput?.addEventListener("change", async () => {
+    const file = fileInput.files?.[0];
+    if (!file) return;
+    const text = await file.text();
+    editor.value = text;
+    dirty = false;
+    try {
+      localStorage.setItem(STORAGE_KEY, text);
+    } catch (_) {}
+    renderNow();
+    setStatus(`Opened ${file.name}`);
+    fileInput.value = "";
+  });
+
+  btnSave?.addEventListener("click", () => {
+    downloadMd("document.md", editor.value);
+    dirty = false;
+    setStatus("Downloaded document.md");
+  });
+
+  btnClear?.addEventListener("click", () => {
+    if (!confirm("Reset editor to the built-in sample and clear the stored draft?")) return;
+    editor.value = DEFAULT_DOC;
+    try {
+      localStorage.removeItem(STORAGE_KEY);
+    } catch (_) {}
+    dirty = false;
+    renderNow();
+    setStatus("Reset to default sample");
+  });
+
+  exampleSelect?.addEventListener("change", () => {
+    const v = exampleSelect.value;
+    if (v) loadExample(v);
+    exampleSelect.value = "";
+  });
+
+  window.addEventListener("keydown", (e) => {
+    if ((e.metaKey || e.ctrlKey) && e.key === "s") {
+      e.preventDefault();
+      downloadMd("document.md", editor.value);
+      setStatus("Downloaded document.md");
+    }
+  });
+
+  renderNow();
+}
+
+init();