duet-mcp 0.6.1

package/lib/wire.d.ts

@@ -0,0 +1,14 @@
+/**
+ * サーバ・ブラウザ・vite の設定が共有する定数。
+ * どこから読まれてもよいように、node の API に依存させないこと。
+ */
+/**
+ * ポートは app.id から導出する（FNV-1a）。
+ * 設定項目を持たないので、分け忘れによる別アプリへの誤接続が起きない。
+ */
+export declare function portFor(appId: string): number;
+export declare const baseUrlFor: (appId: string) => string;
+/** ロングポーリングの長さ。サーバもブラウザも vite もここだけを読む。 */
+export declare const WAIT_MS = 25000;
+export declare const MAX_WAIT_MS = 120000;
+export declare const MIN_WAIT_MS = 1000;

package/lib/wire.js

@@ -0,0 +1,42 @@
+/**
+ * サーバ・ブラウザ・vite の設定が共有する定数。
+ * どこから読まれてもよいように、node の API に依存させないこと。
+ */
+/**
+ * 逃げ道。導出したポートが他のプロセスと衝突したときだけ使う。
+ *
+ * 既定を設定項目にはしない（分け忘れによる別アプリへの誤接続を防ぐため）。
+ * ただし 8000-8999 の 1000 枠なので、衝突したときにアプリ名を変えるしか
+ * 手が無いのは行き過ぎだった。
+ *
+ * 注意: daemon と vite の両方のプロセスに同じ値を渡すこと。片方だけだと
+ * dev server のプロキシ先が daemon と食い違う。
+ */
+function override() {
+    // ここはブラウザにもバンドルされる。process の存在を確かめてから読む。
+    const raw = typeof process === "undefined" ? undefined : process.env?.DUET_PORT;
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 && n < 65536 ? n : undefined;
+}
+/**
+ * ポートは app.id から導出する（FNV-1a）。
+ * 設定項目を持たないので、分け忘れによる別アプリへの誤接続が起きない。
+ */
+export function portFor(appId) {
+    const forced = override();
+    if (forced !== undefined)
+        return forced;
+    let h = 2166136261;
+    for (let i = 0; i < appId.length; i += 1) {
+        h ^= appId.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return 8000 + ((h >>> 0) % 1000);
+}
+export const baseUrlFor = (appId) => `http://127.0.0.1:${portFor(appId)}`;
+/** ロングポーリングの長さ。サーバもブラウザも vite もここだけを読む。 */
+export const WAIT_MS = 25_000;
+export const MAX_WAIT_MS = 120_000;
+export const MIN_WAIT_MS = 1_000;

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "duet-mcp",
+  "version": "0.6.1",
+  "type": "module",
+  "scripts": {
+    "build": "npm run build:package && npm run build:server && npm run build:web",
+    "build:server": "tsc -p tsconfig.json",
+    "build:web": "for c in */ui/vite.config.ts; do vite build --config \"$c\" || exit 1; done",
+    "dev:web": "vite --config ${DUET_APP:-template}/ui/vite.config.ts",
+    "start": "node dist/${DUET_APP:-template}/main.js",
+    "typecheck": "npm run build:package && tsc -p tsconfig.json --noEmit && for c in */ui/tsconfig.json; do tsc -p \"$c\" || exit 1; done",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "build:package": "tsc -p tsconfig.package.json",
+    "prepack": "npm run build:package",
+    "test:package": "node scripts/test-package.mjs"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "hono": "^4.6.14",
+    "playwright": "^1.49.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^22.10.2",
+    "@types/react": "^18.3.17",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react": "^4.3.4",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "zod": "^3.23.8"
+  },
+  "license": "MIT",
+  "description": "A shared JSON document for humans through a GUI and LLMs through MCP.",
+  "author": "Taniguchi Ryoga (SabaCan0141)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SabaCan0141/duet-mcp.git"
+  },
+  "homepage": "https://github.com/SabaCan0141/duet-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/SabaCan0141/duet-mcp/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "lib",
+    "template/*.ts",
+    "template/ui/*.ts",
+    "template/ui/*.tsx",
+    "template/ui/*.json",
+    "template/ui/*.html",
+    "template/ui/*.css",
+    "doc/README.jp.md"
+  ],
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./server": {
+      "types": "./lib/server.d.ts",
+      "import": "./lib/server.js"
+    },
+    "./react": {
+      "types": "./lib/client.d.ts",
+      "import": "./lib/client.js"
+    },
+    "./wire": {
+      "types": "./lib/wire.d.ts",
+      "import": "./lib/wire.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "gui",
+    "human-in-the-loop",
+    "react"
+  ],
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "zod": "^3.23.8"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/template/app.ts

