@techninja/clearstack 0.2.0

package/templates/shared/README.md

@@ -0,0 +1,22 @@
+# {{name}}
+
+> {{description}}
+
+Built with the [Clearstack](https://github.com/techninja/clearstack) no-build web component specification.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev       # Start dev server
+npm test          # Run tests
+npm run spec      # Spec compliance checker
+```
+
+## Specification
+
+See `docs/` for the full specification this project follows.
+
+## License
+
+MIT

package/templates/shared/docs/app-spec/README.md

@@ -0,0 +1,40 @@
+# Application-Specific Specifications
+
+> This directory is yours. The upstream spec will never touch it.
+
+## What Goes Here
+
+Files in `docs/clearstack/` are managed by the upstream package.
+Running `npx clearstack update` may overwrite them with newer versions.
+**This `docs/app-spec/` directory is excluded from upstream updates** —
+it's where your project's own conventions, domain-specific patterns,
+and architectural decisions live.
+
+## What to Document
+
+| Document | Example content |
+|---|---|
+| `ENTITIES.md` | Your domain entities, their relationships, field descriptions |
+| `PATTERNS.md` | Project-specific component patterns, naming overrides |
+| `API.md` | Custom API endpoints beyond the generic CRUD |
+| `DEPLOYMENT.md` | How this project is built, deployed, and monitored |
+| `DECISIONS.md` | Architecture Decision Records — why you chose X over Y |
+| `OVERRIDES.md` | Where your project intentionally deviates from the base spec and why |
+
+## Rules
+
+- **One topic per file.** Same as the base spec — split when it grows.
+- **Link to the base spec** when extending it, not duplicating it.
+- **Document deviations explicitly.** If you override a base spec convention,
+  say which one and why. Future you (or your LLM) will thank you.
+- **Keep it current.** If a pattern changes, update the doc in the same PR.
+
+## How Updates Work
+
+When you run `npx clearstack update`:
+
+1. Files in `docs/clearstack/` are compared against the upstream package
+2. Changed files are overwritten — review with `git diff docs/`
+3. Files in `.configs/` are also synced to latest standards
+4. **`docs/app-spec/` is never touched** — your files are safe
+5. The `docs/clearstack/.specversion` file tracks which upstream version you synced from

package/templates/shared/docs/clearstack/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/templates/shared/docs/clearstack/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.