@adukiorg/anza 0.2.0 → 0.2.3

package/src/core/router/missing.md

@@ -1,716 +0,0 @@
-# Native Router Missing Support
-
-This document tracks remaining support and enhancement work for `src/core/router`. Implemented behavior belongs in `usage.md`; unsupported, untyped, or under-tested behavior belongs here until it is built and verified.
-
----
-
-## 0. Toolchain and Naming Rules
-
-Heavy parsing, extraction, generation, and validation work belongs in `tools/`, not in browser runtime modules.
-
-Current toolchain support:
-
-```text
-tools/src/extract/html.rs     # HTML template scan
-tools/src/extract/runner.rs   # JS spec scan and type generation
-tools/src/extract/routes.rs   # declarative route manifest generation
-tools/src/watcher/runner.rs   # file watch, debounce, regenerate
-tools/src/types/runner.rs     # shared tool data types
-```
-
-Current commands:
-
-```bash
-anza scan --src src
-anza scan --src src --watch
-anza build --src src --dist dist
-anza dev --src src --port 3000
-```
-
-Current router toolchain support:
-
-- `ui.element({ url, container })` specs are parsed.
-- `routes.json` is emitted during `scan`, `build`, and `dev`.
-- Duplicate route patterns warn.
-- Route param names are extracted from `:param` path segments.
-
-Naming rules for new support:
-
-- Prefer one-word files: `routes.rs`, `match.js`, `history.js`, `sync.js`, `types.rs`.
-- Prefer one-word generated files: `routes.json`, `routes.d.ts`, `types.d.ts`.
-- Prefer one-word commands: `scan`, `build`, `dev`, `check`.
-- Prefer one-word methods in context: `add`, `get`, `set`, `clear`, `reset`, `start`, `stop`, `active`, `match`.
-- Avoid repeated scope: inside `router.guards`, use `clear`, not `clearGuards`; inside `router.links`, use `add`, not `registerConnection`.
-- Keep route segments plural and one word: `/members`, `/loans`, `/causes`.
-
----
-
-## 1. Critical Runtime Gaps
-
-### 1.1. Type declarations do not match runtime
-
-Status: critical mismatch.
-
-Files:
-
-```text
-types/core/router/index.d.ts
-src/core/router/index.js
-src/core/router/match.js
-src/core/router/intercept.js
-```
-
-Problem:
-
-The type file still describes older APIs such as:
-
-```typescript
-router.on(pathPattern, callback)
-router.render(outletElement, content)
-router.match(pathname): { params, callback } | null
-renderOutlet(...)
-```
-
-The runtime exposes:
-
-```javascript
-router.register(pattern, handler, meta)
-router.on('found' | 'notfound' | 'error', callback, signal)
-router.match(url): Promise<{ route, tag, params, result } | null>
-router.nav.to(url)
-router.guards.add(fn)
-router.miss.set(handler)
-router.sync.start()
-router.links.add(pattern, factory)
-router.registerContainer(name, element)
-```
-
-Expected support:
-
-- Rewrite `types/core/router/index.d.ts` to match runtime.
-- Include route record, match result, event payload, guard, transition controller, container, sync, and connection types.
-- Remove `router.render` and `renderOutlet` types unless those functions are implemented.
-- Add `tests/types/router-types.test.ts`.
-- Add a one-word `check` script for `.ts` type tests.
-
-### 1.2. Not-found handler emits an undefined `url`
-
-Status: runtime bug.
-
-File:
-
-```text
-src/core/router/intercept.js
-```
-
-Problem:
-
-Inside the intercepted navigation handler, the not-found branch emits and logs `url`, but that local variable is not defined in that scope.
-
-Current shape:
-
-```javascript
-emit('notfound', { url });
-console.error(`Route matching failed ... ${url}`);
-```
-
-Expected support:
-
-```javascript
-const url = destination.url;
-emit('notfound', { url });
-```
-
-Tests:
-
-- Intercepted unmatched navigation emits `notfound` with the destination URL.
-- Default not-found logging does not throw.
-
-### 1.3. Route handler function semantics are ambiguous
-
-Status: design/runtime risk.
-
-Files:
-
-```text
-src/core/router/match.js
-src/core/router/intercept.js
-```
-
-Problem:
-
-`match()` treats every function handler as a lazy tag factory:
-
-```javascript
-if (typeof tag === 'function') {
-  tag = await tag();
-}
-```
-
-`intercept.js` then treats function handlers with arguments as legacy callbacks:
-
-```javascript
-if (typeof routeMatch.route.handler === 'function' && routeMatch.route.handler.length > 0) {
-  await routeMatch.route.handler(routeMatch.params, event);
-}
-```
-
-This can call callback handlers once with no args during matching and again with params during navigation.
-
-Expected support:
-
-```javascript
-router.register('/path', 'page-tag');
-router.register('/path', { tag: 'page-tag' });
-router.register('/path', { load: async () => 'page-tag' });
-router.register('/path', { handler: async (params, event) => {} });
-```
-
-Recommended path:
-
-- Keep tag strings.
-- Add object route records for lazy tags and callbacks.
-- Deprecate bare function ambiguity.
-- Add a `scan` warning when static ambiguous bare function route handlers can be detected.
-
-Tests:
-
-- Lazy tag factory is called once.
-- Callback handler is not called during `match()`.
-- Callback handler receives `(params, event)` only during intercepted navigation.
-
----
-
-## 2. Declarative Routing Enhancements
-
-### 2.1. Route param casting for UI props
-
-Status: enhancement.
-
-Files:
-
-```text
-src/core/ui/define/orchestrator.js
-src/core/router/match.js
-tools/src/extract/routes.rs
-```
-
-Current behavior:
-
-Route params are assigned directly as strings:
-
-```javascript
-pageEl[key] = value;
-```
-
-Expected support:
-
-- `Number` props receive numbers.
-- `Boolean` props receive booleans by convention.
-- `String` props remain strings.
-- Generated route data can include prop type hints when statically known.
-- Runtime falls back to string params for dynamic routes.
-
-### 2.2. Query string and hash params are not mapped
-
-Status: enhancement.
-
-Files:
-
-```text
-src/core/router/match.js
-src/core/ui/define/orchestrator.js
-```
-
-Current behavior:
-
-Only pathname groups are exposed as `params`.
-
-Expected support:
-
-```javascript
-{
-  params,
-  query,
-  hash,
-  url
-}
-```
-
-Declarative UI route options:
-
-```javascript
-ui.element('page-search', {
-  url: '/search',
-  query: ['q', 'page']
-});
-```
-
-Naming:
-
-- Use `query`, not `searchParams`.
-- Use `hash`, not `fragment`.
-
-### 2.3. No nested route outlet implementation
-
-Status: planned but missing.
-
-Files:
-
-```text
-src/core/router/plan.md
-src/core/router/
-```
-
-Expected support:
-
-- Add `outlet.js`.
-- Define `<route-outlet>`.
-- Diff route chains to preserve parent layouts.
-- Mount changed child segments only.
-
-Naming:
-
-- `outlet.js` is acceptable because the folder already provides router context.
-- `<route-outlet>` is acceptable because custom element names require a hyphen.
-
-### 2.4. Container selector/name semantics need tightening
-
-Status: partial support.
-
-Files:
-
-```text
-src/core/router/container.js
-src/core/ui/define/container.js
-src/core/ui/define/orchestrator.js
-tools/src/extract/routes.rs
-```
-
-Current behavior:
-
-- `ui.container` registers by `name` attribute or tag name.
-- `getContainer(name)` also tries `document.querySelector(name)`.
-- `ui.element({ container })` passes a string through route metadata.
-
-Risk:
-
-Strings such as `main`, `#main`, and `app-main` can mean registry keys or CSS selectors.
-
-Expected support:
-
-- Document and enforce one convention.
-- Recommended: registered container names are plain names; CSS selectors start with `#`, `.`, `[`, or another clear selector marker.
-- Add runtime warnings for ambiguous names.
-- Add `scan` warnings for ambiguous declarative containers.
-
-### 2.5. Container swap cancellation
-
-Status: enhancement.
-
-Files:
-
-```text
-src/core/ui/define/container.js
-src/core/router/transitions.js
-```
-
-Need:
-
-When users navigate rapidly, older swaps can finish after newer swaps.
-
-Expected support:
-
-- Track a per-container swap token.
-- Ignore stale swap completions.
-- Ensure latest route remains mounted.
-
----
-
-## 3. Toolchain Enhancements
-
-### 3.1. Route declarations are not generated
-
-Status: enhancement.
-
-Files:
-
-```text
-tools/src/extract/routes.rs
-tools/src/extract/runner.rs
-tools/src/types/runner.rs
-```
-
-Current support:
-
-- `routes.json` is generated.
-- Duplicate route patterns warn.
-- Path params are listed in each route record.
-
-Missing support:
-
-- Generate `routes.d.ts`.
-- Include route metadata types.
-- Include UI prop type hints for route params.
-- Warn for route segment naming violations.
-- Warn for ambiguous declarative container names.
-
-### 3.2. Generated route docs
-
-Status: enhancement.
-
-Files:
-
-```text
-src/core/router/usage.md
-docs/core/router/index.md
-tools/src/extract/routes.rs
-```
-
-Need:
-
-Once `routes.json` is stable, docs can show generated route maps and param names.
-
-Expected support:
-
-- Keep generated file names short: `routes.json`, `routes.d.ts`.
-- Do not introduce names like `router-routes.json`.
-
----
-
-## 4. View Transition Enhancements
-
-### 4.1. Router transitions wait for `finished`
-
-Status: implementation differs from plan.
-
-File:
-
-```text
-src/core/router/transitions.js
-```
-
-Current behavior:
-
-The router awaits `transition.finished`.
-
-Plan expectation:
-
-Resolve route management on `transition.ready` to avoid blocking on long animations.
-
-Expected support:
-
-- Decide whether router should await `ready` or `finished`.
-- If switching to `ready`, still clear shared element names on `finished`.
-
-### 4.2. Transition event hooks are missing
-
-Status: enhancement.
-
-File:
-
-```text
-src/core/router/transitions.js
-```
-
-Expected support:
-
-```javascript
-router.on('transitionstart', handler);
-router.on('transitionend', handler);
-```
-
-Use cases:
-
-- Progress UI.
-- Analytics.
-- Debugging slow transitions.
-
----
-
-## 5. Event and Error Enhancements
-
-### 5.1. Event set is minimal
-
-Status: enhancement.
-
-File:
-
-```text
-src/core/router/intercept.js
-```
-
-Current events:
-
-```text
-found
-notfound
-error
-```
-
-Useful additions:
-
-```text
-before
-guard
-redirect
-start
-success
-finish
-transitionstart
-transitionend
-```
-
-Tests:
-
-- Events fire in documented order.
-- Redirect event includes from/to.
-- Error event includes destination URL.
-
----
-
-## 6. Security Enhancements
-
-### 6.1. Param validation helpers
-
-Status: enhancement.
-
-Files:
-
-```text
-src/core/router/match.js
-src/core/router/index.js
-```
-
-Need:
-
-Route params are untrusted strings. Add optional validation or parsing utilities.
-
-Example:
-
-```javascript
-router.register('/members/:member', 'page-member', {
-  params: {
-    member: /^\d+$/
-  }
-});
-```
-
-Expected support:
-
-- Invalid params produce notfound or error.
-- Validation failure can redirect.
-- Validation error payload includes the param name.
-
----
-
-## 7. Documentation Enhancements
-
-### 7.1. `docs/core/router/index.md` is stale
-
-Status: stale docs.
-
-File:
-
-```text
-docs/core/router/index.md
-```
-
-Problem:
-
-The docs mention APIs that do not exist in runtime:
-
-```javascript
-router.on('/dashboard', ...)
-router.render(...)
-```
-
-Expected support:
-
-- Rewrite docs to match `src/core/router/usage.md`.
-- Keep conceptual architecture separate from public API examples.
-
-### 7.2. Older docs use `router.on(pattern, handler)`
-
-Status: stale repo-wide docs.
-
-Files:
-
-```text
-docs/plan.md
-docs/library.md
-docs/library2.md
-docs/notes/20 - Internal API.md
-usages/index.md
-usages/server.md
-README.md
-```
-
-Expected support:
-
-- Update or explicitly mark old API as historical.
-- Prefer `router.register(pattern, handler, meta)` for route registration.
-- Reserve `router.on(type, callback)` for router events.
-
----
-
-## 8. Test Coverage Gaps
-
-### 8.1. Intercept tests are mostly simulated
-
-Status: weak coverage.
-
-File:
-
-```text
-tests/core/router/intercept.test.js
-```
-
-Needed coverage:
-
-- Mock `window.navigation`.
-- Verify `setup()` attaches one `navigate` listener.
-- Verify `destroy()` removes listeners.
-- Verify guard redirect calls `controller.redirect`.
-- Verify Safari fallback uses replace navigation.
-- Verify `found`, `notfound`, and `error` emit from actual handler flow.
-- Verify strict container guard throws when required container is missing.
-
-### 8.2. Declarative routing test manually mounts components
-
-Status: weak coverage.
-
-File:
-
-```text
-tests/core/router/declarative.test.js
-```
-
-Problem:
-
-The test manually creates and inserts the page element instead of exercising the full UI orchestrator through emitted router events.
-
-Expected support:
-
-- Drive a real `found` event.
-- Assert `ui.container` receives a route page.
-- Assert same-tag params update the existing instance.
-
-### 8.3. History wrapper tests are missing
-
-Status: missing coverage.
-
-File:
-
-```text
-tests/core/router/history.test.js
-```
-
-Needed coverage:
-
-- `navigate`
-- `replace`
-- `back`
-- `forward`
-- `go`
-- `current`
-- `entries`
-- `canBack`
-- `canForward`
-- no-window fallbacks
-
-### 8.4. Container registry tests are missing
-
-Status: missing coverage.
-
-File:
-
-```text
-tests/core/router/container.test.js
-```
-
-Needed coverage:
-
-- Register and retrieve.
-- Duplicate singleton throws.
-- Unregister only removes matching element.
-- CSS selector fallback works.
-- Invalid selector is ignored.
-- `clearContainers` clears map and observer.
-
-### 8.5. Sync and connection tests need grouped APIs
-
-Status: partial coverage.
-
-Files:
-
-```text
-tests/core/router/sync.test.js
-src/core/router/sync/tab.js
-src/core/router/sync/transport.js
-```
-
-Needed coverage:
-
-- `router.sync.start()` is idempotent.
-- `router.sync.stop()` removes handlers.
-- `router.sync.active()` reports state.
-- `router.sync.close()` closes the channel.
-- `router.links.add()` returns a disposer.
-- `router.links.remove()` closes one active connection.
-- `router.links.clear()` closes all active connections.
-
-### 8.6. Type tests are missing
-
-Status: missing coverage.
-
-Files:
-
-```text
-tests/types/router-types.test.ts
-types/core/router/index.d.ts
-routes.d.ts
-```
-
-Needed coverage:
-
-- `router.register` handler/tag/meta shapes.
-- `router.on` event payloads.
-- `router.match` async result.
-- `router.nav.to` chain.
-- Guard and miss grouped APIs.
-- Sync grouped APIs.
-- Container APIs.
-- Connection APIs.
-- Generated route params from `routes.d.ts`.
-- `npm run check` or equivalent one-word command runs the type tests.
-
----
-
-## 9. Suggested Implementation Order
-
-1. Fix the not-found `url` runtime bug.
-2. Rewrite `types/core/router/index.d.ts`.
-3. Add `check` tooling and router type tests.
-4. Resolve route handler function ambiguity.
-5. Generate `routes.d.ts`.
-6. Add route segment and container validation to `scan`.
-7. Add history and container tests.
-8. Expand sync and connection tests for grouped APIs.
-9. Add route param/query/hash support.
-10. Decide whether transitions should await `ready` or `finished`.
-11. Rewrite stale `docs/core/router/index.md`.
-
-## 10. Done Criteria
-
-This missing-support list is complete when:
-
-- Router type declarations match runtime.
-- The not-found path emits a valid URL.
-- Public docs no longer mention missing APIs.
-- Route handler semantics are explicit.
-- Heavy route extraction, validation, and generation live in `tools/`.
-- Generated route files use short names such as `routes.json` and `routes.d.ts`.
-- Declarative UI routes are tested through the real orchestration path.
-- History, container, sync, and connection APIs have focused tests.
-- Query/hash/param casting enhancements are either implemented or clearly deferred.