@playfast/reform 0.0.7 → 0.0.8

package/{dist/internal/capture.d.ts → src/internal/capture.ts}

@@ -1,19 +1,22 @@
-import { Context } from 'effect';
-import type { Trigger } from '../ui/trigger';
+import { Context } from 'effect'
+import type { Trigger } from '../ui/trigger'
+
 /**
  * A single rendered UI node's observable surface: which contract rendered, the
  * props it received, and the event triggers it was handed. This is exactly what
  * a headless inspector (the proof facade, the dev tool) needs — no DOM, no JSX.
  */
 export interface UiCapture {
-    readonly name: string;
-    readonly props: unknown;
-    readonly events: Record<string, Trigger<unknown>>;
+  readonly name: string
+  readonly props: unknown
+  readonly events: Record<string, Trigger<unknown>>
 }
+
 /** Where captured renders are reported, when a capturing host is present. */
 export interface CaptureSinkApi {
-    record(capture: UiCapture): void;
+  record(capture: UiCapture): void
 }
+
 /**
  * An OPTIONAL service. Core's `ui` read consults it via `serviceOption`: when a
  * capturing host provides it (proofs, the dev tool), every resolved view reports
@@ -21,8 +24,7 @@ export interface CaptureSinkApi {
  * replacing any presentation. Production never provides it, so nothing is
  * recorded and there is no cost beyond one `serviceOption` lookup per render.
  */
-declare const CaptureSinkBase: Context.TagClass<CaptureSink, 'reform/internal/CaptureSink', CaptureSinkApi>;
-export declare class CaptureSink extends CaptureSinkBase {
-}
-export {};
-//# sourceMappingURL=capture.d.ts.map
+const CaptureSinkBase: Context.TagClass<CaptureSink, 'reform/internal/CaptureSink', CaptureSinkApi> =
+  Context.Tag('reform/internal/CaptureSink')<CaptureSink, CaptureSinkApi>()
+
+export class CaptureSink extends CaptureSinkBase {}

package/{dist/internal/ctx.d.ts → src/internal/ctx.ts}

@@ -1,5 +1,6 @@
-import type { Effect } from 'effect';
-import type { YieldWrap } from 'effect/Utils';
+import type { Effect } from 'effect'
+import type { YieldWrap } from 'effect/Utils'
+
 /**
  * The context (`R`) a generator body requires, recovered from the effects it
  * yields. Shared by `Composition.live` and `Procedure.live`, whose bodies are
@@ -8,5 +9,8 @@ import type { YieldWrap } from 'effect/Utils';
  * A body that never yields (`Eff = never`) requires nothing — guard that case
  * first, or `infer R` resolves to `unknown` and leaks into the layer's `RIn`.
  */
-export type Ctx<Eff> = [Eff] extends [never] ? never : [Eff] extends [YieldWrap<Effect.Effect<any, any, infer R>>] ? R : never;
-//# sourceMappingURL=ctx.d.ts.map
+export type Ctx<Eff> = [Eff] extends [never]
+  ? never
+  : [Eff] extends [YieldWrap<Effect.Effect<any, any, infer R>>]
+    ? R
+    : never

package/src/internal/errors.test.ts

