bitwrench 2.0.31 → 2.1.0

package/docs/cli.md

@@ -189,32 +189,56 @@ bwcli serve -v
 Your app sends bwserve protocol messages (JSON) to the input port. All connected browsers update in real time.
 
 ```bash
-# Patch a value:
+# Patch a value (v2.1 wire protocol — ref, discriminated fields, v:1 stamp):
 curl -X POST http://localhost:9000 \
   -H "Content-Type: application/json" \
-  -d '{"type":"patch","target":"temp","content":"23.5 C"}'
+  -d '{"v":1,"type":"patch","ref":"temp","text":"23.5 C"}'
 
 # Batch update:
 curl -X POST http://localhost:9000 \
-  -d '{"type":"batch","ops":[
-    {"type":"patch","target":"temp","content":"23.5"},
-    {"type":"patch","target":"humidity","content":"67%"}
+  -d '{"v":1,"type":"batch","ops":[
+    {"v":1,"type":"patch","ref":"temp","text":"23.5"},
+    {"v":1,"type":"patch","ref":"humidity","text":"67%"}
   ]}'
 
 # r-prefix relaxed JSON is also accepted (for C/embedded):
-curl -X POST http://localhost:9000 -d "r{'type':'patch','target':'temp','content':'23.5'}"
+curl -X POST http://localhost:9000 -d "r{'v':1,'type':'patch','ref':'temp','text':'23.5'}"
 ```
 
+### Interactive Commands
+
+Messages with a `"command"` field are interactive -- they return a JSON response (not broadcast). Use these to inspect or query connected clients:
+
+```bash
+# List connected clients
+curl -X POST http://localhost:9000 -d '{"command":"clients"}'
+
+# Eval a JS expression in the browser
+curl -X POST http://localhost:9000 -d '{"command":"query","code":"document.title"}'
+
+# DOM tree snapshot
+curl -X POST http://localhost:9000 -d '{"command":"tree","selector":"#app","depth":2}'
+
+# Take a screenshot (requires --allow-screenshot)
+curl -X POST http://localhost:9000 -d '{"command":"screenshot"}'
+```
+
+When no `clientId` is specified, the command routes to the most recently connected client.
+
 ### Options
 
 ```
-bwcli serve [options]
+bwcli serve [dir] [options]
 
 Options:
   -p, --port <number>         Web port for browsers (default: 8080)
-      --input-port <number>   Input port for protocol messages (default: 9000)
+  -l, --listen <number>       Input port for protocol messages (default: 9000)
+  -b, --bind <address>        Host/address to bind to (default: 0.0.0.0)
       --stdin                 Read messages from stdin instead of input port
   -t, --theme <name>          Theme preset or hex colors
+      --title <string>        Page title (default: "bwcli serve")
+      --no-dir-list           Disable directory listings
+      --allow-screenshot      Enable client.screenshot() capability
       --open                  Open browser on start
   -v, --verbose               Verbose output (shows all messages)
   -h, --help                  Print help
@@ -232,7 +256,7 @@ Both strict JSON and r-prefix relaxed JSON are accepted on the input port. See [
 
 ## The `bwcli attach` subcommand — Remote Debugging REPL
 
-`bwcli attach` provides a built-in terminal-based debugger for any bitwrench page. It starts a bwserve instance and waits for a browser to connect via a drop-in `<script>` tag. Once connected, you get an interactive REPL for evaluating JS, inspecting the DOM, taking screenshots, and listening to events.
+`bwcli attach` provides a built-in terminal-based debugger for any bitwrench page. It starts a bwserve instance and waits for a browser to connect via a drop-in `<script>` tag. Once connected, you get an interactive REPL for inspecting the DOM, mounting components, taking screenshots, and listening to events.
 
 ### Usage
 
@@ -265,15 +289,13 @@ The drop-in script automatically loads bitwrench if it's not already on the page
 Once connected, you get a `bw>` prompt:
 
 ```
-bw> document.title                    # Evaluate JS expression
 bw> /tree #app 2                      # Show DOM tree
 bw> /screenshot body page.png         # Capture screenshot (requires --allow-screenshot)
 bw> /mount #app card {"title":"Hi"}   # Mount BCCL component
