foldkit 0.101.0 → 0.102.0

package/dist/dom/scrollLock.js

@@ -46,7 +46,7 @@ const handleTouchMove = (event) => {
  *
  * @example
  * ```typescript
- * Dom.lockScroll.pipe(Effect.as(CompletedLockScroll()))
+ * Dom.lockScroll
  * ```
  */
 export const lockScroll = Effect.sync(() => {
@@ -73,7 +73,7 @@ export const lockScroll = Effect.sync(() => {
  *
  * @example
  * ```typescript
- * Dom.unlockScroll.pipe(Effect.as(CompletedUnlockScroll()))
+ * Dom.unlockScroll
  * ```
  */
 export const unlockScroll = Effect.sync(() => {

package/dist/dom/waitForAnimation.d.ts

@@ -10,7 +10,7 @@ import { Effect } from 'effect';
  *
  * @example
  * ```typescript
- * Dom.waitForAnimationSettled('#menu-items').pipe(Effect.as(EndedAnimation()))
+ * Dom.waitForAnimationSettled('#menu-items')
  * ```
  */
 export declare const waitForAnimationSettled: (selector: string) => Effect.Effect<void>;

package/dist/dom/waitForAnimation.js

@@ -10,7 +10,7 @@ import { Effect } from 'effect';
  *
  * @example
  * ```typescript
- * Dom.waitForAnimationSettled('#menu-items').pipe(Effect.as(EndedAnimation()))
+ * Dom.waitForAnimationSettled('#menu-items')
  * ```
  */
 export const waitForAnimationSettled = (selector) => Effect.callback(resume => {

package/dist/html/boundary.d.ts

@@ -0,0 +1,98 @@
+import type { DispatchSync } from './runtimeSingleton.js';
+/** Wrapping descriptor stored per Submodel boundary. */
+export type WrapDescriptor = Readonly<{
+    toParentMessage: (message: unknown) => unknown;
+}>;
+/** Boundary id is a `|`-joined chain of Submodel slot ids. Empty
+ *  string represents the root boundary. Two-level example:
+ *  `"work-history|entry-abc123"`. User-supplied slot ids must not
+ *  contain the separator character; {@link composeBoundary} throws when
+ *  they do. */
+export type BoundaryId = string;
+export declare const ROOT_BOUNDARY: BoundaryId;
+export declare const composeBoundary: (parent: BoundaryId, childId: string) => BoundaryId;
+/** Per-runtime registry of Submodel wrapping descriptors. The runtime
+ *  creates one of these in `start` and reuses it across renders.
+ *  `h.submodel` writes into `wraps` each render and attaches a snabbdom
+ *  `destroy` hook that calls `deregisterBoundaryWrap` when the
+ *  corresponding vnode is removed from the DOM tree. The dispatch path
+ *  reads from `wraps` at event-fire time.
+ *
+ *  `boundaryDispatches` caches per-(outerDispatch, boundaryId) dispatcher
+ *  closures so `requireDispatch` returns a stable reference across
+ *  repeated calls with the same outerDispatch (necessary for
+ *  `createLazy`'s dispatch-identity check). Keyed by outerDispatch as a
+ *  WeakMap so DevTools jump-to renders with a different
+ *  outerDispatch (typically a noOpDispatch that drops messages) get
+ *  their own per-boundary cache. Without this two-level keying, a
+ *  dispatcher created during a live render would still close over the
+ *  live outerDispatch after a jump-to and silently mutate the live app.
+ *
+ *  `seenThisRender` tracks boundaries marked alive during the current
+ *  render for duplicate-slotId detection: two `h.submodel` calls
+ *  inside the same parent boundary must use different `slotId`s.
+ *  Values are the call site captured at register time, surfaced when a
+ *  second register collides so both locations land in the throw
+ *  message. The map is cleared at the start of each render via
+ *  `beginRender`. Boundaries behind a `createLazy`/`createKeyedLazy`
+ *  cache hit are replayed into this map via {@link markSeenForLazyHit}
+ *  so the duplicate-slotId guard catches collisions against memoized
+ *  siblings, not just against siblings that re-ran this frame. It is
+ *  NOT used for pruning; pruning is driven by VNode destroy hooks
+ *  instead.
+ *
+ *  `lazyTrackingStack` is a stack of sets used by `createLazy` and
+ *  `createKeyedLazy` to capture which boundary ids were marked alive
+ *  during the wrapped function's first execution. On a later cache
+ *  hit, the lazy helper replays the captured ids into
+ *  `seenThisRender` so the duplicate-slotId guard sees them. Each
+ *  active lazy invocation pushes its own set; `registerBoundaryWrap`
+ *  and `markSeenForLazyHit` write to every set on the stack so an
+ *  outer lazy correctly captures ids contributed by inner lazies it
+ *  wraps. */
+export type BoundaryRegistry = {
+    readonly wraps: Map<BoundaryId, WrapDescriptor>;
+    readonly boundaryDispatches: WeakMap<DispatchSync, Map<BoundaryId, DispatchSync>>;
+    readonly seenThisRender: Map<BoundaryId, string>;
+    readonly lazyTrackingStack: Array<Map<BoundaryId, string>>;
+};
+export declare const createBoundaryRegistry: () => BoundaryRegistry;
+export declare const registerBoundaryWrap: (registry: BoundaryRegistry, boundaryId: BoundaryId, descriptor: WrapDescriptor) => void;
+/** Starts capturing boundary registrations on a fresh set pushed onto
+ *  `lazyTrackingStack`. Used by `createLazy`/`createKeyedLazy` around the
+ *  wrapped view function. Must be paired with {@link endLazyTracking} on
+ *  the same call stack so an exception inside the view does not leak the
+ *  tracking frame to a later render. */
+export declare const beginLazyTracking: (registry: BoundaryRegistry) => Map<BoundaryId, string>;
+/** Pops the most recent tracking set. Throws when called on an empty
+ *  stack to surface unmatched begin/end pairs immediately rather than
+ *  silently corrupting later renders. */
+export declare const endLazyTracking: (registry: BoundaryRegistry) => void;
+/** Replays a set of boundary ids captured during a previous lazy run
+ *  into `seenThisRender` so the duplicate-slotId guard sees them. Also
+ *  forwards them into any active tracking sets so an outer lazy
+ *  wrapping this cache hit captures the ids in its own snapshot.
+ *
+ *  Skips ids already present in `seenThisRender` to preserve the
+ *  original call site of the live entry (the first registration this
+ *  render still wins the error message). */
+export declare const markSeenForLazyHit: (registry: BoundaryRegistry, trackedIds: ReadonlyMap<BoundaryId, string>) => void;
+/** Removes a boundary's wrap. Called by `h.submodel`'s destroy hook when
+ *  the corresponding vnode leaves the DOM.
+ *
+ *  Does not touch `boundaryDispatches`: it is a WeakMap keyed by
+ *  outerDispatch, so per-outerDispatch inner Maps become unreachable and
+ *  are GC'd when their outerDispatch is. Cached dispatcher closures that
+ *  outlive a deregister become inert. `dispatchAcrossBoundary` throws
+ *  when it cannot find an ancestor wrap, which surfaces a clear error
+ *  rather than letting events from a destroyed boundary silently
+ *  misroute. */
+export declare const deregisterBoundaryWrap: (registry: BoundaryRegistry, boundaryId: BoundaryId) => void;
+export declare const getOrCreateBoundaryDispatch: (registry: BoundaryRegistry, outerDispatch: DispatchSync, boundaryId: BoundaryId) => DispatchSync;
+/** Called at the start of each top-level render. Clears the
+ *  per-render duplicate-slotId tracking map so siblings inside the
+ *  same parent boundary can be re-validated. Does NOT touch `wraps`
+ *  or `boundaryDispatches`. Those persist across renders and are
+ *  evicted by vnode destroy hooks instead. */
+export declare const beginRender: (registry: BoundaryRegistry) => void;
+//# sourceMappingURL=boundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.d.ts","sourceRoot":"","sources":["../../src/html/boundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAA;CAC/C,CAAC,CAAA;AAEF;;;;eAIe;AACf,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAI/B,eAAO,MAAM,aAAa,EAAE,UAAe,CAAA;AAE3C,eAAO,MAAM,eAAe,GAC1B,QAAQ,UAAU,EAClB,SAAS,MAAM,KACd,UAUF,CAAA;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAsCa;AACb,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,UAAU,EAAE,cAAc,CAAC,CAAA;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAClC,YAAY,EACZ,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC,CAC9B,CAAA;IACD,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;IAChD,QAAQ,CAAC,iBAAiB,EAAE,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAA;CAC3D,CAAA;AAED,eAAO,MAAM,sBAAsB,QAAO,gBAKxC,CAAA;AAqBF,eAAO,MAAM,oBAAoB,GAC/B,UAAU,gBAAgB,EAC1B,YAAY,UAAU,EACtB,YAAY,cAAc,KACzB,IA6BF,CAAA;AAED;;;;wCAIwC;AACxC,eAAO,MAAM,iBAAiB,GAC5B,UAAU,gBAAgB,KACzB,GAAG,CAAC,UAAU,EAAE,MAAM,CAIxB,CAAA;AAED;;yCAEyC;AACzC,eAAO,MAAM,eAAe,GAAI,UAAU,gBAAgB,KAAG,IAQ5D,CAAA;AAED;;;;;;;4CAO4C;AAC5C,eAAO,MAAM,kBAAkB,GAC7B,UAAU,gBAAgB,EAC1B,YAAY,WAAW,CAAC,UAAU,EAAE,MAAM,CAAC,KAC1C,IAWF,CAAA;AAED;;;;;;;;;gBASgB;AAChB,eAAO,MAAM,sBAAsB,GACjC,UAAU,gBAAgB,EAC1B,YAAY,UAAU,KACrB,IAEF,CAAA;AA4CD,eAAO,MAAM,2BAA2B,GACtC,UAAU,gBAAgB,EAC1B,eAAe,YAAY,EAC3B,YAAY,UAAU,KACrB,YAkBF,CAAA;AAED;;;;8CAI8C;AAC9C,eAAO,MAAM,WAAW,GAAI,UAAU,gBAAgB,KAAG,IAExD,CAAA"}

package/dist/html/boundary.js

@@ -0,0 +1,176 @@
+const BOUNDARY_SEPARATOR = '|';
+export const ROOT_BOUNDARY = '';
+export const composeBoundary = (parent, childId) => {
+    if (childId.includes(BOUNDARY_SEPARATOR)) {
+        throw new Error(`Foldkit: h.submodel slotId cannot contain the boundary separator ` +
+            `"${BOUNDARY_SEPARATOR}". Got ${JSON.stringify(childId)}.`);
+    }
+    return parent === ROOT_BOUNDARY
+        ? childId
+        : `${parent}${BOUNDARY_SEPARATOR}${childId}`;
+};
+const splitBoundary = (boundaryId) => boundaryId === ROOT_BOUNDARY ? [] : boundaryId.split(BOUNDARY_SEPARATOR);
+export const createBoundaryRegistry = () => ({
+    wraps: new Map(),
+    boundaryDispatches: new WeakMap(),
+    seenThisRender: new Map(),
+    lazyTrackingStack: [],
+});
+const captureCallSite = () => {
+    const stack = new Error().stack ?? '';
+    const lines = stack.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0 ||
+            trimmed.startsWith('Error') ||
+            trimmed.includes('captureCallSite') ||
+            trimmed.includes('registerBoundaryWrap') ||
+            trimmed.includes('at submodel')) {
+            continue;
+        }
+        return trimmed;
+    }
+    return '(call site unavailable)';
+};
+export const registerBoundaryWrap = (registry, boundaryId, descriptor) => {
+    const existingCallSite = registry.seenThisRender.get(boundaryId);
+    if (existingCallSite !== undefined) {
+        const ownSlotId = boundaryId.includes(BOUNDARY_SEPARATOR)
+            ? boundaryId.slice(boundaryId.lastIndexOf(BOUNDARY_SEPARATOR) + 1)
+            : boundaryId;
+        const newCallSite = captureCallSite();
+        throw new Error(`Foldkit: duplicate h.submodel slotId "${ownSlotId}" at boundary "${boundaryId}".\n` +
+            `  First registration: ${existingCallSite}\n` +
+            `  Second registration: ${newCallSite}\n` +
+            `Each h.submodel call inside the same parent boundary must use a unique \`slotId\`. ` +
+            `The slotId is DOM-slot identity, not model identity. If the same model is ` +
+            `rendered in two locations (desktop + mobile, master + detail), each slot ` +
+            `needs its own id (e.g. "desktop-foo", "mobile-foo"). For lists, use a stable ` +
+            `per-item identifier.`);
+    }
+    // NOTE: compute the call site before writing either map. If
+    // captureCallSite throws (e.g. hardened runtime without
+    // Error.stack), neither map is mutated, so a later registration
+    // with the same slotId throws the duplicate error correctly instead
+    // of silently overwriting after a half-finished prior write.
+    const callSite = captureCallSite();
+    registry.wraps.set(boundaryId, descriptor);
+    registry.seenThisRender.set(boundaryId, callSite);
+    for (const tracked of registry.lazyTrackingStack) {
+        tracked.set(boundaryId, callSite);
+    }
+};
+/** Starts capturing boundary registrations on a fresh set pushed onto
+ *  `lazyTrackingStack`. Used by `createLazy`/`createKeyedLazy` around the
+ *  wrapped view function. Must be paired with {@link endLazyTracking} on
+ *  the same call stack so an exception inside the view does not leak the
+ *  tracking frame to a later render. */
+export const beginLazyTracking = (registry) => {
+    const tracked = new Map();
+    registry.lazyTrackingStack.push(tracked);
+    return tracked;
+};
+/** Pops the most recent tracking set. Throws when called on an empty
+ *  stack to surface unmatched begin/end pairs immediately rather than
+ *  silently corrupting later renders. */
+export const endLazyTracking = (registry) => {
+    if (registry.lazyTrackingStack.length === 0) {
+        throw new Error('Foldkit: endLazyTracking called on an empty stack. This means a ' +
+            '`beginLazyTracking` was not paired with `endLazyTracking` upstream.');
+    }
+    registry.lazyTrackingStack.pop();
+};
+/** Replays a set of boundary ids captured during a previous lazy run
+ *  into `seenThisRender` so the duplicate-slotId guard sees them. Also
+ *  forwards them into any active tracking sets so an outer lazy
+ *  wrapping this cache hit captures the ids in its own snapshot.
+ *
+ *  Skips ids already present in `seenThisRender` to preserve the
+ *  original call site of the live entry (the first registration this
+ *  render still wins the error message). */
+export const markSeenForLazyHit = (registry, trackedIds) => {
+    for (const [boundaryId, callSite] of trackedIds) {
+        if (!registry.seenThisRender.has(boundaryId)) {
+            registry.seenThisRender.set(boundaryId, callSite);
+        }
+        for (const outerTracked of registry.lazyTrackingStack) {
+            if (!outerTracked.has(boundaryId)) {
+                outerTracked.set(boundaryId, callSite);
+            }
+        }
+    }
+};
+/** Removes a boundary's wrap. Called by `h.submodel`'s destroy hook when
+ *  the corresponding vnode leaves the DOM.
+ *
+ *  Does not touch `boundaryDispatches`: it is a WeakMap keyed by
+ *  outerDispatch, so per-outerDispatch inner Maps become unreachable and
+ *  are GC'd when their outerDispatch is. Cached dispatcher closures that
+ *  outlive a deregister become inert. `dispatchAcrossBoundary` throws
+ *  when it cannot find an ancestor wrap, which surfaces a clear error
+ *  rather than letting events from a destroyed boundary silently
+ *  misroute. */
+export const deregisterBoundaryWrap = (registry, boundaryId) => {
+    registry.wraps.delete(boundaryId);
+};
+/** Applies the wrapping chain for `boundaryId` from innermost to
+ *  outermost, then dispatches the fully-wrapped message via
+ *  `outerDispatch`. Called at event-fire time by the dispatcher closure
+ *  returned from `getOrCreateBoundaryDispatch`.
+ *
+ *  Throws when an ancestor wrap is missing from the registry. DOM events
+ *  fire synchronously, so a sync handler against a live boundary always
+ *  finds a complete chain. A missing wrap implies one of: (a) the wrap
+ *  was deregistered between event scheduling and dispatch (e.g. a slot
+ *  callback captured at one render is invoked from a deferred context
+ *  after the Submodel unmounted), or (b) the registry is corrupt.
+ *  Either way, silently skipping the ancestor and applying only outer
+ *  wraps would produce a malformed Message that the outermost
+ *  `Match.tagsExhaustive` would then crash on with no useful trace. */
+const dispatchAcrossBoundary = (registry, outerDispatch, boundaryId, message) => {
+    let wrapped = message;
+    const parts = splitBoundary(boundaryId);
+    for (let depth = parts.length; depth > 0; depth--) {
+        const ancestorBoundary = parts.slice(0, depth).join(BOUNDARY_SEPARATOR);
+        const descriptor = registry.wraps.get(ancestorBoundary);
+        if (descriptor === undefined) {
+            throw new Error(`Foldkit: dispatchAcrossBoundary missing wrap for ancestor ` +
+                `"${ancestorBoundary}" of boundary "${boundaryId}". This means a ` +
+                `Submodel's wrap was deregistered between event scheduling and ` +
+                `dispatch. Most likely cause: a slot callback (h.submodel ` +
+                `\`viewInputs\` function value) was invoked from a deferred context ` +
+                `(setTimeout, Promise.then, stored callback) after the parent ` +
+                `Submodel unmounted. Slot callbacks must be invoked synchronously ` +
+                `inside the render in which they were created.`);
+        }
+        wrapped = descriptor.toParentMessage(wrapped);
+    }
+    outerDispatch(wrapped);
+};
+export const getOrCreateBoundaryDispatch = (registry, outerDispatch, boundaryId) => {
+    if (boundaryId === ROOT_BOUNDARY) {
+        return outerDispatch;
+    }
+    let perOuterDispatch = registry.boundaryDispatches.get(outerDispatch);
+    if (perOuterDispatch === undefined) {
+        perOuterDispatch = new Map();
+        registry.boundaryDispatches.set(outerDispatch, perOuterDispatch);
+    }
+    const existing = perOuterDispatch.get(boundaryId);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const dispatch = message => {
+        dispatchAcrossBoundary(registry, outerDispatch, boundaryId, message);
+    };
+    perOuterDispatch.set(boundaryId, dispatch);
+    return dispatch;
+};
+/** Called at the start of each top-level render. Clears the
+ *  per-render duplicate-slotId tracking map so siblings inside the
+ *  same parent boundary can be re-validated. Does NOT touch `wraps`
+ *  or `boundaryDispatches`. Those persist across renders and are
+ *  evicted by vnode destroy hooks instead. */
+export const beginRender = (registry) => {
+    registry.seenThisRender.clear();
+};

package/dist/html/childAttribute.d.ts

@@ -0,0 +1,44 @@
+import { type DispatchSync } from './runtimeSingleton.js';
+declare const BRAND = "__childAttribute";
+/** An attribute carrying a handler that dispatches through a Submodel
+ *  boundary's wrapping chain. Published by Submodels (typically Foldkit's
+ *  `Ui.*` primitives) for a parent to spread into its own element
+ *  attribute arrays. The parent does not know or care which child
+ *  produced these; the runtime routes each handler through the
+ *  originating Submodel's wrap chain at event-fire time.
+ *
+ *  Created via {@link childAttributes}. Element constructors accept
+ *  `ChildAttribute` alongside `Attribute<Message>` in their attribute
+ *  arrays. */
+export type ChildAttribute = Readonly<{
+    readonly [BRAND]: true;
+    readonly attribute: unknown;
+    readonly dispatch: DispatchSync;
+}>;
+export declare const isChildAttribute: (value: unknown) => value is ChildAttribute;
+/** Captures the current boundary's dispatcher and wraps each attribute
+ *  so handlers inside it route through that boundary's wrapping chain at
+ *  event-fire time, even when the attribute is later spread into a
+ *  parent's element in a different boundary.
+ *
+ *  Submodels call this when publishing attribute groups to a consumer's
+ *  `toView` slot callback:
+ *
+ *  ```ts
+ *  // Inside a SubmodelView running in the child's boundary:
+ *  return viewInputs.toView({
+ *    checkbox: childAttributes([
+ *      h.OnClick(Toggled()),
+ *      h.Role('checkbox'),
+ *    ]),
+ *    ...
+ *  })
+ *  ```
+ *
+ *  Without this binding step the consumer's element constructor would
+ *  process `h.OnClick(Toggled())` using the parent's dispatcher (because
+ *  the consumer's `toView` runs in the parent's boundary), bypassing the
+ *  Submodel's `toParentMessage`. */
+export declare const childAttributes: <Attribute>(attributes: ReadonlyArray<Attribute>) => ReadonlyArray<ChildAttribute>;
+export {};
+//# sourceMappingURL=childAttribute.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"childAttribute.d.ts","sourceRoot":"","sources":["../../src/html/childAttribute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,uBAAuB,CAAA;AAE1E,QAAA,MAAM,KAAK,qBAAqB,CAAA;AAEhC;;;;;;;;;cASc;AACd,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;CAChC,CAAC,CAAA;AAEF,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,cACI,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;;;;oCAsBoC;AACpC,eAAO,MAAM,eAAe,GAAI,SAAS,EACvC,YAAY,aAAa,CAAC,SAAS,CAAC,KACnC,aAAa,CAAC,cAAc,CAO9B,CAAA"}

package/dist/html/childAttribute.js

@@ -0,0 +1,34 @@
+import { requireDispatch } from './runtimeSingleton.js';
+const BRAND = '__childAttribute';
+export const isChildAttribute = (value) => typeof value === 'object' && value !== null && BRAND in value;
+/** Captures the current boundary's dispatcher and wraps each attribute
+ *  so handlers inside it route through that boundary's wrapping chain at
+ *  event-fire time, even when the attribute is later spread into a
+ *  parent's element in a different boundary.
+ *
+ *  Submodels call this when publishing attribute groups to a consumer's
+ *  `toView` slot callback:
+ *
+ *  ```ts
+ *  // Inside a SubmodelView running in the child's boundary:
+ *  return viewInputs.toView({
+ *    checkbox: childAttributes([
+ *      h.OnClick(Toggled()),
+ *      h.Role('checkbox'),
+ *    ]),
+ *    ...
+ *  })
+ *  ```
+ *
+ *  Without this binding step the consumer's element constructor would
+ *  process `h.OnClick(Toggled())` using the parent's dispatcher (because
+ *  the consumer's `toView` runs in the parent's boundary), bypassing the
+ *  Submodel's `toParentMessage`. */
+export const childAttributes = (attributes) => {
+    const dispatch = requireDispatch();
+    return attributes.map(attribute => ({
+        [BRAND]: true,
+        attribute,
+        dispatch,
+    }));
+};

package/dist/html/index.d.ts

@@ -1,9 +1,32 @@
-import { Data, Effect, Option, Stream } from 'effect';
+import { Context, Data, Option, Stream } from 'effect';
 import type { File } from '../file/index.js';
 import type { MountAction } from '../mount/index.js';
-import { Dispatch } from '../runtime/index.js';
 import { VNode } from '../vdom.js';
+import { type ChildAttribute } from './childAttribute.js';
+import { type DispatchSync } from './runtimeSingleton.js';
 export { createKeyedLazy, createLazy } from './lazy.js';
+export { beginRender as __beginRender, createBoundaryRegistry as __createBoundaryRegistry, } from './boundary.js';
+export type { BoundaryRegistry } from './boundary.js';
+export { childAttributes } from './childAttribute.js';
+export type { ChildAttribute } from './childAttribute.js';
+export { defineView, submodel } from './submodel.js';
+export type { SubmodelConfig, SubmodelView } from './submodel.js';
+/** Pushes a dispatch and runtime context frame for the duration of a render.
+ *  The runtime calls this immediately before invoking a user `view` and
+ *  matches it with {@link __clearRuntime} in a `finally` so an exception
+ *  inside view code does not leak the frame to the next render. Test
+ *  scaffolding that builds VNodes outside of a real program (Scene, Canvas
+ *  view-only tests, Mount tests) uses the same pair. Nested frames are
+ *  supported via an internal stack. */
+export declare const __setRuntime: (dispatch: DispatchSync, runtimeContext: Context.Context<never>, boundaryRegistry?: import("./boundary.js").BoundaryRegistry) => void;
+/** Pops the current dispatch and runtime context frame. Must be paired with a
+ *  prior {@link __setRuntime} on the same call stack. */
+export declare const __clearRuntime: () => void;
+/** Returns the current dispatch function. Foldkit's `Canvas.view` reads this
+ *  to build its synchronous pointer handlers, since it builds VNodes directly
+ *  rather than going through the html factory. Most application code never
+ *  needs to call this. */
+export declare const __requireDispatch: () => DispatchSync;
 /**
  * The `id` of the DOM element that hosts the Foldkit DevTools shadow root.
  * Lives here (not in `devTools/`) because the `OnBlur` handler below uses it
@@ -16,7 +39,7 @@ export declare const DEVTOOLS_HOST_ID = "foldkit-devtools";
  * Tag symbol attached to file-aware event handler functions so Scene test
  * helpers can distinguish `OnFileChange` from `OnChange` (both register on
  * the DOM `change` event) and `OnDropFiles` from `OnDrop` (both register on
- * the DOM `drop` event). Internal implementation detail — consumer code
+ * the DOM `drop` event). Internal implementation detail. Consumer code
  * should never need to reference this directly.
  */
 export declare const FileHandlerSymbol: unique symbol;
@@ -29,8 +52,10 @@ export type KeyboardModifiers = Readonly<{
     altKey: boolean;
     metaKey: boolean;
 }>;
-/** A virtual DOM element represented as an `Effect` that produces a `VNode`. */
-export type Html = Effect.Effect<VNode | null, never, Dispatch>;
+/** A virtual DOM element. Constructed synchronously by the element factories
+ *  returned from {@link html}. The runtime patches a `VNode` (or `null` to
+ *  render nothing) into the application container. */
+export type Html = VNode | null;
 export type Child = Html | string;
 /** A view's complete output for the runtime: title, body, and optional document
  *  metadata. The runtime applies `title` to `document.title`, syncs `canonical`
@@ -60,7 +85,15 @@ export type FoldkitMountMarker = Readonly<{
     name: string;
     args?: Record<string, unknown>;
 }>;
-/** Union of all HTML, SVG, and MathML attributes a virtual DOM element can carry. */
+/** Union of all HTML, SVG, and MathML attributes a virtual DOM element can carry.
+ *
+ *  When a Submodel publishes attribute groups to a consumer's `toView`
+ *  slot, those attributes are wrapped via {@link childAttributes} into
+ *  {@link ChildAttribute}, a distinct type that carries the Submodel's
+ *  own dispatcher. Element constructors accept the union
+ *  `ReadonlyArray<Attribute<Message> | ChildAttribute>`, so consumers
+ *  can spread published bundles directly into their own attribute
+ *  arrays. */
 export type Attribute<Message> = Data.TaggedEnum<{
     Key: {
         readonly value: string;
@@ -798,22 +831,27 @@ declare const Prop: <A>(args: {
     readonly f: (event: CustomEvent<any>) => A;
 };
 export { Prop, OnCustomEvent };
-export declare const customElement: <Message>() => (tagName: string) => (attributes?: ReadonlyArray<Attribute<Message>>, children?: ReadonlyArray<Child>) => Html;
-type ElementFunction<Message> = (attributes: ReadonlyArray<Attribute<Message>>, children: ReadonlyArray<Child>) => Html;
-type VoidElementFunction<Message> = (attributes: ReadonlyArray<Attribute<Message>>) => Html;
-/**
- * Factory that returns all HTML, SVG, and MathML element constructors,
- * attribute constructors, a `keyed` helper for keyed elements, and `empty`
- * for rendering nothing.
- */
-export declare const html: <Message = never>() => {
-    empty: Effect.Effect<null, never, never>;
-    keyed: (tagName: TagName) => (key: string, attributes?: readonly ({
+export declare const customElement: <Message>() => (tagName: string) => (attributes?: ReadonlyArray<Attribute<Message> | ChildAttribute>, children?: ReadonlyArray<Child>) => Html;
+type ElementFunction<Message> = (attributes: ReadonlyArray<Attribute<Message> | ChildAttribute>, children: ReadonlyArray<Child>) => Html;
+type VoidElementFunction<Message> = (attributes: ReadonlyArray<Attribute<Message> | ChildAttribute>) => Html;
+declare const buildHtmlFactory: <Message>() => {
+    empty: null;
+    keyed: (tagName: TagName) => (key: string, attributes?: readonly (Readonly<{
+        readonly attribute: unknown;
+        readonly dispatch: DispatchSync;
+        readonly __childAttribute: true;
+    }> | {
         readonly _tag: "Type";
         readonly value: string;
     } | {
         readonly _tag: "Start";
         readonly value: number;
+    } | {
+        readonly _tag: "OnFileChange";
+        readonly f: (files: ReadonlyArray<File>) => Message;
+    } | {
+        readonly _tag: "OnDropFiles";
+        readonly f: (files: ReadonlyArray<File>) => Message;
     } | {
         readonly _tag: "Key";
         readonly value: string;
@@ -953,9 +991,6 @@ export declare const html: <Message = never>() => {
     } | {
         readonly _tag: "OnChange";
         readonly f: (value: string) => Message;
-    } | {
-        readonly _tag: "OnFileChange";
-        readonly f: (files: ReadonlyArray<File>) => Message;
     } | {
         readonly _tag: "OnSubmit";
         readonly message: Message;
@@ -1009,9 +1044,6 @@ export declare const html: <Message = never>() => {
     } | {
         readonly _tag: "OnDrop";
         readonly message: Message;
-    } | {
-        readonly _tag: "OnDropFiles";
-        readonly f: (files: ReadonlyArray<File>) => Message;
     } | {
         readonly _tag: "OnTouchStart";
         readonly message: Message;
@@ -1558,6 +1590,9 @@ export declare const html: <Message = never>() => {
             f: (element: Element) => Stream.Stream<Message, any, never>;
         }>;
     })[], children?: ReadonlyArray<Child>) => Html;
+    submodel: <View extends ((...args: ReadonlyArray<any>) => VNode | null) & {
+        readonly __submodelMessage: unknown;
+    }>(config: import("./submodel.js").SubmodelConfig<View>) => VNode | null;
     Key: (value: string) => {
         readonly _tag: "Key";
         readonly value: string;
@@ -2779,4 +2814,16 @@ export declare const html: <Message = never>() => {
     munderover: ElementFunction<Message>;
     semantics: ElementFunction<Message>;
 };
+/**
+ * Returns all HTML, SVG, and MathML element constructors, attribute
+ * constructors, a `keyed` helper for keyed elements, and `empty` for
+ * rendering nothing.
+ *
+ * The returned object is a process-wide singleton. The `Message` type
+ * parameter is erased at runtime, and the element and attribute constructors
+ * carry no per-program state (dispatch is read from the runtime singleton at
+ * call time), so calling `html()` repeatedly from inside view functions does
+ * not allocate a fresh object.
+ */
+export declare const html: <Message = never>() => ReturnType<typeof buildHtmlFactory<Message>>;
 //# sourceMappingURL=index.d.ts.map