foldkit 0.157.0 → 0.158.0

package/dist/runtime/runtimeStatus.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The three flags that gate Message processing and rendering. The boot
+ * closure creates one per runtime and shares it with the units it builds,
+ * so the unit that sets a flag and the units that read it see one value.
+ * A plain mutable object rather than a Ref, because every reader and
+ * writer runs synchronously on the main thread.
+ */
+export type RuntimeStatus = {
+    isRuntimeDisposed: boolean;
+    isRenderingFrame: boolean;
+    isCrashed: boolean;
+};
+/** A fresh status: not disposed, not crashed, and no frame on the stack. */
+export declare const makeRuntimeStatus: () => RuntimeStatus;
+//# sourceMappingURL=runtimeStatus.d.ts.map

package/dist/runtime/runtimeStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeStatus.d.ts","sourceRoot":"","sources":["../../src/runtime/runtimeStatus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAM1B,iBAAiB,EAAE,OAAO,CAAA;IAO1B,gBAAgB,EAAE,OAAO,CAAA;IAIzB,SAAS,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAO,aAInC,CAAA"}

package/dist/runtime/runtimeStatus.js

@@ -0,0 +1,6 @@
+/** A fresh status: not disposed, not crashed, and no frame on the stack. */
+export const makeRuntimeStatus = () => ({
+    isRuntimeDisposed: false,
+    isRenderingFrame: false,
+    isCrashed: false,
+});

package/dist/runtime/slowPhase.d.ts

@@ -0,0 +1,82 @@
+import { Option, Schema } from 'effect';
+import type { Visibility } from './visibility.js';
+/** Context provided when view construction exceeds its configured time budget. */
+export type SlowViewContext<Model, Message> = Readonly<{
+    _tag: 'View';
+    model: Model;
+    message: Option.Option<Message>;
+    durationMs: number;
+    thresholdMs: number;
+}>;
+/** Context provided when update exceeds its configured time budget. */
+export type SlowUpdateContext<Model, Message> = Readonly<{
+    _tag: 'Update';
+    previousModel: Model;
+    nextModel: Model;
+    message: Message;
+    durationMs: number;
+    thresholdMs: number;
+}>;
+/** Context provided when DOM patching exceeds its configured time budget. */
+export type SlowPatchContext<Model, Message> = Readonly<{
+    _tag: 'Patch';
+    model: Model;
+    message: Option.Option<Message>;
+    durationMs: number;
+    thresholdMs: number;
+}>;
+/** Context provided when subscription dependency extraction exceeds its configured time budget. */
+export type SlowSubscriptionDependenciesContext<Model> = Readonly<{
+    _tag: 'SubscriptionDependencies';
+    subscriptionKey: string;
+    model: Model;
+    durationMs: number;
+    thresholdMs: number;
+}>;
+/** Tagged union of every slow-phase context passed to `slow.onSlow`. */
+export type SlowContext<Model, Message> = SlowViewContext<Model, Message> | SlowUpdateContext<Model, Message> | SlowPatchContext<Model, Message> | SlowSubscriptionDependenciesContext<Model>;
+/** Phase names measured by the slow warning runtime option. */
+export declare const SlowPhase: Schema.Literals<readonly ["Update", "View", "Patch", "SubscriptionDependencies"]>;
+export type SlowPhase = typeof SlowPhase.Type;
+/** Budget overrides for slow warning phases. Omitted fields use Foldkit defaults. */
+export type SlowThresholdOverrides = Readonly<{
+    Update?: number;
+    View?: number;
+    Patch?: number;
+    SubscriptionDependencies?: number;
+}>;
+/** One measured phase: its budget and the callback fired when it is exceeded. */
+export type ResolvedSlowPhaseConfig<Context> = Readonly<{
+    thresholdMs: number;
+    onSlow: (context: Context) => void;
+}>;
+type ResolvedSlowConfig<Model, Message> = Readonly<{
+    view: Option.Option<ResolvedSlowPhaseConfig<SlowViewContext<Model, Message>>>;
+    update: Option.Option<ResolvedSlowPhaseConfig<SlowUpdateContext<Model, Message>>>;
+    patch: Option.Option<ResolvedSlowPhaseConfig<SlowPatchContext<Model, Message>>>;
+    subscriptionDependencies: Option.Option<ResolvedSlowPhaseConfig<SlowSubscriptionDependenciesContext<Model>>>;
+}>;
+/**
+ * Slow-phase warning configuration.
+ *
+ * By default, all phases are enabled in development with Foldkit's default
+ * thresholds. Pass `false` to disable warnings entirely. Pass an object to
+ * refine those defaults.
+ *
+ * - `show`: `'Development'` (default) enables warnings only when Vite HMR is active. `'Always'` enables them in every environment.
+ * - `measuredPhases`: Phases to measure. Defaults to every slow warning phase.
+ * - `thresholdOverrides`: Per-phase budget overrides. Omitted fields keep defaults; overrides for unmeasured phases are ignored.
+ * - `onSlow`: Callback for every measured phase that exceeds its budget. Replaces Foldkit's default `console.warn`; Foldkit will not also warn for tags your callback ignores.
+ */
+export type SlowConfig<Model, Message> = false | Readonly<{
+    show?: Visibility;
+    measuredPhases?: ReadonlyArray<SlowPhase>;
+    thresholdOverrides?: SlowThresholdOverrides;
+    onSlow?: (context: SlowContext<Model, Message>) => void;
+}>;
+export declare const __resolveSlowConfig: <Model, Message>(slow: SlowConfig<Model, Message> | undefined, isSlowVisible: (show: Visibility) => boolean) => Option.Option<ResolvedSlowConfig<Model, Message>>;
+export declare const measureSlowPhase: <Context, Result>(maybeConfig: Option.Option<ResolvedSlowPhaseConfig<Context>>, run: () => Result) => readonly [Result, Option.Option<number>];
+export declare const reportSlowPhase: <Context>(maybeConfig: Option.Option<ResolvedSlowPhaseConfig<Context>>, maybeDurationMs: Option.Option<number>, makeContext: (durationMs: number, thresholdMs: number) => Context) => void;
+export declare const defaultSlowCallback: (context: SlowContext<unknown, unknown>) => void;
+export {};
+//# sourceMappingURL=slowPhase.d.ts.map

