@fluixi/core 1.0.0-alpha.100

package/dist/src/lib/server/hydration.cjs

@@ -0,0 +1,169 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/server/hydration.ts
+var hydration_exports = {};
+__export(hydration_exports, {
+  cleanupHydration: () => cleanupHydration,
+  clearHydrationData: () => clearHydrationData,
+  clearHydrationDataKey: () => clearHydrationDataKey,
+  createHydratableResource: () => createHydratableResource,
+  deserializeHydrationData: () => deserializeHydrationData,
+  generateMarkerID: () => generateMarkerID,
+  getHydrationData: () => getHydrationData,
+  hasHydrationData: () => hasHydrationData,
+  hydrationMarker: () => hydrationMarker,
+  hydrationMarkerEnd: () => hydrationMarkerEnd,
+  hydrationMarkerStart: () => hydrationMarkerStart,
+  isClientEnvironment: () => isClientEnvironment,
+  isHydrating: () => isHydrating,
+  isServerEnvironment: () => isServerEnvironment,
+  serializeHydrationData: () => serializeHydrationData,
+  setHydrating: () => setHydrating,
+  setHydrationData: () => setHydrationData,
+  useHydrationData: () => useHydrationData
+});
+module.exports = __toCommonJS(hydration_exports);
+var import_dom = require("@fluixi/dom");
+var hydrating = false;
+var hydrationDataMap = /* @__PURE__ */ new Map();
+var markerCounter = 0;
+function isHydrating() {
+  return hydrating;
+}
+function setHydrating(state) {
+  hydrating = state;
+}
+function setHydrationData(key, data) {
+  hydrationDataMap.set(key, data);
+}
+function getHydrationData(key) {
+  return hydrationDataMap.get(key);
+}
+function hasHydrationData(key) {
+  return hydrationDataMap.has(key);
+}
+function clearHydrationData() {
+  hydrationDataMap.clear();
+}
+function clearHydrationDataKey(key) {
+  hydrationDataMap.delete(key);
+}
+function serializeHydrationData() {
+  if (hydrationDataMap.size === 0) {
+    return "";
+  }
+  const data = Object.fromEntries(hydrationDataMap);
+  const json = JSON.stringify(data);
+  return `<script type="application/json" id="__FLUIXI_HYDRATION__">${json}<\/script>`;
+}
+function deserializeHydrationData() {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  const script = document.getElementById("__FLUIXI_HYDRATION__");
+  if (!script || script.getAttribute("type") !== "application/json") {
+    return false;
+  }
+  try {
+    const json = script.textContent || "{}";
+    const data = JSON.parse(json);
+    for (const [key, value] of Object.entries(data)) {
+      hydrationDataMap.set(key, value);
+    }
+    return true;
+  } catch (error) {
+    console.error("Failed to deserialize hydration data:", error);
+    return false;
+  }
+}
+function generateMarkerID() {
+  return `h${markerCounter++}`;
+}
+function hydrationMarker(id) {
+  return `<!--#${id}-->`;
+}
+function hydrationMarkerStart(id) {
+  return `<!--#${id}-->`;
+}
+function hydrationMarkerEnd(id) {
+  return `<!--/${id}-->`;
+}
+function createHydratableResource(key, fetcher) {
+  return async () => {
+    if (isHydrating() || typeof window !== "undefined") {
+      const cached = getHydrationData(key);
+      if (cached !== void 0) {
+        return cached;
+      }
+    }
+    const data = await fetcher();
+    if (typeof window === "undefined") {
+      setHydrationData(key, data);
+    }
+    return data;
+  };
+}
+function useHydrationData(key, value) {
+  const hydrationData = getHydrationData(key);
+  if (hydrationData !== void 0) {
+    return hydrationData;
+  }
+  const computedValue = typeof value === "function" ? value() : value;
+  if (typeof window === "undefined") {
+    setHydrationData(key, computedValue);
+  }
+  return computedValue;
+}
+function cleanupHydration() {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const script = document.getElementById("__FLUIXI_HYDRATION__");
+  if (script) {
+    script.remove();
+  }
+  const walker = document.createTreeWalker(
+    document.body,
+    NodeFilter.SHOW_COMMENT,
+    null
+  );
+  const comments = [];
+  let node;
+  while (node = walker.nextNode()) {
+    const comment = node;
+    const text = comment.nodeValue || "";
+    if (text.startsWith("#") || text.startsWith("/")) {
+      comments.push(comment);
+    }
+  }
+  comments.forEach((comment) => comment.remove());
+  clearHydrationData();
+}
+if (typeof window !== "undefined") {
+  window.addEventListener("load", () => {
+    setTimeout(cleanupHydration, 100);
+  });
+}
+function isServerEnvironment() {
+  return (0, import_dom.isServer)();
+}
+function isClientEnvironment() {
+  return !(0, import_dom.isServer)();
+}

