foldkit 0.157.0 → 0.158.0

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

@@ -1 +1 @@
-{"version":3,"file":"browserListeners.d.ts","sourceRoot":"","sources":["../../src/runtime/browserListeners.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,eAAO,MAAM,2BAA2B,GAAI,OAAO,YACvC,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,iBACrB,aAAa,CAAC,OAAO,CAAC,KACpC,CAAC,MAAM,IAAI,CAWb,CAAA;AAgBD,eAAO,MAAM,oBAAoB,GAAI,OAAO,YAChC,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,iBACrB,aAAa,CAAC,OAAO,CAAC,KACpC,CAAC,MAAM,IAAI,CAwDb,CAAA"}
+{"version":3,"file":"browserListeners.d.ts","sourceRoot":"","sources":["../../src/runtime/browserListeners.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AAErC,oFAAoF;AACpF,MAAM,MAAM,aAAa,CAAC,OAAO,IAAI,QAAQ,CAAC;IAC5C,YAAY,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAA;IAC9C,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAA;CACnC,CAAC,CAAA;AAEF,eAAO,MAAM,2BAA2B,GAAI,OAAO,YACvC,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,iBACrB,aAAa,CAAC,OAAO,CAAC,KACpC,CAAC,MAAM,IAAI,CAWb,CAAA;AAgBD,eAAO,MAAM,oBAAoB,GAAI,OAAO,YAChC,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,iBACrB,aAAa,CAAC,OAAO,CAAC,KACpC,CAAC,MAAM,IAAI,CAwDb,CAAA"}

package/dist/runtime/browserScheduler.d.ts

@@ -0,0 +1,3 @@
+import { Effect } from 'effect';
+export declare const provideBrowserScheduler: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+//# sourceMappingURL=browserScheduler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browserScheduler.d.ts","sourceRoot":"","sources":["../../src/runtime/browserScheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,QAAQ,CAAA;AA0BjD,eAAO,MAAM,uBAAuB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UACrC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACsD,CAAA"}

package/dist/runtime/browserScheduler.js

@@ -0,0 +1,22 @@
+import { Effect, Layer, Scheduler } from 'effect';
+// NOTE: scheduling fix for browser performance. Effect needs to defer work
+// onto a future tick of the event loop. The default browser scheduler picks
+// `setTimeout(f, 0)`, but browsers clamp `setTimeout` to a minimum of 4ms.
+// `queueMicrotask` runs on the very next tick (sub-millisecond). Dispatch no
+// longer routes through the Effect scheduler, but Command and Subscription
+// fibers still do; without this override every fiber yield (for example, an
+// op-budget suspension, or a Stream step) would take an extra 4-16ms
+// round-trip before
+// its result Message lands.
+const microtaskSetImmediate = (callback) => {
+    let cancelled = false;
+    queueMicrotask(() => {
+        if (!cancelled)
+            callback();
+    });
+    return () => {
+        cancelled = true;
+    };
+};
+const browserScheduler = new Scheduler.MixedScheduler('async', microtaskSetImmediate);
+export const provideBrowserScheduler = (effect) => Effect.provide(effect, Layer.succeed(Scheduler.Scheduler, browserScheduler));

package/dist/runtime/crashUI.d.ts

@@ -1,10 +1,41 @@
-import { Effect } from 'effect';
-import { Document } from '../html/index.js';
+import { Effect, Option } from 'effect';
+import { Document, Html, type HtmlBuilder } from '../html/index.js';
+import { VNode } from '../vdom.js';
+/** Context provided to crash.view and crash.report when the runtime encounters
+ *  an unrecoverable error. `message` is the Message being processed when the
+ *  crash occurred, present as an `Option` because a crash during the initial
+ *  render has no triggering Message. */
+export type CrashContext<Model, Message> = Readonly<{
+    error: Error;
+    model: Model;
+    message: Option.Option<Message>;
+}>;
+/** Configuration for crash handling, with custom crash UI and/or crash
+ *  reporting. The crash view renders after the dispatch loop has stopped, so
+ *  its builder's Message is `never` and no handler is expressible. Reload or
+ *  navigate with a raw DOM attribute instead. */
+export type CrashConfig<Model, Message> = Readonly<{
+    view?: (context: CrashContext<Model, Message>, h: HtmlBuilder<never>) => Document;
+    report?: (context: CrashContext<Model, Message>) => void;
+}>;
+/** Configuration for crash handling in a `makeElement` app. The crash view
+ *  returns `Html`, not a `Document`, because a scoped app never owns the
+ *  document `<head>`. */
+export type ElementCrashConfig<Model, Message> = Readonly<{
+    view?: (context: CrashContext<Model, Message>, h: HtmlBuilder<never>) => Html;
+    report?: (context: CrashContext<Model, Message>) => void;
+}>;
 export declare const noOpDispatch: {
     dispatchAsync: (_message: unknown) => Effect.Effect<void, never, never>;
     dispatchSync: (_message: unknown) => void;
 };
-export declare const defaultCrashView: (context: Readonly<{
-    error: Error;
-}>, viewError?: unknown) => Document;
+export declare const defaultCrashView: (context: CrashContext<unknown, unknown>, viewError?: unknown) => Document;
+/** Mutable holder for the vnode tree currently mounted in the container.
+ *  The render frame writes it after every patch; the dispose finalizer, the
+ *  replay render, and {@link renderCrashView} read it. A plain object rather
+ *  than a Ref because every reader runs synchronously on the main thread. */
+export type VNodeSlot = {
+    maybeCurrentVNode: Option.Option<VNode>;
+};
+export declare const renderCrashView: <Model, Message>(context: CrashContext<Model, Message>, crash: CrashConfig<Model, Message> | undefined, container: HTMLElement, vnodeSlot: VNodeSlot, manageDocument: boolean) => void;
 //# sourceMappingURL=crashUI.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"crashUI.d.ts","sourceRoot":"","sources":["../../src/runtime/crashUI.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,OAAO,EAAE,QAAQ,EAAmB,MAAM,kBAAkB,CAAA;AAE5D,eAAO,MAAM,YAAY;IACvB,aAAa,aAAa,OAAO;IACjC,YAAY,aAAa,OAAO;CACjC,CAAA;AAmBD,eAAO,MAAM,gBAAgB,YAClB,QAAQ,CAAC;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC,cACvB,OAAO,KAClB,QAwLF,CAAA"}
+{"version":3,"file":"crashUI.d.ts","sourceRoot":"","sources":["../../src/runtime/crashUI.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEhD,OAAO,EACL,QAAQ,EACR,IAAI,EACJ,KAAK,WAAW,EAKjB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,KAAK,EAAgB,MAAM,YAAY,CAAA;AAIhD;;;wCAGwC;AACxC,MAAM,MAAM,YAAY,CAAC,KAAK,EAAE,OAAO,IAAI,QAAQ,CAAC;IAClD,KAAK,EAAE,KAAK,CAAA;IACZ,KAAK,EAAE,KAAK,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;CAChC,CAAC,CAAA;AAEF;;;iDAGiD;AACjD,MAAM,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,IAAI,QAAQ,CAAC;IACjD,IAAI,CAAC,EAAE,CACL,OAAO,EAAE,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,EACrC,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,KAClB,QAAQ,CAAA;IACb,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACzD,CAAC,CAAA;AAEF;;yBAEyB;AACzB,MAAM,MAAM,kBAAkB,CAAC,KAAK,EAAE,OAAO,IAAI,QAAQ,CAAC;IACxD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,IAAI,CAAA;IAC7E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACzD,CAAC,CAAA;AAEF,eAAO,MAAM,YAAY;IACvB,aAAa,aAAa,OAAO;IACjC,YAAY,aAAa,OAAO;CACjC,CAAA;AAmBD,eAAO,MAAM,gBAAgB,YAClB,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,cAC3B,OAAO,KAClB,QAwLF,CAAA;AAED;;;6EAG6E;AAC7E,MAAM,MAAM,SAAS,GAAG;IACtB,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;CACxC,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,KAAK,EAAE,OAAO,WACnC,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,SAC9B,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,SAAS,aACnC,WAAW,aACX,SAAS,kBACJ,OAAO,KACtB,IA8DF,CAAA"}

package/dist/runtime/crashUI.js

@@ -1,5 +1,9 @@
-import { Effect } from 'effect';
-import { inertHtml as ih } from '../html/index.js';
+import { Context, Effect, Option } from 'effect';
+import { __clearRuntime as clearHtmlRuntime, __htmlBuilder as htmlBuilderFor, inertHtml as ih, __setRuntime as setHtmlRuntime, } from '../html/index.js';
+import { MountTracker } from '../mount/index.js';
+import { __patchVNode } from '../vdom.js';
+import { Dispatch } from './dispatch.js';
+import { applyDocumentMetadata } from './documentMetadata.js';
 export const noOpDispatch = {
     dispatchAsync: (_message) => Effect.void,
     dispatchSync: (_message) => { },
@@ -163,3 +167,52 @@ export const defaultCrashView = (context, viewError) => {
     ]);
     return { title: 'Application Crash', body };
 };
+export const renderCrashView = (context, crash, container, vnodeSlot, manageDocument) => {
+    console.error('[foldkit] Application crash:', context.error);
+    if (crash?.report) {
+        try {
+            crash.report(context);
+        }
+        catch (reportError) {
+            console.error('[foldkit] crash.report failed:', reportError);
+        }
+    }
+    const crashContext = Context.make(Dispatch, noOpDispatch).pipe(Context.add(MountTracker, {
+        started: () => { },
+        ended: () => { },
+    }));
+    try {
+        setHtmlRuntime(noOpDispatch.dispatchSync, crashContext);
+        let crashDocument;
+        try {
+            crashDocument = crash?.view
+                ? crash.view(context, htmlBuilderFor())
+                : defaultCrashView(context);
+        }
+        finally {
+            clearHtmlRuntime();
+        }
+        const patchedVNode = __patchVNode(vnodeSlot.maybeCurrentVNode, crashDocument.body, container);
+        vnodeSlot.maybeCurrentVNode = Option.some(patchedVNode);
+        if (manageDocument) {
+            applyDocumentMetadata(crashDocument, patchedVNode.elm);
+        }
+    }
+    catch (viewError) {
+        console.error('[foldkit] crash.view failed:', viewError);
+        const fallbackViewError = viewError instanceof Error ? viewError : new Error(String(viewError));
+        setHtmlRuntime(noOpDispatch.dispatchSync, crashContext);
+        let fallbackDocument;
+        try {
+            fallbackDocument = defaultCrashView(context, fallbackViewError);
+        }
+        finally {
+            clearHtmlRuntime();
+        }
+        const patchedVNode = __patchVNode(vnodeSlot.maybeCurrentVNode, fallbackDocument.body, container);
+        vnodeSlot.maybeCurrentVNode = Option.some(patchedVNode);
+        if (manageDocument) {
+            applyDocumentMetadata(fallbackDocument, patchedVNode.elm);
+        }
+    }
+};

package/dist/runtime/devToolsConfig.d.ts

@@ -0,0 +1,85 @@
+import { Effect, Option, Schema, Scope } from 'effect';
+import type { DevToolsStore } from '../devTools/store.js';
+import { type Visibility } from './visibility.js';
+/** Position of the DevTools badge and panel on screen. */
+export type DevToolsPosition = 'BottomRight' | 'BottomLeft' | 'TopRight' | 'TopLeft';
+/** Controls DevTools interaction mode.
+ *
+ * - `'Inspect'`: Messages stream in and clicking a row shows its state snapshot without pausing the rendered view.
+ * - `'TimeTravel'`: Clicking a row installs a paused historical view while the live application continues. Resume to patch the latest live view.
+ */
+export type DevToolsMode = 'Inspect' | 'TimeTravel';
+/** Mode value for the DevTools panel. Either a single mode used in every
+ *  environment, or an object selecting different modes for development and
+ *  production. Use the object form to keep `'TimeTravel'` for local debugging
+ *  while shipping the safer `'Inspect'` mode to users. `'TimeTravel'` in
+ *  production pauses the user's rendered view when a history row is clicked. */
+export type DevToolsModeConfig = DevToolsMode | Readonly<{
+    development: DevToolsMode;
+    production: DevToolsMode;
+}>;
+/**
+ * Factory that mounts the in-browser DevTools overlay against a recording
+ * store. The runtime keeps the store and the WebSocket bridge (so external
+ * tooling like the DevTools MCP server works without an overlay); the visual
+ * overlay is injected so it can live in `@foldkit/devtools` and pull in
+ * `@foldkit/ui` without coupling the core runtime to either.
+ *
+ * Foldkit's Vite plugin supplies the installed overlay automatically. It is
+ * included in production when `@foldkit/devtools` is a regular dependency.
+ */
+export type DevToolsOverlay = (store: DevToolsStore, position: DevToolsPosition, mode: DevToolsMode, maybeBanner: Option.Option<string>) => Effect.Effect<void, never, Scope.Scope>;
+/**
+ * DevTools configuration.
+ *
+ * Pass `false` to disable DevTools entirely.
+ *
+ * - `show`: `'Development'` (default) enables in dev mode only, `'Always'` enables in all environments including production.
+ * - `position`: Where the badge and panel appear. Defaults to `'BottomRight'`.
+ * - `mode`: `'TimeTravel'` (default) enables full time-travel debugging by installing a paused historical view while the live application continues. `'Inspect'` allows browsing state snapshots without replacing the live view. Pass `{ development, production }` to use different modes per environment. Useful when DevTools is shown in production (`show: 'Always'`) and you want `'TimeTravel'` only in local development.
+ * - `banner`: Optional text shown as a banner at the top of the panel.
+ * - `excludeFromHistory`: Message `_tag` values whose dispatches should not be recorded in DevTools history. The Messages still drive `update` and the runtime as usual; they just don't appear in the history panel and don't pay the per-Message diff cost. Use for high-frequency Messages (animation frames, pointer moves, scroll events) that would flood history without adding insight.
+ * - `maxEntries`: Maximum number of recorded Messages retained in history before the oldest is evicted. Defaults to 100. Clamped to the range 20-500: smaller values keep the panel snappy under high message rates, larger values give you more scroll-back. Each retained entry stores a full Model snapshot, so memory cost scales linearly with both `maxEntries` and your Model size.
+ * - `keyframeInterval`: Number of recorded Messages between full Model snapshots. Defaults to 31. Time-travel to an index replays `update` forward from the nearest earlier keyframe, so this is a memory/time tradeoff: smaller values store more snapshots (more memory) but make each jump cheaper, down to `1` where every jump is a constant-time snapshot lookup with no replay. Reach for a denser interval when the app has a heavy `update` and time-travel jumps feel sluggish. Clamped to a minimum of 1. Forced to 1 automatically when `excludeFromHistory` is active, since excluded Messages are never replayed.
+ */
+export type DevToolsConfig = false | Readonly<{
+    show?: Visibility;
+    position?: DevToolsPosition;
+    mode?: DevToolsModeConfig;
+    banner?: string;
+    excludeFromHistory?: ReadonlyArray<string>;
+    maxEntries?: number;
+    keyframeInterval?: number;
+    /**
+     * The application's `Message` Schema. When provided and the running app
+     * is connected to the Foldkit DevTools MCP server, AI agents can dispatch
+     * Messages into the runtime. The Schema decodes inbound dispatch payloads
+     * at the bridge boundary and returns a clean error on mismatch.
+     *
+     * Without this field, `RequestDispatchMessage` is rejected with an
+     * informative error.
+     */
+    Message?: Schema.Codec<any, any, unknown, unknown>;
+}>;
+/** Registers the overlay supplied by the Foldkit Vite plugin. */
+export declare const __setDevToolsOverlay: (overlay: DevToolsOverlay | undefined) => void;
+/** The DevTools settings a runtime boots with once `show` has been resolved
+ *  against the environment. */
+export type ResolvedDevToolsConfig = Readonly<{
+    position: DevToolsPosition;
+    mode: DevToolsMode;
+    maybeBanner: Option.Option<string>;
+    maybeOverlay: Option.Option<DevToolsOverlay>;
+}>;
+/** Resolves the DevTools config for this boot, or `Option.none()` when
+ *  DevTools is disabled or hidden. `'Development'` visibility requires Vite
+ *  HMR and a top-level window, so an app previewed inside an iframe does not
+ *  stack a second panel over its host's. */
+export declare const resolveDevToolsConfig: (devTools: DevToolsConfig | undefined) => Option.Option<ResolvedDevToolsConfig>;
+/** The Message tags `excludeFromHistory` keeps out of the DevTools history. */
+export declare const resolveExcludeFromHistoryTags: (devTools: DevToolsConfig | undefined) => ReadonlySet<string>;
+/** The configured `maxEntries`, clamped to the supported range. */
+export declare const resolveDevToolsMaxEntries: (devTools: DevToolsConfig | undefined) => number | undefined;
+/** The configured `keyframeInterval`, floored and clamped to its minimum. */
+export declare const resolveDevToolsKeyframeInterval: (devTools: DevToolsConfig | undefined) => number | undefined;
+//# sourceMappingURL=devToolsConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"devToolsConfig.d.ts","sourceRoot":"","sources":["../../src/runtime/devToolsConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAQ,MAAM,QAAQ,CAAA;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,KAAK,UAAU,EAAa,MAAM,iBAAiB,CAAA;AAE5D,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAC1B,aAAa,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,CAAA;AAEvD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,CAAA;AAEnD;;;;gFAIgF;AAChF,MAAM,MAAM,kBAAkB,GAC1B,YAAY,GACZ,QAAQ,CAAC;IAAE,WAAW,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,YAAY,CAAA;CAAE,CAAC,CAAA;AAErE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;AAE5C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,KAAK,GACL,QAAQ,CAAC;IACP,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kBAAkB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;CACnD,CAAC,CAAA;AAIN,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,YACtB,eAAe,GAAG,SAAS,KACnC,IAEF,CAAA;AAiBD;+BAC+B;AAC/B,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,IAAI,EAAE,YAAY,CAAA;IAClB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAClC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;CAC7C,CAAC,CAAA;AAEF;;;4CAG4C;AAC5C,eAAO,MAAM,qBAAqB,aACtB,cAAc,GAAG,SAAS,KACnC,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAmBtC,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B,aAC9B,cAAc,GAAG,SAAS,KACnC,WAAW,CAAC,MAAM,CASlB,CAAA;AAEH,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,aAC1B,cAAc,GAAG,SAAS,KACnC,MAAM,GAAG,SAaT,CAAA;AAEH,6EAA6E;AAC7E,eAAO,MAAM,+BAA+B,aAChC,cAAc,GAAG,SAAS,KACnC,MAAM,GAAG,SAUT,CAAA"}

package/dist/runtime/devToolsConfig.js

@@ -0,0 +1,49 @@
+import { Option, pipe } from 'effect';
+import { isVisible } from './visibility.js';
+let registeredDevToolsOverlay;
+/** Registers the overlay supplied by the Foldkit Vite plugin. */
+export const __setDevToolsOverlay = (overlay) => {
+    registeredDevToolsOverlay = overlay;
+};
+const DEFAULT_DEV_TOOLS_SHOW = 'Development';
+const DEFAULT_DEV_TOOLS_POSITION = 'BottomRight';
+const DEFAULT_DEV_TOOLS_MODE = 'TimeTravel';
+const resolveDevToolsMode = (config) => {
+    if (typeof config === 'string') {
+        return config;
+    }
+    else {
+        return import.meta.hot ? config.development : config.production;
+    }
+};
+const DEV_TOOLS_MAX_ENTRIES_MIN = 20;
+const DEV_TOOLS_MAX_ENTRIES_MAX = 500;
+const DEV_TOOLS_KEYFRAME_INTERVAL_MIN = 1;
+/** Resolves the DevTools config for this boot, or `Option.none()` when
+ *  DevTools is disabled or hidden. `'Development'` visibility requires Vite
+ *  HMR and a top-level window, so an app previewed inside an iframe does not
+ *  stack a second panel over its host's. */
+export const resolveDevToolsConfig = (devTools) => {
+    const isInIframe = window.self !== window.top;
+    return pipe(devTools ?? {}, Option.liftPredicate(config => config !== false), Option.filter(config => isVisible(config.show ?? DEFAULT_DEV_TOOLS_SHOW, !!import.meta.hot && !isInIframe)), Option.map(config => ({
+        position: config.position ?? DEFAULT_DEV_TOOLS_POSITION,
+        mode: resolveDevToolsMode(config.mode ?? DEFAULT_DEV_TOOLS_MODE),
+        maybeBanner: Option.fromNullishOr(config.banner),
+        maybeOverlay: Option.fromNullishOr(registeredDevToolsOverlay),
+    })));
+};
+/** The Message tags `excludeFromHistory` keeps out of the DevTools history. */
+export const resolveExcludeFromHistoryTags = (devTools) => pipe(devTools ?? {}, Option.liftPredicate(config => config !== false), Option.flatMapNullishOr(config => config.excludeFromHistory), Option.match({
+    onNone: () => new Set(),
+    onSome: tags => new Set(tags),
+}));
+/** The configured `maxEntries`, clamped to the supported range. */
+export const resolveDevToolsMaxEntries = (devTools) => pipe(devTools ?? {}, Option.liftPredicate(config => config !== false), Option.flatMapNullishOr(config => config.maxEntries), Option.match({
+    onNone: () => undefined,
+    onSome: value => Math.max(DEV_TOOLS_MAX_ENTRIES_MIN, Math.min(DEV_TOOLS_MAX_ENTRIES_MAX, value)),
+}));
+/** The configured `keyframeInterval`, floored and clamped to its minimum. */
+export const resolveDevToolsKeyframeInterval = (devTools) => pipe(devTools ?? {}, Option.liftPredicate(config => config !== false), Option.flatMapNullishOr(config => config.keyframeInterval), Option.match({
+    onNone: () => undefined,
+    onSome: value => Math.max(DEV_TOOLS_KEYFRAME_INTERVAL_MIN, Math.floor(value)),
+}));

package/dist/runtime/devToolsIntegration.d.ts

@@ -0,0 +1,56 @@
+import { Effect, type Scope } from 'effect';
+import { type MountRecord } from '../devTools/store.js';
+import { MountRuntime, MountTracker, type ViewState } from '../mount/index.js';
+import { type DevToolsConfig } from './devToolsConfig.js';
+/** The Mount starts and ends recorded since the last drain. */
+export type MountEvents = Readonly<{
+    starts: ReadonlyArray<MountRecord>;
+    ends: ReadonlyArray<MountRecord>;
+}>;
+/** What the DevTools history keeps about a Command: its name and arguments. */
+export type RecordableCommand = Readonly<{
+    name: string;
+    args?: Record<string, unknown>;
+}>;
+/** The replay bridge the render side hands the store when it is installed. */
+export type DevToolsRenderBridge = Readonly<{
+    renderReplay: (model: unknown) => Effect.Effect<void>;
+    markRenderPending: Effect.Effect<void>;
+}>;
+/**
+ * Everything the runtime needs from DevTools, whether or not DevTools is
+ * configured. The Mount tracker and runtime, the view state, and the pause
+ * check exist from boot, and the tracker records only once the store
+ * exists. `installDevToolsStore` creates the store, mounts the overlay,
+ * and starts the WebSocket bridge once the render side can supply the
+ * replay bridge, and does nothing when DevTools is off. The recording
+ * helpers no-op until the store exists.
+ */
+export type DevToolsIntegration<Model, Message> = Readonly<{
+    mountTracker: typeof MountTracker.Service;
+    mountRuntime: typeof MountRuntime.Service;
+    drainMountEvents: () => MountEvents;
+    readViewState: () => ViewState;
+    setViewState: (nextViewState: ViewState) => void;
+    isPausedNow: () => boolean;
+    installDevToolsStore: (bridge: DevToolsRenderBridge) => Effect.Effect<void, never, Scope.Scope>;
+    resumeDevTools: Effect.Effect<void>;
+    recordInit: (initModel: Model, initCommands: ReadonlyArray<RecordableCommand>) => Effect.Effect<void>;
+    recordMessage: (message: Message, currentModel: Model, nextModel: Model, commands: ReadonlyArray<RecordableCommand>) => void;
+    attachRenderedMounts: () => void;
+}>;
+/**
+ * Builds the DevTools integration for one runtime from the `devTools`
+ * config. `update` and `maybeFreezeModel` drive time-travel replay, and
+ * `enqueueMessageEffect` is how Messages sent over the WebSocket bridge
+ * reach the queue.
+ */
+export declare const makeDevToolsIntegration: <Model, Message>({ devTools, update, maybeFreezeModel, enqueueMessageEffect, }: Readonly<{
+    devTools: DevToolsConfig | undefined;
+    update: (model: Model, message: Message) => Readonly<{
+        model: Model;
+    }>;
+    maybeFreezeModel: (model: Model) => Model;
+    enqueueMessageEffect: (message: Message) => Effect.Effect<void>;
+}>) => Effect.Effect<DevToolsIntegration<Model, Message>>;
+//# sourceMappingURL=devToolsIntegration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"devToolsIntegration.d.ts","sourceRoot":"","sources":["../../src/runtime/devToolsIntegration.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EAIN,KAAK,KAAK,EAGX,MAAM,QAAQ,CAAA;AAEf,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EAEf,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,KAAK,cAAc,EAKpB,MAAM,qBAAqB,CAAA;AAE5B,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;IAClC,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CACjC,CAAC,CAAA;AAEF,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B,CAAC,CAAA;AAEF,8EAA8E;AAC9E,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACrD,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CACvC,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,CAAC,KAAK,EAAE,OAAO,IAAI,QAAQ,CAAC;IACzD,YAAY,EAAE,OAAO,YAAY,CAAC,OAAO,CAAA;IACzC,YAAY,EAAE,OAAO,YAAY,CAAC,OAAO,CAAA;IACzC,gBAAgB,EAAE,MAAM,WAAW,CAAA;IACnC,aAAa,EAAE,MAAM,SAAS,CAAA;IAC9B,YAAY,EAAE,CAAC,aAAa,EAAE,SAAS,KAAK,IAAI,CAAA;IAChD,WAAW,EAAE,MAAM,OAAO,CAAA;IAC1B,oBAAoB,EAAE,CACpB,MAAM,EAAE,oBAAoB,KACzB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IAC5C,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACnC,UAAU,EAAE,CACV,SAAS,EAAE,KAAK,EAChB,YAAY,EAAE,aAAa,CAAC,iBAAiB,CAAC,KAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACxB,aAAa,EAAE,CACb,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,KAAK,EACnB,SAAS,EAAE,KAAK,EAChB,QAAQ,EAAE,aAAa,CAAC,iBAAiB,CAAC,KACvC,IAAI,CAAA;IACT,oBAAoB,EAAE,MAAM,IAAI,CAAA;CACjC,CAAC,CAAA;AAOF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,EAAE,OAAO,iEAKnD,QAAQ,CAAC;IACV,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC;QAAE,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IACtE,gBAAgB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAAA;IACzC,oBAAoB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CAChE,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAuOlD,CAAA"}

package/dist/runtime/devToolsIntegration.js

@@ -0,0 +1,186 @@
+import { Array, Effect, Option, PubSub, Stream, SubscriptionRef, } from 'effect';
+import { createDevToolsStore, } from '../devTools/store.js';
+import { startWebSocketBridge } from '../devTools/webSocketBridge.js';
+import { MountRuntime, liveViewStateChanges, } from '../mount/index.js';
+import { resolveDevToolsConfig, resolveDevToolsKeyframeInterval, resolveDevToolsMaxEntries, resolveExcludeFromHistoryTags, } from './devToolsConfig.js';
+const toCommandRecord = (command) => command.args !== undefined
+    ? { name: command.name, args: command.args }
+    : { name: command.name };
+/**
+ * Builds the DevTools integration for one runtime from the `devTools`
+ * config. `update` and `maybeFreezeModel` drive time-travel replay, and
+ * `enqueueMessageEffect` is how Messages sent over the WebSocket bridge
+ * reach the queue.
+ */
+export const makeDevToolsIntegration = ({ devTools, update, maybeFreezeModel, enqueueMessageEffect, }) => Effect.gen(function* () {
+    const resolvedDevTools = resolveDevToolsConfig(devTools);
+    const excludeFromHistoryTags = resolveExcludeFromHistoryTags(devTools);
+    const devToolsMaxEntries = resolveDevToolsMaxEntries(devTools);
+    const devToolsKeyframeInterval = resolveDevToolsKeyframeInterval(devTools);
+    let currentViewState = 'Live';
+    const maybeViewStatePubSub = Option.isSome(resolvedDevTools)
+        ? Option.some(yield* PubSub.unbounded({
+            replay: 1,
+        }))
+        : Option.none();
+    const viewStateChanges = Option.match(maybeViewStatePubSub, {
+        onNone: () => liveViewStateChanges,
+        onSome: viewStatePubSub => {
+            PubSub.publishUnsafe(viewStatePubSub, currentViewState);
+            return Stream.fromPubSub(viewStatePubSub);
+        },
+    });
+    const setViewState = (nextViewState) => {
+        if (nextViewState === currentViewState) {
+            return;
+        }
+        currentViewState = nextViewState;
+        if (Option.isSome(maybeViewStatePubSub)) {
+            PubSub.publishUnsafe(maybeViewStatePubSub.value, nextViewState);
+        }
+    };
+    const readViewState = () => currentViewState;
+    // NOTE: the DevTools store is installed at most once during boot and
+    // never replaced. Caching it in a closure variable avoids a
+    // `Ref.get` on every message and on every render frame (the
+    // store powers the pause check). Plain `null` rather than `Option`:
+    // the hot path only ever presence-checks it, and the check should
+    // stay a bare comparison.
+    let devToolsStore = null;
+    const mountRuntime = MountRuntime.of({
+        captureViewStateChanges: () => Stream.concat(Stream.make(currentViewState), viewStateChanges).pipe(Stream.changes),
+    });
+    const isPausedNow = () => devToolsStore !== null &&
+        SubscriptionRef.getUnsafe(devToolsStore.stateRef).isPaused;
+    // NOTE: recording is gated on the DevTools store because the store
+    // is the only consumer. Without the gate every Mount start and end
+    // in a production frame would allocate a record just to be sliced
+    // and dropped.
+    const mountStartBuffer = [];
+    const mountEndBuffer = [];
+    const mountTracker = {
+        started: (name, args) => {
+            if (devToolsStore === null) {
+                return;
+            }
+            mountStartBuffer.push(args === undefined ? { name } : { name, args });
+        },
+        ended: (name, args) => {
+            if (devToolsStore === null) {
+                return;
+            }
+            mountEndBuffer.push(args === undefined ? { name } : { name, args });
+        },
+    };
+    const drainMountEvents = () => {
+        const starts = mountStartBuffer.slice();
+        const ends = mountEndBuffer.slice();
+        mountStartBuffer.length = 0;
+        mountEndBuffer.length = 0;
+        return { starts, ends };
+    };
+    const installDevToolsStore = ({ renderReplay, markRenderPending, }) => Option.match(resolvedDevTools, {
+        onNone: () => Effect.void,
+        onSome: ({ position, mode, maybeBanner, maybeOverlay }) => Effect.gen(function* () {
+            // NOTE: when excludeFromHistory is active, the runtime drops
+            // excluded Messages from the recorded history. Replay walks the
+            // recorded entries forward from the nearest keyframe. With
+            // exclusion, the dropped Messages aren't in that walk, so any
+            // cumulative state they would have produced is missing from the
+            // replayed model. Setting keyframeInterval to 1 stores a full
+            // snapshot on every recorded entry, so time-travel becomes a
+            // direct lookup that reflects the real live state at the moment
+            // the entry was recorded.
+            const isExcludingMessages = excludeFromHistoryTags.size > 0;
+            const store = yield* createDevToolsStore({
+                /* eslint-disable @typescript-eslint/consistent-type-assertions */
+                replay: (model, message) => {
+                    const replayUpdate = update(model, message);
+                    return maybeFreezeModel(replayUpdate.model);
+                },
+                /* eslint-enable @typescript-eslint/consistent-type-assertions */
+                render: renderReplay,
+                markRenderPending,
+            }, {
+                ...(devToolsKeyframeInterval !== undefined && {
+                    keyframeInterval: devToolsKeyframeInterval,
+                }),
+                ...(devToolsMaxEntries !== undefined && {
+                    maxEntries: devToolsMaxEntries,
+                }),
+                // NOTE: exclusion forces keyframeInterval to 1 regardless of any
+                // configured value, since excluded Messages are never replayed
+                // and a denser interval would leave gaps in the replayed model.
+                // Spread last so it wins over `keyframeInterval` above.
+                ...(isExcludingMessages && { keyframeInterval: 1 }),
+            });
+            devToolsStore = store;
+            // NOTE: the boot records init through `recordInit` after the init
+            // render, so the mount buffer reflects the Mounts that fired on the
+            // first paint.
+            yield* Option.match(maybeOverlay, {
+                onNone: () => Effect.void,
+                onSome: overlay => overlay(store, position, mode, maybeBanner),
+            });
+            if (import.meta.hot) {
+                const maybeMessageSchema = devTools !== undefined && devTools !== false
+                    ? Option.fromNullishOr(devTools.Message)
+                    : Option.none();
+                yield* startWebSocketBridge(store, import.meta.hot, 
+                /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                message => enqueueMessageEffect(message), 
+                /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                maybeMessageSchema);
+            }
+        }),
+    });
+    const recordInit = (initModel, initCommands) => Effect.gen(function* () {
+        const initMountEvents = drainMountEvents();
+        if (devToolsStore !== null) {
+            yield* devToolsStore.recordInit(initModel, Array.map(initCommands, toCommandRecord), initMountEvents.starts);
+        }
+    });
+    const attachRenderedMounts = () => {
+        if (devToolsStore !== null) {
+            const mountEvents = drainMountEvents();
+            Effect.runFork(devToolsStore.attachRenderedMounts(mountEvents.starts, mountEvents.ends));
+        }
+    };
+    const recordMessage = (message, currentModel, nextModel, commands) => {
+        // NOTE: store writes go through `Effect.runFork`, not
+        // `Effect.runSync`. Both complete inline when the store's state
+        // Ref is uncontended (the always case on this path), but a
+        // DevTools fiber holding the Ref's permit across a yield would
+        // make `runSync` throw and crash the app; `runFork` parks and
+        // finishes the write when the permit frees, and the Ref's FIFO
+        // permit queue preserves write order.
+        if (devToolsStore !== null) {
+            const store = devToolsStore;
+            /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+            const tag = message._tag;
+            const isModelChanged = currentModel !== nextModel;
+            if (!excludeFromHistoryTags.has(tag)) {
+                Effect.runFork(store.recordMessage(
+                /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+                message, currentModel, nextModel, Array.map(commands, toCommandRecord), isModelChanged));
+            }
+            else if (isModelChanged) {
+                Effect.runFork(store.updateLatestModel(nextModel));
+            }
+        }
+    };
+    const resumeDevTools = Effect.suspend(() => devToolsStore !== null ? devToolsStore.resume : Effect.void);
+    return {
+        mountTracker,
+        mountRuntime,
+        drainMountEvents,
+        readViewState,
+        setViewState,
+        isPausedNow,
+        installDevToolsStore,
+        resumeDevTools,
+        recordInit,
+        recordMessage,
+        attachRenderedMounts,
+    };
+});

package/dist/runtime/dispatch.d.ts

@@ -0,0 +1,10 @@
+import { Context, Effect } from 'effect';
+declare const Dispatch_base: Context.ServiceClass<Dispatch, "@foldkit/Dispatch", {
+    readonly dispatchAsync: (message: unknown) => Effect.Effect<void>;
+    readonly dispatchSync: (message: unknown) => void;
+}>;
+/** Effect service tag that provides message dispatching to the view layer. */
+export declare class Dispatch extends Dispatch_base {
+}
+export {};
+//# sourceMappingURL=dispatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/runtime/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;;4BAMZ,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;2BAC1C,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI;;AALrD,8EAA8E;AAC9E,qBAAa,QAAS,SAAQ,aAMN;CAAG"}

package/dist/runtime/dispatch.js

@@ -0,0 +1,4 @@
+import { Context } from 'effect';
+/** Effect service tag that provides message dispatching to the view layer. */
+export class Dispatch extends Context.Service()('@foldkit/Dispatch') {
+}

package/dist/runtime/documentMetadata.d.ts

@@ -0,0 +1,3 @@
+import { Document } from '../html/index.js';
+export declare const applyDocumentMetadata: (nextDocument: Document, mountedRoot: Node | undefined) => void;
+//# sourceMappingURL=documentMetadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documentMetadata.d.ts","sourceRoot":"","sources":["../../src/runtime/documentMetadata.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAA4B,MAAM,kBAAkB,CAAA;AAsLrE,eAAO,MAAM,qBAAqB,iBAClB,QAAQ,eACT,IAAI,GAAG,SAAS,KAC5B,IA8CF,CAAA"}