npm - @kudzujs/core - Versions diffs - 0.5.8 → 0.5.10 - Mend

@kudzujs/core 0.5.8 → 0.5.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +26 -4
package/framework/README.md +3 -2
package/framework/build.mjs +300 -25
package/framework/core.d.ts +4 -2
package/framework/core.mjs +20 -6
package/framework/dependency-runtime.js +36 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -126,17 +126,20 @@ Static trusted HTML can be rendered without a transform layer:
 The HTML is intentionally not sanitized. Use only trusted or previously sanitized build-time content. Reactive raw HTML, children on the same element, void elements, and keyed-list raw HTML are rejected.
-Every CSS file under `src` is copied to the same relative path under `dist/assets` and linked in deterministic order. Project-page deployments and post-build artifacts use `kudzu.config.mjs`:
+Every CSS file under `src` is copied to the same relative path under `dist/assets` and linked in deterministic order. Stylesheets produced by another build step can be declared globally so Kudzu still emits them in every document `<head>`. Configured root-relative URLs receive `base`; absolute HTTP URLs are preserved. Project-page deployments and post-build artifacts use `kudzu.config.mjs`:
 ```js
 export default {
   base: "/newsletter",
+  styles: ["/assets/generated.css"],
   async afterBuild({ outDir, routes, plans, rewrites, base }) {
-    // Write host rewrites, RSS, sitemap, or other static artifacts.
+    // Write generated.css, host rewrites, RSS, sitemap, or other static artifacts.
   }
 }
 ```
+Do not render `<link rel="stylesheet">` from page or component JSX. Kudzu rejects direct static body stylesheets with a source location and catches computed JSX stylesheet output during rendering. Trusted `dangerouslySetInnerHTML` remains unparsed and is responsible for its own resource tags.
 ## State Semantics
 Kudzu intentionally differs from React's state snapshot behavior:
@@ -329,7 +332,7 @@ The original component remains reusable across multiple lists and ordinary JSX.
 Each item must be an ordinary plain object with a unique string or finite-number key; nested data may contain only JSON-safe arrays, ordinary plain objects, and primitive values. Null-prototype objects are rejected to preserve JSON round-trip parity. The current syntax requires a local-state `.map`, one identifier callback parameter, one intrinsic JSX root or top-level local or relative-imported row component, and `key={item.<field>}`. Row components accept destructured projected props and top-level single-`const` calculations before one intrinsic return. A list alias may only be rendered once and cannot be read by other JavaScript. Derived expressions must be pure and synchronous: item reads, literals, operators, templates, approved read-only string/array methods, deterministic `Math` methods, and `String`/`Number`/`Boolean` conversion are supported. Component state, imported helpers used inside calculations, browser globals, Promise values, mutation, arbitrary calls, and prototype-sensitive properties are rejected. Package or namespace row imports, same-file exported rows, reusable aliases, prop spreads/defaults/rest, children, nested item conditions, lists, or component tags, refs, and `dangerouslySetInnerHTML` remain unsupported. Keyed rows must be placed inside an explicit `<tbody>`, `<thead>`, or `<tfoot>`.
-## Mount Effects
+## Effects
 Browser-only initial work uses the familiar empty-dependency effect shape:
@@ -357,12 +360,30 @@ useEffect(() => {
 }, [])
 ```
-Cleanup runs once when the document leaves outside the browser back-forward cache. Effect-local resources and component state read by nested cleanup closures retain their mount-time values. Cleanup failures are isolated so later cleanups still run. Only inline block-bodied callbacks with a literal empty dependency array are supported. Dependencies, named or dynamically obtained cleanup functions, cleanup parameters or generators, other return values, callback parameters, and non-serializable captures are rejected at build time. Async effects cannot return cleanup functions; the cleanup itself may be async. Pages without effects receive no effect entry, and effects without cleanup retain their smaller runtime output.
+Cleanup runs once when the document leaves outside the browser back-forward cache. Effect-local resources and component state read by nested cleanup closures retain their setup-time values. Cleanup failures are isolated so later cleanups still run.
+Literal arrays of direct primitive `useState` or `useParams` signal identifiers rerun after committed dependency changes:
+```tsx
+const [event, setEvent] = useState("resize")
+useEffect(() => {
+  const listener = () => console.log(event)
+  window.addEventListener(event, listener)
+  return () => window.removeEventListener(event, listener)
+}, [event])
+```
+Dependency values are limited to JSON-safe strings, finite numbers, booleans, and `null`; direct signal aliases are accepted, while expressions, property reads, ordinary props or locals, objects, spreads, and dynamic arrays fail the build. Kudzu compares dependencies with `Object.is`, coalesces multiple commits in one turn, invokes every affected previous cleanup in declaration order, awaits asynchronous cleanup, and then runs the affected setups in declaration order. The component itself is not rerun.
+Effect callbacks must be inline and block-bodied. Named or dynamically obtained cleanup functions, cleanup parameters or generators, other return values, callback parameters, and non-serializable captures are rejected. Async effects cannot return cleanup functions; the cleanup itself may be async. Pages without effects receive no effect entry. Empty-dependency effects retain their smaller output, and dependency-only capability code is isolated to the routes that use `kudzu-deps.js` unless another capability already requires the shared runtime.
 A matched mount-fetch benchmark renders a title and two keyed rows from local JSON. With one warm-up and seven rotating clean builds, Kudzu shipped initial HTML, 3.4 KB initial JS gzip, 8.1 KB total output, and built in 374 ms. React CSR shipped no initial content, 59.3 KB initial JS gzip, 189.2 KB total output, and built in 992 ms. Hand-written ESM shipped 534 B initial JS gzip, 1.2 KB total output, and built in 210 ms. Fresh-profile Chrome medians to loaded data were 157.9 ms, 166.5 ms, and 153.4 ms respectively.
 A matched resize-listener cleanup fixture, measured with the same warm-up and seven rotating clean builds, shipped 1.2 KB JavaScript gzip and built in 402 ms with Kudzu. Svelte shipped 10.1 KB and built in 861 ms, Vue shipped 23.6 KB and built in 768 ms, and React shipped 59.1 KB and built in 1,058 ms. Kudzu and the 127 B hand-written Astro baseline emitted initial HTML; the CSR fixtures did not.
+In the matched dependency-rerun fixture, Kudzu shipped 1.5 KB JavaScript gzip and built in 429 ms. Svelte shipped 9.7 KB in 995 ms, Vue 23.8 KB in 943 ms, React 59.2 KB in 1,172 ms, and the hand-written Astro baseline 196 B in 969 ms. Kudzu and Astro emitted initial HTML; the CSR fixtures did not.
 ## Normal JavaScript
 Command-only setters use the smallest optimized path. Conditions, local variables, browser globals, events, and `async`/`await` compile to external ESM without `eval`, `new Function`, or inline executable code.
@@ -409,6 +430,7 @@ TSX
 - Static pages ship no client JavaScript.
 - Interactive pages receive only the runtime capabilities they use.
+- Interactive route modules are discovered in the document head and retain deferred execution after HTML parsing, overlapping cold downloads with document transfer.
 - Production JavaScript is minified; development output stays readable.
 - Components are authoring units; no component tree is retained in the browser.
 - There is no VDOM, hydration pass, router, or client application runtime.

package/framework/README.md CHANGED Viewed

@@ -4,6 +4,7 @@
 - `core.mjs`: server-side JSX rendering, state slots, context providers, behavior metadata, and serializable capture validation.
 - `jsx-runtime.mjs`: automatic JSX runtime used by TypeScript.
 - `runtime.js`: command-only runtime for direct state-to-text patches.
+- `dependency-runtime.js`: command runtime with commit observation for dependency effects.
 - `shared-runtime.js`: command runtime with capability commit and DOM lifecycle hooks, emitted only when needed.
 - `binding-runtime.js`: optional generic attributes, form properties, comment-bounded text patches, and conditional range patches.
 - `list-runtime.js`: optional keyed list validation, external item-expression evaluation, item-local conditional ranges, dynamic styles and item-handler scopes, moves, and cleanup.
@@ -13,6 +14,6 @@
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
-Static routes receive no browser runtime. Command routes receive `runtime.js`; runtime bracket pages using `useParams()` add one route-specific pathname matcher; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`; mount effects add `effect-runtime.js` and one route-specific entry. Effect cleanup integrates with shared unmount hooks when present and otherwise disposes directly on non-persisted `pagehide`; unrelated routes and effects retain their existing runtime. List builds remove unused text-range, attribute, event, expression, condition, seed, and mount branches. Effect builds omit capture deserialization entirely when every effect scope is empty. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators and their bundled relative TypeScript helpers live under `dist/assets/handlers/`; shared helper chunks are emitted only when multiple handler entries need them. Runtime fallback rewrites are ordered by specificity in `.kudzu/kudzu-plan.json` and passed to `afterBuild()`; exact static files take precedence in development. The dev server derives stable state identities from route-unique state variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
+Static routes receive no browser runtime. Command routes receive `runtime.js`; dependency effects use route-specific `kudzu-deps.js` unless that route already requires shared commit hooks; runtime bracket pages using `useParams()` add one route-specific pathname matcher; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`; effects add `effect-runtime.js` and one route-specific entry. Generated module scripts live in the document head, so cold downloads overlap HTML transfer while standard module deferral preserves execution after parsing. A single effect with one dependency compiles to a direct runner; generic maps, sets, and ordering are reserved for larger effect graphs. Dependency commits coalesce in a microtask; affected cleanups are awaited in declaration order before replacement setups run. Document cleanup integrates with shared unmount hooks when present and otherwise disposes directly on non-persisted `pagehide`. List builds remove unused text-range, attribute, event, expression, condition, seed, and mount branches. Effect builds omit capture deserialization entirely when every effect scope is empty. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators and their bundled relative TypeScript helpers live under `dist/assets/handlers/`; shared helper chunks are emitted only when multiple handler entries need them. Runtime fallback rewrites are ordered by specificity in `.kudzu/kudzu-plan.json` and passed to `afterBuild()`; exact static files take precedence in development. The dev server derives stable state identities from route-unique state variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
-Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.
+Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime. Source CSS and global `kudzu.config` styles are emitted in document heads before `afterBuild()` runs; static stylesheet links in component JSX fail compilation instead of loading from the body.

package/framework/build.mjs CHANGED Viewed

@@ -19,6 +19,7 @@ const devClient = (session, revision, schema) => `<script>(()=>{const show=event
 export async function build({ quiet = false, minify = true } = {}) {
   const config = await loadConfig()
   const base = normalizeBase(config.base)
+  const configuredStyles = normalizeStyles(config.styles, base)
   await rm(workDirectory, { recursive: true, force: true })
   await rm(outputDirectory, { recursive: true, force: true })
   await mkdir(workDirectory, { recursive: true })
@@ -41,16 +42,23 @@ export async function build({ quiet = false, minify = true } = {}) {
   if (!pageFiles.length) throw new Error("No pages found in src/pages/")
   let behaviorCount = 0
+  let regularBehaviorCount = 0
   let bindingCount = 0
   let listCount = 0
   let listStyleCount = 0
-  let stateSeedCount = 0
+  let regularStateSeedCount = 0
+  let dependencyStateSeedCount = 0
   const plans = []
+  const pageEntries = []
   const effectEntries = []
   const paramEntries = []
   const rewrites = []
   const emittedRoutes = new Set()
-  const styleUrls = cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`))
+  const styleUrls = [...new Set([
+    ...cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)),
+    ...configuredStyles
+  ])]
+  const runtimePlaceholder = `/__kudzu_runtime_${randomUUID()}.js`
   for (const pageFile of pageFiles) {
     const compiledFile = compiledPath(pageFile)
@@ -81,21 +89,28 @@ export async function build({ quiet = false, minify = true } = {}) {
         ...(module.metadata ?? {}),
         styles: styleUrls.length ? styleUrls : false,
         base,
+        runtimeAsset: runtimePlaceholder,
         effectAsset: assetPath(base, `assets/${effectPath}`),
         paramAsset: assetPath(base, `assets/${paramPath}`),
         runtimeParams: runtimeSchema?.params
       }, props)
-      const routeDirectory = join(outputDirectory, route)
-      await mkdir(routeDirectory, { recursive: true })
-      await writeFile(join(routeDirectory, "index.html"), result.html)
+      const hasDependencies = result.plan.effects.some(effect => effect.dependencies?.length)
+      const usesDependencyRuntime = hasDependencies && !result.hasBindings && !result.hasLists && !result.plan.events.some(event => event.native)
+      pageEntries.push({ route, html: result.html, usesDependencyRuntime })
       plans.push({ route: routePath, ...result.plan })
-      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params })
-      if (result.hasEffects) effectEntries.push({ path: effectPath, effects: result.plan.effects, paramPath: result.hasParams ? paramPath : undefined })
-      if (result.hasBehaviors) behaviorCount++
+      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params, usesDependencyRuntime })
+      if (result.hasEffects) effectEntries.push({ path: effectPath, effects: result.plan.effects, paramPath: result.hasParams ? paramPath : undefined, usesDependencyRuntime })
+      if (result.hasBehaviors) {
+        behaviorCount++
+        if (!usesDependencyRuntime) regularBehaviorCount++
+      }
       if (result.hasBindings) bindingCount++
       if (result.hasLists) listCount++
       if (result.hasListStyles) listStyleCount++
-      if (result.hasStateSeed) stateSeedCount++
+      if (result.hasStateSeed) {
+        if (usesDependencyRuntime) dependencyStateSeedCount++
+        else regularStateSeedCount++
+      }
     }
   }
@@ -119,11 +134,24 @@ export async function build({ quiet = false, minify = true } = {}) {
   const nativeModules = handlerModules.filter(module => module.hasNativeHandlers).map(module => assetPath(base, `assets/${module.path}`))
   const hasNativeHandlers = nativeModules.length > 0
   const hasEffects = effectEntries.length > 0
-  if (behaviorCount) {
-    const runtimeFile = bindingCount || listCount || hasNativeHandlers ? "./shared-runtime.js" : "./runtime.js"
-    const runtime = specializeRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), commandEvents, stateSeedCount > 0)
+  const hasSharedRuntime = bindingCount || listCount || hasNativeHandlers
+  const hasDependencyRuntime = pageEntries.some(entry => entry.usesDependencyRuntime)
+  const runtimeName = usesDependencyRuntime => usesDependencyRuntime ? "kudzu-deps.js" : "kudzu.js"
+  for (const entry of pageEntries) {
+    const routeDirectory = join(outputDirectory, entry.route)
+    await mkdir(routeDirectory, { recursive: true })
+    const html = entry.html.replace(runtimePlaceholder, escapeAttribute(assetPath(base, `assets/${runtimeName(entry.usesDependencyRuntime)}`)))
+    await writeFile(join(routeDirectory, "index.html"), html)
+  }
+  if (behaviorCount && (hasSharedRuntime || regularBehaviorCount)) {
+    const runtimeFile = hasSharedRuntime ? "./shared-runtime.js" : "./runtime.js"
+    const runtime = specializeRuntime(await readFile(new URL(runtimeFile, import.meta.url), "utf8"), commandEvents, regularStateSeedCount > 0)
     await writeJavaScript(join(assetsDirectory, "kudzu.js"), runtime, minify)
   }
+  if (hasDependencyRuntime) {
+    const runtime = specializeRuntime(await readFile(new URL("./dependency-runtime.js", import.meta.url), "utf8"), commandEvents, dependencyStateSeedCount > 0)
+    await writeJavaScript(join(assetsDirectory, "kudzu-deps.js"), runtime, minify)
+  }
   if (bindingCount || hasNativeHandlers || hasEffectCaptures) await writeJavaScript(join(assetsDirectory, "kudzu-serialization.js"), await readFile(new URL("./serialization.js", import.meta.url), "utf8"), minify, {
     "globalThis.__KUDZU_CAPTURE_STATE__": String(hasNestedStateCaptures),
     "globalThis.__KUDZU_CAPTURE_SETTER__": String(hasSetterCaptures)
@@ -186,12 +214,12 @@ export async function build({ quiet = false, minify = true } = {}) {
   for (const entry of paramEntries) {
     const output = join(assetsDirectory, entry.path)
     await mkdir(dirname(output), { recursive: true })
-    await writeJavaScript(output, printParamEntry(entry.schema, entry.params, output, assetsDirectory, base), minify)
+    await writeJavaScript(output, printParamEntry(entry.schema, entry.params, output, assetsDirectory, base, runtimeName(entry.usesDependencyRuntime)), minify)
   }
   for (const entry of effectEntries) {
     const output = join(assetsDirectory, entry.path)
     await mkdir(dirname(output), { recursive: true })
-    await writeJavaScript(output, printEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base, entry.paramPath), minify)
+    await writeJavaScript(output, printEffectEntry(entry.effects, output, handlerModules, assetsDirectory, base, entry.paramPath, runtimeName(entry.usesDependencyRuntime)), minify)
   }
   const clientModules = await collectClientModules(handlerModules.flatMap(module => module.clientImports), sourceFileSet)
   for (const file of clientModules) {
@@ -243,8 +271,9 @@ function specializeNativeRuntime(source, events, modules) {
   return `${imports}\n${specializeEvents(source, events).replace(/const modules = new Map\(\[[^\n]*\]\)/, `const modules = new Map([${entries}])`)}`
 }
-function printEffectEntry(effects, output, handlerModules, assetsDirectory, base, paramPath) {
+function printEffectEntry(effects, output, handlerModules, assetsDirectory, base, paramPath, runtimeName) {
   const hasCleanup = effects.some(effect => effect.cleanup)
+  const hasDependencies = effects.some(effect => effect.dependencies?.length)
   const moduleUrls = [...new Set(effects.map(effect => effect.module))]
   const modules = moduleUrls.map(url => {
     const module = handlerModules.find(entry => assetPath(base, `assets/${entry.path}`) === url)
@@ -252,14 +281,117 @@ function printEffectEntry(effects, output, handlerModules, assetsDirectory, base
     return module
   })
   const imports = [
-    hasCleanup
-      ? `import * as __kRuntime from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}\nconst { browserState, commitDom } = __kRuntime`
-      : `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}`,
+    hasCleanup || hasDependencies
+      ? `import * as __kRuntime from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}\nconst { browserState, commitDom } = __kRuntime`
+      : `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}`,
     `import { createEffectContext } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu-effect.js")))}`,
     ...(paramPath ? [`import ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, paramPath)))}`] : []),
     ...modules.map((module, index) => `import * as __kEffectModule${index} from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, module.path)))}`)
   ]
   const entries = moduleUrls.map((url, index) => `[${JSON.stringify(url)}, __kEffectModule${index}]`).join(",")