@@ -0,0 +1,33 @@
+import { expect, it } from '@effect/vitest'
+import { Context, Effect, Layer, ManagedRuntime } from 'effect'
+import { AsyncSceneLayer, forceSync } from '../index'
+
+// `forceSync` is the sync-build boundary: reform materialises a scene's layer graph
+// with `runSync` so the first frame renders synchronously (D2). A layer whose acquire
+// suspends makes that `runSync` throw Effect's opaque `AsyncFiberException`; the
+// boundary translates it into `AsyncSceneLayer`, which names the cause and the fix.
+
+class Thing extends Context.Tag('test/Thing')<Thing, number>() {}
+
+it('translates an async layer build into AsyncSceneLayer', () => {
+  // A layer whose acquire suspends — exactly what a consumer trips on.
+  const asyncLayer = Layer.effect(Thing, Effect.as(Effect.sleep('1 millis'), 1))
+  const runtime = ManagedRuntime.make(asyncLayer)
+  expect(() => forceSync(() => runtime.runSync(Effect.context<Thing>()))).toThrow(AsyncSceneLayer)
+})
+
+it('passes a synchronous layer build through unchanged', () => {
+  const syncLayer = Layer.succeed(Thing, 1)
+  const runtime = ManagedRuntime.make(syncLayer)
+  const context = forceSync(() => runtime.runSync(Effect.context<Thing>()))
+  expect(Context.get(context, Thing)).toBe(1)
+})
+
+it('re-throws a non-async error untouched', () => {
+  class Boom extends Error {}
+  expect(() =>
+    forceSync(() => {
+      throw new Boom('nope')
+    }),
+  ).toThrow(Boom)
+})

package/src/internal/errors.ts

