@magnet-js/ssr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando G. Vilar
+
+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/esm/mod.d.ts

@@ -0,0 +1,4 @@
+export { ssrWindow } from "./ssr.js";
+export { wait } from "./wait.js";
+export type { Done, Wait } from "./wait.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}

package/esm/mod.js

@@ -0,0 +1,2 @@
+export { ssrWindow } from "./ssr.js";
+export { wait } from "./wait.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/ssr.d.ts

@@ -0,0 +1,93 @@
+import type { MagnetWindow } from "@magnet-js/ui";
+/**
+ * Base class for server-side elements. Tracks attributes and children with
+ * just enough surface area for Magnet to operate during SSR.
+ *
+ * Event listener methods are no-ops because listeners are never invoked on
+ * the server. `attachShadow` creates a declarative shadow root rendered as a
+ * `<template shadowrootmode="...">` child.
+ */
+declare class SSRElement {
+    readonly name: string;
+    /** Plain attribute map. Namespaced attributes are stored by their full key. */
+    readonly attributes: any;
+    protected children: Set<object>;
+    isConnected: boolean;
+    readonly nodeType = 1;
+    private shadow;
+    constructor(name: string);
+    /** Sets a regular attribute. */
+    setAttribute(name: string, value: string): void;
+    /** Sets a namespaced attribute, storing it under the supplied key. */
+    setAttributeNS(_namespace: string, name: string, value: string): void;
+    /** Removes an attribute by key. */
+    removeAttribute(name: string): void;
+    /** Removes a namespaced attribute by key. */
+    removeAttributeNS(_namespace: string, name: string): void;
+    /**
+     * Creates a declarative shadow root for SSR.
+     *
+     * Renders as a `<template shadowrootmode="...">` child element. Throws if
+     * a shadow root has already been attached.
+     */
+    attachShadow({ clonable, customElementRegistry, delegatesFocus, mode, serializable, slotAssignment, }: ShadowRootInit): SSRParentHTMLElement;
+    /** Returns the declarative shadow root, or `null` if none exists. */
+    get shadowRoot(): SSRElement | null;
+    /** Replaces all children with a single escaped text node. */
+    set textContent(value: string);
+    /** Concatenates the rendered text of all children. */
+    get textContent(): string;
+    /** No-op: event listeners are not invoked on the server. */
+    addEventListener(_type: string, _callback: EventListenerOrEventListenerObject | null, _options?: AddEventListenerOptions | boolean): void;
+    /** No-op: event listeners are not invoked on the server. */
+    removeEventListener(_type: string, _callback: EventListenerOrEventListenerObject | null, _options?: EventListenerOptions | boolean): void;
+    /** Appends a child, replacing it if already present. */
+    appendChild(child: object): object;
+    /** Removes a child from this element. */
+    removeChild(child: object): object;
+    /** Inserts a child before a reference child, or appends if the ref is missing. */
+    insertBefore(child: object, ref: object): object;
+}
+/** HTML element with the XHTML namespace and an uppercase tag name. */
+export declare class SSRHTMLElement extends SSRElement {
+    get namespaceURI(): any;
+    get tagName(): string;
+}
+/** Void HTML element that renders as a self-closing tag. */
+export declare class SSRVoidHTMLElement extends SSRHTMLElement {
+    toString(): string;
+}
+/**
+ * Serializes an element opening tag into `parts`.
+ *
+ * Truthy attribute values are emitted as `key="value"`; empty strings are
+ * emitted as boolean attributes (`key`).
+ */
+export declare const voidToString: (parts: string[], name: string, attributes: Record<string, string>, end: string) => void;
+/** HTML element with children, rendered as `<tag>...</tag>`. */
+export declare class SSRParentHTMLElement extends SSRHTMLElement {
+    toString(): string;
+}
+/** Base class for MathML and SVG elements, rendered as self-closing or parent tags. */
+export declare class SSRNSElement extends SSRElement {
+    toString(): string;
+}
+/** MathML element with the MathML namespace. */
+export declare class SSRMathMLElement extends SSRNSElement {
+    get namespaceURI(): any;
+    get tagName(): string;
+}
+/** SVG element with the SVG namespace. */
+export declare class SSRSVGElement extends SSRNSElement {
+    get namespaceURI(): any;
+    get tagName(): string;
+}
+/**
+ * Minimal `MagnetWindow` implementation for server-side rendering.
+ *
+ * Use this as the `window` when constructing a Magnet context to render
+ * components to HTML strings on the server.
+ */
+export declare const ssrWindow: MagnetWindow;
+export {};
+//# sourceMappingURL=ssr.d.ts.map

