@techninja/clearstack 0.2.16 → 0.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.2.16",
+  "version": "0.2.19",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -23,7 +23,7 @@
     "test": "node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js",
     "spec": "node --env-file=.env scripts/spec.js",
     "lint": "eslint --config .configs/eslint.config.js . --fix",
-    "format": "prettier --config .configs/.prettierrc --write src scripts tests",
+    "format": "prettier --config .configs/.prettierrc --write src scripts tests templates/**/*.md templates/**/*.html templates/**/*.css templates/**/*.json",
     "typecheck": "tsc --project .configs/jsconfig.json",
     "release": "node scripts/release.js",
     "prepublishOnly": "node scripts/sync-docs.js"
@@ -54,8 +54,11 @@
     "express": "^5.2.1",
     "hybrids": "^9.1.22",
     "lucide-static": "^1.7.0",
+    "markdownlint-cli2": "^0.21.0",
     "playwright": "^1.50.0",
     "prettier": "^3.8.1",
+    "stylelint": "^17.6.0",
+    "stylelint-config-standard": "^40.0.0",
     "typescript": "^6.0.2",
     "ws": "^8.20.0"
   }

package/templates/fullstack/data/seed.json

@@ -1 +1 @@
-{"example": {}}
+{ "example": {} }

package/templates/shared/.configs/.markdownlint.jsonc

@@ -0,0 +1,9 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD024": { "siblings_only": true },
+  "MD033": false,
+  "MD040": false,
+  "MD041": false,
+  "MD060": false,
+}

package/templates/shared/.configs/.stylelintrc.json

@@ -0,0 +1,16 @@
+{
+  "extends": "stylelint-config-standard",
+  "rules": {
+    "import-notation": "string",
+    "selector-class-pattern": null,
+    "custom-property-pattern": null,
+    "no-descending-specificity": null,
+    "rule-empty-line-before": [
+      "always",
+      {
+        "except": ["first-nested"],
+        "ignore": ["after-comment"]
+      }
+    ]
+  }
+}

package/templates/shared/.configs/jsconfig.json

@@ -13,13 +13,6 @@
       "hybrids": ["../node_modules/hybrids/types/index.d.ts"]
     }
   },
-  "include": [
-    "../src/**/*.js",
-    "../scripts/**/*.js"
-  ],
-  "exclude": [
-    "../node_modules",
-    "../src/public/vendor",
-    "../**/*.test.js"
-  ]
+  "include": ["../src/**/*.js", "../scripts/**/*.js"],
+  "exclude": ["../node_modules", "../src/public/vendor", "../**/*.test.js"]
 }

package/templates/shared/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,7 +1,7 @@
 ---
 name: Bug Report
 about: Something isn't working as expected
-title: "[Bug] "
+title: '[Bug] '
 labels: bug
 ---
 

package/templates/shared/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,7 +1,7 @@
 ---
 name: Feature Request
 about: Suggest a new feature or improvement
-title: "[Feature] "
+title: '[Feature] '
 labels: enhancement
 ---
 

package/templates/shared/.github/ISSUE_TEMPLATE/spec_correction.md

@@ -1,7 +1,7 @@
 ---
 name: Spec Correction
 about: The spec says one thing but implementation reveals another
-title: "[Spec] "
+title: '[Spec] '
 labels: spec
 ---
 

package/templates/shared/.github/pull_request_template.md

@@ -11,12 +11,15 @@
 <!-- List the key changes. Group by category if helpful. -->
 
 ### Added
+
 -
 
 ### Changed
+
 -
 
 ### Fixed
+
 -
 
 ## Spec Compliance

package/templates/shared/.github/workflows/spec.yml

@@ -12,11 +12,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 24
           cache: npm
 
       - run: npm ci

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

@@ -12,14 +12,14 @@ 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 |
+| 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
 

package/templates/shared/docs/clearstack/BACKEND_API_SPEC.md

@@ -1,4 +1,5 @@
 # Backend API Specification
+
 ## REST Endpoints, JSON Schema Discovery & Realtime Sync
 
 > Defines the server-side data contract. The frontend consumes this API via
@@ -70,25 +71,25 @@ The `Allow` header is also set for HTTP compliance.
 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 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` |
+| ----------- | -------------- |
+| `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.
@@ -115,13 +116,13 @@ The `schema-form` component maps `fields` entries to the corresponding
 
 ### 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 |
+| 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.
@@ -134,12 +135,12 @@ create/edit form without entity-specific template code.
 
 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 |
+| 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:
 
@@ -200,11 +201,11 @@ 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` |
+| Field    | Value                                             |
+| -------- | ------------------------------------------------- |
+| `type`   | Entity name (lowercase, singular): `user`, `post` |
+| `id`     | Entity ID that changed                            |
+| `action` | `created`, `updated`, or `deleted`                |
 
 ### Frontend Integration
 
@@ -226,11 +227,44 @@ required.
 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' }],
-]));
+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)
@@ -244,7 +278,9 @@ schemas.set('users', {
   title: 'User',
   type: 'object',
   required: ['firstName', 'lastName', 'email'],
-  properties: { /* ... as above ... */ },
+  properties: {
+    /* ... as above ... */
+  },
 });
 ```
 
@@ -262,17 +298,18 @@ 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) |
+| 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)

package/templates/shared/docs/clearstack/BUILD_LOG.md

@@ -1,4 +1,5 @@
 # Build Log
+
 ## How This Project Was Built
 
 > This entire repository — specification, implementation, tests, and this
@@ -13,33 +14,39 @@ 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
@@ -47,6 +54,7 @@ Each phase was implemented, tested, and verified before proceeding.
 - 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
@@ -54,6 +62,7 @@ Each phase was implemented, tested, and verified before proceeding.
 - 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)
@@ -66,81 +75,95 @@ 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
@@ -149,26 +172,26 @@ These are the significant corrections:
 
 ## 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 |
+| 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 |
+| External dependencies        | 4 runtime (hybrids, express, ws, lucide-static)  |
+| Build tools                  | 0                                                |
 
 ---