@playfast/reform 0.0.1

package/dist/cjs/remote/remoteState.js

@@ -0,0 +1,307 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.live = exports.make = void 0;
+const effect_1 = require("effect");
+const asyncData_js_1 = require("../calc/asyncData.js");
+const Channel = __importStar(require("../channel/channel.js"));
+const definition_js_1 = require("../definition/definition.js");
+const Event = __importStar(require("../event/event.js"));
+const queryDriver_js_1 = require("../internal/queryDriver.js");
+const reuse_js_1 = require("../internal/reuse.js");
+const scheduler_js_1 = require("../internal/scheduler.js");
+const sources_js_1 = require("../internal/sources.js");
+const store_js_1 = require("../internal/store.js");
+const track_js_1 = require("../internal/track.js");
+const Reducer = __importStar(require("../reducer/reducer.js"));
+const bus_js_1 = require("../runtime/bus.js");
+const loop_js_1 = require("../runtime/loop.js");
+const State = __importStar(require("../state/state.js"));
+const token_js_1 = require("../state/token.js");
+// Intent payloads are typed by the definition's `Intents`, but `Intents` is an
+// open type parameter inside `make`/`live`, so the runtime schemas can only be
+// structural (`Schema.Unknown` in the intent slot). Event schemas are
+// reflective metadata — never decoded on the dispatch path — so the typed view
+// is granted here once (the `narrowStore`/`narrowHandled` style; `any`
+// short-circuits the schema's invariance, no value is cast).
+const looseSchema = (schema) => schema;
+/**
+ * Define a remote state: a query (like `AsyncCalc.make`) plus the intent
+ * events that mutate it. `yield* TheClass` reads the overlaid view;
+ * `TheClass.truth` / `TheClass.pending` / `TheClass.Failed` expose the rest of
+ * the surface. The query/send/apply logic is supplied by `RemoteState.live`.
+ */
+const make = (name, config) => {
+    const store = effect_1.Context.GenericTag(`reform/remoteState/${name}`);
+    const truthTag = effect_1.Context.GenericTag(`reform/remoteState/${name}/truth`);
+    const pendingTag = effect_1.Context.GenericTag(`reform/remoteState/${name}/pending`);
+    const gated = (0, queryDriver_js_1.gatedFlag)(config.alwaysOn);
+    const manifest = {
+        kind: 'RemoteState',
+        name,
+        output: config.output,
+        gated,
+        intents: config.intents.map((event) => event.tag),
+        ...(config.error !== undefined ? { error: config.error } : {}),
+    };
+    // Annotated consts so the template literal expressions keep their literal
+    // types (contextual typing) — the statics must match the interface exactly.
+    const truthName = `${name}/truth`;
+    const pendingName = `${name}/pending`;
+    const failedName = `${name}/Failed`;
+    const read = effect_1.Effect.flatMap(store, track_js_1.readTracked);
+    return (0, definition_js_1.yieldableClass)(read, {
+        manifest,
+        store,
+        name,
+        inputs: config.inputs,
+        intents: config.intents,
+        gated,
+        truth: new token_js_1.StateToken(truthName, truthTag),
+        pending: new token_js_1.StateToken(pendingName, pendingTag),
+        Failed: Event.make(failedName, looseSchema(effect_1.Schema.Struct({ intent: effect_1.Schema.Unknown, error: effect_1.Schema.Unknown }))),
+    });
+};
+exports.make = make;
+/**
+ * Wire a remote state: the query driver (truth), the overlay (visible view),
+ * the hidden queue reducer, the send procedure, and the settle link between
+ * them — one layer. Hidden names minted per call, namespaced by the remote
+ * state's name: events `…/Queued`/`…/Acked`/`…/Settled`/`…/Invalidated`, state
+ * `…/revision`, reducers `…/pending`/`…/revision`, procedure `…/send`, default
+ * channel `…/sends`.
+ */
+const live = (remote, config) => {
+    const name = remote.manifest.name;
+    const truthTag = remote.truth.store;
+    const pendingTag = remote.pending.store;
+    // The hidden event vocabulary. `Queued` carries the intent (the queue
+    // reducer's only source of it); `Acked`/`Settled` name the op; `Invalidated`
+    // bumps the hidden revision exactly like an `invalidateOn` event.
+    const Queued = Event.make(`${name}/Queued`, looseSchema(effect_1.Schema.Struct({ opId: effect_1.Schema.String, intent: effect_1.Schema.Unknown })));
+    const Acked = Event.make(`${name}/Acked`, effect_1.Schema.Struct({ opId: effect_1.Schema.String }));
+    const Settled = Event.make(`${name}/Settled`, effect_1.Schema.Struct({ opId: effect_1.Schema.String }));
+    const Invalidated = Event.make(`${name}/Invalidated`, effect_1.Schema.Struct({}));
+    // The hidden revision pair (the `invalidateOn` machinery, unconditional here:
+    // `Invalidated` always drives it; user `invalidateOn` events join the same fold).
+    const revisionState = State.make(`${name}/revision`, queryDriver_js_1.RevisionSchema);
+    const revisionReducer = Reducer.make(`${name}/revision`, {
+        states: [revisionState],
+        events: [Invalidated, ...(config.invalidateOn ?? [])],
+    });
+    // The settle link, keyed per live so two remote states never cross-resolve.
+    const linkTag = effect_1.Context.GenericTag(`reform/remoteState/${name}/link`);
+    // ── 1. Driver + link: the truth store and the generation bookkeeping. ──────
+    const driverLayer = effect_1.Layer.scopedContext(effect_1.Effect.gen(function* () {
+        // `disabled` is rejected at the type level for non-gated definitions
+        // (erased to `never` there); read it through a loose view for the runtime.
+        const cfg = config;
+        // Requirement-free read (`serviceOption`): the assembly below always
+        // provides the revision store alongside this driver.
+        const revision = effect_1.Option.getOrUndefined(yield* effect_1.Effect.serviceOption(revisionState.store));
+        const runtime = yield* effect_1.Effect.runtime();
+        // Settle waiters: a plain registry, not fibers parked per intent — so the
+        // settle path is independent of the user channel's policy (`latest`/
+        // `exclusive` lanes can't orphan a pending entry by cancelling its fiber).
+        const waiters = effect_1.MutableRef.make([]);
+        const onSettled = (generation) => {
+            const due = effect_1.MutableRef.get(waiters).filter((waiter) => waiter.waitFor <= generation);
+            if (due.length === 0)
+                return;
+            effect_1.MutableRef.update(waiters, (all) => all.filter((waiter) => waiter.waitFor > generation));
+            // Dispatch synchronously (`publish` only enqueues on the unbounded bus):
+            // the settle is enqueued in the same flush as the converged value write.
+            for (const waiter of due) {
+                effect_1.Runtime.runSync(runtime)((0, bus_js_1.publish)('Normal', Event.construct(Settled, { opId: waiter.opId })));
+            }
+        };
+        const driver = yield* (0, queryDriver_js_1.makeQueryDriver)({
+            name,
+            label: 'RemoteState',
+            gated: remote.gated,
+            inputs: remote.inputs,
+            query: cfg.query,
+            invalidateBy: cfg.invalidateBy,
+            disabled: cfg.disabled,
+            coalesce: cfg.coalesce,
+            reuse: cfg.reuse,
+            extraKey: revision === undefined
+                ? undefined
+                : {
+                    read: () => revision.getSnapshot(),
+                    subscribe: (listener) => revision.subscribe(listener),
+                },
+            onSettled,
+        });
+        const link = {
+            requested: driver.requested,
+            register: (opId, waitFor) => effect_1.MutableRef.update(waiters, (all) => [...all, { opId, waitFor }]),
+        };
+        return effect_1.Context.make(truthTag, (0, asyncData_js_1.narrowStore)(driver.store)).pipe(effect_1.Context.add(linkTag, link));
+    }));
+    // ── 2. Overlay: visible = pending.reduce(apply, truth). ────────────────────
+    const overlayLayer = effect_1.Layer.scoped(remote.store, effect_1.Effect.gen(function* () {
+        const scheduler = yield* scheduler_js_1.resolveScheduler;
+        // Widened so the arm dispatch below is a plain tag union (read-only view).
+        const feedStore = (0, asyncData_js_1.widenStore)(yield* truthTag);
+        const queueStore = yield* pendingTag;
+        const memo = effect_1.MutableRef.make(undefined);
+        const recompute = () => {
+            const feed = feedStore.getSnapshot();
+            const pending = queueStore.getSnapshot();
+            const key = [feed, pending];
+            const prev = effect_1.MutableRef.get(memo);
+            if (prev !== undefined && (0, sources_js_1.sameKey)(key, prev.key))
+                return prev.output;
+            // `apply` runs over every `Success` — including `refetching: true`, so
+            // queued intents stay visible while the server converges; the other
+            // arms pass through by reference.
+            const overlaid = feed._tag === 'Success'
+                ? asyncData_js_1.AsyncData.success(pending.reduce((value, entry) => config.apply(value, entry.intent), feed.value), feed.refetching)
+                : feed;
+            // With `reuse`, also reconcile consecutive overlay outputs: the fold
+            // rebuilds the value per recompute, so untouched subtrees would
+            // otherwise lose identity every time the queue moves.
+            const output = config.reuse === true &&
+                prev !== undefined &&
+                prev.output._tag === 'Success' &&
+                overlaid._tag === 'Success'
+                ? asyncData_js_1.AsyncData.success((0, reuse_js_1.reuse)(prev.output.value, overlaid.value), overlaid.refetching)
+                : overlaid;
+            effect_1.MutableRef.set(memo, { key, output });
+            return output;
+        };
+        const subscribe = (listener) => {
+            const offFeed = feedStore.subscribe(listener);
+            const offQueue = queueStore.subscribe(listener);
+            return () => {
+                offFeed();
+                offQueue();
+            };
+        };
+        const derived = (0, store_js_1.makeDerivedStore)(recompute, subscribe, scheduler);
+        yield* effect_1.Effect.addFinalizer(() => effect_1.Effect.sync(derived.unsubscribe));
+        return (0, asyncData_js_1.narrowStore)(derived.store);
+    }));
+    // ── 3. Queue reducer: the pending queue's SOLE writer. ─────────────────────
+    // Assembled directly against the registry rather than through `Reducer.live`,
+    // whose parameter types are conditionals TS keeps deferred while `Intents` is
+    // an open type parameter (user code instantiates the public surface
+    // concretely, so this is the one generic caller).
+    const queueReducerName = `${name}/pending`;
+    const queueHandles = new Set([Queued.tag, Acked.tag, Settled.tag]);
+    const foldQueue = (queue, event) => 
+    // `Queued` is the arm carrying the intent (the `undefined` guard is for the
+    // type only — every `Queued` carries one). An ack/settle for an id that is
+    // absent (or already confirmed) keeps the same reference — a true no-op.
+    event._tag === Queued.tag
+        ? event.intent === undefined
+            ? queue
+            : [...queue, { opId: event.opId, intent: event.intent, status: 'sending' }]
+        : event._tag === Acked.tag
+            ? queue.some((entry) => entry.opId === event.opId && entry.status === 'sending')
+                ? queue.map((entry) => entry.opId === event.opId ? { ...entry, status: 'confirmed' } : entry)
+                : queue
+            : queue.some((entry) => entry.opId === event.opId)
+                ? queue.filter((entry) => entry.opId !== event.opId)
+                : queue;
+    const queueReducerLayer = effect_1.Layer.scopedDiscard(effect_1.Effect.gen(function* () {
+        const reducers = yield* loop_js_1.Reducers;
+        if (reducers.entries.some((entry) => entry.name === queueReducerName)) {
+            yield* effect_1.Effect.logWarning(`reform: duplicate reducer name '${queueReducerName}' registered`);
+        }
+        const store = yield* pendingTag;
+        const entry = {
+            name: queueReducerName,
+            handles: queueHandles,
+            // The loop only invokes `apply` for events in `handles`; `narrowHandled`
+            // restores that typed view from the erased envelope.
+            apply: (event) => store.set(foldQueue(store.get(), (0, bus_js_1.narrowHandled)(event))),
+        };
+        yield* effect_1.Effect.acquireRelease(effect_1.Effect.sync(() => reducers.register(entry)), () => effect_1.Effect.sync(() => reducers.unregister(entry)));
+    }));
+    // ── 4. Send procedure: intent dispatch → deliver → ack/settle bookkeeping. ─
+    // Hand-assembled `ProcedureEntry` for the same deferred-conditional reason as
+    // the queue reducer (the `Procedure.live` internals, verbatim).
+    const channel = config.channel ?? Channel.make(`${name}/sends`, { policy: { _tag: 'merge' } });
+    const procedureName = `${name}/send`;
+    const sendHandles = new Set(remote.intents.map((event) => event.tag));
+    const sendProcedureLayer = effect_1.Layer.scopedDiscard(effect_1.Effect.gen(function* () {
+        const procedures = yield* Channel.Procedures;
+        if (procedures.entries.some((entry) => entry.name === procedureName)) {
+            yield* effect_1.Effect.logWarning(`reform: duplicate procedure name '${procedureName}' registered`);
+        }
+        const link = yield* linkTag;
+        // Snapshot the body's full context (Bus + the send's R2) so `run` is total.
+        const runtime = yield* effect_1.Effect.runtime();
+        const deliver = (intent) => effect_1.Effect.gen(function* () {
+            const opId = yield* effect_1.Effect.sync(() => crypto.randomUUID());
+            yield* Event.dispatch(Queued, { opId, intent });
+            const outcome = yield* config.send(intent).pipe(
+            // A defect in `send` is a bug, but it must not strand the entry:
+            // fold it into the failure arm so the intent settles and `Failed`
+            // fires (the channel would otherwise swallow it after logging).
+            effect_1.Effect.catchAllDefect((defect) => effect_1.Effect.fail(defect)), effect_1.Effect.either, 
+            // A cancelled send (a `latest`/`exclusive` user channel tearing the
+            // run down) settles too: the overlay reverts, and if the request
+            // did reach the server the next refetch shows it as truth.
+            effect_1.Effect.onInterrupt(() => Event.dispatch(Settled, { opId })));
+            yield* effect_1.Either.match(outcome, {
+                onLeft: (error) => effect_1.Effect.zipRight(Event.dispatch(remote.Failed, { intent, error }), Event.dispatch(Settled, { opId })),
+                onRight: () => 
+                // Register the waiter BEFORE the invalidation bump: `Invalidated`
+                // routes through the drain loop later, so the run it triggers is
+                // necessarily requested after `requested()` here — the waiter can
+                // never be satisfied by a refetch that predates the ack.
+                effect_1.Effect.sync(() => link.register(opId, link.requested() + 1)).pipe(effect_1.Effect.zipRight(Event.dispatch(Acked, { opId })), effect_1.Effect.zipRight(Event.dispatch(Invalidated, {}))),
+            });
+        });
+        const entry = {
+            name: procedureName,
+            channelName: channel.manifest.name,
+            handles: sendHandles,
+            run: (event) => effect_1.Effect.provide(deliver((0, bus_js_1.narrowHandled)(event)), runtime),
+        };
+        yield* effect_1.Effect.acquireRelease(effect_1.Effect.sync(() => procedures.register(entry)), () => effect_1.Effect.sync(() => procedures.unregister(entry)));
+    }));
+    // ── Assembly. ───────────────────────────────────────────────────────────────
+    // The pending store backs both the overlay and the queue reducer; the hidden
+    // revision store feeds both the driver (`extraKey`) and its reducer; the
+    // channel `.live` is idempotent by name+policy, so a user channel shared with
+    // other procedures wires up exactly once.
+    const pendingStoreLayer = effect_1.Layer.effect(pendingTag, effect_1.Effect.map(scheduler_js_1.resolveScheduler, (scheduler) => (0, store_js_1.makeStore)([], scheduler)));
+    return effect_1.Layer.mergeAll(overlayLayer, queueReducerLayer, Reducer.live(revisionReducer, queryDriver_js_1.bumpRevision), sendProcedureLayer, Channel.live(channel)).pipe(effect_1.Layer.provideMerge(driverLayer), effect_1.Layer.provide(State.live(revisionState, queryDriver_js_1.revisionZero)), effect_1.Layer.provideMerge(pendingStoreLayer));
+};
+exports.live = live;