package/esm/ssr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../src/ssr.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AA+ClD;;;;;;;GAOG;AACH,cAAM,UAAU;IAQF,QAAQ,CAAC,IAAI,EAAE,MAAM;IAPjC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,MAAyC;IAC5D,SAAS,CAAC,QAAQ,cAAqB;IACvC,WAAW,UAAS;IACpB,QAAQ,CAAC,QAAQ,KAAK;IACtB,OAAO,CAAC,MAAM,CAA2B;gBAEpB,IAAI,EAAE,MAAM;IAEjC,gCAAgC;IAChC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIxC,sEAAsE;IACtE,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAI9D,mCAAmC;IACnC,eAAe,CAAC,IAAI,EAAE,MAAM;IAI5B,6CAA6C;IAC7C,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAIlD;;;;;OAKG;IACH,YAAY,CACV,EACE,QAAQ,EACR,qBAAqB,EACrB,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,cAAc,GACf,EAAE,cAAc;IAoBnB,qEAAqE;IACrE,IAAI,UAAU,sBAEb;IAED,6DAA6D;IAC7D,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,EAG5B;IAED,sDAAsD;IACtD,IAAI,WAAW,IAAI,MAAM,CAKxB;IAED,4DAA4D;IAC5D,gBAAgB,CACd,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,kCAAkC,GAAG,IAAI,EACpD,QAAQ,CAAC,EAAE,uBAAuB,GAAG,OAAO,GAC3C,IAAI;IAEP,4DAA4D;IAC5D,mBAAmB,CACjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,kCAAkC,GAAG,IAAI,EACpD,QAAQ,CAAC,EAAE,oBAAoB,GAAG,OAAO,GACxC,IAAI;IAEP,wDAAwD;IACxD,WAAW,CAAC,KAAK,EAAE,MAAM;IAQzB,yCAAyC;IACzC,WAAW,CAAC,KAAK,EAAE,MAAM;IAKzB,kFAAkF;IAClF,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAgBxC;AAED,uEAAuE;AACvE,qBAAa,cAAe,SAAQ,UAAU;IAC5C,IAAI,YAAY,QAEf;IACD,IAAI,OAAO,WAEV;CACF;AAED,4DAA4D;AAC5D,qBAAa,kBAAmB,SAAQ,cAAc;IAC3C,QAAQ;CAKlB;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAChB,MAAM,EAAE,QACT,MAAM,cACA,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAC7B,MAAM,SAaZ,CAAC;AAEF,gEAAgE;AAChE,qBAAa,oBAAqB,SAAQ,cAAc;IAC7C,QAAQ;CAOlB;AAED,uFAAuF;AACvF,qBAAa,YAAa,SAAQ,UAAU;IACjC,QAAQ;CAUlB;AAED,gDAAgD;AAChD,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,IAAI,YAAY,QAEf;IACD,IAAI,OAAO,WAEV;CACF;AAED,0CAA0C;AAC1C,qBAAa,aAAc,SAAQ,YAAY;IAC7C,IAAI,YAAY,QAEf;IACD,IAAI,OAAO,WAEV;CACF;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,YAcvB,CAAC"}

package/esm/ssr.js

