foldkit 0.157.0 → 0.158.0

package/dist/runtime/hydrationHandoff.js

@@ -0,0 +1,395 @@
+import { Array, Effect, Option, Predicate, Schema, pipe } from 'effect';
+import { HYDRATION_BUILD_ATTRIBUTE } from '../buildToken.js';
+import { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE, } from '../hydrationMarker.js';
+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. A container outside that root is a refused handoff, not a fresh
+// application beside server markup that remains live. 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.
+// 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 (runtimeId === '') {
+            containRefusedPage(root.ownerDocument);
+            throw new Error('[foldkit] Found a server-rendered root with an empty ' +
+                `\`${FOLDKIT_APP_ATTRIBUTE}\` stamp. A hydratable root must carry ` +
+                'a nonempty runtime id so the runtime can pair it with its Flags ' +
+                'payload and preserved HMR state.');
+        }
+        if (!root.ownerDocument.body?.contains(root)) {
+            containRefusedPage(root.ownerDocument);
+            throw new Error('[foldkit] Found a server-rendered root outside the document body. ' +
+                'Runtime.hydrate supports one page-owning application in the ' +
+                'document light DOM. Do not hydrate a root in the head, a shadow ' +
+                'tree, or a detached subtree.');
+        }
+        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. Remove the duplicate root. Foldkit " +
+                'hydrates one page-owning application per document.');
+        }
+        seen.add(runtimeId);
+    }
+};
+const assertSinglePageApplication = (stampedRoots) => {
+    if (stampedRoots.length > 1) {
+        containRefusedPage(document);
+        throw new Error('[foldkit] Found more than one page-owning application stamped with ' +
+            `\`${FOLDKIT_APP_ATTRIBUTE}\`. Hydrating multiple applications in ` +
+            'one document is not supported: each application owns the document ' +
+            'metadata and installs document-wide navigation listeners. Render ' +
+            'one application per page.');
+    }
+};
+// 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.
+export const buildSkew = (root, buildId, runtimeId) => {
+    if (!Predicate.isString(buildId) || 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.');
+};
+// Take the served page out of reach before startup stops.
+//
+// Refusing to adopt a page keeps this build's code away from it, but the markup
+// is still a live document: its links navigate, its forms submit to whatever
+// action the deployment that wrote them intended, and its controls take focus.
+// A visitor who clicks after a failed handoff would be acting on a page with no
+// running code to reconsider.
+//
+// The boundary is an element the served page already has, marked in place.
+// Nothing moves. Wrapping the root in a fresh inert element would reparent it:
+// every upgraded custom element in the subtree would run `disconnectedCallback`
+// and then `connectedCallback` again, and every embedded browsing context would
+// reload. Marking a stable ancestor costs neither.
+//
+// That ancestor is the document's body, which is where a hydratable root always
+// sits: `renderToString` refuses to render `html`, `head`, or `body` as the
+// root, and `hydrate` is for an application that owns the page. Inertness
+// propagates from an inert HTML element to every descendant whatever their
+// namespace, so an SVG or MathML root is covered too. `inert` is an HTML
+// attribute, so marking such a root directly would only create an expando.
+// Verified in Chromium for HTML, SVG foreign content, and MathML.
+//
+// A modal dialog lives in the top layer, where ancestor inertness does not reach
+// it. The refusal shield is itself a modal dialog opened after the served page's
+// top-layer content, so it covers an old dialog even inside a closed shadow
+// root. It is a sibling of `body`, outside the inert and `aria-hidden` boundary,
+// covers the viewport, and refuses its cancel action. Existing dialogs are not
+// closed: calling author-owned `close` or `cancel` listeners while startup is
+// failing can run arbitrary stale code. Same-document input guards stop
+// physical keyboard input if older top-layer content requests focus.
+//
+// This runs when the client reaches the failure, so it cannot undo what the page
+// already did: subresources the parser fetched, custom elements that upgraded,
+// scripts the served deployment authored, or anything a visitor managed before
+// the client entry ran. Nor is this a script sandbox. A capture listener on
+// `window` or `document` runs before an event reaches the shield, and a timer or
+// listener can open newer top-layer UI. The boundary stops pointer and physical
+// keyboard input from activating the old page's same-document native links,
+// forms, and controls without reconnecting its DOM.
+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 REFUSAL_DOCUMENT_INPUT_EVENTS = ['keydown', 'keypress', 'keyup'];
+const preventRefusalShieldInteraction = (event) => {
+    event.preventDefault();
+    event.stopImmediatePropagation();
+};
+// NOTE: `showModal` throws when the owning document is not fully active. A
+// foreign or detached document still needs the original Foldkit refusal rather
+// than a browser exception from its containment UI.
+const tryOpenRefusalShieldAsModal = (shield) => {
+    if (typeof shield.showModal !== 'function') {
+        return false;
+    }
+    try {
+        shield.showModal();
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const openRefusalShield = (shield) => {
+    shield.inert = true;
+    shield.setAttribute('inert', '');
+    if (shield.open && typeof shield.close === 'function') {
+        shield.close();
+    }
+    if (!tryOpenRefusalShieldAsModal(shield)) {
+        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,
+        });
+    }
+    for (const eventName of REFUSAL_DOCUMENT_INPUT_EVENTS) {
+        ownerDocument.addEventListener(eventName, preventRefusalShieldInteraction, {
+            capture: true,
+            passive: false,
+        });
+    }
+    ownerDocument.documentElement.appendChild(shield);
+    refusalShields.set(ownerDocument, shield);
+    openRefusalShield(shield);
+};
+export 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.
+export const hasServerRenderedMarkup = (ownerDocument) => ownerDocument.querySelector(`[${FOLDKIT_APP_ATTRIBUTE}], [${HYDRATION_BUILD_ATTRIBUTE}], ` +
+    `[${FOLDKIT_FLAGS_ATTRIBUTE}]`) !== null;
+export const findDocumentHydration = (container, isFlagsRequired) => {
+    const stampedRoots = Array.fromIterable(document.querySelectorAll(`[${FOLDKIT_APP_ATTRIBUTE}]`));
+    assertRuntimeIdsAreUnique(stampedRoots);
+    assertSinglePageApplication(stampedRoots);
+    if (container !== null) {
+        const stampedAncestor = container.closest(`[${FOLDKIT_APP_ATTRIBUTE}]`);
+        if (container.hasAttribute(FOLDKIT_APP_ATTRIBUTE)) {
+            const isDocumentRoot = Option.match(Array.head(stampedRoots), {
+                onNone: () => false,
+                onSome: root => root === container,
+            });
+            if (!isDocumentRoot) {
+                containRefusedPage(container.ownerDocument);
+                throw new Error('[foldkit] Runtime.hydrate received a stamped container that is ' +
+                    'not the single server root in the document light DOM. Hydration ' +
+                    'supports one page-owning application under the document body. ' +
+                    'Do not hydrate a root in a shadow tree or detached subtree.');
+            }
+            return hydrationForRoot(container, isFlagsRequired);
+        }
+        return Array.match(stampedRoots, {
+            onEmpty: () => {
+                if (stampedAncestor === null) {
+                    return undefined;
+                }
+                containRefusedPage(container.ownerDocument);
+                throw new Error('[foldkit] Runtime.hydrate received a container under a stamped ' +
+                    'root outside the document body light DOM. Do not hydrate a root ' +
+                    'in a shadow tree, detached subtree, or another document.');
+            },
+            onNonEmpty: roots => {
+                const onlyRoot = Array.headNonEmpty(roots);
+                if (stampedAncestor === onlyRoot) {
+                    return hydrationForRoot(onlyRoot, isFlagsRequired);
+                }
+                containRefusedPage(container.ownerDocument);
+                throw new Error('[foldkit] Runtime.hydrate received a container outside the ' +
+                    "document's server-rendered application root. A page-owning " +
+                    'application must adopt that single root rather than boot beside ' +
+                    'server markup it does not own.');
+            },
+        });
+    }
+    return Option.match(Array.head(stampedRoots), {
+        onNone: () => undefined,
+        onSome: root => hydrationForRoot(root, isFlagsRequired),
+    });
+};
+/**
+ * Decides whether this boot adopts the server-rendered root and where its
+ * Flags come from. A hydrating boot with no stamped root, a root served by
+ * another deployment, or a missing, duplicated, or undecodable Flags
+ * payload contains the served page and stops startup. The build id is
+ * compared before the payload text is read and before `init` runs, so
+ * nothing acts on another deployment's data. An HMR-restored Model skips
+ * adoption and gets a fresh patch against the stamped root.
+ */
+export const resolveHydrationHandoff = ({ bootMode, hydration, bootFlags, configuredFlags, isFlagsRequired, FlagsCodec, hmrModel, container, buildId, provideResources, }) => Effect.gen(function* () {
+    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,
+    });
+    return { maybeHydrationRoot, resolveFlags };
+});