package/dist/runtime/slowPhase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slowPhase.d.ts","sourceRoot":"","sources":["../../src/runtime/slowPhase.ts"],"names":[],"mappings":"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"}

package/dist/runtime/slowPhase.js

@@ -0,0 +1,83 @@
+import { Array, Match, Option, Predicate, Record, Schema, pipe } from 'effect';
+/** Phase names measured by the slow warning runtime option. */
+export const SlowPhase = Schema.Literals([
+    'Update',
+    'View',
+    'Patch',
+    'SubscriptionDependencies',
+]);
+const DEFAULT_SLOW_SHOW = 'Development';
+const DEFAULT_SLOW_VIEW_THRESHOLD_MS = 16;
+const DEFAULT_SLOW_UPDATE_THRESHOLD_MS = 4;
+const DEFAULT_SLOW_PATCH_THRESHOLD_MS = 8;
+const DEFAULT_SLOW_SUBSCRIPTION_DEPENDENCIES_THRESHOLD_MS = 2;
+const ALL_SLOW_PHASES = [
+    'Update',
+    'View',
+    'Patch',
+    'SubscriptionDependencies',
+];
+const resolveSlowPhase = (isMeasured, thresholdMs, onSlow) => Option.liftPredicate({
+    thresholdMs,
+    onSlow,
+}, () => isMeasured);
+export const __resolveSlowConfig = (slow, isSlowVisible) => {
+    const maybeSlowConfig = Match.value(slow).pipe(Match.withReturnType(), Match.when(false, () => Option.none()), Match.when(Predicate.isUndefined, () => Option.some({})), Match.orElse(config => Option.some(config)));
+    return pipe(maybeSlowConfig, Option.filter(config => isSlowVisible(config.show ?? DEFAULT_SLOW_SHOW)), Option.map(config => {
+        const onSlow = config.onSlow ?? defaultSlowCallback;
+        const measuredPhases = config.measuredPhases ?? ALL_SLOW_PHASES;
+        const isPhaseMeasured = (phase) => Array.contains(measuredPhases, phase);
+        return {
+            view: resolveSlowPhase(isPhaseMeasured('View'), config.thresholdOverrides?.View ?? DEFAULT_SLOW_VIEW_THRESHOLD_MS, onSlow),
+            update: resolveSlowPhase(isPhaseMeasured('Update'), config.thresholdOverrides?.Update ?? DEFAULT_SLOW_UPDATE_THRESHOLD_MS, onSlow),
+            patch: resolveSlowPhase(isPhaseMeasured('Patch'), config.thresholdOverrides?.Patch ?? DEFAULT_SLOW_PATCH_THRESHOLD_MS, onSlow),
+            subscriptionDependencies: resolveSlowPhase(isPhaseMeasured('SubscriptionDependencies'), config.thresholdOverrides?.SubscriptionDependencies ??
+                DEFAULT_SLOW_SUBSCRIPTION_DEPENDENCIES_THRESHOLD_MS, onSlow),
+        };
+    }));
+};
+export const measureSlowPhase = (maybeConfig, run) => {
+    if (Option.isSome(maybeConfig)) {
+        const start = performance.now();
+        const result = run();
+        return [result, Option.some(performance.now() - start)];
+    }
+    else {
+        return [run(), Option.none()];
+    }
+};
+export const reportSlowPhase = (maybeConfig, maybeDurationMs, makeContext) => {
+    if (Option.isSome(maybeConfig)) {
+        const { thresholdMs, onSlow } = maybeConfig.value;
+        const maybeExceededDuration = Option.filter(maybeDurationMs, durationMs => durationMs > thresholdMs);
+        if (Option.isSome(maybeExceededDuration)) {
+            onSlow(makeContext(maybeExceededDuration.value, thresholdMs));
+        }
+    }
+};
+const messageTag = (rawMessage) => pipe(rawMessage, Option.liftPredicate(Predicate.isObject), Option.flatMap(Record.get('_tag')), Option.match({
+    onNone: () => 'unknown',
+    onSome: String,
+}));
+const optionMessageTrigger = (maybeMessage) => Option.match(maybeMessage, {
+    onNone: () => 'init',
+    onSome: messageTag,
+});
+const TUNING_HINT = 'Set slow.thresholdOverrides to change budgets or pass slow: false to disable warnings.';
+export const defaultSlowCallback = (context) => {
+    const { durationMs, thresholdMs: budget } = context;
+    const duration = durationMs.toFixed(1);
+    const summary = Match.value(context).pipe(Match.tagsExhaustive({
+        View: ({ message }) => `Slow view: ${duration}ms (budget: ${budget}ms), triggered by ${optionMessageTrigger(message)}. Keep render-only work in the view path and memoize expensive subtrees with createLazy or createKeyedLazy.`,
+        Update: ({ message }) => `Slow update: ${duration}ms (budget: ${budget}ms), triggered by ${messageTag(message)}. Inspect the triggering Message branch; move render-only derivations to memoized views and keep update focused on state transitions.`,
+        Patch: ({ message }) => `Slow patch: ${duration}ms (budget: ${budget}ms), triggered by ${optionMessageTrigger(message)}. Key mapped lists by stable ids, split large views, or memoize stable subtrees with createLazy.`,
+        SubscriptionDependencies: ({ subscriptionKey }) => `Slow subscription dependencies: ${duration}ms (budget: ${budget}ms) for subscription "${subscriptionKey}". Keep modelToDependencies a cheap projection from modeled fields; avoid scans, sorting, serialization, and large dependency objects.`,
+    }));
+    const maybeRawMessage = Match.value(context).pipe(Match.withReturnType(), Match.tagsExhaustive({
+        Update: ({ message }) => Option.some(message),
+        View: ({ message }) => message,
+        Patch: ({ message }) => message,
+        SubscriptionDependencies: () => Option.none(),
+    }));
+    console.warn(`[foldkit] ${summary} ${TUNING_HINT}`, context, ...Option.toArray(maybeRawMessage));
+};

