foldkit 0.106.0 → 0.108.0

package/dist/runtime/runtime.js

@@ -1,11 +1,12 @@
 import { BrowserRuntime } from '@effect/platform-browser';
-import { Array, Cause, Context, Duration, Effect, Exit, Function, Layer, Match, Option, Predicate, PubSub, Queue, Record, Ref, Scheduler, Schema, Stream, SubscriptionRef, pipe, } from 'effect';
+import { Array, Cause, Context, Duration, Effect, Exit, Fiber, Function, Layer, Match, Option, Predicate, PubSub, Queue, Record, Ref, Scheduler, Schema, Stream, SubscriptionRef, pipe, } from 'effect';
 import { h } from 'snabbdom';
 import { createOverlay } from '../devTools/overlay.js';
 import { createDevToolsStore, } from '../devTools/store.js';
 import { startWebSocketBridge } from '../devTools/webSocketBridge.js';
 import { __beginRender as beginHtmlRender, __clearRuntime as clearHtmlRuntime, __createBoundaryRegistry as createHtmlBoundaryRegistry, __setRuntime as setHtmlRuntime, } from '../html/index.js';
 import { MountTracker } from '../mount/index.js';
+import { __CurrentPortChannels, __makeInboundChannel, } from '../port/index.js';
 import { fromString as urlFromString } from '../url/index.js';
 import { dedupeSharedVNodes, patch, toVNode } from '../vdom.js';
 import { addBfcacheRestoreListener, addNavigationEventListeners, } from './browserListeners.js';
