@intentius/behold 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/behold",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "license": "Apache-2.0",
   "type": "module",
   "description": "behold — a live control plane on chant. See your whole estate (every substrate in one graph), coloured by drift; act through delegated, gated Ops.",

package/web/app.js

@@ -9,9 +9,12 @@
 // position), and the theme picker into the panel's View-tab slot (a stable element
 // renderPanelView never rewrites, so the select mounts once and survives re-renders).
 import { createRefreshQueue } from "./refresh-queue.js";
+import { readViewQuery, writeViewQuery, settleView, settlePlace, refusalLine } from "./view-url.js";
+import { readEmbed, selectMessage, viewFromMessage } from "./embed.js";
+import { gateCards } from "./workspace-gates.js";
 import { readCostLine } from "./read-cost.js";
 import { applyMemberFrame, pendingLine, stillPending } from "./pending.js";
-import { initTheme, mountThemePicker, readableOn, colorForCategory, onThemeChange, getTokens, getTheme, pinTokensFor } from "./theme.js";
+import { initTheme, setTheme, mountThemePicker, readableOn, colorForCategory, onThemeChange, getTokens, getTheme, pinTokensFor } from "./theme.js";
 // #399 M2 / #401 M4 of #397: the colour-by modes' arithmetic and the
 // provenance badge's wording — every decision the behaviour overlay makes,
 // pure and unit-tested beside the file. This module owns the fetches, the SVG
@@ -86,7 +89,13 @@ import { hasOperator, renderOperator, APPROVED_SEMANTICS } from "./operator.js";
 import { releaseRows } from "./release.js";
 import { comparisonRow, comparisonSummary } from "./cross-env.js";
 initTheme();
-initPanel();
+// #476: framed in a host pane. The flag is a class on <html>, so the CSS that
+// folds the chrome away needs no JS, and the theme is the host's for this
+// frame only.
+const embedOpts = readEmbed(location.search);
+if (embedOpts.theme && !setTheme(embedOpts.theme, { persist: false })) console.warn(`behold: no theme named ${embedOpts.theme}`);
+if (embedOpts.embed) document.documentElement.classList.add("embed");
+initPanel({ embed: embedOpts.embed });
 mountThemePicker(document.getElementById("panel-theme"));
 
 // Colour node fills by category/kind using the theme's FULL palette (spicypath-style, so the
@@ -116,6 +125,8 @@ try {
 } catch {
   /* private mode */
 }
+// #475: what a load with no `lens=` would paint, so the URL carries any other.
+let savedColourMode = colourMode;
 
 const COLOUR_MODE_TITLE = {
   drift: "Colour each card by what chant observed live — the overlay behold has always drawn",
@@ -140,6 +151,7 @@ function setColourMode(mode) {
   colourMode = mode;
   try {
     localStorage.setItem(COLOUR_STORE_KEY, mode);
+    savedColourMode = mode;
   } catch {
     /* private mode */
   }
@@ -1227,12 +1239,29 @@ function wire(ir) {
       host.querySelectorAll(".sel").forEach((n) => n.classList.remove("sel"));
       g.classList.add("sel");
       inspect(node);
+      noteSelection(node.id);
       // #254: in carve mode a click is also the walkthrough's Pick step — the
       // inspect pane already shows the score arithmetic the lens spelled out,
       // and the stepper picks up the same node.
       carvePick(node);
     });
   }
+  // #475/#476: a member's box picks the member. Only boxes that are members
+  // (a wave or a VPC box is not one), and only a click on the box itself, not
+  // on a card inside it or after a drag-pan.
+  const members = new Set(ir.nodes.map((n) => nodeMember(n.id)).filter(Boolean));
+  for (const rect of host.querySelectorAll("rect[data-group-id]")) {
+    const id = rect.getAttribute("data-group-id");
+    if (!members.has(id)) continue;
+    rect.addEventListener("click", (e) => {
+      if (panMoved || e.target !== rect) return;
+      host.querySelectorAll(".sel").forEach((n) => n.classList.remove("sel"));
+      selectedNodeId = null;
+      view.member = id;
+      renderStatusbar();
+      embedSelected(id, null);
+    });
+  }
 }
 
 // View state driven by the ⌘K palette's lens commands (#17, moved off the
