@kudzujs/core 0.6.5 → 0.6.6

package/GOAL_B.md

@@ -0,0 +1,153 @@
+# Goal B: Static Realtime Dashboards
+
+Goal B makes Kudzu sufficient for a ThingsBoard-shaped realtime device dashboard without turning Kudzu into a stream runtime, widget framework, or server platform. It preserves complete static documents, zero-JavaScript routes that use no browser capabilities, direct DOM ownership, native navigation fallback, and the absence of React, a VDOM, hydration, or a retained browser component tree.
+
+`MIGRATION_ROADMAP.md` remains the source of truth for compiler invariants and fixture-first development. This document is the implementation contract for realtime dashboard work.
+
+## Product Target
+
+A user can statically deploy this flow:
+
+```text
+dashboard -> devices -> device detail -> alarms -> settings
+```
+
+The first vertical slice is deliberately smaller:
+
+```text
+plain route <-> realtime device dashboard
+```
+
+The dashboard receives a logical 1,000 telemetry samples per second, keeps a bounded history in a module Worker, downsamples it, and updates one imperative chart without routing samples through `useState()`.
+
+## Runtime Model
+
+```text
+Complete static dashboard shell
+  -> route-specific effect ESM
+  -> route-owned module Worker
+  -> bounded telemetry buffer and downsampling
+  -> batched imperative chart updates
+```
+
+Kudzu state is for low-frequency UI state such as selected device, time range, filters, tabs, connection status, alarm status, and widget configuration. High-frequency samples belong in a Worker or imperative browser module.
+
+The Worker is a capability, not a framework runtime. Routes that do not create one must not load its graph. Static routes must remain JavaScript-free.
+
+## Milestone 1: Relative TypeScript Workers
+
+Status: implemented and verified. The compiler recognizes only the exact inline-effect form below, emits its validated graph separately, rewrites the constructor to the base-aware same-origin asset, and leaves routes without this capability on their existing output paths.
+
+Support this exact shape inside a compiled inline `useEffect` callback:
+
+```tsx
+useEffect(() => {
+  const worker = new Worker(
+    new URL("../telemetry.worker.ts", import.meta.url),
+    { type: "module" },
+  )
+
+  const onMessage = (event: MessageEvent<ChartFrame>) => chart.render(event.data)
+  worker.addEventListener("message", onMessage)
+
+  return () => {
+    worker.removeEventListener("message", onMessage)
+    worker.terminate()
+    chart.dispose()
+  }
+}, [])
+```
+
+Compiler requirements:
+
+- accept only an unshadowed `Worker` with `new URL(relativeLiteral, import.meta.url)` and literal `{ type: "module" }`;
+- resolve one `.worker.ts` entry under project source and bundle its relative TypeScript graph separately from window code;
+- emit deterministic content-hashed ESM under `assets/workers` and rewrite the constructor to the base-aware emitted URL;
+- reject package imports, JSX, TypeScript import-equals declarations, dynamic imports, `require()`, paths outside source, malformed options, and unsupported Worker forms with source locations;
+- reject ordinary runtime imports or re-exports of `.worker.ts`; type-only imports may erase normally;
+- do not mark Worker files as navigation capability scripts or import them into the window;
+- create the Worker only when the owning effect mounts;
+- preserve byte-for-byte generated shared/list/effect paths for builds without relative TypeScript Workers where practical;
+- reject generated/public asset collisions instead of silently overwriting output.
+
+Worker construction inside imported helpers or imported keyed-row effects, `SharedWorker`, classic workers, inline Blob workers, and arbitrary dynamic Worker URLs are outside Milestone 1. Imported keyed rows must move Worker ownership to a directly compiled page or local component effect so lexical global analysis remains tied to the original source tree.
+
+## Ownership
+
+| Owner | Lifetime | Dashboard responsibility |
+|---|---|---|
+| Document | Full document | authentication expiry and global diagnostics |
+| Layout | Enhanced navigation session | tenant session or shared transport |
+| Route | Current dashboard/device | Worker, telemetry subscription, request cancellation |
+| DOM range | Current widget | chart, gauge, map, table, animation frame |
+| Worker | Explicit owner cleanup | parsing, bounded buffering, aggregation, downsampling |
+
+Leaving a route must remove message listeners, stop chart work, terminate its Worker, and invalidate stale UI writes before another route mounts. BFCache-preserved documents must retain their live ownership until a real document exit.
+
+## Fixture Contract
+
+The first fixture must provide:
+
+- one complete realtime dashboard document and one complete plain document in an opt-in navigation group;
+- one unrelated static route with zero JavaScript;
+- a relative TypeScript Worker importing at least one relative helper;
+- a fixed-capacity ring buffer with deterministic eviction;
+- logical 1,000 samples/second input in batches rather than a 1 ms browser timer;
+- bounded downsampled frames delivered at no more than display cadence;
+- one imperative canvas or DOM chart updated without sample-level Kudzu setters;
+- direct load, dashboard-to-plain navigation, back/forward, and repeated cached revisits;
+- exact counters for Worker starts, terminations, messages, renders, listeners, and stale post-cleanup work;
+- native document fallback when JavaScript or Worker creation fails.
+
+## Acceptance Criteria
+
+- the Worker graph is absent from static and plain route HTML and is fetched only after the dashboard effect mounts;
+- two unchanged production builds emit identical Worker names and bytes;
+- changing Worker source changes its content hash;
+- base-prefixed deployment produces a valid same-origin Worker URL;
+- 30 dashboard/plain cycles create and terminate exactly 30 route Workers with no growing listener or chart ownership;
+- messages arriving after cleanup cannot update removed route DOM;
+- the ring buffer remains at its configured capacity under sustained input;
+- chart rendering is batched and sample ingestion does not call `useState()`;
+- routes without Worker capabilities remain byte-for-byte unaffected;
+- output raw/gzip cost, clean build time, sample throughput, render cadence, and lifecycle counters are recorded;
+- `npm run check`, `npm test`, package dry-run, and browser checks pass.
+
+Verified measurements for the focused `/dash` fixture: the minified Worker graph is `assets/workers/telemetry.worker-BVG2SA55.js`, 907 B raw and 477 B gzip. The dashboard window graph is 11,388 B raw and 5,148 B gzip across its shared runtime, effect runtime, navigation, route effect entry, and handler module; the Worker is not part of that graph. Seven clean minified builds measured 455.1, 459.9, 460.7, 463.5, 467.6, 472.6, and 475.2 ms, with a 463.5 ms median.
+
+The real-Worker browser check uses real wall time and requires sustained generation beyond 1,130 samples at 700-1,300 logical samples/second, an exact 128-sample ring bound, batches of 10, exactly 24 displayed points, multiple renders, and a render ceiling below 25 Hz. Delayed Worker ticks catch up in batches to the logical 1,000 samples/second clock; frames emit no more often than every 50 ms. The imperative chart performs a minimal canvas path draw. The navigation ownership check completed 30 dashboard/plain cycles with exactly 30 starts and 30 terminations, exactly 60 listener additions and removals across message and error listeners, zero retained listeners after every cleanup, disposed every old chart canvas, fresh ownership on back/forward and cached revisits, and no render from a removed message listener invoked after cleanup. Dashboard, plain, and static HTML contain no Worker asset URL; plain does not load the route effect graph, and static contains no script, capability marker, or state payload. A no-Worker equivalent emitted byte-identical shared runtime, effect runtime, navigation, and route effect entry files with no `assets/workers` directory. An unreachable imported-row effect referencing `unused.worker.ts` emitted no Worker asset. Two unchanged builds emitted identical Worker names and bytes, and a controlled downsample-source change changed the emitted hash.
+
+## Delivery Order
+
+1. **Worker compiler capability**: exact syntax, graph bundling, hashing, base rewriting, diagnostics, and zero-cost exclusion.
+2. **Realtime vertical slice**: mock telemetry Worker, bounded buffer, downsampling, imperative chart, and route cleanup.
+3. **Shared transport**: add a layout-owned mock connection only if multiple routes prove that one Worker per route is wasteful.
+4. **Device workflows**: filters, commands, timeout/error handling, and stale response suppression.
+5. **Alarm workflows**: active/history views and optimistic acknowledgement with rollback.
+6. **Widget expansion**: add one gauge, table, map, or real chart engine at a time only when a fixture requires it.
+
+Each phase starts with one failing fixture and ends with correctness, lifecycle, browser, size, and build measurements.
+
+## Performance Gates
+
+- sustained 1,000 samples/second does not create one main-thread task or Kudzu state commit per sample;
+- Worker memory is bounded by declared buffer capacity;
+- chart updates are batched to at most one per display frame;
+- dashboard departure stops observable messages and renders before the next route mounts;
+- repeated navigation leaves no growing Worker, timer, listener, chart, state, DOM, or heap ownership;
+- Worker support adds no bytes to routes and builds that do not use it;
+- material losses are profiled and fixed or documented as explicit tradeoffs using matched initial content and behavior.
+
+## Non-Goals
+
+- implementing ThingsBoard's server, protocol, rule engine, database, or complete UI;
+- storing telemetry samples in Kudzu component state;
+- adding a general observable, scheduler, stream, state, or widget runtime;
+- retaining a browser component tree;
+- request-time SSR, Server Actions, or a hidden application server;
+- a plugin marketplace or arbitrary third-party React widgets;
+- claiming Worker isolation as a security sandbox.
+
+## Completion Definition
+
+Goal B Milestone 1 is complete when the focused realtime fixture proves deterministic relative TypeScript Worker emission, bounded high-frequency processing, imperative chart updates, exact route ownership and cleanup across repeated navigation, native/static fallback, zero-cost exclusion, source diagnostics, and recorded production measurements.

