Documentation navigation

Published API · 0.1.0-rc.1

foldkit · devtools-host

Published foldkit API declarations for devtools-host.

./devtools-host

@wsagency/wseffect-foldkit · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit/devtools-host'

Exported declarations

__setDevToolsOverlay

Registers the overlay supplied by the Foldkit Vite plugin.

__setDevToolsOverlay: (overlay: DevToolsOverlay | undefined) => void

CommandRecord

export type CommandRecord = Readonly<{
    id: number;
    name: string;
    args?: Record<string, unknown>;
    maybeSubmodelPath: Option.Option<ReadonlyArray<string>>;
}>;

DEVTOOLS_HOST_ID

The `id` of the DOM element that hosts the Foldkit DevTools shadow root. Defined here (not in `devTools/`) because the `OnBlur` handler below uses it to suppress blur Messages whose `relatedTarget` is this host (i.e. when focus crosses into the DevTools UI). Surfaced publicly through `foldkit/devtools-host` (not `foldkit/html`); the DevTools overlay imports it from there when creating the host element, so the two stay in sync.

DEVTOOLS_HOST_ID = "foldkit-devtools"

DevToolsOverlay

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>;

DevToolsStore

export type DevToolsStore = Readonly<{
    recordInit: (model: unknown, commands: ReadonlyArray<CommandRecord>, mountStarts?: ReadonlyArray<MountRecord>) => Effect.Effect<void>;
    recordMessage: (message: Readonly<{
        _tag: string;
    }>, modelBeforeUpdate: unknown, modelAfterUpdate: unknown, commands: ReadonlyArray<CommandRecord>, isModelChanged: boolean) => Effect.Effect<void>;
    recordResolvedCommand: (id: number, submodelPath: ReadonlyArray<string>) => Effect.Effect<void>;
    updateLatestModel: (model: unknown) => Effect.Effect<void>;
    attachRenderedMounts: (mountStarts: ReadonlyArray<MountRecord>, mountEnds: ReadonlyArray<MountRecord>) => Effect.Effect<void>;
    getModelAtIndex: (index: number) => Effect.Effect<unknown>;
    getMessageAtIndex: (index: number) => Effect.Effect<Option.Option<unknown>>;
    getDiffAtIndex: (index: number) => Effect.Effect<DiffResult>;
    jumpTo: (index: number) => Effect.Effect<unknown>;
    resume: Effect.Effect<void>;
    clear: Effect.Effect<void>;
    stateRef: SubscriptionRef.SubscriptionRef<StoreState>;
}>;

extractSubmodelInfo

Walk a chain of `Got<Submodel>Message` wrappers in a recorded Message and return the wrapper tags plus the innermost leaf tag. The Submodel pattern propagates child Messages up to a parent by wrapping them in `GotChildMessage({ message: childMessage })`. Nested submodels stack those wrappers. Walking the chain reveals the parent → child → grandchild dispatch path that produced the entry. Returns an empty path and `Option.none` for top-level Messages whose tag doesn't match the `Got*Message` pattern. Otherwise the path lists wrapper tags from outer to inner, and `maybeLeafTag` is `Some` when the innermost wrapped value is itself a tagged Message (the underlying child Message that originated the chain).

extractSubmodelInfo: (tag: string, message: unknown) => SubmodelInfo

GOT_MESSAGE_PATTERN

GOT_MESSAGE_PATTERN: RegExp

INIT_INDEX

INIT_INDEX = -1

isTagged

isTagged: <I>(input: I) => input is I & {
    readonly _tag: string;
}

latestEntryIndex

The absolute index of the most recently recorded entry, or `INIT_INDEX` when no Messages have been recorded yet.

latestEntryIndex: (state: StoreState) => number

MountRecord

export type MountRecord = Readonly<{
    name: string;
    args?: Record<string, unknown>;
}>;

StoreState

export type StoreState = Readonly<{
    entries: ReadonlyArray<HistoryEntry>;
    keyframes: HashMap.HashMap<number, unknown>;
    maybeInitModel: Option.Option<unknown>;
    initCommands: ReadonlyArray<CommandRecord>;
    initMountStarts: ReadonlyArray<MountRecord>;
    startIndex: number;
    isPaused: boolean;
    pausedAtIndex: number;
    maybeLatestModel: Option.Option<unknown>;
}>;

toInspectableValue

Convert Effect `Redacted` values to their labeled placeholder strings and DOM-class instances (File, Blob, Date, URL) to plain-object representations so the tree renderer's key-enumeration walk can see their meaningful data, which otherwise lives on the prototype as getters and is invisible to `Object.keys`. Recurses through arrays and records so the transform applies at every level. File is matched before Blob because File extends Blob. Memoized by reference. The transform allocates fresh wrappers via `Array.map` / `Record.map` even when the input contains no DOM classes (because `map` always allocates), which would otherwise produce a fresh tree of references on every call. Without memoization, the inspector tree's row-level `lazyTreeNode` cache would miss on every row of every render — the cached row args reference last render's wrapper objects, not this render's. Memoizing on the input reference makes subsequent calls with the same snapshot return identical references end-to-end, so the row lazy actually hits.

toInspectableValue: (value: unknown) => unknown