@@ -48,7 +49,130 @@ const defaultSlowViewCallback = (context) => {
 /** Effect service tag that provides message dispatching to the view layer. */
 export class Dispatch extends Context.Service()('@foldkit/Dispatch') {
 }
-const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscriptions, container, routing: routingConfig, crash, slowView, freezeModel, resources, managedResources, devTools, }) => {
+const makeHostConnector = () => {
+    let isDisposed = false;
+    let maybeDeliverInbound = Option.none();
+    const pendingInboundSends = [];
+    const listenersByPort = new Map();
+    const sendInbound = (portName, port, value) => {
+        if (isDisposed) {
+            return Exit.void;
+        }
+        const decodeExit = Schema.decodeUnknownExit(port.schema)(value);
+        Exit.match(decodeExit, {
+            onFailure: cause => {
+                console.error(`[foldkit] Inbound port "${portName}" rejected a value:`, Cause.squash(cause));
+            },
+            onSuccess: decodedValue => {
+                Option.match(maybeDeliverInbound, {
+                    onNone: () => {
+                        pendingInboundSends.push({ port, value: decodedValue });
+                    },
+                    onSome: deliverInbound => deliverInbound(port, decodedValue),
+                });
+            },
+        });
+        return Exit.asVoid(decodeExit);
+    };
+    const addListener = (port, listener) => {
+        if (isDisposed) {
+            return Function.constVoid;
+        }
+        const listeners = listenersByPort.get(port) ?? new Set();
+        listenersByPort.set(port, listeners);
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    };
+    // NOTE: delivery is deferred to a microtask so a host listener never runs
+    // inside the runtime's Command fiber (a listener that synchronously calls
+    // send or dispose must not re-enter the runtime), and so a host that
+    // subscribes synchronously right after embed() returns still receives
+    // emissions from init Commands.
+    const deliverOutbound = (port, encodedValue) => {
+        if (isDisposed) {
+            return;
+        }
+        queueMicrotask(() => {
+            if (isDisposed) {
+                return;
+            }
+            const listeners = listenersByPort.get(port) ?? new Set();
+            listeners.forEach(listener => {
+                try {
+                    listener(encodedValue);
+                }
+                catch (listenerError) {
+                    console.error('[foldkit] An outbound port listener threw:', listenerError);
+                }
+            });
+        });
+    };
+    const bind = (deliverInbound) => {
+        maybeDeliverInbound = Option.some(deliverInbound);
+        const flushedSends = pendingInboundSends.splice(0);
+        flushedSends.forEach(({ port, value }) => deliverInbound(port, value));
+    };
+    const unbind = () => {
+        maybeDeliverInbound = Option.none();
+    };
+    const dispose = () => {
+        isDisposed = true;
+        pendingInboundSends.length = 0;
+        listenersByPort.forEach(listeners => listeners.clear());
+        listenersByPort.clear();
+    };
+    return { sendInbound, addListener, deliverOutbound, bind, unbind, dispose };
+};
+const makePortChannels = (ports, maybeConnector) => {
+    const inboundChannelsByPort = new Map();
+    Object.values(ports.inbound ?? {}).forEach(port => {
+        inboundChannelsByPort.set(port, __makeInboundChannel());
+    });
+    const outboundPorts = new Set(Object.values(ports.outbound ?? {}));
+    const channels = {
+        isConfigured: true,
+        lookupInbound: port => Option.fromNullishOr(inboundChannelsByPort.get(port)),
+        lookupOutbound: port => outboundPorts.has(port)
+            ? Option.some(encodedValue => Option.match(maybeConnector, {
+                onNone: Function.constVoid,
+                onSome: connector => connector.deliverOutbound(port, encodedValue),
+            }))
+            : Option.none(),
+    };
+    const deliverInbound = (port, value) => {
+        Option.match(Option.fromNullishOr(inboundChannelsByPort.get(port)), {
+            onNone: Function.constVoid,
+            onSome: channel => channel.deliver(value),
+        });
+    };
+    return { channels, deliverInbound };
+};
+const validatePorts = (ports) => {
+    const inboundEntries = Object.entries(ports.inbound ?? {});
+    const outboundEntries = Object.entries(ports.outbound ?? {});
+    const inboundNames = new Set(inboundEntries.map(([name]) => name));
+    outboundEntries.forEach(([name]) => {
+        if (inboundNames.has(name)) {
+            throw new Error(`[foldkit] Port name "${name}" appears in both inbound and outbound. ` +
+                'Port names share one namespace on the EmbedHandle, so each name ' +
+                'must be unique across both records.');
+        }
+    });
+    const seenPorts = new Set();
+    const allEntries = [...inboundEntries, ...outboundEntries];
+    allEntries.forEach(([name, port]) => {
+        if (seenPorts.has(port)) {
+            throw new Error(`[foldkit] The Port registered as "${name}" is also registered under ` +
+                'another name. Each entry in the ports record needs its own ' +
+                'Port.inbound or Port.outbound value.');
+        }
+        seenPorts.add(port);
+    });
+};
+const runtimeInternals = new WeakMap();
+const makeRuntime = ({ ports, Model, flags: resolveFlags, init, update, view, manageDocument, subscriptions, container, routing: routingConfig, crash, slowView, freezeModel, resources, managedResources, devTools, }) => {
     const resolvedSlowView = pipe(slowView ?? {}, Option.liftPredicate(config => config !== false), Option.filter(config => Match.value(config.show ?? DEFAULT_SLOW_VIEW_SHOW).pipe(Match.when('Always', () => true), Match.when('Development', () => !!import.meta.hot), Match.exhaustive)), Option.map(config => ({
         thresholdMs: config.thresholdMs ?? DEFAULT_SLOW_VIEW_THRESHOLD_MS,
         onSlowView: config.onSlowView ?? defaultSlowViewCallback,
@@ -60,6 +184,9 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
     }));
     const devToolsMaxEntries = pipe(devTools ?? {}, Option.liftPredicate(config => config !== false), Option.flatMapNullishOr(config => config.maxEntries), Option.map(value => Math.max(DEV_TOOLS_MAX_ENTRIES_MIN, Math.min(DEV_TOOLS_MAX_ENTRIES_MAX, value))), Option.getOrUndefined);
     const maybeFreezeModel = (model) => isFreezeModelActive ? deepFreeze(model) : model;
+    if (Predicate.isNotUndefined(ports)) {
+        validatePorts(ports);
+    }
     const runtimeId = container?.id ?? '';
     // NOTE: When the message queue drains a chain of dispatches (e.g. recursive
     // Commands, websocket bursts), processing all of them inside one macrotask
@@ -77,11 +204,17 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
         const handle = requestAnimationFrame(() => resume(Effect.void));
         return Effect.sync(() => cancelAnimationFrame(handle));
     });
-    const start = (hmrModel) => Effect.scoped(Effect.gen(function* () {
+    const startWith = (maybeConnector, hmrModel) => Effect.scoped(Effect.gen(function* () {
         if (runtimeId === '') {
             return yield* Effect.die(new Error('[foldkit] Runtime container must have an `id` for HMR model preservation. ' +
-                'Set `container.id = "app"` (or any unique string) before passing it to makeProgram.'));
+                'Set `container.id = "app"` (or any unique string) before passing it to makeApplication or makeElement.'));
         }
+        // NOTE: every perpetual fiber (render loop, Subscription streams,
+        // ManagedResource lifecycles) and every Command fiber forks into the
+        // runtime scope, so interrupting the runtime fiber (what dispose
+        // does) interrupts them all and runs their finalizers. A detached
+        // fork would outlive the runtime.
+        const runtimeScope = yield* Effect.scope;
         // NOTE: one persistent MessageChannel for the runtime lifetime,
         // shared by every burst-budget yield. The queue-drain fiber is the
         // sole consumer, so a single `pendingYieldResume` slot is sufficient.
@@ -106,7 +239,29 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
                 }
             });
         });