package/dist/runtime/index.d.ts

@@ -1,2 +1,17 @@
-export * from './runtime.js';
+export type { RoutingConfig } from './browserListeners.js';
+export type { CrashConfig, CrashContext, ElementCrashConfig, } from './crashUI.js';
+export type { DevToolsConfig, DevToolsMode, DevToolsModeConfig, DevToolsPosition, } from './devToolsConfig.js';
+export { Dispatch } from './dispatch.js';
+export type { EmbedHandle, InboundPortHandle, InboundPortHandles, OutboundPortHandle, OutboundPortHandles, PortHandles, } from './hostConnector.js';
+export { makeApplication } from './makeApplication.js';
+export type { ApplicationConfig, ApplicationConfigWithFlags, ApplicationInit, RoutingApplicationConfig, RoutingApplicationConfigWithFlags, RoutingApplicationInit, } from './makeApplication.js';
+export { makeElement } from './makeElement.js';
+export type { ElementConfig, ElementConfigWithFlags, ElementInit, } from './makeElement.js';
+export type { MakeRuntimeReturn } from './runtime.js';
+export { SlowPhase, defaultSlowCallback } from './slowPhase.js';
+export type { SlowConfig, SlowContext, SlowPatchContext, SlowSubscriptionDependenciesContext, SlowThresholdOverrides, SlowUpdateContext, SlowViewContext, } from './slowPhase.js';
+export { embed, hydrate, run } from './start.js';
+export type { HydrateOptions, RunOptions } from './start.js';
+export type { ViewTransitionConfig, ViewTransitionContext, ViewTransitionDecision, } from './viewTransition.js';
+export type { Visibility } from './visibility.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,YAAY,EACV,WAAW,EACX,YAAY,EACZ,kBAAkB,GACnB,MAAM,cAAc,CAAA;AAErB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,GACZ,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,YAAY,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,eAAe,EACf,wBAAwB,EACxB,iCAAiC,EACjC,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,YAAY,EACV,aAAa,EACb,sBAAsB,EACtB,WAAW,GACZ,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAErD,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAE/D,YAAY,EACV,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,mCAAmC,EACnC,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AAEhD,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5D,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,qBAAqB,CAAA;AAE5B,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/runtime/index.js

