@obvi/blueprint 1.1.0 → 1.1.1

package/README.md

@@ -11,6 +11,7 @@ A blueprint is a technical document that should look like one: monochrome ink on
 - **Semantic HTML is the API.** Headings, paragraphs, lists, tables, figures, and landmarks render as a finished document with no classes to memorize. You write meaning; the design arrives for free.
 - **Classless-first, not class-only.** Components exist only for the few patterns native HTML cannot express, and each is a composition of real semantic elements rather than a replacement for them.
 - **Zero-specificity by contract.** Everything ships in cascade layers wrapped in `:where()`, so the library never fights your own CSS. Your styles always win, with no `!important` and no parent-scoping.
+- **Runtime-complete package.** The default stylesheet includes the chrome that `blueprint.js` injects, and runtime icons are inline SVG, so installed documents do not depend on repository-only CSS or assets.
 
 The result is one portable stylesheet, no build step, that turns plain semantic markup into a polished blueprint.
 

package/dist/blueprint.css

@@ -2814,9 +2814,12 @@
     padding-bottom: var(--bp-shell-inset-block);
   }
   /* <main> is the paper sheet spanning the full column between the vertical
-     frame rules; direct children keep the prose measure from Tier 1b. */
+     frame rules; direct children keep the prose measure from Tier 1b. Keep the
+     shell out of the overflow/scroll chain so viewport-fixed navigation nested
+     by stored Blueprints is not clipped by WebKit. The page owns scrolling. */
   :where(html[data-bp-document] main) {
     max-width: none;
+    overflow: visible;
     margin: 0 var(--bp-shell-inset-right) 0 var(--bp-shell-inset-left);
     min-height: calc(
       100vh - var(--bp-shell-inset-top) - var(--bp-shell-inset-block)
@@ -4192,3 +4195,1038 @@
     }
   }
 }
