@techninja/clearstack 0.3.7 → 0.3.9

package/docs/CONVENTIONS.md

@@ -109,6 +109,50 @@ render: ({ items }) => html`
 
 ---
 
+## Import Map Aliases
+
+All cross-directory imports in browser-facing code use `#prefix/` aliases
+defined in the import map (`src/index.html`). This eliminates fragile
+relative paths like `../../../utils/foo.js`.
+
+### Available Prefixes
+
+| Prefix          | Resolves to                    |
+| --------------- | ------------------------------ |
+| `#store/`       | `/store/`                      |
+| `#utils/`       | `/utils/`                      |
+| `#atoms/`       | `/components/atoms/`           |
+| `#molecules/`   | `/components/molecules/`       |
+| `#organisms/`   | `/components/organisms/`       |
+| `#templates/`   | `/components/templates/`       |
+| `#pages/`       | `/pages/`                      |
+
+### Rules
+
+- **No `../` imports.** The spec check (`npm run spec`) flags any `../`
+  in browser-facing JS. Use a `#prefix/` alias instead.
+- **Same-directory `./` is fine.** `index.js` re-exports and co-located
+  files use `./` naturally.
+- **Server/API files are exempt.** `src/api/` and `src/server.js` run in
+  Node, not the browser — they use `./` relative imports.
+- **Test files are exempt.** `*.test.js` files may use relative paths.
+- **jsconfig.json mirrors the import map.** The `paths` entries in
+  `.configs/jsconfig.json` let `tsc --checkJs` resolve `#prefix/` imports.
+
+### Examples
+
+```javascript
+// ✅ Good — clear, refactor-safe
+import AppState from '#store/AppState.js';
+import { formatDate } from '#utils/formatDate.js';
+import '#atoms/app-badge/app-badge.js';
+
+// ❌ Bad — fragile, hard to read
+import AppState from '../../../store/AppState.js';
+```
+
+---
+
 ## Error Handling
 
 Errors are handled **at the boundary where they are actionable.** Each layer
@@ -193,8 +237,8 @@ state: store(AppState),
 // In src/utils/filterActive.js
 export const filterActive = (items) => items.filter(i => i.active);
 
-// In component
-import { filterActive } from '../../utils/filterActive.js';
+// In component — use import map alias, never ../
+import { filterActive } from '#utils/filterActive.js';
 render: ({ items }) => html`<ul>${filterActive(items).map(...)}</ul>`,
 ```
 

package/docs/SERVER_AND_DEPS.md

@@ -121,7 +121,14 @@ declared in `src/index.html`.
     <script type="importmap">
       {
         "imports": {
-          "hybrids": "/vendor/hybrids/index.js"
+          "hybrids": "/vendor/hybrids/index.js",
+          "#store/": "/store/",
+          "#utils/": "/utils/",
+          "#atoms/": "/components/atoms/",
+          "#molecules/": "/components/molecules/",
+          "#organisms/": "/components/organisms/",
+          "#templates/": "/components/templates/",
+          "#pages/": "/pages/"
         }
       }
     </script>
@@ -139,6 +146,8 @@ declared in `src/index.html`.
 2. Import map resolves `'hybrids'` → `/vendor/hybrids/index.js`.
 3. Server serves the file from `src/vendor/hybrids/index.js`.
 4. Hybrids' internal imports use relative paths — they resolve naturally.
+5. `#prefix/` entries resolve cross-directory app imports without `../`.
+   For example, `import '#utils/formatDate.js'` resolves to `/utils/formatDate.js`.
 
 ### Rules
 

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,14 +1,13 @@
 /**
  * Spec compliance checker — config, commands, and orchestration.
- * Core utilities live in spec-utils.js.
  * @module lib/check
  */
 
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { checkFileLines, runCmd, countFiles } from './spec-utils.js';
+import { checkFileLines, runCmd, countFiles, checkImports } from './spec-utils.js';
 
