@kudzujs/core 0.8.49 → 0.8.51

package/MIGRATION_ROADMAP.md

@@ -2,7 +2,7 @@
 
 This document is the source of truth for Kudzu's product direction, architecture invariants, and future development order. Read it before extending React-shaped syntax or browser capabilities.
 
-The executable post-`0.8.49` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
+The executable post-`0.8.51` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
 
 [`GOAL_A.md`](./GOAL_A.md) and [`GOAL_B.md`](./GOAL_B.md) are completed capability-validation records. Their commerce and realtime dashboard fixtures prove general lifecycle, navigation, async-workflow, and Worker capabilities; they are not separate product verticals or future priority lists.
 
@@ -61,8 +61,9 @@ The following are available building blocks, not future vertical roadmaps:
 - Async build-time components, `getStaticPaths()`, runtime path parameters, metadata, base paths, public assets, CSS, CSS Modules, and post-build hooks.
 - React import normalization for supported named/aliased hooks, direct `React.*` members, fragments, same-file `memo`, inline `useCallback`, direct intrinsic `forwardRef`, top-level `useId`, and analyzable `useMemo` expressions and collections.
 - Function components, props, children, context, direct bindings, conditions, controlled form properties, refs, and synchronous or async handlers.
-- `useState`, independent repeated non-keyed child state with conditional mount ownership, reduced relative-imported `useReducer`, direct dispatch specialization, and reduced Zustand-shaped shared state proven by migration fixtures.
+- `useState`, independent repeated non-keyed child state with conditional mount ownership, reduced relative-imported `useReducer`, direct dispatch specialization, and reduced Zustand-shaped shared state lowered through package-neutral shared-state/action IR and proven by migration fixtures.
 - Mount and dependency effects with cleanup, route/layout lifetimes, conditional/keyed ownership, stale-write isolation, and relative TypeScript Workers.
+- Direct browser-only package references in inline effect setup/cleanup callbacks bundle into route-owned effect ESM without entering build-time component execution or static sibling output.
 - Keyed local-state and imported static collections, pure selectors, nested direct-property lists, recursive and directly exported row specialization, static/keyed component reuse, analyzable specialized prop spreads, serializable literal defaults, direct intrinsic rest forwarding, forwarded JSX children, latest-item handlers, row state/effects/refs, and stable keyed identity.
 - Complete-document native fallback and optional shared-layout navigation groups with parameter initialization, finite prefetch caching, focus, history, cleanup, and independent capability output.
 - React-shaped SVG presentation attributes, direct `clsx` lowering, fixed-locale reactive `Intl.NumberFormat` display formatting, relative TypeScript handler helpers, and source-located diagnostics.
@@ -97,7 +98,7 @@ This queue orders the next investigations by general migration value. Start only
 - Guarded `localStorage` restoration and persistence compose through existing mount/dependency effects, preserving deterministic static fallbacks without a storage runtime.
 - Reachable source compilation excludes unused React/Vite modules while preserving source diagnostics for every reachable module.
 - Direct imported immutable maps fold to static HTML, and relative structured calculations reevaluate consumed scalar fields through existing binding ESM.
-- Direct event-only package imports bundle into route handlers without executing during static rendering.
+- Direct event-handler and inline owned-effect package imports bundle into route handler/effect ESM without executing during static rendering.
 - Production Tailwind output, Inter assets, direct native SVG charts, and Excel export compose without adding Tailwind, Recharts, or a package runtime to Kudzu.
 - FIRE migration validation covers all fourteen routes, URL/storage updates and reload, reset, presets, chart identity, Quiz recommendation, keyed Debt updates, Excel workbook creation, and zero-JavaScript Home/Books/Apps output.
 

package/PERFORMANCE.md

@@ -6,7 +6,15 @@ Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm ru
 
 The maintained 2026-08-13 comparison used Node 24.14.0 and an Intel Core i5-9500 Linux x64 host, one warm-up, and seven alternating fresh-process samples against clean `v0.8.44`. A narrow fast path skips Kudzu semantic transformation for 450 plain `.ts` modules whose runtime edges are exclusively resolvable relative TypeScript imports or exports; all other modules retain the existing transformer. Compile median fell from 2,323.9 ms to 1,413.2 ms (39.2%) and clean-build median from 3,325.3 ms to 2,382.4 ms (28.4%); every paired sample improved. Compile peak-RSS median fell from 571.2 MiB to 552.6 MiB, while build peak RSS was 570.9 MiB versus 568.8 MiB. Compiler scratch fell from 7,328,390 to 1,971,061 bytes. Both targets emitted the same 50 static HTML files, 10,980 bytes, and deploy SHA-256 `e107d78a7f55bc8a1af0ea6e53efeffa19b3d44d21c892484d103fa346e7ba7b`. This is a source-scale compiler comparison, not a cross-framework result.
 