@@ -0,0 +1,300 @@
+import { createEmpty, isVoid, MATHML_NAMESPACE, SVG_NAMESPACE, XHTML_NAMESPACE, } from "@magnet-js/common";
+/** Minimal server-side comment node. Renders as `<!--data-->`. */
+class SSRComment {
+    constructor(data) {
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: data
+        });
+        Object.defineProperty(this, "nodeType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 8
+        });
+    }
+    /** Length of the rendered comment string. */
+    get length() {
+        return this.data.length + 7;
+    }
+    /** Returns the HTML comment representation. */
+    toString() {
+        return `<!--${this.data}-->`;
+    }
+}
+/** Minimal server-side text node. Escapes `&`, `<`, and `>`. */
+class SSRText {
+    constructor(text) {
+        Object.defineProperty(this, "nodeType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 3
+        });
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.data = text.replace(/&|<|>/g, (value) => {
+            switch (value) {
+                case "&":
+                    return "&amp;";
+                case "<":
+                    return "&lt;";
+            }
+            return "&gt;";
+        });
+    }
+    /** Length of the escaped text content. */
+    get length() {
+        return this.data.length;
+    }
+    /** Returns the escaped text content. */
+    toString() {
+        return this.data;
+    }
+}
+/**
+ * Base class for server-side elements. Tracks attributes and children with
+ * just enough surface area for Magnet to operate during SSR.
+ *
+ * Event listener methods are no-ops because listeners are never invoked on
+ * the server. `attachShadow` creates a declarative shadow root rendered as a
+ * `<template shadowrootmode="...">` child.
+ */
+class SSRElement {
+    constructor(name) {
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: name
+        });
+        /** Plain attribute map. Namespaced attributes are stored by their full key. */
+        Object.defineProperty(this, "attributes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: createEmpty()
+        });
+        Object.defineProperty(this, "children", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "isConnected", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "nodeType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 1
+        });
+        Object.defineProperty(this, "shadow", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    /** Sets a regular attribute. */
+    setAttribute(name, value) {
+        this.attributes[name] = value;
+    }
+    /** Sets a namespaced attribute, storing it under the supplied key. */
+    setAttributeNS(_namespace, name, value) {
+        this.attributes[name] = value;
+    }
+    /** Removes an attribute by key. */
+    removeAttribute(name) {
+        delete this.attributes[name];
+    }
+    /** Removes a namespaced attribute by key. */
+    removeAttributeNS(_namespace, name) {
+        delete this.attributes[name];
+    }
+    /**
+     * Creates a declarative shadow root for SSR.
+     *
+     * Renders as a `<template shadowrootmode="...">` child element. Throws if
+     * a shadow root has already been attached.
+     */
+    attachShadow({ clonable, customElementRegistry, delegatesFocus, mode, serializable, slotAssignment, }) {
+        if (this.shadow)
+            throw new Error("Shadow root already exists");
+        const shadow = new SSRParentHTMLElement("template");
+        shadow.attributes.shadowrootmode = mode;
+        if (clonable)
+            shadow.attributes.shadowrootclonable = "";
+        if (customElementRegistry) {
+            shadow.attributes.shadowrootcustomelementregistry = "";
+        }
+        if (delegatesFocus)
+            shadow.attributes.shadowrootdelegatesfocus = "";
+        if (serializable)
+            shadow.attributes.shadowrootserializable = "";
+        if (slotAssignment) {
+            shadow.attributes.shadowrootslotassignment = slotAssignment;
+        }
+        this.appendChild(shadow);
+        this.shadow = shadow;
+        return shadow;
+    }
+    /** Returns the declarative shadow root, or `null` if none exists. */
+    get shadowRoot() {
+        return this.shadow;
+    }
+    /** Replaces all children with a single escaped text node. */
+    set textContent(value) {
+        this.children.clear();
+        this.appendChild(new SSRText(value));
+    }
+    /** Concatenates the rendered text of all children. */
+    get textContent() {
+        const out = new Array(this.children.size);
+        let i = 0;
+        for (const child of this.children)
+            out[i++] = child.toString();
+        return out.join("");
+    }
+    /** No-op: event listeners are not invoked on the server. */
+    addEventListener(_type, _callback, _options) { }
+    /** No-op: event listeners are not invoked on the server. */
+    removeEventListener(_type, _callback, _options) { }
+    /** Appends a child, replacing it if already present. */
+    appendChild(child) {
+        if (child) {
+            this.children.delete(child);
+            this.children.add(child);
+        }
+        return child;
+    }
+    /** Removes a child from this element. */
+    removeChild(child) {
+        if (child)
+            this.children.delete(child);
+        return child;
+    }
+    /** Inserts a child before a reference child, or appends if the ref is missing. */
+    insertBefore(child, ref) {
+        if (child) {
+            if (ref && this.children.has(ref)) {
+                if (ref !== child) {
+                    const nextChildren = new Set();
+                    this.children.delete(child);
+                    for (const prev of this.children) {
+                        if (prev === ref)
+                            nextChildren.add(child);
+                        nextChildren.add(prev);
+                    }
+                    this.children = nextChildren;
+                }
+            }
+            else
+                this.appendChild(child);
+        }
+        return child;
+    }
+}
+/** HTML element with the XHTML namespace and an uppercase tag name. */
+export class SSRHTMLElement extends SSRElement {
+    get namespaceURI() {
+        return XHTML_NAMESPACE;
+    }
+    get tagName() {
+        return this.name.toUpperCase();
+    }
+}
+/** Void HTML element that renders as a self-closing tag. */
+export class SSRVoidHTMLElement extends SSRHTMLElement {
+    toString() {
+        const parts = [];
+        voidToString(parts, this.name, this.attributes, ">");
+        return parts.join("");
+    }
+}
+/**
+ * Serializes an element opening tag into `parts`.
+ *
+ * Truthy attribute values are emitted as `key="value"`; empty strings are
+ * emitted as boolean attributes (`key`).
+ */
+export const voidToString = (parts, name, attributes, end) => {
+    parts.push("<" + name);
+    const keys = Object.keys(attributes);
+    let i = keys.length;
+    let key;
+    let value;
+    while (i--) {
+        key = keys[i];
+        value = attributes[key];
+        parts.push(value ? ` ${key}="${value}"` : ` ${key}`);
+    }
+    parts.push(end);
+};
+/** HTML element with children, rendered as `<tag>...</tag>`. */
+export class SSRParentHTMLElement extends SSRHTMLElement {
+    toString() {
+        const parts = [];
+        voidToString(parts, this.name, this.attributes, ">");
+        for (const child of this.children)
+            parts.push(child.toString());
+        parts.push("</" + this.name + ">");
+        return parts.join("");
+    }
+}
+/** Base class for MathML and SVG elements, rendered as self-closing or parent tags. */
+export class SSRNSElement extends SSRElement {
+    toString() {
+        const parent = this.children.size > 0;
+        const parts = [];
+        voidToString(parts, this.name, this.attributes, parent ? " >" : "/>");
+        if (parent) {
+            for (const child of this.children)
+                parts.push(child.toString());
+            parts.push("</" + this.name + ">");
+        }
+        return parts.join("");
+    }
+}
+/** MathML element with the MathML namespace. */
+export class SSRMathMLElement extends SSRNSElement {
+    get namespaceURI() {
+        return MATHML_NAMESPACE;
+    }
+    get tagName() {
+        return this.name;
+    }
+}
+/** SVG element with the SVG namespace. */
+export class SSRSVGElement extends SSRNSElement {
+    get namespaceURI() {
+        return SVG_NAMESPACE;
+    }
+    get tagName() {
+        return this.name;
+    }
+}
+/**
+ * Minimal `MagnetWindow` implementation for server-side rendering.
+ *
+ * Use this as the `window` when constructing a Magnet context to render
+ * components to HTML strings on the server.
+ */
+export const ssrWindow = {
+    document: {
+        createComment: (data) => new SSRComment(data),
+        createElement: (name) => new (isVoid(name) ? SSRVoidHTMLElement : SSRParentHTMLElement)(name),
+        createElementNS: (namespace, name) => new (namespace === MATHML_NAMESPACE ? SSRMathMLElement : SSRSVGElement)(name),
+        createTextNode: (data) => new SSRText(data),
+    },
+};

