@hienlh/ppm 0.23.13 → 0.23.15

package/src/web/components/settings/design-settings-section.tsx

@@ -15,6 +15,7 @@ import {
 import { DesignInstructionsEditor } from "./design-instructions-editor";
 import { DesignSkillMentionStatus } from "./design-skill-mention-status";
 import { DesignAppsSettingsSection } from "./design-apps-settings-section";
+import { DesignWindowSetting } from "./design-window-setting";
 
 /** One picker list across providers; the first provider's copy of a shared name wins. */
 function mergeSkills(settings: DesignSettings): SlashItem[] {
@@ -142,6 +143,8 @@ export function DesignSettingsSection() {
 
   return (
     <div className="space-y-4">
+      <DesignWindowSetting />
+      <div className="h-px bg-border" />
       {projectName && (
         <>
           <DesignAppsSettingsSection projectName={projectName} />

package/src/web/components/settings/design-window-setting.tsx

@@ -0,0 +1,28 @@
+import { Switch } from "@/components/ui/switch";
+import { useSettingsStore } from "@/stores/settings-store";
+
+/**
+ * Settings → Design: whether a design opens in a floating window or as a tab. Applies to
+ * designs opened from now on; one already open stays where it is.
+ */
+export function DesignWindowSetting() {
+  const enabled = useSettingsStore((s) => s.designWindows);
+  return (
+    // The whole row is the label, so the 44px target is the row rather than the 36x20 track.
+    <label className="flex min-h-11 cursor-pointer items-center justify-between gap-4">
+      <span className="space-y-1">
+        <span className="block text-sm font-medium">Open designs in a window</span>
+        <span className="block text-xs leading-relaxed text-text-subtle">
+          A design floats over your panels, where you can move it, snap it to the right half or
+          minimize it to the status bar. Off: designs open as tabs. On a phone a design is
+          always full screen.
+        </span>
+      </span>
+      <Switch
+        checked={enabled}
+        onCheckedChange={(checked) => useSettingsStore.getState().setDesignWindows(checked)}
+        aria-label="Open designs in a window"
+      />
+    </label>
+  );
+}

package/src/web/components/settings/settings-categories.ts

@@ -26,6 +26,7 @@ import {
   Zap,
   Monitor,
   MonitorSmartphone,
+  Wrench,
 } from "@/lib/icons";
 
 /**
@@ -41,6 +42,7 @@ export type SettingsCategoryId =
   | "remote-desktop"
   | "database-drivers"
   | "ai-provider"
+  | "tools"
   | "accounts"
   | "design"
   | "voice"
@@ -91,6 +93,7 @@ export const SETTINGS_CATEGORIES: SettingsCategoryDef[] = [
   { id: "database-drivers", group: "core", label: "Database Drivers", subtitle: "MySQL and MariaDB support, installed on request", icon: Database },
 
   { id: "ai-provider", group: "ai", label: "AI Provider", subtitle: "Model, execution mode, limits", icon: Bot },
+  { id: "tools", group: "ai", label: "Tools", subtitle: "PPM tools the AI can use", icon: Wrench },
   { id: "accounts", group: "ai", label: "Accounts", subtitle: "Claude and Codex sign-ins, rotation", icon: KeyRound },
   { id: "design", group: "ai", label: "Design", subtitle: "Design instructions and skills", icon: LayoutGrid },
   { id: "voice", group: "ai", label: "Voice Input", subtitle: "Speech to text for the chat box", icon: Mic },

package/src/web/components/settings/settings-section-content.tsx

@@ -19,6 +19,7 @@ export const SECTIONS: Record<SettingsCategoryId, PreloadableComponent<object>>
   "remote-desktop": lazyWithPreload(() => import("./remote-desktop-settings-section").then((m) => ({ default: m.RemoteDesktopSettingsSection }))),
   "database-drivers": lazyWithPreload(() => import("./database-drivers-section").then((m) => ({ default: m.DatabaseDriversSection }))),
   "ai-provider": lazyWithPreload(() => import("./ai-settings-section").then((m) => ({ default: m.AISettingsSection }))),
+  tools: lazyWithPreload(() => import("./tools-settings-section").then((m) => ({ default: m.ToolsSettingsSection }))),
   accounts: lazyWithPreload(() => import("./accounts/accounts-settings-section").then((m) => ({ default: m.AccountsSettingsSection }))),
   design: lazyWithPreload(() => import("./design-settings-section").then((m) => ({ default: m.DesignSettingsSection }))),
   voice: lazyWithPreload(() => import("./voice-settings-section").then((m) => ({ default: m.VoiceSettingsSection }))),

package/src/web/components/settings/tools-settings-section.tsx

@@ -0,0 +1,120 @@
+/**
+ * Settings → Tools: PPM's own tools for the AI chat, on or off one by one, for Claude and Codex
+ * alike (`ai.ppm_tools`; the defaults are in `src/shared/ppm-tools.ts`).
+ */
+import { useCallback, useEffect, useState } from "react";
+import { toast } from "sonner";
+import { getAISettings, updateAISettings, type AISettings } from "@/lib/api-settings";
+import { DB_TOOLS } from "../../../shared/db-ai-tools";
+import { ppmToolOn, TERMINAL_TOOLS, type PpmTool } from "../../../shared/ppm-tools";
+import { SectionHeader, SwitchRow } from "./settings-rows";
+
+const errorText = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+const TOOL_COPY: Record<PpmTool, { label: string; note: string }> = {
+  open_file: {
+    label: "Open files",
+    note: "Opens a file in a PPM tab, at a line when it points you at one.",
+  },
+  open_preview: {
+    label: "Show pages",
+    note: "Opens a page, chart or report it made in a PPM tab, and reads back its errors and a screenshot. While on, Claude's claude.ai Artifact tool is off.",
+  },
+  open_url: {
+    label: "Show running apps",
+    note: "Opens a web server running on this machine, such as a dev server, in a PPM tab. On another device it goes through a private Tailscale forward; it never makes a public link.",
+  },
+  read_terminal: {
+    label: "Read terminals",
+    note: "Reads what the terminals of the chat's project printed, so you need not paste an error into the chat.",
+  },
+  run_in_terminal: {
+    label: "Type commands",
+    note: "Opens a terminal with a command typed in, for one that needs your password or your eyes. Nothing runs until you press Enter.",
+  },
+  db_query: {
+    label: "Read databases",
+    note: "Runs read-only SQL. It cannot change anything.",
+  },
+  open_query: {
+    label: "Open Query tabs",
+    note: "Opens a Query tab holding a script it wrote. You press Run.",
+  },
+  db_execute: {
+    label: "Change databases",
+    note: "Runs a change only after you approve it with PPM's password, once, in one transaction.",
+  },
+};
+
+const GROUPS: Array<{ title: string; intro: string; tools: readonly PpmTool[] }> = [
+  { title: "Tabs", intro: "On the device you are chatting from.", tools: ["open_file", "open_preview", "open_url"] },
+  { title: "Terminal", intro: "PPM's own terminals, on the machine PPM runs on.", tools: TERMINAL_TOOLS },
+  {
+    title: "Database",
+    intro: "On the connections with “Available to the AI chat” on. The AI never sees their passwords.",
+    tools: DB_TOOLS,
+  },
+];
+
+export function ToolsSettingsSection() {
+  const [settings, setSettings] = useState<AISettings | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    try {
+      setSettings(await getAISettings());
+      setLoadError(null);
+    } catch (e) {
+      setLoadError(errorText(e));
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  // Shown at once; a refused save reloads what the server actually has.
+  const toggle = useCallback(async (tool: PpmTool, on: boolean) => {
+    setSettings((current) => (current ? { ...current, ppm_tools: { ...current.ppm_tools, [tool]: on } } : current));
+    try {
+      setSettings(await updateAISettings({ ppm_tools: { [tool]: on } }));
+    } catch (e) {
+      toast.error("Could not save", { description: errorText(e) });
+      await load();
+    }
+  }, [load]);
+
+  if (!settings) {
+    return <p className="text-xs text-muted-foreground">{loadError ?? "Loading…"}</p>;
+  }
+
+  return (
+    <div className="space-y-6">
+      <p className="text-xs leading-relaxed text-muted-foreground">
+        PPM's own tools for the AI chat, with Claude and Codex alike. New chats get the tools that are
+        on; turning one off also stops it in chats already open.
+      </p>
+      {GROUPS.map((group) => (
+        <section key={group.title} className="space-y-3">
+          <SectionHeader title={group.title}>{group.intro}</SectionHeader>
+          <div className="divide-y divide-border rounded-lg border border-border">
+            {group.tools.map((tool) => (
+              <SwitchRow
+                key={tool}
+                label={
+                  <>
+                    {TOOL_COPY[tool].label}
+                    <code className="ml-2 font-mono text-[11px] text-muted-foreground">{tool}</code>
+                  </>
+                }
+                note={TOOL_COPY[tool].note}
+                checked={ppmToolOn(settings, tool)}
+                onChange={(on) => void toggle(tool, on)}
+              />
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}

package/src/web/components/shared/docx-html-sanitize.ts

@@ -0,0 +1,59 @@
+import { unified } from "unified";
+import rehypeParse from "rehype-parse";
+import rehypeSanitize, { defaultSchema, type Options as SanitizeSchema } from "rehype-sanitize";
+import rehypeStringify from "rehype-stringify";
+
+/**
+ * What a converted `.docx`'s HTML may keep. mammoth does no sanitising, so a `javascript:`
+ * hyperlink in a document (verified: one click read the auth token from the page) reaches the
+ * preview's `innerHTML` as a live link, and a `<script>` smuggled through a document would run.
+ * The preview has no `markdownUrlTransform`, so unlike the Markdown path the scheme check is
+ * done here: links keep http(s)/mailto, images keep http(s) and the `data:` URIs mammoth
+ * inlines its embedded pictures as. Starts from GitHub's allow-list, so headings, bold/italic,
+ * lists, tables and images survive.
+ *
+ * This is its own file rather than part of `markdown-sanitize.ts` so the Markdown renderer's
+ * chunk does not carry rehype-parse/rehype-stringify, which only the lazy docx preview needs.
+ */
+export const docxSanitizeSchema: SanitizeSchema = {
+  ...defaultSchema,
+  attributes: {
+    ...defaultSchema.attributes,
+    img: [...(defaultSchema.attributes?.img ?? []), "src", "width", "height"],
+  },
+  protocols: {
+    ...defaultSchema.protocols,
+    src: ["http", "https", "data"],
+    href: ["http", "https", "mailto"],
+  },
+};
+
+interface HastNode {
+  tagName?: string;
+  properties?: Record<string, unknown>;
+  children?: HastNode[];
+}
+
+/**
+ * The allow-list keeps any `data:` image src, but hast-util-sanitize checks only the `data:`
+ * prefix — so `data:text/html,…` survives. An `<img>` cannot run it, yet it has no business in
+ * a document, so this drops every `data:` src that is not `data:image/`.
+ */
+function dropNonImageDataSrc(node: HastNode): void {
+  const src = node.tagName === "img" ? node.properties?.src : undefined;
+  if (typeof src === "string" && /^data:/i.test(src) && !/^data:image\//i.test(src)) {
+    delete node.properties!.src;
+  }
+  node.children?.forEach(dropNonImageDataSrc);
+}
+
+const docxPipeline = unified()
+  .use(rehypeParse, { fragment: true })
+  .use(rehypeSanitize, docxSanitizeSchema)
+  .use(() => (tree: unknown) => dropNonImageDataSrc(tree as HastNode))
+  .use(rehypeStringify);
+
+/** Hold HTML from an untrusted document to the docx allow-list before it reaches `innerHTML`. */
+export function sanitizeDocxHtml(html: string): string {
+  return String(docxPipeline.processSync(html));
+}

package/src/web/components/shared/markdown-code-block.tsx

@@ -46,7 +46,9 @@ let mermaidPromise: Promise<typeof import("mermaid")["default"]> | null = null;
 function getMermaid() {
   if (!mermaidPromise) {
     mermaidPromise = import("mermaid").then((mod) => {
-      mod.default.initialize({ startOnLoad: false, theme: "default", securityLevel: "loose", fontFamily: "ui-sans-serif, system-ui, sans-serif" });
+      // "strict": a diagram is text the AI wrote, and "loose" keeps `click … href "javascript:…"`
+      // links live in the SVG, one click from running on PPM's origin. PPM wires no click handlers.
+      mod.default.initialize({ startOnLoad: false, theme: "default", securityLevel: "strict", fontFamily: "ui-sans-serif, system-ui, sans-serif" });
       return mod.default;
     });
   }

package/src/web/components/shared/markdown-renderer.tsx

@@ -4,6 +4,7 @@ import remarkGfm from "remark-gfm";
 import remarkMath from "remark-math";
 import remarkBreaks from "remark-breaks";
 import rehypeRaw from "rehype-raw";
+import rehypeSanitize from "rehype-sanitize";
 import rehypeKatex from "rehype-katex";
 import { useImageOverlay } from "@/stores/image-overlay-store";
 import { collectGallery, GALLERY_ITEM_ATTR } from "@/lib/image-gallery";
@@ -14,6 +15,7 @@ import { normalizeMathDelimiters } from "@/lib/markdown-math-delimiters";
 import { MdContext, useMdContext, LOCAL_PATH_RE, markdownUrlTransform, parseMarkdownFileTarget } from "./markdown-context";
 import { useMarkdownFileNavigation } from "./use-markdown-file-navigation";
 import { MdPre, MdCode } from "./markdown-code-block";
+import { markdownSanitizeSchema, rehypePrefixFragmentLinks, sanitizedRemarkRehypeOptions } from "./markdown-sanitize";
 
 interface MarkdownRendererProps {
   content: string;
@@ -21,15 +23,24 @@ interface MarkdownRendererProps {
   className?: string;
   codeActions?: boolean;
   isStreaming?: boolean;
+  /**
+   * Parse HTML inside the Markdown (default), keeping only what `markdownSanitizeSchema`
+   * allows. Off for text nobody in this session wrote, such as a system tag's content, where
+   * HTML in the source is shown as text instead.
+   */
+  rawHtml?: boolean;
 }
 
 /** Plugin arrays — stable references to avoid re-creating on each render */
 const remarkPlugins = [[remarkGfm, { singleTilde: false }], [remarkMath, { singleDollarTextMath: false }], remarkBreaks] as any;
-const rehypePlugins = [rehypeRaw, rehypeKatex] as any;
+// Sanitise straight after parsing raw HTML and before KaTeX, so KaTeX's own markup is not
+// held to the allow-list.
+const rehypePlugins = [rehypeRaw, [rehypeSanitize, markdownSanitizeSchema], rehypePrefixFragmentLinks, rehypeKatex] as any;
+const rehypePluginsNoRaw = [rehypeKatex] as any;
 /** Component map — stable references; dynamic state flows through MdContext */
 const mdComponents = { a: MdLink, img: MdImage, pre: MdPre, code: MdCode, table: MdTable };
 
-export function MarkdownRenderer({ content, projectName, className = "", codeActions = false, isStreaming = false }: MarkdownRendererProps) {
+export function MarkdownRenderer({ content, projectName, className = "", codeActions = false, isStreaming = false, rawHtml = true }: MarkdownRendererProps) {
   const openImageOverlayFn = useImageOverlay((s) => s.open);
   const openDiagramOverlayFn = useDiagramOverlay((s) => s.open);
   const openFileOrSearch = useMarkdownFileNavigation(projectName);
@@ -48,7 +59,8 @@ export function MarkdownRenderer({ content, projectName, className = "", codeAct
       <div className={`markdown-content prose-sm ${isStreaming ? "is-streaming" : ""} ${className}`}>
         <ReactMarkdown
           remarkPlugins={remarkPlugins}
-          rehypePlugins={rehypePlugins}
+          rehypePlugins={rawHtml ? rehypePlugins : rehypePluginsNoRaw}
+          remarkRehypeOptions={rawHtml ? sanitizedRemarkRehypeOptions : undefined}
           urlTransform={markdownUrlTransform}
           components={mdComponents}
         >

package/src/web/components/shared/markdown-sanitize.ts

@@ -0,0 +1,65 @@
+import { defaultSchema, type Options as SanitizeSchema } from "rehype-sanitize";
+
+/**
+ * What HTML inside Markdown may become once rehype-raw has parsed it. The app shell has no CSP
+ * and keeps the auth token in `localStorage`, so anything that can run script, navigate the
+ * page, load a document or restyle the app is dropped: `<iframe srcdoc>`, `<script>`, `on*`
+ * handlers, `<svg onload>`, `<form>`, `<object>`, `<embed>`, `<meta http-equiv>`, `<base>`,
+ * `<style>`, `style=` and arbitrary `class=` (Tailwind classes alone can lay a fake screen over
+ * the app). An element not listed is unwrapped, so its text still shows.
+ *
+ * It starts from GitHub's allow-list (rehype-sanitize's default), which already covers GFM:
+ * tables, task-list checkboxes (forced disabled), footnotes, `<details>`, `<kbd>`, `<sub>`,
+ * `<sup>`, `<br>`, images and links.
+ *
+ * URLs are deliberately not checked here. `markdownUrlTransform` runs over every element's
+ * URL attributes after the plugins, raw HTML included, and is the one place that decides which
+ * destinations are allowed — it has to keep `README.md:5` and `C:\x.png`, which a scheme
+ * allow-list reads as the schemes `readme.md` and `c` and would delete.
+ *
+ * KaTeX and Shiki add their markup after this runs (rehype-katex is the next plugin, Shiki
+ * renders inside the code-block component), so neither needs anything allowed here beyond the
+ * classes remark-math puts on the code it hands to rehype-katex.
+ */
+export const markdownSanitizeSchema: SanitizeSchema = {
+  ...defaultSchema,
+  strip: [...(defaultSchema.strip ?? []), "style"],
+  tagNames: [...(defaultSchema.tagNames ?? []), "abbr", "mark", "small", "u"],
+  // `<source>` is only on the list for `<picture>`; anywhere else it is a media loader.
+  ancestors: { ...defaultSchema.ancestors, source: ["picture"] },
+  attributes: {
+    ...defaultSchema.attributes,
+    code: [["className", /^language-./, "math-inline", "math-display"]],
+  },
+  protocols: { cite: ["http", "https"], longDesc: ["http", "https"] },
+};
+
+const CLOBBER_PREFIX = defaultSchema.clobberPrefix ?? "user-content-";
+
+interface HastNode {
+  type: string;
+  tagName?: string;
+  properties?: Record<string, unknown>;
+  children?: HastNode[];
+}
+
+function prefixFragments(node: HastNode): void {
+  const href = node.tagName === "a" ? node.properties?.href : undefined;
+  if (typeof href === "string" && href.length > 1 && href.startsWith("#")) {
+    node.properties!.href = `#${CLOBBER_PREFIX}${href.slice(1)}`;
+  }
+  node.children?.forEach(prefixFragments);
+}
+
+/**
+ * The sanitiser prefixes every `id` and `name` (a bare `id="config"` would otherwise become
+ * `window.config`), but not the `#fragment` links that point at them, so footnotes and in-page
+ * anchors stopped landing anywhere. This prefixes those links the same way. It needs
+ * remark-rehype's own footnote prefix turned off, or footnote ids get the prefix twice.
+ */
+export function rehypePrefixFragmentLinks() {
+  return (tree: HastNode) => prefixFragments(tree);
+}
+
+/** remark-rehype options for the sanitised pipeline: the sanitiser adds the id prefix. */
+export const sanitizedRemarkRehypeOptions = { clobberPrefix: "" };

package/src/web/components/web-preview/web-preview-tab.tsx

@@ -30,7 +30,8 @@ function allowFramingHere(): Promise<void> {
  */
 export function WebPreviewTab({ metadata }: { metadata?: Record<string, unknown> }) {
   const url = safePreviewUrl(metadata?.url, window.location.origin);
-  const isPrivate = metadata?.via === "tailscale";
+  // `local` is the AI's open_url on the host's own browser: no forward, so only this machine reaches it.
+  const isPrivate = metadata?.via === "tailscale" || metadata?.via === "local";
   const [reloadKey, setReloadKey] = useState(0);
   const [copied, setCopied] = useState(false);
   const [framingAsked, setFramingAsked] = useState(false);
@@ -58,7 +59,8 @@ export function WebPreviewTab({ metadata }: { metadata?: Record<string, unknown>
       <div role="toolbar" aria-label="Web preview"
         className="flex items-center gap-2 md:gap-1 shrink-0 h-12 md:h-8 px-2 border-t md:border-t-0 md:border-b border-border">
         <span className="flex items-center justify-center shrink-0 size-7 text-muted-foreground"
-          title={isPrivate ? "Private: only devices in your tailnet can open this address" : "Public: anyone with this link can open it"}>
+          title={metadata?.via === "local" ? "Private: only this machine can open this address"
+            : isPrivate ? "Private: only devices in your tailnet can open this address" : "Public: anyone with this link can open it"}>
           {isPrivate ? <Lock className="size-3.5" /> : <Globe className="size-3.5" />}
         </span>
         <span className="flex-1 min-w-0 truncate text-xs text-muted-foreground select-all">{url}</span>
@@ -76,7 +78,8 @@ export function WebPreviewTab({ metadata }: { metadata?: Record<string, unknown>
           own cookies and storage; without allow-top-navigation it cannot navigate PPM away. */}
       {framingAsked ? (
         <iframe
-          key={reloadKey}
+          // The AI's open_url sets aiOpenAt on every call: a page it opens again reloads.
+          key={`${reloadKey}:${String(metadata?.aiOpenAt ?? "")}`}
           title={`Preview of ${url}`}
           src={url}
           sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-modals allow-downloads"

package/src/web/design-share-page/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <meta name="robots" content="noindex, nofollow" />
+    <meta name="referrer" content="no-referrer" />
+    <meta name="color-scheme" content="light dark" />
+    <!-- No favicon request: PPM serves no /favicon.ico, so the automatic one is a console 404. -->
+    <link rel="icon" href="data:," />
+    <title>Design review</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/src/web/design-share-page/main.tsx

@@ -0,0 +1,11 @@
+import { createRoot } from "react-dom/client";
+import "./share.css";
+import { ShareApp } from "./share-app";
+
+/**
+ * Entry of the reviewer's page at `/s/<code>`. Deliberately none of the app's start-up: no
+ * service worker, no stores, no PPM token, no trace client. Everything this page knows comes
+ * from `/s/<code>/…`.
+ */
+const root = document.getElementById("root");
+if (root) createRoot(root).render(<ShareApp />);

package/src/web/design-share-page/share-api.ts

@@ -0,0 +1,131 @@
+import { GUEST_KEY_HEADER, GUEST_VERSION_CHANGED, type DesignShareGuestInfo } from "../../shared/design-share-guest-types";
+import type { GuestThread } from "./share-thread-model";
+
+/**
+ * The reviewer page's calls to `/s/<code>/…`. Nothing here reads or sends PPM's own token:
+ * a write carries the reviewer's key and the cross-origin header pair, nothing else.
+ *
+ * Every failure is an {@link ShareApiError} whose `failure` says what the page should do:
+ * `invalid` (the link no longer opens — say so and stop), `rate-limited` (wait), `network`
+ * (try again later) or `error` with the server's message for the reviewer.
+ */
+
+export type ShareFailure =
+  | { kind: "invalid" }
+  | { kind: "rate-limited"; retryAfterMs: number }
+  | { kind: "network" }
+  | { kind: "error"; status: number; message: string; code?: string };
+
+export class ShareApiError extends Error {
+  constructor(readonly failure: ShareFailure) {
+    super(failureMessage(failure));
+  }
+}
+
+/** Seconds from a `Retry-After` header, at least one, defaulting to ten. */
+export function retryAfterMs(header: string | null): number {
+  const seconds = Number(header);
+  return (Number.isFinite(seconds) && seconds > 0 ? Math.ceil(seconds) : 10) * 1000;
+}
+
+/**
+ * What a failed response means. `invalidOn404` is for the link-level reads (`/info`, the
+ * thread list), where 404 can only mean the code stopped opening; on a write a 404 is the
+ * thread that is gone, which the next poll shows.
+ */
+export function failureFromResponse(
+  status: number, body: unknown, retryAfter: string | null, invalidOn404: boolean,
+): ShareFailure {
+  if (status === 404 && invalidOn404) return { kind: "invalid" };
+  if (status === 429) return { kind: "rate-limited", retryAfterMs: retryAfterMs(retryAfter) };
+  const raw = body && typeof body === "object" ? body as { error?: unknown; code?: unknown } : {};
+  const message = typeof raw.error === "string" && raw.error ? raw.error.slice(0, 300) : "Something went wrong; try again";
+  return { kind: "error", status, message, ...(typeof raw.code === "string" ? { code: raw.code } : {}) };
+}
+
+export function failureMessage(f: ShareFailure): string {
+  switch (f.kind) {
+    case "invalid": return "This link is no longer valid";
+    case "rate-limited": return `Too many requests. Try again in ${Math.ceil(f.retryAfterMs / 1000)} s.`;
+    case "network": return "Could not reach the server. Check your connection.";
+    case "error": return f.message;
+  }
+}
+
+/** The code in `/s/<code>`, or null for any other path. */
+export function shareCodeFromPath(pathname: string): string | null {
+  const m = /^\/s\/([A-Za-z0-9_-]{1,128})$/.exec(pathname);
+  return m ? m[1]! : null;
+}
+
+async function call<T>(url: string, init: RequestInit, invalidOn404: boolean): Promise<{ data: T; res: Response }> {
+  let res: Response;
+  try {
+    res = await fetch(url, { credentials: "omit", cache: "no-store", ...init });
+  } catch {
+    throw new ShareApiError({ kind: "network" });
+  }
+  const body: unknown = res.status === 304 ? null : await res.json().catch(() => null);
+  if (!res.ok && res.status !== 304) {
+    throw new ShareApiError(failureFromResponse(res.status, body, res.headers.get("retry-after"), invalidOn404));
+  }
+  return { data: (body as { data?: T } | null)?.data as T, res };
+}
+
+export function shareBase(code: string): string {
+  return `/s/${encodeURIComponent(code)}`;
+}
+
+export async function fetchShareInfo(code: string): Promise<DesignShareGuestInfo> {
+  return (await call<DesignShareGuestInfo>(`${shareBase(code)}/info`, {}, true)).data;
+}
+
+/**
+ * The thread list and the version the link shows now, or `unchanged` when `etag` still
+ * describes both (304: the ETag covers the version, so a re-pin always answers in full).
+ */
+export async function fetchThreads(
+  code: string, key: string, etag: string | null,
+): Promise<{ unchanged: true } | { unchanged: false; threads: GuestThread[]; versionId: string | null; etag: string | null }> {
+  const headers: Record<string, string> = { [GUEST_KEY_HEADER]: key };
+  if (etag) headers["If-None-Match"] = etag;
+  const { data, res } = await call<{ threads: GuestThread[]; versionId?: unknown }>(`${shareBase(code)}/comments`, { headers }, true);
+  if (res.status === 304) return { unchanged: true };
+  const versionId = typeof data?.versionId === "string" ? data.versionId : null;
+  return { unchanged: false, threads: data?.threads ?? [], versionId, etag: res.headers.get("etag") };
+}
+
+/** A write refused because the owner re-pinned the link since this page loaded. */
+export function isVersionChanged(f: ShareFailure): boolean {
+  return f.kind === "error" && f.code === GUEST_VERSION_CHANGED;
+}
+
+function write<T>(code: string, key: string, method: string, path: string, body: object): Promise<T> {
+  return call<T>(`${shareBase(code)}/comments${path}`, {
+    method,
+    headers: { "Content-Type": "application/json", "X-PPM-Request": "1", [GUEST_KEY_HEADER]: key },
+    body: JSON.stringify(body),
+  }, false).then((r) => r.data);
+}
+
+const seg = (id: string): string => `/${encodeURIComponent(id)}`;
+
+/** Every write the reviewer can make; each answers the thread as it now stands. */
+export function shareWrites(code: string, key: string) {
+  const thread = (p: Promise<{ thread: GuestThread }>) => p.then((d) => d.thread);
+  return {
+    /** `versionId`: the version this page shows, which the comment's anchor was read from. */
+    addThread: (anchor: unknown, body: string, name: string, versionId: string) =>
+      thread(write(code, key, "POST", "", { anchor, body, name, versionId })),
+    reply: (id: string, body: string, name: string) =>
+      thread(write(code, key, "POST", `${seg(id)}/replies`, { body, name })),
+    editThread: (id: string, body: string) => thread(write(code, key, "PATCH", seg(id), { body })),
+    deleteThread: (id: string) => write<{ deleted: string }>(code, key, "DELETE", seg(id), {}).then(() => undefined),
+    editReply: (id: string, replyId: string, body: string) =>
+      thread(write(code, key, "PATCH", `${seg(id)}/replies${seg(replyId)}`, { body })),
+    deleteReply: (id: string, replyId: string) =>
+      thread(write(code, key, "DELETE", `${seg(id)}/replies${seg(replyId)}`, {})),
+  };
+}
+
+export type ShareWrites = ReturnType<typeof shareWrites>;

package/src/web/design-share-page/share-app.tsx

@@ -0,0 +1,14 @@
+import { shareCodeFromPath } from "./share-api";
+import { useShareInfo } from "./use-share-info";
+import { ShareReview } from "./share-review";
+import { ShareFailed, ShareInvalid, ShareLoading } from "./share-states";
+
+/** The reviewer page: what the link opens, or why it does not. */
+export function ShareApp() {
+  const code = shareCodeFromPath(window.location.pathname);
+  const { state, retry } = useShareInfo(code);
+  if (!code || state.status === "invalid") return <ShareInvalid />;
+  if (state.status === "loading") return <ShareLoading />;
+  if (state.status === "error") return <ShareFailed message={state.message} onRetry={retry} />;
+  return <ShareReview info={state.info} code={code} />;
+}