partforge 0.41.0 → 0.45.0

package/src/framework/mount.js

@@ -11,24 +11,36 @@ import { buildControls } from "./controls.js";
 import { relevantParamKeys } from "./param-deps.js";
 import { createMeshCache } from "./mesh-cache.js";
 import { createGeometryService } from "./geometry-service.js";
-import { viewSubParts } from "./jobs.js";
+import { viewSubParts } from "./part-model.js";
 import { resolveDerived } from "./derive.js";
-import { detectBackend } from "./geometry/probe.js";
+import { detectBackend } from "./backend-select.js";
 import { createDebugOverlay } from "./debug-overlay.js";
 import { createRegenLoop } from "./regen-loop.js";
 import { createPoseFastPath } from "./pose-fast-path.js";
 import { createStatusUi } from "./status-ui.js";
 import { createViewTabs } from "./view-tabs.js";
 import { attachPickToggle, attachHoverLabels, attachPicker, formatSelection } from "./selection/index.js";
-import { createPickRequestClient } from "./pick-request/index.js";
+import { createPickRequestClient, resolvePickServerUrl, PICK_SERVER_DEFAULT_URL } from "./pick-request/index.js";
 import { exportablePartNames, partLabel } from "./export-select.js";
-import { createExportController } from "./export-controller.js";
+import { createExportController, backendForFormat } from "./export-controller.js";
+import { createCaptureBuild } from "./capture-build.js";
+import { attachAnimationControls } from "./animation-controls.js";
+import { resolveDefaultView } from "./default-view.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView }) {
   return {
     ready, dispose, setParams,
+    // Part-declared animation playback (spec 2026-08-02): null when the part
+    // declares no animations. { play(name?), pause(), seek(t), stop(), state() }.
+    animation: animation ?? null,
+    // Active view name (never null once mounted). See onViewChange for the push side.
+    getView,
+    // Programmatic tab switch; false for a name the part doesn't declare.
+    setView,
+    // Offscreen render of a named view (default when omitted, or on an unknown name).
+    captureView,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
     captureCurrent: (opts) => viewer.captureCurrent(opts),
     // Park/unpark the viewer: stops the render loop and frees the drawing
@@ -78,10 +90,17 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.41.0):
-//   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload });
+// Embedding contract (0.45.0):
+//   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload, onViewChange });
 //   await runtime.ready;   // first successful build of the default view
 //   runtime.setParams({ openAngle: 45 }); // programmatic edit; pose-only changes apply instantly
+//   runtime.getView();     // active view name (string), never null once mounted
+//   runtime.setView("lid");       // switch tab programmatically; returns false (and leaves the
+//                                 // active tab untouched) for a name the part doesn't declare
+//   await runtime.captureView();  // JPEG data URL of the DEFAULT view rendered offscreen (pass
+//                                 // a name for a specific view, falling back to the default for
+//                                 // an unknown one), never disturbing the active tab or the live
+//                                 // scene; null on failure (never throws)
 //   runtime.captureCurrent({ size: 2048 });  // one offscreen render of the user's current
 //                                         // framing (live camera pose + viewport aspect) at the
 //                                         // given long-edge resolution → JPEG data URL, or null
@@ -103,16 +122,27 @@ function createCleanupStack() {
 //                                 // loop would otherwise render a hidden pane forever.
 //                                 // Captures still work while parked (they re-allocate).
 //                                 // setActive(true) restores it. Safe after dispose().
+//   runtime.animation?.play("open");  // part-declared animation playback: null when the
+//                                 // part declares no animations, else
+//                                 // { play(name?), pause(), seek(t), stop(), state() }.
+//                                 // play() with an unknown name warns and does nothing;
+//                                 // any user/host param edit pauses playback. A part's
+//                                 // `autoplay: true` animation self-starts on first show
+//                                 // and each view switch until the user touches the
+//                                 // transport — no runtime call needed for that part.
 //   const off = runtime.onContextLost(() => …);  // WebGL context loss, i.e. the GPU or the
 //                                 // OS gave up — surface it rather than showing a dead
 //                                 // canvas. Returns an unsubscribe.
 //   runtime.dispose();     // full teardown
 // onBuild fires per completed build, so it does NOT fire for a pose-only edit —
 // those are repaired in the viewer and produce no build at all.
+// onViewChange fires once synchronously during mount with the initial resolved
+// view (before ready), then again on every subsequent view change (user click
+// or a programmatic setView) — always the new view name.
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
-export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange,
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -139,7 +169,6 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       threeMf: elements.exports?.threeMf ?? byId("download-3mf"),
     },
     chrome: {
-      pause: elements.chrome?.pause ?? byId("pause"),
       reframe: elements.chrome?.reframe ?? byId("reframe"),
       theme: elements.chrome?.theme ?? byId("theme"),
       cutaway: elements.chrome?.cutaway ?? byId("cutaway"),
@@ -203,10 +232,16 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // View tabs (generated from part.views) + live params. A tab switch shows the
     // cached assembly instantly if it's current, else auto-builds what's missing.
     const tabsCtl = createViewTabs(els.tabs, part, {
-      onChange: () => { pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); },
+      onChange: (name) => {
+        pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); animCtl?.autoplayKick();
+        onViewChange?.(name);
+      },
     });
     cleanup.defer(() => tabsCtl.detach());
     const view = () => tabsCtl.current();