package/esm/wait.d.ts

@@ -0,0 +1,67 @@
+import type { SignalAPI } from "@magnet-js/common";
+/**
+ * Marks a single unit of pending asynchronous work as complete.
+ *
+ * Returned by {@link Wait}. Each call must balance a prior call to the
+ * wait-group factory. Calling the same `Done` more than once is a no-op.
+ */
+export interface Done {
+    (): void;
+}
+/**
+ * Wait-group factory used to coordinate asynchronous work during SSR.
+ *
+ * Magnet components can start async operations (for example data fetching)
+ * and register each operation by calling `wait()`. The returned {@link Done}
+ * callback is invoked when the operation finishes. The `done` promise
+ * resolves once every registered operation has completed, signaling that
+ * the server can safely serialize the rendered tree.
+ */
+export interface Wait {
+    /** Registers one pending operation and returns its completion callback. */
+    (): Done;
+    /**
+     * Resolves the first time every registered operation has completed.
+     *
+     * Once resolved, this promise never returns to a pending state; the wait
+     * group must be fully populated before the counter reaches zero.
+     */
+    done: Promise<void>;
+}
+/**
+ * Creates a wait group for coordinating async work during server-side
+ * rendering.
+ *
+ * Use it when a component triggers asynchronous tasks whose results update
+ * signals. The server awaits `wait.done` before stringifying the rendered
+ * DOM tree.
+ *
+ * The returned `done` promise resolves the first time the pending counter
+ * reaches zero. After that it stays resolved forever, so every unit of work
+ * must be registered before the counter reaches zero.
+ *
+ * The `signal` argument provides the reactive primitives used to detect
+ * completion. A one-shot effect watches an internal settled signal and
+ * resolves `done` the first time the signal becomes true, after any signal
+ * effects scheduled by the async work have run.
+ *
+ * @example
+ * ```ts
+ * const ready = wait(tc39);
+ *
+ * const page = app(() => {
+ *   const data = state<string | null>(null);
+ *   const done = ready();
+ *   fetchData().then((value) => {
+ *     data.set(value);
+ *     done();
+ *   });
+ *   return div(data);
+ * });
+ *
+ * await ready.done;
+ * console.log(page.toString());
+ * ```
+ */
+export declare const wait: (signal: Pick<SignalAPI, "state" | "effect">) => Wait;
+//# sourceMappingURL=wait.d.ts.map

package/esm/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,IAAI,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,IAAI;IACnB,2EAA2E;IAC3E,IAAI,IAAI,CAAC;IAET;;;;;OAKG;IACH,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,IAAI,WAAY,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC,KAAG,IAyBlE,CAAC"}

package/esm/wait.js

