@techninja/clearstack 0.2.16 → 0.2.19

package/docs/CONVENTIONS.md

@@ -1,4 +1,5 @@
 # Conventions
+
 ## Naming Rules & Anti-Patterns
 
 > Quick reference for naming and what to avoid.
@@ -13,37 +14,37 @@
 
 All custom element tags use **kebab-case** with an `app-` prefix:
 
-| Thing | Name | Tag |
-|---|---|---|
-| Button atom | `app-button` | `<app-button>` |
-| Header organism | `app-header` | `<app-header>` |
+| Thing                | Name          | Tag             |
+| -------------------- | ------------- | --------------- |
+| Button atom          | `app-button`  | `<app-button>`  |
+| Header organism      | `app-header`  | `<app-header>`  |
 | Page layout template | `page-layout` | `<page-layout>` |
-| Home page view | `home-view` | `<home-view>` |
+| Home page view       | `home-view`   | `<home-view>`   |
 
 The `app-` prefix prevents collisions with native elements and third-party
 components. Page views and templates may drop the prefix when unambiguous.
 
 ### Files & Directories
 
-| Type | Convention | Example |
-|---|---|---|
-| Component file | Match tag name | `app-button.js` |
-| Component CSS | Match tag name | `app-button.css` |
-| Component dir | Match tag name | `app-button/` |
-| Re-export | Always `index.js` | `index.js` |
-| Store model | PascalCase | `UserModel.js` |
-| Utility function | camelCase | `formatDate.js` |
-| Shared CSS | Descriptive kebab | `tokens.css`, `reset.css` |
+| Type             | Convention        | Example                   |
+| ---------------- | ----------------- | ------------------------- |
+| Component file   | Match tag name    | `app-button.js`           |
+| Component CSS    | Match tag name    | `app-button.css`          |
+| Component dir    | Match tag name    | `app-button/`             |
+| Re-export        | Always `index.js` | `index.js`                |
+| Store model      | PascalCase        | `UserModel.js`            |
+| Utility function | camelCase         | `formatDate.js`           |
+| Shared CSS       | Descriptive kebab | `tokens.css`, `reset.css` |
 
 ### JavaScript
 
-| Type | Convention | Example |
-|---|---|---|
-| Event handlers | `handle` + action | `handleClick`, `handleSubmit` |
-| Store models | PascalCase noun | `UserModel`, `AppState` |
-| Utility functions | camelCase verb | `formatDate`, `parseQuery` |
-| Constants | UPPER_SNAKE | `MAX_RETRIES`, `API_BASE` |
-| JSDoc typedefs | PascalCase | `@typedef {Object} User` |
+| Type              | Convention        | Example                       |
+| ----------------- | ----------------- | ----------------------------- |
+| Event handlers    | `handle` + action | `handleClick`, `handleSubmit` |
+| Store models      | PascalCase noun   | `UserModel`, `AppState`       |
+| Utility functions | camelCase verb    | `formatDate`, `parseQuery`    |
+| Constants         | UPPER_SNAKE       | `MAX_RETRIES`, `API_BASE`     |
+| JSDoc typedefs    | PascalCase        | `@typedef {Object} User`      |
 
 ---
 
@@ -52,12 +53,14 @@ components. Page views and templates may drop the prefix when unambiguous.
 ### ❌ Never Do This
 
 **DOM queries inside components:**
+
 ```javascript
 // BAD — breaks encapsulation, ignores shadow DOM
 const el = document.querySelector('.my-thing');
 ```
 
 **Manual event listeners:**
+
 ```javascript
 // BAD — leaks memory, bypasses hybrids lifecycle
 connectedCallback() {
@@ -66,18 +69,21 @@ connectedCallback() {
 ```
 
 **Global mutable state:**
+
 ```javascript
 // BAD — invisible dependencies, untraceable bugs
 window.appState = { user: null };
 ```
 
 **Imperative DOM manipulation:**
+
 ```javascript
 // BAD — fights the reactive render cycle
 host.shadowRoot.querySelector('span').textContent = 'updated';
 ```
 
 **Business logic in render:**
+
 ```javascript
 // BAD — render should be pure projection of state
 render: ({ items }) => html`
@@ -86,11 +92,13 @@ render: ({ items }) => html`
 ```
 
 **Files over 150 lines:**
+
 ```
 // BAD — extract to utils/ or split into sub-components
 ```
 
 **Deep nesting (>3 component levels):**
