@techninja/clearstack 0.2.8 → 0.2.18

package/docs/STATE_AND_ROUTING.md

@@ -1,4 +1,5 @@
 # State & Routing
+
 ## Store, Routing, Unified App State & Realtime Sync
 
 > How data flows through the application.
@@ -19,7 +20,11 @@ export default define({
   tag: 'app-toggle',
   open: false,
   render: ({ open }) => html`
-    <button onclick="${host => { host.open = !host.open; }}">
+    <button
+      onclick="${(host) => {
+        host.open = !host.open;
+      }}"
+    >
       ${open ? 'Close' : 'Open'}
     </button>
   `,
@@ -85,9 +90,11 @@ export default define({
   tag: 'theme-toggle',
   state: store(AppState),
   render: ({ state }) => html`
-    <button onclick="${host => {
-      store.set(host.state, { theme: host.state.theme === 'light' ? 'dark' : 'light' });
-    }}">
+    <button
+      onclick="${(host) => {
+        store.set(host.state, { theme: host.state.theme === 'light' ? 'dark' : 'light' });
+      }}"
+    >
       Theme: ${state.theme}
     </button>
   `,
@@ -114,13 +121,14 @@ const UserModel = {
   lastName: '',
   email: '',
   [store.connect]: {
-    get: (id) => fetch(`/api/users/${id}`).then(r => r.json()),
-    set: (id, values) => fetch(`/api/users/${id}`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(values),
-    }).then(r => r.json()),
-    list: (id) => fetch(`/api/users?${new URLSearchParams(id)}`).then(r => r.json()),
+    get: (id) => fetch(`/api/users/${id}`).then((r) => r.json()),
+    set: (id, values) =>
+      fetch(`/api/users/${id}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(values),
+      }).then((r) => r.json()),
+    list: (id) => fetch(`/api/users?${new URLSearchParams(id)}`).then((r) => r.json()),
   },
 };
 
@@ -129,19 +137,19 @@ export default UserModel;
 
 #### Store API Quick Reference
 
-| Method | Purpose |
-|---|---|
-| `store(Model)` | Descriptor — binds model to a component property |
-| `store.get(Model, id)` | Get a cached instance (triggers fetch if needed) |
-| `store.set(model, values)` | Update (async, returns Promise) |
-| `store.sync(model, values)` | Update (sync, immediate) |
-| `store.pending(model)` | `false` or `Promise` while loading |
-| `store.ready(model)` | `true` when loaded and valid |
-| `store.error(model)` | `false` or `Error` |
-| `store.clear(Model)` | Invalidate singular model cache |
-| `store.clear([Model])` | Invalidate list cache — **required for list stores** |
-| `store.submit(draft)` | Submit draft mode changes |
-| `store.resolve(Model, id)` | Returns Promise that resolves when ready |
+| Method                      | Purpose                                              |
+| --------------------------- | ---------------------------------------------------- |
+| `store(Model)`              | Descriptor — binds model to a component property     |
+| `store.get(Model, id)`      | Get a cached instance (triggers fetch if needed)     |
+| `store.set(model, values)`  | Update (async, returns Promise)                      |
+| `store.sync(model, values)` | Update (sync, immediate)                             |
+| `store.pending(model)`      | `false` or `Promise` while loading                   |
+| `store.ready(model)`        | `true` when loaded and valid                         |
+| `store.error(model)`        | `false` or `Error`                                   |
+| `store.clear(Model)`        | Invalidate singular model cache                      |
+| `store.clear([Model])`      | Invalidate list cache — **required for list stores** |
+| `store.submit(draft)`       | Submit draft mode changes                            |
+| `store.resolve(Model, id)`  | Returns Promise that resolves when ready             |
 
 #### Decision Tree: Local vs Shared State
 
@@ -161,13 +169,12 @@ clear triggers re-fetch). Always guard property access on list items:
 
 ```javascript
 // ❌ BAD — task may be pending, accessing .title throws
-tasks.map((task) => html`<span>${task.title}</span>`)
+tasks.map((task) => html`<span>${task.title}</span>`);
 
 // ✅ GOOD — guard each item, show fallback for pending items
-tasks.map((task) => store.ready(task)
-  ? html`<span>${task.title}</span>`
-  : html`<span class="spinner"></span>`
-)
+tasks.map((task) =>
+  store.ready(task) ? html`<span>${task.title}</span>` : html`<span class="spinner"></span>`,
+);
 ```
 
 This is especially important after batch operations (e.g. drag reorder)
@@ -189,11 +196,7 @@ import HomeView from '../pages/home/index.js';
 export default define({
   tag: 'app-router',
   stack: router(HomeView, { url: '/' }),
-  render: ({ stack }) => html`
-    <template layout="column height::100vh">
-      ${stack}
-    </template>
-  `,
+  render: ({ stack }) => html` <template layout="column height::100vh"> ${stack} </template> `,
 });
 ```
 
@@ -222,14 +225,14 @@ export default define({
 
 ### Routing Patterns
 
-| Pattern | Code |
-|---|---|
-| Navigate to view | `<a href="${router.url(View)}">` |
-| Navigate with params | `router.url(View, { id: '42' })` |
-| Back button | `<a href="${router.backUrl()}">Back</a>` |
-| Check active view | `router.active(View)` |
-| Guarded route | `guard: () => isAuthenticated()` |
-| Dialog overlay | `dialog: true` on the view config |
+| Pattern              | Code                                     |
+| -------------------- | ---------------------------------------- |
+| Navigate to view     | `<a href="${router.url(View)}">`         |
+| Navigate with params | `router.url(View, { id: '42' })`         |
+| Back button          | `<a href="${router.backUrl()}">Back</a>` |
+| Check active view    | `router.active(View)`                    |
+| Guarded route        | `guard: () => isAuthenticated()`         |
+| Dialog overlay       | `dialog: true` on the view config        |
 
 ---
 
@@ -253,12 +256,12 @@ DOM
 
 ### AppState vs Entity Models
 
-| Concern | Where |
-|---|---|
-| Theme, sidebar, UI flags | `AppState` (singleton) |
+| Concern                   | Where                                 |
+| ------------------------- | ------------------------------------- |
+| Theme, sidebar, UI flags  | `AppState` (singleton)                |
 | User records, posts, etc. | `UserModel`, `PostModel` (enumerable) |
-| Form draft state | `store(Model, { draft: true })` |
-| Route state | `router()` — managed by hybrids |
+| Form draft state          | `store(Model, { draft: true })`       |
+| Route state               | `router()` — managed by hybrids       |
 
 ---
 
@@ -280,7 +283,7 @@ export function connectRealtime(url, modelMap) {
   source.addEventListener('update', (event) => {
     const { type } = JSON.parse(event.data);
     const Model = modelMap[type];
-    if (Model) store.clear(Model);  // full clear triggers re-fetch
+    if (Model) store.clear(Model); // full clear triggers re-fetch
   });
 
   source.addEventListener('error', () => {
@@ -326,9 +329,7 @@ export default define({
       return disconnect;
     },
   },
-  render: ({ stack }) => html`
-    <template layout="column height::100vh">${stack}</template>
-  `,
+  render: ({ stack }) => html` <template layout="column height::100vh">${stack}</template> `,
 });
 ```
 
@@ -354,7 +355,7 @@ source.addEventListener('update', (event) => {
   const { type } = JSON.parse(event.data);
   clearTimeout(timers[type]);
   timers[type] = setTimeout(() => {
-    store.clear([Model]);  // one clear after the batch settles
+    store.clear([Model]); // one clear after the batch settles
   }, 300);
 });
 ```

package/docs/TESTING.md

@@ -1,4 +1,5 @@
 # Testing
+
 ## Philosophy, Tools & Patterns
 
 > How we test in a no-build web component project.
@@ -17,15 +18,15 @@ bugs at the boundary where they're introduced, not 5 layers up.
 
 ### Core Principles
 
-| Principle | Rule |
-|---|---|
-| Test at the right level | Pure logic → unit. Components → browser. API → integration. |
-| No mocking the framework | Don't mock `html`, `store`, or `define`. Test through them. |
-| Real browser for components | Web components need a real DOM. No jsdom, no happy-dom. |
-| Zero build for tests | Test files are ES modules, same as app code. |
-| Small test files | Same 150-line rule applies to test files. |
-| Test behavior, not implementation | Assert what the user sees, not internal state shape. |
-| Co-locate tests | Tests live next to the code they test. |
+| Principle                         | Rule                                                        |
+| --------------------------------- | ----------------------------------------------------------- |
+| Test at the right level           | Pure logic → unit. Components → browser. API → integration. |
+| No mocking the framework          | Don't mock `html`, `store`, or `define`. Test through them. |
+| Real browser for components       | Web components need a real DOM. No jsdom, no happy-dom.     |
+| Zero build for tests              | Test files are ES modules, same as app code.                |
+| Small test files                  | Same 150-line rule applies to test files.                   |
+| Test behavior, not implementation | Assert what the user sees, not internal state shape.        |
+| Co-locate tests                   | Tests live next to the code they test.                      |
 
 ---
 
@@ -33,10 +34,10 @@ bugs at the boundary where they're introduced, not 5 layers up.
 
 ### Two Test Runners, Clear Boundaries
 
-| Tool | Tests | Runs in |
-|---|---|---|
-| `node:test` (built-in) | Server, utils, store model shapes | Node.js |
-| `@web/test-runner` | Components, pages, browser integration | Real Chromium |
+| Tool                   | Tests                                  | Runs in       |
+| ---------------------- | -------------------------------------- | ------------- |
+| `node:test` (built-in) | Server, utils, store model shapes      | Node.js       |
+| `@web/test-runner`     | Components, pages, browser integration | Real Chromium |
 
 No other test frameworks. No Jest, no Mocha, no Jasmine.
 
@@ -77,24 +78,24 @@ server.test.js                  ← node:test
 
 ### Test File Naming
 
-| Code file | Test file |
-|---|---|
+| Code file       | Test file            |
+| --------------- | -------------------- |
 | `app-button.js` | `app-button.test.js` |
 | `formatDate.js` | `formatDate.test.js` |
-| `UserModel.js` | `UserModel.test.js` |
-| `src/server.js` | `server.test.js` |
+| `UserModel.js`  | `UserModel.test.js`  |
+| `src/server.js` | `server.test.js`     |
 
 ### What Gets Tested
 
-| Layer | What to assert |
-|---|---|
-| **Utils** | Input → output. Edge cases. |
+| Layer            | What to assert                                                            |
+| ---------------- | ------------------------------------------------------------------------- |
+| **Utils**        | Input → output. Edge cases.                                               |
 | **Store models** | Shape is correct. Computed fields work. Storage connector URLs are right. |
-| **Atoms** | Renders correct HTML. Props reflect to attributes. Events fire. |
-| **Molecules** | Child atoms are present. Composed behavior works. |
-| **Organisms** | Store integration. Data flows to children. |
-| **Server API** | CRUD responses. Schema endpoint. Status codes. |
-| **Pages** | Don't unit-test pages. Test via manual or E2E if needed. |
+| **Atoms**        | Renders correct HTML. Props reflect to attributes. Events fire.           |
+| **Molecules**    | Child atoms are present. Composed behavior works.                         |
+| **Organisms**    | Store integration. Data flows to children.                                |
+| **Server API**   | CRUD responses. Schema endpoint. Status codes.                            |
+| **Pages**        | Don't unit-test pages. Test via manual or E2E if needed.                  |
 
 ---
 
@@ -191,7 +192,9 @@ describe('app-button', () => {
   it('dispatches click event', async () => {
     const el = await fixture(html`<app-button label="Go"></app-button>`);
     let clicked = false;
-    el.addEventListener('click', () => { clicked = true; });
+    el.addEventListener('click', () => {
+      clicked = true;
+    });
     el.shadowRoot.querySelector('button').click();
     expect(clicked).to.be.true;
   });
@@ -230,9 +233,7 @@ import { playwrightLauncher } from '@web/test-runner-playwright';
 export default {
   files: 'src/components/**/*.test.js',
   nodeResolve: true,
-  browsers: [
-    playwrightLauncher({ product: 'chromium' }),
-  ],
+  browsers: [playwrightLauncher({ product: 'chromium' })],
 };
 ```
 
@@ -255,14 +256,14 @@ export default {
 
 Each implementation phase must pass its tests before proceeding:
 
-| Phase | Implement | Then test |
-|---|---|---|
-| 1. Infrastructure | server, vendor script, index.html | Server starts, routes respond, vendor files exist |
-| 2. Store + Utils | models, formatDate, realtimeSync | Model shapes, util outputs, localStorage round-trip |
-| 3. Atoms | app-button, app-badge, app-icon | Render, props, events |
-| 4. Molecules | task-card, project-card | Composition, slot content |
-| 5. Organisms | task-list, project-header | Store binding, data rendering |
-| 6. Pages + Router | views, app-router | Navigation, full page render |
+| Phase             | Implement                         | Then test                                           |
+| ----------------- | --------------------------------- | --------------------------------------------------- |
+| 1. Infrastructure | server, vendor script, index.html | Server starts, routes respond, vendor files exist   |
+| 2. Store + Utils  | models, formatDate, realtimeSync  | Model shapes, util outputs, localStorage round-trip |
+| 3. Atoms          | app-button, app-badge, app-icon   | Render, props, events                               |
+| 4. Molecules      | task-card, project-card           | Composition, slot content                           |
+| 5. Organisms      | task-list, project-header         | Store binding, data rendering                       |
+| 6. Pages + Router | views, app-router                 | Navigation, full page render                        |
 
 **Rule: never skip a checkpoint.** If phase 3 tests fail, fix before
 starting phase 4. Bugs compound; catch them at the boundary.

package/docs/app-spec/ENTITIES.md

@@ -4,27 +4,27 @@
 
 The top-level organizational unit.
 
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| id | string (uuid) | auto | Read-only, generated on create |
-| name | string | yes | 1–200 chars |
-| description | string | no | Max 1000 chars |
-| status | enum | no | `active` (default), `archived` |
-| createdAt | date-time | auto | Read-only |
+| Field       | Type          | Required | Notes                          |
+| ----------- | ------------- | -------- | ------------------------------ |
+| id          | string (uuid) | auto     | Read-only, generated on create |
+| name        | string        | yes      | 1–200 chars                    |
+| description | string        | no       | Max 1000 chars                 |
+| status      | enum          | no       | `active` (default), `archived` |
+| createdAt   | date-time     | auto     | Read-only                      |
 
 ## Task
 
 A work item belonging to a Project.
 
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| id | string (uuid) | auto | Read-only, generated on create |
-| projectId | string (uuid) | yes | Foreign key → Project.id |
-| title | string | yes | 1–200 chars |
-| status | enum | no | `todo` (default), `doing`, `done` |
-| priority | enum | no | `low`, `med` (default), `high` |
-| sortOrder | number | no | Manual ordering within a project |
-| createdAt | date-time | auto | Read-only |
+| Field     | Type          | Required | Notes                             |
+| --------- | ------------- | -------- | --------------------------------- |
+| id        | string (uuid) | auto     | Read-only, generated on create    |
+| projectId | string (uuid) | yes      | Foreign key → Project.id          |
+| title     | string        | yes      | 1–200 chars                       |
+| status    | enum          | no       | `todo` (default), `doing`, `done` |
+| priority  | enum          | no       | `low`, `med` (default), `high`    |
+| sortOrder | number        | no       | Manual ordering within a project  |
+| createdAt | date-time     | auto     | Read-only                         |
 
 ## Relationships
 

package/docs/app-spec/README.md

@@ -11,9 +11,9 @@ all served as raw ES modules with zero build tools.
 
 ## Features
 
-| Feature | Entities | Patterns Exercised |
-|---|---|---|
-| Project management | Project | CRUD, schema discovery, validation, SSE sync |
-| Task tracking | Task | Filtered lists, drag reorder, status enums |
+| Feature            | Entities | Patterns Exercised                           |
+| ------------------ | -------- | -------------------------------------------- |
+| Project management | Project  | CRUD, schema discovery, validation, SSE sync |
+| Task tracking      | Task     | Filtered lists, drag reorder, status enums   |
 
 See [ENTITIES.md](./ENTITIES.md) for field definitions and relationships.

package/lib/check.js

@@ -47,8 +47,10 @@ export async function check(projectDir, scope) {
   const results = [
     checkFiles(projectDir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`),
     checkFiles(projectDir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`),
-    runCmd('ESLint', 'npx eslint --config .configs/eslint.config.js .', projectDir),
+    runCmd('ESLint', 'npx eslint --config .configs/eslint.config.js . --fix', projectDir),
+    runCmd('Stylelint', 'npx stylelint --config .configs/.stylelintrc.json "src/**/*.css" --fix', projectDir),
     runCmd('Prettier', 'npx prettier --config .configs/.prettierrc --check src', projectDir),
+    runCmd('Markdown', 'npx markdownlint-cli2 --config .configs/.markdownlint.jsonc --fix "docs/**/*.md" "*.md"', projectDir),
     runCmd('JSDoc types', 'npx tsc --project .configs/jsconfig.json', projectDir),
   ];
 

package/lib/package-gen.js

@@ -43,8 +43,11 @@ export async function writePackageJson(dest, vars, existing) {
     eslint: '^10.1.0',
     'eslint-config-prettier': '^10.1.8',
     'eslint-plugin-jsdoc': '^62.8.1',
+    'markdownlint-cli2': '^0.22.0',
     playwright: '^1.50.0',
     prettier: '^3.8.1',
+    stylelint: '^17.6.0',
+    'stylelint-config-standard': '^40.0.0',
     typescript: '^6.0.2',
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.2.8",
+  "version": "0.2.18",
   "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@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - 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