@kudzujs/core 0.7.8 → 0.7.10

package/GOAL_A.md

@@ -1,187 +1,116 @@
-# Goal A: Static Business Applications
+# Goal A: Static Application Lifecycles And Opt-In Navigation
 
-Goal A makes Kudzu sufficient for a conventional business application, starting with a complete commerce journey and leaving a clean path to realtime dashboards. It must preserve Kudzu's static HTML, zero-JavaScript static routes, direct DOM updates, and lack of a browser component tree.
+Goal A is a completed compiler-capability milestone for general React-to-static migration. It proves that ordinary React-shaped applications can retain shared layouts, route lifetimes, asynchronous workflows, and optional same-document navigation while every route remains a complete static document.
 
-This is the implementation contract. `MIGRATION_ROADMAP.md` remains the source of truth for compiler invariants and the fixture-first workflow.
+The six-route commerce journey is one executable validation fixture. It is not Kudzu's product scope, a commerce API, or the priority model for future development. [`MIGRATION_ROADMAP.md`](./MIGRATION_ROADMAP.md) is the source of truth for product direction and future fixture-driven work.
 
-The benchmark runner, framework fixtures, generated artifacts, and raw arrays are retained as local validation material and are intentionally excluded from the repository and npm package. Published numbers below are a dated product record rather than a reproducible public benchmark bundle. The matched versions were Kudzu 0.5.10, React 19.2.8 with Vite, Next.js 16.2.11, Nuxt 4.5.0 with Vue 3.5.40, and SvelteKit 2.70.1 with Svelte 5.56.7.
+## Status
 
-## Implementation Status
+Goal A is complete for explicitly configured emitted-route groups with shared layouts. Implemented capabilities include:
 
-**Goal A is complete for one explicitly configured emitted-route group with one shared layout.** Complete standalone documents, exact and runtime-parameter navigation, native fallback, persistent layout state/effects, disposable route state/effects, optimistic workflows, desktop/mobile performance gates, and the dashboard expansion seam are covered. Multiple independent shared-layout groups and conditional/keyed DOM-owned effects within layout and route lifetimes were added post-Goal-A.
+- complete standalone documents for exact and runtime-parameter routes;
+- native navigation fallback and opt-in same-document navigation;
+- persistent layout state and effects with disposable route state and effects;
+- conditional and keyed DOM ownership within layout and route lifetimes;
+- validated finite prefetch caching for eligible links;
+- optimistic success, rejection, rollback, and stale-write suppression;
+- multiple independent shared-layout groups with overlap diagnostics.
 
-- **Phase 1 complete**: a local six-route commerce fixture, locked React/Next/Nuxt/SvelteKit comparisons, and a reproducible artifact/build/Chrome runner validate the implementation.
-- **Phase 2 complete**: effects inside conditional ranges and supported keyed row components mount with their DOM owner, unsubscribe and clean up on removal, and remount without affecting effect-free output.
-- **Phase 3 complete**: page-exported layouts render complete documents with compiler-owned route boundaries, collision-free layout/route IDs, and state/effect ownership metadata. Effects remain document effects and client navigation is unchanged.
-- **Phase 4 route/layout effects implemented**: layout effects mount once per document session, route effects remount after awaited route cleanup, and primitive dependency subscriptions exist only while their lifetime is mounted. Conditional/keyed effects use per-lifetime owner registries; route registries are fresh on cached revisits. Direct primitive keyed-item properties rerun only changed rows; reorder does not rerun and key changes remount. Disposed effect setters and queued commits are inactive.
-- **Phase 4 document prefetch implemented**: visible, near-visible, hovered, or focused eligible group anchors prefetch and validate complete documents without importing target capabilities. The finite in-memory full-URL cache removes the measured product-cart HTML RTT while preserving retry and native fallback.
-- **Phase 5 complete**: matched async cart success/rejection flows prove immediate optimistic updates, duplicate prevention, accessible errors, rollback, route-local reset, and stale-write suppression without new framework APIs.
-- **Phase 6 expansion probe complete**: one layout-owned mock `EventTarget` stream and one route-owned imperative chart stub use existing effects and a relative TypeScript helper across repeated navigation, with exact listener and disposal assertions. This proves only the compatibility seam; Kudzu does not provide telemetry or chart support.
-- **Desktop and mobile gates complete**: both profiles use seven rotating fresh Chrome runs per target and record zero cold/warm CLS.
+Future migration features do not extend Goal A as a product vertical. They return to the migration roadmap and begin with a failing conventional React fixture.
 
-The capability-local prefetch/cache increased the commerce navigation asset from 1,887 B to 2,306 B gzip (+419 B). Routes outside the configured group remain unchanged.
+## Capability Contract
 