+
 ```
 // BAD — flatten by composing at the page level
 <app-layout>
@@ -109,14 +117,14 @@ let everything else propagate.
 
 ### Boundary Rules
 
-| Layer | Responsibility | Example |
-|---|---|---|
-| **Utils** | Never catch. Return error values or throw. Caller decides. | `formatDate(null)` returns `''` |
-| **Store connectors** | Let fetch failures propagate. Hybrids' `store.error()` catches them. | Don't wrap fetch in try/catch |
-| **Components** | Display `store.pending()` / `store.error()` states. Never try/catch in render. | `${store.error(model) && html`<div class="error-message">...</div>`}` |
-| **Event handlers** | Guard with `store.ready()` before accessing store properties. | `if (!store.ready(host.state)) return;` |
-| **Server routes** | Return HTTP status + JSON error body. Never crash the process. | `res.status(404).json({ error: 'Not found' })` |
-| **Server infra** | Handle process-level errors with clear messages and exit codes. | Port conflict → log message → `process.exit(1)` |
+| Layer                | Responsibility                                                                 | Example                                                               |
+| -------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| **Utils**            | Never catch. Return error values or throw. Caller decides.                     | `formatDate(null)` returns `''`                                       |
+| **Store connectors** | Let fetch failures propagate. Hybrids' `store.error()` catches them.           | Don't wrap fetch in try/catch                                         |
+| **Components**       | Display `store.pending()` / `store.error()` states. Never try/catch in render. | `${store.error(model) && html`<div class="error-message">...</div>`}` |
+| **Event handlers**   | Guard with `store.ready()` before accessing store properties.                  | `if (!store.ready(host.state)) return;`                               |
+| **Server routes**    | Return HTTP status + JSON error body. Never crash the process.                 | `res.status(404).json({ error: 'Not found' })`                        |
+| **Server infra**     | Handle process-level errors with clear messages and exit codes.                | Port conflict → log message → `process.exit(1)`                       |
 
 ### Why This Matters
 
@@ -141,7 +149,7 @@ next layer up to handle what it can't.
 // BAD — accesses store properties without ready guard
 function toggle(host) {
   const next = host.state.theme === 'light' ? 'dark' : 'light';
-  store.set(host.state, { theme: next });  // crashes if model is in error state
+  store.set(host.state, { theme: next }); // crashes if model is in error state
 }
 ```
 
