mulmoclaude 0.1.0

package/server/api/routes/mulmoScriptValidate.ts

@@ -0,0 +1,101 @@
+// Request-body validators for the mulmo-script PUT endpoints. Split
+// from `mulmo-script.ts` so the pure shape checks can be unit-tested
+// without spinning up Express.
+//
+// The `@mulmocast/types` package exports zod schemas that mirror the
+// canonical MulmoScript / MulmoBeat shapes. Using them here keeps the
+// server and client agreeing on what a "valid script" is — the same
+// schemas back client-side edit-time validation in
+// `src/plugins/presentMulmoScript/View.vue`.
+
+import { mulmoBeatSchema, mulmoScriptSchema } from "@mulmocast/types";
+import { isRecord } from "../../utils/types.js";
+
+export type ValidationResult<T> = { ok: true; value: T } | { ok: false; error: string };
+
+function formatZodIssues(
+  // Zod's `$ZodIssue.path` is `PropertyKey[]` (includes `symbol`).
+  // Accept the wider type so callers can pass `safeParse().error.issues`
+  // directly; stringify any non-string/number segments at format time.
+  issues: ReadonlyArray<{ message: string; path: ReadonlyArray<PropertyKey> }>,
+): string {
+  if (issues.length === 0) return "invalid shape";
+  const head = issues
+    .slice(0, 3)
+    .map((i) => {
+      const pathStr = i.path.length > 0 ? i.path.map((seg) => String(seg)).join(".") : "<root>";
+      return `${pathStr}: ${i.message}`;
+    })
+    .join("; ");
+  return issues.length > 3 ? `${head} (+${issues.length - 3} more)` : head;
+}
+
+/**
+ * Validate the `update-script` request body. Returns the parsed,
+ * schema-conformant script on success, or a human-readable error
+ * suitable for sending back as a 400 response.
+ */
+export function validateUpdateScriptBody(body: unknown): ValidationResult<{
+  filePath: string;
+  script: unknown;
+}> {
+  if (!isRecord(body)) {
+    return { ok: false, error: "body must be an object" };
+  }
+  if (typeof body.filePath !== "string" || body.filePath === "") {
+    return { ok: false, error: "filePath must be a non-empty string" };
+  }
+  if (body.script === undefined) {
+    return { ok: false, error: "script is required" };
+  }
+  const parsed = mulmoScriptSchema.safeParse(body.script);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: `invalid script: ${formatZodIssues(parsed.error.issues)}`,
+    };
+  }
+  return {
+    ok: true,
+    value: { filePath: body.filePath as string, script: parsed.data },
+  };
+}
+
+/**
+ * Validate the `update-beat` request body. `beatIndex` is allowed
+ * to be any non-negative integer; the handler still bounds-checks
+ * against the actual script length after reading the file.
+ */
+export function validateUpdateBeatBody(body: unknown): ValidationResult<{
+  filePath: string;
+  beatIndex: number;
+  beat: unknown;
+}> {
+  if (!isRecord(body)) {
+    return { ok: false, error: "body must be an object" };
+  }
+  if (typeof body.filePath !== "string" || body.filePath === "") {
+    return { ok: false, error: "filePath must be a non-empty string" };
+  }
+  if (typeof body.beatIndex !== "number" || !Number.isInteger(body.beatIndex) || body.beatIndex < 0) {
+    return { ok: false, error: "beatIndex must be a non-negative integer" };
+  }
+  if (body.beat === undefined) {
+    return { ok: false, error: "beat is required" };
+  }
+  const parsed = mulmoBeatSchema.safeParse(body.beat);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: `invalid beat: ${formatZodIssues(parsed.error.issues)}`,
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      filePath: body.filePath as string,
+      beatIndex: body.beatIndex as number,
+      beat: parsed.data,
+    },
+  };
+}

package/server/api/routes/notifications.ts