package/dist/cjs/runtime/bus.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publish = exports.busLayer = exports.Bus = exports.narrowHandled = void 0;
+const effect_1 = require("effect");
+/**
+ * Re-narrow an erased `Tagged` envelope to a handler's declared event union. The
+ * loop and channels only route events whose tag is in a handler's `handles`, so
+ * at runtime the envelope IS one of those events; the registries store it as the
+ * generic `Tagged`, and this restores the typed view. The one documented home
+ * for that boundary cast, shared by `Reducer.live` and `Procedure.live`.
+ */
+const narrowHandled = (event) => event;
+exports.narrowHandled = narrowHandled;
+/** The single dispatch bus: an unbounded PubSub fanned out to the loop and procedures. */
+class Bus extends effect_1.Context.Tag('reform/Bus')() {
+}
+exports.Bus = Bus;
+// Unbounded so `publish` never suspends: UI triggers dispatch synchronously
+// (`Runtime.runSync`, no fiber fork per event), and an event storm can't apply
+// backpressure to the UI thread. The single drain loop empties the bus every
+// microtask, so it does not accumulate. Swap to `PubSub.dropping(N)` if bounded
+// memory is preferred over never dropping (publish stays synchronous either way).
+exports.busLayer = effect_1.Layer.scoped(Bus, effect_1.PubSub.unbounded());
+const publish = (priority, event) => effect_1.Effect.flatMap(Bus, (bus) => effect_1.PubSub.publish(bus, { priority, event }));
+exports.publish = publish;

