@kudzujs/core 0.16.24 → 0.16.26

package/README.md

@@ -14,16 +14,14 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.16.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.16.24 - imported article search and benchmark integrity.** Ordinary imported search aliases and counts compile through existing semantics with byte-identical JavaScript to the inlined control. Revision-4 benchmark protocols preserve partial evidence and enforce setup-inclusive deadlines for future runs; no fresh AI performance result is claimed, and `1.0.0` remains blocked. Read the [release notes](./RELEASES.md#01624---imported-article-search-and-benchmark-integrity), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.24), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Current release: [0.16.26](https://github.com/kudzujs/kudzu/releases/tag/v0.16.26).** Write reusable components, native event handlers, and pure collection expressions; Kudzu specializes supported source into static content and direct browser updates.
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)
 - [Components and migration support](https://kudzujs.cloud/docs#components)
 - [Current limits](https://kudzujs.cloud/docs#limits)
 - [Benchmarks](https://kudzujs.cloud/docs#benchmarks)
-- [Raw performance records](https://github.com/kudzujs/kudzu/blob/main/PERFORMANCE.md)
-- [React migration roadmap](https://github.com/kudzujs/kudzu/blob/main/MIGRATION_ROADMAP.md)
-- [Release history](./RELEASES.md)
+- [Release history](https://github.com/kudzujs/kudzu/releases)
 
 ## Quick Start
 
@@ -88,6 +86,50 @@ npm run dev
 npm run build
 ```
 
+## Authoring
+
+Use native HTML controls and events. Read the control through `event.currentTarget`
+inside the handler and update state with its setter; Kudzu does not use React
+synthetic events. Setters update logical state immediately and batch DOM writes.
+
+Keep derived values pure: top-level `const` locals can normalize primitive state,
+filter an immutable collection, and reuse its `.length` in JSX. Render ordinary
+child components with stable keys rather than manually rebuilding DOM rows.
+For example, with `items` exported as a JSON-safe immutable array from `../data`
+and `Item` as a relative component rendering one item:
+
+```tsx
+import { useState } from "@kudzujs/core"
+import { items } from "../data"
+import { Item } from "../Item"
+
+export default function ItemsPage() {
+  const [query, setQuery] = useState("")
+  const normalized = query.trim().toLowerCase()
+  const visible = items.filter(item => item.name.toLowerCase().includes(normalized))
+  const count = visible.length
+
+  return <main>
+    <label htmlFor="item-query">Find items</label>
+    <input id="item-query" type="search" value={query}
+      onInput={event => setQuery(event.currentTarget.value)} />
+    <p aria-live="polite">Matches: {count}</p>
+    <ul>{visible.map(item => <Item key={item.id} item={item} />)}</ul>
+  </main>
+}
+```
+
+Collection aliases must stay within supported collection/count uses; arbitrary
+calls, mutation, and escaping reactive collections are not supported. Use the
+build's source-located diagnostic and [current limits](https://kudzujs.cloud/docs#limits)
+to identify the boundary rather than assuming arbitrary React code will compile.
+
+Keep interactions in the routes that need them. Build-known direct imported
+maps and pure static filters can emit complete HTML without list JavaScript.
+A static sibling outside an enhanced-navigation group ships no JavaScript merely
+because another page is interactive. Shared layout effects or explicit navigation
+groups have their own lifetime; native anchors remain the default.
+
 ## How It Works
 
 ```text
@@ -155,7 +197,7 @@ npm run check
 npm test
 ```
 
-Read [AGENTS.md](https://github.com/kudzujs/kudzu/blob/main/AGENTS.md) and the [migration roadmap](https://github.com/kudzujs/kudzu/blob/main/MIGRATION_ROADMAP.md) before extending migration syntax or browser capabilities.
+Contributor instructions live in the [repository](https://github.com/kudzujs/kudzu).
 
 ## License
 

package/framework/compiler/effect-private-ref-pass.mjs

@@ -72,6 +72,8 @@ export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
       if (frameAssignments.length && invalidReference) throw sourceNodeError(invalidReference, sourceFile, "Animation frame refs may only use direct .current reads and assignments")
       if (frameAssignments.length && !topLevelConst) throw sourceNodeError(node, sourceFile, "Animation frame refs must be one top-level component const")
       if (attachedToJsx && mutations.length) throw sourceNodeError(mutations[0], sourceFile, "JSX object refs may not assign to ref.current")
+      const renderWrite = mutations.find(access => nearestFunction(access) === owner)
+      if (renderWrite) throw sourceNodeError(renderWrite, sourceFile, "Mutable refs cannot be assigned during render; use component state for values retained across effect replacements, or an effect-private ref with cleanup for invocation-local values")
       if (!topLevelConst || invalidReference || !accesses.length) return
       const effectCalls = owner.body.statements.flatMap(statement => hasUseEffectImport && ts.isExpressionStatement(statement) && ts.isCallExpression(statement.expression) && ts.isIdentifier(statement.expression.expression) && statement.expression.expression.text === "useEffect" && !isShadowedIdentifier(statement.expression.expression, sourceFile) ? [statement.expression] : [])
       const effects = effectCalls.filter(effect => {

package/framework/compiler/source-compiler.mjs

@@ -1709,7 +1709,10 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
             collectionLengthDeclarations.add(current)
             return false
           }
-          if (ts.isJsxExpression(current) && current.initializer === undefined) return false
+          if (ts.isJsxExpression(current) && current.initializer === undefined) {
+            resolveReactiveJsxExpression(reference.parent, owner, settersForNode(reference, settersByFunction), collectionValueDeclarations)
+            return false
+          }
         }
         return true
       })
@@ -2464,6 +2467,8 @@ function keyedListParts(expression, setters, declarations, fail, aliases = new S
   const field = keyExpression && directProperty(keyExpression, parameters.item)
   const positional = Boolean(keyExpression && parameters.index && ts.isIdentifier(unwrapExpression(keyExpression)) && unwrapExpression(keyExpression).text === parameters.index)
   if (!field && !positional) fail(key ?? root, `Keyed list root must have key={${parameters.item}.<field>} or key={${parameters.index ?? "index"}}`)
+  // Direct build-known imports can execute their map without keyed browser ownership.
+  if (collection.static && !collection.localStatic && !collection.selectorStates.size && !collection.aliasDeclarations?.length) return undefined
   return { ...collection, static: collection.static && (!collection.localStatic || collection.selector.length > 0), callback, root, item: parameters.item, index: parameters.index, indexed: Boolean(parameters.index), keyField: positional ? null : field }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.16.24",
+  "version": "0.16.26",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -23,13 +23,8 @@
   },
   "files": [
     "bin/",
-    "docs/next-architecture/",
     "framework/",
-    "GOAL_A.md",
-    "GOAL_B.md",
-    "MIGRATION_ROADMAP.md",
-    "PERFORMANCE.md",
-    "RELEASES.md",
+    "!framework/README.md",
     "README.md",
     "LICENSE"
   ],

package/GOAL_A.md

@@ -1,116 +0,0 @@
-# Goal A: Static Application Lifecycles And Opt-In Navigation
-
-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.
-
-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.
-
-## Status
-
-Goal A is complete for explicitly configured emitted-route groups with shared layouts. Implemented capabilities include:
-
-- 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.
-
-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.
-
-## Capability Contract
-
-A migrated application may use familiar function components, props, children, JSX, hooks, conditions, collections, and handlers while Kudzu emits:
-
-```text
-complete static document
-  -> optional persistent layout range
-  -> replaceable route range
-  -> only the route-specific ESM capabilities used
-```
-
-The capability must preserve:
-
-- complete indexable HTML for every route;
-- direct entry, reload, back, forward, query strings, and base paths;
-- 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.
-
-## Invariants
-
-- 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.
-
-## Ownership Model
-
-Goal A adds explicit ownership, not a state library or application runtime.
-
-| Owner | Lifetime | General examples |
-|---|---|---|
-| 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 |
-
-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.
-
-## Validation Fixture
-
-The reduced commerce journey remains a useful integration fixture because it exercises the neutral capability contract in one flow:
-
-```text
-home -> category -> product -> cart -> checkout -> account
-```
-
-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.
-
-Other applications should validate the same capabilities with domain-appropriate fixtures such as documentation, content, administration, forms, and dashboards.
-
-## Performance Protocol
-
-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.
-
-Record at least:
-
-- deploy bytes and initial raw/gzip JavaScript;
-- HTML, CSS, media, and route transfer bytes;
-- clean build median;
-- 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.
-
-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.
-
-## Regression Gates
-
-- 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.
-
-## Historical Validation Record
-
-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.
-- 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,121 +0,0 @@
-# Goal B: Relative TypeScript Worker Capability Proof
-
-This historical capability milestone is distinct from the active [Goal B optimization program](./docs/next-architecture/goal-b-optimization-benchmarks.md).
-
-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`.
-
-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.
-
-## Status
-
-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.
-
-Further Worker, transport, effect, or React compatibility work must begin with a reduced conventional React migration fixture that fails.
-
-## Capability Target
-
-The focused proof uses one Worker-enabled route, one plain companion route, and one unrelated static route:
-
-```text
-plain route <-> Worker-enabled route
-```
-
-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.
-
-## Supported Form
-
-The Worker must be constructed directly inside a compiled inline effect:
-
-```tsx
-useEffect(() => {
-  const worker = new Worker(
-    new URL("../telemetry.worker.ts", import.meta.url),
-    { type: "module" },
-  )
-
-  const onMessage = (event: MessageEvent<Frame>) => resource.render(event.data)
-  worker.addEventListener("message", onMessage)
-
-  return () => {
-    worker.removeEventListener("message", onMessage)
-    worker.terminate()
-    resource.dispose()
-  }
-}, [])
-```
-
-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, 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;
-- 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 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 | Capability responsibility |
-|---|---|---|
-| 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 |
-
-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 capability fixture proves:
-
-- 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;
-- 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 And Performance Gates
-
-- 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.
-
-## Historical Validation Record
-
-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.
-
-These numbers are dated conformance evidence. They do not define a dashboard product target.
-
-## Historical 0.7.12 Rerun
-
-At commit `05e5cc2` on Apple M3 / macOS 26.5.2 / Node 25.6.1, `npm run benchmark` measured clean build times of 404.2, 401.3, 408.2, 404.4, 399.9, 408.8, and 402.0 ms after one warm-up, for a 404.2 ms median. That rerun's Worker graph was 907 B raw / 475 B gzip; its complete dashboard window graph was 11,960 B raw / 5,365 B aggregate gzip.
-
-Chrome 150.0.7871.187 passed the tracked throughput, cadence, stale-write, bounded-history, and 30-cycle start/termination checks through the focused Worker browser test. Those rerun values differ from the historical completion snapshot because shared window capabilities and the local toolchain changed; both sets remain release provenance, not current artifact claims.
-
-## Non-Goals
-
-- 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.