partforge 0.3.3 → 0.5.0

package/src/framework/geometry/solid-hash.js

@@ -0,0 +1,21 @@
+// Stable content hash for cached solids. Serializes scalar args canonically and
+// folds via FNV-1a → base36. Solid operands are passed as their own (already
+// computed) short `_hash` string, so composing two solids stays O(1) and the
+// resulting key length stays bounded no matter how deep the build graph is.
+export function h(...parts) {
+  return fnv(parts.map(canon).join("|"));
+}
+
+function canon(x) {
+  if (Array.isArray(x)) return "[" + x.map(canon).join(",") + "]";
+  if (x && typeof x === "object") return "{" + Object.keys(x).sort().map((k) => k + ":" + canon(x[k])).join(",") + "}";
+  return String(x);
+}
+
+// FNV-1a folded to 32-bit space (collision risk acceptable: retained only for one
+// sub-part's build graph ~3–15 nodes, rebuilt each round, no accumulation).
+function fnv(s) {
+  let hsh = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { hsh ^= s.charCodeAt(i); hsh = Math.imul(hsh, 0x01000193); }
+  return (hsh >>> 0).toString(36);
+}

package/src/framework/jobs.js

@@ -42,13 +42,20 @@ export async function handle(kernel, part, msg, post) {
   try {
     if (msg.type === "generate") {
       const t0 = Date.now();
+      const useCache = msg.cache !== false; // ?debug toggle can disable caching (cache:false)
       const meshes = [];
+      kernel.resetCacheStats?.(); // count hits/misses for just this job
       for (const name of msg.subparts) {
-        const m = buildPosed(name, "display", msg.view).toMesh({ quality: "preview" });
-        meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges });
-        kernel.cleanup?.();
+        if (useCache) kernel.beginSubPart?.(name); // open the per-sub-part cache round
+        try {
+          const m = buildPosed(name, "display", msg.view).toMesh({ quality: "preview" });
+          meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges });
+        } finally {
+          if (useCache) kernel.endSubPart?.(); // always close the bracket — a throw mid-build must not strand pinned solids
+          kernel.cleanup?.();                  // free this round's transients (cached/pinned solids survive)
+        }
       }