-        const maybeResourceLayer = Option.fromNullishOr(resources);
+        // NOTE: `Effect.provide(effect, layer)` builds the Layer into a
+        // scope that closes when the provided effect ends, so providing the
+        // Layer per Command would construct and tear down every resource on
+        // each invocation. Building once into `runtimeScope` through a
+        // cached Effect is what makes `resources` long-lived: the first
+        // Command or Subscription that runs triggers construction, every
+        // later one shares the same built services, and release happens at
+        // runtime teardown. The build is uninterruptible because
+        // `Effect.cached` caches whatever Exit the first run produces:
+        // dispose racing an in-flight build would otherwise cache an
+        // interrupt, which every waiter would then surface as a crash.
+        const maybeAcquireResourceContext = yield* Option.match(Option.fromNullishOr(resources), {
+            onNone: () => Effect.succeed(Option.none()),
+            onSome: resourceLayer => Effect.map(Effect.cached(Effect.uninterruptible(Layer.buildWithScope(resourceLayer, runtimeScope))), Option.some),
+        });
+        const maybePortChannels = pipe(Option.fromNullishOr(ports), Option.map(portsConfig => makePortChannels(portsConfig, maybeConnector)));
+        yield* Option.match(Option.all({
+            connector: maybeConnector,
+            portChannels: maybePortChannels,
+        }), {
+            onNone: () => Effect.void,
+            onSome: ({ connector, portChannels }) => Effect.acquireRelease(Effect.sync(() => connector.bind(portChannels.deliverInbound)), () => Effect.sync(() => connector.unbind())),
+        });
         // NOTE: One boundary registry per runtime instance, shared
         // across renders so Submodel wrap descriptors registered by
         // h.submodel persist between renders. The render function calls