-bw> /render #app {"t":"h1","c":"Hi"}  # Render TACO
+bw> /render #app {"t":"h1","c":"Hi"}  # Render TACO at selector
 bw> /patch counter 42                 # Update element text
 bw> /listen button click              # Watch DOM events
 bw> /unlisten button click            # Stop watching
-bw> /exec alert('hello')             # Execute JS (fire-and-forget)
 bw> /clients                          # List connected clients
 bw> /help                             # Command reference
 bw> /quit                             # Exit
@@ -291,6 +313,8 @@ Options:
   -h, --help                 Print help
 ```
 
+Bare JS evaluation and the `/exec` command were removed in v2.1. Non-slash input is no longer evaluated. Use the slash commands above for all interactions.
+
 For the complete guide, see [bwcli attach documentation](bw-attach.md).
 
 ## Page layout

package/docs/component-cheatsheet.md

@@ -1,7 +1,7 @@
 # Component Cheat Sheet
 
 > **Before you write custom TACO for a common UI pattern, check this list.**
-> Bitwrench ships ready-made `make*()` factories. Each returns a Level 0 TACO object.
+> Bitwrench ships ready-made `make*()` factories. Each returns a plain TACO object.
 
 ## Full Component Table
 
@@ -92,7 +92,7 @@ bw.message('#my-carousel', 'goToSlide', 2);
 bw.message('.bw_uuid_abc123', 'next');
 ```
 