package/README.md

@@ -380,6 +380,20 @@ Dependency values are limited to JSON-safe strings, finite numbers, booleans, an
 
 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.
 
+An inline effect may own an exact relative TypeScript module Worker:
+
+```tsx
+useEffect(() => {
+  const worker = new Worker(
+    new URL("../telemetry.worker.ts", import.meta.url),
+    { type: "module" },
+  )
+  return () => worker.terminate()
+}, [])
+```
+
+Kudzu resolves the path from the callback source, bundles the Worker and its relative TypeScript imports separately as content-hashed ESM under `assets/workers`, and rewrites the constructor to the base-prefixed same-origin asset URL. The Worker is fetched only when the effect mounts; it is not a capability script, preload, or window import. Unrendered effect handlers do not cause their Worker root to be emitted. This slice requires unshadowed global `Worker` and `URL`, exact `import.meta.url`, a relative `.worker.ts` string literal, and exactly `{ type: "module" }`. Worker graphs reject JSX, package runtime imports, TypeScript import-equals declarations, dynamic imports, `require()`, missing files, and paths outside `src`. Worker source cannot be imported or re-exported as an ordinary runtime module. Construction in event handlers, imported helpers, or imported keyed-row effects is rejected; move keyed-row Worker ownership to a directly compiled page or local component effect. Public or absolute JavaScript Workers remain ordinary browser code and are not transformed.
+
 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.
