@tempots/client 0.0.1

package/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,204 @@
+# @tempots/client
+
+Client-side hydration utilities for Tempo applications with SSR support.
+
+## Installation
+
+```bash
+npm install @tempots/client
+# or
+pnpm add @tempots/client
+```
+
+## Features
+
+- **Hydration**: Attach client-side interactivity to server-rendered HTML
+- **Islands Architecture**: Partial hydration with lazy loading strategies
+- **Multiple Hydration Strategies**: immediate, idle, visible, and media query-based
+- **Full Tempo Compatibility**: Works seamlessly with Tempo signals and components
+
+## Usage
+
+### Quick Start with `startClient()`
+
+The simplest way to initialize your client-side application:
+
+```typescript
+// entry-client.ts
+import { startClient } from '@tempots/client'
+import { App, Counter, TodoList } from './app'
+
+startClient({
+  app: () => App(),              // App to render in client-only mode
+  islands: { Counter, TodoList }, // Islands to hydrate
+  debug: true,                    // Optional: enable debug logging
+})
+```
+
+`startClient()` automatically:
+- Detects SSR vs client-only mode
+- Initializes islands with their hydration strategies
+- Sets up HMR cleanup (when available)
+
+### Basic Hydration (Low-Level)
+
+For more control, use the low-level `hydrate()` function:
+
+```typescript
+import { hydrate } from '@tempots/client'
+import { App } from './App'
+
+// Server-rendered HTML is already in the DOM
+const container = document.getElementById('app')!
+
+// Hydrate with client-side interactivity
+const cleanup = hydrate(App(), container)
+
+// Later, to cleanup all event listeners:
+cleanup()
+```
+
+### Islands Architecture
+
+Islands allow you to hydrate only specific interactive components while keeping the rest as static HTML.
+
+#### Server-side: Mark islands
+
+```typescript
+import { html } from '@tempots/dom'
+import {
+  ISLAND_ATTR,
+  ISLAND_OPTIONS_ATTR,
+  ISLAND_HYDRATE_ATTR,
+} from '@tempots/client'
+
+// Or use the islandMarker helper
+import { islandMarker } from '@tempots/client'
+
+const Page = () => html.div(
+  html.h1('Static content - no JS shipped'),
+
+  // This counter will be hydrated as an island
+  html.div(
+    ...islandMarker('Counter', { initial: 10 }, 'visible'),
+    // Server-rendered content
+    html.button('-'),
+    html.span('10'),
+    html.button('+'),
+  ),
+)
+```
+
+#### Client-side: Initialize islands
+
+```typescript
+import { initIslands } from '@tempots/client'
+import { Counter } from './islands/Counter'
+
+// Initialize all islands found in the document
+const cleanup = initIslands({
+  Counter,
+})
+```
+
+### Hydration Strategies
+
+Islands support multiple hydration strategies to optimize loading performance:
+
+```typescript
+// Hydrate immediately when JS loads
+islandMarker('Counter', options, 'immediate')
+
+// Hydrate when browser is idle (requestIdleCallback)
+islandMarker('Counter', options, 'idle')
+
+// Hydrate when scrolled into view (IntersectionObserver)
+islandMarker('Counter', options, 'visible')
+
+// Hydrate when media query matches
+islandMarker('Counter', options, { media: '(min-width: 768px)' })
+```
+
+## API
+
+### `startClient(options)`
+
+High-level function to initialize the Tempo client with automatic SSR detection.
+
+**Options:**
+- `app?: () => Renderable` - App component for client-only rendering
+- `islands: IslandRegistry` - Map of island names to component factories
+- `container?: string | HTMLElement` - Container selector or element (default: `"#app"`)
+- `providers?: Providers` - Providers to inject during hydration
+- `debug?: boolean` - Enable debug logging (default: `false`)
+
+**Returns:** `() => void` - Cleanup function
+
+**Example:**
+```typescript
+startClient({
+  app: () => App(),
+  islands: { Counter, TodoList },
+  container: '#app',
+  debug: true,
+})
+```
+
+### `hydrate(renderable, container, options?)`
+
+Hydrates server-rendered HTML with client-side interactivity.
+
+**Parameters:**
+- `renderable: Renderable` - The Tempo renderable (should match server render)
+- `container: HTMLElement` - Container with server-rendered content
+- `options?: HydrateOptions` - Optional configuration
+
+**Options:**
+- `providers?: Providers` - Providers to inject during hydration
+- `removeMarkers?: boolean` - Remove hydration markers after hydration (default: true)
+
+**Returns:** `() => void` - Cleanup function
+
+### `hydrateIsland(element, component, componentOptions, hydrateOptions?)`
+
+Hydrates a single island element.
+
+**Parameters:**
+- `element: HTMLElement` - The island container element
+- `component: (options: O) => Renderable` - Component factory
+- `componentOptions: O` - Options to pass to the component
+- `hydrateOptions?: IslandHydrateOptions` - Optional configuration
+
+**Returns:** `() => void` - Cleanup function
+
+### `initIslands(registry, options?)`
+
+Scans the document for islands and hydrates them based on their strategy.
+
+**Parameters:**
+- `registry: IslandRegistry` - Map of island names to component factories
+- `options?: IslandHydrateOptions` - Optional configuration
+
+**Returns:** `() => void` - Cleanup function for all islands
+
+### `islandMarker(name, options, strategy?)`
+
+Creates attributes for marking an island during server-side rendering.
+
+**Parameters:**
+- `name: string` - Island name (must match registry key)
+- `options: unknown` - Options to serialize
+- `strategy?: HydrationStrategy` - When to hydrate (default: 'visible')
+
+**Returns:** `Array<{ name: string; value: string }>` - Attribute list
+
+## Constants
+
+- `ISLAND_ATTR` - Attribute name for island markers (`data-tempo-island`)
+- `ISLAND_HYDRATE_ATTR` - Attribute for hydration strategy (`data-tempo-hydrate`)
+- `ISLAND_OPTIONS_ATTR` - Attribute for serialized options (`data-tempo-options`)
+- `HYDRATION_ID_ATTR` - Attribute for hydration IDs (`data-tts-id`)
+
+## License
+
+Apache-2.0