@@ -0,0 +1,69 @@
+// PoC push endpoint — proves the server can fire a delayed message
+// simultaneously to every open Web tab (pub-sub) and every bridge
+// (chat-service `pushToBridge`). Stepping stone for the in-app
+// notification center (#144) and external-channel notifications
+// (#142); see plans/feat-notification-push-scaffold.md for the
+// motivation and the production plan.
+//
+// Usage:
+//   curl -X POST http://localhost:3001/api/notifications/test \
+//     -H "Authorization: Bearer $(cat ~/mulmoclaude/.session-token)" \
+//     -H "Content-Type: application/json" \
+//     -d '{"message":"hello","delaySeconds":5}'
+//
+// The route is exported as a factory so the host wiring can inject
+// the pub-sub publisher and the chat-service push handle without
+// this file pulling in either module directly.
+
+import { Router, type Request, type Response } from "express";
+import { scheduleTestNotification, type NotificationDeps, type ScheduleNotificationOptions } from "../../events/notifications.js";
+import { log } from "../../system/logger/index.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+
+interface TestRequestBody {
+  message?: unknown;
+  delaySeconds?: unknown;
+  transportId?: unknown;
+  chatId?: unknown;
+}
+
+interface TestResponse {
+  firesAt: string;
+  delaySeconds: number;
+}
+
+function parseBody(body: TestRequestBody): ScheduleNotificationOptions {
+  const opts: ScheduleNotificationOptions = {};
+  if (typeof body.message === "string" && body.message.length > 0) {
+    opts.message = body.message;
+  }
+  if (typeof body.delaySeconds === "number") {
+    opts.delaySeconds = body.delaySeconds;
+  }
+  if (typeof body.transportId === "string" && body.transportId.length > 0) {
+    opts.transportId = body.transportId;
+  }
+  if (typeof body.chatId === "string" && body.chatId.length > 0) {
+    opts.chatId = body.chatId;
+  }
+  return opts;
+}
+
+export function createNotificationsRouter(deps: NotificationDeps): Router {
+  const router = Router();
+  router.post(API_ROUTES.notifications.test, (req: Request<object, unknown, TestRequestBody>, res: Response<TestResponse>) => {
+    const opts = parseBody(req.body ?? {});
+    const scheduled = scheduleTestNotification(opts, deps);
+    log.info("notifications", "scheduled test push", {
+      delaySeconds: scheduled.delaySeconds,
+      firesAt: scheduled.firesAt,
+      transportId: opts.transportId,
+      chatId: opts.chatId,
+    });
+    res.status(202).json({
+      firesAt: scheduled.firesAt,
+      delaySeconds: scheduled.delaySeconds,
+    });
+  });
+  return router;
+}

package/server/api/routes/pdf.ts

