@kudzujs/core 0.14.3 → 0.15.1

package/PERFORMANCE.md

@@ -2,6 +2,26 @@
 
 Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm run benchmark:native`, `npm run benchmark:module-cache`, `npm run benchmark:project-navigation`, `npm run benchmark:project-state`, and `npm run benchmark:source-scale` are maintained in this repository; `npm run benchmark:commerce` is a maintained paired runner over the public external storefront; older excluded-workspace sections are historical provenance only and are not current framework rankings.
 
+## 0.15.1 Key-Scoped Native Popover Intake
+
+Measured 2026-08-27 on macOS arm64 with Node 24.14.0 and Chrome
+151.0.7922.174. The maintained project fixture uses native Popover with one
+key-scoped `useId()` relationship per project row. Required Chrome verifies
+Escape, light dismiss, trigger focus restoration, reorder identity, inserted
+and remounted IDs, and enhanced-navigation cleanup.
+
+The application emits 44 files totaling 171,202 raw / 53,629 aggregate gzip
+bytes with deploy SHA-256
+`46ba45b4a423b9627c6ede5f8dd3a667f593cb5401454ae42ecc66207b07b323`.
+The maintained two-route session contains 17 JavaScript files totaling 77,779
+raw / 27,050 aggregate gzip bytes. `/help` remains 0 B JavaScript.
+
+Seven fresh Chrome profiles record table update samples of `[0.4, 0.4, 0.5,
+0.4, 0.5, 0.5, 0.5]` ms, a 0.5 ms median and 0.4/0.5 ms range. Navigation
+samples are `[4, 2.4, 2.6, 2.5, 2.5, 2.8, 2.4]` ms, a 2.5 ms median and 2.4/4
+ms range. These ranges overlap prior retained-path evidence; no timing
+improvement or regression is claimed.
+
 ## 0.14.3 10,000-Item Browser Decision Intake
 
 Measured 2026-08-27 on Linux x64 with Node 24.14.0 and Chrome

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.14.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.14.3 - 10,000-item browser decision.** Measured direct DOM, pagination, and scroll-window alternatives select native pagination for large project tables without adding virtualization or range runtime semantics. Read the [release notes](./RELEASES.md#0143---10000-item-browser-decision), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.14.3), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.15.1 - Key-scoped native popovers.** Keyed row `useId()` now scopes native Popover triggers and intrinsic ID references by row key without adding an overlay runtime. Read the [release notes](./RELEASES.md#0151---key-scoped-native-popovers), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.15.1), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,39 @@
 # Kudzu Releases
 
+## 0.15.1 - Key-Scoped Native Popovers
+
+Kudzu 0.15.1 lets ordinary keyed row components use `useId()` for native
+Popover triggers and intrinsic ID relationships without duplicate cloned IDs.
+
+### Changed in 0.15.1
+
+- Key-scoped keyed-row `useId()` through the existing list ownership path.
+- Rewrites cloned `id`, `htmlFor`, static ARIA IDREF, `form`, `headers`, `list`,
+  and `popovertarget` attributes.
+- Rejects keyed IDs used in text, handlers, aliases, arbitrary attributes, or
+  component prop forwarding.
+- Proves native Popover Escape, light dismiss, trigger focus restoration,
+  retained reorder identity, inserted and remounted IDs, and route cleanup.
+- Adds no overlay runtime, focus manager, positioning engine, Portal/Slot
+  reconciliation, retained component tree, or public API.
+- Updates `create-kudzu@0.1.126` to generate projects on
+  `@kudzujs/core@^0.15.1`.
+
+### Output And Browser Evidence
+
+- The maintained application emits 44 files totaling 171,202 raw / 53,629
+  aggregate gzip bytes; `/help` remains 0 B JavaScript.
+- The two-route session remains 17 JavaScript files totaling 77,779 raw /
+  27,050 aggregate gzip bytes.
+- Seven Chrome profiles record a 0.5 ms table-update median and 2.5 ms
+  navigation median, within prior retained-path ranges.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.15.1
+```
+
 ## 0.14.3 - 10,000-Item Browser Decision
 
 Kudzu 0.14.3 measures direct DOM, pagination, and scroll-window alternatives

package/docs/next-architecture/application-capability-release-plan.md

@@ -1030,6 +1030,13 @@ virtual range ownership.
 - **Done condition:** range semantics are package-neutral, optional, measured,
   and absent from non-virtual routes.
 
+Closed by stop condition. The `0.14.3` decision selected pagination over both
+direct 10,000-row DOM and the authored fixed-height scroll window. No independent
+application fixture proves pagination or application-owned bounded ranges
+insufficient, against the required three. Kudzu therefore adds no visible-range
+owner, measurement policy, range primitive, or virtualization runtime and moves
+to the next evidence-ready application capability.
+
 ## `0.15.x`: Overlay And Layer Ownership
 
 ### `0.15.0`: Native Dialog Baseline
