@techninja/clearstack 0.3.27 → 0.3.28

package/docs/STATE_AND_ROUTING.md

@@ -381,6 +381,54 @@ 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 Cache Poisons Boolean Flags Across Reconnects
+
+When a routed view has a boolean property used as a fallback/error flag,
+the router cache can poison it across reconnects. If the flag is ever set
+to `true` (e.g. a failed fetch), the cached value persists. On the next
+navigation to that view, `connect` runs but the property is already `true`
+from cache — even though the default is `false`:
+
+```javascript
+// ❌ BAD — if fallback was ever true, it stays true on reconnect
+export default define({
+  tag: 'my-view',
+  data: {
+    value: undefined,
+    connect(host, _key, invalidate) {
+      loadData(host).then(() => invalidate());
+    },
+  },
+  fallback: false, // default is false, but cache may hold true
+  render: ({ data, fallback }) => {
+    if (fallback) return html`<p>Error</p>`; // stuck here forever
+    // ...
+  },
+});
+
+// ✅ GOOD — reset the flag in connect before the async load
+export default define({
+  tag: 'my-view',
+  data: {
+    value: undefined,
+    connect(host, _key, invalidate) {
+      host.fallback = false; // clear stale cache
+      loadData(host).then(() => invalidate());
+    },
+  },
+  fallback: false,
+  render: ({ data, fallback }) => {
+    if (fallback) return html`<p>Error</p>`;
+    // ...
+  },
+});
+```
+
+The general rule: any boolean flag that gates render output and is set
+by an async `connect` flow should be explicitly reset at the top of
+`connect`. This is especially common with fetch-or-fallback patterns
+where the fallback path sets the flag to `true` on network errors.
+
 #### `router.backUrl()` Serializes All Parent Properties
 
 `router.backUrl()` encodes the parent view's property values into query

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "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

@@ -381,6 +381,54 @@ 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 Cache Poisons Boolean Flags Across Reconnects
+
+When a routed view has a boolean property used as a fallback/error flag,
+the router cache can poison it across reconnects. If the flag is ever set
+to `true` (e.g. a failed fetch), the cached value persists. On the next
+navigation to that view, `connect` runs but the property is already `true`
+from cache — even though the default is `false`:
+
+```javascript
+// ❌ BAD — if fallback was ever true, it stays true on reconnect
+export default define({
+  tag: 'my-view',
+  data: {
+    value: undefined,
+    connect(host, _key, invalidate) {
+      loadData(host).then(() => invalidate());
+    },
+  },
+  fallback: false, // default is false, but cache may hold true
+  render: ({ data, fallback }) => {
+    if (fallback) return html`<p>Error</p>`; // stuck here forever
+    // ...
+  },
+});
+
+// ✅ GOOD — reset the flag in connect before the async load
+export default define({
+  tag: 'my-view',
+  data: {
+    value: undefined,
+    connect(host, _key, invalidate) {
+      host.fallback = false; // clear stale cache
+      loadData(host).then(() => invalidate());
+    },
+  },
+  fallback: false,
+  render: ({ data, fallback }) => {
+    if (fallback) return html`<p>Error</p>`;
+    // ...
+  },
+});
+```
+
+The general rule: any boolean flag that gates render output and is set
+by an async `connect` flow should be explicitly reset at the top of
+`connect`. This is especially common with fetch-or-fallback patterns
+where the fallback path sets the flag to `true` on network errors.
+
 #### `router.backUrl()` Serializes All Parent Properties
 
 `router.backUrl()` encodes the parent view's property values into query

package/templates/shared/scripts/vendor-deps.js

@@ -2,10 +2,11 @@
 
 /**
  * Copies third-party ES module sources into src/vendor/ so the browser
- * can load them directly via import map. Runs on `npm postinstall`.
+ * can load them directly via import map. Runs on `npm run setup`.
+ * Applies local patches after copy.
  */
 
-import { cpSync, mkdirSync } from 'node:fs';
+import { cpSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -23,3 +24,24 @@ for (const dep of DEPS) {
   cpSync(src, dest, { recursive: true });
   console.log(`✓ Vendored: ${dep.name} → src/vendor/${dep.name}/`);
 }
+
+// Patch: fix router bootstrap URL rewrite (hybrids#router deep-link bug)
+const routerPath = resolve(VENDOR_DIR, 'hybrids/router.js');
+let routerSrc = readFileSync(routerPath, 'utf8');
+const original = `    globalThis.history.replaceState([entry], "", options.url);`;
+const patched = `    let nestedEntry = entry;
+    while (nestedEntry.nested) nestedEntry = nestedEntry.nested;
+    const entryConfig = getConfigById(nestedEntry.id);
+    const bootstrapUrl = entryConfig && entryConfig.browserUrl
+      ? entryConfig.url(nestedEntry.params, true)
+      : options.url;
+
+    globalThis.history.replaceState([entry], "", bootstrapUrl);`;
+
+if (routerSrc.includes(original)) {
+  routerSrc = routerSrc.replace(original, patched);
+  writeFileSync(routerPath, routerSrc);
+  console.log('✓ Patched: hybrids/router.js (bootstrap deep-link URL fix)');
+} else if (!routerSrc.includes('bootstrapUrl')) {
+  console.warn('⚠ Could not apply router patch — source changed upstream');
+}