@@ -0,0 +1,145 @@
+import { Cause, Data, Option, Runtime } from 'effect'
+
+/**
+ * Tagged errors for the framework's synchronous boundaries. Even when thrown
+ * (React render, layer build, reflection), an error carries a `_tag` and its
+ * structured fields — never a bare `Error` — so callers and tooling can match on
+ * it. `Data.TaggedError` subclasses are real `Error`s, so `throw` still works.
+ */
+
+/**
+ * The constructor shape `Data.TaggedError(tag)<A>` produces, named so the
+ * generated `.d.ts` can describe the `extends` base under `isolatedDeclarations`
+ * (which forbids an inferred expression in an extends clause).
+ */
+type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = new (
+  args: A,
+) => Cause.YieldableError & { readonly _tag: Tag } & Readonly<A>
+
+/** The fieldless variant — a `Data.TaggedError(tag)<{}>` constructor. */
+type EmptyTaggedErrorClass<Tag extends string> = new () => Cause.YieldableError & { readonly _tag: Tag }
+
+const SlotRenderingUnavailableBase: TaggedErrorClass<
+  'reform/SlotRenderingUnavailable',
+  { readonly slot: string }
+> = Data.TaggedError('reform/SlotRenderingUnavailable')<{ readonly slot: string }>
+
+/** A `<slots.X/>` was rendered without a render-target host to realize it. */
+export class SlotRenderingUnavailable extends SlotRenderingUnavailableBase {
+  override get message(): string {
+    return `reform: rendering slot '${this.slot}' requires @reform/react`
+  }
+}
+
+const InvalidProvideTargetBase: EmptyTaggedErrorClass<'reform/InvalidProvideTarget'> =
+  Data.TaggedError('reform/InvalidProvideTarget')<{}>
+
+/** `provide(target, …)` was handed something that is neither a ui contract nor a slot. */
+export class InvalidProvideTarget extends InvalidProvideTargetBase {
+  override get message(): string {
+    return 'reform: provide target is neither a ui contract nor a slot'
+  }
+}
+
+const UnknownGroupStateBase: TaggedErrorClass<'reform/UnknownGroupState', { readonly name: string }> =
+  Data.TaggedError('reform/UnknownGroupState')<{ readonly name: string }>
+
+/** `StateGroup.select(group, name)` named a state the group does not contain. */
+export class UnknownGroupState extends UnknownGroupStateBase {
+  override get message(): string {
+    return `reform: unknown state '${this.name}' in group`
+  }
+}
+
+const FeatureLoadFailedBase: TaggedErrorClass<'reform/FeatureLoadFailed', { readonly cause: unknown }> =
+  Data.TaggedError('reform/FeatureLoadFailed')<{ readonly cause: unknown }>
+
+/**
+ * A lazy `Feature`'s `load` Effect failed — the dynamic `import()` rejected (a
+ * missing chunk, a network failure, a module-eval throw). Surfaced as a typed
+ * failure the host hands to the feature's `placeholder.failed`, never a bare
+ * rejection. `cause` is the original rejection value.
+ */
+export class FeatureLoadFailed extends FeatureLoadFailedBase {
+  override get message(): string {
+    return `reform: a feature failed to load (${String(this.cause)})`
+  }
+}
+
+const AsyncReducerBase: EmptyTaggedErrorClass<'reform/AsyncReducer'> =
+  Data.TaggedError('reform/AsyncReducer')<{}>
+
+/** A reducer fold returned a thenable — folds must be pure synchronous writes. */
+export class AsyncReducer extends AsyncReducerBase {
+  override get message(): string {
+    return 'reform: a reducer fold must be synchronous (it returned a Promise)'
+  }
+}
+
+const AsyncSceneLayerBase: EmptyTaggedErrorClass<'reform/AsyncSceneLayer'> =
+  Data.TaggedError('reform/AsyncSceneLayer')<{}>
+
+/**
+ * A scene layer performed async work during reform's synchronous layer build.
+ * Reform materialises a scene's layer graph with `runSync` so the first frame
+ * renders synchronously (D2); a `Layer.effect`/`scoped` whose acquire suspends
+ * (HTTP, opening a DB, `Effect.sleep`) makes that `runSync` throw Effect's opaque
+ * `AsyncFiberException`. `forceSync` catches it and rethrows this, which names the
+ * cause and the sanctioned fix instead of pointing at Effect internals.
+ */
+export class AsyncSceneLayer extends AsyncSceneLayerBase {
+  override get message(): string {
+    return (
+      'reform: a scene layer performed async work while building. Reform builds the ' +
+      'scene synchronously so the first frame can render — a layer acquire must be ' +
+      'synchronous (Layer.sync/Layer.succeed). For async setup (open a connection, ' +
+      'fetch config), use Resource.live from @playfast/reform-resource, which builds ' +
+      'synchronously and resolves in the background.'
+    )
+  }
+}
+
+/**
+ * Whether a thrown value is Effect's "ran async under runSync" defect. `runSync`
+ * throws the bare `AsyncFiberException`; a `ManagedRuntime.runSync` whose layer
+ * build suspends instead throws a `FiberFailure` carrying it as a `Die`, so both
+ * shapes are checked.
+ */
+const isAsyncBuildDefect = (error: unknown): boolean => {
+  if (Runtime.isAsyncFiberException(error)) return true
+  if (!Runtime.isFiberFailure(error)) return false
+  const die = Cause.dieOption(error[Runtime.FiberFailureCauseId])
+  return Option.isSome(die) && Runtime.isAsyncFiberException(die.value)
+}
+
+/**
+ * Run a synchronous runtime read (the scene layer build / context capture) and
+ * translate Effect's async-fiber defect into `AsyncSceneLayer`; any other throw
+ * passes through unchanged. The single home for the sync-build boundary, shared by
+ * the React host and the remote server.
+ */
+export const forceSync = <A>(thunk: () => A): A => {
+  try {
+    return thunk()
+  } catch (error) {
+    if (isAsyncBuildDefect(error)) throw new AsyncSceneLayer()
+    throw error
+  }
+}
+
+const DuplicateRegistrationBase: TaggedErrorClass<
+  'reform/DuplicateRegistration',
+  { readonly kind: string; readonly name: string }
+> = Data.TaggedError('reform/DuplicateRegistration')<{ readonly kind: string; readonly name: string }>
+
+/**
+ * Two distinct primitives were registered under one name into the same runtime —
+ * a silent footgun, since names key DI tags and channel lanes. Thrown for a
+ * channel name reused with a different policy (the second would otherwise be
+ * dropped). Reducer/procedure name clashes are warned (logged), not thrown.
+ */
+export class DuplicateRegistration extends DuplicateRegistrationBase {
+  override get message(): string {
+    return `reform: duplicate ${this.kind} registered under name '${this.name}'`
+  }
+}

