@kudzujs/core 0.7.12 → 0.7.13

package/GOAL_B.md

@@ -102,6 +102,12 @@ The focused fixture emitted a 907 B raw / 477 B gzip Worker graph and an 11,388
 
 These numbers are dated conformance evidence. They do not define a dashboard product target.
 
+## Reproducible 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. The current Worker graph is 907 B raw / 475 B gzip; the complete dashboard window graph is 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. These current values differ from the historical completion snapshot because shared window capabilities and the local toolchain changed; the historical values above remain release provenance, not current artifact claims.
+
 ## Non-Goals
 
 - Device, alarm, tenant, transport, chart, map, or widget product features.

package/README.md

@@ -10,13 +10,14 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.7.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.7.12 - Exported row reuse.** Directly exported same-file row components can be reused across static and keyed JSX sites while every call still lowers to intrinsic DOM. Read the [release notes](./RELEASES.md#0712---exported-row-reuse) or open the [release page](https://kudzujs.cloud/releases/0.7.12).
+**Latest release: 0.7.13 - Deterministic useId.** Ordinary React-shaped components can retain top-level `useId()` calls while Kudzu emits stable static HTML IDs and no browser capability. Read the [release notes](./RELEASES.md#0713---deterministic-useid) or open the [release page](https://kudzujs.cloud/releases/0.7.13).
 
 - [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](./PERFORMANCE.md)
 - [React migration roadmap](./MIGRATION_ROADMAP.md)
 - [Release history](./RELEASES.md)
 
@@ -77,7 +78,7 @@ ordinary React-shaped TSX
 ```
 
 - Function components execute at build time and do not survive as browser components.
-- `useState` and reduced `useReducer` compile to synchronous logical state and batched direct DOM writes.
+- `useState` and reduced `useReducer` compile to synchronous logical state and batched direct DOM writes; top-level `useId` becomes deterministic static HTML without browser JavaScript.
 - Conditions, keyed collections, attributes, events, refs, effects, and supported component boundaries compile to route-specific capabilities.
 - Build-known data and routes become complete HTML through async components and `getStaticPaths()`.
 - Native document navigation is the default; static routes do not load a client runtime.

package/RELEASES.md

@@ -1,5 +1,28 @@
 # Kudzu Releases
 
+## 0.7.13 - Deterministic useId
+
+Kudzu 0.7.13 preserves conventional top-level React `useId()` authoring while emitting deterministic static HTML IDs with no browser runtime.
+
+### New in 0.7.13
+
+- `useId` may be imported directly or with an alias from `react`, or called as a direct default/namespace React member.
+- Each top-level `const id = useId()` receives a stable build-time ID that can be reused by `id`, `htmlFor`, and ARIA ID-reference attributes.
+- Repeated component calls receive distinct IDs, while unchanged clean builds reproduce the same output.
+- Shared layouts and route content use separate ID namespaces during complete-document and enhanced navigation builds.
+- Static routes remain JavaScript-free; no hook dispatcher, hydration metadata, or browser component function is emitted.
+- Calls with arguments, non-top-level forms, and keyed-row ownership fail with source-located diagnostics.
+
+### Boundary
+
+`useId()` accepts no arguments and must initialize one top-level `const` identifier in an ordinary component. Keyed rows remain unsupported because cloned row templates require key-scoped rewriting of `id`, `for`, ARIA IDREF, and fragment-reference attributes; Kudzu rejects the unsafe shape instead of emitting duplicate IDs.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.7.13
+```
+
 ## 0.7.12 - Exported row reuse
 
 Kudzu 0.7.12 lets directly exported same-file row components remain ordinary reusable source while every supported call still specializes to intrinsic DOM.
@@ -319,7 +342,7 @@ This is source migration support, not a React compatibility runtime. Aliased hoo
 
 ### Measured fixture
 
-The two-route landing fixture retains React imports across relative components. Its static route has no script, while its interactive mobile-menu route emits 10,245 B raw / 5,030 B aggregate gzip JavaScript across seven capability files. Seven clean builds after one warm-up measured a 310.0 ms median on the development machine described in `MIGRATION_ROADMAP.md`.
+The two-route landing fixture retains React imports across relative components. Its static route has no script, while its interactive mobile-menu route emitted 10,245 B raw / 5,030 B aggregate gzip JavaScript across seven capability files in the 0.7.0 release snapshot. Seven clean builds after one warm-up measured a 310.0 ms median in that historical development environment; the original runner and raw array are not tracked in the current repository.
 
 ### Upgrade
 

package/framework/README.md

@@ -2,7 +2,7 @@
 
 Kudzu specializes ordinary common React-shaped TSX so migrations need minimal source restructuring. Declarative components, collection pipelines, conditions, hooks, and handlers should be lowered at build time rather than replaced with application-owned imperative DOM code. This principle applies across migrations and is not Stay-specific; it does not imply a React package, VDOM, hydration, or ecosystem runtime.
 
-Migration source may retain conventional `react` imports for supported named or aliased hooks, direct members such as `React.useState`, same-file `memo`, inline `useCallback`, direct-state expression or analyzable collection-pipeline `useMemo`, and default, namespace, or named `Fragment`. Collection memos may start from local array state or a named relative import of an exported JSON-safe `const` array and may read direct local state declared in their dependency array. `build.mjs` canonicalizes those forms and rewrites module references to `@kudzujs/core` before build-time evaluation. Memo wrappers are erased or inlined into existing bindings and keyed-list selectors because no browser component rerender or memo cache exists. Static routes remain JavaScript-free and emitted modules are checked for surviving React imports.
+Migration source may retain conventional `react` imports for supported named or aliased hooks, direct members such as `React.useState`, same-file `memo`, inline `useCallback`, direct-state expression or analyzable collection-pipeline `useMemo`, top-level `const` identifiers initialized by `useId()`, and default, namespace, or named `Fragment`. `useId()` becomes a deterministic build-time HTML ID and emits no browser capability; keyed rows reject it because cloned row templates cannot safely duplicate HTML IDs. Collection memos may start from local array state or a named relative import of an exported JSON-safe `const` array and may read direct local state declared in their dependency array. `build.mjs` canonicalizes those forms and rewrites module references to `@kudzujs/core` before build-time evaluation. Memo wrappers are erased or inlined into existing bindings and keyed-list selectors because no browser component rerender or memo cache exists. Static routes remain JavaScript-free and emitted modules are checked for surviving React imports.
 
 Direct `clsx` calls over literal strings, numbers, arrays, object conditions, and conditional expressions are similarly lowered to ordinary concatenation and conditional expressions. The package import is erased, and dynamic classes continue through the existing binding compiler without serializing or shipping the `clsx` function.
 
@@ -39,8 +39,4 @@ The reduced `useReducer` form reuses ordinary state slots and React's pure reduc
 
 `kudzu.config` may opt one emitted shared-layout group into same-document navigation with legacy `navigation: { routes: ["/product", "/items/[id]"] }`, or multiple groups with `navigation: { groups: [{ routes: [...] }, { routes: [...] }] }`. The forms are mutually exclusive. Identities are globally unique emitted exact paths or `runtimeParams` patterns; each group uses one page-exported layout function identity. Runtime records securely match concrete pathnames under `base`, and their cache-safe parameter initializer runs before route DOM/effects mount on every transition. Each group receives a deterministic route-hashed asset specialized to only its records, pattern decoder, and effect/parameter lifecycle needs. Cross-group and ungrouped anchors remain native and are not prefetched; overlapping path domains across groups fail the build. Route effect entries export cache-safe layout and route mount functions: layout effects, including conditional/keyed DOM-owned effects, persist for the group session; route effects receive a fresh owner registry after each route insertion; and non-persisted page disposal cleans route before layout. Direct primitive state, runtime parameter, and keyed-item property dependencies and cleanup are supported. Fragment payloads and coordinated View Transitions are not implemented.
 
-The current matched commerce profile emits 35,355 deploy bytes and loads 7,334 B gzip of product-route JavaScript, including 2,425 B for navigation. These sizes are unchanged because its top-level-only navigation effects retain the smaller specialized path. Validated prefetch reduced the original 128.7 ms product-to-cart navigation to 5.6 ms in the current run. Seven interleaved artifact-clean builds after warm-up measured Kudzu at 486.8 ms and React at 545.4 ms, making Kudzu 10.7% faster. Cache-disabled output is byte-for-byte identical.
-
-In matched state-only and item-property keyed-row builds, the minified route effect entry changes from 3,829 B raw/1,667 B gzip to 4,392 B raw/1,823 B gzip, the shared runtime from 1,291 B raw/671 B gzip to 1,503 B raw/751 B gzip, and the list runtime from 6,606 B raw/2,474 B gzip to 6,652 B raw/2,493 B gzip. The complete targeted-notification capability costs +821 B raw/+255 B gzip and remains absent from builds without item dependencies. Seven clean builds of the expanded three-route fixture measured 420-440 ms with a 430 ms median; this records current build cost rather than claiming a cross-version speed change.
-
-The matched 1,000-row cross-framework effect fixture measured Kudzu at 8,264 B initial JavaScript gzip, 426 ms build, 3.6 ms selected-row cleanup/update/setup, 2.4 ms unrelated-field update, and 8.8 ms reorder. React CSR measured 60,921 B, 1,198 ms, 9.8 ms, 5.9 ms, and 16.8 ms respectively; Vue measured 5.8, 2.4, and 10.5 ms for the browser operations, and Svelte measured 5.7, 4.1, and 58.1 ms. Browser operations begin only after all targets have 1,000 rows and effects ready. Kudzu emits those rows in HTML while the framework CSR fixtures begin from empty shells, so JavaScript, output, and build values are not architecture-equivalent comparisons. Targeted changed-root notification avoids an extra O(n) effect-record scan; list validation, serialization, and reconciliation remain O(n).
+Cross-framework performance tables are historical snapshots from an excluded local benchmark workspace; the current checkout does not contain their competitor fixtures, runners, or raw arrays. The maintained provenance warning and tables live in the web docs. `npm run benchmark` is the tracked reproducible Worker fixture measurement, while the focused Chrome Worker test verifies throughput, cadence, bounded history, stale-write isolation, and route lifecycle behavior.

package/framework/build.mjs

@@ -1882,7 +1882,7 @@ function normalizeZustandMigrationSyntax(sourceFile, factory, context) {
 }
 
 function normalizeReactMigrationSyntax(sourceFile, factory, context, importedCollections = new Set()) {
-  const supported = new Set(["createContext", "useContext", "useEffect", "useReducer", "useRef", "useState"])
+  const supported = new Set(["createContext", "useContext", "useEffect", "useId", "useReducer", "useRef", "useState"])
   const erased = new Set(["memo", "useCallback", "useMemo"])
   const aliases = new Map()
   const reactObjects = new Set()
@@ -2074,6 +2074,24 @@ function normalizeReactMigrationSyntax(sourceFile, factory, context, importedCol
   return normalized
 }
 
+function validateUseIdSyntax(sourceFile) {
+  const imported = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && ["@kudzujs/core", "react"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useId"))
+  if (!imported) return
+  const visit = node => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "useId" && !isShadowedIdentifier(node.expression, sourceFile)) {
+      if (node.arguments.length) throw sourceNodeError(node, sourceFile, "useId() does not accept arguments")
+      const declaration = node.parent
+      const statement = declaration?.parent?.parent
+      const owner = nearestFunction(node)
+      if (!ts.isVariableDeclaration(declaration) || declaration.initializer !== node || !ts.isIdentifier(declaration.name) || !statement || !ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0 || !owner || !ts.isBlock(owner.body) || statement.parent !== owner.body) {
+        throw sourceNodeError(node, sourceFile, "useId() must be assigned to one top-level const identifier in a component")
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+}
+
 function importDeclarationNames(statement) {
   const names = []
   if (statement.importClause?.name) names.push(statement.importClause.name.text)
@@ -2158,6 +2176,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
     ts.setParentRecursive(sourceFile, false)
     sourceFile = normalizeReactMigrationSyntax(sourceFile, factory, context, importedCollections)
     ts.setParentRecursive(sourceFile, false)
+    validateUseIdSyntax(sourceFile)
     sourceFile = normalizeZustandMigrationSyntax(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
     sourceFile = normalizeRenderControlFlow(sourceFile, factory, context)
@@ -2173,6 +2192,7 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         ts.setParentRecursive(imported, false)
         imported = normalizeReactMigrationSyntax(imported, factory, context, importedSerializableCollectionNames(imported, target, sourceFiles, sourceIndex))
         ts.setParentRecursive(imported, false)
+        validateUseIdSyntax(imported)
         imported = normalizeZustandMigrationSyntax(imported, factory, context)
         ts.setParentRecursive(imported, false)
         imported = normalizeRenderControlFlow(imported, factory, context)
@@ -3281,6 +3301,7 @@ function validateKeyedList(parts, sourceFile, listValues, listEventItems, listCo
     if (!ts.isIdentifier(tag) || tag.text[0] !== tag.text[0].toLowerCase()) fail(node, "Keyed list items must use intrinsic JSX elements")
   }
   const visit = node => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "useId") fail(node, "useId() is not supported in keyed rows")
     if (ts.isJsxFragment(node)) fail(node, "Fragments are not supported in keyed lists")
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) validateElement(node)
     if (node !== root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) fail(node, nestedDiagnostic)
@@ -3586,6 +3607,7 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
         rowRefs.push({ name })
         continue
       }
+      if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useId") throw sourceNodeError(declaration.initializer, component.getSourceFile(), "useId() is not supported in keyed row components")
       if (!ts.isIdentifier(declaration.name) || !declaration.initializer) fail(declaration, `${label} component locals must be initialized identifiers`)
       const calculation = substituteClone(declaration.initializer, substitutions, factory, context)
       calculations.push({ name: declaration.name.text, expression: calculation })

package/framework/core.d.ts

@@ -5,6 +5,7 @@ export type EffectCleanup = () => void | Promise<void>
 export type EffectDependency = string | number | boolean | null
 export const Fragment: unique symbol
 
+export function useId(): string
 export function useState<T>(initialValue: T): [T, StateSetter<T>]
 export function useReducer<State, Action>(reducer: Reducer<State, Action>, initialValue: State): [State, Dispatch<Action>]
 export function useEffect(effect: () => void | EffectCleanup | Promise<void>, dependencies: readonly EffectDependency[]): void

package/framework/core.mjs

@@ -47,6 +47,12 @@ const svgAttributeAliases = {
 
 let renderContext
 
+export function useId() {
+  if (!renderContext) throw new Error("useId() can only run while rendering a Kudzu component")
+  if (renderContext.listRoot || renderContext.listRowRoot || renderContext.listTemplate) throw new Error("useId() is not supported in keyed rows")
+  return `k-${nextRenderId("i")}`
+}
+
 export function useState(initialValue, name) {
   if (!renderContext) {
     throw new Error("useState() can only run while rendering a Kudzu component")
@@ -406,7 +412,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}, props = {}, layout) {
-  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowRefs: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], stores: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerModules: new Set(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, nextId: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowRefs: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], stores: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerModules: new Set(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const page = { [routeScopeMarker]: true, component, props }
@@ -910,7 +916,7 @@ function nextRowList() {
 
 function nextRenderId(kind) {
   if (renderContext.scoped) return `${renderContext.renderScope === "layout" ? "l" : "r"}${kind}${renderContext.counters[renderContext.renderScope][kind]++}`
-  const counters = { s: "nextState", r: "nextRef", c: "nextCondition", l: "nextList", e: "nextEffect", p: "nextParam" }
+  const counters = { s: "nextState", r: "nextRef", c: "nextCondition", l: "nextList", e: "nextEffect", p: "nextParam", i: "nextId" }
   return `${kind}${renderContext[counters[kind]]++}`
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.7.12",
+  "version": "0.7.13",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -51,6 +51,7 @@
     "dev": "node ./bin/kudzu.mjs dev",
     "check": "tsc --noEmit && tsc -p test/fixtures/tsconfig.json --noEmit && node ./bin/kudzu.mjs build",
     "test": "node --test test/*.test.mjs",
+    "benchmark": "node test/performance.mjs",
     "prepublishOnly": "npm run check && npm test",
     "deploy": "wrangler deploy",
     "preview": "wrangler dev"