-export { checkFileLines, runCmd, countFiles, findFiles, elapsed } from './spec-utils.js';
+export { checkFileLines, runCmd, countFiles, findFiles, elapsed, checkImports } from './spec-utils.js';
 
 /** Detect the project's package manager runner (npx, pnpm exec, yarn). */
 function detectRunner(projectDir) {
@@ -62,42 +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)`),
-    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/lib/package-gen.js

@@ -49,6 +49,16 @@ export async function writePackageJson(dest, vars, existing) {
     typescript: '^6.0.2',
   };
 
+  const subpathImports = {
+    '#store/*': './src/store/*',
+    '#utils/*': './src/utils/*',
+    '#atoms/*': './src/components/atoms/*',
+    '#molecules/*': './src/components/molecules/*',
+    '#organisms/*': './src/components/organisms/*',
+    '#templates/*': './src/components/templates/*',
+    '#pages/*': './src/pages/*',
+  };
+
   const pkg = existing
     ? {
         ...existing,
@@ -56,6 +66,7 @@ export async function writePackageJson(dest, vars, existing) {
         description: vars.description,
         type: 'module',
         main: 'src/server.js',
+        imports: { ...existing.imports, ...subpathImports },
         scripts: { ...existing.scripts, ...specScripts },
         dependencies: { ...existing.dependencies, ...specDeps },
         devDependencies: { ...existing.devDependencies, ...specDevDeps },
@@ -66,6 +77,7 @@ export async function writePackageJson(dest, vars, existing) {
         type: 'module',
         description: vars.description,
         main: 'src/server.js',
+        imports: subpathImports,
         scripts: specScripts,
         keywords: ['hybrids', 'web-components', 'no-build'],
         license: 'MIT',

package/lib/spec-utils.js

@@ -79,6 +79,38 @@ export function checkFileLines(root, extensions, max, ignoreDirs, label) {
   return false;
 }
 
+/**
+ * Check for relative parent imports (`../`) in browser-facing JS files.
+ * Same-directory (`./`) and server/test files are allowed.
+ * @param {string} root
+ * @param {string[]} ignoreDirs
+ * @param {string} label
+ * @returns {boolean}
+ */
+export function checkImports(root, ignoreDirs, label) {
+  const start = performance.now();
+  const files = findFiles(root, ['.js'], ignoreDirs, root)
+    .filter((f) => f.startsWith('src/') && !f.includes('vendor/') && !f.includes('api/') && !f.endsWith('.test.js') && !f.endsWith('server.js'));
+  const violations = [];
+  const importRe = /(?:^|\n)\s*import\s.*?from\s+['"](\.\.[^'"]*)['"]|(?:^|\n)\s*import\s+['"](\.\.[^'"]*)['"]|(?:^|\n)\s*export\s.*?from\s+['"](\.\.[^'"]*)['"/]/g;
+  for (const file of files) {
+    const src = readFileSync(resolve(root, file), 'utf-8');
+    let m;
+    while ((m = importRe.exec(src)) !== null) {
+      const spec = m[1] || m[2] || m[3];
+      violations.push({ file, spec });
+    }
+  }
+  const time = elapsed(start);
+  if (violations.length === 0) {
+    console.log(`  ✅ ${label} (${files.length} files, ${time})`);
+    return true;
+  }
+  console.log(`  ❌ ${label} — ${violations.length} violation(s):`);
+  for (const v of violations) console.log(`     ${v.file}: import '${v.spec}' → use #prefix/ alias`);
+  return false;
+}
+
 /**
  * Run a shell command, report pass/fail with timing.
  * @param {string} label

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -31,6 +31,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "imports": {
+    "#store/*": "./src/store/*",
+    "#utils/*": "./src/utils/*",
+    "#atoms/*": "./src/components/atoms/*",
+    "#molecules/*": "./src/components/molecules/*",
+    "#organisms/*": "./src/components/organisms/*",
+    "#templates/*": "./src/components/templates/*",
+    "#pages/*": "./src/pages/*"
+  },
   "keywords": [
     "web-components",
     "no-build",

package/templates/fullstack/src/router/index.js

@@ -4,7 +4,7 @@
  */
 
 import { html, define, router } from 'hybrids';