@@ -130,17 +285,21 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
             Layer.empty, mergeResourceIntoLayer)),
         });
         const provideAllResources = (effect) => {
-            const withResources = Option.match(maybeResourceLayer, {
+            const withResources = Option.match(maybeAcquireResourceContext, {
                 onNone: () => effect,
-                onSome: resourceLayer => Effect.provide(effect, resourceLayer),
+                onSome: acquireResourceContext => Effect.flatMap(acquireResourceContext, resourceContext => Effect.provideContext(effect, resourceContext)),
             });
-            return Option.match(maybeManagedResourceLayer, {
+            const withManagedResources = Option.match(maybeManagedResourceLayer, {
                 /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
                 onNone: () => withResources,
                 onSome: managedLayer => 
                 /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
                 Effect.provide(withResources, managedLayer),
             });
+            return Option.match(maybePortChannels, {
+                onNone: () => withManagedResources,
+                onSome: portChannels => Effect.provideService(withManagedResources, __CurrentPortChannels, portChannels.channels),
+            });
         };
         const flags = yield* resolveFlags;
         const ModelJsonCodec = Schema.toCodecJson(
@@ -198,26 +357,62 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
             : init(flags, Option.getOrUndefined(currentUrl));
         const initModel = maybeFreezeModel(initModelRaw);
         const modelPubSub = yield* PubSub.unbounded();
-        yield* Effect.forEach(
-        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
-        initCommands, command => Effect.forkDetach(command.effect.pipe(Effect.withSpan(command.name, {
-            attributes: command.args ?? {},
-        }), provideAllResources, Effect.flatMap(enqueueNormal))));
         if (routingConfig) {
-            addNavigationEventListeners(enqueueHighUnsafe, routingConfig);
+            yield* Effect.acquireRelease(Effect.sync(() => addNavigationEventListeners(enqueueHighUnsafe, routingConfig)), removeNavigationEventListeners => Effect.sync(() => removeNavigationEventListeners()));
         }
         const modelRef = yield* Ref.make(initModel);
         const maybeCurrentVNodeRef = yield* Ref.make(Option.none());
-        // NOTE: shared by every perpetual fiber's crash path (init render,
-        // render loop, message drain). Each fiber catches its own cause so a
-        // failure surfaces as the crash view instead of dying silently and
-        // leaving the DOM frozen at the last successful render.
+        // NOTE: registered before any perpetual fiber is forked so it runs
+        // after they are interrupted (scope finalizers are LIFO). Patching to
+        // an empty tree fires snabbdom destroy hooks, which is what releases
+        // Mounts; swapping the placeholder for the original container leaves
+        // the host DOM as it was before the first render, ready for a fresh
+        // embed of the same container. Gated on interruption: that is the
+        // dispose path. A runtime that stops because it crashed completes
+        // normally after rendering the crash view, and the crash view must
+        // stay visible.
+        yield* Effect.addFinalizer(exit => Effect.gen(function* () {
+            if (!Exit.hasInterrupts(exit)) {
+                return;
+            }
+            const maybeCurrentVNode = yield* Ref.get(maybeCurrentVNodeRef);
+            yield* Option.match(maybeCurrentVNode, {
+                onNone: () => Effect.void,
+                onSome: currentVNode => Effect.sync(() => {
+                    const placeholderNode = patchVNode(Option.some(currentVNode), null, container).elm;
+                    if (placeholderNode && placeholderNode.parentNode) {
+                        placeholderNode.parentNode.replaceChild(container, placeholderNode);
+                        container.replaceChildren();
+                    }
+                }),
+            });
+        }));
+        const isCrashedRef = yield* Ref.make(false);
+        // NOTE: shared by every fiber's crash path: init render, render
+        // loop, message drain, and the Command and Subscription forks (a
+        // Command's Effect and a Subscription's Stream are typed with a
+        // `never` error channel, so a cause escaping one can only be a
+        // `resources` Layer build failure or an escaped defect, both
+        // unrecoverable). Each fiber catches its own cause so
+        // a failure surfaces as the crash view instead of dying silently
+        // and leaving the DOM frozen at the last successful render. The
+        // first crash wins: concurrent Command fibers can fail on the same
+        // broken Layer, and only one should report and render.
         const crashWith = (cause, maybeMessage) => Effect.gen(function* () {
+            const wasCrashed = yield* Ref.getAndSet(isCrashedRef, true);
+            if (wasCrashed) {
+                return;
+            }
             const model = yield* Ref.get(modelRef);
             const squashed = Cause.squash(cause);
             const error = squashed instanceof Error ? squashed : new Error(String(squashed));
-            renderCrashView({ error, model, message: maybeMessage }, crash, container, maybeCurrentVNodeRef);
+            renderCrashView({ error, model, message: maybeMessage }, crash, container, maybeCurrentVNodeRef, manageDocument);
         });
+        yield* Effect.forEach(
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        initCommands, command => Effect.forkIn(runtimeScope)(command.effect.pipe(Effect.withSpan(command.name, {
+            attributes: command.args ?? {},
+        }), provideAllResources, Effect.flatMap(enqueueNormal), Effect.catchCause(cause => crashWith(cause, Option.none())))));
         // NOTE: queue-drain-fiber-local state. Kept as plain closure
         // variables instead of `Ref`s because nothing else reads or writes
         // them concurrently, and JS's single-threaded model already orders
@@ -276,9 +471,9 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
             if (!Array.isReadonlyArrayEmpty(commands)) {
                 yield* Effect.forEach(
                 /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
-                commands, command => Effect.forkDetach(command.effect.pipe(Effect.withSpan(command.name, {
+                commands, command => Effect.forkIn(runtimeScope)(command.effect.pipe(Effect.withSpan(command.name, {
                     attributes: command.args ?? {},
-                }), provideAllResources, Effect.flatMap(enqueueNormal))));
+                }), provideAllResources, Effect.flatMap(enqueueNormal), Effect.catchCause(cause => crashWith(cause, Option.some(message))))));
             }
             /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
             const messageTag = message._tag;
@@ -336,7 +531,9 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
             const maybeCurrentVNode = yield* Ref.get(maybeCurrentVNodeRef);
             const patchedVNode = yield* Effect.sync(() => patchVNode(maybeCurrentVNode, nextVNode, container));
             yield* Ref.set(maybeCurrentVNodeRef, Option.some(patchedVNode));
-            yield* Effect.sync(() => applyDocumentMetadata(nextDocument, patchedVNode.elm));
+            if (manageDocument) {
+                yield* Effect.sync(() => applyDocumentMetadata(nextDocument, patchedVNode.elm));
+            }
         }).pipe(Effect.provideService(Dispatch, dispatchService), Effect.provideService(MountTracker, mountTracker));
         const isInIframe = window.self !== window.top;
         const resolvedDevTools = pipe(devTools ?? {}, Option.liftPredicate(config => config !== false), Option.filter(config => Match.value(config.show ?? DEFAULT_DEV_TOOLS_SHOW).pipe(Match.when('Always', () => true), Match.when('Development', () => !!import.meta.hot && !isInIframe), Match.exhaustive)), Option.map(config => ({
@@ -405,9 +602,22 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
                 maybeMessageSchema);
             }
         }
+        // NOTE: a fast-failing init Command (a `resources` Layer that
+        // throws synchronously) can render the crash view before this
+        // point. Rendering the init view would paint over it, so a crashed
+        // runtime suspends here instead, exactly like the failing-init-
+        // render path below.
+        const isCrashedBeforeInitRender = yield* Ref.get(isCrashedRef);
+        if (isCrashedBeforeInitRender) {
+            return yield* Effect.never;
+        }
         const initRenderExit = yield* Effect.exit(render(initModel, Option.none()));
         if (Exit.isFailure(initRenderExit)) {
-            return yield* crashWith(initRenderExit.cause, Option.none());
+            yield* crashWith(initRenderExit.cause, Option.none());
+            // NOTE: suspend instead of returning. Completing would close the
+            // runtime scope and tear down the crash view; the scope must stay
+            // open until the runtime is interrupted (dispose, or page unload).
+            return yield* Effect.never;
         }
         const initMountEvents = drainMountEvents();
         yield* Option.match(maybeDevToolsStore, {
@@ -425,6 +635,14 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
             awaitNextFrame,
             isPaused: isPausedEffect,
             render: Effect.gen(function* () {
+                // NOTE: a Message that dirtied the model can also be the one
+                // whose Command crashed the runtime. Without this guard the
+                // next animation frame would render the live view over the
+                // crash view.
+                const isCrashed = yield* Ref.get(isCrashedRef);
+                if (isCrashed) {
+                    return;
+                }
                 const model = yield* Ref.get(modelRef);
                 const maybeMessage = yield* Ref.get(maybeLastDirtyMessageRef);
                 yield* render(model, maybeMessage);
@@ -435,18 +653,23 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
                 });
             }),
         });
-        yield* Effect.forkDetach(renderLoop.pipe(Effect.catchCause(cause => Effect.gen(function* () {
+        yield* Effect.forkIn(runtimeScope)(renderLoop.pipe(Effect.catchCause(cause => Effect.gen(function* () {
             const maybeMessage = yield* Ref.get(maybeLastDirtyMessageRef);
             yield* crashWith(cause, maybeMessage);
         }))));
-        addBfcacheRestoreListener();
+        // NOTE: reloading on bfcache restore is a page-level decision, so
+        // only a page-owning runtime installs the listener. An embedded app
+        // must never force the host page to reload.
+        if (manageDocument) {
+            yield* Effect.acquireRelease(Effect.sync(() => addBfcacheRestoreListener()), removeBfcacheRestoreListener => Effect.sync(() => removeBfcacheRestoreListener()));
+        }
         if (subscriptions) {
             yield* pipe(subscriptions, Record.toEntries, Effect.forEach(([_key, { dependenciesSchema, modelToDependencies, keepAliveEquivalence, dependenciesToStream, },]) => Effect.gen(function* () {
                 const latestDependenciesRef = yield* Ref.make(modelToDependencies(initModel));
                 const equivalence = keepAliveEquivalence ??
                     Schema.toEquivalence(dependenciesSchema);
                 const modelStream = Stream.concat(Stream.make(initModel), Stream.fromPubSub(modelPubSub));
-                yield* Effect.forkDetach(modelStream.pipe(
+                yield* Effect.forkIn(runtimeScope)(modelStream.pipe(
                 // NOTE: Ref.set runs upstream of Stream.changesWith on
                 // every model change, so readDependencies() returns
                 // current values even when the equivalence filter
@@ -460,7 +683,7 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
                     return dependencies;
                 })), Stream.changesWith(equivalence), Stream.switchMap(dependencies => dependenciesToStream(dependencies, () => Ref.getUnsafe(latestDependenciesRef))), Stream.runForEach(message => 
                 /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
-                enqueueHigh(message)), provideAllResources));
+                enqueueHigh(message)), provideAllResources, Effect.catchCause(cause => crashWith(cause, Option.none()))));
             }), {
                 concurrency: 'unbounded',
                 discard: true,
@@ -489,7 +712,7 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
         const forkManagedResourceLifecycle = ({ config, ref: resourceRef, }) => Effect.gen(function* () {
             const modelStream = Stream.concat(Stream.make(initModel), Stream.fromPubSub(modelPubSub));
             const equivalence = Schema.toEquivalence(config.schema);
-            yield* Effect.forkDetach(modelStream.pipe(Stream.map(config.modelToMaybeRequirements), Stream.changesWith(equivalence), Stream.switchMap(maybeRequirementsToLifecycle(config, resourceRef)), Stream.runForEach(Effect.flatMap(enqueueHigh))));
+            yield* Effect.forkIn(runtimeScope)(modelStream.pipe(Stream.map(config.modelToMaybeRequirements), Stream.changesWith(equivalence), Stream.switchMap(maybeRequirementsToLifecycle(config, resourceRef)), Stream.runForEach(Effect.flatMap(enqueueHigh))));
         });
         yield* Effect.forEach(managedResourceRefs, forkManagedResourceLifecycle, {
             concurrency: 'unbounded',
@@ -551,8 +774,20 @@ const makeRuntime = ({ Model, flags: resolveFlags, init, update, view, subscript
             yield* processBatch(Array.prepend(rest, first));
             yield* drainQueue;
         })), Effect.catchCause(cause => crashWith(cause, currentMessage)));
+        // NOTE: reached only after the drain loop crashed and the crash view
+        // rendered. Suspending keeps the runtime scope open so the crash view
+        // and the DevTools overlay stay up for inspection; interruption
+        // (dispose, or page unload) still tears everything down.
+        yield* Effect.never;
     }));
-    return { runtimeId, start };
+    const start = (hmrModel) => startWith(Option.none(), hmrModel);
+    const program = { runtimeId, start, ports };
+    runtimeInternals.set(program, {
+        startWith,
+        isEmbedActive: false,
+        maybeActiveFiber: Option.none(),
+    });
+    return program;
 };
 // NOTE: exported for `patchVNode.test.ts` to assert the dedupeSharedVNodes
 // wiring; not part of the public surface (`runtime/public.ts` is curated).
@@ -594,7 +829,7 @@ const applyDocumentMetadata = (nextDocument, mountedRoot) => {
         content: ogUrl,
     });
 };