package/dist/src/lib/server/hydration.d.ts

@@ -0,0 +1,198 @@
+/**
+ * @module @fluixi/core/server/hydration
+ *
+ * Hydration:
+ * - DOM reused (no recreation)
+ * - No component execution (components ran on server)
+ * - Bindings reattached
+ * - Structural markers required
+ */
+/**
+ * Hydration data structure
+ */
+export interface HydrationData {
+    [key: string]: any;
+}
+/**
+ * Check if currently hydrating
+ *
+ * During hydration, DOM is reused, not recreated
+ *
+ * @example
+ * ```typescript
+ * import { isHydrating } from '@fluixi/core/server';
+ *
+ * if (isHydrating()) {
+ *   // Reuse existing DOM
+ * }
+ * ```
+ */
+export declare function isHydrating(): boolean;
+/**
+ * Set hydration state
+ *
+ * @internal
+ */
+export declare function setHydrating(state: boolean): void;
+/**
+ * Store data for hydration
+ *
+ * On server, store data to serialize into HTML
+ * On client during hydration, this data is reused
+ *
+ * @example
+ * ```typescript
+ * import { setHydrationData } from '@fluixi/core/server';
+ *
+ * // On server
+ * setHydrationData('user', { id: 1, name: 'Alice' });
+ * ```
+ */
+export declare function setHydrationData(key: string, data: any): void;
+/**
+ * Get hydration data
+ *
+ * On client, retrieve data stored on server
+ *
+ * @example
+ * ```typescript
+ * import { getHydrationData } from '@fluixi/core/server';
+ *
+ * // On client
+ * const user = getHydrationData('user');
+ * ```
+ */
+export declare function getHydrationData(key: string): any;
+/**
+ * Check if hydration data exists
+ */
+export declare function hasHydrationData(key: string): boolean;
+/**
+ * Clear all hydration data
+ *
+ * @internal
+ */
+export declare function clearHydrationData(): void;
+/**
+ * Clear specific hydration data
+ */
+export declare function clearHydrationDataKey(key: string): void;
+/**
+ * Serialize hydration data to script tag
+ *
+ * Embed data in HTML for client hydration
+ *
+ * @example
+ * ```typescript
+ * import { serializeHydrationData } from '@fluixi/core/server';
+ *
+ * const html = await renderToString(() => App());
+ * const script = serializeHydrationData();
+ * return html + script;
+ * ```
+ */
+export declare function serializeHydrationData(): string;
+/**
+ * Deserialize hydration data from DOM
+ *
+ * On client, load data from script tag
+ *
+ * @example
+ * ```typescript
+ * import { deserializeHydrationData } from '@fluixi/core/server';
+ *
+ * // On client startup
+ * if (deserializeHydrationData()) {
+ *   console.log('Hydration data loaded');
+ * }
+ * ```
+ */
+export declare function deserializeHydrationData(): boolean;
+/**
+ * Generate unique hydration marker ID
+ *
+ * @internal
+ */
+export declare function generateMarkerID(): string;
+/**
+ * Create hydration marker
+ *
+ * Structural markers required for hydration points
+ *
+ * @example
+ * ```typescript
+ * import { hydrationMarker } from '@fluixi/core/server';
+ *
+ * const marker = hydrationMarker('component-1');
+ * // Returns: <!--h:component-1-->
+ * ```
+ */
+export declare function hydrationMarker(id: string): string;
+/**
+ * Create start hydration marker
+ */
+export declare function hydrationMarkerStart(id: string): string;
+/**
+ * Create end hydration marker
+ */
+export declare function hydrationMarkerEnd(id: string): string;
+/**
+ * Create hydration-friendly resource
+ *
+ * Resources loaded on server are serialized
+ * On client, reused during hydration (no re-fetch)
+ *
+ * @example
+ * ```typescript
+ * import { createHydratableResource } from '@fluixi/core/server';
+ *
+ * const loadUser = createHydratableResource('user', async () => {
+ *   const res = await fetch('/api/user');
+ *   return res.json();
+ * });
+ * ```
+ */
+export declare function createHydratableResource<T>(key: string, fetcher: () => Promise<T>): () => Promise<T>;
+/**
+ * Use hydration data in component
+ *
+ * Components use hydration data to restore state
+ * without re-execution
+ *
+ * @example
+ * ```typescript
+ * import { useHydrationData } from '@fluixi/core/server';
+ *
+ * const MyComponent = () => {
+ *   const data = useHydrationData('my-data', { initial: true });
+ *   return html`<div>${JSON.stringify(data)}</div>`;
+ * };
+ * ```
+ */
+export declare function useHydrationData<T>(key: string, value: T | (() => T)): T;
+/**
+ * Cleanup hydration artifacts from DOM
+ *
+ * After hydration, remove markers and serialized data
+ *
+ * @example
+ * ```typescript
+ * import { cleanupHydration } from '@fluixi/core/server';
+ *
+ * // After hydration completes
+ * cleanupHydration();
+ * ```
+ */
+export declare function cleanupHydration(): void;
+/**
+ * Whether this is a server render.
+ *
+ * Defers to `@fluixi/dom`, which keeps the flag on a realm singleton that
+ * `renderToString` sets. A local `typeof window` test disagrees with it inside a jsdom
+ * process, which is where server rendering is usually tested, and `router/data.ts`
+ * branches on this to decide whether a loader may touch the client.
+ */
+export declare function isServerEnvironment(): boolean;
+/** Whether this is running in a browser, the negation of a server render. */
+export declare function isClientEnvironment(): boolean;
+//# sourceMappingURL=hydration.d.ts.map