@@ -0,0 +1,163 @@
+import fs from "fs";
+import path from "path";
+import { Router, Request, Response } from "express";
+import { marked } from "marked";
+import puppeteer from "puppeteer";
+import { errorMessage } from "../../utils/errors.js";
+import { badRequest, serverError } from "../../utils/httpError.js";
+import { WORKSPACE_DIRS } from "../../workspace/paths.js";
+import { resolveWithinRoot, readBinarySafeSync } from "../../utils/files/safe.js";
+import { resolveWorkspacePath } from "../../utils/files/workspace-io.js";
+import { log } from "../../system/logger/index.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+
+const router = Router();
+
+const MARKDOWN_CSS = `
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+    font-size: 13px;
+    line-height: 1.6;
+    color: #1f2937;
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 32px 48px;
+  }
+  h1 { font-size: 1.75rem; font-weight: 700; margin: 0 0 0.75rem; color: #111827; }
+  h2 { font-size: 1.25rem; font-weight: 600; margin: 1.5rem 0 0.5rem; color: #1f2937; border-bottom: 1px solid #e5e7eb; padding-bottom: 0.25rem; }
+  h3 { font-size: 1rem; font-weight: 600; margin: 1rem 0 0.4rem; color: #374151; }
+  p { margin: 0 0 0.75rem; }
+  ul, ol { margin: 0 0 0.75rem 1.5rem; }
+  li { margin-bottom: 0.2rem; }
+  ul { list-style-type: disc; }
+  ol { list-style-type: decimal; }
+  code { background: #f3f4f6; padding: 0.1rem 0.3rem; border-radius: 0.25rem; font-size: 0.85em; font-family: monospace; }
+  pre { background: #f3f4f6; padding: 0.75rem; border-radius: 0.375rem; overflow-x: auto; margin: 0 0 0.75rem; }
+  pre code { background: none; padding: 0; }
+  blockquote { border-left: 3px solid #d1d5db; padding-left: 1rem; color: #6b7280; margin: 0.75rem 0; }
+  hr { border: none; border-top: 1px solid #e5e7eb; margin: 1.25rem 0; }
+  table { border-collapse: collapse; width: 100%; margin: 0 0 0.75rem; font-size: 0.875rem; }
+  th, td { border: 1px solid #e5e7eb; padding: 0.5rem 0.75rem; text-align: left; }
+  th { background: #f9fafb; font-weight: 600; }
+  strong { font-weight: 600; }
+  a { color: #2563eb; }
+  img { max-width: 100%; height: auto; }
+`;
+
+const MIME_BY_EXT: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+};
+
+// Realpath of the workspace, resolved once at module load. Used to
+// validate that image paths resolved relative to markdowns/ stay
+// inside the workspace after symlink resolution.
+const workspaceReal = fs.realpathSync(resolveWorkspacePath(""));
+
+/**
+ * Inline local images as base64 data URIs so Puppeteer can render them.
+ * Markdown files live in workspace/artifacts/documents/ and reference
+ * images as "../images/xyz.png" → workspace/artifacts/images/xyz.png.
+ *
+ * Paths are validated against the workspace root via resolveWithinRoot
+ * so an attacker-controlled <img src="../../../etc/passwd"> can't read
+ * files outside the workspace.
+ */
+function inlineImages(html: string): string {
+  const baseDir = path.join(workspaceReal, WORKSPACE_DIRS.markdowns);
+  return html.replace(/(<img\s[^>]*src=")([^"]+)(")/g, (_match, before: string, src: string, after: string) => {
+    if (src.startsWith("data:") || src.startsWith("http")) {
+      return _match;
+    }
+    // Resolve the image path relative to markdowns/ but require the
+    // final realpath to stay inside the workspace root. markdowns/
+    // references like "../images/foo.png" are common so we can't
+    // restrict to markdowns/ itself.
+    const unsafeAbs = path.resolve(baseDir, src);
+    // Make unsafeAbs relative to the workspace for the
+    // resolveWithinRoot check (it expects a relative path).
+    const relToWorkspace = path.relative(workspaceReal, unsafeAbs);
+    if (relToWorkspace.startsWith("..") || path.isAbsolute(relToWorkspace)) {
+      log.warn("pdf", "image path escapes workspace", { src });
+      return _match;
+    }
+    const abs = resolveWithinRoot(workspaceReal, relToWorkspace);
+    if (!abs) {
+      log.warn("pdf", "image path rejected by safe-resolve", { src });
+      return _match;
+    }
+    const buf = readBinarySafeSync(abs);
+    if (!buf) {
+      log.warn("pdf", "could not read image", { abs });
+      return _match;
+    }
+    const ext = path.extname(abs).toLowerCase();
+    const mime = MIME_BY_EXT[ext] ?? "application/octet-stream";
+    return `${before}data:${mime};base64,${buf.toString("base64")}${after}`;
+  });
+}
+
+function wrapHtml(body: string, css: string): string {
+  return `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>${css}</style>
+</head>
+<body>${body}</body>
+</html>`;
+}
+
+async function renderPdf(fullHtml: string, format: "Letter" | "A4" = "Letter"): Promise<Buffer> {
+  const browser = await puppeteer.launch({ headless: true });
+  try {
+    const page = await browser.newPage();
+    await page.setContent(fullHtml, { waitUntil: "networkidle0" });
+    const pdfBuffer = await page.pdf({
+      format,
+      margin: { top: "16mm", bottom: "16mm", left: "16mm", right: "16mm" },
+      printBackground: true,
+    });
+    return Buffer.from(pdfBuffer);
+  } finally {
+    await browser.close();
+  }
+}
+
+function sendPdf(res: Response, buffer: Buffer, filename: string): void {
+  const safeFilename = filename.endsWith(".pdf") ? filename : `${filename}.pdf`;
+  res.setHeader("Content-Type", "application/pdf");
+  res.setHeader("Content-Disposition", `attachment; filename="document.pdf"; filename*=UTF-8''${encodeURIComponent(safeFilename)}`);
+  res.send(buffer);
+}
+
+interface PdfMarkdownBody {
+  markdown: string;
+  filename?: string;
+  format?: "Letter" | "A4";
+}
+
+router.post(API_ROUTES.pdf.markdown, async (req: Request<object, unknown, PdfMarkdownBody>, res: Response) => {
+  const { markdown, filename = "document.pdf", format = "Letter" } = req.body;
+
+  if (!markdown) {
+    badRequest(res, "markdown is required");
+    return;
+  }
+
+  try {
+    log.info("pdf", "markdown", { filename, length: markdown.length });
+    const html = inlineImages(await marked.parse(markdown));
+    const buffer = await renderPdf(wrapHtml(html, MARKDOWN_CSS), format);
+    sendPdf(res, buffer, filename);
+  } catch (err) {
+    log.error("pdf", "generation failed", { error: String(err) });
+    serverError(res, `PDF generation failed: ${errorMessage(err)}`);
+  }
+});
+
+export default router;