+  if (effects.length === 1 && effects[0].dependencies?.length === 1) return printSingleDependencyEffect(imports, effects[0], hasCleanup)
+  const disposal = hasCleanup ? `
+let disposed = false
+const dispose = root => {
+  if (root !== document || disposed) return
+  disposed = true
+  active = false
+  pending.clear()
+  for (const record of records) invokeCleanup(record)
+}
+if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose)
+addEventListener("pagehide", event => {
+  if (event.persisted) return
+  if (__kRuntime.unmountDom) __kRuntime.unmountDom(document)
+  else dispose(document)
+})` : ""
+  if (hasDependencies) return `${imports.join("\n")}
+const effects = ${inlineJson(effects)}
+const modules = new Map([${entries}])
+const records = effects.map((effect, index) => ({ effect, index, values: undefined, cleanup: undefined }))
+const dependencies = new Map()
+const pending = new Set()
+let scheduled = false
+let flushing = false
+let active = true
+for (const record of records) {
+  for (const id of record.effect.dependencies ?? []) {
+    const subscribers = dependencies.get(id) ?? new Set()
+    subscribers.add(record)
+    dependencies.set(id, subscribers)
+  }
+}
+__kRuntime.registerCommitter(id => {
+  if (!active) return
+  for (const record of dependencies.get(id) ?? []) pending.add(record)
+  schedule()
+})
+for (const record of records) {
+  try {
+    record.values = readDependencies(record)
+    invoke(record)
+  } catch (error) {
+    console.error(error)
+  }
+}
+function schedule() {
+  if (!pending.size || scheduled || flushing) return
+  scheduled = true
+  queueMicrotask(flush)
+}
+async function flush() {
+  scheduled = false
+  if (!active) return pending.clear()
+  flushing = true
+  try {
+    const selected = [...pending].sort((left, right) => left.index - right.index)
+    pending.clear()
+    const changed = []
+    for (const record of selected) {
+      try {
+        const values = readDependencies(record)
+        if (!record.values || values.some((value, index) => !Object.is(value, record.values[index]))) {
+          record.values = values
+          changed.push(record)
+        }
+      } catch (error) {
+        console.error(error)
+      }
+    }
+    for (const record of changed) await invokeCleanup(record)
+    if (active) for (const record of changed) invoke(record)
+  } finally {
+    flushing = false
+    if (active) schedule()
+  }
+}
+function readDependencies(record) {
+  return (record.effect.dependencies ?? []).map(id => {
+    const value = browserState.get(id)
+    if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive")
+    return value
+  })
+}
+function invoke(record) {
+  try {
+    const effect = record.effect
+    const result = modules.get(effect.module)[effect.handler](createEffectContext(browserState, effect.states, commitDom, effect.scope))
+    if (effect.cleanup && typeof result === "function") record.cleanup = result
+    else if (result && typeof result.then === "function") result.catch(error => console.error(error))
+  } catch (error) {
+    console.error(error)
+  }
+}
+async function invokeCleanup(record) {
+  const cleanup = record.cleanup
+  record.cleanup = undefined
+  if (!cleanup) return
+  try {
+    await cleanup()
+  } catch (error) {
+    console.error(error)
+  }
+}${disposal}`
   if (!hasCleanup) return `${imports.join("\n")}
 const effects = ${inlineJson(effects)}
 const modules = new Map([${entries}])
@@ -306,8 +438,96 @@ addEventListener("pagehide", event => {
 })`
 }