@@ -1 +1,5 @@
-export * from './runtime.js';
+export { Dispatch } from './dispatch.js';
+export { makeApplication } from './makeApplication.js';
+export { makeElement } from './makeElement.js';
+export { SlowPhase, defaultSlowCallback } from './slowPhase.js';
+export { embed, hydrate, run } from './start.js';

package/dist/runtime/makeApplication.d.ts

@@ -0,0 +1,71 @@
+import { Layer, Schema } from 'effect';
+import { Document, type HtmlBuilder } from '../html/index.js';
+import type { ManagedResources } from '../managedResource/index.js';
+import type { Ports } from '../port/index.js';
+import type { Subscriptions } from '../subscription/subscription.js';
+import type { Return as UpdateReturn } from '../update/index.js';
+import { Url } from '../url/index.js';
+import type { RoutingConfig } from './browserListeners.js';
+import type { CrashConfig } from './crashUI.js';
+import type { DevToolsConfig } from './devToolsConfig.js';
+import { type FlagsSchemaConfig, type MakeRuntimeReturn } from './runtime.js';
+import type { SlowConfig } from './slowPhase.js';
+import type { ViewTransitionConfig } from './viewTransition.js';
+type BaseApplicationConfig<Model, Message, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined> = Readonly<{
+    Model: Schema.Codec<Model, any, unknown, unknown>;
+    update: (model: Model, message: Message) => UpdateReturn<Model, Message, Resources | ManagedResourceServices>;
+    view: (model: Model, h: HtmlBuilder<Message>) => Document;
+    subscriptions?: Subscriptions<Model, Message, Resources | ManagedResourceServices>;
+    container: HTMLElement | null;
+    ports?: P;
+    crash?: CrashConfig<Model, Message>;
+    slow?: SlowConfig<Model, Message>;
+    viewTransition?: ViewTransitionConfig<Model, Message>;
+    freezeModel?: boolean;
+    preserveScroll?: boolean;
+    resources?: Layer.Layer<Resources>;
+    managedResources?: ManagedResources<Model, Message, ManagedResourceServices>;
+    devTools?: DevToolsConfig;
+}>;
+/** Configuration for `makeApplication` with Flags and URL routing. */
+export type RoutingApplicationConfigWithFlags<Model, Message, Flags, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined> = BaseApplicationConfig<Model, Message, Resources, ManagedResourceServices, P> & FlagsSchemaConfig<Flags> & Readonly<{
+    routing: RoutingConfig<Message>;
+    init: (flags: Flags, url: Url) => UpdateReturn<Model, Message, Resources | ManagedResourceServices>;
+}>;
+/** Configuration for `makeApplication` with URL routing but no Flags. */
+export type RoutingApplicationConfig<Model, Message, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined> = BaseApplicationConfig<Model, Message, Resources, ManagedResourceServices, P> & Readonly<{
+    routing: RoutingConfig<Message>;
+    init: (url: Url) => UpdateReturn<Model, Message, Resources | ManagedResourceServices>;
+}>;
+/** Configuration for `makeApplication` with Flags but no URL routing. */
+export type ApplicationConfigWithFlags<Model, Message, Flags, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined> = BaseApplicationConfig<Model, Message, Resources, ManagedResourceServices, P> & FlagsSchemaConfig<Flags> & Readonly<{
+    init: (flags: Flags) => UpdateReturn<Model, Message, Resources | ManagedResourceServices>;
+}>;
+/** Configuration for `makeApplication` without Flags or URL routing. */
+export type ApplicationConfig<Model, Message, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined> = BaseApplicationConfig<Model, Message, Resources, ManagedResourceServices, P> & Readonly<{
+    init: () => UpdateReturn<Model, Message, Resources | ManagedResourceServices>;
+}>;
+/** The `init` function type for a `makeApplication` app without URL routing. */
+export type ApplicationInit<Model, Message, Flags = void, Resources = never, ManagedResourceServices = never> = Flags extends void ? () => UpdateReturn<Model, Message, Resources | ManagedResourceServices> : (flags: Flags) => UpdateReturn<Model, Message, Resources | ManagedResourceServices>;
+/** The `init` function type for a `makeApplication` app with URL routing, receives the current URL and optional Flags. */
+export type RoutingApplicationInit<Model, Message, Flags = void, Resources = never, ManagedResourceServices = never> = Flags extends void ? (url: Url) => UpdateReturn<Model, Message, Resources | ManagedResourceServices> : (flags: Flags, url: Url) => UpdateReturn<Model, Message, Resources | ManagedResourceServices>;
+/** Creates a Foldkit application that owns the page and returns a runtime that
+ *  can be passed to `run`. The `view` returns a `Document`, so the runtime
+ *  manages `document.title` and the canonical / og:url tags. Add a `routing`
+ *  config for URL routing. Use one page-owning application per document. To
+ *  mount an app scoped to a node without touching the document `<head>`, use
+ *  `makeElement`. */
+export declare function makeApplication<Model, Message extends {
+    _tag: string;
+}, Flags, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined>(config: RoutingApplicationConfigWithFlags<Model, Message, Flags, Resources, ManagedResourceServices, P>): MakeRuntimeReturn<P, Flags, Resources, 'Application'>;
+export declare function makeApplication<Model, Message extends {
+    _tag: string;
+}, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined>(config: RoutingApplicationConfig<Model, Message, Resources, ManagedResourceServices, P>): MakeRuntimeReturn<P, void, Resources, 'Application'>;
+export declare function makeApplication<Model, Message extends {
+    _tag: string;
+}, Flags, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined>(config: ApplicationConfigWithFlags<Model, Message, Flags, Resources, ManagedResourceServices, P>): MakeRuntimeReturn<P, Flags, Resources, 'Application'>;
+export declare function makeApplication<Model, Message extends {
+    _tag: string;
+}, Resources = never, ManagedResourceServices = never, P extends Ports | undefined = undefined>(config: ApplicationConfig<Model, Message, Resources, ManagedResourceServices, P>): MakeRuntimeReturn<P, void, Resources, 'Application'>;
+export {};
+//# sourceMappingURL=makeApplication.d.ts.map

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

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

