foldkit 0.146.0 → 0.148.0

package/dist/runtime/runtime.js

@@ -1,8 +1,11 @@
 import { Array, Cause, Context, Duration, Effect, Exit, Fiber, Function, Layer, Match, Option, Predicate, PubSub, Record, Ref, Runtime, Scheduler, Schema, Stream, SubscriptionRef, pipe, } from 'effect';
+import { HYDRATION_BUILD_ATTRIBUTE } from '../buildToken.js';
 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 +194,205 @@ 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 flagsScripts = pipe(Array.fromIterable(document.querySelectorAll(`script[${FOLDKIT_FLAGS_ATTRIBUTE}]`)), Array.filter(script => script.getAttribute(FOLDKIT_FLAGS_ATTRIBUTE) === runtimeId));
+    return { root, runtimeId, flagsScripts, 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.
+// A runtime id names one application for the whole page: it pairs a root with
+// its Flags payload, and it keys the Model and scroll position hot reloading
+// preserves. Two roots sharing one are not two applications but one claimed
+// twice, so whichever boots second would read the other's handoff and restore
+// the other's Model. `injectIntoTemplate` refuses to build such a page; this is
+// the check for a page assembled some other way.
+//
+// Distinct ids do not make two hydrated applications independent, which is not
+// a supported arrangement: each page-owning application rewrites the document's
+// metadata and installs document-wide navigation listeners.
+const assertRuntimeIdsAreUnique = (stampedRoots) => {
+    const seen = new Set();
+    for (const root of stampedRoots) {
+        const runtimeId = root.getAttribute(FOLDKIT_APP_ATTRIBUTE) ?? '';
+        if (seen.has(runtimeId)) {
+            containRefusedPage(root.ownerDocument);
+            throw new Error(`[foldkit] Found more than one server-rendered root stamped ` +
+                `"${runtimeId}". A runtime id names one application for the whole ` +
+                'page: it pairs a root with its Flags payload and keys the Model and ' +
+                'scroll position hot reloading preserves, so two roots sharing one ' +
+                "would take each other's state. Render each application with its " +
+                'own `runtimeId`.');
+        }
+        seen.add(runtimeId);
+    }
+};
+// The reason this page cannot be adopted by this client, or `undefined` when
+// the two name the same deployment.
+//
+// The client's id is required and must be non-empty. An absent one would
+// otherwise equal the absent marker on a page served before build ids existed,
+// which reads a page from an unknown deployment as one of this build's own: the
+// exact case the id exists to refuse.
+const buildSkew = (root, buildId, runtimeId) => {
+    if (buildId === undefined || buildId === '') {
+        return new Error('[foldkit] Runtime.hydrate was given no build id. Hydration compares ' +
+            'the id the server stamped on the root with this client’s own before ' +
+            'it adopts any DOM, and without one a page from any deployment would ' +
+            'be adopted as this one. Pass ' +
+            '`buildId: import.meta.env.FOLDKIT_BUILD_ID`, the same value the ' +
+            'server entry passes to `renderToString`.');
+    }
+    const servedBuild = root.getAttribute(HYDRATION_BUILD_ATTRIBUTE);
+    if (servedBuild === buildId) {
+        return undefined;
+    }
+    return new Error(`[foldkit] Runtime.hydrate found application "${runtimeId}" served by ` +
+        `${servedBuild === null ? 'no known deployment' : `deployment "${servedBuild}"`}` +
+        `, but this client belongs to deployment "${buildId}". Startup stops ` +
+        'here rather than reading a handoff written by other code: the Flags in ' +
+        'the page are that deployment’s, and this build could accept them while ' +
+        'every value in them means something else. Serve the page from the ' +
+        'running deployment, and keep stale HTML out of shared caches.');
+};
+const REFUSED_ATTRIBUTE = 'data-foldkit-refused';
+const REFUSAL_SHIELD_ATTRIBUTE = 'data-foldkit-refusal-shield';
+const refusalShields = new WeakMap();
+const REFUSAL_SHIELD_INPUT_EVENTS = [
+    'auxclick',
+    'click',
+    'contextmenu',
+    'dblclick',
+    'keydown',
+    'keypress',
+    'keyup',
+    'mousedown',
+    'mouseup',
+    'pointerdown',
+    'pointerup',
+    'touchend',
+    'touchstart',
+];
+const preventRefusalShieldInteraction = (event) => {
+    event.preventDefault();
+    event.stopImmediatePropagation();
+};
+const openRefusalShield = (shield) => {
+    shield.inert = true;
+    shield.setAttribute('inert', '');
+    if (shield.open && typeof shield.close === 'function') {
+        shield.close();
+    }
+    if (typeof shield.showModal === 'function') {
+        shield.showModal();
+    }
+    else {
+        shield.setAttribute('open', '');
+    }
+    shield.inert = false;
+    shield.removeAttribute('inert');
+    shield.focus({ preventScroll: true });
+};
+const installRefusalShield = (ownerDocument) => {
+    const existing = refusalShields.get(ownerDocument);
+    if (existing !== undefined && existing.isConnected) {
+        openRefusalShield(existing);
+        return;
+    }
+    const shield = ownerDocument.createElement('dialog');
+    shield.setAttribute(REFUSAL_SHIELD_ATTRIBUTE, '');
+    shield.setAttribute('aria-label', 'Page unavailable');
+    shield.setAttribute('aria-modal', 'true');
+    shield.setAttribute('closedby', 'none');
+    shield.tabIndex = -1;
+    shield.textContent =
+        'This page could not start safely. Reload to get the current version.';
+    shield.style.alignItems = 'center';
+    shield.style.background = 'rgba(15, 23, 42, 0.96)';
+    shield.style.border = '0';
+    shield.style.boxSizing = 'border-box';
+    shield.style.color = 'white';
+    shield.style.font = '600 1rem/1.5 system-ui, sans-serif';
+    shield.style.display = 'grid';
+    shield.style.height = '100vh';
+    shield.style.inset = '0';
+    shield.style.margin = '0';
+    shield.style.maxHeight = 'none';
+    shield.style.maxWidth = 'none';
+    shield.style.overflow = 'hidden';
+    shield.style.padding = '2rem';
+    shield.style.position = 'fixed';
+    shield.style.touchAction = 'none';
+    shield.style.userSelect = 'none';
+    shield.style.width = '100vw';
+    shield.addEventListener('cancel', preventRefusalShieldInteraction);
+    for (const eventName of REFUSAL_SHIELD_INPUT_EVENTS) {
+        shield.addEventListener(eventName, preventRefusalShieldInteraction, {
+            capture: true,
+            passive: false,
+        });
+    }
+    ownerDocument.documentElement.appendChild(shield);
+    refusalShields.set(ownerDocument, shield);
+    openRefusalShield(shield);
+};
+const containRefusedPage = (ownerDocument) => {
+    const boundary = ownerDocument.body ?? ownerDocument.documentElement;
+    boundary.inert = true;
+    boundary.setAttribute('inert', '');
+    boundary.setAttribute('aria-hidden', 'true');
+    boundary.setAttribute(REFUSED_ATTRIBUTE, '');
+    installRefusalShield(ownerDocument);
+};
+// Whether this page carries anything a Foldkit server render leaves behind. A
+// resolution failure on such a page is a refused handoff, and the markup is
+// contained; the same failure on a page with none of these markers is a client
+// application whose container never existed, where there is no server render to
+// refuse and nothing to take out of reach.
+const hasServerRenderedMarkup = (ownerDocument) => ownerDocument.querySelector(`[${FOLDKIT_APP_ATTRIBUTE}], [${HYDRATION_BUILD_ATTRIBUTE}], ` +
+    `[${FOLDKIT_FLAGS_ATTRIBUTE}]`) !== null;
+const findDocumentHydration = (container, isFlagsRequired) => {
+    const stampedRoots = Array.fromIterable(document.querySelectorAll(`[${FOLDKIT_APP_ATTRIBUTE}]`));
+    assertRuntimeIdsAreUnique(stampedRoots);
+    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) {
+        containRefusedPage(document);
+        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 +516,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 +554,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, buildId) => {
         // 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 +566,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 +639,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 +676,102 @@ 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,
             });