@@ -0,0 +1,17 @@
+import { fileURLToPath } from "node:url";
+import { defineApp } from "duet-mcp";
+import { initialDoc, type Doc } from "./doc.js";
+import { ops } from "./ops.js";
+
+export const app = defineApp<Doc>({
+  id: "template",
+  // Resolve the app root from dist/template/app.js, independently of the MCP client cwd.
+  rootDir: fileURLToPath(new URL("../../", import.meta.url)),
+  version: "0.1.0",
+  initialDoc,
+  ops,
+  // The port is derived from the app id. A GUI is required.
+  webDist: "template/ui/dist",
+  // Capture the same GUI for the LLM; only the capture region needs configuration.
+  shot: { selector: "#studio", viewport: { w: 1440, h: 1150 } },
+});

package/template/doc.ts

@@ -0,0 +1,18 @@
+// JSON shared by humans and LLMs. In-progress drafts stay in the UI.
+export type Box = { x: number; y: number; width: number; height: number };
+export type Settings = {
+  caption: string;
+  notes: string;
+  visible: boolean;
+  grid: boolean;
+  style: "solid" | "outline";
+  color: "violet" | "blue" | "coral";
+  opacity: number;
+};
+export type Doc = { text: string; settings: Settings; box: Box };
+export const defaultSettings = (): Settings => ({
+  caption: "Make room for ideas.", notes: "One idea, shaped together by you and AI.",
+  visible: true, grid: true, style: "solid", color: "violet", opacity: 100,
+});
+export const initialDoc = (): Doc => ({ text: "", settings: defaultSettings(), box: { x: 160, y: 120, width: 360, height: 220 } });
+export const CANVAS = { width: 720, height: 480, min: 64 };

package/template/main.ts

@@ -0,0 +1,8 @@
+// Static ESM imports run before console redirection.
+// Any extra stdout output can break JSON-RPC. Keep this entry point limited to
+// redirecting console output and dynamically importing the application.
+console.log = console.error;
+console.info = console.error;
+console.debug = console.error;
+
+await import("./start.js");

package/template/ops.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { opFactory } from "duet-mcp";
+import type { Op } from "duet-mcp";
+import type { Doc } from "./doc.js";
+
+const op = opFactory<Doc>();
+
+// Each operation becomes both an MCP tool and a POST /api/op/:name endpoint.
+// Define operations around intent. Keep typing and drag previews local until committed.
+export const ops: Op<Doc>[] = [
+  op({
+    name: "set_text",
+    description: "Replace the shared note text.",
+    input: { text: z.string() },
+    handler: ({ doc }, { text }) => {
+      // The revision stays unchanged for a no-op; no comparison is needed here.
+      doc.text = text;
+      return { text };
+    },
+  }),
+];
+
+// Commit the form as one edit.
+ops.push(op({
+  name: "set_settings",
+  description: "Set the canvas heading, notes, visibility, grid, style, color, and opacity.",
+  input: {
+    caption: z.string().max(80), notes: z.string().max(500), visible: z.boolean(), grid: z.boolean(),
+    style: z.enum(["solid", "outline"]), color: z.enum(["violet", "blue", "coral"]),
+    opacity: z.number().int().min(10).max(100),
+  },
+  handler: ({ doc }, settings) => { doc.settings = settings; },
+}));
+ops.push(op({
+  name: "set_box",
+  description: "Move or resize the box within a 720×480 canvas. The minimum size is 64×64.",
+  input: { x: z.number().min(0), y: z.number().min(0), width: z.number().min(64), height: z.number().min(64) },
+  handler: ({ doc, reject }, box) => {
+    if (box.x + box.width > 720 || box.y + box.height > 480) return reject("Keep the box within the canvas bounds.");
+    doc.box = box;
+  },
+}));

