@hienlh/ppm 0.22.11 → 0.23.1

package/src/server/routes/design-check.ts

@@ -0,0 +1,48 @@
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import { CHECK_REQUEST_ID_RE, parseCanvasCheckReport } from "../../shared/design-canvas-check.ts";
+import { isValidDesignSlug } from "../../services/design/design-slug.ts";
+import { canvasCheckBroker } from "../../services/design/check/design-canvas-check-broker.ts";
+import type { DesignRouteEnv } from "./design-route-helpers.ts";
+
+/**
+ * `POST /api/project/:projectName/designs/:slug/check/:requestId` — a browser's answer to a
+ * `design:check_request`. Authenticated like every design route, and settles only a check
+ * that is pending for this very project and design.
+ *
+ * The body was measured inside the design frame, where the page's own scripts run, so it is
+ * size-capped before parsing and validated field by field; nothing in it is ever a path.
+ */
+
+/** A 400 KB screenshot as base64 plus 30 capped findings, with room to spare. */
+export const MAX_CHECK_BODY_BYTES = 768 * 1024;
+
+export const designCheckRoutes = new Hono<DesignRouteEnv>();
+
+designCheckRoutes.post("/:requestId", async (c) => {
+  const slug = c.req.param("slug") ?? "";
+  const requestId = c.req.param("requestId");
+  if (!isValidDesignSlug(slug) || !CHECK_REQUEST_ID_RE.test(requestId)) return c.json(err("Invalid design or request"), 400);
+  const declared = Number(c.req.header("content-length") ?? "0");
+  if (declared > MAX_CHECK_BODY_BYTES) return c.json(err("Check report too large"), 413);
+  let raw: string;
+  try {
+    raw = await c.req.text();
+  } catch {
+    return c.json(err("Could not read the report"), 400);
+  }
+  if (Buffer.byteLength(raw) > MAX_CHECK_BODY_BYTES) return c.json(err("Check report too large"), 413);
+  let body: unknown;
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    return c.json(err("Expected a JSON report"), 400);
+  }
+  const report = parseCanvasCheckReport(body);
+  if (!report) return c.json(err("Malformed check report"), 400);
+  if (!canvasCheckBroker.resolveCheck(c.get("projectPath"), slug, requestId, report)) {
+    // Already answered by another client, timed out, or never asked of this design.
+    return c.json(err("No pending check with that id"), 404);
+  }
+  return c.json(ok({ accepted: true }));
+});

package/src/server/routes/design-comments.ts

@@ -0,0 +1,63 @@
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import {
+  addComment, deleteComment, listComments, previewElementContext, updateComment,
+} from "../../services/design/design-comments.service.ts";
+import { designFail as fail, designJsonBody as jsonBody, type DesignRouteEnv } from "./design-route-helpers.ts";
+
+/**
+ * `/api/project/:projectName/designs/:slug/comments` — pinned element comments.
+ *
+ * `POST /context` answers with the server-built snippet for one element without saving
+ * anything, for "Send to AI" on a single element: the prompt must never carry markup the
+ * page reported about itself.
+ */
+
+export const designCommentRoutes = new Hono<DesignRouteEnv>();
+
+designCommentRoutes.get("/", async (c) => {
+  try {
+    return c.json(ok(await listComments(c.get("projectPath"), c.req.param("slug") ?? "")));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designCommentRoutes.post("/", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await addComment(c.get("projectPath"), c.req.param("slug") ?? "", body)), 201);
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designCommentRoutes.post("/context", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await previewElementContext(c.get("projectPath"), c.req.param("slug") ?? "", body)));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designCommentRoutes.patch("/:id", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await updateComment(c.get("projectPath"), c.req.param("slug") ?? "", c.req.param("id"), body)));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designCommentRoutes.delete("/:id", async (c) => {
+  try {
+    await deleteComment(c.get("projectPath"), c.req.param("slug") ?? "", c.req.param("id"));
+    return c.json(ok({ deleted: c.req.param("id") }));
+  } catch (e) {
+    return fail(c, e);
+  }
+});