package/src/internal/inspect.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from '@effect/vitest'
+import { Schema as S } from 'effect'
+import { State } from '../index'
+import { makeStore } from './store'
+
+// Every reform value should print like an Effect value (an `_id`-tagged JSON),
+// not `[object Object]` — via `toJSON`/`toString`/the Node inspect symbol.
+
+describe('Inspectable', () => {
+  it('a Store reports its current value as tagged JSON', () => {
+    const store = makeStore(41)
+    expect(store.toJSON()).toEqual({ _id: 'reform/Store', value: 41 })
+    store.set(42)
+    expect(store.toJSON()).toEqual({ _id: 'reform/Store', value: 42 })
+    // toString and JSON.stringify route through the same toJSON.
+    expect(JSON.parse(JSON.stringify(store))).toEqual({ _id: 'reform/Store', value: 42 })
+    expect(store.toString()).toContain('reform/Store')
+  })
+
+  it('a definition reports its manifest', () => {
+    class Count extends State.make('count', S.Number) {}
+    // Inspectable is attached at runtime (definitions are reflected via their
+    // manifest); reach the method through a typed view.
+    const inspectable = Count as unknown as { toJSON(): unknown }
+    expect(inspectable.toJSON()).toBe(Count.manifest)
+    expect(String(Count)).toContain('"kind": "State"')
+  })
+})

package/src/internal/inspect.ts

@@ -0,0 +1,34 @@
+import { format, type Inspectable, NodeInspectSymbol } from 'effect/Inspectable'
+
+export { type Inspectable, NodeInspectSymbol }
+
+/**
+ * The `Inspectable` trio built around a `toJSON`, so every reform value prints
+ * like an Effect value — `_id`-tagged JSON under `console.log`, Node's
+ * inspector, `JSON.stringify`, and `String(...)` — instead of `[object Object]`.
+ * Mirrors Effect's `BaseProto` / `Inspectable.Class` (`Inspectable.ts:170`).
+ */
+export const inspectable = (toJSON: () => unknown): Inspectable => ({
+  toJSON,
+  toString: () => format(toJSON()),
+  [NodeInspectSymbol]: () => toJSON(),
+})
+
+/**
+ * Attach the `Inspectable` trio to an existing object as *non-enumerable* own
+ * properties (so they don't show up in `Object.keys`/`for…in` over a definition
+ * class). Used where the value is built by other means — the definition classes,
+ * whose statics are merged in separately.
+ */
+export const attachInspectable = <T extends object>(target: T, toJSON: () => unknown): T => {
+  const trio = inspectable(toJSON) as unknown as Record<PropertyKey, unknown>
+  for (const key of Reflect.ownKeys(trio)) {
+    Object.defineProperty(target, key, {
+      value: trio[key],
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    })
+  }
+  return target
+}

package/src/internal/queryDriver.ts

