@lemonriver/core 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemonriver/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Runtime and CLI for LemonRiver — write slides in slides/, we handle the rest.",
   "type": "module",
   "exports": {
@@ -30,6 +30,12 @@
     "env.d.ts",
     "src/app",
     "src/locale",
+    "src/agent/prompt.ts",
+    "src/agent/provider.ts",
+    "src/agent/types.ts",
+    "src/editing/placeholder-id.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
     "skills",
     "README.md"
   ],
@@ -70,7 +76,7 @@
     "@tailwindcss/vite": "^4.3.3",
     "@vitejs/plugin-react": "^6.1.1",
     "@xyflow/react": "^12.12.0",
-    "chalk": "^6.0.0",
+    "chalk": "^6.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
@@ -84,14 +90,14 @@
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "react-image-crop": "^11.0.10",
-    "react-router-dom": "^7.18.1",
-    "shadcn": "^4.12.0",
+    "react-router-dom": "^7.18.4",
+    "shadcn": "^4.21.4",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",
-    "use-sync-external-store": "^1.6.0",
-    "vite": "^8.3.0"
+    "use-sync-external-store": "^1.7.0",
+    "vite": "^8.3.3"
   },
   "devDependencies": {
     "@playwright/test": "~1.63.0",
@@ -104,6 +110,7 @@
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
+    "check:pack": "node scripts/check-pack.mjs",
     "test:e2e": "pnpm run build && playwright test"
   }
 }

package/skills/apply-comments/SKILL.md

@@ -5,7 +5,7 @@ description: Apply pending @slide-comment markers written by the LemonRiver insp
 
 # Apply slide comments
 
-The LemonRiver editor has an inspector tool that lets the user click on a rendered page element and attach a textual comment (e.g. *"make this red"*, *"change to 'Open Slide Rocks'"*). Each comment is persisted as an in-source JSX marker inside `slides/<slideId>/index.tsx`.
+The LemonRiver editor has a comment mode that lets the user click a rendered page element, or drag across a region of the page, and attach a textual comment (e.g. *"make this red"*, *"change to 'Open Slide Rocks'"*). Each comment is persisted as an in-source JSX marker inside `slides/<slideId>/index.tsx`.
 
 Your job: read those markers, perform the described edits, and delete the markers.
 
@@ -17,8 +17,10 @@ Your job: read those markers, perform the described edits, and delete the marker
 {/* @slide-comment id="c-<8hex>" ts="<ISO>" text="<base64url(JSON)>" */}
 ```
 
-- Always sits on its own line as the **first child inside** the JSX element it refers to (i.e. between that element's opening `>` and its other children). The marker is dropped *into* its target, not floated above it.
-- `text` is base64url-encoded JSON: `{"note": "...", "hint"?: "..."}`.
+- Sits as the **first child inside** the JSX element it refers to (i.e. between that element's opening `>` and its other children). The marker is dropped *into* its target, not floated above it. Newly written markers get a line of their own; older ones may share a line with the content that follows them.
+- `text` is base64url-encoded JSON: `{"note": "...", "hint"?: "...", "rect"?: {"x", "y", "w", "h"}, "page"?: n}`.
+  - `rect` is present when the comment was left on a dragged region rather than on an element. Values are pixels on the 1920×1080 page canvas, measured from the page's top-left corner. The marker still sits inside the deepest element that contains the region, but the note refers to what is *inside* that region — possibly several children, or only part of the enclosing element.
+  - `page` is the 0-based index (into the default export array) of the page the comment was left on.
 - Detection regex (authoritative — use exactly this):
 
   ```
@@ -33,13 +35,14 @@ Your job: read those markers, perform the described edits, and delete the marker
 
 2. **Read the file and find all markers.**
    - Run the regex above against the whole file.
