@techninja/clearstack 0.3.8 → 0.3.9

package/docs/STATE_AND_ROUTING.md

@@ -33,6 +33,43 @@ export default define({
 
 Local state resets when the component disconnects from the DOM.
 
+#### Property Defaults: Never Use `undefined` or `null`
+
+Hybrids infers a property's type from its initial value. The router's cache
+observer calls `.toString()` on property values during state transitions.
+If a property is defined as `undefined` or later set to `null`, this crashes:
+
+```javascript
+// ❌ BAD — undefined has no type info, null crashes .toString()
+export default define({
+  tag: 'my-view',
+  _data: undefined,  // no type info for hybrids to work with
+  // ...
+});
+
+// Later in a handler:
+host._data = null;  // TypeError: Cannot read properties of null (reading 'toString')
+```
+
+Always provide a typed default value, and reset to the same type:
+
+```javascript
+// ✅ GOOD — array default, connect no-op prevents hybrids from observing it
+export default define({
+  tag: 'my-view',
+  _data: { value: [], connect: () => {} },
+  // ...
+});
+
+// Later in a handler:
+host._data = [];  // safe — same type as default
+```
+
+The `connect: () => {}` no-op prevents hybrids from doing anything special
+with the property — it's just internal state storage. This pattern is useful
+for "private" properties that hold transient data (parsed results, file
+contents, etc.) that shouldn't participate in the reactive render cycle.
+
 ### Shared State via Store
 
 For state shared across components or persisted beyond a component's lifetime,
@@ -180,6 +217,40 @@ tasks.map((task) =>
 This is especially important after batch operations (e.g. drag reorder)
 where multiple items are invalidated simultaneously.
 
+#### Async `connect` on Array Properties
+
+When a plain array property uses `connect` to load data asynchronously,
+the render function fires **before** the async load completes. Even though
+the default `value` is `[]`, hybrids may resolve the property as a
+non-array during the pending phase.
+
+Always guard with `Array.isArray()` before calling array methods:
+
+```javascript
+export default define({
+  tag: 'my-view',
+  items: {
+    value: [],
+    connect: (host, _key, invalidate) => {
+      fetchItems().then((list) => { host.items = list; invalidate(); });
+    },
+  },
+  render: ({ items }) => html`
+    // ❌ BAD — items may not be an array yet when render fires
+    ${items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)}
+
+    // ✅ GOOD — guard before calling array methods
+    ${Array.isArray(items) && items.length > 0
+      ? items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)
+      : html``}
+  `,
+});
+```
+
+This applies to any property with `value: []` and an async `connect`.
+The `connect` callback sets the value and calls `invalidate()`, but the
+first render happens before that resolves.
+
 ---
 
 ## Routing
@@ -234,6 +305,71 @@ export default define({
 | Guarded route        | `guard: () => isAuthenticated()`         |
 | Dialog overlay       | `dialog: true` on the view config        |
 
+#### Router Property Cache: Same-Value Writes Are No-Ops
+
+The router caches component property values across navigations and page
+reloads. When a view reconnects, its properties are restored from cache
+**before** `connect` callbacks run.
+
+This means if a `connect` callback loads data asynchronously and then sets
+a property to the same value the cache already holds, hybrids sees no
+change and skips the re-render:
+
+```javascript
+// ❌ BAD — if router cache already has resultCount=22,
+// setting it to 22 again is a no-op. No re-render happens.
+connect: (host, _key, invalidate) => {
+  loadFromDB(host.userId).then((data) => {
+    populateMemoryCache(data);     // side effect: fills an external object
+    host.resultCount = data.length; // may equal cached value → no re-render
+    invalidate();
+  });
+},
+
+// ✅ GOOD — reset to a sentinel value first, then set the real value.
+// Hybrids sees 0 → 22, triggers re-render after data is loaded.
+connect: (host, _key, invalidate) => {
+  loadFromDB(host.userId).then((data) => {
+    populateMemoryCache(data);
+    host.resultCount = 0;           // force a change
+    host.resultCount = data.length; // now hybrids sees a real change
+    invalidate();
+  });
+},
+```
+
+This is especially important when render depends on external mutable state
+(e.g. an in-memory cache object) that the property change is meant to
+signal. Without the reset, the component renders with stale external state.
+
+#### `router.backUrl()` Serializes All Parent Properties
+
+`router.backUrl()` encodes the parent view's property values into query
+params so hybrids can restore them when navigating back. If the parent has
+properties holding complex objects (arrays of records, parsed data, etc.),
+the URL becomes enormous — potentially megabytes — and the browser locks
+up just rendering the `<a>` element.
+
+The `connect: () => {}` no-op prevents hybrids from *observing* a property,
+but the router still serializes it. The only way to fully exclude a
+property from URL serialization is to not define it on the routed view at
+all (use a module-level variable or a separate store).
+
+For child views that don't need to restore specific parent state, use a
+direct href instead of `router.backUrl()`:
+
+```javascript
+// ❌ BAD — serializes ALL parent properties into the href
+// If parent has a 700K-item array, the URL is megabytes
+html`<a href="${router.backUrl()}">← Back</a>`
+
+// ✅ GOOD — direct link, no serialization
+html`<a href="/dashboard">← Back</a>`
+```
+
+Use `router.backUrl()` only when the parent view has simple scalar
+properties (strings, numbers, booleans) that are cheap to serialize.
+
 ---
 
 ## Unified App State

package/lib/check.js

@@ -1,6 +1,5 @@
 /**
  * Spec compliance checker — config, commands, and orchestration.
- * Core utilities live in spec-utils.js.
  * @module lib/check
  */
 
@@ -62,43 +61,74 @@ function buildCmds(runner) {
 /** @deprecated Use buildCmds() instead — kept for backward compat. */
 export const CMDS = buildCmds('npx');
 
-/**
- * Run the full spec compliance check (used by clearstack CLI).
- * @param {string} projectDir
- * @param {string} [scope]
- */
+/** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
+
+/** Build the unified checks array. Children have a `parent` key. */
+export function buildChecks(dir, cfg, cmds) {
+  const js = () => countFiles(dir, ['.js'], cfg.ignore);
+  const css = () => countFiles(dir, ['.css'], cfg.ignore);
+  const md = () => countFiles(dir, ['.md'], cfg.ignore);
+  return [
+    { key: 'code', name: `Code (max ${cfg.codeMax} lines)`,
+      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`) },
+    { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
+      run: () => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`) },
+    { key: 'imports', name: 'Import map aliases (no ../ imports)',
+      run: () => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)') },
+    { key: 'es', name: 'ESLint', parent: 'lint',
+      run: () => runCmd('ESLint', cmds.lint, dir, `${js()} files`) },
+    { key: 'css', name: 'Stylelint', parent: 'lint',
+      run: () => runCmd('Stylelint', cmds.stylelint, dir, `${css()} files`) },
+    { key: 'md', name: 'Markdown lint', parent: 'lint',
+      run: () => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`) },
+    { key: 'prettier', name: 'Prettier', parent: 'format',
+      run: () => runCmd('Prettier', cmds.prettier, dir, `${js()} files`) },
+    { key: 'types', name: 'JSDoc types (tsc --checkJs)',
+      run: () => runCmd('JSDoc types', cmds.types, dir, `${js()} files`) },
+    { key: 'audit', name: 'Security audit',
+      run: () => runCmd('Security audit', cmds.audit, dir) },
+  ];
+}
+
+/** Resolve a scope like 'lint', 'lint es', or 'code' to runnable check(s). */
+export function resolveChecks(checks, scope) {
+  const [first, second] = scope.split(/\s+/);
+  if (second) {
+    const match = checks.find((c) => c.parent === first && c.key === second);
+    return match ? [match] : null;
+  }
+  const children = checks.filter((c) => c.parent === first);
+  if (children.length) return children;
+  const exact = checks.find((c) => c.key === first && !c.parent);
+  return exact ? [exact] : null;
+}
+
+/** All unique parent keys. */
+export function parentKeys(checks) {
+  return [...new Set(checks.filter((c) => c.parent).map((c) => c.parent))];
+}
+
+/** Run the full spec compliance check (used by clearstack CLI). */
 export async function check(projectDir, scope) {
   const cfg = loadConfig(projectDir);
   const cmds = buildCmds(detectRunner(projectDir));
+  const checks = buildChecks(projectDir, cfg, cmds);
 
-  if (scope === 'code') {
-    if (!checkFileLines(projectDir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`))
+  if (scope) {
+    const matched = resolveChecks(checks, scope);
+    if (!matched) {
+      console.log(`Unknown check: ${scope}`);
+      const tops = checks.filter((c) => !c.parent).map((c) => c.key);
+      console.log(`Available: ${[...tops, ...parentKeys(checks)].join(', ')}`);
       process.exit(1);
+    }
+    const ok = matched.every((c) => c.run());
+    if (!ok) process.exit(1);
     return;
   }
-  if (scope === 'docs') {
-    if (!checkFileLines(projectDir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`))
-      process.exit(1);
-    return;
-  }
-
-  const jsFiles = countFiles(projectDir, ['.js'], cfg.ignore);
-  const cssFiles = countFiles(projectDir, ['.css'], cfg.ignore);
-  const mdFiles = countFiles(projectDir, ['.md'], cfg.ignore);
 
   console.log('Running spec compliance check...\n');
-  const results = [
-    checkFileLines(projectDir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`),
-    checkFileLines(projectDir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`),
-    checkImports(projectDir, cfg.ignore, 'Import map aliases (no ../ imports)'),
-    runCmd('ESLint', cmds.lint, projectDir, `${jsFiles} files`),
-    runCmd('Stylelint', cmds.stylelint, projectDir, `${cssFiles} files`),
-    runCmd('Prettier', cmds.prettier, projectDir, `${jsFiles} files`),
-    runCmd('Markdown', cmds.mdlint, projectDir, `${mdFiles} files`),
-    runCmd('JSDoc types', cmds.types, projectDir, `${jsFiles} files`),
-    runCmd('Security audit', cmds.audit, projectDir),
-  ];
-
+  const results = checks.map((c) => c.run());
   const passed = results.filter(Boolean).length;
   console.log(`\n${'='.repeat(40)}`);
   console.log(`${passed}/${results.length} checks passed.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

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

@@ -33,6 +33,43 @@ export default define({
 
 Local state resets when the component disconnects from the DOM.
 
+#### Property Defaults: Never Use `undefined` or `null`
+
+Hybrids infers a property's type from its initial value. The router's cache
+observer calls `.toString()` on property values during state transitions.
+If a property is defined as `undefined` or later set to `null`, this crashes:
+
+```javascript
+// ❌ BAD — undefined has no type info, null crashes .toString()
+export default define({
+  tag: 'my-view',
+  _data: undefined,  // no type info for hybrids to work with
+  // ...
+});
+
+// Later in a handler:
+host._data = null;  // TypeError: Cannot read properties of null (reading 'toString')
+```
+
+Always provide a typed default value, and reset to the same type:
+
+```javascript
+// ✅ GOOD — array default, connect no-op prevents hybrids from observing it
+export default define({
+  tag: 'my-view',
+  _data: { value: [], connect: () => {} },
+  // ...
+});
+
+// Later in a handler:
+host._data = [];  // safe — same type as default
+```
+
+The `connect: () => {}` no-op prevents hybrids from doing anything special
+with the property — it's just internal state storage. This pattern is useful
+for "private" properties that hold transient data (parsed results, file
+contents, etc.) that shouldn't participate in the reactive render cycle.
+
 ### Shared State via Store
 
 For state shared across components or persisted beyond a component's lifetime,
@@ -180,6 +217,40 @@ tasks.map((task) =>
 This is especially important after batch operations (e.g. drag reorder)
 where multiple items are invalidated simultaneously.
 
+#### Async `connect` on Array Properties
+
+When a plain array property uses `connect` to load data asynchronously,
+the render function fires **before** the async load completes. Even though
+the default `value` is `[]`, hybrids may resolve the property as a
+non-array during the pending phase.
+
+Always guard with `Array.isArray()` before calling array methods:
+
+```javascript
+export default define({
+  tag: 'my-view',
+  items: {
+    value: [],
+    connect: (host, _key, invalidate) => {
+      fetchItems().then((list) => { host.items = list; invalidate(); });
+    },
+  },
+  render: ({ items }) => html`
+    // ❌ BAD — items may not be an array yet when render fires
+    ${items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)}
+
+    // ✅ GOOD — guard before calling array methods
+    ${Array.isArray(items) && items.length > 0
+      ? items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)
+      : html``}
+  `,
+});
+```
+
+This applies to any property with `value: []` and an async `connect`.
+The `connect` callback sets the value and calls `invalidate()`, but the
+first render happens before that resolves.
+
 ---
 
 ## Routing
@@ -234,6 +305,71 @@ export default define({
 | Guarded route        | `guard: () => isAuthenticated()`         |
 | Dialog overlay       | `dialog: true` on the view config        |
 
+#### Router Property Cache: Same-Value Writes Are No-Ops
+
+The router caches component property values across navigations and page
+reloads. When a view reconnects, its properties are restored from cache
+**before** `connect` callbacks run.
+
+This means if a `connect` callback loads data asynchronously and then sets
+a property to the same value the cache already holds, hybrids sees no
+change and skips the re-render:
+
+```javascript
+// ❌ BAD — if router cache already has resultCount=22,
+// setting it to 22 again is a no-op. No re-render happens.
+connect: (host, _key, invalidate) => {
+  loadFromDB(host.userId).then((data) => {
+    populateMemoryCache(data);     // side effect: fills an external object
+    host.resultCount = data.length; // may equal cached value → no re-render
+    invalidate();
+  });
+},
+
+// ✅ GOOD — reset to a sentinel value first, then set the real value.
+// Hybrids sees 0 → 22, triggers re-render after data is loaded.
+connect: (host, _key, invalidate) => {
+  loadFromDB(host.userId).then((data) => {
+    populateMemoryCache(data);
+    host.resultCount = 0;           // force a change
+    host.resultCount = data.length; // now hybrids sees a real change
+    invalidate();
+  });
+},
+```
+
+This is especially important when render depends on external mutable state
+(e.g. an in-memory cache object) that the property change is meant to
+signal. Without the reset, the component renders with stale external state.
+
+#### `router.backUrl()` Serializes All Parent Properties
+
+`router.backUrl()` encodes the parent view's property values into query
+params so hybrids can restore them when navigating back. If the parent has
+properties holding complex objects (arrays of records, parsed data, etc.),
+the URL becomes enormous — potentially megabytes — and the browser locks
+up just rendering the `<a>` element.
+
+The `connect: () => {}` no-op prevents hybrids from *observing* a property,
+but the router still serializes it. The only way to fully exclude a
+property from URL serialization is to not define it on the routed view at
+all (use a module-level variable or a separate store).
+
+For child views that don't need to restore specific parent state, use a
+direct href instead of `router.backUrl()`:
+
+```javascript
+// ❌ BAD — serializes ALL parent properties into the href
+// If parent has a 700K-item array, the URL is megabytes
+html`<a href="${router.backUrl()}">← Back</a>`
+
+// ✅ GOOD — direct link, no serialization
+html`<a href="/dashboard">← Back</a>`
+```
+
+Use `router.backUrl()` only when the parent view has simple scalar
+properties (strings, numbers, booleans) that are cheap to serialize.
+
 ---
 
 ## Unified App State