@obvi/blueprint 1.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flatfile Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,443 @@
+# blueprint.css
+
+A classless-first CSS design system for beautiful technical blueprint documents.
+
+Drop a single stylesheet onto a plain semantic HTML document and it renders as a polished blueprint — monochrome ink on paper, set in Booton, with the Obvious drafting-blue identity reserved for illustrations alone. No classes required. On top of that semantic base sits a small, zero-specificity component layer for the compositions blueprint authors keep hand-rolling.
+
+## What ships
+
+- **`blueprint.css`** — the portable visual library. One file, no build step.
+- **`blueprint.js`** — optional TOC-current-state and reading-progress behavior.
+- **`SKILL.md`** — the canonical Blueprint authoring workflow and design contract.
+- **`code-highlighting/`** — optional Prism theme, source component behavior, and vendored runtime.
+- **`index.html`** — a self-demonstrating reference page built *with* the library. Every component is shown live beside its source markup.
+- **`harness/`** — Puppeteer-based render + measure gate that validates the build across desktop/tablet/mobile and light/dark themes.
+
+## Philosophy
+
+### Semantic HTML is the API
+
+The default authoring mode is plain HTML: headings, paragraphs, lists, tables, figures, quotes, definition lists, landmarks, and disclosure elements. The library styles those base elements intentionally so authors write *meaning* and the design arrives for free.
+
+### Classless-first, not class-only
+
+Classes are reserved for patterns native HTML cannot express on its own — things like a primary decision panel, a typed callout family, or a true option-comparison grid. Every promoted component is a composition of real semantic elements, not a replacement for them.
+
+### The specificity contract
+
+This library is engineered to eliminate the silent cascade trap that plagued the prior base sheet.
+
+- The stylesheet is ordered with **cascade layers**:
+  `@layer reset, tokens, base, components, utilities`
+- Every selector inside those layers is wrapped in **`:where()`**, so its specificity is zero.
+
+That means:
+
+1. **Components always beat base elements** because `components` comes after `base`, regardless of selector specificity.
+2. **Your own CSS always beats the library** because unlayered author CSS sits above all layered rules.
+3. A bare authored class inside the typographic base wins with **no parent-scoping** and no `!important`.
+
+The harness proves this with a cascade fixture.
+
+## Library structure
+
+### 1. Tokens & scales
+
+The `tokens` layer defines:
+
+- a neutral ink scale (the Obvious opacity-based black/white) for all text and chrome
+- a dedicated illustration accent (`--bp-illustration-*`) — the only blue, used by SVG marks
+- neutral document surfaces
+- light/dark theme tokens via `data-obvious-theme`
+- a named type scale
+- a 3-step monospace label scale
+- an 8px spacing rhythm
+- a 1px SVG stroke token
+
+### 2. Classless semantic base
+
+The `base` layer styles raw HTML at zero specificity, including:
+
+- document landmarks (`main`, `article`, `section`, `header`, `footer`, `nav`, `aside`, `hgroup`)
+- headings with automatic section numbering
+- paragraphs, lists, emphasis, links, code/pre, definitions, and abbreviations
+- citation + provenance (`blockquote[cite]`, `cite`, `q`, `figure`, `figcaption`, footnotes, `time`)
+- semantic tables with row-header vs column-header distinction
+- disclosure (`details` / `summary`)
+
+Body text defaults to **left-aligned** — not justified.
+
+### 3. Component layer
+
+Reusable primitives promoted from repeated blueprint authoring patterns:
+
+- `.bp-lede` — narrative lede escape hatch
+- `.bp-decision` — primary decision panel: an inverted `.bp-decision__bar` (kicker `.bp-label` + optional `.bp-decision__status` pill + optional `.bp-decision__meta` provenance with `<time>`), the hero `.bp-decision-stmt`, stacked `.bp-decision__tenets` (a `<dl>`), and a hatched `.bp-decision__revisit` change-condition footer. Add `.bp-decision--collapsible` on a `<details>` whose `<summary>` is the `.bp-decision__bar` (kicker + a compact `.bp-decision__title` left, `.bp-decision__meta` + `.bp-decision__caret` right) for a native, script-free collapsed form: collapsed it is just the bar, and the tenets + revisit footer reveal on expand
+- `<bp-callout type="locked|invariant|ref">` — typed callout element (expands to the `.bp-callout` family below). Drafting-style: four L-shaped corner registration ticks (drawn as background gradients, no extra DOM) bracket the body instead of a box, headed by a `.bp-ctag` label (icon + compact mono caption). `--locked` uses solid ink ticks, `--invariant` adds the hatch fill with heavier ticks, `--ref` uses soft ticks. `label="…"` overrides the caption and `icon="none"` drops the glyph; the raw `.bp-callout--locked` / `--invariant` / `--ref` markup stays valid for hand-built or stored documents
+- `.bp-deflist` — widened definition-list variant
+- `.bp-option-grid`, `.bp-opt--rec`, `.bp-verdict` — parallel option comparisons
+- `.bp-sequence` — numbered linear pipeline
+- `.bp-state-grid` — state model grid
+- `.bp-table-wrap` — wide-table scroll container
+- `<bp-callout>` — typed callout Web Component; `type` picks the role (locked / invariant / ref) and it expands to the ticked frame, icon, and label
+- `<bp-source>` — collapsible, syntax-highlighted source Web Component with copy control
+- `<bp-cite>` — inline code-citation tooltip; hovering/focusing the cited text reveals the source in a top-layer popover
+- `.bp-node`, `.bp-edge`, `.bp-svg-label`, `.bp-svg-meta` — SVG figure marks (the drafting-blue illustration layer)
+- `.bp-stack-iso`, `.bp-stack-top`, `.bp-stack-face`, `.bp-stack-grid`, `.bp-svg-dot` — isometric solids for box/machine/conveyor illustrations with callout leaders
+- `.bp-sidebar`, `.bp-toc` — the fixed contents rail: auto-numbered entries, a hairline guide track, and a gliding active marker driven by `blueprint.js`
+- `.bp-contents` — a full-width, inline contents section: a calm numbered, multi-column index with dotted leaders and no active/selected state (a top-of-document index has no "current" entry; the fixed rail handles position tracking)
+- `.scroll-progress`, `.bp-title-block` — document chrome
+
+### Compatibility and TOC state contract
+
+Version 1.0.4 retains a transitional compatibility layer for markup emitted by current Blueprint authoring tools and stored documents. Legacy token names and `.bp-content`, `.bp-layout`, `.bp-card-grid`, `.bp-card`, `.bp-chip`, `.bp-document`, `.bp-title`, `.bp-placeholder`, `.bp-section`, `.bp-section-number`, `.bp-figure`, `.bp-figure-caption`, `.bp-table`, and `.bp-toc` remain supported while semantic HTML is preferred for new documents.
+
+A document with section navigation uses `blueprint.js` to set **exactly one** TOC link to `aria-current="location"`. The stylesheet also recognizes `.active` and `.is-active`, but `aria-current` is canonical and provides the accessibility contract.
+
+At 860px and below, `.bp-sidebar` and `.bp-toc` become horizontally scrollable section navigation instead of disappearing. Print hides only Blueprint TOC/sidebar chrome, not unrelated authored `nav` elements.
+
+## Install from npm
+
+The package is published privately under the standard `@obvi` npm scope. Supply
+an npm token with access to the organization without committing it:
+
+```ini
+@obvi:registry=https://registry.npmjs.org
+//registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}
+```
+
+Pin the exact package version so the stylesheet is immutable across installs:
+
+```bash
+npm install --save-exact @obvi/blueprint@1.0.9
+```
+
+Import the canonical stylesheet from the supported package export:
+
+```js
+import "@obvi/blueprint/blueprint.css";
+```
+
+For static HTML that does not use a bundler, copy the exported stylesheet from
+`node_modules/@obvi/blueprint/dist/blueprint.css` into your deployed
+assets and link that copy.
+
+The npm tarball intentionally excludes the authoring `SKILL.md`, docs site,
+examples, harness, and source scripts. Consumers receive only the built runtime
+assets under `dist/` plus package metadata and license notices.
+
+## Include the stylesheet
+
+```html
+<link rel="stylesheet" href="blueprint.css" />
+```
+
+Set theme on the root element:
+
+```html
+<html data-obvious-theme="light">
+<html data-obvious-theme="dark">
+```
+
+## Fonts & offline use
+
+The stylesheet loads the Booton variable font from the Obvious CDN (`https://obvious.ai/fonts/`). This works out of the box for online consumers.
+
+**Self-hosting:** If you need the font available offline or want to avoid an external network dependency, download `BootonVF.woff2` and `BootonItalicsVF.woff2` from that URL, host them alongside your stylesheet, and replace the `src` URLs in the two `@font-face` blocks at the top of `blueprint.css`:
+
+```css
+/* Before (CDN) */
+src: url("https://obvious.ai/fonts/BootonVF.woff2") format("woff2");
+
+/* After (self-hosted) */
+src: url("./fonts/BootonVF.woff2") format("woff2");
+```
+
+**Fallback:** If Booton fails to load for any reason, `--bp-sans` falls back through `system-ui → -apple-system → sans-serif`. All text remains legible; only the Booton identity is lost.
+
+## Example: no classes required
+
+```html
+<section>
+  <h2>Recovery saga</h2>
+  <p>A crashed worker must never leave a session both orphaned and still-claimed.</p>
+  <p>Each step below is idempotent, so replaying from any checkpoint converges to a single owner.</p>
+</section>
+```
+
+The section number, heading hierarchy, and first-paragraph lede all render from structure alone.
+
+## Example: authored class beats the base naturally
+
+```html
+<style>
+  .author-lede {
+    font-size: 28px;
+    line-height: 36px;
+  }
+</style>
+
+<p class="author-lede">A bare authored class wins with no parent-scoping.</p>
+```
+
+The harness verifies that this computes to `28px / 36px`, while a sibling paragraph remains at the base `14px / 20px`.
+
+## Docs page
+
+Open `index.html` in a browser. It includes:
+
+- the semantic-first story
+- the specificity contract
+- token and scale samples
+- citation/provenance examples
+- semantic table behavior
+- the full inline technical family
+- every promoted component rendered live beside its source
+- a theme toggle and scroll-progress bar
+
+## Harness
+
+One-time setup:
+
+```bash
+npm install
+npx puppeteer browsers install chrome
+```
+
+Run the gate:
+
+```bash
+npm run measure
+```
+
+This checks:
+
+- computed hierarchy (font-size / line-height)
+- the no-parent-scoping cascade contract
+- no page-level horizontal overflow at `1440 / 700 / 390`
+- TOC DOM state and computed visual distinction across `1440 / 861 / 860 / 390`
+- initial hash, click, reload, history, down/up scroll, and document-bottom transitions
+- hover, keyboard focus, reduced motion, mobile navigation, and print scoping
+- light and dark themes
+- the same behavioral fixture against source and packed package CSS
+
+For screenshots:
+
+```bash
+npm run render
+```
+
+Both commands write to `harness/output/`.
+
+## Project layout
+
+```text
+.
+├── blueprint.css
+├── blueprint.js
+├── dist/
+│   ├── blueprint.css
+│   ├── blueprint.js
+│   └── code-highlighting/
+│       ├── blueprint-code.css
+│       └── blueprint-code.js
+├── index.html
+├── package.json
+└── harness/
+    ├── README.md
+    ├── lib.mjs
+    ├── measure.mjs
+    ├── render.mjs
+    └── fixtures/
+        └── cascade.html
+```
+
+## Code highlighting: embed decision + monochrome theme
+
+### Decision
+
+**Use Prism (a class-based runtime syntax highlighter) plus a CSS theme file. Do not use Shiki.**
+
+This project’s core promise is **one portable CSS file, no build step**. A class-based runtime highlighter emits stable token classes into the DOM (`.token.keyword`, `.token.string`, etc.), and the monochrome syntax theme is therefore **just CSS**. It drops into a blueprint exactly the way `blueprint.css` does and keys off the same `data-obvious-theme` attribute for light/dark.
+
+Shiki was considered and rejected for this use case. It is the most accurate option because it uses TextMate grammars, but it also **bakes colors inline at build time** and typically requires a rendering/build step. That fights both parts of this deliverable:
+
+1. the theme should be a **portable CSS file**, not generated HTML with inline styles, and
+2. blueprint documents should remain **drop-in and static** rather than requiring a compilation pipeline.
+
+Shiki is a good choice when grammar accuracy outweighs portability. It is the wrong fit when the deliverable itself is a reusable CSS theme.
+
+### Why Prism instead of highlight.js?
+
+Both Prism and highlight.js satisfy the core architectural decision because both are runtime highlighters that can be themed with CSS. Prism is the better fit here for one concrete reason: **its token taxonomy is finer-grained**.
+
+A monochrome theme cannot rely on hue changes to separate syntax classes. It needs the highlighter to expose meaningful semantic buckets so the theme can differentiate by **luminance, weight, and italic** instead. Prism gives us stable classes like:
+
+- `.token.keyword`
+- `.token.string`
+- `.token.comment`
+- `.token.function`
+- `.token.number`
+- `.token.operator`
+- `.token.punctuation`
+- `.token.class-name`
+- `.token.attr-name`
+
+That richer taxonomy made it possible to create a readable hierarchy in a single neutral ink — code is text, so it stays monochrome and leaves blue to the illustrations. Prism also has a simple drop-in story for static HTML and an optional line-numbers plugin that layers on cleanly.
+
+### Markup contract for blueprint documents
+
+Canonical block pattern:
+
+```html
+<pre class="language-typescript"><code class="language-typescript">
+export const answer = 42;
+</code></pre>
+```
+
+Rules:
+
+1. **Put the language on both elements** (`pre` and `code`) using Prism’s `language-xxx` convention.
+2. **Escape HTML-sensitive characters** inside code samples when authoring static HTML (`<`, `>`, `&`).
+3. For a filename or caption, wrap the block in a figure:
+
+```html
+<figure class="bpc-code">
+  <figcaption>session-scheduler.ts</figcaption>
+  <pre class="language-typescript line-numbers"><code class="language-typescript">
+  // code…
+  </code></pre>
+</figure>
+```
+
+4. Use plain inline `<code>` for short fragments in prose. Use `<pre><code>` for multi-line listings.
+5. Highlighting is **additive**. If JavaScript never runs, the document still renders readable monospace code via the base `pre` / `code` styles. The theme only adds color, weight, and optional line-number chrome on top.
+
+### Runtime initialization contract
+
+Static HTML loads one self-contained browser module:
+
+```html
+<link rel="stylesheet" href="./blueprint-code.css" />
+<script type="module" src="./blueprint-code.js"></script>
+```
+
+Application builds import the same registration entry once:
+
+```js
+import "blueprint-css/web-components";
+```
+
+The browser module bundles Prism core, the bounded language set, custom-element registration, and Clipboard API behavior. Consumers never load or order Prism scripts. It highlights conventional `<pre><code>` blocks and every `<bp-source>` instance.
+
+### Web Component integration
+
+Use [`<bp-source>`](#bp-source) when a blueprint should show its own source without hand-authoring the repeated disclosure, toolbar, label, Prism classes, and copy control. Load the module once in the page shell or app entry; component markup needs no colocated script. The copy action uses clean source text, so Prism token spans never leak into the clipboard.
+
+### Files in this side-mission deliverable
+
+- `code-highlighting/blueprint-code.css` — the portable monochrome Prism theme
+- `code-highlighting/blueprint-code.js` — self-contained browser bundle: Prism + native `<bp-source>` + Clipboard API
+- `code-highlighting/src/blueprint-code.js` — component source
+- `code-highlighting/scripts/build.mjs` — deterministic esbuild bundle
+- `code-highlighting/demo.html` — standalone multi-language demo page
+- `code-highlighting/vendor/prism/` — repo-only standalone-theme fixtures (MIT)
+- `code-highlighting/scripts/measure.mjs` — headless render + measurement harness
+
+### Token → treatment mapping
+
+| Token role | Treatment principle |
+| --- | --- |
+| comment | faint gray, italic, de-emphasized |
+| punctuation | muted gray; structure recedes |
+| operator | muted but stronger than punctuation |
+| variable / plain code | baseline code ink |
+| string | mid gray, calm |
+| number / constant | darker gray stop; literals pop |
+| function | darker ink with medium weight |
+| class-name / builtin | darker ink with medium weight |
+| keyword | darkest ink, heaviest weight |
+| markup tag | keyword-adjacent weight; structural |
+| attr-name | mid-strong ink |
+| diff inserted / deleted | differentiated by luminance/tint + the +/- glyph, not hue |
+
+### Verification
+
+The demo is verified by measurement, not eyeballing.
+
+One-time setup:
+
+```bash
+cd code-highlighting
+npm install --no-save puppeteer@23
+npx puppeteer browsers install chrome
+```
+
+Run the harness:
+
+```bash
+node scripts/measure.mjs
+```
+
+What it checks:
+
+- Prism actually ran (`.token` spans exist)
+- token colors resolved to the theme rather than falling back to plain text color
+- at least five distinct token colors exist (the hierarchy is not flattened)
+- no page-level horizontal overflow
+- WCAG contrast is adequate in **both** light and dark themes
+- screenshots are written to `code-highlighting/.measure/demo-light.png` and `demo-dark.png`
+
+### How to include the theme in a blueprint
+
+1. Load the base blueprint stylesheet.
+2. Load `blueprint-code.css` after it.
+3. Load or import `blueprint-code.js` once in the page shell or app entry.
+4. Use `<bp-source>` or write conventional blocks with the `language-xxx` markup contract above.
+
+That keeps the consumer contract portable: **one CSS theme, one bounded browser module, and no Prism configuration.**
+See the feature branch / open PR for the full library, docs page, and harness.
+
+## Web Components
+
+Blueprint stays semantic-HTML-first. A native custom element is added only when a repeated pattern needs behavior that HTML and CSS cannot provide alone. Components render their semantic structure into light DOM so the existing Blueprint cascade and David's syntax theme remain the single visual source of truth.
+
+### `<bp-callout>`
+
+`<bp-callout>` collapses the typed-callout markup (the type icon, `.bp-ctag` label, and the corner-ticked `<aside>`) into one element. The body can be bare text or block content; bare text is wrapped in a `<p>`:
+
+```html
+<bp-callout type="invariant">
+  The fence token is monotonic and never reused.
+</bp-callout>
+```
+
+| Input | Contract |
+| --- | --- |
+| `type` | `locked` (commitment), `invariant` (must-hold rule), or `ref` / `reference` (enumerated values). Defaults to `locked`. |
+| `label` | Optional caption override; defaults to the type's name. |
+| `icon` | `none` drops the leading glyph. |
+
+This is light DOM and registers from `blueprint.js`; the raw `.bp-callout` class markup remains valid for documents authored or stored without the element.
+
+### `<bp-source>`
+
+`<bp-source>` turns escaped source text into a native `<details>` disclosure with an explicit language label, a Prism-highlighted `<pre><code>` block, and a copy control:
+
+```html
+<bp-source language="typescript" open>
+  interface Session {
+    id: string;
+    epoch: number;
+  }
+</bp-source>
+```
+
+| Input | Contract |
+| --- | --- |
+| `language` | Explicit bounded Prism grammar or supported alias; unavailable and unknown grammars fall back to readable plain text. |
+| `summary` | Optional disclosure label; defaults to `Source`. |
+| `open` | Uses the native boolean disclosure state. |
+| `sourceText` | Read-only clean source used by the built-in copy action. |
+
+No author-written clipboard JavaScript or separate copy library is needed. Browsers do not expose declarative copy-to-clipboard HTML, so the Web Component owns the small native Clipboard API call internally.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-party notices
+
+## PrismJS 1.30.0
+
+The distributed `code-highlighting/blueprint-code.js` includes PrismJS.
+
+MIT LICENSE
+
+Copyright (c) 2012 Lea Verou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.