package/dist/cjs/runtime/loop.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Engine = exports.reducersLayer = exports.Reducers = void 0;
+const effect_1 = require("effect");
+const channel_js_1 = require("../channel/channel.js");
+const scheduler_js_1 = require("../internal/scheduler.js");
+const bus_js_1 = require("./bus.js");
+class Reducers extends effect_1.Context.Tag('reform/Reducers')() {
+}
+exports.Reducers = Reducers;
+/** Drop an item from a `Map<string, Array>` bucket, pruning the key when it empties. */
+const dropFromBuckets = (map, key, item) => {
+    const bucket = map.get(key);
+    if (bucket === undefined)
+        return;
+    const next = bucket.filter((entry) => entry !== item);
+    if (next.length === 0)
+        map.delete(key);
+    else
+        map.set(key, next);
+};
+const makeReducerRegistry = () => {
+    const entries = [];
+    const byTag = new Map();
+    return {
+        entries,
+        byTag,
+        register: (entry) => {
+            entries.push(entry);
+            for (const tag of entry.handles) {
+                const bucket = byTag.get(tag);
+                if (bucket === undefined)
+                    byTag.set(tag, [entry]);
+                else
+                    bucket.push(entry);
+            }
+        },
+        unregister: (entry) => {
+            const index = entries.indexOf(entry);
+            if (index >= 0)
+                entries.splice(index, 1);
+            for (const tag of entry.handles)
+                dropFromBuckets(byTag, tag, entry);
+        },
+    };
+};
+exports.reducersLayer = effect_1.Layer.sync(Reducers, makeReducerRegistry);
+/** High before Normal; within a priority class, dispatch order is preserved. */
+const rank = (priority) => (priority === 'High' ? 0 : 1);
+// The single drain loop: one fiber that frame-batches the bus. Each tick it
+// harvests every event dispatched in that microtask, runs all matching reducers
+// in ONE synchronous pass (so the store notifier flushes once for the batch),
+// then routes each event to the channels its procedures run on.
+const drain = effect_1.Effect.gen(function* () {
+    const bus = yield* bus_js_1.Bus;
+    const reducers = yield* Reducers;
+    const { byName: channels } = yield* channel_js_1.Channels;
+    const procedures = yield* channel_js_1.Procedures;
+    const subscription = yield* effect_1.PubSub.subscribe(bus);
+    yield* effect_1.Effect.forkScoped(effect_1.Effect.forever(effect_1.Effect.gen(function* () {
+        // Block until the first event, then drain the rest of this tick.
+        const first = yield* effect_1.Queue.take(subscription);
+        const rest = yield* effect_1.Queue.takeAll(subscription);
+        const frame = [first, ...effect_1.Chunk.toArray(rest)];
+        // Stable priority order: High-dispatched (UI) events fold before
+        // Normal-dispatched (procedure follow-up) events in the same frame. A
+        // two-bucket partition does this in O(m) with no comparator — push order
+        // preserves intra-priority dispatch order — instead of sorting the frame.
+        const high = [];
+        const normal = [];
+        for (const envelope of frame) {
+            if (rank(envelope.priority) === 0)
+                high.push(envelope);
+            else
+                normal.push(envelope);
+        }
+        const ordered = high.concat(normal);
+        // One synchronous block: every reducer write for the frame coalesces into
+        // a single notification flush. Routing to channels happens here too, so
+        // procedure bodies (run later, off their channel fibers) see post-batch
+        // state. No `yield*` in between, or the flush could fire early.
+        const failures = [];
+        yield* effect_1.Effect.sync(() => {
+            for (const envelope of ordered) {
+                for (const reducer of reducers.byTag.get(envelope.event._tag) ?? []) {
+                    // Isolate each fold: a synchronous throw in one reducer must not
+                    // abandon the rest of the frame nor (via the `forever` below) kill
+                    // the drain fiber and freeze the whole app. Collect and log after.
+                    try {
+                        reducer.apply(envelope.event);
+                    }
+                    catch (error) {
+                        failures.push({ event: envelope.event, error });
+                    }
+                }
+            }
+            for (const envelope of ordered) {
+                // Offer to each DISTINCT channel once. Routing per-procedure would
+                // offer a shared channel multiple times for one event, and each offer
+                // re-runs every procedure on it — duplicate execution.
+                for (const channelName of procedures.channelsByTag.get(envelope.event._tag) ?? []) {
+                    channels.get(channelName)?.offer(envelope.event);
+                }
+            }
+        });
+        yield* effect_1.Effect.forEach(failures, (failure) => effect_1.Effect.logError(`reform: reducer threw handling '${failure.event._tag}'`, failure.error), { discard: true });
+    }).pipe(
+    // Belt-and-suspenders: even a defect outside the isolated fold (a bug in
+    // the loop itself) is logged and the tick restarts, so the bus never goes
+    // permanently deaf.
+    effect_1.Effect.catchAllCause((cause) => effect_1.Effect.logError('reform: drain tick crashed', cause)))));
+});
+/**
+ * The reform engine: provides the bus + reducer/channel/procedure registries +
+ * the per-runtime notification scheduler to the application and forks the single
+ * drain loop. Registration mutates the live collections, so reducers/procedures/
+ * channels merged alongside are picked up before the first dispatch (boot).
+ */
+exports.Engine = effect_1.Layer.scopedDiscard(drain).pipe(effect_1.Layer.provideMerge(effect_1.Layer.mergeAll(bus_js_1.busLayer, exports.reducersLayer, channel_js_1.channelsLayer, channel_js_1.proceduresLayer, scheduler_js_1.notificationsLayer)));

