@techninja/clearstack 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hybrids-spec contributors
+
+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,81 @@
+# Clearstack
+
+A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
+
+## Why This Exists
+
+Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: **what if we optimized for comprehension instead?**
+
+The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.
+
+This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: `npm run spec` checks every file against its own rules.
+
+## Quick Start
+
+```bash
+npm install
+npm start         # http://localhost:3000
+npm test          # node + browser tests
+npm run spec      # interactive spec compliance checker
+```
+
+## What's In The Box
+
+A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
+
+## Specification
+
+| Document | What It Covers |
+|---|---|
+| [FRONTEND_IMPLEMENTATION_RULES.md](./docs/FRONTEND_IMPLEMENTATION_RULES.md) | Philosophy, framework choice, project structure, atomic design |
+| [COMPONENT_PATTERNS.md](./docs/COMPONENT_PATTERNS.md) | Authoring, light DOM, styling, layout engine, JSDoc typing |
+| [STATE_AND_ROUTING.md](./docs/STATE_AND_ROUTING.md) | Store, routing, unified app state, realtime SSE sync |
+| [CONVENTIONS.md](./docs/CONVENTIONS.md) | Naming rules, anti-patterns |
+| [SERVER_AND_DEPS.md](./docs/SERVER_AND_DEPS.md) | Express server, import maps, vendor dependency loading |
+| [BACKEND_API_SPEC.md](./docs/BACKEND_API_SPEC.md) | REST CRUD, JSON Schema via HEAD, entity management |
+| [TESTING.md](./docs/TESTING.md) | Testing philosophy, tools, patterns, phase checkpoints |
+| [BUILD_LOG.md](./docs/BUILD_LOG.md) | How this project was built — LLM-human collaboration proof |
+| [QUICKSTART.md](./docs/QUICKSTART.md) | Scaffolder setup, development workflow, updating, compliance |
+
+## Start a New Project
+
+The Clearstack scaffolder generates a spec-compliant project from templates and keeps it in sync as the spec evolves.
+
+```bash
+npx clearstack init       # interactive project scaffolder
+npx clearstack update     # sync spec docs + configs from upstream
+npx clearstack check      # run spec compliance checks
+```
+
+Two modes: **fullstack** (Express + WebSocket + JSON DB + SSE) or **static** (localStorage, no server).
+
+See [QUICKSTART.md](./docs/QUICKSTART.md) for the full walkthrough.
+
+## Rules That Matter
+
+- **No build tools.** ES modules served directly to the browser.
+- **≤150 lines per code file.** When it grows, it splits.
+- **Light DOM by default.** Shared styles just work.
+- **JSDoc over TypeScript.** Types without a compile step — validated by `tsc --checkJs`.
+- **Test at the boundary.** Each phase passes before the next begins.
+- **The spec checks itself.** `npm run spec:code` and `npm run spec:docs`.
+- **Lint and format.** ESLint + Prettier, semicolons, 2-space indent.
+
+## Scripts
+
+```bash
+npm start           # Start server
+npm run dev         # Start with --watch
+npm test            # Node + browser tests
+npm run lint        # ESLint check
+npm run lint:fix    # ESLint auto-fix
+npm run format      # Prettier auto-format
+npm run typecheck   # JSDoc type validation via tsc
+npm run spec        # Interactive spec compliance checker
+npm run spec:code   # Check code files ≤150 lines
+npm run spec:docs   # Check doc files ≤500 lines
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * clearstack CLI — scaffold, update, and check spec-compliant projects.
+ * Usage:
+ *   clearstack init [-y] [--mode fullstack|static] [--port 3000]
+ *   clearstack update
+ *   clearstack check [code|docs]
+ *   clearstack                   → interactive menu
+ */
+
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+const cmd = args.find((a) => !a.startsWith('-'));
+const flags = Object.fromEntries(
+  args.filter((a) => a.startsWith('--')).map((a) => {
+    const [k, v] = a.slice(2).split('=');
+    return [k, v ?? true];
+  }),
+);
+const yes = args.includes('-y') || args.includes('--yes');
+
+/** Show interactive menu. */
+async function interactive() {
+  const { select } = await import('@inquirer/prompts');
+  const action = await select({
+    message: 'clearstack — what do you want to do?',
+    choices: [
+      { name: 'Initialize a new project', value: 'init' },
+      { name: 'Update spec docs + configs', value: 'update' },
+      { name: 'Run spec compliance check', value: 'check' },
+    ],
+  });
+  await run(action);
+}
+
+/**
+ * Run a subcommand.
+ * @param {string} action
+ */
+async function run(action) {
+  if (action === 'init') {
+    const { init } = await import('../lib/init.js');
+    await init(PKG_ROOT, { yes, ...flags });
+  } else if (action === 'update') {
+    const { update } = await import('../lib/update.js');
+    await update(PKG_ROOT);
+  } else if (action === 'check') {
+    const sub = args.find((a) => a !== cmd && !a.startsWith('-'));
+    const { check } = await import('../lib/check.js');
+    await check(process.cwd(), sub);
+  } else {
+    console.log('Usage: clearstack [init|update|check] [-y]');
+  }
+}
+
+if (cmd) await run(cmd);
+else if (yes) await run('check');
+else await interactive();

package/docs/BACKEND_API_SPEC.md

@@ -0,0 +1,281 @@
+# Backend API Specification
+## REST Endpoints, JSON Schema Discovery & Realtime Sync
+
+> Defines the server-side data contract. The frontend consumes this API via
+> `[store.connect]` storage connectors.
+> See [STATE_AND_ROUTING.md](./STATE_AND_ROUTING.md) for how the frontend
+> binds to these endpoints.
+
+---
+
+## Design Principles
+
+- **Standard REST** — resources as nouns, HTTP verbs for actions.
+- **JSON Schema via OPTIONS** — every entity endpoint exposes its schema and
+  allowed methods on `OPTIONS` requests, enabling automated form generation.
+- **Field-level validation errors** — server returns `422` with per-field
+  error messages that map directly to form fields.
+- **SSE for realtime** — a single `/api/events` stream pushes entity change
+  notifications to connected clients.
+- **Stateless requests** — no server-side sessions. Auth via tokens if needed.
+
+---
+
+## URL Structure
+
+```
+/api/:entity            OPTIONS (schema + methods), GET (list), POST (create)
+/api/:entity/:id        OPTIONS (schema + methods), GET (read), PUT (update), DELETE (remove)
+/api/events             GET (SSE stream)
+```
+
+All request/response bodies are `application/json`.
+
+---
+
+## OPTIONS — Schema & Capability Discovery
+
+An `OPTIONS` request to any entity endpoint returns the JSON Schema and
+allowed HTTP methods. This is the primary mechanism for schema-driven forms.
+
+### Example: `OPTIONS /api/projects`
+
+```json
+{
+  "schema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Project",
+    "type": "object",
+    "required": ["name"],
+    "properties": { ... }
+  },
+  "methods": ["OPTIONS", "GET", "POST"]
+}
+```
+
+### Example: `OPTIONS /api/projects/p1`
+
+```json
+{
+  "schema": { ... },
+  "methods": ["OPTIONS", "GET", "PUT", "DELETE"]
+}
+```
+
+The `Allow` header is also set for HTTP compliance.
+`GET /api/:entity?schema=true` is still supported as a convenience.
+
+### Schema-Driven Forms
+
+The frontend can fetch the schema at runtime and generate form fields
+automatically. The schema provides:
+
+| JSON Schema keyword | Form behavior |
+|---|---|
+| `type: "string"` | `<input type="text">` |
+| `format: "email"` | `<input type="email">` |
+| `format: "date-time"` | `<input type="datetime-local">` |
+| `enum: [...]` | `<select>` with options |
+| `minLength` / `maxLength` | Validation constraints |
+| `readOnly: true` | Field displayed but not editable |
+| `required: [...]` | Native `required` attribute + visual indicator |
+
+JSON Schema constraints map directly to HTML validation attributes:
+
+| JSON Schema | HTML attribute |
+|---|---|
+| `minLength` | `minlength` |
+| `maxLength` | `maxlength` |
+| `minimum` | `min` |
+| `maximum` | `max` |
+| `pattern` | `pattern` |
+
+The browser's native constraint validation API enforces these — no custom
+JS validation needed for client-side checks.
+
+---
+
+## Server-Side Validation & Error Responses
+
+Some validation can only happen server-side (uniqueness, business rules).
+When validation fails, the server returns `422` with field-level errors:
+
+```json
+{
+  "error": "Validation failed",
+  "fields": {
+    "name": "name is required",
+    "status": "Must be one of: active, archived"
+  }
+}
+```
+
+The `schema-form` component maps `fields` entries to the corresponding
+`form-field` components, which display the error below the input.
+
+### Error Response Contract
+
+| Status | Body | Meaning |
+|---|---|---|
+| `422` | `{ error, fields }` | Validation failed — `fields` maps names to messages |
+| `404` | `{ error }` | Entity or collection not found |
+| `201` | Entity JSON | Created successfully |
+| `200` | Entity JSON | Updated successfully |
+| `204` | Empty | Deleted successfully |
+
+This allows a single generic `schema-form` component to render any entity's
+create/edit form without entity-specific template code.
+
+---
+
+## CRUD Operations
+
+### List — `GET /api/:entity`
+
+Query params for filtering, sorting, pagination:
+
+| Param | Example | Purpose |
+|---|---|---|
+| `limit` | `?limit=20` | Page size (default: 20) |
+| `offset` | `?offset=40` | Skip N records |
+| `sort` | `?sort=-createdAt` | Sort field, `-` prefix for desc |
+| `filter` | `?role=admin` | Field equality filter |
+
+Response:
+
+```json
+{
+  "data": [ { "id": "1", "firstName": "Jane", ... } ],
+  "total": 42,
+  "limit": 20,
+  "offset": 0
+}
+```
+
+### Read — `GET /api/:entity/:id`
+
+Returns a single entity object:
+
+```json
+{ "id": "1", "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com" }
+```
+
+Returns `404` if not found.
+
+### Create — `POST /api/:entity`
+
+Request body: entity fields (without `id` or `readOnly` fields).
+Response: the created entity with `id` and server-generated fields.
+Status: `201 Created`.
+
+### Update — `PUT /api/:entity/:id`
+
+Request body: full or partial entity fields.
+Response: the updated entity.
+Status: `200 OK`.
+
+### Delete — `DELETE /api/:entity/:id`
+
+Response: `204 No Content`.
+
+---
+
+## Realtime Sync — SSE
+
+### Endpoint: `GET /api/events`
+
+Returns a `text/event-stream` connection. The server pushes events when
+entities are created, updated, or deleted.
+
+### Event Format
+
+```
+event: update
+data: {"type":"user","id":"1","action":"updated"}
+
+event: update
+data: {"type":"user","id":"3","action":"created"}
+
+event: update
+data: {"type":"user","id":"2","action":"deleted"}
+```
+
+| Field | Value |
+|---|---|
+| `type` | Entity name (lowercase, singular): `user`, `post` |
+| `id` | Entity ID that changed |
+| `action` | `created`, `updated`, or `deleted` |
+
+### Frontend Integration
+
+See [STATE_AND_ROUTING.md](./STATE_AND_ROUTING.md) — the `connectRealtime()`
+utility listens to this stream and calls `store.clear()` on the relevant
+model, triggering automatic re-fetch for any component displaying that data.
+
+---
+
+## Dummy Data
+
+The server ships with in-memory dummy data for development. No database
+required.
+
+### Data Structure (server-side)
+
+```javascript
+/** @type {Map<string, Map<string, object>>} */
+const db = new Map();
+
+// Seed with dummy users
+db.set('users', new Map([
+  ['1', { id: '1', firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com', role: 'admin', createdAt: '2024-01-15T09:00:00Z' }],
+  ['2', { id: '2', firstName: 'John', lastName: 'Smith', email: 'john@example.com', role: 'editor', createdAt: '2024-02-20T14:30:00Z' }],
+  ['3', { id: '3', firstName: 'Alex', lastName: 'Chen', email: 'alex@example.com', role: 'viewer', createdAt: '2024-03-10T11:15:00Z' }],
+]));
+```
+
+### Schema Registry (server-side)
+
+Schemas are defined once and served via OPTIONS:
+
+```javascript
+const schemas = new Map();
+schemas.set('users', {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'User',
+  type: 'object',
+  required: ['firstName', 'lastName', 'email'],
+  properties: { /* ... as above ... */ },
+});
+```
+
+### Adding a New Entity
+
+1. Define the JSON Schema in the schema registry.
+2. Seed dummy data in the `db` Map.
+3. The generic CRUD router handles all operations automatically.
+4. Create a corresponding frontend store model in `src/store/`.
+
+No entity-specific route handlers needed — the server uses a single generic
+router that works for any entity registered in the schema map.
+
+---
+
+## Frontend ↔ Backend Contract
+
+| Frontend (Hybrids Store) | Backend (Express) |
+|---|---|
+| `[store.connect].get(id)` | `GET /api/:entity/:id` |
+| `[store.connect].set(id, values)` | `PUT /api/:entity/:id` |
+| `[store.connect].list(params)` | `GET /api/:entity?...` |
+| `store.set(model, null)` (delete) | `DELETE /api/:entity/:id` |
+| Schema fetch for forms | `OPTIONS /api/:entity` |
+| Schema fetch for item | `OPTIONS /api/:entity/:id` |
+| Realtime invalidation | `GET /api/events` (SSE) |
+
+This contract means adding a new entity type requires:
+- One JSON Schema definition (server)
+- One store model file (frontend)
+- Dummy seed data (server, for dev)
+
+Everything else — CRUD routes, form generation, cache invalidation — is
+handled by the generic infrastructure.

package/docs/BUILD_LOG.md

@@ -0,0 +1,193 @@
+# Build Log
+## How This Project Was Built
+
+> This entire repository — specification, implementation, tests, and this
+> document — was authored in a single continuous conversation between a human
+> and an LLM (Amazon Q). No code was written outside this collaboration.
+
+---
+
+## Timeline
+
+The project was built over ~1.5 days in a single LLM context window.
+Each phase was implemented, tested, and verified before proceeding.
+
+### Phase 1: Specification
+- Wrote the initial spec as one file, hit ~500 lines
+- Split into 7 topic-specific documents (the spec eating its own dogfood)
+- Chose Hybrids.js after reading its source and type definitions from node_modules
+
+### Phase 2: Infrastructure
+- Express server, vendor-deps script, import maps, HTML shell
+- JSON Schema registry with seed data
+- Generic CRUD router — one router handles all entity types
+- 15 server tests passing before writing any frontend code
+
+### Phase 3: Store Models & Utils
+- Singleton models (AppState, UserPrefs) with localStorage connectors
+- Enumerable models (ProjectModel, TaskModel) with API connectors
+- Utility functions (formatDate, timeAgo, statusColors)
+- 35 tests passing
+
+### Phase 4: Components (Atoms → Molecules → Organisms)
+- Built bottom-up: app-button, app-badge, app-icon → task-card, project-card → task-list, project-header
+- Browser tests via @web/test-runner + Playwright
+- 63 tests passing
+
+### Phase 5: Pages, Router & Integration
+- page-layout template, home-view, project-view, app-router
+- SSE realtime sync wired at the router level
+- SPA fallback for direct URL navigation
+
+### Phase 6: Schema-Driven Forms
+- OPTIONS endpoint returns JSON Schema + form layout
+- schema-form organism auto-generates fields from schema
+- Native HTML validation from schema constraints
+- Server-side validation returns 422 with per-field errors
+- Form layout system with column grouping and action alignment
+
+### Phase 7: Polish & Tooling
+- Dark mode via CSS custom property overrides
+- Spec checker CLI with interactive menu
+- ESLint + Prettier + tsc --checkJs for JSDoc type validation
+- GitHub Actions CI pipeline
+- File reorganization (docs/, .configs/, tests/)
+
+### Phase 8: Drag Reorder & Whiteboard
+- Drag-to-reorder with visual gap indicator and backend persistence
+- WebSocket server for real-time canvas collaboration
+- SVG whiteboard with drawing tools (in progress)
+
+---
+
+## Discoveries & Corrections
+
+The spec was written first, then corrected as implementation revealed gaps.
+These are the significant corrections:
+
+### Light DOM breaks slots
+- **Expected:** `<slot>` for content composition
+- **Actual:** Hybrids throws on `<slot>` in light DOM
+- **Fix:** Template functions instead of template components
+- **Documented in:** COMPONENT_PATTERNS.md → Content Composition
+
+### Template components break host context
+- **Expected:** Event handlers in content templates resolve to the page
+- **Actual:** `host` resolves to the nearest hybrids component (the template)
+- **Fix:** Use plain functions that return `html`, not `define()`'d components
+- **Documented in:** COMPONENT_PATTERNS.md → Event Handler Host Context
+
+### Custom events don't bubble by default
+- **Expected:** `dispatch(host, 'press')` reaches parent listeners
+- **Actual:** Without `bubbles: true`, events stop at the dispatching element
+- **Fix:** Always `dispatch(host, 'event', { bubbles: true })`
+- **Documented in:** COMPONENT_PATTERNS.md → Custom Events Must Bubble
+
+### store.clear(Model) vs store.clear([Model])
+- **Expected:** `store.clear(TaskModel)` refreshes task lists
+- **Actual:** Only clears singular cache, not list cache
+- **Fix:** Use `store.clear([TaskModel])` for list stores
+- **Documented in:** STATE_AND_ROUTING.md → Store API Quick Reference
+
+### store.ready(list) doesn't guarantee item readiness
+- **Expected:** If the list is ready, items are ready
+- **Actual:** Individual items can be pending after cache clear
+- **Fix:** Guard each item with `store.ready(task)` in map()
+- **Documented in:** STATE_AND_ROUTING.md → Guarding List Item Access
+
+### localStorage connector must return {}, not undefined
+- **Expected:** Returning undefined uses model defaults
+- **Actual:** Hybrids treats undefined as a failed get → error state
+- **Fix:** Return `{}` so hybrids merges with defaults
+- **Documented in:** STATE_AND_ROUTING.md → localStorage Connector
+
+### Batch operations cause SSE storms
+- **Expected:** Reordering N tasks sends N updates, UI handles it
+- **Actual:** N SSE events → N store.clear() calls → cascading errors
+- **Fix:** Debounce SSE handler per entity type (300ms)
+- **Documented in:** STATE_AND_ROUTING.md → Debouncing Batch Operations
+
+### Server sort used string comparison for numbers
+- **Expected:** sortOrder field sorts numerically
+- **Actual:** `localeCompare` on numbers gives wrong order
+- **Fix:** Detect numeric values and use `a - b` comparison
+
+### SVG transforms: two-group rotation approach
+- **Expected:** Embed rotation in shapeTransform string
+- **Actual:** Rotation center in local coords doesn't match screen position
+- **Fix:** Outer `<g>` for rotation (screen-space center), inner `<g>` for translate+scale
+- **Documented in:** COMPONENT_PATTERNS.md → Coordinate Transforms
+
+### Move after rotation: unrotate is wrong for translate
+- **Expected:** Unrotate screen delta for the inner translate
+- **Actual:** Causes magnified/skewed movement
+- **Fix:** Move both rotation center AND inner translate by raw screen delta
+- **Key insight:** `rotate(deg, cx, cy)` = `translate(cx,cy) rotate(deg) translate(-cx,-cy)`. Shifting cx,cy and translate by the same delta cancels out.
+
+### Resize after rotation: unrotate IS needed
+- **Expected:** Same approach as move
+- **Actual:** Handles are visually rotated, so screen drag doesn't align with object axes
+- **Fix:** Unrotate resize deltas only, not move deltas
+
+### SVG innerHTML destroys event listeners
+- **Expected:** Event listeners persist across renders
+- **Actual:** `innerHTML` replaces the DOM, losing all listeners
+- **Fix:** Re-bind mouse listeners in `observe`, attach keyboard to host element
+- **Documented in:** COMPONENT_PATTERNS.md → SVG Content via innerHTML
+
+### Path d-string manipulation breaks arc commands
+- **Expected:** Regex replace on coordinate pairs works for all paths
+- **Actual:** Arc commands have flags (0/1) that get mangled
+- **Fix:** Use `shapeTransform` for complex shapes, only rewrite d for M/L paths
+
+### Canvas pan offset not applied to drawing coordinates
+- **Expected:** Drawing at the visual position works after panning
+- **Actual:** Coordinates calculated from SVG rect, not accounting for pan
+- **Fix:** Shared `canvasPos()` utility subtracts pan offset from all tools
+
+---
+
+## Metrics
+
+| Metric | Value |
+|---|---|
+| Total source files | 108 |
+| Utility modules | 25 |
+| Component files | 13 |
+| Style sheets | 6 |
+| API modules | 6 |
+| Page views | 2 |
+| Test files | 14 |
+| Node tests | 65 |
+| Browser tests | 41 |
+| Spec documents | 10 |
+| Max lines per file | 150 (enforced) |
+| Max lines per doc | 500 (enforced) |
+| Automated checks | 7 (line counts, lint, format, types, tests) |
+| Build phases | 8 + whiteboard |
+| Bugs found & fixed | ~25 significant |
+| Bugs requiring >4 iterations | 3 (drag reorder, event bubbling, SVG transforms) |
+| External dependencies | 4 runtime (hybrids, express, ws, lucide-static) |
+| Build tools | 0 |
+
+---
+
+## What This Proves
+
+1. **Small files work for LLMs.** Every file fits in a single read. No scrolling,
+   no "show me lines 200-300", no losing context.
+
+2. **The spec catches drift.** When implementation diverged from the spec
+   (e.g. using slots in light DOM), the spec checker or manual review caught
+   it, and both the code and spec were corrected.
+
+3. **Test-at-the-boundary works.** Each phase was tested before the next began.
+   The two hardest bugs (drag reorder, event bubbling) were in the last phases
+   where components composed deeply — exactly where integration tests matter.
+
+4. **No-build is viable.** The app loads in 0.17s LCP, handles real-time sync
+   across browsers, and every file is debuggable as-written in devtools.
+
+5. **The spec improves through implementation.** 9 significant corrections were
+   made to the spec based on what we learned building the proof. The spec is
+   now more accurate than if it had been written in isolation.