package/src/server/routes/design-export.ts

@@ -0,0 +1,84 @@
+import { Hono } from "hono";
+import { posix } from "node:path";
+import { err } from "../../types/api.ts";
+import { getDesign } from "../../services/design/design-store.service.ts";
+import { resolveDesignDir, resolveDesignsRoot } from "../../services/design/design-paths.ts";
+import { validateExportEntry } from "../../services/design/export/design-export-entry.ts";
+import { createDesignAssetReader } from "../../services/design/export/design-export-asset-reader.ts";
+import { buildStandaloneHtml } from "../../services/design/export/design-standalone-html.ts";
+import { createDesignZip } from "../../services/design/export/design-zip-export.ts";
+import { designFail as fail, type DesignRouteEnv } from "./design-route-helpers.ts";
+
+/**
+ * `/api/project/:projectName/designs/:slug/export` — downloads of one design.
+ *
+ * `GET /zip` streams `<slug>.zip`; `GET /html?entry=` answers one self-contained HTML file
+ * (the design's entry page when `entry` is absent), with `X-PPM-Export-Warnings` counting
+ * what could not be inlined and `X-PPM-Export-Warning-List` naming the first of them.
+ *
+ * Both answer `application/octet-stream` as an attachment. The HTML is AI-authored and must
+ * never render on PPM's origin, so it is never served as `text/html` here, and the browser
+ * saves it from a Blob of the same neutral type rather than navigating to it.
+ */
+
+export const designExportRoutes = new Hono<DesignRouteEnv>();
+
+/** Proxies (nginx's default buffer is 4-8 KB for all headers) refuse bigger responses. */
+const MAX_WARNING_HEADER = 3000;
+
+/** As many warnings as fit the header budget, URI-encoded JSON. */
+function warningHeader(warnings: string[]): string {
+  const listed: string[] = [];
+  let value = encodeURIComponent("[]");
+  for (const w of warnings) {
+    const next = encodeURIComponent(JSON.stringify([...listed, w.slice(0, 200)]));
+    if (next.length > MAX_WARNING_HEADER) break;
+    listed.push(w.slice(0, 200));
+    value = next;
+  }
+  return value;
+}
+
+function downloadHeaders(filename: string): Record<string, string> {
+  return {
+    "Content-Type": "application/octet-stream",
+    "Content-Disposition": `attachment; filename="${filename}"`,
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "no-store",
+  };
+}
+
+designExportRoutes.get("/zip", async (c) => {
+  const slug = c.req.param("slug") ?? "";
+  try {
+    const stream = await createDesignZip(c.get("projectPath"), slug);
+    return new Response(stream, { headers: downloadHeaders(`${slug}.zip`) });
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designExportRoutes.get("/html", async (c) => {
+  const slug = c.req.param("slug") ?? "";
+  try {
+    const projectPath = c.get("projectPath");
+    const design = await getDesign(projectPath, slug);
+    const designDir = await resolveDesignDir(projectPath, slug);
+    const root = await resolveDesignsRoot(projectPath);
+    // The slug resolved, so designs/ exists; the null check only satisfies the type.
+    if (!root) return c.json(err("Design not found"), 404);
+    const entry = validateExportEntry(c.req.query("entry") ?? design.entry, designDir);
+    const { html, warnings } = await buildStandaloneHtml(entry.rel, createDesignAssetReader(designDir, root));
+    const page = posix.basename(entry.rel).replace(/\.html?$/, "");
+    const filename = page === "index" ? `${slug}.html` : `${slug}-${page}.html`;
+    return new Response(html, {
+      headers: {
+        ...downloadHeaders(filename),
+        "X-PPM-Export-Warnings": String(warnings.length),
+        "X-PPM-Export-Warning-List": warningHeader(warnings),
+      },
+    });
+  } catch (e) {
+    return fail(c, e);
+  }
+});

package/src/server/routes/design-preview.ts

@@ -0,0 +1,159 @@
+import { Hono } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { stat } from "node:fs/promises";
+import { ok, err } from "../../types/api.ts";
+import { mapFsError } from "../../services/fs-path-guard.service.ts";
+import { browserFacingHost } from "../helpers/preview-asset-guard.ts";
+import { rangeFileResponse } from "../helpers/range-file-response.ts";
+import { resolveProjectPath } from "../helpers/resolve-project.ts";
+import { BRIDGE_NONCE_RE } from "../../shared/design-bridge-protocol.ts";
+import { isValidDesignSlug } from "../../services/design/design-slug.ts";
+import { getDesign } from "../../services/design/design-store.service.ts";
+import { readDesignFileSafe } from "../../services/design/design-safe-walk.ts";
+import { decodeDesignText, MAX_DESIGN_SOURCE_BYTES } from "../../services/design/source/design-source-file.ts";
+import { buildDesignCsp } from "../../services/design/preview/design-csp.ts";
+import { resolveScopedAsset } from "../../services/design/preview/design-preview-scope.ts";
+import { renderDesignHtml } from "../../services/design/preview/design-preview-html.ts";
+import { printInjection } from "../../services/design/preview/print-view.ts";
+import { EXPIRED_PAGE_CSP, expiredPageHtml } from "../../services/design/preview/expired-page.ts";
+import {
+  createDesignPreviewTokenStore, isDesignPreviewPurpose, type DesignPreviewCapability,
+} from "../../services/design/preview/design-preview-tokens.ts";
+
+/**
+ * The design canvas's capability route pair.
+ *
+ * `api` (behind auth) mints and refreshes a token for one design; `content` (before auth,
+ * the iframe has no PPM credentials) serves that design's files under the design CSP. A
+ * token is the only credential in the iframe URL, and it reads one design only.
+ */
+
+const PREFIX = "/api/design-preview/content";
+
+const BASE_HEADERS = {
+  "Referrer-Policy": "no-referrer",
+  "Cache-Control": "no-store",
+  "X-Content-Type-Options": "nosniff",
+  // The sandboxed document has an opaque origin and sends `Origin: null` for module scripts
+  // and fonts. `null` answers exactly that, where `*` would answer every site on the web.
+  "Access-Control-Allow-Origin": "null",
+};
+
+function errorStatus(error: unknown): ContentfulStatusCode {
+  const status = (error as { status?: number }).status;
+  if (status === 403 || status === 413) return status;
+  return 404;
+}
+
+export function createDesignPreviewRoutes(now: () => number = Date.now) {
+  const store = createDesignPreviewTokenStore(now);
+  const api = new Hono();
+  const content = new Hono();
+
+  // The app's global `cors()` answers `*`, and Hono copies headers set before a handler over
+  // the handler's own response, so the value set below would be lost. Re-assert it after.
+  content.use("*", async (c, next) => {
+    await next();
+    c.res.headers.set("Access-Control-Allow-Origin", "null");
+  });
+
+  const urlFor = (cap: DesignPreviewCapability, entry: string): string =>
+    `${PREFIX}/${cap.token}/${cap.slug}/${entry.split("/").map(encodeURIComponent).join("/")}`;
+
+  api.post("/", async (c) => {
+    const body: unknown = await c.req.json().catch(() => null);
+    const b = body && typeof body === "object" && !Array.isArray(body) ? (body as Record<string, unknown>) : null;
+    if (!b || typeof b.projectName !== "string" || !b.projectName || !isValidDesignSlug(b.slug)
+      || !isDesignPreviewPurpose(b.purpose) || (b.token !== undefined && typeof b.token !== "string")) {
+      return c.json(err("projectName, a design slug and purpose (canvas, print or standalone) are required"), 400);
+    }
+    const slug = b.slug;
+    const purpose = b.purpose;
+    let projectPath: string;
+    try {
+      projectPath = resolveProjectPath(b.projectName);
+    } catch {
+      return c.json(err("Project not found"), 404);
+    }
+    try {
+      const design = await getDesign(projectPath, slug);
+      let cap: DesignPreviewCapability;
+      let rotated = false;
+      if (typeof b.token === "string") {
+        if (purpose !== "canvas") return c.json(err("Only a canvas preview can be refreshed"), 400);
+        const result = store.refresh(b.token, { projectPath, slug });
+        if (!result.ok) {
+          return result.reason === "unknown"
+            ? c.json(err("Preview expired; mint a new one"), 404)
+            : c.json(err("This token belongs to another preview"), 403);
+        }
+        cap = result.capability;
+        rotated = result.rotated;
+      } else {
+        cap = store.mint({ projectPath, slug }, purpose);
+      }
+      return c.json(ok({ url: urlFor(cap, design.entry), token: cap.token, expiresAt: cap.idleExpires, rotated }));
+    } catch (e) {
+      const info = mapFsError(e);
+      if (info.status >= 500) console.error(`[design-preview] mint ${slug}: ${info.message}`);
+      return c.json(err(info.status === 403 ? "Access denied" : info.message), info.status as ContentfulStatusCode);
+    }
+  });
+
+  content.get("/:token/*", async (c) => {
+    const token = c.req.param("token");
+    const url = new URL(c.req.url);
+    const encoded = url.pathname.slice(`${PREFIX}/${token}/`.length);
+    const n = url.searchParams.get("n");
+    const nonce = n && BRIDGE_NONCE_RE.test(n) ? n : null;
+    const cap = store.resolve(token);
+    if (!cap) {
+      if (/\.html?$/i.test(encoded)) {
+        return new Response(expiredPageHtml(nonce), {
+          status: 404,
+          headers: { ...BASE_HEADERS, "Content-Security-Policy": EXPIRED_PAGE_CSP, "Content-Type": "text/html; charset=utf-8" },
+        });
+      }
+      return c.json(err("Preview expired; reopen the design"), 404);
+    }
+    try {
+      const asset = await resolveScopedAsset(cap, encoded);
+      if (!(await stat(asset.abs)).isFile()) return c.json(err("File not found"), 404);
+      // A scheme-less host source follows the document's actual scheme through tunnels.
+      const source = `${browserFacingHost(c.req.header("host"), c.req.url)}${PREFIX}/${token}/`;
+      const headers: Record<string, string> = {
+        ...BASE_HEADERS,
+        "Content-Security-Policy": buildDesignCsp(source, { allowModals: cap.purpose === "print" }),
+      };
+      const head = c.req.method === "HEAD";
+      if (/\.html?$/i.test(asset.abs)) {
+        // The token's purpose alone decides what the page gets: the bridge for the canvas, the
+        // print style and script for print, nothing for standalone. No query flag changes it.
+        const inject = cap.purpose === "print" ? printInjection((await getDesign(cap.projectPath, cap.slug)).kind) : undefined;
+        const page = await renderDesignHtml(cap, asset, { nonce, withBridge: cap.purpose === "canvas", inject });
+        return new Response(head ? null : page.body, {
+          headers: {
+            ...headers, "Content-Type": "text/html; charset=utf-8",
+            "X-PPM-Gen": page.gen, "X-PPM-Instrumented": page.instrumented ? "1" : "0",
+          },
+        });
+      }
+      if (/\.css$/i.test(asset.abs)) {
+        const bytes = await readDesignFileSafe(asset.abs, MAX_DESIGN_SOURCE_BYTES);
+        // A copy typed over a plain ArrayBuffer, which is what BodyInit accepts.
+        return new Response(head ? null : new Uint8Array(bytes), {
+          headers: { ...headers, "Content-Type": "text/css; charset=utf-8", "X-PPM-Gen": decodeDesignText(bytes, { lossy: true }).gen },
+        });
+      }
+      return rangeFileResponse(asset.abs, c.req.raw, headers);
+    } catch (error) {
+      const status = errorStatus(error);
+      const message = status === 403 ? "Access denied" : status === 413 ? "File too large to preview" : "Preview asset not found";
+      return c.json(err(message), status);
+    }
+  });
+
+  return { api, content, store };
+}
+
+export const designPreviewRoutes = createDesignPreviewRoutes();

package/src/server/routes/design-route-helpers.ts

@@ -0,0 +1,25 @@
+import type { Context } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { err } from "../../types/api.ts";
+import { mapFsError } from "../../services/fs-path-guard.service.ts";
+
+/** Shared by `/designs` and the sub-routers mounted under it. */
+
+export type DesignRouteEnv = { Variables: { projectPath: string; projectName: string } };
+
+/** Answers with the status a service error carries; logs only what is the server's fault. */
+export function designFail(c: Context<DesignRouteEnv>, e: unknown): Response {
+  const info = mapFsError(e);
+  if (info.status >= 500) console.error(`[design] ${c.req.method} ${c.req.path}: ${info.message}`);
+  return c.json(err(info.message), info.status as ContentfulStatusCode);
+}
+
+/** The request's JSON body when it is an object, else null. */
+export async function designJsonBody(c: Context<DesignRouteEnv>): Promise<Record<string, unknown> | null> {
+  try {
+    const body: unknown = await c.req.json();
+    return body && typeof body === "object" && !Array.isArray(body) ? (body as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}

package/src/server/routes/design-style.ts

@@ -0,0 +1,28 @@
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import { StyleConflictError, commitStylePatch } from "../../services/design/design-style-patch.service.ts";
+import { designFail as fail, designJsonBody as jsonBody, type DesignRouteEnv } from "./design-route-helpers.ts";
+
+/**
+ * `/api/project/:projectName/designs/:slug/style` — a move or resize from the canvas.
+ *
+ * `POST {file, gen, ppmId, tag, props}` answers `{gen, undoId}`. A 409 says why in
+ * `data.reason` — `stale` (the file changed since the canvas loaded it) or `element-moved`
+ * (no element with that tag at that position) — with the file's current gen; a 429 means the
+ * design's canvas write limit was hit.
+ */
+
+export const designStyleRoutes = new Hono<DesignRouteEnv>();
+
+designStyleRoutes.post("/", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await commitStylePatch(c.get("projectPath"), c.req.param("slug") ?? "", body)));
+  } catch (e) {
+    if (e instanceof StyleConflictError) {
+      return c.json({ ...err(e.message), data: { reason: e.code, currentGen: e.currentGen } }, 409);
+    }
+    return fail(c, e);
+  }
+});

package/src/server/routes/design-tweaks.ts

@@ -0,0 +1,38 @@
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import {
+  StaleTweakGenError, commitTweaks, readDesignTweaks,
+} from "../../services/design/design-tweaks-commit.service.ts";
+import { designFail as fail, designJsonBody as jsonBody, type DesignRouteEnv } from "./design-route-helpers.ts";
+
+/**
+ * `/api/project/:projectName/designs/:slug/tweaks` — the design's tweak controls.
+ *
+ * `GET` answers with the controls `design.json` declares (and why any were skipped);
+ * `POST {entry, gens, values}` writes values into the stylesheets. A stale gen is a 409
+ * whose `data` names the file and its current gen, so the canvas can reload and let the
+ * user apply again without losing the values they chose.
+ */
+
+export const designTweakRoutes = new Hono<DesignRouteEnv>();
+
+designTweakRoutes.get("/", async (c) => {
+  try {
+    return c.json(ok(await readDesignTweaks(c.get("projectPath"), c.req.param("slug") ?? "")));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designTweakRoutes.post("/", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await commitTweaks(c.get("projectPath"), c.req.param("slug") ?? "", body)));
+  } catch (e) {
+    if (e instanceof StaleTweakGenError) {
+      return c.json({ ...err(e.message), data: { file: e.file, currentGen: e.currentGen } }, 409);
+    }
+    return fail(c, e);
+  }
+});