package/dist/cjs/scene/scene.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isScene = exports.seedScene = exports.scene = void 0;
+const effect_1 = require("effect");
+const seeds_js_1 = require("../internal/seeds.js");
+/**
+ * Define a scene — `scene(TodoApp, { provide: [makeTestApp(client, seeds)] })`.
+ * The composition's contract flows through `C`, so consumers stay typed.
+ */
+const scene = (composition, config) => ({
+    kind: 'Scene',
+    composition,
+    provide: config.provide,
+    ...(config.boot !== undefined ? { boot: config.boot } : {}),
+});
+exports.scene = scene;
+/**
+ * Overlay seed values onto a CLOSED scene — the tooling/test seam (dev-tool
+ * inspector overrides, proofs). Scenes stay closed for authors: this does not
+ * reopen `provide`, it wraps each layer with `Layer.locally(CurrentSeedOverrides,
+ * seeds)` so `State.live` boots matching stores from the override instead of
+ * the authored seed.
+ *
+ * Keys are state MEMBER NAMES as reflected in `manifest.states` (e.g. `count`),
+ * not group names. If two groups in one scene share a member name, both receive
+ * the override (documented limitation). Values are schema-validated at build:
+ * an invalid value silently falls back to the authored seed. `StateFamily`
+ * entries are not covered.
+ */
+const seedScene = (base, seeds) => Object.keys(seeds).length === 0
+    ? base
+    : { ...base, provide: base.provide.map(effect_1.Layer.locally(seeds_js_1.CurrentSeedOverrides, seeds)) };
+exports.seedScene = seedScene;
+/** Reflection guard: is this exported value a scene? */
+const isScene = (v) => typeof v === 'object' && v !== null && v.kind === 'Scene';
+exports.isScene = isScene;