-      post({ type: "meshes", meshes, ms: Date.now() - t0 });
+      post({ type: "meshes", meshes, ms: Date.now() - t0, cache: kernel.cacheStats?.() });
     } else if (msg.type === "export-stl") {
       const out = [];
       for (const name of exportSubParts(part, msg.view, p)) {

package/src/framework/mount.js

@@ -3,10 +3,13 @@ import { zipSync } from "fflate";
 import { createViewer } from "./viewer.js";
 import { loadRotating, saveRotating, loadCamera, saveCamera, loadView, saveView } from "./view-state.js";
 import { buildControls } from "./controls.js";
-import { relevantParamKeys } from "./param-deps.js";
+import { relevantParamKeys, subPartReadKeys, relevanceHash, RELEVANT_ALL } from "./param-deps.js";
 import { createGeometryService } from "./geometry-service.js";
 import { viewSubParts } from "./jobs.js";
 import { detectBackend } from "./geometry/probe.js";
+import { createDebugOverlay } from "./debug-overlay.js";
+import { attachPicker, formatSelection } from "./selection/index.js";
+import { createPickRequestClient } from "./pick-request/index.js";
 
 // Mount a full parametric-part app from a PartDefinition: 3-D viewer + control
 // panel + the two geometry workers + the auto-regenerating view/cache loop +
@@ -24,6 +27,15 @@ export function mount(part, { createWorker, container = document.getElementById(
   if (forcedBackend !== "occt" && forcedBackend !== "manifold") forcedBackend = null;
   const backendFor = () => forcedBackend ?? detectBackend(part, params);
 
+  // ?debug shows the cache debug overlay; ?debug&nocache starts with caching off.
+  const qs = new URLSearchParams(location.search);
+  const debug = qs.has("debug");
+  let cachingOn = !(debug && qs.has("nocache"));
+  let lastGen = { skipped: 0, rebuilt: 0 }; // Layer-1 counts for the most recent generate
+  const dbg = debug
+    ? createDebugOverlay({ initialCachingOn: cachingOn, onToggle: (on) => { cachingOn = on; forceRegen(); } })
+    : null;
+
   const statusEl = document.getElementById("status");
   const dlBtn = document.getElementById("download");
   const dlStepBtn = document.getElementById("download-step");
@@ -56,16 +68,88 @@ export function mount(part, { createWorker, container = document.getElementById(
   const savedBtn = savedView ? [...partSeg.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === savedView) : null;
   let view = savedBtn ? savedView : defaultView;
   if (savedBtn) for (const b of partSeg.children) b.classList.toggle("on", b === savedBtn);
+
+  // ?pick enables click-to-select: a toggle button + a transient toast. Off by
+  // default — no button, no listener, no behavior change. Deleting this block and
+  // the selection/ dir reverts the app exactly.
+  if (qs.has("pick")) {
+    const btn = document.createElement("button");
+    btn.id = "pf-pick";
+    btn.textContent = "Pick";
+    btn.title = "Click a surface to copy a selection token";
+    Object.assign(btn.style, {
+      position: "fixed", left: "12px", bottom: "12px", zIndex: 9999,
+      font: "12px system-ui, sans-serif", padding: "6px 10px", cursor: "pointer",
+    });
+    document.body.appendChild(btn);
+
+    const toast = document.createElement("div");
+    Object.assign(toast.style, {
+      position: "fixed", left: "12px", bottom: "48px", zIndex: 9999, maxWidth: "60ch",
+      font: "12px ui-monospace, monospace", padding: "6px 10px", borderRadius: "4px",
+      background: "rgba(20,24,29,0.92)", color: "#d8e0ea", display: "none",
+      whiteSpace: "pre-wrap", wordBreak: "break-word",
+    });
+    document.body.appendChild(toast);
+
+    const picker = attachPicker(viewer, {
+      part,
+      getContext: () => ({ view, params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} }),
+      onPick: (selection) => {
+        const token = formatSelection(selection, { style: "token" });
+        navigator.clipboard?.writeText(token);
+        toast.textContent = `copied: ${token}`;
+        toast.style.display = "block";
+        setTimeout(() => { toast.style.display = "none"; }, 4000);
+      },
+    });
+
+    btn.addEventListener("click", () => {
+      const isActive = btn.classList.toggle("on");
+      picker.setActive(isActive);
+      btn.style.outline = isActive ? "2px solid #ffcc33" : "";
+    });
+  } else if (qs.has("pickserver")) {
+    // Agent-driven mode: arm the picker only when the local pick-server asks for a
+    // click. Mutually exclusive with the clipboard ?pick toggle (else-if), so only one
+    // click listener is ever live. `?pickserver` or `?pickserver=http://host:port`.
+    const serverUrl = typeof qs.get("pickserver") === "string" && qs.get("pickserver")
+      ? qs.get("pickserver") : "http://127.0.0.1:4518";
+    createPickRequestClient({
+      serverUrl,
+      viewer,
+      part,
+      getContext: () => ({ view, params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} }),
+    });
+  }
+
   let framedView = null; // the view the camera was last framed to (null until first show)
   let cameraRestored = false; // saved camera applied once, on the first frame after load
   let generating = false;
   let paramsVersion = 0; // bumped on every settings edit
   let genVersion = -1;   // the params version the in-flight generate is building
   let genTimer = null;   // debounce timer for auto-regenerate
-  const cacheVersion = Object.fromEntries(names.map((n) => [n, -1])); // params version each was built at
+  const cacheHash = {}; // n -> relevance hash each sub-part's cached mesh was built at
+
+  // Memoize the per-sub-part read-key map per (paramsVersion, view): subPartReadKeys
+  // runs probe builds, so we compute it once per change, not per sub-part.
+  let _readsKey = null, _readsMap = null;
+  const readsFor = () => {
+    const key = `${paramsVersion}|${view}`;
+    if (_readsKey !== key) { _readsKey = key; _readsMap = subPartReadKeys(part, view, params); }
+    return _readsMap;
+  };
+  // The relevance hash for one sub-part at the current params (RELEVANT_ALL → hash
+  // over ALL params, so any edit invalidates it — the safe fallback).
+  const hashFor = (n) => {
+    if (!cachingOn) return `v${paramsVersion}`; // caching off: any edit invalidates every sub-part (Layer 1 off)
+    const reads = readsFor();
+    const keys = reads === RELEVANT_ALL ? Object.keys(params) : [...(reads.get(n) ?? Object.keys(params))];
+    return relevanceHash(keys, params);
+  };
 
-  // A cached sub-part is current only if it was built at the latest params version.
-  const isCurrent = (n) => viewer._subCache[n] && cacheVersion[n] === paramsVersion;
+  // A cached sub-part is current only if its relevance hash is unchanged.
+  const isCurrent = (n) => !!viewer._subCache[n] && cacheHash[n] === hashFor(n);
   const missingParts = () => viewSubParts(part, view, params).filter((n) => !isCurrent(n));
 
   // Reflect the active view. If every needed part is current, show it and enable
@@ -138,13 +222,14 @@ export function mount(part, { createWorker, container = document.getElementById(
         for (const m of data.meshes) {
           if (viewer._subCache[m.name]) { viewer._subCache[m.name].userData.edges?.dispose(); viewer._subCache[m.name].dispose(); }
           viewer.setSubGeometry(m.name, m);
-          cacheVersion[m.name] = genVersion;
+          cacheHash[m.name] = hashFor(m.name);
         }
         hideBusy();
         refreshView();
         if (data.ms && missingParts().length === 0) {
           setStatus(`${statusEl.textContent} · ${(data.ms / 1000).toFixed(1)} s`);
         }
+        dbg?.update({ ms: data.ms, hits: data.cache?.hits ?? 0, misses: data.cache?.misses ?? 0, skipped: lastGen.skipped, rebuilt: lastGen.rebuilt });
         maybeGenerate(); // active view may still need parts (tab switched during build)
         break;
       }
@@ -194,12 +279,22 @@ export function mount(part, { createWorker, container = document.getElementById(
   // Build whatever the active view is missing — automatic, no Generate button.
   function maybeGenerate() {
     if (!kernelReady || generating) return; // retried when the current build finishes
-    const missing = missingParts();
+    const needed = viewSubParts(part, view, params);
+    const missing = needed.filter((n) => !isCurrent(n));
     if (missing.length === 0) return;
     generating = true;
     genVersion = paramsVersion;
+    lastGen = { skipped: needed.length - missing.length, rebuilt: missing.length }; // for the overlay
     showBusy("generating");
-    service.generate({ type: "generate", subparts: missing, view, params }, backendFor());
+    service.generate({ type: "generate", subparts: missing, view, params, cache: cachingOn }, backendFor());
+  }
+
+  // Re-run the active view under the current caching setting, so toggling the
+  // ?debug switch updates the readout for the same design without a param change.
+  function forceRegen() {
+    for (const n of viewSubParts(part, view, params)) delete cacheHash[n];
+    refreshView();
+    maybeGenerate();
   }
 
   partSeg.addEventListener("click", (e) => {

package/src/framework/param-deps.js

@@ -48,3 +48,34 @@ export function relevantParamKeys(part, view, params) {
     return RELEVANT_ALL; // couldn't analyze — treat everything as relevant
   }
 }
+
+// Per-sub-part version of relevantParamKeys: which raw params each ON-SCREEN
+// sub-part of the active view reads. Used by Layer 1 (mount.js) to skip
+// regenerating sub-parts whose inputs are unchanged. Errs to RELEVANT_ALL on any
+// analysis failure (caller then treats every param as relevant — safe, just slower).
+export function subPartReadKeys(part, view, params) {
+  try {
+    const deriveInputs = new Set();
+    const derived = part.derive ? (part.derive(recorder(params, deriveInputs)) ?? {}) : {};
+    const { kernel } = createProbeKernel();
+    const map = new Map();
+    for (const name of viewSubParts(part, view, params)) {
+      const sp = part.parts[name];
+      const reads = new Set();
+      const dSeen = new Set();
+      if (sp.enabled) sp.enabled(recorder(params, reads)); // gate params change presence too
+      sp.build(kernel, recorder(params, reads), recorder(derived, dSeen));
+      if (dSeen.size > 0) for (const k of deriveInputs) reads.add(k);
+      map.set(name, reads);
+    }
+    return map;
+  } catch {
+    return RELEVANT_ALL;
+  }
+}
+
+// Stable string of the given param keys' current values — the cache-validity key
+// for one sub-part. Sorted so key order never affects the result.
+export function relevanceHash(keys, params) {
+  return JSON.stringify(keys.slice().sort().map((k) => [k, params[k]]));
+}

package/src/framework/pick-request/batch.js

@@ -0,0 +1,42 @@
+// Pure state machine for one batch of click requests: ordered prompts in,
+// ordered picks out. No http, no DOM, no timers (the server owns the clock).
+import { randomUUID } from "node:crypto";
+
+export function createBatch(prompts) {
+  return { id: randomUUID(), prompts: [...prompts], picks: [], index: 0, status: "collecting" };
+}
+
+export function view(batch) {
+  const collecting = batch.status === "collecting";
+  return {
+    id: batch.id,
+    index: batch.index,
+    total: batch.prompts.length,
+    prompt: collecting ? batch.prompts[batch.index] : null,
+    status: batch.status,
+  };
+}
+
+// Record a click for the current step. Ignores a non-collecting batch or an index
+// that isn't the one we're waiting on (stale/duplicate click guard).
+export function resolve(batch, index, selection) {
+  if (batch.status !== "collecting" || index !== batch.index) return batch;
+  batch.picks.push({ prompt: batch.prompts[batch.index], selection });
+  batch.index += 1;
+  if (batch.index >= batch.prompts.length) batch.status = "done";
+  return batch;
+}
+
+export function cancel(batch) {
+  if (batch.status === "collecting") batch.status = "cancelled";
+  return batch;
+}
+
+export function timeout(batch) {
+  if (batch.status === "collecting") batch.status = "timeout";
+  return batch;
+}
+
+export function result(batch) {
+  return { status: batch.status, picks: batch.picks };
+}

package/src/framework/pick-request/client.js

@@ -0,0 +1,100 @@
+// Browser side of request-a-pick: subscribe to the pick-server, show a prompt banner,
+// arm the existing picker on demand, and POST each click back. Self-created DOM; the
+// look (position, theme colours, slide-in animation) lives in app.css (#pf-pick-banner),
+// so it follows the app's light/dark theme. Visibility is toggled via display.
+import { attachPicker } from "../selection/pick.js";
+
+export function createPickRequestClient({ serverUrl = "http://127.0.0.1:4518", viewer, part, getContext }) {
+  let active = null; // { id, index } of the prompt we're waiting on
+
+  // --- prompt banner: chat-style (avatar + message) ---------------------------
+  const banner = document.createElement("div");
+  banner.id = "pf-pick-banner";
+  banner.style.display = "none";
+
+  const row = document.createElement("div");
+  row.className = "pf-pick-row";
+  const avatar = document.createElement("div");
+  avatar.className = "pf-pick-avatar";
+  avatar.textContent = "🤖";
+  const msg = document.createElement("div");
+  msg.className = "pf-pick-msg";
+  const label = document.createElement("div");
+  label.className = "pf-pick-label";
+  const prompt = document.createElement("div");
+  prompt.className = "pf-pick-prompt";
+  msg.append(label, prompt);
+  row.append(avatar, msg);
+
+  const close = document.createElement("button");
+  close.id = "pf-pick-close";
+  close.type = "button";
+  close.textContent = "×";
+  close.setAttribute("aria-label", "Dismiss");
+
+  banner.append(row, close);
+  document.body.appendChild(banner);
+
+  const show = () => { banner.style.display = "block"; };
+  const hide = () => { banner.style.display = "none"; };
+  const showError = (text) => { label.textContent = ""; prompt.textContent = text; show(); };
+
+  // Render a prompt as a chat message. The prompt text comes from the agent, so it goes
+  // through textContent (never innerHTML) to stay injection-safe.
+  const showPrompt = (v) => {
+    label.textContent = v.total > 1 ? `Your agent asks: (${v.index + 1} of ${v.total})` : "Your agent asks:";
+    prompt.textContent = v.prompt;
+    show();
+  };
+
+  const postJson = (path, body) =>
+    fetch(`${serverUrl}${path}`, {
+      method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+    }).catch(() => showError("⚠ couldn't reach pick-server — click not sent"));
+
+  const picker = attachPicker(viewer, {
+    part, getContext,
+    onPick: (selection) => {
+      if (!active) return;
+      postJson("/resolve", { id: active.id, index: active.index, selection });
+    },
+  });
+
+  // The × dismisses the request (cancels the active batch on the server) and hides the
+  // banner immediately for responsiveness.
+  close.addEventListener("click", () => {
+    if (active) postJson("/cancel", { id: active.id });
+    hide();
+  });
+
+  // --- dev test button: preview the banner locally, no agent round-trip -------
+  const test = document.createElement("button");
+  test.id = "pf-pick-test";
+  test.type = "button";
+  test.textContent = "🤖 test prompt";
+  test.title = "Preview the agent prompt banner (local, no agent)";
+  test.addEventListener("click", () => {
+    if (banner.style.display !== "none") { hide(); return; } // toggle off (and re-arm the animation)
+    showPrompt({ index: 0, total: 1, prompt: "Click a face — this is a test prompt" });
+  });
+  document.body.appendChild(test);
+
+  const es = new globalThis.EventSource(`${serverUrl}/events`);
+  es.addEventListener("prompt", (e) => {
+    const v = JSON.parse(e.data);
+    active = { id: v.id, index: v.index };
+    showPrompt(v);
+    picker.setActive(true);
+  });
+  es.addEventListener("cleared", () => {
+    active = null;
+    hide();
+    picker.setActive(false);
+  });
+  es.onerror = () => { showError("⚠ agent pick-server not reachable"); };
+  es.onopen = () => { if (!active) hide(); };
+
+  return {
+    detach: () => { es.close(); picker.detach(); banner.remove(); test.remove(); },
+  };
+}

package/src/framework/pick-request/index.js

@@ -0,0 +1 @@
+export { createPickRequestClient } from "./client.js";

package/src/framework/pick-request/server.js

@@ -0,0 +1,158 @@
+// src/framework/pick-request/server.js
+// The Node side of request-a-pick: an http+SSE server holding one active batch,
+// a blocking CLI client (requestPicks), and CLI output formatting. 127.0.0.1 only.
+import { createServer, request as httpRequest } from "node:http";
+import { createBatch, view, resolve, cancel, timeout, result } from "./batch.js";
+import { formatSelection } from "../selection/format.js";
+
+const json = (res, code, obj, origin) => {
+  res.writeHead(code, { "content-type": "application/json", "access-control-allow-origin": origin || "*" });
+  res.end(JSON.stringify(obj));
+};
+const readBody = (req) => new Promise((resolve_) => {
+  let b = "";
+  req.on("data", (c) => (b += c));
+  req.on("end", () => {
+    if (!b) { resolve_({}); return; }
+    try { resolve_(JSON.parse(b)); } catch { resolve_({ _parseError: true }); }
+  });
+});
+
+export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
+  let batch = null;        // the one active batch (or null)
+  let pending = null;      // { res, timer } — the held POST /request response
+  const sseClients = new Set();
+  const allSockets = new Set(); // track every socket for forceful teardown
+
+  const sse = (event, data) => {
+    for (const res of sseClients) res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  };
+  const finish = () => {                 // resolve the held /request with the result
+    if (pending) {
+      clearTimeout(pending.timer);
+      json(pending.res, 200, result(batch));
+      pending = null;
+    }
+    sse("cleared", {});
+    batch = null;
+  };
+
+  const server = createServer(async (req, res) => {
+    const origin = req.headers.origin;
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, {
+        "access-control-allow-origin": origin || "*",
+        "access-control-allow-methods": "GET,POST,OPTIONS",
+        "access-control-allow-headers": "content-type",
+      });
+      return res.end();
+    }
+    const url = req.url.split("?")[0];
+
+    if (req.method === "POST" && url === "/request") {
+      if (batch) return json(res, 409, { status: "busy" }, origin);
+      const body = await readBody(req);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
+      if (!Array.isArray(body.prompts) || body.prompts.length === 0) {
+        return json(res, 400, { error: "prompts must be a non-empty array" }, origin);
+      }
+      batch = createBatch(body.prompts);
+      pending = { res, timer: setTimeout(() => { timeout(batch); finish(); }, timeoutMs) };
+      sse("prompt", view(batch));
+      return; // held open until finish()
+    }
+    if (req.method === "GET" && url === "/events") {
+      res.writeHead(200, {
+        "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive",
+        "access-control-allow-origin": origin || "*",
+      });
+      res.write(": connected\n\n"); // SSE comment — flushes headers, makes fetch() resolve
+      sseClients.add(res);
+      if (batch) res.write(`event: prompt\ndata: ${JSON.stringify(view(batch))}\n\n`); // replay current
+      req.on("close", () => sseClients.delete(res));
+      return;
+    }
+    if (req.method === "POST" && url === "/resolve") {
+      const body = await readBody(req);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
+      const { id, index, selection } = body;
+      if (batch && id === batch.id) {
+        resolve(batch, index, selection);
+        if (view(batch).status === "collecting") sse("prompt", view(batch));
+        else finish();
+      }
+      return json(res, 200, { ok: true }, origin);
+    }
+    if (req.method === "POST" && url === "/cancel") {
+      const body = await readBody(req);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
+      const { id } = body;
+      if (batch && id === batch.id) { cancel(batch); finish(); }
+      return json(res, 200, { ok: true }, origin);
+    }
+    return json(res, 404, { error: "not found" }, origin);
+  });
+
+  server.on("connection", (socket) => {
+    allSockets.add(socket);
+    socket.on("close", () => allSockets.delete(socket));
+  });
+
+  return {
+    start: () => new Promise((res_) => server.listen(port, "127.0.0.1", () => res_({ port: server.address().port }))),
+    stop: () => new Promise((res_) => {
+      // If a batch is active, cancel it and resolve the held /request cleanly
+      // so any awaiting requestPicks() gets a result instead of a socket hang-up.
+      if (batch) { cancel(batch); finish(); }
+      for (const c of sseClients) c.end();
+      server.close(() => res_());
+      // destroy any lingering sockets (SSE keep-alive) so server.close resolves
+      for (const s of allSockets) s.destroy();
+    }),
+  };
+}
+
+// CLI client: POST the prompts and await the held response (blocks until the batch
+// reaches a terminal status server-side). Fails fast with a hint if nothing answers.
+export function requestPicks({ port = 4518, host = "127.0.0.1", prompts }) {
+  return new Promise((resolve_, reject) => {
+    const payload = JSON.stringify({ prompts });
+    const req = httpRequest(
+      { host, port, path: "/request", method: "POST", headers: { "content-type": "application/json", "content-length": Buffer.byteLength(payload) } },
+      (res) => {
+        let b = "";
+        res.on("data", (c) => (b += c));
+        res.on("end", () => {
+          try {
+            resolve_(JSON.parse(b));
+          } catch {
+            reject(new Error(`unexpected response from pick-server on ${host}:${port} (is the app open and \`partforge pick-serve\` running?)`));
+          }
+        });
+      },
+    );
+    req.on("error", (e) => reject(new Error(`could not reach pick-server on ${host}:${port} (is the app open and \`partforge pick-serve\` running?) — ${e.message}`)));
+    req.end(payload);
+  });
+}
+
+// Human-readable CLI output: one summary line per pick, then the raw JSON to parse.
+export function formatPickResult({ status, picks }) {
+  const safePicks = Array.isArray(picks) ? picks : [];
+  const lines = [`status: ${status} (${safePicks.length} pick${safePicks.length === 1 ? "" : "s"})`];
+  for (const { prompt, selection } of safePicks) {
+    let summary;
+    try {
+      if (selection && selection.point && selection.normal && selection.params) {
+        summary = formatSelection(selection, { style: "prompt" });
+      } else {
+        summary = selection?.subPart ?? JSON.stringify(selection);
+      }
+    } catch {
+      summary = JSON.stringify(selection);
+    }
+    lines.push(`• "${prompt}" → ${summary}`);
+  }
+  lines.push("", JSON.stringify({ status, picks }, null, 2));
+  return lines.join("\n");
+}

package/src/framework/selection/format.js

@@ -0,0 +1,31 @@
+// Pure serializer. No three.js, no DOM. Three styles for the same Selection:
+//   token  — compact clipboard/CLI line
+//   json   — the structured object (embedded tool-call transport)
+//   prompt — one natural-language sentence an LLM ingests well
+const AXIS_LABEL = { "1,0,0": "+X", "-1,0,0": "-X", "0,1,0": "+Y", "0,-1,0": "-Y", "0,0,1": "+Z", "0,0,-1": "-Z" };
+
+const fmtNormal = (n) => AXIS_LABEL[n.join(",")] ?? n.join(",");
+const fmtParams = (p) => Object.entries(p).map(([k, v]) => `${k}:${v}`).join(",");
+
+function tokenStyle(s) {
+  const head = `@${s.subPart}`;
+  const feat = s.feature
+    ? ` · ${s.feature.kind === "cylinder"
+        ? `cyl-face r=${s.feature.radius} axis=${s.feature.axis}`
+        : `${s.feature.kind}-face`}`
+    : "";
+  return `${head}${feat} · pt(${s.point.join(",")}) n(${fmtNormal(s.normal)}) · {${fmtParams(s.params)}}`;
+}
+
+function promptStyle(s) {
+  const params = Object.entries(s.params).map(([k, v]) => `${k}: ${v}`).join(", ");
+  const feat = s.feature ? ` a ${s.feature.kind} face,` : "";
+  return `On sub-part **${s.subPart}**, the user pointed at${feat} local point (${s.point.join(", ")}), `
+    + `normal ${fmtNormal(s.normal)}, with params {${params}}.`;
+}
+
+export function formatSelection(selection, { style = "token" } = {}) {
+  if (style === "json") return selection;
+  if (style === "prompt") return promptStyle(selection);
+  return tokenStyle(selection);
+}

package/src/framework/selection/index.js

@@ -0,0 +1,5 @@
+// Public surface for the click-to-select module. The future agent harness depends
+// only on attachPicker's onPick callback + the Selection contract — nothing else.
+export { resolveSelection, quantizePoint, snapNormal } from "./resolve.js";
+export { formatSelection } from "./format.js";
+export { attachPicker, worldToSubPartLocal } from "./pick.js";

package/src/framework/selection/pick.js

@@ -0,0 +1,48 @@
+// Viewer adapter — the ONLY three.js/DOM-aware file in the selection module.
+// Raycasts a click against the visible sub-meshes, converts the hit to the
+// sub-part's local CAD frame, and hands a resolved Selection to onPick.
+import * as THREE from "three";
+import { resolveSelection } from "./resolve.js";
+
+// Invert the mesh's world transform (pivot rotation + per-view recentring) to recover
+// shared-frame CAD coords — the same frame build() models in.
+export function worldToSubPartLocal(mesh, world) {
+  const v = Array.isArray(world) ? new THREE.Vector3(world[0], world[1], world[2]) : world.clone();
+  mesh.worldToLocal(v);
+  return [v.x, v.y, v.z];
+}
+
+export function attachPicker(viewer, { part, getContext, onPick }) {
+  const raycaster = new THREE.Raycaster();
+  const ndc = new THREE.Vector2();
+  let active = false;
+
+  function onClick(ev) {
+    if (!active) return;
+    const rect = viewer.domElement.getBoundingClientRect();
+    ndc.x = ((ev.clientX - rect.left) / rect.width) * 2 - 1;
+    ndc.y = -((ev.clientY - rect.top) / rect.height) * 2 + 1;
+    raycaster.setFromCamera(ndc, viewer.camera);
+
+    const meshes = Object.values(viewer._subMeshes).filter((m) => m.visible);
+    const hit = raycaster.intersectObjects(meshes, false)[0];
+    if (!hit) return;
+
+    const selection = resolveSelection(part, getContext(), {
+      subPart: hit.object.name,
+      pointLocal: worldToSubPartLocal(hit.object, hit.point),
+      // face.normal is in the geometry's local frame, which equals the CAD frame here
+      // (the mesh carries no local transform; only its parents rotate/recentre).
+      normalLocal: hit.face ? [hit.face.normal.x, hit.face.normal.y, hit.face.normal.z] : [0, 0, 0],
+      // hit.face metadata (kind/axis/radius) is the L1 increment — not populated yet.
+    });
+    viewer.flashPoint([hit.point.x, hit.point.y, hit.point.z]);
+    onPick(selection);
+  }
+
+  viewer.domElement.addEventListener("click", onClick);
+  return {
+    setActive: (on) => { active = !!on; },
+    detach: () => viewer.domElement.removeEventListener("click", onClick),
+  };
+}