-In the focused effect-enabled navigation fixture, mount support adds 171 B gzip to the same-route navigation asset and 37 B gzip to the shared runtime. The active-context guard adds 18 B gzip to `kudzu-effect.js` (257 B total); cache-safe route entries are 1,059-1,116 B gzip. The effect-free commerce specialization remains byte-for-byte unchanged.
-
-The post-Goal-A runtime-pattern matcher increases the exact-only commerce navigation asset from 2,306 B to 2,461 B gzip. The mixed exact/runtime navigation fixture emits a 3,105 B gzip navigation asset and a 703 B gzip cache-safe parameter initializer.
-
-The post-Goal-A multiple-group fixture emits a 7,448 B raw / 3,099 B gzip (`gzip -9`) mixed runtime/effect group asset, including one native exclusion for an overlapping ungrouped exact route, and a separately specialized 5,681 B raw / 2,448 B gzip exact effect-free group asset. These measurements do not revise the historical Goal A benchmark.
-
-In a matched one-effect navigation build with the same conditional capability, moving the effect from the route body into the conditional owner changes the route effect entry from 2,181 B raw / 1,036 B gzip to 4,135 B raw / 1,807 B gzip (`+1,954 B` raw / `+771 B` gzip). Owner-hook unsubscription changes the shared runtime from 1,347 B raw / 718 B gzip to 1,459 B raw / 732 B gzip (`+112 B` raw / `+14 B` gzip). Top-level-only and effect-free navigation builds retain their smaller generators.
-
-In matched state-only and item-property keyed-row builds, targeted notification adds 821 B raw / 255 B gzip across the route effect entry, shared runtime, and list runtime. Builds without item-property dependencies retain their previous generated path.
-
-In the latest matched 1,000-row keyed-effect runtime microbenchmark, Kudzu measured 3.6 ms selected-row cleanup/update/setup, 2.4 ms unrelated-field update, and 8.8 ms reorder after all rows and effects were ready. React CSR measured 9.8, 5.9, and 16.8 ms; Vue measured 5.8, 2.4, and 10.5 ms; and Svelte measured 5.7, 4.1, and 58.1 ms. Targeted changed-root notification avoids an extra O(n) effect-record scan; list reconciliation remains O(n). Kudzu emits initial rows while these framework fixtures are CSR, so their JavaScript, output, and build observations are not architecture-equivalent claims.
-
-A 0.6.4 release-tree desktop rerun of the matched six-route commerce fixture measured Kudzu at 486.8 ms build, 35,355 deploy bytes, 7,334 B gzip product JavaScript, 332/156 ms cold/warm LCP, 122.6 ms startup task, 4.8 ms interaction, and 5.6 ms product-cart navigation. React measured 545.4 ms build, 61,464 B gzip product JavaScript, 332/264 ms LCP, 179.9 ms startup task, 10.2 ms interaction, and 9.9 ms navigation. Kudzu built 10.7% faster and its top-level-only fixture retained byte-identical deploy, product-graph, and navigation-asset sizes after navigation-owned effects were added. Raw arrays and the consolidated report are retained under the local demo benchmark workspace.
-
-The Phase 6 chart probe's complete initial module graph is 11,902 B raw / 5,331 B gzip. It adds no framework API or package and does not change the commerce benchmark fixture.
-
-The app-mode Kudzu fixture emits 34,879 deploy bytes. Its product route loads 15,800 raw / 7,215 gzip bytes of initial JavaScript, including the 2,306 B gzip navigation capability. Routes outside a configured application group retain the static zero-JavaScript and byte-for-byte gates.
-
-The latest matched run used seven rotating production builds and seven rotating fresh Chrome profiles per target at 4x CPU slowdown, 100 ms latency, and 200 KiB/s download. Raw local results retain the full arrays, artifact groups, environment, and limitations.
-
-| Target | Product JS gzip | Cold transfer | Cold LCP | Warm LCP | Cold task | Cold heap | Interaction | Product-cart |
-|---|---:|---:|---:|---:|---:|---:|---:|---:|
-| Kudzu | 7,215 B | 34,809 B | 324 ms | 140 ms | 103.3 ms | 648,844 B | 3.7 ms | 5.7 ms |
-| React + Vite | 61,464 B | 202,842 B | 324 ms | 232 ms | 160.0 ms | 1,062,520 B | 10.5 ms | 8.3 ms |
-| Next.js | 190,090 B | 546,581 B | 316 ms | 156 ms | 357.7 ms | 2,157,020 B | 11.4 ms | 26.9 ms |
-| Nuxt | 67,620 B | 195,953 B | 320 ms | 204 ms | 205.1 ms | 1,721,348 B | 3.9 ms | 33.0 ms |
-| SvelteKit | 32,473 B | 90,929 B | 340 ms | 172 ms | 125.8 ms | 999,496 B | 4.7 ms | 20.3 ms |
-
-The navigation capability initially measured 128.7 ms because it paid one HTML round trip. Validated near-viewport document prefetch reduced the final seven-run median to 5.7 ms while Kudzu still transferred 62% less than SvelteKit and 83% less than React on the cold product load. A progressive-HTML grid shift found by the benchmark was fixed in the matched CSS; 30 focused Kudzu profiles and the final desktop/mobile cross-framework runs then recorded zero cold and warm CLS.
-
-The original final table measured 460.8 ms for Kudzu and 429.5 ms for React, and a focused follow-up confirmed a 6-7% loss primarily from TypeScript ESM/compiler startup. A post-gate startup fix now enables Node's native module compile cache before lazily loading the compiler. The first empty-cache build measured 541.4 ms against the previous 547.6 ms path; after one warm-up, 31 interleaved artifact-clean builds measured Kudzu at 425.8 ms and React at 483.4 ms, making Kudzu 11.9% faster in that run. Cache-disabled and cached builds emit byte-for-byte identical output.
-
-The mobile profile uses a 390x844 viewport, 6x CPU slowdown, 150 ms latency, and 150 KiB/s download. Kudzu measured 420 ms cold LCP, 220 ms warm LCP, 5.6 ms interaction, 8.7 ms product-cart navigation, 4.1 ms optimistic rejection, and 158 ms rollback/error.
-
-## Product Target
-
-A user can build and deploy this flow without React, a VDOM, hydration, or a request server:
+A migrated application may use familiar function components, props, children, JSX, hooks, conditions, collections, and handlers while Kudzu emits:
 
 ```text
-home -> category -> product -> cart -> checkout -> account
+complete static document
+  -> optional persistent layout range
+  -> replaceable route range
+  -> only the route-specific ESM capabilities used
 ```
 
-The reference fixture must cover:
+The capability must preserve:
 
-- complete indexable HTML for public pages;
+- complete indexable HTML for every route;
 - direct entry, reload, back, forward, query strings, and base paths;
-- product filters stored in the URL;
-- product variants and quantity as route state;
-- cart and session information shared by an application layout;
-- async loading, empty, error, retry, and cancellation behavior;
-- optimistic cart updates with rollback after a rejected request;
-- accessible focus, title, scroll, and announcement behavior after navigation;
+- URL, route, and shared-layout state with explicit lifetimes;
+- async loading, empty, error, retry, cancellation, and stale-result handling;
+- optimistic updates, rejection, rollback, and accessible status output;
+- focus, title, scroll, and announcement behavior after enhanced navigation;
 - ordinary document navigation when JavaScript is absent, late, or fails.
 
-The fixture is a generic executable requirement, not a reusable commerce package. Kudzu should add only compiler features that the reduced fixture proves necessary.
+## Invariants
 
-## Runtime Model
+- Native `<a>` navigation is the default.
+- Navigation enhancement is explicit per emitted route group.
+- Every enhanced route also exists as a complete document.
+- Static routes emit zero client JavaScript.
+- Interactive routes emit only the capabilities they use.
+- React, a VDOM, hydration, retained browser components, and browser component rerenders remain forbidden.
+- External, download, modified-click, reload, malformed, unsupported, and ungrouped links keep native behavior.
+- A failed or superseded transition cannot commit stale route state.
+- No separate fragment protocol, router API, cache, or scheduler is added without a measured fixture requirement.
 
-Kudzu continues to emit a complete document for every route. Native `<a>` navigation remains the default. An explicitly configured application route group may enhance eligible same-origin links after the initial document has loaded.
+## Ownership Model
 
-```text
-Static document
-  -> optional persistent layout
-  -> replaceable route range
-  -> capability-specific route ESM
-```
-
-The implementation must use the smallest measured mechanism. A separate fragment format, prefetcher, cache, or router API is not required unless the fixture and browser measurements show that parsing the existing document output is insufficient.
-
-Navigation enhancement must not become a general SPA runtime:
+Goal A adds explicit ownership, not a state library or application runtime.
 
-- no VDOM, hydration, retained component tree, or component rerenderer;
-- no global router on routes outside an opted-in application group;
-- no interception of external, download, modified-click, reload, or explicitly native links;
-- no client-only route as the sole representation of indexable content;
-- no duplicated source component execution in the browser.
-
-## Ownership And Cleanup
-
-Goal A needs explicit ownership, not a new state library:
-
-| Owner | Lifetime | Examples |
+| Owner | Lifetime | General examples |
 |---|---|---|
-| Document | Full document | global listeners and document exit cleanup |
-| Layout | Enhanced navigation session | user summary, cart count, persistent connection |
-| Route | Current route range | filters, selected variant, request, subscription |
-| DOM range | Conditional or keyed item | listener, effect, imperative child resource |
-
-Removing an owner must dispose its effects, listeners, pending work, and descendant registrations exactly once. A failed or superseded navigation must not commit stale route state. Full document navigation remains the recovery path.
+| Document | Full document | global listeners and document-exit cleanup |
+| Layout | Enhanced navigation session | user summary, navigation state, shared resource |
+| Route | Current route range | filters, requests, subscriptions, pending work |
+| DOM range | Conditional or keyed item | listener, effect, ref, imperative child resource |
 