@@ -1040,6 +1047,31 @@ virtual range ownership.
 - **Stop condition:** a custom modal/focus-trap runtime replaces `<dialog>`.
 - **Done condition:** project delete and edit confirmation pass accessibly.
 
+Implementation evidence is local and release gates remain pending. The maintained
+project application replaces immediate keyed project deletion with one shared
+native `<dialog>`, one route-owned object ref, and one pending project ID state.
+Existing row callback specialization opens the browser top layer; native cancel,
+explicit cancel, and confirmation handlers close it without a Portal, focus trap,
+overlay runtime, or retained component tree.
+
+Required Chrome proves modal top-layer behavior, native initial focus, explicit
+cancel, Escape-equivalent `requestClose()`, trigger-focus restoration, confirmed
+keyed deletion with fallback focus, retained sibling identity, and exact top-layer
+release on enhanced route navigation. The static `/help` sibling remains 0 B
+JavaScript. The slice adds no semantic primitive, IR kind, compiler pass,
+production compiler/runtime line, normalization rule, adapter, runtime concept,
+or public API. The application emits 44 files totaling 169,778 raw / 53,294
+aggregate gzip bytes with deploy SHA-256
+`91c5517e69c341bbd2051f07b3f0ad7df627098ba8e1984561268ea8666f3407`.
+The maintained two-route session remains 17 JavaScript files totaling 77,453 raw
+/ 26,905 aggregate gzip bytes.
+
+Seven fresh macOS arm64 Chrome 151 profiles record table update samples of
+`[0.5, 0.6, 0.6, 0.6, 0.6, 0.4, 0.5]` ms, a 0.6 ms median and 0.4/0.6 ms range,
+plus navigation samples of `[2.3, 2.6, 2.9, 2.6, 2.5, 2.7, 2.5]` ms, a 2.6 ms
+median and 2.3/2.9 ms range. These retained-path ranges overlap the previous
+same-environment evidence, so no timing improvement or regression is claimed.
+
 ### `0.15.1`: Popover, Dropdown, And Menu Behavior
 
 - **Purpose:** establish the native-first non-modal overlay boundary.
@@ -1050,6 +1082,38 @@ virtual range ownership.
 - **Stop condition:** package Portal/Slot reconciliation enters the runtime.
 - **Done condition:** supported native and custom boundaries are explicit.
 
+Completed with the maintained project application as the qualifying fixture. A
+keyed project row now authors one top-level `useId()`, a native
+`popovertarget`, and a native `popover="auto"` action group. The compiler scopes
+the generated ID by the existing keyed ownership path and the list runtime
+rewrites only intrinsic `id`, `for`, static ARIA IDREF, `form`, `headers`,
+`list`, and `popovertarget` attributes. Unsupported ID escapes receive a source
+diagnostic. Native Chrome behavior supplies the top layer, Escape, light
+dismiss, and trigger focus restoration; ordinary keyed ownership preserves IDs
+across reorder, scopes inserted rows, recreates deterministic IDs after
+remove/re-add, and releases an open popover during enhanced navigation. The
+authored overlay uses static anchor positioning and `role="group"`, so menu
+roving focus is not applicable.
+
+The slice adds no semantic primitive, IR kind, compiler pass, runtime concept,
+public API, Portal/Slot reconciliation, focus manager, positioning engine, or
+retained overlay tree. It adds 52 and removes 24 production lines across the
+source compiler, RouteIR validation, capability projection, build renderer, and
+existing list runtime. The maintained application emits 44 files totaling
+171,202 raw / 53,629 aggregate gzip bytes with deploy SHA-256
+`46ba45b4a423b9627c6ede5f8dd3a667f593cb5401454ae42ecc66207b07b323`.
+The two-route session remains 17 JavaScript files totaling 77,779 raw / 27,050
+aggregate gzip bytes, a 326 raw / 145 gzip byte increase from `0.15.0`; the
+static `/help` sibling remains 0 B JavaScript. Familiar React-shaped `useId()`
+authoring remains intact, so no application adapter or migration-only source
+structure is added.
+
+Seven fresh macOS arm64 Chrome 151 profiles record table update samples of
+`[0.4, 0.4, 0.5, 0.4, 0.5, 0.5, 0.5]` ms, a 0.5 ms median and 0.4/0.5 ms range,
+plus navigation samples of `[4, 2.4, 2.6, 2.5, 2.5, 2.8, 2.4]` ms, a 2.5 ms
+median and 2.4/4 ms range. These retained-path ranges overlap prior evidence,
+so no timing improvement or regression is claimed.
+
 ### `0.15.2`: Toast And Notification Ownership
 
 - **Purpose:** provide application feedback across route mutations.
