@obvi/blueprint 1.0.10 → 1.1.1

package/dist/blueprint.js

@@ -1,3 +1,950 @@
+// Document chrome — site nav, reading progress, contents rail, and footer
+// metadata are injected at runtime so authored pages stay semantic (<main> only).
+// Chrome glyphs are Iconoir (MIT) line icons, stored as raw path data and
+// drawn at runtime so the framework ships zero icon-pack dependencies. Each
+// stroke inherits currentColor, so the ink-scale tokens theme them for free.
+const SIDEBAR_COLLAPSE_ICON = [
+  'M19 21L5 21C3.89543 21 3 20.1046 3 19L3 5C3 3.89543 3.89543 3 5 3L19 3C20.1046 3 21 3.89543 21 5L21 19C21 20.1046 20.1046 21 19 21Z',
+  'M7.25 10L5.5 12L7.25 14',
+  'M9.5 21V3',
+]
+const SIDEBAR_EXPAND_ICON = [
+  'M19 21L5 21C3.89543 21 3 20.1046 3 19L3 5C3 3.89543 3.89543 3 5 3L19 3C20.1046 3 21 3.89543 21 5L21 19C21 20.1046 20.1046 21 19 21Z',
+  'M9.5 21V3',
+  'M5.5 10L7.25 12L5.5 14',
+]
+const SEARCH_ICON = [
+  'M3 11C3 15.4183 6.58172 19 11 19C13.213 19 15.2161 18.1015 16.6644 16.6493C18.1077 15.2022 19 13.2053 19 11C19 6.58172 15.4183 3 11 3C6.58172 3 3 6.58172 3 11Z',
+  'M17 17L21 21',
+]
+const DOC_CHEVRON_ICON = 'M6 9L12 15L18 9'
+const THEME_MOON_ICON =
+  'M3 11.5066C3 16.7497 7.25034 21 12.4934 21C16.2209 21 19.4466 18.8518 21 15.7259C12.4934 15.7259 8.27411 11.5066 8.27411 3C5.14821 4.55344 3 7.77915 3 11.5066Z'
+const THEME_BULB_ICON = [
+  'M9 18H15',
+  'M10 21H14',
+  'M9.00082 15C9.00098 13 8.50098 12.5 7.50082 11.5C6.50067 10.5 6.02422 9.48689 6.00082 8C5.95284 4.95029 8.00067 3 12.0008 3C16.001 3 18.0488 4.95029 18.0008 8C17.9774 9.48689 17.5007 10.5 16.5008 11.5C15.501 12.5 15.001 13 15.0008 15',
+]
+const BLUEPRINT_LOGO_OUTLINE =
+  'M7.3 19H12.7C14.3802 19 15.2202 19 15.862 18.673C16.4265 18.3854 16.8854 17.9265 17.173 17.362C17.5 16.7202 17.5 15.8802 17.5 14.2V9.1075C17.5 8.3982 17.5 8.04355 17.4222 7.70852C17.3531 7.41144 17.2392 7.12663 17.0843 6.86389C16.9096 6.56761 16.665 6.31078 16.1759 5.79716L13.0259 2.48966C12.5028 1.94045 12.2413 1.66585 11.9324 1.46921C11.6585 1.29489 11.3582 1.16618 11.0431 1.08809C10.6876 1 10.3084 1 9.55 1H7.3C5.61984 1 4.77976 1 4.13803 1.32698C3.57354 1.6146 3.1146 2.07354 2.82698 2.63803C2.5 3.27976 2.5 4.11984 2.5 5.8V14.2C2.5 15.8802 2.5 16.7202 2.82698 17.362C3.1146 17.9265 3.57354 18.3854 4.13803 18.673C4.77976 19 5.61984 19 7.3 19Z'
+const BLUEPRINT_LOGO_FILL = 'M16 16H5V6L16 16ZM6.5 14.5H11.5L6.5 9.5V14.5Z'
+
+function metaSelector({ name, property } = {}) {
+  if (property) return `meta[property="${property}"]`
+  if (name) return `meta[name="${name}"]`
+  return null
+}
+
+function readMetaContent(doc, target) {
+  const selector = metaSelector(target)
+  return selector ? doc.querySelector(selector)?.content?.trim() ?? '' : ''
+}
+
+function readMetaContentAll(doc, target) {
+  const selector = metaSelector(target)
+  if (!selector) return []
+  return [...doc.querySelectorAll(selector)]
+    .map((meta) => meta.content?.trim())
+    .filter(Boolean)
+}
+
+function readMetaJson(doc, name) {
+  const raw = readMetaContent(doc, { name })
+  if (!raw) return null
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+function formatPublishedDate(iso) {
+  if (!iso) return null
+  const day = iso.includes('T') ? iso.split('T')[0] : iso
+  const date = new Date(day.includes('T') ? day : `${day}T12:00:00`)
+  if (Number.isNaN(date.getTime())) return null
+  return {
+    iso: day,
+    label: date.toLocaleDateString(undefined, {
+      day: 'numeric',
+      month: 'long',
+      year: 'numeric',
+      timeZone: 'UTC',
+    }),
+  }
+}
+
+function pageBasename(href, win) {
+  try {
+    return new URL(href, win.location.href).pathname.split('/').pop() || 'index.html'
+  } catch {
+    return href.split('/').pop() || 'index.html'
+  }
+}
+
+function isCurrentHref(href, win) {
+  const current = win.location.pathname.split('/').pop() || 'index.html'
+  return pageBasename(href, win) === current
+}
+
+function createChromeSvg(doc, pathD, size = 16) {
+  const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('fill', 'none')
+  svg.setAttribute('stroke', 'currentColor')
+  svg.setAttribute('stroke-width', '1.5')
+  svg.setAttribute('stroke-linecap', 'round')
+  svg.setAttribute('stroke-linejoin', 'round')
+  svg.setAttribute('width', String(size))
+  svg.setAttribute('height', String(size))
+  svg.setAttribute('aria-hidden', 'true')
+  for (const d of Array.isArray(pathD) ? pathD : [pathD]) {
+    const path = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
+    path.setAttribute('d', d)
+    svg.append(path)
+  }
+  return svg
+}
+
+function createBlueprintLogo(doc) {
+  const svg = createChromeSvg(doc, BLUEPRINT_LOGO_OUTLINE, 20)
+  svg.setAttribute('viewBox', '0 0 20 20')
+  svg.classList.add('site-nav__logo')
+  const fill = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
+  fill.setAttribute('d', BLUEPRINT_LOGO_FILL)
+  fill.setAttribute('fill', 'currentColor')
+  fill.setAttribute('stroke', 'none')
+  svg.append(fill)
+  return svg
+}
+
+function injectScrollProgress(doc) {
+  if (doc.querySelector('.scroll-progress')) return null
+  const bar = doc.createElement('div')
+  bar.className = 'scroll-progress'
+  bar.setAttribute('aria-hidden', 'true')
+  return bar
+}
+
+function injectSiteNav(doc, win) {
+  if (doc.querySelector('.site-nav')) return null
+  const links = readMetaJson(doc, 'bp:site-nav')
+  if (!links?.length) return null
+
+  const nav = doc.createElement('nav')
+  nav.className = 'site-nav'
+  nav.setAttribute('aria-label', 'Site')
+
+  const brandLabel =
+    readMetaContent(doc, { property: 'og:site_name' }) ||
+    doc.title.split('—')[0]?.trim() ||
+    'Home'
+  const brandHref = readMetaContent(doc, { name: 'bp:site-home' }) || 'index.html'
+
+  const brand = doc.createElement('a')
+  brand.className = 'site-nav__brand'
+  brand.href = brandHref
+  brand.setAttribute('aria-label', `${brandLabel} home`)
+
+  const logo = createBlueprintLogo(doc)
+
+  const wordmark = doc.createElement('span')
+  wordmark.className = 'site-nav__wordmark'
+  wordmark.textContent = brandLabel
+
+  brand.append(logo, wordmark)
+
+  const list = doc.createElement('ul')
+  list.className = 'site-nav__links'
+
+  for (const item of links) {
+    const li = doc.createElement('li')
+    const link = doc.createElement('a')
+    link.href = item.href
+    link.textContent = item.label
+    if (item.current || isCurrentHref(item.href, win)) {
+      link.setAttribute('aria-current', 'page')
+    }
+    li.append(link)
+    list.append(li)
+  }
+
+  nav.append(brand, list)
+
+  if (readMetaContent(doc, { name: 'bp:site-theme' }) === 'nav') {
+    const theme = doc.createElement('button')
+    theme.className = 'toggle site-nav__theme'
+    theme.type = 'button'
+    theme.id = 'themeToggle'
+    theme.setAttribute('aria-label', 'Toggle light and dark theme')
+    theme.textContent = 'Theme'
+    nav.append(theme)
+  }
+
+  return nav
+}
+
+function injectSidebarToggle(doc) {
+  if (doc.querySelector('.sidebar-toggle')) return null
+  const toggle = doc.createElement('button')
+  toggle.className = 'sidebar-toggle'
+  toggle.type = 'button'
+  toggle.setAttribute('aria-controls', 'bp-contents-rail')
+  toggle.setAttribute('aria-expanded', 'true')
+  toggle.setAttribute('aria-label', 'Hide contents sidebar')
+
+  const icons = doc.createElement('span')
+  icons.className = 'sidebar-toggle__icons'
+  icons.setAttribute('aria-hidden', 'true')
+
+  const collapse = doc.createElement('span')
+  collapse.className =
+    'sidebar-toggle__icon sidebar-toggle__icon--collapse bp-transition-opacity bp-duration-slow bp-ease-in-out'
+  collapse.append(createChromeSvg(doc, SIDEBAR_COLLAPSE_ICON))
+
+  const expand = doc.createElement('span')
+  expand.className =
+    'sidebar-toggle__icon sidebar-toggle__icon--expand bp-transition-opacity bp-duration-slow bp-ease-in-out'
+  expand.append(createChromeSvg(doc, SIDEBAR_EXPAND_ICON))
+
+  icons.append(collapse, expand)
+  toggle.append(icons)
+  return toggle
+}
+
+function buildDocSwitcher(doc, win) {
+  const collections = readMetaJson(doc, 'bp:collections')
+  if (!collections?.length) return null
+
+  const details = doc.createElement('details')
+  details.className = 'doc-switcher'
+
+  const summary = doc.createElement('summary')
+  summary.className = 'doc-switcher__current sidebar-field'
+  summary.setAttribute('aria-label', 'Switch blueprint collection')
+
+  const current =
+    collections.find((item) => item.current || isCurrentHref(item.href, win)) ??
+    collections[0]
+  const collectionMeta = readMetaContent(doc, { name: 'bp:collection-meta' })
+
+  const label = doc.createElement('span')
+  label.className = 'doc-switcher__label'
+
+  const title = doc.createElement('span')
+  title.className = 'doc-switcher__title'
+  title.textContent = current.title
+
+  const meta = doc.createElement('span')
+  meta.className = 'doc-switcher__meta'
+  meta.textContent = collectionMeta || current.desc || ''
+
+  label.append(title)
+  if (meta.textContent) label.append(meta)
+
+  const chevron = doc.createElement('span')
+  chevron.className =
+    'doc-switcher__chevron bp-transition-transform bp-duration-normal bp-ease-in-out'
+  chevron.setAttribute('aria-hidden', 'true')
+  chevron.append(createChromeSvg(doc, DOC_CHEVRON_ICON))
+
+  summary.append(label, chevron)
+
+  const menu = doc.createElement('div')
+  menu.className = 'doc-switcher__menu'
+  menu.setAttribute('role', 'menu')
+
+  for (const item of collections) {
+    const link = doc.createElement('a')
+    link.href = item.href
+    link.setAttribute('role', 'menuitem')
+    if (item.current || isCurrentHref(item.href, win)) {
+      link.className = 'is-current'
+      link.setAttribute('aria-current', 'page')
+    }
+
+    const option = doc.createElement('span')
+    option.className = 'doc-switcher__option'
+
+    const name = doc.createElement('span')
+    name.className = 'doc-switcher__name'
+    name.textContent = item.title
+
+    option.append(name)
+    if (item.desc) {
+      const desc = doc.createElement('span')
+      desc.className = 'doc-switcher__desc'
+      desc.textContent = item.desc
+      option.append(desc)
+    }
+
+    const go = doc.createElement('span')
+    go.className = 'doc-switcher__go bp-transition-opacity'
+    go.setAttribute('aria-hidden', 'true')
+    go.append(createChromeSvg(doc, DOC_CHEVRON_ICON, 14))
+
+    link.append(option, go)
+    menu.append(link)
+  }
+
+  details.append(summary, menu)
+  return details
+}
+
+function buildSidebarFooter(doc) {
+  const footer = doc.createElement('div')
+  footer.className = 'sidebar-footer'
+
+  const theme = doc.createElement('button')
+  theme.className = 'theme-toggle'
+  theme.type = 'button'
+  theme.setAttribute('role', 'switch')
+  theme.setAttribute('aria-checked', 'false')
+  theme.setAttribute('aria-label', 'Switch to dark theme')
+
+  const thumb = doc.createElement('span')
+  thumb.className =
+    'theme-toggle__thumb bp-transition-transform bp-duration-normal bp-ease-in-out'
+  thumb.setAttribute('aria-hidden', 'true')
+
+  const moon = doc.createElement('span')
+  moon.className = 'theme-toggle__icon theme-toggle__icon--moon'
+  moon.setAttribute('aria-hidden', 'true')
+  moon.append(createChromeSvg(doc, THEME_MOON_ICON, 14))
+
+  const bulb = doc.createElement('span')
+  bulb.className = 'theme-toggle__icon theme-toggle__icon--bulb'
+  bulb.setAttribute('aria-hidden', 'true')
+  bulb.append(createChromeSvg(doc, THEME_BULB_ICON, 14))
+
+  theme.append(thumb, moon, bulb)
+
+  const meta = doc.createElement('div')
+  meta.className = 'sidebar-meta'
+
+  const authors = readMetaContentAll(doc, { property: 'article:author' })
+  const published = formatPublishedDate(
+    readMetaContent(doc, { property: 'article:published_time' })
+  )
+
+  if (authors.length) {
+    const item = doc.createElement('div')
+    item.className = 'sidebar-meta__item'
+    const label = doc.createElement('p')
+    label.className = 'bp-meta'
+    label.textContent = authors.length > 1 ? 'Authors' : 'Author'
+    const value = doc.createElement('p')
+    value.className = 'bp-note'
+    value.textContent = authors.join(', ')
+    item.append(label, value)
+    meta.append(item)
+  }
+
+  if (published) {
+    const item = doc.createElement('div')
+    item.className = 'sidebar-meta__item'
+    const label = doc.createElement('p')
+    label.className = 'bp-meta'
+    label.textContent = 'Date'
+    const value = doc.createElement('p')
+    value.className = 'bp-note'
+    const time = doc.createElement('time')
+    time.dateTime = published.iso
+    time.textContent = published.label
+    value.append(time)
+    item.append(label, value)
+    meta.append(item)
+  }
+
+  footer.append(theme)
+  if (meta.childNodes.length) footer.append(meta)
+  return footer
+}
+
+function injectSidebar(doc, win) {
+  if (doc.querySelector('.bp-sidebar')) return null
+
+  const nav = doc.createElement('nav')
+  nav.className = 'bp-sidebar'
+  nav.id = 'bp-contents-rail'
+  nav.setAttribute('aria-label', 'Contents')
+
+  const panel = doc.createElement('div')
+  panel.className = 'bp-sidebar__panel'
+
+  const search = doc.createElement('div')
+  search.className = 'sidebar-search'
+  // The trigger is a button (it opens a dialog, it is not a text field): the
+  // field carries the chrome (border/radius/surface) and the magnifier + ⌘K
+  // hint sit inside it beside the label. Pressing it — or ⌘K / Ctrl+K — opens
+  // the command palette; see wireSearchPalette().
+  const searchField = doc.createElement('button')
+  searchField.type = 'button'
+  searchField.className =
+    'sidebar-search__field sidebar-field bp-transition-colors bp-ease'
+  searchField.setAttribute('aria-haspopup', 'dialog')
+  searchField.setAttribute('aria-keyshortcuts', 'Meta+K Control+K')
+  searchField.setAttribute('aria-label', 'Search (⌘K)')
+  const searchIcon = createChromeSvg(doc, SEARCH_ICON, 14)
+  searchIcon.classList.add('sidebar-search__icon')
+  const searchLabel = doc.createElement('span')
+  searchLabel.className = 'sidebar-search__label'
+  searchLabel.textContent = 'Search'
+  const searchHint = doc.createElement('span')
+  searchHint.className = 'sidebar-search__hint'
+  searchHint.setAttribute('aria-hidden', 'true')
+  const searchHintCmd = doc.createElement('kbd')
+  searchHintCmd.textContent = '⌘'
+  const searchHintKey = doc.createElement('kbd')
+  searchHintKey.textContent = 'K'
+  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 list = doc.createElement('ul')
+  panel.append(list)
+
+  nav.append(panel, buildSidebarFooter(doc))
+  return nav
+}
+
+function syncThemeSwitch(doc, button) {
+  const dark = doc.documentElement.dataset.obviousTheme === 'dark'
+  button.setAttribute('aria-checked', String(dark))
+  button.setAttribute(
+    'aria-label',
+    dark ? 'Switch to light theme' : 'Switch to dark theme'
+  )
+}
+
+// A reader's explicit pick is persisted here so the page reopens in their
+// theme — mirrors the bp-sidebar collapse key.
+const THEME_KEY = 'bp-theme'
+
+function readStoredTheme(win) {
+  try {
+    const value = win.localStorage.getItem(THEME_KEY)
+    return value === 'dark' || value === 'light' ? value : null
+  } catch {
+    return null
+  }
+}
+
+function writeStoredTheme(win, value) {
+  try {
+    win.localStorage.setItem(THEME_KEY, value)
+  } catch {}
+}
+
+function systemPrefersDark(win) {
+  try {
+    return win.matchMedia?.('(prefers-color-scheme: dark)').matches ?? false
+  } catch {
+    return false
+  }
+}
+
+// Opt-in (head meta `bp:theme` = "auto"): when no explicit pick exists the page
+// follows the OS color scheme. Off by default, so an author/bridge-set
+// data-obvious-theme is left untouched.
+function followsSystemTheme(doc) {
+  return readMetaContent(doc, { name: 'bp:theme' }).toLowerCase() === 'auto'
+}
+
+function themePrefersReducedMotion(win) {
+  try {
+    return win.matchMedia('(prefers-reduced-motion: reduce)').matches
+  } catch {
+    return false
+  }
+}
+
+function setTheme(doc, theme) {
+  doc.documentElement.dataset.obviousTheme = theme
+  for (const button of doc.querySelectorAll('.theme-toggle')) {
+    syncThemeSwitch(doc, button)
+  }
+}
+
+// Flip with a single compositor crossfade (View Transitions API). Timing is
+// owned by ::view-transition-* rules in blueprint.css. If the update callback
+// is deferred (some embedded hosts), apply immediately so the toggle never
+// desyncs from persistence; instant when reduced motion is on or VT is missing.
+function setThemeAnimated(doc, win, theme) {
+  const apply = () => setTheme(doc, theme)
+  if (themePrefersReducedMotion(win) || typeof doc.startViewTransition !== 'function') {
+    apply()
+    return
+  }
+  const root = doc.documentElement
+  let applied = false
+  const clearSwitching = () => {
+    delete root.dataset.bpThemeSwitching
+  }
+  const runUpdate = () => {
+    applied = true
+    apply()
+  }
+  root.dataset.bpThemeSwitching = ''
+  try {
+    let transition
+    try {
+      transition = doc.startViewTransition({ update: runUpdate, types: ['bp-theme'] })
+    } catch {
+      transition = doc.startViewTransition(runUpdate)
+    }
+    if (!applied) runUpdate()
+    if (transition?.finished) {
+      transition.finished.finally(clearSwitching).catch(clearSwitching)
+    } else {
+      clearSwitching()
+    }
+  } catch {
+    clearSwitching()
+    apply()
+  }
+}
+
+// Resolve the theme at load: a persisted pick always wins; otherwise, when the
+// page opts into bp:theme=auto, follow the OS scheme. No animation on load.
+function resolveInitialTheme(doc, win) {
+  const stored = readStoredTheme(win)
+  if (stored) {
+    setTheme(doc, stored)
+    return
+  }
+  if (followsSystemTheme(doc)) {
+    setTheme(doc, systemPrefersDark(win) ? 'dark' : 'light')
+  }
+}
+
+function wireThemeToggle(doc, win) {
+  const root = doc.documentElement
+  const toggleTheme = () => {
+    const next = root.dataset.obviousTheme === 'dark' ? 'light' : 'dark'
+    setThemeAnimated(doc, win, next)
+    writeStoredTheme(win, next)
+  }
+
+  for (const button of doc.querySelectorAll('.theme-toggle')) {
+    if (button.dataset.bpThemeWired) continue
+    button.dataset.bpThemeWired = 'true'
+    syncThemeSwitch(doc, button)
+    button.addEventListener('click', toggleTheme)
+  }
+
+  const navTheme = doc.getElementById('themeToggle')
+  if (navTheme && !navTheme.dataset.bpThemeWired) {
+    navTheme.dataset.bpThemeWired = 'true'
+    navTheme.addEventListener('click', toggleTheme)
+  }
+
+  // Track the OS scheme live, but only until the reader makes an explicit pick
+  // (a persisted value), which wins thereafter.
+  if (followsSystemTheme(doc) && win.matchMedia) {
+    const query = win.matchMedia('(prefers-color-scheme: dark)')
+    query.addEventListener?.('change', (event) => {
+      if (readStoredTheme(win)) return
+      setThemeAnimated(doc, win, event.matches ? 'dark' : 'light')
+    })
+  }
+}
+
+function wireSidebarCollapse(doc, win) {
+  const root = doc.documentElement
+  const toggle = doc.querySelector('.sidebar-toggle')
+  if (!toggle || toggle.dataset.bpSidebarWired) return
+  toggle.dataset.bpSidebarWired = 'true'
+
+  const KEY = 'bp-sidebar'
+  const read = () => {
+    try {
+      return win.localStorage.getItem(KEY)
+    } catch {
+      return null
+    }
+  }
+  const write = (value) => {
+    try {
+      win.localStorage.setItem(KEY, value)
+    } catch {}
+  }
+  const apply = (collapsed) => {
+    root.dataset.sidebar = collapsed ? 'collapsed' : 'open'
+    toggle.setAttribute('aria-expanded', String(!collapsed))
+    toggle.setAttribute(
+      'aria-label',
+      collapsed ? 'Show contents sidebar' : 'Hide contents sidebar'
+    )
+  }
+
+  apply(read() === 'collapsed')
+  win.requestAnimationFrame(() => {
+    root.classList.add('bp-sidebar-animate')
+  })
+
+  toggle.addEventListener('click', () => {
+    const collapsed = root.dataset.sidebar !== 'collapsed'
+    apply(collapsed)
+    write(collapsed ? 'collapsed' : 'open')
+  })
+}
+
+// Search command palette. The sidebar trigger — and ⌘K / Ctrl+K from anywhere —
+// opens a centered dialog over a scrim. It is wired to the document's own
+// headings: the rail's section links populate the list, the input filters them
+// by a case-insensitive substring, ↑/↓ move the selection, and Enter / click
+// jump to the section and close. Richer search (snippets, ranking, a built
+// index, cross-document scope) is deferred to the search-logic owner; this is
+// the open/close + jump-to-section surface.
+function wireSearchPalette(doc, win) {
+  const trigger = doc.querySelector('.sidebar-search__field')
+  if (!trigger || trigger.dataset.bpSearchWired) return
+  trigger.dataset.bpSearchWired = 'true'
+
+  const isMacLike = /Mac|iPhone|iPad/.test(win.navigator?.platform || '')
+  if (!isMacLike) {
+    const cmd = trigger.querySelector('.sidebar-search__hint kbd')
+    if (cmd) cmd.textContent = 'Ctrl'
+    trigger.setAttribute('aria-label', 'Search (Ctrl+K)')
+  }
+
+  let overlay = null
+  let panel = null
+  let input = null
+  let results = null
+  let footStatus = null
+  let entries = []
+  let visible = []
+  let selected = 0
+  let returnFocus = null
+  let prevOverflow = ''
+
+  // Mirror the document's own structure from the rendered rail, so the palette
+  // stays portable (no per-document hardcoding). Each top-level entry carries
+  // its group eyebrow as the breadcrumb; nested entries fold the parent in too.
+  const collectEntries = () => {
+    const list =
+      doc.querySelector('.bp-sidebar .bp-sidebar__panel > ul') ??
+      doc.querySelector('.bp-toc > ul')
+    if (!list) return []
+    const out = []
+    let group = ''
+    for (const li of list.children) {
+      if (li.classList.contains('bp-nav-group')) {
+        group = (li.textContent || '').trim()
+        continue
+      }
+      const link = li.querySelector(':scope > a[href^="#"]')
+      if (!link) continue
+      const title = (link.textContent || '').trim()
+      out.push({ href: link.getAttribute('href') || '', title, crumb: group })
+      for (const sub of li.querySelectorAll(':scope > ul > li > a[href^="#"]')) {
+        out.push({
+          href: sub.getAttribute('href') || '',
+          title: (sub.textContent || '').trim(),
+          crumb: [group, title].filter(Boolean).join(' › '),
+        })
+      }
+    }
+    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 highlight = (text, q) => {
+    if (!q) return [doc.createTextNode(text)]
+    const idx = text.toLowerCase().indexOf(q)
+    if (idx < 0) return [doc.createTextNode(text)]
+    const mark = doc.createElement('mark')
+    mark.textContent = text.slice(idx, idx + q.length)
+    return [
+      doc.createTextNode(text.slice(0, idx)),
+      mark,
+      doc.createTextNode(text.slice(idx + q.length)),
+    ]
+  }
+
+  const buildRow = (entry, index, q) => {
+    const row = doc.createElement('a')
+    row.className = 'docs-search__row'
+    row.id = `docs-search-row-${index}`
+    row.setAttribute('role', 'option')
+    row.href = entry.href
+    row.dataset.index = String(index)
+    row.addEventListener('click', () => close())
+    row.addEventListener('mousemove', () => {
+      if (selected !== index) {
+        selected = index
+        applySelection()
+      }
+    })
+
+    const mainCol = doc.createElement('span')
+    mainCol.className = 'docs-search__row-main'
+    if (entry.crumb) {
+      const crumb = doc.createElement('span')
+      crumb.className = 'docs-search__crumb'
+      crumb.textContent = entry.crumb
+      mainCol.append(crumb)
+    }
+    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))
+    mainCol.append(title)
+
+    const enter = doc.createElement('kbd')
+    enter.className = 'docs-search__enter'
+    enter.textContent = '↵'
+
+    row.append(mainCol, enter)
+    return row
+  }
+
+  const buildEmpty = (query) => {
+    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')
+    title.className = 'docs-search__empty-title'
+    title.textContent = `No results for “${(query || '').trim()}”`
+    const note = doc.createElement('span')
+    note.className = 'docs-search__empty-note'
+    note.textContent = 'Try a different term, or check your spelling.'
+    wrap.append(iconWrap, title, note)
+    return wrap
+  }
+
+  const applySelection = () => {
+    const rows = results.querySelectorAll('.docs-search__row[role="option"]')
+    let activeId = ''
+    rows.forEach((row, index) => {
+      const isSel = index === selected
+      row.setAttribute('aria-selected', String(isSel))
+      if (isSel) {
+        activeId = row.id
+        row.scrollIntoView({ block: 'nearest' })
+      }
+    })
+    if (activeId) input.setAttribute('aria-activedescendant', activeId)
+    else input.removeAttribute('aria-activedescendant')
+  }
+
+  const move = (delta) => {
+    if (!visible.length) return
+    selected = (selected + delta + visible.length) % visible.length
+    applySelection()
+  }
+
+  const render = (query) => {
+    const q = (query || '').trim().toLowerCase()
+    visible = q
+      ? entries.filter((entry) => entry.title.toLowerCase().includes(q))
+      : entries
+    selected = 0
+    results.replaceChildren()
+
+    if (visible.length === 0) {
+      results.append(buildEmpty(query))
+      footStatus.textContent = '0 results'
+      input.removeAttribute('aria-activedescendant')
+      return
+    }
+
+    const group = doc.createElement('div')
+    group.className = 'docs-search__group'
+    group.append(doc.createTextNode(q ? 'Results' : 'On this page'))
+    const count = doc.createElement('span')
+    count.className = 'docs-search__group-count'
+    count.textContent = String(visible.length)
+    group.append(count)
+    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) => {
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      close()
+    } else if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      move(1)
+    } else if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      move(-1)
+    } else if (event.key === 'Enter') {
+      const row = results.querySelector(
+        `.docs-search__row[data-index="${selected}"]`
+      )
+      if (row) {
+        event.preventDefault()
+        row.click()
+      }
+    } else if (event.key === 'Tab') {
+      const focusable = panel.querySelectorAll(
+        'a[href], button, input, [tabindex]:not([tabindex="-1"])'
+      )
+      const first = focusable[0]
+      const last = focusable[focusable.length - 1]
+      if (
+        first &&
+        last &&
+        (event.shiftKey ? doc.activeElement === first : doc.activeElement === last)
+      ) {
+        event.preventDefault()
+        ;(event.shiftKey ? last : first).focus()
+      }
+    }
+  }
+
+  const build = () => {
+    overlay = doc.createElement('div')
+    overlay.className = 'docs-search-overlay'
+    overlay.addEventListener('click', (event) => {
+      if (event.target === overlay) close()
+    })
+
+    panel = doc.createElement('div')
+    panel.className = 'docs-search'
+    panel.setAttribute('role', 'dialog')
+    panel.setAttribute('aria-modal', 'true')
+    panel.setAttribute('aria-label', 'Search')
+
+    const field = doc.createElement('div')
+    field.className = 'docs-search__field'
+    const icon = createChromeSvg(doc, SEARCH_ICON, 16)
+    icon.classList.add('docs-search__icon')
+    input = doc.createElement('input')
+    input.className = 'docs-search__input'
+    input.type = 'search'
+    input.placeholder = 'Search the docs…'
+    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.autocomplete = 'off'
+    input.spellcheck = false
+    const esc = doc.createElement('span')
+    esc.className = 'docs-search__esc'
+    esc.textContent = 'esc'
+    field.append(icon, input, esc)
+
+    results = doc.createElement('div')
+    results.className = 'docs-search__results'
+    results.id = 'docs-search-listbox'
+    results.setAttribute('role', 'listbox')
+    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)
+
+    panel.append(field, results, foot)
+    overlay.append(panel)
+    ;(doc.body || doc.documentElement).append(overlay)
+
+    input.addEventListener('input', () => render(input.value))
+  }
+
+  const open = () => {
+    if (!overlay) build()
+    if (overlay.classList.contains('is-open')) return
+    entries = collectEntries()
+    returnFocus = doc.activeElement
+    prevOverflow = doc.documentElement.style.overflow
+    doc.documentElement.style.overflow = 'hidden'
+    input.value = ''
+    render('')
+    overlay.classList.add('is-open')
+    input.setAttribute('aria-expanded', 'true')
+    doc.addEventListener('keydown', onKeydown)
+    input.focus({ preventScroll: true })
+    win.requestAnimationFrame(() => input.focus({ preventScroll: true }))
+  }
+
+  function close() {
+    if (!overlay || !overlay.classList.contains('is-open')) return
+    overlay.classList.remove('is-open')
+    input.setAttribute('aria-expanded', 'false')
+    input.removeAttribute('aria-activedescendant')
+    doc.documentElement.style.overflow = prevOverflow ?? ''
+    doc.removeEventListener('keydown', onKeydown)
+    if (returnFocus && typeof returnFocus.focus === 'function') returnFocus.focus()
+  }
+
+  trigger.addEventListener('click', open)
+
+  doc.addEventListener('keydown', (event) => {
+    if ((event.metaKey || event.ctrlKey) && (event.key === 'k' || event.key === 'K')) {
+      event.preventDefault()
+      if (overlay && overlay.classList.contains('is-open')) close()
+      else open()
+    }
+  })
+}
+
+function injectDocumentChrome(doc, win = doc.defaultView, navigationTree = []) {
+  if (doc.body?.dataset.bpChromeReady === 'true') return
+  const main = doc.querySelector('main')
+  if (!main) return
+
+  const hasNavigation = navigationTree.length > 0
+  const sidebar = hasNavigation ? injectSidebar(doc, win) : null
+  const chrome = [
+    injectSiteNav(doc, win),
+    hasNavigation ? injectScrollProgress(doc) : null,
+    sidebar ? injectSidebarToggle(doc) : null,
+    sidebar,
+  ].filter(Boolean)
+
+  if (chrome.length > 0) {
+    main.before(...chrome)
+  }
+
+  if (sidebar) {
+    doc.documentElement.dataset.bpDocument = ''
+  }
+
+  wireThemeToggle(doc, win)
+  wireSidebarCollapse(doc, win)
+  doc.body.dataset.bpChromeReady = 'true'
+}
+
 // Optional behavior for TOC current state and reading progress.
 import { registerBlueprintChoiceElements } from './blueprint-choices.js'
 