package/server/api/routes/plugins.ts

@@ -0,0 +1,276 @@
+import path from "path";
+import { Router, Request, Response } from "express";
+import { executeMindMap } from "@gui-chat-plugin/mindmap";
+import { executeSpreadsheet, type SpreadsheetArgs } from "../../../src/plugins/spreadsheet/definition.js";
+import { executeQuiz } from "@mulmochat-plugin/quiz";
+import { executeForm } from "@mulmochat-plugin/form";
+import { executeOpenCanvas } from "../../../src/plugins/canvas/definition.js";
+import { executePresent3D } from "@gui-chat-plugin/present3d";
+import { generateGeminiImageFromPrompt, isGeminiAvailable } from "../../utils/gemini.js";
+import { errorMessage } from "../../utils/errors.js";
+import { badRequest, serverError } from "../../utils/httpError.js";
+import { log } from "../../system/logger/index.js";
+import { saveImage } from "../../utils/files/image-store.js";
+import { saveMarkdown, overwriteMarkdown, isMarkdownPath } from "../../utils/files/markdown-store.js";
+import { saveSpreadsheet, overwriteSpreadsheet, isSpreadsheetPath } from "../../utils/files/spreadsheet-store.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { WORKSPACE_DIRS } from "../../workspace/paths.js";
+
+const router = Router();
+
+interface PluginErrorResponse {
+  message: string;
+}
+
+// Wraps a plugin's `execute*` invocation in an Express handler. Each
+// plugin route used to inline the same try/catch + 500 response shell;
+// this collapses them to one line per route.
+//
+// The callback receives the Express request and is responsible for
+// pulling whatever it needs out of `req.body` and forwarding it to
+// the plugin's execute function. `req.body` is `any` by Express
+// default and each plugin's execute function does its own runtime
+// validation — matching the behavior of the inline handlers this
+// replaces.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function wrapPluginExecute<TBody = any, TResult = unknown>(
+  execute: (req: Request<object, unknown, TBody>) => Promise<TResult>,
+): (req: Request<object, unknown, TBody>, res: Response<TResult | PluginErrorResponse>) => Promise<void> {
+  return async (req, res) => {
+    try {
+      const result = await execute(req);
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ message: errorMessage(err) });
+    }
+  };
+}
+
+const IMAGE_PLACEHOLDER = /!\[([^\]]+)\]\(\/?__too_be_replaced_image_path__\)/g;
+
+async function generateImageFile(prompt: string): Promise<string | null> {
+  if (!isGeminiAvailable()) return null;
+  try {
+    const { imageData } = await generateGeminiImageFromPrompt(prompt);
+    if (imageData) return saveImage(imageData);
+    log.warn("present-document", "Gemini returned no image data for prompt", {
+      promptPreview: prompt.slice(0, 80),
+    });
+  } catch (err) {
+    // Surface the failure so missing-image symptoms in the canvas
+    // are debuggable from the server log instead of vanishing.
+    log.warn("present-document", "Gemini image generation failed", {
+      error: errorMessage(err),
+      promptPreview: prompt.slice(0, 80),
+    });
+  }
+  return null;
+}
+
+async function fillImagePlaceholders(markdown: string): Promise<string> {
+  const matches = [...markdown.matchAll(IMAGE_PLACEHOLDER)];
+  if (matches.length === 0) return markdown;
+  // Only attempt generation when Gemini is wired up; otherwise the
+  // placeholder still gets stripped below so we don't leak a broken
+  // <img src="...__too_be_replaced_image_path__"> into the rendered
+  // document.
+  const geminiOk = isGeminiAvailable();
+  if (!geminiOk) {
+    log.warn("present-document", "GEMINI_API_KEY not set — image placeholders will render as text markers", { placeholderCount: matches.length });
+  }
+
+  const results = await Promise.all(
+    matches.map(async (m) => ({
+      full: m[0],
+      prompt: m[1],
+      url: geminiOk ? await generateImageFile(m[1]) : null,
+    })),
+  );
+
+  // Surface a single tally line so the operator can see the
+  // success rate even when most calls go through. The per-call
+  // error already lands at warn from generateImageFile's catch.
+  if (geminiOk) {
+    const failed = results.filter((r) => !r.url).length;
+    if (failed > 0) {
+      log.warn("present-document", "image generation had failures", {
+        failed,
+        total: results.length,
+      });
+    }
+  }
+
+  let filled = markdown;
+  for (const { full, prompt, url } of results) {
+    // On success → real image. On failure / no key → italic text
+    // marker so the alt prompt still surfaces but no broken image
+    // 404s through the View. The user can re-render later once
+    // GEMINI_API_KEY is set.
+    filled = filled.replace(
+      full,
+      // `url` is workspace-relative (e.g. "artifacts/images/xxx.png").
+      // The document lives at "artifacts/documents/yyy.md". Compute a
+      // relative path from the document's directory so the markdown
+      // image reference resolves correctly.
+      url ? `![${prompt}](${path.posix.relative(WORKSPACE_DIRS.markdowns, url)})` : `*🖼️ Image: ${prompt}*`,
+    );
+  }
+  return filled;
+}
+
+// presentDocument — fills image placeholders via Gemini if API key is available
+interface PresentDocumentBody {
+  title: string;
+  markdown: string;
+  filenamePrefix: string;
+}
+
+interface PresentDocumentSuccess {
+  message: string;
+  title: string;
+  data: { markdown: string; filenamePrefix: string };
+}
+
+interface PresentDocumentError {
+  error: string;
+}
+
+router.post(
+  API_ROUTES.plugins.presentDocument,
+  async (req: Request<object, unknown, PresentDocumentBody>, res: Response<PresentDocumentSuccess | PresentDocumentError>) => {
+    const { title, markdown, filenamePrefix } = req.body;
+    if (typeof filenamePrefix !== "string" || filenamePrefix.trim().length === 0) {
+      badRequest(res, "filenamePrefix is required");
+      return;
+    }
+    const filledMarkdown = await fillImagePlaceholders(markdown);
+    const markdownPath = await saveMarkdown(filledMarkdown, filenamePrefix);
+    res.json({
+      message: `Document "${title}" is ready.`,
+      title,
+      data: { markdown: markdownPath, filenamePrefix },
+    });
+  },
+);
+
+// Update markdown file on disk (user edits in View)
+interface UpdateMarkdownBody {
+  markdown: string;
+}
+
+interface UpdateMarkdownResponse {
+  path: string;
+}
+
+interface UpdateMarkdownError {
+  error: string;
+}
+
+router.put(
+  API_ROUTES.plugins.updateMarkdown,
+  async (req: Request<{ filename: string }, unknown, UpdateMarkdownBody>, res: Response<UpdateMarkdownResponse | UpdateMarkdownError>) => {
+    const relativePath = `${WORKSPACE_DIRS.markdowns}/${req.params.filename}`;
+    const { markdown } = req.body;
+    if (!markdown) {
+      badRequest(res, "markdown is required");
+      return;
+    }
+    if (!isMarkdownPath(relativePath)) {
+      badRequest(res, "invalid markdown path");
+      return;
+    }
+    try {
+      await overwriteMarkdown(relativePath, markdown);
+      res.json({ path: relativePath });
+    } catch (err) {
+      serverError(res, errorMessage(err));
+    }
+  },
+);
+
+// `null as never` in the calls below: each plugin's `execute*`
+// function expects a client-side context object as its first
+// argument. The server-side bridge has no such context — these
+// functions only touch their second arg (the request body) on this
+// path — so we satisfy the type signature with a never cast rather
+// than fabricating a fake context.
+
+// presentSpreadsheet — validate, then save sheets to disk
+router.post(
+  API_ROUTES.plugins.presentSpreadsheet,
+  wrapPluginExecute<SpreadsheetArgs, unknown>(async (req) => {
+    const result = await executeSpreadsheet(req.body);
+    if (!Array.isArray(result.data.sheets)) {
+      throw new Error("Expected sheets array from executeSpreadsheet");
+    }
+    const sheetsPath = await saveSpreadsheet(result.data.sheets);
+    return { ...result, data: { ...result.data, sheets: sheetsPath } };
+  }),
+);
+
+// Update spreadsheet file on disk (user edits in View)
+interface UpdateSpreadsheetBody {
+  sheets: unknown[];
+}
+
+interface UpdateSpreadsheetResponse {
+  path: string;
+}
+
+interface UpdateSpreadsheetError {
+  error: string;
+}
+
+router.put(
+  API_ROUTES.plugins.updateSpreadsheet,
+  async (req: Request<{ filename: string }, unknown, UpdateSpreadsheetBody>, res: Response<UpdateSpreadsheetResponse | UpdateSpreadsheetError>) => {
+    const relativePath = `${WORKSPACE_DIRS.spreadsheets}/${req.params.filename}`;
+    const { sheets } = req.body;
+    if (!Array.isArray(sheets)) {
+      badRequest(res, "sheets must be an array");
+      return;
+    }
+    if (!isSpreadsheetPath(relativePath)) {
+      badRequest(res, "invalid spreadsheet path");
+      return;
+    }
+    try {
+      await overwriteSpreadsheet(relativePath, sheets);
+      res.json({ path: relativePath });
+    } catch (err) {
+      serverError(res, errorMessage(err));
+    }
+  },
+);
+
+// createMindMap — uses package execute for node layout computation
+router.post(
+  API_ROUTES.plugins.mindmap,
+  wrapPluginExecute((req) => executeMindMap(null as never, req.body)),
+);
+
+// putQuestions — quiz
+router.post(
+  API_ROUTES.plugins.quiz,
+  wrapPluginExecute((req) => executeQuiz(null as never, req.body)),
+);
+
+// presentForm — form
+router.post(
+  API_ROUTES.plugins.form,
+  wrapPluginExecute((req) => executeForm(null as never, req.body)),
+);
+
+// openCanvas — drawing canvas
+router.post(
+  API_ROUTES.plugins.canvas,
+  wrapPluginExecute(() => executeOpenCanvas()),
+);
+
+// present3d — 3D visualization
+router.post(
+  API_ROUTES.plugins.present3d,
+  wrapPluginExecute((req) => executePresent3D(null as never, req.body)),
+);
+
+export default router;