+
+/* Shared document chrome. This stays separate in source so the docs site can
+   iterate on it independently, but the npm build appends it to the default
+   blueprint.css export because blueprint.js injects these runtime elements. */
+
+:root {
+  --bp-site-nav-height: 44px;
+}
+
+/* Only the pages that still use the top bar (e.g. the code demo) reserve
+   space for it. The main docs page drops it in favor of the sidebar
+   blueprint switcher + bottom-left theme toggle below. */
+body:has(.site-nav) {
+  padding-top: var(--bp-site-nav-height);
+}
+
+/* Frame and shell top inset align below the site nav. */
+html[data-bp-document]:has(.site-nav) {
+  --bp-shell-inset-top: calc(var(--bp-site-nav-height) + var(--bp-shell-inset-block));
+}
+
+.site-nav {
+  position: fixed;
+  inset: 0 0 auto;
+  z-index: 400;
+  display: flex;
+  align-items: stretch;
+  height: var(--bp-site-nav-height);
+  padding: 0 16px;
+  border-bottom: 1px solid var(--bp-edge);
+  background: var(--bp-paper);
+  color: var(--bp-text);
+  font-family: var(--bp-mono, var(--mono, ui-monospace, monospace));
+  font-size: 11px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.site-nav__brand,
+.site-nav a {
+  display: flex;
+  align-items: center;
+  min-height: 0;
+  padding: 0 12px;
+  color: var(--bp-text-secondary);
+  text-decoration: none;
+}
+
+.site-nav__brand {
+  gap: 8px;
+  padding-left: 0;
+  color: var(--bp-ink);
+  font-weight: 650;
+  letter-spacing: 0.04em;
+  text-transform: none;
+}
+
+.site-nav__logo {
+  width: 20px;
+  height: 20px;
+  flex: 0 0 20px;
+  color: var(--bp-ink);
+}
+
+.site-nav__links {
+  display: flex;
+  align-items: stretch;
+  gap: 2px;
+  margin: 0 0 0 12px;
+  padding: 0;
+  list-style: none;
+}
+
+.site-nav__links > li {
+  display: flex;
+  margin: 0;
+  line-height: 1;
+}
+
+.site-nav a:hover,
+.site-nav a[aria-current="page"] {
+  color: var(--bp-ink);
+  background: var(--bp-fill-amb);
+}
+
+.site-nav a:focus-visible,
+.site-nav button:focus-visible {
+  outline: 2px solid var(--bp-ink);
+  outline-offset: -2px;
+}
+
+body > .site-nav .site-nav__theme {
+  position: static;
+  inset: auto;
+  z-index: auto;
+  align-self: center;
+  margin: 0 0 0 auto;
+  padding: 6px 10px;
+  border: 1px solid var(--bp-ink);
+  border-radius: var(--bp-radius-0, 0);
+  background: oklch(0 0 0 / 0);
+  color: var(--bp-ink);
+  font-family: inherit;
+  font-size: inherit;
+  letter-spacing: inherit;
+  line-height: 1;
+  text-transform: uppercase;
+  cursor: pointer;
+}
+
+body > .site-nav .site-nav__theme:hover {
+  background: var(--bp-fill-amb);
+}
+
+/* The docs sidebar remains fixed, but begins below the global site nav. */
+.site-nav ~ .bp-sidebar {
+  top: var(--bp-site-nav-height);
+  height: calc(100vh - var(--bp-site-nav-height));
+}
+
+.site-nav + .scroll-progress {
+  position: fixed;
+  top: calc(var(--bp-site-nav-height)+ 4px);
+  right: 0;
+  left: 0;
+  height: 2px;
+  background: var(--bp-ink);
+  transform: scaleX(0);
+  transform-origin: left;
+  z-index: 500;
+  pointer-events: none;
+  transition: transform var(--bp-duration-instant) var(--bp-ease-linear);
+}
+
+@media (max-width: 560px) {
+  :root {
+    --bp-site-nav-height: 40px;
+  }
+
+  .site-nav {
+    padding: 0 8px;
+  }
+
+  .site-nav__brand {
+    padding: 0 8px 0 0;
+  }
+
+  .site-nav__wordmark {
+    display: none;
+  }
+
+  .site-nav__links {
+    margin-left: 0;
+  }
+
+  .site-nav a {
+    padding: 0 8px;
+  }
+
+  body > .site-nav .site-nav__theme {
+    padding: 6px 8px;
+  }
+}
+
+/* =====================================================================
+   Blueprint collection switcher (sidebar header) + bottom-left theme toggle
+   ---------------------------------------------------------------------
+   Docs chrome that replaces the old top bar: the sidebar wordmark becomes
+   a menu for jumping between blueprints, and the theme control becomes a
+   line icon pinned to the bottom-left corner.
+   ===================================================================== */
+
+/* Reset the library <details>/<summary> chrome for the switcher. */
+.doc-switcher {
+  position: relative;
+  margin: 0 0 var(--bp-space-3);
+  padding: 0;
+  border: 0;
+  background: none;
+}
+/* Shared field chrome for the switcher trigger and the search input so they
+   read as one control family (border, radius, surface + hover/focus states). */
+.sidebar-field {
+  border: 1px solid var(--bp-edge);
+  border-radius: var(--bp-radius-6, 6px);
+  background: var(--bp-paper);
+  /* Hover-only color motion — idle fields snap on theme flip so the root
+     view-transition crossfade isn't fighting per-field token tweens. */
+  transition: none;
+}
+.sidebar-field:hover,
+.sidebar-field:focus-within {
+  border-color: var(--bp-ink-line);
+  background: var(--bp-fill-amb);
+  transition:
+    border-color var(--bp-duration-fast) var(--bp-ease-out),
+    background-color var(--bp-duration-fast) var(--bp-ease-out);
+}
+.doc-switcher__current {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--bp-space-3);
+  margin: 0;
+  /* Match the sidebar toggle box so the two controls align on one row. */
+  height: var(--bp-sidebar-toggle-size);
+  padding: 0 var(--bp-space-3);
+  list-style: none;
+  font-weight: 400;
+  cursor: pointer;
+}
+.doc-switcher__current::-webkit-details-marker {
+  display: none;
+}
+.doc-switcher__current::before {
+  content: none !important;
+}
+.doc-switcher__label {
+  display: flex;
+  flex-direction: column;
+  gap: var(--bp-space-1);
+  min-width: 0;
+}
+.doc-switcher__title {
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+}
+.doc-switcher__meta {
+  display: none;
+}
+.doc-switcher__chevron {
+  display: inline-flex;
+  flex: 0 0 auto;
+  color: var(--bp-text-secondary);
+}
+.doc-switcher[open] .doc-switcher__chevron {
+  transform: rotate(180deg);
+}
+.doc-switcher__menu {
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: calc(100% + var(--bp-space-1));
+  z-index: 300;
+  display: flex;
+  flex-direction: column;
+  gap: var(--bp-space-1);
+  padding: var(--bp-space-1);
+  border: 1px solid var(--bp-edge);
+  /* Container radius − padding = item radius, so the rows nest perfectly. */
+  border-radius: var(--bp-radius-8, 8px);
+  background: var(--bp-paper);
+  box-shadow: var(--bp-shadow-pop);
+  transform-origin: top center;
+}
+/* Open animation: keyframes re-run every time [open] is set on the <details>,
+   unlike @starting-style which only fires on first render. Close stays instant
+   (native <details> hides content immediately). Timing uses motion tokens. */
+.doc-switcher[open] .doc-switcher__menu {
+  animation: bp-doc-switcher-in var(--bp-duration-normal) var(--bp-ease-out);
+}
+@keyframes bp-doc-switcher-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+.doc-switcher__menu a {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--bp-space-2);
+  padding: var(--bp-space-2) var(--bp-space-3);
+  border-radius: var(--bp-radius-4, 4px);
+  text-decoration: none;
+}
+.doc-switcher__menu a:hover {
+  background: var(--bp-fill-amb);
+}
+.doc-switcher__menu a.is-current {
+  background: var(--bp-fill-hi);
+}
+.doc-switcher__option {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+.doc-switcher__name {
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+}
+.doc-switcher__desc {
+  overflow: hidden;
+  font-size: var(--bp-label-md);
+  line-height: 1.4;
+  color: var(--bp-text-secondary);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+/* Reused chevron as a quiet "go to" affordance — only on the current and
+   hovered rows so the resting menu stays clean and condensed. */
+.doc-switcher__go {
+  flex: 0 0 auto;
+  display: inline-flex;
+  color: var(--bp-text-secondary);
+  opacity: 0;
+  transform: rotate(-90deg);
+}
+.doc-switcher__menu a:hover .doc-switcher__go,
+.doc-switcher__menu a.is-current .doc-switcher__go {
+  opacity: 1;
+}
+
+/* Sidebar search — header row beside the corner toggle, above the header scrim. */
+.sidebar-search {
+  position: relative;
+  /* Sit above the header scrim (z 200) so the field stays crisp while the TOC
+     fades behind it. */
+  z-index: 300;
+  /* Left margin clears the fixed corner toggle so search sits on the same row,
+     beside it. Right edge stops at the content edge so it lines up with the
+     TOC entry pills below. */
+  margin: calc(-1 * var(--bp-space-2)) 0 var(--bp-space-3)
+    calc(var(--bp-sidebar-toggle-size) + var(--bp-space-3));
+}
+/* Trigger button: magnifier + label + ⌘K hint on one row. It is a <button>
+   (it opens the search dialog, it is not a text field); the .sidebar-field
+   chrome carries the border/radius/surface and children align inside it. */
+.sidebar-search__field {
+  display: flex;
+  align-items: center;
+  gap: var(--bp-space-2);
+  width: 100%;
+  height: var(--bp-sidebar-toggle-size);
+  padding: 0 var(--bp-space-3);
+  font: inherit;
+  text-align: left;
+  color: inherit;
+  cursor: pointer;
+  -webkit-appearance: none;
+  appearance: none;
+}
+.sidebar-search__field:focus-visible {
+  outline: 2px solid var(--bp-ink);
+  outline-offset: 2px;
+}
+.sidebar-search__icon {
+  flex: 0 0 auto;
+  display: inline-flex;
+  color: var(--bp-text-secondary);
+}
+.sidebar-search__label {
+  flex: 1 1 auto;
+  min-width: 0;
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: 400;
+  color: var(--bp-text-secondary);
+}
+/* ⌘K affordance — quiet keycaps, sized down from the base kbd for the rail. */
+.sidebar-search__hint {
+  flex: 0 0 auto;
+  display: inline-flex;
+  gap: 2px;
+}
+.sidebar-search__hint kbd {
+  padding: 0 4px;
+  border-width: 1px;
+  border-radius: var(--bp-radius-2, 2px);
+  font-size: var(--bp-label-md);
+  line-height: 1.5;
+  color: var(--bp-text-secondary);
+}
+
+/* =====================================================================
+   Search command menu (docs chrome) — Mintlify-style palette
+   ---------------------------------------------------------------------
+   Opened from the sidebar trigger or ⌘K / Ctrl+K (see wireSearchPalette).
+   Reuses the rounded sidebar control family: paper surface, --bp-radius-8
+   panel with --bp-shadow-pop, --bp-radius-4 rows, the --bp-fill-amb /
+   --bp-fill-hi hover + selected surfaces, and the shared open animation.
+   Chrome stays on the neutral ink scale. Query filtering is a plain
+   substring match over the page's headings; richer search is deferred.
+   ===================================================================== */
+
+/* Modal scrim. Hidden until .is-open; centers the panel near the top of the
+   viewport, the way command palettes sit. Sits above all docs chrome. Uses
+   the same drafting scrim as .bp-lightbox (--bp-scrim + --bp-hatch). */
+.docs-search-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 600;
+  display: none;
+  justify-content: center;
+  align-items: flex-start;
+  padding: clamp(var(--bp-space-5), 12vh, var(--bp-space-7)) var(--bp-space-4)
+    var(--bp-space-4);
+  background-color: var(--bp-scrim);
+  background-image: var(--bp-hatch);
+}
+.docs-search-overlay.is-open {
+  display: flex;
+  animation: bp-search-overlay-in var(--bp-duration-fast, 120ms)
+    var(--bp-ease-out);
+}
+.docs-search-overlay.is-open .docs-search {
+  animation: bp-doc-switcher-in var(--bp-duration-normal) var(--bp-ease-out);
+}
+@keyframes bp-search-overlay-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+/* The panel. Position-agnostic: the overlay wrapper centers it over a scrim. */
+.docs-search {
+  display: flex;
+  flex-direction: column;
+  width: min(640px, 100%);
+  max-height: min(560px, 80vh);
+  overflow: hidden;
+  border: 1px solid var(--bp-edge);
+  border-radius: var(--bp-radius-8, 8px);
+  background: var(--bp-paper);
+  box-shadow: var(--bp-shadow-pop);
+}
+
+/* Search row */
+.docs-search__field {
+  display: flex;
+  align-items: center;
+  gap: var(--bp-space-3);
+  padding: var(--bp-space-3) var(--bp-space-4);
+  border-bottom: 1px solid var(--bp-edge);
+}
+.docs-search__icon {
+  flex: 0 0 auto;
+  display: inline-flex;
+  color: var(--bp-text-secondary);
+}
+.docs-search__input {
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-body);
+  line-height: var(--bp-lh-body);
+  color: var(--bp-text);
+  -webkit-appearance: none;
+  appearance: none;
+}
+.docs-search__input::placeholder {
+  color: var(--bp-text-secondary);
+}
+.docs-search__input:focus {
+  outline: none;
+}
+.docs-search__input::-webkit-search-decoration,
+.docs-search__input::-webkit-search-cancel-button {
+  -webkit-appearance: none;
+}
+.docs-search__esc {
+  flex: 0 0 auto;
+  padding: 1px 6px;
+  font-size: var(--bp-label-md);
+  letter-spacing: var(--bp-label-md-ls);
+  text-transform: uppercase;
+  color: var(--bp-text-secondary);
+}
+
+/* Results region */
+.docs-search__results {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  padding: var(--bp-space-2);
+}
+/* Group label — machine voice (mono + uppercase) with a trailing count. */
+.docs-search__group {
+  display: flex;
+  align-items: center;
+  gap: var(--bp-space-2);
+  padding: var(--bp-space-2) var(--bp-space-3) var(--bp-space-1);
+  font-family: var(--bp-mono);
+  font-size: var(--bp-label-md);
+  letter-spacing: var(--bp-label-md-ls);
+  text-transform: uppercase;
+  color: var(--bp-text-secondary);
+}
+.docs-search__group-count {
+  color: var(--bp-text-secondary);
+  opacity: 0.7;
+}
+
+/* A result row: breadcrumb · title · snippet, with a trailing return key.
+   Rows are <a> for navigation; suppress the base prose link underline except
+   on the selected/hovered surface (background carries the affordance). */
+.docs-search__row {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  align-items: center;
+  gap: var(--bp-space-1) var(--bp-space-3);
+  padding: var(--bp-space-2) var(--bp-space-3);
+  border-radius: var(--bp-radius-4, 4px);
+  cursor: pointer;
+  text-decoration: none;
+  color: inherit;
+}
+.docs-search__row:hover {
+  background: var(--bp-fill-amb);
+  text-decoration: none;
+}
+/* Keyboard-selected row — reuses the rail's "current" surface. */
+.docs-search__row[aria-selected="true"] {
+  background: var(--bp-fill-hi);
+  text-decoration: none;
+}
+.docs-search__row-main {
+  display: flex;
+  flex-direction: column;
+  gap: var(--bp-space-1);
+  min-width: 0;
+}
+.docs-search__crumb {
+  display: block;
+  font-family: var(--bp-mono);
+  font-size: var(--bp-label-md);
+  letter-spacing: var(--bp-label-md-ls);
+  color: var(--bp-text-secondary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.docs-search__title {
+  display: flex;
+  align-items: baseline;
+  gap: var(--bp-space-1);
+  min-width: 0;
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+}
+/* The "#" anchor glyph borrows the machine voice so it reads as a heading
+   link, not prose. */
+.docs-search__hash {
+  flex: 0 0 auto;
+  font-family: var(--bp-mono);
+  color: var(--bp-text-secondary);
+}
+.docs-search__snippet {
+  overflow: hidden;
+  font-size: var(--bp-text-small);
+  line-height: 1.4;
+  color: var(--bp-text-secondary);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.docs-search__snippet mark {
+  padding: 0;
+  background: var(--bp-highlight);
+  color: var(--bp-text);
+}
+/* Return-key affordance — only on the selected/hovered row, like the
+   switcher's quiet "go to" chevron. */
+.docs-search__enter {
+  flex: 0 0 auto;
+  align-self: center;
+  padding: 1px 5px;
+  font-size: var(--bp-label-md);
+  color: var(--bp-text-secondary);
+  opacity: 0;
+}
+.docs-search__row:hover .docs-search__enter,
+.docs-search__row[aria-selected="true"] .docs-search__enter {
+  opacity: 1;
+}
+
+/* Empty state */
+.docs-search__empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--bp-space-2);
+  padding: var(--bp-space-6) var(--bp-space-4);
+  text-align: center;
+}
+.docs-search__empty-icon {
+  display: inline-flex;
+  color: var(--bp-text-secondary);
+  opacity: 0.6;
+}
+.docs-search__empty-title {
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-small);
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+}
+.docs-search__empty-note {
+  font-size: var(--bp-text-small);
+  color: var(--bp-text-secondary);
+}
+
+/* Footer keyboard legend */
+.docs-search__foot {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--bp-space-1) var(--bp-space-3);
+  padding: var(--bp-space-2) var(--bp-space-4);
+  border-top: 1px solid var(--bp-edge);
+  font-family: var(--bp-mono);
+  font-size: var(--bp-label-md);
+  letter-spacing: var(--bp-label-md-ls);
+  color: var(--bp-text-secondary);
+}
+.docs-search__keys {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--bp-space-1) var(--bp-space-3);
+}
+.docs-search__key {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--bp-space-1);
+}
+.docs-search__foot kbd {
+  padding: 0 4px;
+  border-width: 1px;
+  border-radius: var(--bp-radius-2, 2px);
+  font-size: var(--bp-label-md);
+  line-height: 1.5;
+  color: var(--bp-text-secondary);
+}
+
+/* Sidebar footer scrim token. The footer (theme switch + author/date) gets a
+   soft fade above it so the scrollable TOC dissolves into the rail rather than
+   colliding with the footer. The bottom band stays solid to back the footer.
+   Interpolating `in oklch` is premultiplied, so a plain `oklch(0 0 0 / 0)` stop
+   fades cleanly (the zero-alpha endpoint contributes no colour, no muddy
+   mid-tone) — and our rail bg is achromatic, so no same-colour stop is needed.
+   The plain gradient syntax stays as the fallback for engines without oklch
+   gradient interpolation. */
+:root {
+  /* Shared square control size for the corner toggle, doc-switcher trigger,
+     theme switch, and scrim geometry — one token keeps every calc in sync. */
+  --bp-sidebar-toggle-size: 30px;
+  /* Content column inset — toggle, TOC pills, switcher, and footer share one
+     left/right edge so the rail reads as an even column. */
+  --bp-sidebar-content-inset: calc(var(--bp-space-4) + var(--bp-space-3));
+  /* Frame line → chrome row: same gap below the top line and above the bottom. */
+  --bp-sidebar-chrome-gap: var(--bp-space-3);
+  --bp-sidebar-chrome-inset-top: calc(
+    var(--bp-shell-inset-top, var(--bp-space-4)) + var(--bp-sidebar-chrome-gap)
+  );
+  --bp-sidebar-chrome-inset-bottom: calc(
+    var(--bp-shell-inset-block, var(--bp-space-4)) + var(--bp-sidebar-chrome-gap)
+  );
+  --bp-sidebar-footer: calc(
+    var(--bp-sidebar-chrome-inset-bottom) + var(--bp-sidebar-toggle-size)
+  );
+  /* Scroll clearance: footer band + breathing room for the last TOC pill. */
+  --bp-sidebar-scroll-padding-bottom: calc(
+    var(--bp-sidebar-footer) + var(--bp-space-4)
+  );
+  --bp-sidebar-fade: linear-gradient(
+    to top,
+    var(--bp-bg) var(--bp-sidebar-footer),
+    oklch(0 0 0 / 0)
+  );
+
+  /* Header counterpart: a circular scrim centred on the corner toggle so the
+     TOC dissolves *around* the icon as it scrolls up under it — radiating from
+     the icon rather than a flat top edge. Centre = toggle inset + half its box.
+     Solid out to --bp-space-4, then fades over --bp-space-6. */
+  --bp-sidebar-header-scrim: calc(
+    var(--bp-sidebar-icon-center) + var(--bp-space-4) + var(--bp-space-6)
+  );
+  --bp-sidebar-icon-center: calc(
+    var(--bp-sidebar-chrome-inset-top) + var(--bp-sidebar-toggle-size) / 2
+  );
+  --bp-sidebar-icon-fade: radial-gradient(
+    circle at var(--bp-sidebar-icon-center) var(--bp-sidebar-icon-center),
+    var(--bp-bg) var(--bp-space-4),
+    oklch(0 0 0 / 0) calc(var(--bp-space-4) + var(--bp-space-6))
+  );
+}
+@supports (
+  background:
+    linear-gradient(in oklch, oklch(0.5 0.1 30), oklch(0.5 0.1 240))
+) {
+  :root {
+    --bp-sidebar-fade: linear-gradient(
+      in oklch to top,
+      var(--bp-bg) var(--bp-sidebar-footer),
+      oklch(0 0 0 / 0)
+    );
+    --bp-sidebar-icon-fade: radial-gradient(
+      in oklch circle at var(--bp-sidebar-icon-center)
+        var(--bp-sidebar-icon-center),
+      var(--bp-bg) var(--bp-space-4),
+      oklch(0 0 0 / 0) calc(var(--bp-space-4) + var(--bp-space-6))
+    );
+  }
+}
+
+/* Sidebar footer: the theme switch and the author/date block read as two flex
+   items with space between them, spanning the same band as the TOC entries
+   (left edge on the pill, right edge at the rail's content edge). */
+.sidebar-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--bp-space-3);
+}
+
+/* Author / date metadata — grouped as the footer's right-hand flex item. */
+.sidebar-meta {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--bp-space-4);
+}
+.sidebar-meta__item {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+.sidebar-meta__item .bp-meta {
+  margin: 0;
+  line-height: 1.25;
+}
+.sidebar-meta__item .bp-note {
+  margin: 0;
+  line-height: 1.35;
+}
+
+/* Leave room at the bottom of the rail so the last entry clears the footer. */
+.bp-sidebar {
+  --bp-theme-toggle-height: var(--bp-sidebar-toggle-size);
+  padding-bottom: var(--bp-sidebar-scroll-padding-bottom);
+}
+
+/* Bottom-left theme switch (Iconoir half-moon / light-bulb). Scoped to the
+   sidebar so the code demo's in-nav theme button is unaffected. */
+.bp-sidebar .theme-toggle {
+  /* A flex child of .sidebar-footer; relative so the thumb anchors to it. */
+  position: relative;
+  flex: 0 0 auto;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  align-items: center;
+  width: 54px;
+  height: var(--bp-theme-toggle-height);
+  padding: 2px;
+  border: 1px solid var(--bp-edge);
+  border-radius: var(--bp-radius-6, 6px);
+  background: var(--bp-fill-amb);
+  color: var(--bp-text-secondary);
+  cursor: pointer;
+  transition: none;
+}
+.bp-sidebar .theme-toggle:hover {
+  border-color: var(--bp-ink-line);
+  background: var(--bp-paper);
+  transition:
+    border-color var(--bp-duration-fast) var(--bp-ease-out),
+    background-color var(--bp-duration-fast) var(--bp-ease-out),
+    color var(--bp-duration-fast) var(--bp-ease-out);
+}
+.bp-sidebar .theme-toggle:focus-visible {
+  outline: 2px solid var(--bp-ink);
+  outline-offset: 2px;
+}
+.bp-sidebar .theme-toggle__thumb {
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  /* height − (2×border + 2×pad) keeps an even 2px gap on every side. */
+  width: calc(var(--bp-theme-toggle-height) - 6px);
+  height: calc(var(--bp-theme-toggle-height) - 6px);
+  border: 1px solid var(--bp-ink-line);
+  border-radius: var(--bp-radius-4, 4px);
+  background: var(--bp-paper);
+  box-shadow: 0 1px 2px oklch(0 0 0 / 0.06);
+  pointer-events: none;
+}
+[data-obvious-theme="dark"] .bp-sidebar .theme-toggle__thumb {
+  transform: translateX(24px);
+}
+.bp-sidebar .theme-toggle svg {
+  display: block;
+}
+.bp-sidebar .theme-toggle__icon {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+:not([data-obvious-theme="dark"]) .bp-sidebar .theme-toggle__icon--moon,
+[data-obvious-theme="dark"] .bp-sidebar .theme-toggle__icon--bulb {
+  color: var(--bp-ink);
+}
+
+/* =====================================================================
+   Sidebar collapse toggle (Iconoir sidebar glyph, pinned top-left)
+   ---------------------------------------------------------------------
+   Docs chrome that hides/shows the fixed contents rail, like the doc
+   switcher and theme toggle above. It lives on <body> (not inside the
+   rail) so it stays reachable once the rail is gone. The collapsed-state
+   rules are unlayered author CSS, so they win over blueprint.css per the
+   specificity contract. The whole rail slides as one rigid unit — its scrims
+   + footer ride along (no opacity tricks), and the sheet trails one space-4
+   behind the rail's edge the entire way (shared duration + easing).
+   ===================================================================== */
+.sidebar-toggle {
+  position: fixed;
+  /* Same offset from the top frame line as the footer keeps from the bottom. */
+  top: var(--bp-sidebar-chrome-inset-top);
+  left: var(--bp-sidebar-content-inset);
+  z-index: 320;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--bp-sidebar-toggle-size);
+  height: var(--bp-sidebar-toggle-size);
+  padding: 0;
+  border: 1px solid var(--bp-edge);
+  border-radius: var(--bp-radius-6, 6px);
+  background: var(--bp-fill-amb);
+  color: var(--bp-text-secondary);
+  cursor: pointer;
+  transition: none;
+}
+.sidebar-toggle:hover {
+  border-color: var(--bp-ink-line);
+  background: var(--bp-paper);
+  color: var(--bp-ink);
+  transition:
+    border-color var(--bp-duration-fast) var(--bp-ease-out),
+    background-color var(--bp-duration-fast) var(--bp-ease-out),
+    color var(--bp-duration-fast) var(--bp-ease-out);
+}
+.sidebar-toggle:focus-visible {
+  outline: 2px solid var(--bp-ink);
+  outline-offset: 2px;
+}
+.sidebar-toggle__icons {
+  position: relative;
+  display: block;
+  width: 16px;
+  height: 16px;
+}
+.sidebar-toggle__icon {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+.sidebar-toggle__icon--collapse {
+  opacity: 1;
+}
+.sidebar-toggle__icon--expand {
+  opacity: 0;
+}
+[data-sidebar="collapsed"] .sidebar-toggle__icon--collapse {
+  opacity: 0;
+}
+[data-sidebar="collapsed"] .sidebar-toggle__icon--expand {
+  opacity: 1;
+}
+.sidebar-toggle svg {
+  display: block;
+}
+
+@media (min-width: 861px) {
+  /* Top padding lives on the panel (space-6 aligns the search row with the
+     fixed corner toggle); zero the shell's own top padding so it isn't added
+     on top, which would push the search below the toggle. */
+  .bp-sidebar {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    padding-top: 0;
+    padding-bottom: 0;
+    padding-inline: 0;
+  }
+
+  /* The panel scrolls; padding-bottom reserves the fixed footer band so every
+     TOC entry can scroll fully into view above it. scroll-padding-bottom keeps
+     browser-managed scroll (keyboard focus, scrollIntoView, find-in-page) from
+     landing a near-bottom entry under the fixed footer overlay. Horizontal
+     padding aligns the TOC pills with the fixed corner toggle. */
+  .bp-sidebar__panel {
+    flex: 1 1 auto;
+    min-height: 0;
+    height: auto;
+    overflow-x: hidden;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    -webkit-overflow-scrolling: touch;
+    padding-top: var(--bp-space-6);
+    padding-inline: var(--bp-sidebar-content-inset);
+    padding-bottom: var(--bp-sidebar-scroll-padding-bottom);
+    scroll-padding-bottom: var(--bp-sidebar-scroll-padding-bottom);
+  }
+
+  /* Drop the switcher below the header scrim (search stays above it on z 300). */
+  .doc-switcher {
+    margin-top: max(
+      0px,
+      calc(
+        var(--bp-sidebar-header-scrim) - var(--bp-space-6) + var(--bp-space-2) -
+          var(--bp-sidebar-toggle-size) - var(--bp-space-3) + var(--bp-space-2)
+      )
+    );
+  }
+
+  /* The rail slides as one unit. At rest transform is none, so the fixed scrims
+     (::before/::after) + footer stay viewport-anchored for the scroll dissolve;
+     during the slide a non-none transform makes the rail their containing block,
+     so they ride along with it (their %-based geometry resolves against the
+     rail's own width, which is identical math — see the footer rule below).
+     Transition only after bp-sidebar-animate is set (index.html) to skip first
+     paint; visibility flips at the end so the rail leaves the tab order. */
+  html.bp-sidebar-animate .bp-sidebar {
+    transition:
+      transform var(--bp-duration-slow) var(--bp-ease-in-out),
+      visibility var(--bp-duration-slow);
+  }
+  [data-sidebar="collapsed"] .bp-sidebar {
+    transform: translateX(-100%);
+    visibility: hidden;
+    pointer-events: none;
+  }
+
+  /* The sheet reclaims the rail's width in step with the slide. <main> is laid
+     out with margin-inline (blueprint.css shell rules), not `left`, so the
+     reclaim must transition margin — transitioning `left` on a static box was a
+     no-op, which made the sheet snap while the rail slid. Same duration/easing
+     as the rail + frame line so all three move as one. Gated on
+     bp-sidebar-animate so it never fires on first paint. */
+  html.bp-sidebar-animate[data-bp-document] main {
+    transition: margin var(--bp-duration-slow) var(--bp-ease-in-out);
+  }
+  html.bp-sidebar-animate[data-bp-document]::after {
+    transition: background-position var(--bp-duration-slow) var(--bp-ease-in-out);
+  }
+
+  /* Footer pins to the bottom of the rail, spanning the TOC band: left edge on
+     the entry pill (content edge) and right edge at the rail's content edge. */
+  .sidebar-footer {
+    position: fixed;
+    left: var(--bp-sidebar-content-inset);
+    right: calc(100% - var(--bp-sidebar) + var(--bp-sidebar-content-inset));
+    bottom: var(--bp-sidebar-chrome-inset-bottom);
+    z-index: 300;
+  }
+
+  /* Fade scrim above the footer: the TOC scrolls out beneath it (z below the
+     footer controls), with a solid bottom band backing the footer. */
+  .bp-sidebar::after {
+    content: "";
+    position: fixed;
+    left: 0;
+    bottom: 0;
+    width: var(--bp-sidebar);
+    height: calc(var(--bp-sidebar-footer) + var(--bp-space-4));
+    background: var(--bp-sidebar-fade);
+    pointer-events: none;
+    z-index: 200;
+  }
+
+  /* Radial scrim around the corner toggle: the TOC dissolves in a circle that
+     radiates from the icon as entries scroll up beneath it. The box is large
+     enough to hold the gradient's outer radius; transparent beyond it. */
+  .bp-sidebar::before {
+    content: "";
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: var(--bp-sidebar);
+    height: var(--bp-sidebar-header-scrim);
+    background: var(--bp-sidebar-icon-fade);
+    pointer-events: none;
+    z-index: 200;
+  }
+
+  /* Collapsed: the rail (slid out via the rule above) vacates its width and the
+     sheet reclaims it, trailing one space-4 behind the rail's edge throughout. */
+  [data-sidebar="collapsed"][data-bp-document] {
+    --bp-shell-inset-left: var(--bp-space-4);
+  }
+}
+
+/* Below the rail's fixed breakpoint it becomes a static horizontal nav,
+   where collapsing has no meaning — hide the control entirely. */
+@media (max-width: 860px) {
+  .sidebar-toggle {
+    display: none;
+  }
+}
+
+@media print {
+  body {
+    padding-top: 0;
+  }
+
+  .site-nav,
+  .bp-sidebar .theme-toggle,
+  .sidebar-toggle {
+    display: none;
+  }
+}

package/dist/blueprint.js

@@ -25,6 +25,9 @@ const THEME_BULB_ICON = [
   '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}"]`
@@ -103,6 +106,18 @@ function createChromeSvg(doc, pathD, size = 16) {
   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')
@@ -131,9 +146,7 @@ function injectSiteNav(doc, win) {
   brand.href = brandHref
   brand.setAttribute('aria-label', `${brandLabel} home`)
 
-  const logo = doc.createElement('span')
-  logo.className = 'site-nav__logo'
-  logo.setAttribute('aria-hidden', 'true')
+  const logo = createBlueprintLogo(doc)
 
   const wordmark = doc.createElement('span')
   wordmark.className = 'site-nav__wordmark'
@@ -905,15 +918,16 @@ function wireSearchPalette(doc, win) {
   })
 }
 
-function injectDocumentChrome(doc, win = doc.defaultView) {
+function injectDocumentChrome(doc, win = doc.defaultView, navigationTree = []) {
   if (doc.body?.dataset.bpChromeReady === 'true') return
   const main = doc.querySelector('main')
   if (!main) return
 
-  const sidebar = injectSidebar(doc, win)
+  const hasNavigation = navigationTree.length > 0
+  const sidebar = hasNavigation ? injectSidebar(doc, win) : null
   const chrome = [
     injectSiteNav(doc, win),
-    injectScrollProgress(doc),
+    hasNavigation ? injectScrollProgress(doc) : null,
     sidebar ? injectSidebarToggle(doc) : null,
     sidebar,
   ].filter(Boolean)
@@ -944,8 +958,9 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
   // 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)
-  injectDocumentChrome(doc, win)
-  generateNavigationFromHeadings(doc)
+  const navigationTree = ensureDocumentNavTree(doc)
+  injectDocumentChrome(doc, win, navigationTree)
+  generateNavigationFromHeadings(doc, navigationTree)
   wireSectionHeadingLinks(doc, win)
   wireSearchPalette(doc, win)
   wireFigureDiagramSize(doc)
@@ -1507,8 +1522,7 @@ function populateAllBpToc(doc, tree) {
   }
 }
 
-function generateNavigationFromHeadings(doc) {
-  const tree = ensureDocumentNavTree(doc)
+function generateNavigationFromHeadings(doc, tree = ensureDocumentNavTree(doc)) {
   if (tree.length === 0) return
 
   const navFragment = renderNavTree(doc, tree)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obvi/blueprint",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A classless-first CSS design system for beautiful technical blueprint documents.",
   "license": "MIT",
   "type": "module",
@@ -39,10 +39,12 @@
     "build": "npm run build:code && node scripts/build-package.mjs",
     "build:code": "node code-highlighting/scripts/build.mjs",
     "render": "node harness/render.mjs",
-    "measure": "node harness/measure.mjs && node harness/behavior.mjs",
+    "measure": "node harness/measure.mjs && node harness/behavior.mjs && node harness/navigation-clipping.mjs",
     "verify:package": "node scripts/verify-package.mjs",
+    "verify:release-evidence": "node --test harness/release-evidence.test.mjs",
     "lint:style": "node scripts/lint-style.mjs",
-    "verify": "npm run build && npm run lint:style && npm run measure && npm run verify:package",
+    "release:evidence": "node harness/release-evidence.mjs",
+    "verify": "npm run build && npm run lint:style && npm run verify:release-evidence && npm run measure && npm run verify:package",
     "prepack": "npm run build"
   },
   "devDependencies": {