-const renderCrashView = (context, crash, container, maybeCurrentVNodeRef) => {
+const renderCrashView = (context, crash, container, maybeCurrentVNodeRef, manageDocument) => {
     console.error('[foldkit] Application crash:', context.error);
     if (crash?.report) {
         try {
@@ -621,7 +856,10 @@ const renderCrashView = (context, crash, container, maybeCurrentVNodeRef) => {
         }
         const maybeCurrentVNode = Effect.runSync(Ref.get(maybeCurrentVNodeRef));
         const patchedVNode = patchVNode(maybeCurrentVNode, crashDocument.body, container);
-        applyDocumentMetadata(crashDocument, patchedVNode.elm);
+        Effect.runSync(Ref.set(maybeCurrentVNodeRef, Option.some(patchedVNode)));
+        if (manageDocument) {
+            applyDocumentMetadata(crashDocument, patchedVNode.elm);
+        }
     }
     catch (viewError) {
         console.error('[foldkit] crash.view failed:', viewError);
@@ -636,14 +874,17 @@ const renderCrashView = (context, crash, container, maybeCurrentVNodeRef) => {
         }
         const maybeCurrentVNode = Effect.runSync(Ref.get(maybeCurrentVNodeRef));
         const patchedVNode = patchVNode(maybeCurrentVNode, fallbackDocument.body, container);
-        applyDocumentMetadata(fallbackDocument, patchedVNode.elm);
+        Effect.runSync(Ref.set(maybeCurrentVNodeRef, Option.some(patchedVNode)));
+        if (manageDocument) {
+            applyDocumentMetadata(fallbackDocument, patchedVNode.elm);
+        }
     }
 };
-export function makeProgram(config) {
+export function makeApplication(config) {
     const { container } = config;
     if (container === null) {
         throw new Error('[foldkit] Container is null. Make sure the element exists in the DOM ' +
-            'before calling makeProgram (e.g. that your <div id="root"></div> has ' +
+            'before calling makeApplication (e.g. that your <div id="root"></div> has ' +
             'rendered, and your script runs after it).');
     }
     const hasRouting = 'routing' in config;
@@ -655,6 +896,8 @@ export function makeProgram(config) {
         Model: config.Model,
         update: config.update,
         view: config.view,
+        manageDocument: true,
+        ports: config.ports,
         ...(config.subscriptions && { subscriptions: config.subscriptions }),
         container,
         ...(hasRouting && { routing: config.routing }),
@@ -708,6 +951,79 @@ export function makeProgram(config) {
     }
     /* eslint-enable @typescript-eslint/consistent-type-assertions */
 }
+const toCrashConfig = (nullableCrash) => {
+    if (Predicate.isUndefined(nullableCrash)) {
+        return undefined;
+    }
+    const elementCrashView = nullableCrash.view;
+    return {
+        ...(Predicate.isNotUndefined(elementCrashView) && {
+            view: (context) => ({
+                title: '',
+                body: elementCrashView(context),
+            }),
+        }),
+        ...(Predicate.isNotUndefined(nullableCrash.report) && {
+            report: nullableCrash.report,
+        }),
+    };
+};
+export function makeElement(config) {
+    const { container } = config;
+    if (container === null) {
+        throw new Error('[foldkit] Container is null. Make sure the element exists in the DOM ' +
+            'before calling makeElement (e.g. that your <div id="root"></div> has ' +
+            'rendered, and your script runs after it).');
+    }
+    const hasFlags = 'Flags' in config;
+    const elementView = config.view;
+    const view = (model) => ({
+        title: '',
+        body: elementView(model),
+    });
+    const nullableCrash = toCrashConfig(config.crash);
+    const baseConfig = {
+        Model: config.Model,
+        update: config.update,
+        view,
+        manageDocument: false,
+        ports: config.ports,
+        ...(config.subscriptions && { subscriptions: config.subscriptions }),
+        container,
+        ...(Predicate.isNotUndefined(nullableCrash) && { crash: nullableCrash }),
+        ...(Predicate.isNotUndefined(config.slowView) && {
+            slowView: config.slowView,
+        }),
+        ...(Predicate.isNotUndefined(config.freezeModel) && {
+            freezeModel: config.freezeModel,
+        }),
+        ...(config.resources && { resources: config.resources }),
+        ...(config.managedResources && {
+            managedResources: config.managedResources,
+        }),
+        ...(Predicate.isNotUndefined(config.devTools) && {
+            devTools: config.devTools,
+        }),
+    };
+    /* eslint-disable @typescript-eslint/consistent-type-assertions */
+    if (hasFlags) {
+        return makeRuntime({
+            ...baseConfig,
+            Flags: config.Flags,
+            flags: config.flags,
+            init: (flags) => config.init(flags),
+        });
+    }
+    else {
+        return makeRuntime({
+            ...baseConfig,
+            Flags: Schema.Void,
+            flags: Effect.succeed(undefined),
+            init: () => config.init(),
+        });
+    }
+    /* eslint-enable @typescript-eslint/consistent-type-assertions */
+}
 const encodePreserveModelMessage = Schema.encodeUnknownSync(PreserveModelMessage);
 const encodeRequestModelMessage = Schema.encodeUnknownSync(RequestModelMessage);
 const decodeRestoreModelMessage = Schema.decodeUnknownExit(RestoreModelMessage);
@@ -735,36 +1051,120 @@ const microtaskSetImmediate = (callback) => {
 };
 const browserScheduler = new Scheduler.MixedScheduler('async', microtaskSetImmediate);
 const provideBrowserScheduler = (effect) => Effect.provide(effect, Layer.succeed(Scheduler.Scheduler, browserScheduler));
-/** Starts a Foldkit runtime, with HMR support for development. */
+// NOTE: asks @foldkit/vite-plugin for a model preserved across the last HMR
+// reload. The plugin only serves a model whose preservation was flushed by a
+// reload, so a host-driven dispose-then-embed remount initializes fresh while
+// a code reload restores state.
+const resolveHmrModel = (runtimeId) => {
+    const hot = import.meta.hot;
+    if (!hot) {
+        return Effect.succeed(undefined);
+    }
+    return pipe(Effect.callback(resume => {
+        const handler = (message) => {
+            Exit.match(decodeRestoreModelMessage(message), {
+                onFailure: Function.constVoid,
+                onSuccess: ({ id, model }) => {
+                    if (id === runtimeId) {
+                        hot.off('foldkit:restore-model', handler);
+                        resume(Effect.succeed(model));
+                    }
+                },
+            });
+        };
+        hot.on('foldkit:restore-model', handler);
+        hot.send('foldkit:request-model', encodeRequestModelMessage(RequestModelMessage.make({ id: runtimeId })));
+        return Effect.sync(() => hot.off('foldkit:restore-model', handler));
+    }), Effect.timeout(PLUGIN_RESPONSE_TIMEOUT_MS), Effect.catchTag('TimeoutError', () => {
+        console.warn('[foldkit] No response from @foldkit/vite-plugin. Add it to your vite.config.ts for HMR model preservation:\n\n' +
+            "  import { foldkit } from '@foldkit/vite-plugin'\n\n" +
+            '  export default defineConfig({ plugins: [foldkit()] })\n\n' +
+            'Starting without HMR support.');
+        return Effect.succeed(undefined);
+    }));
+};
+/** Starts a Foldkit runtime that owns the page for the page's whole lifetime,
+ *  with HMR support for development. To start a runtime under a
+ *  host-controlled lifecycle instead, use `embed`. */
 export const run = (program) => {
-    if (import.meta.hot) {
-        const hot = import.meta.hot;
-        const { runtimeId, start } = program;
-        const requestPreservedModel = pipe(Effect.callback(resume => {
-            const handler = (message) => {
-                Exit.match(decodeRestoreModelMessage(message), {
-                    onFailure: Function.constVoid,
-                    onSuccess: ({ id, model }) => {
-                        if (id === runtimeId) {
-                            hot.off('foldkit:restore-model', handler);
-                            resume(Effect.succeed(model));
-                        }
-                    },
-                });
+    BrowserRuntime.runMain(provideBrowserScheduler(Effect.flatMap(resolveHmrModel(program.runtimeId), program.start)));
+};
+const buildPortHandles = (ports, connector) => {
+    const handles = {};
+    if (Predicate.isNotUndefined(ports)) {
+        Object.entries(ports.inbound ?? {}).forEach(([portName, port]) => {
+            handles[portName] = {
+                send: (value) => connector.sendInbound(portName, port, value),
             };
-            hot.on('foldkit:restore-model', handler);
-            hot.send('foldkit:request-model', encodeRequestModelMessage(RequestModelMessage.make({ id: runtimeId })));
-            return Effect.sync(() => hot.off('foldkit:restore-model', handler));
-        }), Effect.timeout(PLUGIN_RESPONSE_TIMEOUT_MS), Effect.catchTag('TimeoutError', () => {
-            console.warn('[foldkit] No response from @foldkit/vite-plugin. Add it to your vite.config.ts for HMR model preservation:\n\n' +
-                "  import { foldkit } from '@foldkit/vite-plugin'\n\n" +
-                '  export default defineConfig({ plugins: [foldkit()] })\n\n' +
-                'Starting without HMR support.');
-            return Effect.succeed(undefined);
-        }), Effect.flatMap(start));
-        BrowserRuntime.runMain(provideBrowserScheduler(requestPreservedModel));
+        });
+        Object.entries(ports.outbound ?? {}).forEach(([portName, port]) => {
+            handles[portName] = {
+                subscribe: (listener) => connector.addListener(port, listener),
+            };
+        });
     }
-    else {
-        BrowserRuntime.runMain(provideBrowserScheduler(program.start()));
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+    return handles;
+};
+/**
+ * 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 const embed = (program) => {
+    const nullableInternals = runtimeInternals.get(program);
+    if (Predicate.isUndefined(nullableInternals)) {
+        throw new Error('[foldkit] embed expects a program created by makeApplication or makeElement.');
+    }
+    const internals = nullableInternals;
+    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)));
+    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 };
 };