package/dist/runtime/start.d.ts

@@ -0,0 +1,96 @@
+import { Effect } from 'effect';
+import type { Ports } from '../port/index.js';
+import { type EmbedHandle } from './hostConnector.js';
+import type { BootMode } from './hydrationHandoff.js';
+import { type MakeRuntimeReturn } from './runtime.js';
+/** Client-only startup input for an application that declares Flags. Pass it
+ *  to `run` or `embed`; `hydrate` instead decodes the exact Flags value
+ *  embedded by the server render.
+ */
+export type RunOptions<Flags, Resources = never> = Readonly<{
+    flags: Effect.Effect<Flags, never, Resources>;
+}>;
+type RuntimeProgram = Readonly<{
+    runtimeId: string;
+    start: (hmrModel?: unknown) => Effect.Effect<void>;
+    ports: Ports | undefined;
+}>;
+/** Starts a program Effect with explicit boot inputs for runtime tests.
+ * @internal */
+export declare const __startProgram: (program: RuntimeProgram, hmrModel: unknown, bootMode: BootMode, flags?: Effect.Effect<unknown, never, any>, buildId?: string) => Effect.Effect<void>;
+/** Starts a Foldkit runtime that owns the page for the page's whole lifetime,
+ *  with HMR support for development. The first render builds the DOM fresh in
+ *  the container, replacing whatever is there. On a server-rendered page use
+ *  `hydrate` instead, which adopts the existing DOM. To start a runtime under a
+ *  host-controlled lifecycle, use `embed`. */
+export declare function run<P extends Ports | undefined, Resources, Kind extends 'Application' | 'Element'>(program: MakeRuntimeReturn<P, void, Resources, Kind>): void;
+export declare function run<P extends Ports | undefined, Flags, Resources, Kind extends 'Application' | 'Element'>(program: MakeRuntimeReturn<P, Flags, Resources, Kind>, options: RunOptions<Flags, Resources>): void;
+/** Options for {@link hydrate}. */
+export type HydrateOptions = Readonly<{
+    /**
+     * The deployment this client belongs to, compared against the id the server
+     * stamped on the root before the Flags payload text is accessed or decoded,
+     * so a page from a different deployment stops startup rather than handing its
+     * Flags to this build. Required, and must be non-empty: an absent id would
+     * equal the absent marker on a page served before build ids existed.
+     *
+     * Pass `import.meta.env.FOLDKIT_BUILD_ID`, which `@foldkit/vite-plugin` fills
+     * from its `buildId` option or the `FOLDKIT_BUILD_ID` environment variable,
+     * the same value the server entry passes to `renderToString`.
+     */
+    buildId: string;
+}>;
+/** Starts a Foldkit runtime by adopting a server-rendered DOM in place instead
+ *  of building it fresh. Use this as the client entry for a page served by
+ *  `renderToString`: the first render attaches to the stamped root, keeps the
+ *  existing nodes, and reconstructs the Model from the Flags the server
+ *  embedded. The handoff is strict: a missing server root, an empty or
+ *  duplicated root stamp, more than one stamped root, a requested root outside
+ *  the document body light DOM, a missing Flags payload, an undecodable
+ *  payload, or a page from another deployment terminates startup. Every one of
+ *  those contains the page first:
+ *  the document's body is marked `inert` and a nondismissable modal shield is
+ *  opened above existing top-layer content, so pointer and physical keyboard
+ *  input do not activate same-document native links, forms, or controls.
+ *  Containment leaves author-owned dialogs open without calling `close` or
+ *  dispatching `cancel`.
+ *  Nothing is moved, so no custom element reconnects and no frame reloads.
+ *  This is not a script, event, or embedded-document sandbox: existing
+ *  capture-phase handlers, browser-generated top-layer events, timers, and
+ *  stale scripts can still run. Controls in embedded documents can still
+ *  receive input if stale code focuses them. Stale code can also open newer
+ *  top-layer UI. Use `run` in a separate client-only entry when the page should
+ *  boot without server output.
+ *
+ * @experimental Server rendering and hydration are experimental while their
+ * contracts settle. */
+export declare const hydrate: <P extends Ports | undefined, Flags, Resources>(program: MakeRuntimeReturn<P, Flags, Resources, 'Application'>, options: HydrateOptions) => void;
+/**
+ * Starts a Foldkit runtime under a host-controlled lifecycle and returns an
+ * `EmbedHandle`. This is the entry point for embedding a Foldkit app inside
+ * another application: the host pushes values in through the handle's inbound
+ * Ports, listens to outbound Ports, and calls `dispose` when it unmounts the
+ * app. The host never touches the Model or dispatches Messages directly; the
+ * Schema-typed Ports are the whole boundary.
+ *
+ * Works with programs from both `makeApplication` and `makeElement`; for a
+ * widget on a page the host owns, `makeElement` is the natural fit.
+ *
+ * A program can be embedded once at a time (it owns one container). After
+ * `dispose`, the same container can be embedded again with a fresh program.
+ *
+ * ```ts
+ * const handle = Runtime.embed(element)
+ *
+ * handle.ports.stepChanged.send(5)
+ * const unsubscribe = handle.ports.countChanged.subscribe(count => {
+ *   console.log(count)
+ * })
+ *
+ * handle.dispose()
+ * ```
+ */
+export declare function embed<P extends Ports | undefined = undefined, Resources = never, Kind extends 'Application' | 'Element' = 'Application' | 'Element'>(program: MakeRuntimeReturn<P, void, Resources, Kind>): EmbedHandle<P>;
+export declare function embed<P extends Ports | undefined, Flags, Resources, Kind extends 'Application' | 'Element'>(program: MakeRuntimeReturn<P, Flags, Resources, Kind>, options: RunOptions<Flags, Resources>): EmbedHandle<P>;
+export {};
+//# sourceMappingURL=start.d.ts.map