package/template/start.ts

@@ -0,0 +1,4 @@
+import { runApp } from "duet-mcp/server";
+import { app } from "./app.js";
+
+await runApp(app);

package/template/ui/canvas.tsx

@@ -0,0 +1,91 @@
+import { useEffect, useRef, useState } from "react";
+import { useEdit, type Observed } from "duet-mcp/react";
+import { CANVAS, type Box, type Doc, type Settings } from "../doc";
+import { EditActions } from "./edit-actions";
+const colors = { violet: "#7c3aed", blue: "#2563eb", coral: "#e76c55" };
+const clamp = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));
+type Gesture = { id: number; x: number; y: number; box: Box; mode: string; latest: Box };
+
+export function Canvas({ snap, settings, box: saved }: { snap: Observed<Doc>; settings: Settings; box: Box }) {
+  const edit = useEdit<Box>();
+  const ref = useRef<HTMLCanvasElement>(null);
+  const gesture = useRef<Gesture | null>(null);
+  const [displayWidth, setDisplayWidth] = useState(CANVAS.width);
+  useEffect(() => {
+    const observer = new ResizeObserver(([entry]) => setDisplayWidth(entry.contentRect.width));
+    observer.observe(ref.current!);
+    return () => observer.disconnect();
+  }, []);
+  const box = edit.active ? edit.value! : saved;
+  useEffect(() => {
+    const canvas = ref.current!;
+    const dpr = window.devicePixelRatio || 1;
+    canvas.width = Math.max(1, Math.round(displayWidth * dpr)); canvas.height = Math.max(1, Math.round(displayWidth * 2 / 3 * dpr));
+    const c = canvas.getContext("2d")!;
+    c.scale(canvas.width / CANVAS.width, canvas.height / CANVAS.height);
+    c.fillStyle = "#fcfcfe"; c.fillRect(0, 0, 720, 480);
+    if (settings.grid) {
+      c.fillStyle = "#dddde8";
+      for (let x = 24; x < 720; x += 24) for (let y = 24; y < 480; y += 24) { c.beginPath(); c.arc(x, y, 1, 0, Math.PI * 2); c.fill(); }
+    }
+    if (!settings.visible) return;
+    c.save(); c.globalAlpha = settings.opacity / 100;
+    c.fillStyle = settings.style === "solid" ? colors[settings.color] : "#fff";
+    c.strokeStyle = colors[settings.color]; c.lineWidth = 2;
+    c.beginPath(); c.roundRect(box.x, box.y, box.width, box.height, 12); c.fill(); c.stroke();
+    c.save(); c.beginPath(); c.rect(box.x + 12, box.y + 10, Math.max(0, box.width - 24), Math.max(0, box.height - 20)); c.clip();
+    c.fillStyle = settings.style === "solid" ? "#fff" : colors[settings.color];
+    c.font = "600 24px system-ui"; c.textAlign = "center";
+    c.fillText(settings.caption, box.x + box.width / 2, box.y + box.height / 2, Math.max(1, box.width - 36));
+    c.font = "11px system-ui"; c.globalAlpha *= .7;
+    c.fillText("A LITTLE SPACE FOR SOMETHING GREAT", box.x + box.width / 2, box.y + box.height / 2 + 28, Math.max(1, box.width - 36));
+    c.restore(); c.restore();
+    c.strokeStyle = "#8b5cf6"; c.lineWidth = 1; c.strokeRect(box.x - 5, box.y - 5, box.width + 10, box.height + 10);
+    for (const [x, y] of [[box.x,box.y],[box.x+box.width,box.y],[box.x,box.y+box.height],[box.x+box.width,box.y+box.height]]) {
+      c.fillStyle = "white"; c.fillRect(x-5,y-5,10,10); c.strokeRect(x-5,y-5,10,10);
+    }
+  }, [box, settings, displayWidth]);
+  const point = (e: React.PointerEvent<HTMLCanvasElement>) => { const r=e.currentTarget.getBoundingClientRect(); return { x:(e.clientX-r.left)*720/r.width, y:(e.clientY-r.top)*480/r.height }; };
+  const hit = (p: {x:number;y:number}) => {
+    const corners = [["nw",box.x,box.y],["ne",box.x+box.width,box.y],["sw",box.x,box.y+box.height],["se",box.x+box.width,box.y+box.height]] as const;
+    const radius = 12 * 720 / (ref.current?.getBoundingClientRect().width || 720);
+    for (const [mode,x,y] of corners) if (Math.abs(p.x-x)<radius && Math.abs(p.y-y)<radius) return mode;
+    return p.x>=box.x && p.x<=box.x+box.width && p.y>=box.y && p.y<=box.y+box.height ? "move" : "";
+  };
+  const cancel = () => { if (gesture.current) { gesture.current=null; edit.cancel(); } };
+  return <section className="panel overflow-hidden">
+    <div className="flex items-center justify-between border-b border-slate-100 px-6 py-4"><h2 className="text-sm font-semibold">Canvas playground</h2><span className="rounded-md bg-slate-100 px-2 py-1 text-[10px] text-slate-500">720 × 480</span></div>
+    <div className="p-4 sm:p-6">
+      <canvas ref={ref} aria-label="Canvas: move and resize the box" tabIndex={0} className="block aspect-[3/2] w-full touch-none rounded-xl border border-slate-200"
+        onKeyDown={e => { if(e.key === "Escape") cancel(); }}
+        onPointerDown={e => {
+          if(e.button!==0 || !settings.visible || edit.active || gesture.current) return;
+          const p=point(e), mode=hit(p); if(!mode) return;
+          e.currentTarget.focus(); e.currentTarget.setPointerCapture(e.pointerId);
+          gesture.current={id:e.pointerId,...p,box:{...saved},mode,latest:{...saved}}; edit.begin(snap,{...saved});
+        }}
+        onPointerMove={e => {
+          const p=point(e), g=gesture.current;
+          if(!g) { const mode=settings.visible ? hit(p) : ""; e.currentTarget.style.cursor=mode==="move"?"grab":mode==="nw"||mode==="se"?"nwse-resize":mode?"nesw-resize":"default"; return; }
+          if(g.id!==e.pointerId) return;
+          const dx=p.x-g.x,dy=p.y-g.y,b=g.box; let next:Box;
+          if(g.mode==="move") next={...b,x:clamp(b.x+dx,0,720-b.width),y:clamp(b.y+dy,0,480-b.height)};
+          else {
+            const left=g.mode.includes("w")?clamp(b.x+dx,0,b.x+b.width-64):b.x;
+            const top=g.mode.includes("n")?clamp(b.y+dy,0,b.y+b.height-64):b.y;
+            const right=g.mode.includes("e")?clamp(b.x+b.width+dx,b.x+64,720):b.x+b.width;
+            const bottom=g.mode.includes("s")?clamp(b.y+b.height+dy,b.y+64,480):b.y+b.height;
+            next={x:left,y:top,width:right-left,height:bottom-top};
+          }
+          g.latest=Object.fromEntries(Object.entries(next).map(([k,v])=>[k,Math.round(v)])) as Box; edit.setValue(g.latest);
+        }}
+        onPointerUp={e => { const g=gesture.current;if(!g||g.id!==e.pointerId)return;gesture.current=null;e.currentTarget.releasePointerCapture(e.pointerId);void edit.run("set_box",g.latest).catch(()=>{}); }}
+        onPointerCancel={cancel} onLostPointerCapture={cancel} />
+      <div className="mt-4 flex flex-wrap items-center justify-between gap-3 text-xs text-slate-400"><span>Drag to move · Resize from corners · Esc to cancel</span><span className="font-mono">{Math.round(box.width)} × {Math.round(box.height)}</span></div>
+      <div className="mt-5 grid grid-cols-4 gap-3">
+        {(["x","y","width","height"] as const).map(key=><label key={key}><span className="label">{({x:"X",y:"Y",width:"Width",height:"Height"})[key]}</span><input className="field" aria-label={`Box ${key}`} type="number" min={key==="x"||key==="y"?0:64} max={key==="x"||key==="width"?720:480} value={box[key]} disabled={edit.pending} onChange={e=>{if(!edit.active)edit.begin(snap,{...saved});edit.setValue({...box,[key]:Number(e.target.value)});}} /></label>)}
+      </div>
+      {edit.active && <EditActions edit={edit} snap={snap} name="set_box" args={v=>({...v})} current={JSON.stringify(saved)} />}
+    </div>
+  </section>;
+}