@@ -0,0 +1,59 @@
+/**
+ * Creates a wait group for coordinating async work during server-side
+ * rendering.
+ *
+ * Use it when a component triggers asynchronous tasks whose results update
+ * signals. The server awaits `wait.done` before stringifying the rendered
+ * DOM tree.
+ *
+ * The returned `done` promise resolves the first time the pending counter
+ * reaches zero. After that it stays resolved forever, so every unit of work
+ * must be registered before the counter reaches zero.
+ *
+ * The `signal` argument provides the reactive primitives used to detect
+ * completion. A one-shot effect watches an internal settled signal and
+ * resolves `done` the first time the signal becomes true, after any signal
+ * effects scheduled by the async work have run.
+ *
+ * @example
+ * ```ts
+ * const ready = wait(tc39);
+ *
+ * const page = app(() => {
+ *   const data = state<string | null>(null);
+ *   const done = ready();
+ *   fetchData().then((value) => {
+ *     data.set(value);
+ *     done();
+ *   });
+ *   return div(data);
+ * });
+ *
+ * await ready.done;
+ * console.log(page.toString());
+ * ```
+ */
+export const wait = (signal) => {
+    let resolve;
+    const done = new Promise((r) => {
+        resolve = r;
+    });
+    let counter = 0;
+    const settled = signal.state(false);
+    const dispose = signal.effect(() => {
+        if (settled.get()) {
+            dispose();
+            resolve();
+        }
+    });
+    const waiter = () => {
+        counter++;
+        let callback = () => {
+            if (!--counter)
+                settled.set(true);
+        };
+        return () => callback = callback?.();
+    };
+    waiter.done = done;
+    return waiter;
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@magnet-js/ssr",
+  "version": "0.1.0",
+  "description": "Server-side rendering support for Magnet components.",
+  "homepage": "https://gitlab.com/magnetjs/monorepo/-/tree/main/packages/ssr",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/magnetjs/monorepo.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://gitlab.com/magnetjs/monorepo/-/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    }
+  },
+  "dependencies": {
+    "@magnet-js/common": "0.1.0",
+    "@magnet-js/ui": "0.1.0"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/mod.d.ts

@@ -0,0 +1,4 @@
+export { ssrWindow } from "./ssr.js";
+export { wait } from "./wait.js";
+export type { Done, Wait } from "./wait.js";
+//# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}

package/script/mod.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wait = exports.ssrWindow = void 0;
+var ssr_js_1 = require("./ssr.js");
+Object.defineProperty(exports, "ssrWindow", { enumerable: true, get: function () { return ssr_js_1.ssrWindow; } });
+var wait_js_1 = require("./wait.js");
+Object.defineProperty(exports, "wait", { enumerable: true, get: function () { return wait_js_1.wait; } });

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/ssr.d.ts

@@ -0,0 +1,93 @@
+import type { MagnetWindow } from "@magnet-js/ui";
+/**
+ * Base class for server-side elements. Tracks attributes and children with
+ * just enough surface area for Magnet to operate during SSR.
+ *
+ * Event listener methods are no-ops because listeners are never invoked on
+ * the server. `attachShadow` creates a declarative shadow root rendered as a
+ * `<template shadowrootmode="...">` child.
+ */
+declare class SSRElement {
+    readonly name: string;
+    /** Plain attribute map. Namespaced attributes are stored by their full key. */
+    readonly attributes: any;
+    protected children: Set<object>;
+    isConnected: boolean;
+    readonly nodeType = 1;
+    private shadow;
+    constructor(name: string);
+    /** Sets a regular attribute. */
+    setAttribute(name: string, value: string): void;
+    /** Sets a namespaced attribute, storing it under the supplied key. */
+    setAttributeNS(_namespace: string, name: string, value: string): void;
+    /** Removes an attribute by key. */
+    removeAttribute(name: string): void;
+    /** Removes a namespaced attribute by key. */
+    removeAttributeNS(_namespace: string, name: string): void;
+    /**
+     * Creates a declarative shadow root for SSR.
+     *
+     * Renders as a `<template shadowrootmode="...">` child element. Throws if
+     * a shadow root has already been attached.
+     */
+    attachShadow({ clonable, customElementRegistry, delegatesFocus, mode, serializable, slotAssignment, }: ShadowRootInit): SSRParentHTMLElement;
+    /** Returns the declarative shadow root, or `null` if none exists. */
+    get shadowRoot(): SSRElement | null;
+    /** Replaces all children with a single escaped text node. */
+    set textContent(value: string);
+    /** Concatenates the rendered text of all children. */
+    get textContent(): string;
+    /** No-op: event listeners are not invoked on the server. */
+    addEventListener(_type: string, _callback: EventListenerOrEventListenerObject | null, _options?: AddEventListenerOptions | boolean): void;
+    /** No-op: event listeners are not invoked on the server. */
+    removeEventListener(_type: string, _callback: EventListenerOrEventListenerObject | null, _options?: EventListenerOptions | boolean): void;
+    /** Appends a child, replacing it if already present. */
+    appendChild(child: object): object;
+    /** Removes a child from this element. */
+    removeChild(child: object): object;
+    /** Inserts a child before a reference child, or appends if the ref is missing. */
+    insertBefore(child: object, ref: object): object;
+}
+/** HTML element with the XHTML namespace and an uppercase tag name. */
+export declare class SSRHTMLElement extends SSRElement {
+    get namespaceURI(): any;
+    get tagName(): string;
+}
+/** Void HTML element that renders as a self-closing tag. */
+export declare class SSRVoidHTMLElement extends SSRHTMLElement {
+    toString(): string;
+}
+/**
+ * Serializes an element opening tag into `parts`.
+ *
+ * Truthy attribute values are emitted as `key="value"`; empty strings are
+ * emitted as boolean attributes (`key`).
+ */
+export declare const voidToString: (parts: string[], name: string, attributes: Record<string, string>, end: string) => void;
+/** HTML element with children, rendered as `<tag>...</tag>`. */
+export declare class SSRParentHTMLElement extends SSRHTMLElement {
+    toString(): string;
+}
+/** Base class for MathML and SVG elements, rendered as self-closing or parent tags. */
+export declare class SSRNSElement extends SSRElement {
+    toString(): string;
+}
+/** MathML element with the MathML namespace. */
+export declare class SSRMathMLElement extends SSRNSElement {
+    get namespaceURI(): any;
+    get tagName(): string;
+}
+/** SVG element with the SVG namespace. */
+export declare class SSRSVGElement extends SSRNSElement {
+    get namespaceURI(): any;
+    get tagName(): string;
+}
+/**
+ * Minimal `MagnetWindow` implementation for server-side rendering.
+ *
+ * Use this as the `window` when constructing a Magnet context to render
+ * components to HTML strings on the server.
+ */
+export declare const ssrWindow: MagnetWindow;
+export {};
+//# sourceMappingURL=ssr.d.ts.map

package/script/ssr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../src/ssr.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AA+ClD;;;;;;;GAOG;AACH,cAAM,UAAU;IAQF,QAAQ,CAAC,IAAI,EAAE,MAAM;IAPjC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,MAAyC;IAC5D,SAAS,CAAC,QAAQ,cAAqB;IACvC,WAAW,UAAS;IACpB,QAAQ,CAAC,QAAQ,KAAK;IACtB,OAAO,CAAC,MAAM,CAA2B;gBAEpB,IAAI,EAAE,MAAM;IAEjC,gCAAgC;IAChC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIxC,sEAAsE;IACtE,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAI9D,mCAAmC;IACnC,eAAe,CAAC,IAAI,EAAE,MAAM;IAI5B,6CAA6C;IAC7C,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAIlD;;;;;OAKG;IACH,YAAY,CACV,EACE,QAAQ,EACR,qBAAqB,EACrB,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,cAAc,GACf,EAAE,cAAc;IAoBnB,qEAAqE;IACrE,IAAI,UAAU,sBAEb;IAED,6DAA6D;IAC7D,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,EAG5B;IAED,sDAAsD;IACtD,IAAI,WAAW,IAAI,MAAM,CAKxB;IAED,4DAA4D;IAC5D,gBAAgB,CACd,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,kCAAkC,GAAG,IAAI,EACpD,QAAQ,CAAC,EAAE,uBAAuB,GAAG,OAAO,GAC3C,IAAI;IAEP,4DAA4D;IAC5D,mBAAmB,CACjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,kCAAkC,GAAG,IAAI,EACpD,QAAQ,CAAC,EAAE,oBAAoB,GAAG,OAAO,GACxC,IAAI;IAEP,wDAAwD;IACxD,WAAW,CAAC,KAAK,EAAE,MAAM;IAQzB,yCAAyC;IACzC,WAAW,CAAC,KAAK,EAAE,MAAM;IAKzB,kFAAkF;IAClF,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAgBxC;AAED,uEAAuE;AACvE,qBAAa,cAAe,SAAQ,UAAU;IAC5C,IAAI,YAAY,QAEf;IACD,IAAI,OAAO,WAEV;CACF;AAED,4DAA4D;AAC5D,qBAAa,kBAAmB,SAAQ,cAAc;IAC3C,QAAQ;CAKlB;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAChB,MAAM,EAAE,QACT,MAAM,cACA,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAC7B,MAAM,SAaZ,CAAC;AAEF,gEAAgE;AAChE,qBAAa,oBAAqB,SAAQ,cAAc;IAC7C,QAAQ;CAOlB;AAED,uFAAuF;AACvF,qBAAa,YAAa,SAAQ,UAAU;IACjC,QAAQ;CAUlB;AAED,gDAAgD;AAChD,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,IAAI,YAAY,QAEf;IACD,IAAI,OAAO,WAEV;CACF;AAED,0CAA0C;AAC1C,qBAAa,aAAc,SAAQ,YAAY;IAC7C,IAAI,YAAY,QAEf;IACD,IAAI,OAAO,WAEV;CACF;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,YAcvB,CAAC"}

package/script/ssr.js

@@ -0,0 +1,310 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ssrWindow = exports.SSRSVGElement = exports.SSRMathMLElement = exports.SSRNSElement = exports.SSRParentHTMLElement = exports.voidToString = exports.SSRVoidHTMLElement = exports.SSRHTMLElement = void 0;
+const common_1 = require("@magnet-js/common");
+/** Minimal server-side comment node. Renders as `<!--data-->`. */
+class SSRComment {
+    constructor(data) {
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: data
+        });
+        Object.defineProperty(this, "nodeType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 8
+        });
+    }
+    /** Length of the rendered comment string. */
+    get length() {
+        return this.data.length + 7;
+    }
+    /** Returns the HTML comment representation. */
+    toString() {
+        return `<!--${this.data}-->`;
+    }
+}
+/** Minimal server-side text node. Escapes `&`, `<`, and `>`. */
+class SSRText {
+    constructor(text) {
+        Object.defineProperty(this, "nodeType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 3
+        });
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.data = text.replace(/&|<|>/g, (value) => {
+            switch (value) {
+                case "&":
+                    return "&amp;";
+                case "<":
+                    return "&lt;";
+            }
+            return "&gt;";
+        });
+    }
+    /** Length of the escaped text content. */
+    get length() {
+        return this.data.length;
+    }
+    /** Returns the escaped text content. */
+    toString() {
+        return this.data;
+    }
+}
+/**
+ * Base class for server-side elements. Tracks attributes and children with
+ * just enough surface area for Magnet to operate during SSR.
+ *
+ * Event listener methods are no-ops because listeners are never invoked on
+ * the server. `attachShadow` creates a declarative shadow root rendered as a
+ * `<template shadowrootmode="...">` child.
+ */
+class SSRElement {
+    constructor(name) {
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: name
+        });
+        /** Plain attribute map. Namespaced attributes are stored by their full key. */
+        Object.defineProperty(this, "attributes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (0, common_1.createEmpty)()
+        });
+        Object.defineProperty(this, "children", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "isConnected", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "nodeType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 1
+        });
+        Object.defineProperty(this, "shadow", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    /** Sets a regular attribute. */
+    setAttribute(name, value) {
+        this.attributes[name] = value;
+    }
+    /** Sets a namespaced attribute, storing it under the supplied key. */
+    setAttributeNS(_namespace, name, value) {
+        this.attributes[name] = value;
+    }
+    /** Removes an attribute by key. */
+    removeAttribute(name) {
+        delete this.attributes[name];
+    }
+    /** Removes a namespaced attribute by key. */
+    removeAttributeNS(_namespace, name) {
+        delete this.attributes[name];
+    }
+    /**
+     * Creates a declarative shadow root for SSR.
+     *
+     * Renders as a `<template shadowrootmode="...">` child element. Throws if
+     * a shadow root has already been attached.
+     */
+    attachShadow({ clonable, customElementRegistry, delegatesFocus, mode, serializable, slotAssignment, }) {
+        if (this.shadow)
+            throw new Error("Shadow root already exists");
+        const shadow = new SSRParentHTMLElement("template");
+        shadow.attributes.shadowrootmode = mode;
+        if (clonable)
+            shadow.attributes.shadowrootclonable = "";
+        if (customElementRegistry) {
+            shadow.attributes.shadowrootcustomelementregistry = "";
+        }
+        if (delegatesFocus)
+            shadow.attributes.shadowrootdelegatesfocus = "";
+        if (serializable)
+            shadow.attributes.shadowrootserializable = "";
+        if (slotAssignment) {
+            shadow.attributes.shadowrootslotassignment = slotAssignment;
+        }
+        this.appendChild(shadow);
+        this.shadow = shadow;
+        return shadow;
+    }
+    /** Returns the declarative shadow root, or `null` if none exists. */
+    get shadowRoot() {
+        return this.shadow;
+    }
+    /** Replaces all children with a single escaped text node. */
+    set textContent(value) {
+        this.children.clear();
+        this.appendChild(new SSRText(value));
+    }
+    /** Concatenates the rendered text of all children. */
+    get textContent() {
+        const out = new Array(this.children.size);
+        let i = 0;
+        for (const child of this.children)
+            out[i++] = child.toString();
+        return out.join("");
+    }
+    /** No-op: event listeners are not invoked on the server. */
+    addEventListener(_type, _callback, _options) { }
+    /** No-op: event listeners are not invoked on the server. */
+    removeEventListener(_type, _callback, _options) { }
+    /** Appends a child, replacing it if already present. */
+    appendChild(child) {
+        if (child) {
+            this.children.delete(child);
+            this.children.add(child);
+        }
+        return child;
+    }
+    /** Removes a child from this element. */
+    removeChild(child) {
+        if (child)
+            this.children.delete(child);
+        return child;
+    }
+    /** Inserts a child before a reference child, or appends if the ref is missing. */
+    insertBefore(child, ref) {
+        if (child) {
+            if (ref && this.children.has(ref)) {
+                if (ref !== child) {
+                    const nextChildren = new Set();
+                    this.children.delete(child);
+                    for (const prev of this.children) {
+                        if (prev === ref)
+                            nextChildren.add(child);
+                        nextChildren.add(prev);
+                    }
+                    this.children = nextChildren;
+                }
+            }
+            else
+                this.appendChild(child);
+        }
+        return child;
+    }
+}
+/** HTML element with the XHTML namespace and an uppercase tag name. */
+class SSRHTMLElement extends SSRElement {
+    get namespaceURI() {
+        return common_1.XHTML_NAMESPACE;
+    }
+    get tagName() {
+        return this.name.toUpperCase();
+    }
+}
+exports.SSRHTMLElement = SSRHTMLElement;
+/** Void HTML element that renders as a self-closing tag. */
+class SSRVoidHTMLElement extends SSRHTMLElement {
+    toString() {
+        const parts = [];
+        (0, exports.voidToString)(parts, this.name, this.attributes, ">");
+        return parts.join("");
+    }
+}
+exports.SSRVoidHTMLElement = SSRVoidHTMLElement;
+/**
+ * Serializes an element opening tag into `parts`.
+ *
+ * Truthy attribute values are emitted as `key="value"`; empty strings are
+ * emitted as boolean attributes (`key`).
+ */
+const voidToString = (parts, name, attributes, end) => {
+    parts.push("<" + name);
+    const keys = Object.keys(attributes);
+    let i = keys.length;
+    let key;
+    let value;
+    while (i--) {
+        key = keys[i];
+        value = attributes[key];
+        parts.push(value ? ` ${key}="${value}"` : ` ${key}`);
+    }
+    parts.push(end);
+};
+exports.voidToString = voidToString;
+/** HTML element with children, rendered as `<tag>...</tag>`. */
+class SSRParentHTMLElement extends SSRHTMLElement {
+    toString() {
+        const parts = [];
+        (0, exports.voidToString)(parts, this.name, this.attributes, ">");
+        for (const child of this.children)
+            parts.push(child.toString());
+        parts.push("</" + this.name + ">");
+        return parts.join("");
+    }
+}
+exports.SSRParentHTMLElement = SSRParentHTMLElement;
+/** Base class for MathML and SVG elements, rendered as self-closing or parent tags. */
+class SSRNSElement extends SSRElement {
+    toString() {
+        const parent = this.children.size > 0;
+        const parts = [];
+        (0, exports.voidToString)(parts, this.name, this.attributes, parent ? " >" : "/>");
+        if (parent) {
+            for (const child of this.children)
+                parts.push(child.toString());
+            parts.push("</" + this.name + ">");
+        }
+        return parts.join("");
+    }
+}
+exports.SSRNSElement = SSRNSElement;
+/** MathML element with the MathML namespace. */
+class SSRMathMLElement extends SSRNSElement {
+    get namespaceURI() {
+        return common_1.MATHML_NAMESPACE;
+    }
+    get tagName() {
+        return this.name;
+    }
+}
+exports.SSRMathMLElement = SSRMathMLElement;
+/** SVG element with the SVG namespace. */
+class SSRSVGElement extends SSRNSElement {
+    get namespaceURI() {
+        return common_1.SVG_NAMESPACE;
+    }
+    get tagName() {
+        return this.name;
+    }
+}
+exports.SSRSVGElement = SSRSVGElement;
+/**
+ * Minimal `MagnetWindow` implementation for server-side rendering.
+ *
+ * Use this as the `window` when constructing a Magnet context to render
+ * components to HTML strings on the server.
+ */
+exports.ssrWindow = {
+    document: {
+        createComment: (data) => new SSRComment(data),
+        createElement: (name) => new ((0, common_1.isVoid)(name) ? SSRVoidHTMLElement : SSRParentHTMLElement)(name),
+        createElementNS: (namespace, name) => new (namespace === common_1.MATHML_NAMESPACE ? SSRMathMLElement : SSRSVGElement)(name),
+        createTextNode: (data) => new SSRText(data),
+    },
+};