@@ -8,17 +955,28 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
   if (root.dataset.blueprintRuntime === 'ready') return
   root.dataset.blueprintRuntime = 'ready'
 
-  wireSectionHeadingLinks(doc)
+  // Resolve the theme before chrome is injected so the toggle renders in the
+  // correct state and the page doesn't repaint a second time.
+  resolveInitialTheme(doc, win)
+  const navigationTree = ensureDocumentNavTree(doc)
+  injectDocumentChrome(doc, win, navigationTree)
+  generateNavigationFromHeadings(doc, navigationTree)
+  wireSectionHeadingLinks(doc, win)
+  wireSearchPalette(doc, win)
   wireFigureDiagramSize(doc)
 
-  // The shell becomes the scroll container only while it is fixed (wide
+  // <main> becomes the scroll container only while it is fixed (wide
   // layout). At ≤700px the CSS reverts it to static and the window scrolls, so
   // resolve the scroller live rather than caching it — a wide→narrow resize
   // otherwise leaves the scroll listener bound to an element that no longer
   // scrolls, silently freezing reading-progress and TOC highlighting.
-  const shell = doc.querySelector('.bp-shell')
+  const main = doc.querySelector('main')
   const resolveScroller = () =>
-    shell && win.getComputedStyle(shell).position === 'fixed' ? shell : null
+    main &&
+    root.dataset.bpDocument !== undefined &&
+    win.getComputedStyle(main).position === 'fixed'
+      ? main
+      : null
   let shellScroller = resolveScroller()
   const scrollTop = () => (shellScroller ? shellScroller.scrollTop : win.scrollY)
   const scrollHeight = () =>
