foldkit 0.101.0 → 0.102.0

package/dist/html/lazy.d.ts

@@ -1,25 +1,30 @@
-import type { Html } from './index.js';
+import type { VNode } from '../vdom.js';
 /** Creates a memoization slot for a view function. On each render, if the
- *  function reference, dispatch context, and all arguments are referentially
- *  equal (`===`) to the previous call, the cached VNode is returned without
+ *  function reference, dispatch, and all arguments are referentially equal
+ *  (`===`) to the previous call, the cached VNode is returned without
  *  re-running the view function. Snabbdom's `patchVnode` short-circuits when
  *  it sees the same VNode reference, so both VNode construction and subtree
  *  diffing are skipped.
  *
+ *  Dispatch is part of the cache key because event handlers in the cached
+ *  VNode close over the dispatch active when the VNode was built. Returning
+ *  a VNode built under a different dispatch would silently misroute every
+ *  event from that subtree.
+ *
  *  The cached VNode must be rendered at a single position in the tree.
  *  Snabbdom tracks the real DOM through each VNode's mutable `.elm` field
  *  and assumes one VNode per position. Rendering the same cached VNode at
  *  two positions causes patches to collide and can duplicate or misplace
  *  DOM nodes. If the same content needs to appear in multiple positions,
  *  create one slot per position. */
-export declare const createLazy: () => (<Args extends ReadonlyArray<unknown>>(fn: (...args: Args) => Html, args: Args) => Html);
+export declare const createLazy: () => (<Args extends ReadonlyArray<unknown>>(fn: (...args: Args) => VNode | null, args: Args) => VNode | null);
 /** Creates a keyed memoization map for view functions rendered in a loop. Each
  *  key gets its own independent cache slot. On each render, only entries whose
- *  function reference, dispatch context, or arguments have changed by reference
- *  are recomputed.
+ *  function reference, dispatch, or arguments have changed by reference are
+ *  recomputed.
  *
  *  Like `createLazy`, each key's cached VNode must be rendered at a single
  *  position in the tree. If the same item needs to appear in multiple
  *  positions, create one keyed lazy per position. */
-export declare const createKeyedLazy: () => (<Args extends ReadonlyArray<unknown>>(key: string, fn: (...args: Args) => Html, args: Args) => Html);
+export declare const createKeyedLazy: () => (<Args extends ReadonlyArray<unknown>>(key: string, fn: (...args: Args) => VNode | null, args: Args) => VNode | null);
 //# sourceMappingURL=lazy.d.ts.map