package/script/wait.d.ts

@@ -0,0 +1,67 @@
+import type { SignalAPI } from "@magnet-js/common";
+/**
+ * Marks a single unit of pending asynchronous work as complete.
+ *
+ * Returned by {@link Wait}. Each call must balance a prior call to the
+ * wait-group factory. Calling the same `Done` more than once is a no-op.
+ */
+export interface Done {
+    (): void;
+}
+/**
+ * Wait-group factory used to coordinate asynchronous work during SSR.
+ *
+ * Magnet components can start async operations (for example data fetching)
+ * and register each operation by calling `wait()`. The returned {@link Done}
+ * callback is invoked when the operation finishes. The `done` promise
+ * resolves once every registered operation has completed, signaling that
+ * the server can safely serialize the rendered tree.
+ */
+export interface Wait {
+    /** Registers one pending operation and returns its completion callback. */
+    (): Done;
+    /**
+     * Resolves the first time every registered operation has completed.
+     *
+     * Once resolved, this promise never returns to a pending state; the wait
+     * group must be fully populated before the counter reaches zero.
+     */
+    done: Promise<void>;
+}
+/**
+ * Creates a wait group for coordinating async work during server-side
+ * rendering.
+ *
+ * Use it when a component triggers asynchronous tasks whose results update
+ * signals. The server awaits `wait.done` before stringifying the rendered
+ * DOM tree.
+ *
+ * The returned `done` promise resolves the first time the pending counter
+ * reaches zero. After that it stays resolved forever, so every unit of work
+ * must be registered before the counter reaches zero.
+ *
+ * The `signal` argument provides the reactive primitives used to detect
+ * completion. A one-shot effect watches an internal settled signal and
+ * resolves `done` the first time the signal becomes true, after any signal
+ * effects scheduled by the async work have run.
+ *
+ * @example
+ * ```ts
+ * const ready = wait(tc39);
+ *
+ * const page = app(() => {
+ *   const data = state<string | null>(null);
+ *   const done = ready();
+ *   fetchData().then((value) => {
+ *     data.set(value);
+ *     done();
+ *   });
+ *   return div(data);
+ * });
+ *
+ * await ready.done;
+ * console.log(page.toString());
+ * ```
+ */
+export declare const wait: (signal: Pick<SignalAPI, "state" | "effect">) => Wait;
+//# sourceMappingURL=wait.d.ts.map