package/dist/runtime/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/runtime/start.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EAOP,MAAM,QAAQ,CAAA;AAEf,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAG7C,OAAO,EACL,KAAK,WAAW,EAGjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,cAAc,CAAA;AAEvE;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,IAAI,QAAQ,CAAC;IAC1D,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;CAC9C,CAAC,CAAA;AAEF,KAAK,cAAc,GAAG,QAAQ,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAClD,KAAK,EAAE,KAAK,GAAG,SAAS,CAAA;CACzB,CAAC,CAAA;AAEF;eACe;AACf,eAAO,MAAM,cAAc,YAChB,cAAc,YACb,OAAO,YACP,QAAQ,UACV,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,YAChC,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAqBpB,CAAA;AA6BD;;;;8CAI8C;AAC9C,wBAAgB,GAAG,CACjB,CAAC,SAAS,KAAK,GAAG,SAAS,EAC3B,SAAS,EACT,IAAI,SAAS,aAAa,GAAG,SAAS,EACtC,OAAO,EAAE,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,IAAI,CAAA;AAC7D,wBAAgB,GAAG,CACjB,CAAC,SAAS,KAAK,GAAG,SAAS,EAC3B,KAAK,EACL,SAAS,EACT,IAAI,SAAS,aAAa,GAAG,SAAS,EAEtC,OAAO,EAAE,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EACrD,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,GACpC,IAAI,CAAA;AAQP,mCAAmC;AACnC,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC;;;;;;;;;;OAUG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;uBAuBuB;AACvB,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,KAAK,GAAG,SAAS,EAAE,KAAK,EAAE,SAAS,WAC1D,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,CAAC,WACrD,cAAc,KACtB,IAEF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CACnB,CAAC,SAAS,KAAK,GAAG,SAAS,GAAG,SAAS,EACvC,SAAS,GAAG,KAAK,EACjB,IAAI,SAAS,aAAa,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,EAClE,OAAO,EAAE,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;AACvE,wBAAgB,KAAK,CACnB,CAAC,SAAS,KAAK,GAAG,SAAS,EAC3B,KAAK,EACL,SAAS,EACT,IAAI,SAAS,aAAa,GAAG,SAAS,EAEtC,OAAO,EAAE,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EACrD,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,GACpC,WAAW,CAAC,CAAC,CAAC,CAAA"}