package/dist/html/lazy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../../src/html/lazy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAsCtC;;;;;;;;;;;;oCAYoC;AACpC,eAAO,MAAM,UAAU,QAAO,CAAC,CAAC,IAAI,SAAS,aAAa,CAAC,OAAO,CAAC,EACjE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,EAC3B,IAAI,EAAE,IAAI,KACP,IAAI,CAUR,CAAA;AAED;;;;;;;qDAOqD;AACrD,eAAO,MAAM,eAAe,QAAO,CAAC,CAAC,IAAI,SAAS,aAAa,CAAC,OAAO,CAAC,EACtE,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,EAC3B,IAAI,EAAE,IAAI,KACP,IAAI,CAWR,CAAA"}
+{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../../src/html/lazy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAiEvC;;;;;;;;;;;;;;;;;oCAiBoC;AACpC,eAAO,MAAM,UAAU,QAAO,CAAC,CAAC,IAAI,SAAS,aAAa,CAAC,OAAO,CAAC,EACjE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,KAAK,GAAG,IAAI,EACnC,IAAI,EAAE,IAAI,KACP,KAAK,GAAG,IAAI,CAUhB,CAAA;AAED;;;;;;;qDAOqD;AACrD,eAAO,MAAM,eAAe,QAAO,CAAC,CAAC,IAAI,SAAS,aAAa,CAAC,OAAO,CAAC,EACtE,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,KAAK,GAAG,IAAI,EACnC,IAAI,EAAE,IAAI,KACP,KAAK,GAAG,IAAI,CAWhB,CAAA"}

package/dist/html/lazy.js

@@ -1,26 +1,45 @@
-import { Effect, Predicate } from 'effect';
-import { Dispatch } from '../runtime/index.js';
+import { Predicate } from 'effect';
+import { beginLazyTracking, endLazyTracking, markSeenForLazyHit, } from './boundary.js';
+import { requireBoundary, requireDispatch, } from './runtimeSingleton.js';
 const argsEqual = (previous, current) => previous.length === current.length &&
     previous.every((value, index) => value === current[index]);
-const resolveOrCache = (previousEntry, fn, args, onCache) => Effect.gen(function* () {
-    const dispatch = yield* Dispatch;
+const resolveOrCache = (previousEntry, fn, args, onCache) => {
+    const dispatch = requireDispatch();
+    const { registry } = requireBoundary();
+    // NOTE: dispatch identity in the cache key matters for the DevTools
+    // jumpTo path: a replay render installs `noOpDispatch`, and without
+    // this check a subsequent live render could return a vnode whose
+    // handlers still reference the noOp.
     if (Predicate.isNotUndefined(previousEntry) &&
         previousEntry.fn === fn &&
         previousEntry.dispatch === dispatch &&
         argsEqual(previousEntry.args, args)) {
+        markSeenForLazyHit(registry, previousEntry.trackedBoundaries);
         return previousEntry.vnode;
     }
-    const vnode = yield* fn(...args);
-    onCache({ fn, args, dispatch, vnode });
+    const trackedBoundaries = beginLazyTracking(registry);
+    let vnode;
+    try {
+        vnode = fn(...args);
+    }
+    finally {
+        endLazyTracking(registry);
+    }
+    onCache({ fn, args, dispatch, vnode, trackedBoundaries });
     return vnode;
-});
+};
 /** Creates a memoization slot for a view function. On each render, if the
- *  function reference, dispatch context, and all arguments are referentially
- *  equal (`===`) to the previous call, the cached VNode is returned without
+ *  function reference, dispatch, and all arguments are referentially equal
+ *  (`===`) to the previous call, the cached VNode is returned without
  *  re-running the view function. Snabbdom's `patchVnode` short-circuits when
  *  it sees the same VNode reference, so both VNode construction and subtree
  *  diffing are skipped.
  *
+ *  Dispatch is part of the cache key because event handlers in the cached
+ *  VNode close over the dispatch active when the VNode was built. Returning
+ *  a VNode built under a different dispatch would silently misroute every
+ *  event from that subtree.
+ *
  *  The cached VNode must be rendered at a single position in the tree.
  *  Snabbdom tracks the real DOM through each VNode's mutable `.elm` field
  *  and assumes one VNode per position. Rendering the same cached VNode at
@@ -35,8 +54,8 @@ export const createLazy = () => {
 };
 /** Creates a keyed memoization map for view functions rendered in a loop. Each
  *  key gets its own independent cache slot. On each render, only entries whose
- *  function reference, dispatch context, or arguments have changed by reference
- *  are recomputed.
+ *  function reference, dispatch, or arguments have changed by reference are
+ *  recomputed.
  *
  *  Like `createLazy`, each key's cached VNode must be rendered at a single
  *  position in the tree. If the same item needs to appear in multiple

package/dist/html/public.d.ts

@@ -1,3 +1,3 @@
-export { createKeyedLazy, createLazy, html } from './index.js';
-export type { Attribute, Document, Html, KeyboardModifiers, TagName, } from './index.js';
+export { childAttributes, createKeyedLazy, createLazy, html, submodel, } from './index.js';
+export type { Attribute, ChildAttribute, Document, Html, KeyboardModifiers, TagName, } from './index.js';
 //# sourceMappingURL=public.d.ts.map

package/dist/html/public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/html/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAE9D,YAAY,EACV,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,iBAAiB,EACjB,OAAO,GACR,MAAM,YAAY,CAAA"}
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/html/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,EACf,UAAU,EACV,IAAI,EACJ,QAAQ,GACT,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,IAAI,EACJ,iBAAiB,EACjB,OAAO,GACR,MAAM,YAAY,CAAA"}

package/dist/html/public.js

@@ -1 +1 @@
-export { createKeyedLazy, createLazy, html } from './index.js';
+export { childAttributes, createKeyedLazy, createLazy, html, submodel, } from './index.js';

package/dist/html/runtimeSingleton.d.ts

@@ -0,0 +1,72 @@
+import type { Context } from 'effect';
+import { type BoundaryId, type BoundaryRegistry } from './boundary.js';
+/** Synchronous message dispatcher provided to view-time element constructors. */
+export type DispatchSync = (message: unknown) => void;
+export type Frame = Readonly<{
+    outerDispatch: DispatchSync;
+    runtimeContext: Context.Context<never>;
+    boundaryRegistry: BoundaryRegistry;
+    boundaryId: BoundaryId;
+}>;
+/** Pushes a new dispatch and runtime context onto the singleton stack. The
+ *  runtime calls this before invoking a user `view`, and any test or
+ *  framework helper that builds VNodes outside of a normal render uses the
+ *  same pair. Nested calls are supported: each push must be matched by a
+ *  paired {@link clearRuntime} so the previous frame is restored.
+ *
+ *  Optionally accepts a {@link BoundaryRegistry}; the runtime supplies the
+ *  same registry across renders so Submodel wrap descriptors persist. When
+ *  omitted (e.g. crash views, test helpers that don't use Submodels), a
+ *  fresh empty registry is created. The frame starts in the root
+ *  boundary. */
+export declare const setRuntime: (dispatch: DispatchSync, runtimeContext: Context.Context<never>, boundaryRegistry?: BoundaryRegistry) => void;
+/** Pushes a new frame that inherits the current frame's dispatch, context,
+ *  and registry, but uses a different boundary. Used by `h.submodel` to
+ *  enter a child Submodel's wrapping context. Must be paired with
+ *  {@link clearRuntime}. */
+export declare const pushBoundary: (boundaryId: BoundaryId) => void;
+/** Pushes a fully-specified frame, ignoring whatever is currently on the
+ *  stack. Used by `h.submodel`'s slot-callback wrapping so the wrapped
+ *  callback runs in the OUTER (parent) Submodel's context, regardless of
+ *  what frame is active at the time the callback is invoked.
+ *
+ *  Unlike {@link pushBoundary} (which inherits dispatch/registry/context
+ *  from the current top), this lets the caller capture a full frame
+ *  snapshot at one point and replay it later. Without this primitive, a
+ *  slot callback invoked from a deferred context (setTimeout, Promise,
+ *  stored callback) would inherit from whatever render's frame happens
+ *  to be on the stack at the time, silently mis-binding dispatch and
+ *  registry. Must be paired with {@link clearRuntime}. */
+export declare const pushFrame: (frame: Frame) => void;
+/** Pops the current frame, restoring whatever frame was previously active.
+ *  Must be paired with a {@link setRuntime} or {@link pushBoundary} on the
+ *  same call stack, including via `try`/`finally` so an exception inside
+ *  view code does not leak the frame to subsequent renders.
+ *
+ *  Throws when called on an empty stack. That signals an unmatched
+ *  push/pop pair somewhere upstream and would silently corrupt later
+ *  renders if it slid by. */
+export declare const clearRuntime: () => void;
+/** Returns the current dispatcher. For frames in the root boundary, this
+ *  is the runtime's actual dispatch; for nested Submodel boundaries, this
+ *  is a cached per-boundary dispatcher that applies the wrapping chain at
+ *  event-fire time. Throws when called outside of a runtime frame. */
+export declare const requireDispatch: () => DispatchSync;
+/** Returns the current runtime Effect Context, used by Mount integrations
+ *  that fork message-producing Effects against the live runtime services. */
+export declare const requireRuntimeContext: () => Context.Context<never>;
+/** Returns the current frame's boundary registry and boundary id. Used by
+ *  `h.submodel` to register wrapping descriptors and compute child
+ *  boundary ids. Throws when called outside of a runtime frame. */
+export declare const requireBoundary: () => Readonly<{
+    registry: BoundaryRegistry;
+    boundaryId: BoundaryId;
+}>;
+/** Returns the full current frame, used by `h.submodel` to snapshot the
+ *  parent's context before pushing a child boundary. The snapshot is
+ *  captured into slot-callback closures so they can replay the parent's
+ *  full frame via {@link pushFrame} when invoked, instead of inheriting
+ *  from whatever happens to be on the stack at invocation time. Throws
+ *  when called outside of a runtime frame. */
+export declare const getCurrentFrame: () => Frame;
+//# sourceMappingURL=runtimeSingleton.d.ts.map

package/dist/html/runtimeSingleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeSingleton.d.ts","sourceRoot":"","sources":["../../src/html/runtimeSingleton.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAErC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,gBAAgB,EAItB,MAAM,eAAe,CAAA;AAEtB,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;AAErD,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC3B,aAAa,EAAE,YAAY,CAAA;IAC3B,cAAc,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACtC,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,UAAU,EAAE,UAAU,CAAA;CACvB,CAAC,CAAA;AAIF;;;;;;;;;;gBAUgB;AAChB,eAAO,MAAM,UAAU,GACrB,UAAU,YAAY,EACtB,gBAAgB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EACtC,mBAAkB,gBAA2C,KAC5D,IAOF,CAAA;AAED;;;4BAG4B;AAC5B,eAAO,MAAM,YAAY,GAAI,YAAY,UAAU,KAAG,IAarD,CAAA;AAED;;;;;;;;;;;0DAW0D;AAC1D,eAAO,MAAM,SAAS,GAAI,OAAO,KAAK,KAAG,IAExC,CAAA;AAED;;;;;;;6BAO6B;AAC7B,eAAO,MAAM,YAAY,QAAO,IAU/B,CAAA;AAED;;;sEAGsE;AACtE,eAAO,MAAM,eAAe,QAAO,YAYlC,CAAA;AAED;6EAC6E;AAC7E,eAAO,MAAM,qBAAqB,QAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAQ7D,CAAA;AAED;;mEAEmE;AACnE,eAAO,MAAM,eAAe,QAAO,QAAQ,CAAC;IAC1C,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,UAAU,EAAE,UAAU,CAAA;CACvB,CAQA,CAAA;AAED;;;;;8CAK8C;AAC9C,eAAO,MAAM,eAAe,QAAO,KAQlC,CAAA"}

package/dist/html/runtimeSingleton.js

@@ -0,0 +1,112 @@
+import { ROOT_BOUNDARY, createBoundaryRegistry, getOrCreateBoundaryDispatch, } from './boundary.js';
+const stack = [];
+/** Pushes a new dispatch and runtime context onto the singleton stack. The
+ *  runtime calls this before invoking a user `view`, and any test or
+ *  framework helper that builds VNodes outside of a normal render uses the
+ *  same pair. Nested calls are supported: each push must be matched by a
+ *  paired {@link clearRuntime} so the previous frame is restored.
+ *
+ *  Optionally accepts a {@link BoundaryRegistry}; the runtime supplies the
+ *  same registry across renders so Submodel wrap descriptors persist. When
+ *  omitted (e.g. crash views, test helpers that don't use Submodels), a
+ *  fresh empty registry is created. The frame starts in the root
+ *  boundary. */
+export const setRuntime = (dispatch, runtimeContext, boundaryRegistry = createBoundaryRegistry()) => {
+    stack.push({
+        outerDispatch: dispatch,
+        runtimeContext,
+        boundaryRegistry,
+        boundaryId: ROOT_BOUNDARY,
+    });
+};
+/** Pushes a new frame that inherits the current frame's dispatch, context,
+ *  and registry, but uses a different boundary. Used by `h.submodel` to
+ *  enter a child Submodel's wrapping context. Must be paired with
+ *  {@link clearRuntime}. */
+export const pushBoundary = (boundaryId) => {
+    const parent = stack[stack.length - 1];
+    if (parent === undefined) {
+        throw new Error('Foldkit: pushBoundary called without an active runtime frame');
+    }
+    stack.push({
+        outerDispatch: parent.outerDispatch,
+        runtimeContext: parent.runtimeContext,
+        boundaryRegistry: parent.boundaryRegistry,
+        boundaryId,
+    });
+};
+/** Pushes a fully-specified frame, ignoring whatever is currently on the
+ *  stack. Used by `h.submodel`'s slot-callback wrapping so the wrapped
+ *  callback runs in the OUTER (parent) Submodel's context, regardless of
+ *  what frame is active at the time the callback is invoked.
+ *
+ *  Unlike {@link pushBoundary} (which inherits dispatch/registry/context
+ *  from the current top), this lets the caller capture a full frame
+ *  snapshot at one point and replay it later. Without this primitive, a
+ *  slot callback invoked from a deferred context (setTimeout, Promise,
+ *  stored callback) would inherit from whatever render's frame happens
+ *  to be on the stack at the time, silently mis-binding dispatch and
+ *  registry. Must be paired with {@link clearRuntime}. */
+export const pushFrame = (frame) => {
+    stack.push(frame);
+};
+/** Pops the current frame, restoring whatever frame was previously active.
+ *  Must be paired with a {@link setRuntime} or {@link pushBoundary} on the
+ *  same call stack, including via `try`/`finally` so an exception inside
+ *  view code does not leak the frame to subsequent renders.
+ *
+ *  Throws when called on an empty stack. That signals an unmatched
+ *  push/pop pair somewhere upstream and would silently corrupt later
+ *  renders if it slid by. */
+export const clearRuntime = () => {
+    if (stack.length === 0) {
+        throw new Error('Foldkit: clearRuntime called on an empty runtime stack. This means ' +
+            'a `pushBoundary` or `setRuntime` was not paired with `clearRuntime` ' +
+            '(or vice versa) upstream. Likely a bug in a custom Submodel ' +
+            'integration or view-time helper.');
+    }
+    stack.pop();
+};
+/** Returns the current dispatcher. For frames in the root boundary, this
+ *  is the runtime's actual dispatch; for nested Submodel boundaries, this
+ *  is a cached per-boundary dispatcher that applies the wrapping chain at
+ *  event-fire time. Throws when called outside of a runtime frame. */
+export const requireDispatch = () => {
+    const frame = stack[stack.length - 1];
+    if (frame === undefined) {
+        throw new Error('Foldkit: html element constructors must be called inside a runtime-driven render');
+    }
+    return getOrCreateBoundaryDispatch(frame.boundaryRegistry, frame.outerDispatch, frame.boundaryId);
+};
+/** Returns the current runtime Effect Context, used by Mount integrations
+ *  that fork message-producing Effects against the live runtime services. */
+export const requireRuntimeContext = () => {
+    const frame = stack[stack.length - 1];
+    if (frame === undefined) {
+        throw new Error('Foldkit: html element constructors must be called inside a runtime-driven render');
+    }
+    return frame.runtimeContext;
+};
+/** Returns the current frame's boundary registry and boundary id. Used by
+ *  `h.submodel` to register wrapping descriptors and compute child
+ *  boundary ids. Throws when called outside of a runtime frame. */
+export const requireBoundary = () => {
+    const frame = stack[stack.length - 1];
+    if (frame === undefined) {
+        throw new Error('Foldkit: h.submodel must be called inside a runtime-driven render');
+    }
+    return { registry: frame.boundaryRegistry, boundaryId: frame.boundaryId };
+};
+/** Returns the full current frame, used by `h.submodel` to snapshot the
+ *  parent's context before pushing a child boundary. The snapshot is
+ *  captured into slot-callback closures so they can replay the parent's
+ *  full frame via {@link pushFrame} when invoked, instead of inheriting
+ *  from whatever happens to be on the stack at invocation time. Throws
+ *  when called outside of a runtime frame. */
+export const getCurrentFrame = () => {
+    const frame = stack[stack.length - 1];
+    if (frame === undefined) {
+        throw new Error('Foldkit: getCurrentFrame called without an active runtime frame');
+    }
+    return frame;
+};

package/dist/html/submodel.d.ts

@@ -0,0 +1,98 @@
+import type { VNode } from '../vdom.js';
+declare const SUBMODEL_MESSAGE_BRAND = "__submodelMessage";
+/** A view function branded with the Message type it dispatches. Build
+ *  one with {@link defineView}:
+ *
+ *  ```ts
+ *  export const view = defineView<Counter.Model, Counter.Message>(
+ *    (model) => h.button([h.OnClick(Increment())], ['+']),
+ *  )
+ *  ```
+ *
+ *  When `ViewInputs` is provided, the view takes a second `viewInputs`
+ *  argument:
+ *
+ *  ```ts
+ *  export const view = defineView<
+ *    Checkbox.Model,
+ *    Checkbox.Message,
+ *    ViewInputs
+ *  >((model, viewInputs) => viewInputs.toView({ checkbox: [...] }))
+ *  ```
+ *
+ *  Required at the `h.submodel` call site so unbranded plain functions
+ *  fail to type-check there. */
+export type SubmodelView<Model, Message, ViewInputs = void> = (ViewInputs extends void ? (model: Model) => VNode | null : (model: Model, viewInputs: ViewInputs) => VNode | null) & {
+    readonly [SUBMODEL_MESSAGE_BRAND]: Message;
+};
+/** Defines the view function of a Submodel, a child component embedded
+ *  via `h.submodel`.
+ *
+ *  Use this ONLY for views that will be embedded via `h.submodel`. Plain
+ *  view functions (page-level render functions, helper render functions
+ *  that compose Html, etc.) don't need to be defined this way. Write
+ *  them as ordinary `(model) => Html` functions.
+ *
+ *  Explicit type arguments are required because Message has no
+ *  inferable source on the function signature itself. */
+export declare const defineView: <Model, Message, ViewInputs = void>(fn: ViewInputs extends void ? (model: Model) => VNode | null : (model: Model, viewInputs: ViewInputs) => VNode | null) => SubmodelView<Model, Message, ViewInputs>;
+type AnySubmodelView = ((...args: ReadonlyArray<any>) => VNode | null) & {
+    readonly [SUBMODEL_MESSAGE_BRAND]: unknown;
+};
+type ViewModelOf<View extends AnySubmodelView> = Parameters<View>[0];
+type ViewInputsOf<View extends AnySubmodelView> = Parameters<View> extends [unknown, infer ViewInputs] ? ViewInputs : void;
+type ViewMessageOf<View extends AnySubmodelView> = View extends {
+    readonly [SUBMODEL_MESSAGE_BRAND]: infer Message;
+} ? Message : never;
+/** Configuration for embedding a child Submodel into a parent's view.
+ *
+ *  - `slotId`: unique identifier for this Submodel instance under the
+ *    current boundary. Name the slot semantically (e.g.
+ *    `'sidebar-group'`). For lists, use a stable per-item id (typically
+ *    `entry.id`), not the array index. If the same model is rendered in
+ *    two DOM positions (desktop + mobile, master + detail), each slot
+ *    needs its own id (e.g. `'desktop-sidebar-group'`,
+ *    `'mobile-sidebar-group'`). Two `h.submodel` calls inside the same
+ *    parent boundary with the same `slotId` throw at view-build time,
+ *    including across `createLazy`/`createKeyedLazy` cache hits.
+ *  - `view`: the child's `SubmodelView`. Must be branded via
+ *    {@link defineView} so `h.submodel` can infer the child's Message
+ *    type. Unbranded plain functions fail to type-check here.
+ *  - `model`: the child's model, inferred from `view`'s first parameter.
+ *    Compared by `===` when the boundary is wrapped in a memoizing
+ *    helper such as `createKeyedLazy`.
+ *  - `viewInputs`: optional second-argument data passed to `view`,
+ *    inferred from `view`'s second parameter. Function values AT THE TOP
+ *    LEVEL of `viewInputs` (slot callbacks like `toView`) are
+ *    auto-wrapped to execute in the parent's boundary so handlers the
+ *    consumer builds inside them dispatch through the parent's wrapping
+ *    chain. Function values nested below the top level (e.g.
+ *    `viewInputs: { config: { onSubmit } }`) throw at view-build time
+ *    with a path-based error like `viewInputs.config.onSubmit`. The
+ *    check is runtime-only (TypeScript cannot distinguish a
+ *    user-declared nested callback from a data value whose prototype
+ *    carries methods), so a misuse compiles cleanly and surfaces the
+ *    first time the boundary renders. Keep slot callbacks at the top
+ *    level of `viewInputs`.
+ *  - `toParentMessage`: function that lifts a child message into the
+ *    current boundary's Message type. The argument is typed as the
+ *    child's Message via the view's brand, so destructuring is correctly
+ *    typed without annotation. For per-instance identifiers, capture
+ *    them in a closure
+ *    (`(message) => GotEntryMessage({ entryId: entry.id, message })`).
+ *
+ *  High-level events the parent handles declaratively flow through
+ *  each Submodel's `OutMessage`. The parent's `GotChildMessage`
+ *  handler unpacks the third tuple element of the child's `update`
+ *  return and pattern-matches on `Option<OutMessage>`. See `Ui.Menu`,
+ *  `Ui.Listbox`, etc., for examples. */
+export type SubmodelConfig<View extends AnySubmodelView> = Readonly<{
+    slotId: string;
+    model: ViewModelOf<View>;
+    view: View;
+    viewInputs?: ViewInputsOf<View>;
+    toParentMessage: (message: ViewMessageOf<View>) => unknown;
+}>;
+export declare const submodel: <View extends AnySubmodelView>(config: SubmodelConfig<View>) => VNode | null;
+export {};
+//# sourceMappingURL=submodel.d.ts.map

package/dist/html/submodel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submodel.d.ts","sourceRoot":"","sources":["../../src/html/submodel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAoBvC,QAAA,MAAM,sBAAsB,sBAAsB,CAAA;AAElD;;;;;;;;;;;;;;;;;;;;;gCAqBgC;AAChC,MAAM,MAAM,YAAY,CACtB,KAAK,EACL,OAAO,EACP,UAAU,GAAG,IAAI,IACf,CAAC,UAAU,SAAS,IAAI,GACxB,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,GAAG,IAAI,GAC9B,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,KAAK,KAAK,GAAG,IAAI,CAAC,GAAG;IAC5D,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAC3C,CAAA;AAED;;;;;;;;;yDASyD;AACzD,eAAO,MAAM,UAAU,GAAI,KAAK,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,EAC1D,IAAI,UAAU,SAAS,IAAI,GACvB,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,GAAG,IAAI,GAC9B,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,KAAK,KAAK,GAAG,IAAI,KACzD,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAQM,CAAA;AAEhD,KAAK,eAAe,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,KAAK,KAAK,GAAG,IAAI,CAAC,GAAG;IACvE,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAC3C,CAAA;AAED,KAAK,WAAW,CAAC,IAAI,SAAS,eAAe,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;AAEpE,KAAK,YAAY,CAAC,IAAI,SAAS,eAAe,IAC5C,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,UAAU,CAAC,GAAG,UAAU,GAAG,IAAI,CAAA;AAE1E,KAAK,aAAa,CAAC,IAAI,SAAS,eAAe,IAAI,IAAI,SAAS;IAC9D,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAA;CACjD,GACG,OAAO,GACP,KAAK,CAAA;AAET;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wCAyCwC;AACxC,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,eAAe,IAAI,QAAQ,CAAC;IAClE,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;IACxB,IAAI,EAAE,IAAI,CAAA;IACV,UAAU,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,CAAA;IAC/B,eAAe,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,KAAK,OAAO,CAAA;CAC3D,CAAC,CAAA;AA2IF,eAAO,MAAM,QAAQ,GAAI,IAAI,SAAS,eAAe,EACnD,QAAQ,cAAc,CAAC,IAAI,CAAC,KAC3B,KAAK,GAAG,IAsDV,CAAA"}

package/dist/html/submodel.js

@@ -0,0 +1,190 @@
+import { Predicate } from 'effect';
+import { composeBoundary, deregisterBoundaryWrap, registerBoundaryWrap, } from './boundary.js';
+import { isChildAttribute } from './childAttribute.js';
+import { clearRuntime, getCurrentFrame, pushBoundary, pushFrame, } from './runtimeSingleton.js';
+// NOTE: string key (not Symbol) so SubmodelView types from different
+// module instances (e.g. pnpm hoisting variations) stay structurally
+// compatible.
+const SUBMODEL_MESSAGE_BRAND = '__submodelMessage';
+/** Defines the view function of a Submodel, a child component embedded
+ *  via `h.submodel`.
+ *
+ *  Use this ONLY for views that will be embedded via `h.submodel`. Plain
+ *  view functions (page-level render functions, helper render functions
+ *  that compose Html, etc.) don't need to be defined this way. Write
+ *  them as ordinary `(model) => Html` functions.
+ *
+ *  Explicit type arguments are required because Message has no
+ *  inferable source on the function signature itself. */
+export const defineView = (fn) => 
+// NOTE: The cast attaches the SUBMODEL_MESSAGE_BRAND to the runtime
+// function value at the type level only. Message has no inferable
+// source on the function signature itself, so the brand carries it.
+// `h.submodel` reads the brand at the embed site to type-check
+// `toParentMessage`. There is no runtime brand to add; the cast is
+// the entire mechanism.
+/* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+fn;
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Walks below the top level of `viewInputs` and throws if it finds a
+ *  function. Top-level functions are auto-scoped to the parent
+ *  boundary; functions nested inside an object value or array element
+ *  would silently capture the child's boundary and dispatch through
+ *  the child's wrapping chain, which is almost certainly not what the
+ *  consumer meant. Failing loud at view-build time is cheaper than a
+ *  confused bug report from a misrouted Message. */
+const assertNoNestedFunctions = (viewInputs) => {
+    for (const key of Object.keys(viewInputs)) {
+        const value = viewInputs[key];
+        if (isFrameworkBranded(value)) {
+            continue;
+        }
+        if (isPlainObject(value) || Array.isArray(value)) {
+            walkForFunctions(value, [key]);
+        }
+    }
+};
+// Framework-branded values that legitimately carry function members
+// internally (e.g. `ChildAttribute.dispatch`). The walker treats these
+// as opaque leaves, the same way it treats primitives.
+const isFrameworkBranded = (value) => isChildAttribute(value);
+const walkForFunctions = (source, path) => {
+    const visit = (value, segment) => {
+        const nextPath = [...path, segment];
+        if (typeof value === 'function') {
+            throw new Error(`Foldkit: h.submodel \`viewInputs\` may only contain functions at the ` +
+                `top level. Found a function at \`viewInputs.${nextPath.join('.')}\`. ` +
+                `Lift it to the top level of \`viewInputs\` so it can be auto-scoped to ` +
+                `the parent boundary, or pass the value as primitive data.`);
+        }
+        if (isFrameworkBranded(value)) {
+            return;
+        }
+        if (isPlainObject(value) || Array.isArray(value)) {
+            walkForFunctions(value, nextPath);
+        }
+    };
+    if (Array.isArray(source)) {
+        source.forEach((element, index) => visit(element, `[${index}]`));
+    }
+    else if (isPlainObject(source)) {
+        for (const key of Object.keys(source)) {
+            visit(source[key], key);
+        }
+    }
+};
+const wrapViewInputsForOuterBoundary = (viewInputs, outerFrame) => {
+    if (!isPlainObject(viewInputs)) {
+        return viewInputs;
+    }
+    assertNoNestedFunctions(viewInputs);
+    const wrapped = {};
+    for (const key of Object.keys(viewInputs)) {
+        const value = viewInputs[key];
+        if (typeof value === 'function') {
+            // Capture the parent's full frame (dispatch, context, registry,
+            // boundaryId) at wrap time. The slot callback uses `pushFrame` to
+            // replay that exact frame on every invocation, regardless of what
+            // happens to be on the stack at call time. Without this, a
+            // callback invoked from a deferred context (setTimeout, stored
+            // callback) would inherit from whatever render's frame was active,
+            // silently mis-binding dispatch and registry.
+            wrapped[key] = (...args) => {
+                pushFrame(outerFrame);
+                try {
+                    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                    return value(...args);
+                }
+                finally {
+                    clearRuntime();
+                }
+            };
+        }
+        else {
+            wrapped[key] = value;
+        }
+    }
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+    return wrapped;
+};
+/** Returns a copy of the vnode with a snabbdom `destroy` hook that
+ *  deregisters this Submodel's boundary when the DOM node is removed.
+ *  Composes with any existing destroy hook the user's view may have set.
+ *
+ *  Copies the vnode (rather than mutating in place) so module-level
+ *  cached vnodes a user might return from view are not contaminated with
+ *  a destroy hook bound to this boundary id.
+ *
+ *  This is what lets `h.submodel` survive cache hits from
+ *  `createKeyedLazy`. When a cached vnode is reused across renders,
+ *  snabbdom doesn't fire destroy, so the wrap stays registered and
+ *  dispatches continue to route correctly. When the vnode is actually
+ *  removed (entry deleted from a list, conditional render flips),
+ *  destroy fires and the wrap is evicted: bounded memory, no leaks.
+ *
+ *  See `submodel.test.ts` for the cache-hit-survival and
+ *  destroy-deregisters-wrap assertions. */
+const withBoundaryCleanup = (vnode, registry, boundaryId) => {
+    const data = vnode.data ?? {};
+    const hook = data.hook ?? {};
+    const previousDestroy = hook.destroy;
+    const compositeDestroy = (removed) => {
+        deregisterBoundaryWrap(registry, boundaryId);
+        if (previousDestroy !== undefined) {
+            previousDestroy(removed);
+        }
+    };
+    return {
+        ...vnode,
+        data: { ...data, hook: { ...hook, destroy: compositeDestroy } },
+    };
+};
+export const submodel = (config) => {
+    // Snapshot the parent frame BEFORE pushing the child boundary. The
+    // snapshot is captured into slot-callback closures by
+    // `wrapViewInputsForOuterBoundary` so they can replay the parent's
+    // full frame when invoked.
+    const parentFrame = getCurrentFrame();
+    const registry = parentFrame.boundaryRegistry;
+    const childBoundaryId = composeBoundary(parentFrame.boundaryId, config.slotId);
+    registerBoundaryWrap(registry, childBoundaryId, {
+        toParentMessage: 
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        config.toParentMessage,
+    });
+    let vnode;
+    pushBoundary(childBoundaryId);
+    try {
+        try {
+            if (Predicate.isUndefined(config.viewInputs)) {
+                /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                const view = config.view;
+                vnode = view(config.model);
+            }
+            else {
+                const wrappedViewInputs = wrapViewInputsForOuterBoundary(
+                /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                config.viewInputs, parentFrame);
+                /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                const view = config.view;
+                vnode = view(config.model, wrappedViewInputs);
+            }
+        }
+        catch (error) {
+            // The view threw; the registered wrap would otherwise leak with
+            // no destroy hook ever firing. Drop it before propagating.
+            deregisterBoundaryWrap(registry, childBoundaryId);
+            throw error;
+        }
+    }
+    finally {
+        clearRuntime();
+    }
+    if (vnode === null) {
+        // No vnode means no destroy hook will ever fire; deregister now so
+        // the wrap doesn't leak.
+        deregisterBoundaryWrap(registry, childBoundaryId);
+        return null;
+    }
+    return withBoundaryCleanup(vnode, registry, childBoundaryId);
+};

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * as Route from './route/public.js';
 export * as Runtime from './runtime/public.js';
 export * as Schema from './schema/public.js';
 export * as Struct from './struct/public.js';
+export * as Submodel from './submodel/public.js';
 export * as Subscription from './subscription/public.js';
 export * as Scene from './test/scene.js';
 export * as Story from './test/story.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,aAAa,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,GAAG,MAAM,iBAAiB,CAAA;AACtC,OAAO,KAAK,eAAe,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,eAAe,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,YAAY,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,KAAK,MAAM,iBAAiB,CAAA;AACxC,OAAO,KAAK,KAAK,MAAM,iBAAiB,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,GAAG,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,aAAa,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,GAAG,MAAM,iBAAiB,CAAA;AACtC,OAAO,KAAK,eAAe,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,eAAe,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,YAAY,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,KAAK,MAAM,iBAAiB,CAAA;AACxC,OAAO,KAAK,KAAK,MAAM,iBAAiB,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,GAAG,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -15,6 +15,7 @@ export * as Route from './route/public.js';
 export * as Runtime from './runtime/public.js';
 export * as Schema from './schema/public.js';
 export * as Struct from './struct/public.js';
+export * as Submodel from './submodel/public.js';
 export * as Subscription from './subscription/public.js';
 export * as Scene from './test/scene.js';
 export * as Story from './test/story.js';

package/dist/render/render.d.ts

@@ -33,7 +33,7 @@ export declare const afterCommit: Effect.Effect<void>;
  *
  * @example
  * ```typescript
- * Render.afterPaint.pipe(Effect.as(TransitionFrameAdvanced()))
+ * Render.afterPaint
  * ```
  */
 export declare const afterPaint: Effect.Effect<void>;