partforge 0.46.4 → 0.47.1

package/src/framework/chrome.css

@@ -250,6 +250,26 @@
   .pf-anim-bar { bottom: 64px; }
 }
 
+/* Placement half of app.css's touch layout — same query, so the two must be
+   edited together. That layout stacks the bar into rows, and a shrink-to-fit
+   absolutely-positioned box sizes itself to its widest single item (195px,
+   measured at 390px) rather than to the room available, wrapping every row far
+   earlier than it needs to. State the width outright.
+
+   The lift off the viewbar comes along for a landscape phone, which is wider
+   than 719px and so misses the block above. It also keeps this clear of the
+   viewbar CLAMP in animation-controls.js: with the bands no longer
+   intersecting, applyPlacement() returns before touching left/transform, so
+   the stacked bar stays centred instead of being slid sideways by a rule that
+   was reasoning about a single-row bar.
+
+   The cap is for a tablet — a coarse pointer on a wide stage — where an
+   unbounded stacked bar would span 700px+ and strand the reset button across a
+   mostly empty row. A phone is narrower than the cap and still fills its width. */
+@media (max-width: 719px), (pointer: coarse) {
+  .pf-anim-bar { width: calc(100% - 24px); max-width: 520px; bottom: 64px; }
+}
+
 
 
 /* ---- reduced motion -----------------------------------------------------

package/src/framework/controls.js

@@ -1,364 +1,15 @@
-// Builds the sectioned control panel from a part's `parameters` schema.
+// The control panel's public entry point. The implementation lives in panel/:
 //
-// Most sections show a preset picker (below the title) plus an expandable
-// "Advanced" block of sliders. The "features" section instead puts, under
-// Advanced, a checkbox per feature followed by its own controls — ticking one
-// enables it and reveals those controls right below it.
-// All controls mutate the shared `params` object and call onDirty() on change.
-
-import { renderMarkdown } from "./markdown.js";
-
-// Short numeric string without float noise (4 dp max) for the value box.
-const numStr = (v) => String(Math.round(v * 1e4) / 1e4);
-
-// --- relevance (dim controls / hide sections that don't affect on-screen parts) ---
-// `relevant` is a Set of param keys, or any non-Set value (e.g. RELEVANT_ALL) → show all.
-function applyRelevance(relevant, controls, sections) {
-  const showAll = !(relevant instanceof Set);
-  for (const { key, el: node } of controls) {
-    const irrelevant = !showAll && !relevant.has(key);
-    node.classList.toggle("irrelevant", irrelevant);
-    if (irrelevant) node.title = "Doesn't affect the parts in the current view";
-    else node.removeAttribute("title");
-  }
-  for (const { el: node, keys } of sections) {
-    const anyRelevant = showAll || [...keys].some((k) => relevant.has(k));
-    node.classList.toggle("section-hidden", !anyRelevant);
-  }
-}
-
-// --- visibility (hidden controls/sections) --------------------------------
-export const visibleAdvanced = (sec) => (sec.advanced ?? []).filter((d) => !d.hidden);
-export const visibleFeatures = (sec) => (sec.features ?? []).filter((f) => !f.hidden);
-// Standalone toggle checkboxes a preset section can show (outside the Advanced fold),
-// e.g. preview switches. Each: { key, label, on?, description?, hidden? }.
-export const visibleToggles = (sec) => (sec.toggles ?? []).filter((t) => !t.hidden);
-export function sectionRenders(sec) {
-  if (sec.hidden) return false;
-  if (sec.features) return visibleFeatures(sec).length > 0;
-  const hasPresets = sec.presets && Object.keys(sec.presets).length > 0;
-  return !!hasPresets || visibleAdvanced(sec).length > 0 || visibleToggles(sec).length > 0;
-}
-
-// Parse a typed value → clamped to [min, max], or null if not a finite number.
-export function clampToRange(raw, min, max) {
-  const v = parseFloat(raw);
-  if (!Number.isFinite(v)) return null;
-  return Math.min(max, Math.max(min, v));
-}
-
-// --- info glyph + per-panel popover -----------------------------------------
-// Popover top edge: below the glyph when it fits, flipped above when the
-// viewport bottom would clip it (e.g. the animation transport bar's ⓘ, which
-// sits at the bottom of the stage). Pure, for direct unit testing — happy-dom
-// reports zero layout metrics, so the flip can't be exercised via the DOM.
-export function popoverTop({ glyphTop, glyphBottom, popHeight, viewportHeight }) {
-  const below = glyphBottom + 6;
-  if (below + popHeight <= viewportHeight - 8) return below;
-  return Math.max(8, glyphTop - 6 - popHeight);
-}
-
-// One popover element per panel, shared by all its glyphs (only one open at a
-// time). Document-level dismiss listeners are registered per panel and removed
-// by panel.dispose().
-export function createInfoPopover() {
-  const pop = el("div", "popover");
-  pop.hidden = true;
-  document.body.append(pop);
-  let owner = null; // the glyph whose description is showing
-
-  function close() {
-    if (pop.hidden) return;
-    pop.hidden = true;
-    if (owner) { owner.setAttribute("aria-expanded", "false"); owner = null; }
-  }
-  const onDocClick = (e) => {
-    if (!pop.hidden && !pop.contains(e.target) && !e.target.closest?.(".info")) close();
-  };
-  const onDocKeydown = (e) => { if (e.key === "Escape") close(); };
-  document.addEventListener("click", onDocClick);
-  document.addEventListener("keydown", onDocKeydown);
-
-  return {
-    toggle(glyph, description) {
-      if (owner === glyph) { close(); return; } // toggle off
-      close();
-      pop.innerHTML = renderMarkdown(description);
-      pop.hidden = false;
-      owner = glyph;
-      glyph.setAttribute("aria-expanded", "true");
-      const r = glyph.getBoundingClientRect();
-      pop.style.top = `${popoverTop({ glyphTop: r.top, glyphBottom: r.bottom, popHeight: pop.offsetHeight, viewportHeight: window.innerHeight })}px`;
-      pop.style.left = `${Math.max(8, r.left - 8)}px`;
-    },
-    dispose() {
-      document.removeEventListener("click", onDocClick);
-      document.removeEventListener("keydown", onDocKeydown);
-      pop.remove();
-    },
-  };
-}
-
-// Append a focusable ⓘ glyph to `container` that toggles the panel's shared
-// popover with `description` (Markdown). No-op when description is empty.
-export function attachInfo(container, description, info) {
-  if (typeof description !== "string" || !description.trim()) return;
-  const glyph = document.createElement("button");
-  glyph.type = "button";
-  glyph.className = "info";
-  glyph.textContent = "ⓘ";
-  glyph.setAttribute("aria-label", "More info");
-  glyph.setAttribute("aria-expanded", "false");
-  glyph.addEventListener("click", (e) => { e.stopPropagation(); info.toggle(glyph, description); });
-  container.append(glyph);
-}
-
-function el(tag, className, text) {
-  const node = document.createElement(tag);
-  if (className) node.className = className;
-  if (text != null) node.textContent = text;
-  return node;
-}
-
-// One parameter control bound to params[def.key]. `def.control`:
-//   "slider" (default) — range slider + an editable number box (drag OR type)
-//   "number"           — number box only (no slider)
-//   "text"             — single-line text field
-//   "textarea"         — multiline text field
-// The box accepts exact values (finer than `step`); typed values clamp to
-// [min, max] on commit (blur/Enter). Returns { wrap, sync }.
-function makeSlider(def, params, onChange, info) {
-  const numeric = def.control === "number";
-  const wrap = el("div", "slider");
-  const row = el("div", "row");
-  const label = el("label", "", def.label);
-  attachInfo(label, def.description, info);
-  row.append(label);
-
-  // editable value box (+ optional unit suffix)
-  const val = el("div", "val");
-  const box = document.createElement("input");
-  box.type = "number";
-  box.className = "num";
-  box.min = def.min; box.max = def.max; box.step = def.step;
-  box.value = numStr(params[def.key]);
-  val.append(box);
-  if (def.unit) val.append(el("span", "unit", def.unit));
-  row.append(val);
-  wrap.append(row);
-
-  let slider = null;
-  if (!numeric) {
-    slider = document.createElement("input");
-    slider.type = "range";
-    slider.min = def.min; slider.max = def.max; slider.step = def.step;
-    slider.value = params[def.key];
-    slider.addEventListener("input", () => {
-      params[def.key] = +slider.value;
-      box.value = numStr(+slider.value);
-      onChange?.();
-    });
-    wrap.append(slider);
-  }
-
-  // live preview while typing (unclamped); clamp + reformat on commit (blur/Enter)
-  box.addEventListener("input", () => {
-    const v = parseFloat(box.value);
-    if (!Number.isFinite(v)) return;
-    params[def.key] = v;
-    if (slider) slider.value = v;
-    onChange?.();
-  });
-  box.addEventListener("change", () => {
-    const v = clampToRange(box.value, def.min, def.max);
-    if (v == null) { box.value = numStr(params[def.key]); return; } // revert invalid input
-    params[def.key] = v;
-    box.value = numStr(v);
-    if (slider) slider.value = v;
-    onChange?.();
-  });
-
-  const sync = () => {
-    box.value = numStr(params[def.key]);
-    if (slider) slider.value = params[def.key];
-  };
-  return { wrap, sync };
-}
-
-function makeTextControl(def, params, onChange, info) {
-  const multiline = def.control === "textarea";
-  const wrap = el("div", "slider");
-  const row = el("div", "row");
-  const label = el("label", "", def.label);
-  attachInfo(label, def.description, info);
-  row.append(label);
-  wrap.append(row);
-
-  const field = document.createElement(multiline ? "textarea" : "input");
-  if (!multiline) field.type = "text";
-  field.className = "text-input";
-  field.value = String(params[def.key] ?? "");
-  field.addEventListener("input", () => {
-    params[def.key] = field.value;
-    onChange?.();
-  });
-  wrap.append(field);
-
-  const sync = () => { field.value = String(params[def.key] ?? ""); };
-  return { wrap, sync };
-}
-
-const makeParameterControl = (def, params, onChange, info) =>
-  def.control === "text" || def.control === "textarea"
-    ? makeTextControl(def, params, onChange, info)
-    : makeSlider(def, params, onChange, info);
-
-// A collapsible "Advanced ▾" block. Returns { adv, toggle }.
-function advancedBlock() {
-  const adv = el("div", "adv hidden");
-  const toggle = el("button", "adv-toggle", "Advanced ▾");
-  toggle.addEventListener("click", () => {
-    const hidden = adv.classList.toggle("hidden");
-    toggle.textContent = hidden ? "Advanced ▾" : "Advanced ▴";
-  });
-  return { adv, toggle };
-}
-
-export function buildControls(root, parameters, params, onDirty) {
-  const info = createInfoPopover();
-  const controls = []; // { key, el } per control element
-  const sections = []; // { el, keys:Set } per rendered section
-  const syncFns = []; // { key, sync } for every widget that can re-read params
-  for (const sec of parameters) {
-    if (!sectionRenders(sec)) continue;
-    const section = el("div", "section");
-    const title = el("div", "sec-title", sec.title);
-    attachInfo(title, sec.description, info);
-    section.append(title);
-    const keys = new Set();
-    const register = (key, node, sync) => {
-      controls.push({ key, el: node });
-      keys.add(key);
-      if (sync) syncFns.push({ key, sync });
-    };
-    if (sec.features) buildFeatureSection(section, sec, params, onDirty, register, info);
-    else buildPresetSection(section, sec, params, onDirty, register, info);
-    root.append(section);
-    sections.push({ el: section, keys });
-  }
-  return {
-    applyRelevance: (relevant) => applyRelevance(relevant, controls, sections),
-    // Re-read params into the widgets — all of them, or just `keys`. The
-    // programmatic twin of a user edit (setParams); never fires onDirty.
-    syncValues: (keys) => {
-      const only = keys && new Set(keys);
-      for (const { key, sync } of syncFns) if (!only || only.has(key)) sync();
-    },
-    dispose: () => { info.dispose(); root.replaceChildren(); },
-  };
-}
-
-function buildPresetSection(section, sec, params, onDirty, register, info) {
-  // preset picker, below the title, full width (omitted when the section has no presets)
-  let preset = null;
-  const presetNames = sec.presets ? Object.keys(sec.presets) : [];
-  if (presetNames.length) {
-    preset = document.createElement("select");
-    preset.className = "preset";
-    for (const name of [...presetNames, "Custom"]) {
-      const o = document.createElement("option");
-      o.value = name; o.textContent = name; preset.append(o);
-    }
-    preset.value = presetNames[0];
-    section.append(preset);
-  }
-
-  // standalone toggle checkboxes (e.g. preview switches), shown below the preset and
-  // outside the Advanced fold so they stay visible. Independent of the preset selector.
-  for (const t of visibleToggles(sec)) {
-    const row = el("label", "feat");
-    const box = document.createElement("input");
-    box.type = "checkbox";
-    box.checked = params[t.key] > 0;
-    const lbl = el("span", "", t.label);
-    attachInfo(lbl, t.description, info);
-    row.append(box, lbl);
-    box.addEventListener("change", () => { params[t.key] = box.checked ? (t.on ?? 1) : 0; onDirty?.(); });
-    register(t.key, row, () => { box.checked = params[t.key] > 0; });
-    section.append(row);
-  }
-
-  const advanced = visibleAdvanced(sec);
-  const syncs = {};
-  if (advanced.length) {
-    const { adv, toggle } = advancedBlock();
-    for (const def of advanced) {
-      const s = makeParameterControl(def, params, () => { if (preset) preset.value = "Custom"; onDirty?.(); }, info);
-      adv.append(s.wrap);
-      syncs[def.key] = s.sync; // raw: preset APPLICATION must not mark itself Custom
-      // A programmatic edit diverges from the preset exactly as a user edit does,
-      // so the picker falls back to Custom — leaving a stale preset name selected
-      // would also make it unre-appliable (no change event for the current option).
-      register(def.key, s.wrap, () => { s.sync(); if (preset) preset.value = "Custom"; });
-    }
-    section.append(toggle, adv);
-  }
-
-  // applying a preset overwrites its keys and refreshes this section's sliders
-  if (preset) {
-    preset.addEventListener("change", () => {
-      const bundle = sec.presets[preset.value];
-      if (!bundle) return; // "Custom"
-      Object.assign(params, bundle);
-      for (const key in syncs) if (key in params) syncs[key]();
-      onDirty?.();
-    });
-  }
-}
-
-function buildFeatureSection(section, sec, params, onDirty, register, info) {
-  // Everything lives under Advanced: each feature is a checkbox followed by its
-  // own controls, which appear directly below it when the box is checked.
-  const { adv, toggle } = advancedBlock();
-  section.append(toggle, adv);
-
-  for (const feat of visibleFeatures(sec)) {
-    const checkRow = el("label", "feat");
-    const box = document.createElement("input");
-    box.type = "checkbox";
-    box.checked = params[feat.key] > 0;
-    const featLabel = el("span", "", feat.label);
-    attachInfo(featLabel, feat.description, info);
-    checkRow.append(box, featLabel);
-    // `group` is created just below — the sync only ever runs after this
-    // function returns, so the closure is safely bound by then.
-    register(feat.key, checkRow, () => {
-      box.checked = params[feat.key] > 0;
-      group.classList.toggle("hidden", !box.checked);
-    });
-
-    const group = el("div", "feat-group");
-    const syncs = [];
-    for (const def of feat.sliders.filter((d) => !d.hidden)) {
-      const s = makeParameterControl(def, params, onDirty, info);
-      group.append(s.wrap);
-      syncs.push(s.sync);
-      register(def.key, s.wrap, s.sync);
-    }
-    group.classList.toggle("hidden", !box.checked);
-
-    box.addEventListener("change", () => {
-      if (box.checked) {
-        if (!(params[feat.key] > 0)) params[feat.key] = feat.on; // enable
-        syncs.forEach((s) => s());
-        group.classList.remove("hidden");
-      } else {
-        params[feat.key] = 0; // disable
-        group.classList.add("hidden");
-      }
-      onDirty?.();
-    });
-
-    adv.append(checkRow, group); // checkbox, then its controls right below
-  }
-}
+//   panel/legacy.js       the original advanced/toggles/features shapes
+//   panel/model.js        canonical nodes -> render tree, plus conditions
+//   panel/widget-specs.js the control-type registry (shared with partforge/lint)
+//   panel/panel-state.js  one pure pass for visibility/disabling/dimming
+//   panel/widgets/        one DOM factory per type
+//   panel/render.js       the DOM binder
+//
+// This file stays at its path because animation-controls.js imports the popover
+// helpers from it, and because it is the documented import site.
+export { buildControls } from "./panel/render.js";
+export { popoverTop, createInfoPopover, attachInfo } from "./panel/info.js";
+export { clampToRange } from "./panel/widgets/numeric.js";
+export { visibleAdvanced, visibleFeatures, visibleToggles, sectionRenders } from "./panel/legacy.js";

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

@@ -9,6 +9,8 @@ import { EASINGS } from "../animation.js";
 import { CANONICAL_VIEWS } from "../view-angles.js";
 import { probeSubPartPose } from "../pose-probe-core.js";
 import { resolveDerived } from "../derive.js";
+import { desugar } from "../panel/legacy.js";
+import { controlNodes } from "../panel/model.js";
 
 const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
 
@@ -22,20 +24,19 @@ const animEntries = (part) =>
 // rule checks its own slice). A bare-tracks animation is one anonymous step.
 const rawSteps = (a) => (Array.isArray(a.steps) ? a.steps.filter(isPlainObject) : [{ ...a, label: null }]);
 
-// The control descriptor ranges, for value-in-range checks. Mirrors
-// rules-schema.js's collectDescriptors walk (not shared: each group owns its
-// own walk by design — see lint/index.js header).
+// The control descriptor ranges, for value-in-range checks. Walks the shared
+// panel model rather than re-implementing the schema walk — before that model
+// existed this duplicated rules-schema.js's collectDescriptors by design, and
+// the two could drift.
+//
+// desugar() is used directly, WITHOUT buildTree(): hidden controls must stay in,
+// because an animation may legitimately drive a parameter with no visible UI.
 function paramRanges(part) {
   const ranges = new Map();
-  const secs = Array.isArray(part?.parameters) ? part.parameters : [];
-  const add = (d) => {
-    if (d && typeof d.key === "string" && !ranges.has(d.key)) ranges.set(d.key, { min: d.min, max: d.max });
-  };
-  for (const sec of secs) {
-    for (const d of Array.isArray(sec?.advanced) ? sec.advanced : []) add(d);
-    for (const f of Array.isArray(sec?.features) ? sec.features : []) {
-      for (const s of Array.isArray(f?.sliders) ? f.sliders : []) add(s);
-    }
+  for (const c of controlNodes(desugar(part?.parameters))) {
+    // A checkbox has no range; only numeric controls constrain a keyframe.
+    if (c.type === "checkbox") continue;
+    if (typeof c.key === "string" && !ranges.has(c.key)) ranges.set(c.key, { min: c.min, max: c.max });
   }
   return ranges;
 }

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

@@ -4,11 +4,11 @@
 // resolve against `defaults`, which produce a control that silently does nothing.
 import { err, warn } from "./finding.js";
 import { suggest } from "../geometry/op-options.js";
+import { fieldsFor } from "../panel/widget-specs.js";
+import { sectionRenders } from "../panel/legacy.js";
 
-// Fields controls.js reads on a slider/number descriptor.
-const CONTROL_FIELDS = ["key", "label", "unit", "min", "max", "step", "control", "hidden", "description"];
+// Legacy container descriptors aren't widget types, so they keep explicit lists.
 const FEATURE_FIELDS = ["key", "label", "on", "sliders", "hidden", "description"];
-const TOGGLE_FIELDS = ["key", "label", "on", "hidden", "description"];
 
 const sections = (part) => (Array.isArray(part?.parameters) ? part.parameters : []);
 const arr = (x) => (Array.isArray(x) ? x : []);
@@ -21,7 +21,7 @@ function collectDescriptors(part) {
   const out = [];
   sections(part).forEach((sec, si) => {
     arr(sec?.advanced).forEach((d, i) => {
-      if (d) out.push({ d, path: `parameters[${si}].advanced[${i}]`, fields: CONTROL_FIELDS });
+      if (d) out.push({ d, path: `parameters[${si}].advanced[${i}]`, fields: fieldsFor("slider") });
     });
     arr(sec?.features).forEach((f, i) => {
       if (!f) return;
@@ -31,11 +31,11 @@ function collectDescriptors(part) {
         // recognise the demo.js flange_d pattern below: a slider sharing its key
         // with the feature is not an independent parameter, it's the feature's own
         // magnitude, and `defaults[key] === 0` there means "off", not "out of range".
-        if (s) out.push({ d: s, path: `parameters[${si}].features[${i}].sliders[${j}]`, fields: CONTROL_FIELDS, featureKey: f.key });
+        if (s) out.push({ d: s, path: `parameters[${si}].features[${i}].sliders[${j}]`, fields: fieldsFor("slider"), featureKey: f.key });
       });
     });
     arr(sec?.toggles).forEach((t, i) => {
-      if (t) out.push({ d: t, path: `parameters[${si}].toggles[${i}]`, fields: TOGGLE_FIELDS });
+      if (t) out.push({ d: t, path: `parameters[${si}].toggles[${i}]`, fields: fieldsFor("checkbox") });
     });
   });
   return out;
@@ -43,21 +43,10 @@ function collectDescriptors(part) {
 
 const defaultKeys = (part) => new Set(Object.keys(part?.defaults ?? {}));
 
-// Mirrors src/framework/controls.js's own visibility predicates (visibleFeatures /
-// sectionRenders, controls.js:32,36-41) — NOT imported, because controls.js pulls in
-// `marked`/`dompurify` (via markdown.js) for its description popovers, which would
-// break partforge/lint's zero-bare-dependency purity guarantee (test/lint-purity.test.js).
-// `features-requires-sliders` must not flag a `feat.sliders.filter(...)` the panel
-// will never reach: controls.js only iterates `visibleFeatures(sec)` (skipping any
-// feature marked `hidden: true`), and only builds a section at all when
-// `sectionRenders(sec)` is true.
-const visibleFeatures = (sec) => arr(sec?.features).filter((f) => f && !f.hidden);
-function sectionRenders(sec) {
-  if (sec?.hidden) return false;
-  if (sec?.features) return visibleFeatures(sec).length > 0;
-  const hasPresets = sec?.presets && Object.keys(sec.presets).length > 0;
-  return !!hasPresets || arr(sec?.advanced).some((d) => d && !d.hidden) || arr(sec?.toggles).some((t) => t && !t.hidden);
-}
+// These used to be hand-copied from controls.js, because importing it would have
+// dragged `marked`/`dompurify` into partforge/lint and broken its zero-dependency
+// guarantee. panel/legacy.js imports nothing, so lint can share the real
+// implementation and the two can no longer drift.
 
 export const SCHEMA_RULES = [
   {

package/src/framework/panel/info.js

@@ -0,0 +1,76 @@
+// The ⓘ glyph and its per-panel popover. Shared by the control panel and the
+// animation transport bar (animation-controls.js), which is why it is its own
+// module rather than living inside the panel renderer.
+import { renderMarkdown } from "../markdown.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+// Popover top edge: below the glyph when it fits, flipped above when the
+// viewport bottom would clip it (e.g. the animation transport bar's ⓘ, which
+// sits at the bottom of the stage). Pure, for direct unit testing — happy-dom
+// reports zero layout metrics, so the flip can't be exercised via the DOM.
+export function popoverTop({ glyphTop, glyphBottom, popHeight, viewportHeight }) {
+  const below = glyphBottom + 6;
+  if (below + popHeight <= viewportHeight - 8) return below;
+  return Math.max(8, glyphTop - 6 - popHeight);
+}
+
+// One popover element per panel, shared by all its glyphs (only one open at a
+// time). Document-level dismiss listeners are registered per panel and removed
+// by panel.dispose().
+export function createInfoPopover() {
+  const pop = el("div", "popover");
+  pop.hidden = true;
+  document.body.append(pop);
+  let owner = null; // the glyph whose description is showing
+
+  function close() {
+    if (pop.hidden) return;
+    pop.hidden = true;
+    if (owner) { owner.setAttribute("aria-expanded", "false"); owner = null; }
+  }
+  const onDocClick = (e) => {
+    if (!pop.hidden && !pop.contains(e.target) && !e.target.closest?.(".info")) close();
+  };
+  const onDocKeydown = (e) => { if (e.key === "Escape") close(); };
+  document.addEventListener("click", onDocClick);
+  document.addEventListener("keydown", onDocKeydown);
+
+  return {
+    toggle(glyph, description) {
+      if (owner === glyph) { close(); return; } // toggle off
+      close();
+      pop.innerHTML = renderMarkdown(description);
+      pop.hidden = false;
+      owner = glyph;
+      glyph.setAttribute("aria-expanded", "true");
+      const r = glyph.getBoundingClientRect();
+      pop.style.top = `${popoverTop({ glyphTop: r.top, glyphBottom: r.bottom, popHeight: pop.offsetHeight, viewportHeight: window.innerHeight })}px`;
+      pop.style.left = `${Math.max(8, r.left - 8)}px`;
+    },
+    dispose() {
+      document.removeEventListener("click", onDocClick);
+      document.removeEventListener("keydown", onDocKeydown);
+      pop.remove();
+    },
+  };
+}
+
+// Append a focusable ⓘ glyph to `container` that toggles the panel's shared
+// popover with `description` (Markdown). No-op when description is empty.
+export function attachInfo(container, description, info) {
+  if (typeof description !== "string" || !description.trim()) return;
+  const glyph = document.createElement("button");
+  glyph.type = "button";
+  glyph.className = "info";
+  glyph.textContent = "ⓘ";
+  glyph.setAttribute("aria-label", "More info");
+  glyph.setAttribute("aria-expanded", "false");
+  glyph.addEventListener("click", (e) => { e.stopPropagation(); info.toggle(glyph, description); });
+  container.append(glyph);
+}