-   - For each match, base64url-decode `text` and `JSON.parse` it to get `{ note, hint? }`.
-   - Record each hit as `{ id, lineIndex (0-based), note, hint }`.
+   - For each match, base64url-decode `text` and `JSON.parse` it to get `{ note, hint?, rect?, page? }`.
+   - Record each hit as `{ id, lineIndex (0-based), note, hint, rect, page }`.
    - If there are no markers, tell the user and stop.
 
 3. **Understand each comment in context.**
    - The targeted JSX element is the **enclosing** element of the marker — i.e. read upward from the marker line until you reach the unclosed JSX opening tag whose body the marker lives in. That element is the target. (For self-closing elements like `<img />`, the inspector hoists the marker to the nearest non-self-closing ancestor; in that case the comment usually refers to a child of the enclosing element rather than the enclosing element itself — use the `note` text to disambiguate.)
    - Read enough surrounding code (parent element, sibling elements, inline styles) to apply the change faithfully. A comment inside a `<div>` with an inline `background` style usually refers to that element's styling, for example.
+   - When the payload has a `rect`, work out which children of the enclosing element fall inside that region (compare their positions and sizes against the rect on the 1920×1080 canvas) and apply the note to those — not to the whole enclosing element.
    - If the `note` is ambiguous, do the smallest reasonable interpretation and mention the assumption in your summary.
 
 4. **Apply edits in reverse line order.**
@@ -47,12 +50,13 @@ Your job: read those markers, perform the described edits, and delete the marker
    - Processing top-down would invalidate line numbers for later markers as the file shrinks/grows.
 
 5. **Remove each marker after applying its edit.**
-   - Delete the entire marker line including its trailing `\n`.
+   - Delete the marker token. If nothing else is left on that line, delete the whole line including its trailing `\n`; if content shares the line, keep that content.
    - Never leave a marker behind for an edit you applied — that signals a failure. Markers deliberately skipped per the edge cases below stay in place.
 
 6. **Verify.**
    - After all edits, re-read the file and confirm the only remaining markers are ones you reported as skipped.
    - Confirm the edited JSX is well-formed (balanced tags, no dangling attributes). If the project's `package.json` has typecheck/lint scripts, run them with the project's package manager; scaffolded projects ship neither TypeScript nor a linter — there, rely on the running dev server (or the `build` script) to surface compile errors. Fix any errors you introduced.
+   - If the dev server is running, screenshot each edited page via `/s/<id>/preview?p=N` to confirm the change looks right — see **Previewing a page visually** in `slide-authoring`.
 
 7. **Report.**
    - Summarise: `N applied, M skipped` plus a one-line description of each change (including the slide id).

package/skills/create-slide/SKILL.md