-import HomeView from '../pages/home/home-view.js';
+import HomeView from '#pages/home/home-view.js';
 
 export default define({
   tag: 'app-router',

package/templates/shared/.configs/jsconfig.json

@@ -10,7 +10,14 @@
     "skipLibCheck": true,
     "types": ["node"],
     "paths": {
-      "hybrids": ["../node_modules/hybrids/types/index.d.ts"]
+      "hybrids": ["../node_modules/hybrids/types/index.d.ts"],
+      "#store/*": ["../src/store/*"],
+      "#utils/*": ["../src/utils/*"],
+      "#atoms/*": ["../src/components/atoms/*"],
+      "#molecules/*": ["../src/components/molecules/*"],
+      "#organisms/*": ["../src/components/organisms/*"],
+      "#templates/*": ["../src/components/templates/*"],
+      "#pages/*": ["../src/pages/*"]
     }
   },
   "include": ["../src/**/*.js", "../scripts/**/*.js"],

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

@@ -109,6 +109,50 @@ render: ({ items }) => html`
 
 ---
 
+## Import Map Aliases
+
+All cross-directory imports in browser-facing code use `#prefix/` aliases
+defined in the import map (`src/index.html`). This eliminates fragile
+relative paths like `../../../utils/foo.js`.
+
+### Available Prefixes
+
+| Prefix          | Resolves to                    |
+| --------------- | ------------------------------ |
+| `#store/`       | `/store/`                      |
+| `#utils/`       | `/utils/`                      |
+| `#atoms/`       | `/components/atoms/`           |
+| `#molecules/`   | `/components/molecules/`       |
+| `#organisms/`   | `/components/organisms/`       |
+| `#templates/`   | `/components/templates/`       |
+| `#pages/`       | `/pages/`                      |
+
+### Rules
+
+- **No `../` imports.** The spec check (`npm run spec`) flags any `../`
+  in browser-facing JS. Use a `#prefix/` alias instead.
+- **Same-directory `./` is fine.** `index.js` re-exports and co-located
+  files use `./` naturally.
+- **Server/API files are exempt.** `src/api/` and `src/server.js` run in
+  Node, not the browser — they use `./` relative imports.
+- **Test files are exempt.** `*.test.js` files may use relative paths.
+- **jsconfig.json mirrors the import map.** The `paths` entries in
+  `.configs/jsconfig.json` let `tsc --checkJs` resolve `#prefix/` imports.
+
+### Examples
+
+```javascript
+// ✅ Good — clear, refactor-safe
+import AppState from '#store/AppState.js';
+import { formatDate } from '#utils/formatDate.js';
+import '#atoms/app-badge/app-badge.js';
+
+// ❌ Bad — fragile, hard to read
+import AppState from '../../../store/AppState.js';
+```
+
+---
+
 ## Error Handling
 
 Errors are handled **at the boundary where they are actionable.** Each layer
@@ -193,8 +237,8 @@ state: store(AppState),
 // In src/utils/filterActive.js
 export const filterActive = (items) => items.filter(i => i.active);
 
-// In component
-import { filterActive } from '../../utils/filterActive.js';
+// In component — use import map alias, never ../
+import { filterActive } from '#utils/filterActive.js';
 render: ({ items }) => html`<ul>${filterActive(items).map(...)}</ul>`,
 ```
 

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

@@ -121,7 +121,14 @@ declared in `src/index.html`.
     <script type="importmap">
       {
         "imports": {
-          "hybrids": "/vendor/hybrids/index.js"
+          "hybrids": "/vendor/hybrids/index.js",
+          "#store/": "/store/",
+          "#utils/": "/utils/",
+          "#atoms/": "/components/atoms/",
+          "#molecules/": "/components/molecules/",
+          "#organisms/": "/components/organisms/",
+          "#templates/": "/components/templates/",
+          "#pages/": "/pages/"
         }
       }
     </script>
@@ -139,6 +146,8 @@ declared in `src/index.html`.
 2. Import map resolves `'hybrids'` → `/vendor/hybrids/index.js`.
 3. Server serves the file from `src/vendor/hybrids/index.js`.
 4. Hybrids' internal imports use relative paths — they resolve naturally.
+5. `#prefix/` entries resolve cross-directory app imports without `../`.
+   For example, `import '#utils/formatDate.js'` resolves to `/utils/formatDate.js`.
 
 ### Rules
 

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

package/templates/shared/src/components/atoms/theme-toggle/theme-toggle.js

@@ -5,11 +5,11 @@
  */
 
 import { html, define, store } from 'hybrids';
-import AppState from '../../../store/AppState.js';
+import AppState from '#store/AppState.js';
 
 /**
  * @typedef {Object} ThemeToggleHost
- * @property {import('../../../store/AppState.js').AppState} state
+ * @property {import('#store/AppState.js').AppState} state
  */
 
 /**

package/templates/shared/src/index.html

@@ -14,7 +14,14 @@
     <script type="importmap">
       {
         "imports": {
-          "hybrids": "/vendor/hybrids/index.js"
+          "hybrids": "/vendor/hybrids/index.js",
+          "#store/": "/store/",
+          "#utils/": "/utils/",
+          "#atoms/": "/components/atoms/",
+          "#molecules/": "/components/molecules/",
+          "#organisms/": "/components/organisms/",
+          "#templates/": "/components/templates/",
+          "#pages/": "/pages/"
         }
       }
     </script>

package/templates/static/src/pages/home/home-view.js

@@ -4,12 +4,12 @@
  */
 
 import { html, define, store } from 'hybrids';
-import AppState from '../../store/AppState.js';
-import '../../components/atoms/app-button/app-button.js';
+import AppState from '#store/AppState.js';
+import '#atoms/app-button/app-button.js';
 
 /**
  * @typedef {Object} HomeViewHost
- * @property {import('../../store/AppState.js').AppState} state
+ * @property {import('#store/AppState.js').AppState} state
  */
 
 /** @param {HomeViewHost & HTMLElement} host */

package/templates/static/src/router/index.js

@@ -4,7 +4,7 @@
  */
 
 import { html, define, router } from 'hybrids';
-import HomeView from '../pages/home/home-view.js';
+import HomeView from '#pages/home/home-view.js';
 
 export default define({
   tag: 'app-router',