package/server/api/routes/presentHtml.ts

@@ -0,0 +1,48 @@
+import { Router, Request, Response } from "express";
+import { WORKSPACE_DIRS } from "../../workspace/paths.js";
+import { writeWorkspaceText } from "../../utils/files/workspace-io.js";
+import { buildArtifactPath } from "../../utils/files/naming.js";
+import { errorMessage } from "../../utils/errors.js";
+import { badRequest, serverError } from "../../utils/httpError.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+
+const router = Router();
+
+interface PresentHtmlBody {
+  html: string;
+  title?: string;
+}
+
+interface PresentHtmlSuccessResponse {
+  message: string;
+  instructions: string;
+  data: { html: string; title?: string; filePath: string };
+}
+
+interface PresentHtmlErrorResponse {
+  error: string;
+}
+
+type PresentHtmlResponse = PresentHtmlSuccessResponse | PresentHtmlErrorResponse;
+
+router.post(API_ROUTES.html.present, async (req: Request<object, unknown, PresentHtmlBody>, res: Response<PresentHtmlResponse>) => {
+  const { html, title } = req.body;
+  if (!html) {
+    badRequest(res, "html is required");
+    return;
+  }
+
+  try {
+    const filePath = buildArtifactPath(WORKSPACE_DIRS.htmls, title, ".html", "page");
+    await writeWorkspaceText(filePath, html);
+    res.json({
+      message: `Saved HTML to ${filePath}`,
+      instructions: "Acknowledge that the HTML page has been presented to the user.",
+      data: { html, title, filePath },
+    });
+  } catch (err) {
+    serverError(res, errorMessage(err));
+  }
+});
+
+export default router;