@@ -82,6 +82,8 @@ If the user asked for a speech script / speaker notes (in the initial request or
 
 Run the checklist in `slide-authoring` ("Self-review before finishing"). It covers structural correctness, layout discipline, and asset existence.
 
+If the dev server is already running, screenshot each page through the preview route and fix what looks off — see **Previewing a page visually** in `slide-authoring`.
+
 ## Step 8 — Hand off to the user
 
 Tell the user:

package/skills/current-slide/SKILL.md

@@ -95,6 +95,7 @@ User: "tighten the spacing on this page"
 3. Read `pagePath` (e.g. `slides/q2-roadmap/index.tsx`).
 4. Identify the page at `pageIndex` in the default-exported array.
 5. Consult the `slide-authoring` skill for spacing rules, then edit that page in place.
+6. To check the result visually, screenshot `s/<slideId>/preview?p=<pageNumber>` on the dev server — see **Previewing a page visually** in `slide-authoring`.
 
 If `current.json` is missing or stale, ask: "Which slide and page should I tighten? The dev server hasn't published a current page recently."
 

package/skills/slide-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: slide-authoring
-description: Technical reference for writing or editing LemonRiver pages — file contract, 1920×1080 canvas, type scale, layout, palette/visual direction, assets, speaker notes, stepped reveals, page transitions, and morph transitions. Consult this whenever you are about to write or modify any file under `slides/<id>/`, including from inside the `create-slide` or `apply-comments` workflows, or for any ad-hoc slide edit. Triggers on phrases like "edit slide", "tweak this page", "fix the layout", "change the palette", "reveal one by one", "add a transition", "morph transition", "write the speaker notes", "generate the script / talk track", "investigate the slide framework", "how do slides work here".
+description: Technical reference for writing or editing LemonRiver pages — file contract, 1920×1080 canvas, type scale, layout, palette/visual direction, assets, speaker notes, stepped reveals, page transitions, and morph transitions. Consult this whenever you are about to write or modify any file under `slides/<id>/`, including from inside the `create-slide` or `apply-comments` workflows, or for any ad-hoc slide edit. Triggers on phrases like "edit slide", "tweak this page", "fix the layout", "change the palette", "reveal one by one", "add a transition", "morph transition", "write the speaker notes", "generate the script / talk track", "preview / screenshot a page", "check how it looks", "investigate the slide framework", "how do slides work here".
 ---
 
 # Authoring LemonRiver pages
@@ -335,6 +335,35 @@ This applies whenever the *visual element* repeats, not whenever the *data* does
 - Arrow keys / PageUp / PageDown navigate. `F` enters fullscreen play mode.
 - In play mode: Space/→ next, ← prev, Esc exit.
 - Hot reload: edit `index.tsx` and the browser updates live.
+- Dev-only preview route `/s/<id>/preview?p=N` renders one page with no editor chrome — see **Previewing a page visually**.
+
+## Previewing a page visually
+
+After writing or editing a page, look at it — the vertical-budget math catches overflow, but not clashing colors, awkward wraps, or a broken image. While the dev server runs, every page has a chrome-less preview URL; don't drive the full editor UI (home → deck → thumbnail) to get there.
+
+1. **Find the dev server.** Read `node_modules/.open-slide/server.json` (written on startup, removed on shutdown):
+
+   ```json
+   { "url": "http://localhost:5173/", "port": 5173, "pid": 41234, "startedAt": "…" }
+   ```
+
+   Missing file = the dev server isn't running. Don't start it yourself unless the user asked; skip the visual check and mention it in your hand-off.
+
+2. **Open** `<url>s/<slideId>/preview?p=<pageNumber>` — `p` is 1-based. Add `&step=<n>` to show only the first `n` `<Step>`s of a stepped page (default: fully revealed).
+
+3. **Wait** for `[data-osd-preview="ready"]` — set once fonts, `data-waitfor` targets, images, and entry animations have settled. It becomes `[data-osd-preview="error"]` instead when the slide id is unknown, the page is out of range, the page throws while rendering, or something hasn't settled within 10 s (a font or image never loaded, a `data-waitfor` target never appeared, an animation is still running); `[data-osd-preview-error]` holds the message. Fix the cause rather than screenshotting anyway.
+
+4. **Screenshot** with a **1920×1080 viewport** so the page renders at native size (smaller viewports scale it down to fit). Use whatever browser tool you have (Playwright / Chrome MCP, a browser-automation tool). If the project already has Playwright installed, the CLI works too — `--no` stops `npx` from downloading it:
+
+   ```bash
+   npx --no playwright screenshot --viewport-size "1920,1080" \
+     --wait-for-selector '[data-osd-preview="ready"]' \
+     "http://localhost:5173/s/<slideId>/preview?p=3" /tmp/<slideId>-p3.png
+   ```
+
+   If no browser tool is available, don't install one without asking — skip the visual check.
+
+Then view the image and fix what you see. The preview hot-reloads like the editor, and it never moves the user's cursor in `current.json`.
 
 ## Self-review before finishing
 
@@ -353,6 +382,7 @@ This applies whenever the *visual element* repeats, not whenever the *data* does
 - [ ] If a `SlideTransition` is declared, every page sits in one family — same duration band (200–280 ms), same easing pair, same hold-then-fade-in shape (no enter delay, no `throughBackground` outside a deliberate section break), magnitude under 12 px / 3%. No six-different-vocabularies decks. When in doubt, omit transitions entirely. (Pages that opt into `morph` may exceed the band to match the morph — see `references/morph.md`.)
 - [ ] If a transition opts into `morph`: every morph `id` is unique per page and stable across the pair, morph geometry is pixel-constant (never measured after mount), no `transform` sits on the morph node, and entrance animations are gated behind `useIsActivePage()`.
 - [ ] If the user asked for a speech script / speaker notes, it lives in `export const notes` (index-aligned with the page array) — not in a markdown or text file.
+- [ ] If the dev server is running, you previewed every page you touched (see **Previewing a page visually**) and fixed what looked off.
 - [ ] Nothing outside `slides/<id>/` was edited.
 
 ## Anti-patterns

package/src/agent/prompt.ts

@@ -0,0 +1,141 @@
+import { UNTITLED_SLIDE_ID_RE } from '../editing/placeholder-id.ts';
+import { parseQuestions } from './provider.ts';
+import type { AgentQuestion, AgentTurnContext } from './types.ts';
+
+const PAGE_BY_PAGE =
+  'Write a new deck page by page so the user can follow along on the canvas: first replace the file with the imports, meta (keeping its existing createdAt), design and the cover page only, then add each remaining page with its own separate edit, keeping the file compiling after every write.';
+
+const DECK_SLUG =
+  "This deck's folder still has a placeholder name. Never rename or move the folder yourself: once the deck has content, end your final reply with a slug for it on a line of its own as <deck-slug>short-kebab-case-english-slug</deck-slug>, and LemonRiver renames the folder from it.";
+
+export function systemPromptAppend(askInstruction: string): string {
+  return [
+    'You are running inside the LemonRiver dev server, driven from its in-app agent panel in the browser rather than a terminal.',
+    'The workspace is a LemonRiver project: decks live under slides/<id>/index.tsx and the dev server hot-reloads every edit, so the user sees changes immediately.',
+    'Use the project skills: create-slide to draft a new deck, apply-comments to resolve @slide-comment markers left by the inspector, create-theme for themes, and slide-authoring as the technical reference before writing a page.',
+    PAGE_BY_PAGE,
+    'Keep replies short and concrete: the panel is narrow. Prefer doing the work over describing it, and finish with a one-line summary of what changed.',
+    askInstruction,
+  ].join(' ');
+}
+
+export function buildTurnPrompt(text: string, context: AgentTurnContext | undefined): string {
+  const lines = contextLines(context);
+  if (lines.length === 0) return text;
+  return `${text}\n\n<open-slide-context>\n${lines.join('\n')}\n</open-slide-context>`;
+}
+
+// Slide titles and selected text come from deck content, so they sit in their
+// own tags with `<` escaped and can't close the context block.
+const escapeTag = (s: string) => s.replace(/</g, '&lt;');
+
+function contextLines(context: AgentTurnContext | undefined): string[] {
+  if (!context?.slideId) return [];
+  const file = `slides/${context.slideId}/index.tsx`;
+  const lines: string[] = [];
+  if (context.newDeck) {
+    lines.push(
+      `${file} is a blank deck created for this request. Draft the deck the user describes into it with the create-slide skill: replace the placeholder page, keep the slide id, and do not create another folder.`,
+      'Ask the create-slide scoping questions in a single round, only for what the request leaves unclear; skip any it already answers.',
+      PAGE_BY_PAGE,
+      DECK_SLUG,
+    );
+    return lines;
+  }
+  lines.push(`The user is viewing slide "${context.slideId}": ${file}.`);
+  if (UNTITLED_SLIDE_ID_RE.test(context.slideId)) lines.push(DECK_SLUG);
+  if (context.slideTitle) {
+    lines.push(`<slide-title>${escapeTag(context.slideTitle)}</slide-title>`);
+  }
+  if (context.pageNumber && context.totalPages) {
+    lines.push(
+      `They are on page ${context.pageNumber} of ${context.totalPages} (0-based index ${context.pageNumber - 1} in the default export array).`,
+    );
+  }
+  if (context.selection) {
+    const { line, column, tagName, text } = context.selection;
+    lines.push(
+      `They have selected a <${escapeTag(tagName)}> element at ${file}:${line}:${column}.${text ? ' Its text is in <selected-text>.' : ''} "This element" refers to it.`,
+    );
+    if (text) lines.push(`<selected-text>${escapeTag(text)}</selected-text>`);
+  }
+  if (context.pendingComments) {
+    lines.push(
+      `There are ${context.pendingComments} pending @slide-comment markers in this slide's source.`,
+    );
+  }
+  return lines;
+}
+
+const DECK_SLUG_RE = /\s*<deck-slug>\s*([^<]*?)\s*<\/deck-slug>\s*/gi;
+
+export function extractDeckSlug(text: string): string | null {
+  let slug: string | null = null;
+  for (const match of text.matchAll(DECK_SLUG_RE)) slug = match[1] || slug;
+  return slug;
+}
+
+// Also drops a tag that is still streaming in, so the marker never flashes
+// in the transcript.
+export function stripDeckSlug(text: string): string {
+  return text
+    .replace(DECK_SLUG_RE, '\n')
+    .replace(/\s*<deck-slug>[^<]*$/i, '')
+    .trimEnd();
+}
+
+export function applyCommentsPrompt(slideId: string): string {
+  return `Use the apply-comments skill to apply every pending @slide-comment marker in slides/${slideId}/index.tsx, then remove the markers.`;
+}
+
+const QUESTIONS_RE = /<open-slide-questions>([\s\S]*?)<\/open-slide-questions>/i;
+
+export const TEXT_QUESTIONS_INSTRUCTION =
+  'You cannot ask the user anything interactively here, and nothing you print in the middle of a turn can be answered. When you need answers before continuing, stop working and end your turn with a final message holding only an <open-slide-questions> block: a JSON array of at most 4 questions shaped like [{"header":"Pages","question":"How many pages?","multiSelect":false,"options":[{"label":"6-10 (Recommended)","description":"Standard length"}]}], each with 2 to 4 options, written in the user\'s language. The panel shows them as a form and sends the answers back as your next message. Write nothing after the block and do not continue the task in the same turn.';
+
+// Splits a reply written under TEXT_QUESTIONS_INSTRUCTION into its prose and
+// questions. Returns null when the reply holds no usable block.
+export function extractQuestionBlock(
+  text: string,
+): { text: string; questions: AgentQuestion[] } | null {
+  const match = QUESTIONS_RE.exec(text);
+  if (!match) return null;
+  const body = match[1]
+    .trim()
+    .replace(/^```(?:json)?\s*/i, '')
+    .replace(/\s*```$/, '');
+  let raw: unknown;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  const questions = parseQuestions({
+    questions: Array.isArray(raw) ? raw : (raw as { questions?: unknown } | null)?.questions,
+  });
+  if (questions.length === 0) return null;
+  return { text: text.replace(QUESTIONS_RE, '').trim(), questions };
+}
+
+export function answersPrompt(
+  questions: AgentQuestion[],
+  answers: Record<string, string> | null,
+): string {
+  if (!answers) {
+    return 'I skipped your questions. Continue the task with your best judgement and sensible defaults.';
+  }
+  const lines = questions.map((q) => `- ${q.question} ${answers[q.question] || '(no answer)'}`);
+  return `My answers:\n${lines.join('\n')}\n\nContinue the task with these answers.`;
+}
+
+// For agents whose history can't be rewound: the edited message goes on top
+// of the old conversation, so the agent is told to set that part aside.
+export function editedPrompt(original: string, text: string): string {
+  return `I went back and edited an earlier message of mine. Treat everything after it in this conversation, including your replies, as discarded, and respond to the edited version instead. Files keep whatever changes were already made.\n\n<original-message>\n${escapeTag(original)}\n</original-message>\n\n${text}`;
+}
+
+// For agents rewound to before the edited message: their history forgets the
+// later turns, but the files on disk still hold what those turns wrote.
+export function rewoundPrompt(text: string): string {
+  return `${text}\n\n<open-slide-note>I went back and edited this message. Files keep the changes made after it in the discarded part of this conversation, so read the current files before editing them.</open-slide-note>`;
+}

package/src/agent/provider.ts

@@ -0,0 +1,123 @@
+import path from 'node:path';
+import type { AgentEffort, AgentModelOption, AgentProviderId, AgentQuestion } from './types.ts';
+
+export type ProviderEvent =
+  | { type: 'session-id'; id: string }
+  // A point in the provider's own history that a later edit can rewind to.
+  | { type: 'checkpoint'; id: string }
+  | { type: 'text-start'; id: string }
+  | { type: 'text-delta'; id: string; text: string }
+  | { type: 'text-end'; id: string; text: string | null }
+  | { type: 'tool-start'; id: string; name: string; title: string; detail: string | null }
+  | { type: 'tool-end'; id: string; ok: boolean }
+  | { type: 'error'; text: string }
+  | { type: 'result'; durationMs: number | null; costUsd: number | null }
+  // Questions the agent wrote into its reply instead of asking through a
+  // tool: the turn ends, and the answers arrive as the next prompt.
+  | { type: 'questions'; questions: AgentQuestion[] };
+
+export type PermissionRequest = { tool: string; title: string; detail: string | null };
+
+export type ProviderRunOptions = {
+  cwd: string;
+  // Directories the agent may write to without asking: the deck and asset
+  // folders. Edits anywhere else (configs, package.json) need approval.
+  writableRoots: string[];
+  prompt: string;
+  systemPromptAppend: string;
+  resume: string | null;
+  resumeAt: string | null;
+  model: string | null;
+  effort: AgentEffort | null;
+  signal: AbortSignal;
+  emit: (event: ProviderEvent) => void;
+  askUser: (questions: AgentQuestion[]) => Promise<Record<string, string> | null>;
+  requestPermission: (request: PermissionRequest) => Promise<boolean>;
+};
+
+export interface AgentProvider {
+  id: AgentProviderId;
+  name: string;
+  sdkPackage: string;
+  cliCommand: string;
+  askInstruction: string;
+  canRewind: boolean;
+  models(): Promise<AgentModelOption[]>;
+  run(opts: ProviderRunOptions): Promise<void>;
+}
+
+export class ProviderUnavailableError extends Error {
+  constructor(provider: AgentProvider) {
+    super(
+      `${provider.name} is not connected: install ${provider.sdkPackage} in this workspace to use it from the agent panel.`,
+    );
+    this.name = 'ProviderUnavailableError';
+  }
+}
+
+const DETAIL_MAX = 400;
+
+export function clipDetail(value: unknown): string | null {
+  if (value === undefined || value === null) return null;
+  const text = typeof value === 'string' ? value : safeJson(value);
+  if (!text) return null;
+  const oneLine = text.replace(/\s+/g, ' ').trim();
+  return oneLine.length > DETAIL_MAX ? `${oneLine.slice(0, DETAIL_MAX - 1)}…` : oneLine;
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export function isInsideRoots(cwd: string, file: unknown, roots: string[]): boolean {
+  if (typeof file !== 'string' || !file) return false;
+  const resolved = path.resolve(cwd, file);
+  return roots.some((root) => {
+    const rel = path.relative(root, resolved);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  });
+}
+
+export function relativeToCwd(cwd: string, file: unknown): string | null {
+  if (typeof file !== 'string' || !file) return null;
+  const normalizedCwd = cwd.replace(/[\\/]+$/, '');
+  if (file.startsWith(normalizedCwd)) {
+    const rest = file.slice(normalizedCwd.length).replace(/^[\\/]+/, '');
+    return rest || '.';
+  }
+  return file;
+}
+
+export function parseQuestions(input: Record<string, unknown>): AgentQuestion[] {
+  const raw = Array.isArray(input.questions) ? input.questions : [];
+  const questions: AgentQuestion[] = [];
+  for (const q of raw) {
+    if (!q || typeof q !== 'object') continue;
+    const r = q as Record<string, unknown>;
+    const options = Array.isArray(r.options)
+      ? r.options
+          .map((o) => {
+            if (!o || typeof o !== 'object') return null;
+            const opt = o as Record<string, unknown>;
+            if (typeof opt.label !== 'string') return null;
+            return {
+              label: opt.label,
+              description: typeof opt.description === 'string' ? opt.description : undefined,
+            };
+          })
+          .filter((o): o is { label: string; description: string | undefined } => o !== null)
+      : [];
+    if (typeof r.question !== 'string') continue;
+    questions.push({
+      header: typeof r.header === 'string' ? r.header : '',
+      question: r.question,
+      options,
+      multiSelect: r.multiSelect === true,
+    });
+  }
+  return questions;
+}

package/src/agent/types.ts

@@ -0,0 +1,151 @@
+export const AGENT_PROVIDER_IDS = ['claude', 'codex'] as const;
+
+export type AgentProviderId = (typeof AGENT_PROVIDER_IDS)[number];
+
+export const AGENT_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+
+export type AgentEffort = (typeof AGENT_EFFORTS)[number];
+
+export function isAgentProviderId(value: unknown): value is AgentProviderId {
+  return typeof value === 'string' && (AGENT_PROVIDER_IDS as readonly string[]).includes(value);
+}
+
+export function isAgentEffort(value: unknown): value is AgentEffort {
+  return typeof value === 'string' && (AGENT_EFFORTS as readonly string[]).includes(value);
+}
+
+export type AgentModelOption = {
+  // Empty when the option stands for the CLI's own default model.
+  id: string;
+  label: string;
+  efforts: AgentEffort[];
+};
+
+export type AgentProviderStatus = {
+  id: AgentProviderId;
+  name: string;
+  sdkPackage: string;
+  sdkVersion: string | null;
+  cliCommand: string;
+  cliFound: boolean;
+  cliVersion: string | null;
+  ready: boolean;
+  models: AgentModelOption[];
+};
+
+export type AgentStatus = {
+  enabled: boolean;
+  packageManager: string;
+  providers: AgentProviderStatus[];
+};
+
+type AgentQuestionOption = { label: string; description?: string };
+
+export type AgentQuestion = {
+  header: string;
+  question: string;
+  options: AgentQuestionOption[];
+  multiSelect: boolean;
+};
+
+export type AgentItem =
+  | {
+      kind: 'user';
+      id: string;
+      ts: string;
+      text: string;
+      // The provider history point just before this message, so editing it
+      // can rewind the agent's conversation there.
+      resumeAt?: string;
+      newDeck?: boolean;
+    }
+  | { kind: 'assistant'; id: string; ts: string; text: string; streaming: boolean }
+  | {
+      kind: 'tool';
+      id: string;
+      ts: string;
+      name: string;
+      title: string;
+      detail: string | null;
+      status: 'running' | 'done' | 'error';
+    }
+  | {
+      kind: 'question';
+      id: string;
+      ts: string;
+      questions: AgentQuestion[];
+      answers: Record<string, string> | null;
+      status: 'pending' | 'answered' | 'cancelled';
+    }
+  | {
+      kind: 'permission';
+      id: string;
+      ts: string;
+      tool: string;
+      title: string;
+      detail: string | null;
+      status: 'pending' | 'allowed' | 'denied';
+    }
+  | { kind: 'error'; id: string; ts: string; text: string }
+  | {
+      kind: 'result';
+      id: string;
+      ts: string;
+      durationMs: number | null;
+      costUsd: number | null;
+      aborted: boolean;
+    };
+
+type AgentSessionStatus = 'idle' | 'running';
+
+export type AgentSessionSummary = {
+  id: string;
+  provider: AgentProviderId;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  status: AgentSessionStatus;
+  slideId: string | null;
+};
+
+export type AgentSession = AgentSessionSummary & {
+  providerSessionId: string | null;
+  providerCheckpoint?: string | null;
+  // Set once the oldest items were dropped to stay under the item cap.
+  trimmed?: boolean;
+  items: AgentItem[];
+};
+
+export type AgentTurnContext = {
+  slideId?: string;
+  slideTitle?: string;
+  pageNumber?: number;
+  totalPages?: number;
+  pendingComments?: number;
+  selection?: { line: number; column: number; tagName: string; text: string } | null;
+  newDeck?: boolean;
+};
+
+export type RespondPayload =
+  | { answers: Record<string, string> }
+  | { allow: boolean }
+  | { cancel: true };
+
+export type AgentStreamEvent =
+  | { type: 'session'; session: AgentSessionSummary }
+  | { type: 'session-removed'; sessionId: string }
+  | { type: 'item'; sessionId: string; item: AgentItem }
+  | { type: 'delta'; sessionId: string; itemId: string; text: string }
+  | { type: 'truncate'; sessionId: string; itemId: string }
+  | { type: 'slide-renamed'; from: string; to: string };
+
+export function sessionSummary(session: AgentSession): AgentSessionSummary {
+  const {
+    providerSessionId: _p,
+    providerCheckpoint: _c,
+    trimmed: _t,
+    items: _i,
+    ...summary
+  } = session;
+  return summary;
+}

package/src/app/app.tsx

@@ -8,6 +8,7 @@ import { AssetsPage } from './routes/assets';
 import { Home } from './routes/home';
 import { HomeShell } from './routes/home-shell';
 import { Presenter } from './routes/presenter';
+import { Preview } from './routes/preview';
 import { Slide } from './routes/slide';
 import { ThemeDetailPage, ThemesGalleryPage } from './routes/themes';
 
@@ -43,6 +44,7 @@ export function App() {
               }
             />
           )}
