@kudzujs/core 0.16.48 → 0.17.0

package/README.md

@@ -12,9 +12,9 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 *Watch: React-shaped TSX to static HTML and route-specific ESM in 22 seconds.*
 
-> Experimental `0.16.x`: the compiler API and supported TSX surface may change.
+> Experimental `0.17.x`: the compiler API and supported TSX surface may change.
 
-**Current release: [0.16.48](https://github.com/kudzujs/kudzu/releases/tag/v0.16.48).** Binding setup uses one native attribute read per selected property and removes temporary arrays and name conversion. Measured JavaScript savings are 53 raw / 43 gzip bytes in C2 and 153 / 119 in Project, with unchanged HTML, route plans and application behavior. The 21-profile comparison does not establish faster row restoration. Generator `create-kudzu@0.1.160` is unchanged. No reliable AI-token saving is established; the AI-cost/1.0 gates remain blocked.
+**Current release: [0.17.0](https://github.com/kudzujs/kudzu/releases/tag/v0.17.0).** Selected calculation effect dependencies accept static primitive configuration alongside at least two direct state inputs, reusing existing normalization and evaluators. Proven read-only effects omit state-write machinery, and ordinary owned effects omit keyed-row machinery. Measured fixture savings range from 253 to 990 raw JavaScript bytes without new runtime concepts. Generator `create-kudzu@0.1.161` targets core `^0.17.0`. Restoration latency and AI-cost/1.0 gates remain unresolved.
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)
@@ -177,6 +177,7 @@ ordinary React-shaped TSX
 - React Bootstrap `Row` and `Col` with children, static classes, and numeric literal `Col` breakpoints erase to native Bootstrap grid markup; applications retain ownership of Bootstrap CSS.
 - Browser-only query data uses owned effects with application loading/error/data state; URL-derived dependencies, stale-response isolation, keyed results, and recovery require no query package runtime.
 - Only TypeScript modules reachable from pages are compiled. Imported immutable direct maps can fold to static HTML, while direct fields from relative structured calculations reevaluate through route binding ESM.
+- A selected primitive calculation field can be the sole effect dependency with at least two direct state inputs plus static primitive arguments. Strings, finite numbers except negative zero, booleans, null, and const aliases normalized to those literals add no signals or calculation runtime. Object/array configuration, mutable locals, composed arguments, undefined/non-finite values, and parameter defaults/rest remain unsupported.
 - Package imports used directly inside JSX event callbacks are removed from build modules and retained only in bundled route handler ESM.
 - A named or aliased React Router `useNavigate()` top-level binding lowers direct nested-callback calls with safe static root-relative destinations to native `location.assign()` or `location.replace()` navigation.
 - Unsupported nearby patterns fail during the build with a source location and actionable boundary.

package/framework/compiler/effect-codegen.mjs

@@ -303,6 +303,7 @@ ${hasDependencyExpressions || hasDependencyEvaluators ? printDerivedDependencyRe
 }
 
 function printOwnedNavigableEffectEntry(effects, output, handlerModules, assetsDirectory, runtimeDirectory, base) {
+  const hasLists = effects.some(effect => effect.list || effect.itemDependencies?.length)
   const hasItemDependencies = effects.some(effect => effect.itemDependencies?.length)
   const hasDependencyExpressions = effects.some(effect => effect.dependencyExpressions?.length)
   const hasDependencyEvaluators = effects.some(effect => effect.dependencyEvaluators?.length)
@@ -331,18 +332,18 @@ function mount(lifetime) {
   const selectedEffects = effects.map((effect, index) => ({ effect, index })).filter(entry => entry.effect.lifetime === lifetime)
   const records = new Set()
   const owners = new Map()
-  const listTemplates = new Map()
+  ${hasLists ? `const listTemplates = new Map()
   const registrations = new WeakMap()
-  const dependencies = new Map()
+  ` : ""}const dependencies = new Map()
   const pending = new Set()
   const startedCleanups = new Set()
   let scheduled = false
   for (const template of selectedEffects) {
-    if (template.effect.list) listTemplates.set(template.effect.owner, template)
-    else {
+    ${hasLists ? `if (template.effect.list) listTemplates.set(template.effect.owner, template)
+    else {` : ""}
       const record = createRecord(template, !template.effect.owner)
       if (template.effect.owner) owners.set(template.effect.owner, record)
-    }
+    ${hasLists ? "}" : ""}
   }
   const unsubscribeCommitter = selectedEffects.some(({ effect }) => effect.dependencies?.length) ? __kRuntime.registerCommitter(id => {
     if (!active) return
@@ -371,18 +372,18 @@ function mount(lifetime) {
       dependencies.set(id, subscribers)
     }
   }
-  function unregisterDependencies(record) {
+  ${hasLists ? `function unregisterDependencies(record) {
     for (const id of record.effect.dependencies ?? []) {
       const subscribers = dependencies.get(id)
       subscribers?.delete(record)
       if (!subscribers?.size) dependencies.delete(id)
     }
   }
-  function mountOwned(root) {
+  ` : ""}function mountOwned(root) {
     if (!active) return
     for (const marker of matching(root)) {
       if (!marker.isConnected) continue
-      if (marker.dataset.kEffects) {
+      ${hasLists ? `if (marker.dataset.kEffects) {
         if (registrations.has(marker)) continue
         const rowRecords = JSON.parse(marker.dataset.kEffects).flatMap(owner => {
           const template = listTemplates.get(owner)
@@ -395,25 +396,25 @@ function mount(lifetime) {
         if (rowRecords.length) registrations.set(marker, rowRecords)
         continue
       }
-      const record = owners.get(marker.dataset.kEffect)
+      ` : ""}const record = owners.get(marker.dataset.kEffect)
       if (record && !record.mounted) mountRecord(record, marker)
     }
   }
   function unmountOwned(root) {
     if (!active) return
     for (const marker of matching(root)) {
-      const rowRecords = registrations.get(marker)
+      ${hasLists ? `const rowRecords = registrations.get(marker)
       if (rowRecords) {
         for (const record of rowRecords) unmountRecord(record, true)
         registrations.delete(marker)
         continue
       }
-      const record = owners.get(marker.dataset.kEffect)
+      ` : ""}const record = owners.get(marker.dataset.kEffect)
       if (record?.marker === marker) unmountRecord(record)
     }
   }
   function matching(root) {
-    const selector = "template[data-k-effect],[data-k-effects]"
+    const selector = ${JSON.stringify(hasLists ? "template[data-k-effect],[data-k-effects]" : "template[data-k-effect]")}
     return [...(root.matches?.(selector) ? [root] : []), ...(root.querySelectorAll?.(selector) ?? [])]
   }
   function mountRecord(record, marker) {
@@ -426,16 +427,16 @@ function mount(lifetime) {
     if (record.disposal) record.disposal.then(begin)
     else begin()
   }
-  function unmountRecord(record, dynamic = false) {
+  function unmountRecord(record${hasLists ? ", dynamic = false" : ""}) {
     if (!record.mounted) return
     record.mounted = false
     record.marker = undefined
     record.version++
     pending.delete(record)
-    if (dynamic) {
+    ${hasLists ? `if (dynamic) {
       unregisterDependencies(record)
       records.delete(record)
-    }
+    }` : ""}
     void cleanup(record)
   }
   function start(record) {
@@ -505,9 +506,9 @@ ${hasDependencyExpressions || hasDependencyEvaluators ? printDerivedDependencyRe
     record.token = token
     try {
       const effect = record.effect
-      const scope = effect.list
+      const scope = ${hasLists ? `effect.list
         ? Object.fromEntries(Object.entries(effect.scope).map(([name, value]) => [name, value?.type === "list-item" ? JSON.parse(record.marker.dataset.kEffectItem) : value]))
-        : effect.scope
+        : effect.scope` : "effect.scope"}
       const result = modules.get(effect.module)[effect.handler](createEffectContext(__kRuntime.browserState, effect.states, __kRuntime.commitDom, scope, () => active && token.active && record.token === token))
       if (effect.cleanup && typeof result === "function") record.cleanup = result
       else if (result && typeof result.then === "function") result.catch(error => console.error(error))
@@ -572,6 +573,7 @@ function printDerivedDependencyRead(state, hasExpressions, hasEvaluators) {
 }
 
 function printOwnedEffectEntry(imports, effects, entries) {
+  const hasLists = effects.some(effect => effect.list || effect.itemDependencies?.length)
   const hasItemDependencies = effects.some(effect => effect.itemDependencies?.length)
   const hasOrdinaryDependencies = effects.some(effect => effect.dependencies?.length)
   const hasDependencyExpressions = effects.some(effect => effect.dependencyExpressions?.length)
@@ -582,12 +584,12 @@ function printOwnedEffectEntry(imports, effects, entries) {
   return `${imports.join("\n")}
 const effects = ${inlineJson(effects)}
 const modules = new Map([${entries}])
-${hasItemDependencies ? "let order = 0\n" : ""}const records = effects.map((effect, index) => effect.list ? undefined : createRecord(effect, index)).filter(Boolean)
-const listTemplates = new Map(effects.map((effect, index) => effect.list ? [effect.owner, { effect, index }] : undefined).filter(Boolean))
-const owners = new Map(records.filter(record => record.effect.owner).map(record => [record.effect.owner, record]))
-const listRegistrations = new WeakMap()
+${hasItemDependencies ? "let order = 0\n" : ""}const records = ${hasLists ? "effects.map((effect, index) => effect.list ? undefined : createRecord(effect, index)).filter(Boolean)" : "effects.map((effect, index) => createRecord(effect, index))"}
+${hasLists ? `const listTemplates = new Map(effects.map((effect, index) => effect.list ? [effect.owner, { effect, index }] : undefined).filter(Boolean))
+` : ""}const owners = new Map(records.filter(record => record.effect.owner).map(record => [record.effect.owner, record]))
+${hasLists ? `const listRegistrations = new WeakMap()
 const listOwnerSets = new Map()
-const mountedRecords = new Set(records.filter(record => record.mounted))
+` : ""}const mountedRecords = new Set(records.filter(record => record.mounted))
 const dependencies = new Map()
 const pending = new Set()
 let scheduled = false
@@ -611,14 +613,14 @@ function registerDependencies(record) {
   dependencies.set(id, subscribers)
   }
 }
-function unregisterDependencies(record) {
+${hasLists ? `function unregisterDependencies(record) {
   for (const id of record.effect.dependencies ?? []) {
     const subscribers = dependencies.get(id)
     subscribers?.delete(record)
     if (!subscribers?.size) dependencies.delete(id)
   }
 }
-${hasItemDependencies ? `if (${hasOrdinaryDependencies}) ` : ""}__kRuntime.registerCommitter(id => {
+` : ""}${hasItemDependencies ? `if (${hasOrdinaryDependencies}) ` : ""}__kRuntime.registerCommitter(id => {
   if (!active) return
   for (const record of dependencies.get(id) ?? []) if (record.mounted) pending.add(record)
   schedule()
@@ -631,7 +633,7 @@ ${hasItemDependencies ? `for (const listState of new Set(effects.filter(effect =
 ` : ""}__kRuntime.registerMountHook(root => {
   if (!active) return
   for (const marker of matching(root)) {
-    if (marker.dataset.kEffects) {
+    ${hasLists ? `if (marker.dataset.kEffects) {
       if (listRegistrations.has(marker)) continue
        const encoded = marker.dataset.kEffects
        let effectOwners = listOwnerSets.get(encoded)
@@ -650,7 +652,7 @@ ${hasItemDependencies ? `for (const listState of new Set(effects.filter(effect =
       listRegistrations.set(marker, rowRecords)
       continue
     }
-    const record = owners.get(marker.dataset.kEffect)
+    ` : ""}const record = owners.get(marker.dataset.kEffect)
     if (!record?.mounted) mount(record, marker)
   }
 }, "effects")
@@ -659,17 +661,17 @@ __kRuntime.registerUnmountHook(root => {
     if (!active) return
     active = false
     pending.clear()
-    for (const record of [...mountedRecords]) unmount(record, record.effect.list)
+    for (const record of [...mountedRecords]) unmount(record${hasLists ? ", record.effect.list" : ""})
     return
   }
   for (const marker of matching(root)) {
-    const rowRecords = listRegistrations.get(marker)
+    ${hasLists ? `const rowRecords = listRegistrations.get(marker)
     if (rowRecords) {
       for (const record of rowRecords) unmount(record, true)
       listRegistrations.delete(marker)
       continue
     }
-    const record = owners.get(marker.dataset.kEffect)
+    ` : ""}const record = owners.get(marker.dataset.kEffect)
     if (record?.marker === marker) unmount(record)
   }
 }, "effects")
@@ -679,10 +681,10 @@ addEventListener("pagehide", event => {
   if (!event.persisted) __kRuntime.unmountDom(document)
 })
 function matching(root) {
-  const selector = "template[data-k-effect],[data-k-effects]"
+  const selector = ${JSON.stringify(hasLists ? "template[data-k-effect],[data-k-effects]" : "template[data-k-effect]")}
   return [...(root.matches?.(selector) ? [root] : []), ...(root.querySelectorAll?.(selector) ?? [])]
 }
-function mount(record, marker, fresh = false) {
+function mount(record, marker${hasLists ? ", fresh = false" : ""}) {
   record.mounted = true
   record.marker = marker
   mountedRecords.add(record)
@@ -691,14 +693,14 @@ function mount(record, marker, fresh = false) {
     if (!active || !record.mounted || record.version !== version || !marker.isConnected) return
     start(record)
   })
-  else if (fresh || active && marker.isConnected) start(record)
+  else if (${hasLists ? "fresh || " : ""}active && marker.isConnected) start(record)
 }
-function unmount(record, dynamic = false) {
+function unmount(record${hasLists ? ", dynamic = false" : ""}) {
   if (!record.mounted) return
   record.mounted = false
   record.marker = undefined
   mountedRecords.delete(record)
-  if (dynamic) unregisterDependencies(record)
+  ${hasLists ? "if (dynamic) unregisterDependencies(record)" : ""}
   record.version++
   pending.delete(record)
   invokeCleanup(record)
@@ -769,17 +771,17 @@ function invoke(record) {
   record.token = token
   try {
     const effect = record.effect
-    const scope = effect.list
+    const scope = ${hasLists ? `effect.list
       ? Object.fromEntries(Object.entries(effect.scope).map(([name, value]) => [name, value?.type === "list-item" ? __kRuntime.listItems.get(record.marker) : value]))
-      : effect.scope
-    const marker = record.marker
+      : effect.scope` : "effect.scope"}
+    ${hasLists ? `const marker = record.marker
     ${hasRowRef ? "const rowPath = effect.list ? __kRuntime.listRowPaths.get(marker) : undefined" : ""}
     const resolveRef = id => {
       if (!marker?.isConnected) return null
       const resolved = ${hasRowRef ? 'id.replace("$k", rowPath)' : "id"}
       return marker.dataset.kRef === resolved ? marker : [...marker.querySelectorAll("[data-k-ref]")].find(node => node.dataset.kRef === resolved) ?? null
     }
-    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, scope, () => active && token.active && record.token === token, effect.list ? resolveRef : undefined))
+    ` : ""}const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, scope, () => active && token.active && record.token === token${hasLists ? ", effect.list ? resolveRef : undefined" : ""}))
     if (effect.cleanup && typeof result === "function") record.cleanup = result
     else if (result && typeof result.then === "function") result.catch(error => console.error(error))
   } catch (error) {

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

@@ -105,6 +105,7 @@ export function planRouteCapabilities(records, { navigationRouteCount = 0 } = {}
   lists.generalRowHooks ||= lists.rowRefs || lists.complexRowState
   lists.asyncParts = lists.expressions || lists.expressionAttributes || lists.conditions
   lists.mounts ||= lists.conditions || lists.nested
+  if (effects.any && plans.every(plan => plan.effects.every(effect => !Object.keys(effect.states).length && !hasCaptureType(effect.scope, "setter")))) effects.stateWrites = false
 
   const capabilityIR = {
     version: 1,
@@ -143,6 +144,7 @@ export function assertCapabilityIR(capabilityIR, records, options = {}) {
   if (capabilityIR.lists.rowRefs && !capabilityIR.lists.rowHooks || capabilityIR.lists.generalRowHooks && !capabilityIR.lists.rowHooks) throw new Error("CapabilityIR row ownership requires row hooks")
   if (capabilityIR.effects.navigableOwners && (!capabilityIR.effects.navigable || !capabilityIR.effects.any)) throw new Error("CapabilityIR navigable effect owners require navigable effects")
   if ((capabilityIR.bindings.count || capabilityIR.lists.count || capabilityIR.events.native.length || options.navigationRouteCount) && !capabilityIR.runtime.shared) throw new Error("CapabilityIR shared runtime flag is inconsistent")
+  if (capabilityIR.effects.stateWrites !== undefined && (capabilityIR.effects.stateWrites !== false || !capabilityIR.effects.any)) throw new Error("Invalid CapabilityIR effect state-write exclusion")
   assertJsonSafe(capabilityIR, "CapabilityIR")
   if (records) {
     const expected = planRouteCapabilities(records, options, false)

package/framework/compiler/runtime-codegen.mjs

@@ -16,10 +16,15 @@ export function generateCoreRuntime(source, capabilityIR) {
 export function generateEffectRuntime(source, capabilityIR) {
   assertCapabilityIR(capabilityIR)
   const { captures, effects } = capabilityIR
+  let runtime = effects.captures ? replaceRequired(source, '"./serialization.js"', '"./kudzu-serialization.js"', "serialization import", "effect-runtime.js") : replaceRequired(source, /^import[^\n]+\n/, "", "serialization import", "effect-runtime.js")
+  if (effects.stateWrites === false) runtime = replaceSequenceRequired(runtime, [
+    [/  \/\* effect-state-writes \*\/[\s\S]*?  \/\* effect-state-writes-end \*\/\n/, "", "unused effect state writes"],
+    ["    set(name, value) {\n      setId(stateIds[name], value)\n    }\n", "", "unused effect setter"]
+  ], "effect-runtime.js")
   return {
-    source: effects.captures ? replaceRequired(source, '"./serialization.js"', '"./kudzu-serialization.js"', "serialization import", "effect-runtime.js") : replaceRequired(source, /^import[^\n]+\n/, "", "serialization import", "effect-runtime.js"),
+    source: runtime,
     define: {
-      "globalThis.__KUDZU_CAPTURE_SETTER__": String(captures.setter),
+      "globalThis.__KUDZU_CAPTURE_SETTER__": String(effects.stateWrites !== false && captures.setter),
       "globalThis.__KUDZU_EFFECT_CAPTURES__": String(effects.captures)
     }
   }

package/framework/compiler/source-compiler.mjs

@@ -1043,7 +1043,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       const reject = (target, message) => { throw sourceNodeError(target, calculationSource, message) }
       if (calculation.asteriskToken || calculation.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) reject(calculation, "Imported calculations used by useEffect() must be synchronous; move async work into the owned effect")
       if (calculation.parameters.some(parameter => !ts.isIdentifier(parameter.name) || parameter.dotDotDotToken || parameter.initializer || parameter.questionToken)) reject(calculation, "Imported calculations used by useEffect() require ordinary identifier parameters without defaults or rest")
-      if (call.arguments.some(argument => !ts.isIdentifier(unwrapExpression(argument)))) fail(call, "useEffect() selected calculation arguments must be direct primitive state identifiers; aliases, property paths, and composed arguments are not supported")
+      if (call.arguments.some(argument => !ts.isIdentifier(unwrapExpression(argument)) && !isStaticPrimitiveArgument(argument))) fail(call, "useEffect() selected calculation arguments must be direct primitive state identifiers or static primitive literals; property paths and composed arguments are not supported")
       const shapes = returns.map(returned => returned.properties.map(property => {
         if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property) || ts.isComputedPropertyName(property.name) || ["__proto__", "constructor", "prototype"].includes(property.name.text)) reject(property, "Imported calculations used by useEffect() must return direct safe plain-object fields without spreads, methods, or computed names")
         return property.name.text
@@ -2085,7 +2085,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           const call = unwrapExpression(expanded.expression)
           if (!ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || !importBindings.has(call.expression.text)) return undefined
           const states = referencedStateNames(call, setters, call, bindingIndex)
-          if (states.size < 2 || call.arguments.some(argument => !ts.isIdentifier(unwrapExpression(argument)) || !states.has(unwrapExpression(argument).text))) effectFail(call, "useEffect() selected calculations require at least two direct primitive state arguments")
+          if (states.size < 2) effectFail(call, "useEffect() selected calculations require at least two direct primitive state arguments")
+          if (call.arguments.some(argument => !isStaticPrimitiveArgument(argument) && (!ts.isIdentifier(unwrapExpression(argument)) || !states.has(unwrapExpression(argument).text)))) effectFail(call, "useEffect() selected calculation arguments must be direct state identifiers or static primitive literals after const normalization")
           return { name: value.expression.text, field: value.name.text, call, states, source: dependency }
         }
         const dependencyAnalysis = analyzeEffectDependencies({
@@ -3243,6 +3244,13 @@ function isPrimitiveDefaultLiteral(node) {
     node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword || node.kind === ts.SyntaxKind.NullKeyword
 }
 
+function isStaticPrimitiveArgument(node) {
+  const value = unwrapExpression(node)
+  if (!isPrimitiveDefaultLiteral(value) && !ts.isNoSubstitutionTemplateLiteral(value)) return false
+  const number = ts.isNumericLiteral(value) ? Number(value.text) : ts.isPrefixUnaryExpression(value) ? (value.operator === ts.SyntaxKind.MinusToken ? -1 : 1) * Number(value.operand.text) : null
+  return number === null || Number.isFinite(number) && !Object.is(number, -0)
+}
+
 function isEventOnlyComponentLocal(root, name) {
   let found = false
   let eventOnly = true

package/framework/effect-runtime.js

@@ -1,6 +1,7 @@
 import { deserialize } from "./serialization.js"
 
 export function createEffectContext(state, stateIds, commit, serializedScope = {}, active = () => true, resolveRef) {
+  /* effect-state-writes */
   const changed = new Set()
   let scheduled = false
 
@@ -22,6 +23,7 @@ export function createEffectContext(state, stateIds, commit, serializedScope = {
       queueMicrotask(flush)
     }
   }
+  /* effect-state-writes-end */
 
   const scope = globalThis.__KUDZU_EFFECT_CAPTURES__
     ? Object.fromEntries(Object.entries(serializedScope).map(([name, value]) => [name, deserialize(value, id => state.get(id), globalThis.__KUDZU_CAPTURE_SETTER__ ? setId : undefined, undefined, resolveRef)]))

package/package.json

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