-function printParamEntry(schema, params, output, assetsDirectory, base) {
-  return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, "kudzu.js")))}
+function printSingleDependencyEffect(imports, effect, hasCleanup) {
+  const disposal = hasCleanup ? `
+const dispose = root => {
+  if (root !== document || !active) return
+  active = false
+  pending = false
+  invokeCleanup()
+}
+if (__kRuntime.registerUnmountHook) __kRuntime.registerUnmountHook(dispose)
+addEventListener("pagehide", event => {
+  if (event.persisted) return
+  if (__kRuntime.unmountDom) __kRuntime.unmountDom(document)
+  else dispose(document)
+})` : ""
+  return `${imports.join("\n")}
+const effect = ${inlineJson(effect)}
+const dependency = effect.dependencies[0]
+let value
+let cleanup
+let active = true
+let pending = false
+let scheduled = false
+let running = false
+__kRuntime.registerCommitter(id => {
+  if (active && id === dependency) {
+    pending = true
+    schedule()
+  }
+})
+try {
+  value = readDependency()
+  invoke()
+} catch (error) {
+  console.error(error)
+}
+function schedule() {
+  if (!pending || scheduled || running) return
+  scheduled = true
+  queueMicrotask(flush)
+}
+async function flush() {
+  scheduled = false
+  if (!active) return
+  let next
+  try {
+    next = readDependency()
+  } catch (error) {
+    console.error(error)
+    return
+  }
+  pending = false
+  if (Object.is(next, value)) return
+  value = next
+  running = true
+  try {
+    await invokeCleanup()
+    if (active) invoke()
+  } finally {
+    running = false
+    if (active) schedule()
+  }
+}
+function readDependency() {
+  const next = browserState.get(dependency)
+  if (next !== null && typeof next !== "string" && typeof next !== "boolean" && !(typeof next === "number" && Number.isFinite(next) && !Object.is(next, -0))) throw new Error("useEffect() dependency state must remain a JSON-safe primitive")
+  return next
+}
+function invoke() {
+  try {
+    const result = __kEffectModule0[effect.handler](createEffectContext(browserState, effect.states, commitDom, effect.scope))
+    if (effect.cleanup && typeof result === "function") cleanup = result
+    else if (result && typeof result.then === "function") result.catch(error => console.error(error))
+  } catch (error) {
+    console.error(error)
+  }
+}
+async function invokeCleanup() {
+  const current = cleanup
+  cleanup = undefined
+  if (!current) return
+  try {
+    await current()
+  } catch (error) {
+    console.error(error)
+  }
+}${disposal}`
+}
+function printParamEntry(schema, params, output, assetsDirectory, base, runtimeName) {
+  return `import { browserState, commitDom } from ${JSON.stringify(relativeModulePath(output, join(assetsDirectory, runtimeName)))}
 const base = ${inlineJson(browserPath(base).slice(1).split("/").filter(Boolean).map(segment => decodeURIComponent(segment)))}
 const schema = ${inlineJson(schema.segments)}
 const params = ${inlineJson(params)}
@@ -501,7 +721,7 @@ export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
 }
 function injectDevClient(html, session, revision, schema) {
-  return `${html}${devClient(session, revision, schema)}`
+  return `${html}${devClient(session, revision, schema).replace("binding|list|native", "binding|deps|list|native")}`
 }
 function stripBaseStrict(path, base) {
@@ -576,6 +796,10 @@ function escapeHtml(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
 }
+function escapeAttribute(value) {
+  return escapeHtml(value).replaceAll('"', "&quot;").replaceAll("'", "&#39;")
+}
 async function compile(file, sourceFiles, sourceIndex, base) {
   const source = sourceIndex.get(file)
   const nativeHandlers = []
@@ -625,6 +849,7 @@ async function compile(file, sourceFiles, sourceIndex, base) {
 function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports) {
   return context => sourceFile => {
     const factory = context.factory
+    const hasLinkElements = /<link/i.test(sourceFile.text)
     sourceFile = normalizeRenderControlFlow(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
     const importBindings = clientImportBindings(sourceFile, file, sourceFiles)
@@ -827,6 +1052,10 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       if (specializedDeclarations.has(node)) return node
       if (componentSpecializations.has(node)) return ts.visitNode(componentSpecializations.get(node).root, visitor)
+      if (hasLinkElements && (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) && isStylesheetLink(node)) {
+        fail(node, "Stylesheets must be placed under src/ or declared in kudzu.config styles so Kudzu can emit them in <head>")
+      }
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")) {
         const target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
         return factory.updateImportDeclaration(node, node.modifiers, node.importClause, factory.createStringLiteral(relativeModulePath(compiledPath(file), compiledPath(target))), node.attributes)
@@ -838,13 +1067,15 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
       }
       if (hasUseEffectImport && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "useEffect") {
-        if (node.arguments.length !== 2) fail(node, "useEffect() requires exactly a callback and literal empty dependency array")
+        if (node.arguments.length !== 2) fail(node, "useEffect() requires exactly a callback and literal dependency array")
         const [callback, dependencies] = node.arguments
         if (!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) fail(callback, "useEffect() callback must be an inline function")
         if (ts.isFunctionExpression(callback) && callback.name) fail(callback, "useEffect() callback function must be anonymous")
         if (callback.asteriskToken) fail(callback, "useEffect() callback cannot be a generator")
         if (callback.parameters.length) fail(callback, "useEffect() callback cannot declare parameters")
-        if (!ts.isArrayLiteralExpression(dependencies) || dependencies.elements.length) fail(dependencies, "useEffect() dependencies must be a literal empty array")
+        if (!ts.isArrayLiteralExpression(dependencies)) fail(dependencies, "useEffect() dependencies must be a literal array")
+        const invalidDependency = dependencies.elements.find(dependency => !ts.isIdentifier(dependency))
+        if (invalidDependency) fail(invalidDependency, "useEffect() dependencies must be direct state or runtime parameter identifiers")
         if (!nearestFunction(node)) fail(node, "useEffect() cannot be used outside a Kudzu component")
         if (!ts.isBlock(callback.body)) fail(callback, "useEffect() callback must use a block body")
         const returns = effectReturns(callback)
@@ -1268,6 +1499,19 @@ function jsxTagName(node) {
   return ts.isJsxElement(node) ? node.openingElement.tagName : ts.isJsxSelfClosingElement(node) ? node.tagName : undefined
 }
+function isStylesheetLink(node) {
+  const element = ts.isJsxElement(node) ? node.openingElement : node
+  if (!ts.isIdentifier(element.tagName) || element.tagName.text.toLowerCase() !== "link") return false
+  const attribute = element.attributes.properties.find(property => ts.isJsxAttribute(property) && property.name.getText().toLowerCase() === "rel")
+  if (!attribute?.initializer) return false
+  const value = ts.isStringLiteral(attribute.initializer)
+    ? attribute.initializer.text
+    : ts.isJsxExpression(attribute.initializer) && attribute.initializer.expression && (ts.isStringLiteral(attribute.initializer.expression) || ts.isNoSubstitutionTemplateLiteral(attribute.initializer.expression))
+      ? attribute.initializer.expression.text
+      : undefined
+  return value?.toLowerCase().split(/\s+/).includes("stylesheet") ?? false
+}
 function isContextProviderValue(node, contexts) {
   if (node.name.getText() !== "value") return false
   const element = node.parent?.parent
@@ -1912,6 +2156,8 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
   const stateNames = new Set(setters.values())
   const snapshotNames = snapshotNested ? nestedStateNames(expression, setters) : new Set()
   const snapshots = new Map([...snapshotNames].map(name => [name, factory.createUniqueName("__kEffectState")]))
+  const captureSnapshotNames = snapshotNested ? nestedCaptureNames(expression, captures) : new Set()
+  const captureSnapshots = new Map([...captureSnapshotNames].map(name => [name, factory.createUniqueName("__kEffectCapture")]))
   const transformer = context => root => {
     const visitor = node => {
       if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text) && !isShadowedIdentifier(node.expression, expression)) {
@@ -1940,9 +2186,11 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
         )
       }
       if (ts.isShorthandPropertyAssignment(node) && captures.has(node.name.text) && !isShadowedIdentifier(node.name, expression)) {
+        if (captureSnapshots.has(node.name.text) && insideNestedFunction(node, expression)) return factory.createPropertyAssignment(node.name, captureSnapshots.get(node.name.text))
         return factory.createPropertyAssignment(node.name, scopeRead(factory, node.name.text))
       }
       if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, expression)) {
+        if (captureSnapshots.has(node.text) && insideNestedFunction(node, expression)) return captureSnapshots.get(node.text)
         return scopeRead(factory, node.text)
       }
       return ts.visitEachChild(node, visitor, context)
@@ -1954,8 +2202,12 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
     let body = ts.isBlock(expression.body)
       ? transformed.transformed[0]
       : factory.createBlock([factory.createReturnStatement(transformed.transformed[0])], true)
-    if (snapshots.size) body = factory.updateBlock(body, [
-      factory.createVariableStatement(undefined, factory.createVariableDeclarationList([...snapshots].map(([name, identifier]) => factory.createVariableDeclaration(identifier, undefined, undefined, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(name)]))), ts.NodeFlags.Const)),
+    const snapshotDeclarations = [
+      ...[...snapshots].map(([name, identifier]) => factory.createVariableDeclaration(identifier, undefined, undefined, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "get"), undefined, [factory.createStringLiteral(name)]))),
+      ...[...captureSnapshots].map(([name, identifier]) => factory.createVariableDeclaration(identifier, undefined, undefined, factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "scope"), undefined, [factory.createStringLiteral(name)])))
+    ]
+    if (snapshotDeclarations.length) body = factory.updateBlock(body, [
+      factory.createVariableStatement(undefined, factory.createVariableDeclarationList(snapshotDeclarations, ts.NodeFlags.Const)),
       ...body.statements
     ])
     const modifiers = [factory.createModifier(ts.SyntaxKind.ExportKeyword)]
@@ -1975,6 +2227,16 @@ function printNativeHandler({ exportName, expression, captures, setters, snapsho
   }
 }
+function nestedCaptureNames(expression, captures) {
+  const names = new Set()
+  const visit = node => {
+    if (ts.isIdentifier(node) && captures.has(node.text) && isReferenceIdentifier(node) && insideNestedFunction(node, expression) && !isShadowedIdentifier(node, expression)) names.add(node.text)
+    ts.forEachChild(node, visit)
+  }
+  visit(expression.body)
+  return names
+}
 function nestedStateNames(expression, setters) {
   const states = new Set(setters.values())
   const names = new Set()
@@ -2124,6 +2386,19 @@ async function loadConfig() {
   return {}
 }
+function normalizeStyles(value, base) {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) throw new Error("kudzu.config styles must be an array of URLs")
+  return value.map((style, index) => {
+    if (typeof style !== "string" || !style) throw new Error(`kudzu.config styles[${index}] must be a non-empty URL`)
+    if (style.startsWith("//")) throw new Error(`kudzu.config styles[${index}] must be root-relative or an absolute HTTP URL`)
+    if (style.startsWith("/")) return withBase(base, style)
+    if (!/^https?:\/\//i.test(style)) throw new Error(`kudzu.config styles[${index}] must be root-relative or an absolute HTTP URL`)
+    try { new URL(style) } catch { throw new Error(`kudzu.config styles[${index}] must be root-relative or an absolute HTTP URL`) }
+    return style
+  })
+}
 function normalizeBase(value) {
   if (value == null || value === "" || value === "/") return ""
   if (typeof value !== "string" || !value.startsWith("/") || /[?#\0]/.test(value) || /%(?:2f|5c)/i.test(value)) throw new Error("kudzu.config base must be a root-relative path")

package/framework/core.d.ts CHANGED Viewed

@@ -1,8 +1,9 @@
 export type StateSetter<T> = (value: T | ((previous: T) => T)) => void
 export type EffectCleanup = () => void | Promise<void>
+export type EffectDependency = string | number | boolean | null
 export function useState<T>(initialValue: T): [T, StateSetter<T>]
-export function useEffect(effect: () => void | EffectCleanup | Promise<void>, dependencies: readonly []): void
+export function useEffect(effect: () => void | EffectCleanup | Promise<void>, dependencies: readonly EffectDependency[]): void
 export function useParams<Params extends Record<string, string> = Record<string, string>>(): Readonly<Params>
 export interface RefObject<T> {
@@ -49,6 +50,7 @@ export function renderPage<Props = Record<string, never>>(
     manifest?: string
     styles?: boolean | string[]
     base?: string
+    runtimeAsset?: string
     effectAsset?: string
     paramAsset?: string
     runtimeParams?: string[]
@@ -71,7 +73,7 @@ export function renderPage<Props = Record<string, never>>(
       commands?: Array<[string, string, unknown]>
       native?: { module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown> }
     }>
-    effects: Array<{ module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown>; cleanup?: true }>
+    effects: Array<{ module: string; handler: string; states: Record<string, string>; scope: Record<string, unknown>; dependencies?: string[]; cleanup?: true }>
     bindings: Array<{
       target: string
       state?: string

package/framework/core.mjs CHANGED Viewed

@@ -66,14 +66,20 @@ function createSignal(id, value) {
 export function useEffect(callback, dependencies, module, handler, states, scope, source, cleanup) {
   if (!renderContext) throw new Error("useEffect() can only run while rendering a Kudzu component")
-  if (typeof callback !== "function" || !Array.isArray(dependencies) || dependencies.length || !module || !handler) {
-    throw new Error("useEffect() must be compiled with a literal empty dependency array")
-  }
-  renderContext.effects.push({ module, handler, states, scope, source, ...(cleanup ? { cleanup: true } : {}) })
+  if (typeof callback !== "function" || !Array.isArray(dependencies) || !module || !handler) throw new Error("useEffect() must be compiled with a literal dependency array")
+  const dependencyIds = dependencies.map(dependency => {
+    if (!dependency?.[signalMarker] || !validEffectDependency(dependency.value)) throw new Error(`${source} useEffect() dependencies must be primitive Kudzu state or runtime parameter identifiers`)
+    return dependency.id
+  })
+  renderContext.effects.push({ module, handler, states, scope, source, ...(dependencyIds.length ? { dependencies: dependencyIds } : {}), ...(cleanup ? { cleanup: true } : {}) })
   renderContext.hasBehaviors = true
   renderContext.hasEffects = true
 }
+function validEffectDependency(value) {
+  return value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0)
+}
 export function useRef(initialValue) {
   if (!renderContext) throw new Error("useRef() can only run while rendering a Kudzu component")
   if (initialValue !== null) throw new Error("Kudzu DOM refs must initialize with null")
@@ -271,6 +277,7 @@ export async function renderPage(component, metadata = {}, props = {}) {
         return {
           module: effect.module,
           handler: effect.handler,
+          ...(effect.dependencies ? { dependencies: effect.dependencies } : {}),
           ...(effect.cleanup ? { cleanup: true } : {}),
           ...nativeDescriptor(effect.states.map(([name, read]) => [name, read()]), effect.scope.map(([name, read]) => [name, read()]))
         }
@@ -284,7 +291,7 @@ export async function renderPage(component, metadata = {}, props = {}) {
       ? ""
       : (Array.isArray(metadata.styles) ? metadata.styles : [assetPath(metadata.base, "assets/style.css")]).map(href => `<link rel="stylesheet" href="${escapeAttribute(href)}">`).join("")
     const runtime = renderContext.hasBehaviors
-      ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu.js")}"></script>`
+      ? `<script type="module" src="${escapeAttribute(metadata.runtimeAsset ?? assetPath(metadata.base, "assets/kudzu.js"))}"></script>`
       : ""
     const nativeRuntime = renderContext.hasNativeBehaviors
       ? `<script type="module" src="${assetPath(metadata.base, "assets/kudzu-native.js")}"></script>`
@@ -317,7 +324,7 @@ export async function renderPage(component, metadata = {}, props = {}) {
       : ""
     return {
-      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}</head><body${state}${textBindings}>${body}${runtime}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}</body></html>`,
+      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}${runtime}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}</head><body${state}${textBindings}>${body}</body></html>`,
       hasBehaviors: renderContext.hasBehaviors,
       hasEffects: renderContext.hasEffects,
       hasParams: renderContext.hasParams,
@@ -476,6 +483,13 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   const tag = node.type
   const props = node.props ?? {}
+  if (typeof tag === "string" && tag.toLowerCase() === "link") {
+    const rel = Object.entries(props).find(([name]) => name.toLowerCase() === "rel")?.[1]
+    const value = rel?.[signalMarker] || rel?.[bindingMarker] ? rel.value : rel
+    if (typeof value === "string" && value.toLowerCase().split(/\s+/).includes("stylesheet")) {
+      throw new Error("Stylesheets must be placed under src/ or declared in kudzu.config styles so Kudzu can emit them in <head>")
+    }
+  }
   const directListText = props.children?.[listFieldMarker] ? props.children : undefined
   const childSelectValue = tag === "select"
     ? Object.hasOwn(props, "value") ? bindingValue(props.value) : noSelectValue

package/framework/dependency-runtime.js ADDED Viewed

@@ -0,0 +1,36 @@
+export function applyCommands(state, commands, commit, log = console.log) {
+  const changed = new Set()
+  for (const [operation, id, operand] of commands) {
+    const current = state.get(id)
+    if (operation === "log") log(operand, current)
+    else {
+      state.set(id, operation === "add" ? current + operand : operand)
+      changed.add(id)
+    }
+  }
+  for (const id of changed) commit(id, state.get(id))
+}
+export const browserState = new Map()
+const committers = []
+export function registerCommitter(commit) {
+  committers.push(commit)
+}
+export function commitDom(id, value) {
+  for (const node of document.querySelectorAll(`[data-k-text="${id}"]`)) node.textContent = value
+  for (const commit of committers) commit(id)
+}
+if (typeof document !== "undefined") {
+  const initialState = document.body.dataset.kState
+  if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)
+  for (const node of document.querySelectorAll("[data-k-text]")) browserState.set(node.dataset.kText, JSON.parse(node.dataset.kValue))
+  const eventNames = ["click", "input", "change"]
+  for (const eventName of eventNames) document.addEventListener(eventName, event => {
+    const target = event.target.closest(`[data-k-on-${eventName}]`)
+    if (target) applyCommands(browserState, JSON.parse(target.getAttribute(`data-k-on-${eventName}`)), commitDom)
+  })
+}

package/package.json CHANGED Viewed

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