package/dist/runtime/start.js

@@ -0,0 +1,99 @@
+import { Effect, Fiber, Function, Option, Predicate, Runtime, pipe, } from 'effect';
+import { provideBrowserScheduler } from './browserScheduler.js';
+import { resolveHmrModel } from './hmrModelBridge.js';
+import { buildPortHandles, makeHostConnector, } from './hostConnector.js';
+import { runtimeInternals } from './runtime.js';
+/** Starts a program Effect with explicit boot inputs for runtime tests.
+ * @internal */
+export const __startProgram = (program, hmrModel, bootMode, flags, buildId) => {
+    const internals = runtimeInternals.get(program);
+    if (Predicate.isUndefined(internals)) {
+        return Effect.die(new Error('[foldkit] Runtime boot expects a program created by ' +
+            'makeApplication or makeElement.'));
+    }
+    if (bootMode === 'Hydrate' && internals.kind !== 'Application') {
+        return Effect.die(new Error('[foldkit] Runtime.hydrate expects a program created by ' +
+            'makeApplication.'));
+    }
+    return internals.startWith(Option.none(), hmrModel, bootMode, flags, buildId);
+};
+// NOTE: deliberately not `BrowserRuntime.runMain`, which interrupts the
+// runtime on `beforeunload`. `beforeunload` is a question, not a commitment:
+// the browser also fires it for a click on a download link, for a navigation
+// the user cancels, and when freezing the page into the back/forward cache.
+// The document survives all three, but the interrupt finalizer has already
+// put the container element back empty, so the page is left alive with no app
+// in it. A page-owning runtime gains nothing from tearing itself down while
+// the document is on its way out, so it starts with no page-lifecycle
+// interrupt at all and lets the document take the runtime with it. Error
+// reporting and the keep-alive interval come from `makeRunMain` either way.
+const runMainWithoutUnloadInterrupt = Runtime.makeRunMain(Function.constVoid);
+const startProgram = (program, bootMode, flags, buildId) => {
+    runMainWithoutUnloadInterrupt(provideBrowserScheduler(Effect.flatMap(resolveHmrModel(program.runtimeId), hmrModel => __startProgram(program, hmrModel, bootMode, flags, buildId))));
+};
+export function run(program, options) {
+    startProgram(program, 'Fresh', options?.flags);
+}
+/** Starts a Foldkit runtime by adopting a server-rendered DOM in place instead
+ *  of building it fresh. Use this as the client entry for a page served by
+ *  `renderToString`: the first render attaches to the stamped root, keeps the
+ *  existing nodes, and reconstructs the Model from the Flags the server
+ *  embedded. The handoff is strict: a missing server root, an empty or
+ *  duplicated root stamp, more than one stamped root, a requested root outside
+ *  the document body light DOM, a missing Flags payload, an undecodable
+ *  payload, or a page from another deployment terminates startup. Every one of
+ *  those contains the page first:
+ *  the document's body is marked `inert` and a nondismissable modal shield is
+ *  opened above existing top-layer content, so pointer and physical keyboard
+ *  input do not activate same-document native links, forms, or controls.
+ *  Containment leaves author-owned dialogs open without calling `close` or
+ *  dispatching `cancel`.
+ *  Nothing is moved, so no custom element reconnects and no frame reloads.
+ *  This is not a script, event, or embedded-document sandbox: existing
+ *  capture-phase handlers, browser-generated top-layer events, timers, and
+ *  stale scripts can still run. Controls in embedded documents can still
+ *  receive input if stale code focuses them. Stale code can also open newer
+ *  top-layer UI. Use `run` in a separate client-only entry when the page should
+ *  boot without server output.
+ *
+ * @experimental Server rendering and hydration are experimental while their
+ * contracts settle. */
+export const hydrate = (program, options) => {
+    startProgram(program, 'Hydrate', undefined, options?.buildId);
+};
+export function embed(program, options) {
+    const internals = runtimeInternals.get(program);
+    if (Predicate.isUndefined(internals)) {
+        throw new Error('[foldkit] embed expects a program created by makeApplication or makeElement.');
+    }
+    if (internals.isEmbedActive) {
+        throw new Error('[foldkit] This program is already embedded. Dispose the existing ' +
+            'handle first, or create a separate program: each program owns one ' +
+            'container.');
+    }
+    internals.isEmbedActive = true;
+    const connector = makeHostConnector();
+    // NOTE: a dispose immediately followed by a fresh embed (React strict mode
+    // runs effects exactly that way) must not start the new runtime while the
+    // old one is still tearing down: the teardown finalizer is what puts the
+    // container element back in the DOM. Awaiting the previous fiber's exit
+    // sequences the two.
+    const startEffect = pipe(Option.match(internals.maybeActiveFiber, {
+        onNone: () => Effect.void,
+        onSome: previousFiber => Effect.asVoid(Fiber.await(previousFiber)),
+    }), Effect.andThen(resolveHmrModel(program.runtimeId)), Effect.flatMap(hmrModel => internals.startWith(Option.some(connector), hmrModel, 'Fresh', options?.flags)));
+    const fiber = Effect.runFork(provideBrowserScheduler(startEffect));
+    internals.maybeActiveFiber = Option.some(fiber);
+    let isHandleDisposed = false;
+    const dispose = () => {
+        if (isHandleDisposed) {
+            return;
+        }
+        isHandleDisposed = true;
+        connector.dispose();
+        internals.isEmbedActive = false;
+        Effect.runFork(Fiber.interrupt(fiber));
+    };
+    const ports = buildPortHandles(program.ports, connector);
+    return { ports, dispose };
+}