-High-frequency data is deliberately not a Goal A state feature. A later dashboard can keep WebSocket parsing, telemetry buffers, charts, maps, and editors in Workers or imperative browser modules while Kudzu owns their route or layout lifecycle.
+Removing an owner disposes its effects, listeners, pending work, and descendant registrations exactly once. A non-persisted document exit cleans route ownership before layout ownership. A BFCache-persisted document retains live ownership for restoration.
 
-## Delivery Order
+## Validation Fixture
 
-Each phase starts with one failing fixture and ends with correctness, browser, size, and build measurements.
+The reduced commerce journey remains a useful integration fixture because it exercises the neutral capability contract in one flow:
 
-1. **Benchmark harness**: freeze the commerce journey, network profiles, framework versions, generated artifacts, and measurement scripts before optimizing Kudzu.
-2. **Owned effects**: complete cleanup for conditional ranges and keyed items using the existing mount and unmount hooks. **Complete.**
-3. **Layout and route scopes**: retain only declared layout state and dispose route-owned behavior on every completed transition. **Compiler ownership complete; transition behavior belongs to Phase 4.**
-4. **Opt-in navigation**: support eligible links, history, aborts, stale responses, focus, scroll, metadata, and native fallback. **Complete for emitted exact/runtime-parameter routes and layout/route effects, including conditional/keyed DOM ownership.**
-5. **Business workflows**: close only fixture-proven gaps in forms, async requests, optimistic updates, and diagnostics. **Complete for the matched cart success/rejection flow.**
-6. **Expansion probe**: prove that one persistent mock stream and one imperative chart stub can mount, update, navigate, and dispose without adding a component runtime. **Compatibility probe complete; real telemetry and chart engines remain outside Goal A.**
-
-Do not begin a later phase while the current phase has an unexplained correctness or performance regression.
+```text
+home -> category -> product -> cart -> checkout -> account
+```
 
-## Performance Comparison
+Its product filters prove URL state, variants prove route state, cart/session data proves layout state, rejected updates prove rollback, and product-to-cart transitions prove enhanced navigation. These nouns belong to the fixture only; Kudzu must not add commerce-specific APIs or architecture.
 
-The matched comparison set is:
+Other applications should validate the same capabilities with domain-appropriate fixtures such as documentation, content, administration, forms, and dashboards.
 
-- Kudzu from the previous completed phase;
-- React with an equivalent production static deployment;
-- Next.js static export;
-- Vue/Nuxt static generation;
-- Svelte/SvelteKit static generation;
-- hand-written HTML and DOM JavaScript where it provides a useful lower bound.
+## Performance Protocol
 
-Every implementation must render the same initial content and provide the same tested behavior. Results that omit initial HTML, navigation semantics, error handling, or accessibility are reported separately and cannot be presented as direct wins.
+Matched comparisons may include React/Vite, static exports from established frameworks, and hand-written HTML/DOM code as a lower bound. Every target must provide the same initial content, behavior, errors, navigation semantics, and accessibility before results are compared directly.
 
-Use identical content, CSS, local images, API payloads, cache state, browser version, CPU profile, and network profile. Record at least:
+Record at least:
 
-- deploy artifact bytes and initial raw/gzip JavaScript;
-- HTML, CSS, image, and route payload transfer bytes;
+- deploy bytes and initial raw/gzip JavaScript;
+- HTML, CSS, media, and route transfer bytes;
 - clean build median;
-- cold and warm LCP, CLS, and INP;
-- hydration or startup main-thread work;
-- cold and warm route transition time;
-- cart update and rollback latency;
-- browser heap after initial load and repeated navigation;
-- duplicate listeners, unfinished requests, and lifecycle leaks.
-
-Production builds receive one warm-up and at least seven interleaved runs. Keep raw results and record the median; use additional runs when ranges overlap or a result controls an architectural decision.
-
-## Performance Gates
-
-Goal A is not complete unless:
-
-- static routes still emit zero JavaScript;
-- routes outside an application group remain byte-for-byte unaffected by navigation support;
-- an application route ships only the layout and route capabilities it uses;
-- no hydration task or browser component tree is introduced;
-- repeated navigation leaves no growing listener, request, state, DOM, or heap ownership;
-- Kudzu has no unexplained material regression against its previous phase;
-- material losses against the fastest matched framework are profiled and either fixed or documented as an explicit product tradeoff;
-- performance claims include fixture limitations and do not compare unequal initial content as equivalent.
+- cold and warm LCP, CLS, INP, startup work, and heap;
+- state update, optimistic rejection, rollback, and route transition latency;
+- repeated-navigation listener, request, state, DOM, and heap ownership.
 
-For browser timings, treat a repeatable median change above 5% as material. Deterministic byte growth is reviewed regardless of percentage. Measurement noise is not a reason to optimize: repeat the interleaved run first.
+Production builds receive one warm-up and at least seven interleaved runs. Browser comparisons use rotating fresh profiles and additional runs when ranges overlap. A repeatable browser median change above 5% is material; deterministic byte growth is always reviewed.
 
-When a gate fails, stop feature work, reduce the cause, fix the shared path, rerun `npm run check`, `npm test`, and the affected benchmark, then continue. Do not hide regressions with prefetching, omitted content, or a weaker competitor fixture.
+## Regression Gates
 
-## Completion Definition
+- Static routes still emit zero JavaScript.
+- Routes outside configured groups remain unaffected by navigation support.
+- No hydration task or retained component tree is introduced.
+- Repeated navigation leaves no growing ownership.
+- Material regressions against Kudzu's previous path are explained and fixed or recorded as explicit tradeoffs.
+- Competitor comparisons disclose unequal rendering architecture and fixture limitations.
+- `npm run check`, `npm test`, and applicable browser checks pass.
 
-Goal A is complete when the commerce fixture passes direct-load and enhanced-navigation browser tests, every lifecycle owner cleans up correctly, static fallback behavior remains intact, and the benchmark gates above pass on both desktop and mobile profiles.
+## Historical Validation Record
 
-The final validation record must retain the generated artifacts, framework versions, commands, raw measurements, medians, known losses, and deliberate limits.
+The completed commerce and lifecycle measurements remain dated evidence, not current product requirements. The latest retained records include complete desktop/mobile navigation runs, zero cold/warm CLS, exact cleanup counters, capability byte deltas, and matched framework comparisons. Release notes and repository history retain version-specific numbers; new measurements must record their source revision, fixture, browser, hardware, raw arrays, and limitations.
 
 ## Non-Goals
 
 - A default SPA router.
-- Arbitrary React application or package compatibility.
-- Runtime component registration or client component rendering.
-- Request-time SSR, server actions, or a hidden server.
-- A charting, mapping, telemetry, virtual-grid, or visual-editor engine.
-- A custom widget marketplace or plugin security model.
-- Winning every synthetic metric at the cost of correctness, accessibility, or deploy output.
+- A commerce framework or reusable commerce package.
+- Arbitrary React package compatibility.
+- Runtime component registration, hydration, or client component rendering.
+- Request-time SSR, server actions, or a hidden application server.
+- Charting, mapping, telemetry, virtual-grid, or editor engines.
+- Winning synthetic metrics by omitting equivalent content, behavior, accessibility, or fallback.

package/GOAL_B.md

@@ -1,44 +1,28 @@
-# Goal B: Static Realtime Dashboards
+# Goal B: Relative TypeScript Worker Capability Proof
 