package/template/ui/card-editing.tsx

@@ -0,0 +1,48 @@
+// Example for movable lists. Keep drafts in a Map outside the columns.
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { refreshDoc, type Observed, useDoc } from "duet-mcp/react";
+import { EditSession } from "duet-mcp/react";
+
+type CardsDoc = { cards: { id: string; column: string; title: string }[] };
+export function CardEditingExample() {
+  const snap = useDoc<CardsDoc>();
+  const [editors] = useState(() => new Map<string, EditSession<string>>());
+  if (!snap) return null;
+  // Keep deleted cards visible while editing so their drafts can be recovered.
+  const ids = [...new Set([...snap.doc.cards.map(c => c.id), ...editors.keys()])];
+  return <>{["todo", "done", "deleted"].map(column => <section key={column}>
+    <h2>{column}</h2>
+    {ids.filter(id => (snap.doc.cards.find(c => c.id === id)?.column ?? "deleted") === column).map(id => {
+      let editor = editors.get(id);
+      if (!editor) { editor = new EditSession<string>(); editors.set(id, editor); }
+      return <CardEditor key={id} id={id} snap={snap} editor={editor} />;
+    })}
+  </section>)}</>;
+}
+function CardEditor({id,snap,editor}:{id:string;snap:Observed<CardsDoc>;editor:EditSession<string>}) {
+  const state=useSyncExternalStore(editor.subscribe,editor.getSnapshot,editor.getSnapshot);
+  const [confirmed, setConfirmed] = useState(false);
+  useEffect(() => { setConfirmed(false); }, [state.error]);
+  const card=snap.doc.cards.find(c=>c.id===id);
+  const value=state.active ? state.value! : card?.title ?? "";
+  const blocked=!!state.error || !!(state.result && "conflict" in state.result);
+  return <div>
+    <input aria-label={id} value={value} disabled={state.pending} onChange={e=>{
+      if(!state.active)editor.begin(snap,card?.title??"");
+      editor.setValue(e.target.value);
+    }}/>
+    <button disabled={!card || !state.active || state.pending || blocked}
+      onClick={()=>{void editor.run("rename_card",{cardId:id,title:value}).catch(()=>{});}}>Save</button>
+    <button disabled={!state.active || state.pending} onClick={editor.cancel}>Cancel</button>
+    {!card && <span>This card was deleted. You can still copy your draft.</span>}
+    {blocked && <section>
+      <p>{state.error ?? "The document changed while you were editing."}</p>
+      <p>Current: {card?.title ?? "(deleted)"} / Draft: {value}</p>
+      <button onClick={() => { void refreshDoc().then(() => setConfirmed(true)); }}>Refresh current values</button>
+      <button disabled={!card || state.pending || (!!state.error && !confirmed)} onClick={() => {
+        editor.restart(snap, value);
+        void editor.run("rename_card", { cardId: id, title: value }).catch(() => {});
+      }}>Review and apply draft</button>
+    </section>}
+  </div>;
+}