package/dist/src/lib/server/hydration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/hydration.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AA2BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEjD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAEjD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEvD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAuBlD;AAMD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAErD;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,MAAM,OAAO,CAAC,CAAC,CAAC,CAoBlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAiBxE;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAiCvC;AAgBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}

package/dist/src/lib/server/hydration.js

@@ -0,0 +1,345 @@
+/**
+ * @module @fluixi/core/server/hydration
+ *
+ * Hydration:
+ * - DOM reused (no recreation)
+ * - No component execution (components ran on server)
+ * - Bindings reattached
+ * - Structural markers required
+ */
+import { isServer as domIsServer } from '@fluixi/dom';
+// ============================================================================
+// STATE
+// ============================================================================
+/**
+ * Global hydration flag
+ * Indicates if we're currently hydrating
+ */
+let hydrating = false;
+/**
+ * Hydration data registry
+ * Stores data serialized on server and consumed on client
+ */
+const hydrationDataMap = new Map();
+/**
+ * Hydration marker counter for unique IDs
+ */
+let markerCounter = 0;
+// ============================================================================
+// HYDRATION STATE
+// ============================================================================
+/**
+ * Check if currently hydrating
+ *
+ * During hydration, DOM is reused, not recreated
+ *
+ * @example
+ * ```typescript
+ * import { isHydrating } from '@fluixi/core/server';
+ *
+ * if (isHydrating()) {
+ *   // Reuse existing DOM
+ * }
+ * ```
+ */
+export function isHydrating() {
+    return hydrating;
+}
+/**
+ * Set hydration state
+ *
+ * @internal
+ */
+export function setHydrating(state) {
+    hydrating = state;
+}
+// ============================================================================
+// HYDRATION DATA MANAGEMENT
+// ============================================================================
+/**
+ * Store data for hydration
+ *
+ * On server, store data to serialize into HTML
+ * On client during hydration, this data is reused
+ *
+ * @example
+ * ```typescript
+ * import { setHydrationData } from '@fluixi/core/server';
+ *
+ * // On server
+ * setHydrationData('user', { id: 1, name: 'Alice' });
+ * ```
+ */
+export function setHydrationData(key, data) {
+    hydrationDataMap.set(key, data);
+}
+/**
+ * Get hydration data
+ *
+ * On client, retrieve data stored on server
+ *
+ * @example
+ * ```typescript
+ * import { getHydrationData } from '@fluixi/core/server';
+ *
+ * // On client
+ * const user = getHydrationData('user');
+ * ```
+ */
+export function getHydrationData(key) {
+    return hydrationDataMap.get(key);
+}
+/**
+ * Check if hydration data exists
+ */
+export function hasHydrationData(key) {
+    return hydrationDataMap.has(key);
+}
+/**
+ * Clear all hydration data
+ *
+ * @internal
+ */
+export function clearHydrationData() {
+    hydrationDataMap.clear();
+}
+/**
+ * Clear specific hydration data
+ */
+export function clearHydrationDataKey(key) {
+    hydrationDataMap.delete(key);
+}
+// ============================================================================
+// SERIALIZATION
+// ============================================================================
+/**
+ * Serialize hydration data to script tag
+ *
+ * Embed data in HTML for client hydration
+ *
+ * @example
+ * ```typescript
+ * import { serializeHydrationData } from '@fluixi/core/server';
+ *
+ * const html = await renderToString(() => App());
+ * const script = serializeHydrationData();
+ * return html + script;
+ * ```
+ */
+export function serializeHydrationData() {
+    if (hydrationDataMap.size === 0) {
+        return '';
+    }
+    const data = Object.fromEntries(hydrationDataMap);
+    const json = JSON.stringify(data);
+    return `<script type="application/json" id="__FLUIXI_HYDRATION__">${json}</script>`;
+}
+/**
+ * Deserialize hydration data from DOM
+ *
+ * On client, load data from script tag
+ *
+ * @example
+ * ```typescript
+ * import { deserializeHydrationData } from '@fluixi/core/server';
+ *
+ * // On client startup
+ * if (deserializeHydrationData()) {
+ *   console.log('Hydration data loaded');
+ * }
+ * ```
+ */
+export function deserializeHydrationData() {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    const script = document.getElementById('__FLUIXI_HYDRATION__');
+    if (!script || script.getAttribute('type') !== 'application/json') {
+        return false;
+    }
+    try {
+        const json = script.textContent || '{}';
+        const data = JSON.parse(json);
+        for (const [key, value] of Object.entries(data)) {
+            hydrationDataMap.set(key, value);
+        }
+        return true;
+    }
+    catch (error) {
+        console.error('Failed to deserialize hydration data:', error);
+        return false;
+    }
+}
+// ============================================================================
+// HYDRATION MARKERS
+// ============================================================================
+/**
+ * Generate unique hydration marker ID
+ *
+ * @internal
+ */
+export function generateMarkerID() {
+    return `h${markerCounter++}`;
+}
+/**
+ * Create hydration marker
+ *
+ * Structural markers required for hydration points
+ *
+ * @example
+ * ```typescript
+ * import { hydrationMarker } from '@fluixi/core/server';
+ *
+ * const marker = hydrationMarker('component-1');
+ * // Returns: <!--h:component-1-->
+ * ```
+ */
+export function hydrationMarker(id) {
+    return `<!--#${id}-->`;
+}
+/**
+ * Create start hydration marker
+ */
+export function hydrationMarkerStart(id) {
+    return `<!--#${id}-->`;
+}
+/**
+ * Create end hydration marker
+ */
+export function hydrationMarkerEnd(id) {
+    return `<!--/${id}-->`;
+}
+// ============================================================================
+// RESOURCE HYDRATION
+// ============================================================================
+/**
+ * Create hydration-friendly resource
+ *
+ * Resources loaded on server are serialized
+ * On client, reused during hydration (no re-fetch)
+ *
+ * @example
+ * ```typescript
+ * import { createHydratableResource } from '@fluixi/core/server';
+ *
+ * const loadUser = createHydratableResource('user', async () => {
+ *   const res = await fetch('/api/user');
+ *   return res.json();
+ * });
+ * ```
+ */
+export function createHydratableResource(key, fetcher) {
+    return async () => {
+        // During hydration or on client, check for cached data
+        if (isHydrating() || typeof window !== 'undefined') {
+            const cached = getHydrationData(key);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        // Server or no cache: fetch data
+        const data = await fetcher();
+        // On server, store for serialization
+        if (typeof window === 'undefined') {
+            setHydrationData(key, data);
+        }
+        return data;
+    };
+}
+/**
+ * Use hydration data in component
+ *
+ * Components use hydration data to restore state
+ * without re-execution
+ *
+ * @example
+ * ```typescript
+ * import { useHydrationData } from '@fluixi/core/server';
+ *
+ * const MyComponent = () => {
+ *   const data = useHydrationData('my-data', { initial: true });
+ *   return html`<div>${JSON.stringify(data)}</div>`;
+ * };
+ * ```
+ */
+export function useHydrationData(key, value) {
+    // Check for hydration data first
+    const hydrationData = getHydrationData(key);
+    if (hydrationData !== undefined) {
+        return hydrationData;
+    }
+    // Compute or use provided value
+    const computedValue = typeof value === 'function' ? value() : value;
+    // On server, store for serialization
+    if (typeof window === 'undefined') {
+        setHydrationData(key, computedValue);
+    }
+    return computedValue;
+}
+// ============================================================================
+// CLEANUP
+// ============================================================================
+/**
+ * Cleanup hydration artifacts from DOM
+ *
+ * After hydration, remove markers and serialized data
+ *
+ * @example
+ * ```typescript
+ * import { cleanupHydration } from '@fluixi/core/server';
+ *
+ * // After hydration completes
+ * cleanupHydration();
+ * ```
+ */
+export function cleanupHydration() {
+    if (typeof window === 'undefined') {
+        return;
+    }
+    // Remove hydration data script
+    const script = document.getElementById('__FLUIXI_HYDRATION__');
+    if (script) {
+        script.remove();
+    }
+    // Remove hydration markers (comments)
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_COMMENT, null);
+    const comments = [];
+    let node;
+    while ((node = walker.nextNode())) {
+        const comment = node;
+        const text = comment.nodeValue || '';
+        if (text.startsWith('#') || text.startsWith('/')) {
+            comments.push(comment);
+        }
+    }
+    comments.forEach((comment) => comment.remove());
+    // Clear hydration data from memory
+    clearHydrationData();
+}
+/**
+ * Auto-cleanup hydration on page load (client-side)
+ */
+if (typeof window !== 'undefined') {
+    window.addEventListener('load', () => {
+        // Delay cleanup to ensure hydration is complete
+        setTimeout(cleanupHydration, 100);
+    });
+}
+// ============================================================================
+// ENVIRONMENT HELPERS
+// ============================================================================
+/**
+ * Whether this is a server render.
+ *
+ * Defers to `@fluixi/dom`, which keeps the flag on a realm singleton that
+ * `renderToString` sets. A local `typeof window` test disagrees with it inside a jsdom
+ * process, which is where server rendering is usually tested, and `router/data.ts`
+ * branches on this to decide whether a loader may touch the client.
+ */
+export function isServerEnvironment() {
+    return domIsServer();
+}
+/** Whether this is running in a browser, the negation of a server render. */
+export function isClientEnvironment() {
+    return !domIsServer();
+}