@@ -1252,7 +1281,10 @@ function wire(ir) {
 // null on a project that declares no `stacks[]` at all — the picker (and the
 // status strip's stack tag) then never renders. Every fetch reads this, so
 // the `changed` SSE re-pull and a palette lens change go through the same path.
-const view = { env: null, detail: 2, components: true, logical: false, runtime: false, ops: false, tier: null, target: null, stack: null, radial: false, collapse: false, compareTo: null };
+// member (#475) is the estate member the view is on: a host opens behold with
+// ?member=, and picking a card or a member box moves it. It changes no fetch;
+// the graph is the whole estate, framed on that member's box.
+const view = { member: null, env: null, detail: 2, components: true, logical: false, runtime: false, ops: false, tier: null, target: null, stack: null, radial: false, collapse: false, compareTo: null };
 
 // #182: `components` is the boot default, but a project that declares no
 // components renders it as ZERO nodes — the first screen was a blank graph
@@ -2099,9 +2131,318 @@ function panelDotRow(color, main, tag, onClick) {
   return row;
 }
 
+// --- #475: the view in the URL -----------------------------------------------
+// The query is read once, at boot (openFromQuery), and written back with
+// history.replaceState from renderStatusbar(), which every view change already
+// runs through. member and node can only be checked once a graph is on screen,
+// so they wait in `pendingPlace` for the first paint (afterPaint). What the
+// link asked for and behold could not open is said on the now line.
+let pendingPlace = null;
+let urlRefusals = [];
+let selectedNodeId = null;
+
+let viewUrlReady = false; // nothing is written back until the link has been read
+function openFromQuery() {
+  viewUrlReady = true;
+  applyWantedView(readViewQuery(location.search));
+}
+
+/**
+ * Move the view to what a link or the host asked for. Values the estate can't
+ * honour are kept in `urlRefusals` for the now line; member and node wait in
+ * `pendingPlace` for a graph to check them against. Returns whether the
+ * fetch-shaping part of the view moved (a re-read is needed).
+ */
+function applyWantedView(want) {
+  if (!Object.keys(want).length) return false;
+  const before = fetchKey();
+  // env first: whether the runtime stop exists depends on it.
+  const first = settleView("env" in want ? { env: want.env } : {}, { envs: environments });
+  if ("env" in first.apply) view.env = first.apply.env;
+  const { env: _env, ...rest } = want;
+  const { apply, refused } = settleView(rest, {
+    zooms: availableZooms().map(([, z]) => z),
+    tiers,
+    lenses: COLOUR_MODES,
+  });
+  urlRefusals.push(...first.refused, ...refused);
+  if (apply.tier) view.tier = apply.tier;
+  if (apply.zoom) {
+    applyZoom(apply.zoom);
+    autoZoomFallback = false; // the link chose the zoom; an empty one is said, not swapped
+  }
+  if (apply.lens) colourMode = apply.lens; // not written to localStorage: the link's pick, not yours
+  if ("radial" in apply) view.radial = apply.radial;
+  if (want.member === null) {
+    view.member = null;
+    selectedNodeId = null;
+  }
+  if (apply.member && !apply.node && selectedNodeId && nodeMember(selectedNodeId) !== apply.member) {
+    // Another member, and no card named in it: the old pick goes.
+    selectedNodeId = null;
+    document.querySelectorAll("#graph .sel").forEach((n) => n.classList.remove("sel"));
+  }
+  if (apply.member || apply.node) pendingPlace = { member: apply.member || null, node: apply.node || null };
+  return fetchKey() !== before;
+}
+function fetchKey() {
+  return [view.env, zoomValue(), view.tier, view.radial].join("|");
+}
+
+// #476: the host moves the view with a `behold:view` message carrying the same
+// fields as the URL. Only from the host's origin (viewFromMessage).
+window.addEventListener("message", (e) => {
+  const want = viewFromMessage(e, embedOpts.host);
+  if (!want) return;
+  const lensBefore = colourMode;
+  if (applyWantedView(want)) {
+    resetDialCaches();
+    renderStatusbar();
+    load();
+    return;
+  }
+  if (colourMode !== lensBefore) recolorNodesByCategory();
+  if (pendingPlace && lastGraphIr) afterPaint(lastGraphIr);
+  else if (want.member === null) fitGraph();
+  const line = refusalLine(urlRefusals);
+  urlRefusals = [];
+  if (line) nowline(line);
+  renderStatusbar();
+});
+
+/** Tell the host what was picked: a card (member + node) or a member's box. */
+function embedSelected(member, node) {
+  if (embedOpts.embed && member) setInspectCollapsed(!node);
+  if (!embedOpts.host || window.parent === window) return;
+  try {
+    window.parent.postMessage(selectMessage(member, node), embedOpts.host);
+  } catch {
+    /* the parent went away */
+  }
+}
+
+// --- #477: a declared workspace's waiting gates --------------------------------
+// Read when the env changes and when the server says something moved (the
+// `changed` event, which a host's POST /api/refresh?notify=1 also sends).
+// Framed, the cards carry no button: the host approves (workspace-gates.js).
+let wsGates = { env: undefined, answer: null, seq: 0 };
+// ?gates=<env> (#477): the env the gate strip reads, apart from the graph's.
+// A host that opens behold on the source graph still wants the gates of the
+// env its block watches.
+const gatesEnvParam = new URLSearchParams(location.search).get("gates") || "";
+function gatesEnv() {
+  return gatesEnvParam || view.env || "";
+}
+function loadWorkspaceGates({ force = false } = {}) {
+  if (staticMode) return;
+  const env = gatesEnv();
+  if (!force && wsGates.env === env) return paintWorkspaceGates();
+  // Every read is numbered; only the newest one paints, so an answer for an
+  // env the view has left never lands under the one it moved to.
+  const seq = ++wsGates.seq;
+  wsGates.env = env;
+  fetch(`/api/workspace/gates${env ? `?env=${encodeURIComponent(env)}` : ""}`)
+    .then((r) => r.json())
+    .then((j) => {
+      if (seq === wsGates.seq) wsGates.answer = j;
+    })
+    .catch(() => {
+      if (seq === wsGates.seq) wsGates.answer = null;
+    })
+    .finally(() => {
+      if (seq === wsGates.seq) paintWorkspaceGates();
+    });
+}
+function paintWorkspaceGates() {
+  const host = document.getElementById("ws-gates");
+  if (!host) return;
+  const answer = wsGates.answer;
+  host.replaceChildren();
+  if (!answer || !answer.workspace) {
+    host.hidden = true;
+    return;
+  }
+  const { cards, elsewhere, refusal } = gateCards(answer, { embed: embedOpts.embed, member: embedOpts.embed ? view.member : null });
+  for (const c of cards) {
+    const box = document.createElement("div");
+    box.className = "ws-gate";
+    box.dataset.gate = c.key;
+    const title = document.createElement("div");
+    title.className = "ws-gate-title";
+    title.textContent = c.title;
+    const facts = document.createElement("div");
+    facts.className = "ws-gate-facts";
+    facts.textContent = c.facts;
+    facts.title = c.command;
+    box.append(title, facts);
+    if (c.note) {
+      const note = document.createElement("div");
+      note.className = "ws-gate-note";
+      note.textContent = c.note;
+      box.appendChild(note);
+    }
+    if (c.button && !previewMode && !staticMode) {
+      const b = button(c.button.label, "approve", () => approveWorkspaceGate(c.key, b));
+      b.title = c.button.title;
+      box.appendChild(b);
+    }
+    host.appendChild(box);
+  }
+  if (elsewhere) {
+    const more = document.createElement("div");
+    more.className = "ws-gate ws-gate-note";
+    more.textContent = `${elsewhere} more gate${elsewhere === 1 ? "" : "s"} waiting in other members`;
+    host.appendChild(more);
+  }
+  if (refusal) {
+    const err = document.createElement("div");
+    err.className = "ws-gate ws-gate-note";
+    err.textContent = `gates unread: ${refusal.error}`;
+    err.title = refusal.remedy || "";
+    host.appendChild(err);
+  }
+  host.hidden = !host.children.length;
+}
+function approveWorkspaceGate(key, btn) {
+  if (btn) btn.disabled = true;
+  fetch("/api/workspace/gates/approve", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ key, env: wsGates.answer && wsGates.answer.env }) })
+    .then((r) => r.json())
+    .then((j) => {
+      if (j.error) {
+        showToast(`✗ approve ${key}: ${j.error}`, false);
+        nowline("✗ " + j.error);
+      } else {
+        showToast(`✓ ${key} approved as ${j.approver}`, true);
+      }
+      loadWorkspaceGates({ force: true });
+    })
+    .catch((e) => showToast(`✗ approve ${key}: ${e}`, false))
+    .finally(() => {
+      if (btn) btn.disabled = false;
+    });
+}
+
+/** The member names a graph shows: its member boxes, and the first segment of
+ * each composed node id. */
+function membersOf(ir) {
+  const out = new Set();
+  for (const n of (ir && ir.nodes) || []) {
+    const m = nodeMember(n.id);
+    if (m) out.add(m);
+  }
+  const svg = currentSvg();
+  if (svg && out.size) for (const r of svg.querySelectorAll("rect[data-group-id]")) out.add(r.getAttribute("data-group-id"));
+  return out;
+}
+
+/** After every paint: place the view where the link (or the last pick) put it. */
+function afterPaint(ir) {
+  const ids = new Set(((ir && ir.nodes) || []).map((n) => n.id));
+  if (pendingPlace) {
+    const place = settlePlace(pendingPlace, membersOf(ir), ids);
+    pendingPlace = null;
+    urlRefusals.push(...place.refused);
+    if (place.apply.member) view.member = place.apply.member;
+    if (place.apply.node) {
+      selectNode(place.apply.node, { quiet: true });
+      revealNode(place.apply.node);
+    }
+    renderStatusbar();
+  } else if (selectedNodeId && !ids.has(selectedNodeId)) {
+    // The pick isn't on this view any more; the URL stops naming it.
+    selectedNodeId = null;
+    syncViewUrl();
+  }
+  if (view.member && !selectedNodeId) revealMember(view.member);
+  const line = refusalLine(urlRefusals);
+  urlRefusals = [];
+  if (line) nowline(line);
+}
+
+/** A card was picked (graph click, panel row, palette, the link). */
+function noteSelection(id, { quiet = false } = {}) {
+  selectedNodeId = id;
+  const m = nodeMember(id);
+  if (m) view.member = m;
+  syncViewUrl();
+  // A pick the link or the host made isn't a click: the host isn't told.
+  if (!quiet) embedSelected(view.member, id);
+}
+
+/** Frame one member's box, or the cards in it when the zoom draws no boxes. */
+function revealMember(member) {
+  const svg = currentSvg();
+  if (!svg || !vbInit) return false;
+  let box = null;
+  const rect = svg.querySelector(`rect[data-group-id="${CSS.escape(member)}"]`);
+  if (rect) {
+    box = boxInSvg(svg, rect);
+  } else {
+    for (const g of svg.querySelectorAll("[data-node-id]")) {
+      if (nodeMember(g.getAttribute("data-node-id")) !== member) continue;
+      const b = boxInSvg(svg, g);
+      if (b) box = box ? union(box, b) : b;
+    }
+  }
+  if (!box || !(box.width > 0) || !(box.height > 0)) return false;
+  const pad = 0.06;
+  const aspect = vbInit[3] / vbInit[2];
+  let w = box.width * (1 + 2 * pad);
+  let h = box.height * (1 + 2 * pad);
+  if (h / w > aspect) w = h / aspect;
+  else h = w * aspect;
+  vb = [box.x + box.width / 2 - w / 2, box.y + box.height / 2 - h / 2, w, h];
+  vbAtFit = false;
+  applyVB();
+  return true;
+}
+/** An element's box in the svg's user units, after every transform on the way
+ * (a dragged box is a `translate` on its wrapper, #228). */
+function boxInSvg(svg, el) {
+  try {
+    const b = el.getBBox();
+    const m = svg.getScreenCTM() && el.getScreenCTM() ? svg.getScreenCTM().inverse().multiply(el.getScreenCTM()) : null;
+    if (!m) return { x: b.x, y: b.y, width: b.width, height: b.height };
+    const pts = [[b.x, b.y], [b.x + b.width, b.y], [b.x, b.y + b.height], [b.x + b.width, b.y + b.height]].map(([x, y]) => new DOMPoint(x, y).matrixTransform(m));
+    const xs = pts.map((p) => p.x);
+    const ys = pts.map((p) => p.y);
+    return { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) };
+  } catch {
+    return null;
+  }
+}
+function union(a, b) {
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return { x, y, width: Math.max(a.x + a.width, b.x + b.width) - x, height: Math.max(a.y + a.height, b.y + b.height) - y };
+}
+
+/** Write the view into the address bar, keeping every other parameter. */
+function syncViewUrl() {
+  if (!viewUrlReady) return;
+  const place = pendingPlace || {};
+  const state = {
+    member: place.member || view.member,
+    zoom: zoomValue(),
+    env: view.env,
+    tier: view.tier,
+    lens: colourMode,
+    node: place.node || selectedNodeId,
+    radial: view.radial && !view.components && !view.logical && !view.ops,
+  };
+  const defaults = { env: (projectInfo && projectInfo.currentEnv) || null, lens: savedColourMode };
+  const next = location.pathname + writeViewQuery(location.search, state, defaults) + location.hash;
+  if (next === location.pathname + location.search + location.hash) return;
+  try {
+    history.replaceState(history.state, "", next);
+  } catch {
+    /* a sandboxed frame may refuse; the view still works */
+  }
+}
+
 // Select a node from a panel row the same way a graph click would: highlight
 // its card (when it's in the current SVG) and open its inspect panel.