package/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("@tempots/core"),a=require("@tempots/dom");function y(r,e,t={}){const{providers:n={},removeMarkers:i=!0}=t,s=N(e),o=new p.DisposalScope,c=new d(e.ownerDocument,e,void 0,n,s,0),h=p.withScope(o,()=>r.render(c));return i&&g(e),(l=!1)=>{o.dispose(),h(l)}}function N(r){const e=new Map;return r.querySelectorAll(`[${a.HYDRATION_ID_ATTR}]`).forEach(n=>{const i=n.getAttribute(a.HYDRATION_ID_ATTR);i&&e.set(i,n)}),e}function g(r){r.querySelectorAll(`[${a.HYDRATION_ID_ATTR}]`).forEach(t=>{t.removeAttribute(a.HYDRATION_ID_ATTR),t.removeAttribute("data-tts-node")})}class d{constructor(e,t,n,i,s,o){this.document=e,this.element=t,this.reference=n,this.providers=i,this.hydrationMap=s,this.childIndex=o}makeChildElement=(e,t)=>{const n=this.element.children;for(let s=this.childIndex;s<n.length;s++){const o=n[s];if(o.tagName.toLowerCase()===e.toLowerCase())return this.childIndex=s+1,new d(this.document,o,void 0,this.providers,this.hydrationMap,0)}console.warn(`Hydration mismatch: could not find element <${e}> in container`);const i=t!==void 0?this.document.createElementNS(t,e):this.document.createElement(e);return this.appendOrInsert(i),new d(this.document,i,void 0,this.providers,this.hydrationMap,0)};makeChildText=e=>{const t=this.element.childNodes;for(let i=this.childIndex;i<t.length;i++){const s=t[i];if(s.nodeType===Node.TEXT_NODE)return this.childIndex=i+1,s.textContent!==e&&(s.textContent=e),new d(this.document,this.element,s,this.providers,this.hydrationMap,this.childIndex)}const n=this.document.createTextNode(e);return this.appendOrInsert(n),new d(this.document,this.element,n,this.providers,this.hydrationMap,this.childIndex)};setText=e=>{this.reference&&(this.reference.nodeValue=e)};getText=()=>this.reference?.nodeValue??this.element.textContent??"";makeRef=()=>{const e=this.element.childNodes;for(let n=this.childIndex;n<e.length;n++){const i=e[n];if(i.nodeType===Node.TEXT_NODE&&(i.textContent===""||i.textContent===null))return this.childIndex=n+1,new d(this.document,this.element,i,this.providers,this.hydrationMap,this.childIndex)}const t=this.document.createTextNode("");return this.appendOrInsert(t),new d(this.document,this.element,t,this.providers,this.hydrationMap,this.childIndex)};makePortal=e=>{const t=typeof e=="string"?this.document.querySelector(e):e;if(t==null)throw new Error(`Cannot find element by selector for portal: ${e}`);return new d(this.document,t,void 0,this.providers,this.hydrationMap,0)};appendOrInsert=e=>{this.reference===void 0?this.element.appendChild(e):this.element.insertBefore(e,this.reference)};setProvider=(e,t,n)=>new d(this.document,this.element,this.reference,{...this.providers,[e]:[t,n]},this.hydrationMap,this.childIndex);getProvider=e=>{if(this.providers[e]===void 0)throw new Error(`Provider not found: ${String(e)}`);const[t,n]=this.providers[e];return{value:t,onUse:n}};clear=e=>{e&&(this.reference!==void 0?this.reference.parentNode?.removeChild(this.reference):this.element.parentNode?.removeChild(this.element))};addClasses=e=>{this.element.classList.add(...e)};removeClasses=e=>{this.element.classList.remove(...e)};getClasses=()=>Array.from(this.element.classList);on=(e,t,n)=>{const i=s=>t(s,this);return this.element.addEventListener(e,i,n),s=>{s&&this.element.removeEventListener(e,i,n)}};isBrowserDOM=()=>!1;isBrowser=()=>!0;isHeadlessDOM=()=>!1;isHeadless=()=>!1;setStyle=(e,t)=>{this.element.style[e]=t};getStyle=e=>this.element.style[e];makeAccessors=e=>{const t=this.element;return{get:()=>t[e],set:n=>{t[e]=n}}}}const u="data-tempo-island",I="data-tempo-hydrate",A="data-tempo-options";function S(r,e,t,n={}){r.innerHTML="";const i=new a.BrowserContext(r.ownerDocument,r,void 0,n.providers??{}),s=new p.DisposalScope,o=p.withScope(s,()=>e(t).render(i));return(c=!1)=>{s.dispose(),o(c)}}function D(r,e,t){if(e==="immediate")return t(),()=>{};if(e==="idle")if("requestIdleCallback"in window){const n=requestIdleCallback(t);return()=>cancelIdleCallback(n)}else{const n=setTimeout(t,1);return()=>clearTimeout(n)}if(e==="visible"){const n=new IntersectionObserver(i=>{for(const s of i)if(s.isIntersecting){n.disconnect(),t();break}},{rootMargin:"50px"});return n.observe(r),()=>n.disconnect()}if(typeof e=="object"&&"media"in e){const n=window.matchMedia(e.media);if(n.matches)return t(),()=>{};const i=s=>{s.matches&&(n.removeEventListener("change",i),t())};return n.addEventListener("change",i),()=>n.removeEventListener("change",i)}return t(),()=>{}}function O(r){return!r||r==="immediate"||r==="load"?"immediate":r==="idle"?"idle":r==="visible"?"visible":r.startsWith("media:")?{media:r.slice(6).trim()}:"immediate"}function v(r,e={}){const t=[];return document.querySelectorAll(`[${u}]`).forEach(i=>{const s=i,o=s.getAttribute(u);if(!o){console.warn("[Tempo Islands] Element missing island name:",s);return}const c=r[o];if(!c){console.warn(`[Tempo Islands] Component "${o}" not found in registry`);return}const h=s.getAttribute(A);let l={};if(h)try{l=JSON.parse(h)}catch(f){console.warn(`[Tempo Islands] Failed to parse options for "${o}":`,f)}const m=s.getAttribute(I),T=O(m),w=D(s,T,()=>{const f=S(s,c,l,e);t.push(f),s.removeAttribute(u),s.removeAttribute(I),s.removeAttribute(A)});t.push(w)}),()=>{t.forEach(i=>i())}}function R(r,e={},t="visible"){const n=typeof t=="object"?`media:${t.media}`:t;return[{name:u,value:r},{name:A,value:JSON.stringify(e)},{name:I,value:n}]}function b(r){const{app:e,islands:t,container:n="#app",providers:i={},debug:s=!1}=r,o=s?m=>console.log(`[Tempo] ${m}`):()=>{},c=typeof n=="string"?document.querySelector(n):n;if(!c)return console.error(`[Tempo] Could not find container: ${typeof n=="string"?n:"(element)"}`),()=>{};const h=c.querySelector(`[${u}]`)!==null;let l;if(h)o("SSR mode: Initializing islands..."),l=v(t,{providers:i}),o("Islands initialized! Static content stays static.");else if(e){o("Client-only mode: Rendering app...");const m=new a.BrowserContext(document,c,void 0,i),T=new p.DisposalScope,w=p.withScope(T,()=>e().render(m)),f=v(t,{providers:i});l=()=>{f(),T.dispose(),w(!0)},o("App rendered and islands initialized!")}else o("No SSR content detected, initializing islands only..."),l=v(t,{providers:i});return l}Object.defineProperty(exports,"HYDRATION_ID_ATTR",{enumerable:!0,get:()=>a.HYDRATION_ID_ATTR});exports.HydrationContext=d;exports.ISLAND_ATTR=u;exports.ISLAND_HYDRATE_ATTR=I;exports.ISLAND_OPTIONS_ATTR=A;exports.hydrate=y;exports.hydrateIsland=S;exports.initIslands=v;exports.islandMarker=R;exports.startClient=b;