@@ -0,0 +1,247 @@
+import {
+  Brand,
+  Cause,
+  Chunk,
+  Effect,
+  MutableRef,
+  Option,
+  Queue,
+  Schema,
+  type Scope,
+  Stream,
+} from 'effect'
+import { type AnyAsyncData, AsyncData } from '../calc/asyncData'
+import { reuse } from './reuse'
+import { resolveScheduler } from './scheduler'
+import {
+  type InputsObject,
+  type InputStores,
+  type InvalidateBy,
+  sameKey,
+  wireSources,
+} from './sources'
+import { makeStore, type Store } from './store'
+import { type AnySource } from '../state/token'
+
+// The query-lifecycle driver shared by `AsyncCalc.live` and `RemoteState.live`:
+// sense the inputs, run the query latest-wins (or trailing-conflated), fold the
+// result into an `AnyAsyncData` store with stale-while-revalidate semantics.
+// Extracted so both primitives run the exact same machinery — the asyncCalc
+// test suite is the driver's regression suite.
+
+/** `Gated` (whether the `Idle` arm exists) is the inverse of `alwaysOn`. */
+export type GatedOf<AlwaysOn extends boolean> = AlwaysOn extends true ? false : true
+
+/** The runtime gated flag for an `alwaysOn` config, typed as its `Gated` literal. */
+export const gatedFlag = <AlwaysOn extends boolean>(alwaysOn: AlwaysOn | undefined): GatedOf<AlwaysOn> =>
+  (alwaysOn !== true) as GatedOf<AlwaysOn>
+
+// The hidden revision behind `invalidateOn` — a module-local *branded* number.
+// Reform store services are type-identified (`Context.GenericTag<Store<A>>`), so
+// the hidden state's value type must be un-collidable: `Layer.provide` erases
+// exactly `Store<Revision>` from the returned layer and can never type-level
+// erase a user input that happens to be a number state. Never exported from the
+// package index, so the editor catalog (which only indexes module exports)
+// never sees it.
+export type Revision = number & Brand.Brand<'reform/Revision'>
+export const Revision: Brand.Brand.Constructor<Revision> = Brand.nominal<Revision>()
+export const RevisionSchema: Schema.Schema<Revision, number> = Schema.Number.pipe(
+  Schema.brand('reform/Revision'),
+)
+export const revisionZero: Revision = Revision(0)
+export const bumpRevision = (r: Revision): Revision => Revision(r + 1)
+
+export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A, E, R> {
+  /** The owning definition's name — only for the defect log line. */
+  readonly name: string
+  /** The owning primitive's kind label — only for the defect log line. */
+  readonly label: string
+  /** Whether `disabled` is honored / the `Idle` arm can occur. */
+  readonly gated: boolean
+  readonly inputs: Inputs
+  readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
+  readonly invalidateBy?: InvalidateBy<Inputs> | undefined
+  readonly disabled?: ((inputs: InputsObject<Inputs>) => boolean) | undefined
+  readonly coalesce?: 'switch' | 'trailing' | undefined
+  readonly reuse?: boolean | undefined
+  /**
+   * An extra key segment + wake source beyond the declared inputs — the hidden
+   * `invalidateOn` revision. Kept out of `wireSources` so the user's `query`
+   * and `invalidateBy` see exactly the declared inputs.
+   */
+  readonly extraKey?:
+    | {
+        readonly read: () => unknown
+        readonly subscribe: (listener: () => void) => () => void
+      }
+    | undefined
+  /**
+   * Fired when a run's `Success` value has landed in the store (same scheduler
+   * flush — never before the converged value is readable), with the run's
+   * generation. Not fired on `Error`, interrupt, or while disabled. The seam
+   * `RemoteState` settles pending intents through.
+   */
+  readonly onSettled?: ((generation: number) => void) | undefined
+}
+
+export interface QueryDriver<A, E> {
+  /** The lifecycle store (the full union — callers narrow to their arms). */
+  readonly store: Store<AnyAsyncData<A, E>>
+  /**
+   * The highest generation requested so far (0 before the first kick).
+   * Generations are assigned when a run is REQUESTED (enqueued), so a waiter
+   * registered as `requested() + 1` is satisfied only by a run that began
+   * after registration — the settle-ordering rule `RemoteState` builds on.
+   */
+  readonly requested: () => number
+}
+
+/**
+ * Build the driver: store + subscription + request queue + run fiber, all owned
+ * by the ambient scope (callers run this under `Layer.scoped`). A change to an
+ * input re-runs the query latest-wins (a new run cancels the in-flight one; or,
+ * with `coalesce: 'trailing'`, lets it finish and runs one trailing refetch);
+ * while a re-run is in flight the last `Success`/`Error` is kept with
+ * `refetching: true`.
+ */
+export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R>(
+  options: QueryDriverOptions<Inputs, A, E, R>,
+): Effect.Effect<QueryDriver<A, E>, never, InputStores<Inputs> | R | Scope.Scope> =>
+  Effect.gen(function* () {
+    const scheduler = yield* resolveScheduler
+    const sources = yield* wireSources(options.inputs, options.invalidateBy)
+    const extraKey = options.extraKey
+
+    const keyOf = (args: InputsObject<Inputs>): ReadonlyArray<unknown> =>
+      extraKey === undefined ? sources.keyOf(args) : [...sources.keyOf(args), extraKey.read()]
+    const subscribeAll = (listener: () => void): (() => void) => {
+      const offSources = sources.subscribe(listener)
+      const offExtra = extraKey?.subscribe(listener)
+      return () => {
+        offSources()
+        offExtra?.()
+      }
+    }
+    const disabledNow = (args: InputsObject<Inputs> = sources.snapshot()): boolean =>
+      options.gated && options.disabled !== undefined ? options.disabled(args) : false
+
+    const store = makeStore<AnyAsyncData<A, E>>(
+      disabledNow() ? AsyncData.idle : AsyncData.loading,
+      scheduler,
+    )
+    // The last requested key, so a change that doesn't move it (or only churns
+    // an input `invalidateBy` ignores) doesn't re-fetch.
+    const lastKey = MutableRef.make<ReadonlyArray<unknown> | undefined>(undefined)
+    // The run-generation counter: bumped when a run is REQUESTED (enqueued), so
+    // `requested()` names the newest run that could possibly be in flight.
+    const generation = MutableRef.make(0)
+    const nextGeneration = (): number => {
+      MutableRef.update(generation, (n) => n + 1)
+      return MutableRef.get(generation)
+    }
+
+    // Mark a re-fetch in flight without dropping the visible value (SWR).
+    const markRefetching = () => {
+      const prev = store.get()
+      if (prev._tag === 'Success') store.set(AsyncData.success(prev.value, true))
+      else if (prev._tag === 'Error') store.set(AsyncData.error(prev.error, true))
+      else store.set(AsyncData.loading)
+    }
+
+    // One run of the query, folded into the store. A failure becomes `Error`; an
+    // interrupt (latest-wins cancel) leaves the state untouched; a defect (a bug
+    // in the body) is logged and isolated — the driver keeps running. A `Success`
+    // additionally reports its generation through `onSettled`, after the write,
+    // so settle-driven consequences observe the converged value.
+    const runQuery = (request: Request): Effect.Effect<void, never, R> =>
+      options.query(request.args).pipe(
+        Effect.tapDefect((defect) =>
+          Effect.logError(`reform: ${options.label} '${options.name}' query defect`, defect),
+        ),
+        Effect.matchCause({
+          onSuccess: (value) => {
+            if (!disabledNow()) {
+              // `reuse`: share unchanged subtrees with the previous Success
+              // value, so a refetch that barely moved keeps identities stable.
+              const prev = store.get()
+              const shared =
+                options.reuse === true && prev._tag === 'Success'
+                  ? reuse(prev.value, value)
+                  : value
+              store.set(AsyncData.success(shared, false))
+              options.onSettled?.(request.generation)
+            }
+          },
+          onFailure: (cause) => {
+            const failure = Cause.failureOption(cause)
+            if (Option.isSome(failure) && !disabledNow()) {
+              store.set(AsyncData.error(failure.value, false))
+            }
+          },
+        }),
+      )
+
+    interface Request {
+      readonly args: InputsObject<Inputs>
+      readonly generation: number
+    }
+
+    // The driver. `'switch'` (default): each new request cancels the in-flight
+    // run — the same latest-wins semantics a `latest` channel gives procedures.
+    // `'trailing'`: a strictly sequential consumer that, on wake, drains every
+    // request that piled up during the flight and runs the LATEST one —
+    // "exactly one trailing run after settle" by construction. The trailing
+    // run's generation is the max drained (the latest request's), so it
+    // vouches for every request it conflated.
+    const trailing = options.coalesce === 'trailing'
+    const requests = yield* Queue.unbounded<Request>()
+    yield* Effect.forkScoped(
+      trailing
+        ? Effect.forever(
+            Effect.gen(function* () {
+              const first = yield* Queue.take(requests)
+              const queued = yield* Queue.takeAll(requests)
+              const request = Option.getOrElse(Chunk.last(queued), () => first)
+              // A disable that landed while the request waited: skip the run.
+              if (!disabledNow()) yield* runQuery(request)
+              // The settle may have written a stale-key result with
+              // `refetching: false`; if a newer request is already waiting,
+              // restore the syncing flag before the next take — both writes
+              // coalesce into one scheduler flush for subscribers.
+              const pending = yield* Queue.size(requests)
+              if (pending > 0 && !disabledNow()) yield* Effect.sync(markRefetching)
+            }),
+          )
+        : Stream.fromQueue(requests).pipe(
+            Stream.flatMap((request) => Stream.fromEffect(runQuery(request)), { switch: true }),
+            Stream.runDrain,
+          ),
+    )
+
+    const trigger = () => {
+      const args = sources.snapshot()
+      if (disabledNow(args)) {
+        // Switched off: show Idle and forget the key so re-enabling always re-runs.
+        MutableRef.set(lastKey, undefined)
+        store.set(AsyncData.idle)
+        return
+      }
+      const key = keyOf(args)
+      const previous = MutableRef.get(lastKey)
+      if (previous !== undefined && sameKey(key, previous)) return
+      MutableRef.set(lastKey, key)
+      markRefetching()
+      Queue.unsafeOffer(requests, { args, generation: nextGeneration() })
+    }
+    const unsubscribe = subscribeAll(trigger)
+    yield* Effect.addFinalizer(() => Effect.sync(unsubscribe))
+
+    // Kick off the first fetch unless the query starts disabled.
+    const initial = sources.snapshot()
+    if (!disabledNow(initial)) {
+      MutableRef.set(lastKey, keyOf(initial))
+      Queue.unsafeOffer(requests, { args: initial, generation: nextGeneration() })
+    }
+
+    return { store, requested: () => MutableRef.get(generation) }
+  })