@@ -168,16 +176,19 @@ function toggle(host) {
 ### ✅ Always Do This
 
 **Declarative event binding:**
+
 ```javascript
-html`<button onclick="${handleClick}">Go</button>`
+html`<button onclick="${handleClick}">Go</button>`;
 ```
 
 **Store for shared state:**
+
 ```javascript
 state: store(AppState),
 ```
 
 **Pure functions for logic:**
+
 ```javascript
 // In src/utils/filterActive.js
 export const filterActive = (items) => items.filter(i => i.active);
@@ -188,6 +199,7 @@ render: ({ items }) => html`<ul>${filterActive(items).map(...)}</ul>`,
 ```
 
 **JSDoc on all exports:**
+
 ```javascript
 /** @param {User} user */
 export const fullName = (user) => `${user.firstName} ${user.lastName}`;

package/docs/FRONTEND_IMPLEMENTATION_RULES.md

@@ -1,4 +1,5 @@
 # Frontend Implementation Rules
+
 ## Hybrids.js "No-Build" Web Component Specification
 
 > A concise, LLM-and-human-friendly specification for building web applications
@@ -17,15 +18,15 @@
 
 **Sub-specifications:**
 
-| Document | Covers |
-|---|---|
-| [COMPONENT_PATTERNS.md](./COMPONENT_PATTERNS.md) | Authoring, light DOM, styling, layout engine, file size rules |
-| [JSDOC_TYPING.md](./JSDOC_TYPING.md) | JSDoc typing strategy, tsc validation, component/model/handler patterns |
-| [STATE_AND_ROUTING.md](./STATE_AND_ROUTING.md) | Store, routing, unified app state, realtime sync |
-| [CONVENTIONS.md](./CONVENTIONS.md) | Naming conventions, anti-patterns |
-| [SERVER_AND_DEPS.md](./SERVER_AND_DEPS.md) | Express server, import maps, vendor dependency loading |
-| [BACKEND_API_SPEC.md](./BACKEND_API_SPEC.md) | REST endpoints, JSON Schema via HEAD, entity CRUD, realtime sync |
-| [TESTING.md](./TESTING.md) | Testing philosophy, tools, patterns, build-phase checkpoints |
+| Document                                         | Covers                                                                  |
+| ------------------------------------------------ | ----------------------------------------------------------------------- |
+| [COMPONENT_PATTERNS.md](./COMPONENT_PATTERNS.md) | Authoring, light DOM, styling, layout engine, file size rules           |
+| [JSDOC_TYPING.md](./JSDOC_TYPING.md)             | JSDoc typing strategy, tsc validation, component/model/handler patterns |
+| [STATE_AND_ROUTING.md](./STATE_AND_ROUTING.md)   | Store, routing, unified app state, realtime sync                        |
+| [CONVENTIONS.md](./CONVENTIONS.md)               | Naming conventions, anti-patterns                                       |
+| [SERVER_AND_DEPS.md](./SERVER_AND_DEPS.md)       | Express server, import maps, vendor dependency loading                  |
+| [BACKEND_API_SPEC.md](./BACKEND_API_SPEC.md)     | REST endpoints, JSON Schema via HEAD, entity CRUD, realtime sync        |
+| [TESTING.md](./TESTING.md)                       | Testing philosophy, tools, patterns, build-phase checkpoints            |
 
 ---
 
@@ -36,16 +37,16 @@ no transpiler, no compile step. Code runs exactly as written.
 
 ### Core Principles
 
-| Principle | Rule |
-|---|---|
-| No build tools | No Webpack, Vite, Rollup, esbuild, or Babel |
-| ES modules only | All `.js` files are native ES modules served to the browser |
-| Import maps | Bare specifiers (e.g. `"hybrids"`) resolved via `<script type="importmap">` |
-| Small files | Every file ≤ **150 lines** before extracting shared logic |
-| Explicit over implicit | Name things clearly; avoid magic strings and hidden conventions |
-| Readable over clever | Optimize for comprehension by humans and LLMs alike |
-| Declarative over imperative | Use framework patterns, not raw DOM manipulation |
-| Composition over inheritance | Build complex UIs by composing small components |
+| Principle                    | Rule                                                                        |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| No build tools               | No Webpack, Vite, Rollup, esbuild, or Babel                                 |
+| ES modules only              | All `.js` files are native ES modules served to the browser                 |
+| Import maps                  | Bare specifiers (e.g. `"hybrids"`) resolved via `<script type="importmap">` |
+| Small files                  | Every file ≤ **150 lines** before extracting shared logic                   |
+| Explicit over implicit       | Name things clearly; avoid magic strings and hidden conventions             |
+| Readable over clever         | Optimize for comprehension by humans and LLMs alike                         |
+| Declarative over imperative  | Use framework patterns, not raw DOM manipulation                            |
+| Composition over inheritance | Build complex UIs by composing small components                             |
 
 ### What This Means in Practice
 
@@ -72,15 +73,15 @@ web component framework built on plain objects and pure functions.
 
 ### Why Hybrids
 
-| Need | Hybrids Provides |
-|---|---|
-| Components | `define()` — plain object definitions, no classes |
-| Templating | `html``` — tagged template literals with reactive bindings |
-| State | `store()` — global state with async storage, caching, relations |
-| Routing | `router()` — view-graph-based routing with guards and dialogs |
-| Layout | `layout=""` attribute — CSS layout engine in templates |
-| Localization | `localize()` — automatic template translation |
-| ES modules | Ships as raw ES modules in `src/` — no build needed |
+| Need         | Hybrids Provides                                                |
+| ------------ | --------------------------------------------------------------- |
+| Components   | `define()` — plain object definitions, no classes               |
+| Templating   | `html``` — tagged template literals with reactive bindings      |
+| State        | `store()` — global state with async storage, caching, relations |
+| Routing      | `router()` — view-graph-based routing with guards and dialogs   |
+| Layout       | `layout=""` attribute — CSS layout engine in templates          |
+| Localization | `localize()` — automatic template translation                   |
+| ES modules   | Ships as raw ES modules in `src/` — no build needed             |
 
 ### API Surface (v9.1)
 
@@ -88,27 +89,27 @@ These are the only imports you need:
 
 ```javascript
 import {
-  define,       // Register a component
-  html,         // Template tagged literal
-  store,        // State management
-  router,       // Routing
-  mount,        // Mount component on existing element
-  parent,       // Access parent component
-  children,     // Access child components
-  dispatch,     // Dispatch custom events
-  msg,          // Localization messages
-  localize,     // Register translations
+  define, // Register a component
+  html, // Template tagged literal
+  store, // State management
+  router, // Routing
+  mount, // Mount component on existing element
+  parent, // Access parent component
+  children, // Access child components
+  dispatch, // Dispatch custom events
+  msg, // Localization messages
+  localize, // Register translations
 } from 'hybrids';
 ```
 
 ### Why Not Alternatives
 
-| Alternative | Reason to pass |
-|---|---|
-| **Lit** | Class-based, heavier API surface, decorators encourage build tools |
-| **Stencil** | Requires a compiler — violates no-build constraint |
-| **Vanilla** | No state management, no templating — too much boilerplate |
-| **React/Vue/Svelte** | Require build steps, not native web components |
+| Alternative          | Reason to pass                                                     |
+| -------------------- | ------------------------------------------------------------------ |
+| **Lit**              | Class-based, heavier API surface, decorators encourage build tools |
+| **Stencil**          | Requires a compiler — violates no-build constraint                 |
+| **Vanilla**          | No state management, no templating — too much boilerplate          |
+| **React/Vue/Svelte** | Require build steps, not native web components                     |
 
 ---
 
@@ -185,12 +186,12 @@ import direction: **higher tiers import from lower tiers, never the reverse.**
 
 ### Tiers
 
-| Tier | Location | Scope | Examples |
-|---|---|---|---|
-| **Atom** | `components/atoms/` | Single-purpose UI primitive. One element, one job. | `app-button`, `app-icon`, `app-input` |
-| **Molecule** | `components/molecules/` | Small composition of 2–4 atoms that form a reusable unit. | `nav-link`, `search-bar`, `form-field` |
+| Tier         | Location                | Scope                                                              | Examples                                |
+| ------------ | ----------------------- | ------------------------------------------------------------------ | --------------------------------------- |
+| **Atom**     | `components/atoms/`     | Single-purpose UI primitive. One element, one job.                 | `app-button`, `app-icon`, `app-input`   |
+| **Molecule** | `components/molecules/` | Small composition of 2–4 atoms that form a reusable unit.          | `nav-link`, `search-bar`, `form-field`  |
 | **Organism** | `components/organisms/` | Complex UI section. May contain molecules, atoms, and local state. | `app-header`, `app-footer`, `user-card` |
-| **Template** | `components/templates/` | Page-level layout shell. Defines slot regions, no business logic. | `page-layout`, `dashboard-layout` |
+| **Template** | `components/templates/` | Page-level layout shell. Defines slot regions, no business logic.  | `page-layout`, `dashboard-layout`       |
 
 **Pages** (`src/pages/`) sit outside the component hierarchy. They are
 route-bound views that compose templates and organisms.
@@ -214,13 +215,13 @@ Pages → Templates → Organisms → Molecules → Atoms
 
 Use this checklist to decide if a component belongs at a higher tier:
 
-| Signal | Action |
-|---|---|
-| It renders a single HTML element with props | Keep as **atom** |
-| It composes 2–4 atoms into a reusable group | Make it a **molecule** |
-| It has its own local state or fetches data | Promote to **organism** |
-| It defines layout regions via slots, no logic | Make it a **template** |
-| It's bound to a route and composes a full page | Put it in **pages/** |
+| Signal                                         | Action                  |
+| ---------------------------------------------- | ----------------------- |
+| It renders a single HTML element with props    | Keep as **atom**        |
+| It composes 2–4 atoms into a reusable group    | Make it a **molecule**  |
+| It has its own local state or fetches data     | Promote to **organism** |
+| It defines layout regions via slots, no logic  | Make it a **template**  |
+| It's bound to a route and composes a full page | Put it in **pages/**    |
 
 ### File Anatomy (All Tiers)
 
@@ -235,5 +236,3 @@ app-button/
 
 If a component needs helpers that push it past 150 lines, extract them to
 `src/utils/` — not into sibling files within the component directory.
-
-

package/docs/JSDOC_TYPING.md

@@ -1,4 +1,5 @@
 # JSDoc Typing Strategy
+
 ## Type Safety Without TypeScript
 
 > JSDoc annotations provide editor intellisense, LLM comprehension, and

package/docs/QUICKSTART.md

@@ -28,12 +28,12 @@ npx clearstack init -y     # non-interactive (defaults)
 
 The interactive prompt asks for:
 
-| Prompt | Default | Notes |
-|---|---|---|
-| Project name | current directory name | Used in package.json and templates |
-| Description | `A Clearstack project` | Goes into package.json |
-| Mode | — | **Fullstack**: Express + WebSocket + JSON DB + SSE. **Static**: localStorage only |
-| Port | `3000` | Fullstack only. Set in `.env` |
+| Prompt       | Default                | Notes                                                                             |
+| ------------ | ---------------------- | --------------------------------------------------------------------------------- |
+| Project name | current directory name | Used in package.json and templates                                                |
+| Description  | `A Clearstack project` | Goes into package.json                                                            |
+| Mode         | —                      | **Fullstack**: Express + WebSocket + JSON DB + SSE. **Static**: localStorage only |
+| Port         | `3000`                 | Fullstack only. Set in `.env`                                                     |
 
 If a `package.json` already exists, Clearstack merges into it — your existing fields (`author`, `license`, `engines`, `keywords`, etc.) are preserved.
 
@@ -120,10 +120,12 @@ git diff docs/ .configs/            # review what changed
 ```
 
 This updates:
+
 - `docs/clearstack/*.md` — spec documentation
 - `.configs/*` — linter, formatter, type checker, test runner configs
 
 This never touches:
+
 - `docs/app-spec/` — your project specs
 - `src/` — your code
 - `scripts/` — your build scripts
@@ -163,15 +165,15 @@ spec:code → spec:docs → lint → format → typecheck → test
 
 ## Summary
 
-| Task | Command |
-|---|---|
-| Install Clearstack | `npm install -D @techninja/clearstack` |
-| Scaffold a project | `npx clearstack init` |
-| Install dependencies | `npm install` |
-| Start dev server | `npm run dev` / `npx serve public` |
-| Lint + format | `npm run lint:fix && npm run format` |
-| Type check | `npm run typecheck` |
-| Run tests | `npm test` |
-| Full spec check | `npm run spec` |
-| Update spec + configs | `npm run spec:update` |
-| Review spec changes | `git diff docs/ .configs/` |
+| Task                  | Command                                |
+| --------------------- | -------------------------------------- |
+| Install Clearstack    | `npm install -D @techninja/clearstack` |
+| Scaffold a project    | `npx clearstack init`                  |
+| Install dependencies  | `npm install`                          |
+| Start dev server      | `npm run dev` / `npx serve public`     |
+| Lint + format         | `npm run lint:fix && npm run format`   |
+| Type check            | `npm run typecheck`                    |
+| Run tests             | `npm test`                             |
+| Full spec check       | `npm run spec`                         |
+| Update spec + configs | `npm run spec:update`                  |
+| Review spec changes   | `git diff docs/ .configs/`             |

package/docs/SERVER_AND_DEPS.md

@@ -1,4 +1,5 @@
 # Server & Dependencies
+
 ## Express Server, Import Maps & Vendor Loading
 
 > How the backend serves the frontend and how dependencies are resolved
@@ -13,13 +14,13 @@
 
 ### Responsibilities
 
-| Route | Serves |
-|---|---|
-| `/` | `public/index.html` (app shell) |
-| `/vendor/*` | `public/vendor/` (vendored ES modules) |
-| `/src/*` | `src/` (application source, as-is) |
-| `/api/*` | REST endpoints (see BACKEND_API_SPEC) |
-| `/api/events` | SSE stream for realtime sync |
+| Route         | Serves                                 |
+| ------------- | -------------------------------------- |
+| `/`           | `public/index.html` (app shell)        |
+| `/vendor/*`   | `public/vendor/` (vendored ES modules) |
+| `/src/*`      | `src/` (application source, as-is)     |
+| `/api/*`      | REST endpoints (see BACKEND_API_SPEC)  |
+| `/api/events` | SSE stream for realtime sync           |
 
 ### Key Rules
 
@@ -65,9 +66,7 @@ import { cpSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 const VENDOR_DIR = resolve('public/vendor');
-const DEPS = [
-  { name: 'hybrids', src: 'node_modules/hybrids/src' },
-];
+const DEPS = [{ name: 'hybrids', src: 'node_modules/hybrids/src' }];
 
 mkdirSync(VENDOR_DIR, { recursive: true });
 
@@ -112,25 +111,25 @@ declared in `public/index.html`.
 ```html
 <!DOCTYPE html>
 <html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>App</title>
-  <link rel="stylesheet" href="/src/styles/reset.css">
-  <link rel="stylesheet" href="/src/styles/tokens.css">
-
-  <script type="importmap">
-  {
-    "imports": {
-      "hybrids": "/vendor/hybrids/index.js"
-    }
-  }
-  </script>
-</head>
-<body>
-  <app-router></app-router>
-  <script type="module" src="/src/router/index.js"></script>
-</body>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>App</title>
+    <link rel="stylesheet" href="/src/styles/reset.css" />
+    <link rel="stylesheet" href="/src/styles/tokens.css" />
+
+    <script type="importmap">
+      {
+        "imports": {
+          "hybrids": "/vendor/hybrids/index.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <app-router></app-router>
+    <script type="module" src="/src/router/index.js"></script>
+  </body>
 </html>
 ```