package/dist/runtime/subscriptionFibers.d.ts

@@ -0,0 +1,21 @@
+import { Cause, Effect, Option, PubSub, type Scope } from 'effect';
+import type { Subscriptions } from '../subscription/subscription.js';
+import { type ResolvedSlowPhaseConfig, type SlowSubscriptionDependenciesContext } from './slowPhase.js';
+/**
+ * Forks one fiber per Subscription into the runtime scope. Each fiber
+ * derives the Subscription's dependencies from every Model, restarts its
+ * stream when they change under its equivalence, and feeds the Messages
+ * the stream emits into the queue. A defect anywhere in that pipeline
+ * crashes the runtime instead of dying silently in the fiber.
+ */
+export declare const forkSubscriptionFibers: <Model, Message, Services>({ subscriptions, initModel, modelPubSub, runtimeScope, maybeSlowSubscriptionDependencies, enqueueMessageEffect, provideAllResources, crashWith, }: Readonly<{
+    subscriptions: Subscriptions<Model, Message, Services>;
+    initModel: Model;
+    modelPubSub: PubSub.PubSub<Model>;
+    runtimeScope: Scope.Scope;
+    maybeSlowSubscriptionDependencies: Option.Option<ResolvedSlowPhaseConfig<SlowSubscriptionDependenciesContext<Model>>>;
+    enqueueMessageEffect: (message: Message) => Effect.Effect<void>;
+    provideAllResources: <A>(effect: Effect.Effect<A, never, Services>) => Effect.Effect<A>;
+    crashWith: (cause: Cause.Cause<never>, maybeMessage: Option.Option<Message>) => Effect.Effect<void>;
+}>) => Effect.Effect<void>;
+//# sourceMappingURL=subscriptionFibers.d.ts.map