+            // Every hydration refusal that knows which root it was going to adopt
+            // contains that root first. The build id is one reason to refuse; a
+            // missing, duplicated, malformed, or Schema-incompatible Flags payload
+            // is another, and the page left behind is just as live in each case.
+            const refuseHydration = (root, message, cause) => {
+                containRefusedPage(root.ownerDocument);
+                return Effect.die(cause === undefined
+                    ? new Error(message)
+                    : new Error(message, { cause }));
+            };
+            const decodeFlagsPayload = (payload, runtimeId, root) => 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 => cause,
+            }).pipe(Effect.catch(cause => refuseHydration(root, '[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)));
+            const maybeRequestedHydration = bootMode === 'Hydrate'
+                ? Option.fromNullishOr(hydration)
+                : Option.none();
+            if (bootMode === 'Hydrate' && Option.isNone(maybeRequestedHydration)) {
+                // A hydrating client that finds no stamped root will not adopt
+                // whatever the page holds, so the page is contained whether or not the
+                // caller named a container.
+                containRefusedPage(container === null ? document : container.ownerDocument);
+                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.'));
+            }
+            // The build the served page came from is settled here, before the Flags
+            // payload text is accessed, parsed, or decoded, before `init` runs, and
+            // therefore before any Command, Subscription, ManagedResource, or port
+            // this boot would start. A page from another deployment carries that
+            // deployment's Flags, which the current Schema may well accept while
+            // every value in them means something else, so deferring the comparison
+            // to the DOM patch lets stale data reach new code that already acted on
+            // it.
+            if (Option.isSome(maybeRequestedHydration)) {
+                const skew = buildSkew(maybeRequestedHydration.value.root, buildId, maybeRequestedHydration.value.runtimeId);
+                if (skew !== undefined) {
+                    containRefusedPage(maybeRequestedHydration.value.root.ownerDocument);
+                    return yield* Effect.die(skew);
+                }
+            }
+            // 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.flagsScripts, {
+                        onEmpty: () => refuseHydration(requestedHydration.root, '[foldkit] Runtime.hydrate found application ' +
+                            `"${requestedHydration.runtimeId}" but its ` +
+                            'server Flags payload is missing.'),
+                        onNonEmpty: ([payloadScript, ...remainingScripts]) => Array.isArrayNonEmpty(remainingScripts)
+                            ? refuseHydration(requestedHydration.root, '[foldkit] Runtime.hydrate found multiple ' +
+                                'server Flags payloads for application ' +
+                                `"${requestedHydration.runtimeId}".`)
+                            : decodeFlagsPayload(payloadScript.textContent ?? '', requestedHydration.runtimeId, requestedHydration.root),
+                    })
+                    : /* 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 +921,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 +1229,28 @@ 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);
+                        // An empty id reaches the adoption step's own check as a
+                        // value that matches nothing. Boot already refused a
+                        // hydration without an id, so this stands in only for a
+                        // caller that reached here another way.
+                        return __hydrateVNode(hydrationRoot, nextVNode, boundaryRegistry.dedupeSeen, buildId ?? '');
+                    }
+                    return __patchVNode(maybeCurrentVNode, nextVNode, container, boundaryRegistry.dedupeSeen);
+                }));
                 vnodeSlot.maybeCurrentVNode = Option.some(patchedVNode);
                 reportSlowPhase(maybeLiveSlowPatch, maybePatchDuration, (durationMs, thresholdMs) => ({
                     _tag: 'Patch',
@@ -1372,10 +1681,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, buildId) => startWith(maybeConnector, hmrModel, bootMode, flags, buildId),
+        kind,
         isEmbedActive: false,
         maybeActiveFiber: Option.none(),
     });
@@ -1390,11 +1704,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 +1740,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 +1812,37 @@ 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) {
+        // A server-rendered page whose root lost its stamp reaches exactly here:
+        // template injection put the render where the placeholder was, so
+        // `getElementById` finds nothing and the stamp that would have named the
+        // root is gone. There is no handoff to refuse further along, and the markup
+        // is as live as any other refused page, so it is contained here.
+        if (hasServerRenderedMarkup(document)) {
+            containRefusedPage(document);
+        }
         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 +1870,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 +1879,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 +1888,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 +1897,8 @@ export function makeApplication(config) {
         return makeRuntime({
             ...baseConfig,
             Flags: Schema.Void,
-            flags: Option.none(),
+            configuredFlags: Option.none(),
+            isFlagsRequired: false,
             init: () => config.init(),
         });
     }
@@ -1610,6 +1936,7 @@ export function makeElement(config) {
     });
     const crash = toCrashConfig(config.crash);
     const baseConfig = {
+        kind: 'Element',
         Model: config.Model,
         update: config.update,
         view,
@@ -1640,7 +1967,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 +1976,8 @@ export function makeElement(config) {
         return makeRuntime({
             ...baseConfig,
             Flags: Schema.Void,
-            flags: Option.none(),
+            configuredFlags: Option.none(),
+            isFlagsRequired: false,
             init: () => config.init(),
         });
     }
@@ -1716,6 +2045,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, 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
@@ -1727,11 +2070,34 @@ 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, 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, a root stamped more
+ *  than once, more than one root with no container to choose between them, 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 native links, forms, controls,
+ *  and focus targets stop responding. 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 or
+ *  event sandbox: existing capture-phase handlers, browser-generated top-layer
+ *  events, timers, and other stale scripts can still run and can 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);
 };
 const buildPortHandles = (ports, connector) => {
     const handles = {};
@@ -1750,32 +2116,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 +2136,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 +2151,4 @@ export const embed = (program) => {
     };
     const ports = buildPortHandles(program.ports, connector);
     return { ports, dispose };
-};
+}