package/dist/cjs/state/state.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.live = exports.make = void 0;
+const effect_1 = require("effect");
+const definition_js_1 = require("../definition/definition.js");
+const scheduler_js_1 = require("../internal/scheduler.js");
+const seeds_js_1 = require("../internal/seeds.js");
+const store_js_1 = require("../internal/store.js");
+const track_js_1 = require("../internal/track.js");
+/**
+ * Atomic reactive state. `State.make` is the *definition* (a reflectable
+ * manifest + an internal store tag); it carries no starting value — the seed is
+ * an implementation detail supplied at create-time by `State.live(state, seed)`.
+ * Composed into a `StateGroup` exactly as `@effect/rpc` composes rpcs.
+ */
+const make = (name, schema, options = {}) => {
+    const store = effect_1.Context.GenericTag(`reform/state/${name}`);
+    const manifest = {
+        kind: 'State',
+        name,
+        schema,
+        ...(options.title !== undefined ? { title: options.title } : {}),
+        ...(options.description !== undefined ? { description: options.description } : {}),
+    };
+    const read = effect_1.Effect.flatMap(store, track_js_1.readTracked);
+    return (0, definition_js_1.yieldableClass)(read, { manifest, store });
+};
+exports.make = make;
+/**
+ * Resolve the value a store should boot from: the ambient seed override when
+ * one is present (and valid) for this state's member name, else the authored
+ * `initial`. Reads `CurrentSeedOverrides` — empty outside the tooling seam
+ * (`Scene.seedScene`), so production wiring always boots from `initial`. An
+ * override is decoded against the state's schema; an invalid value silently
+ * falls back to `initial` — a half-typed override from the dev tool must never
+ * crash a preview.
+ */
+const resolveSeed = (state, initial) => effect_1.Effect.map(effect_1.FiberRef.get(seeds_js_1.CurrentSeedOverrides), (overrides) => state.manifest.name in overrides
+    ? effect_1.Option.getOrElse(effect_1.Schema.decodeUnknownOption(state.manifest.schema)(overrides[state.manifest.name]), () => initial)
+    : initial);
+/**
+ * Allocate a state's store, seeded with `initial` — `State.live(Feed, seed)`.
+ * The seed lives here (implementation), not on the definition, so the same
+ * definition can boot from different values in app vs. test wiring.
+ */
+const live = (state, initial) => effect_1.Layer.effect(state.store, effect_1.Effect.zipWith(scheduler_js_1.resolveScheduler, resolveSeed(state, initial), (scheduler, seed) => (0, store_js_1.makeStore)(seed, scheduler)));
+exports.live = live;