-Goal B makes Kudzu sufficient for a ThingsBoard-shaped realtime device dashboard without turning Kudzu into a stream runtime, widget framework, or server platform. It preserves complete static documents, zero-JavaScript routes that use no browser capabilities, direct DOM ownership, native navigation fallback, and the absence of React, a VDOM, hydration, or a retained browser component tree.
+Goal B is a completed cross-application compiler-capability proof for one browser-only pattern used by realtime React-shaped applications: a route-owned relative TypeScript module Worker created and cleaned up from an inline `useEffect`.
 
-`MIGRATION_ROADMAP.md` remains the source of truth for compiler invariants and fixture-first development. This document is the implementation contract for realtime dashboard work.
+The realtime dashboard is a stress and conformance fixture. It is not a Kudzu product vertical, dashboard API, stream runtime, widget framework, server platform, or claim of ThingsBoard compatibility. [`MIGRATION_ROADMAP.md`](./MIGRATION_ROADMAP.md) remains the source of truth for future fixture-driven migration work.
 
-## Product Target
+## Status
 
-A user can statically deploy this flow:
+The exact relative TypeScript Worker capability is implemented and verified. Kudzu recognizes one statically analyzable constructor form, emits its validated module graph separately, rewrites the URL for the configured base, ties creation and termination to effect ownership, and adds no Worker bytes to routes that do not use it.
 
-```text
-dashboard -> devices -> device detail -> alarms -> settings
-```
+Further Worker, transport, effect, or React compatibility work must begin with a reduced conventional React migration fixture that fails.
 
-The first vertical slice is deliberately smaller:
+## Capability Target
 
-```text
-plain route <-> realtime device dashboard
-```
-
-The dashboard receives a logical 1,000 telemetry samples per second, keeps a bounded history in a module Worker, downsamples it, and updates one imperative chart without routing samples through `useState()`.
-
-## Runtime Model
+The focused proof uses one Worker-enabled route, one plain companion route, and one unrelated static route:
 
 ```text
-Complete static dashboard shell
-  -> route-specific effect ESM
-  -> route-owned module Worker
-  -> bounded telemetry buffer and downsampling
-  -> batched imperative chart updates
+plain route <-> Worker-enabled route
 ```
 
-Kudzu state is for low-frequency UI state such as selected device, time range, filters, tabs, connection status, alarm status, and widget configuration. High-frequency samples belong in a Worker or imperative browser module.
-
-The Worker is a capability, not a framework runtime. Routes that do not create one must not load its graph. Static routes must remain JavaScript-free.
+The stress fixture generates a logical 1,000 samples per second, keeps bounded history in a module Worker, downsamples it, and updates one imperative chart. Telemetry and chart details validate Worker isolation, throughput, and ownership; they are not Kudzu product features or advice to rewrite ordinary declarative UI imperatively.
 
-## Milestone 1: Relative TypeScript Workers
+## Supported Form
 
-Status: implemented and verified. The compiler recognizes only the exact inline-effect form below, emits its validated graph separately, rewrites the constructor to the base-aware same-origin asset, and leaves routes without this capability on their existing output paths.
-
-Support this exact shape inside a compiled inline `useEffect` callback:
+The Worker must be constructed directly inside a compiled inline effect:
 
 ```tsx
 useEffect(() => {
@@ -47,13 +31,13 @@ useEffect(() => {
     { type: "module" },
   )
 
-  const onMessage = (event: MessageEvent<ChartFrame>) => chart.render(event.data)
+  const onMessage = (event: MessageEvent<Frame>) => resource.render(event.data)
   worker.addEventListener("message", onMessage)
 
   return () => {
     worker.removeEventListener("message", onMessage)
     worker.terminate()
-    chart.dispose()
+    resource.dispose()
   }
 }, [])
 ```
@@ -63,87 +47,67 @@ Compiler requirements:
 - accept only an unshadowed `Worker` with `new URL(relativeLiteral, import.meta.url)` and literal `{ type: "module" }`;
 - resolve one `.worker.ts` entry under project source and bundle its relative TypeScript graph separately from window code;
 - emit deterministic content-hashed ESM under `assets/workers` and rewrite the constructor to the base-aware emitted URL;
-- reject package imports, JSX, TypeScript import-equals declarations, dynamic imports, `require()`, paths outside source, malformed options, and unsupported Worker forms with source locations;
+- reject package imports, JSX, import-equals declarations, dynamic imports, `require()`, paths outside source, malformed options, and unsupported Worker forms with source locations;
 - reject ordinary runtime imports or re-exports of `.worker.ts`; type-only imports may erase normally;
-- do not mark Worker files as navigation capability scripts or import them into the window;
-- create the Worker only when the owning effect mounts;
-- preserve byte-for-byte generated shared/list/effect paths for builds without relative TypeScript Workers where practical;
-- reject generated/public asset collisions instead of silently overwriting output.
+- never mark Worker files as document capability scripts or import them into the window;
+- create the Worker only when its owning effect mounts;
+- preserve zero-cost exclusion for builds without relative TypeScript Workers;
+- reject generated/public asset collisions.
 
-Worker construction inside imported helpers or imported keyed-row effects, `SharedWorker`, classic workers, inline Blob workers, and arbitrary dynamic Worker URLs are outside Milestone 1. Imported keyed rows must move Worker ownership to a directly compiled page or local component effect so lexical global analysis remains tied to the original source tree.
+Worker construction in imported helpers or imported keyed-row effects, `SharedWorker`, classic workers, Blob workers, arbitrary dynamic URLs, and package runtime graphs remain outside this completed capability.
 
 ## Ownership
 
-| Owner | Lifetime | Dashboard responsibility |
+| Owner | Lifetime | Capability responsibility |
 |---|---|---|
-| Document | Full document | authentication expiry and global diagnostics |
-| Layout | Enhanced navigation session | tenant session or shared transport |
-| Route | Current dashboard/device | Worker, telemetry subscription, request cancellation |
-| DOM range | Current widget | chart, gauge, map, table, animation frame |
-| Worker | Explicit owner cleanup | parsing, bounded buffering, aggregation, downsampling |
+| Document | Full document | global diagnostics and document-exit cleanup |
+| Layout | Enhanced navigation session | explicitly shared browser resource |
+| Route | Current route range | Worker, subscription, request cancellation |
+| DOM range | Connected conditional/keyed range | imperative resource and animation work |
+| Worker | Explicit owner cleanup | parsing, bounded buffering, aggregation |
 
-Leaving a route must remove message listeners, stop chart work, terminate its Worker, and invalidate stale UI writes before another route mounts. BFCache-preserved documents must retain their live ownership until a real document exit.
+On an enhanced same-document transition, route cleanup removes listeners, stops imperative work, terminates its Worker, and invalidates stale UI writes before the next route mounts. Non-persisted document exit performs cleanup; a BFCache-persisted document retains live ownership for restoration.
 
 ## Fixture Contract
 
-The first fixture must provide:
+The capability fixture proves:
 
-- one complete realtime dashboard document and one complete plain document in an opt-in navigation group;
+- one complete Worker-enabled document and one complete plain document in an opt-in navigation group;
 - one unrelated static route with zero JavaScript;
 - a relative TypeScript Worker importing at least one relative helper;