package/template/ui/edit-actions.tsx

@@ -0,0 +1,30 @@
+import { useState } from "react";
+import { refreshDoc, useEdit, type Observed } from "duet-mcp/react";
+import type { Doc } from "../doc";
+
+export function EditActions<T>({ edit, snap, name, args, current }: {
+  edit: ReturnType<typeof useEdit<T>>; snap: Observed<Doc>; name: string;
+  args: (value: T) => Record<string, unknown>; current: string;
+}) {
+  const [confirmedError, setConfirmedError] = useState<string | null>(null);
+  const [refreshError, setRefreshError] = useState("");
+  const conflict = !!edit.result && "conflict" in edit.result;
+  const rejected = edit.result && "rejected" in edit.result ? edit.result.rejected : null;
+  const send = () => { setConfirmedError(null); void edit.run(name, args(edit.value!)).catch(() => {}); };
+  return <div className="mt-4 space-y-3">
+    <div className="flex items-center gap-2">
+      <button className="primary" disabled={!edit.active || edit.pending || conflict || !!edit.error} onClick={send}>Apply</button>
+      <button className="secondary" disabled={!edit.active || edit.pending} onClick={edit.cancel}>Cancel</button>
+      <span className="text-xs text-slate-400" role="status">{edit.pending ? "Saving…" : edit.active ? "Unsaved changes" : "Saved"}</span>
+    </div>
+    {rejected && <p role="alert" className="text-xs text-rose-600">{rejected}</p>}
+    {(conflict || edit.error) && <section className="space-y-3 rounded-xl bg-amber-50 p-3 text-xs" aria-label="Review changes">
+      <p role="alert">{edit.error ?? "The document changed while you were editing. Review the current values and your draft."}</p>
+      <p className="break-words">Current: {current}</p>
+      <p className="break-words">Draft: {JSON.stringify(edit.value)}</p>
+      <button className="secondary" onClick={() => { void refreshDoc().then(() => {setConfirmedError(edit.error);setRefreshError("");}).catch(e => setRefreshError(String(e))); }}>Refresh current values</button>
+      {refreshError && <p role="alert">{refreshError}</p>}
+      <button className="primary" disabled={edit.pending || (!!edit.error && confirmedError !== edit.error)} onClick={() => { edit.restart(snap, edit.value!); send(); }}>Review and apply draft</button>
+    </section>}
+  </div>;
+}

