@obvi/blueprint 1.1.3 → 1.3.0

package/dist/blueprint.js

@@ -9,7 +9,7 @@ function extractRationale(root) {
   if (!node) return null;
   const wrap = node.ownerDocument.createElement("div");
   wrap.className = "bp-choice-rationale";
-  wrap.append(...node.childNodes);
+  wrap.append(...[...node.childNodes].map((child) => child.cloneNode(true)));
   return wrap;
 }
 function bodyWithoutRationale(root) {
@@ -120,6 +120,187 @@ function buildResolvedChoice(doc, { options, verdictKicker, resolvedValue }) {
   root.append(stack);
   return root;
 }
+function buildChoiceManifest(host, layout, options, resolvedValue) {
+  return {
+    id: host.id || host.getAttribute("name") || "",
+    label: host.getAttribute("data-obvious-choice-label") || host.getAttribute("aria-label") || host.getAttribute("name") || host.id || "",
+    layout,
+    resolvedValue,
+    options: options.map((option) => ({
+      value: option.value,
+      label: option.title || option.tab || option.value,
+      title: option.title
+    }))
+  };
+}
+function dispatchChoiceEvent(host, type, detail) {
+  host.dispatchEvent(new CustomEvent(type, { bubbles: true, composed: true, detail }));
+}
+function setChoiceControlsDisabled(root, disabled) {
+  for (const control of root.querySelectorAll("input, button")) {
+    if (control instanceof HTMLInputElement || control instanceof HTMLButtonElement) {
+      control.disabled = disabled;
+    }
+  }
+}
+function appendLockedHostActions(doc, root, state) {
+  const actions = el(doc, "div", "bp-choice__actions");
+  const status = el(doc, "output", "bp-choice__hint");
+  status.setAttribute("aria-live", "polite");
+  status.textContent = state.message;
+  const reset = el(doc, "button", "bp-choice__reset");
+  reset.type = "button";
+  reset.disabled = state.busy;
+  reset.textContent = state.busy ? "Saving…" : state.reconsider;
+  actions.append(status, reset);
+  root.append(actions);
+  return reset;
+}
+function buildInteractiveChoice(doc, source) {
+  const {
+    layout,
+    options,
+    verdictKicker,
+    adoptLabel,
+    hint,
+    reconsider,
+    compareSummary,
+    compareBody,
+    scopeId,
+    initialValue,
+    busy,
+    message
+  } = source;
+  const viewName = `${scopeId}-view`;
+  const pickName = `${scopeId}-pick`;
+  const form = el(doc, "form", `bp-choice bp-choice--${layout}`);
+  form.dataset.bpChoice = scopeId;
+  const titleOpts = options.map((option) => ({ value: option.value, title: option.title }));
+  form.append(buildVerdict(doc, verdictKicker, titleOpts));
+  if (layout === "tabs") {
+    const selectedView = options.some((option) => option.value === initialValue) ? initialValue : options[0]?.value;
+    const seg = el(doc, "div", "bp-choice__seg");
+    seg.setAttribute("role", "tablist");
+    for (const opt of options) {
+      const segOpt = el(doc, "label", "bp-choice__seg-opt");
+      const input = doc.createElement("input");
+      input.type = "radio";
+      input.name = viewName;
+      input.value = opt.value;
+      input.className = "bp-choice__view";
+      if (opt.value === selectedView) {
+        input.defaultChecked = true;
+        input.checked = true;
+      }
+      segOpt.append(input, doc.createTextNode(opt.tab));
+      seg.append(segOpt);
+    }
+    form.append(seg);
+    const panels = el(doc, "div", "bp-choice__panels");
+    for (const opt of options) {
+      const panel = el(doc, "div", "bp-choice__panel");
+      panel.dataset.value = opt.value;
+      const h3 = el(doc, "h3");
+      h3.textContent = opt.title;
+      panel.append(h3);
+      panel.append(bodyWithoutRationale(opt.el));
+      const rationale = extractRationale(opt.el);
+      if (rationale) panel.append(rationale);
+      const actions = el(doc, "div", "bp-choice__actions");
+      const adopt = el(doc, "label", "bp-choice__adopt");
+      const commit = doc.createElement("input");
+      commit.type = "radio";
+      commit.name = pickName;
+      commit.value = opt.value;
+      commit.className = "bp-choice__commit";
+      adopt.append(commit, doc.createTextNode(adoptLabel));
+      actions.append(adopt);
+      panel.append(actions);
+      panels.append(panel);
+    }
+    form.append(panels);
+    const style = el(doc, "style");
+    style.textContent = scopedTabRules(`[data-bp-choice="${scopeId}"]`, viewName, pickName, titleOpts);
+    form.prepend(style);
+    form.append(buildFooter(doc, hint || "Switch tabs to preview · adopt to commit", reconsider));
+  }
+  if (layout === "stack") {
+    const stack = el(doc, "div", "bp-choice__stack");
+    for (const opt of options) {
+      const card = el(doc, "label", "bp-choice__card");
+      const input = doc.createElement("input");
+      input.type = "radio";
+      input.name = pickName;
+      input.value = opt.value;
+      input.className = "bp-choice__pick";
+      card.append(input);
+      const head = el(doc, "div", "bp-choice__card-head");
+      if (opt.optionLabel) head.append(label(doc, opt.optionLabel));
+      const chosen = el(doc, "span", "bp-choice__tag bp-choice__tag--ink bp-choice__card-chosen");
+      chosen.textContent = "✓ Chosen";
+      const rejected = el(doc, "span", "bp-choice__tag bp-choice__tag--out bp-choice__card-rejected");
+      rejected.textContent = "Not chosen";
+      head.append(chosen, rejected);
+      card.append(head);
+      const h4 = el(doc, "h4");
+      h4.textContent = opt.title;
+      card.append(h4);
+      card.append(bodyWithoutRationale(opt.el));
+      const rationale = extractRationale(opt.el);
+      if (rationale) card.append(rationale);
+      stack.append(card);
+    }
+    form.append(stack);
+    form.append(buildFooter(doc, hint || "Select a card to commit · rejected drafts stay readable below", reconsider));
+  }
+  if (layout === "gallery") {
+    const gallery = el(doc, "div", "bp-choice__gallery");
+    for (const opt of options) {
+      const mock = el(doc, "label", "bp-choice__mock");
+      const input = doc.createElement("input");
+      input.type = "radio";
+      input.name = pickName;
+      input.value = opt.value;
+      input.className = "bp-choice__pick";
+      mock.append(input);
+      const frame = el(doc, "div", "bp-choice__mock-frame");
+      const frameInner = frameContent(opt.el);
+      if (frameInner) frame.append(frameInner);
+      mock.append(frame);
+      const cap = el(doc, "div", "bp-choice__mock-cap");
+      const h4 = el(doc, "h4");
+      h4.textContent = opt.caption;
+      cap.append(h4);
+      const chosen = el(doc, "span", "bp-choice__tag bp-choice__tag--ink bp-choice__mock-pick bp-choice__mock-chosen");
+      chosen.textContent = "✓ Chosen";
+      const rejected = el(doc, "span", "bp-choice__tag bp-choice__tag--out bp-choice__mock-pick bp-choice__mock-rejected");
+      rejected.textContent = "Not chosen";
+      cap.append(chosen, rejected);
+      mock.append(cap);
+      gallery.append(mock);
+    }
+    form.append(gallery);
+    if (compareSummary && compareBody) {
+      const details = el(doc, "details", "bp-choice__compare");
+      const summary = el(doc, "summary");
+      summary.textContent = compareSummary;
+      details.append(summary);
+      const body = el(doc, "div", "bp-choice__compare-body");
+      body.append(compareBody.cloneNode(true));
+      details.append(body);
+      form.append(details);
+    }
+    form.append(buildFooter(doc, hint || "Select a mockup to track the decision", reconsider));
+  }
+  if (message) {
+    const status = el(doc, "output", "bp-choice__hint");
+    status.setAttribute("aria-live", "polite");
+    status.textContent = message;
+    form.append(status);
+  }
+  setChoiceControlsDisabled(form, busy);
+  return form;
+}
 var BlueprintRationaleElement = class extends HTMLElement {
   connectedCallback() {
     if (this.dataset.bpRendered) return;
@@ -130,158 +311,104 @@ var BlueprintRationaleElement = class extends HTMLElement {
 var BlueprintChoiceOptionElement = class extends HTMLElement {
 };
 var BlueprintChoiceElement = class extends HTMLElement {
+  constructor() {
+    super();
+    this.choiceSource = null;
+    this.choiceHostState = null;
+    this.choiceScopeId = null;
+  }
   connectedCallback() {
-    if (this.dataset.bpRendered) return;
+    if (this.choiceSource) return;
     this.dataset.bpRendered = "1";
-    const doc = this.ownerDocument;
     const layout = (this.getAttribute("layout") || "stack").toLowerCase();
-    const verdictKicker = this.getAttribute("verdict") ?? "Chosen";
-    const adoptLabel = this.getAttribute("adopt") ?? "Adopt this direction";
-    const hint = this.getAttribute("hint") ?? "";
-    const reconsider = this.getAttribute("reconsider") ?? "Reconsider";
-    const compareSummary = this.getAttribute("compare");
-    const compareBody = this.querySelector(':scope > [slot="compare"]');
-    const options = readOptions(this);
-    const resolvedValue = this.getAttribute("resolved");
-    if (resolvedValue !== null) {
-      this.replaceChildren(buildResolvedChoice(doc, { options, verdictKicker, resolvedValue }));
-      return;
-    }
-    const scopeId = nextId("bp-choice");
-    const viewName = `${scopeId}-view`;
-    const pickName = `${scopeId}-pick`;
-    const form = el(doc, "form", `bp-choice bp-choice--${layout}`);
-    form.dataset.bpChoice = scopeId;
-    const titleOpts = options.map((o) => ({ value: o.value, title: o.title }));
-    form.append(buildVerdict(doc, verdictKicker, titleOpts));
-    if (layout === "tabs") {
-      const seg = el(doc, "div", "bp-choice__seg");
-      seg.setAttribute("role", "tablist");
-      for (const [index, opt] of options.entries()) {
-        const segOpt = el(doc, "label", "bp-choice__seg-opt");
-        const input = doc.createElement("input");
-        input.type = "radio";
-        input.name = viewName;
-        input.value = opt.value;
-        input.className = "bp-choice__view";
-        if (index === 0) {
-          input.defaultChecked = true;
-          input.checked = true;
-        }
-        segOpt.append(input, doc.createTextNode(opt.tab));
-        seg.append(segOpt);
-      }
-      form.append(seg);
-      const panels = el(doc, "div", "bp-choice__panels");
-      for (const opt of options) {
-        const panel = el(doc, "div", "bp-choice__panel");
-        panel.dataset.value = opt.value;
-        const h3 = el(doc, "h3");
-        h3.textContent = opt.title;
-        panel.append(h3);
-        panel.append(bodyWithoutRationale(opt.el));
-        const rationale = extractRationale(opt.el);
-        if (rationale) panel.append(rationale);
-        const actions = el(doc, "div", "bp-choice__actions");
-        const adopt = el(doc, "label", "bp-choice__adopt");
-        const commit = doc.createElement("input");
-        commit.type = "radio";
-        commit.name = pickName;
-        commit.value = opt.value;
-        commit.className = "bp-choice__commit";
-        adopt.append(commit, doc.createTextNode(adoptLabel));
-        actions.append(adopt);
-        panel.append(actions);
-        panels.append(panel);
-      }
-      form.append(panels);
-      const style = el(doc, "style");
-      style.textContent = scopedTabRules(`[data-bp-choice="${scopeId}"]`, viewName, pickName, titleOpts);
-      form.prepend(style);
-      form.append(
-        buildFooter(
-          doc,
-          hint || "Switch tabs to preview · adopt to commit",
-          reconsider
-        )
-      );
-    }
-    if (layout === "stack") {
-      const stack = el(doc, "div", "bp-choice__stack");
-      for (const opt of options) {
-        const card = el(doc, "label", "bp-choice__card");
-        const input = doc.createElement("input");
-        input.type = "radio";
-        input.name = pickName;
-        input.value = opt.value;
-        input.className = "bp-choice__pick";
-        card.append(input);
-        const head = el(doc, "div", "bp-choice__card-head");
-        if (opt.optionLabel) head.append(label(doc, opt.optionLabel));
-        const chosen = el(doc, "span", "bp-choice__tag bp-choice__tag--ink bp-choice__card-chosen");
-        chosen.textContent = "✓ Chosen";
-        const rejected = el(doc, "span", "bp-choice__tag bp-choice__tag--out bp-choice__card-rejected");
-        rejected.textContent = "Not chosen";
-        head.append(chosen, rejected);
-        card.append(head);
-        const h4 = el(doc, "h4");
-        h4.textContent = opt.title;
-        card.append(h4);
-        card.append(bodyWithoutRationale(opt.el));
-        const rationale = extractRationale(opt.el);
-        if (rationale) card.append(rationale);
-        stack.append(card);
-      }
-      form.append(stack);
-      form.append(
-        buildFooter(
-          doc,
-          hint || "Select a card to commit · rejected drafts stay readable below",
-          reconsider
-        )
-      );
-    }
-    if (layout === "gallery") {
-      const gallery = el(doc, "div", "bp-choice__gallery");
-      for (const opt of options) {
-        const mock = el(doc, "label", "bp-choice__mock");
-        const input = doc.createElement("input");
-        input.type = "radio";
-        input.name = pickName;
-        input.value = opt.value;
-        input.className = "bp-choice__pick";
-        mock.append(input);
-        const frame = el(doc, "div", "bp-choice__mock-frame");
-        const frameInner = frameContent(opt.el);
-        if (frameInner) frame.append(frameInner);
-        mock.append(frame);
-        const cap = el(doc, "div", "bp-choice__mock-cap");
-        const h4 = el(doc, "h4");
-        h4.textContent = opt.caption;
-        cap.append(h4);
-        const chosen = el(doc, "span", "bp-choice__tag bp-choice__tag--ink bp-choice__mock-pick bp-choice__mock-chosen");
-        chosen.textContent = "✓ Chosen";
-        const rejected = el(doc, "span", "bp-choice__tag bp-choice__tag--out bp-choice__mock-pick bp-choice__mock-rejected");
-        rejected.textContent = "Not chosen";
-        cap.append(chosen, rejected);
-        mock.append(cap);
-        gallery.append(mock);
-      }
-      form.append(gallery);
-      if (compareSummary && compareBody) {
-        const details = el(doc, "details", "bp-choice__compare");
-        const summary = el(doc, "summary");
-        summary.textContent = compareSummary;
-        details.append(summary);
-        const body = el(doc, "div", "bp-choice__compare-body");
-        body.append(compareBody.cloneNode(true));
-        details.append(body);
-        form.append(details);
+    this.choiceSource = {
+      layout,
+      options: readOptions(this),
+      verdictKicker: this.getAttribute("verdict") ?? "Chosen",
+      adoptLabel: this.getAttribute("adopt") ?? "Adopt this direction",
+      hint: this.getAttribute("hint") ?? "",
+      reconsider: this.getAttribute("reconsider") ?? "Reconsider",
+      compareSummary: this.getAttribute("compare"),
+      compareBody: this.querySelector(':scope > [slot="compare"]'),
+      resolvedValue: this.getAttribute("resolved")
+    };
+    this.choiceScopeId = nextId("bp-choice");
+    this.renderChoice();
+    dispatchChoiceEvent(this, "bp-choice-ready", this.getDecisionManifest());
+  }
+  getDecisionManifest() {
+    if (!this.choiceSource) return null;
+    return buildChoiceManifest(
+      this,
+      this.choiceSource.layout,
+      this.choiceSource.options,
+      this.choiceSource.resolvedValue
+    );
+  }
+  /**
+   * Apply ephemeral host-owned state without mutating authored attributes.
+   * Passing null restores the authored open/resolved rendering.
+   *
+   * @param {{ status: 'open' | 'locked', value: string | null, busy?: boolean, message?: string } | null} state
+   */
+  applyDecisionState(state) {
+    if (!this.choiceSource) return false;
+    if (state !== null) {
+      const valueExists = state.value === null || this.choiceSource.options.some((option) => option.value === state.value);
+      if (state.status !== "open" && state.status !== "locked" || !valueExists) return false;
+      if (state.status === "locked" && state.value === null) return false;
+    }
+    this.choiceHostState = state ? { status: state.status, value: state.value, busy: Boolean(state.busy), message: state.message ?? "" } : null;
+    this.renderChoice();
+    return true;
+  }
+  renderChoice() {
+    if (!this.choiceSource || !this.choiceScopeId) return;
+    const source = this.choiceSource;
+    const hostState = this.choiceHostState;
+    const lockedValue = hostState?.status === "locked" ? hostState.value : hostState ? null : source.resolvedValue;
+    if (lockedValue !== null) {
+      const root = buildResolvedChoice(this.ownerDocument, {
+        options: source.options,
+        verdictKicker: source.verdictKicker,
+        resolvedValue: lockedValue
+      });
+      if (hostState) {
+        const reset = appendLockedHostActions(this.ownerDocument, root, {
+          message: hostState.message,
+          reconsider: source.reconsider,
+          busy: hostState.busy
+        });
+        reset.addEventListener("click", () => {
+          dispatchChoiceEvent(this, "bp-choice-reconsider", this.getDecisionManifest());
+        });
       }
-      form.append(
-        buildFooter(doc, hint || "Select a mockup to track the decision", reconsider)
-      );
+      this.replaceChildren(root);
+      return;
     }
+    const form = buildInteractiveChoice(this.ownerDocument, {
+      ...source,
+      scopeId: this.choiceScopeId,
+      initialValue: hostState?.value ?? null,
+      busy: hostState?.busy ?? false,
+      message: hostState?.message ?? ""
+    });
+    form.addEventListener("change", (event) => {
+      const input = event.target;
+      if (!(input instanceof HTMLInputElement) || !input.checked) return;
+      const isCommit = source.layout === "tabs" ? input.classList.contains("bp-choice__commit") : input.classList.contains("bp-choice__pick");
+      if (!isCommit) return;
+      const option = source.options.find((candidate) => candidate.value === input.value);
+      if (!option) return;
+      dispatchChoiceEvent(this, "bp-choice-commit", {
+        ...this.getDecisionManifest(),
+        value: option.value,
+        option: { value: option.value, label: option.title || option.tab || option.value, title: option.title }
+      });
+    });
+    form.addEventListener("reset", () => {
+      dispatchChoiceEvent(this, "bp-choice-reconsider", this.getDecisionManifest());
+    });
     this.replaceChildren(form);
   }
 };
@@ -756,11 +883,31 @@ function injectSidebar(doc, win) {
   searchHint.append(searchHintCmd, searchHintKey);
   searchField.append(searchIcon, searchLabel, searchHint);
   search.append(searchField);
-  panel.append(search);
   const switcher = buildDocSwitcher(doc, win);
-  if (switcher) panel.append(switcher);
+  const tocSwitcher = doc.createElement("details");
+  tocSwitcher.className = "bp-toc-switcher";
+  tocSwitcher.open = true;
+  const tocSummary = doc.createElement("summary");
+  tocSummary.className = "bp-toc-switcher__current sidebar-field";
+  tocSummary.setAttribute("aria-label", "Jump to section");
+  const tocLabel = doc.createElement("span");
+  tocLabel.className = "bp-toc-switcher__label";
+  const tocTitle = doc.createElement("span");
+  tocTitle.className = "bp-toc-switcher__title";
+  tocTitle.textContent = "Contents";
+  tocLabel.append(tocTitle);
+  const tocChevron = doc.createElement("span");
+  tocChevron.className = "bp-toc-switcher__chevron bp-transition-transform bp-duration-normal bp-ease-in-out";
+  tocChevron.setAttribute("aria-hidden", "true");
+  tocChevron.append(createChromeSvg(doc, DOC_CHEVRON_ICON));
+  tocSummary.append(tocLabel, tocChevron);
   const list = doc.createElement("ul");
-  panel.append(list);
+  tocSwitcher.append(tocSummary, list);
+  const mobileHead = doc.createElement("div");
+  mobileHead.className = "sidebar-mobile-head";
+  mobileHead.append(tocSwitcher, search);
+  panel.append(mobileHead);
+  if (switcher) panel.append(switcher);
   nav.append(panel, buildSidebarFooter(doc));
   return nav;
 }
@@ -834,6 +981,7 @@ function setThemeAnimated(doc, win, theme) {
       transition = doc.startViewTransition(runUpdate);
     }
     if (!applied) runUpdate();
+    transition?.ready?.catch(clearSwitching);
     if (transition?.finished) {
       transition.finished.finally(clearSwitching).catch(clearSwitching);
     } else {
@@ -931,14 +1079,14 @@ function wireSearchPalette(doc, win) {
   let panel = null;
   let input = null;
   let results = null;
-  let footStatus = null;
+  let actionDefs = [];
   let entries = [];
   let visible = [];
   let selected = 0;
   let returnFocus = null;
   let prevOverflow = "";
   const collectEntries = () => {
-    const list = doc.querySelector(".bp-sidebar .bp-sidebar__panel > ul") ?? doc.querySelector(".bp-toc > ul");
+    const list = doc.querySelector(".bp-sidebar .bp-sidebar__panel .bp-toc-switcher > ul") ?? doc.querySelector(".bp-sidebar .bp-sidebar__panel > ul") ?? doc.querySelector(".bp-toc > ul");
     if (!list) return [];
     const out = [];
     let group = "";
@@ -961,16 +1109,57 @@ function wireSearchPalette(doc, win) {
     }
     return out;
   };
-  const keyHint = (caps, labelText) => {
-    const span = doc.createElement("span");
-    span.className = "docs-search__key";
-    for (const cap of caps) {
-      const kbd = doc.createElement("kbd");
-      kbd.textContent = cap;
-      span.append(kbd);
-    }
-    span.append(doc.createTextNode(` ${labelText}`));
-    return span;
+  const modGlyph = isMacLike ? "⌘" : "⌃";
+  const matchesShortcut = (event, key) => {
+    const mod = isMacLike ? event.metaKey : event.ctrlKey;
+    if (!mod || !event.shiftKey) return false;
+    return event.key.toLowerCase() === key.toLowerCase();
+  };
+  const buildActionDefs = () => {
+    const defs = [];
+    if (doc.querySelector(".theme-toggle")) {
+      defs.push({
+        label: "Toggle theme",
+        icon: THEME_MOON_ICON,
+        chip: `${modGlyph}⇧L`,
+        shortcut: "l",
+        run: () => doc.querySelector(".theme-toggle")?.click()
+      });
+    }
+    if (doc.querySelector(".sidebar-toggle")) {
+      defs.push({
+        label: "Toggle sidebar",
+        icon: SIDEBAR_COLLAPSE_ICON,
+        chip: `${modGlyph}⇧B`,
+        shortcut: "b",
+        run: () => doc.querySelector(".sidebar-toggle")?.click()
+      });
+    }
+    return defs;
+  };
+  const buildAction = (def) => {
+    const button = doc.createElement("button");
+    button.type = "button";
+    button.className = "docs-search__action bp-transition-colors bp-ease";
+    const icon = createChromeSvg(doc, def.icon, 16);
+    icon.classList.add("docs-search__action-icon");
+    const label2 = doc.createElement("span");
+    label2.className = "docs-search__action-label";
+    label2.textContent = def.label;
+    button.append(icon, label2);
+    if (def.chip) {
+      const chip = doc.createElement("kbd");
+      chip.className = "docs-search__chip";
+      for (const glyph of Array.from(def.chip)) {
+        const key = doc.createElement("span");
+        key.textContent = glyph;
+        chip.append(key);
+      }
+      button.append(chip);
+    }
+    button.addEventListener("click", () => def.run(button));
+    def.button = button;
+    return button;
   };
   const highlight = (text, q) => {
     if (!q) return [doc.createTextNode(text)];
@@ -1000,6 +1189,11 @@ function wireSearchPalette(doc, win) {
     });
     const mainCol = doc.createElement("span");
     mainCol.className = "docs-search__row-main";
+    const iconBox = doc.createElement("span");
+    iconBox.className = "docs-search__icon-box";
+    iconBox.setAttribute("aria-hidden", "true");
+    iconBox.textContent = "#";
+    mainCol.append(iconBox);
     if (entry.crumb) {
       const crumb = doc.createElement("span");
       crumb.className = "docs-search__crumb";
@@ -1008,11 +1202,7 @@ function wireSearchPalette(doc, win) {
     }
     const title = doc.createElement("span");
     title.className = "docs-search__title";
-    const hash = doc.createElement("span");
-    hash.className = "docs-search__hash";
-    hash.setAttribute("aria-hidden", "true");
-    hash.textContent = "#";
-    title.append(hash, ...highlight(entry.title, q));
+    title.append(...highlight(entry.title, q));
     mainCol.append(title);
     const enter = doc.createElement("kbd");
     enter.className = "docs-search__enter";
@@ -1020,19 +1210,22 @@ function wireSearchPalette(doc, win) {
     row.append(mainCol, enter);
     return row;
   };
-  const buildEmpty = (query) => {
+  const buildEmpty = () => {
     const wrap = doc.createElement("div");
     wrap.className = "docs-search__empty";
-    const iconWrap = doc.createElement("span");
-    iconWrap.className = "docs-search__empty-icon";
-    iconWrap.append(createChromeSvg(doc, SEARCH_ICON, 28));
-    const title = doc.createElement("span");
+    const center = doc.createElement("div");
+    center.className = "docs-search__empty-center";
+    const copy = doc.createElement("div");
+    copy.className = "docs-search__empty-copy";
+    const title = doc.createElement("p");
     title.className = "docs-search__empty-title";
-    title.textContent = `No results for “${(query || "").trim()}”`;
-    const note = doc.createElement("span");
+    title.textContent = "No results found";
+    const note = doc.createElement("p");
     note.className = "docs-search__empty-note";
-    note.textContent = "Try a different term, or check your spelling.";
-    wrap.append(iconWrap, title, note);
+    note.textContent = "Try searching with different keywords";
+    copy.append(title, note);
+    center.append(copy);
+    wrap.append(center);
     return wrap;
   };
   const applySelection = () => {
@@ -1060,8 +1253,7 @@ function wireSearchPalette(doc, win) {
     selected = 0;
     results.replaceChildren();
     if (visible.length === 0) {
-      results.append(buildEmpty(query));
-      footStatus.textContent = "0 results";
+      results.append(buildEmpty());
       input.removeAttribute("aria-activedescendant");
       return;
     }
@@ -1075,9 +1267,14 @@ function wireSearchPalette(doc, win) {
     results.append(group);
     visible.forEach((entry, index) => results.append(buildRow(entry, index, q)));
     applySelection();
-    footStatus.textContent = q ? `${visible.length} result${visible.length === 1 ? "" : "s"}` : "Jump to a section";
   };
   const onKeydown = (event) => {
+    const action = actionDefs.find((def) => matchesShortcut(event, def.shortcut));
+    if (action) {
+      event.preventDefault();
+      action.run(action.button);
+      return;
+    }
     if (event.key === "Escape") {
       event.preventDefault();
       close();
@@ -1088,6 +1285,7 @@ function wireSearchPalette(doc, win) {
       event.preventDefault();
       move(-1);
     } else if (event.key === "Enter") {
+      if (event.target?.closest?.(".docs-search__action")) return;
       const row = results.querySelector(
         `.docs-search__row[data-index="${selected}"]`
       );
@@ -1125,12 +1323,12 @@ function wireSearchPalette(doc, win) {
     input = doc.createElement("input");
     input.className = "docs-search__input";
     input.type = "search";
-    input.placeholder = "Search the docs…";
+    input.placeholder = "Search the blueprint…";
     input.setAttribute("role", "combobox");
     input.setAttribute("aria-autocomplete", "list");
     input.setAttribute("aria-controls", "docs-search-listbox");
     input.setAttribute("aria-expanded", "false");
-    input.setAttribute("aria-label", "Search the docs");
+    input.setAttribute("aria-label", "Search the blueprint");
     input.autocomplete = "off";
     input.spellcheck = false;
     const esc = doc.createElement("span");
@@ -1144,15 +1342,11 @@ function wireSearchPalette(doc, win) {
     results.setAttribute("aria-label", "Search results");
     const foot = doc.createElement("div");
     foot.className = "docs-search__foot";
-    footStatus = doc.createElement("span");
-    const keys = doc.createElement("span");
-    keys.className = "docs-search__keys";
-    keys.append(
-      keyHint(["↑", "↓"], "navigate"),
-      keyHint(["↵"], "open"),
-      keyHint(["esc"], "close")
-    );
-    foot.append(footStatus, keys);
+    const actions = doc.createElement("div");
+    actions.className = "docs-search__actions";
+    actionDefs = buildActionDefs();
+    for (const def of actionDefs) actions.append(buildAction(def));
+    foot.append(actions);
     panel.append(field, results, foot);
     overlay.append(panel);
     (doc.body || doc.documentElement).append(overlay);
@@ -1393,7 +1587,7 @@ function initializeBlueprintRuntime(doc = document, win = window) {
     if (!list || !listItem) return true;
     const container = link.closest(".bp-sidebar, .bp-toc, .sidebar");
     if (!container) return true;
-    const topList = container.querySelector(":scope > .bp-sidebar__panel > ul") ?? container.querySelector(":scope > ul");
+    const topList = container.querySelector(":scope > .bp-sidebar__panel .bp-toc-switcher > ul") ?? container.querySelector(":scope > .bp-sidebar__panel > ul") ?? container.querySelector(":scope > ul");
     return list === topList;
   };
   const entries = [...doc.querySelectorAll('.bp-sidebar a[href^="#"], .bp-toc a[href^="#"], .sidebar a[href^="#"]')].filter(isPrimaryNavLink).map((link) => ({
@@ -1405,6 +1599,14 @@ function initializeBlueprintRuntime(doc = document, win = window) {
   );
   let scheduled = false;
   let scrollingTo = null;
+  const tocSwitchers = [...doc.querySelectorAll(".bp-toc-switcher")];
+  const tocSwitcherTitles = [...doc.querySelectorAll(".bp-toc-switcher__title")];
+  const railColumnQuery = win.matchMedia("(min-width: 861px)");
+  const syncTocSwitcherOpen = () => {
+    for (const sw of tocSwitchers) sw.open = railColumnQuery.matches;
+  };
+  syncTocSwitcherOpen();
+  railColumnQuery.addEventListener("change", syncTocSwitcherOpen);
   const placeMarker = (link) => {
     const container = link.closest(".bp-sidebar, .bp-toc, .sidebar");
     const list = container?.querySelector(":scope > ul") ?? container?.querySelector("ul");
@@ -1412,18 +1614,59 @@ function initializeBlueprintRuntime(doc = document, win = window) {
     list.style.setProperty("--bp-toc-y", `${link.offsetTop}px`);
     list.style.setProperty("--bp-toc-h", `${link.offsetHeight}px`);
   };
+  const revealInRail = (link) => {
+    const panel = link.closest(".bp-sidebar__panel");
+    if (!panel || panel.scrollHeight <= panel.clientHeight) return;
+    const style = win.getComputedStyle(panel);
+    const padTop = Number.parseFloat(style.scrollPaddingTop) || 0;
+    const padBottom = Number.parseFloat(style.scrollPaddingBottom) || 0;
+    const panelRect = panel.getBoundingClientRect();
+    const linkRect = link.getBoundingClientRect();
+    const safeTop = panelRect.top + padTop;
+    const safeBottom = panelRect.bottom - padBottom;
+    let delta = 0;
+    if (linkRect.top < safeTop) delta = linkRect.top - safeTop;
+    else if (linkRect.bottom > safeBottom) delta = linkRect.bottom - safeBottom;
+    if (delta === 0) return;
+    panel.scrollBy({
+      top: delta,
+      behavior: prefersReducedMotion() ? "auto" : "smooth"
+    });
+  };
+  let lastCurrent = null;
   const setCurrent = (section) => {
+    const changed = section !== lastCurrent;
+    let activeLabel = "";
     for (const item of entries) {
       if (section && item.section === section) {
         item.link.setAttribute("aria-current", "location");
         placeMarker(item.link);
+        if (changed) revealInRail(item.link);
+        if (!activeLabel) activeLabel = item.link.textContent.trim();
       } else {
         item.link.removeAttribute("aria-current");
       }
     }
+    lastCurrent = section;
+    if (changed) {
+      const summaryLabel = activeLabel || "Contents";
+      for (const title of tocSwitcherTitles) title.textContent = summaryLabel;
+    }
+  };
+  const mobileHead = doc.querySelector(".sidebar-mobile-head");
+  const contentsRail = doc.querySelector("#bp-contents-rail");
+  const syncHeadDivider = () => {
+    if (!mobileHead || !contentsRail) return;
+    if (win.getComputedStyle(mobileHead).position !== "fixed") {
+      mobileHead.removeAttribute("data-bp-head-stuck");
+      return;
+    }
+    const stuck = contentsRail.getBoundingClientRect().bottom <= mobileHead.getBoundingClientRect().bottom + 0.5;
+    mobileHead.toggleAttribute("data-bp-head-stuck", stuck);
   };
   const update = () => {
     scheduled = false;
+    syncHeadDivider();
     if (progress) {
       const max = scrollHeight() - clientHeight();
       progress.style.transform = `scaleX(${max > 0 ? scrollTop() / max : 0})`;
@@ -1505,6 +1748,9 @@ function initializeBlueprintRuntime(doc = document, win = window) {
     event.preventDefault();
     if (win.location.hash !== link.hash) win.history.pushState(null, "", link.hash);
     if (entries.some(({ section: target }) => target === section)) setCurrent(section);
+    if (!railColumnQuery.matches) {
+      for (const sw of tocSwitchers) sw.open = false;
+    }
     scrollToSection(section);
   });
   let scrollSource = shellScroller ?? win;
@@ -1765,7 +2011,7 @@ function renderContentsTree(doc, tree) {
 function findSidebarNavLists(doc) {
   const lists = [];
   for (const nav of doc.querySelectorAll(".bp-sidebar:not([data-bp-nav-manual])")) {
-    const list = nav.querySelector(":scope > .bp-sidebar__panel > ul") ?? nav.querySelector(":scope > ul");
+    const list = nav.querySelector(":scope > .bp-sidebar__panel .bp-toc-switcher > ul") ?? nav.querySelector(":scope > .bp-sidebar__panel > ul") ?? nav.querySelector(":scope > ul");
     if (list) lists.push(list);
   }
   for (const nav of doc.querySelectorAll(".bp-toc:not([data-bp-nav-manual])")) {