+    // Tell the embedder the starting tab exactly once, synchronously, so a host
+    // (partforge-cloud) never has to poll getView() to learn where we opened.
+    onViewChange?.(tabsCtl.current());
     const params = { ...part.defaults };
 
     // Current selection context for the pickers: the active view + live params +
@@ -240,10 +275,17 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       cleanup.defer(() => pickToggle.detach());
     } else if (qs.has("pickserver")) {
       // Agent-driven mode: arm the picker only when the local pick-server asks for a
-      // click. `?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";
-      pickClient = createPickRequestClient({ serverUrl, viewer, part, getContext });
+      // click. `?pickserver&picktoken=<token>` or `?pickserver=http://host:port&picktoken=…`.
+      // The URL is attacker-suppliable (anyone can hand the user a link), so a
+      // non-loopback target is refused rather than honoured — otherwise every click,
+      // with its live parameter values, would stream to a remote host.
+      const serverUrl = resolvePickServerUrl(qs.get("pickserver"), {
+        onReject: (raw) => console.warn(
+          `partforge: ignoring non-loopback ?pickserver=${raw} — using ${PICK_SERVER_DEFAULT_URL}`,
+        ),
+      });
+      const token = qs.get("picktoken") || "";
+      pickClient = createPickRequestClient({ serverUrl, token, viewer, part, getContext });
       cleanup.defer(() => pickClient.detach());
     }
 
@@ -282,9 +324,18 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       params, getView: view, getParamsVersion: () => loop.version(),
     });
 
+    // paramsVersion of the most recent animation-frame apply. It is what lets
+    // the meshes handler tell "stale because playback moved on" (show it — that
+    // IS best-effort playback) from "stale because the user edited" (discard).
+    let lastAnimApplyVersion = -1;
+
     // First-build readiness: resolves on the first accepted meshes result, rejects on
     // a first-build error. Guarded against unhandled rejection when never awaited.
     let readySettled = false;
+    // First-show autoplay latch: separate from `readySettled`, which the error
+    // branch also settles — a part whose first build fails but whose retry
+    // succeeds still deserves its autoplay.
+    let autoplayKicked = false;
     let resolveReady, rejectReady;
     const ready = new Promise((res, rej) => { resolveReady = res; rejectReady = rej; });
     ready.catch(() => {});
