partforge 0.41.0 → 0.44.0

package/src/framework/lint/rules-place.js

@@ -0,0 +1,76 @@
+// Group 6 — the two place() invariants (docs/AUTHORING-PARTS.md "Display vs
+// export placement"), promoted from doc-only conventions to lint because the
+// animation system leans on place() for every pose-only track:
+//   1. Display placement must not depend on the active view (display meshes
+//      are cached across views; a view-dependent pose serves stale geometry).
+//   2. Display vs export may differ only by a rigid motion (translate/rotate).
+// Both checks run the geometry-free pose probe; an untrusted probe (query op /
+// function selector in build or place) proves nothing and stays silent — the
+// runtime declines the fast path for those sub-parts anyway.
+import { err } from "./finding.js";
+import { probeSubPartPose } from "../pose-probe-core.js";
+
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+
+// The sub-part names visible in a view at params p — restated locally (like
+// rules-schema.js restates controls.js's visibility predicates) rather than
+// imported from jobs.js, which would break the lint purity closure.
+function viewNames(part, view, p) {
+  return Object.entries(isPlainObject(part?.parts) ? part.parts : {})
+    .filter(([, sp]) => Array.isArray(sp?.views) && sp.views.includes(view))
+    .filter(([, sp]) => { try { return sp.enabled ? !!sp.enabled(p) : true; } catch { return false; } })
+    .map(([name]) => name);
+}
+
+const poseKey = (pose) => JSON.stringify(pose);
+
+export const PLACE_RULES = [
+  {
+    id: "view-dependent-display-place",
+    run: ({ part, p, d }) => {
+      const out = [];
+      const views = Object.keys(isPlainObject(part?.views) ? part.views : {});
+      if (views.length < 2) return out;
+      for (const [name, sp] of Object.entries(isPlainObject(part?.parts) ? part.parts : {})) {
+        const inViews = views.filter((v) => viewNames(part, v, p).includes(name));
+        if (inViews.length < 2) continue;
+        const probes = inViews.map((view) => probeSubPartPose(sp, { view, purpose: "display", p, d }));
+        if (probes.some((x) => !x.trusted)) continue;
+        const first = probes[0];
+        const differs = probes.some((x) => x.baseHash !== first.baseHash || poseKey(x.pose) !== poseKey(first.pose));
+        if (differs) {
+          out.push(err("view-dependent-display-place",
+            `sub-part "${name}" display placement differs between views (${inViews.join(", ")})`,
+            "Display meshes are built once per sub-part and cached across views, so a view-dependent display pose shows stale geometry after a tab switch. Only `place(..., { purpose: \"export\" })` may vary; keep the display branch view-independent.",
+            `parts.${name}.place`,
+            "view-dependent-display-place"));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "place-not-rigid",
+    run: ({ part, p, d }) => {
+      const out = [];
+      for (const [name, sp] of Object.entries(isPlainObject(part?.parts) ? part.parts : {})) {
+        if (!sp?.place) continue;
+        for (const view of Object.keys(isPlainObject(part?.views) ? part.views : {})) {
+          if (!viewNames(part, view, p).includes(name)) continue;
+          const display = probeSubPartPose(sp, { view, purpose: "display", p, d });
+          const exportP = probeSubPartPose(sp, { view, purpose: "export", p, d });
+          if (!display.trusted || !exportP.trusted) continue;
+          if (display.baseHash !== exportP.baseHash) {
+            out.push(err("place-not-rigid",
+              `sub-part "${name}" display and export placements differ by more than a rigid motion (view "${view}")`,
+              "place() may move a solid between purposes (translate/rotate) but never reshape it — a geometry op on one branch means the exported part is not the previewed part. Move the op into build().",
+              `parts.${name}.place`,
+              "place-not-rigid"));
+            break; // one finding per sub-part — further views add nothing
+          }
+        }
+      }
+      return out;
+    },
+  },
+];

package/src/framework/lint/rules-shape.js

@@ -83,4 +83,16 @@ export const SHAPE_RULES = [
           `views.${v}`));
     },
   },
+  {
+    id: "default-view-ambiguous",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.views)) return [];
+      const flagged = Object.keys(part.views).filter((v) => part.views[v]?.default === true);
+      if (flagged.length < 2) return [];
+      return [warn("default-view-ambiguous",
+        `${flagged.length} views set \`default: true\`: ${flagged.map((v) => `"${v}"`).join(", ")}`,
+        `Only one view can open by default. The viewer takes the first one declared — "${flagged[0]}" — and ignores the rest; remove \`default: true\` from the others.`,
+        `views.${flagged[1]}.default`)];
+    },
+  },
 ];

package/src/framework/lint/rules-verify.js

@@ -4,8 +4,8 @@
 // Catching them statically removes both the wasted boot and the stdout caveat.
 import { err } from "./finding.js";
 import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
-import { PROFILES } from "../../testing/dfm-profiles.js";
-import { parseAssertion } from "../../testing/assert-dsl.js";
+import { PROFILES } from "../oracle/dfm-profiles.js";
+import { parseAssertion } from "../oracle/assert-dsl.js";
 import { suggest } from "../geometry/op-options.js";
 
 // Resolve `expect` to a plain object. The function form (p, d) => ({…}) is invoked

package/src/framework/mount.js

@@ -11,24 +11,28 @@ 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 { attachAnimationControls } from "./animation-controls.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 }) {
   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,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
     captureCurrent: (opts) => viewer.captureCurrent(opts),
     // Park/unpark the viewer: stops the render loop and frees the drawing
@@ -78,7 +82,7 @@ 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):
+// Embedding contract (0.44.0):
 //   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload });
 //   await runtime.ready;   // first successful build of the default view
 //   runtime.setParams({ openAngle: 45 }); // programmatic edit; pose-only changes apply instantly
@@ -103,6 +107,14 @@ 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.
@@ -139,7 +151,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,7 +214,7 @@ 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: () => { pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); animCtl?.autoplayKick(); },
     });
     cleanup.defer(() => tabsCtl.detach());
     const view = () => tabsCtl.current();
@@ -240,10 +251,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 +300,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(() => {});
@@ -346,7 +373,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 +391,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;
@@ -405,7 +453,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 +466,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 +484,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 +531,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 +547,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());
 
@@ -490,6 +564,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       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";