package/dist/runtime/makeApplication.js

@@ -0,0 +1,98 @@
+import { Option, Predicate, Schema } from 'effect';
+import { fromString as urlFromString } from '../url/index.js';
+import { containRefusedPage, findDocumentHydration, hasServerRenderedMarkup, } from './hydrationHandoff.js';
+import { makeRuntime, } from './runtime.js';
+export function makeApplication(config) {
+    const { container } = config;
+    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). On a server-rendered page ' +
+            'the runtime instead finds the root by its `data-foldkit-app` stamp.');
+    }
+    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: resolvedContainer,
+        ...(hydration && { hydration }),
+        ...(hasRouting && { routing: config.routing }),
+        ...(config.crash && { crash: config.crash }),
+        ...(Predicate.isNotUndefined(config.slow) && {
+            slow: config.slow,
+        }),
+        ...(Predicate.isNotUndefined(config.viewTransition) && {
+            viewTransition: config.viewTransition,
+        }),
+        ...(Predicate.isNotUndefined(config.freezeModel) && {
+            freezeModel: config.freezeModel,
+        }),
+        ...(Predicate.isNotUndefined(config.preserveScroll) && {
+            preserveScroll: config.preserveScroll,
+        }),
+        ...(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 && hasRouting) {
+        return makeRuntime({
+            ...baseConfig,
+            Flags: config.Flags,
+            configuredFlags: Option.none(),
+            isFlagsRequired: true,
+            init: (flags, url) => config.init(flags, url ?? currentUrl),
+        });
+    }
+    else if (hasRouting) {
+        return makeRuntime({
+            ...baseConfig,
+            Flags: Schema.Void,
+            configuredFlags: Option.none(),
+            isFlagsRequired: false,
+            init: (_flags, url) => config.init(url ?? currentUrl),
+        });
+    }
+    else if (hasFlags) {
+        return makeRuntime({
+            ...baseConfig,
+            Flags: config.Flags,
+            configuredFlags: Option.none(),
+            isFlagsRequired: true,
+            init: (flags) => config.init(flags),
+        });
+    }
+    else {
+        return makeRuntime({
+            ...baseConfig,
+            Flags: Schema.Void,
+            configuredFlags: Option.none(),
+            isFlagsRequired: false,
+            init: () => config.init(),
+        });
+    }
+    /* eslint-enable @typescript-eslint/consistent-type-assertions */
+}