@chr33s/solarflare 0.0.2

package/src/hydration.ts

@@ -0,0 +1,238 @@
+import { serializeToString, parseFromString } from "./serialize.ts";
+import { serializeHeadState, hydrateHeadState } from "./head.ts";
+import { initStore, setPathname, params, serverData, pathname } from "./store.ts";
+
+/** Store island ID. */
+const STORE_ISLAND_ID = "sf-store";
+
+/** Head island ID. */
+const HEAD_ISLAND_ID = "sf-head";
+
+/** Gets the default data island ID for a component tag. */
+export function getComponentDataIslandId(tag: string) {
+  return `${tag}-data`;
+}
+
+/** Gets the deferred data island ID for a component tag and key. */
+export function getDeferredIslandId(tag: string, key: string) {
+  return `${tag}-deferred-${key}`;
+}
+
+/** Gets the deferred hydration script ID for a component tag and key. */
+export function getHydrateScriptId(tag: string, key: string) {
+  return `${tag}-hydrate-${key}`;
+}
+
+/** Gets the deferred data island prefix for a component tag. */
+export function getDeferredIslandPrefix(tag: string) {
+  return `${tag}-deferred-`;
+}
+
+/** Gets the hydration script prefix for a component tag. */
+export function getHydrateScriptPrefix(tag: string) {
+  return `${tag}-hydrate-`;
+}
+
+/**
+ * Serializes data to a script tag for progressive hydration.
+ * Includes a stable id attribute for diff-dom-streaming replacements.
+ */
+export async function serializeDataIsland(id: string, data: unknown) {
+  const serialized = await serializeToString(data);
+  return /* html */ `<script type="application/json" id="${id}" data-island="${id}">${serialized}</script>`;
+}
+
+/** Extracts and parses data from a data island script tag. */
+export async function extractDataIsland<T = unknown>(id: string) {
+  if (typeof document === "undefined") return null;
+
+  const script = document.querySelector(`script[data-island="${CSS.escape(id)}"]`);
+  if (!script?.textContent) return null;
+
+  try {
+    return await parseFromString<T>(script.textContent);
+  } catch {
+    console.error(`[solarflare] Failed to parse data island "${id}"`);
+    return null;
+  }
+}
+
+/** Serializes store state for client hydration. */
+export async function serializeStoreForHydration() {
+  const state = {
+    params: params.value,
+    serverData: serverData.value.data,
+    pathname: pathname.value,
+  };
+
+  return serializeDataIsland(STORE_ISLAND_ID, state);
+}
+
+/** Serializes head state for client hydration. */
+export async function serializeHeadForHydration() {
+  return /* html */ `<script type="application/json" data-island="${HEAD_ISLAND_ID}">${serializeHeadState()}</script>`;
+}
+
+/** Hydrates store from serialized state (client-side). */
+export async function hydrateStore() {
+  if (typeof document === "undefined") return;
+
+  const state = await extractDataIsland<{
+    params: Record<string, string>;
+    serverData: unknown;
+    pathname: string;
+  }>(STORE_ISLAND_ID);
+
+  if (!state) return;
+
+  initStore({
+    params: state.params,
+    serverData: state.serverData,
+  });
+
+  setPathname(state.pathname);
+
+  const script = document.querySelector(`script[data-island="${CSS.escape(STORE_ISLAND_ID)}"]`);
+  script?.remove();
+}
+
+/** Hydrates head state from serialized data island (client-side). */
+export async function hydrateHead() {
+  if (typeof document === "undefined") return;
+
+  const script = document.querySelector(`script[data-island="${CSS.escape(HEAD_ISLAND_ID)}"]`);
+  if (!script?.textContent) return;
+
+  hydrateHeadState(script.textContent);
+
+  script.remove();
+}
+
+/** Navigation mode flag - when true, don't remove data island scripts during hydration. */
+let navigationMode = false;
+
+/** Sets navigation mode (called by router during client-side navigation). */
+export function setNavigationMode(active: boolean) {
+  navigationMode = active;
+}
+
+/**
+ * Hydrates a component when its data island arrives.
+ * Removes island scripts unless navigation mode is active.
+ */
+export async function hydrateComponent(tag: string, dataIslandId?: string) {
+  if (typeof document === "undefined") return;
+
+  const element = document.querySelector(tag) as HTMLElement & {
+    _sfDeferred?: Record<string, unknown>;
+    _vdom?: unknown;
+  };
+  if (!element) return;
+
+  const islandId = dataIslandId ?? getComponentDataIslandId(tag);
+  const data = await extractDataIsland<Record<string, unknown>>(islandId);
+
+  if (data && typeof data === "object") {
+    element.removeAttribute("data-loading");
+    element._sfDeferred = { ...element._sfDeferred, ...data };
+
+    if (!navigationMode) {
+      const scripts = document.querySelectorAll(`script[data-island="${CSS.escape(islandId)}"]`);
+      scripts.forEach((script) => script.remove());
+    }
+
+    element.dispatchEvent(
+      new CustomEvent("sf:hydrate", {
+        detail: data,
+        bubbles: true,
+      }),
+    );
+  }
+}
+
+/** Module-level hydration state. */
+let hydrationReady = false;
+const hydrationQueue: Array<{ tag: string; id: string; attempts: number }> = [];
+let eventListenerAttached = false;
+let processingQueue = false;
+const MAX_HYDRATION_RETRIES = 50;
+const HYDRATION_RETRY_DELAY_MS = 50;
+
+/** Handles hydration queue events. */
+function handleQueueHydrateEvent(e: Event) {
+  const { tag, id } = (e as CustomEvent<{ tag: string; id: string }>).detail;
+  queueHydration(tag, id);
+}
+
+/** Processes the hydration queue sequentially. */
+async function processHydrationQueue() {
+  if (processingQueue) return;
+  processingQueue = true;
+
+  while (hydrationQueue.length > 0) {
+    const item = hydrationQueue.shift();
+    if (!item) continue;
+
+    const { tag, id: dataIslandId, attempts } = item;
+    // Skip stale entries for elements no longer in the DOM
+    if (!document.querySelector(tag)) {
+      if (attempts < MAX_HYDRATION_RETRIES) {
+        hydrationQueue.push({ tag, id: dataIslandId, attempts: attempts + 1 });
+      }
+      await new Promise((resolve) => setTimeout(resolve, HYDRATION_RETRY_DELAY_MS));
+      continue;
+    }
+
+    try {
+      await hydrateComponent(tag, dataIslandId);
+    } catch (err) {
+      console.error("[solarflare] hydrateComponent error:", err);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+
+  processingQueue = false;
+}
+
+/** Queues a hydration call. */
+export function queueHydration(tag: string, dataIslandId: string) {
+  hydrationQueue.push({ tag, id: dataIslandId, attempts: 0 });
+  if (hydrationReady) {
+    void processHydrationQueue();
+  }
+}
+
+/** Checks if hydration coordinator is initialized. */
+export function isHydrationReady() {
+  return hydrationReady;
+}
+
+/** Initializes the hydration coordinator. */
+export function initHydrationCoordinator() {
+  if (typeof document === "undefined") return;
+
+  // Attach event listener for streaming SSR hydration triggers (only once)
+  if (!eventListenerAttached) {
+    document.addEventListener("sf:queue-hydrate", handleQueueHydrateEvent);
+    eventListenerAttached = true;
+  }
+
+  if (hydrationReady) return;
+
+  hydrationReady = true;
+  void processHydrationQueue();
+}
+
+/** Cleans up the hydration coordinator (call on app unmount/navigation). */
+export function cleanupHydrationCoordinator() {
+  if (typeof document === "undefined") return;
+
+  if (eventListenerAttached) {
+    document.removeEventListener("sf:queue-hydrate", handleQueueHydrateEvent);
+    eventListenerAttached = false;
+  }
+
+  hydrationReady = false;
+  processingQueue = false;
+  hydrationQueue.length = 0;
+}

package/src/manifest.runtime.ts

@@ -0,0 +1,25 @@
+import type { ChunkManifest } from "./manifest.ts";
+import type { ModuleMap } from "./server.ts";
+// @ts-ignore - Generated at build time, aliased by bundler
+import modules from ".modules.generated";
+// @ts-ignore - Generated at build time, aliased by bundler
+import chunkManifest from ".chunks.generated.json";
+
+export const typedModules = modules as ModuleMap;
+
+export const manifest = chunkManifest as ChunkManifest;
+
+/** Gets the script path for a route from the chunk manifest. */
+export function getScriptPath(tag: string) {
+  return manifest.tags[tag];
+}
+
+/** Gets stylesheets for a route pattern from the chunk manifest. */
+export function getStylesheets(pattern: string) {
+  return manifest.styles[pattern] ?? [];
+}
+
+/** Gets dev mode scripts from the chunk manifest. */
+export function getDevScripts() {
+  return manifest.devScripts;
+}

package/src/manifest.ts

@@ -0,0 +1,23 @@
+/** Route entry from build-time manifest. */
+export interface RouteManifestEntry {
+  pattern: string;
+  tag: string;
+  chunk?: string;
+  styles?: string[];
+  type: "client" | "server";
+  params: string[];
+}
+
+/** Build-time routes manifest. */
+export interface RoutesManifest {
+  routes: RouteManifestEntry[];
+  base?: string;
+}
+
+/** Chunk manifest mapping routes to assets. */
+export interface ChunkManifest {
+  chunks: Record<string, string>;
+  tags: Record<string, string>;
+  styles: Record<string, string[]>;
+  devScripts?: string[];
+}

package/src/paths.ts

@@ -0,0 +1,96 @@
+/** Module kind based on file naming convention. */
+export type ModuleKind = "server" | "client" | "layout" | "error" | "unknown";
+
+/** Parsed path information with validated metadata. */
+export interface ParsedPath {
+  original: string;
+  normalized: string;
+  kind: ModuleKind;
+  segments: string[];
+  params: string[];
+  isIndex: boolean;
+  isPrivate: boolean;
+  pattern: string;
+  tag: string;
+  specificity: number;
+}
+
+/** Determines module kind from file path. */
+function getModuleKind(filePath: string): ModuleKind {
+  if (filePath.includes(".server.")) return "server";
+  if (filePath.includes(".client.")) return "client";
+  if (filePath.includes("_layout.")) return "layout";
+  if (filePath.includes("_error.")) return "error";
+  return "unknown";
+}
+
+/** Parses a file path into structured metadata. */
+export function parsePath(filePath: string): ParsedPath {
+  const normalized = filePath.replace(/^\.\//, "").replace(/^.*\/app\//, "");
+  const kind = getModuleKind(normalized);
+  const isPrivate = normalized.includes("/_") || normalized.startsWith("_");
+
+  const withoutExt = normalized.replace(/\.(client|server)\.tsx?$/, "").replace(/\.tsx?$/, "");
+
+  const segments = withoutExt.split("/").filter(Boolean);
+
+  const params: string[] = [];
+  for (const segment of segments) {
+    const match = segment.match(/^\$(.+)$/);
+    if (match) {
+      params.push(match[1]);
+    }
+  }
+
+  const isIndex = withoutExt === "index" || withoutExt.endsWith("/index") || withoutExt === "";
+
+  const pattern =
+    "/" +
+      withoutExt
+        .replace(/\/index$/, "")
+        .replace(/^index$/, "")
+        .replace(/\$([^/]+)/g, ":$1") || "";
+
+  const tag =
+    "sf-" +
+      withoutExt
+        .replace(/\//g, "-")
+        .replace(/\$/g, "")
+        .replace(/^index$/, "root")
+        .replace(/-index$/, "")
+        .toLowerCase() || "sf-root";
+
+  const staticSegments = segments.filter((s) => !s.startsWith("$")).length;
+  const dynamicSegments = segments.filter((s) => s.startsWith("$")).length;
+  const specificity =
+    staticSegments * 2 + dynamicSegments + (pattern === "/" ? 0 : segments.length);
+
+  return {
+    original: filePath,
+    normalized,
+    kind,
+    segments,
+    params,
+    isIndex,
+    isPrivate,
+    pattern,
+    tag,
+    specificity,
+  };
+}
+
+/** Finds a paired module path given a client or server path. */
+export function findPairedModulePath(
+  path: string,
+  modules: { client: Record<string, unknown>; server: Record<string, unknown> },
+) {
+  if (path.includes(".client.")) {
+    const serverPath = path.replace(".client.", ".server.");
+    return serverPath in modules.server ? serverPath : null;
+  }
+  if (path.includes(".server.")) {
+    const clientPath = path.replace(".server.", ".client.");
+    return clientPath in modules.client ? clientPath : null;
+  }
+  return null;
+}

package/src/render-priority.ts

@@ -0,0 +1,69 @@
+import { type VNode, h, Fragment } from "preact";
+
+/** Priority levels for content rendering. */
+export type RenderPriority = "critical" | "high" | "normal" | "low" | "idle";
+
+/** Creates a deferred rendering boundary. */
+export function Deferred(props: {
+  priority?: RenderPriority;
+  fallback?: VNode;
+  children: VNode;
+}): VNode {
+  const { priority = "normal", fallback, children } = props;
+
+  // On server, we render a placeholder that gets replaced
+  if (typeof window === "undefined") {
+    const id = `sf-deferred-${Math.random().toString(36).slice(2, 9)}`;
+
+    return h(Fragment, null, [
+      h(
+        "sf-deferred",
+        {
+          id,
+          "data-priority": priority,
+          style: { display: "contents" },
+        },
+        fallback ?? h("div", { class: "sf-loading" }),
+      ),
+      h("template", {
+        "data-sf-deferred": id,
+        dangerouslySetInnerHTML: { __html: `<!--SF: DEFERRED:${id}-->` },
+      }),
+    ]);
+  }
+
+  return children;
+}
+
+/** Skeleton loader component. */
+export function Skeleton(props: {
+  width?: string;
+  height?: string;
+  variant?: "text" | "rect" | "circle";
+  count?: number;
+}): VNode {
+  const { width = "100%", height = "1em", variant = "text", count = 1 } = props;
+
+  const style = {
+    width,
+    height,
+    backgroundColor: "#e0e0e0",
+    borderRadius: variant === "circle" ? "50%" : variant === "text" ? "4px" : "0",
+    animation: "sf-skeleton-pulse 1.5s ease-in-out infinite",
+  };
+
+  const items = Array.from({ length: count }, (_, i) =>
+    h("div", { key: i, class: "sf-skeleton", style }),
+  );
+
+  return h(Fragment, null, items);
+}
+
+/** Injects skeleton animation CSS. */
+export const SKELETON_CSS = /* css */ `
+@keyframes sf-skeleton-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.5; }
+}
+. sf-loading { min-height: 100px; }
+`;

package/src/route-cache.ts

@@ -0,0 +1,163 @@
+/** Cache configuration per route. */
+export interface RouteCacheConfig {
+  maxAge: number;
+  staleWhileRevalidate?: number;
+  keyGenerator?: (request: Request, params: Record<string, string>) => string;
+  cacheAuthenticated?: boolean;
+  vary?: string[];
+}
+
+/** Default cache configs by route type. */
+export const DEFAULT_CACHE_CONFIGS: Record<string, RouteCacheConfig> = {
+  static: {
+    maxAge: 3600,
+    staleWhileRevalidate: 86400,
+  },
+  dynamic: {
+    maxAge: 60,
+    staleWhileRevalidate: 300,
+  },
+  private: {
+    maxAge: 0,
+    cacheAuthenticated: false,
+  },
+};
+
+/** Generates cache control header value. */
+export function generateCacheControl(config: RouteCacheConfig, isPrivate: boolean) {
+  const directives: string[] = [];
+
+  if (isPrivate || !config.cacheAuthenticated) {
+    directives.push("private");
+  } else {
+    directives.push("public");
+  }
+
+  if (config.maxAge > 0) {
+    directives.push(`max-age=${config.maxAge}`);
+  } else {
+    directives.push("no-cache");
+  }
+
+  if (config.staleWhileRevalidate) {
+    directives.push(`stale-while-revalidate=${config.staleWhileRevalidate}`);
+  }
+
+  return directives.join(", ");
+}
+
+/** Response cache with Cloudflare Cache API (or in-memory fallback). */
+export class ResponseCache {
+  #cache?: Cache;
+  #memory = new Map<string, { response: Response; expires: number }>();
+  #maxSize: number;
+
+  constructor(maxSize = 100) {
+    this.#maxSize = maxSize;
+    if (typeof caches !== "undefined") {
+      this.#cache = (caches as any).default;
+    }
+  }
+
+  async get(key: string) {
+    if (this.#cache) {
+      const res = await this.#cache.match(this.#toRequest(key));
+      return res ?? null;
+    }
+    const entry = this.#memory.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expires) {
+      this.#memory.delete(key);
+      return null;
+    }
+    return entry.response.clone();
+  }
+
+  async set(key: string, response: Response, maxAge: number) {
+    if (this.#cache) {
+      const headers = new Headers(response.headers);
+      headers.set("Cache-Control", `public, max-age=${maxAge}`);
+      await this.#cache.put(
+        this.#toRequest(key),
+        new Response(response.clone().body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers,
+        }),
+      );
+      return;
+    }
+    while (this.#memory.size >= this.#maxSize) {
+      const firstKey = this.#memory.keys().next().value;
+      if (firstKey) this.#memory.delete(firstKey);
+    }
+    this.#memory.set(key, {
+      response: response.clone(),
+      expires: Date.now() + maxAge * 1000,
+    });
+  }
+
+  #toRequest(key: string) {
+    return new Request(`https://cache.local/${encodeURIComponent(key)}`);
+  }
+
+  static generateKey(request: Request, params: Record<string, string>) {
+    const url = new URL(request.url);
+    const sortedParams = Object.entries(params)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => `${k}=${v}`)
+      .join("&");
+    return `${url.pathname}?${sortedParams}`;
+  }
+}
+
+/** Cache-aware request handler wrapper */
+export async function withCache(
+  request: Request,
+  params: Record<string, string>,
+  config: RouteCacheConfig,
+  handler: () => Promise<Response>,
+  cache: ResponseCache,
+) {
+  const hasAuth = request.headers.has("Authorization") || request.headers.has("Cookie");
+  if (hasAuth && !config.cacheAuthenticated) {
+    return handler();
+  }
+
+  const key = config.keyGenerator
+    ? config.keyGenerator(request, params)
+    : ResponseCache.generateKey(request, params);
+
+  const cached = await cache.get(key);
+  if (cached) {
+    const headers = new Headers(cached.headers);
+    headers.set("X-Cache", "HIT");
+    return new Response(cached.body, {
+      status: cached.status,
+      statusText: cached.statusText,
+      headers,
+    });
+  }
+
+  const response = await handler();
+
+  // Only cache successful responses
+  if (response.ok && config.maxAge > 0) {
+    await cache.set(key, response, config.maxAge);
+  }
+
+  // Add cache headers
+  const headers = new Headers(response.headers);
+  headers.set("Cache-Control", generateCacheControl(config, hasAuth));
+  headers.set("X-Cache", "MISS");
+
+  if (config.vary?.length) {
+    headers.set("Vary", config.vary.join(", "));
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}

package/src/router-deferred.ts

@@ -0,0 +1,85 @@
+import { getDeferredIslandPrefix, getHydrateScriptPrefix } from "./hydration.ts";
+
+/**
+ * Handles deferred hydration script and island insertion during streamed navigation.
+ */
+export function handleDeferredHydrationNode(
+  entryTag: string,
+  processedScripts: Set<string>,
+  node: Element,
+) {
+  const hydratePrefix = getHydrateScriptPrefix(entryTag);
+  const islandPrefix = getDeferredIslandPrefix(entryTag);
+
+  const processHydrationScript = (script: HTMLScriptElement) => {
+    const scriptId = script.id;
+    if (!scriptId || !scriptId.startsWith(hydratePrefix)) return;
+    if (processedScripts.has(scriptId)) return;
+    processedScripts.add(scriptId);
+
+    // Parse the hydration detail from the script content
+    // Format: detail:{"tag":"sf-root","id":"sf-root-deferred-defer-xxx"}
+    const scriptContent = script.textContent;
+    if (scriptContent) {
+      const match = scriptContent.match(/detail:(\{[^}]+\})/);
+      if (match) {
+        try {
+          const detail = JSON.parse(match[1]) as { tag: string; id: string };
+          document.dispatchEvent(new CustomEvent("sf:queue-hydrate", { detail }));
+          return;
+        } catch {
+          // Fallback: script will execute naturally when inserted
+        }
+      }
+    }
+  };
+
+  const processDataIsland = (script: HTMLScriptElement) => {
+    const id = script.getAttribute("data-island");
+    if (!id || !id.startsWith(islandPrefix)) return;
+    const islandKey = `island:${id}`;
+    if (processedScripts.has(islandKey)) return;
+    processedScripts.add(islandKey);
+    document.dispatchEvent(
+      new CustomEvent("sf:queue-hydrate", {
+        detail: { tag: entryTag, id },
+      }),
+    );
+  };
+
+  if (node.tagName === "SCRIPT") {
+    const script = node as HTMLScriptElement;
+    processHydrationScript(script);
+    processDataIsland(script);
+    return;
+  }
+
+  // Also scan descendants in case a container node was inserted
+  const scripts = node.querySelectorAll("script");
+  for (const script of scripts) {
+    processHydrationScript(script as HTMLScriptElement);
+    processDataIsland(script as HTMLScriptElement);
+  }
+}
+
+export function dedupeDeferredScripts(entryTag: string) {
+  const islandPrefix = getDeferredIslandPrefix(entryTag);
+  const hydratePrefix = getHydrateScriptPrefix(entryTag);
+  const scripts = document.querySelectorAll(
+    `script[data-island^="${islandPrefix}"], script[id^="${hydratePrefix}"]`,
+  );
+  const seen = new Map<string, HTMLScriptElement>();
+
+  for (const script of scripts) {
+    const dataIsland = script.getAttribute("data-island");
+    const key = dataIsland ? `island:${dataIsland}` : script.id ? `hydrate:${script.id}` : null;
+
+    if (!key) continue;
+
+    const previous = seen.get(key);
+    if (previous) {
+      previous.remove();
+    }
+    seen.set(key, script as HTMLScriptElement);
+  }
+}