@techninja/clearstack 0.2.16 → 0.2.19

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

@@ -1,4 +1,5 @@
 # Component Patterns
+
 ## Authoring, Styling, Templates & JSDoc Typing
 
 > How to write, style, and type components in this framework.
@@ -33,13 +34,13 @@ See the Light DOM section below for why.
 
 Properties are declared as default values. Hybrids infers the type:
 
-| Declaration | Type | Reflected to attribute |
-|---|---|---|
-| `count: 0` | Number | Yes |
-| `label: ''` | String | Yes |
-| `active: false` | Boolean | Yes |
-| `items: []` | Array/Object | No |
-| `onClick: () => {}` | Function | No |
+| Declaration         | Type         | Reflected to attribute |
+| ------------------- | ------------ | ---------------------- |
+| `count: 0`          | Number       | Yes                    |
+| `label: ''`         | String       | Yes                    |
+| `active: false`     | Boolean      | Yes                    |
+| `items: []`         | Array/Object | No                     |
+| `onClick: () => {}` | Function     | No                     |
 
 ### Property Descriptors
 
@@ -51,8 +52,10 @@ export default define({
   elapsed: {
     value: 0,
     connect(host, key, invalidate) {
-      const id = setInterval(() => { host.elapsed++; }, 1000);
-      return () => clearInterval(id);  // cleanup on disconnect
+      const id = setInterval(() => {
+        host.elapsed++;
+      }, 1000);
+      return () => clearInterval(id); // cleanup on disconnect
     },
     observe(host, value) {
       if (value >= 60) dispatch(host, 'timeout');
@@ -62,12 +65,12 @@ export default define({
 });
 ```
 
-| Descriptor field | Purpose |
-|---|---|
-| `value` | Default value or factory function |
-| `connect(host, key, invalidate)` | Runs on DOM connect. Return cleanup fn. |
-| `observe(host, value, lastValue)` | Runs when value changes |
-| `reflect` | `true` or `(value) => string` — sync to attribute |
+| Descriptor field                  | Purpose                                           |
+| --------------------------------- | ------------------------------------------------- |
+| `value`                           | Default value or factory function                 |
+| `connect(host, key, invalidate)`  | Runs on DOM connect. Return cleanup fn.           |
+| `observe(host, value, lastValue)` | Runs when value changes                           |
+| `reflect`                         | `true` or `(value) => string` — sync to attribute |
 
 ### Event Handling
 
@@ -81,9 +84,7 @@ function handleClick(host, event) {
 export default define({
   tag: 'app-counter',
   count: 0,
-  render: ({ count }) => html`
-    <button onclick="${handleClick}">Count: ${count}</button>
-  `,
+  render: ({ count }) => html` <button onclick="${handleClick}">Count: ${count}</button> `,
 });
 ```
 
@@ -148,12 +149,12 @@ Custom events from atoms can be unreliable when templates are passed as
 properties through intermediate components (e.g. `page-layout`'s `content`).
 The host context and event bubbling path may not resolve as expected.
 
-| Context | Use | Why |
-|---|---|---|
-| Inside a component's own template | `app-button` | Host context is correct, events bubble normally |
+| Context                              | Use                          | Why                                              |
+| ------------------------------------ | ---------------------------- | ------------------------------------------------ |
+| Inside a component's own template    | `app-button`                 | Host context is correct, events bubble normally  |
 | Inside a `content` template property | Plain `<button class="btn">` | Direct `onclick` handler, no custom event needed |
-| Reusable molecule/organism | `app-button` | Encapsulated, predictable host |
-| Page-level actions | Plain `<button class="btn">` | Simplest, most reliable |
+| Reusable molecule/organism           | `app-button`                 | Encapsulated, predictable host                   |
+| Page-level actions                   | Plain `<button class="btn">` | Simplest, most reliable                          |
 
 The `.btn` classes are global (defined in `buttons.css`), so plain buttons
 look identical to `app-button`. Use the atom when you need its component
@@ -213,11 +214,11 @@ tree. CSS scoping is achieved through **native CSS nesting** on the tag name
 
 Shadow DOM is the exception, not the rule. Enable it only when:
 
-| Situation | Why shadow DOM |
-|---|---|
-| Wrapping a third-party widget | Prevent its styles from leaking out |
+| Situation                           | Why shadow DOM                      |
+| ----------------------------------- | ----------------------------------- |
+| Wrapping a third-party widget       | Prevent its styles from leaking out |
 | Distributing a standalone component | Consumer's styles must not break it |
-| Embedding untrusted content | Hard style boundary needed |
+| Embedding untrusted content         | Hard style boundary needed          |
 
 For an internal application where you control all the CSS, shadow DOM
 creates more problems than it solves — you end up fighting it to inject
@@ -302,11 +303,11 @@ Every component automatically inherits all shared styles. No injection needed.
 
 ### Three Layers of CSS
 
-| Layer | File(s) | What goes here |
-|---|---|---|
-| **Tokens** | `tokens.css` | `:root` custom properties — colors, spacing, type, radii, shadows |
-| **Shared** | `shared.css` | Error states, loading states, icon base, screen-reader utils, transitions |
-| **Components** | `components.css` + per-component `.css` | Styles scoped to tag names via native CSS nesting |
+| Layer          | File(s)                                 | What goes here                                                            |
+| -------------- | --------------------------------------- | ------------------------------------------------------------------------- |
+| **Tokens**     | `tokens.css`                            | `:root` custom properties — colors, spacing, type, radii, shadows         |
+| **Shared**     | `shared.css`                            | Error states, loading states, icon base, screen-reader utils, transitions |
+| **Components** | `components.css` + per-component `.css` | Styles scoped to tag names via native CSS nesting                         |
 
 ### Per-Component CSS with Native Nesting
 
@@ -326,17 +327,22 @@ app-button {
     color: white;
     font: inherit;
 
-    &:hover { background: var(--color-primary-hover); }
-    &:disabled { opacity: 0.5; cursor: not-allowed; }
+    &:hover {
+      background: var(--color-primary-hover);
+    }
+    &:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
   }
 
-  &[variant="secondary"] button {
+  &[variant='secondary'] button {
     background: var(--color-surface);
     color: var(--color-text);
     border: 1px solid var(--color-border);
   }
 
-  &[variant="ghost"] button {
+  &[variant='ghost'] button {
     background: transparent;
     color: var(--color-primary);
   }
@@ -393,7 +399,7 @@ Components reference tokens, never hardcode values.
 All templates use `html` from hybrids:
 
 ```javascript
-html`<div>${expression}</div>`
+html`<div>${expression}</div>`;
 ```
 
 Expressions can be: strings, numbers, booleans, other templates, arrays of
@@ -413,14 +419,14 @@ render: () => html`
 `,
 ```
 
-| Attribute | Effect |
-|---|---|
-| `layout="row"` | Flexbox row |
-| `layout="column"` | Flexbox column |
-| `layout="grid:1\|max"` | CSS grid with defined tracks |
-| `layout="grow"` | `flex-grow: 1` |
-| `layout="center"` | Center content |
-| `layout="gap:2"` | Gap using spacing scale |
+| Attribute               | Effect                         |
+| ----------------------- | ------------------------------ |
+| `layout="row"`          | Flexbox row                    |
+| `layout="column"`       | Flexbox column                 |
+| `layout="grid:1\|max"`  | CSS grid with defined tracks   |
+| `layout="grow"`         | `flex-grow: 1`                 |
+| `layout="center"`       | Center content                 |
+| `layout="gap:2"`        | Gap using spacing scale        |
 | `layout@768px="hidden"` | Responsive — applies at ≥768px |
 
 ### Keyed Lists
@@ -455,12 +461,12 @@ render: ({ dataPromise }) => html`
 
 ### When a file grows too large
 
-| Situation | Action |
-|---|---|
-| Component logic exceeds 150 lines | Extract helpers to `src/utils/` |
-| Template is too complex | Split into child sub-components |
-| CSS exceeds 150 lines | Extract shared patterns to `src/styles/` |
-| Store model has many relations | Split related models into own files |
+| Situation                         | Action                                   |
+| --------------------------------- | ---------------------------------------- |
+| Component logic exceeds 150 lines | Extract helpers to `src/utils/`          |
+| Template is too complex           | Split into child sub-components          |
+| CSS exceeds 150 lines             | Extract shared patterns to `src/styles/` |
+| Store model has many relations    | Split related models into own files      |
 
 ### What counts toward the limit
 

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

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

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