-- a fixed-capacity ring buffer with deterministic eviction;
-- logical 1,000 samples/second input in batches rather than a 1 ms browser timer;
-- bounded downsampled frames delivered at no more than display cadence;
-- one imperative canvas or DOM chart updated without sample-level Kudzu setters;
-- direct load, dashboard-to-plain navigation, back/forward, and repeated cached revisits;
-- exact counters for Worker starts, terminations, messages, renders, listeners, and stale post-cleanup work;
+- bounded deterministic buffering and batched sample generation;
+- bounded frames delivered no faster than display cadence;
+- one imperative resource updated without sample-level Kudzu setters;
+- direct load, enhanced navigation, back/forward, and repeated cached revisits;
+- exact starts, terminations, messages, renders, listeners, disposal, and stale-write counters;
 - native document fallback when JavaScript or Worker creation fails.
 
-## Acceptance Criteria
-
-- the Worker graph is absent from static and plain route HTML and is fetched only after the dashboard effect mounts;
-- two unchanged production builds emit identical Worker names and bytes;
-- changing Worker source changes its content hash;
-- base-prefixed deployment produces a valid same-origin Worker URL;
-- 30 dashboard/plain cycles create and terminate exactly 30 route Workers with no growing listener or chart ownership;
-- messages arriving after cleanup cannot update removed route DOM;
-- the ring buffer remains at its configured capacity under sustained input;
-- chart rendering is batched and sample ingestion does not call `useState()`;
-- routes without Worker capabilities remain byte-for-byte unaffected;
-- output raw/gzip cost, clean build time, sample throughput, render cadence, and lifecycle counters are recorded;
-- `npm run check`, `npm test`, package dry-run, and browser checks pass.
-
-Verified measurements for the focused `/dash` fixture: the minified Worker graph is `assets/workers/telemetry.worker-BVG2SA55.js`, 907 B raw and 477 B gzip. The dashboard window graph is 11,388 B raw and 5,148 B gzip across its shared runtime, effect runtime, navigation, route effect entry, and handler module; the Worker is not part of that graph. Seven clean minified builds measured 455.1, 459.9, 460.7, 463.5, 467.6, 472.6, and 475.2 ms, with a 463.5 ms median.
-
-The real-Worker browser check uses real wall time and requires sustained generation beyond 1,130 samples at 700-1,300 logical samples/second, an exact 128-sample ring bound, batches of 10, exactly 24 displayed points, multiple renders, and a render ceiling below 25 Hz. Delayed Worker ticks catch up in batches to the logical 1,000 samples/second clock; frames emit no more often than every 50 ms. The imperative chart performs a minimal canvas path draw. The navigation ownership check completed 30 dashboard/plain cycles with exactly 30 starts and 30 terminations, exactly 60 listener additions and removals across message and error listeners, zero retained listeners after every cleanup, disposed every old chart canvas, fresh ownership on back/forward and cached revisits, and no render from a removed message listener invoked after cleanup. Dashboard, plain, and static HTML contain no Worker asset URL; plain does not load the route effect graph, and static contains no script, capability marker, or state payload. A no-Worker equivalent emitted byte-identical shared runtime, effect runtime, navigation, and route effect entry files with no `assets/workers` directory. An unreachable imported-row effect referencing `unused.worker.ts` emitted no Worker asset. Two unchanged builds emitted identical Worker names and bytes, and a controlled downsample-source change changed the emitted hash.
+## Acceptance And Performance Gates
 
-## Delivery Order
+- The Worker graph is absent from static and plain route HTML and fetched only after its effect mounts.
+- Two unchanged builds emit identical Worker names and bytes; source changes alter the content hash.
+- Base-prefixed output constructs a valid same-origin Worker URL.
+- Repeated route cycles create and terminate exactly one route Worker each with no growing ownership.
+- Messages after cleanup cannot update removed route DOM.
+- Worker memory remains bounded by declared capacity.
+- High-frequency ingestion does not create one main-thread task or Kudzu state commit per sample.
+- Imperative rendering is batched to its declared cadence.
+- Builds without this capability remain unaffected.
+- Raw/gzip output, build time, throughput, cadence, and lifecycle counters are recorded.
+- `npm run check`, `npm test`, package dry-run, and applicable browser checks pass.
 
-1. **Worker compiler capability**: exact syntax, graph bundling, hashing, base rewriting, diagnostics, and zero-cost exclusion.
-2. **Capability conformance fixture**: mock telemetry Worker, bounded buffer, downsampling, imperative DOM ownership, and route cleanup.
+## Historical Validation Record
 
-Further work belongs to the React migration roadmap and starts from a reduced compatibility fixture that fails. Kudzu does not implement device, alarm, transport, or widget product features.
+The focused fixture emitted a 907 B raw / 477 B gzip Worker graph and an 11,388 B raw / 5,148 B gzip window graph. Seven clean minified builds measured a 463.5 ms median. Thirty route cycles produced exactly 30 starts and terminations, balanced message/error listener registration, bounded 128-sample history, no retained chart ownership, no stale post-cleanup render, deterministic unchanged builds, and a changed hash after a controlled Worker source edit.
 
-## Performance Gates
-
-- sustained 1,000 samples/second does not create one main-thread task or Kudzu state commit per sample;
-- Worker memory is bounded by declared buffer capacity;
-- chart updates are batched to at most one per display frame;
-- dashboard departure stops observable messages and renders before the next route mounts;
-- repeated navigation leaves no growing Worker, timer, listener, chart, state, DOM, or heap ownership;
-- Worker support adds no bytes to routes and builds that do not use it;
-- material losses are profiled and fixed or documented as explicit tradeoffs using matched initial content and behavior.
+These numbers are dated conformance evidence. They do not define a dashboard product target.
 
 ## Non-Goals
 
-- implementing ThingsBoard's server, protocol, rule engine, database, or complete UI;
-- storing telemetry samples in Kudzu component state;
-- adding a general observable, scheduler, stream, state, or widget runtime;
-- retaining a browser component tree;
-- request-time SSR, Server Actions, or a hidden application server;
-- a plugin marketplace or arbitrary third-party React widgets;
-- claiming Worker isolation as a security sandbox.
-
-## Completion Definition
-
-Goal B Milestone 1 is complete when the focused realtime fixture proves deterministic relative TypeScript Worker emission, bounded high-frequency processing, imperative chart updates, exact route ownership and cleanup across repeated navigation, native/static fallback, zero-cost exclusion, source diagnostics, and recorded production measurements.
+- Device, alarm, tenant, transport, chart, map, or widget product features.
+- A general stream, observable, scheduler, state, or plugin runtime.
+- Storing high-frequency samples in Kudzu component state.
+- Retaining a browser component tree.
+- Request-time SSR, server actions, or a hidden server.
+- Arbitrary third-party React widgets.
+- Treating Worker isolation as a security sandbox.

package/README.md

@@ -10,11 +10,11 @@ Kudzu is designed so ordinary common React-shaped TSX can migrate with minimal s
 
 > Experimental `0.7.x`: the compiler API and supported TSX surface may change.
 
