effectweb 0.2.2 → 0.3.0

package/dist/component.d.ts

@@ -1,14 +1,15 @@
+import type { Snapshot } from './snapshot.js';
 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 & {
+    init: (props: Snapshot<Props>) => (State | Snapshot<State>) & {
         readonly props?: never;
     };
     view: View<State & {
         readonly props: Props;
-    }, Partial<State> & {
+    }, (Partial<State> | Partial<Snapshot<State>>) & {
         readonly props?: never;
     }>;
 }): View<Props, never>;
@@ -16,9 +17,9 @@ export declare function localComponent<Props, State extends object>(definition:
 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>;
+    init: (props: Snapshot<Props>) => Model | Snapshot<Model>;
+    receive?: (model: Snapshot<Model>, props: Snapshot<Props>) => Transition<Model, Message, R>;
+    update: (model: Snapshot<Model>, message: Message) => Transition<Model, Message, R>;
     view: View<Model, Message>;
 } & ([R] extends [never] ? {
     runtime?: UiRuntime<R>;
@@ -27,7 +28,7 @@ export declare function component<Props, Model extends {
 })): 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;
+    create: (props: Snapshot<Props>) => import('./program').Program<Model, Message>;
+    receive: (source: import('./program').Program<Model, Message>, props: Snapshot<Props>) => void;
     view: View<Model, Message>;
 }): View<Props, never>;

package/dist/diagnostics.d.ts

@@ -10,6 +10,7 @@ export interface BindingUpdate {
     readonly source: BindingSource;
     readonly changed: readonly string[];
     readonly kind: 'derive' | 'binding';
+    readonly reason: 'initial' | 'dependencies';
 }
 /** Each registration has its own lifetime; observers can be stopped in any order. */
 export declare function observeBindings(next: (update: BindingUpdate) => void): () => void;
@@ -30,3 +31,27 @@ export declare function observePrograms(limit?: number): {
     events: () => ProgramUpdate[];
     dispose: () => boolean;
 };
+/** Counts aggregate all mounted instances of a source expression. */
+export interface BindingInspection {
+    readonly source: BindingSource;
+    readonly derives: number;
+    readonly bindings: number;
+    readonly changed: readonly string[];
+    readonly reason: BindingUpdate['reason'];
+}
+export interface BindingInspector {
+    /** Most recently updated first; bounded by limit (default 200, maximum 1000). */
+    entries(): readonly BindingInspection[];
+    subscribe(next: () => void): () => void;
+    clear(): void;
+    /** Unsubscribe and release all metadata and listeners. */
+    dispose(): void;
+}
+/** Development metadata only: never reads or retains models, values, or DOM nodes. */
+export declare function inspectBindings(options?: {
+    readonly limit?: number;
+}): BindingInspector;
+/** Mount a live source inspector. Mount before the application to include initial evaluations.
+ * The returned cleanup removes the panel; an externally supplied inspector keeps its lifetime.
+ */
+export declare function mountBindingInspector(target: HTMLElement, inspector?: BindingInspector): () => void;

package/dist/diagnostics.js

