preview-artifact 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anup Aglawe
+
+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

@@ -0,0 +1,190 @@
+# preview-artifact
+
+Open the artifacts your coding agents produce (plans, design docs, audit
+reports, papers) in the browser — **read them beautifully, edit them in place,
+save back to disk, and live-reload** when an agent rewrites the file.
+
+Handles **Markdown** (`.md`), **LaTeX** (`.tex`), and **PDF** (`.pdf`).
+
+Fully local. No cloud, no telemetry, no account.
+
+```bash
+preview-artifact open docs/plans/2026-05-31-some-design.md
+```
+
+## Screenshots
+
+Editorial read view — serif display type, warm paper, orange frame:
+
+![Read view](docs/screenshots/read-markdown.png)
+
+Rich markdown — images, headings, and a live mermaid diagram, GFM tables, task
+lists and KaTeX math:
+
+![Markdown with image](docs/screenshots/showcase.png)
+![Mermaid, checklist, table](docs/screenshots/showcase-diagram.png)
+
+LaTeX (`.tex`) — equations typeset by KaTeX over highlighted source:
+
+![LaTeX](docs/screenshots/latex.png)
+
+WYSIWYG edit mode (Milkdown) with the YAML frontmatter split into its own panel:
+
+![Edit mode](docs/screenshots/edit-markdown.png)
+
+## Why
+
+Terminal markdown is hard to read and IDE preview is read-only & bland. AI
+artifacts are code-heavy — fenced code, mermaid diagrams, GFM tables, YAML
+frontmatter, task lists — and deserve a real reading surface you can also edit.
+
+## Features
+
+- **Read mode** — rich typography (GitHub markdown CSS), syntax-highlighted
+  code (highlight.js), rendered **mermaid** diagrams, GFM tables and task lists,
+  **KaTeX math** (`$…$` / `$$…$$`), and **images** (remote URLs plus local files
+  resolved relative to the document, in both read and edit modes).
+- **LaTeX (`.tex`)** — display equations typeset by KaTeX with the rest shown as
+  highlighted LaTeX source; editable and saveable as plain source.
+- **PDF (`.pdf`)** — embedded read-only viewer.
+- **Edit mode** — Milkdown (ProseMirror) WYSIWYG that round-trips markdown
+  faithfully. YAML frontmatter is split into its own panel so the editor can
+  never corrupt it.
+- **Save** — writes back to the same file. `Cmd/Ctrl+S`.
+- **Live-reload** — a file watcher pushes external changes over a websocket; if
+  you have unsaved edits it asks before discarding them.
+- **Toggle** — `Cmd/Ctrl+E` flips Read ⇄ Edit.
+
+## Install
+
+Requires Node ≥ 18. One command — installs the `preview-artifact` binary
+globally (builds itself on install):
+
+```bash
+# once published to npm:
+npm install -g preview-artifact
+
+# or straight from GitHub today:
+npm install -g github:anup-a/preview-artifact
+```
+
+<details>
+<summary>From a local clone (for development)</summary>
+
+```bash
+git clone https://github.com/anup-a/preview-artifact.git
+cd preview-artifact
+npm install        # runs the build automatically (prepare script)
+npm link           # makes `preview-artifact` available globally
+```
+</details>
+
+## Usage
+
+```bash
+preview-artifact open path/to/file.md   # open in the browser
+preview-artifact path/to/file.md        # shorthand
+preview-artifact open file.md --no-open # start server without launching a browser
+preview-artifact --help
+```
+
+Use it from any project — it's not tied to any particular repo.
+
+## Use it from your coding agent
+
+This tool is meant to be launched *by* your agent when it finishes writing an
+artifact. The CLI self-daemonizes and returns immediately, so agents just run it
+— no backgrounding needed. See [`AGENTS.md`](./AGENTS.md) for the canonical
+instructions; quick reference below.
+
+### Claude Code (plugin)
+
+Install the plugin from this repo's marketplace, which adds the
+`/preview-artifact` command in every project:
+
+```
+/plugin marketplace add anup-a/preview-artifact
+/plugin install preview-artifact@preview-artifact
+```
+
+Then: `/preview-artifact path/to/file.md`. (When working inside this repo the
+command is also auto-available from [`.claude/commands/`](./.claude/commands/).)
+
+### Codex (custom prompt)
+
+Adds a `/preview-artifact` slash command to Codex. See
+[`plugins/codex/`](./plugins/codex/):
+
+```bash
+mkdir -p ~/.codex/prompts
+cp plugins/codex/prompts/preview-artifact.md ~/.codex/prompts/
+```
+
+### Cursor / Aider / other shell agents
+
+They read `AGENTS.md` automatically and can launch it directly:
+
+```bash
+preview-artifact open path/to/file.md   # prints the URL, then returns
+```
+
+### If `preview-artifact` isn't on your agent's PATH
+
+`npm link` installs the binary into npm's global bin. If your agent runs with a
+minimal PATH and can't find it, add npm's global bin to PATH:
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+…or run it straight from the cloned repo without linking at all:
+
+```bash
+node bin/preview-artifact.js open file.md   # from the preview-artifact/ dir
+```
+
+## How it works
+
+One shared **daemon** serves every file; the file is passed as a `?path=` query
+parameter rather than getting its own server/port. The CLI auto-starts the
+daemon (detached) on first use, reuses it afterward, and records its port in
+`~/.preview-artifact/daemon.json`.
+
+```
+bin/preview-artifact.js  CLI — ensures the daemon is up, opens /?path=<file>
+server/index.mjs         daemon: serves the SPA, GET/PUT /api/file?path=,
+                         GET /api/raw?path= (pdf bytes), /ws?path= live-reload
+src/                     Vite + React SPA
+  App.tsx                  orchestration: load, read/edit toggle, save, reload
+  readview.ts              markdown-it + highlight.js + mermaid + KaTeX (read mode)
+  Editor.tsx               Milkdown Crepe wrapper (markdown edit mode)
+  frontmatter.ts           split/join YAML frontmatter so it never round-trips
+.claude/commands/        Claude Code /preview-artifact slash command
+AGENTS.md                instructions for coding agents
+```
+
+- Binds to `127.0.0.1` only and sets no CORS headers, so cross-origin pages
+  can't read API responses or perform preflighted writes.
+- Markdown frontmatter is sliced off before the editor sees the body and
+  re-attached verbatim on save, so YAML survives editing untouched.
+
+## Development
+
+```bash
+node server/index.mjs                 # start the daemon (default port 4317)
+npm run dev                           # Vite dev server, proxies /api + /ws to 4317
+# then open http://localhost:5173/?path=/abs/path/to/file.md
+npm run typecheck
+```
+
+After any change under `src/`, run `npm run build` — the daemon serves the built
+`dist/`, not live source.
+
+## Scope
+
+v1 is deliberately single-file. No directory browser, auth, multi-user, or
+collaboration — git already handles history.
+
+## License
+
+MIT