-function selectNode(id) {
+function selectNode(id, { quiet = false } = {}) {
   const node = lastGraphIr && lastGraphIr.nodes.find((n) => n.id === id);
   if (!node) return;
   const host = document.getElementById("graph");
@@ -2109,6 +2450,7 @@ function selectNode(id) {
   const g = host.querySelector(`[data-node-id="${CSS.escape(id)}"]`);
   if (g) g.classList.add("sel");
   inspect(node);
+  noteSelection(node.id, { quiet });
   carvePick(node);
 }
 
@@ -2704,6 +3046,7 @@ function renderStatusbar() {
   // Pure state — the strip echoes the axes whose controls live on the floating
   // panel and in ⌘K, so the current view stays legible with the panel collapsed.
   const parts = [`zoom: ${zoomValue()}`, view.env ? `env: ${view.env}` : "env: (source)"];
+  if (view.member) parts.unshift(`member: ${view.member}`);
   // #399: which colour the graph is in is state, not a control, so it belongs
   // on the strip the same way the zoom and the env do. Only when it is not
   // drift — drift is what the strip has always implied.
@@ -2717,6 +3060,10 @@ function renderStatusbar() {
   const stillReading = pendingLine(pendingMembers, pendingTotal);
   if (stillReading) parts.push(stillReading);
   el.textContent = parts.join(" · ");
+  syncViewUrl();
+  // #477: gates don't wait on the graph (a member that fails to draw can still
+  // have a gate waiting). Re-read only when the env moved; `changed` forces it.
+  if (projectInfo) loadWorkspaceGates();
   // #131: why this level rendered empty, or as the one below it. The server
   // decides (src/zoom-notes.ts) — the SPA never infers it, so the note always
   // describes the graph that actually came back. Appended rather than mixed
@@ -3060,7 +3407,9 @@ function mountOperator(host) {
     box,
     operatorState,
     {
-      approve: (op, gate) => approveConvergeGate(op, gate),
+      approve: embedOpts.embed || previewMode || staticMode ? null : (op, gate) => approveConvergeGate(op, gate),
+      approver: projectInfo && projectInfo.approver,
+      why: embedOpts.embed ? "host" : previewMode ? "preview" : "static",
       // A static export has no server to ask, so it gets no history affordance
       // at all rather than a button that can only fail.
       ...(staticMode ? {} : { history: () => toggleOperatorHistory() }),
@@ -3078,7 +3427,7 @@ function mountPlayhead(host) {
   if (!hasPlayhead(runState)) return;
   const box = document.createElement("div");
   box.className = "run-playhead";
-  renderPlayhead(box, runState, gateCard, { approve: (op, gate) => signal(op, gate) });
+  renderPlayhead(box, runState, gateCard, { approve: embedOpts.embed || previewMode || staticMode ? null : (op, gate) => signal(op, gate), approver: projectInfo && projectInfo.approver, why: embedOpts.embed ? "host" : previewMode ? "preview" : "static" });
   host.appendChild(box);
 }
 
@@ -4674,6 +5023,7 @@ async function loadOnce(opts = {}, isCurrent = () => true) {
     pendingMembers = body.meta && body.meta.mode === "progressive" ? [...(body.meta.pending || [])] : [];
     pendingTotal = pendingMembers.length;
     render(body.ir, body.svg, body.meta);
+    afterPaint(body.ir);
   } catch (err) {
     // A background settle poll must not blow away a good graph on a transient error.
     if (!opts.quiet && isCurrent()) {
@@ -4807,6 +5157,7 @@ async function initPickers() {
   environments = info.environments || [];
   tiers = info.tiers || [];
   targets = info.targets || [];
+  openFromQuery();
   renderStatusbar();
   load();
 }
@@ -4849,6 +5200,7 @@ events.addEventListener("member", (e) => {
 events.addEventListener("changed", () => {
   bulkDiffCache = null; // an op ran → per-node live state may have changed
   load();
+  loadWorkspaceGates({ force: true });
   loadSubstrates(); // a bring-up (or any op) finished → re-detect readiness
 });
 
@@ -5500,6 +5852,8 @@ async function initActions() {
   }
 }
 initActions();
+// #476: a frame keeps its own inspect state, folded until something is picked.
+const INSPECT_COLLAPSED_KEY = embedOpts.embed ? "behold.inspectCollapsed.embed" : "behold.inspectCollapsed";
 initInspectPane();
 
 // Inspect pane chrome (#15): collapse (chevron / edge tab) + drag-to-resize, with
@@ -5508,7 +5862,11 @@ initInspectPane();
 // so the ⌘K palette (#73) can drive the same collapse/reopen the chevron does.
 function setInspectCollapsed(on) {
   document.getElementById("app").classList.toggle("inspect-collapsed", on);
-  localStorage.setItem("behold.inspectCollapsed", on ? "1" : "0");
+  try {
+    localStorage.setItem(INSPECT_COLLAPSED_KEY, on ? "1" : "0");
+  } catch {
+    /* private mode */
+  }
 }
 function toggleInspect() {
   setInspectCollapsed(!document.getElementById("app").classList.contains("inspect-collapsed"));
@@ -5521,7 +5879,13 @@ function initInspectPane() {
   // Restore persisted width + collapsed state.
   const savedW = Number(localStorage.getItem("behold.inspectW"));
   if (savedW >= MIN && savedW <= MAX) document.documentElement.style.setProperty("--inspect-w", savedW + "px");
-  if (localStorage.getItem("behold.inspectCollapsed") === "1") app.classList.add("inspect-collapsed");
+  let folded = null;
+  try {
+    folded = localStorage.getItem(INSPECT_COLLAPSED_KEY);
+  } catch {
+    /* private mode */
+  }
+  if (folded === "1" || (folded === null && embedOpts.embed)) app.classList.add("inspect-collapsed");
 
   document.getElementById("inspect-collapse").addEventListener("click", () => setInspectCollapsed(true));
   document.getElementById("inspect-reopen").addEventListener("click", () => setInspectCollapsed(false));
@@ -5691,6 +6055,10 @@ function paletteCommands() {
   }
 
   // Env/stack/tier/target selection — replaces the old header pickers.
+  if (view.member) c.push([`member: whole estate (leave ${view.member})`, () => { view.member = null; selectedNodeId = null; renderStatusbar(); fitGraph(); }]);
+  for (const m of lastGraphIr ? membersOf(lastGraphIr) : []) {
+    if (m !== view.member) c.push([`member: ${m}`, () => { view.member = m; selectedNodeId = null; renderStatusbar(); revealMember(m); }]);
+  }
   c.push(["env: (source)" + (!view.env ? " ✓" : ""), () => { view.env = null; resetDialCaches(); load(); }]);
   for (const e of environments) {
     c.push([`env: ${e}` + (view.env === e ? " ✓" : ""), () => { view.env = e; resetDialCaches(); load(); }]);
@@ -5722,7 +6090,7 @@ function paletteCommands() {
     if (opsApply) {
       // #165: not for a designated env — its ApplyOp is refused server-side too.
       if (!designatedFor(view.env || opsInitialEnv)) c.push([`Deploy: Sync (${opsApply.name})`, () => runOp(opsApply.name)]);
-      if (opsApply.gate) c.push([`Approve ${opsApply.gate}`, () => signal(opsApply.name, opsApply.gate)]);
+      if (opsApply.gate && !embedOpts.embed) c.push([`Approve ${opsApply.gate}`, () => signal(opsApply.name, opsApply.gate)]);
     }
     // #165: a designated env's applies happen on the forge, so a rollback PR
     // opened from here would have nothing local to land — hidden, as designed.

package/web/embed.js

@@ -0,0 +1,76 @@
+// #476: behold framed in a host pane (arugula's workspace block). Pure logic,
+// no DOM: app.js reads the embed parameters once, posts `behold:select` to the
+// parent when a member or a card is picked, and takes `behold:view` from the
+// parent to move the view.
+//
+//   ?embed=1            compact chrome: no Deploy tab, no theme picker, the
+//                       panel and the inspect pane start folded
+//   ?theme=<name>       a theme for this frame only (light, dark, or any theme
+//                       name the picker lists); never saved
+//   ?host=<origin>      the parent's origin. Messages go only there, and only
+//                       messages from there are taken. No host, no messages.
+//
+// Gates in a frame are the host's to approve (#477): behold draws them and
+// says where to approve.
+
+import { VIEW_KEYS } from "./view-url.js";
+
+/** The light/dark words a host can pass, mapped to a theme the picker has. */
+export const THEME_ALIASES = { light: "GitHub Light Default", dark: "GitHub Dark Default" };
+
+/** The embed parameters of a query. `host` is an origin, or null when it is
+ * missing or not one (a path, a bare word): a target origin has to be exact. */
+export function readEmbed(search) {
+  const q = new URLSearchParams(search || "");
+  const embed = /^(1|true|on|yes)$/i.test(q.get("embed") || "");
+  let host = null;
+  const raw = (q.get("host") || "").trim();
+  if (raw) {
+    try {
+      const u = new URL(raw);
+      if (u.protocol === "http:" || u.protocol === "https:") host = u.origin;
+    } catch {
+      host = null;
+    }
+  }
+  const t = (q.get("theme") || "").trim();
+  const theme = t ? THEME_ALIASES[t.toLowerCase()] || t : null;
+  return { embed, host, theme };
+}
+
+/** The message a pick sends the parent. `node` is null when a member's box was
+ * picked rather than a card. */
+export function selectMessage(member, node) {
+  return { type: "behold:select", member: member || null, node: node || null };
+}
+
+/**
+ * A `behold:view` message from the parent, reduced to the view keys it
+ * carries, or null when it isn't one or doesn't come from the host. The values
+ * go through the same checks as the URL's (view-url.js settleView).
+ */
+export function viewFromMessage(event, host) {
+  if (!host || !event || event.origin !== host) return null;
+  const d = event.data;
+  if (!d || typeof d !== "object" || d.type !== "behold:view") return null;
+  const want = {};
+  for (const k of VIEW_KEYS) {
+    if (!(k in d)) continue;
+    const v = d[k];
+    if (k === "radial") {
+      if (typeof v === "boolean") want.radial = v;
+      continue;
+    }
+    if (k === "env") {
+      if (v === null || v === "") want.env = null;
+      else if (typeof v === "string") want.env = v;
+      continue;
+    }
+    if (k === "member" && v === null) {
+      want.member = null; // the whole estate
+      continue;
+    }
+    if (typeof v === "string" && v) want[k] = v;
+  }
+  return want;
+}

package/web/embed.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { readEmbed, selectMessage, viewFromMessage, THEME_ALIASES } from "./embed.js";
+
+describe("readEmbed (#476)", () => {
+  it("reads embed, an exact host origin and a theme", () => {
+    expect(readEmbed("?embed=1&host=http%3A%2F%2Flocalhost%3A7777%2Fsome%2Fpath&theme=dark")).toEqual({
+      embed: true,
+      host: "http://localhost:7777",
+      theme: THEME_ALIASES.dark,
+    });
+  });
+  it("takes no host that isn't an http(s) origin", () => {
+    expect(readEmbed("?host=localhost").host).toBe(null);
+    expect(readEmbed("?host=javascript%3Aalert(1)").host).toBe(null);
+  });
+  it("passes a theme name through", () => {
+    expect(readEmbed("?theme=Atom%20One%20Light").theme).toBe("Atom One Light");
+  });
+  it("is off by default", () => {
+    expect(readEmbed("")).toEqual({ embed: false, host: null, theme: null });
+  });
+});
+
+describe("selectMessage (#476)", () => {
+  it("names the member and the card", () => {
+    expect(selectMessage("delivery", "delivery/appService")).toEqual({ type: "behold:select", member: "delivery", node: "delivery/appService" });
+    expect(selectMessage("delivery", null)).toEqual({ type: "behold:select", member: "delivery", node: null });
+  });
+});
+
+describe("viewFromMessage (#476)", () => {
+  const host = "http://localhost:7777";
+  it("takes the view keys from the host", () => {
+    const e = { origin: host, data: { type: "behold:view", member: "delivery", env: "prod", radial: true, embed: "ignored", zoom: 3 } };
+    expect(viewFromMessage(e, host)).toEqual({ member: "delivery", env: "prod", radial: true });
+  });
+  it("reads member null as the whole estate and env empty as the source", () => {
+    expect(viewFromMessage({ origin: host, data: { type: "behold:view", member: null, env: "" } }, host)).toEqual({ member: null, env: null });
+  });
+  it("ignores another origin, another type, and any message when there is no host", () => {
+    expect(viewFromMessage({ origin: "http://evil", data: { type: "behold:view", member: "x" } }, host)).toBe(null);
+    expect(viewFromMessage({ origin: host, data: { type: "other" } }, host)).toBe(null);
+    expect(viewFromMessage({ origin: host, data: { type: "behold:view" } }, null)).toBe(null);
+  });
+});