@@ -495,6 +509,7 @@ Supported:
 - Base-path deployments, multiple CSS files, and `afterBuild`
 - Primitive `useState` bindings
 - Mount-only `useEffect(fn, [])` compiled to route-specific ESM
+- Relative TypeScript module Workers owned by inline effects
 - Conditional and keyed-row effect ownership with cleanup on DOM removal
 - Synchronous and async event handlers
 - Relative imported helpers in native handlers

package/framework/README.md

@@ -17,6 +17,8 @@
 
 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.
 
+Exact relative `.worker.ts` constructors in inline effects are validated and bundled in a separate content-hashed ESM graph under `dist/assets/workers/`. Those files are referenced only by rendered effect handlers and never become document capability scripts, preloads, or window imports; unreachable source effects do not emit their Worker roots. Worker graphs allow relative TypeScript ESM runtime imports only and reject JSX, package runtime imports, import-equals declarations, dynamic imports, `require()`, and paths outside `src`. Ordinary runtime imports or re-exports of `.worker.ts` and Worker construction in imported keyed-row effects are rejected.
+
 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.
 
 Direct JSON-safe primitive keyed-item dependencies subscribe each row record to its owning list commit and compare selected fields after `list-runtime.js` synchronously refreshes the row marker. Only changed rows rerun with the complete latest item; reorder compares equal, unrelated fields do nothing, and key changes remain remove plus mount. Builds without item dependencies emit no item reader or list-state subscription code.

