@techninja/clearstack 0.3.16 → 0.3.19

package/docs/BUILD_LOG.md

@@ -204,6 +204,14 @@ These are the significant corrections:
 - **Fix:** Cast params to `any` before accessing custom properties
 - **Documented in:** JSDOC_TYPING.md → `list` Connector Params
 
+### Array model prototype items persist as real data
+
+- **Expected:** `items: [{ sku: '', quantity: 0 }]` only defines the schema
+- **Actual:** The prototype item exists as a real entry in the array at runtime
+- **Impact:** Cart showed a ghost item with empty sku and 0 quantity; Stripe rejected the 0-price line item
+- **Fix:** Always filter array model data with `.filter(i => i.sku)` before use
+- **Documented in:** STATE_AND_ROUTING.md → Store Array Properties
+
 ---
 
 ## Metrics
@@ -250,3 +258,102 @@ These are the significant corrections:
 5. **The spec improves through implementation.** 9 significant corrections were
    made to the spec based on what we learned building the proof. The spec is
    now more accurate than if it had been written in isolation.
+
+---
+
+## StatiCart: Second Project Validation
+
+StatiCart is a full e-commerce platform built on Clearstack — the second
+project built against the spec, validating that the patterns hold beyond
+the original POC. Three phases (catalog, cart, polish) were completed in
+a single LLM session.
+
+### Velocity
+
+| Metric | Value |
+| --- | --- |
+| Phases completed | 3 of 8 |
+| Components created | 7 (2 atoms, 2 molecules, 2 organisms, 0 templates) |
+| Pages created | 5 (catalog, product-detail, cart, order-success, order-cancelled) |
+| Store models | 2 (Product enumerable, CartState singleton) |
+| Utilities | 4 (formatPrice, setPageMeta, productVariants, statusColors) |
+| Tests | 41 (10 node, 31 browser) |
+| Spec checks | 9/9 passing |
+| Files over 150 lines | 0 (2 hit the limit, both split successfully) |
+
+Three phases of a real app in one session. No blocked-on-framework moments.
+Every blocker was a hybrids runtime behavior, not a Clearstack constraint.
+
+### What the 150-Line Limit Actually Did
+
+The limit forced two splits during this build:
+
+1. `shared.css` hit 203 lines after adding page layout styles → split into
+   `pages.css`. Later `pages.css` hit 163 → split into `pages-cart.css`.
+2. `product-detail-view.js` hit 154 after adding the image gallery →
+   extracted `productVariants.js` utility.
+
+Both splits improved the code. The page styles split by concern (catalog
+vs cart) which made each file scannable. The utility extraction made
+`effectivePrice`/`effectiveStock` reusable and independently testable.
+
+Without the limit, these would have stayed as 300-line monoliths. The
+LLM would have needed to re-read them on every edit, and the utility
+functions would never have gotten their own test file.
+
+### What the Spec Documentation Prevented
+
+The Clearstack spec docs prevented several classes of bugs entirely:
+
+- **No `../` imports.** The import map alias rule (`#store/`, `#atoms/`)
+  was enforced from the first file. Zero refactoring of import paths.
+- **`shadow: false` everywhere.** No time wasted on shadow DOM styling
+  issues. Global CSS just worked.
+- **Named event handlers.** No "button doesn't work" debugging from
+  inline arrows in nested templates.
+- **`store.connect.get` returns `{}`.** The localStorage pattern was
+  correct on first write for CartState.
+- **Template functions over template components.** No host context bugs.
+
+### What the Spec Didn't Prevent (New Discoveries)
+
+Five new hybrids gotchas were found and documented:
+
+1. **Empty arrays throw** — `items: []` needs a prototype item
+2. **`id` is reserved in nested models** — even inside array prototypes
+3. **Enumerable models need `@type {any}`** — tsc can't type `id: true`
+4. **List store descriptors need 3 casts** — descriptor, ready(), and map()
+5. **`list` connector params need cast** — `ModelIdentifier` not plain object
+6. **Array prototype items persist as real data** — the prototype item
+   used to define the array shape is included in the actual data
+
+All six are hybrids type system friction, not architectural issues. The
+runtime behavior is correct — it's the JSDoc/tsc layer that struggles.
+Each was fixed in under 2 minutes once identified.
+
+### Test Runner Discovery
+
+`@web/test-runner` doesn't support browser import maps. A custom
+`resolveImport` plugin was needed to map `#prefix/` aliases to absolute
+paths. This is now documented in TESTING.md with the full config pattern.
+
+### Framework Reuse Validation
+
+The Clearstack scaffolder (`npm run spec update`) worked correctly for
+doc syncing. The config overwrite issue (jsconfig.json, eslint.config.js)
+was found and fixed upstream — `update` now skips existing configs unless
+`--force` is passed. This validates the "dependency, not template" model.
+
+### Key Insight
+
+The speed came from **not having to make architectural decisions**. The
+spec answered every "where does this go" question before it was asked:
+store models in `src/store/`, atoms vs molecules vs organisms, CSS in
+per-component files registered in `components.css`, pages in `src/pages/`.
+The LLM never had to ask "how should I structure this?" — it read the
+spec and built.
+
+This is the core value proposition: **Clearstack trades flexibility for
+velocity.** A team (or LLM) that knows the spec can build without
+discussion. The constraints aren't limitations — they're decisions that
+have already been made.

