effectweb 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TeleVecha contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# effectweb
+
+Immutable Effect models and JSX compiled to direct DOM updates, without signals, proxies, or virtual DOM.
+
+Use with `effectweb-compiler/vite` and Effect `4.0.0-rc.112`. The package includes programs, named tasks, async presentation, query caching, DOM lifetimes, and `effectweb/testing` helpers.
+
+See [setup and example](https://github.com/DerpyCrabs/EffectWeb#vite-setup) and the [authoring guide](https://github.com/DerpyCrabs/EffectWeb/blob/main/docs/authoring.md).
+
+Early API; runtime and compiler versions advance together. Client-side only. Persistence and multi-tab coordination belong to the application.

package/dist/AsyncContent.d.ts

@@ -0,0 +1,20 @@
+import { Cause } from 'effect';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import { type Slot, type View } from './index.js';
+import type { JSX } from './jsx.js';
+export interface AsyncContentProps<A, E> {
+    result: AsyncResult.AsyncResult<A, E>;
+    content: Slot<A>;
+    pending?: JSX.Element;
+    empty?: JSX.Element;
+    failure?: Slot<Cause.Cause<E>>;
+    refreshing?: JSX.Element;
+    pendingDelay?: number;
+}
+type Props = AsyncContentProps<unknown, unknown>;
+/** Presentation only: resource owners choose identity, loading, caching and cancellation. */
+export declare const AsyncContent: {
+    <A, E>(props: AsyncContentProps<A, E>): JSX.Element;
+    readonly build: View<Props, never>["build"];
+};
+export {};

package/dist/AsyncContent.js

@@ -0,0 +1,75 @@
+import * as _tv_dom from "./dom.js";
+import { Cause, Effect, Option } from "effect";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+import { component } from "./component.js";
+import { view } from "./index.js";
+import { effectCommand } from "./program.js";
+const implementation = component({
+    init: (props) => ({
+        props,
+        pending: false,
+        visible: false
+    }),
+    receive(model, props) {
+        const pending = props.result.waiting && Option.isNone(AsyncResult.value(props.result));
+        if (!pending)
+            return {
+                model: {
+                    props,
+                    pending: false,
+                    visible: false
+                },
+                cancel: ["pending"]
+            };
+        if (model.pending && model.props.pendingDelay === props.pendingDelay)
+            return { model: {
+                    ...model,
+                    props
+                } };
+        const delay = Math.max(0, props.pendingDelay ?? 0);
+        return {
+            model: {
+                props,
+                pending: true,
+                visible: delay === 0
+            },
+            cancel: ["pending"],
+            commands: delay === 0 ? [] : [effectCommand("pending", () => Effect.sleep(delay), {
+                    onSuccess: () => ({ type: "ShowPending" }),
+                    onFailure: () => ({ type: "ShowPending" })
+                })]
+        };
+    },
+    update: (model) => ({ model: {
+            ...model,
+            visible: true
+        } }),
+    view: _tv_dom.compiled((_tv_scope_1, _tv_parent_2, _tv_before_3) => {
+        const _tv_derived_4 = _tv_scope_1.derive(() => [_tv_scope_1.value?.props], () => ((_tv_capture_5) => _tv_capture_5.props)(_tv_scope_1.value));
+        const _tv_derived_6 = _tv_scope_1.derive(() => [_tv_derived_4()?.result], () => ((_tv_capture_7) => AsyncResult.value(_tv_capture_7.result))(_tv_derived_4()));
+        const _tv_derived_8 = _tv_scope_1.derive(() => [_tv_derived_4()?.result, _tv_derived_4()?.result?.waiting], () => ((_tv_capture_9) => AsyncResult.isFailure(_tv_capture_9.result) && !_tv_capture_9.result.waiting ? _tv_capture_9.result : undefined)(_tv_derived_4()));
+        _tv_dom.branch(_tv_scope_1, _tv_parent_2, _tv_before_3, () => Option.isSome(_tv_derived_6()), (_tv_scope_1, _tv_parent_10, _tv_before_11) => {
+            _tv_dom.text(_tv_scope_1, _tv_parent_10, _tv_before_11, () => [_tv_derived_4(), _tv_derived_6()?.value], () => _tv_derived_4().content(_tv_derived_6().value));
+            _tv_dom.branch(_tv_scope_1, _tv_parent_10, _tv_before_11, () => _tv_derived_4().result.waiting, (_tv_scope_1, _tv_parent_12, _tv_before_13) => {
+                _tv_dom.text(_tv_scope_1, _tv_parent_12, _tv_before_13, () => [_tv_derived_4()?.refreshing], () => _tv_derived_4().refreshing);
+            }, (_tv_scope_1, _tv_parent_12, _tv_before_13) => { });
+            _tv_dom.branch(_tv_scope_1, _tv_parent_10, _tv_before_11, () => _tv_derived_8() && _tv_derived_4().failure, (_tv_scope_1, _tv_parent_14, _tv_before_15) => {
+                _tv_dom.text(_tv_scope_1, _tv_parent_14, _tv_before_15, () => [_tv_derived_4(), _tv_derived_8()?.cause], () => _tv_derived_4().failure(_tv_derived_8().cause));
+            }, (_tv_scope_1, _tv_parent_14, _tv_before_15) => { });
+        }, (_tv_scope_1, _tv_parent_10, _tv_before_11) => {
+            _tv_dom.branch(_tv_scope_1, _tv_parent_10, _tv_before_11, () => _tv_derived_8() && _tv_derived_4().failure, (_tv_scope_1, _tv_parent_16, _tv_before_17) => {
+                _tv_dom.text(_tv_scope_1, _tv_parent_16, _tv_before_17, () => [_tv_derived_4(), _tv_derived_8()?.cause], () => _tv_derived_4().failure(_tv_derived_8().cause));
+            }, (_tv_scope_1, _tv_parent_16, _tv_before_17) => {
+                _tv_dom.branch(_tv_scope_1, _tv_parent_16, _tv_before_17, () => _tv_scope_1.value.pending, (_tv_scope_1, _tv_parent_18, _tv_before_19) => {
+                    _tv_dom.branch(_tv_scope_1, _tv_parent_18, _tv_before_19, () => _tv_scope_1.value.visible, (_tv_scope_1, _tv_parent_20, _tv_before_21) => {
+                        _tv_dom.text(_tv_scope_1, _tv_parent_20, _tv_before_21, () => [_tv_derived_4()?.pending], () => _tv_derived_4().pending);
+                    }, (_tv_scope_1, _tv_parent_20, _tv_before_21) => { });
+                }, (_tv_scope_1, _tv_parent_18, _tv_before_19) => {
+                    _tv_dom.text(_tv_scope_1, _tv_parent_18, _tv_before_19, () => [_tv_derived_4()?.empty], () => _tv_derived_4().empty);
+                });
+            });
+        });
+    })
+});
+/** Presentation only: resource owners choose identity, loading, caching and cancellation. */
+export const AsyncContent = implementation;

package/dist/actions.d.ts

@@ -0,0 +1,27 @@
+import type { Send, Transition } from './program.js';
+type Handler<Model> = (model: Model, ...args: never[]) => Transition<Model, unknown>;
+type Arguments<F> = F extends (model: never, ...args: infer Args) => unknown ? Args : never;
+type HandlerMessage<Handlers> = {
+    [Name in keyof Handlers]: {
+        readonly type: Name;
+        readonly args: Arguments<Handlers[Name]>;
+    };
+}[keyof Handlers];
+export type ActionMessage<Definition> = Definition extends {
+    update: (model: never, message: infer Message) => unknown;
+} ? Message : never;
+type Creators<Handlers> = {
+    [Name in keyof Handlers]: (...args: Arguments<Handlers[Name]>) => Extract<HandlerMessage<Handlers>, {
+        type: Name;
+    }>;
+};
+type Dispatch<Handlers> = {
+    [Name in keyof Handlers]: (...args: Arguments<Handlers[Name]>) => void;
+};
+/** Declare action names and payloads once. Dispatch still crosses the ordinary program message queue. */
+export declare function defineActions<Model>(): <Handlers extends Record<string, Handler<Model>>>(handlers: Handlers) => {
+    message: Creators<Handlers>;
+    bind(this: void, send: Send<HandlerMessage<Handlers>>): Dispatch<Handlers>;
+    update(this: void, model: Model, action: HandlerMessage<Handlers>): ReturnType<Handlers[keyof Handlers]>;
+};
+export {};

package/dist/actions.js

@@ -0,0 +1,31 @@
+/** Declare action names and payloads once. Dispatch still crosses the ordinary program message queue. */
+export function defineActions() {
+    return (handlers) => {
+        const message = Object.create(null);
+        for (const name of Object.keys(handlers)) {
+            Object.defineProperty(message, name, {
+                enumerable: true,
+                value: (...args) => ({ type: name, args }),
+            });
+        }
+        return {
+            message,
+            bind(send) {
+                const dispatch = Object.create(null);
+                for (const name of Object.keys(handlers)) {
+                    Object.defineProperty(dispatch, name, {
+                        enumerable: true,
+                        value: (...args) => send({ type: name, args }),
+                    });
+                }
+                return dispatch;
+            },
+            update(model, action) {
+                if (!Object.hasOwn(handlers, action.type))
+                    throw new Error(`Unknown action: ${String(action.type)}`);
+                const handler = handlers[action.type];
+                return handler(model, ...action.args);
+            },
+        };
+    };
+}

package/dist/cache.d.ts

@@ -0,0 +1,32 @@
+import { Effect } from 'effect';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
+import { type UiLoad, type UiPage } from './load.js';
+import type { Query } from './query.js';
+import type { UiRuntime } from './runtime.js';
+export { loadEffect, type UiLoad, type UiPage } from './load.js';
+export { shareValue } from './share.js';
+export declare function makeUiModel(): UiModel<never>;
+export declare function makeUiModel<R>(runtime: UiRuntime<R>): UiModel<R>;
+declare function createUiModel<R>(runtime?: UiRuntime<R>): {
+    registry: AtomRegistry.AtomRegistry;
+    generation: Atom.Writable<number, number>;
+    resource<A, E = unknown>(key: string, load: () => Effect.Effect<A, E>): Atom.Atom<AsyncResult.AsyncResult<A, E>>;
+    query: <Args, A, E>(definition: Query<Args, A, E, R>, args: Args) => Atom.Atom<AsyncResult.AsyncResult<A, E>>;
+    /** Prefetch and views observe the same atom; failure types and shared cancellation remain intact. */
+    prefetch<Args, A, E>(definition: Query<Args, A, E, R>, args: Args): Effect.Effect<A, E>;
+    invalidateQuery<Args, A, E>(definition: Query<Args, A, E, R>, ...selected: [] | [Args]): void;
+    invalidate(prefix: string): void;
+    resetResources(): void;
+    dispose(): void;
+};
+export type UiModel<R = never> = ReturnType<typeof createUiModel<R>>;
+/** Cursor progress and prior successful pages belong to the resource, including retries. */
+export declare function makePagedResource<A, Cursor>(registry: AtomRegistry.AtomRegistry, load: (cursor: Cursor | undefined) => UiLoad<UiPage<A, Cursor>>, itemKey: (item: A) => string): {
+    atom: Atom.Atom<AsyncResult.AsyncResult<UiPage<A, Cursor> & {
+        pageCount: number;
+    }, unknown>>;
+    more(): void;
+    refresh(): void;
+};

package/dist/cache.js

@@ -0,0 +1,147 @@
+import { Effect, Option } from 'effect';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
+import { loadEffect } from './load.js';
+import { shareValue } from './share.js';
+export { loadEffect } from './load.js';
+export { shareValue } from './share.js';
+export function makeUiModel(runtime) {
+    return createUiModel(runtime);
+}
+function createUiModel(runtime) {
+    const registry = AtomRegistry.make({ defaultIdleTTL: 30_000 });
+    const generation = Atom.keepAlive(Atom.make(0));
+    const resources = new Map();
+    const acquire = (key, load) => {
+        let entry = resources.get(key);
+        if (entry)
+            entry.load = load;
+        else {
+            const next = {
+                load,
+                atom: Atom.make((get) => {
+                    const previous = Option.flatMap(get.self(), AsyncResult.value);
+                    return loadEffect(() => next.load()).pipe(Effect.map((value) => {
+                        next.loadedAt = Date.now();
+                        return Option.isSome(previous) ? shareValue(previous.value, value) : value;
+                    }));
+                }),
+            };
+            entry = next;
+            resources.set(key, entry);
+        }
+        // Bound definitions as well as the registry's values. Mounted resources stay shared.
+        if (resources.size > 512) {
+            for (const [oldKey, old] of resources) {
+                if (resources.size <= 512)
+                    break;
+                if (oldKey !== key && !registry.getNodes().has(old.atom))
+                    resources.delete(oldKey);
+            }
+        }
+        return { entry, atom: entry.atom };
+    };
+    const queryKey = (definition, args) => `query:${definition.id}:${definition.key(args)}`;
+    const selectQuery = (definition, args) => {
+        const { entry, atom } = acquire(queryKey(definition, args), () => {
+            const effect = Effect.suspend(() => definition.load(args));
+            return runtime ? runtime.provide(effect) : effect;
+        });
+        entry.queryId = definition.id;
+        if (registry.getNodes().has(atom) &&
+            entry.loadedAt !== undefined &&
+            Date.now() - entry.loadedAt >= definition.staleTime) {
+            const current = registry.get(atom);
+            if (!current.waiting)
+                registry.refresh(atom);
+        }
+        return atom;
+    };
+    return {
+        registry,
+        generation,
+        resource(key, load) {
+            return acquire(key, load).atom;
+        },
+        query: selectQuery,
+        /** Prefetch and views observe the same atom; failure types and shared cancellation remain intact. */
+        prefetch(definition, args) {
+            return Effect.suspend(() => AtomRegistry.getResult(registry, selectQuery(definition, args), { suspendOnWaiting: true }));
+        },
+        invalidateQuery(definition, ...selected) {
+            if (selected.length) {
+                const entry = resources.get(queryKey(definition, selected[0]));
+                if (entry)
+                    registry.refresh(entry.atom);
+            }
+            else {
+                for (const entry of resources.values())
+                    if (entry.queryId === definition.id)
+                        registry.refresh(entry.atom);
+            }
+        },
+        invalidate(prefix) {
+            for (const [key, entry] of resources)
+                if (key.startsWith(prefix))
+                    registry.refresh(entry.atom);
+        },
+        resetResources() {
+            Atom.batch(() => {
+                for (const entry of resources.values()) {
+                    entry.load = () => Effect.interrupt;
+                    registry.refresh(entry.atom);
+                }
+                resources.clear();
+                registry.update(generation, (value) => value + 1);
+            });
+        },
+        dispose() {
+            registry.dispose();
+            resources.clear();
+        },
+    };
+}
+/** Cursor progress and prior successful pages belong to the resource, including retries. */
+export function makePagedResource(registry, load, itemKey) {
+    const requested = Atom.make(1);
+    const atom = Atom.make((get) => {
+        const count = get(requested);
+        const previous = Option.getOrUndefined(Option.flatMap(get.self(), AsyncResult.value));
+        const append = previous && count === previous.pageCount + 1 ? previous : undefined;
+        return loadEffect(() => load(append?.next)).pipe(Effect.map((page) => {
+            const known = new Set(append?.items.map(itemKey));
+            const incoming = page.items.filter((item) => {
+                const key = itemKey(item);
+                if (known.has(key))
+                    return false;
+                known.add(key);
+                return true;
+            });
+            return {
+                ...page,
+                items: append ? [...append.items, ...incoming] : incoming,
+                pageCount: append ? count : 1,
+            };
+        }));
+    }).pipe(Atom.setIdleTTL(0));
+    return {
+        atom,
+        more() {
+            const result = registry.get(atom);
+            const previous = Option.getOrUndefined(AsyncResult.value(result));
+            if (result.waiting || !previous || previous.next === undefined)
+                return;
+            Atom.batch(() => {
+                registry.set(requested, previous.pageCount + 1);
+                registry.refresh(atom);
+            });
+        },
+        refresh() {
+            Atom.batch(() => {
+                registry.set(requested, 1);
+                registry.refresh(atom);
+            });
+        },
+    };
+}

package/dist/collection.d.ts

@@ -0,0 +1,15 @@
+export type Identity = string | number;
+/** Identity belongs to the domain collection, not to each place that renders it. */
+export interface Rows<A> {
+    readonly items: readonly A[];
+    readonly identity: (item: A, index: number) => Identity;
+    readonly length: number;
+    map<B>(render: (item: A, index: number) => B): B[];
+    filter(predicate: (item: A, index: number) => boolean): Rows<A>;
+    slice(start?: number, end?: number): Rows<A>;
+}
+export declare function collection<A>(identity: (item: A, index: number) => Identity): {
+    from: (items: readonly A[]) => Rows<A>;
+};
+/** Ordered protocol structures such as keyboard rows and rich-text fragments have positional identity. */
+export declare function sequence<A>(items: readonly A[]): Rows<A>;

package/dist/collection.js

@@ -0,0 +1,24 @@
+export function collection(identity) {
+    const cache = new WeakMap();
+    const from = (items) => {
+        const cached = cache.get(items);
+        if (cached)
+            return cached;
+        const rows = {
+            items,
+            identity,
+            length: items.length,
+            map: (render) => items.map(render),
+            filter: (predicate) => from(items.filter(predicate)),
+            slice: (start, end) => from(items.slice(start, end)),
+        };
+        cache.set(items, rows);
+        return rows;
+    };
+    return { from };
+}
+const positions = collection((_item, index) => index);
+/** Ordered protocol structures such as keyboard rows and rich-text fragments have positional identity. */
+export function sequence(items) {
+    return positions.from(items);
+}

package/dist/component.d.ts

@@ -0,0 +1,33 @@
+import type { View } from './dom.js';
+import type { Transition } from './program.js';
+import { type UiRuntime } from './runtime.js';
+/** Local fields with no command lifecycle. Sends are shallow patches, never updater callbacks. */
+export declare function localComponent<Props, State extends object>(definition: {
+    init: (props: Props) => State & {
+        readonly props?: never;
+    };
+    view: View<State & {
+        readonly props: Props;
+    }, Partial<State> & {
+        readonly props?: never;
+    }>;
+}): View<Props, never>;
+/** A child model receives immutable parent inputs and owns its own message/command loop. */
+export declare function component<Props, Model extends {
+    readonly props: Props;
+}, Message, R = never>(definition: {
+    init: (props: Props) => Model;
+    receive?: (model: Model, props: Props) => Transition<Model, Message, R>;
+    update: (model: Model, message: Message) => Transition<Model, Message, R>;
+    view: View<Model, Message>;
+} & ([R] extends [never] ? {
+    runtime?: UiRuntime<R>;
+} : {
+    runtime: UiRuntime<R>;
+})): View<Props, never>;
+/** Mount an existing program without introducing a second state owner. */
+export declare function programView<Props, Model, Message>(definition: {
+    create: (props: Props) => import('./program').Program<Model, Message>;
+    receive: (source: import('./program').Program<Model, Message>, props: Props) => void;
+    view: View<Model, Message>;
+}): View<Props, never>;

package/dist/component.js

@@ -0,0 +1,58 @@
+import { compiled, Scope } from './dom.js';
+import { mapCommand, program } from './program.js';
+import { patchModel } from './state.js';
+import { defaultUiRuntime } from './runtime.js';
+/** Local fields with no command lifecycle. Sends are shallow patches, never updater callbacks. */
+export function localComponent(definition) {
+    return component({
+        init: (props) => ({ ...definition.init(props), props }),
+        update: (model, patch) => {
+            const next = patchModel(model, patch);
+            return { model: next === model ? model : { ...next, props: model.props } };
+        },
+        view: definition.view,
+    });
+}
+/** A child model receives immutable parent inputs and owns its own message/command loop. */
+export function component(definition) {
+    const runtime = definition.runtime ?? defaultUiRuntime;
+    return compiled((scope, parent, before) => {
+        const wrap = (next) => ({
+            model: next.model,
+            ...(next.cancel ? { cancel: next.cancel } : {}),
+            ...(next.commands
+                ? {
+                    commands: next.commands.map((command) => mapCommand(runtime.command(command), (message) => ({ type: 'Message', message }))),
+                }
+                : {}),
+        });
+        const source = program({
+            initial: definition.init(scope.value),
+            onDefect: scope.report,
+            update: (model, envelope) => wrap(envelope.type === 'Input'
+                ? (definition.receive?.(model, envelope.props) ?? {
+                    model: Object.is(model.props, envelope.props)
+                        ? model
+                        : { ...model, props: envelope.props },
+                })
+                : definition.update(model, envelope.message)),
+        });
+        const child = new Scope(source.model(), (message) => source.send({ type: 'Message', message }), scope.report);
+        scope.cleanups.push(() => source.dispose(), () => child.dispose(), () => unsubscribe());
+        const unsubscribe = source.subscribe((model) => child.set(model));
+        definition.view.build(child, parent, before);
+        scope.jobs.push(() => source.send({ type: 'Input', props: scope.value }));
+        source.send({ type: 'Input', props: scope.value });
+    });
+}
+/** Mount an existing program without introducing a second state owner. */
+export function programView(definition) {
+    return compiled((scope, parent, before) => {
+        const source = definition.create(scope.value);
+        const child = new Scope(source.model(), source.send, scope.report);
+        const unsubscribe = source.subscribe((model) => child.set(model));
+        scope.cleanups.push(() => source.dispose(), () => child.dispose(), () => unsubscribe());
+        definition.view.build(child, parent, before);
+        scope.jobs.push(() => definition.receive(source, scope.value));
+    });
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,32 @@
+/** Emitted only by development builds. No model values are retained in diagnostic events. */
+export interface BindingSource {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    readonly expression: string;
+    readonly dependencies: readonly string[];
+}
+export interface BindingUpdate {
+    readonly source: BindingSource;
+    readonly changed: readonly string[];
+    readonly kind: 'derive' | 'binding';
+}
+/** Each registration has its own lifetime; observers can be stopped in any order. */
+export declare function observeBindings(next: (update: BindingUpdate) => void): () => void;
+export declare function traceBinding(source: BindingSource | undefined, previous: readonly unknown[] | undefined, next: readonly unknown[], kind: BindingUpdate['kind']): void;
+export interface ProgramUpdate {
+    readonly program: number;
+    readonly name?: string;
+    readonly kind: 'update' | 'start' | 'cancel' | 'complete' | 'defect' | 'dispose';
+    readonly slot?: string;
+    /** Message discriminant only. Payloads, model values and resource keys are never retained. */
+    readonly message?: string;
+}
+export declare const nextProgramId: () => number;
+export declare const hasProgramObservers: () => boolean;
+export declare function traceProgram(event: ProgramUpdate): void;
+/** Opt-in bounded metadata history. Inspection only: no command replay or payload snapshots. */
+export declare function observePrograms(limit?: number): {
+    events: () => ProgramUpdate[];
+    dispose: () => boolean;
+};

package/dist/diagnostics.js

@@ -0,0 +1,57 @@
+import { reportError, reportSafely } from './errors.js';
+const observers = new Map();
+/** Each registration has its own lifetime; observers can be stopped in any order. */
+export function observeBindings(next) {
+    const token = Symbol();
+    observers.set(token, next);
+    return () => {
+        observers.delete(token);
+    };
+}
+export function traceBinding(source, previous, next, kind) {
+    if (!source || !observers.size)
+        return;
+    const update = {
+        source,
+        kind,
+        changed: source.dependencies.filter((_, index) => !previous || !Object.is(previous[index], next[index])),
+    };
+    // Observers registered during dispatch start with the next update.
+    // oxlint-disable-next-line unicorn/no-useless-spread
+    for (const [token, observer] of [...observers]) {
+        if (!observers.has(token))
+            continue;
+        try {
+            observer(update);
+        }
+        catch (error) {
+            reportSafely(reportError, error);
+        }
+    }
+}
+let programId = 0;
+export const nextProgramId = () => ++programId;
+const programObservers = new Set();
+export const hasProgramObservers = () => programObservers.size > 0;
+export function traceProgram(event) {
+    for (const observer of programObservers) {
+        try {
+            observer(event);
+        }
+        catch (error) {
+            reportSafely(reportError, error);
+        }
+    }
+}
+/** Opt-in bounded metadata history. Inspection only: no command replay or payload snapshots. */
+export function observePrograms(limit = 100) {
+    const capacity = Math.max(1, Math.min(1000, Math.floor(limit) || 100));
+    const entries = [];
+    const receive = (event) => {
+        entries.push(event);
+        if (entries.length > capacity)
+            entries.shift();
+    };
+    programObservers.add(receive);
+    return { events: () => entries.slice(), dispose: () => programObservers.delete(receive) };
+}

package/dist/dom.d.ts

@@ -0,0 +1,66 @@
+import { type ReportError } from './errors.js';
+import { type BindingSource } from './diagnostics.js';
+import type { Rows } from './index.js';
+import type { JSX } from './jsx.js';
+import type { DomMount } from './mount.js';
+import type { Program, Send } from './program.js';
+type Dependencies = () => readonly unknown[];
+type Cleanup = () => void;
+type Build<M, E> = (scope: Scope<M, E>, parent: Node, before: Node | null) => void;
+/** Compiler implementation. No implicit tracking, proxies, or per-binding subscriptions. */
+export declare class Scope<M, E> {
+    value: M;
+    readonly send: Send<E>;
+    readonly report: ReportError;
+    readonly jobs: Cleanup[];
+    readonly cleanups: Cleanup[];
+    disposed: boolean;
+    private revision;
+    constructor(value: M, send: Send<E>, report?: ReportError);
+    derive<A>(dependencies: Dependencies, compute: () => A, source?: BindingSource): () => A;
+    watch(dependencies: Dependencies, apply: () => void, source?: BindingSource): void;
+    set(value: M): void;
+    dispose(): void;
+}
+export interface View<M, E> {
+    (props: M): JSX.Element;
+    (props: {
+        model: M;
+        send: Send<E>;
+    }): JSX.Element;
+    readonly build: Build<M, E>;
+}
+declare const contentBrand: unique symbol;
+/** Owned markup accepted wherever JSX can render content. */
+export interface CompiledContent {
+    readonly [contentBrand]: true;
+}
+/** A compiled template with a typed placement value, captured in its declaring view. */
+export interface Slot<A = void> {
+    (value: A): JSX.Element;
+    readonly [contentBrand]: [A] extends [void] ? true : false;
+}
+/** Compiler marker: declare inside view(), or directly in a compiled component prop. */
+export declare function slot<A = void>(_render: (value: A) => JSX.Element): Slot<A>;
+/** Compiler output. Captures follow their declaring scope; placements own independent scopes. */
+export declare function compiledSlot<M, E, A>(owner: Scope<M, E>, build: Build<A, E>): Slot<A>;
+/** This declaration is a compiler marker, never a component setup callback. */
+export declare function view<M, E>(_render: (model: M, send: Send<E>) => JSX.Element): View<M, E>;
+export declare function compiled<M, E>(build: Build<M, E>): View<M, E>;
+export declare function mountView<M, E>(parent: Node, definition: View<M, E>, source: Program<M, E>, options?: {
+    onError?: ReportError;
+}): () => void;
+export declare function element(parent: Node, before: Node | null, tag: string): Element;
+export declare function attribute(element: Element, name: string, value: unknown): void;
+export declare function text<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null, dependencies: Dependencies, read: () => unknown, source?: BindingSource): void;
+export declare function event<M, E>(scope: Scope<M, E>, element: Element, name: string, handler: (event: Event) => unknown): void;
+export declare function branch<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null, choose: () => boolean, yes: Build<M, E>, no: Build<M, E>): void;
+export declare function each<M, E, A>(scope: Scope<M, E>, parent: Node, before: Node | null, read: () => Rows<A> | readonly A[], outer: Dependencies, indexUsed: boolean, build: Build<readonly [A, number], E>): void;
+export declare function invoke<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null, dependencies: Dependencies, read: () => readonly unknown[], build: Build<readonly unknown[], E>): void;
+export declare function child<M, E, C, F>(scope: Scope<M, E>, parent: Node, before: Node | null, definition: View<C, F>, dependencies: Dependencies, model: () => C, send: Send<F>): void;
+export declare function attach<M, E>(scope: Scope<M, E>, element: Element, dependencies: Dependencies, read: () => DomMount | undefined): void;
+export declare function portal<M, E>(scope: Scope<M, E>, build: Build<M, E>): void;
+/** Build static markup once per document/namespace, then clone native nodes at each use. */
+export declare function template(build: (parent: Node, before: Node | null) => void): (parent: Node, before: Node | null) => void;
+export declare function literal(parent: Node, before: Node | null, value: string): void;
+export {};