package/framework/build.mjs

@@ -45,8 +45,10 @@ export async function build({ quiet = false, minify = true } = {}) {
   const sourceIndex = new Map(await Promise.all(sourceFiles.map(async file => [file, await readFile(file, "utf8")])))
 
   const handlerModules = []
+  const workerReferences = []
   for (const file of sourceFiles) {
-    const handlerModule = await compile(file, sourceFileSet, sourceIndex, base)
+    if (file.endsWith(".worker.ts")) continue
+    const handlerModule = await compile(file, sourceFileSet, sourceIndex, base, workerReferences)
     if (handlerModule) handlerModules.push(handlerModule)
   }
 
@@ -161,6 +163,18 @@ export async function build({ quiet = false, minify = true } = {}) {
 
   const assetsDirectory = join(outputDirectory, "assets")
   await mkdir(assetsDirectory, { recursive: true })
+  const renderedEffects = new Set(plans.flatMap(plan => plan.effects.map(effect => `${effect.module}:${effect.handler}`)))
+  const renderedWorkerReferences = workerReferences.filter(reference => renderedEffects.has(`${reference.module}:${reference.handler}`))
+  if (renderedWorkerReferences.length && await exists(join(root, "public", "assets", "workers"))) throw new Error("public/assets/workers collides with Kudzu's generated Worker asset namespace")
+  const workerAssets = await emitWorkers(renderedWorkerReferences, sourceFileSet, assetsDirectory, base, minify)
+  for (const module of handlerModules) {
+    for (const reference of workerReferences) {
+      if (reference.module !== assetPath(base, `assets/${module.path}`)) continue
+      const url = workerAssets.get(reference.placeholder) ?? "about:blank"
+      module.code = module.code.replaceAll(JSON.stringify(reference.placeholder), JSON.stringify(url))
+    }
+    if (module.code.includes("/__kudzu_worker_")) throw new Error(`Worker URL placeholder survived in ${module.path}`)
+  }
   const commandEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.commands).map(event => event.event)))].sort()
   const nativeEvents = [...new Set(plans.flatMap(plan => plan.events.filter(event => event.native).map(event => event.event)))].sort()
   const hasTextBindings = plans.some(plan => plan.bindings.some(binding => binding.target === "text"))