package/src/internal/reuse.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from '@effect/vitest'
+import { Data, Schema as S } from 'effect'
+import { reuse } from './reuse'
+
+// The structural-sharing pass behind `reuse: true`: identities move only where
+// values moved, and the result is always value-equal to the fresh output.
+
+describe('reuse', () => {
+  it('returns the previous value when the next is deeply value-equal', () => {
+    const prev = { a: [1, 2, { b: 'x' }], c: { d: true } }
+    const next = { a: [1, 2, { b: 'x' }], c: { d: true } }
+    expect(reuse(prev, next)).toBe(prev)
+  })
+
+  it('keeps identity of unchanged array elements while replacing changed ones', () => {
+    const e0 = { id: 1, name: 'a' }
+    const e1 = { id: 2, name: 'b' }
+    const prev = [e0, e1]
+    const next = [{ id: 1, name: 'a' }, { id: 2, name: 'B' }]
+    const out = reuse(prev, next)
+    expect(out).not.toBe(prev)
+    expect(out[0]).toBe(e0)
+    expect(out[1]).not.toBe(e1)
+    expect(out[1]).toEqual({ id: 2, name: 'B' })
+  })
+
+  it('keeps identity of unchanged record subtrees', () => {
+    const left = { items: [1, 2, 3] }
+    const prev = { left, right: { items: [4] } }
+    const next = { left: { items: [1, 2, 3] }, right: { items: [4, 5] } }
+    const out = reuse(prev, next)
+    expect(out.left).toBe(left)
+    expect(out.right).not.toBe(prev.right)
+    expect(out).toEqual(next)
+  })
+
+  it('substitutes Equal-implementing instances by value equality', () => {
+    class Row extends S.Class<Row>('Row')({ id: S.Number, name: S.String }) {}
+    const prevRow = new Row({ id: 1, name: 'a' })
+    const prev = { rows: [prevRow] }
+    const next = { rows: [new Row({ id: 1, name: 'a' })] }
+    const out = reuse(prev, next)
+    expect(out).toBe(prev)
+
+    const tagged = Data.struct({ k: 'v' })
+    const out2 = reuse({ t: tagged }, { t: Data.struct({ k: 'v' }) })
+    expect(out2.t).toBe(tagged)
+  })
+
+  it('walks INTO a differing Schema class, keeping its unchanged children', () => {
+    class Row extends S.Class<Row>('Row')({ id: S.Number, name: S.String }) {}
+    class View extends S.Class<View>('View')({ title: S.String, rows: S.Array(Row) }) {}
+    const keep = new Row({ id: 1, name: 'a' })
+    const prev = new View({ title: 't', rows: [keep, new Row({ id: 2, name: 'b' })] })
+    const next = new View({ title: 't', rows: [new Row({ id: 1, name: 'a' }), new Row({ id: 2, name: 'B' })] })
+    const out = reuse(prev, next)
+    // The container changed (row 2 renamed) so a fresh View comes back — but it
+    // is still a View (prototype preserved) and the untouched row keeps its
+    // exact previous identity.
+    expect(out).not.toBe(prev)
+    expect(out).toBeInstanceOf(View)
+    expect(out.rows[0]).toBe(keep)
+    expect(out.rows[1]).not.toBe(prev.rows[1])
+    expect(out.rows[1]?.name).toBe('B')
+    expect(out).toStrictEqual(next)
+  })
+
+  it('compares Dates by instant (Effect Equal) and treats other class instances as opaque leaves', () => {
+    // Effect's `Equal.equals` compares Dates structurally: same instant ⇒ the
+    // previous identity is kept.
+    const prev = { at: new Date(0) }
+    const out = reuse(prev, { at: new Date(0) })
+    expect(out.at).toBe(prev.at)
+
+    // A class without Equal: never recursed into, the fresh leaf wins even
+    // when its fields look identical.
+    class Opaque {
+      readonly v: number
+      constructor(v: number) {
+        this.v = v
+      }
+    }
+    const nextOpaque = { o: new Opaque(1) }
+    const out2 = reuse({ o: new Opaque(1) }, nextOpaque)
+    expect(out2.o).toBe(nextOpaque.o)
+  })
+
+  it('returns next below the depth bound', () => {
+    type Nest = { readonly n?: Nest; readonly v: number }
+    const deep = (depth: number): Nest => (depth === 0 ? { v: 0 } : { v: depth, n: deep(depth - 1) })
+    const prev = deep(20)
+    const next = deep(20)
+    const out = reuse(prev, next)
+    // Value-equal throughout — shared down to the bound, fresh below it.
+    expect(out).toEqual(next)
+  })
+
+  it('is value-equal to next and mutates neither argument', () => {
+    const prev = { a: [{ x: 1 }], b: 'keep' }
+    const next = { a: [{ x: 2 }], b: 'keep' }
+    const prevCopy = structuredClone(prev)
+    const nextCopy = structuredClone(next)
+    const out = reuse(prev, next)
+    expect(out).toEqual(nextCopy)
+    expect(prev).toEqual(prevCopy)
+    expect(next).toEqual(nextCopy)
+  })
+
+  it('shares nothing when shapes diverge (added/removed keys)', () => {
+    const prev = { a: 1, b: 2 }
+    const next = { a: 1 }
+    const out = reuse<Record<string, number>>(prev, next)
+    expect(out).toEqual({ a: 1 })
+    expect(out).not.toBe(prev)
+  })
+})