package/dist/runtime/subscriptionFibers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptionFibers.d.ts","sourceRoot":"","sources":["../../src/runtime/subscriptionFibers.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,MAAM,EACN,MAAM,EACN,MAAM,EAIN,KAAK,KAAK,EAGX,MAAM,QAAQ,CAAA;AAEf,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mCAAmC,EAGzC,MAAM,gBAAgB,CAAA;AAEvB;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,KAAK,EAAE,OAAO,EAAE,QAAQ,qJAS5D,QAAQ,CAAC;IACV,aAAa,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;IACtD,SAAS,EAAE,KAAK,CAAA;IAChB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACjC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAA;IACzB,iCAAiC,EAAE,MAAM,CAAC,MAAM,CAC9C,uBAAuB,CAAC,mCAAmC,CAAC,KAAK,CAAC,CAAC,CACpE,CAAA;IACD,oBAAoB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC/D,mBAAmB,EAAE,CAAC,CAAC,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KACtC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACrB,SAAS,EAAE,CACT,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EACzB,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KACjC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CACzB,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CA8FpB,CAAA"}

package/dist/runtime/subscriptionFibers.js

@@ -0,0 +1,47 @@
+import { Effect, Option, Record, Ref, Schema, Stream, pipe, } from 'effect';
+import { measureSlowPhase, reportSlowPhase, } from './slowPhase.js';
+/**
+ * Forks one fiber per Subscription into the runtime scope. Each fiber
+ * derives the Subscription's dependencies from every Model, restarts its
+ * stream when they change under its equivalence, and feeds the Messages
+ * the stream emits into the queue. A defect anywhere in that pipeline
+ * crashes the runtime instead of dying silently in the fiber.
+ */
+export const forkSubscriptionFibers = ({ subscriptions, initModel, modelPubSub, runtimeScope, maybeSlowSubscriptionDependencies, enqueueMessageEffect, provideAllResources, crashWith, }) => pipe(subscriptions, Record.toEntries, Effect.forEach(([key, { dependenciesSchema, modelToDependencies, keepAliveEquivalence, dependenciesToStream, },]) => Effect.gen(function* () {
+    const equivalence = keepAliveEquivalence ?? Schema.toEquivalence(dependenciesSchema);
+    const [initDependencies, maybeInitDependenciesDuration] = measureSlowPhase(maybeSlowSubscriptionDependencies, () => modelToDependencies(initModel));
+    reportSlowPhase(maybeSlowSubscriptionDependencies, maybeInitDependenciesDuration, (durationMs, thresholdMs) => ({
+        _tag: 'SubscriptionDependencies',
+        subscriptionKey: key,
+        model: initModel,
+        durationMs,
+        thresholdMs,
+    }));
+    const latestDependenciesRef = yield* Ref.make(initDependencies);
+    const modelChangesStream = Stream.fromPubSub(modelPubSub).pipe(
+    // NOTE: Ref.set runs upstream of Stream.changesWith on
+    // every model change, so readDependencies() returns
+    // current values even when the equivalence filter
+    // doesn't emit. Moving this into a tap after
+    // changesWith would silently break subscribers whose
+    // dependencies are equivalence-stable across model
+    // changes.
+    Stream.mapEffect(model => Effect.gen(function* () {
+        const [dependencies, maybeDependenciesDuration] = measureSlowPhase(maybeSlowSubscriptionDependencies, () => modelToDependencies(model));
+        reportSlowPhase(maybeSlowSubscriptionDependencies, maybeDependenciesDuration, (durationMs, thresholdMs) => ({
+            _tag: 'SubscriptionDependencies',
+            subscriptionKey: key,
+            model,
+            durationMs,
+            thresholdMs,
+        }));
+        yield* Ref.set(latestDependenciesRef, dependencies);
+        return dependencies;
+    })));
+    yield* Effect.forkIn(runtimeScope)(Stream.concat(Stream.make(initDependencies), modelChangesStream).pipe(Stream.changesWith(equivalence), Stream.switchMap(dependencies => dependenciesToStream(dependencies, () => Ref.getUnsafe(latestDependenciesRef))), Stream.runForEach(message => 
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+    enqueueMessageEffect(message)), provideAllResources, Effect.catchCause(cause => crashWith(cause, Option.none()))));
+}), {
+    concurrency: 'unbounded',
+    discard: true,
+}));