@@ -27,10 +985,23 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
     shellScroller ? shellScroller.clientHeight : win.innerHeight
 
   const progress = doc.querySelector('.scroll-progress')
+  const isPrimaryNavLink = (link) => {
+    const listItem = link.closest('li')
+    const list = listItem?.parentElement
+    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')
+    return list === topList
+  }
   // Only the fixed rails track an active entry. A full-width .bp-contents
   // index (typically parked at the top of a document) has no "current" entry,
-  // so it stays a static index and is intentionally excluded here.
+  // so it stays a static index and is intentionally excluded here. Sub-nav
+  // links nest one level beneath a primary entry and are click targets only.
   const entries = [...doc.querySelectorAll('.bp-sidebar a[href^="#"], .bp-toc a[href^="#"], .sidebar a[href^="#"]')]
+    .filter(isPrimaryNavLink)
     .map((link) => ({
       link,
       section: doc.getElementById(decodeURIComponent(link.hash.slice(1))),
@@ -76,19 +1047,24 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
       progress.style.transform = `scaleX(${max > 0 ? scrollTop() / max : 0})`
     }
     if (sections.length === 0) return
+    const threshold = win.innerHeight * 0.35
     if (scrollingTo) {
-      const top = scrollingTo.getBoundingClientRect().top
-      if (top <= win.innerHeight * 0.35 && top >= -8) scrollingTo = null
-      else {
+      const rect = scrollingTo.getBoundingClientRect()
+      const top = rect.top
+      const visible = rect.bottom > 0 && top < win.innerHeight
+      if (top <= threshold && top >= -8) {
+        scrollingTo = null
+      } else if (visible) {
         setCurrent(scrollingTo)
         return
+      } else {
+        scrollingTo = null
       }
     }
     if (scrollTop() + clientHeight() >= scrollHeight() - 2) {
       setCurrent(sections.at(-1))
       return
     }
-    const threshold = win.innerHeight * 0.35
     setCurrent(
       sections.reduce(
         (current, section) => (section.getBoundingClientRect().top <= threshold ? section : current),
@@ -101,11 +1077,18 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
     scheduled = true
     win.requestAnimationFrame(update)
   }
+  const prefersReducedMotion = () => themePrefersReducedMotion(win)
   const updateFromHash = () => {
     const match = entries.find(({ link }) => link.hash === win.location.hash)
     if (match) {
       scrollingTo = match.section
       setCurrent(match.section)
+      const top = match.section.getBoundingClientRect().top
+      const threshold = win.innerHeight * 0.35
+      if (top > threshold || top < -8) {
+        match.section.scrollIntoView({ block: 'start' })
+      }
+      scheduleUpdate()
       return
     }
     scrollingTo = null
@@ -114,7 +1097,6 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
 
   const navLinkSelector =
     '.bp-sidebar a[href^="#"], .bp-toc a[href^="#"], .sidebar a[href^="#"], .bp-contents a[href^="#"]'
-  const prefersReducedMotion = () => win.matchMedia('(prefers-reduced-motion: reduce)').matches
 
   const scrollToSection = (section) => {
     scrollingTo = section
@@ -178,14 +1160,17 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
   updateFromHash()
 }
 
-// Section heading permalink — pixelarticons in the main-column gutter; link on
-// heading hover, copy on icon hover, check after a successful copy.
-const HEADING_LINK_ICON =
-  'M4 6h7v2H4zm0 10h7v2H4zM2 8h2v8H2zm18-2h-7v2h7zm0 10h-7v2h7zm2-8h-2v8h2zM7 11h10v2H7z'
-const HEADING_COPY_ICON =
-  'M8 6h12v2H8zM4 2h12v2H4zm2 6h2v12H6zM2 4h2v12H2zm6 16h12v2H8zM20 8h2v12h-2zm-4-4h2v2h-2zM4 16h2v2H4z'
-const HEADING_CHECK_ICON =
-  'M10 18H8v-2h2v2Zm-2-2H6v-2h2v2Zm4-2v2h-2v-2h2Zm-6 0H4v-2h2v2Zm8 0h-2v-2h2v2Zm2-2h-2v-2h2v2Zm2-2h-2V8h2v2Zm2-2h-2V6h2v2Z'
+// Section heading permalink — Iconoir line glyphs in the main-column gutter;
+// link on heading hover, copy on icon hover, check after a successful copy.
+const HEADING_LINK_ICON = [
+  'M14 11.9976C14 9.5059 11.683 7 8.85714 7C8.52241 7 7.41904 7.00001 7.14286 7.00001C4.30254 7.00001 2 9.23752 2 11.9976C2 14.376 3.70973 16.3664 6 16.8714C6.36756 16.9525 6.75006 16.9952 7.14286 16.9952',
+  'M10 11.9976C10 14.4893 12.317 16.9952 15.1429 16.9952C15.4776 16.9952 16.581 16.9952 16.8571 16.9952C19.6975 16.9952 22 14.7577 22 11.9976C22 9.6192 20.2903 7.62884 18 7.12383C17.6324 7.04278 17.2499 6.99999 16.8571 6.99999',
+]
+const HEADING_COPY_ICON = [
+  'M19.4 20H9.6C9.26863 20 9 19.7314 9 19.4V9.6C9 9.26863 9.26863 9 9.6 9H19.4C19.7314 9 20 9.26863 20 9.6V19.4C20 19.7314 19.7314 20 19.4 20Z',
+  'M15 9V4.6C15 4.26863 14.7314 4 14.4 4H4.6C4.26863 4 4 4.26863 4 4.6V14.4C4 14.7314 4.26863 15 4.6 15H9',
+]
+const HEADING_CHECK_ICON = 'M5 13L9 17L19 7'
 const headingLinkTimers = new WeakMap()
 
 function createHeadingPixelIcon(doc, name, pathD) {
@@ -193,12 +1178,18 @@ function createHeadingPixelIcon(doc, name, pathD) {
   svg.setAttribute('viewBox', '0 0 24 24')
   svg.setAttribute('width', '16')
   svg.setAttribute('height', '16')
-  svg.setAttribute('fill', 'currentColor')
+  svg.setAttribute('fill', 'none')
+  svg.setAttribute('stroke', 'currentColor')
+  svg.setAttribute('stroke-width', '1.5')
+  svg.setAttribute('stroke-linecap', 'round')
+  svg.setAttribute('stroke-linejoin', 'round')
   svg.setAttribute('aria-hidden', 'true')
   svg.classList.add('bp-heading-link__icon', `bp-heading-link__icon--${name}`)
-  const path = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
-  path.setAttribute('d', pathD)
-  svg.append(path)
+  for (const d of Array.isArray(pathD) ? pathD : [pathD]) {
+    const path = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
+    path.setAttribute('d', d)
+    svg.append(path)
+  }
   return svg
 }
 
@@ -230,7 +1221,7 @@ function showHeadingLinkState(button, state, label) {
   const previousTimer = headingLinkTimers.get(button)
   if (previousTimer) clearTimeout(previousTimer)
 
-  const heading = button.closest('h2')
+  const heading = button.closest('h1, h2, h3, h4, h5, h6')
 
   if (state === 'idle') {
     delete button.dataset.bpCopyState
@@ -262,24 +1253,321 @@ function wireFigureDiagramSize(doc) {
   }
 }
 
-function wireSectionHeadingLinks(doc, win = doc.defaultView) {
-  for (const section of doc.querySelectorAll('section[id]')) {
-    const heading =
-      section.querySelector(':scope > h2:first-child') ??
-      section.querySelector(':scope > hgroup:first-child > h2')
-    if (!heading || heading.querySelector(':scope > .bp-heading-row')) continue
+const SIDEBAR_HEADING_SELECTOR =
+  'h2[data-sidebar], h3[data-sidebar], h4[data-sidebar], h5[data-sidebar], h6[data-sidebar]'
+const NAV_CONTENT_ROOT = 'main, [data-bp-nav-root]'
 
-    const label = heading.textContent.trim()
-    heading.replaceChildren()
+function slugifyHeadingId(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/['']/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
 
-    const row = doc.createElement('span')
-    row.className = 'bp-heading-row'
+function isSectionLeadHeading(heading) {
+  const section = heading.closest('section')
+  if (!section) return false
+  return (
+    heading === section.querySelector(':scope > h2:first-child') ||
+    heading === section.querySelector(':scope > hgroup:first-child > h2')
+  )
+}
+
+function ensureUniqueHeadingId(doc, base, heading) {
+  let candidate = base || 'section'
+  let suffix = 2
+  while (doc.getElementById(candidate) && doc.getElementById(candidate) !== heading) {
+    candidate = `${base}-${suffix}`
+    suffix += 1
+  }
+  return candidate
+}
+
+function resolveHeadingId(doc, heading) {
+  if (heading.id) return heading.id
+
+  const section = heading.closest('section[id]')
+  if (section && isSectionLeadHeading(heading)) {
+    // `<section id>` is the single anchoring contract: leave the id on the
+    // section and point navigation, permalinks, and scroll-spy at it.
+    return section.id
+  }
+
+  const base = slugifyHeadingId(
+    heading.getAttribute('data-sidebar') || heading.textContent || 'section'
+  )
+  heading.id = ensureUniqueHeadingId(doc, base, heading)
+  return heading.id
+}
+
+function getSidebarLabel(heading) {
+  return heading.getAttribute('data-sidebar')?.trim() || heading.textContent.trim()
+}
+
+// A repeated <header> in the nav root (every one after the masthead) is a
+// navigation GROUP divider: it reuses the masthead structure (eyebrow + h1 +
+// optional <bp-subheader>) and its title becomes a quiet eyebrow above the
+// sections that follow, in both the fixed rail and the inline contents.
+function findNavMasthead(root) {
+  return root.querySelector(':scope > header')
+}
+
+function getGroupLabel(header) {
+  const explicit = header.getAttribute('data-sidebar')?.trim()
+  if (explicit) return explicit
+  const heading = header.querySelector('h1, h2, h3, h4, h5, h6')
+  if (heading?.textContent.trim()) return heading.textContent.trim()
+  const eyebrow = header.querySelector('bp-eyebrow')
+  if (eyebrow?.textContent.trim()) return eyebrow.textContent.trim()
+  return header.textContent.trim() || 'Section'
+}
+
+function resolveGroupId(doc, header) {
+  if (header.id) return header.id
+  const base = slugifyHeadingId(getGroupLabel(header))
+  header.id = ensureUniqueHeadingId(doc, base, header)
+  return header.id
+}
+
+// Collect group dividers (nav-root <header>s after the masthead) and every
+// data-sidebar heading in a single document-ordered pass.
+function collectNavNodes(doc) {
+  const root = doc.querySelector(NAV_CONTENT_ROOT) ?? doc.body
+  const masthead = findNavMasthead(root)
+  const selector = `:scope > header, ${SIDEBAR_HEADING_SELECTOR}`
+  return [...root.querySelectorAll(selector)].filter((node) => node !== masthead)
+}
+
+function buildSidebarTree(nodes, doc) {
+  const tree = []
+  let currentGroup = null
+  let currentPrimary = null
+
+  for (const node of nodes) {
+    if (node.tagName === 'HEADER') {
+      currentGroup = {
+        type: 'group',
+        label: getGroupLabel(node),
+        id: resolveGroupId(doc, node),
+        children: [],
+      }
+      currentPrimary = null
+      tree.push(currentGroup)
+      continue
+    }
+
+    const level = Number(node.tagName.slice(1))
+    const item = {
+      type: 'section',
+      heading: node,
+      label: getSidebarLabel(node),
+      id: node.id || resolveHeadingId(doc, node),
+      children: [],
+    }
+
+    if (level === 2) {
+      currentPrimary = item
+      ;(currentGroup ? currentGroup.children : tree).push(item)
+      continue
+    }
+
+    if (currentPrimary) {
+      currentPrimary.children.push(item)
+      continue
+    }
+
+    ;(currentGroup ? currentGroup.children : tree).push(item)
+  }
+
+  return tree
+}
+
+function createNavLink(doc, { id, label }) {
+  const link = doc.createElement('a')
+  link.href = `#${id}`
+  link.textContent = label
+  return link
+}
+
+// Group eyebrow + its section entries stay siblings in one flat list so the
+// gliding pill, auto-numbering, scroll-spy, and search keep working unchanged;
+// the group row carries no link and is skipped by the numbering counter.
+function createNavGroupRow(doc, group, labelClass) {
+  const li = doc.createElement('li')
+  li.className = 'bp-nav-group'
+  const label = doc.createElement('span')
+  label.className = labelClass
+  label.textContent = group.label
+  li.append(label)
+  return li
+}
+
+function renderNavTree(doc, tree) {
+  const fragment = doc.createDocumentFragment()
+
+  const appendSection = (section) => {
+    const li = doc.createElement('li')
+    li.append(createNavLink(doc, section))
+
+    if (section.children?.length > 0) {
+      const subList = doc.createElement('ul')
+      for (const child of section.children) {
+        const subItem = doc.createElement('li')
+        subItem.append(createNavLink(doc, child))
+        subList.append(subItem)
+      }
+      li.append(subList)
+    }
+
+    fragment.append(li)
+  }
+
+  for (const item of tree) {
+    if (item.type === 'group') {
+      fragment.append(createNavGroupRow(doc, item, 'bp-nav-group__label'))
+      item.children.forEach(appendSection)
+      continue
+    }
+    appendSection(item)
+  }
+
+  return fragment
+}
+
+function renderContentsTree(doc, tree) {
+  const fragment = doc.createDocumentFragment()
+
+  const appendSection = (section) => {
+    const li = doc.createElement('li')
+    li.append(createNavLink(doc, section))
+    fragment.append(li)
+  }
+
+  for (const item of tree) {
+    if (item.type === 'group') {
+      const li = createNavGroupRow(doc, item, 'bp-contents-group__label')
+      li.className = 'bp-contents-group'
+      fragment.append(li)
+      item.children.forEach(appendSection)
+      continue
+    }
+    appendSection(item)
+  }
+
+  return fragment
+}
+
+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')
+    if (list) lists.push(list)
+  }
+
+  for (const nav of doc.querySelectorAll('.bp-toc:not([data-bp-nav-manual])')) {
+    const list = nav.querySelector(':scope > ul')
+    if (list) lists.push(list)
+  }
+
+  return lists
+}
+
+function ensureDocumentNavTree(doc) {
+  const nodes = collectNavNodes(doc)
+  if (nodes.length === 0) return []
+
+  for (const node of nodes) {
+    if (node.tagName === 'HEADER') resolveGroupId(doc, node)
+    else resolveHeadingId(doc, node)
+  }
+
+  return buildSidebarTree(nodes, doc)
+}
+
+function populateBpTocElement(element, doc, tree) {
+  if (element.dataset.bpTocReady === 'true') return
+  if (!tree?.length) return
+
+  element.dataset.bpTocReady = 'true'
+
+  const label =
+    element.getAttribute('label')?.trim() ||
+    element.textContent.trim() ||
+    'Contents'
+  const ariaLabel = element.getAttribute('aria-label')?.trim() || label
+
+  const nav = doc.createElement('nav')
+  nav.className = 'bp-contents'
+  nav.setAttribute('aria-label', ariaLabel)
+
+  const eyebrow = doc.createElement('p')
+  eyebrow.className = 'bp-eyebrow'
+  eyebrow.textContent = label
+
+  const list = doc.createElement('ol')
+  list.append(renderContentsTree(doc, tree))
+
+  nav.append(eyebrow, list)
+  element.replaceChildren(nav)
+}
+
+function populateAllBpToc(doc, tree) {
+  for (const element of doc.querySelectorAll('bp-toc')) {
+    populateBpTocElement(element, doc, tree)
+  }
+}
+
+function generateNavigationFromHeadings(doc, tree = ensureDocumentNavTree(doc)) {
+  if (tree.length === 0) return
+
+  const navFragment = renderNavTree(doc, tree)
+
+  for (const list of findSidebarNavLists(doc)) {
+    list.replaceChildren(navFragment.cloneNode(true))
+  }
+
+  populateAllBpToc(doc, tree)
+}
+
+function formatHeadingEyebrow(number) {
+  return String(number).padStart(2, '0')
+}
+
+function wireSectionHeadingLinks(doc, win = doc.defaultView) {
+  const root = doc.querySelector(NAV_CONTENT_ROOT) ?? doc.body
+  let primaryNumber = 0
+
+  for (const heading of root.querySelectorAll(SIDEBAR_HEADING_SELECTOR)) {
+    if (heading.querySelector(':scope > .bp-heading-row')) continue
+
+    const level = Number(heading.tagName.slice(1))
+    const label = getSidebarLabel(heading)
+    const titleNodes = [...heading.childNodes]
+    const id = resolveHeadingId(doc, heading)
+
+    heading.replaceChildren()
+
+    if (level === 2) {
+      primaryNumber += 1
+      const eyebrow = doc.createElement('span')
+      eyebrow.className = 'bp-heading-eyebrow'
+      eyebrow.textContent = formatHeadingEyebrow(primaryNumber)
+      heading.append(eyebrow)
+    }
+
+    const row = doc.createElement('span')
+    row.className = 'bp-heading-row'
 
     const button = createHeadingLinkButton(doc, label)
 
     const title = doc.createElement('span')
     title.className = 'bp-heading-title'
-    title.textContent = label
+    title.append(...titleNodes)
 
     row.append(button, title)
     heading.append(row)
@@ -312,7 +1600,7 @@ function wireSectionHeadingLinks(doc, win = doc.defaultView) {
 
     button.addEventListener('click', (event) => {
       event.preventDefault()
-      const url = new URL(`#${section.id}`, win?.location.href ?? '').href
+      const url = new URL(`#${id}`, win?.location.href ?? '').href
       copySectionUrl(url)
         .then(() => showHeadingLinkState(button, 'copied', label))
         .catch(() => showHeadingLinkState(button, 'error', label))
@@ -367,6 +1655,25 @@ function createCalloutIcon(doc, pathD) {
   return svg
 }
 
+// ---------------------------------------------------------------------
+// <bp-toc> — inline table of contents (full-width .bp-contents family).
+//
+// Place the element wherever the index should appear; it expands to a
+// numbered, multi-column nav on load from h2 headings marked data-sidebar.
+// Sub-sections appear in the fixed rail only; the inline block stays flat.
+//
+//   <bp-toc label="Contents"></bp-toc>
+//
+// label: eyebrow text (default: Contents). aria-label overrides the nav label.
+// ---------------------------------------------------------------------
+class BlueprintTocElement extends HTMLElement {
+  connectedCallback() {
+    const doc = this.ownerDocument
+    if (doc.documentElement.dataset.blueprintRuntime !== 'ready') return
+    populateBpTocElement(this, doc, ensureDocumentNavTree(doc))
+  }
+}
+
 class BlueprintCalloutElement extends HTMLElement {
   #rendered = false
 
@@ -407,10 +1714,1141 @@ class BlueprintCalloutElement extends HTMLElement {
   }
 }
 
+// ---------------------------------------------------------------------
+// <bp-mock> — a drafting "browser frame" for UX mockups.
+//
+// Wraps a low-fidelity component sketch in an ink chrome frame (window
+// ticks + a mono URL/title). The frame is light-DOM and the authored
+// children are moved into a scalable canvas, so the mock is contained by
+// construction — no shadow DOM. Two optional behaviours:
+//   • viewport="1280"  draws the canvas at that pixel width and scales it
+//     to fit the frame (crisp 1:1 when the frame is wide enough or when
+//     expanded), so a desktop layout can be mocked inside a narrow column.
+//   • expandable        an expand control lifts the frame into a near-
+//     fullscreen overlay (Esc / the control dismiss; focus is restored).
+//
+//   <bp-mock label="app.example.com" viewport="1280"> … </bp-mock>
+//
+// label: mono caption in the chrome bar. viewport: canvas width in px.
+// expandable="false" drops the expand control.
+// ---------------------------------------------------------------------
+const MOCK_EXPAND_ICON = [
+  'M9 9L4 4M4 4V8M4 4H8',
+  'M15 9L20 4M20 4V8M20 4H16',
+  'M9 15L4 20M4 20V16M4 20H8',
+  'M15 15L20 20M20 20V16M20 20H16',
+]
+const MOCK_COLLAPSE_ICON = [
+  'M20 20L15 15M15 15V19M15 15H19',
+  'M4 20L9 15M9 15V19M9 15H5',
+  'M20 4L15 9M15 9V5M15 9H19',
+  'M4 4L9 9M9 9V5M9 9H5',
+]
+
+class BlueprintMockElement extends HTMLElement {
+  #rendered = false
+  #ro = null
+  #wrap = null
+  #stage = null
+  #canvas = null
+  #btn = null
+  #naturalWidth = 0
+  #onKeydown = null
+  #returnFocus = null
+  #prevOverflow = ''
+
+  connectedCallback() {
+    if (this.#rendered) return
+    this.#rendered = true
+
+    const doc = this.ownerDocument
+    const label = this.getAttribute('label') || ''
+    const vw = Number.parseInt(this.getAttribute('viewport') || '', 10)
+    this.#naturalWidth = Number.isFinite(vw) && vw > 0 ? vw : 0
+    const expandable = this.getAttribute('expandable') !== 'false'
+
+    const wrap = doc.createElement('div')
+    wrap.className = 'bp-mock'
+    wrap.setAttribute('role', 'group')
+    if (label) wrap.setAttribute('aria-label', `Mockup: ${label}`)
+
+    const frame = doc.createElement('div')
+    frame.className = 'bp-mock__frame'
+
+    const bar = doc.createElement('div')
+    bar.className = 'bp-mock__bar'
+
+    const ticks = doc.createElement('span')
+    ticks.className = 'bp-mock__ticks'
+    ticks.setAttribute('aria-hidden', 'true')
+    ticks.append(doc.createElement('i'), doc.createElement('i'), doc.createElement('i'))
+    bar.append(ticks)
+
+    const cap = doc.createElement('span')
+    cap.className = 'bp-mock__label'
+    cap.textContent = label
+    bar.append(cap)
+
+    if (expandable) {
+      const btn = doc.createElement('button')
+      btn.type = 'button'
+      btn.className = 'bp-mock__btn'
+      btn.setAttribute('aria-expanded', 'false')
+      btn.setAttribute('aria-label', 'Expand mockup')
+      btn.append(createChromeSvg(doc, MOCK_EXPAND_ICON, 14))
+      btn.addEventListener('click', () => this.#toggle())
+      bar.append(btn)
+      this.#btn = btn
+    }
+
+    const stage = doc.createElement('div')
+    stage.className = 'bp-mock__stage'
+
+    const canvas = doc.createElement('div')
+    canvas.className = 'bp-mock__canvas'
+    if (this.#naturalWidth) canvas.style.width = `${this.#naturalWidth}px`
+    canvas.append(...this.childNodes)
+    stage.append(canvas)
+
+    frame.append(bar, stage)
+    wrap.append(frame)
+    this.replaceChildren(wrap)
+
+    this.#wrap = wrap
+    this.#stage = stage
+    this.#canvas = canvas
+
+    if (this.#naturalWidth && typeof ResizeObserver !== 'undefined') {
+      this.#ro = new ResizeObserver(() => this.#relayout())
+      this.#ro.observe(stage)
+      this.#ro.observe(canvas)
+      this.#relayout()
+    }
+  }
+
+  disconnectedCallback() {
+    this.#ro?.disconnect()
+    if (this.#onKeydown) this.ownerDocument.removeEventListener('keydown', this.#onKeydown)
+  }
+
+  // Scale the fixed-width canvas down to whatever width the stage offers,
+  // then collapse the stage to the scaled height so there is no dead space.
+  #relayout() {
+    if (!this.#naturalWidth || !this.#stage) return
+    const avail = this.#stage.clientWidth
+    if (!avail) return
+    const scale = Math.min(1, avail / this.#naturalWidth)
+    this.#canvas.style.setProperty('--bp-mock-scale', String(scale))
+    this.#stage.style.height = `${Math.round(this.#canvas.offsetHeight * scale)}px`
+  }
+
+  #toggle() {
+    const doc = this.ownerDocument
+    const expanded = this.#wrap.classList.toggle('is-expanded')
+    if (this.#btn) {
+      this.#btn.setAttribute('aria-expanded', String(expanded))
+      this.#btn.setAttribute('aria-label', expanded ? 'Collapse mockup' : 'Expand mockup')
+      this.#btn.replaceChildren(
+        createChromeSvg(doc, expanded ? MOCK_COLLAPSE_ICON : MOCK_EXPAND_ICON, 14)
+      )
+    }
+    if (expanded) {
+      this.#returnFocus = doc.activeElement
+      // The page scrolls, so freeze the background behind the overlay.
+      this.#prevOverflow = doc.documentElement.style.overflow
+      doc.documentElement.style.overflow = 'hidden'
+      this.#onKeydown = (event) => {
+        if (event.key === 'Escape') this.#toggle()
+      }
+      doc.addEventListener('keydown', this.#onKeydown)
+      this.#btn?.focus()
+    } else {
+      doc.documentElement.style.overflow = this.#prevOverflow ?? ''
+      if (this.#onKeydown) {
+        doc.removeEventListener('keydown', this.#onKeydown)
+        this.#onKeydown = null
+      }
+      if (this.#returnFocus && typeof this.#returnFocus.focus === 'function') {
+        this.#returnFocus.focus()
+      }
+    }
+    // The stage width changes with the overlay; rescale on the next frame.
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => this.#relayout())
+    } else {
+      this.#relayout()
+    }
+  }
+}
+
+// ---------------------------------------------------------------------
+// <bp-gallery> — an elegant grid of images that expands to a lightbox.
+//
+// Wraps author-provided images (screenshots, generated mockups, or user
+// uploads) in a tidy responsive grid. Each thumbnail wears a bluescale
+// treatment — desaturated and washed in the illustration ramp — until it
+// is hovered or focused, when its true color is revealed. Activating a
+// thumbnail lifts the full-color image into a near-fullscreen lightbox
+// over a drafting scrim (Esc / the close control dismiss; arrow keys and
+// the prev/next controls page between images; focus is restored).
+//
+//   <bp-gallery label="Concept explorations">
+//     <figure>
+//       <img src="hero.png" alt="Landing hero" />
+//       <figcaption>Landing hero</figcaption>
+//     </figure>
+//     <img src="settings.png" alt="Settings panel" />
+//   </bp-gallery>
+//
+// label: optional mono caption for the gallery as a whole (accessible
+// name + lightbox kicker). Captions come from a child <figcaption> when
+// present, otherwise the image's alt text. The component is light-DOM and
+// expands to documented .bp-gallery* markup styled by blueprint.css.
+// ---------------------------------------------------------------------
+const GALLERY_ZOOM_ICON = [
+  'M8 11H11M14 11H11M11 11V8M11 11V14',
+  'M17 17L21 21',
+  'M3 11C3 15.4183 6.58172 19 11 19C13.213 19 15.2161 18.1015 16.6644 16.6493C18.1077 15.2022 19 13.2053 19 11C19 6.58172 15.4183 3 11 3C6.58172 3 3 6.58172 3 11Z',
+]
+const GALLERY_CLOSE_ICON =
+  'M6.75827 17.2426L12.0009 12M17.2435 6.75736L12.0009 12M12.0009 12L6.75827 6.75736M12.0009 12L17.2435 17.2426'
+const GALLERY_PREV_ICON = 'M15 6L9 12L15 18'
+const GALLERY_NEXT_ICON = 'M9 6L15 12L9 18'
+
+class BlueprintGalleryElement extends HTMLElement {
+  #rendered = false
+  /** @type {{ src: string, alt: string, caption: string }[]} */
+  #slides = []
+  #label = ''
+  #box = null
+  #boxImg = null
+  #boxCaption = null
+  #boxCounter = null
+  #boxKicker = null
+  #index = 0
+  #onKeydown = null
+  #returnFocus = null
+  #prevOverflow = ''
+
+  connectedCallback() {
+    if (this.#rendered) return
+    this.#rendered = true
+
+    const doc = this.ownerDocument
+    this.#label = this.getAttribute('label') || ''
+
+    // Collect the authored images and their captions before replacing the
+    // light-DOM children. A <figcaption> wins; otherwise fall back to alt.
+    for (const img of this.querySelectorAll('img')) {
+      const figure = img.closest('figure')
+      const cap = figure?.querySelector('figcaption')
+      const caption = (cap?.textContent || img.getAttribute('alt') || '').trim()
+      this.#slides.push({
+        src: img.getAttribute('src') || '',
+        alt: (img.getAttribute('alt') || caption || '').trim(),
+        caption,
+      })
+    }
+
+    const wrap = doc.createElement('div')
+    wrap.className = 'bp-gallery'
+    wrap.setAttribute('role', 'group')
+    if (this.#label) wrap.setAttribute('aria-label', `Gallery: ${this.#label}`)
+
+    const grid = doc.createElement('div')
+    grid.className = 'bp-gallery__grid'
+
+    this.#slides.forEach((slide, index) => {
+      const item = doc.createElement('button')
+      item.type = 'button'
+      item.className = 'bp-gallery__item'
+      item.setAttribute(
+        'aria-label',
+        slide.caption ? `View image: ${slide.caption}` : `View image ${index + 1}`
+      )
+      item.addEventListener('click', () => this.#open(index))
+
+      const thumb = doc.createElement('span')
+      thumb.className = 'bp-gallery__thumb'
+
+      const img = doc.createElement('img')
+      img.className = 'bp-gallery__img'
+      img.src = slide.src
+      img.alt = slide.alt
+      img.loading = 'lazy'
+      img.decoding = 'async'
+
+      // The bluescale wash: a blue veil that color-blends the grayscale
+      // thumbnail, faded away on hover/focus to reveal true color.
+      const wash = doc.createElement('span')
+      wash.className = 'bp-gallery__wash'
+      wash.setAttribute('aria-hidden', 'true')
+
+      const zoom = doc.createElement('span')
+      zoom.className = 'bp-gallery__zoom'
+      zoom.setAttribute('aria-hidden', 'true')
+      zoom.append(createChromeSvg(doc, GALLERY_ZOOM_ICON, 16))
+
+      thumb.append(img, wash, zoom)
+      item.append(thumb)
+
+      if (slide.caption) {
+        const cap = doc.createElement('span')
+        cap.className = 'bp-gallery__caption'
+        cap.textContent = slide.caption
+        item.append(cap)
+      }
+
+      grid.append(item)
+    })
+
+    wrap.append(grid)
+    this.replaceChildren(wrap)
+  }
+
+  disconnectedCallback() {
+    if (this.#onKeydown) this.ownerDocument.removeEventListener('keydown', this.#onKeydown)
+    this.#box?.remove()
+    this.#box = null
+  }
+
+  #ensureBox() {
+    if (this.#box) return
+    const doc = this.ownerDocument
+
+    const box = doc.createElement('div')
+    box.className = 'bp-lightbox'
+    box.setAttribute('role', 'dialog')
+    box.setAttribute('aria-modal', 'true')
+    box.setAttribute('aria-label', this.#label ? `${this.#label} — image viewer` : 'Image viewer')
+    box.addEventListener('click', (event) => {
+      if (event.target === box) this.#close()
+    })
+
+    const close = doc.createElement('button')
+    close.type = 'button'
+    close.className = 'bp-lightbox__close'
+    close.setAttribute('aria-label', 'Close image viewer')
+    close.append(createChromeSvg(doc, GALLERY_CLOSE_ICON, 18))
+    close.addEventListener('click', () => this.#close())
+
+    const prev = doc.createElement('button')
+    prev.type = 'button'
+    prev.className = 'bp-lightbox__nav bp-lightbox__nav--prev'
+    prev.setAttribute('aria-label', 'Previous image')
+    prev.append(createChromeSvg(doc, GALLERY_PREV_ICON, 22))
+    prev.addEventListener('click', () => this.#step(-1))
+
+    const next = doc.createElement('button')
+    next.type = 'button'
+    next.className = 'bp-lightbox__nav bp-lightbox__nav--next'
+    next.setAttribute('aria-label', 'Next image')
+    next.append(createChromeSvg(doc, GALLERY_NEXT_ICON, 22))
+    next.addEventListener('click', () => this.#step(1))
+
+    const figure = doc.createElement('figure')
+    figure.className = 'bp-lightbox__figure'
+
+    const img = doc.createElement('img')
+    img.className = 'bp-lightbox__img'
+    img.alt = ''
+
+    const meta = doc.createElement('figcaption')
+    meta.className = 'bp-lightbox__meta'
+
+    const kicker = doc.createElement('span')
+    kicker.className = 'bp-lightbox__kicker'
+    kicker.textContent = this.#label
+
+    const counter = doc.createElement('span')
+    counter.className = 'bp-lightbox__counter'
+
+    const caption = doc.createElement('span')
+    caption.className = 'bp-lightbox__caption'
+
+    meta.append(kicker, counter, caption)
+    figure.append(img, meta)
+    box.append(close, prev, figure, next)
+
+    const host = doc.body || doc.documentElement
+    host.append(box)
+
+    this.#box = box
+    this.#boxImg = img
+    this.#boxCaption = caption
+    this.#boxCounter = counter
+    this.#boxKicker = kicker
+  }
+
+  #render() {
+    const slide = this.#slides[this.#index]
+    if (!slide) return
+    this.#boxImg.src = slide.src
+    this.#boxImg.alt = slide.alt
+    this.#boxCaption.textContent = slide.caption
+    this.#boxCaption.hidden = !slide.caption
+    this.#boxKicker.hidden = !this.#label
+    const many = this.#slides.length > 1
+    this.#boxCounter.textContent = many ? `${this.#index + 1} / ${this.#slides.length}` : ''
+    this.#boxCounter.hidden = !many
+    this.#box.classList.toggle('is-single', !many)
+  }
+
+  #open(index) {
+    if (!this.#slides.length) return
+    this.#ensureBox()
+    this.#index = index
+    this.#render()
+
+    const doc = this.ownerDocument
+    this.#returnFocus = doc.activeElement
+    this.#prevOverflow = doc.documentElement.style.overflow
+    doc.documentElement.style.overflow = 'hidden'
+    this.#box.classList.add('is-open')
+
+    this.#onKeydown = (event) => {
+      if (event.key === 'Escape') this.#close()
+      else if (event.key === 'ArrowRight') this.#step(1)
+      else if (event.key === 'ArrowLeft') this.#step(-1)
+    }
+    doc.addEventListener('keydown', this.#onKeydown)
+    this.#box.querySelector('.bp-lightbox__close')?.focus()
+  }
+
+  #step(delta) {
+    if (this.#slides.length < 2) return
+    const count = this.#slides.length
+    this.#index = (this.#index + delta + count) % count
+    this.#render()
+  }
+
+  #close() {
+    if (!this.#box) return
+    const doc = this.ownerDocument
+    this.#box.classList.remove('is-open')
+    doc.documentElement.style.overflow = this.#prevOverflow ?? ''
+    if (this.#onKeydown) {
+      doc.removeEventListener('keydown', this.#onKeydown)
+      this.#onKeydown = null
+    }
+    if (this.#returnFocus && typeof this.#returnFocus.focus === 'function') {
+      this.#returnFocus.focus()
+    }
+  }
+}
+
+// Presentational text-role elements. No behavior — styled by tag name in
+// blueprint.css (lede paragraph, quiet aside, muted mono micro-label). They
+// exist as elements so authors compose with markup instead of utility classes.
+class BlueprintSubheaderElement extends HTMLElement {}
+class BlueprintNoteElement extends HTMLElement {}
+class BlueprintEyebrowElement extends HTMLElement {}
+
+// ---------------------------------------------------------------------
+// <bp-table> — an opt-in enhanced data table.
+//
+// A light-DOM wrapper around a plain author <table>; the <table> keeps its
+// base styling and the expanded form stays a valid stored document. On
+// upgrade the runtime wraps the table in a .bp-table-x scroll shell so
+// horizontal overflow is contained without making <bp-table> the sticky
+// header's scroll ancestor; wide / hover / sticky / compact are pure CSS
+// (attribute selectors in blueprint.css). The runtime's other job is the
+// value-specific work CSS cannot do: scan each column's <tbody> data cells
+// and, when they all read as numbers, end-align that column's <td> AND its
+// <th scope="col"> by stamping a .bp-col-num class.
+//
+//   <bp-table sticky density="compact" wide><table>…</table></bp-table>
+//
+// numeric: omit to auto-detect; `off` disables alignment; an explicit
+// 1-based list ("2,3") forces those columns. sticky pins the header + key
+// column; density="compact" tightens cells; wide breaks past the measure.
+// ---------------------------------------------------------------------
+
+// A cell reads as numeric: optional sign / currency, digits with optional
+// grouping and decimals, optional percent.
+const TABLE_NUMERIC = /^[+-]?[$€£¥]?\s?\d[\d,]*(\.\d+)?\s?%?$/
+// Dash / "n/a" placeholders count as empty (not as text), so a numeric
+// column with a few gaps still resolves as numeric.
+const TABLE_BLANK = /^(—|–|-|n\/?a)$/i
+
+class BlueprintTableElement extends HTMLElement {
+  static get observedAttributes() {
+    return ['numeric']
+  }
+
+  #observer = null
+  #applying = false
+
+  connectedCallback() {
+    this.#ensureScrollShell()
+    this.#apply()
+    if (typeof MutationObserver !== 'undefined' && !this.#observer) {
+      // Re-detect when the author's table content changes. Our own class
+      // edits are attribute mutations, which this observer ignores, so it
+      // cannot loop; the flag is belt-and-suspenders.
+      this.#observer = new MutationObserver(() => {
+        if (!this.#applying) this.#apply()
+      })
+      this.#observer.observe(this, { childList: true, subtree: true, characterData: true })
+    }
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect()
+    this.#observer = null
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) {
+      this.#ensureScrollShell()
+      this.#apply()
+    }
+  }
+
+  // Wrap the author's <table> in a horizontal scroll shell. Sticky header
+  // cells must stick to the page scrollport, not to <bp-table> — so overflow-x
+  // lives here, on .bp-table-x, instead of on the host.
+  #ensureScrollShell() {
+    const table = this.querySelector(':scope > table')
+    if (!table) return
+    let shell = this.querySelector(':scope > .bp-table-x')
+    if (!shell) {
+      shell = document.createElement('div')
+      shell.className = 'bp-table-x'
+      this.insertBefore(shell, table)
+    }
+    if (table.parentElement !== shell) shell.append(table)
+  }
+
+  // Resolve which 1-based columns end-align, then stamp .bp-col-num on the
+  // matching cells across thead / tbody / tfoot.
+  #apply() {
+    const table = this.querySelector('table')
+    if (!table) return
+    this.#applying = true
+    try {
+      for (const el of this.querySelectorAll('.bp-col-num')) {
+        el.classList.remove('bp-col-num')
+      }
+      const attr = (this.getAttribute('numeric') || '').trim().toLowerCase()
+      if (attr === 'off') return
+      let columns
+      if (attr) {
+        columns = new Set(
+          attr.split(',').map((n) => Number.parseInt(n, 10)).filter((n) => n > 0)
+        )
+        if (!columns.size) columns = this.#detect(table)
+      } else {
+        columns = this.#detect(table)
+      }
+      if (columns.size) this.#mark(table, columns)
+    } finally {
+      this.#applying = false
+    }
+  }
+
+  // A column is numeric when every non-blank <td> in it parses as a number.
+  // <th> cells (the key column) are skipped but still advance the column
+  // index so it stays aligned with the header row.
+  #detect(table) {
+    const tally = new Map()
+    for (const body of table.tBodies) {
+      for (const row of body.rows) {
+        let col = 0
+        for (const cell of row.cells) {
+          const span = cell.colSpan || 1
+          col += 1
+          if (cell.tagName === 'TH') {
+            col += span - 1
+            continue
+          }
+          const text = cell.textContent.trim()
+          if (!text || TABLE_BLANK.test(text)) continue
+          const rec = tally.get(col) || { total: 0, numeric: 0 }
+          rec.total += 1
+          if (TABLE_NUMERIC.test(text)) rec.numeric += 1
+          tally.set(col, rec)
+          col += span - 1
+        }
+      }
+    }
+    const columns = new Set()
+    for (const [col, rec] of tally) {
+      if (rec.total > 0 && rec.numeric === rec.total) columns.add(col)
+    }
+    return columns
+  }
+
+  // Stamp .bp-col-num on every cell whose 1-based column index is numeric.
+  #mark(table, columns) {
+    const stamp = (rows) => {
+      for (const row of rows) {
+        let col = 0
+        for (const cell of row.cells) {
+          const span = cell.colSpan || 1
+          col += 1
+          for (let i = 0; i < span; i += 1) {
+            if (columns.has(col + i)) {
+              cell.classList.add('bp-col-num')
+              break
+            }
+          }
+          col += span - 1
+        }
+      }
+    }
+    if (table.tHead) stamp(table.tHead.rows)
+    for (const body of table.tBodies) stamp(body.rows)
+    if (table.tFoot) stamp(table.tFoot.rows)
+  }
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('bp-toc')) {
+  customElements.define('bp-toc', BlueprintTocElement)
+}
+
 if (typeof customElements !== 'undefined' && !customElements.get('bp-callout')) {
   customElements.define('bp-callout', BlueprintCalloutElement)
 }
 
+if (typeof customElements !== 'undefined' && !customElements.get('bp-mock')) {
+  customElements.define('bp-mock', BlueprintMockElement)
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('bp-gallery')) {
+  customElements.define('bp-gallery', BlueprintGalleryElement)
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('bp-table')) {
+  customElements.define('bp-table', BlueprintTableElement)
+}
+
+if (typeof customElements !== 'undefined') {
+  for (const [name, ctor] of [
+    ['bp-subheader', BlueprintSubheaderElement],
+    ['bp-note', BlueprintNoteElement],
+    ['bp-eyebrow', BlueprintEyebrowElement],
+  ]) {
+    if (!customElements.get(name)) customElements.define(name, ctor)
+  }
+}
+
+// ---------------------------------------------------------------------
+// <bp-workplan> — a live "work plan" surface.
+//
+// Visualizes a set of typed, dependent tasks that resolve into waves of
+// work, rendered four ways (list · gantt · kanban · swimlanes). It is a
+// frame client: it reads its plan from a `.plan` property, the global
+// `window.__WORKPLAN__`, or a `{ type: 'workplan:update', plan }`
+// postMessage — so a host frame drives it and the author writes no task
+// data. With no plan it paints a "waiting for a plan" state.
+//
+//   <bp-workplan mode="gantt" header="…" subheader="…"></bp-workplan>
+//
+// mode: list|gantt|kanban|swimlanes pins a layout; omit it for the
+// built-in view selector. header/subheader override the plan's titles.
+// unit: hours|days sets the gantt axis. ignore-global opts out of the
+// window.__WORKPLAN__ source (postMessage only).
+// ---------------------------------------------------------------------
+;(() => {
+  const VIEW_OPTIONS = [
+    ['list', 'List'],
+    ['gantt', 'Gantt'],
+    ['kanban', 'Kanban'],
+    ['swimlanes', 'Swimlanes'],
+  ]
+
+  // Waves + readiness + a longest-path schedule, all derived (not authored).
+  function derive(plan) {
+    const byId = new Map(plan.tasks.map((t) => [t.id, t]))
+    const waveMemo = new Map()
+    const startMemo = new Map()
+
+    const wave = (id, trail = new Set()) => {
+      if (waveMemo.has(id)) return waveMemo.get(id)
+      const deps = byId.get(id)?.dependsOn ?? []
+      let w = 0
+      for (const d of deps) {
+        if (!byId.has(d) || trail.has(d)) continue
+        w = Math.max(w, wave(d, new Set([...trail, id])) + 1)
+      }
+      waveMemo.set(id, w)
+      return w
+    }
+
+    const start = (id, trail = new Set()) => {
+      if (startMemo.has(id)) return startMemo.get(id)
+      const deps = byId.get(id)?.dependsOn ?? []
+      let s = 0
+      for (const d of deps) {
+        const dep = byId.get(d)
+        if (!dep || trail.has(d)) continue
+        s = Math.max(s, start(d, new Set([...trail, id])) + (dep.effort ?? 1))
+      }
+      startMemo.set(id, s)
+      return s
+    }
+
+    return plan.tasks.map((t) => {
+      const deps = t.dependsOn ?? []
+      const blockedBy = deps.filter((d) => byId.get(d)?.status !== 'done')
+      const ready = blockedBy.length === 0
+      const s = start(t.id)
+      return {
+        ...t,
+        wave: wave(t.id),
+        ready,
+        locked: !ready && t.status !== 'done',
+        start: s,
+        finish: s + (t.effort ?? 1),
+        blockedBy,
+      }
+    })
+  }
+
+  function phase(t) {
+    if (t.status === 'done') return 'done'
+    if (t.locked) return 'blocked'
+    if (t.status === 'active') return 'active'
+    return 'ready'
+  }
+
+  const esc = (s) =>
+    String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]))
+
+  const TYPE_LABEL = {
+    research: 'Research',
+    write: 'Write',
+    review: 'Review',
+    design: 'Design',
+    code: 'Code',
+  }
+
+  const CI_LABEL = {
+    running: 'Tests running',
+    failed: 'CI failed',
+    passed: 'CI passed',
+    approved: 'Approved',
+  }
+
+  const UNIT_SUFFIX = { hours: 'h', days: 'd' }
+  const UNIT_AXIS = { hours: 'Hours', days: 'Days' }
+
+  // 16×16 glyphs, drawn in currentColor; UI chrome stays on the ink scale.
+  const TYPE_ICON = {
+    research: '<circle cx="7" cy="7" r="4.2"/><path d="M10 10l4 4"/>',
+    write: '<path d="M3 13l8.5-8.5 2.5 2.5L5.5 15.5 2.5 16z"/><path d="M11 5l2.5 2.5"/>',
+    review: '<path d="M2 8s2.4-4 6-4 6 4 6 4-2.4 4-6 4-6-4-6-4z"/><circle cx="8" cy="8" r="1.8"/>',
+    design: '<path d="M8 2v12"/><path d="M8 2l4.5 10.5a5 5 0 01-9 0z"/>',
+    code: '<path d="M6 4L2 8l4 4"/><path d="M10 4l4 4-4 4"/>',
+  }
+
+  const CI_ICON = {
+    running: '<circle cx="8" cy="8" r="5.4" stroke-dasharray="3 3"/>',
+    failed: '<circle cx="8" cy="8" r="6"/><path d="M5.5 5.5l5 5M10.5 5.5l-5 5"/>',
+    passed: '<circle cx="8" cy="8" r="6"/><path d="M5 8.2l2 2 4-4.4"/>',
+    approved: '<path d="M3 8.4l2.2 2.2 4.4-4.8"/><path d="M7 8.4l2.2 2.2 4.4-4.8"/>',
+  }
+
+  // 8-point spark — the mark for automated (agent) work.
+  const AGENT_ICON = '<path d="M8 1.5v13M1.5 8h13M3.7 3.7l8.6 8.6M12.3 3.7l-8.6 8.6"/>'
+
+  const svgMark = (paths, cls) =>
+    `<svg class="${cls}" viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${paths}</svg>`
+
+  const typeBadge = (t) =>
+    `<span class="wp-type wp-type--${t}">${svgMark(TYPE_ICON[t], 'wp-type__glyph')}<span class="wp-type__label">${TYPE_LABEL[t]}</span></span>`
+
+  const phaseDot = (p) => `<span class="wp-dot wp-dot--${p}" role="img" aria-label="${p}"></span>`
+
+  // Inline (no pill) PR status: glyph for running/failed, positive ink for
+  // passed/approved, mono throughout. `compact` drops the diff stat.
+  function prStatus(pr, compact = false) {
+    const needsGlyph = pr.ci === 'running' || pr.ci === 'failed'
+    const diff =
+      !compact && pr.additions != null
+        ? `<span class="wp-pr__diff"><span class="wp-pr__add">+${pr.additions}</span> <span class="wp-pr__del">\u2212${pr.deletions ?? 0}</span></span>`
+        : ''
+    return (
+      `<span class="wp-pr wp-pr--${pr.ci}" title="${esc(`PR #${pr.number} — ${CI_LABEL[pr.ci]}`)}">` +
+      (needsGlyph ? svgMark(CI_ICON[pr.ci], 'wp-pr__glyph') : '') +
+      `<span class="wp-pr__num">#${pr.number}</span>` +
+      `<span class="wp-pr__ci">${esc(CI_LABEL[pr.ci])}</span>` +
+      diff +
+      `</span>`
+    )
+  }
+
+  function initials(name) {
+    const parts = name.trim().split(/\s+/)
+    if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase()
+    return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase()
+  }
+
+  // Agent → spark mark (square); human → initials monogram (circle).
+  function ownerMark(owner) {
+    if (!owner) return ''
+    if (owner.kind === 'agent') {
+      return `<span class="wp-owner wp-owner--agent" title="${esc(owner.name)} (agent)">${svgMark(AGENT_ICON, 'wp-owner__glyph')}</span>`
+    }
+    return `<span class="wp-owner wp-owner--human" title="${esc(owner.name)}">${esc(initials(owner.name))}</span>`
+  }
+
+  function waitLabel(t, byId) {
+    const names = t.blockedBy.map((d) => byId.get(d)?.name ?? d)
+    return `Waiting on ${names.join(', ')}`
+  }
+
+  function waitNote(t, byId) {
+    if (!t.locked) return ''
+    const label = waitLabel(t, byId)
+    return `<span class="wp-wait" title="${esc(label)}">${esc(label)}</span>`
+  }
+
+  function groupByWave(tasks) {
+    const map = new Map()
+    for (const t of tasks) {
+      const arr = map.get(t.wave) ?? []
+      arr.push(t)
+      map.set(t.wave, arr)
+    }
+    return [...map.entries()].sort((a, b) => a[0] - b[0])
+  }
+
+  function renderList(tasks, byId) {
+    const blocks = groupByWave(tasks)
+      .map(
+        ([w, items]) => `
+        <div class="wp-wave">
+          <div class="wp-wave__head">
+            <span class="wp-wave__no">Wave ${w + 1}</span>
+            <span class="wp-wave__count">${items.length} task${items.length === 1 ? '' : 's'}</span>
+          </div>
+          <div class="wp-list">
+            ${items
+              .map((t) => {
+                const p = phase(t)
+                return `
+                <div class="wp-row wp-row--${p}" data-locked="${t.locked}">
+                  ${phaseDot(p)}
+                  ${typeBadge(t.type)}
+                  <span class="wp-row__main">
+                    <span class="wp-row__name">${esc(t.name)}</span>
+                    ${waitNote(t, byId)}
+                  </span>
+                  <span class="wp-row__pr">${t.pr ? prStatus(t.pr) : ''}</span>
+                  ${ownerMark(t.owner)}
+                </div>`
+              })
+              .join('')}
+          </div>
+        </div>`
+      )
+      .join('')
+    return `<div class="wp-view wp-view--list">${blocks}</div>`
+  }
+
+  function renderKanban(tasks, byId) {
+    const cols = [
+      { key: 'blocked', title: 'Blocked' },
+      { key: 'ready', title: 'Ready' },
+      { key: 'active', title: 'In progress' },
+      { key: 'done', title: 'Done' },
+    ]
+    const columns = cols
+      .map(({ key, title }) => {
+        const items = tasks.filter((t) => phase(t) === key)
+        return `
+        <div class="wp-col wp-col--${key}">
+          <div class="wp-col__head">
+            <span class="wp-col__title">${title}</span>
+            <span class="wp-col__count">${items.length}</span>
+          </div>
+          <div class="wp-col__body">
+            ${
+              items.length === 0
+                ? '<div class="wp-col__empty">No tasks</div>'
+                : items
+                    .map(
+                      (t) => `
+              <div class="wp-card wp-card--${key}" data-locked="${t.locked}"${t.locked ? ` title="${esc(waitLabel(t, byId))}"` : ''}>
+                <div class="wp-card__top">
+                  ${typeBadge(t.type)}
+                  ${phaseDot(phase(t))}
+                </div>
+                <div class="wp-card__name">${esc(t.name)}</div>
+                ${t.pr ? `<div class="wp-card__pr">${prStatus(t.pr, true)}</div>` : ''}
+                <div class="wp-card__foot">
+                  <span class="wp-card__wave">Wave ${t.wave + 1}</span>
+                  ${ownerMark(t.owner)}
+                </div>
+              </div>`
+                    )
+                    .join('')
+            }
+          </div>
+        </div>`
+      })
+      .join('')
+    return `<div class="wp-view wp-view--kanban">${columns}</div>`
+  }
+
+  function renderSwimlanes(tasks) {
+    const order = ['research', 'design', 'write', 'code', 'review']
+    const maxWave = Math.max(0, ...tasks.map((t) => t.wave))
+    const header =
+      `<div class="wp-swim__corner">Type \u00d7 wave</div>` +
+      Array.from({ length: maxWave + 1 }, (_, w) => `<div class="wp-swim__whead">Wave ${w + 1}</div>`).join('')
+    const lanes = order
+      .filter((type) => tasks.some((t) => t.type === type))
+      .map((type) => {
+        const cells = Array.from({ length: maxWave + 1 }, (_, w) => {
+          const items = tasks.filter((t) => t.type === type && t.wave === w)
+          return `<div class="wp-swim__cell">${items
+            .map((t) => {
+              const p = phase(t)
+              return `<div class="wp-chip wp-chip--${p}" data-locked="${t.locked}" title="${esc(t.name)}">
+                <div class="wp-chip__head">
+                  ${phaseDot(p)}
+                  <span class="wp-chip__name">${esc(t.name)}</span>
+                  ${ownerMark(t.owner)}
+                </div>
+                ${t.pr ? `<div class="wp-chip__pr">${prStatus(t.pr, true)}</div>` : ''}
+              </div>`
+            })
+            .join('')}</div>`
+        }).join('')
+        return `<div class="wp-swim__lanehead">${typeBadge(type)}</div>${cells}`
+      })
+      .join('')
+    return `<div class="wp-view wp-view--swim" style="--wp-waves:${maxWave + 1}">${header}${lanes}</div>`
+  }
+
+  function renderGantt(tasks, unit) {
+    const span = Math.max(1, ...tasks.map((t) => t.finish))
+    const suffix = UNIT_SUFFIX[unit]
+    const axis = Array.from(
+      { length: span + 1 },
+      (_, d) => `<span class="wp-gantt__tick" style="--at:${d}">${d}</span>`
+    ).join('')
+    const rows = [...tasks]
+      .sort((a, b) => a.start - b.start || a.wave - b.wave)
+      .map((t) => {
+        const p = phase(t)
+        const pct = (n) => (n / span) * 100
+        return `
+        <div class="wp-gantt__row wp-gantt__row--${p}" data-locked="${t.locked}">
+          <div class="wp-gantt__label">
+            ${typeBadge(t.type)}
+            <span class="wp-gantt__name">${esc(t.name)}</span>
+            ${ownerMark(t.owner)}
+          </div>
+          <div class="wp-gantt__track">
+            <div class="wp-gantt__bar wp-gantt__bar--${p}" style="left:${pct(t.start)}%;width:${pct(t.finish - t.start)}%">
+              ${phaseDot(p)}
+              <span class="wp-gantt__bar-label">${t.pr ? `#${t.pr.number}` : `${t.effort ?? 1}${suffix}`}</span>
+            </div>
+          </div>
+        </div>`
+      })
+      .join('')
+    return `<div class="wp-view wp-view--gantt">
+      <div class="wp-gantt__row wp-gantt__row--axis">
+        <div class="wp-gantt__label wp-gantt__label--axis">${UNIT_AXIS[unit]} \u2192</div>
+        <div class="wp-gantt__track wp-gantt__track--axis" style="--span:${span}">${axis}</div>
+      </div>
+      ${rows}
+    </div>`
+  }
+
+  function summarize(tasks) {
+    return {
+      total: tasks.length,
+      done: tasks.filter((t) => t.status === 'done').length,
+      active: tasks.filter((t) => phase(t) === 'active').length,
+      blocked: tasks.filter((t) => t.locked).length,
+      waves: new Set(tasks.map((t) => t.wave)).size,
+    }
+  }
+
+  function renderEmpty() {
+    return `<div class="wp-empty" role="status">
+      <svg viewBox="0 0 48 48" width="48" height="48" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="wp-empty__art">
+        <rect x="7" y="9" width="34" height="30" rx="2"/>
+        <path d="M7 17h34"/>
+        <path d="M13 24h10M13 30h16" stroke-dasharray="2 3"/>
+        <circle cx="33" cy="29" r="6"/>
+        <path d="M33 26v3l2 2"/>
+      </svg>
+      <div class="wp-empty__title">Waiting for a plan</div>
+      <div class="wp-empty__hint">No work plan has been received yet. The host frame will post one over <span class="wp-mono">postMessage</span>.</div>
+    </div>`
+  }
+
+  const MESSAGE_TYPE = 'workplan:update'
+  const GLOBAL_KEY = '__WORKPLAN__'
+  const MODES = new Set(['list', 'gantt', 'kanban', 'swimlanes'])
+
+  class BlueprintWorkplanElement extends HTMLElement {
+    static get observedAttributes() {
+      return ['mode', 'unit', 'header', 'subheader']
+    }
+
+    #plan = null
+    #root = null
+    #activeView = 'list'
+    #onMessage = (e) => this.#handleMessage(e)
+    #onClick = (e) => this.#handleClick(e)
+
+    set plan(value) {
+      this.#plan = value
+      this.#render()
+    }
+    get plan() {
+      return this.#plan
+    }
+
+    get mode() {
+      const m = this.getAttribute('mode')
+      return MODES.has(m) ? m : null
+    }
+
+    get unit() {
+      return this.getAttribute('unit') === 'days' ? 'days' : 'hours'
+    }
+
+    connectedCallback() {
+      if (!this.#root) {
+        this.#root = this.ownerDocument.createElement('div')
+        this.#root.className = 'bp-workplan'
+        this.#root.addEventListener('click', this.#onClick)
+        this.replaceChildren(this.#root)
+      }
+      if (!this.#plan && !this.hasAttribute('ignore-global')) {
+        const fromGlobal = this.ownerDocument.defaultView?.[GLOBAL_KEY]
+        if (fromGlobal) this.#plan = fromGlobal
+      }
+      this.ownerDocument.defaultView?.addEventListener('message', this.#onMessage)
+      this.#render()
+    }
+
+    disconnectedCallback() {
+      this.ownerDocument.defaultView?.removeEventListener('message', this.#onMessage)
+    }
+
+    attributeChangedCallback() {
+      this.#render()
+    }
+
+    #handleMessage(e) {
+      const data = e.data
+      if (!data || data.type !== MESSAGE_TYPE || !data.plan) return
+      this.#plan = data.plan
+      this.#render()
+    }
+
+    // Delegated: the toolbar's buttons live in re-rendered markup, so we
+    // listen on the persistent root and read intent off data-attributes.
+    #handleClick(e) {
+      const target = e.target
+      const btn = target instanceof Element ? target.closest('[data-wp-view],[data-wp-unit]') : null
+      if (!btn || !this.#root?.contains(btn)) return
+      const view = btn.getAttribute('data-wp-view')
+      if (view) {
+        this.#activeView = view
+        this.#render()
+        return
+      }
+      const unit = btn.getAttribute('data-wp-unit')
+      if (unit) this.setAttribute('unit', unit)
+    }
+
+    get #view() {
+      return this.mode ?? this.#activeView
+    }
+
+    #toolbar(view, showModes) {
+      const modes = showModes
+        ? `<div class="wp-modes" role="tablist" aria-label="Choose a view">` +
+          VIEW_OPTIONS.map(
+            ([v, label]) =>
+              `<button class="wp-modes__btn" type="button" role="tab" aria-selected="${v === view}" data-wp-view="${v}">${label}</button>`
+          ).join('') +
+          `</div>`
+        : ''
+      const unit =
+        view === 'gantt'
+          ? `<div class="wp-modes wp-modes--unit" role="group" aria-label="Time unit">` +
+            ['hours', 'days']
+              .map(
+                (u) =>
+                  `<button class="wp-modes__btn" type="button" aria-selected="${u === this.unit}" data-wp-unit="${u}">${UNIT_AXIS[u]}</button>`
+              )
+              .join('') +
+            `</div>`
+          : ''
+      return modes || unit ? `<div class="wp-toolbar">${modes}${unit}</div>` : ''
+    }
+
+    #render() {
+      if (!this.#root) return
+      const plan = this.#plan
+      const hasData = !!plan && Array.isArray(plan.tasks) && plan.tasks.length > 0
+      const view = this.#view
+      const showModes = this.mode === null
+
+      const title = this.getAttribute('header') ?? plan?.title ?? ''
+      const subtitle = this.getAttribute('subheader') ?? plan?.subtitle ?? ''
+
+      let stats = ''
+      let body = ''
+      if (hasData) {
+        this.#root.dataset.state = 'ready'
+        const derived = derive(plan)
+        const byId = new Map(plan.tasks.map((t) => [t.id, t]))
+        const counts = summarize(derived)
+        stats =
+          `<div class="wp-stats">` +
+          `<div class="wp-stat"><span class="wp-stat__k">Done</span><span class="wp-stat__v">${counts.done}/${counts.total}</span></div>` +
+          `<div class="wp-stat"><span class="wp-stat__k">Active</span><span class="wp-stat__v">${counts.active}</span></div>` +
+          `<div class="wp-stat"><span class="wp-stat__k">Blocked</span><span class="wp-stat__v">${counts.blocked}</span></div>` +
+          `<div class="wp-stat"><span class="wp-stat__k">Waves</span><span class="wp-stat__v">${counts.waves}</span></div>` +
+          `</div>`
+        body =
+          view === 'gantt'
+            ? renderGantt(derived, this.unit)
+            : view === 'kanban'
+              ? renderKanban(derived, byId)
+              : view === 'swimlanes'
+                ? renderSwimlanes(derived)
+                : renderList(derived, byId)
+      } else {
+        this.#root.dataset.state = 'empty'
+        body = renderEmpty()
+      }
+
+      const head =
+        title || subtitle || stats
+          ? `<div class="wp-head">` +
+            `<div class="wp-head__title">` +
+            (title ? `<div class="wp-head__name">${esc(title)}</div>` : '') +
+            (subtitle ? `<div class="wp-head__sub">${esc(subtitle)}</div>` : '') +
+            `</div>` +
+            stats +
+            `</div>`
+          : ''
+
+      const toolbar = hasData ? this.#toolbar(view, showModes) : ''
+
+      this.#root.innerHTML = head + toolbar + `<div class="wp-canvas">${body}</div>`
+    }
+  }
+
+  if (typeof customElements !== 'undefined' && !customElements.get('bp-workplan')) {
+    customElements.define('bp-workplan', BlueprintWorkplanElement)
+  }
+})()
+
 if (typeof document !== 'undefined') {
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', () => initializeBlueprintRuntime(), { once: true })