foldkit 0.148.0 → 0.148.2-canary.34a250d515a4

package/README.md

@@ -18,12 +18,14 @@
 
 ---
 
-Foldkit is a TypeScript frontend framework built on [Effect](https://effect.website/) and architected like [Elm](https://guide.elm-lang.org/architecture/). One Model, one update function, one way to do things. No hooks, no local state, no hidden mutations. It's all in on Effect with no escape hatch, though a program doesn't have to own the whole page: [`Runtime.embed`](https://foldkit.dev/core/embedding) runs a Foldkit widget inside any existing app, React included. The same program also [renders on the server](https://foldkit.dev/core/server-rendering), at build time or per request, and hydrates in place.
+Foldkit is a TypeScript frontend framework built on [Effect](https://effect.website/). It gives your entire application one architecture: a [Schema](https://effect.website/docs/schema/introduction/)-defined Model as the single source of truth, fact-named Messages, an exhaustive update function, and explicit Commands for side effects. Routing, server rendering, UI components, Submodels, and browser lifecycles all use that same Model and Message flow.
 
-Your Model is a [Schema](https://effect.website/docs/schema/introduction/) and side effects are values you return, not callbacks you fire. If you know Effect, Foldkit feels natural. If you're new to it, Foldkit is a good way in. Coming from React? [Start here](https://foldkit.dev/react/coming-from-react), or read the [same pixel-art editor built in both frameworks](https://foldkit.dev/react/foldkit-vs-react-side-by-side).
+Foldkit uses [The Elm Architecture](https://guide.elm-lang.org/architecture/) instead of component-owned state and hook lifecycles. That discipline is a real commitment. Foldkit works best when the team wants shared conventions across the application and is ready to build on Effect throughout. If your backend already uses Effect, Foldkit carries the same tools and patterns into the browser: Schema, services, Streams, and scoped resources.
+
+A Foldkit program can own the whole page or run as a widget inside an existing application, React included, through [`Runtime.embed`](https://foldkit.dev/core/embedding). The same program can [render on the server](https://foldkit.dev/core/server-rendering) at build time or per request, then hydrate in place. Coming from React? [Start here](https://foldkit.dev/react/coming-from-react), or compare the [same pixel-art editor built in both frameworks](https://foldkit.dev/react/foldkit-vs-react-side-by-side).
 
 > [!NOTE]
-> Foldkit is pre-1.0. The core API is stable, but breaking changes may occur in minor releases. See the [changelog](./CHANGELOG.md) for details.
+> Foldkit is in beta and under active development. The core API is stable, but breaking changes may occur in minor releases. See the [changelog](./CHANGELOG.md) for details.
 
 ## Get Started
 
@@ -35,14 +37,14 @@ npx create-foldkit-app@latest
 
 ## Counter
 
-A complete Foldkit program. State lives in a single Model, events become Messages, and a pure function handles every transition. `main.ts` defines the program and `entry.ts` boots the runtime, so `main.ts` stays importable from tests without booting a runtime as a side effect.
+A complete Foldkit program. State lives in a single Model, events become Messages, and a pure function handles every transition. `main.ts` defines the program and `entry.ts` boots the Runtime, so `main.ts` stays importable from tests without booting a Runtime as a side effect.
 
 ```ts
 // src/main.ts
-import { Match as M, Schema as S } from 'effect'
+import { Schema as S } from 'effect'
 import { Command, Runtime } from 'foldkit'
 import { Document, HtmlBuilder } from 'foldkit/html'
-import { m } from 'foldkit/message'
+import { defineMessageUnion } from 'foldkit/message'
 import { evo } from 'foldkit/struct'
 
 // MODEL
@@ -52,32 +54,23 @@ export type Model = typeof Model.Type
 
 // MESSAGE
 
-const ClickedDecrement = m('ClickedDecrement')
-const ClickedIncrement = m('ClickedIncrement')
-const ClickedReset = m('ClickedReset')
-
-export const Message = S.Union([
-  ClickedDecrement,
-  ClickedIncrement,
-  ClickedReset,
-])
+export const Message = defineMessageUnion({
+  ClickedDecrement: {},
+  ClickedIncrement: {},
+  ClickedReset: {},
+})
 export type Message = typeof Message.Type
 
 // UPDATE
 
-export const update = (
-  model: Model,
-  message: Message,
-): readonly [Model, ReadonlyArray<Command.Command<Message>>] =>
-  M.value(message).pipe(
-    M.withReturnType<
-      readonly [Model, ReadonlyArray<Command.Command<Message>>]
-    >(),
-    M.tagsExhaustive({
+export const update = (model: Model, message: Message) =>
+  Message.match<readonly [Model, ReadonlyArray<Command.Command<Message>>]>(
+    message,
+    {
       ClickedDecrement: () => [evo(model, { count: count => count - 1 }), []],
       ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
       ClickedReset: () => [evo(model, { count: () => 0 }), []],
-    }),
+    },
   )
 
 // INIT
@@ -95,9 +88,9 @@ export const view = (model: Model, h: HtmlBuilder<Message>): Document => ({
     [],
     [
       h.p([], [model.count.toString()]),
-      h.button([h.OnClick(ClickedDecrement())], ['-']),
-      h.button([h.OnClick(ClickedReset())], ['Reset']),
-      h.button([h.OnClick(ClickedIncrement())], ['+']),
+      h.button([h.OnClick(Message.ClickedDecrement())], ['-']),
+      h.button([h.OnClick(Message.ClickedReset())], ['Reset']),
+      h.button([h.OnClick(Message.ClickedIncrement())], ['+']),
     ],
   ),
 })
@@ -124,9 +117,9 @@ Source: [examples/counter](https://github.com/foldkit/foldkit/blob/main/examples
 
 ## What Ships With Foldkit
 
-A complete system, not a collection of libraries you stitch together. Each of these is documented in depth at [foldkit.dev](https://foldkit.dev).
+Routing, server rendering, UI components, composition, and browser lifecycles all use the same Model and Message flow. The pieces below ship as one system and are documented in depth at [foldkit.dev](https://foldkit.dev).
 
-- **Commands**: Side effects as named Effects that return Messages and are run by the runtime.
+- **Commands**: Side effects as named Effects that return Messages and are run by the Runtime.
 - **Routing**: Type-safe bidirectional routing from parser combinators. URLs parse to Routes, Routes build URLs.
 - **Subscriptions**: External event streams declared as a function of the Model.
 - **Managed Resources**: Model-driven lifecycle for WebSockets, AudioContext, and other long-lived handles.
@@ -146,9 +139,9 @@ A complete system, not a collection of libraries you stitch together. Each of th
 - **Slow Warnings**: Development warnings when update, view, patch, or Subscription extraction exceeds its budget.
 - **HMR**: Vite plugin with state-preserving hot module replacement. Change your view, keep your state.
 
-## Correctness You (And Your LLM) Can See
+## AI-Assisted Development
 
-Every state change flows through one update function, and every side effect is declared explicitly. You don't have to hold a mental model of what runs when, you can point at it. That's what makes Foldkit unusually AI-friendly: the property that makes the code easy for humans to reason about makes it easy for an LLM to generate and review.
+Every feature has the same visible structure: a Schema-defined Model, fact-named Messages, exhaustive update, and explicit Commands. AI-generated changes follow code paths a person can inspect and test. Foldkit DevTools and its MCP server expose the same Model and Message history while the application runs.
 
 ## Examples
 

package/dist/controlledDomState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controlledDomState.d.ts","sourceRoot":"","sources":["../src/controlledDomState.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAoBhD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GACvC,SAAS,OAAO,EAChB,cAAc,MAAM,EACpB,OAAO,OAAO,KACb,IAqDF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,OAAO,EAChB,cAAc,MAAM,KACnB,IA0CF,CAAA;AAsFD,eAAO,MAAM,0BAA0B,GACrC,SAAS,OAAO,EAChB,OAAO,KAAK,KACX,IAYF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,GACjD,SAAS,OAAO,EAChB,cAAc,MAAM,KACnB,IA0BF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACvC,SAAS,OAAO,EAChB,YAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,KACxD,aAAa,CAAC,MAAM,CAuBtB,CAAA"}
+{"version":3,"file":"controlledDomState.d.ts","sourceRoot":"","sources":["../src/controlledDomState.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAoBhD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GACvC,SAAS,OAAO,EAChB,cAAc,MAAM,EACpB,OAAO,OAAO,KACb,IAyDF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,OAAO,EAChB,cAAc,MAAM,KACnB,IA0CF,CAAA;AAsFD,eAAO,MAAM,0BAA0B,GACrC,SAAS,OAAO,EAChB,OAAO,KAAK,KACX,IAYF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,GACjD,SAAS,OAAO,EAChB,cAAc,MAAM,KACnB,IA0BF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACvC,SAAS,OAAO,EAChB,YAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,KACxD,aAAa,CAAC,MAAM,CAuBtB,CAAA"}

package/dist/controlledDomState.js

@@ -58,13 +58,17 @@ export const synchronizeControlledDefault = (element, propertyName, value) => {
         return;
     }
     if (propertyName === 'value' && tagName === 'select') {
+        // NOTE: set the live selection before copying it into the defaults. Two
+        // options can share one value, so `select.value` may already equal the
+        // controlled value while a later child `selected` still owns the live
+        // selection. The value setter gives the first matching option ownership.
+        Reflect.set(element, 'value', value);
         for (const option of element.querySelectorAll('option')) {
             if (option.defaultSelected !== option.selected) {
                 option.defaultSelected = option.selected;
             }
             setBooleanDefaultAttribute(option, 'selected', option.selected);
         }
-        Reflect.set(element, 'value', value);
     }
 };
 /** Clears default state owned by a controlled property that left a vnode.

package/dist/experimental/server/serialize.d.ts

@@ -32,10 +32,10 @@ export declare const controlledValueContent: (properties: Readonly<Record<string
  *  tree serializes to an empty comment, mirroring how the runtime patches
  *  `null` as a comment node.
  *
- * A hydratable render also stamps a digest of each vnode's key and identity, so
- * hydration can tell one logical entity from another; the raw key and the
- * compiler's source identity never appear in the markup. A render that is not
- * hydratable emits neither.
+ * A hydratable render also stamps a fingerprint of each vnode's key and
+ * identity, so hydration can tell one logical entity from another; the raw key
+ * and the compiler's source identity never appear in the markup. A render that
+ * is not hydratable emits neither.
  *
  * @internal Not part of the `foldkit/experimental/server` surface; `renderToString` is the public entry to serialization.
  */

package/dist/experimental/server/serialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/serialize.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAGpD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B,CAAC,CAAA;AAsNF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAM1C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,MAMpD,CAAA;AA0MD,eAAO,MAAM,sBAAsB,GACjC,YAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,KACxD,MAAM,GAAG,SAMX,CAAA;AAugBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,KAAK,GAAG,IAAI,EAClB,UAAU,gBAAgB,KACzB,MAUF,CAAA"}
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/serialize.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAGpD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B,CAAC,CAAA;AAsNF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAM1C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,MAMpD,CAAA;AA0MD,eAAO,MAAM,sBAAsB,GACjC,YAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,KACxD,MAAM,GAAG,SAMX,CAAA;AA2hBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,KAAK,GAAG,IAAI,EAClB,UAAU,gBAAgB,KACzB,MAUF,CAAA"}

package/dist/experimental/server/serialize.js

@@ -532,7 +532,17 @@ const selectValueForChildren = (tagName, node, inherited) => {
     if (tagName !== 'select') {
         return inherited;
     }
-    const value = node.data?.props?.['value'];
+    const properties = node.data?.props;
+    if (isClientOnlyProperty(properties, 'value')) {
+        throw new Error('[foldkit] Cannot server-render a native <select> with a client-only ' +
+            'value property. Foldkit applies that value before options exist in ' +
+            'a fresh client render and after they exist during hydration, so the ' +
+            'two renders can select different options. CustomElement property ' +
+            'factories belong on their declared Custom Element. Use h.Value(...) ' +
+            'to give a native select one controlled selection to serialize and ' +
+            'hydrate.');
+    }
+    const value = properties?.['value'];
     if (typeof value === 'string') {
         return {
             value,
@@ -611,14 +621,20 @@ const serializeElement = (output, context, node, selector, depth, extraAttribute
         }
     }
     // The server HTML does not otherwise carry a vnode's key or identity, so
-    // hydration would adopt keyed children positionally. Stamp a digest of each so
-    // hydration can verify it is adopting the same logical entity without the raw
-    // key or source identity appearing in public markup; it strips the markers as
-    // it adopts.
+    // hydration would adopt keyed children positionally. Stamp a fingerprint of
+    // each so hydration can verify it is adopting the same logical entity without
+    // the raw key or source identity appearing in public markup; it strips the
+    // markers as it adopts.
     if (context.emitHydrationMarkers) {
         if (node.key !== undefined) {
             const keyMarker = hydrationKeyMarker(node.key);
             if (keyMarker === undefined) {
+                if (typeof node.key === 'number' && Number.isNaN(node.key)) {
+                    throw new Error('[foldkit] Cannot server-render an element keyed by NaN as ' +
+                        'hydratable. NaN is not equal to itself, so hydration cannot ' +
+                        'tell whether the server and client mean the same element. ' +
+                        'Key hydratable elements by a string or a number other than NaN.');
+                }
                 throw new Error('[foldkit] Cannot server-render an element keyed by a symbol. A ' +
                     'symbol key cannot be compared across the server and the client ' +
                     '(a local symbol is a new value in every realm, so hydration ' +
@@ -766,10 +782,10 @@ const serializeNode = (output, context, node, depth, extraAttributes, selectValu
  *  tree serializes to an empty comment, mirroring how the runtime patches
  *  `null` as a comment node.
  *
- * A hydratable render also stamps a digest of each vnode's key and identity, so
- * hydration can tell one logical entity from another; the raw key and the
- * compiler's source identity never appear in the markup. A render that is not
- * hydratable emits neither.
+ * A hydratable render also stamps a fingerprint of each vnode's key and
+ * identity, so hydration can tell one logical entity from another; the raw key
+ * and the compiler's source identity never appear in the markup. A render that
+ * is not hydratable emits neither.
  *
  * @internal Not part of the `foldkit/experimental/server` surface; `renderToString` is the public entry to serialization.
  */

package/dist/experimental/server/server.d.ts

@@ -6,9 +6,10 @@ export declare const __assertNoDeclarativeShadowRoot: (html: string) => void;
 export declare const __assertNoLiveBaseElement: (html: string) => void;
 export declare const __assertNoDocumentStructureEscape: (html: string) => void;
 export { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE };
-/** The server render of one request: the stamped root markup (plus the Flags
- *  payload script when the application declares Flags) and the `Document`
- *  head fields for the host to place into its HTML template.
+/** The server render of one request: the body markup and the `Document` head
+ *  fields for the host to place into its HTML template. Hydratable output
+ *  contains a stamped root and, when the application declares Flags, its
+ *  payload script. Static output carries no handoff markers.
  *
  * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
  */
@@ -171,6 +172,8 @@ export type StaticRenderOptions = CommonRenderOptions & Readonly<{
 }>;
 /** Options for {@link renderToString}. `runtimeId` names the application in the
  *  root stamp and Flags payload; it defaults to `'app'` and must be non-empty.
+ *  A nondefault `runtimeId` changes the root, Flags, and HMR pairing. It does
+ *  not permit a second hydratable application in one document.
  *
  *  A hydratable render (the default) requires `buildId`. Pass
  *  `isHydratable: false` for static markup that nothing will hydrate, which
@@ -204,10 +207,10 @@ export type RenderUrlFlagsOptions<Flags> = RenderUrlOptions & RenderFlagsOptions
  *
  * Resolves `init` for the request (with the given Flags and URL when the
  * config declares them), runs the pure `view` under a no-op dispatch frame,
- * and serializes the resulting `Document` body. The root element is stamped
- * with {@link FOLDKIT_APP_ATTRIBUTE} and, when the config declares `Flags`,
- * the Schema-encoded Flags ride along in a JSON script tag so a hydrating
- * client boots from the same Model.
+ * and serializes the resulting `Document` body. For hydratable output, the
+ * root element is stamped with {@link FOLDKIT_APP_ATTRIBUTE} and, when the
+ * config declares `Flags`, the Schema-encoded Flags ride along in a JSON script
+ * tag so a hydrating client boots from the same Model.
  *
  * Commands returned by `init` are not run: the rendered HTML is the
  * post-`init` state, and the client runs those Commands after hydration.

package/dist/experimental/server/server.d.ts.map

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

package/dist/experimental/server/server.js

@@ -1,4 +1,4 @@
-import { Array as Array_, Context, Data, Effect, Option, Predicate, Schema, pipe, } from 'effect';
+import { Array as Array_, Context, Data, Effect, Option, Predicate, Schema, String, pipe, } from 'effect';
 import { html as Parse5Html, defaultTreeAdapter, parse, parseFragment, } from 'parse5';
 import { HYDRATION_BUILD_ATTRIBUTE } from '../../buildToken.js';
 import { MATHML_NAMESPACE, SVG_NAMESPACE, parsedAttributeName, } from '../../domReflection.js';
@@ -857,11 +857,12 @@ export function renderToString(config, options) {
         // builds of one deployment or be shared by two that render differently.
         // Refusing is the only honest answer, and it names what to supply.
         const configuredBuildId = options?.buildId;
-        if (isHydratable &&
-            (configuredBuildId === undefined || configuredBuildId === '')) {
+        const isConfiguredBuildId = Predicate.isString(configuredBuildId) &&
+            !String.isEmpty(configuredBuildId);
+        if (isHydratable && !isConfiguredBuildId) {
             return yield* Effect.fail(new MissingBuildId());
         }
-        const buildId = configuredBuildId ?? '';
+        const buildId = isConfiguredBuildId ? configuredBuildId : '';
         const url = hasRouting ? yield* parseUrl(options?.url ?? '') : undefined;
         const flagsHandoff = isHydratable && FlagsCodec !== undefined
             ? yield* encodeFlagsHandoff(FlagsCodec, options?.flags, runtimeId)

package/dist/experimental/server/template.d.ts

@@ -36,7 +36,11 @@ export type InjectIntoTemplateOptions = Readonly<{
  * top-level JSON Flags script. Static output may contain one element, text, or
  * comment root, or no body output. The helper rejects additional top-level
  * content, ambiguous handoff markers, and source that the HTML parser drops,
- * splits, moves, or reconstructs before insertion.
+ * splits, moves, or reconstructs before insertion. It also refuses to place a
+ * hydratable application in a template that already contains one. Static body
+ * output may be inserted beside a hydratable application because no runtime
+ * adopts it. Each insertion still applies that render's `Document` head
+ * fields.
  *
  * This helper is pure with no module state, so a host process may import it
  * directly even when the render itself must stay inside the server entry's

package/dist/experimental/server/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/template.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,aAAa,CAAA;AA6oBpB;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C;iDAC6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,EAChB,UAAU,mBAAmB,EAC7B,UAAU,yBAAyB,KAClC,MA0MF,CAAA"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/template.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,aAAa,CAAA;AA6oBpB;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C;iDAC6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,EAChB,UAAU,mBAAmB,EAC7B,UAAU,yBAAyB,KAClC,MAuNF,CAAA"}

package/dist/experimental/server/template.js

@@ -462,7 +462,11 @@ const isContainerPlaceholder = (element, containerId) => element.tagName === 'di
  * top-level JSON Flags script. Static output may contain one element, text, or
  * comment root, or no body output. The helper rejects additional top-level
  * content, ambiguous handoff markers, and source that the HTML parser drops,
- * splits, moves, or reconstructs before insertion.
+ * splits, moves, or reconstructs before insertion. It also refuses to place a
+ * hydratable application in a template that already contains one. Static body
+ * output may be inserted beside a hydratable application because no runtime
+ * adopts it. Each insertion still applies that render's `Document` head
+ * fields.
  *
  * This helper is pure with no module state, so a host process may import it
  * directly even when the render itself must stay inside the server entry's
@@ -485,7 +489,7 @@ export const injectIntoTemplate = (template, rendered, options) => {
     }
     if (containers.length > 1) {
         throw new Error(`[foldkit] injectIntoTemplate found more than one <div id="${containerId}"></div> placeholder in the template. ` +
-            'Keep exactly one placeholder for each application root.');
+            'Keep exactly one placeholder with that id.');
     }
     // The runtime id names an application across the whole page: it pairs a root
     // with its Flags payload, and it keys the Model and scroll position HMR
@@ -506,8 +510,16 @@ export const injectIntoTemplate = (template, rendered, options) => {
                 'that id. 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. Give each application its own " +
-                '`runtimeId` when rendering.');
+                "take each other's state. Remove the duplicate root. Foldkit " +
+                'supports one page-owning hydratable application per document.');
+        }
+        const existingApplications = collectMatching(document, element => attributeValue(element, FOLDKIT_APP_ATTRIBUTE) !== undefined);
+        if (existingApplications.length > 0) {
+            throw new Error('[foldkit] injectIntoTemplate is placing a hydratable application, ' +
+                'but the page already holds a server-rendered application. Foldkit ' +
+                'supports one page-owning application per document because each ' +
+                'application owns the document metadata and installs document-wide ' +
+                'navigation listeners. Render one application per page.');
         }
         const existingFlags = collectMatching(document, element => attributeValue(element, FOLDKIT_FLAGS_ATTRIBUTE) === renderedRuntimeId);
         if (existingFlags.length > 0) {

package/dist/hydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAwPhD,eAAO,MAAM,kBAAkB,GAAI,SAAS,OAAO,EAAE,OAAO,KAAK,KAAG,MA4BnE,CAAA;AAmsBD,eAAO,MAAM,cAAc,GACzB,eAAe,OAAO,EACtB,WAAW,KAAK,GAAG,IAAI,EACvB,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,EAC7B,SAAS,MAAM,KACd,KAwDF,CAAA"}
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAmUhD,eAAO,MAAM,kBAAkB,GAAI,SAAS,OAAO,EAAE,OAAO,KAAK,KAAG,MA4BnE,CAAA;AA+rBD,eAAO,MAAM,cAAc,GACzB,eAAe,OAAO,EACtB,WAAW,KAAK,GAAG,IAAI,EACvB,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,EAC7B,SAAS,MAAM,KACd,KA0DF,CAAA"}

package/dist/hydrate.js

@@ -161,6 +161,44 @@ const isControlledCurrentState = (element, propertyName) => {
         (propertyName === 'muted' && (tagName === 'audio' || tagName === 'video')));
 };
 const STALE_REFLECTED_PROPERTY = Symbol('foldkit/stale-reflected-property');
+const NO_SELECTED_OPTION = -1;
+// NOTE: a controlled select owns the effective state of every descendant
+// option. The serializer marks the first matching option, and the browser's
+// value setter does the same during a fresh render. Compare hydration against
+// that parent-owned state instead of each option's shadowed `selected` prop.
+const registerControlledSelectState = (element, vnode, status) => {
+    const properties = vnode.data?.props;
+    const authoredValue = properties?.['value'];
+    if (!(element instanceof HTMLSelectElement) ||
+        typeof authoredValue !== 'string' ||
+        isClientOnlyProperty(properties, 'value')) {
+        return;
+    }
+    const options = Array.from(element.options);
+    const selectedOption = options.find(option => option.value === authoredValue);
+    for (const option of options) {
+        status.controlledOptionSelection.set(option, option === selectedOption);
+    }
+    status.controlledSelectState.set(element, {
+        selectedIndex: selectedOption?.index ?? NO_SELECTED_OPTION,
+        value: selectedOption?.value ?? '',
+    });
+};
+const detectControlledSelectMismatch = (element, status) => {
+    const selectState = status.controlledSelectState.get(element);
+    if (selectState !== undefined &&
+        (Reflect.get(element, 'value') !== selectState.value ||
+            Reflect.get(element, 'selectedIndex') !== selectState.selectedIndex)) {
+        detectMismatch(status);
+    }
+    const isSelected = status.controlledOptionSelection.get(element);
+    if (isSelected !== undefined) {
+        if (Reflect.get(element, 'selected') !== isSelected ||
+            Reflect.get(element, 'defaultSelected') !== isSelected) {
+            detectMismatch(status);
+        }
+    }
+};
 const seedReflectedProperties = (element, vnode, propertyNames, isCustomElement, status) => {
     const properties = vnode.data?.props;
     if (properties === undefined || propertyNames.length === 0) {
@@ -173,6 +211,12 @@ const seedReflectedProperties = (element, vnode, propertyNames, isCustomElement,
         if (attributeName === undefined) {
             continue;
         }
+        const isOwnedByControlledSelect = (name === 'value' && status.controlledSelectState.has(element)) ||
+            (name === 'selected' && status.controlledOptionSelection.has(element));
+        if (isOwnedByControlledSelect) {
+            seeded[name] = authored;
+            continue;
+        }
         const isEquivalent = !isCustomElement && isControlledCurrentState(element, name)
             ? Object.is(Reflect.get(element, name), authored)
             : element.getAttribute(attributeName) ===
@@ -231,6 +275,7 @@ export const __elementSignature = (element, vnode) => {
 // value is written by one module and then removed as stale state by another.
 // The hydration stamp is never seeded, so it is never removed.
 const seedAdoptedState = (element, vnode, clone, status, isCustomElement) => {
+    detectControlledSelectMismatch(element, status);
     const classOwnedByModule = vnode.data?.class !== undefined &&
         htmlAttributeValue(vnode.data?.attrs, 'class') === undefined;
     const styleOwnedByModule = vnode.data?.style !== undefined &&
@@ -339,11 +384,11 @@ const matchesNamespace = (element, vnode) => (element.namespaceURI ?? HTML_NAMES
 // The server DOM does not encode a vnode's key or identity, so a positional
 // match on tag and namespace alone could adopt a different logical entity: a
 // reordered or stale keyed list would take over the wrong DOM node, and the user
-// state sitting on it. The serializer stamps a digest of key and identity; here
-// the same digest is computed for the vnode and compared, so a mismatch rebuilds
-// instead of transferring state to the wrong row or branch. A key type the
-// digest does not support (a symbol, which a hydratable render refuses) never
-// matches, so it rebuilds rather than adopting on a guess.
+// state sitting on it. The serializer stamps a fingerprint of the key and
+// identity; here the same fingerprint is computed for the vnode and compared,
+// so a mismatch rebuilds instead of transferring state to the wrong row or
+// branch. An unsupported key (NaN or a symbol, which a hydratable render
+// refuses) never matches, so it rebuilds rather than adopting on a guess.
 const matchesAdoptionKey = (element, vnode) => {
     const serverKey = element.getAttribute(HYDRATION_KEY_ATTRIBUTE);
     if (vnode.key === undefined) {
@@ -351,9 +396,9 @@ const matchesAdoptionKey = (element, vnode) => {
     }
     const clientKey = hydrationKeyMarker(vnode.key);
     if (clientKey === undefined) {
-        // A key type the digest cannot represent (a symbol, which a hydratable
-        // render refuses) cannot be compared, so it never matches: rebuilding beats
-        // adopting on a guess.
+        // An unsupported key (NaN or a symbol, which a hydratable render refuses)
+        // cannot be compared, so it never matches: rebuilding beats adopting on a
+        // guess.
         return false;
     }
     return serverKey === clientKey;
@@ -510,6 +555,7 @@ const adoptElement = (element, vnode, status) => {
         return clonePreparedTree(replaceHydrationElement(element, vnode));
     }
     const clone = cloneOf(vnode, element);
+    registerControlledSelectState(element, vnode, status);
     // Strip the hydration markers the serializer stamped: they are internal to the
     // handoff, already verified by the parent's positional walk before this call,
     // and must not remain on the adopted element.
@@ -804,6 +850,8 @@ export const __hydrateVNode = (hydrationRoot, nextVNode, seen, buildId) => {
     const status = {
         isMismatchDetected: false,
         adoptedSignatures: new Map(),
+        controlledOptionSelection: new Map(),
+        controlledSelectState: new Map(),
     };
     // The build token is checked again here, though the runtime has already
     // refused a mismatch before reading the handoff. This is the last line of

package/dist/hydrationMarker.d.ts

@@ -1,6 +1,7 @@
-/** Attribute stamped on the server-rendered application root. Its presence
- *  tells a booting runtime to hydrate instead of rendering fresh, and its
- *  value is the runtime id used for HMR model preservation. */
+/** Attribute stamped on a hydratable server-rendered application root. Its
+ *  nonempty value is the runtime id used to pair the root with its Flags
+ *  payload and scope preserved HMR state. `makeApplication` locates the root;
+ *  `Runtime.hydrate` adopts it. */
 export declare const FOLDKIT_APP_ATTRIBUTE = "data-foldkit-app";
 /** Attribute on the JSON script tag carrying the Schema-encoded flags the
  *  server rendered with. A hydrating runtime decodes this payload instead of

package/dist/hydrationMarker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrationMarker.d.ts","sourceRoot":"","sources":["../src/hydrationMarker.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAC/D,eAAO,MAAM,qBAAqB,qBAAqB,CAAA;AAEvD;;;kBAGkB;AAClB,eAAO,MAAM,uBAAuB,uBAAuB,CAAA"}
+{"version":3,"file":"hydrationMarker.d.ts","sourceRoot":"","sources":["../src/hydrationMarker.ts"],"names":[],"mappings":"AAAA;;;mCAGmC;AACnC,eAAO,MAAM,qBAAqB,qBAAqB,CAAA;AAEvD;;;kBAGkB;AAClB,eAAO,MAAM,uBAAuB,uBAAuB,CAAA"}

package/dist/hydrationMarker.js

@@ -1,6 +1,7 @@
-/** Attribute stamped on the server-rendered application root. Its presence
- *  tells a booting runtime to hydrate instead of rendering fresh, and its
- *  value is the runtime id used for HMR model preservation. */
+/** Attribute stamped on a hydratable server-rendered application root. Its
+ *  nonempty value is the runtime id used to pair the root with its Flags
+ *  payload and scope preserved HMR state. `makeApplication` locates the root;
+ *  `Runtime.hydrate` adopts it. */
 export const FOLDKIT_APP_ATTRIBUTE = 'data-foldkit-app';
 /** Attribute on the JSON script tag carrying the Schema-encoded flags the
  *  server rendered with. A hydrating runtime decodes this payload instead of

package/dist/hydrationMarkers.d.ts

@@ -1,8 +1,8 @@
 export declare const HYDRATION_KEY_ATTRIBUTE = "data-foldkit-key";
 export declare const HYDRATION_IDENTITY_ATTRIBUTE = "data-foldkit-identity";
-/** The marker value for a vnode key, or `undefined` for a key type the
- *  hydration handoff does not support (a symbol, which the server refuses to
- *  render and hydration therefore never adopts).
+/** The marker value for a vnode key, or `undefined` for a key the hydration
+ *  handoff does not support (`NaN` or a symbol, both of which the server
+ *  refuses in hydratable output).
  *
  * @internal
  */

package/dist/hydrationMarkers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrationMarkers.d.ts","sourceRoot":"","sources":["../src/hydrationMarkers.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,uBAAuB,qBAAqB,CAAA;AACzD,eAAO,MAAM,4BAA4B,0BAA0B,CAAA;AAkCnE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,WAAW,KAAG,MAAM,GAAG,SAQ9D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,MAAM,KAAG,MAClC,CAAA"}
+{"version":3,"file":"hydrationMarkers.d.ts","sourceRoot":"","sources":["../src/hydrationMarkers.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,uBAAuB,qBAAqB,CAAA;AACzD,eAAO,MAAM,4BAA4B,0BAA0B,CAAA;AAmCnE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,WAAW,KAAG,MAAM,GAAG,SAW9D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,MAAM,KAAG,MAC7B,CAAA"}