@hienlh/ppm 0.23.13 → 0.23.15

package/src/web/design-share-page/share-bottom-sheet.tsx

@@ -0,0 +1,61 @@
+import { useEffect, useRef, type ReactNode } from "react";
+
+/**
+ * A phone's bottom sheet, without the app's radix layer: a backdrop that closes it, a panel
+ * at most 85% of the screen tall with rounded top corners, clear of the home indicator. Esc
+ * closes it, focus moves into it when it opens and goes back where it was when it closes,
+ * and Tab stays inside it while it is open.
+ */
+
+const FOCUSABLE = "button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [href], [tabindex]:not([tabindex='-1'])";
+
+export function ShareBottomSheet({ open, onClose, label, children }: {
+  open: boolean;
+  onClose: () => void;
+  label: string;
+  children: ReactNode;
+}) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+
+  useEffect(() => {
+    if (!open) return;
+    const previous = document.activeElement as HTMLElement | null;
+    const panel = panelRef.current;
+    // An input already focused by its own autoFocus keeps it; otherwise the panel takes it.
+    if (panel && !panel.contains(document.activeElement)) panel.focus();
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") { e.preventDefault(); onCloseRef.current(); return; }
+      if (e.key !== "Tab" || !panel) return;
+      const items = [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];
+      if (items.length === 0) { e.preventDefault(); return; }
+      const first = items[0]!, last = items[items.length - 1]!;
+      if (e.shiftKey && (document.activeElement === first || document.activeElement === panel)) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      previous?.focus?.();
+    };
+  }, [open]);
+
+  if (!open) return null;
+  return (
+    <div className="fixed inset-0 z-50">
+      <div className="absolute inset-0 bg-black/40" onClick={onClose} aria-hidden="true" />
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={label}
+        tabIndex={-1}
+        className="absolute inset-x-0 bottom-0 flex max-h-[85dvh] flex-col rounded-t-2xl border-t border-border bg-panel pb-[max(0.5rem,env(safe-area-inset-bottom))] shadow-2xl outline-none"
+      >
+        <div className="mx-auto mt-2 h-1.5 w-10 shrink-0 rounded-full bg-border" aria-hidden="true" />
+        <div className="flex min-h-0 flex-1 flex-col">{children}</div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,92 @@
+import { useEffect, useRef, useState } from "react";
+import { RefreshCw } from "@/lib/icons";
+import { fitFrame, type Size } from "../components/design/canvas/canvas-geometry";
+import type { CommentPins } from "../components/design/comments/use-comment-pins";
+import type { ElementPicker } from "../components/design/comments/use-element-picker";
+import type { ShareCanvasState } from "./use-share-canvas";
+import type { GuestThread } from "./share-thread-model";
+import { SharePinsOverlay } from "./share-pins-overlay";
+import { buttonOutline, cx } from "./share-ui";
+
+/**
+ * The stage: the shared version in a sandboxed frame, sized to the chosen device frame and
+ * scaled to fit, with the pins over it and a hint while the reviewer is choosing an element.
+ *
+ * `sandbox="allow-scripts"` without `allow-same-origin` gives the design an opaque origin,
+ * so its scripts can read nothing of this page — which matters more here than in the app,
+ * because this page shares its origin with PPM. `no-referrer` keeps the link's code out of
+ * any request the design makes.
+ */
+
+function useStageSize() {
+  const ref = useRef<HTMLDivElement>(null);
+  const [size, setSize] = useState<Size>({ width: 0, height: 0 });
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const observer = new ResizeObserver(([entry]) => {
+      if (entry) setSize({ width: entry.contentRect.width, height: entry.contentRect.height });
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+  return { ref, size };
+}
+
+export function ShareCanvas({ canvas, title, frameSize, picker, pins, open, numbers, activeId, onOpenThread, isMobile }: {
+  canvas: ShareCanvasState;
+  title: string;
+  frameSize: Size | null;
+  picker: ElementPicker;
+  pins: CommentPins;
+  open: readonly GuestThread[];
+  numbers: ReadonlyMap<string, number>;
+  activeId: string | null;
+  onOpenThread: (id: string) => void;
+  isMobile: boolean;
+}) {
+  const stage = useStageSize();
+  const fit = fitFrame(frameSize, stage.size);
+  const framed = frameSize !== null;
+  const hint = picker.on && !picker.selected
+    ? isMobile
+      ? picker.outlined ? `Tap the <${picker.outlined.tag}> again to comment on it.` : "Tap the part you want to comment on."
+      : "Click the part you want to comment on · Esc to stop"
+    : null;
+
+  return (
+    <div ref={stage.ref} className={cx("relative min-h-0 min-w-0 flex-1 overflow-hidden", framed && "bg-stage")}>
+      <div
+        className={cx("absolute left-1/2 top-1/2 origin-center bg-white", framed && "rounded-md shadow-lg ring-1 ring-border")}
+        style={{ width: fit.width, height: fit.height, transform: `translate(-50%, -50%) scale(${fit.scale})` }}
+      >
+        <iframe
+          ref={canvas.iframeRef}
+          src={canvas.src}
+          title={`Shared design: ${title}`}
+          sandbox="allow-scripts"
+          referrerPolicy="no-referrer"
+          onLoad={canvas.bridge.frameLoaded}
+          className="block size-full border-0 bg-white"
+        />
+      </div>
+      <SharePinsOverlay open={open} numbers={numbers} pins={pins} fit={fit} stage={stage.size}
+        activeId={activeId} onOpen={onOpenThread} />
+      {hint && (
+        <div className="pointer-events-none absolute inset-x-0 top-2 z-20 flex justify-center px-3">
+          <p className="rounded-full border border-border bg-panel px-3 py-1.5 text-sm text-text-2 shadow-md" role="status">{hint}</p>
+        </div>
+      )}
+      {canvas.dead && (
+        <div className="absolute inset-x-0 top-2 z-30 flex justify-center px-3">
+          <div className="flex items-center gap-2 rounded-lg border border-border bg-panel px-3 py-2 text-sm shadow-md" role="alert">
+            The design stopped responding.
+            <button type="button" className={buttonOutline} onClick={canvas.reload}>
+              <RefreshCw className="size-4" /> Reload
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,104 @@
+import { useState, type FormEvent } from "react";
+import { Loader2, X } from "@/lib/icons";
+import type { PickedElement } from "../../shared/design-bridge-messages-picker";
+import { COMMENT_LIMITS } from "../../shared/design-comment-types";
+import { ShareNameField } from "./share-name-prompt";
+import { buttonPrimary, buttonQuiet, cx, fieldClass } from "./share-ui";
+
+/**
+ * Writing: one form for a new comment, a reply and an edit. While the reviewer has no name
+ * yet the form asks for it too, and the name is checked before anything is sent.
+ */
+
+export interface NameControl {
+  name: string | null;
+  setName: (raw: string) => { ok: true; name: string } | { ok: false; error: string };
+}
+
+export function ShareTextForm({ names, submitLabel, placeholder, initial = "", onSubmit, onCancel, autoFocus, compact }: {
+  /** Absent for an edit, which keeps the name the entry was written with. */
+  names?: NameControl;
+  submitLabel: string;
+  placeholder: string;
+  initial?: string;
+  /** Resolves true when it went through, which clears the form. */
+  onSubmit: (body: string, name: string) => Promise<boolean>;
+  onCancel?: () => void;
+  autoFocus?: boolean;
+  compact?: boolean;
+}) {
+  const [body, setBody] = useState(initial);
+  const [nameDraft, setNameDraft] = useState("");
+  const [nameError, setNameError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const trimmed = body.trim();
+  const tooLong = [...body].length > COMMENT_LIMITS.body;
+
+  const submit = async (e: FormEvent) => {
+    e.preventDefault();
+    if (busy || !trimmed || tooLong) return;
+    let name = names?.name ?? "";
+    if (names && !name) {
+      const saved = names.setName(nameDraft);
+      if (!saved.ok) { setNameError(saved.error); return; }
+      name = saved.name;
+    }
+    setBusy(true);
+    const ok = await onSubmit(trimmed, name);
+    setBusy(false);
+    if (ok) setBody("");
+  };
+
+  return (
+    <form onSubmit={submit} className="flex flex-col gap-2">
+      {names && !names.name && (
+        <ShareNameField value={nameDraft} onChange={(v) => { setNameDraft(v); setNameError(null); }} error={nameError} />
+      )}
+      <textarea
+        value={body}
+        onChange={(e) => setBody(e.target.value)}
+        placeholder={placeholder}
+        aria-label={placeholder}
+        autoFocus={autoFocus}
+        rows={compact ? 2 : 3}
+        className={cx(fieldClass, "resize-y leading-relaxed")}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) void submit(e);
+        }}
+      />
+      {tooLong && <p className="text-xs text-error">At most {COMMENT_LIMITS.body} characters.</p>}
+      <div className="flex justify-end gap-2">
+        {onCancel && <button type="button" className={buttonQuiet} onClick={onCancel}>Cancel</button>}
+        <button type="submit" className={buttonPrimary} disabled={busy || !trimmed || tooLong}>
+          {busy && <Loader2 className="size-4 animate-spin" />} {submitLabel}
+        </button>
+      </div>
+    </form>
+  );
+}
+
+/** A new comment on the element the reviewer picked: its tag and text, never its markup. */
+export function ShareComposer({ element, names, onSubmit, onCancel }: {
+  element: PickedElement;
+  names: NameControl;
+  onSubmit: (body: string, name: string) => Promise<boolean>;
+  onCancel: () => void;
+}) {
+  return (
+    <div className="flex flex-col gap-3 p-4">
+      <div className="flex items-start gap-2">
+        <div className="min-w-0 flex-1">
+          <h2 className="text-sm font-semibold">New comment</h2>
+          <p className="mt-0.5 truncate text-xs text-text-3">
+            <span className="font-mono">&lt;{element.tag}&gt;</span>{element.text ? ` ${element.text}` : ""}
+          </p>
+        </div>
+        <button type="button" className={buttonQuiet} onClick={onCancel} aria-label="Cancel comment">
+          <X className="size-5" />
+        </button>
+      </div>
+      <ShareTextForm names={names} submitLabel="Comment" placeholder="What should change here?" autoFocus
+        onSubmit={onSubmit} />
+    </div>
+  );
+}

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

@@ -0,0 +1,92 @@
+import { useId, useState } from "react";
+import { Pencil, ShieldCheck, Trash2 } from "@/lib/icons";
+import type { CommentAuthor } from "../../shared/design-comment-types";
+import { bylineOf, type RootDelete } from "./share-thread-model";
+import { ShareTextForm } from "./share-composer";
+import { buttonQuiet, cx, formatDateTime } from "./share-ui";
+
+/**
+ * One comment or reply: byline, time, the text, and the reviewer's own actions on it.
+ *
+ * Everything a reviewer or the owner wrote is rendered as a React text node and nothing
+ * else — never markup, never markdown — so a body cannot become part of this page, which
+ * shares its origin with PPM. The owner's byline is a badge, which no typed name can be.
+ */
+
+export function Byline({ author }: { author: CommentAuthor }) {
+  const by = bylineOf(author);
+  if (by.owner) {
+    return (
+      <span className="inline-flex items-center gap-1 rounded-full bg-owner px-2 py-0.5 text-xs font-semibold text-owner-fg">
+        <ShieldCheck className="size-3.5" /> Owner
+      </span>
+    );
+  }
+  return <span className="min-w-0 truncate text-sm font-semibold">{by.name}</span>;
+}
+
+export function ShareEntry({ author, createdAt, updatedAt, body, mine, onEdit, onDelete, deleteRule }: {
+  author: CommentAuthor;
+  createdAt: string;
+  updatedAt: string;
+  body: string;
+  mine: boolean;
+  onEdit?: (body: string) => Promise<boolean>;
+  onDelete?: () => Promise<boolean>;
+  /** For a thread's root; a reply is deletable whenever it is the reviewer's own. */
+  deleteRule?: RootDelete | null;
+}) {
+  const [editing, setEditing] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+  const [blockedShown, setBlockedShown] = useState(false);
+  const reasonId = useId();
+  const blocked = deleteRule && !deleteRule.allowed ? deleteRule.reason : null;
+  const canDelete = mine && onDelete && deleteRule !== null;
+
+  return (
+    <div className="flex flex-col gap-1">
+      <div className="flex min-w-0 items-center gap-2">
+        <Byline author={author} />
+        {mine && <span className="shrink-0 text-xs text-text-3">(you)</span>}
+        <span className="ml-auto shrink-0 text-xs text-text-3">
+          {formatDateTime(createdAt)}{updatedAt !== createdAt ? " · edited" : ""}
+        </span>
+      </div>
+      {editing && onEdit ? (
+        <ShareTextForm submitLabel="Save" placeholder="Edit your comment" initial={body} autoFocus compact
+          onCancel={() => setEditing(false)}
+          onSubmit={async (next) => { const ok = await onEdit(next); if (ok) setEditing(false); return ok; }} />
+      ) : (
+        <p className="whitespace-pre-wrap break-words text-sm leading-relaxed text-text">{body}</p>
+      )}
+      {mine && !editing && (onEdit || canDelete) && (
+        <div className="-ml-3 flex flex-wrap items-center gap-1">
+          {onEdit && (
+            <button type="button" className={buttonQuiet} onClick={() => setEditing(true)}>
+              <Pencil className="size-4" /> Edit
+            </button>
+          )}
+          {canDelete && !confirming && (
+            // A blocked delete stays a working button: tapping it says why, rather than doing nothing.
+            <button type="button" className={cx(buttonQuiet, blocked && "opacity-60")}
+              aria-expanded={blocked ? blockedShown : undefined} aria-controls={blocked ? reasonId : undefined}
+              onClick={() => (blocked ? setBlockedShown((v) => !v) : setConfirming(true))}>
+              <Trash2 className="size-4" /> Delete
+            </button>
+          )}
+          {confirming && (
+            <>
+              <span className="px-1 text-sm text-text-2">Delete this?</span>
+              <button type="button" className={cx(buttonQuiet, "text-error")}
+                onClick={async () => { const ok = await onDelete!(); if (!ok) setConfirming(false); }}>
+                Delete
+              </button>
+              <button type="button" className={buttonQuiet} onClick={() => setConfirming(false)}>Keep</button>
+            </>
+          )}
+        </div>
+      )}
+      {blocked && blockedShown && <p id={reasonId} className="text-xs text-text-2" role="status">{blocked}</p>}
+    </div>
+  );
+}

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

@@ -0,0 +1,81 @@
+import { GUEST_KEY_RE } from "../../shared/design-share-guest-types";
+import { parseGuestName } from "../../shared/design-comment-thread-types";
+
+/**
+ * Who this browser is on one share link: a random key that makes entries "mine", and the
+ * name the reviewer typed. Both live in this origin's storage under `ppm-share:<linkId>:*`,
+ * keyed by the link's opaque id rather than its code, so the code is never written to
+ * storage and two links never share an identity.
+ *
+ * The key comes from `crypto.getRandomValues`, which exists on a plain-HTTP origin;
+ * `crypto.subtle` and `randomUUID` do not, and a LAN address is how a phone often arrives.
+ */
+
+export interface KeyValueStore {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+export type IdentityField = "key" | "name";
+
+export function storageKey(linkId: string, field: IdentityField): string {
+  return `ppm-share:${linkId}:${field}`;
+}
+
+/** Bytes as unpadded base64url; 32 bytes give the 43 characters the server expects. */
+export function encodeGuestKey(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function newGuestKey(fill: (bytes: Uint8Array) => Uint8Array = (b) => crypto.getRandomValues(b)): string {
+  return encodeGuestKey(fill(new Uint8Array(32)));
+}
+
+/** The stored key, or a new one saved in its place when there is none or it is malformed. */
+export function loadGuestKey(store: KeyValueStore, linkId: string, make: () => string = newGuestKey): string {
+  const stored = store.getItem(storageKey(linkId, "key"));
+  if (stored && GUEST_KEY_RE.test(stored)) return stored;
+  const key = make();
+  store.setItem(storageKey(linkId, "key"), key);
+  return key;
+}
+
+/** The stored name if it would still be accepted, else null (the page asks again). */
+export function loadGuestName(store: KeyValueStore, linkId: string): string | null {
+  const parsed = parseGuestName(store.getItem(storageKey(linkId, "name")));
+  return parsed.ok ? parsed.name : null;
+}
+
+export function saveGuestName(
+  store: KeyValueStore, linkId: string, raw: string,
+): { ok: true; name: string } | { ok: false; error: string } {
+  const parsed = parseGuestName(raw);
+  if (parsed.ok) store.setItem(storageKey(linkId, "name"), parsed.name);
+  return parsed;
+}
+
+/**
+ * `localStorage`, or memory when it cannot be used (a private window can throw on every
+ * access). An identity held in memory only lasts the visit, which is still a working page.
+ */
+export function browserStore(): KeyValueStore {
+  const memory = new Map<string, string>();
+  const fallback: KeyValueStore = {
+    getItem: (k) => memory.get(k) ?? null,
+    setItem: (k, v) => { memory.set(k, v); },
+  };
+  try {
+    const ls = window.localStorage;
+    const probe = "ppm-share:probe";
+    ls.setItem(probe, "1");
+    ls.removeItem(probe);
+    return {
+      getItem: (k) => { try { return ls.getItem(k); } catch { return fallback.getItem(k); } },
+      setItem: (k, v) => { try { ls.setItem(k, v); } catch { fallback.setItem(k, v); } },
+    };
+  } catch {
+    return fallback;
+  }
+}

package/src/web/design-share-page/share-name-prompt.tsx

@@ -0,0 +1,59 @@
+import { useId, useState, type FormEvent } from "react";
+import { COMMENT_LIMITS } from "../../shared/design-comment-types";
+import { buttonPrimary, buttonQuiet, fieldClass } from "./share-ui";
+
+/**
+ * The reviewer's name: asked inside the first form that writes anything (so a comment is
+ * one step, not two), and changeable later. 1 to 40 characters; "Owner" is refused by the
+ * same rule the server applies, because the owner's entries carry a badge, not a name.
+ */
+
+export function ShareNameField({ value, onChange, error }: {
+  value: string;
+  onChange: (v: string) => void;
+  error: string | null;
+}) {
+  const id = useId();
+  return (
+    <div className="flex flex-col gap-1">
+      <label htmlFor={id} className="text-xs font-medium text-text-2">Your name</label>
+      <input
+        id={id}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        maxLength={COMMENT_LIMITS.guestName * 2}
+        autoComplete="name"
+        placeholder="Shown next to your comments"
+        className={fieldClass}
+        aria-invalid={error ? true : undefined}
+      />
+      {error && <p className="text-xs text-error" role="alert">{error}</p>}
+    </div>
+  );
+}
+
+/** The change-name form. */
+export function ShareNamePrompt({ current, onSave, onDone }: {
+  current: string | null;
+  onSave: (raw: string) => { ok: true } | { ok: false; error: string };
+  onDone: () => void;
+}) {
+  const [value, setValue] = useState(current ?? "");
+  const [error, setError] = useState<string | null>(null);
+  const submit = (e: FormEvent) => {
+    e.preventDefault();
+    const saved = onSave(value);
+    if (!saved.ok) { setError(saved.error); return; }
+    onDone();
+  };
+  return (
+    <form onSubmit={submit} className="flex flex-col gap-3 p-4">
+      <p className="text-sm text-text-2">Your name is shown next to what you write on this link. Comments you already wrote keep the name they were written with.</p>
+      <ShareNameField value={value} onChange={(v) => { setValue(v); setError(null); }} error={error} />
+      <div className="flex justify-end gap-2">
+        <button type="button" className={buttonQuiet} onClick={onDone}>Cancel</button>
+        <button type="submit" className={buttonPrimary}>Save name</button>
+      </div>
+    </form>
+  );
+}

package/src/web/design-share-page/share-panel-content.tsx

@@ -0,0 +1,57 @@
+import type { PickedElement } from "../../shared/design-bridge-messages-picker";
+import type { PinStatus } from "../components/design/comments/use-comment-pins";
+import type { GuestThread } from "./share-thread-model";
+import type { NameControl } from "./share-composer";
+import type { ShareActions } from "./use-share-session";
+import { ShareComposer } from "./share-composer";
+import { ShareNamePrompt } from "./share-name-prompt";
+import { ShareThreadView } from "./share-thread-view";
+import { ShareThreadsPanel } from "./share-threads-panel";
+
+/**
+ * What the comments column shows — the side panel on a desktop, the bottom sheet on a
+ * phone: the list, one thread, the new-comment form for the element just chosen, or the
+ * name form. The same content in both places, so the two layouts cannot drift apart.
+ */
+
+export type PanelView = { kind: "list" } | { kind: "thread"; id: string } | { kind: "compose" } | { kind: "name" };
+
+export function SharePanelContent({ view, setView, threads, numbers, statusOf, names, actions, picked, expiryText, onCompose, onCancelCompose, onClose }: {
+  view: PanelView;
+  setView: (view: PanelView) => void;
+  threads: { open: GuestThread[]; resolved: GuestThread[] };
+  numbers: ReadonlyMap<string, number>;
+  statusOf: (id: string) => PinStatus;
+  names: NameControl;
+  actions: ShareActions;
+  picked: PickedElement | null;
+  expiryText: string | null;
+  onCompose: (el: PickedElement, body: string, name: string) => Promise<boolean>;
+  onCancelCompose: () => void;
+  onClose?: () => void;
+}) {
+  if (view.kind === "compose" && picked) {
+    return <ShareComposer element={picked} names={names} onCancel={onCancelCompose} onSubmit={(body, name) => onCompose(picked, body, name)} />;
+  }
+  if (view.kind === "name") {
+    return <ShareNamePrompt current={names.name} onSave={names.setName} onDone={() => setView({ kind: "list" })} />;
+  }
+  const toList = () => setView({ kind: "list" });
+  if (view.kind === "thread") {
+    const thread = threads.open.find((t) => t.id === view.id) ?? threads.resolved.find((t) => t.id === view.id);
+    // A thread the owner deleted meanwhile is simply gone from the list.
+    if (thread) {
+      return (
+        <ShareThreadView thread={thread} number={numbers.get(thread.id) ?? null} status={statusOf(thread.id)}
+          names={names} actions={actions} onBack={toList} onDeleted={toList} />
+      );
+    }
+  }
+  return (
+    <ShareThreadsPanel
+      open={threads.open} resolved={threads.resolved} numbers={numbers} statusOf={statusOf}
+      activeId={view.kind === "thread" ? view.id : null} name={names.name} expiryText={expiryText}
+      onOpen={(id) => setView({ kind: "thread", id })} onChangeName={() => setView({ kind: "name" })} onClose={onClose}
+    />
+  );
+}

package/src/web/design-share-page/share-pins-overlay.tsx

@@ -0,0 +1,50 @@
+import type { FrameFit, Size } from "../components/design/canvas/canvas-geometry";
+import type { CommentPins } from "../components/design/comments/use-comment-pins";
+import { pinCenter, rectVisible } from "../components/design/comments/comment-overlay-geometry";
+import type { GuestThread } from "./share-thread-model";
+import { cx } from "./share-ui";
+
+/**
+ * Numbered pins over the design, one per open thread whose element is on screen, at the
+ * element's top-right corner — the same place the owner's canvas puts them. Each is a 44px
+ * target around a smaller dot, and a tap opens the thread; a reviewer has nothing else to do
+ * with a pin, so there is no menu and no long-press.
+ */
+export function SharePinsOverlay({ open, numbers, pins, fit, stage, activeId, onOpen }: {
+  open: readonly GuestThread[];
+  numbers: ReadonlyMap<string, number>;
+  pins: CommentPins;
+  fit: FrameFit;
+  stage: Size;
+  activeId: string | null;
+  onOpen: (id: string) => void;
+}) {
+  return (
+    <div className="pointer-events-none absolute inset-0 z-10 overflow-hidden" aria-label="Comment pins">
+      {open.map((t) => {
+        const status = pins.statusOf(t.id);
+        const rect = pins.rects.get(t.id)?.rect;
+        if ((status !== "pinned" && status !== "moved") || !rect || !rectVisible(rect, fit)) return null;
+        const at = pinCenter(rect, fit, stage);
+        const n = numbers.get(t.id);
+        return (
+          <button
+            key={t.id}
+            type="button"
+            onClick={() => onOpen(t.id)}
+            aria-label={`Comment ${n ?? ""}: ${t.body}`}
+            className="pointer-events-auto absolute flex size-11 -translate-x-1/2 -translate-y-1/2 select-none items-center justify-center"
+            style={{ left: at.left, top: at.top }}
+          >
+            <span className={cx(
+              "flex size-6 items-center justify-center rounded-full bg-primary text-xs font-semibold text-primary-fg shadow-md ring-2 ring-panel",
+              activeId === t.id && "scale-125 ring-text",
+            )}>
+              {n}
+            </span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}