+          {import.meta.env.DEV && <Route path="/s/:slideId/preview" element={<Preview />} />}
           <Route path="*" element={<NotFound />} />
         </Routes>
       </TooltipProvider>

package/src/app/assets/open-slide.svg

@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512" fill="none">
+  <defs>
+    <linearGradient id="tile" x1="256" y1="16" x2="256" y2="496" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFFFFF"/>
+      <stop offset="1" stop-color="#EFEBE6"/>
+    </linearGradient>
+    <linearGradient id="tile-edge" x1="256" y1="16" x2="256" y2="496" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFFFFF"/>
+      <stop offset="0.5" stop-color="#FFFFFF" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.08"/>
+    </linearGradient>
+    <linearGradient id="slide" x1="256" y1="172" x2="256" y2="340" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FF8A5E"/>
+      <stop offset="0.45" stop-color="#FE5226"/>
+      <stop offset="1" stop-color="#EE4316"/>
+    </linearGradient>
+    <linearGradient id="slide-edge" x1="256" y1="172" x2="256" y2="340" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFFFFF" stop-opacity="0.55"/>
+      <stop offset="0.35" stop-color="#FFFFFF" stop-opacity="0"/>
+      <stop offset="0.8" stop-color="#B8300C" stop-opacity="0"/>
+      <stop offset="1" stop-color="#B8300C" stop-opacity="0.5"/>
+    </linearGradient>
+    <radialGradient id="slide-sheen" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(196 184) rotate(32) scale(200 110)">
+      <stop offset="0" stop-color="#FFFFFF" stop-opacity="0.26"/>
+      <stop offset="1" stop-color="#FFFFFF" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="lift" x="60" y="140" width="392" height="260" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="18" stdDeviation="16" flood-color="#FE5226" flood-opacity="0.32"/>
+      <feDropShadow dx="0" dy="3" stdDeviation="3" flood-color="#8A2306" flood-opacity="0.22"/>
+    </filter>
+  </defs>
+  <rect x="16" y="16" width="480" height="480" rx="112" fill="url(#tile)"/>
+  <rect x="17.5" y="17.5" width="477" height="477" rx="110.5" stroke="url(#tile-edge)" stroke-width="3"/>
+  <g filter="url(#lift)">
+    <rect x="112" y="172" width="288" height="168" rx="34" fill="url(#slide)"/>
+  </g>
+  <rect x="112" y="172" width="288" height="168" rx="34" fill="url(#slide-sheen)"/>
+  <rect x="113.5" y="173.5" width="285" height="165" rx="32.5" stroke="url(#slide-edge)" stroke-width="3"/>
+</svg>