@@ -1528,7 +1542,7 @@ function escapeAttribute(value) {
   return escapeHtml(value).replaceAll('"', """).replaceAll("'", "'")
 }
 
-async function compile(file, sourceFiles, sourceIndex, base) {
+async function compile(file, sourceFiles, sourceIndex, base, workerReferences) {
   const source = sourceIndex.get(file)
   const nativeHandlers = []
   const effectHandlers = []
@@ -1544,7 +1558,7 @@ async function compile(file, sourceFiles, sourceIndex, base) {
       jsx: ts.JsxEmit.ReactJSX,
       jsxImportSource: "@kudzujs/core"
     },
-    transformers: { before: [createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, clientImports)] },
+    transformers: { before: [createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, assetPath(base, `assets/${handlerPath}`), file, sourceFiles, sourceIndex, clientImports, workerReferences)] },
     reportDiagnostics: true
   })
 
@@ -1574,12 +1588,13 @@ async function compile(file, sourceFiles, sourceIndex, base) {
   return { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: nativeHandlers.length > 0, hasEffects: effectHandlers.length > 0, clientImports: [...clientImports] }
 }
 
-function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports) {
+function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings, listExpressions, handlerUrl, file, sourceFiles, sourceIndex, clientImports, workerReferences) {
   return context => sourceFile => {
     const factory = context.factory
     const hasLinkElements = /<link/i.test(sourceFile.text)
     sourceFile = normalizeRenderControlFlow(sourceFile, factory, context)
     ts.setParentRecursive(sourceFile, false)
+    rejectOrdinaryWorkerImports(sourceFile, file, sourceFiles)
     const importBindings = clientImportBindings(sourceFile, file, sourceFiles)
     const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && statement.moduleSpecifier.text === "@kudzujs/core" && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
     const importedSources = new Map()
@@ -1855,7 +1870,19 @@ function createKudzuTransformer(nativeHandlers, effectHandlers, reactiveBindings
         if (invalidCleanup) effectFail(invalidCleanup, "useEffect() cleanup functions cannot declare parameters or be generators")
         if (returns.cleanup && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)) effectFail(callback, "useEffect() async callbacks cannot return cleanup functions")
         const setters = settersForNode(node, settersByFunction)
-        const descriptor = compileNativeCallback(callback, setters, factory, effectHandlers, listEffect?.imports ?? importBindings, clientImports, "effect", dependencyItem, true, returns.cleanup)
+        const callbackSource = listEffect?.sourceFile ?? sourceFile
+        const callbackFile = callbackSource.fileName
+        const workerStart = workerReferences.length
+        let compiledCallback
+        if (listEffect && callbackFile !== file) {
+          const originalCallback = listEffect.source.arguments[0]
+          rejectWorkerConstructions(originalCallback, callbackSource, "Relative TypeScript Worker construction in imported keyed-row effects is not supported; construct the Worker in a directly compiled page or local component effect")
+          compiledCallback = callback
+        } else {
+          compiledCallback = rewriteEffectWorkers(callback, callbackFile, callbackSource, sourceFiles, workerReferences, factory, context)
+        }
+        const descriptor = compileNativeCallback(compiledCallback, setters, factory, effectHandlers, listEffect?.imports ?? importBindings, clientImports, "effect", dependencyItem, true, returns.cleanup)
+        for (const reference of workerReferences.slice(workerStart)) Object.assign(reference, { module: handlerUrl, handler: descriptor.exportName })
         usesListItem ||= Boolean(itemDependencies.length && !listEffect)
         usesBehavior = true
         return factory.updateCallExpression(node, node.expression, node.typeArguments, [
@@ -2547,6 +2574,7 @@ function compileEvent(expression, setters, functions, factory, nativeHandlers, h
   const optimized = compileOptimizedEvent(expression, setters, factory)
   if (optimized) return optimized
 
+  rejectWorkerConstructions(expression, expression.getSourceFile(), "Relative TypeScript Worker construction is only supported directly inside an inline useEffect() callback")
   const descriptor = compileNativeCallback(expression, setters, factory, nativeHandlers, importBindings, clientImports, "handler", listItem)
   return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
     factory.createStringLiteral(handlerUrl),
@@ -2609,9 +2637,81 @@ function compileOptimizedEvent(expression, setters, factory) {
 }
 
 const nativeGlobals = new Set([
-  "Array", "ArrayBuffer", "BigInt", "Boolean", "Date", "Error", "Event", "FormData", "Infinity", "Intl", "JSON", "Map", "Math", "NaN", "Number", "Object", "Promise", "Proxy", "RangeError", "ReferenceError", "Reflect", "RegExp", "Set", "String", "Symbol", "TypeError", "URL", "URLSearchParams", "WeakMap", "WeakSet", "WebSocket", "atob", "btoa", "clearInterval", "clearTimeout", "console", "crypto", "document", "fetch", "globalThis", "history", "isFinite", "isNaN", "location", "navigator", "parseFloat", "parseInt", "queueMicrotask", "requestAnimationFrame", "setInterval", "setTimeout", "structuredClone", "undefined", "window"
+  "Array", "ArrayBuffer", "BigInt", "Boolean", "Date", "Error", "Event", "FormData", "Infinity", "Intl", "JSON", "Map", "Math", "NaN", "Number", "Object", "Promise", "Proxy", "RangeError", "ReferenceError", "Reflect", "RegExp", "Set", "String", "Symbol", "TypeError", "URL", "URLSearchParams", "WeakMap", "WeakSet", "WebSocket", "Worker", "atob", "btoa", "clearInterval", "clearTimeout", "console", "crypto", "document", "fetch", "globalThis", "history", "isFinite", "isNaN", "location", "navigator", "parseFloat", "parseInt", "queueMicrotask", "requestAnimationFrame", "setInterval", "setTimeout", "structuredClone", "undefined", "window"
 ])
 
+function rewriteEffectWorkers(callback, file, sourceFile, sourceFiles, workerReferences, factory, context) {
+  const visit = node => {
+    const candidate = relativeWorkerCandidate(node, sourceFile)
+    if (candidate) {
+      if (nearestFunction(node) !== callback) throw sourceNodeError(node, sourceFile, "Relative TypeScript Worker construction must be directly inside the inline useEffect() callback, not a nested function")
+      const { worker, url, specifier, options } = validateWorkerCandidate(candidate, sourceFile)
+      const target = resolve(dirname(file), specifier)
+      const sourceRelative = relative(sourceDirectory, target)
+      if (sourceRelative.startsWith(`..${sep}`) || sourceRelative === ".." || resolve(sourceDirectory, sourceRelative) !== target) throw sourceNodeError(url.arguments[0], sourceFile, "Relative TypeScript Worker source must remain under src/")
+      if (!sourceFiles.has(target)) throw sourceNodeError(url.arguments[0], sourceFile, `Relative TypeScript Worker ${JSON.stringify(specifier)} must resolve to an existing .worker.ts file under src/`)
+      const identity = `${sourceRelative.replaceAll(sep, "/")}:${ts.getOriginalNode(node).getStart(sourceFile)}`
+      const placeholder = `/__kudzu_worker_${createHash("sha256").update(identity).digest("hex").slice(0, 16)}__.js`
+      workerReferences.push({ root: target, placeholder })
+      return factory.updateNewExpression(worker, worker.expression, worker.typeArguments, [factory.createStringLiteral(placeholder), options])
+    }
+    return ts.visitEachChild(node, visit, context)
+  }
+  return ts.visitEachChild(callback, visit, context)
+}
+
+function rejectWorkerConstructions(expression, sourceFile, message) {
+  const visit = node => {
+    if (relativeWorkerCandidate(node, sourceFile)) throw sourceNodeError(node, sourceFile, message)
+    ts.forEachChild(node, visit)
+  }
+  visit(expression.body ?? expression)
+}
+
+function relativeWorkerCandidate(node, sourceFile) {
+  if (!ts.isNewExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== "Worker") return undefined
+  const first = node.arguments?.[0]
+  if (!first || !ts.isNewExpression(first) || !ts.isIdentifier(first.expression) || first.expression.text !== "URL") return undefined
+  const specifier = first.arguments?.[0]
+  const base = first.arguments?.[1]
+  const relativeLiteral = ts.isStringLiteral(specifier) && (specifier.text.startsWith("./") || specifier.text.startsWith("../"))
+  if (!relativeLiteral && !(specifier && !ts.isStringLiteral(specifier) && base && isImportMetaUrl(base))) return undefined
+  return { worker: node, url: first, sourceFile }
+}
+
+function validateWorkerCandidate(candidate, sourceFile) {
+  const { worker, url } = candidate
+  if (!isUnshadowedGlobal(worker.expression, sourceFile)) throw sourceNodeError(worker.expression, sourceFile, "Relative TypeScript Workers require the unshadowed global Worker constructor")
+  if (!isUnshadowedGlobal(url.expression, sourceFile)) throw sourceNodeError(url.expression, sourceFile, "Relative TypeScript Workers require the unshadowed global URL constructor")
+  if (url.arguments?.length !== 2 || !isImportMetaUrl(url.arguments[1])) throw sourceNodeError(url, sourceFile, "Relative TypeScript Workers require new URL(relativeLiteral, import.meta.url)")
+  const specifierNode = url.arguments[0]
+  if (!ts.isStringLiteral(specifierNode) || !(specifierNode.text.startsWith("./") || specifierNode.text.startsWith("../"))) throw sourceNodeError(specifierNode, sourceFile, "Relative TypeScript Worker paths must be relative string literals")
+  if (/[\\?#]/.test(specifierNode.text) || !specifierNode.text.endsWith(".worker.ts")) throw sourceNodeError(specifierNode, sourceFile, "Relative TypeScript Worker paths must end in .worker.ts")
+  if (worker.arguments?.length !== 2) throw sourceNodeError(worker, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+  const options = worker.arguments[1]
+  if (!ts.isObjectLiteralExpression(options) || options.properties.length !== 1) throw sourceNodeError(options, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+  const property = options.properties[0]
+  const name = ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined
+  if (name !== "type" || !ts.isStringLiteral(property.initializer) || property.initializer.text !== "module") throw sourceNodeError(property, sourceFile, 'Relative TypeScript Workers require exactly { type: "module" } as the second argument')
+  return { worker, url, specifier: specifierNode.text, options }
+}
+
+function isImportMetaUrl(node) {
+  return ts.isPropertyAccessExpression(node) && node.name.text === "url" && ts.isMetaProperty(node.expression) && node.expression.keywordToken === ts.SyntaxKind.ImportKeyword && node.expression.name.text === "meta"
+}
+
+function isUnshadowedGlobal(identifier, sourceFile) {
+  if (isShadowedIdentifier(identifier, sourceFile)) return false
+  return !sourceFile.statements.some(statement => {
+    if (statementDeclaresName(statement, identifier.text)) return true
+    if (!ts.isImportDeclaration(statement) || !statement.importClause) return false
+    const clause = statement.importClause
+    if (clause.name?.text === identifier.text) return true
+    if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) return clause.namedBindings.name.text === identifier.text
+    return clause.namedBindings && ts.isNamedImports(clause.namedBindings) ? clause.namedBindings.elements.some(entry => entry.name.text === identifier.text) : false
+  })
+}
+
 function nativeCaptureNames(expression, setters) {
   return captureNames(expression, expression.body, setters)
 }
@@ -2704,7 +2804,31 @@ function isShadowedIdentifier(node, scopeRoot) {
 
 function statementDeclaresName(statement, name) {
   if (ts.isVariableStatement(statement)) return statement.declarationList.declarations.some(declaration => bindingNames(declaration.name).includes(name))
-  return (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name?.text === name
+  if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isImportEqualsDeclaration(statement)) return statement.name?.text === name
+  if ((ts.isEnumDeclaration(statement) || ts.isModuleDeclaration(statement)) && !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DeclareKeyword)) return ts.isIdentifier(statement.name) && statement.name.text === name
+  return false
+}
+
+function rejectOrdinaryWorkerImports(sourceFile, file, sourceFiles) {
+  for (const node of sourceFile.statements) {
+    let specifier
+    let runtime = false
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      specifier = node.moduleSpecifier
+      runtime = runtimeModuleReference(node)
+    } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && ts.isStringLiteral(node.moduleReference.expression)) {
+      specifier = node.moduleReference.expression
+      runtime = !node.isTypeOnly
+    }
+    if (!runtime || !specifier?.text.startsWith(".")) continue
+    let target
+    try {
+      target = resolveSourceImport(file, specifier.text, sourceFiles)
+    } catch {
+      continue
+    }
+    if (target.endsWith(".worker.ts")) throw sourceNodeError(specifier, sourceFile, "Worker source modules cannot be imported or re-exported as ordinary runtime modules; use new Worker(new URL(relative.worker.ts, import.meta.url), { type: \"module\" }) inside an inline useEffect() callback")
+  }
 }
 
 function loopDeclaresName(loop, name) {
@@ -2736,7 +2860,12 @@ function clientImportBindings(sourceFile, file, sourceFiles) {
   const bindings = new Map()
   for (const node of sourceFile.statements) {
     if (!ts.isImportDeclaration(node) || !node.importClause || node.importClause.isTypeOnly || !ts.isStringLiteral(node.moduleSpecifier) || !node.moduleSpecifier.text.startsWith(".")) continue
-    const target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
+    let target
+    try {
+      target = resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles)
+    } catch (error) {
+      throw sourceNodeError(node.moduleSpecifier, sourceFile, error.message)
+    }
     if (node.importClause.name) bindings.set(node.importClause.name.text, { kind: "default", local: node.importClause.name.text, target })
     const named = node.importClause.namedBindings
     if (named && ts.isNamespaceImport(named)) bindings.set(named.name.text, { kind: "namespace", local: named.name.text, target })
@@ -2845,6 +2974,71 @@ function printClientImports(entries, handlerPath) {
   return imports.join("\n")
 }
 
+async function emitWorkers(references, sourceFiles, assetsDirectory, base, minify) {
+  const roots = [...new Set(references.map(reference => reference.root))].sort()
+  if (!roots.length) return new Map()
+  await validateWorkerGraphs(roots, sourceFiles)
+  const workerDirectory = join(assetsDirectory, "workers")
+  await mkdir(workerDirectory, { recursive: true })
+  const result = await bundle({
+    absWorkingDir: root,
+    entryPoints: roots,
+    outbase: sourceDirectory,
+    outdir: workerDirectory,
+    entryNames: "[dir]/[name]-[hash]",
+    chunkNames: "chunks/[name]-[hash]",
+    bundle: true,
+    splitting: true,
+    format: "esm",
+    platform: "browser",
+    target: "es2022",
+    minify,
+    legalComments: "none",
+    metafile: true,
+    logLevel: "silent"
+  })
+  const emitted = new Map()
+  for (const [output, metadata] of Object.entries(result.metafile.outputs)) {
+    if (!metadata.entryPoint) continue
+    const entry = resolve(root, metadata.entryPoint)
+    const rootReferences = references.filter(reference => reference.root === entry)
+    const outputFile = resolve(root, output)
+    const url = assetPath(base, relative(outputDirectory, outputFile).replaceAll(sep, "/"))
+    for (const reference of rootReferences) emitted.set(reference.placeholder, url)
+  }
+  for (const reference of references) if (!emitted.has(reference.placeholder)) throw new Error(`Worker entry was not emitted: ${relative(root, reference.root)}`)
+  return emitted
+}
+
+async function validateWorkerGraphs(roots, sourceFiles) {
+  const visited = new Set()
+  const queue = [...roots]
+  while (queue.length) {
+    const file = queue.shift()
+    if (visited.has(file)) continue
+    visited.add(file)
+    const sourceFile = parseSourceFile(file, await readFile(file, "utf8"))
+    if (containsJsx(sourceFile)) throw sourceNodeError(sourceFile, sourceFile, "Worker modules must not contain JSX")
+    const visit = node => {
+      if (ts.isImportEqualsDeclaration(node)) throw sourceNodeError(node, sourceFile, "TypeScript import-equals declarations are not supported in Worker modules; use a relative ESM import")
+      if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) throw sourceNodeError(node, sourceFile, "Dynamic imports are not supported in Worker modules")
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require") throw sourceNodeError(node, sourceFile, "require() is not supported in Worker modules")
+      ts.forEachChild(node, visit)
+    }
+    visit(sourceFile)
+    for (const node of sourceFile.statements) {
+      if ((!ts.isImportDeclaration(node) && !ts.isExportDeclaration(node)) || !node.moduleSpecifier || !ts.isStringLiteral(node.moduleSpecifier) || !runtimeModuleReference(node)) continue
+      if (!node.moduleSpecifier.text.startsWith(".")) throw sourceNodeError(node.moduleSpecifier, sourceFile, "Worker modules may only use relative runtime imports")
+      try {
+        queue.push(resolveSourceImport(file, node.moduleSpecifier.text, sourceFiles))
+      } catch (error) {
+        const message = error.message.slice(error.message.indexOf("Relative import"))
+        throw sourceNodeError(node.moduleSpecifier, sourceFile, message)
+      }
+    }
+  }
+}
+
 async function collectClientModules(entries, sourceFiles) {
   const modules = new Set()
   const queue = [...new Set(entries)]
@@ -2853,6 +3047,7 @@ async function collectClientModules(entries, sourceFiles) {
     if (modules.has(file)) continue
     const source = await readFile(file, "utf8")
     const sourceFile = parseSourceFile(file, source)
+    rejectWorkerConstructions(sourceFile, sourceFile, "Relative TypeScript Worker construction is only supported directly inside an inline useEffect() callback, not imported client helpers")
     if (containsJsx(sourceFile)) throw new Error(`${relative(root, file)} Imported client helpers must not contain JSX`)
     rejectUnsupportedClientImports(sourceFile, file)
     modules.add(file)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "bin/",
     "framework/",
     "GOAL_A.md",
+    "GOAL_B.md",
     "README.md",
     "LICENSE"
   ],