@@ -337,6 +388,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     function onWorkerMessage({ data }) {
       // Headless exportParts() correlation: consume its own replies first.
       if (exportCtl.handleMessage(data, onDownload)) return;
+      // captureView's off-loop build channel: consume its replies before the
+      // live `meshes` case — capture-meshes must never touch live cache/display.
+      if (captureBuild.handleMessage(data)) return;
       switch (data.type) {
         case "ready":
           loop.ready(); // auto-build the default view (keeps the busy spinner up)
@@ -346,7 +400,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
           ui.setStatus(`${data.phase}…`);
           break;
         case "meshes": {
-          if (loop.buildDone()) { // stale results (params changed mid-build) are discarded
+          const fresh = loop.buildDone();
+          if (fresh) { // stale results (params changed mid-build) are discarded
             for (const m of data.meshes) {
               viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
               cache.record(m.name);
@@ -363,6 +418,26 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
             dbg?.update({ ms: data.ms, hits: data.cache?.hits ?? 0, misses: data.cache?.misses ?? 0, skipped: lastGen.skipped, rebuilt: lastGen.rebuilt, posed: lastGen.posed });
             onBuild?.({ status: "success", ms: data.ms });
             if (!readySettled) { readySettled = true; resolveReady(); }
+            // First-show autoplay: latched separately from `ready`, which the
+            // error branch also settles — a part whose first build fails but
+            // whose retry succeeds still deserves its autoplay.
+            if (!autoplayKicked) { autoplayKicked = true; animCtl?.autoplayKick(); }
+          } else if (lastAnimApplyVersion === loop.version()) {
+            // Stale ONLY because animation frames kept bumping the version:
+            // show the delivered meshes anyway — that IS best-effort playback —
+            // but record NOTHING. Cache and fast-path stamps must describe
+            // geometry built at the live params, and this delivery wasn't; the
+            // fast-path stamp is dropped too, so a later pose-only repair can
+            // never re-pose this newer geometry off an older delivery's stamp.
+            // A user edit mid-play pauses playback and bumps the version WITHOUT
+            // touching lastAnimApplyVersion, so a genuinely user-stale result
+            // fails this test and is discarded exactly as before.
+            for (const m of data.meshes) {
+              viewer.setSubGeometry(m.name, m);
+              fastPath.forget(m.name);
+            }
+            ui.hideBusy();
+            refreshView();
           }
           loop.kick(); // stale → rebuild; fresh → the view may still need parts (tab switched mid-build)
           break;
@@ -396,6 +471,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     const service = createGeometryService({ createWorker, onMessage: onWorkerMessage });
     cleanup.defer(() => service.terminate());
 
+    const captureBuild = createCaptureBuild({ send: (msg, backend) => service.send(msg, backend) });
+    cleanup.defer(() => captureBuild.dispose());
+
     const exportCtl = createExportController({
       send: (msg, backend) => service.send(msg, backend),
       currentView: () => view(),
@@ -405,7 +483,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     });
     cleanup.defer(() => exportCtl.dispose("viewer disposed"));
 
-    const panel = buildControls(els.controls, part.parameters, params, onParamChange);
+    let animCtl = null; // assigned below; panel edits must pause active playback
+    const panel = buildControls(els.controls, part.parameters, params, () => {
+      animCtl?.notifyUserEdit();
+      onParamChange();
+    });
     cleanup.defer(() => panel.dispose());
     const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view(), params));
     updateRelevance(); // initial view
@@ -414,8 +496,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // forceRegen path: forceRegen() forgets cache stamps WITHOUT bumping the params
     // version, so a repair there would re-stamp everything current off the memoized
     // probe and the forced rebuild would silently no-op.
-    function onParamChange() {
-      loop.markDirty(); // bump the version first: refreshView below must see the parts as stale
+    function onParamChange({ debounce = true } = {}) {
+      loop.markDirty({ debounce }); // bump the version first: refreshView below must see the parts as stale
       // Pose-only edits: re-posed + re-stamped current, no job. Skipped entirely
       // when caching is off — ?debug&nocache is there to measure true uncached
       // rebuilds, which the fast path would otherwise hide.
@@ -432,11 +514,33 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // path as a slider edit: pose-only changes repair synchronously (no worker
     // job, no debounce); geometry changes fall through to the regen loop.
     function setParams(partial) {
+      animCtl?.notifyUserEdit();
       Object.assign(params, partial);
       panel.syncValues(Object.keys(partial));
       onParamChange();
     }
 
+    // Animation-frame param entry point: same change path as setParams, minus
+    // the regen debounce. The explicit kick after repair is what makes playback
+    // best-effort — a pose-only frame finds nothing missing (repair re-stamped
+    // it) and sends no job; a geometry frame dispatches immediately when the
+    // worker is idle and is otherwise absorbed until buildDone re-kicks.
+    function applyAnimationValues(values) {
+      Object.assign(params, values);
+      panel.syncValues(Object.keys(values));
+      onParamChange({ debounce: false });
+      lastAnimApplyVersion = loop.version(); // this version came from playback, not a user edit
+      loop.kick();
+    }
+
+    // Animation transport + driver (no-op null when the part declares none).
+    animCtl = attachAnimationControls(viewer, part, {
+      container: els.viewer,
+      applyValues: applyAnimationValues,
+      getParamValues: (keys) => Object.fromEntries(keys.map((k) => [k, params[k]])),
+    });
+    if (animCtl) cleanup.defer(() => animCtl.detach());
+
     // 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() {
@@ -457,7 +561,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
 
     const onStepClick = () => {
       ui.showBusy("exporting STEP");
-      service.send({ type: "export-step", view: view(), params }, "occt"); // STEP is always OCCT
+      service.send({ type: "export-step", view: view(), params }, backendForFormat("step", backendFor));
     };
     if (els.exports.step) {
       els.exports.step.addEventListener("click", onStepClick);
@@ -473,7 +577,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       cleanup.defer(() => els.exports.threeMf.removeEventListener("click", on3mfClick));
     }
 
-    // Optional host-page viewer chrome (pause / reframe / theme) + camera persistence.
+    // Optional host-page viewer chrome (reframe / theme) + camera persistence.
     const chrome = attachViewerControls(viewer, els.chrome, { tooltip });
     cleanup.defer(() => chrome.detach());
 
@@ -484,12 +588,35 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       cleanup.dispose();
     }
 
+    // Off-loop offscreen thumbnail: builds `viewName` (or the part's resolved
+    // default when omitted/unknown) via captureBuild's correlated channel, then
+    // renders it in a throwaway scene via viewer.renderMeshPayloads. Never
+    // touches the active tab, getView(), or the live scene — best-effort: any
+    // failure, including a resolved-null from a worker build failure (4A
+    // settles rather than throwing), returns null.
+    const captureView = async (viewName, opts = {}) => {
+      try {
+        const target = (viewName && part.views?.[viewName]) ? viewName : resolveDefaultView(part);
+        const subparts = viewSubParts(part, target, params);
+        if (!subparts.length) return null;
+        const meshes = await captureBuild.request({ subparts, view: target, params, backend: backendFor() });
+        if (!meshes || !meshes.length) return null; // 4A resolves null on a worker build failure
+        return viewer.renderMeshPayloads(meshes, { size: 640, quality: 0.8, angle: "iso", ...opts });
+      } catch {
+        return null; // best-effort: a failed thumbnail never breaks the caller
+      }
+    };
+
     return makeHandle({
       ready, dispose, viewer, setParams,
       setHostPane: paneTabs.setHostPane,
+      getView: view,                         // () => tabsCtl.current()
+      setView: (name) => tabsCtl.select(name),
+      captureView,
       listExportableParts: () =>
         exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
       exportParts: (opts) => exportCtl.exportParts(opts),
+      animation: animCtl?.runtime ?? null,
     });
   } catch (error) {
     try {

package/src/{testing → framework/oracle}/build.js

@@ -1,4 +1,4 @@
-import { viewSubParts, resolveParams, buildPosed } from "../framework/jobs.js";
+import { viewSubParts, resolveParams, buildPosed } from "../part-model.js";
 
 // Build every sub-part of a view in its display (assembly) pose with the given
 // Manifold kernel, returning live solids + copied-out meshes. Mirrors the

package/src/{testing → framework/oracle}/bvh.js

@@ -1,4 +1,4 @@
-// src/testing/bvh.js
+// src/framework/oracle/bvh.js
 // Triangle BVH over a mesh in either Manifold non-indexed soup form (9 floats per
 // triangle, no `indices`) or OCCT indexed form (`positions` = 3 floats/vertex +
 // `indices` = 3 vertex-indices/triangle). A reusable spatial index: nearest ray hit

package/src/{testing → framework/oracle}/measure.js

@@ -1,6 +1,6 @@
 import { buildView } from "./build.js";
 import { cachedBVH } from "./bvh.js";
-import { assemblyOverlaps } from "../framework/assembly.js";
+import { assemblyOverlaps } from "../assembly.js";
 import { meshGaps, pairKey, CONTACT_EPS, GAP_THRESHOLD } from "./gaps.js";
 import { bounds, meshArea, meshCentroid } from "./mesh.js";
 import { minWall } from "./min-wall.js";

package/src/{testing → framework/oracle}/min-wall.js

@@ -1,4 +1,4 @@
-// src/testing/min-wall.js
+// src/framework/oracle/min-wall.js
 // Min wall thickness by ray/shot on a triangle BVH (see the spec's spike: this beat the
 // voxel/SDF approach on both accuracy and speed). For each surface triangle, cast a ray
 // inward (reverse of its outward normal) from the centroid; the nearest hit is the local

package/src/{testing → framework/oracle}/verify.js

@@ -3,9 +3,9 @@ import { measure as defaultMeasure } from "./measure.js";
 import { pairKey, CONTACT_EPS } from "./gaps.js";
 import { resolveProfile } from "./dfm-profiles.js";
 import { expandCases } from "./cases.js";
-import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "../framework/param-deps.js";
-import { resolveParams } from "../framework/jobs.js";
-import { SUBPART_METRICS, VIEW_METRICS } from "../framework/verify-metrics.js";
+import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "../param-deps.js";
+import { resolveParams } from "../part-model.js";
+import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
 
 // Re-exported for backwards compatibility: the registries moved to framework/ so
 // the linter can read the metric vocabulary without importing a geometry kernel.

package/src/framework/param-deps.js

@@ -3,7 +3,7 @@
 // affect what's visible. Pure — no DOM, no real geometry (reuses the geometry-free
 // probe kernel). Errs toward RELEVANT_ALL whenever it can't analyze a build.
 import { createProbeKernel } from "./geometry/probe.js";
-import { viewSubParts } from "./jobs.js";
+import { viewSubParts } from "./part-model.js";
 import { resolveDerived } from "./derive.js";
 
 export const RELEVANT_ALL = Symbol("relevant-all");

package/src/framework/part-model.js

@@ -0,0 +1,48 @@
+// The pure part model: which sub-parts a view shows, which of those are exportable,
+// how a part's params resolve, and how one posed sub-part solid is built. No async,
+// no worker protocol, no kernel boot — just synchronous functions over a
+// PartDefinition, a kernel handle, and params.
+//
+// Deliberately a LEAF of the framework graph. buildPosed is the single definition of
+// "a posed sub-part solid", so the worker job loop (jobs.js), the collision check
+// (assembly.js), the relevance probe (param-deps.js), and the headless oracle
+// (oracle/) all call it. Keeping those four functions out of jobs.js — which is
+// async, imports the kernels, and pulls in the whole export stack — is what lets the
+// oracle depend on the part model without an import cycle back through the job loop.
+import { resolveDerived } from "./derive.js";
+
+// Names of the sub-parts a view shows: declared in the view and enabled for these
+// params. Order follows Object.keys(part.parts) (definition order).
+export function viewSubParts(part, view, params) {
+  return Object.keys(part.parts).filter((name) => {
+    const sp = part.parts[name];
+    const inView = sp.views.includes(view);
+    const on = sp.enabled ? !!sp.enabled(params) : true;
+    return inView && on;
+  });
+}
+
+// Sub-parts to include in an EXPORT of this view: the visible sub-parts, minus any
+// flagged `exportable: false` (reference/preview-only parts — motor ghosts, bearing
+// placeholders, etc.). They still show in the viewer; they're just never written to
+// an STL/STEP/3MF file, so the user never has to toggle them off before exporting.
+export function exportSubParts(part, view, params) {
+  return viewSubParts(part, view, params).filter((name) => part.parts[name].exportable !== false);
+}
+
+// Resolve a part's effective params + derived values for a build: the user's params
+// layered over the part defaults, and derive() run once over the result.
+export function resolveParams(part, params) {
+  const p = { ...part.defaults, ...params };
+  return { p, d: resolveDerived(part, p) };
+}
+
+// Build one sub-part and apply its optional place() for the given purpose/view.
+// `p`/`d` come from resolveParams(). This is the SINGLE definition of "a posed
+// sub-part solid" — the worker, the collision check, and the test harness all call
+// it, so display/export poses can never drift between the app and its tests.
+export function buildPosed(kernel, part, name, { purpose, view, p, d, onProgress } = {}) {
+  const sp = part.parts[name];
+  const solid = sp.build(kernel, p, d, onProgress);
+  return sp.place ? sp.place(solid, { view, purpose, p, d }) : solid;
+}

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

@@ -4,18 +4,26 @@
 // user is working with an agent.
 import { createPromptBanner } from "./prompt-banner.js";
 import { formatSelection } from "../selection/format.js";
+import { PICK_SERVER_DEFAULT_URL } from "./endpoint.js";
 
-export function createPickRequestClient({ serverUrl = "http://127.0.0.1:4518", viewer, part, getContext }) {
+export function createPickRequestClient({ serverUrl = PICK_SERVER_DEFAULT_URL, token = "", viewer, part, getContext }) {
   let active = null; // { id, index } of the agent prompt we're waiting on
   const banner = createPromptBanner({ viewer, part, getContext });
 
+  // Every route on the pick-server is token-gated. POSTs carry it as a header;
+  // EventSource cannot set headers, so the stream carries it in the query string.
   const postJson = (path, body) =>
     fetch(`${serverUrl}${path}`, {
-      method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+      method: "POST",
+      headers: { "content-type": "application/json", ...(token ? { "x-pick-token": token } : {}) },
+      body: JSON.stringify(body),
     }).catch(() => banner.message("⚠ couldn't reach pick-server — click not sent"));
 
   // --- agent prompts over SSE -------------------------------------------------
-  const es = new globalThis.EventSource(`${serverUrl}/events`);
+  const eventsUrl = token
+    ? `${serverUrl}/events?token=${encodeURIComponent(token)}`
+    : `${serverUrl}/events`;
+  const es = new globalThis.EventSource(eventsUrl);
   es.addEventListener("prompt", (e) => {
     const v = JSON.parse(e.data);
     active = { id: v.id, index: v.index };

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

@@ -0,0 +1,60 @@
+// Shared constants + loopback checks for request-a-pick. Deliberately free of both
+// node: imports and DOM access: the browser client, mount.js, the Node server, and
+// the CLI all need these, and the browser side must never pull in node:http.
+//
+// Why loopback matters: the pick-server streams the agent's prompts and receives the
+// user's selection (including live parameter values). Both ends must be pinned to the
+// local machine — an arbitrary `?pickserver=https://evil.example` would ship every
+// click off-box, and an arbitrary reflected CORS origin would let any page the user
+// visits read the stream.
+export const PICK_SERVER_DEFAULT_PORT = 4518;
+export const PICK_SERVER_DEFAULT_TIMEOUT_MS = 120000;
+export const PICK_SERVER_DEFAULT_HOST = "127.0.0.1";
+export const PICK_SERVER_DEFAULT_URL = `http://${PICK_SERVER_DEFAULT_HOST}:${PICK_SERVER_DEFAULT_PORT}`;
+
+// The whole 127/8 block plus the IPv6 loopback and the `localhost` name. Anything
+// else (including 0.0.0.0 and names that merely resolve to 127.0.0.1) is rejected —
+// a DNS name is exactly the DNS-rebinding vector we are guarding against.
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "::1", "[::1]"]);
+const isLoopbackHostname = (h) =>
+  LOOPBACK_HOSTNAMES.has(h) || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+
+// `origin` is an HTTP Origin header value: scheme://host[:port], no path.
+export function isLoopbackOrigin(origin) {
+  if (typeof origin !== "string" || origin === "") return false;
+  let u;
+  try { u = new URL(origin); } catch { return false; }
+  if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+  return isLoopbackHostname(u.hostname);
+}
+
+// `host` is an HTTP Host header value: host[:port], no scheme. A Host that names
+// anything but loopback means the request arrived through a rebound DNS name.
+export function isLoopbackHost(host, port) {
+  if (typeof host !== "string" || host === "") return false;
+  let u;
+  try { u = new URL(`http://${host}`); } catch { return false; }
+  if (!isLoopbackHostname(u.hostname)) return false;
+  // An explicit port must be ours; a bare host means port 80, which we never bind.
+  return u.port !== "" && Number(u.port) === Number(port);
+}
+
+export function isLoopbackUrl(url) {
+  if (typeof url !== "string" || url === "") return false;
+  let u;
+  try { u = new URL(url); } catch { return false; }
+  if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+  return isLoopbackHostname(u.hostname);
+}
+
+// Normalise a user-supplied `?pickserver=` value to an origin we are willing to talk
+// to. Anything non-loopback falls back to the default and reports why, so a tampered
+// URL degrades to "talks to the local server" rather than "exfiltrates every click".
+export function resolvePickServerUrl(raw, { onReject } = {}) {
+  if (typeof raw !== "string" || raw === "") return PICK_SERVER_DEFAULT_URL;
+  if (!isLoopbackUrl(raw)) {
+    onReject?.(raw);
+    return PICK_SERVER_DEFAULT_URL;
+  }
+  return raw.replace(/\/+$/, ""); // paths are appended verbatim; no double slash
+}

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

@@ -1 +1,7 @@
 export { createPickRequestClient } from "./client.js";
+// Browser-safe half of the endpoint contract (no node: imports) — mount.js needs the
+// loopback check and the default URL, and must not reach into the Node server module.
+export {
+  resolvePickServerUrl, isLoopbackUrl,
+  PICK_SERVER_DEFAULT_PORT, PICK_SERVER_DEFAULT_URL,
+} from "./endpoint.js";