@@ -14,10 +14,11 @@ export function traceBinding(source, previous, next, kind) {
     const update = {
         source,
         kind,
+        reason: previous ? 'dependencies' : 'initial',
         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
+    // oxlint-disable-next-line unicorn/no-useless-spread -- Iterate a snapshot because listeners can add or remove subscriptions.
     for (const [token, observer] of [...observers]) {
         if (!observers.has(token))
             continue;
@@ -55,3 +56,168 @@ export function observePrograms(limit = 100) {
     programObservers.add(receive);
     return { events: () => entries.slice(), dispose: () => programObservers.delete(receive) };
 }
+/** Development metadata only: never reads or retains models, values, or DOM nodes. */
+export function inspectBindings(options = {}) {
+    const requested = options.limit ?? 200;
+    const limit = Number.isFinite(requested)
+        ? Math.max(1, Math.min(1000, Math.floor(requested)))
+        : 200;
+    const records = new Map();
+    const listeners = new Set();
+    let disposed = false;
+    const notify = () => {
+        // New subscribers start with the next event.
+        // oxlint-disable-next-line unicorn/no-useless-spread -- Iterate a snapshot because listeners can add or remove subscriptions.
+        for (const listener of [...listeners]) {
+            if (!listeners.has(listener))
+                continue;
+            try {
+                listener();
+            }
+            catch (error) {
+                reportSafely(reportError, error);
+            }
+        }
+    };
+    const stop = observeBindings((update) => {
+        const source = update.source;
+        const key = JSON.stringify([source.file, source.line, source.column, source.expression]);
+        const previous = records.get(key);
+        const record = Object.freeze({
+            source: Object.freeze({
+                file: source.file,
+                line: source.line,
+                column: source.column,
+                expression: source.expression,
+                dependencies: Object.freeze([...source.dependencies]),
+            }),
+            derives: (previous?.derives ?? 0) + Number(update.kind === 'derive'),
+            bindings: (previous?.bindings ?? 0) + Number(update.kind === 'binding'),
+            changed: Object.freeze([...update.changed]),
+            reason: update.reason,
+        });
+        records.delete(key);
+        records.set(key, record);
+        if (records.size > limit)
+            records.delete(records.keys().next().value);
+        notify();
+    });
+    return {
+        entries: () => [...records.values()].reverse(),
+        subscribe(next) {
+            if (!disposed)
+                listeners.add(next);
+            return () => {
+                listeners.delete(next);
+            };
+        },
+        clear() {
+            records.clear();
+            if (!disposed)
+                notify();
+        },
+        dispose() {
+            disposed = true;
+            stop();
+            records.clear();
+            listeners.clear();
+        },
+    };
+}
+/** Mount a live source inspector. Mount before the application to include initial evaluations.
+ * The returned cleanup removes the panel; an externally supplied inspector keeps its lifetime.
+ */
+export function mountBindingInspector(target, inspector) {
+    const inspection = inspector ?? inspectBindings();
+    const document = target.ownerDocument;
+    const panel = document.createElement('section');
+    panel.setAttribute('aria-label', 'EffectWeb dependency inspector');
+    const heading = document.createElement('h2');
+    heading.textContent = 'EffectWeb dependencies';
+    const hint = document.createElement('p');
+    hint.textContent =
+        'Development builds only. Counts include initial evaluations and aggregate mounted instances. Old sources are evicted.';
+    const filter = document.createElement('input');
+    filter.type = 'search';
+    filter.placeholder = 'Filter file, expression or dependency';
+    filter.setAttribute('aria-label', filter.placeholder);
+    const clear = document.createElement('button');
+    clear.type = 'button';
+    clear.textContent = 'Clear counts';
+    const table = document.createElement('table');
+    const header = table.createTHead().insertRow();
+    for (const label of [
+        'Source expression',
+        'Inferred dependencies',
+        'Latest reason',
+        'Derives',
+        'Bindings',
+    ]) {
+        const cell = document.createElement('th');
+        cell.scope = 'col';
+        cell.textContent = label;
+        header.append(cell);
+    }
+    const body = table.createTBody();
+    const status = document.createElement('p');
+    let active = true;
+    let queued = false;
+    const render = () => {
+        queued = false;
+        if (!active)
+            return;
+        const search = filter.value.toLowerCase();
+        const entries = inspection
+            .entries()
+            .filter((entry) => [entry.source.file, entry.source.expression, ...entry.source.dependencies]
+            .join(' ')
+            .toLowerCase()
+            .includes(search));
+        body.replaceChildren();
+        for (const entry of entries) {
+            const row = body.insertRow();
+            const source = entry.source;
+            const values = [
+                `${source.file}:${source.line}:${source.column}\n${source.expression}`,
+                source.dependencies.join(', ') || 'No snapshot dependencies',
+                entry.reason === 'initial'
+                    ? 'Initial evaluation'
+                    : `Changed: ${entry.changed.join(', ') || 'dependency value'}`,
+                String(entry.derives),
+                String(entry.bindings),
+            ];
+            for (const value of values) {
+                const cell = row.insertCell();
+                cell.textContent = value;
+                cell.style.whiteSpace = 'pre-wrap';
+                cell.style.verticalAlign = 'top';
+                cell.style.padding = '0.4em';
+            }
+        }
+        status.textContent = entries.length
+            ? `${entries.length} source expressions`
+            : 'No matching evaluations. Interact with an application compiled in development mode.';
+    };
+    const schedule = () => {
+        if (!queued && active) {
+            queued = true;
+            queueMicrotask(render);
+        }
+    };
+    const reset = () => inspection.clear();
+    filter.addEventListener('input', render);
+    clear.addEventListener('click', reset);
+    const stop = inspection.subscribe(schedule);
+    panel.append(heading, hint, filter, clear, table, status);
+    target.append(panel);
+    render();
+    return () => {
+        active = false;
+        stop();
+        filter.removeEventListener('input', render);
+        clear.removeEventListener('click', reset);
+        panel.remove();
+        if (!inspector)
+            inspection.dispose();
+    };
+}

package/dist/dom-attributes.json

@@ -0,0 +1,71 @@
+{
+  "boolean": [
+    "allowfullscreen",
+    "async",
+    "autofocus",
+    "autoplay",
+    "capture",
+    "checked",
+    "controls",
+    "default",
+    "defer",
+    "disabled",
+    "disablepictureinpicture",
+    "disableremoteplayback",
+    "download",
+    "formnovalidate",
+    "hidden",
+    "inert",
+    "ismap",
+    "itemscope",
+    "loop",
+    "multiple",
+    "muted",
+    "nomodule",
+    "novalidate",
+    "open",
+    "playsinline",
+    "readonly",
+    "required",
+    "reversed",
+    "selected"
+  ],
+  "booleanish": ["contenteditable", "draggable", "spellcheck"],
+  "aliases": {
+    "className": "class",
+    "tabIndex": "tabindex",
+    "htmlFor": "for",
+    "contentEditable": "contenteditable",
+    "readOnly": "readonly",
+    "playsInline": "playsinline",
+    "autoFocus": "autofocus",
+    "autoPlay": "autoplay",
+    "allowFullscreen": "allowfullscreen",
+    "formNoValidate": "formnovalidate",
+    "isMap": "ismap",
+    "itemScope": "itemscope",
+    "noModule": "nomodule",
+    "noValidate": "novalidate",
+    "disablePictureInPicture": "disablepictureinpicture",
+    "disableRemotePlayback": "disableremoteplayback",
+    "acceptCharset": "accept-charset",
+    "httpEquiv": "http-equiv",
+    "classname": "class",
+    "htmlfor": "for",
+    "acceptcharset": "accept-charset",
+    "httpequiv": "http-equiv"
+  },
+  "properties": {
+    "readonly": "readOnly",
+    "playsinline": "playsInline",
+    "allowfullscreen": "allowFullscreen",
+    "formnovalidate": "formNoValidate",
+    "ismap": "isMap",
+    "itemscope": "itemScope",
+    "nomodule": "noModule",
+    "novalidate": "noValidate",
+    "disablepictureinpicture": "disablePictureInPicture",
+    "disableremoteplayback": "disableRemotePlayback"
+  },
+  "booleanValues": { "translate": { "true": "yes", "false": "no" } }
+}

package/dist/dom.d.ts

@@ -1,7 +1,8 @@
+import type { Snapshot } from './snapshot.js';
 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 { jsxComponent, type JSX } from './jsx.js';
 import type { DomMount } from './mount.js';
 import type { Program, Send } from './program.js';
 type Dependencies = () => readonly unknown[];
@@ -22,14 +23,20 @@ export declare class Scope<M, E> {
     set(value: M): void;
     dispose(): void;
 }
-export interface View<M, E> {
-    (props: M): JSX.Element;
-    (props: {
-        model: M;
-        send: Send<E>;
-    }): JSX.Element;
+export interface View<M, E> extends JSX.ComponentType {
+    (this: never, props: [E] extends [never] ? M | Snapshot<M> : never): JSX.Element;
     readonly build: Build<M, E>;
 }
+/** Compiler marker for mounting a view with an explicit model and message dispatcher. */
+export declare const ViewBinding: (<M, E>(this: never, _props: {
+    view: View<M, E>;
+    model: NoInfer<M> | Snapshot<NoInfer<M>>;
+    send: Send<NoInfer<E>>;
+}) => JSX.Element) & {
+    [jsxComponent]: true;
+};
+/** Untyped callers get an actionable failure instead of silently losing child messages. */
+export declare function unboundSend(_message: never): never;
 declare const contentBrand: unique symbol;
 /** Owned markup accepted wherever JSX can render content. */
 export interface CompiledContent {
@@ -37,30 +44,46 @@ export interface CompiledContent {
 }
 /** A compiled template with a typed placement value, captured in its declaring view. */
 export interface Slot<A = void> {
-    (value: A): JSX.Element;
+    (value: A | Snapshot<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>;
+export declare function slot<A = void>(_render: (value: Snapshot<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 = never>(_render: (model: M, send: Send<E>) => JSX.Element): View<M, E>;
+export declare function view<M, E = never>(_render: (model: Snapshot<M>, send: Send<E>) => JSX.Element): View<M, E>;
 export declare function compiled<M, E>(build: Build<M, E>): View<M, E>;
+export interface PortalProps {
+    readonly children?: JSX.Element;
+    readonly mount?: Element | undefined;
+}
+/** Owned content in an element target, defaulting to the document body. */
+export declare const Portal: View<PortalProps, never>;
 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;
+/** Compiler output for attributes whose unchanged value needs no DOM refresh. */
+export declare function bindAttribute<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => unknown, source?: BindingSource): void;
+/** Handled edits can change a control even when dispatch publishes no new model. */
+export declare function bindControl<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => unknown, source?: BindingSource): 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;
+/** One handler identity owns its requests, regardless of the JSX attribute spelling. */
+export declare function bindEvent<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => unknown): void;
+/** Reconcile merged JSX attributes. Each host, event and control owns its cleanup. */
+export declare function bindAttributes<M, E>(scope: Scope<M, E>, element: Element, dependencies: Dependencies, read: () => Readonly<Record<string, 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;
+/** A late-bound compiled definition owns one replaceable DOM region. */
+export declare function viewRegion<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null): (next: View<M, E> | undefined) => void;
+export declare function attach<M, E, T extends Element>(scope: Scope<M, E>, element: T, dependencies: Dependencies, read: () => DomMount<NoInfer<T>> | undefined): void;
+export declare function portal<M, E>(scope: Scope<M, E>, build: Build<M, E>, mount?: () => Element | undefined): 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 template(build: string | ((parent: Node, before: Node | null) => void), depth?: number): (parent: Node, before: Node | null) => Node;
 export declare function literal(parent: Node, before: Node | null, value: string): void;
 export {};