package/docs/CONVENTIONS.md

@@ -197,6 +197,20 @@ function toggle(host) {
 }
 ```
 
+```javascript
+// BAD — silent catch hides the failure completely
+try {
+  store.clear([Model]);
+} catch {
+  /* list may not exist */
+}
+```
+
+**Never use empty `catch` blocks.** If you catch to prevent crashing,
+you must `console.warn` or `console.error` so the failure is visible.
+Silent catches turn bugs into ghosts — things "just don't work" with
+zero console output to trace.
+
 ### ✅ Do
 
 ```javascript
@@ -215,6 +229,15 @@ function toggle(host) {
 }
 ```
 
+```javascript
+// GOOD — catch to prevent crash, but log so failures are visible
+try {
+  store.clear([Model]);
+} catch (e) {
+  console.warn('[store] clear failed:', e.message);
+}
+```
+
 ---
 
 ### ✅ Always Do This
@@ -251,10 +274,24 @@ export const fullName = (user) => `${user.firstName} ${user.lastName}`;
 
 ---
 
-## File Size: Soft Warnings Before Hard Limits
+## File Size: Why 150 Lines
+
+The 150-line limit isn't about the number — it's about **context cost**.
+A 400-line file isn't hard to scroll through, but it's expensive to
+_hold in mind_. Humans can only reason about a limited scope at once.
+LLMs face the same constraint differently: every token spent reading a
+bloated file is a token not spent on the actual task. Small files mean
+context is spent on _building_, not on _understanding what you're
+looking at_.
+
+When every file is small enough to comprehend in one pass, both humans
+and LLMs can generate, review, and modify code without re-reading
+unrelated sections. Refactors become safe because the blast radius of
+any change is one small file. The limit forces decomposition into
+concept-sized units — not arbitrary chunks, but files where each one
+answers a single question.
 
-The 150-line limit is a hard gate in CI, but treat **~120 lines as a yellow
-light.** When a file passes 120 lines:
+Treat **~120 lines as a yellow light.** When a file passes 120 lines:
 
 1. Add a `// SPLIT CANDIDATE:` comment noting where a logical split could happen
 2. Continue working — don't split mid-feature
@@ -270,7 +307,9 @@ function moveObj(o, dx, dy) { ... }
 ### When a File Exceeds 150 Lines
 
 The **only correct response** is to split the file into two or more files.
-Never do any of the following to reduce line count:
+The concepts have outgrown the container — find the seam between them
+and give each its own file. Never do any of the following to reduce
+line count:
 
 - Remove or shorten JSDoc comments
 - Collapse multi-line expressions onto one line
@@ -370,7 +409,8 @@ npm run spec all
 npm run spec code          # line counts (code files ≤150)
 npm run spec docs          # line counts (doc files ≤500)
 npm run spec imports       # import map aliases (no ../)
-npm run spec types         # JSDoc types (tsc --checkJs)
+npm run spec types         # all jsconfigs (auto-discovered)
+npm run spec types frontend # just .configs/jsconfig.json
 npm run spec audit         # security audit
 
 # Parent keys run all children

package/docs/JSDOC_TYPING.md

@@ -13,8 +13,8 @@
 TypeScript's `tsc` compiler validates JSDoc annotations via `--checkJs`,
 giving us compile-time type checking without a build step.
 
-A `jsconfig.json` at the project root enables `checkJs: true`. Running
-`npm run typecheck` invokes `tsc --project jsconfig.json` which:
+A `jsconfig.json` at `.configs/jsconfig.json` enables `checkJs: true` for
+frontend code. Running `npm run spec types` invokes `tsc` against it.
 
 1. Reads all `.js` files in `src/` and `scripts/`
 2. Parses JSDoc annotations as type information
@@ -24,6 +24,27 @@ A `jsconfig.json` at the project root enables `checkJs: true`. Running
 This means `@typedef`, `@type`, `@param`, and `@returns` are not just
 documentation — they are **enforced types**.
 
+### Multiple Type Configs
+
+The spec checker auto-discovers `jsconfig.json` files in subdirectories.
+If your project has a separate backend (e.g. `api/`) with its own
+dependencies and module resolution, add `api/jsconfig.json`:
+
+```
+your-project/
+├── .configs/jsconfig.json    ← frontend (src/, scripts/)
+└── api/jsconfig.json         ← backend (api/, auto-discovered)
+```
+
+```bash
+npm run spec types            # runs all discovered jsconfigs
+npm run spec types frontend   # just .configs/jsconfig.json
+npm run spec types api        # just api/jsconfig.json
+```
+
+The child key matches the directory name. Both must pass for
+`npm run spec all` to succeed.
+
 ---
 
 ## Component Properties
@@ -151,4 +172,4 @@ list: async (params) => {
 - Keep JSDoc blocks to 3–5 lines. No novels.
 - Use `/** @type {any} */ (expr)` for framework type limitations (e.g.
   `store.pending()` on array results) — document why with a comment.
-- Run `npm run typecheck` before committing. Zero errors required.
+- Run `npm run spec types` before committing. Zero errors required.