-**0.7.8:** Static collection fast paths. Compiler-owned static filters reuse validated item metadata and detached row prototypes, making 1,000-row filtering match Vue and restoring filtered rows faster than React, Vue, and Svelte in the matched benchmark. See [release notes](./RELEASES.md#078---static-collection-fast-paths).
+**0.7.10:** Component composition. Existing specialized collection wrappers and keyed rows now retain direct analyzable prop spreads and forwarded JSX children without adding a browser component runtime. See [release notes](./RELEASES.md#0710---component-composition).
 
 Documentation: [kudzujs.cloud/docs](https://kudzujs.cloud/docs)
 
-Development target: [Goal A static business applications](./GOAL_A.md)
+Development direction: [React migration roadmap](./MIGRATION_ROADMAP.md)
 
 ## Install
 
@@ -465,7 +465,7 @@ Initial child rows remain complete HTML. Kudzu stores one child row prototype, i
 
 In the matched 100-parent/1,000-child fixture, Kudzu measured 1.3/0.4/5.0/0.7 ms for child update and condition change, child reverse, parent reverse, and parent removal. Hand-written Astro/native measured 0.5/0.4/3.9/0.2 ms, Svelte 2.7/1.2/6.7/1.3 ms, Vue 4.9/2.5/6.1/2.2 ms, and React 11.8/5.0/8.2/4.4 ms. Kudzu and Astro emit initial rows while the CSR targets do not, so artifact sizes are not architecture-equivalent.
 
-Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. Collections must remain anchored to local array state or a supported static named import; inline callbacks accept one or two identifier parameters, and row roots must be intrinsic JSX or supported same-file/relative components with `key={item.<field>}` or `key={index}`. State-backed list wrappers use one destructured props parameter, an intrinsic return root, no effects, and a direct local-state prop. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` effect dependencies are rejected. A collection alias may only be rendered once and cannot be read by other JavaScript. Collection callbacks and derived expressions must be pure and synchronous: supported reads, operators, templates, approved read-only methods, deterministic `Math`, and primitive conversion compile; imported callbacks, browser globals, promises, mutation, arbitrary calls, and prototype-sensitive properties fail. Lazy or dynamic keyed-row state initializers, non-`null` refs, callback refs, package/namespace/star row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, fragments, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
+Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. Collections must remain anchored to local array state or a supported static named import; inline callbacks accept one or two identifier parameters, and row roots must be intrinsic JSX or supported same-file/relative components with `key={item.<field>}` or `key={index}`. Specialized wrappers and keyed rows accept forwarded JSX children and source-ordered prop spreads from inline object literals or one direct `const` object literal declared in the calling component. Specialized keyed row components accept missing destructured string, finite-number, boolean, or `null` props with literal defaults. State-backed list wrappers use one destructured props parameter, an intrinsic return root, no effects, and a direct local-state prop. Whole-item, computed, nested, derived, `__proto__`, `prototype`, and `constructor` effect dependencies are rejected. A collection alias may only be rendered once and cannot be read by other JavaScript. Collection callbacks and derived expressions must be pure and synchronous: supported reads, operators, templates, approved read-only methods, deterministic `Math`, and primitive conversion compile; imported callbacks, browser globals, promises, mutation, arbitrary calls, and prototype-sensitive properties fail. Lazy or dynamic keyed-row state initializers, non-`null` refs, callback refs, package/namespace/star row imports, same-file exported rows, reusable aliases, dynamic/computed prop spreads, rest props, non-primitive defaults, fragments, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
 
 The focused wrapper fixture emits 1,393 B raw / 500 B gzip HTML and 10,719 B raw / 4,665 B gzip JavaScript across its route capabilities. After one warm-up, seven clean builds measured 314.1, 325.3, 322.3, 327.2, 336.1, 322.4, and 315.0 ms, with a 322.4 ms median.
 
@@ -674,18 +674,21 @@ Supported:
 - Layout- and route-lifetime effect mounts in navigation groups
 - Conditional/keyed DOM-owned effects in navigation groups
 
-Not implemented yet:
+Selected current migration limits:
 
-- Reusable keyed-list aliases
-- Arbitrary, imported, mutating, or asynchronous collection callbacks
-- Lazy/dynamic keyed-row state initializers and callback refs
-- Server actions and request-time SSR
-- React package/runtime/ecosystem compatibility or React islands
-- HMR and framework DevTools
+- Non-primitive prop defaults/rest, exported reusable specialized rows, `forwardRef`, and `useId` still need fixture-driven component specialization. Direct analyzable prop spreads and forwarded JSX children are supported across existing specialized collection boundaries.
+- Hookful non-keyed imported components and pure lazy state/reducer initializers remain narrower than ordinary React.
+- Reusable collection aliases, computed child collections, imported pure transforms, and common immutable pagination/sorting forms need failing fixtures before expansion.
+- Effect dependencies remain limited to directly analyzable primitive signals and supported keyed-item properties.
+- Conditional/keyed ranges inside SVG and router-shaped package source remain separate compatibility work.
+- Arbitrary, mutating, asynchronous, or package collection callbacks remain deliberate static-analysis boundaries.
+- Server actions, request-time SSR, a React runtime/ecosystem layer, React islands, and a default SPA router are non-goals.
+
+See the [active fixture queue](./MIGRATION_ROADMAP.md#active-fixture-queue) for development order. Unsupported syntax is not automatically backlog work; a real React migration fixture must fail first.
 
 ## Benchmarks
 
-### Goal A Commerce Journey
+### Goal A Validation Fixture: Commerce Journey
 
 The matched fixture covers home, category, product, cart, checkout, and account routes with complete initial HTML, shared application layout state, product options, optimistic cart success and rejection, accessible errors, rollback, and product-to-cart navigation. Kudzu, React + Vite, Next.js, Nuxt, and SvelteKit render the same tested content and interactions.
 

package/RELEASES.md

@@ -1,5 +1,51 @@
 # Kudzu Releases
 
+## 0.7.10 - Component composition
+
+Kudzu 0.7.10 preserves common component composition across existing compiler-specialized collection boundaries.
+
+### New in 0.7.10
+
+- State-backed collection wrappers, keyed rows, and reducer specializations accept prop spreads from direct inline object literals or one direct `const` object literal declared in the calling component.
+- Spread and explicit props apply in source order, preserving ordinary override behavior.
+- Specialized components accept forwarded JSX children, including mixed text and element children, while still lowering to intrinsic DOM.
+- Non-self-closing specialized component tags are counted as one JSX use instead of treating the closing tag as another reference.
+- A conventional React-shaped landing fixture proves imported layout children, component spreads, keyed row children, interaction output, and a zero-JavaScript static route.
+- Dynamic, computed, circular, prototype-sensitive, and method/accessor spread shapes fail with source-located diagnostics.
+
+### Boundary
+
+Spread sources must be inline object literals or one direct `const` object literal declared in the calling component. State collections still cross the specialization boundary as direct props. Rest bindings, non-primitive defaults, exported reusable specialized rows, `forwardRef`, and `useId` remain fixture-driven work.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.10
+```
+
+## 0.7.9 - Keyed-row prop defaults
+
+Kudzu 0.7.9 lets ordinary keyed row components retain destructured primitive literal prop defaults instead of restructuring every call site.
+
+### New in 0.7.9
+
+- Same-file and relative-imported keyed row components accept string, finite-number, boolean, and `null` defaults.
+- Missing props receive their default literals during existing component specialization.
+- The component call lowers to intrinsic keyed JSX; React imports and the component call do not enter browser output.
+- Rest and nested destructuring remain source-diagnosed, while object, array, computed, and call defaults remain rejected.
+- No browser runtime branch or shared asset bytes are added.
+- The product documents now define commerce and realtime dashboards as validation fixtures under one general React migration roadmap, not separate product verticals.
+
+### Boundary
+
+This release supports primitive literal defaults on compiler-specialized keyed rows. General prop spreads, rest bindings, non-primitive defaults, specialized `children`, `forwardRef`, and `useId` remain fixture-driven composition work.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.9
+```
+
 ## 0.7.8 - Static collection fast paths
 
 Kudzu 0.7.8 specializes compiler-owned static `filter` collections so repeated category changes avoid general keyed-list validation and reconciliation.

package/framework/README.md

@@ -31,9 +31,9 @@ Page `metadata` can emit description, canonical, favicon, manifest, Open Graph,
 
 Inline SVG rendering normalizes an explicit set of common React presentation aliases before static serialization and binding descriptor creation. Reactive aliases therefore use the existing generic `setAttribute` path; static SVG adds no JavaScript and reactive SVG adds no SVG-specific runtime.
 
-Same-file and relative-imported component chains receiving a direct local-state array or keyed item are recursively specialized to intrinsic JSX before keyed-list analysis, so their component functions are not retained in the browser. Rows may own multiple direct-property child maps recursively, nested conditions, latest-item handlers, multiple directly serializable state slots, effects, and `null`-initialized object refs. Structural list sites and ancestor key paths scope hooks across updates and reorder and release them on removal. Handler modules are emitted only when a rendered descriptor references them. Direct JSON-safe primitive keyed-item dependencies subscribe each row record to its owning list commit and compare selected fields after `list-runtime.js` synchronously refreshes the row marker. Only changed rows rerun with the complete latest item; reorder compares equal and unrelated fields do nothing. Builds without item dependencies emit no item reader or list-state subscription code.
+Same-file and relative-imported component chains receiving a direct local-state array or keyed item are recursively specialized to intrinsic JSX before keyed-list analysis, so their component functions are not retained in the browser. Missing destructured string, finite-number, boolean, or `null` props use their literal defaults during specialization. Rows may own multiple direct-property child maps recursively, nested conditions, latest-item handlers, multiple directly serializable state slots, effects, and `null`-initialized object refs. Structural list sites and ancestor key paths scope hooks across updates and reorder and release them on removal. Handler modules are emitted only when a rendered descriptor references them. Direct JSON-safe primitive keyed-item dependencies subscribe each row record to its owning list commit and compare selected fields after `list-runtime.js` synchronously refreshes the row marker. Only changed rows rerun with the complete latest item; reorder compares equal and unrelated fields do nothing. Builds without item dependencies emit no item reader or list-state subscription code.
 
-Rendered collection selectors compile one-use aliases and inline `(item)` or `(item, index)` pipelines over local array state or supported static named imports. Supported selectors are pure `filter` with direct local-state reads, direct-property `flatMap`, and `Array.from` before a final keyed `map`; dependency commits re-evaluate the selector against the immutable build-time collection while field keys retain item identity and `key={index}` retains positional identity. Compiler-owned static filters over structural keyed rows validate source references and keys once, retain removed rows as detached prototypes, clone fresh restoration nodes, and insert only new runs without moving retained DOM. This route-specific path is compiled out elsewhere. Compiler-owned collection state is excluded from development snapshot restoration. Arbitrary callbacks, mutation, asynchronous selectors, imported callback functions, prototype-sensitive reads, lazy/dynamic row state initializers, non-`null` or callback refs, and recursive component cycles fail during compilation.
+Rendered collection selectors compile one-use aliases and inline `(item)` or `(item, index)` pipelines over local array state or supported static named imports. Supported selectors are pure `filter` with direct local-state reads, direct-property `flatMap`, and `Array.from` before a final keyed `map`; dependency commits re-evaluate the selector against the immutable build-time collection while field keys retain item identity and `key={index}` retains positional identity. Compiler-owned static filters over structural keyed rows validate source references and keys once, retain removed rows as detached prototypes, clone fresh restoration nodes, and insert only new runs without moving retained DOM. Specialized collection wrappers and keyed rows inline direct object-literal or calling-component `const` object prop spreads in source order and forward JSX children into intrinsic output. This route-specific path is compiled out elsewhere. Compiler-owned collection state is excluded from development snapshot restoration. Dynamic/computed prop spreads, arbitrary callbacks, mutation, asynchronous selectors, imported callback functions, prototype-sensitive reads, lazy/dynamic row state initializers, non-`null` or callback refs, and recursive component cycles fail during compilation.
 
 The reduced `useReducer` form reuses ordinary state slots and React's pure reducer contract. A direct dispatch in a compiled handler becomes a functional `set` whose reducer is bundled from a relative TypeScript module into that handler graph. Pure reducer-owned keyed lists reuse unchanged item identities for reorder, one removal, and append fast paths; ordinary `useState` lists retain full validation. One direct dispatch prop into a same-file or relative-imported synchronous component, including a direct keyed row, is specialized to intrinsic JSX at the call site, so its handler retains the parent reducer scope and no dispatch capture or child handler asset is emitted. A reducer row reads the latest item through the existing list scope and uses the same multiple serializable state, effect, condition, and object-ref specialization as other keyed rows. Relative TypeScript imports referenced inside that child handler receive collision-free call-site aliases and join the parent handler graph. One nested relative-imported intrinsic child may receive an inline or simple `const` callback containing dispatch; the compiler recursively substitutes that callback once and omits the nested child handler asset. Missing primitive literal defaults in these reducer specializations are substituted at the same call site. Reducer-free routes and shared runtimes are unchanged; no reducer runtime or browser component instance exists.
 

package/framework/build.mjs

@@ -3358,17 +3358,113 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
   visit(root)
 }
 
+function directConstObjectLiteral(expression, call, sourceFile) {
+  expression = unwrapExpression(expression)
+  if (ts.isObjectLiteralExpression(expression)) return expression
+  if (!ts.isIdentifier(expression)) return
+  const owner = nearestFunction(call)
+  const scope = owner?.body ?? sourceFile
+  if (!scope || !ts.isBlock(scope) && !ts.isSourceFile(scope)) return
+  const declarations = []
+  for (const statement of scope.statements) {
+    if (!ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === expression.text && declaration.initializer && declaration.end < call.pos) declarations.push(declaration)
+    }
+  }
+  if (declarations.length !== 1) return
+  const initializer = unwrapExpression(declarations[0].initializer)
+  if (ts.isObjectLiteralExpression(initializer)) return initializer
+}
+
+function specializedSpreadEntries(expression, call, sourceFile, fail, label, seen = new Set()) {
+  const object = directConstObjectLiteral(expression, call, sourceFile)
+  if (!object) fail(expression, `${label} component prop spreads must use an inline object literal or one direct const object literal declared in the calling component`)
+  if (seen.has(object)) fail(expression, `${label} component prop spreads cannot be circular`)
+  seen.add(object)
+  const entries = []
+  for (const property of object.properties) {
+    if (ts.isSpreadAssignment(property)) {
+      entries.push(...specializedSpreadEntries(property.expression, call, sourceFile, fail, label, seen))
+      continue
+    }
+    if (ts.isShorthandPropertyAssignment(property)) {
+      entries.push([property.name.text, property.name, property])
+      continue
+    }
+    if (!ts.isPropertyAssignment(property) || ts.isComputedPropertyName(property.name) || !ts.isIdentifier(property.name) && !ts.isStringLiteral(property.name) && !ts.isNumericLiteral(property.name)) {
+      fail(property, `${label} component prop spreads must contain only direct properties`)
+    }
+    entries.push([property.name.text, property.initializer, property])
+  }
+  seen.delete(object)
+  return entries
+}
+
+function specializedCallChildren(call, factory) {
+  if (!ts.isJsxElement(call)) return []
+  return call.children.flatMap(child => {
+    if (ts.isJsxText(child)) {
+      const lines = child.text.split(/\r\n|\n|\r/)
+      const text = lines.length === 1
+        ? child.text
+        : lines.map((line, index) => {
+            let text = line.replace(/\t/g, " ")
+            if (index) text = text.trimStart()
+            if (index < lines.length - 1) text = text.trimEnd()
+            return text
+          }).filter(Boolean).join(" ")
+      return text ? [factory.createStringLiteral(text)] : []
+    }
+    if (ts.isJsxExpression(child)) return child.expression ? [child.expression] : []
+    return [child]
+  })
+}
+
+function flattenForwardedComponentChildren(root, factory, context) {
+  const forwarded = expression => {
+    const value = unwrapExpression(expression)
+    if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value)) return [value]
+    if (ts.isJsxFragment(value)) return [...value.children]
+    if (ts.isArrayLiteralExpression(value) && !value.elements.some(ts.isSpreadElement)) {
+      return value.elements.flatMap(element => {
+        if (ts.isJsxFragment(element)) return [...element.children]
+        if (ts.isJsxElement(element) || ts.isJsxSelfClosingElement(element)) return [element]
+        return [factory.createJsxExpression(undefined, element)]
+      })
+    }
+  }
+  const visit = node => {
+    if (ts.isJsxElement(node)) {
+      const children = node.children.flatMap(child => {
+        const values = ts.isJsxExpression(child) && child.expression ? forwarded(child.expression) : undefined
+        return (values ?? [child]).map(entry => ts.visitNode(entry, visit))
+      })
+      return factory.updateJsxElement(node, ts.visitNode(node.openingElement, visit), children, ts.visitNode(node.closingElement, visit))
+    }
+    return ts.visitEachChild(node, visit, context)
+  }
+  return ts.visitNode(root, visit)
+}
+
 function specializeComponentCall(call, component, sourceFile, factory, context, fail, label = "Keyed list", allowComponentRoot = false) {
   if (component.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword) || component.asteriskToken) fail(component, `${label} components must be synchronous`)
   if (component.parameters.length !== 1 || !ts.isObjectBindingPattern(component.parameters[0].name)) fail(component, `${label} components must use one destructured props parameter`)
-  if (ts.isJsxElement(call) && call.children.some(child => !ts.isJsxText(child) || child.text.trim())) fail(call, `${label} component children are not supported`)
   const callAttributes = ts.isJsxElement(call) ? call.openingElement.attributes : call.attributes
   const props = new Map()
+  const directProps = new Set()
   let key
   for (const attribute of callAttributes.properties) {
-    if (ts.isJsxSpreadAttribute(attribute)) fail(attribute, `${label} component prop spreads are not supported`)
+    if (ts.isJsxSpreadAttribute(attribute)) {
+      for (const [name, value, property] of specializedSpreadEntries(attribute.expression, call, sourceFile, fail, label)) {
+        if (["__proto__", "constructor", "prototype"].includes(name)) fail(property, `${label} component prop spread property ${JSON.stringify(name)} is not supported`)
+        if (name === "key") fail(property, `${label} component prop spreads cannot declare key`)
+        props.set(name, value)
+      }
+      continue
+    }
     const name = attribute.name.text
-    if (props.has(name) || name === "key" && key) fail(attribute, `Duplicate ${label.toLowerCase()} component prop "${name}"`)
+    if (directProps.has(name) || name === "key" && key) fail(attribute, `Duplicate ${label.toLowerCase()} component prop "${name}"`)
     const value = !attribute.initializer
       ? factory.createTrue()
       : ts.isStringLiteral(attribute.initializer)
@@ -3377,12 +3473,20 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
           ? attribute.initializer.expression
           : factory.createIdentifier("undefined")
     if (name === "key") key = attribute
-    else props.set(name, value)
+    else {
+      props.set(name, value)
+      directProps.add(name)
+    }
+  }
+  const children = specializedCallChildren(call, factory)
+  if (children.length) {
+    if (directProps.has("children")) fail(call, `Duplicate ${label.toLowerCase()} component prop "children"`)
+    props.set("children", children.length === 1 ? children[0] : factory.createArrayLiteralExpression(children))
   }
   const substitutions = new Map()
   const acceptedProps = new Set()
   for (const element of component.parameters[0].name.elements) {
-    if (element.dotDotDotToken || !ts.isIdentifier(element.name) || (element.initializer && label === "Keyed list")) fail(element, `${label} component props cannot use rest, defaults, or nested destructuring`)
+    if (element.dotDotDotToken || !ts.isIdentifier(element.name)) fail(element, `${label} component props cannot use rest or nested destructuring`)
     if (element.initializer && !isPrimitiveDefaultLiteral(element.initializer)) fail(element.initializer, `${label} component prop defaults must be primitive literals`)
     const prop = (element.propertyName ?? element.name).text
     acceptedProps.add(prop)
@@ -3454,7 +3558,7 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
   findUnsupportedHook(returned)
   for (const calculation of calculations) findUnsupportedHook(calculation.expression)
   if (unsupportedHook) throw sourceNodeError(unsupportedHook, component.getSourceFile(), `Keyed row ${unsupportedHook.expression.text}() must be one top-level const declaration`)
-  let root = unwrapExpression(substituteClone(returned, substitutions, factory, context))
+  let root = unwrapExpression(flattenForwardedComponentChildren(substituteClone(returned, substitutions, factory, context), factory, context))
   if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) fail(returned, `${label} component must return one JSX element`)
   const tag = jsxTagName(root)
   if (!ts.isIdentifier(tag) || !allowComponentRoot && tag.text[0] !== tag.text[0].toLowerCase()) fail(returned, `${label} component must directly return an intrinsic JSX element`)
@@ -3663,7 +3767,7 @@ function validateListExpression(expression, item, source, fail, index) {
         fail(source, "Derived keyed list item expressions cannot call arbitrary functions")
       }
     }
-    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && node.text !== item && node.text !== index && !pureListGlobals.has(node.text)) {
+    if (ts.isIdentifier(node) && isReferenceIdentifier(node) && !isJsxSyntaxIdentifier(node) && node.text !== item && node.text !== index && !pureListGlobals.has(node.text)) {
       fail(source, `Derived keyed list item expression identifier "${node.text}" is not allowed`)
     }
     ts.forEachChild(node, visit)
@@ -3731,7 +3835,7 @@ function referencesIdentifier(root, name) {
 function identifierReferenceCount(root, name) {
   let count = 0
   const visit = node => {
-    if (ts.isIdentifier(node) && node.text === name && isReferenceIdentifier(node)) count++
+    if (ts.isIdentifier(node) && node.text === name && isReferenceIdentifier(node) && !ts.isJsxClosingElement(node.parent)) count++
     ts.forEachChild(node, visit)
   }
   visit(root)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",