foldkit 0.146.0 → 0.147.0

package/dist/runtime/runtime.js

@@ -2,7 +2,9 @@ import { Array, Cause, Context, Duration, Effect, Exit, Fiber, Function, Layer,
 import { __CurrentRegistry as __CurrentInterruptRegistry, __makeRegistry as __makeInterruptRegistry, } from '../command/interruptible/index.js';
 import { createDevToolsStore, } from '../devTools/store.js';
 import { startWebSocketBridge } from '../devTools/webSocketBridge.js';
-import { __beginRender as beginHtmlRender, __beginReplayRender as beginReplayHtmlRender, __clearRuntime as clearHtmlRuntime, __createBoundaryRegistry as createHtmlBoundaryRegistry, __endReplayRender as endReplayHtmlRender, __htmlBuilder as htmlBuilderFor, __setRuntime as setHtmlRuntime, } from '../html/index.js';
+import { __beginRender as beginHtmlRender, __beginReplayRender as beginReplayHtmlRender, __clearRuntime as clearHtmlRuntime, __createBoundaryRegistry as createHtmlBoundaryRegistry, __endReplayRender as endReplayHtmlRender, __htmlBuilder as htmlBuilderFor, __setRuntime as setHtmlRuntime, textDirectionToAttribute, } from '../html/index.js';
+import { __hydrateVNode } from '../hydrate.js';
+import { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE, } from '../hydrationMarker.js';
 import { MountTracker } from '../mount/index.js';
 import { __CurrentPortChannels, __makeInboundChannel, } from '../port/index.js';
 import { RenderCommit, createCommitNotifier } from '../render/commit.js';
@@ -191,6 +193,53 @@ const createDuplicateIdScanner = () => {
 /** Effect service tag that provides message dispatching to the view layer. */
 export class Dispatch extends Context.Service()('@foldkit/Dispatch') {
 }
+const hydrationForRoot = (root, isFlagsRequired) => {
+    const runtimeId = root.getAttribute(FOLDKIT_APP_ATTRIBUTE) ?? '';
+    const flagsPayloads = pipe(Array.fromIterable(document.querySelectorAll(`script[${FOLDKIT_FLAGS_ATTRIBUTE}]`)), Array.filter(script => script.getAttribute(FOLDKIT_FLAGS_ATTRIBUTE) === runtimeId), Array.map(script => script.textContent ?? ''));
+    return { root, runtimeId, flagsPayloads, isFlagsRequired };
+};
+// NOTE: hydration is scoped to the app's own stamped root so a server-rendered
+// app never adopts another app's DOM. A container that carries the stamp is that
+// root. A container that does not is a non-root element the caller resolved,
+// which happens when the rendered view has its own element with the container's
+// id (a descendant `id="root"`) and `getElementById` returned that inner element
+// instead of the stamped root above it. That inner element resolves to the app
+// root only when the page has exactly one stamped root and this container sits
+// inside it, so a sibling widget (a stamped root the container is not inside) or
+// an outer application's root (when a nested page carries more than one stamped
+// root) is never wrongly adopted; those fall through to a fresh boot or a hard
+// failure instead. A null container is the replace-parity case, where the server
+// root took the placeholder's place and `getElementById` no longer finds it, so
+// the stamp is the only handle; more than one stamped root is then ambiguous and
+// a hard error rather than a silent wrong-DOM adoption.
+const findDocumentHydration = (container, isFlagsRequired) => {
+    const stampedRoots = Array.fromIterable(document.querySelectorAll(`[${FOLDKIT_APP_ATTRIBUTE}]`));
+    if (container !== null) {
+        if (container.hasAttribute(FOLDKIT_APP_ATTRIBUTE)) {
+            return hydrationForRoot(container, isFlagsRequired);
+        }
+        return Array.match(stampedRoots, {
+            onEmpty: () => undefined,
+            onNonEmpty: roots => {
+                const onlyRoot = Array.headNonEmpty(roots);
+                return roots.length === 1 &&
+                    container.closest(`[${FOLDKIT_APP_ATTRIBUTE}]`) === onlyRoot
+                    ? hydrationForRoot(onlyRoot, isFlagsRequired)
+                    : undefined;
+            },
+        });
+    }
+    if (stampedRoots.length > 1) {
+        throw new Error('[foldkit] Found multiple server-rendered roots stamped with ' +
+            `\`${FOLDKIT_APP_ATTRIBUTE}\` but no container to disambiguate them. ` +
+            'Give each app its own container element so the runtime can tell ' +
+            'which root to hydrate.');
+    }
+    return Option.match(Array.head(stampedRoots), {
+        onNone: () => undefined,
+        onSome: root => hydrationForRoot(root, isFlagsRequired),
+    });
+};
 const makeHostConnector = () => {
     let isDisposed = false;
     let maybeDeliverInbound = Option.none();
@@ -314,7 +363,7 @@ const validatePorts = (ports) => {
     });
 };
 const runtimeInternals = new WeakMap();
-const makeRuntime = ({ ports, Model, flags: maybeResolveFlags, init, update, view, manageDocument, subscriptions, container, routing: routingConfig, crash, slow, viewTransition, freezeModel, preserveScroll, resources, managedResources, devTools, }) => {
+const makeRuntime = ({ ports, kind, Model, Flags: FlagsCodec, configuredFlags, isFlagsRequired, init, update, view, manageDocument, subscriptions, container, hydration, routing: routingConfig, crash, slow, viewTransition, freezeModel, preserveScroll, resources, managedResources, devTools, }) => {
     const isSlowVisible = (show) => Match.value(show).pipe(Match.when('Always', () => true), Match.when('Development', () => !!import.meta.hot), Match.exhaustive);
     const htmlBuilder = htmlBuilderFor();
     const resolvedSlow = __resolveSlowConfig(slow, isSlowVisible);
@@ -352,8 +401,10 @@ const makeRuntime = ({ ports, Model, flags: maybeResolveFlags, init, update, vie
     if (Predicate.isNotUndefined(ports)) {
         validatePorts(ports);
     }
-    const runtimeId = container?.id ?? '';
-    const startWith = (maybeConnector, hmrModel) => {
+    const runtimeId = hydration !== undefined && hydration.runtimeId !== ''
+        ? hydration.runtimeId
+        : (container?.id ?? '');
+    const startWith = (maybeConnector, hmrModel, bootMode = 'Fresh', bootFlags) => {
         // NOTE: one notifier per runtime, provided across the whole runtime
         // Effect so Commands, Subscriptions, and Mount-forked Effects all resolve
         // the same signal. A commit in one embedded application must never wake a
@@ -362,7 +413,8 @@ const makeRuntime = ({ ports, Model, flags: maybeResolveFlags, init, update, vie
         return 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 makeApplication or makeElement.'));
+                    'Set `container.id = "app"` (or any unique string) before passing it to makeApplication or makeElement. ' +
+                    'On a server-rendered page the id comes from the `data-foldkit-app` root stamp instead.'));
             }
             // NOTE: every perpetual fiber (for example, Subscription streams
             // and ManagedResource lifecycles) and every Command fiber forks
@@ -434,28 +486,28 @@ const makeRuntime = ({ ports, Model, flags: maybeResolveFlags, init, update, vie
                 });
                 return Effect.provideService(withPortChannels, __CurrentInterruptRegistry, interruptRegistry);
             };
-            // NOTE: flags run through the same cached build that Commands and
+            // NOTE: Flags run through the same cached build that Commands and
             // Subscriptions use, rather than being handed the Layer again, so a
             // service needed both at startup and by a Command is constructed
-            // once. An app without flags never reaches it, which keeps the Layer
+            // once. An app without Flags never reaches it, which keeps the Layer
             // lazy when the first thing that needs it is a Command.
             //
             // NOTE: a Layer that fails to build is not fatal here. Flags resolve
             // before `init`, so there is no Model for a crash view to render
             // against and a failure escaping this point kills the app with a
-            // blank container. Running flags against an empty context instead
-            // lets an app whose flags never touch the Layer boot as it did
-            // before flags could consume `resources`: the cached failure then
+            // blank container. Running Flags against an empty context instead
+            // lets an app whose Flags never touch the Layer boot as it did
+            // before Flags could consume `resources`: the cached failure then
             // surfaces at the first Command or Subscription, where `crashWith`
             // does render the crash view. Flags that do need the Layer still
             // fail here, and both causes are reported: the `Service not found`
             // defect the empty context produced is useless on its own, and the
             // build failure that explains it would be lost if it replaced the
-            // flags cause outright. Combining them also keeps a flags Effect
+            // Flags cause outright. Combining them also keeps a Flags Effect
             // that fails for its own unrelated reason visible instead of
             // attributing its defect to the Layer. Interrupts propagate
             // untouched on both sides, because dispose racing either the build
-            // or the flags run is not a failure to recover from, and
+            // or the Flags run is not a failure to recover from, and
             // `Effect.catchCause` hands the handler interrupt causes too.
             const provideResources = (effect) => Option.match(maybeAcquireResourceContext, {
                 /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
@@ -471,23 +523,73 @@ const makeRuntime = ({ ports, Model, flags: maybeResolveFlags, init, update, vie
                     onSuccess: resourceContext => Effect.provideContext(effect, resourceContext),
                 }),
             });
-            const resolveFlags = Option.match(maybeResolveFlags, {
-                /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
-                onNone: () => Effect.succeed(undefined),
+            const maybeResolveFreshFlags = Option.orElse(Option.fromNullishOr(bootFlags), () => configuredFlags);
+            const resolveFreshFlags = Option.match(maybeResolveFreshFlags, {
+                onNone: () => isFlagsRequired
+                    ? Effect.die(new Error('[foldkit] This application declares Flags. Pass its ' +
+                        'Flags Effect to Runtime.run or Runtime.embed.'))
+                    : /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                        Effect.succeed(undefined),
                 onSome: provideResources,
             });
+            const decodeFlagsPayload = (payload, runtimeId) => Effect.try({
+                try: () => {
+                    const parsedPayload = JSON.parse(payload);
+                    return pipe(
+                    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                    Schema.toCodecJson(FlagsCodec), Schema.decodeUnknownSync, decode => decode(parsedPayload));
+                },
+                catch: cause => new Error('[foldkit] Runtime.hydrate could not decode the server ' +
+                    `Flags payload for application "${runtimeId}". The HTML ` +
+                    'and client bundle must use the same Flags Schema.', { cause }),
+            }).pipe(Effect.orDie);
+            const maybeRequestedHydration = bootMode === 'Hydrate'
+                ? Option.fromNullishOr(hydration)
+                : Option.none();
+            if (bootMode === 'Hydrate' && Option.isNone(maybeRequestedHydration)) {
+                return yield* Effect.die(new Error('[foldkit] Runtime.hydrate could not find a server-rendered ' +
+                    `root stamped with \`${FOLDKIT_APP_ATTRIBUTE}\`. Use ` +
+                    'Runtime.run for a fresh client boot.'));
+            }
+            // NOTE: an HMR-restored Model wins over DOM adoption because the
+            // server DOM reflects older code. The hydration handoff is still
+            // required, but the restored Model gets a fresh patch against its
+            // stamped root.
+            const maybeHydrationRoot = Predicate.isUndefined(hmrModel)
+                ? Option.map(maybeRequestedHydration, requestedHydration => requestedHydration.root)
+                : Option.none();
+            const maybeHydrationFlags = yield* Option.match(maybeRequestedHydration, {
+                onNone: () => Effect.succeed(Option.none()),
+                onSome: requestedHydration => Effect.map(requestedHydration.isFlagsRequired
+                    ? Array.match(requestedHydration.flagsPayloads, {
+                        onEmpty: () => Effect.die(new Error('[foldkit] Runtime.hydrate found application ' +
+                            `"${requestedHydration.runtimeId}" but its ` +
+                            'server Flags payload is missing.')),
+                        onNonEmpty: ([payload, ...remainingPayloads]) => Array.isArrayNonEmpty(remainingPayloads)
+                            ? Effect.die(new Error('[foldkit] Runtime.hydrate found multiple ' +
+                                'server Flags payloads for application ' +
+                                `"${requestedHydration.runtimeId}".`))
+                            : decodeFlagsPayload(payload, requestedHydration.runtimeId),
+                    })
+                    : /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                        Effect.succeed(undefined), Option.some),
+            });
+            const resolveFlags = Option.match(maybeHydrationFlags, {
+                onNone: () => resolveFreshFlags,
+                onSome: Effect.succeed,
+            });
             const ModelJsonCodec = Schema.toCodecJson(
             /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
             Model);
             const decodeHmrModel = Schema.decodeUnknownExit(ModelJsonCodec);
             const encodeHmrModel = Schema.encodeUnknownSync(ModelJsonCodec);
             const currentUrl = Option.fromNullishOr(routingConfig).pipe(Option.flatMap(() => urlFromString(window.location.href)));
-            // NOTE: a restored Model skips `init`, so resolving flags on that
+            // NOTE: a restored Model skips `init`, so resolving Flags on that
             // path would build the `resources` Layer only to discard what it
             // produced. Gating the resolution on the restore decision is what
             // stops a reload from reconnecting whatever the Layer holds. It has
             // to stay ahead of the preserve-scheduler and HMR finalizers: a
-            // flags Effect that fails after those are registered tears down more
+            // Flags Effect that fails after those are registered tears down more
             // than it used to, and their release defects would bury its cause.
             const runInit = Effect.map(resolveFlags, flags => init(flags, Option.getOrUndefined(currentUrl)));
             const [initModelRaw, initCommands] = yield* hmrModel !== undefined
@@ -637,6 +739,10 @@ const makeRuntime = ({ ports, Model, flags: maybeResolveFlags, init, update, vie
                 }
             };
             const vnodeSlot = { maybeCurrentVNode: Option.none() };
+            // NOTE: consumed by the first render only. Set when this boot found
+            // an adoptable server-rendered root; the first patch then goes
+            // through `__hydrateVNode` instead of replacing the container.
+            let pendingHydrationRoot = Option.getOrNull(maybeHydrationRoot);
             // 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
@@ -941,7 +1047,24 @@ const makeRuntime = ({ ports, Model, flags: maybeResolveFlags, init, update, vie
                     thresholdMs,
                 }));
                 const maybeCurrentVNode = vnodeSlot.maybeCurrentVNode;
-                const [patchedVNode, maybePatchDuration] = yield* Effect.sync(() => measureSlowPhase(maybeLiveSlowPatch, () => __patchVNode(maybeCurrentVNode, nextVNode, container, boundaryRegistry.dedupeSeen)));
+                const [patchedVNode, maybePatchDuration] = yield* Effect.sync(() => measureSlowPhase(maybeLiveSlowPatch, () => {
+                    if (Option.isNone(maybeCurrentVNode) &&
+                        pendingHydrationRoot !== null) {
+                        const hydrationRoot = pendingHydrationRoot;
+                        pendingHydrationRoot = null;
+                        // NOTE: strip the stamp before the patch, not after, so the
+                        // patch is the sole owner of the root's attributes. It has
+                        // already served its purpose of locating the root, and
+                        // removing it after would delete a `data-foldkit-app` the view
+                        // itself declares, which a later equal-vnode patch would not
+                        // restore. Removing it here also stops a later boot on the same
+                        // container (a dispose-then-embed remount) from re-detecting
+                        // this now-consumed root as hydratable.
+                        hydrationRoot.removeAttribute(FOLDKIT_APP_ATTRIBUTE);
+                        return __hydrateVNode(hydrationRoot, nextVNode, boundaryRegistry.dedupeSeen);
+                    }
+                    return __patchVNode(maybeCurrentVNode, nextVNode, container, boundaryRegistry.dedupeSeen);
+                }));
                 vnodeSlot.maybeCurrentVNode = Option.some(patchedVNode);
                 reportSlowPhase(maybeLiveSlowPatch, maybePatchDuration, (durationMs, thresholdMs) => ({
                     _tag: 'Patch',
@@ -1372,10 +1495,15 @@ const makeRuntime = ({ ports, Model, flags: maybeResolveFlags, init, update, vie
             yield* Effect.never;
         })).pipe(Effect.provideService(RenderCommit, commitNotifier.service));
     };
-    const start = (hmrModel) => startWith(Option.none(), hmrModel);
-    const program = { runtimeId, start, ports };
+    const start = (hmrModel) => startWith(Option.none(), hmrModel, 'Fresh');
+    const program = {
+        runtimeId,
+        start,
+        ports,
+    };
     runtimeInternals.set(program, {
-        startWith,
+        startWith: (maybeConnector, hmrModel, bootMode, flags) => startWith(maybeConnector, hmrModel, bootMode, flags),
+        kind,
         isEmbedActive: false,
         maybeActiveFiber: Option.none(),
     });
@@ -1390,11 +1518,6 @@ const currentLocationUrl = () => {
     const { origin, pathname, search } = window.location;
     return `${origin}${pathname}${search}`;
 };
-const textDirectionForHtmlElement = {
-    Ltr: 'ltr',
-    Rtl: 'rtl',
-    Auto: 'auto',
-};
 const documentMetadataElements = new WeakMap();
 const metadataElementsForDocument = () => {
     let elements = documentMetadataElements.get(document);
@@ -1431,7 +1554,7 @@ const applyDocumentMetadata = (nextDocument, mountedRoot) => {
         documentElement.lang = nextDocument.lang;
     }
     if (nextDocument.dir !== undefined) {
-        const dir = textDirectionForHtmlElement[nextDocument.dir];
+        const dir = textDirectionToAttribute(nextDocument.dir);
         if (documentElement.dir !== dir) {
             documentElement.dir = dir;
         }
@@ -1503,24 +1626,29 @@ const renderCrashView = (context, crash, container, vnodeSlot, manageDocument) =
 };
 export function makeApplication(config) {
     const { container } = config;
-    if (container === null) {
+    const hasRouting = 'routing' in config;
+    const hasFlags = 'Flags' in config;
+    const hydration = findDocumentHydration(container, hasFlags);
+    const resolvedContainer = hydration?.root ?? container;
+    if (resolvedContainer === null) {
         throw new Error('[foldkit] Container is null. Make sure the element exists in the DOM ' +
             'before calling makeApplication (e.g. that your <div id="root"></div> has ' +
-            'rendered, and your script runs after it).');
+            'rendered, and your script runs after it). On a server-rendered page ' +
+            'the runtime instead finds the root by its `data-foldkit-app` stamp.');
     }
-    const hasRouting = 'routing' in config;
-    const hasFlags = 'Flags' in config;
     const currentUrl = hasRouting
         ? Option.getOrThrow(urlFromString(window.location.href))
         : undefined;
     const baseConfig = {
+        kind: 'Application',
         Model: config.Model,
         update: config.update,
         view: config.view,
         manageDocument: true,
         ports: config.ports,
         ...(config.subscriptions && { subscriptions: config.subscriptions }),
-        container,
+        container: resolvedContainer,
+        ...(hydration && { hydration }),
         ...(hasRouting && { routing: config.routing }),
         ...(config.crash && { crash: config.crash }),
         ...(Predicate.isNotUndefined(config.slow) && {
@@ -1548,7 +1676,8 @@ export function makeApplication(config) {
         return makeRuntime({
             ...baseConfig,
             Flags: config.Flags,
-            flags: Option.some(config.flags),
+            configuredFlags: Option.none(),
+            isFlagsRequired: true,
             init: (flags, url) => config.init(flags, url ?? currentUrl),
         });
     }
@@ -1556,7 +1685,8 @@ export function makeApplication(config) {
         return makeRuntime({
             ...baseConfig,
             Flags: Schema.Void,
-            flags: Option.none(),
+            configuredFlags: Option.none(),
+            isFlagsRequired: false,
             init: (_flags, url) => config.init(url ?? currentUrl),
         });
     }
@@ -1564,7 +1694,8 @@ export function makeApplication(config) {
         return makeRuntime({
             ...baseConfig,
             Flags: config.Flags,
-            flags: Option.some(config.flags),
+            configuredFlags: Option.none(),
+            isFlagsRequired: true,
             init: (flags) => config.init(flags),
         });
     }
@@ -1572,7 +1703,8 @@ export function makeApplication(config) {
         return makeRuntime({
             ...baseConfig,
             Flags: Schema.Void,
-            flags: Option.none(),
+            configuredFlags: Option.none(),
+            isFlagsRequired: false,
             init: () => config.init(),
         });
     }
@@ -1610,6 +1742,7 @@ export function makeElement(config) {
     });
     const crash = toCrashConfig(config.crash);
     const baseConfig = {
+        kind: 'Element',
         Model: config.Model,
         update: config.update,
         view,
@@ -1640,7 +1773,8 @@ export function makeElement(config) {
         return makeRuntime({
             ...baseConfig,
             Flags: config.Flags,
-            flags: Option.some(config.flags),
+            configuredFlags: Option.some(config.flags),
+            isFlagsRequired: true,
             init: (flags) => config.init(flags),
         });
     }
@@ -1648,7 +1782,8 @@ export function makeElement(config) {
         return makeRuntime({
             ...baseConfig,
             Flags: Schema.Void,
-            flags: Option.none(),
+            configuredFlags: Option.none(),
+            isFlagsRequired: false,
             init: () => config.init(),
         });
     }
@@ -1716,6 +1851,20 @@ const resolveHmrModel = (runtimeId) => {
         return Effect.succeed(undefined);
     }));
 };
+/** Starts a program Effect with explicit boot inputs for runtime tests.
+ * @internal */
+export const __startProgram = (program, hmrModel, bootMode, flags) => {
+    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);
+};
 // 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
@@ -1727,11 +1876,25 @@ const resolveHmrModel = (runtimeId) => {
 // 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);
-/** 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) => {
-    runMainWithoutUnloadInterrupt(provideBrowserScheduler(Effect.flatMap(resolveHmrModel(program.runtimeId), program.start)));
+const startProgram = (program, bootMode, flags) => {
+    runMainWithoutUnloadInterrupt(provideBrowserScheduler(Effect.flatMap(resolveHmrModel(program.runtimeId), hmrModel => __startProgram(program, hmrModel, bootMode, flags))));
+};
+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, missing Flags
+ *  payload, or undecodable payload terminates startup and leaves the server
+ *  HTML visible but inert. 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) => {
+    startProgram(program, 'Hydrate');
 };
 const buildPortHandles = (ports, connector) => {
     const handles = {};
@@ -1750,32 +1913,7 @@ const buildPortHandles = (ports, connector) => {
     /* 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) => {
+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.');
@@ -1795,7 +1933,7 @@ export const embed = (program) => {
     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)));
+    }), 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;
@@ -1810,4 +1948,4 @@ export const embed = (program) => {
     };
     const ports = buildPortHandles(program.ports, connector);
     return { ports, dispose };
-};
+}

package/dist/snabbdom/h.d.ts

@@ -4,6 +4,7 @@ export type VNodeChildElement = VNode | string | number | String | Number | unde
 export type ArrayOrElement<T> = T | Array<T>;
 export type VNodeChildren = ArrayOrElement<VNodeChildElement>;
 export declare function addNS(data: any, children: Array<VNode | string> | undefined, sel: string | undefined): void;
+export declare function addMathmlNS(data: any, children: Array<VNode | string> | undefined, sel: string | undefined): void;
 export declare function h(sel: string): VNode;
 export declare function h(sel: string, data: VNodeData | null): VNode;
 export declare function h(sel: string, children: VNodeChildren): VNode;

package/dist/snabbdom/h.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"h.d.ts","sourceRoot":"","sources":["../../src/snabbdom/h.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAS,MAAM,YAAY,CAAA;AAE9D,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAA;AACjC,MAAM,MAAM,iBAAiB,GACzB,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,IAAI,CAAA;AACR,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;AAC5C,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,iBAAiB,CAAC,CAAA;AAE7D,wBAAgB,KAAK,CACnB,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,SAAS,EAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,IAAI,CAYN;AAED,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;AACrC,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,KAAK,CAAA;AAC7D,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,KAAK,CAAA;AAC9D,wBAAgB,CAAC,CACf,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,GAAG,IAAI,EACtB,QAAQ,EAAE,aAAa,GACtB,KAAK,CAAA"}
+{"version":3,"file":"h.d.ts","sourceRoot":"","sources":["../../src/snabbdom/h.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAS,MAAM,YAAY,CAAA;AAE9D,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAA;AACjC,MAAM,MAAM,iBAAiB,GACzB,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,IAAI,CAAA;AACR,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;AAC5C,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,iBAAiB,CAAC,CAAA;AAsD7D,wBAAgB,KAAK,CACnB,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,SAAS,EAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,IAAI,CAQN;AA6DD,wBAAgB,WAAW,CACzB,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,SAAS,EAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,IAAI,CAEN;AAED,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;AACrC,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,KAAK,CAAA;AAC7D,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,KAAK,CAAA;AAC9D,wBAAgB,CAAC,CACf,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,GAAG,IAAI,EACtB,QAAQ,EAAE,aAAa,GACtB,KAAK,CAAA"}

package/dist/snabbdom/h.js

@@ -1,18 +1,95 @@
+import { tagNameFromSelector } from '../tagName.js';
 import * as is from './is.js';
 import { vnode } from './vnode.js';
-export function addNS(data, children, sel) {
-    data.ns = 'http://www.w3.org/2000/svg';
-    if (sel !== 'foreignObject' && children !== undefined) {
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+const MATHML_NAMESPACE = 'http://www.w3.org/1998/Math/MathML';
+// NOTE: inside SVG, the content of foreignObject, desc, and title is parsed in
+// the HTML namespace (SVG's HTML integration points), so the SVG namespace must
+// not propagate into their children.
+const SVG_HTML_INTEGRATION_POINTS = new Set(['foreignObject', 'desc', 'title']);
+// NOTE: inside a MathML text integration point (mi, mo, mn, ms, mtext) the
+// content is parsed as HTML, so the MathML namespace stops there, except for
+// mglyph and malignmark, which the parser keeps in the MathML namespace. A
+// MathML annotation-xml element is an HTML integration point when its encoding
+// is text/html or application/xhtml+xml, so its children are HTML too.
+const MATHML_TEXT_INTEGRATION_POINTS = new Set([
+    'mi',
+    'mo',
+    'mn',
+    'ms',
+    'mtext',
+]);
+const MATHML_TEXT_INTEGRATION_EXCEPTIONS = new Set(['mglyph', 'malignmark']);
+const MATHML_HTML_ENCODINGS = new Set(['text/html', 'application/xhtml+xml']);
+const propagateNamespace = (data, children, sel, namespace, integrationPoints) => {
+    data.ns = namespace;
+    if ((sel === undefined || !integrationPoints.has(sel)) &&
+        children !== undefined) {
         for (let i = 0; i < children.length; ++i) {
             const child = children[i];
             if (typeof child === 'string')
                 continue;
             const childData = child.data;
             if (childData !== undefined) {
-                addNS(childData, child.children, child.sel);
+                propagateNamespace(childData, child.children, child.sel, namespace, integrationPoints);
             }
         }
     }
+};
+export function addNS(data, children, sel) {
+    propagateNamespace(data, children, sel, SVG_NAMESPACE, SVG_HTML_INTEGRATION_POINTS);
+}
+// NOTE: an annotation-xml is an HTML integration point when its encoding
+// attribute is text/html or application/xhtml+xml. HTML attribute names are
+// case-insensitive, so the name is matched case-insensitively as well as the
+// value.
+const isHtmlIntegrationAnnotationXml = (data) => {
+    const attrs = data?.attrs;
+    if (attrs === undefined || attrs === null) {
+        return false;
+    }
+    for (const name of Object.keys(attrs)) {
+        if (name.toLowerCase() === 'encoding') {
+            const value = attrs[name];
+            return (typeof value === 'string' &&
+                MATHML_HTML_ENCODINGS.has(value.toLowerCase()));
+        }
+    }
+    return false;
+};
+// NOTE: MathML namespace propagation carries the integration-point exceptions
+// the generic walk cannot express: children of a text integration point are
+// HTML except mglyph and malignmark, and children of an annotation-xml with an
+// HTML encoding are HTML. Everything else inherits the MathML namespace.
+const propagateMathmlNamespace = (data, children, sel) => {
+    data.ns = MATHML_NAMESPACE;
+    if (children === undefined) {
+        return;
+    }
+    const tag = sel === undefined ? undefined : tagNameFromSelector(sel);
+    if (tag === 'annotation-xml' && isHtmlIntegrationAnnotationXml(data)) {
+        return;
+    }
+    const isTextIntegrationPoint = tag !== undefined && MATHML_TEXT_INTEGRATION_POINTS.has(tag);
+    for (let i = 0; i < children.length; ++i) {
+        const child = children[i];
+        if (typeof child === 'string')
+            continue;
+        const childData = child.data;
+        if (childData === undefined)
+            continue;
+        if (isTextIntegrationPoint) {
+            const childTag = child.sel === undefined ? undefined : tagNameFromSelector(child.sel);
+            if (childTag === undefined ||
+                !MATHML_TEXT_INTEGRATION_EXCEPTIONS.has(childTag)) {
+                continue;
+            }
+        }
+        propagateMathmlNamespace(childData, child.children, child.sel);
+    }
+};
+export function addMathmlNS(data, children, sel) {
+    propagateMathmlNamespace(data, children, sel);
 }
 export function h(sel, b, c) {
     let data = {};
@@ -57,5 +134,9 @@ export function h(sel, b, c) {
         (sel.length === 3 || sel[3] === '.' || sel[3] === '#')) {
         addNS(data, children, sel);
     }
+    else if (sel.startsWith('math') &&
+        (sel.length === 4 || sel[4] === '.' || sel[4] === '#')) {
+        addMathmlNS(data, children, sel);
+    }
     return vnode(sel, data, children, text, undefined);
 }

package/dist/snabbdom/tovnode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tovnode.d.ts","sourceRoot":"","sources":["../../src/snabbdom/tovnode.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAc,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,KAAK,KAAK,EAAS,MAAM,YAAY,CAAA;AAc9C,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAiD1D"}
+{"version":3,"file":"tovnode.d.ts","sourceRoot":"","sources":["../../src/snabbdom/tovnode.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAc,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,KAAK,KAAK,EAAS,MAAM,YAAY,CAAA;AAc9C,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAsD1D"}

package/dist/snabbdom/tovnode.js

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
-import { addNS } from './h.js';
+import { addMathmlNS, addNS } from './h.js';
 import { htmlDomApi } from './htmldomapi.js';
 import { vnode } from './vnode.js';
 /**
@@ -53,6 +53,10 @@ export function toVNode(node, domApi) {
             (sel.length === 3 || sel[3] === '.' || sel[3] === '#')) {
             addNS(data, children, sel);
         }
+        else if (sel.startsWith('math') &&
+            (sel.length === 4 || sel[4] === '.' || sel[4] === '#')) {
+            addMathmlNS(data, children, sel);
+        }
         return vnode(sel, data, children, undefined, node);
     }
     else if (api.isText(node)) {

package/dist/tagName.d.ts

@@ -0,0 +1,6 @@
+/** Extracts the tag name from a snabbdom selector, dropping any `#id` or
+ *  `.class` suffix. Foldkit builds bare-tag selectors, so in practice this
+ *  returns the selector unchanged, but the id/class handling keeps it correct
+ *  for any selector snabbdom itself would accept. */
+export declare const tagNameFromSelector: (selector: string) => string;
+//# sourceMappingURL=tagName.d.ts.map

package/dist/tagName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagName.d.ts","sourceRoot":"","sources":["../src/tagName.ts"],"names":[],"mappings":"AAAA;;;qDAGqD;AACrD,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,MAMtD,CAAA"}