package/template/ui/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>duet — Studio playground</title>
+    <style>
+      html, body { margin: 0; background: #f5f5f5; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/template/ui/main.tsx

@@ -0,0 +1,53 @@
+import { createRoot } from "react-dom/client";
+import { useDoc, useEdit } from "duet-mcp/react";
+import { defaultSettings, initialDoc, type Doc, type Settings } from "../doc";
+import { EditActions } from "./edit-actions";
+import { Canvas } from "./canvas";
+import "./style.css";
+
+function App() {
+  const snap = useDoc<Doc>();
+  const edit = useEdit<Settings>();
+  const textEdit = useEdit<string>();
+  if (!snap) return <main className="p-12 text-sm text-slate-500">Connecting to the studio…</main>;
+  // Provide defaults for text-only snapshots. Save new fields through their operations.
+  const saved = snap.doc.settings ?? defaultSettings();
+  const settings = edit.active ? edit.value! : saved;
+  const set = <K extends keyof Settings>(key: K, value: Settings[K]) => {
+    if (!edit.active) edit.begin(snap, { ...saved });
+    edit.setValue({ ...settings, [key]: value });
+  };
+  return <div id="studio" className="min-h-screen">
+    <header className="border-b border-slate-200/80 bg-white">
+      <div className="mx-auto flex max-w-[1440px] items-center justify-between px-5 py-5 sm:px-10">
+        <div className="flex items-center gap-3"><span className="flex h-9 w-9 items-center justify-center rounded-xl bg-violet-600 text-xl font-bold text-white">d.</span><span className="text-lg font-semibold tracking-tight">duet<span className="ml-3 border-l border-slate-200 pl-3 text-sm font-normal text-slate-400">playground</span></span></div>
+        <div className="flex items-center gap-2 rounded-full border border-emerald-100 bg-emerald-50 px-3 py-1.5 text-xs text-emerald-700"><span className="h-1.5 w-1.5 rounded-full bg-emerald-500"/>Live<span className="hidden sm:inline"> · {snap.actor}</span></div>
+      </div>
+    </header>
+    <main className="mx-auto max-w-[1440px] px-5 py-8 sm:px-10 sm:py-10">
+      <div className="mb-8 flex flex-wrap items-end justify-between gap-4"><div><p className="mb-2 text-[10px] font-bold tracking-[.2em] text-violet-600">YOUR SHARED CREATIVE SPACE</p><h1 className="text-3xl font-semibold tracking-tight">A little space for big ideas.</h1><p className="mt-3 text-sm text-slate-500">Tweak the controls. Move things around. One studio for you and AI.</p></div><span className="rounded-full border border-slate-200 bg-white px-3 py-1.5 text-xs text-slate-500">Studio / 01</span></div>
+      <div className="grid items-start gap-6 lg:grid-cols-[340px_minmax(0,1fr)]">
+        <section className="panel" aria-label="Design settings">
+          <div className="border-b border-slate-100 px-6 py-4"><h2 className="text-sm font-semibold">Design controls</h2><p className="mt-1 text-xs text-slate-400">Apply your settings to update the canvas.</p></div>
+          <div className="space-y-5 p-6"><fieldset disabled={edit.pending} className="space-y-5">
+            <label className="block"><span className="label">Heading</span><input className="field" maxLength={80} value={settings.caption} onChange={e=>set("caption",e.target.value)} /></label>
+            <label className="block"><span className="label">Notes</span><textarea className="field min-h-20 resize-y" maxLength={500} value={settings.notes} onChange={e=>set("notes",e.target.value)} /></label>
+            <div className="border-t border-slate-100 pt-5"><span className="label">Display options</span><div className="space-y-3 text-sm"><label className="flex items-center gap-2.5"><input type="checkbox" className="h-4 w-4" checked={settings.visible} onChange={e=>set("visible",e.target.checked)} />Show box</label><label className="flex items-center gap-2.5"><input type="checkbox" className="h-4 w-4" checked={settings.grid} onChange={e=>set("grid",e.target.checked)} />Dot grid</label></div></div>
+            <fieldset><legend className="label">Style</legend><div className="grid grid-cols-2 gap-2">{([['solid','Solid'],['outline','Outline']] as const).map(([v,label])=><label key={v} className={`flex cursor-pointer items-center gap-2 rounded-lg border p-3 text-xs ${settings.style===v?'border-violet-300 bg-violet-50 text-violet-700':'border-slate-200'}`}><input type="radio" name="style" value={v} checked={settings.style===v} onChange={()=>set("style",v)}/>{label}</label>)}</div></fieldset>
+            <label className="block"><span className="label">Accent color</span><select className="field" value={settings.color} onChange={e=>set("color",e.target.value as Settings['color'])}><option value="violet">Violet</option><option value="blue">Blue</option><option value="coral">Coral</option></select></label>
+            <label className="block"><span className="label flex justify-between">Opacity<span className="font-mono text-violet-600">{settings.opacity}%</span></span><input className="w-full" type="range" min={10} max={100} value={settings.opacity} onChange={e=>set("opacity",Number(e.target.value))}/></label>
+          </fieldset><EditActions edit={edit} snap={snap} name="set_settings" args={v=>({...v})} current={JSON.stringify(saved)}/></div>
+        </section>
+        <div className="space-y-6"><Canvas snap={snap} settings={saved} box={snap.doc.box ?? initialDoc().box}/>
+          <section className="panel p-6" aria-label="Shared note"><div className="mb-4 flex items-center gap-2"><span className="text-violet-500">✦</span><h2 className="text-sm font-semibold">Shared note</h2></div><p className="mb-4 whitespace-pre-wrap text-sm text-slate-500">{saved.notes}</p>
+            <label htmlFor="text" className="label">Text</label><input id="text" className="field" placeholder="Leave a note for your collaborator…" disabled={textEdit.pending} value={textEdit.active?textEdit.value!:snap.doc.text} onChange={e=>{if(!textEdit.active)textEdit.begin(snap,snap.doc.text);textEdit.setValue(e.target.value);}} />
+            <EditActions edit={textEdit} snap={snap} name="set_text" args={text=>({text})} current={snap.doc.text}/>
+            <div id="shot" className="mt-4 whitespace-pre-wrap rounded-lg bg-slate-50 p-4 text-sm text-slate-600">{snap.doc.text || "No notes yet."}</div>
+          </section>
+        </div>
+      </div>
+      <footer className="mt-8 flex flex-wrap justify-between gap-2 text-[11px] text-slate-400"><span>Made for two. Built with duet.</span><span>Changes are shared with everyone in this studio.</span></footer>
+    </main>
+  </div>;
+}
+createRoot(document.getElementById("root")!).render(<App />);

package/template/ui/style.css

@@ -0,0 +1,15 @@
+@import "tailwindcss";
+@theme { --font-sans: "Inter", "Hiragino Sans", "Noto Sans", system-ui, sans-serif; }
+@layer base {
+  body { @apply m-0 bg-[#f5f5f7] text-slate-800 antialiased; }
+  button, input, select, textarea { @apply accent-violet-600; }
+  button { @apply cursor-pointer transition-colors disabled:cursor-not-allowed disabled:opacity-40; }
+  button:focus-visible, input:focus-visible, textarea:focus-visible, select:focus-visible, canvas:focus-visible { @apply outline-2 outline-offset-4 outline-violet-500; }
+}
+@layer components {
+  .panel { @apply rounded-2xl border border-slate-200/80 bg-white shadow-sm; }
+  .field { @apply w-full rounded-lg border border-slate-200 bg-white px-3 py-2.5 text-sm outline-none focus:border-violet-400; }
+  .label { @apply mb-2 block text-xs font-semibold text-slate-600; }
+  .primary { @apply rounded-lg bg-violet-600 px-4 py-2.5 text-xs font-semibold text-white hover:bg-violet-700; }
+  .secondary { @apply rounded-lg border border-slate-200 bg-white px-3 py-2.5 text-xs font-medium hover:bg-slate-50; }
+}

package/template/ui/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  // Include UI files and shared document types; keep server modules out of this build.
+  "include": ["*.ts", "*.tsx", "../doc.ts"]
+}

package/template/ui/vite.config.ts

@@ -0,0 +1,24 @@
+import path from "node:path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { portFor } from "duet-mcp/wire";
+
+// Match the directory name to app.id when copying or renaming the template.
+const appId = path.basename(path.resolve(__dirname, ".."));
+
+// Use the same port derivation as the server.
+const target = `http://127.0.0.1:${portFor(appId)}`;
+
+export default defineConfig({
+  root: __dirname,
+  plugins: [react(), tailwindcss()],
+  build: { outDir: "dist", emptyOutDir: true },
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": { target, changeOrigin: true },
+      "/blob": { target, changeOrigin: true },
+    },
+  },
+});