package/bin/preview-artifact.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// CLI for preview-artifact.
+//
+//   preview-artifact open <file>   open a file in the shared local daemon
+//   preview-artifact <file>        shorthand for "open"
+//   preview-artifact stop          stop the daemon
+//
+// A single daemon serves every file (passed as ?path=), auto-started on first
+// use and reused afterwards. State lives in ~/.preview-artifact/daemon.json.
+import path from "node:path";
+import os from "node:os";
+import { existsSync, readFileSync, mkdirSync, openSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import open from "open";
+
+const STATE_DIR = path.join(os.homedir(), ".preview-artifact");
+const STATE_FILE = path.join(STATE_DIR, "daemon.json");
+const LOG_FILE = path.join(STATE_DIR, "daemon.log");
+const serverEntry = fileURLToPath(new URL("../server/index.mjs", import.meta.url));
+
+function usage(code = 0) {
+  console.log(`preview-artifact — read & edit agent artifacts in the browser
+
+Usage:
+  preview-artifact open <file>   Open a .md / .tex / .pdf file in the browser
+  preview-artifact <file>        Shorthand for "open"
+  preview-artifact stop          Stop the background daemon
+
+Options:
+  --no-open                      Print the URL but don't launch a browser
+  -h, --help                     Show this help
+`);
+  process.exit(code);
+}
+
+function readState() {
+  if (!existsSync(STATE_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Return the port of a running, healthy daemon, or null.
+async function healthyPort() {
+  const state = readState();
+  if (!state?.port) return null;
+  try {
+    const res = await fetch(`http://127.0.0.1:${state.port}/api/health`, {
+      signal: AbortSignal.timeout(800),
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body?.app === "preview-artifact" ? state.port : null;
+  } catch {
+    return null;
+  }
+}
+
+async function startDaemon() {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const out = openSync(LOG_FILE, "a");
+  const child = spawn(process.execPath, [serverEntry], {
+    detached: true,
+    stdio: ["ignore", out, out],
+    env: process.env,
+  });
+  child.unref();
+  // Poll for the daemon to come up (~5s max).
+  for (let i = 0; i < 50; i++) {
+    await new Promise((r) => setTimeout(r, 100));
+    const port = await healthyPort();
+    if (port) return port;
+  }
+  throw new Error(`daemon did not start; see ${LOG_FILE}`);
+}
+
+async function stopDaemon() {
+  const state = readState();
+  if (!state?.pid) {
+    console.log("preview-artifact: no daemon running");
+    return;
+  }
+  try {
+    process.kill(state.pid, "SIGTERM");
+    console.log(`preview-artifact: stopped daemon (pid ${state.pid})`);
+  } catch {
+    console.log("preview-artifact: daemon not running");
+  }
+}
+
+async function openFile(file, noOpen) {
+  const target = path.resolve(process.cwd(), file);
+  if (!existsSync(target)) {
+    console.error(`error: file not found: ${target}`);
+    process.exit(1);
+  }
+  const port = (await healthyPort()) ?? (await startDaemon());
+  const url = `http://127.0.0.1:${port}/?path=${encodeURIComponent(target)}`;
+  console.log(`[preview-artifact] ${path.basename(target)} → ${url}`);
+  if (!noOpen) {
+    await open(url).catch(() => console.log(`open your browser at ${url}`));
+  }
+}
+
+const argv = process.argv.slice(2);
+if (argv.includes("-h") || argv.includes("--help") || argv.length === 0) {
+  usage(0);
+}
+
+const noOpen = argv.includes("--no-open");
+const positional = argv.filter((a) => !a.startsWith("-"));
+
+if (positional[0] === "stop") {
+  await stopDaemon();
+} else {
+  const file = positional[0] === "open" ? positional[1] : positional[0];
+  if (!file) {
+    console.error("error: no file specified\n");
+    usage(1);
+  }
+  await openFile(file, noOpen);
+}

package/dist/assets/apl-CnwPGSsG.js

@@ -0,0 +1 @@
+var e={"+":[`conjugate`,`add`],"−":[`negate`,`subtract`],"×":[`signOf`,`multiply`],"÷":[`reciprocal`,`divide`],"⌈":[`ceiling`,`greaterOf`],"⌊":[`floor`,`lesserOf`],"∣":[`absolute`,`residue`],"⍳":[`indexGenerate`,`indexOf`],"?":[`roll`,`deal`],"⋆":[`exponentiate`,`toThePowerOf`],"⍟":[`naturalLog`,`logToTheBase`],"○":[`piTimes`,`circularFuncs`],"!":[`factorial`,`binomial`],"⌹":[`matrixInverse`,`matrixDivide`],"<":[null,`lessThan`],"≤":[null,`lessThanOrEqual`],"=":[null,`equals`],">":[null,`greaterThan`],"≥":[null,`greaterThanOrEqual`],"≠":[null,`notEqual`],"≡":[`depth`,`match`],"≢":[null,`notMatch`],"∈":[`enlist`,`membership`],"⍷":[null,`find`],"∪":[`unique`,`union`],"∩":[null,`intersection`],"∼":[`not`,`without`],"∨":[null,`or`],"∧":[null,`and`],"⍱":[null,`nor`],"⍲":[null,`nand`],"⍴":[`shapeOf`,`reshape`],",":[`ravel`,`catenate`],"⍪":[null,`firstAxisCatenate`],"⌽":[`reverse`,`rotate`],"⊖":[`axis1Reverse`,`axis1Rotate`],"⍉":[`transpose`,null],"↑":[`first`,`take`],"↓":[null,`drop`],"⊂":[`enclose`,`partitionWithAxis`],"⊃":[`diclose`,`pick`],"⌷":[null,`index`],"⍋":[`gradeUp`,null],"⍒":[`gradeDown`,null],"⊤":[`encode`,null],"⊥":[`decode`,null],"⍕":[`format`,`formatByExample`],"⍎":[`execute`,null],"⊣":[`stop`,`left`],"⊢":[`pass`,`right`]},t=/[\.\/⌿⍀¨⍣]/,n=/⍬/,r=/[\+−×÷⌈⌊∣⍳\?⋆⍟○!⌹<≤=>≥≠≡≢∈⍷∪∩∼∨∧⍱⍲⍴,⍪⌽⊖⍉↑↓⊂⊃⌷⍋⍒⊤⊥⍕⍎⊣⊢]/,i=/←/,a=/[⍝#].*$/,o=function(e){var t=!1;return function(n){return t=n,n===e?t===`\\`:!0}},s={name:`apl`,startState:function(){return{prev:!1,func:!1,op:!1,string:!1,escape:!1}},token:function(s,c){var l;return s.eatSpace()?null:(l=s.next(),l===`"`||l===`'`?(s.eatWhile(o(l)),s.next(),c.prev=!0,`string`):/[\[{\(]/.test(l)?(c.prev=!1,null):/[\]}\)]/.test(l)?(c.prev=!0,null):n.test(l)?(c.prev=!1,`atom`):/[¯\d]/.test(l)?(c.func?(c.func=!1,c.prev=!1):c.prev=!0,s.eatWhile(/[\w\.]/),`number`):t.test(l)||i.test(l)?`operator`:r.test(l)?(c.func=!0,c.prev=!1,e[l]?`variableName.function.standard`:`variableName.function`):a.test(l)?(s.skipToEnd(),`comment`):l===`∘`&&s.peek()===`.`?(s.next(),`variableName.function`):(s.eatWhile(/[\w\$_]/),c.prev=!0,`keyword`))}};export{s as apl};

package/dist/assets/arc-CJ3_-PAT.js

@@ -0,0 +1 @@
+import{At as e,Ct as t,Dt as n,Et as r,Mt as i,Ot as a,St as o,Tt as s,bt as c,jt as l,kt as u,vt as d,xt as f,yt as p}from"./index-Czi2sVlL.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(t,n,i,a,o,s,c){var l=t-i,u=n-a,d=(c?s:-s)/e(l*l+u*u),f=d*u,p=-d*l,m=t+f,h=n+p,g=i+f,_=a+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=o-s,w=m*_-g*h,T=(x<0?-1:1)*e(r(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(o/C-1),y11:D*(o/C-1)}}function x(){var r=m,x=h,S=i(0),C=null,w=g,T=_,E=v,D=null,O=d(k);function k(){var i,d,m=+r.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-s,_=T.apply(this,arguments)-s,v=p(_-g),k=_>g;if(D||=i=O(),h<m&&(d=h,h=m,m=d),!(h>1e-12))D.moveTo(0,0);else if(v>l-1e-12)D.moveTo(h*t(g),h*u(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*t(_),m*u(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):e(m*m+h*h)),R=n(p(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=f(L/m*u(I)),W=f(L/h*u(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*t(A),K=h*u(A),q=m*t(N),J=m*u(N);if(R>1e-12){var Y=h*t(j),X=h*u(j),Z=m*t(M),Q=m*u(M),$;if(v<a)if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/u(c((ee*ne+te*re)/(e(ee*ee+te*te)*e(ne*ne+re*re)))/2),ae=e($[0]*$[0]+$[1]*$[1]);z=n(R,(m-ae)/(ie-1)),B=n(R,(h-ae)/(ie+1))}else z=B=0}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,o(V.y01,V.x01),o(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,o(V.y01,V.x01),o(V.y11,V.x11),!k),D.arc(0,0,h,o(V.cy+V.y11,V.cx+V.x11),o(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,o(H.y11,H.x11),o(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,o(V.y01,V.x01),o(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,o(V.y01,V.x01),o(V.y11,V.x11),!k),D.arc(0,0,m,o(V.cy+V.y11,V.cx+V.x11),o(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,o(H.y11,H.x11),o(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),i)return D=null,i+``||null}return k.centroid=function(){var e=(+r.apply(this,arguments)+ +x.apply(this,arguments))/2,n=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-a/2;return[t(n)*e,u(n)*e]},k.innerRadius=function(e){return arguments.length?(r=typeof e==`function`?e:i(+e),k):r},k.outerRadius=function(e){return arguments.length?(x=typeof e==`function`?e:i(+e),k):x},k.cornerRadius=function(e){return arguments.length?(S=typeof e==`function`?e:i(+e),k):S},k.padRadius=function(e){return arguments.length?(C=e==null?null:typeof e==`function`?e:i(+e),k):C},k.startAngle=function(e){return arguments.length?(w=typeof e==`function`?e:i(+e),k):w},k.endAngle=function(e){return arguments.length?(T=typeof e==`function`?e:i(+e),k):T},k.padAngle=function(e){return arguments.length?(E=typeof e==`function`?e:i(+e),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};

package/dist/assets/architecture-7EHR7CIX-Z0xF5NqR.js

@@ -0,0 +1 @@
+import{x as e}from"./mermaid-parser.core-DedvXRIg.js";export{e as createArchitectureServices};