package/dist/cjs/state/stateFamily.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.live = exports.read = exports.make = exports.Tombstone = void 0;
+const effect_1 = require("effect");
+const definition_js_1 = require("../definition/definition.js");
+const scheduler_js_1 = require("../internal/scheduler.js");
+const store_js_1 = require("../internal/store.js");
+const track_js_1 = require("../internal/track.js");
+/**
+ * A reducer fold returns this to evict the key it folded over, instead of a new
+ * value. The loop drops the entry's store from the family, so a normalized
+ * collection (chat messages, search hits, transient rows) does not grow without
+ * bound — the one fix for the otherwise-unbounded per-key `Map`.
+ */
+exports.Tombstone = Symbol.for('reform/StateFamily/Tombstone');
+const makeFamilyStore = (seed, scheduler, options = {}) => {
+    const entries = new Map();
+    const evictWhenUnused = options.evictWhenUnused === true;
+    // Live subscriber count per key — maintained only when eviction is on.
+    const subscribers = new Map();
+    // Wrap a store's `subscribe` to ref-count, evicting the key when it falls idle.
+    // `get`/`set`/`getVersion` are delegated unchanged, so the loop writes and the
+    // host reads see the same cell; only subscribe/unsubscribe are instrumented.
+    const refCounted = (key, store) => ({
+        ...store,
+        subscribe: (listener) => {
+            subscribers.set(key, (subscribers.get(key) ?? 0) + 1);
+            const off = store.subscribe(listener);
+            const released = { done: false };
+            return () => {
+                if (released.done)
+                    return;
+                released.done = true;
+                off();
+                const remaining = (subscribers.get(key) ?? 1) - 1;
+                if (remaining > 0) {
+                    subscribers.set(key, remaining);
+                    return;
+                }
+                subscribers.delete(key);
+                queueMicrotask(() => {
+                    if ((subscribers.get(key) ?? 0) === 0)
+                        entries.delete(key);
+                });
+            };
+        },
+    });
+    return {
+        at: (key) => {
+            const existing = entries.get(key);
+            if (existing !== undefined)
+                return existing;
+            const base = (0, store_js_1.makeStore)(seed(key), scheduler);
+            const created = evictWhenUnused ? refCounted(key, base) : base;
+            entries.set(key, created);
+            return created;
+        },
+        forget: (key) => {
+            entries.delete(key);
+            subscribers.delete(key);
+        },
+        clear: () => {
+            entries.clear();
+            subscribers.clear();
+        },
+        size: () => entries.size,
+    };
+};
+/**
+ * Normalized keyed state: one logical State per key, backed by a single family
+ * store. Scales with the collection without re-rendering unrelated entries.
+ */
+const make = (name, key, value, options = {}) => {
+    const store = effect_1.Context.GenericTag(`reform/family/${name}`);
+    const manifest = {
+        kind: 'StateFamily',
+        name,
+        key,
+        value,
+        ...(options.title !== undefined ? { title: options.title } : {}),
+        ...(options.description !== undefined ? { description: options.description } : {}),
+    };
+    return (0, definition_js_1.definitionClass)({ manifest, store });
+};
+exports.make = make;
+/**
+ * Read one entry by key — `StateFamily.read(ItemUi, id)`. Inside a render it
+ * subscribes that key's slice; elsewhere it just snapshots (D5).
+ */
+const read = (family, key) => effect_1.Effect.flatMap(family.store, (fs) => (0, track_js_1.readTracked)(fs.at(key)));
+exports.read = read;
+/**
+ * Allocate a family's keyed store — `StateFamily.live(ItemUi, seed)`. The seed
+ * is a plain value or a factory; a factory receives the key, so a new entry can
+ * derive its starting value from its own id (`(id) => ({ ...blank, id }))`).
+ */
+const live = (family, initial, options = {}) => {
+    const seed = typeof initial === 'function' ? initial : () => initial;
+    return effect_1.Layer.effect(family.store, effect_1.Effect.map(scheduler_js_1.resolveScheduler, (scheduler) => makeFamilyStore(seed, scheduler, options)));
+};
+exports.live = live;