-See [State Management -- Level 1.5](state-management.md#level-15-component-handles) for the full handle/slots guide.
+See [State Management -- Component Handles](state-management.md#component-handles) for the full handle/slots guide.
 
 ## How to Use Slots
 

package/docs/component-library.md

@@ -334,7 +334,7 @@ bw.makeButton({
   text: 'Click Me',
   variant: 'primary',       // 'primary' | 'secondary' | 'success' | 'danger' |
                              // 'warning' | 'info' | 'light' | 'dark' |
-                             // 'outline-primary' | 'outline-secondary' | ...
+                             // 'outline_primary' | 'outline_secondary' | ...
   size: '',                  // 'sm' or 'lg'
   disabled: false,
   onclick: function() {},
@@ -1049,7 +1049,7 @@ Build your own with `o.handle` and `o.slots`:
 }
 ```
 
-See [State Management -- Level 1.5](state-management.md#level-15-component-handles) for the full guide.
+See [State Management -- Component Handles](state-management.md#component-handles) for the full guide.
 
 ---
 
@@ -1068,7 +1068,7 @@ Most components accept a `variant` prop. The available variants are:
 | `light` | Light background |
 | `dark` | Dark background |
 
-Buttons also support outline variants: `outline-primary`, `outline-secondary`, etc.
+Buttons also support outline variants: `outline_primary`, `outline_secondary`, etc.
 
 ## Composition
 
@@ -1078,7 +1078,7 @@ Because every factory returns a TACO object, you compose components with standar
 // Functions as component factories
 function userRow(user) {
   return {
-    t: 'div', a: { class: 'bw-card' }, c: [
+    t: 'div', a: { class: 'bw_bccl_card' }, c: [
       bw.makeAvatar({ initials: user.name[0], size: 'sm' }),
       { t: 'span', c: user.name },
       bw.makeBadge({ text: user.role, variant: 'info' })

package/docs/component-lifecycle.md

@@ -0,0 +1,234 @@
+# Component Lifecycle Walkthrough
+
+A stats card, taken through every phase of a component's life — define, create,
+mount, update, unmount — using the v2.1 API. If you read one document after the
+README, read this one: it is the shortest complete tour of how bitwrench
+components actually work.
+
+---
+
+## Phase 1: Define
+
+A stats card that displays a label and a formatted number.
+
+```javascript
+function makeStatsCard(config) {
+  return {
+    t: 'div', a: { class: 'stats-card' },
+    c: [
+      { t: 'h3', a: { class: 'card-title' }, c: config.title || '' },
+      { t: 'span', a: { class: 'card-value' }, c: formatValue(config.value) }
+    ],
+    o: {
+      type: 'stats-card',
+      state: { value: config.value || 0 },
+      slots: { title: '.card-title', value: '.card-value' },
+      handle: {
+        update: function(el, data) {
+          if (data.value !== undefined) {
+            el._bw_state.value = data.value;
+            el.bw.setValue(formatValue(data.value));
+          }
+          if (data.title !== undefined) {
+            el.bw.setTitle(data.title);
+          }
+        }
+      }
+    }
+  };
+}
+
+function formatValue(v) {
+  return '$' + Number(v).toLocaleString();
+}
+```
+
+What we have: a factory function that returns a TACO. Plain data (minus the
+handle function). The factory captures `config` but does NOT create DOM, wire
+lifecycle, or touch the document. This is just an object.
+
+**What goes where:**
+
+- `t, a, c` — structure (tag, attributes, content)
+- `o.type` — typed discovery: elements get a `bw_is_component_stats-card` class,
+  findable via `querySelectorAll`
+- `o.state` — local mutable state (value), initialized from config
+- `o.slots` — cached DOM targets. Auto-generates `el.bw.setTitle()`,
+  `el.bw.getTitle()`, `el.bw.setValue()`, `el.bw.getValue()`
+- `o.handle.update` — the public "give me new data" method. Does formatting
+  logic, then delegates to slot setters for the DOM update
+
+**Slot vs handle interaction:** slots generate simple setters that replace DOM
+content. The `update` handle method adds logic (formatting) then calls slot
+setters. Both live on `el.bw`. They don't collide because they have different
+names: `setValue` (slot) vs `update` (handle).
+
+The handle named `update` is special: `bw.update(ref, data)` dispatches to
+`el.bw.update(data)` automatically. Define an `update` handle and your
+component works with the dispatch API for free.
+
+---
+
+## Phase 2+3: Create + Hydrate
+
+```javascript
+var taco = makeStatsCard({ title: 'Revenue', value: 50000 });
+var node = bw.create(taco);
+```
+
+After this call, `node` is a **detached** DOM element:
+
+- `node.tagName` === `'DIV'`
+- `node.className` includes `stats-card bw_lc bw_is_component bw_uuid_xxxx`
+- `node._bw_state` === `{ value: 50000 }`
+- `node.bw.update` exists (bound handle method)
+- `node.bw.setValue` / `node.bw.setTitle` exist (slot setters, cached selectors)
+- `node.bw.getValue` / `node.bw.getTitle` exist (slot getters)
+- The h3 contains `Revenue`, the span contains `$50,000`
+- **NOT in the document.** Not registered. `o.mounted` has NOT fired.
+
+You rarely call `bw.create()` directly — this is shown for understanding.
+
+---
+
+## Phase 4: Mount
+
+```javascript
+var el = bw.mount('#dashboard', taco);
+```
+
+`bw.mount()` unmounts any previous children of `#dashboard`, creates the
+element, appends it, and runs the mount pass. It returns the root element.
+(`bw.DOM()` is the same function under its other name.)
+
+After mount:
+
+- Element is in the document inside `#dashboard`
+- Its UUID is registered — findable via `bw.el('bw_uuid_xxxx')`
+- `o.mounted` would have fired if this component had one (it doesn't)
+- Element is alive: `el.bw.update({ value: 75000 })` works
+
+**Try it in devtools:** select the card in the Elements panel and type
+`$0._bw_state` — the component's state, no browser extension required.
+`$0.bw` shows its public methods.
+
+---
+
+## Phase 5: Update
+
+Five ways, ordered by cost and coupling:
+
+### Direct handle method call (cheapest)
+
+```javascript
+el.bw.update({ value: 75000 });
+// card shows '$75,000'; el._bw_state.value === 75000
+```
+
+### Slot setter (bypasses the handle's logic)
+
+```javascript
+el.bw.setValue('SOLD OUT');
+// card shows 'SOLD OUT' (raw, no formatting)
+// el._bw_state.value is NOT updated — slot setters don't touch state
+```
+
+This is intentional. Slot setters are low-level; handle methods are the public
+API. If you call `setValue()` directly, keeping state consistent is on you.
+
+### Dispatch via bw.update
+
+```javascript
+bw.update(el, { value: 100000, title: 'Profit' });
+// dispatches to el.bw.update({ ... })
+```
+
+Works identically by UUID, without holding the element reference:
+
+```javascript
+var uuid = bw.getUUID(el);
+bw.update(uuid, { value: 100000 });
+```
+
+### Dispatch via bw.message (explicit method name)
+
+```javascript
+bw.message(el, 'update', { value: 200000 });
+// same as el.bw.update({ value: 200000 })
+```
+
+### Pub/sub (decoupled)
+
+```javascript
+bw.sub('revenue:change', function(data) {
+  el.bw.update(data);
+}, el);
+
+// elsewhere:
+bw.pub('revenue:change', { value: 999999 });
+```
+
+The third argument to `bw.sub()` ties the subscription to the element — when
+the element is unmounted, the subscription is removed automatically.
+
+Note what this component never needs: `bw.refresh()`. It has no `o.render`,
+because every update it supports is surgical. Reach for `o.render` +
+`bw.refresh(el)` when the component's *structure* changes with state, not just
+its values.
+
+---
+
+## Phase 6: Unmount
+
+```javascript
+bw.remove(el);
+```
+
+This unmounts and removes the element. The unmount pass:
+
+- Fires `o.unmount` if it existed (ours doesn't)
+- Unregisters the UUID
+- Unsubscribes all pub/sub subscriptions tied to this element
+- Deletes `_bw_state`, `_bw_render`, `_bw_type`, and `el.bw`
+- Removes the element from the DOM
+
+After this, `el` is an inert DOM node with no bitwrench properties.
+
+---
+
+## The factory as reusable template
+
+```javascript
+var revenue = bw.mount('#stats', makeStatsCard({ title: 'Revenue', value: 50000 }));
+var users   = bw.mount('#stats', makeStatsCard({ title: 'Users',   value: 1234 }));
+var orders  = bw.mount('#stats', makeStatsCard({ title: 'Orders',  value: 89 }));
+```
+
+Three independent instances. Each has its own state, its own UUID, its own slot
+targets. The handle function is shared by reference, but `el` (the first
+argument) is bound per instance. State is per instance (`el._bw_state`).
+
+To update all three at once, publish:
+
+```javascript
+bw.pub('dashboard:refresh', newData);
+// each card subscribed to this topic updates independently
+```
+
+---
+
+## The design in one paragraph
+
+The TACO was consumed at mount time — bitwrench does not keep a copy of it.
+Everything the component is now lives on the DOM element itself: its state
+(`el._bw_state`), its public API (`el.bw`), its identity (`bw_uuid_*` class).
+There is no shadow tree to reconcile and no framework instance to look up.
+That's why updates are explicit and cheap — you (or the component itself) talk
+directly to the element — and why any component can be inspected, driven, or
+debugged from the browser console with no tooling.
+
+## See also
+
+- [State Management](state-management.md) — the full component model, `o.render` + `bw.refresh()`
+- [Thinking in Bitwrench §7](thinking-in-bitwrench.md) — lifecycle options and the update cost spectrum
+- [Component Library](component-library.md) — the built-in BCCL factories, which follow this exact pattern

package/docs/drift-lint.md

@@ -0,0 +1,268 @@
+# drift-lint -- keeping the docs honest
+
+`tools/drift-lint.js` is a repo-specific consistency checker. Where ESLint asks
+"is this code well-formed?", drift-lint asks **"do the docs still tell the truth?"**
+
+It exists because documentation rots silently. Code that calls a removed function
+fails a test; a doc that *teaches* a removed function fails a user, months later,
+with no error pointing back here. The v2.1 alignment release cleaned up exactly
+this kind of rot -- drift-lint is what makes that cleanup permanent instead of a
+one-time event. Every API removal, rename, or terminology ruling gets encoded as
+a rule, and from then on the stale form physically cannot reach a release.
+
+It also extracts the real public API from `src/` at runtime and cross-references
+every `bw.XXX()` call in scanned files against it. If a doc references a function
+that doesn't exist in the source, drift-lint catches it -- no manual rule needed.
+
+## Usage
+
+```
+npm run lint:drift                    # run all rules
+node tools/drift-lint.js              # same thing, direct
+node tools/drift-lint.js --verbose    # show honored ignore blocks and config excludes
+node tools/drift-lint.js --list-rules # print all rules with descriptions
+node tools/drift-lint.js --help       # CLI help
+```
+
+## When it runs
+
+| Trigger | Why there |
+|---------|-----------|
+| `npm run lint:drift` | Direct invocation |
+| `posttest` (after every `npm test`) | Cheapest possible feedback loop |
+| `postbuild` (after every `npm run build`) | Generated artifacts (e.g. `readme.html`) are scanned fresh |
+| `tools/release.js` step 4 | A stale doc cannot ship |
+
+It scans ~120 files in well under a second. No browsers, no network, no flake --
+it is always safe to make blocking.
+
+## What it scans
+
+- **Directories (recursive):** `docs/`, `pages/`, `examples/`, `embedded_python/`
+- **Root files:** `README.md`, `CONTRIBUTING.md`, `ABOUT.md`, `readme.html`, `llms.txt`, `agents.md`
+- **Extensions:** `.md`, `.html`, `.js`, `.py`, `.sh`, `.ts`, `.txt`
+- **Skipped:** `node_modules`, `dist`, `coverage`, `.git`, and `dev/` (internal
+  notes are allowed to discuss stale patterns — the SUPERSEDED archives live there)
+
+`src/` is deliberately out of scope: working code is ESLint's jurisdiction, and
+several rules (like the wire-format field renames) would false-positive against
+the implementation that has to handle both forms.
+
+`readme.html` is scanned even though it is generated: if someone fixes
+`README.md` but forgets `npm run build:readme`, the mirror goes stale — which is
+itself drift, and the postbuild hook catches it.
+
+## Rule kinds
+
+### Name rules
+
+A token that should no longer appear. The simplest and most common kind:
+
+<!-- drift-lint:ignore-start: documenting the rule format requires showing banned tokens -->
+```javascript
+{
+  id: 'toggleStyles',
+  pattern: /toggleStyles/g,
+  message: 'bw.toggleStyles() → bw.toggleThemeMode()',
+  contextExclude: [
+    /removed|was removed|renamed|no longer|SUPERSEDED/i
+  ]
+}
+```
+<!-- drift-lint:ignore-end -->
+
+Fields:
+
+| Field | Meaning |
+|-------|---------|
+| `id` | Short name, shown in the failure report |
+| `pattern` | Regex tested line by line |
+| `message` | What to do instead — write it as `old → new` |
+| `contextExclude` | Regexes that exempt a matching line (e.g. a removal note legitimately names the removed API) |
+| `fileFilter` | Only scan matching paths (e.g. `/\.md$/`) |
+| `fileExclude` | Skip matching paths entirely |
+
+### Structural rules
+
+An anti-pattern *shape* rather than a banned name — every individual token is
+fine, the combination is wrong. Structural rules add two fields: `followedBy`
+(evidence regex) and `within` (line window). The rule fires when the anchor
+matches and the evidence appears within N lines:
+
+```javascript
+{
+  id: 'mounted-event-wiring',
+  pattern: /\bmounted\s*:/,                          // anchor
+  followedBy: /\.addEventListener\(\s*['"](?:click|input|...)['"]/,  // evidence
+  within: 3,
+  message: 'event handler wired in o.mounted is lost on bw.refresh() — use a: { onclick: fn }',
+  fileFilter: /\.(html|js)$/,
+  contextExclude: [
+    /['"`].*addEventListener.*['"`]/,   // quoted demo code in comparison pages
+    /window\.addEventListener|document\.addEventListener/  // page-level listeners are fine
+  ]
+}
+```
+
+For structural rules, `contextExclude` is applied to the **evidence line** —
+that's where false-positive context lives (a quoted code string, a
+window-level listener).
+
+This rule enforces the #1 documented mistake in the lifecycle model: handlers
+attached via `addEventListener` inside `o.mounted` are silently lost when the
+component re-renders via `bw.refresh()`. Handlers belong in `a: { onclick: fn }`,
+which bitwrench re-attaches on every render.
+
+### API rules
+
+The stale-api rule is different from name and structural rules: it has no
+hand-written pattern. Instead, drift-lint extracts the real public API from
+`src/` at startup and checks every `bw.XXX()` call in scanned files against it.
+
+What it extracts:
+- `bw.XXX = function` assignments from all `src/bitwrench*.js` files
+- Object-literal properties on the `bw` object (e.g. `getVersion`, `version`)
+- `export function XXX` from `bitwrench-bccl.js` (become `bw.makeXxx`)
+- `export function XXX` from `bitwrench-color-utils.js` (become `bw.XXX`)
+
+What it skips:
+- `el.bw.XXX()` -- handle/slot method calls on component instances
+- `bw._xxx()` -- private/internal names
+- Lines mentioning "removed", "deprecated", "renamed", etc.
+- Generic naming patterns like `bw.makeXxx()` (convention, not a literal call)
+
+This rule requires no maintenance. When you add, rename, or remove a public
+function in source, the rule automatically picks up the change. If a doc still
+references the old name, drift-lint flags it on the next run.
+
+Run `node tools/drift-lint.js --list-rules` to see the current API count.
+
+## The ignore pragma
+
+Sometimes a scanned file must legitimately contain a banned pattern — this
+document is the canonical example. Others: documenting how old versions worked,
+counter-examples shown for discussion, quoting other frameworks' APIs. Wrap the
+block and **give a reason**:
+
+```markdown
+<!-- drift-lint:ignore-start: comparison table quotes the old 2.0 API on purpose -->
+...exempt content...
+<!-- drift-lint:ignore-end -->
+```
+
+Any comment style works — the scanner matches the pragma text itself, so `//`,
+`#`, `/* */`, and `<!-- -->` are all fine:
+
+```javascript
+// drift-lint:ignore-start: demo intentionally shows the WRONG pattern for teaching
+...
+// drift-lint:ignore-end
+```
+
+For a single line, use `ignore-next-line` instead of a block:
+
+```javascript
+// drift-lint:ignore-next-line: comparing bitwrench to reactive frameworks
+const comparison = "Unlike reactive frameworks, bitwrench uses explicit updates";
+```
+
+Guard rails, so exemptions can't silently swallow more than intended:
+
+- `ignore-start` without a reason → **warning** (the run still passes — a
+  hotfix shouldn't be blocked on prose — but the nag prints on every run
+  until a reason is added. Pragmas without context become archaeology:
+  months later nobody knows what the exemption was protecting.)
+- `ignore-start` never closed → **error** (prevents accidentally exempting the rest of a file)
+- `ignore-end` without a start → **error**
+- nested `ignore-start` → **error**
+- `node tools/drift-lint.js --verbose` lists every honored block with its
+  file, line range, and reason — audit them occasionally; each one is debt
+- the summary line always shows the honored-block count
+
+Prefer `contextExclude` on the rule over pragmas in files: an exclusion encodes
+*why* a context is acceptable once, centrally; pragmas scatter exemptions
+through the tree. Use the pragma when a single file has a unique, legitimate
+need the rule shouldn't generalize.
+
+## Config file (.drift-lint-config.json)
+
+<!-- drift-lint:ignore-start: documenting the config feature requires showing rule IDs and example patterns -->
+For files that structurally and permanently contain a banned pattern (e.g. a
+design philosophy doc that will always discuss reactive systems comparatively),
+use the config file instead of scattering pragmas:
+
+```json
+{
+  "exclude": {
+    "reactive-self": ["docs/bitwrench-northstar-principles.md"],
+    "*": ["docs/legacy-migration-guide.md"]
+  }
+}
+```
+<!-- drift-lint:ignore-end -->
+
+- Keys are rule IDs (from the `id` field in RULES). `"*"` excludes from all rules.
+- Values are arrays of relative paths (from repo root, forward slashes).
+- `--verbose` reports which config excludes are active.
+
+Use config excludes when a file's relationship to a rule is structural — the
+file will always legitimately contain the pattern, and re-wording to avoid it
+would make the document worse. Use pragmas for isolated one-off exemptions
+within an otherwise-scanned file.
+
+## Adding a rule
+
+When you remove, rename, or re-decide something user-facing:
+
+1. Add the rule to `RULES` in `tools/drift-lint.js` in the same commit as the
+   change. The rule *is* the enforcement half of the decision.
+2. Write the message as the migration: `old → new`, not just "don't".
+3. Run `npm run lint:drift` — it will list every place the old form survives.
+   Fix them all in the same commit if feasible.
+4. Add `contextExclude` entries only for patterns of legitimate use you actually
+   observed, not hypothetical ones.
+5. If a doc must keep the old form (removal notes, migration guides,
+   comparison tables), prefer a `contextExclude`; reach for the pragma only
+   for one-off cases.
+
+## Current rule inventory
+
+<!-- drift-lint:ignore-start: the inventory table must name the banned patterns it documents -->
+
+| Rule | Catches | Correct form |
+|------|---------|--------------|
+| `client.render` / `client.exec` / `client.query` / `client.register` | 2.0 bwserve client APIs | `client.mount()`; exec/query/register removed |
+| `bw.createDOM` | 2.0 name | `bw.create()` |
+| `bw.cleanup` | 2.0 name | `bw.unmount()` |
+| `bw.component` | removed API | TACO `o:` options |
+| `data-bw-action` | 2.0 action attribute | `bw_act_*` CSS class |
+| `allowExec` / `--allow-exec` / `/exec` | removed exec surface | removed in v2.1 |
+| `wire:target` / `wire:node` | 2.0 wire field names | `"ref"` / `"taco"` |
+| `parseRJSON` | 2.0 name | `bw.parseJSONFlex()` |
+| `levels-taxonomy` | "Level 0/1/2" component taxonomy | descriptive stage names |
+| `toggleStyles` | removed API | `bw.toggleThemeMode()` |
+| `bw_card-bare` / `bw_btn-bare` | pre-rename BCCL class names in docs | `bw_bccl_card` / `bw_bccl_btn` (the bare forms remain valid as stylesheet classes) |
+| `bw-container` | hyphen class form | `bw_container` (underscore canonical) |
+| `normalizeClass` | never-shipped API | remove reference |
+| `three-level` | stale component-model count | describe stages, don't count |
+| `outline-hyphen` | hyphen variant spelling | `outline_primary` etc. |
+| `reactive-self` | "reactive" as self-description | "explicit stateful" / "state + explicit re-render" (comparative uses are excluded) |
+| `getHandle` | removed API | handles live on `el.bw` directly |
+| `update-as-rerender` | prose claiming `bw.update()` re-renders | `bw.update()` dispatches; re-render is `bw.refresh()` |
+| `mounted-event-wiring` | structural: DOM event handlers wired in `o.mounted` | `a: { onclick: fn }` |
+| `stale-api` | `bw.XXX()` in docs where XXX is not in the public API | auto-detected from `src/` -- no manual rule needed |
+
+<!-- drift-lint:ignore-end -->
+
+## Design constraints
+
+- **Zero dependencies, zero flake.** Plain-string scanning only. If a rule
+  needs an AST, it belongs in ESLint; if it needs a browser, it belongs in
+  Playwright. Drift-lint stays fast enough that nobody is ever tempted to
+  skip it.
+- **Every rule earns its place by having fired at least once.** Rules encode
+  real drift that actually happened (or a decision actually made), not
+  hypothetical hygiene.
+- **False positives are rule bugs.** If a legitimate line trips a rule, fix
+  the rule (`contextExclude`), don't pragma around it — the next legitimate
+  use will trip it again.