package/index.d.ts

@@ -0,0 +1,308 @@
+import { Renderable, Providers, ProviderMark, Clear, BrowserContext, DOMContext, HYDRATION_ID_ATTR, HeadlessContext } from '@tempots/dom';
+/**
+ * Options for client-side hydration.
+ * @public
+ */
+export interface HydrateOptions {
+    /**
+     * Providers to inject during hydration.
+     */
+    providers?: Providers;
+    /**
+     * Whether to remove hydration markers after hydration completes.
+     * Defaults to true.
+     */
+    removeMarkers?: boolean;
+}
+/**
+ * Hydrates server-rendered HTML with client-side interactivity.
+ *
+ * This function takes a server-rendered container and attaches event handlers
+ * and reactive updates to the existing DOM nodes without re-creating them.
+ *
+ * @example
+ * ```typescript
+ * import { hydrate } from '@tempots/client'
+ * import { App } from './App'
+ *
+ * // Server-rendered HTML is already in the DOM
+ * // Hydrate it with client-side interactivity
+ * const cleanup = hydrate(App(), document.getElementById('app')!)
+ *
+ * // Later, to remove all event listeners:
+ * cleanup()
+ * ```
+ *
+ * @param renderable - The Renderable to hydrate with (should match server render).
+ * @param container - The container element with server-rendered content.
+ * @param options - Hydration options.
+ * @returns A cleanup function that removes all event listeners and disposes signals.
+ * @public
+ */
+export declare function hydrate(renderable: Renderable, container: HTMLElement, options?: HydrateOptions): () => void;
+/**
+ * A DOMContext implementation for hydration that reuses existing DOM nodes.
+ *
+ * During hydration, instead of creating new DOM elements, this context
+ * finds and reuses existing elements that were rendered on the server.
+ * Event handlers are attached to the existing elements.
+ *
+ * @public
+ */
+export declare class HydrationContext implements DOMContext {
+    readonly document: Document;
+    readonly element: HTMLElement;
+    readonly reference: Node | undefined;
+    readonly providers: Providers;
+    private readonly hydrationMap;
+    private childIndex;
+    constructor(document: Document, element: HTMLElement, reference: Node | undefined, providers: Providers, hydrationMap: Map<string, HTMLElement>, childIndex: number);
+    /**
+     * Finds the next child element instead of creating a new one.
+     * Falls back to creating a new element if hydration fails.
+     */
+    readonly makeChildElement: (tagName: string, namespace: string | undefined) => DOMContext;
+    /**
+     * Finds the next text node instead of creating a new one.
+     */
+    readonly makeChildText: (text: string) => DOMContext;
+    readonly setText: (text: string) => void;
+    readonly getText: () => string;
+    readonly makeRef: () => DOMContext;
+    readonly makePortal: (selector: string | HTMLElement) => DOMContext;
+    private readonly appendOrInsert;
+    readonly setProvider: <T>(mark: ProviderMark<T>, value: T, onUse: undefined | (() => void)) => DOMContext;
+    readonly getProvider: <T>(mark: ProviderMark<T>) => {
+        value: T;
+        onUse: (() => void) | undefined;
+    };
+    readonly clear: (removeTree: boolean) => void;
+    readonly addClasses: (tokens: string[]) => void;
+    readonly removeClasses: (tokens: string[]) => void;
+    readonly getClasses: () => string[];
+    readonly on: <E>(event: string, listener: (event: E, ctx: HydrationContext) => void, options?: AddEventListenerOptions) => Clear;
+    readonly isBrowserDOM: () => this is BrowserContext;
+    readonly isBrowser: () => this is BrowserContext;
+    readonly isHeadlessDOM: () => this is HeadlessContext;
+    readonly isHeadless: () => this is HeadlessContext;
+    readonly setStyle: (name: string, value: string) => void;
+    readonly getStyle: (name: string) => string;
+    readonly makeAccessors: (name: string) => {
+        get(): unknown;
+        set(value: unknown): void;
+    };
+}
+/**
+ * Attribute name for island markers.
+ * @public
+ */
+export declare const ISLAND_ATTR = "data-tempo-island";
+/**
+ * Attribute name for island hydration strategy.
+ * @public
+ */
+export declare const ISLAND_HYDRATE_ATTR = "data-tempo-hydrate";
+/**
+ * Attribute name for serialized island options.
+ * @public
+ */
+export declare const ISLAND_OPTIONS_ATTR = "data-tempo-options";
+/**
+ * Hydration strategy for islands.
+ *
+ * - `"immediate"` - Hydrate as soon as possible (client:load)
+ * - `"idle"` - Hydrate when the browser is idle (client:idle)
+ * - `"visible"` - Hydrate when scrolled into view (client:visible)
+ * - `"media"` - Hydrate when a media query matches
+ *
+ * @public
+ */
+export type HydrationStrategy = "immediate" | "idle" | "visible" | {
+    media: string;
+};
+/**
+ * Options for island hydration.
+ * @public
+ */
+export interface IslandHydrateOptions {
+    /**
+     * Providers to inject during hydration.
+     */
+    providers?: Providers;
+}
+/**
+ * Island component factory type.
+ * Options are received from JSON deserialization and typed as `unknown`.
+ * Components should cast options to their expected type internally.
+ *
+ * @example
+ * ```typescript
+ * interface CounterOptions { initial?: number }
+ *
+ * const Counter: IslandComponent = (options) => {
+ *   const { initial = 0 } = (options ?? {}) as CounterOptions;
+ *   return html.div(/* ... *\/)
+ * }
+ * ```
+ * @public
+ */
+export type IslandComponent = (options: unknown) => Renderable;
+/**
+ * Island component registry type.
+ * Maps island names to their component factories.
+ * @public
+ */
+export type IslandRegistry = Record<string, IslandComponent>;
+/**
+ * Hydrates a single island element with the given component.
+ *
+ * Unlike full hydration, islands are re-rendered fresh on the client.
+ * The server-rendered HTML is replaced with the interactive component.
+ * This is simpler and more reliable than trying to match existing DOM.
+ *
+ * @example
+ * ```typescript
+ * import { hydrateIsland } from '@tempots/client'
+ * import { Counter } from './islands/Counter'
+ *
+ * const element = document.querySelector('[data-tempo-island="Counter"]')
+ * const options = JSON.parse(element.dataset.tempoProps || '{}')
+ *
+ * hydrateIsland(element, Counter, options)
+ * ```
+ *
+ * @param element - The island container element.
+ * @param component - The component factory function.
+ * @param componentOptions - Options to pass to the component.
+ * @param hydrateOptions - Hydration options.
+ * @returns A cleanup function.
+ * @public
+ */
+export declare function hydrateIsland<O>(element: HTMLElement, component: (options: O) => Renderable, componentOptions: O, hydrateOptions?: IslandHydrateOptions): () => void;
+/**
+ * Initializes all islands in the document using the provided registry.
+ *
+ * This function scans the document for elements with `data-tempo-island` attributes
+ * and hydrates them using the corresponding component from the registry.
+ *
+ * @example
+ * ```typescript
+ * import { initIslands } from '@tempots/client'
+ * import { Counter } from './islands/Counter'
+ * import { TodoList } from './islands/TodoList'
+ *
+ * // Initialize all islands
+ * const cleanup = initIslands({
+ *   Counter,
+ *   TodoList,
+ * })
+ *
+ * // Later, to cleanup all islands:
+ * cleanup()
+ * ```
+ *
+ * @param registry - A map of island names to component factories.
+ * @param options - Hydration options.
+ * @returns A cleanup function that disposes all islands.
+ * @public
+ */
+export declare function initIslands(registry: IslandRegistry, options?: IslandHydrateOptions): () => void;
+/**
+ * Creates an island marker for server-side rendering.
+ *
+ * This function returns attributes that should be added to the island's
+ * root element during SSR to enable client-side hydration.
+ *
+ * @example
+ * ```typescript
+ * // In your SSR template
+ * const Counter = (options: CounterOptions) => {
+ *   return html.div(
+ *     ...islandMarker('Counter', options, 'visible'),
+ *     // ... counter implementation
+ *   )
+ * }
+ * ```
+ *
+ * @param name - The island component name (must match registry key).
+ * @param options - Options to serialize for client-side hydration.
+ * @param strategy - When to hydrate the island.
+ * @returns An array of attribute setters for the island element.
+ * @public
+ */
+export declare function islandMarker(name: string, options?: unknown, strategy?: HydrationStrategy): Array<{
+    name: string;
+    value: string;
+}>;
+/**
+ * Options for the startClient function.
+ * @public
+ */
+export interface ClientOptions<R extends IslandRegistry> {
+    /**
+     * App component for client-only rendering.
+     * If provided and no SSR content is detected, this will be rendered.
+     */
+    app?: () => Renderable;
+    /**
+     * Island component registry.
+     * Maps island names to their component factories.
+     */
+    islands: R;
+    /**
+     * Container selector or element.
+     * @default "#app"
+     */
+    container?: string | HTMLElement;
+    /**
+     * Providers to inject during hydration.
+     */
+    providers?: Providers;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Initializes the Tempo client with automatic SSR detection.
+ *
+ * This is a high-level convenience function that handles:
+ * - Container detection
+ * - SSR vs client-only mode detection
+ * - Island initialization
+ * - HMR cleanup (when available)
+ *
+ * For more control, use the lower-level `initIslands()` and `hydrateIsland()` functions directly.
+ *
+ * @example
+ * ```typescript
+ * // Minimal usage - islands only
+ * import { startClient } from '@tempots/client'
+ * import { Counter, TodoList } from './islands'
+ *
+ * startClient({
+ *   islands: { Counter, TodoList }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With client-only fallback
+ * import { startClient } from '@tempots/client'
+ * import { App, Counter } from './app'
+ *
+ * startClient({
+ *   app: () => App(),
+ *   islands: { Counter },
+ *   debug: true
+ * })
+ * ```
+ *
+ * @param options - Client configuration options.
+ * @returns A cleanup function that disposes all islands and removes event listeners.
+ * @public
+ */
+export declare function startClient<R extends IslandRegistry>(options: ClientOptions<R>): () => void;
+export type { Renderable, Providers };
+export { HYDRATION_ID_ATTR };

package/index.js

@@ -0,0 +1,327 @@
+import { DisposalScope as S, withScope as y } from "@tempots/core";
+import { HYDRATION_ID_ATTR as f, BrowserContext as g } from "@tempots/dom";
+import { HYDRATION_ID_ATTR as q } from "@tempots/dom";
+function D(r, e, t = {}) {
+  const { providers: n = {}, removeMarkers: i = !0 } = t, s = A(e), o = new S(), d = new c(
+    e.ownerDocument,
+    e,
+    void 0,
+    n,
+    s,
+    0
+  ), h = y(o, () => r.render(d));
+  return i && N(e), (l = !1) => {
+    o.dispose(), h(l);
+  };
+}
+function A(r) {
+  const e = /* @__PURE__ */ new Map();
+  return r.querySelectorAll(`[${f}]`).forEach((n) => {
+    const i = n.getAttribute(f);
+    i && e.set(i, n);
+  }), e;
+}
+function N(r) {
+  r.querySelectorAll(`[${f}]`).forEach((t) => {
+    t.removeAttribute(f), t.removeAttribute("data-tts-node");
+  });
+}
+class c {
+  constructor(e, t, n, i, s, o) {
+    this.document = e, this.element = t, this.reference = n, this.providers = i, this.hydrationMap = s, this.childIndex = o;
+  }
+  /**
+   * Finds the next child element instead of creating a new one.
+   * Falls back to creating a new element if hydration fails.
+   */
+  makeChildElement = (e, t) => {
+    const n = this.element.children;
+    for (let s = this.childIndex; s < n.length; s++) {
+      const o = n[s];
+      if (o.tagName.toLowerCase() === e.toLowerCase())
+        return this.childIndex = s + 1, new c(
+          this.document,
+          o,
+          void 0,
+          this.providers,
+          this.hydrationMap,
+          0
+        );
+    }
+    console.warn(
+      `Hydration mismatch: could not find element <${e}> in container`
+    );
+    const i = t !== void 0 ? this.document.createElementNS(t, e) : this.document.createElement(e);
+    return this.appendOrInsert(i), new c(
+      this.document,
+      i,
+      void 0,
+      this.providers,
+      this.hydrationMap,
+      0
+    );
+  };
+  /**
+   * Finds the next text node instead of creating a new one.
+   */
+  makeChildText = (e) => {
+    const t = this.element.childNodes;
+    for (let i = this.childIndex; i < t.length; i++) {
+      const s = t[i];
+      if (s.nodeType === Node.TEXT_NODE)
+        return this.childIndex = i + 1, s.textContent !== e && (s.textContent = e), new c(
+          this.document,
+          this.element,
+          s,
+          this.providers,
+          this.hydrationMap,
+          this.childIndex
+        );
+    }
+    const n = this.document.createTextNode(e);
+    return this.appendOrInsert(n), new c(
+      this.document,
+      this.element,
+      n,
+      this.providers,
+      this.hydrationMap,
+      this.childIndex
+    );
+  };
+  setText = (e) => {
+    this.reference && (this.reference.nodeValue = e);
+  };
+  getText = () => this.reference?.nodeValue ?? this.element.textContent ?? "";
+  makeRef = () => {
+    const e = this.element.childNodes;
+    for (let n = this.childIndex; n < e.length; n++) {
+      const i = e[n];
+      if (i.nodeType === Node.TEXT_NODE && (i.textContent === "" || i.textContent === null))
+        return this.childIndex = n + 1, new c(
+          this.document,
+          this.element,
+          i,
+          this.providers,
+          this.hydrationMap,
+          this.childIndex
+        );
+    }
+    const t = this.document.createTextNode("");
+    return this.appendOrInsert(t), new c(
+      this.document,
+      this.element,
+      t,
+      this.providers,
+      this.hydrationMap,
+      this.childIndex
+    );
+  };
+  makePortal = (e) => {
+    const t = typeof e == "string" ? this.document.querySelector(e) : e;
+    if (t == null)
+      throw new Error(
+        `Cannot find element by selector for portal: ${e}`
+      );
+    return new c(
+      this.document,
+      t,
+      void 0,
+      this.providers,
+      this.hydrationMap,
+      0
+    );
+  };
+  appendOrInsert = (e) => {
+    this.reference === void 0 ? this.element.appendChild(e) : this.element.insertBefore(e, this.reference);
+  };
+  setProvider = (e, t, n) => new c(
+    this.document,
+    this.element,
+    this.reference,
+    { ...this.providers, [e]: [t, n] },
+    this.hydrationMap,
+    this.childIndex
+  );
+  getProvider = (e) => {
+    if (this.providers[e] === void 0)
+      throw new Error(`Provider not found: ${String(e)}`);
+    const [t, n] = this.providers[e];
+    return { value: t, onUse: n };
+  };
+  clear = (e) => {
+    e && (this.reference !== void 0 ? this.reference.parentNode?.removeChild(this.reference) : this.element.parentNode?.removeChild(this.element));
+  };
+  addClasses = (e) => {
+    this.element.classList.add(...e);
+  };
+  removeClasses = (e) => {
+    this.element.classList.remove(...e);
+  };
+  getClasses = () => Array.from(this.element.classList);
+  on = (e, t, n) => {
+    const i = (s) => t(s, this);
+    return this.element.addEventListener(e, i, n), (s) => {
+      s && this.element.removeEventListener(e, i, n);
+    };
+  };
+  // HydrationContext runs in a browser environment, so isBrowser() returns true
+  // to ensure browser-specific code paths (like Location provider) work correctly.
+  // Note: isBrowserDOM returns false since this is not a BrowserContext instance.
+  isBrowserDOM = () => !1;
+  isBrowser = () => !0;
+  isHeadlessDOM = () => !1;
+  isHeadless = () => !1;
+  setStyle = (e, t) => {
+    this.element.style[e] = t;
+  };
+  getStyle = (e) => this.element.style[e];
+  makeAccessors = (e) => {
+    const t = this.element;
+    return {
+      get: () => t[e],
+      set: (n) => {
+        t[e] = n;
+      }
+    };
+  };
+}
+const u = "data-tempo-island", I = "data-tempo-hydrate", T = "data-tempo-options";
+function x(r, e, t, n = {}) {
+  r.innerHTML = "";
+  const i = new g(
+    r.ownerDocument,
+    r,
+    void 0,
+    n.providers ?? {}
+  ), s = new S(), o = y(s, () => e(t).render(i));
+  return (d = !1) => {
+    s.dispose(), o(d);
+  };
+}
+function E(r, e, t) {
+  if (e === "immediate")
+    return t(), () => {
+    };
+  if (e === "idle")
+    if ("requestIdleCallback" in window) {
+      const n = requestIdleCallback(t);
+      return () => cancelIdleCallback(n);
+    } else {
+      const n = setTimeout(t, 1);
+      return () => clearTimeout(n);
+    }
+  if (e === "visible") {
+    const n = new IntersectionObserver(
+      (i) => {
+        for (const s of i)
+          if (s.isIntersecting) {
+            n.disconnect(), t();
+            break;
+          }
+      },
+      { rootMargin: "50px" }
+    );
+    return n.observe(r), () => n.disconnect();
+  }
+  if (typeof e == "object" && "media" in e) {
+    const n = window.matchMedia(e.media);
+    if (n.matches)
+      return t(), () => {
+      };
+    const i = (s) => {
+      s.matches && (n.removeEventListener("change", i), t());
+    };
+    return n.addEventListener("change", i), () => n.removeEventListener("change", i);
+  }
+  return t(), () => {
+  };
+}
+function M(r) {
+  return !r || r === "immediate" || r === "load" ? "immediate" : r === "idle" ? "idle" : r === "visible" ? "visible" : r.startsWith("media:") ? { media: r.slice(6).trim() } : "immediate";
+}
+function w(r, e = {}) {
+  const t = [];
+  return document.querySelectorAll(`[${u}]`).forEach((i) => {
+    const s = i, o = s.getAttribute(u);
+    if (!o) {
+      console.warn("[Tempo Islands] Element missing island name:", s);
+      return;
+    }
+    const d = r[o];
+    if (!d) {
+      console.warn(
+        `[Tempo Islands] Component "${o}" not found in registry`
+      );
+      return;
+    }
+    const h = s.getAttribute(T);
+    let l = {};
+    if (h)
+      try {
+        l = JSON.parse(h);
+      } catch (m) {
+        console.warn(
+          `[Tempo Islands] Failed to parse options for "${o}":`,
+          m
+        );
+      }
+    const a = s.getAttribute(I), p = M(a), v = E(s, p, () => {
+      const m = x(
+        s,
+        d,
+        l,
+        e
+      );
+      t.push(m), s.removeAttribute(u), s.removeAttribute(I), s.removeAttribute(T);
+    });
+    t.push(v);
+  }), () => {
+    t.forEach((i) => i());
+  };
+}
+function L(r, e = {}, t = "visible") {
+  const n = typeof t == "object" ? `media:${t.media}` : t;
+  return [
+    { name: u, value: r },
+    { name: T, value: JSON.stringify(e) },
+    { name: I, value: n }
+  ];
+}
+function C(r) {
+  const {
+    app: e,
+    islands: t,
+    container: n = "#app",
+    providers: i = {},
+    debug: s = !1
+  } = r, o = s ? (a) => console.log(`[Tempo] ${a}`) : () => {
+  }, d = typeof n == "string" ? document.querySelector(n) : n;
+  if (!d)
+    return console.error(`[Tempo] Could not find container: ${typeof n == "string" ? n : "(element)"}`), () => {
+    };
+  const h = d.querySelector(`[${u}]`) !== null;
+  let l;
+  if (h)
+    o("SSR mode: Initializing islands..."), l = w(t, { providers: i }), o("Islands initialized! Static content stays static.");
+  else if (e) {
+    o("Client-only mode: Rendering app...");
+    const a = new g(document, d, void 0, i), p = new S(), v = y(p, () => e().render(a)), m = w(t, { providers: i });
+    l = () => {
+      m(), p.dispose(), v(!0);
+    }, o("App rendered and islands initialized!");
+  } else
+    o("No SSR content detected, initializing islands only..."), l = w(t, { providers: i });
+  return l;
+}
+export {
+  q as HYDRATION_ID_ATTR,
+  c as HydrationContext,
+  u as ISLAND_ATTR,
+  I as ISLAND_HYDRATE_ATTR,
+  T as ISLAND_OPTIONS_ATTR,
+  D as hydrate,
+  x as hydrateIsland,
+  w as initIslands,
+  L as islandMarker,
+  C as startClient
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@tempots/client",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
+  },
+  "license": "Apache-2.0",
+  "description": "Client-side hydration utilities for Tempo SSR applications",
+  "keywords": [
+    "tempo",
+    "tempots",
+    "hydration",
+    "client",
+    "ssr"
+  ],
+  "homepage": "https://github.com/fponticelli/tempots",
+  "bugs": {
+    "url": "https://github.com/fponticelli/tempots/issues"
+  },
+  "author": {
+    "name": "Franco Ponticelli",
+    "email": "franco.ponticelli@gmail.com",
+    "url": "https://github.com/fponticelli"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fponticelli/tempots.git"
+  },
+  "peerDependencies": {
+    "@tempots/core": "^2.1.0",
+    "@tempots/dom": "^36.0.0"
+  }
+}