-## Current 0.8.49 Release Snapshot
+## Current 0.8.51 Release Snapshot
+
+Kudzu 0.8.51 broadens compiler-only package-reference routing into existing owned effect ESM and bundling. Static siblings and routes without the effect retain zero package bytes; no new performance claim is made.
+
+## Maintained 0.8.50 Release Snapshot
+
+Kudzu 0.8.50 changes compiler and build-time shared-state metadata while retaining existing RouteIR state ownership, action handler output, and browser runtimes. No new performance claim is made.
+
+## Maintained 0.8.49 Release Snapshot
 
 Kudzu 0.8.49 broadens compiler-only setter-callback validation to direct child fan-out while retaining the existing command descriptors and browser runtimes. No new performance claim is made.
 

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.8.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.49 - Setter callback fan-out.** One component may forward the same destructured setter callback directly to multiple child controls. Kudzu specializes every branch to the original parent signal without shipping callbacks or a component runtime. Read the [release notes](./RELEASES.md#0849---setter-callback-fan-out), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.49), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.51 - Owned effect package imports.** Browser-only package bindings may be referenced directly inside inline effect setup and cleanup callbacks. Kudzu bundles them only into route-owned effect ESM while build-time component modules and static siblings omit the package. Read the [release notes](./RELEASES.md#0851---owned-effect-package-imports), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.51), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,63 @@
 # Kudzu Releases
 
+## 0.8.51 - Owned effect package imports
+
+Kudzu 0.8.51 lets inline owned effect setup and cleanup callbacks reference browser-only package imports directly.
+
+### Changed in 0.8.51
+
+- Direct package references are accepted inside inline `useEffect` setup callbacks and their directly returned inline cleanup functions.
+- Existing package import records feed the route-specific effect handler ESM and package bundler.
+- Build scratch replaces package-owning effect callbacks with inert functions because build-time rendering records ownership without executing effect code.
+- Render-time, helper-indirect, mixed, side-effect, and dynamic package imports remain source-diagnosed.
+
+### Output and performance
+
+- Package code is retained only by routes whose effect graph references it.
+- Build-time component modules and static sibling routes omit the package and its JavaScript.
+- No package runtime, ResourceIR, public adapter API, or new performance claim is added.
+
+### Validation
+
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 217 tests and 166 generated pages.
+- A direct setup/cleanup fixture bundles TypeScript package data into one owned effect handler while its static sibling ships zero JavaScript.
+- Focused negative fixtures retain diagnostics for render-time and helper-indirect package references.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.51
+```
+
+## 0.8.50 - Package-neutral shared state IR
+
+Kudzu 0.8.50 contains reduced Zustand migration syntax behind package-neutral shared-state and action records before generic signal and handler consumers.
+
+### Changed in 0.8.50
+
+- ModuleIR v2 records JSON-safe `SharedStateIR` identities, fields, and initial values.
+- `SharedActionIR` records reference their owning shared state through validated slots.
+- HandlerIR records the shared actions used by route-specific native handlers.
+- The Zustand adapter preserves package-specific source diagnostics while generic compiler and build-time rendering paths consume shared-state metadata.
+
+### Output and performance
+
+- Existing RouteIR layout state, functional action updates, same-turn behavior, and enhanced-navigation persistence remain unchanged.
+- React, Zustand, subscriptions, and a generic store runtime remain absent from deploy output.
+- No public store or compatibility-adapter API is added, and this release makes no new performance claim.
+
+### Validation
+
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 215 tests and 165 generated pages.
+- Focused ModuleIR tests validate JSON round-tripping and reject dangling shared-action state references.
+- The maintained Zustand browser journey retains repeated same-turn updates, batched effects, layout identity, navigation persistence, and removal behavior.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.50
+```
+
 ## 0.8.49 - Setter callback fan-out
 
 Kudzu 0.8.49 lets one component forward the same destructured setter callback directly through multiple child component `on*` props.

package/docs/next-architecture/README.md

@@ -11,7 +11,7 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 | C: state/resource model | Research only | Reduced fixtures expose a limitation |
 | D: routing compatibility | Current behavior preserved | Revisit only with migration evidence and invariant review |
 
-The active post-`0.8.49` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.12 validation, property-level object-state dependencies, direct three-boundary callback/ref ownership, direct primitive prop state initialization, repeated direct leaf-handler callback use, direct child callback fan-out, collision-free and private Context action setters, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete; broader prop, callback, ref, and Context dataflow remains migration-backed work. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
+The active post-`0.8.51` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.12 validation, property-level object-state dependencies, direct three-boundary callback/ref ownership, direct primitive prop state initialization, repeated direct leaf-handler callback use, direct child callback fan-out, collision-free and private Context action setters, package-neutral shared-state/action IR, browser-only package imports in owned effects, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete. ResourceIR remains research requiring two independent lifecycle fixtures. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
 
 ## Required Invariants
 

package/docs/next-architecture/compiler-current-architecture.md

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.8.49` architecture, built on the completed `0.8.23` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
+This maps the current `0.8.51` architecture, built on the completed `0.8.23` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 
@@ -16,14 +16,14 @@ This maps the current `0.8.49` architecture, built on the completed `0.8.23` Goa
 | Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, effect-return, and source-location analysis. |
 | Source-local binding index | [`framework/compiler/analysis/binding-index.mjs`](../../framework/compiler/analysis/binding-index.mjs) | After normalization, assigns deterministic lexical slots and classifies local, parameter, import, capture, global, and unresolved references. Native handler, effect, binding, list evaluator, optimized-command, and effect-resource consumers use complete index-owned AST; synthesized expressions retain the existing fallback. |
 | Pure collection language | [`framework/compiler/collection-analysis.mjs`](../../framework/compiler/collection-analysis.mjs) | Analyzes collection roots/selectors and serializes the allowed pure expression language used by lists and derived dependencies. |
-| Main semantic analysis | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `createKudzuTransformer()` | Produces transformed source plus explicit component, handler, binding, derived, keyed, and effect ownership results. |
+| Main semantic analysis | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `createKudzuTransformer()` | Produces transformed source plus explicit component, shared-state/action, handler, binding, derived, keyed, and effect ownership results. Zustand package syntax is resolved by its adapter before generic shared-state consumers. |
 | Component ownership analysis | [`framework/compiler/analysis/component-analysis.mjs`](../../framework/compiler/analysis/component-analysis.mjs) | Produces ComponentAnalysis v2 with ordered JSON-safe owner and specialization slots for state, setters, props, refs, IDs, direct SignalIR links, structural OwnerRefs, source-local SiteIds, and source provenance. Three direct callback/ref component boundaries specialize into the same parent signal and intrinsic ownership; Context action-private setters may remain compiler-only and receive collision-free consumer-local aliases; AST identity remains private to its source-local session. |
-| Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes ModuleIR v2 with deterministic SymbolRef, SignalIR, HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and ImportIR slots. One fail-closed boundary validates every source-local and component ownership edge before build-module generation. |
+| Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes ModuleIR v2 with deterministic SymbolRef, SharedStateIR, SharedActionIR, SignalIR, HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and ImportIR slots. One fail-closed boundary validates every source-local and component ownership edge before build-module generation. |
 | Route artifact graph | [`framework/compiler/route-build-record.mjs`](../../framework/compiler/route-build-record.mjs), `createRouteBuildRecord()`, `planRouteArtifacts()` | Validates each rendered route's RouteIR, capabilities, entry paths, styles, and exact handler/effect references. Handler modules, Workers, package-client modules, and bundle entry/chunk closure derive from structural edges without serialized output searches or formatted composite keys. |
 | Route contract validation | [`framework/compiler/route-ir.mjs`](../../framework/compiler/route-ir.mjs), `assertRouteIR()` | Fails before artifact selection for invalid state/parameter identity, commands, native/effect captures and dependencies, reactive descriptors, conditions, keyed-list identity/ownership, marker fields, or JSON safety. Immutable in-memory contracts validate once by identity. |
 | Command IR and codegen | [`framework/compiler/optimize/command-specialization.mjs`](../../framework/compiler/optimize/command-specialization.mjs), [`framework/compiler/ir/module-ir.mjs`](../../framework/compiler/ir/module-ir.mjs), [`framework/compiler/codegen/command-codegen.mjs`](../../framework/compiler/codegen/command-codegen.mjs) | Direct commands use the existing fast path; proven immutable state aliases and one-call local helpers specialize to the same JSON-safe command ModuleIR. Recursion, escape, mutation, and dynamic helper dispatch fail explicitly, while unrelated handlers retain native ESM. Codegen emits the existing `__kBehavior` AST and command ABI. |
 | Source compilation | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `compileSource()` | Runs TypeScript with the Kudzu transformer, rejects surviving React/Router references, and returns a JSON-safe project-relative build module, component analysis, ModuleIR, optional handler module, and imported assets without filesystem writes. |
-| Handler/evaluator lowering | [`framework/compiler/handler-lowering.mjs`](../../framework/compiler/handler-lowering.mjs) | Completes source-local callback/binding/list AST rewriting and diagnostics before the JSON-safe IR boundary. |
+| Handler/evaluator lowering | [`framework/compiler/handler-lowering.mjs`](../../framework/compiler/handler-lowering.mjs) | Completes source-local callback, package-neutral shared-action, binding, and list AST rewriting and diagnostics before the JSON-safe IR boundary. |
 | Handler module codegen | [`framework/compiler/handler-codegen.mjs`](../../framework/compiler/handler-codegen.mjs) | Renders finalized ordered imports and concatenates generated module-export source without TypeScript AST or semantic discovery. |
 | Effect analysis | [`framework/compiler/effect-analysis.mjs`](../../framework/compiler/effect-analysis.mjs) | Classifies ordered signal, ordinary object-property DerivedIR, and keyed-item dependencies and validates cleanup-owned browser resources before EffectIR registration. Object sources keep one signal subscription while the existing tagged evaluator and `Object.is` compare the selected primitive value. |
 | Worker graph | [`framework/compiler/worker-compiler.mjs`](../../framework/compiler/worker-compiler.mjs) | Returns functional Worker rewrite results and JSON-safe EffectIR edges, validates relative graphs, emits content-hashed ESM, and resolves placeholders only for rendered effects. |

package/docs/next-architecture/large-application-ai-native-roadmap.md

@@ -183,7 +183,7 @@ P0 creates the semantic base required by every later large-application capabilit
 - Add an internal compatibility adapter registry.
 - Consolidate React compatibility ownership behind one adapter contract.
 - Register React Router ownership without changing native navigation semantics.
-- Move Zustand-specific logic out of generic core, handler, and state paths onto package-neutral shared-state/action IR.
+- Move Zustand-specific logic out of generic core, handler, and state paths onto package-neutral shared-state/action IR. **Completed in `0.8.50`:** the Zustand pass preserves package diagnostics while generic compiler consumers use validated SharedStateIR/SharedActionIR identities and references; no public adapter or store runtime was added.
 - Characterize Redux/RTK, TanStack Query, React Hook Form, Zod, Radix/Headless UI/MUI, CSS-in-JS, animation, chart, drag/drop, virtualization, auth, REST, and GraphQL against real application fixtures.
 - Prefer native packages and Web APIs, then compilation, deterministic migration, adapters, partial support, or explicit unsupported status in that order.
 - Publish no public adapter API until an external adapter requires independent versioning.
@@ -380,8 +380,8 @@ After the relevant P0 foundations, investigate capabilities in this order:
 
 1. Property-level derived dependencies over ordinary object state. **Completed in `0.8.40`:** direct property paths and top-level immutable primitive locals over object state reuse tagged DerivedIR, subscribe to the source signal, and compare selected values with `Object.is`; whole-object and dynamic dependencies remain rejected.
 2. Multi-boundary component/prop/callback/ref/context dataflow. **Three-boundary callback/ref ownership completed in `0.8.43`; collision-free Context action-private state completed in `0.8.44`; action-only Provider setter exposure removed in `0.8.46`; direct primitive prop state initialization completed in `0.8.47`; repeated direct leaf-handler callback use completed in `0.8.48`; direct child callback fan-out completed in `0.8.49`:** forwarding preserves parent SignalIR, Context action lowering uses compiler-owned aliases when consumer locals reuse Provider state/setter names, action-required setters may remain compiler-only when their state is publicly exposed, specialized children may seed local state from a direct primitive parent signal, and one callback may branch through multiple component `on*` props and intrinsic handlers. A fourth callback boundary, callback aliases/non-handler uses, fully hidden Context state, and object/array prop initializers remain fail-closed. Broader prop, callback, ref, and Context graphs remain migration-led work.
-3. Package-neutral shared state/actions and migration of current Zustand internals.
-4. Browser-only package imports in owned effect/resource modules.
+3. Package-neutral shared state/actions and migration of current Zustand internals. **Completed in `0.8.50`:** Zustand source normalization produces one generic shared-state adapter descriptor; selectors and handlers register JSON-safe SharedStateIR/SharedActionIR records, handler lowering consumes package-neutral actions, and existing RouteIR, layout ownership, same-turn updates, navigation persistence, and browser output remain unchanged. Redux/RTK and public adapter APIs remain unsupported.
+4. Browser-only package imports in owned effect/resource modules. **Completed in `0.8.51` for effects:** direct package references in inline effect setup/cleanup callbacks use existing package import records and route-owned effect ESM bundling; build-time component modules and static siblings omit the package. Helper-indirect, render-time, dynamic-import, and ResourceIR package graphs remain unsupported.
 5. ResourceIR from at least two independent WebSocket/SSE/SDK fixtures with the same semantics.
 6. Route/layout capability and CSS chunk closure.
 7. Incremental source and affected-route builds.
@@ -405,7 +405,7 @@ Current factual baseline:
 |---|---|
 | React source | Compiled, partial |
 | React Router | Compiled, partial |
-| Zustand | Compiled, partial, insufficiently isolated |
+| Zustand | Compiled, partial, isolated through internal shared-state/action IR |
 | Redux/RTK | Unsupported |
 | TanStack Query | Migrated recipe, partial |
 | React Hook Form | Migrated recipe, partial |
@@ -481,4 +481,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## Immediate Decision
 
-PR 1 through PR 12, the `0.8.40` property-dependency slice, the `0.8.41` and `0.8.43` direct multi-boundary callback/ref slices, the `0.8.44` Context alias slice, the `0.8.46` action-only Provider setter slice, the `0.8.47` direct primitive prop initializer slice, the `0.8.48` repeated direct leaf-handler callback slice, the `0.8.49` direct child callback fan-out slice, and the `0.8.42` measured route-output optimization are complete. Continue broader **component/prop/callback/ref/context dataflow** only from the next real migration blocker. Do not skip directly to a store, resource, router, virtualization, or ecosystem package feature.
+PR 1 through PR 12, the `0.8.40` property-dependency slice, the `0.8.41` and `0.8.43` direct multi-boundary callback/ref slices, the `0.8.44` Context alias slice, the `0.8.46` action-only Provider setter slice, the `0.8.47` direct primitive prop initializer slice, the `0.8.48` repeated direct leaf-handler callback slice, the `0.8.49` direct child callback fan-out slice, the `0.8.50` package-neutral shared-state/action slice, the `0.8.51` owned-effect package import slice, and the `0.8.42` measured route-output optimization are complete. Continue with **ResourceIR only after two independent WebSocket/SSE/SDK fixtures prove the same lifecycle semantics**. Do not skip directly to a public adapter/store API, router, virtualization, or unsupported ecosystem package feature.

package/docs/next-architecture/versioning.md

@@ -1,6 +1,6 @@
 # Planned Version Sequence
 
-This is an execution sequence, not release history. `0.8.16` through `0.8.49` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.51` are completed scopes represented by package/release records.
 
 Keep each patch behavior-preserving and independently reviewable. If a boundary proves inseparable, revise this plan before combining releases; do not silently broaden a patch.
 
@@ -40,6 +40,8 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.47` | Initialize specialized child state from one direct primitive parent state prop. | Build-known primitive seeds, independent state ownership, existing handler specialization, and negative object/expression diagnostics pass without a runtime change. |
 | `0.8.48` | Allow one setter-callback prop in multiple direct intrinsic handlers. | Each handler lowers once to the same parent signal; repeated same-handler calls and escaped uses fail without a runtime change. |
 | `0.8.49` | Fan one setter-callback prop out through multiple direct child component event props. | Every branch lowers to the original parent signal; aliases, ordinary props, spreads, and the fourth boundary fail without a runtime change. |
+| `0.8.50` | Isolate reduced Zustand migration behind package-neutral shared-state and action IR. | Validated shared identities/actions preserve RouteIR, layout lifetime, same-turn updates, diagnostics, browser behavior, and zero store runtime. |
+| `0.8.51` | Bundle direct browser-only package references from inline owned effect setup/cleanup callbacks. | Package code stays in referenced route effect ESM; build scratch and static siblings omit it while indirect/render-time uses fail. |
 
 ## Sequence Rules
 

package/framework/README.md

@@ -28,7 +28,7 @@ Direct `clsx` calls over literal strings, numbers, arrays, object conditions, an
 
 Repeated ordinary same-file and relative-imported child components execute independently at build time, so each `useState` call receives a distinct concrete state ID while shared native handler modules retain per-element state maps and captures. A direct JSON-safe primitive parent state passed to a destructured child prop remains the same signal for child DOM bindings and effect dependencies; repeated calls own independent effect records, and conditional removal cleans up before remount recreates the effect. Reactive text and attributes may reference recursively chained top-level immutable locals derived through supported pure primitive expressions from direct state; the compiler substitutes those expressions into the existing binding evaluator and subscribes every source state. Fixed-locale `new Intl.NumberFormat("literal").format(Math.round(expression))` display chains reuse that binding ESM, while dynamic locales and options remain unsupported. Multiple direct primitive dependencies share the existing commit batching path: every value is compared with `Object.is`, and one or more same-turn changes cause one cleanup and rerun. A top-level immutable local derived through a supported pure primitive expression from direct state may also be an effect dependency: source state commits schedule evaluation, the derived result is compared with `Object.is`, and the expression is substituted into setup and cleanup handlers. Effect setup and directly returned cleanup callbacks may each resolve one top-level simple `const` function in the same component; those functions are substituted into the existing handler graph rather than retained in a browser registry. Reactive conditional descriptors own state created by their direct branch: initial visible output reuses the rendered template IDs, removal deletes those slots, and remount recreates them from serialized initial values. Static sibling routes and branches without local state add no ownership metadata, component function, hook dispatcher, or rerender loop.
 
-Reduced Zustand migration stores lower to one ordinary layout-lifetime state slot. The compiler accepts one exported `create(set => ({ data, ...actions }))` store with one serializable data property, direct property selectors, and synchronous capture-free actions using one-argument merge-form `set`; selected actions reuse the reducer-style functional update compiler, so same-turn calls observe current logical state and DOM writes still batch. The shared layout must initialize the store before route consumers, outside keyed rows. No Zustand import, store subscription runtime, React hook, or generic external-store capability is emitted.
+Reduced Zustand migration stores lower through package-neutral `SharedStateIR` and `SharedActionIR` records to one ordinary layout-lifetime state slot. The compiler accepts one exported `create(set => ({ data, ...actions }))` store with one serializable data property, direct property selectors, and synchronous capture-free actions using one-argument merge-form `set`; selected actions reuse the generic functional shared-action compiler, so same-turn calls observe current logical state and DOM writes still batch. The shared layout must initialize the store before route consumers, outside keyed rows. No Zustand import, public store API, subscription runtime, React hook, or generic external-store capability is emitted.
 
 - `build.mjs`: TSX compilation, static, `getStaticPaths`, and runtime-fallback routes, base paths, CSS collection, post-build hooks, behavior extraction, and static HTML output.
 - `compiler/ast-helpers.mjs`: shared TypeScript AST traversal, scope, binding, effect-return, and source-location helpers used by compiler passes.
@@ -36,7 +36,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/animation-frame-pass.mjs`: effect-owned animation-frame ref validation and plain mutable effect-scope lowering.
 - `compiler/browser-signal-passes.mjs`: static media-query external-store and navigator capability-condition normalization.
 - `compiler/collection-analysis.mjs`: pure collection expression IR, selector pipeline, alias, and imported-transform analysis.
-- `compiler/descriptor-session.mjs`: private source-local descriptor registration and deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, import, and client-root finalization.
+- `compiler/descriptor-session.mjs`: private source-local descriptor registration and deterministic JSON-safe SharedStateIR, SharedActionIR, HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, import, and client-root finalization.
 - `compiler/effect-analysis.mjs`: ordered effect dependency classification and cleanup-owned browser resource validation before EffectIR registration.
 - `compiler/normalization-pipeline.mjs`: ordered source normalization with parent-pointer repair after each structurally changed source root.
 - `compiler/param-codegen.mjs`: runtime pathname and search-parameter entry generation from rendered route descriptors.
@@ -44,7 +44,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/custom-hook-timer-pass.mjs`: private custom-hook timeout-ref validation and compiler-owned timer-state lowering.
 - `compiler/effect-codegen.mjs`: route-specific ordinary, owned, and navigable effect entry generation.
 - `compiler/optimize/command-specialization.mjs`, `compiler/ir/module-ir.mjs`, and `compiler/codegen/command-codegen.mjs`: JSON-safe command, keyed, and effect ownership registration, sparse per-source ModuleIR, and source-analysis-free existing behavior-call generation.
-- `compiler/handler-lowering.mjs`: source-local native/effect callback, reducer, Context, Zustand, reactive-binding, and list-evaluator AST lowering before IR finalization.
+- `compiler/handler-lowering.mjs`: source-local native/effect callback, reducer, Context, package-neutral shared-action, reactive-binding, and list-evaluator AST lowering before IR finalization.
 - `compiler/handler-codegen.mjs`: AST-free ordered import rendering and finalized handler/binding export-source assembly.
 - `compiler/render-control-pass.mjs`: render-function early-return and exhaustive adjacent-assignment normalization.
 - `compiler/router-pass.mjs`: React Router import validation and native Link, pathname parameter, search parameter, and imperative navigation lowering.

package/framework/compiler/descriptor-session.mjs

@@ -244,6 +244,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
           snapshot: lowered.captureSnapshots.includes(name)
         })),
         imports: entry.imports.map(entry => importSlot(importRecord(entry))),
+        actions: [...entry.reducers.values()].flatMap(reducer => reducer.sharedAction ? [reducer.sharedAction.slot] : []),
         code: lowered.code,
         ...(source(entry.expression) ? { source: source(entry.expression) } : {})
       })

package/framework/compiler/handler-lowering.mjs

@@ -21,18 +21,18 @@ export function createHandlerLowering({ cloneAst, synthesizeTree }) {
             ts.setParentRecursive(call, false)
             return ts.visitNode(call, visitor)
           }
-          if (reducer.store) return zustandActionDispatch(factory, reducer, node.arguments.map(argument => ts.visitNode(argument, visitor)))
+          if (reducer.sharedAction) return sharedActionDispatch(factory, reducer, node.arguments.map(argument => ts.visitNode(argument, visitor)))
           if (node.arguments.length !== 1) throw sourceNodeError(node, expression.getSourceFile(), "Reducer dispatches require exactly one action")
           return reducerDispatch(factory, reducer, ts.visitNode(node.arguments[0], visitor))
         }
         if (ts.isShorthandPropertyAssignment(node) && reducers.has(node.name.text) && matchesExternalReference(node.name, expression, bindingIndex)) {
           if (reducers.get(node.name.text).contextAction) throw sourceNodeError(node, expression.getSourceFile(), "Context actions must be called directly inside an event handler")
-          if (reducers.get(node.name.text).store) throw sourceNodeError(node, expression.getSourceFile(), "Zustand actions must be called directly inside an event handler")
+          if (reducers.get(node.name.text).sharedAction) throw sourceNodeError(node, expression.getSourceFile(), `${reducers.get(node.name.text).sourceKind} actions must be called directly inside an event handler`)
           return factory.createPropertyAssignment(node.name, reducerReference(factory, reducers.get(node.name.text)))
         }
         if (ts.isIdentifier(node) && reducers.has(node.text) && isReferenceIdentifier(node) && matchesExternalReference(node, expression, bindingIndex)) {
           if (reducers.get(node.text).contextAction) throw sourceNodeError(node, expression.getSourceFile(), "Context actions must be called directly inside an event handler")
-          if (reducers.get(node.text).store) throw sourceNodeError(node, expression.getSourceFile(), "Zustand actions must be called directly inside an event handler")
+          if (reducers.get(node.text).sharedAction) throw sourceNodeError(node, expression.getSourceFile(), `${reducers.get(node.text).sourceKind} actions must be called directly inside an event handler`)
           return reducerReference(factory, reducers.get(node.text))
         }
         if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && setters.has(node.expression.text) && matchesExternalReference(node.expression, expression, bindingIndex)) {
@@ -156,19 +156,20 @@ export function createHandlerLowering({ cloneAst, synthesizeTree }) {
   }
 
   function reducerDispatch(factory, reducer, action) {
-    if (reducer.store) return zustandActionDispatch(factory, reducer, [action])
+    if (reducer.sharedAction) return sharedActionDispatch(factory, reducer, [action])
     const previous = factory.createUniqueName("__kPrevious")
     const update = factory.createArrowFunction(undefined, undefined, [factory.createParameterDeclaration(undefined, undefined, previous)], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createCallExpression(factory.createIdentifier(reducer.reducer), undefined, [previous, action]))
     return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"), undefined, [factory.createStringLiteral(reducer.state), update])
   }
 
-  function zustandActionDispatch(factory, reducer, args) {
+  function sharedActionDispatch(factory, reducer, args) {
     const previous = factory.createUniqueName("__kPrevious")
     const current = factory.createUniqueName("__kStore")
     const updateValue = factory.createUniqueName("__kUpdate")
     const partial = factory.createUniqueName("__kPartial")
     const action = factory.createUniqueName("__kAction")
-    const set = factory.createIdentifier(reducer.store.setName)
+    const shared = reducer.sharedAction
+    const set = factory.createIdentifier(shared.setName)
     const merge = factory.createExpressionStatement(factory.createBinaryExpression(current, factory.createToken(ts.SyntaxKind.EqualsToken), factory.createObjectLiteralExpression([
       factory.createSpreadAssignment(current),
       factory.createSpreadAssignment(partial)
@@ -184,11 +185,11 @@ export function createHandlerLowering({ cloneAst, synthesizeTree }) {
       merge
     ], true)
     const body = factory.createBlock([
-      factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(current, undefined, undefined, factory.createObjectLiteralExpression([factory.createPropertyAssignment(reducer.store.field, previous)]))], ts.NodeFlags.Let)),
+      factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(current, undefined, undefined, factory.createObjectLiteralExpression([factory.createPropertyAssignment(shared.field, previous)]))], ts.NodeFlags.Let)),
       factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(set, undefined, undefined, factory.createArrowFunction(undefined, undefined, [factory.createParameterDeclaration(undefined, undefined, updateValue)], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), setBody))], ts.NodeFlags.Const)),
-      factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(action, undefined, undefined, synthesizeTree(reducer.store.actions.get(reducer.action)))], ts.NodeFlags.Const)),
+      factory.createVariableStatement(undefined, factory.createVariableDeclarationList([factory.createVariableDeclaration(action, undefined, undefined, synthesizeTree(shared.implementation))], ts.NodeFlags.Const)),
       factory.createExpressionStatement(factory.createCallExpression(action, undefined, args)),
-      factory.createReturnStatement(factory.createPropertyAccessExpression(current, reducer.store.field))
+      factory.createReturnStatement(factory.createPropertyAccessExpression(current, shared.field))
     ], true)
     const update = factory.createArrowFunction(undefined, undefined, [factory.createParameterDeclaration(undefined, undefined, previous)], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), body)
     return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier("__k"), "set"), undefined, [factory.createStringLiteral(reducer.state), update])

package/framework/compiler/ir/module-ir.mjs

@@ -1,5 +1,5 @@
 export function createModuleIR(file) {
-  return { version: 2, file, symbols: [], signals: [], handlers: [], bindings: [], derived: [], effects: [], keyedBlocks: [], imports: [], clientModules: [] }
+  return { version: 2, file, symbols: [], sharedStates: [], sharedActions: [], signals: [], handlers: [], bindings: [], derived: [], effects: [], keyedBlocks: [], imports: [], clientModules: [] }
 }
 
 export function assertModuleIRReferences(moduleIR, componentAnalysis) {
@@ -15,6 +15,8 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
     })
   }
   indexed("SymbolRef", moduleIR.symbols)
+  indexed("SharedStateIR", moduleIR.sharedStates)
+  indexed("SharedActionIR", moduleIR.sharedActions)
   indexed("SignalIR", moduleIR.signals)
   indexed("HandlerIR", moduleIR.handlers)
   indexed("BindingIR", moduleIR.bindings)
@@ -22,6 +24,7 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
   indexed("EffectIR", moduleIR.effects)
   indexed("KeyedBlockIR", moduleIR.keyedBlocks)
   indexed("ImportIR", moduleIR.imports)
+  for (const action of moduleIR.sharedActions) slot(moduleIR.sharedStates, action.state, `SharedActionIR ${action.slot}`, "SharedStateIR")
   if (componentAnalysis) {
     indexed("Component owner", componentAnalysis.owners)
     indexed("Component specialization", componentAnalysis.specializations)
@@ -54,6 +57,7 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
     if (!reference || typeof reference !== "object") throw new Error(`${label} must be a StateRef`)
     if (reference.kind === "module-symbol") return moduleSymbol(reference.symbol, label)
     if (reference.kind === "symbol") return slot(moduleIR.symbols, reference.symbol, label, "SymbolRef")
+    if (reference.kind === "shared-state") return slot(moduleIR.sharedStates, reference.sharedState, label, "SharedStateIR")
     if (reference.kind !== "state") throw new Error(`${label} has invalid kind ${JSON.stringify(reference.kind)}`)
     const owner = ownerRef(reference.owner, `${label} owner`)
     const states = reference.owner.kind === "component" || reference.owner.kind === "specialization" ? owner.states : []
@@ -74,6 +78,7 @@ export function assertModuleIRReferences(moduleIR, componentAnalysis) {
     for (const [index, signal] of (handler.signals ?? []).entries()) slot(moduleIR.signals, signal.signal, `HandlerIR ${handler.slot} signal ${index}`, "SignalIR")
     for (const [index, imported] of (handler.imports ?? []).entries()) slot(moduleIR.imports, imported, `HandlerIR ${handler.slot} import ${index}`, "ImportIR")
     for (const [index, capture] of (handler.captures ?? []).entries()) if (capture.symbol !== undefined) slot(moduleIR.symbols, capture.symbol, `HandlerIR ${handler.slot} capture ${index}`, "SymbolRef")
+    for (const [index, action] of (handler.actions ?? []).entries()) slot(moduleIR.sharedActions, action, `HandlerIR ${handler.slot} action ${index}`, "SharedActionIR")
     if (handler.keyedBlock !== undefined) slot(moduleIR.keyedBlocks, handler.keyedBlock, `HandlerIR ${handler.slot} keyed block`, "KeyedBlockIR")
   }
   for (const binding of moduleIR.bindings) {
@@ -149,6 +154,24 @@ export function registerSignal(moduleIR, reference, debugName) {
   return signal
 }
 
+export function registerSharedState(moduleIR, descriptor) {
+  let state = moduleIR.sharedStates.find(entry => entry.identity === descriptor.identity && entry.field === descriptor.field)
+  if (!state) {
+    state = { ...descriptor, slot: moduleIR.sharedStates.length }
+    moduleIR.sharedStates.push(state)
+  }
+  return state
+}
+
+export function registerSharedAction(moduleIR, descriptor) {
+  let action = moduleIR.sharedActions.find(entry => entry.state === descriptor.state && entry.name === descriptor.name)
+  if (!action) {
+    action = { ...descriptor, slot: moduleIR.sharedActions.length }
+    moduleIR.sharedActions.push(action)
+  }
+  return action
+}
+
 export function registerCommandHandler(moduleIR, commands, source) {
   const handler = {
     slot: moduleIR.handlers.length,

package/framework/compiler/source-compiler.mjs

@@ -12,6 +12,7 @@ import { captureNames, createDescriptorSession, createSemanticArtifact, nativeCa
 import { analyzeEffectDependencies, validateEffectOwnedBrowserResources } from "./effect-analysis.mjs"
 import { createHandlerCodegen } from "./handler-codegen.mjs"
 import { createHandlerLowering } from "./handler-lowering.mjs"
+import { registerSharedAction, registerSharedState } from "./ir/module-ir.mjs"
 import { createCommandSpecializer } from "./optimize/command-specialization.mjs"
 import { applyNormalizationPasses } from "./normalization-pipeline.mjs"
 import { assetPath, relativeModulePath, withBase } from "./path-helpers.mjs"
@@ -321,8 +322,8 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const packageBindings = packageImportBindings(sourceFile)
     for (const [name] of packageBindings) {
       const references = referenceIdentifiers(sourceFile, name)
-      const invalid = references.find(reference => !insideJsxEventHandler(reference, sourceFile))
-      if (invalid) throw sourceNodeError(invalid, sourceFile, `Package import ${JSON.stringify(name)} may only be referenced directly inside JSX event handlers`)
+      const invalid = references.find(reference => !insideJsxEventHandler(reference, sourceFile) && !insideOwnedEffectCallback(reference, sourceFile))
+      if (invalid) throw sourceNodeError(invalid, sourceFile, `Package import ${JSON.stringify(name)} may only be referenced directly inside JSX event handlers or owned effect setup/cleanup callbacks`)
     }
     const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && ["@kudzujs/core", "react"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
     const importedSourceCache = new Map()
@@ -346,14 +347,14 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const stateOwnersByFunction = new Map()
     const localStateSettersByFunction = new Map()
     const reducersByFunction = new Map()
-    const zustandStores = new Map()
-    const resolvedZustandStore = entry => {
+    const sharedStateAdapters = new Map()
+    const resolvedSharedState = entry => {
       const exportName = entry.kind === "default" ? "default" : entry.imported
       const key = `${entry.target}:${exportName}`
-      if (zustandStores.has(key)) return zustandStores.get(key)
+      if (sharedStateAdapters.has(key)) return sharedStateAdapters.get(key)
       const targetSource = parseSourceFile(entry.target, sourceIndex.get(entry.target))
       const store = analyzeZustandStores(targetSource).get(exportName)
-      zustandStores.set(key, store)
+      sharedStateAdapters.set(key, store)
       return store
     }
     const functions = new Map()
@@ -552,7 +553,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const collect = node => {
       if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer)) {
         const callName = ts.isIdentifier(node.initializer.expression) ? node.initializer.expression.text : ""
-        if (callName && /^use[A-Z]/.test(callName) && importBindings.has(callName) && importBindings.get(callName).kind !== "namespace" && !resolvedZustandStore(importBindings.get(callName))) {
+        if (callName && /^use[A-Z]/.test(callName) && importBindings.has(callName) && importBindings.get(callName).kind !== "namespace" && !resolvedSharedState(importBindings.get(callName))) {
           if (!isLocalConst(node) || !ts.isObjectBindingPattern(node.name) || node.initializer.arguments.length) throw sourceNodeError(node, sourceFile, "Relative custom hooks must initialize one top-level const object destructuring with no arguments")
           const hook = resolveCustomHook(importBindings.get(callName), node.initializer)
           const names = new Set()
@@ -635,26 +636,31 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         }
         if (ts.isIdentifier(node.name) && callName && importBindings.has(callName) && importBindings.get(callName).kind !== "namespace") {
           const storeImport = importBindings.get(callName)
-          const store = resolvedZustandStore(storeImport)
+          const store = resolvedSharedState(storeImport)
           if (store) {
             const selector = node.initializer.arguments[0]
-            if (node.initializer.arguments.length !== 1 || !selector || !ts.isArrowFunction(selector) || selector.parameters.length !== 1 || !ts.isIdentifier(selector.parameters[0].name) || !ts.isPropertyAccessExpression(unwrapExpression(selector.body)) || !ts.isIdentifier(unwrapExpression(selector.body).expression) || unwrapExpression(selector.body).expression.text !== selector.parameters[0].name.text) throw sourceNodeError(node.initializer, sourceFile, "Zustand selectors must be direct arrows such as state => state.quantities")
+            if (node.initializer.arguments.length !== 1 || !selector || !ts.isArrowFunction(selector) || selector.parameters.length !== 1 || !ts.isIdentifier(selector.parameters[0].name) || !ts.isPropertyAccessExpression(unwrapExpression(selector.body)) || !ts.isIdentifier(unwrapExpression(selector.body).expression) || unwrapExpression(selector.body).expression.text !== selector.parameters[0].name.text) throw sourceNodeError(node.initializer, sourceFile, `${store.sourceKind} selectors must be direct arrows such as ${store.selectorExample}`)
             const selected = unwrapExpression(selector.body).name.text
             const owner = nearestFunction(node)
-            if (!owner) throw sourceNodeError(node, sourceFile, "Zustand stores cannot be used outside a Kudzu component")
+            if (!owner) throw sourceNodeError(node, sourceFile, `${store.sourceKind} stores cannot be used outside a Kudzu component`)
             const setters = settersByFunction.get(owner) ?? new Map()
+            const sharedState = registerSharedState(moduleIR, { identity: store.identity, field: store.field, initialValue: store.initialData })
+            const sharedReference = { kind: "shared-state", sharedState: sharedState.slot }
             if (selected === store.field) {
               const setter = `__kStoreState_${node.name.text}`
               setters.set(setter, node.name.text)
-              registerState(owner, node.name.text, setter, "store", node)
+              registerState(owner, node.name.text, setter, "shared-state", node)
+              stateOwnersByFunction.get(owner).set(node.name.text, sharedReference)
             }
             else if (store.actions.has(selected)) {
               setters.set(node.name.text, node.name.text)
-              registerState(owner, node.name.text, node.name.text, "store-action", node)
+              registerState(owner, node.name.text, node.name.text, "shared-action", node)
+              stateOwnersByFunction.get(owner).set(node.name.text, sharedReference)
+              const action = registerSharedAction(moduleIR, { state: sharedState.slot, name: selected })
               const reducers = reducersByFunction.get(owner) ?? new Map()
-              reducers.set(node.name.text, { state: node.name.text, store, action: selected })
+              reducers.set(node.name.text, { state: node.name.text, sourceKind: store.sourceKind, sharedAction: { ...action, setName: store.setName, field: store.field, implementation: store.actions.get(selected) } })
               reducersByFunction.set(owner, reducers)
-            } else throw sourceNodeError(unwrapExpression(selector.body).name, sourceFile, `Zustand store ${JSON.stringify(store.name)} has no supported property ${JSON.stringify(selected)}`)
+            } else throw sourceNodeError(unwrapExpression(selector.body).name, sourceFile, `${store.sourceKind} store ${JSON.stringify(store.name)} has no supported property ${JSON.stringify(selected)}`)
             settersByFunction.set(owner, setters)
           }
         }
@@ -1764,7 +1770,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         const descriptor = descriptors.compileEffectCallback(compiledCallback, {
           setters,
           reducers: reducersForNode(node, reducersByFunction),
-          importBindings: specializedEffect?.imports ?? importBindings,
+          importBindings: specializedEffect?.imports ?? new Map([...importBindings, ...packageBindings]),
           listItem: dependencyItem,
           keyedBlock: activeKeyedBlock?.block.slot,
           stateOwners: new Map([...stateOwnersForNode(callbackArgument), ...stateOwnersForNode(node), ...(specializedEffectStateOwners.get(node)?.references ?? []), ...(activeStateOwners ?? [])]),
@@ -1798,8 +1804,11 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
           ...(analysisSource(effectSource) ? { source: analysisSource(effectSource) } : {})
         })
         const dependencyExpressions = effect.dependencies.map((dependency, index) => dependency.kind === "derived" ? moduleIR.derived[dependency.derived].expression : ["state", dependencyEntries[index]?.name ?? ordinaryDependencies[index].text])
+        const buildCallback = [...packageBindings].some(([name]) => referenceIdentifiers(callback, name).length)
+          ? factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createBlock([], false))
+          : callback
         return factory.updateCallExpression(node, node.expression, node.typeArguments, [
-          callback,
+          buildCallback,
           factory.createArrayLiteralExpression(subscriptionNames.map(name => factory.createIdentifier(name))),
           factory.createStringLiteral(handlerUrl),
           factory.createStringLiteral(effect.setup.exportName),
@@ -2147,6 +2156,24 @@ function insideJsxEventHandler(node, root) {
   return false
 }
 
+function insideOwnedEffectCallback(node, root) {
+  let callback
+  for (let current = node.parent; current && current !== root.parent; current = current.parent) {
+    if (!isFunctionLike(current)) continue
+    callback = current
+    break
+  }
+  if (!callback) return false
+  if (ts.isCallExpression(callback.parent) && callback.parent.arguments[0] === callback && ts.isIdentifier(callback.parent.expression) && callback.parent.expression.text === "useEffect") return true
+  const returned = callback.parent
+  if (!ts.isReturnStatement(returned)) return false
+  for (let current = returned.parent; current && current !== root.parent; current = current.parent) {
+    if (!isFunctionLike(current)) continue
+    return ts.isCallExpression(current.parent) && current.parent.arguments[0] === current && ts.isIdentifier(current.parent.expression) && current.parent.expression.text === "useEffect"
+  }
+  return false
+}
+
 function validateKeyedList(parts, sourceFile, setters, rowStates, componentSpecializations, expandedRowSpecializations, nestedRowSpecializations, factory, prepareListCallback, bindingIndex) {
   const fail = (node, message) => {
     throw sourceNodeError(node, sourceFile, message)

package/framework/compiler/zustand-pass.mjs

@@ -51,7 +51,18 @@ export function createZustandPass({ isSerializableStateLiteral, nativeCaptureNam
           }
           validateAction(action.body)
         }
-        stores.set(declaration.name.text, { name: declaration.name.text, setName: callback.parameters[0].name.text, field: data[0].name, initialValue: data[0].value, actions, declaration })
+        stores.set(declaration.name.text, {
+          name: declaration.name.text,
+          identity: `${relative(sourceDirectory, sourceFile.fileName).replaceAll(sep, "/")}#${declaration.name.text}`,
+          sourceKind: "Zustand",
+          selectorExample: "state => state.quantities",
+          setName: callback.parameters[0].name.text,
+          field: data[0].name,
+          initialValue: data[0].value,
+          initialData: serializableLiteralValue(data[0].value),
+          actions,
+          declaration
+        })
       }
     }
     const visit = node => {
@@ -70,22 +81,22 @@ export function createZustandPass({ isSerializableStateLiteral, nativeCaptureNam
       if (declaration) throw sourceNodeError(declaration, sourceFile, "Zustand create must directly initialize an exported const store")
       return sourceFile
     }
-    const identity = name => `${relative(sourceDirectory, sourceFile.fileName).replaceAll(sep, "/")}#${name}`
     const visitor = node => {
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && stores.has(node.name.text)) {
         const store = stores.get(node.name.text)
-        return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, factory.createCallExpression(factory.createIdentifier("__kCreateStore"), undefined, [
-          factory.createStringLiteral(identity(store.name)),
+        return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, factory.createCallExpression(factory.createIdentifier("__kCreateSharedState"), undefined, [
+          factory.createStringLiteral(store.identity),
           factory.createStringLiteral(store.field),
           store.initialValue,
-          factory.createArrayLiteralExpression([...store.actions.keys()].map(name => factory.createStringLiteral(name)))
+          factory.createArrayLiteralExpression([...store.actions.keys()].map(name => factory.createStringLiteral(name))),
+          factory.createStringLiteral(store.sourceKind)
         ]))
       }
       if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "zustand") return undefined
       return ts.visitEachChild(node, visitor, context)
     }
     const normalized = ts.visitNode(sourceFile, visitor)
-    const declaration = factory.createImportDeclaration(undefined, factory.createImportClause(false, undefined, factory.createNamedImports([factory.createImportSpecifier(false, undefined, factory.createIdentifier("__kCreateStore"))])), factory.createStringLiteral("@kudzujs/core"))
+    const declaration = factory.createImportDeclaration(undefined, factory.createImportClause(false, undefined, factory.createNamedImports([factory.createImportSpecifier(false, undefined, factory.createIdentifier("__kCreateSharedState"))])), factory.createStringLiteral("@kudzujs/core"))
     const statements = [...normalized.statements]
     statements.splice(statements.findLastIndex(statement => ts.isImportDeclaration(statement)) + 1, 0, declaration)
     return factory.updateSourceFile(normalized, statements)
@@ -93,3 +104,14 @@ export function createZustandPass({ isSerializableStateLiteral, nativeCaptureNam
 
   return { analyzeZustandStores, normalizeZustandMigrationSyntax }
 }
+
+function serializableLiteralValue(node) {
+  const value = unwrapExpression(node)
+  if (ts.isStringLiteral(value) || ts.isNumericLiteral(value)) return ts.isNumericLiteral(value) ? Number(value.text) : value.text
+  if (value.kind === ts.SyntaxKind.TrueKeyword) return true
+  if (value.kind === ts.SyntaxKind.FalseKeyword) return false
+  if (value.kind === ts.SyntaxKind.NullKeyword) return null
+  if (ts.isPrefixUnaryExpression(value)) return value.operator === ts.SyntaxKind.MinusToken ? -Number(value.operand.text) : Number(value.operand.text)
+  if (ts.isArrayLiteralExpression(value)) return value.elements.map(serializableLiteralValue)
+  return Object.fromEntries(value.properties.map(property => [property.name.text, serializableLiteralValue(property.initializer)]))
+}

package/framework/core.mjs

@@ -80,18 +80,18 @@ export function useReducer(reducer, initialValue, name) {
   return [state, dispatch]
 }
 
-export function __kCreateStore(name, field, initialValue, actions) {
+export function __kCreateSharedState(name, field, initialValue, actions, sourceKind = "Shared state") {
   return selector => {
-    if (!renderContext) throw new Error("Zustand stores can only be read while rendering a Kudzu component")
-    let store = renderContext.stores.get(name)
+    if (!renderContext) throw new Error(`${sourceKind} stores can only be read while rendering a Kudzu component`)
+    let store = renderContext.sharedStates.get(name)
     if (!store) {
-      if (renderContext.scoped && renderContext.renderScope !== "layout") throw new Error(`Zustand store ${JSON.stringify(name)} must be initialized by the shared layout before route components use it`)
-      if (renderContext.listRoot || renderContext.listRowRoot || renderContext.listTemplate) throw new Error(`Zustand store ${JSON.stringify(name)} cannot be initialized inside a keyed row`)
+      if (renderContext.scoped && renderContext.renderScope !== "layout") throw new Error(`${sourceKind} store ${JSON.stringify(name)} must be initialized by the shared layout before route components use it`)
+      if (renderContext.listRoot || renderContext.listRowRoot || renderContext.listTemplate) throw new Error(`${sourceKind} store ${JSON.stringify(name)} cannot be initialized inside a keyed row`)
       const [state] = useState(initialValue, `${name}.${field}`)
       store = { [field]: state }
       for (const action of actions) {
         const marker = () => {
-          throw new Error("Zustand actions are compiled into browser handlers")
+          throw new Error(`${sourceKind} actions are compiled into browser handlers`)
         }
         Object.defineProperties(marker, {
           [signalMarker]: { value: true },
@@ -100,7 +100,7 @@ export function __kCreateStore(name, field, initialValue, actions) {
         })
         store[action] = marker
       }
-      renderContext.stores.set(name, store)
+      renderContext.sharedStates.set(name, store)
     }
     return selector(store)
   }
@@ -458,7 +458,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}, props = {}, layout) {
-  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, nextId: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowRefs: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], stores: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerReferences: new Map(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], searchParamsWritable: false, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, nextId: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowRefs: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], sharedStates: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerReferences: new Map(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], searchParamsWritable: false, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const page = { [routeScopeMarker]: true, component, props }

package/package.json

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