@lab206/ssr 0.1.0

package/LICENSE

@@ -0,0 +1,114 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Scott Powers
+
+Licensed Work:        Powers
+                      The Licensed Work is (c) 2026 Scott Powers
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided You do not use the Licensed Work for a
+                      Competing Offering.
+
+                      A “Competing Offering” is a product, hosted service,
+                      library, framework, design system, or documentation
+                      site whose primary purpose is to provide a
+                      general-purpose UI runtime, component library, or
+                      design-system kit that substitutes for the Licensed
+                      Work (including rebranded or forked distributions
+                      marketed as a competing UI kit or “Powers
+                      alternative”).
+
+                      Building end-user applications, internal tools, or
+                      client project work *with* the Licensed Work is
+                      allowed and is not a Competing Offering.
+
+Change Date:          Four years from the first public release of each
+                      version of the Licensed Work, or 2030-08-15,
+                      whichever is earlier for that version
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Software,
+see LICENSE-COMMERCIAL.md or contact the Licensor.
+
+Notice
+
+The Business Source License (this document, or the “License”) is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+“Business Source License” is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,6 @@
+# @lab206/ssr
+
+Part of [Powers](https://github.com/spowers2/powers) — fine-grained UI kit with a design system built in.
+
+- Docs: https://lab206.com/docs
+- License: BUSL-1.1 (source-available)

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { type MountResult } from "@lab206/dom";
+export interface RenderToStringOptions {
+    /** Wait for microtasks / flush reactive updates before serializing. Default true. */
+    flush?: boolean;
+    /** Optional URL for the virtual window (routing, absolute links). */
+    url?: string;
+}
+/**
+ * Mount `app` in a virtual document and return `innerHTML` of the root.
+ * Disposes the app after serialization.
+ */
+export declare function renderToString(app: () => MountResult, options?: RenderToStringOptions): Promise<string>;
+/**
+ * Wrap app HTML in a minimal document shell for full-page SSR responses.
+ */
+export declare function htmlDocument(body: string, options?: {
+    title?: string;
+    head?: string;
+    /** Extra attributes on <html>, e.g. data-pu-theme */
+    htmlAttrs?: string;
+}): string;
+export { island, markIsland, hydrateIsland, hydrateIslands, islandPlaceholder, ISLAND_ATTR, } from "./islands.js";
+export type { IslandFactory, IslandRegistry, HydrateIslandsOptions, } from "./islands.js";
+export { defineIslands, listIslandsInHtml } from "./registry.js";
+export type { IslandRegistryApi } from "./registry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,WAAW,EACtB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA+CjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IACR,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,MAAM,CAgBR;AAUD,OAAO,EACL,MAAM,EACN,UAAU,EACV,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,aAAa,EACb,cAAc,EACd,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACjE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,102 @@
+/**
+ * @lab206/ssr
+ *
+ * - `renderToString` — full tree → HTML (happy-dom)
+ * - `htmlDocument` — wrap body in a document shell
+ * - Islands — `island` / `markIsland` / `hydrateIslands` for selective client interactivity
+ *
+ * @example SSR + island
+ * ```ts
+ * // server
+ * const body = await renderToString(() =>
+ *   h("main", null,
+ *     h("h1", { text: "Static" }),
+ *     island("counter", () => Counter()),
+ *   )
+ * );
+ *
+ * // client
+ * hydrateIslands({ counter: () => Counter() });
+ * ```
+ */
+import { Window } from "happy-dom";
+import { mount } from "@lab206/dom";
+import { flush } from "@lab206/core";
+/**
+ * Mount `app` in a virtual document and return `innerHTML` of the root.
+ * Disposes the app after serialization.
+ */
+export async function renderToString(app, options = {}) {
+    const window = new Window({
+        url: options.url ?? "https://localhost/",
+    });
+    const document = window.document;
+    const g = globalThis;
+    const prev = {
+        window: g.window,
+        document: g.document,
+        Node: g.Node,
+        HTMLElement: g.HTMLElement,
+        Text: g.Text,
+        Element: g.Element,
+    };
+    g.window = window;
+    g.document = document;
+    g.Node = window.Node;
+    g.HTMLElement = window.HTMLElement;
+    g.Text = window.Text;
+    g.Element = window.Element;
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    let html = "";
+    try {
+        const dispose = mount(root, app);
+        if (options.flush !== false) {
+            await Promise.resolve();
+            await Promise.resolve();
+            flush();
+        }
+        html = root.innerHTML;
+        dispose();
+    }
+    finally {
+        g.window = prev.window;
+        g.document = prev.document;
+        g.Node = prev.Node;
+        g.HTMLElement = prev.HTMLElement;
+        g.Text = prev.Text;
+        g.Element = prev.Element;
+        window.close();
+    }
+    return html;
+}
+/**
+ * Wrap app HTML in a minimal document shell for full-page SSR responses.
+ */
+export function htmlDocument(body, options) {
+    const title = options?.title ?? "Powers";
+    const head = options?.head ?? "";
+    const htmlAttrs = options?.htmlAttrs ? ` ${options.htmlAttrs}` : "";
+    return `<!DOCTYPE html>
+<html lang="en"${htmlAttrs}>
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>${escapeHtml(title)}</title>
+${head}
+</head>
+<body>
+<div id="app">${body}</div>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export { island, markIsland, hydrateIsland, hydrateIslands, islandPlaceholder, ISLAND_ATTR, } from "./islands.js";
+export { defineIslands, listIslandsInHtml } from "./registry.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/islands.d.ts

@@ -0,0 +1,61 @@
+import { type Dispose } from "@lab206/core";
+import { type MountResult } from "@lab206/dom";
+export type IslandFactory = () => MountResult;
+export type IslandRegistry = Record<string, IslandFactory>;
+export declare const ISLAND_ATTR = "data-pu-island";
+/**
+ * Mark a host element as a client island (sets `data-pu-island`).
+ * During SSR the inner HTML is serialized; on the client call `hydrateIslands`.
+ */
+export declare function markIsland(name: string, host?: HTMLElement): HTMLElement;
+/**
+ * Create an island host and mount `app` into it (SSR + client create path).
+ * Prefer this when building trees that will be stringified, then hydrated.
+ *
+ * @example
+ * ```ts
+ * // server
+ * const html = await renderToString(() =>
+ *   island("counter", () => <Counter />)
+ * );
+ *
+ * // client
+ * hydrateIslands({ counter: () => <Counter /> });
+ * ```
+ */
+export declare function island(name: string, app: IslandFactory): HTMLElement;
+export interface HydrateIslandsOptions {
+    /** Document or subtree to search (default: document) */
+    root?: ParentNode;
+    /**
+     * Called when a `data-pu-island` has no factory.
+     * Default: console.warn
+     */
+    onMissing?: (name: string, el: HTMLElement) => void;
+    /**
+     * If true, leave server HTML when no factory is registered.
+     * Default: true
+     */
+    preserveOnMissing?: boolean;
+}
+/**
+ * Hydrate all `[data-pu-island]` nodes under `root` using a name → factory map.
+ * Clears server HTML inside each island and mounts the client app.
+ * Returns a dispose that tears down every island.
+ */
+export declare function hydrateIslands(registry: IslandRegistry, rootOrOptions?: ParentNode | HydrateIslandsOptions): Dispose;
+/**
+ * Hydrate a single island by name (first match).
+ */
+export declare function hydrateIsland(name: string, factory: IslandFactory, root?: ParentNode): Dispose;
+/**
+ * Static HTML placeholder for an island (no happy-dom needed).
+ * Useful when the shell is a template string.
+ */
+export declare function islandPlaceholder(name: string, fallbackHtml?: string): string;
+/** @internal */
+export declare function createIslandRoot(app: IslandFactory): {
+    host: HTMLElement;
+    dispose: Dispose;
+};
+//# sourceMappingURL=islands.d.ts.map

package/dist/islands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"islands.d.ts","sourceRoot":"","sources":["../src/islands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,MAAM,aAAa,GAAG,MAAM,WAAW,CAAC;AAC9C,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3D,eAAO,MAAM,WAAW,mBAAmB,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAIxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,WAAW,CAUpE;AAED,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;IACpD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,cAAc,EACxB,aAAa,GAAE,UAAU,GAAG,qBAAgC,GAC3D,OAAO,CAmCT;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,UAAqB,GAC1B,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,SAAK,GAAG,MAAM,CAEzE;AAMD,gBAAgB;AAChB,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB,CAaA"}

package/dist/islands.js

@@ -0,0 +1,112 @@
+import { createRoot } from "@lab206/core";
+import { mount } from "@lab206/dom";
+export const ISLAND_ATTR = "data-pu-island";
+/**
+ * Mark a host element as a client island (sets `data-pu-island`).
+ * During SSR the inner HTML is serialized; on the client call `hydrateIslands`.
+ */
+export function markIsland(name, host) {
+    const el = host ?? document.createElement("div");
+    el.setAttribute(ISLAND_ATTR, name);
+    return el;
+}
+/**
+ * Create an island host and mount `app` into it (SSR + client create path).
+ * Prefer this when building trees that will be stringified, then hydrated.
+ *
+ * @example
+ * ```ts
+ * // server
+ * const html = await renderToString(() =>
+ *   island("counter", () => <Counter />)
+ * );
+ *
+ * // client
+ * hydrateIslands({ counter: () => <Counter /> });
+ * ```
+ */
+export function island(name, app) {
+    const host = markIsland(name);
+    // Mount interactive tree into the island host
+    const result = app();
+    if (result == null)
+        return host;
+    const nodes = Array.isArray(result) ? result : [result];
+    for (const n of nodes) {
+        if (n)
+            host.appendChild(n);
+    }
+    return host;
+}
+/**
+ * Hydrate all `[data-pu-island]` nodes under `root` using a name → factory map.
+ * Clears server HTML inside each island and mounts the client app.
+ * Returns a dispose that tears down every island.
+ */
+export function hydrateIslands(registry, rootOrOptions = document) {
+    const options = rootOrOptions && typeof rootOrOptions === "object" && "nodeType" in rootOrOptions
+        ? { root: rootOrOptions }
+        : rootOrOptions;
+    const root = options.root ?? document;
+    const preserveOnMissing = options.preserveOnMissing !== false;
+    const onMissing = options.onMissing ??
+        ((name) => {
+            console.warn(`[powers/ssr] No island registered for "${name}"`);
+        });
+    const disposers = [];
+    const nodes = root.querySelectorAll?.(`[${ISLAND_ATTR}]`) ?? [];
+    nodes.forEach((node) => {
+        const el = node;
+        const name = el.getAttribute(ISLAND_ATTR);
+        if (!name)
+            return;
+        const factory = registry[name];
+        if (!factory) {
+            onMissing(name, el);
+            if (!preserveOnMissing)
+                el.textContent = "";
+            return;
+        }
+        // Replace server markup with live app
+        el.textContent = "";
+        disposers.push(mount(el, factory));
+    });
+    return () => {
+        for (const d of disposers)
+            d();
+    };
+}
+/**
+ * Hydrate a single island by name (first match).
+ */
+export function hydrateIsland(name, factory, root = document) {
+    return hydrateIslands({ [name]: factory }, { root });
+}
+/**
+ * Static HTML placeholder for an island (no happy-dom needed).
+ * Useful when the shell is a template string.
+ */
+export function islandPlaceholder(name, fallbackHtml = "") {
+    return `<div ${ISLAND_ATTR}="${escapeAttr(name)}">${fallbackHtml}</div>`;
+}
+function escapeAttr(s) {
+    return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+/** @internal */
+export function createIslandRoot(app) {
+    const host = document.createElement("div");
+    let dispose;
+    createRoot((d) => {
+        dispose = d;
+        const result = app();
+        if (result == null)
+            return;
+        const nodes = Array.isArray(result) ? result : [result];
+        for (const n of nodes) {
+            if (n)
+                host.appendChild(n);
+        }
+    });
+    return { host, dispose };
+}
+//# sourceMappingURL=islands.js.map

package/dist/islands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"islands.js","sourceRoot":"","sources":["../src/islands.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,39 @@
+import type { Dispose } from "@lab206/core";
+import type { IslandFactory, IslandRegistry } from "./islands.js";
+export interface IslandRegistryApi {
+    /** Registered factories */
+    readonly entries: IslandRegistry;
+    /** Register or replace an island factory */
+    register(name: string, factory: IslandFactory): void;
+    /** Register many islands at once */
+    registerAll(map: IslandRegistry): void;
+    /** Hydrate all matching islands in the document (or root) */
+    hydrate(root?: ParentNode): Dispose;
+    /** List island names present under root (DOM) */
+    discover(root?: ParentNode): string[];
+    /** Names registered but not found in the document */
+    missingInDom(root?: ParentNode): string[];
+    /** Island names in the DOM that have no factory */
+    missingInRegistry(root?: ParentNode): string[];
+}
+/**
+ * Typed-ish island registry for client entrypoints.
+ *
+ * @example
+ * ```ts
+ * const islands = defineIslands({
+ *   counter: () => Counter(),
+ *   cart: () => CartWidget(),
+ * });
+ *
+ * // after HTML is in the document:
+ * islands.hydrate();
+ * console.log(islands.missingInRegistry()); // unexpected SSR islands
+ * ```
+ */
+export declare function defineIslands(initial?: IslandRegistry): IslandRegistryApi;
+/**
+ * Parse island names from an HTML string (no DOM required).
+ */
+export declare function listIslandsInHtml(html: string): string[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGlE,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACrD,oCAAoC;IACpC,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,6DAA6D;IAC7D,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;IACtC,qDAAqD;IACrD,YAAY,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;IAC1C,mDAAmD;IACnD,iBAAiB,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,OAAO,GAAE,cAAmB,GAC3B,iBAAiB,CAiDnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQxD"}

package/dist/registry.js

@@ -0,0 +1,72 @@
+import { hydrateIslands, ISLAND_ATTR } from "./islands.js";
+/**
+ * Typed-ish island registry for client entrypoints.
+ *
+ * @example
+ * ```ts
+ * const islands = defineIslands({
+ *   counter: () => Counter(),
+ *   cart: () => CartWidget(),
+ * });
+ *
+ * // after HTML is in the document:
+ * islands.hydrate();
+ * console.log(islands.missingInRegistry()); // unexpected SSR islands
+ * ```
+ */
+export function defineIslands(initial = {}) {
+    const entries = { ...initial };
+    function register(name, factory) {
+        entries[name] = factory;
+    }
+    function registerAll(map) {
+        Object.assign(entries, map);
+    }
+    function discover(root = document) {
+        const nodes = root.querySelectorAll?.(`[${ISLAND_ATTR}]`) ?? [];
+        const names = [];
+        nodes.forEach((n) => {
+            const name = n.getAttribute(ISLAND_ATTR);
+            if (name)
+                names.push(name);
+        });
+        return names;
+    }
+    function missingInDom(root = document) {
+        const present = new Set(discover(root));
+        return Object.keys(entries).filter((k) => !present.has(k));
+    }
+    function missingInRegistry(root = document) {
+        return discover(root).filter((name) => !entries[name]);
+    }
+    function hydrate(root = document) {
+        const unknown = missingInRegistry(root);
+        if (unknown.length) {
+            console.warn(`[powers/ssr] DOM islands with no registry entry: ${unknown.join(", ")}`);
+        }
+        return hydrateIslands(entries, root);
+    }
+    return {
+        entries,
+        register,
+        registerAll,
+        hydrate,
+        discover,
+        missingInDom,
+        missingInRegistry,
+    };
+}
+/**
+ * Parse island names from an HTML string (no DOM required).
+ */
+export function listIslandsInHtml(html) {
+    const re = /data-pu-island=["']([^"']+)["']/g;
+    const names = [];
+    let m;
+    while ((m = re.exec(html))) {
+        if (m[1])
+            names.push(m[1]);
+    }
+    return names;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAmB3D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,UAA0B,EAAE;IAE5B,MAAM,OAAO,GAAmB,EAAE,GAAG,OAAO,EAAE,CAAC;IAE/C,SAAS,QAAQ,CAAC,IAAY,EAAE,OAAsB;QACpD,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,SAAS,WAAW,CAAC,GAAmB;QACtC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,SAAS,QAAQ,CAAC,OAAmB,QAAQ;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC,IAAI,WAAW,GAAG,CAAC,IAAI,EAAE,CAAC;QAChE,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YAClB,MAAM,IAAI,GAAI,CAAa,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YACtD,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;QACH,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS,YAAY,CAAC,OAAmB,QAAQ;QAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACxC,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,SAAS,iBAAiB,CAAC,OAAmB,QAAQ;QACpD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,SAAS,OAAO,CAAC,OAAmB,QAAQ;QAC1C,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CACV,oDAAoD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzE,CAAC;QACJ,CAAC;QACD,OAAO,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,OAAO;QACL,OAAO;QACP,QAAQ;QACR,WAAW;QACX,OAAO;QACP,QAAQ;QACR,YAAY;QACZ,iBAAiB;KAClB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,EAAE,GAAG,kCAAkC,CAAC;IAC9C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@lab206/ssr",
+  "version": "0.1.0",
+  "description": "SSR foundation for Powers — render apps to HTML strings (happy-dom).",
+  "type": "module",
+  "license": "BUSL-1.1",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.css",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "dependencies": {
+    "happy-dom": "^17.4.4",
+    "@lab206/core": "0.1.0",
+    "@lab206/dom": "0.1.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "author": "Scott Powers",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://lab206.com",
+  "bugs": {
+    "url": "https://github.com/spowers2/powers/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spowers2/powers.git",
+    "directory": "packages/ssr"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test src/*.test.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,141 @@
+/**
+ * @lab206/ssr
+ *
+ * - `renderToString` — full tree → HTML (happy-dom)
+ * - `htmlDocument` — wrap body in a document shell
+ * - Islands — `island` / `markIsland` / `hydrateIslands` for selective client interactivity
+ *
+ * @example SSR + island
+ * ```ts
+ * // server
+ * const body = await renderToString(() =>
+ *   h("main", null,
+ *     h("h1", { text: "Static" }),
+ *     island("counter", () => Counter()),
+ *   )
+ * );
+ *
+ * // client
+ * hydrateIslands({ counter: () => Counter() });
+ * ```
+ */
+import { Window } from "happy-dom";
+import { mount, type MountResult } from "@lab206/dom";
+import { flush } from "@lab206/core";
+
+export interface RenderToStringOptions {
+  /** Wait for microtasks / flush reactive updates before serializing. Default true. */
+  flush?: boolean;
+  /** Optional URL for the virtual window (routing, absolute links). */
+  url?: string;
+}
+
+/**
+ * Mount `app` in a virtual document and return `innerHTML` of the root.
+ * Disposes the app after serialization.
+ */
+export async function renderToString(
+  app: () => MountResult,
+  options: RenderToStringOptions = {},
+): Promise<string> {
+  const window = new Window({
+    url: options.url ?? "https://localhost/",
+  });
+  const document = window.document;
+
+  const g = globalThis as unknown as Record<string, unknown>;
+  const prev = {
+    window: g.window,
+    document: g.document,
+    Node: g.Node,
+    HTMLElement: g.HTMLElement,
+    Text: g.Text,
+    Element: g.Element,
+  };
+
+  g.window = window;
+  g.document = document;
+  g.Node = window.Node;
+  g.HTMLElement = window.HTMLElement;
+  g.Text = window.Text;
+  g.Element = window.Element;
+
+  const root = document.createElement("div");
+  document.body.appendChild(root);
+
+  let html = "";
+  try {
+    const dispose = mount(root as unknown as ParentNode, app);
+    if (options.flush !== false) {
+      await Promise.resolve();
+      await Promise.resolve();
+      flush();
+    }
+    html = root.innerHTML;
+    dispose();
+  } finally {
+    g.window = prev.window;
+    g.document = prev.document;
+    g.Node = prev.Node;
+    g.HTMLElement = prev.HTMLElement;
+    g.Text = prev.Text;
+    g.Element = prev.Element;
+    window.close();
+  }
+
+  return html;
+}
+
+/**
+ * Wrap app HTML in a minimal document shell for full-page SSR responses.
+ */
+export function htmlDocument(
+  body: string,
+  options?: {
+    title?: string;
+    head?: string;
+    /** Extra attributes on <html>, e.g. data-pu-theme */
+    htmlAttrs?: string;
+  },
+): string {
+  const title = options?.title ?? "Powers";
+  const head = options?.head ?? "";
+  const htmlAttrs = options?.htmlAttrs ? ` ${options.htmlAttrs}` : "";
+  return `<!DOCTYPE html>
+<html lang="en"${htmlAttrs}>
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>${escapeHtml(title)}</title>
+${head}
+</head>
+<body>
+<div id="app">${body}</div>
+</body>
+</html>`;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export {
+  island,
+  markIsland,
+  hydrateIsland,
+  hydrateIslands,
+  islandPlaceholder,
+  ISLAND_ATTR,
+} from "./islands.js";
+export type {
+  IslandFactory,
+  IslandRegistry,
+  HydrateIslandsOptions,
+} from "./islands.js";
+
+export { defineIslands, listIslandsInHtml } from "./registry.js";
+export type { IslandRegistryApi } from "./registry.js";

package/src/islands.ts

@@ -0,0 +1,146 @@
+import { createRoot, type Dispose } from "@lab206/core";
+import { mount, type MountResult } from "@lab206/dom";
+
+export type IslandFactory = () => MountResult;
+export type IslandRegistry = Record<string, IslandFactory>;
+
+export const ISLAND_ATTR = "data-pu-island";
+
+/**
+ * Mark a host element as a client island (sets `data-pu-island`).
+ * During SSR the inner HTML is serialized; on the client call `hydrateIslands`.
+ */
+export function markIsland(name: string, host?: HTMLElement): HTMLElement {
+  const el = host ?? document.createElement("div");
+  el.setAttribute(ISLAND_ATTR, name);
+  return el;
+}
+
+/**
+ * Create an island host and mount `app` into it (SSR + client create path).
+ * Prefer this when building trees that will be stringified, then hydrated.
+ *
+ * @example
+ * ```ts
+ * // server
+ * const html = await renderToString(() =>
+ *   island("counter", () => <Counter />)
+ * );
+ *
+ * // client
+ * hydrateIslands({ counter: () => <Counter /> });
+ * ```
+ */
+export function island(name: string, app: IslandFactory): HTMLElement {
+  const host = markIsland(name);
+  // Mount interactive tree into the island host
+  const result = app();
+  if (result == null) return host;
+  const nodes = Array.isArray(result) ? result : [result];
+  for (const n of nodes) {
+    if (n) host.appendChild(n as Node);
+  }
+  return host;
+}
+
+export interface HydrateIslandsOptions {
+  /** Document or subtree to search (default: document) */
+  root?: ParentNode;
+  /**
+   * Called when a `data-pu-island` has no factory.
+   * Default: console.warn
+   */
+  onMissing?: (name: string, el: HTMLElement) => void;
+  /**
+   * If true, leave server HTML when no factory is registered.
+   * Default: true
+   */
+  preserveOnMissing?: boolean;
+}
+
+/**
+ * Hydrate all `[data-pu-island]` nodes under `root` using a name → factory map.
+ * Clears server HTML inside each island and mounts the client app.
+ * Returns a dispose that tears down every island.
+ */
+export function hydrateIslands(
+  registry: IslandRegistry,
+  rootOrOptions: ParentNode | HydrateIslandsOptions = document,
+): Dispose {
+  const options: HydrateIslandsOptions =
+    rootOrOptions && typeof rootOrOptions === "object" && "nodeType" in rootOrOptions
+      ? { root: rootOrOptions as ParentNode }
+      : (rootOrOptions as HydrateIslandsOptions);
+
+  const root = options.root ?? document;
+  const preserveOnMissing = options.preserveOnMissing !== false;
+  const onMissing =
+    options.onMissing ??
+    ((name: string) => {
+      console.warn(`[powers/ssr] No island registered for "${name}"`);
+    });
+
+  const disposers: Dispose[] = [];
+  const nodes = root.querySelectorAll?.(`[${ISLAND_ATTR}]`) ?? [];
+
+  nodes.forEach((node) => {
+    const el = node as HTMLElement;
+    const name = el.getAttribute(ISLAND_ATTR);
+    if (!name) return;
+    const factory = registry[name];
+    if (!factory) {
+      onMissing(name, el);
+      if (!preserveOnMissing) el.textContent = "";
+      return;
+    }
+    // Replace server markup with live app
+    el.textContent = "";
+    disposers.push(mount(el, factory));
+  });
+
+  return () => {
+    for (const d of disposers) d();
+  };
+}
+
+/**
+ * Hydrate a single island by name (first match).
+ */
+export function hydrateIsland(
+  name: string,
+  factory: IslandFactory,
+  root: ParentNode = document,
+): Dispose {
+  return hydrateIslands({ [name]: factory }, { root });
+}
+
+/**
+ * Static HTML placeholder for an island (no happy-dom needed).
+ * Useful when the shell is a template string.
+ */
+export function islandPlaceholder(name: string, fallbackHtml = ""): string {
+  return `<div ${ISLAND_ATTR}="${escapeAttr(name)}">${fallbackHtml}</div>`;
+}
+
+function escapeAttr(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+/** @internal */
+export function createIslandRoot(app: IslandFactory): {
+  host: HTMLElement;
+  dispose: Dispose;
+} {
+  const host = document.createElement("div");
+  let dispose!: Dispose;
+  createRoot((d) => {
+    dispose = d;
+    const result = app();
+    if (result == null) return;
+    const nodes = Array.isArray(result) ? result : [result];
+    for (const n of nodes) {
+      if (n) host.appendChild(n as Node);
+    }
+  });
+  return { host, dispose };
+}

package/src/registry.ts

@@ -0,0 +1,101 @@
+import type { Dispose } from "@lab206/core";
+import type { IslandFactory, IslandRegistry } from "./islands.js";
+import { hydrateIslands, ISLAND_ATTR } from "./islands.js";
+
+export interface IslandRegistryApi {
+  /** Registered factories */
+  readonly entries: IslandRegistry;
+  /** Register or replace an island factory */
+  register(name: string, factory: IslandFactory): void;
+  /** Register many islands at once */
+  registerAll(map: IslandRegistry): void;
+  /** Hydrate all matching islands in the document (or root) */
+  hydrate(root?: ParentNode): Dispose;
+  /** List island names present under root (DOM) */
+  discover(root?: ParentNode): string[];
+  /** Names registered but not found in the document */
+  missingInDom(root?: ParentNode): string[];
+  /** Island names in the DOM that have no factory */
+  missingInRegistry(root?: ParentNode): string[];
+}
+
+/**
+ * Typed-ish island registry for client entrypoints.
+ *
+ * @example
+ * ```ts
+ * const islands = defineIslands({
+ *   counter: () => Counter(),
+ *   cart: () => CartWidget(),
+ * });
+ *
+ * // after HTML is in the document:
+ * islands.hydrate();
+ * console.log(islands.missingInRegistry()); // unexpected SSR islands
+ * ```
+ */
+export function defineIslands(
+  initial: IslandRegistry = {},
+): IslandRegistryApi {
+  const entries: IslandRegistry = { ...initial };
+
+  function register(name: string, factory: IslandFactory) {
+    entries[name] = factory;
+  }
+
+  function registerAll(map: IslandRegistry) {
+    Object.assign(entries, map);
+  }
+
+  function discover(root: ParentNode = document): string[] {
+    const nodes = root.querySelectorAll?.(`[${ISLAND_ATTR}]`) ?? [];
+    const names: string[] = [];
+    nodes.forEach((n) => {
+      const name = (n as Element).getAttribute(ISLAND_ATTR);
+      if (name) names.push(name);
+    });
+    return names;
+  }
+
+  function missingInDom(root: ParentNode = document): string[] {
+    const present = new Set(discover(root));
+    return Object.keys(entries).filter((k) => !present.has(k));
+  }
+
+  function missingInRegistry(root: ParentNode = document): string[] {
+    return discover(root).filter((name) => !entries[name]);
+  }
+
+  function hydrate(root: ParentNode = document): Dispose {
+    const unknown = missingInRegistry(root);
+    if (unknown.length) {
+      console.warn(
+        `[powers/ssr] DOM islands with no registry entry: ${unknown.join(", ")}`,
+      );
+    }
+    return hydrateIslands(entries, root);
+  }
+
+  return {
+    entries,
+    register,
+    registerAll,
+    hydrate,
+    discover,
+    missingInDom,
+    missingInRegistry,
+  };
+}
+
+/**
+ * Parse island names from an HTML string (no DOM required).
+ */
+export function listIslandsInHtml(html: string): string[] {
+  const re = /data-pu-island=["']([^"']+)["']/g;
+  const names: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(html))) {
+    if (m[1]) names.push(m[1]);
+  }
+  return names;
+}