package/src/server/routes/design-undo.ts

@@ -0,0 +1,27 @@
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import { isDesignError } from "../../services/design/design-error.ts";
+import { undoEdit } from "../../services/design/design-edit-undo-journal.ts";
+import { designFail as fail, designJsonBody as jsonBody, type DesignRouteEnv } from "./design-route-helpers.ts";
+
+/**
+ * `/api/project/:projectName/designs/:slug/undo` — reverse one canvas write.
+ *
+ * `POST {undoId}` answers `{gen, gens}`; 404 for an id the server does not know (unknown,
+ * evicted, or lost with a restart), and 409 with `data.reason: "cannot-undo"` when the text
+ * the write left has changed since. The body carries the id only: what gets written back
+ * comes from the server's own journal.
+ */
+
+export const designUndoRoutes = new Hono<DesignRouteEnv>();
+
+designUndoRoutes.post("/", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await undoEdit(c.get("projectPath"), c.req.param("slug") ?? "", body.undoId)));
+  } catch (e) {
+    if (isDesignError(e) && e.status === 409) return c.json({ ...err(e.message), data: { reason: e.code } }, 409);
+    return fail(c, e);
+  }
+});

package/src/server/routes/designs.ts

@@ -0,0 +1,101 @@
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import { isSnapshotId } from "../../shared/design-types.ts";
+import { designFail as fail, designJsonBody as jsonBody, type DesignRouteEnv } from "./design-route-helpers.ts";
+import { designCommentRoutes } from "./design-comments.ts";
+import { designTweakRoutes } from "./design-tweaks.ts";
+import { designStyleRoutes } from "./design-style.ts";
+import { designUndoRoutes } from "./design-undo.ts";
+import { designExportRoutes } from "./design-export.ts";
+import { designCheckRoutes } from "./design-check.ts";
+import {
+  createDesign, deleteDesign, designSystemStatus, getDesign, listDesigns, renameDesign,
+} from "../../services/design/design-store.service.ts";
+import { listSnapshots } from "../../services/design/design-snapshots.service.ts";
+import { restoreSnapshot } from "../../services/design/design-restore.service.ts";
+
+/**
+ * `/api/project/:projectName/designs` — the design folders of one project.
+ *
+ * Every path is derived from the server-side project path plus a validated slug; nothing
+ * the client sends is used as a path. Later features mount their own sub-routes on this
+ * router (comments, tweaks, write-backs, exports) by appending below.
+ */
+
+export const designRoutes = new Hono<DesignRouteEnv>();
+
+designRoutes.get("/", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const [designs, system] = await Promise.all([listDesigns(projectPath), designSystemStatus(projectPath)]);
+    return c.json(ok({ designs, system }));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designRoutes.post("/", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await createDesign(c.get("projectPath"), { title: body.title, kind: body.kind })), 201);
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designRoutes.get("/:slug", async (c) => {
+  try {
+    return c.json(ok(await getDesign(c.get("projectPath"), c.req.param("slug"))));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designRoutes.patch("/:slug", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await renameDesign(c.get("projectPath"), c.req.param("slug"), body.title)));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+/** Deleting needs `?confirm=<slug>`, so a stray or replayed request cannot drop a design. */
+designRoutes.delete("/:slug", async (c) => {
+  const slug = c.req.param("slug");
+  if (c.req.query("confirm") !== slug) return c.json(err("Confirm the deletion with ?confirm=<slug>"), 400);
+  try {
+    await deleteDesign(c.get("projectPath"), slug);
+    return c.json(ok({ deleted: slug }));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designRoutes.get("/:slug/history", async (c) => {
+  try {
+    return c.json(ok(await listSnapshots(c.get("projectPath"), c.req.param("slug"))));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designRoutes.post("/:slug/history/:id/restore", async (c) => {
+  // Hono hands the param over already decoded, so an encoded `..` is checked as `..`.
+  const id = c.req.param("id");
+  if (!isSnapshotId(id)) return c.json(err("Invalid snapshot id"), 400);
+  try {
+    return c.json(ok(await restoreSnapshot(c.get("projectPath"), c.req.param("slug"), id)));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designRoutes.route("/:slug/comments", designCommentRoutes);
+designRoutes.route("/:slug/tweaks", designTweakRoutes);
+designRoutes.route("/:slug/style", designStyleRoutes);
+designRoutes.route("/:slug/undo", designUndoRoutes);
+designRoutes.route("/:slug/export", designExportRoutes);
+designRoutes.route("/:slug/check", designCheckRoutes);

package/src/server/routes/html-preview.ts

@@ -1,33 +1,17 @@
 import { Hono } from "hono";
 import { realpath, stat } from "node:fs/promises";
-import { basename, dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
-import { assertAllowed, assertNotPpmDir, resolvePath } from "../../services/fs-path-guard.service.ts";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { resolvePath } from "../../services/fs-path-guard.service.ts";
 import { ok, err } from "../../types/api.ts";
+import { browserFacingHost, guardPreviewAsset as guardAsset, isInsideRoot as inside, previewDenied as denied } from "../helpers/preview-asset-guard.ts";
 import { rangeFileResponse } from "../helpers/range-file-response.ts";
 import { resolveProjectPath } from "../helpers/resolve-project.ts";
 
 const PREFIX = "/api/html-preview/content";
 const TTL = 60 * 60 * 1000;
 const MAX_SESSIONS = 128;
-const ASSETS = new Set([".html", ".htm", ".css", ".js", ".mjs", ".json", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".ico", ".mp4", ".webm", ".mov", ".mp3", ".wav", ".ogg", ".m4a", ".woff", ".woff2", ".ttf", ".otf", ".vtt"]);
 interface PreviewSession { root: string; expires: number }
 
-function denied(): never {
-  throw Object.assign(new Error("Preview path is not allowed"), { status: 403 });
-}
-
-function inside(root: string, path: string): boolean {
-  const rel = relative(root, path);
-  return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
-}
-
-function guardAsset(path: string, root = dirname(path)): void {
-  assertAllowed(path);
-  assertNotPpmDir(path);
-  // Only web assets, never hidden directories, dotenv, database or key files.
-  if (relative(root, path).split(/[\\/]/).some((part) => part.startsWith(".")) || !ASSETS.has(extname(path).toLowerCase())) denied();
-}
-
 /** Independent capability store per router pair; no session credentials enter iframe URLs. */
 export function createHtmlPreviewRoutes(now = Date.now) {
   const sessions = new Map<string, PreviewSession>();
@@ -86,11 +70,7 @@ export function createHtmlPreviewRoutes(now = Date.now) {
       if (!inside(session.root, path)) denied();
       guardAsset(path, session.root);
       if (!(await stat(path)).isFile()) return c.json(err("File not found"), 404);
-      // Bun reconstructs req.url with its listening port. Preserve the browser's
-      // Host through Vite/tunnels; validate before inserting into a CSP directive.
-      const requestHost = c.req.header("host") ?? "";
-      const host = /^(?:[a-z0-9.-]+|\[[a-f0-9:]+\])(?::\d{1,5})?$/i.test(requestHost)
-        ? requestHost : new URL(c.req.url).host;
+      const host = browserFacingHost(c.req.header("host"), c.req.url);
       // A scheme-less host source follows the document's actual scheme through tunnels.
       const source = `${host}${PREFIX}/${token}/`;
       const policy = ["sandbox allow-scripts", "default-src 'none'", `script-src 'unsafe-inline' ${source}`,

package/src/server/routes/project-scoped.ts

@@ -8,6 +8,7 @@ import { fileRoutes } from "./files.ts";
 import { sqliteRoutes } from "./sqlite.ts";
 import { workspaceRoutes } from "./workspace.ts";
 import { downloadRoutes } from "./file-download.ts";
+import { designRoutes } from "./designs.ts";
 
 type Env = { Variables: { projectPath: string; projectName: string } };
 
@@ -35,3 +36,4 @@ projectScopedRouter.route("/files", fileRoutes);
 projectScopedRouter.route("/sqlite", sqliteRoutes);
 projectScopedRouter.route("/workspace", workspaceRoutes);
 projectScopedRouter.route("/files/download", downloadRoutes);
+projectScopedRouter.route("/designs", designRoutes);