@@ -1477,5 +1541,8 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.14.0` | Released | Preserve native table CRUD, retained identity, keyboard access, and measured update evidence. | None |
 | `0.14.1` | Released | Preserve immutable object-state replacement, nested keyed identity, latest handlers, and exact row release. | None |
 | `0.14.2` | Released | Preserve bounded cursor loading, duplicate suppression, retry/end behavior, retained identity, and route cleanup. | None |
-| `0.14.3` | Release candidate | Complete commit, CI, tag, GitHub release, npm publication, and registry verification. | Release transaction |
-| `0.14.4` onward | Blocked | Complete or explicitly close `0.14.3` first. | Ordered patch boundary |
+| `0.14.3` | Released | Preserve the published 10,000-item pagination decision and measurement evidence. | None |
+| `0.14.4` | Closed by stop condition | Preserve pagination as the selected strategy until three independent fixtures authorize virtual ownership review. | Evidence favors pagination; zero qualifying fixtures |
+| `0.15.0` | Closed by native composition | Preserve the native dialog, focus, cancellation, keyed deletion, and route cleanup evidence. | No production change; no release consumed |
+| `0.15.1` | Released | Preserve key-scoped IDs, native Popover behavior, retained keyed identity, and route cleanup evidence. | None |
+| `0.15.2` | Active | Begin with a real toast and notification ownership fixture. | None |

package/docs/next-architecture/versioning.md

@@ -66,7 +66,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 
 ## Generator Versions
 
-`create-kudzu@0.1.125` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.14.3`.
+`create-kudzu@0.1.126` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.15.1`.
 
 ## Release Boundary
 

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`, direct intrinsic `forwardRef`, top-level `const` identifiers initialized by `useId()`, and default, namespace, or named `Fragment`. A named or default zero-argument custom hook imported from a relative TypeScript module may return direct shorthand state/setter pairs and callbacks that capture those states, including a callback that resets multiple states to direct primitive literals; callers use one top-level `const` object destructuring without aliases, defaults, or rest. Relative Context-hook actions may require exposed Provider state/setter fields without forcing those hidden fields into public consumer destructuring; compiler-owned collision-free aliases preserve same-named consumer locals. Kudzu's JSX declarations accept ReactNode-shaped component returns and contextually type common intrinsic DOM events, so strict React component props do not need migration-only `unknown` or explicit event annotations. `forwardRef()` accepts one inline synchronous `(props, ref)` function and requires the object ref exactly once on its direct intrinsic root; the compiler removes `ref` from props/rest and erases the wrapper. `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, including type-only `as const` and `satisfies` wrappers, and may read direct local state declared in their dependency array. `compiler/react-migration-pass.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`, direct intrinsic `forwardRef`, top-level `const` identifiers initialized by `useId()`, and default, namespace, or named `Fragment`. A named or default zero-argument custom hook imported from a relative TypeScript module may return direct shorthand state/setter pairs and callbacks that capture those states, including a callback that resets multiple states to direct primitive literals; callers use one top-level `const` object destructuring without aliases, defaults, or rest. Relative Context-hook actions may require exposed Provider state/setter fields without forcing those hidden fields into public consumer destructuring; compiler-owned collision-free aliases preserve same-named consumer locals. Kudzu's JSX declarations accept ReactNode-shaped component returns and contextually type common intrinsic DOM events, so strict React component props do not need migration-only `unknown` or explicit event annotations. `forwardRef()` accepts one inline synchronous `(props, ref)` function and requires the object ref exactly once on its direct intrinsic root; the compiler removes `ref` from props/rest and erases the wrapper. `useId()` becomes a deterministic build-time HTML ID and emits no browser capability; keyed rows key-scope direct intrinsic ID and ID-reference attributes through existing list ownership by row key. Collection memos may start from local array state or a named relative import of an exported JSON-safe `const` array, including type-only `as const` and `satisfies` wrappers, and may read direct local state declared in their dependency array. `compiler/react-migration-pass.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.
 
 Compilation begins from page entries and follows relative runtime imports, re-exports, and validated Worker references; unreachable TypeScript migration files are not transformed. Direct maps over imported immutable JSON-safe arrays fold to literals for zero-JavaScript static rows. Synchronous relative calculation functions may return objects whose direct static fields feed reactive JSX bindings; build rendering uses current signal values and route-specific binding ESM reevaluates the same helper after state commits. One direct array field may instead feed a keyed intrinsic map: its evaluator refreshes a compiler-owned array anchor before the existing list reconciler runs, preserving keyed DOM and SVG identity without a calculation runtime. That field must remain a JSON-safe array after every source-state commit. Package imports have a separate narrow boundary: direct references inside intrinsic JSX event callbacks are erased from build modules and bundled into route handler ESM, while render-time, effect, helper-indirect, and mixed package use fails.
 

package/framework/compiler/route-capability-planner.mjs

@@ -68,7 +68,7 @@ export function planRouteCapabilities(records, { navigationRouteCount = 0 } = {}
       lists.expressionAttributes ||= Boolean(list.expressionAttributes)
       lists.seeds ||= Boolean(list.seed || list.valueSeed)
       lists.effects ||= Boolean(list.effects)
-      lists.rowHooks ||= Boolean(list.rowStates?.length || list.rowRefs?.length)
+      lists.rowHooks ||= Boolean(list.rowStates?.length || list.rowRefs?.length || list.rowIds?.length)
       lists.rowRefs ||= Boolean(list.rowRefs?.length)
       lists.complexRowState ||= Boolean(list.rowStates?.some(state => state.initializer === "list-item" || state.initialValue !== null && typeof state.initialValue === "object"))
       lists.nested ||= Boolean(list.ownerField)
@@ -77,7 +77,7 @@ export function planRouteCapabilities(records, { navigationRouteCount = 0 } = {}
       lists.static ||= Boolean(list.static)
       lists.indexes ||= Boolean(list.indexed)
       lists.stableFastPaths ||= !list.children && !list.ownerField && list.key !== null && !list.indexed && !list.reducer && !list.selector
-      lists.generalRowHooks ||= Boolean(list.ownerField && (list.rowStates?.length || list.rowRefs?.length))
+      lists.generalRowHooks ||= Boolean(list.rowIds?.length || list.ownerField && (list.rowStates?.length || list.rowRefs?.length))
       lists.mounts ||= Boolean(list.mount)
     }
   }

package/framework/compiler/route-ir.mjs

@@ -164,7 +164,7 @@ function assertList(list, index, ids, stateIds, listIds, parentByChild) {
     parentByChild.set(child.id, list.id)
   }
   for (const row of list.rowStates ?? []) if (!isRecord(row) || !rowTemplate(row.id) || !Object.hasOwn(row, "initialValue") || row.initializer !== undefined && row.initializer !== "list-item") throw new Error(`${label} has invalid row state`)
-  for (const row of [...(list.rowRefs ?? []), ...(list.rowConditions ?? [])]) if (!rowTemplate(row)) throw new Error(`${label} has invalid row ownership ID`)
+  for (const row of [...(list.rowRefs ?? []), ...(list.rowIds ?? []), ...(list.rowConditions ?? [])]) if (!rowTemplate(row)) throw new Error(`${label} has invalid row ownership ID`)
   if (list.seed && list.valueSeed || list.seed !== undefined && !validSeed(list.seed) || list.valueSeed !== undefined && !validSeed(list.valueSeed)) throw new Error(`${label} has invalid seed`)
 }
 

package/framework/compiler/source-compiler.mjs

@@ -517,6 +517,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     let usesListItem = false
     let usesRowState = false
     let usesRowRef = false
+    let usesRowId = false
     let usesComponentState = false
     let usesComponentId = false
     let usesComponentRef = false
@@ -1199,7 +1200,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           ...result.ordinaryStates.map(({ state, setter, source }) => ({ name: state, setter, kind: "component", ...(analysisSite(source, "hook") ? { site: analysisSite(source, "hook") } : {}), ...(analysisSource(source) ? { source: analysisSource(source) } : {}) }))
         ],
         refs: [...result.rowRefs.map(({ name, source }) => ({ name, kind: "row", ...(analysisSite(source, "hook") ? { site: analysisSite(source, "hook") } : {}), ...(analysisSource(source) ? { source: analysisSource(source) } : {}) })), ...result.ordinaryRefs.map(({ name, source }) => ({ name, kind: "component", ...(analysisSite(source, "hook") ? { site: analysisSite(source, "hook") } : {}), ...(analysisSource(source) ? { source: analysisSource(source) } : {}) }))],
-        ids: result.ordinaryIds.map(({ name, source }) => ({ name, ...(analysisSite(source, "hook") ? { site: analysisSite(source, "hook") } : {}), ...(analysisSource(source) ? { source: analysisSource(source) } : {}) }))
+        ids: [...result.rowIds.map(({ name, source }) => ({ name, kind: "row", ...(analysisSite(source, "hook") ? { site: analysisSite(source, "hook") } : {}), ...(analysisSource(source) ? { source: analysisSource(source) } : {}) })), ...result.ordinaryIds.map(({ name, source }) => ({ name, kind: "component", ...(analysisSite(source, "hook") ? { site: analysisSite(source, "hook") } : {}), ...(analysisSource(source) ? { source: analysisSource(source) } : {}) }))]
       })
       result.propStateOwners = new Map(result.props.flatMap(prop => {
         const expression = result.propExpressions.get(prop.name)
@@ -1216,7 +1217,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       return result
     }
     const registerRowHooks = (call, specialization) => {
-      if (!specialization.rowStates.length && !specialization.rowRefs.length) return
+      if (!specialization.rowStates.length && !specialization.rowRefs.length && !specialization.rowIds.length) return
       let owner
       for (let current = call.parent; current; current = current.parent) {
         if (isFunctionLike(current) && settersByFunction.has(current)) {
@@ -1236,6 +1237,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       rowHookCalls.push(call)
       usesRowState ||= specialization.rowStates.length > 0
       usesRowRef ||= specialization.rowRefs.length > 0
+      usesRowId ||= specialization.rowIds.length > 0
     }
     const mergeSpecializedImports = (root, componentSource, call, effects = []) => {
       const componentImports = clientImportBindings(componentSource, componentSource.fileName, sourceFiles)
@@ -1716,7 +1718,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       let count = 0
       const visit = (node, currentAggregate = aggregate) => {
         if (node !== root && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "map" && containsJsx(node)) {
-          const nestedAggregate = { calculations: [], effects: [], hookDeclarations: [], rowStates: [], rowRefs: [], specializations: [] }
+          const nestedAggregate = { calculations: [], effects: [], hookDeclarations: [], rowStates: [], rowRefs: [], rowIds: [], specializations: [] }
           for (const argument of node.arguments) visit(argument, nestedAggregate)
           if (nestedAggregate.hookDeclarations.length || nestedAggregate.effects.length) nestedRowSpecializations.set(`${node.pos}:${node.end}`, nestedAggregate)
           return
@@ -1749,6 +1751,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
             currentAggregate.hookDeclarations.push(...specialization.hookDeclarations)
             currentAggregate.rowStates.push(...specialization.rowStates)
             currentAggregate.rowRefs.push(...specialization.rowRefs)
+            currentAggregate.rowIds.push(...specialization.rowIds)
           }
           replacements.set(node, specialization.root)
           count++
@@ -1784,7 +1787,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     }
     for (const { node, parts: originalParts } of rawRenderedLists) {
       if (keyedListParentTag(node) === "table") throw new Error("Keyed table rows must be wrapped in <tbody>, <thead>, or <tfoot>")
-      const specialization = componentSpecializations.get(originalParts.root) ?? { root: originalParts.root, calculations: [], effects: [], hookDeclarations: [], rowStates: [], rowRefs: [], ordinaryStates: [] }
+      const specialization = componentSpecializations.get(originalParts.root) ?? { root: originalParts.root, calculations: [], effects: [], hookDeclarations: [], rowStates: [], rowRefs: [], rowIds: [], ordinaryStates: [] }
       const componentSource = specialization.componentSource ?? sourceFile
       specialization.root = expandKeyedComponents(specialization.root, componentSource, specialization.component ? [specialization.component] : [], specialization)
       if (specialization.imported) synthesizeTree(specialization.root = mergeSpecializedImports(specialization.root, componentSource, originalParts.root, specialization.effects))
@@ -1811,6 +1814,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         specializations: [specialization.analysis?.slot, ...(specialization.specializations ?? [])].filter(slot => slot !== undefined),
         rowStates: [...specialization.rowStates, ...specialization.ordinaryStates],
         rowRefs: specialization.rowRefs,
+        rowIds: specialization.rowIds,
         analysisStateOwners: new Map([...stateOwnersForNode(originalParts.root), ...(specialization.propStateOwners ?? []), ...[...specialization.rowStates, ...specialization.ordinaryStates].map(state => [state.state, state.analysisReference])])
       }
       for (const calculation of specialization.calculations) {
@@ -2297,6 +2301,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     if (usesListEffects) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useEffect"), factory.createIdentifier("__kListUseEffect")))
     if (usesRowState) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useState"), factory.createIdentifier("__kRowUseState")))
     if (usesRowRef) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useRef"), factory.createIdentifier("__kRowUseRef")))
+    if (usesRowId) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useId"), factory.createIdentifier("__kRowUseId")))
     if (usesComponentState) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useState"), factory.createIdentifier("__kComponentUseState")))
     if (usesComponentId) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useId"), factory.createIdentifier("__kComponentUseId")))
     if (usesComponentRef) behaviorImports.push(factory.createImportSpecifier(false, factory.createIdentifier("useRef"), factory.createIdentifier("__kComponentUseRef")))
@@ -2656,7 +2661,6 @@ function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpeci
     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)
@@ -2697,6 +2701,7 @@ function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpeci
           specializations: [specialization?.analysis?.slot, ...(specialization?.specializations ?? [])].filter(slot => slot !== undefined),
           rowStates: specializedStates,
           rowRefs: specialization?.rowRefs ?? [],
+          rowIds: specialization?.rowIds ?? [],
           analysisStateOwners: new Map([...(parts.analysisStateOwners ?? []), ...(specialization?.propStateOwners ?? []), ...specializedStates.map(state => [state.state, state.analysisReference])])
         }
         for (const calculation of specialization?.calculations ?? []) {
@@ -2747,6 +2752,8 @@ function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpeci
   return analysis
 }
 
+const keyedIdReferenceAttributes = new Set(["id", "htmlFor", "aria-activedescendant", "aria-controls", "aria-describedby", "aria-details", "aria-errormessage", "aria-flowto", "aria-labelledby", "aria-owns", "form", "headers", "list", "popovertarget"])
+
 function directConstObjectLiteral(expression, call) {
   expression = unwrapExpression(expression)
   if (ts.isObjectLiteralExpression(expression)) return expression
@@ -2947,6 +2954,7 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
   const hookDeclarations = []
   const rowStates = []
   const rowRefs = []
+  const rowIds = []
   const ordinaryStates = []
   const ordinaryRefs = []
   const ordinaryIds = []
@@ -3012,13 +3020,14 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
         continue
       }
       if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useId") {
-        if (!ordinaryHooks) throw sourceNodeError(declaration.initializer, component.getSourceFile(), "useId() is not supported in keyed row components")
-        if (declaration.initializer.arguments.length || !ts.isIdentifier(declaration.name)) throw sourceNodeError(declaration.initializer, component.getSourceFile(), "Setter-callback component useId() must initialize one top-level const identifier without arguments")
-        const name = `__kComponentId${Math.max(0, call.pos)}_${hookDeclarations.length}`
+        const hookLabel = ordinaryHooks ? "Setter-callback component" : "Keyed row"
+        if (declaration.initializer.arguments.length || !ts.isIdentifier(declaration.name)) throw sourceNodeError(declaration.initializer, component.getSourceFile(), `${hookLabel} useId() must initialize one top-level const identifier without arguments`)
+        const ids = ordinaryHooks ? ordinaryIds : rowIds
+        const name = `${ordinaryHooks ? "__kComponentId" : "__kRowId"}${Math.max(0, call.pos)}_${ids.length}`
         substitutions.set(declaration.name.text, factory.createIdentifier(name))
-        const initializer = factory.createCallExpression(factory.createIdentifier("__kComponentUseId"), undefined, [])
+        const initializer = factory.createCallExpression(factory.createIdentifier(ordinaryHooks ? "__kComponentUseId" : "__kRowUseId"), undefined, [])
         hookDeclarations.push(factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(factory.createIdentifier(name), undefined, undefined, initializer)], ts.NodeFlags.Const)))
-        ordinaryIds.push({ name, source: declaration })
+        ids.push({ name, local: declaration.name.text, source: declaration })
         continue
       }
       if (!ts.isIdentifier(declaration.name) || !declaration.initializer) fail(declaration, `${label} component locals must be initialized identifiers`)
@@ -3029,6 +3038,10 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
     }
     returned = last.expression
   }
+  for (const id of rowIds) {
+    for (const reference of referenceIdentifiers(returned, id.local)) if (!validKeyedIdReference(reference)) throw sourceNodeError(reference, component.getSourceFile(), "Keyed row useId() values may only be used in intrinsic id and ID-reference attributes")
+    for (const calculation of calculations) if (referenceIdentifiers(calculation.expression, id.local).length) throw sourceNodeError(calculation.expression, component.getSourceFile(), "Keyed row useId() values may only be used directly in intrinsic id and ID-reference attributes")
+  }
   let unsupportedHook
   const findUnsupportedHook = node => {
     if (unsupportedHook) return
@@ -3058,6 +3071,7 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
     hookDeclarations,
     rowStates,
     rowRefs,
+    rowIds,
     ordinaryStates,
     ordinaryRefs,
     ordinaryIds,
@@ -3068,6 +3082,16 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
   }
 }
 
+function validKeyedIdReference(reference) {
+  for (let current = reference.parent; current; current = current.parent) {
+    if (!ts.isJsxAttribute(current)) continue
+    const element = current.parent?.parent
+    const tag = element?.tagName
+    return keyedIdReferenceAttributes.has(current.name.text) && ts.isIdentifier(tag) && tag.text[0] === tag.text[0].toLowerCase()
+  }
+  return false
+}
+
 function isSerializableStateLiteral(node) {
   const value = unwrapExpression(node)
   if (isPrimitiveDefaultLiteral(value)) return true

package/framework/core.mjs

@@ -49,8 +49,7 @@ 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")}`
+  return `k-${renderContext.listRoot || renderContext.listRowRoot ? nextRowRenderId("i") : nextRenderId("i")}`
 }
 
 export function useState(initialValue, name, initializer) {
@@ -484,7 +483,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}, props = {}, layout) {
-  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", applicationRoute: metadata.applicationRoute, 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: [], captureCache: new WeakMap(), sharedStates: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerReferences: new Map(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], searchParamsWritable: false, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", applicationRoute: metadata.applicationRoute, 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: [], listRowIds: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], captureCache: new WeakMap(), sharedStates: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerReferences: new Map(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], searchParamsWritable: false, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const page = { [routeScopeMarker]: true, component, props }
@@ -941,6 +940,7 @@ async function renderList(node, namespace, selectValue) {
   const previousListEffectOwners = renderContext.listEffectOwners
   const previousListRowStates = renderContext.listRowStates
   const previousListRowRefs = renderContext.listRowRefs
+  const previousListRowIds = renderContext.listRowIds
   const previousListRowConditions = renderContext.listRowConditions
   const previousListRowLists = renderContext.listRowLists
   try {
@@ -948,10 +948,11 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listEffectOwners = rowList?.effectOwners ?? []
     renderContext.listRowStates = rowList?.rowStates ?? []
     renderContext.listRowRefs = rowList?.rowRefs ?? []
+    renderContext.listRowIds = rowList?.rowIds ?? []
     renderContext.listRowConditions = rowList?.rowConditions ?? []
     renderContext.listRowLists = rowList?.rowLists ?? []
     renderContext.listFields = new Set([node.keyField])
-    const templateRoot = { id, state: node.items.id, descriptor, template: true, effects: [], item: {}, path: ownerRoot?.path ?? [], rowIndexes: { s: 0, r: 0, c: 0, l: 0 } }
+    const templateRoot = { id, state: node.items.id, descriptor, template: true, effects: [], item: {}, path: ownerRoot?.path ?? [], rowIndexes: { s: 0, r: 0, i: 0, c: 0, l: 0 } }
     renderContext.listRoot = templateRoot
     renderContext.listRowRoot = templateRoot
     const template = await renderNode(node.render({}, 0), namespace, selectValue)
@@ -974,6 +975,7 @@ async function renderList(node, namespace, selectValue) {
       descriptor.rowRefs = renderContext.listRowRefs.map(({ id }) => id)
       descriptor.mount = true
     }
+    if (renderContext.listRowIds.length) descriptor.rowIds = renderContext.listRowIds.map(({ id }) => id)
     if (descriptor.rowStates && !descriptor.effects && !descriptor.nested && !template.includes("data-k-text")) descriptor.fastRelease = true
     const valueSeed = node.ownerField || node.keyField === null ? undefined : listSeed(node.values, renderContext.listFields)
     const seed = node.selector.length ? undefined : valueSeed
@@ -984,7 +986,7 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listInitialMarkers = Boolean(descriptor.conditions)
     for (const [index, item] of node.values.entries()) {
       const key = node.keyField === null ? index : item[node.keyField]
-      renderContext.listRoot = { id, state: node.items.id, descriptor, key, template: false, effects: [], item, path: [...(ownerRoot?.path ?? []), `${id}=${typeof key}:${key}`], rowIndexes: { s: 0, r: 0, c: 0, l: 0 } }
+      renderContext.listRoot = { id, state: node.items.id, descriptor, key, template: false, effects: [], item, path: [...(ownerRoot?.path ?? []), `${id}=${typeof key}:${key}`], rowIndexes: { s: 0, r: 0, i: 0, c: 0, l: 0 } }
       renderContext.listRowRoot = renderContext.listRoot
       current += await renderNode(node.render(item, index), namespace, selectValue)
     }
@@ -1007,6 +1009,7 @@ async function renderList(node, namespace, selectValue) {
     renderContext.listEffectOwners = previousListEffectOwners
     renderContext.listRowStates = previousListRowStates
     renderContext.listRowRefs = previousListRowRefs
+    renderContext.listRowIds = previousListRowIds
     renderContext.listRowConditions = previousListRowConditions
     renderContext.listRowLists = previousListRowLists
     renderContext.listDepth--
@@ -1017,7 +1020,7 @@ function nextRowList() {
   const root = renderContext.listRoot ?? renderContext.listRowRoot
   const index = root.rowIndexes.l++
   if (renderContext.listTemplate) {
-    const entry = renderContext.listRowLists[index] ?? { id: nextRenderId("l"), rowLists: [], rowStates: [], rowRefs: [], rowConditions: [], effectOwners: [], planned: false }
+    const entry = renderContext.listRowLists[index] ?? { id: nextRenderId("l"), rowLists: [], rowStates: [], rowRefs: [], rowIds: [], rowConditions: [], effectOwners: [], planned: false }
     renderContext.listRowLists[index] = entry
     return entry
   }
@@ -1035,7 +1038,7 @@ function nextRenderId(kind) {
 function nextRowRenderId(kind, initialValue, initializer) {
   const root = renderContext.listRoot ?? renderContext.listRowRoot
   const index = root.rowIndexes[kind]++
-  const entries = kind === "s" ? renderContext.listRowStates : kind === "r" ? renderContext.listRowRefs : renderContext.listRowConditions
+  const entries = kind === "s" ? renderContext.listRowStates : kind === "r" ? renderContext.listRowRefs : kind === "i" ? renderContext.listRowIds : renderContext.listRowConditions
   if (renderContext.listTemplate) {
     const entry = entries[index]
     if (entry) return entry.id
@@ -1044,7 +1047,7 @@ function nextRowRenderId(kind, initialValue, initializer) {
     return id
   }
   const entry = entries[index]
-  if (!entry) throw new Error(`Keyed row ${kind === "s" ? "state hooks" : kind === "r" ? "ref hooks" : "conditionals"} must have the same order for every item`)
+  if (!entry) throw new Error(`Keyed row ${kind === "s" ? "state hooks" : kind === "r" ? "ref hooks" : kind === "i" ? "ID hooks" : "conditionals"} must have the same order for every item`)
   return rowRenderId(entry.id, root.descriptor.ownerField ? root.path : [`${typeof root.key}:${root.key}`])
 }
 

package/framework/list-runtime.js

@@ -19,6 +19,7 @@ const conditionTemplates = __KUDZU_LIST_CONDITIONS__ ? new WeakMap() : undefined
 const itemPartsSelector = `[data-k-list-text]${__KUDZU_LIST_ATTRIBUTES__ ? ",[data-k-list-attrs]" : ""}${__KUDZU_LIST_EVENTS__ ? ",[data-k-list-events]" : ""}${__KUDZU_LIST_EXPRESSIONS__ ? ",[data-k-list-expression]" : ""}${__KUDZU_LIST_EXPRESSION_ATTRIBUTES__ ? ",[data-k-list-expression-attrs]" : ""}${__KUDZU_LIST_CONDITIONS__ ? ",[data-k-list-condition]" : ""}${__KUDZU_LIST_EFFECTS__ ? ",[data-k-effects]" : ""}`
 const childPrototypes = __KUDZU_NESTED_LISTS__ ? new WeakMap() : undefined
 const itemPartPlans = __KUDZU_NESTED_LISTS__ ? new WeakMap() : undefined
+const rowIdAttributes = new Set(["id", "for", "aria-activedescendant", "aria-controls", "aria-describedby", "aria-details", "aria-errormessage", "aria-flowto", "aria-labelledby", "aria-owns", "form", "headers", "list", "popovertarget"])
 
 function commitLists(id) {
   const lists = listTargets.get(id)
@@ -742,7 +743,7 @@ function listItemPartPlan(template, nested = false, descriptor) {
     conditions: __KUDZU_LIST_CONDITIONS__ ? parts.conditions.map(([node, descriptor]) => [location(node), descriptor, node]) : [],
     effects: __KUDZU_LIST_EFFECTS__ ? parts.effects.map(location) : [],
     rowIds: structural && __KUDZU_GENERAL_ROW_HOOKS__ && hasRowHooks(descriptor) ? source.flatMap(node => {
-      const attributes = [...node.attributes].filter(attribute => attribute.name.startsWith("data-k-") && attribute.value.includes("$k")).map(attribute => attribute.name)
+      const attributes = [...node.attributes].filter(attribute => (attribute.name.startsWith("data-k-") || rowIdAttributes.has(attribute.name)) && attribute.value.includes("$k")).map(attribute => attribute.name)
       return attributes.length ? [[location(node), attributes]] : []
     }) : []
   }
@@ -1086,7 +1087,7 @@ function replaceOwnedRowIds(root) {
   if (!directRowReplacements.delete(root)) return replaceRowIds(root, rowReplacements.get(root))
   const path = listRowPaths.get(root)
   const replace = node => {
-    for (const attribute of [...node.attributes]) if (attribute.name.startsWith("data-k-") && attribute.value.includes("$k")) attribute.value = attribute.value.replaceAll("$k", path)
+    for (const attribute of [...node.attributes]) if ((attribute.name.startsWith("data-k-") || rowIdAttributes.has(attribute.name)) && attribute.value.includes("$k")) attribute.value = attribute.value.replaceAll("$k", path)
     for (const child of node.children) replace(child)
     for (const child of node.content?.children ?? []) replace(child)
   }
@@ -1095,7 +1096,7 @@ function replaceOwnedRowIds(root) {
 /* general-row-hooks-end */
 
 function hasRowHooks(descriptor) {
-  return Boolean(descriptor.rowStates?.length || descriptor.rowRefs?.length || descriptor.rowConditions?.length)
+  return Boolean(descriptor.rowStates?.length || descriptor.rowRefs?.length || descriptor.rowIds?.length || descriptor.rowConditions?.length)
 }
 
 function listLifecycle(descriptor, template) {

package/package.json

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