package/dist/runtime/visibility.d.ts

@@ -0,0 +1,8 @@
+/** Controls when a feature is shown. */
+export type Visibility = 'Development' | 'Always';
+/** Whether a feature configured with `show` is enabled. `'Always'` enables it
+ *  everywhere. `'Development'` enables it only when `isDevelopment` is true.
+ *  Callers pass whether Vite HMR is active, and DevTools also requires a
+ *  top-level window. */
+export declare const isVisible: (show: Visibility, isDevelopment: boolean) => boolean;
+//# sourceMappingURL=visibility.d.ts.map

package/dist/runtime/visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility.d.ts","sourceRoot":"","sources":["../../src/runtime/visibility.ts"],"names":[],"mappings":"AAEA,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAA;AAEjD;;;wBAGwB;AACxB,eAAO,MAAM,SAAS,SAAU,UAAU,iBAAiB,OAAO,KAAG,OAKlE,CAAA"}

package/dist/runtime/visibility.js

@@ -0,0 +1,6 @@
+import { Match } from 'effect';
+/** Whether a feature configured with `show` is enabled. `'Always'` enables it
+ *  everywhere. `'Development'` enables it only when `isDevelopment` is true.
+ *  Callers pass whether Vite HMR is active, and DevTools also requires a
+ *  top-level window. */
+export const isVisible = (show, isDevelopment) => Match.value(show).pipe(Match.when('Always', () => true), Match.when('Development', () => isDevelopment), Match.exhaustive);

package/dist/test/scene.js

@@ -4,7 +4,7 @@ import { kebabToPascal } from '../customElement/index.js';
 import { serializedStylePropertyName } from '../domReflection.js';
 import { FOLDKIT_MOUNT_KEY, FileHandlerSymbol, __clearRuntime as clearHtmlRuntime, __htmlBuilder as htmlBuilderFor, __setRuntime as setHtmlRuntime, } from '../html/index.js';
 import { MountTracker } from '../mount/index.js';
-import { Dispatch } from '../runtime/index.js';
+import { Dispatch } from '../runtime/dispatch.js';
 import { assertAllCommandsResolved, assertAllMountsResolved, assertAllUnmountsAcknowledged, assertExactCommands, assertExactMounts, assertHasCommands, assertHasMounts, assertNoUnacknowledgedUnmounts, assertNoUnresolvedCommands, assertNoUnresolvedMounts, assertResolveUnambiguous, assertZeroCommands, assertZeroMounts, formatCommand, formatMatcher, formatMountList, formatMountMatcher, mountMatches, resolveAllExactInternal, resolveAllInternal, resolveByMatcher, resolveMountByMatcher, } from './internal.js';
 import { accessibleDescription, accessibleName, ancestorsOf, attr, isHidden, resolveTarget, selector, textContent, within, } from './query.js';
 import { allAltText, allDisplayValue, allLabel, allPlaceholder, allRole, allSelector, allTestId, allText, allTitle, } from './query.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldkit",
-  "version": "0.157.0",
+  "version": "0.158.0",
   "description": "A TypeScript frontend framework, built on Effect and architected like Elm",
   "type": "module",
   "main": "./dist/index.js",