package/script/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,IAAI,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,IAAI;IACnB,2EAA2E;IAC3E,IAAI,IAAI,CAAC;IAET;;;;;OAKG;IACH,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,IAAI,WAAY,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC,KAAG,IAyBlE,CAAC"}

package/script/wait.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wait = void 0;
+/**
+ * Creates a wait group for coordinating async work during server-side
+ * rendering.
+ *
+ * Use it when a component triggers asynchronous tasks whose results update
+ * signals. The server awaits `wait.done` before stringifying the rendered
+ * DOM tree.
+ *
+ * The returned `done` promise resolves the first time the pending counter
+ * reaches zero. After that it stays resolved forever, so every unit of work
+ * must be registered before the counter reaches zero.
+ *
+ * The `signal` argument provides the reactive primitives used to detect
+ * completion. A one-shot effect watches an internal settled signal and
+ * resolves `done` the first time the signal becomes true, after any signal
+ * effects scheduled by the async work have run.
+ *
+ * @example
+ * ```ts
+ * const ready = wait(tc39);
+ *
+ * const page = app(() => {
+ *   const data = state<string | null>(null);
+ *   const done = ready();
+ *   fetchData().then((value) => {
+ *     data.set(value);
+ *     done();
+ *   });
+ *   return div(data);
+ * });
+ *
+ * await ready.done;
+ * console.log(page.toString());
+ * ```
+ */
+const wait = (signal) => {
+    let resolve;
+    const done = new Promise((r) => {
+        resolve = r;
+    });
+    let counter = 0;
+    const settled = signal.state(false);
+    const dispose = signal.effect(() => {
+        if (settled.get()) {
+            dispose();
+            resolve();
+        }
+    });
+    const waiter = () => {
+        counter++;
+        let callback = () => {
+            if (!--counter)
+                settled.set(true);
+        };
+        return () => callback = callback?.();
+    };
+    waiter.done = done;
+    return waiter;
+};
+exports.wait = wait;