docs: update TODO with completed audit fix checklist items

fingersandmind · fingersandmind · commit 69e4f7ea260d · 2026-03-18T01:31:45.000+08:00
diff --git a/TODO.md b/TODO.md
@@ -28,6 +28,7 @@ This document contains all identified issues, improvements, and enhancements for
 20. [Web Components](#web-components)
 21. [Code Quality](#code-quality)
 22. [Future Features](#future-features)
+23. [Router & Runtime Fixes (Phased)](#router--runtime-fixes-phased)
 
 ---
 
@@ -1158,6 +1159,134 @@ This document contains all identified issues, improvements, and enhancements for
 - **P2 (Medium)**: Improvements, minor bugs, technical debt
 - **P3 (Low)**: Nice-to-haves, future features
 
+## Router & Runtime Fixes (Phased)
+
+Identified from a full audit of the router (`packages/router/src/client.ts`), signals runtime (`packages/stx/src/signals.ts`), hydration (`packages/stx/src/hydration.ts`), and template processing (`packages/stx/src/process.ts`). Organized into phases for incremental implementation and testing.
+
+### Phase 1: Router Critical Fixes
+
+These directly affect user experience and cause visible bugs.
+
+#### 1.1 Race Condition — Cancel In-Flight Navigation
+**File:** `packages/router/src/client.ts` — `navigate()`
+- [x] Track current in-flight fetch with an `AbortController`
+- [x] Abort previous fetch when a new `navigate()` is called
+- [x] Reset `isNavigating` properly on abort
+- [x] Ensure aborted navigations don't trigger `swap()`
+
+#### 1.2 Prefetch Cache Key Mismatch
+**File:** `packages/router/src/client.ts` — prefetch handler + `navigate()`
+- [x] Normalize cache keys to pathname only (strip query/hash) in the prefetch `mouseover` handler
+- [x] Ensure `navigate()` and prefetch use the same cache key format
+- [x] Add helper like `normalizePathname(url)` to avoid duplication
+
+#### 1.3 Rapid Back/Forward Navigation
+**File:** `packages/router/src/client.ts` — `popstate` handler
+- [x] Cancel any in-flight navigation on popstate (reuse AbortController from 1.1)
+- [x] Reset `isNavigating` so the new popstate navigation can proceed
+- [x] Ensure the last popstate always wins
+
+#### 1.4 Active Link Management Consolidation
+**File:** `packages/router/src/client.ts` — `updateNav()` + `updateActiveLinks()`
+- [x] Merge `updateNav()` and `updateActiveLinks()` into a single function
+- [x] Use consistent matching: exact equality for `exactActiveClass`, `startsWith()` for `activeClass`
+- [x] Normalize trailing slashes before comparison (`/page` and `/page/` should match)
+- [x] Remove old `updateNav()` and update all call sites
+
+#### 1.5 Cache TTL
+**File:** `packages/router/src/client.ts` — cache object
+- [x] Store timestamp alongside cached HTML: `cache[key] = { html, ts }`
+- [x] Check TTL (5 minutes) before serving from cache in `navigate()`
+- [x] Evict expired entries on access
+- [x] Update prefetch to use the same cache structure
+
+---
+
+### Phase 2: Router Medium Fixes
+
+#### 2.1 Scroll Restoration on Back/Forward
+**File:** `packages/router/src/client.ts` — `navigate()` + `popstate` handler
+- [x] Save `{ scrollX, scrollY }` in `history.replaceState()` before navigating away
+- [x] Read scroll position from `event.state` on popstate
+- [x] Restore scroll position after swap completes
+
+#### 2.2 Meta Tag Swapping
+**File:** `packages/router/src/client.ts` — `swap()` → `doSwap()`
+- [x] Collect swappable meta tags from new page (`name`, `property`, `http-equiv`)
+- [x] Replace matching meta tags in current `<head>`, add new ones, remove stale ones
+- [x] Preserve persistent meta tags (`charset`, `viewport`)
+
+#### 2.3 URL Normalization Helper
+**File:** `packages/router/src/client.ts`
+- [x] Create `normalizePath(path)` that strips trailing slash (except `/`)
+- [x] Apply in `shouldIntercept()`, active link functions, and cache lookups
+- [ ] Handle edge cases: encoded characters, double slashes
+
+---
+
+### Phase 3: Signals Runtime Fixes
+
+#### 3.1 `useSearchParams` Listener Leak
+**File:** `packages/stx/src/signals.ts` — `useSearchParams()`
+- [x] Store references to `popstate` and `stx:navigate` listeners
+- [x] Wrap removal in `onDestroy()` callback
+- [ ] Verify cleanup is called on component unmount
+
+#### 3.2 Query Cache Bounds
+**File:** `packages/stx/src/signals.ts` — `_queryCache`
+- [x] Add max cache size constant (50 entries)
+- [x] Evict oldest entry (by insertion order) when limit is reached
+- [x] Keep existing `setTimeout`-based TTL cleanup
+
+#### 3.3 `@html` Directive Sanitization
+**File:** `packages/stx/src/signals.ts` — `@html` handler
+- [x] Sanitize output by stripping `<script>` tags and `on*` event handlers
+- [ ] Document XSS risk clearly (similar to Vue's `v-html` warning)
+- [ ] Consider optional raw mode via a `@html.raw` modifier
+
+---
+
+### Phase 4: Hydration Fixes
+
+#### 4.1 Timeout Cleanup on Success
+**File:** `packages/stx/src/hydration.ts` — `hydrate()`
+- [x] Capture the `setTimeout` return value
+- [x] `clearTimeout()` after `Promise.race` resolves successfully
+
+#### 4.2 JSON.parse Safety
+**File:** `packages/stx/src/hydration.ts` — props parsing
+- [x] Wrap `JSON.parse(propsAttr)` in try-catch
+- [x] Fall back to `{}` on parse failure
+- [x] Log warning with element context for debugging
+
+#### 4.3 Checksum Mismatch Handling
+**File:** `packages/stx/src/hydration.ts` — state restoration
+- [ ] Add `strict` option to `extractState()` (currently a standalone export without options access)
+- [ ] Throw error on checksum mismatch in strict mode
+- [ ] Keep warning-only behavior in development mode
+
+---
+
+### Phase 5: Template Processing Safety
+
+#### 5.1 Expression Evaluation Guard
+**File:** `packages/stx/src/process.ts` — `new Function()` call sites
+- [x] Audit all `new Function()` call sites — all server-side calls already use `createSafeFunction` with `isExpressionSafe()` guard
+- [x] Client-side `new Function()` calls in signals runtime are template-author expressions (same model as Vue/Svelte), not user input — no guard needed
+- [ ] Add tests for known-dangerous expressions
+
+---
+
+### Implementation Notes
+
+- Each phase should be built and tested independently
+- Rebuild the `stx` binary (`bun run build` from stx root) after each phase
+- Test against hoodies-ui after each phase to verify no regressions
+- Phase 1 is the highest priority — these are bugs users will hit immediately
+- Phases 3-5 are lower urgency but prevent subtle production issues
+
+---
+
 ### Contributing
 
 When working on items:
@@ -1169,5 +1298,5 @@ When working on items:
 
 ---
 
-*Last updated: December 2, 2024*
+*Last updated: March 18, 2026*
 *Generated from codebase analysis*
