@chr33s/solarflare 0.0.2

package/src/speculation-rules.ts

@@ -0,0 +1,171 @@
+/** Speculation Rules API types and utilities for prefetch/prerender. */
+
+/** Eagerness levels for speculation. */
+export type SpeculationEagerness = "immediate" | "eager" | "moderate" | "conservative";
+
+/** Referrer policy for speculative requests. */
+type SpeculationReferrerPolicy =
+  | "no-referrer"
+  | "no-referrer-when-downgrade"
+  | "origin"
+  | "origin-when-cross-origin"
+  | "same-origin"
+  | "strict-origin"
+  | "strict-origin-when-cross-origin"
+  | "unsafe-url";
+
+/** Document-sourced rule matching anchors. */
+export interface DocumentRule {
+  source: "document";
+  where?: {
+    href_matches?: string | string[];
+    selector_matches?: string;
+    and?: DocumentRule["where"][];
+    or?: DocumentRule["where"][];
+    not?: DocumentRule["where"];
+  };
+  eagerness?: SpeculationEagerness;
+  referrer_policy?: SpeculationReferrerPolicy;
+  expects_no_vary_search?: string;
+}
+
+/** List-sourced rule with explicit URLs. */
+export interface ListRule {
+  source: "list";
+  urls: string[];
+  eagerness?: SpeculationEagerness;
+  referrer_policy?: SpeculationReferrerPolicy;
+  expects_no_vary_search?: string;
+}
+
+/** Union type for speculation rules. */
+export type SpeculationRule = DocumentRule | ListRule;
+
+/** Complete speculation rules object. */
+export interface SpeculationRules {
+  prefetch?: SpeculationRule[];
+  prerender?: SpeculationRule[];
+}
+
+/** Checks if Speculation Rules API is supported. */
+export function supportsSpeculationRules() {
+  return (
+    typeof HTMLScriptElement !== "undefined" &&
+    HTMLScriptElement.supports?.("speculationrules") === true
+  );
+}
+
+/** Injects speculation rules into the document head. */
+export function injectSpeculationRules(rules: SpeculationRules) {
+  if (typeof document === "undefined") return null;
+
+  const script = document.createElement("script");
+  script.type = "speculationrules";
+  script.textContent = JSON.stringify(rules);
+  const head = document.head;
+  const existing = head.querySelector('script[type="speculationrules"]');
+  if (existing) {
+    existing.replaceWith(script);
+    return script;
+  }
+
+  const range = document.createRange();
+  const firstManaged = head.querySelector("[data-sf-head]");
+  if (firstManaged) {
+    range.setStartBefore(firstManaged);
+    range.collapse(true);
+  } else {
+    range.selectNodeContents(head);
+    range.collapse(false);
+  }
+  range.insertNode(script);
+  return script;
+}
+
+/** Removes all speculation rules scripts from the document. */
+export function clearSpeculationRules() {
+  if (typeof document === "undefined") return;
+
+  const scripts = document.querySelectorAll('script[type="speculationrules"]');
+  for (const script of scripts) {
+    script.remove();
+  }
+}
+
+/** Creates a list-based prefetch rule. */
+export function createPrefetchListRule(
+  urls: string[],
+  options: Omit<ListRule, "source" | "urls"> = {},
+): ListRule {
+  return { source: "list", urls, ...options };
+}
+
+/** Creates a list-based prerender rule. */
+export function createPrerenderListRule(
+  urls: string[],
+  options: Omit<ListRule, "source" | "urls"> = {},
+): ListRule {
+  return { source: "list", urls, ...options };
+}
+
+/** Creates a document-sourced rule matching href patterns. */
+export function createDocumentRule(
+  patterns: string | string[],
+  options: Omit<DocumentRule, "source" | "where"> = {},
+): DocumentRule {
+  return {
+    source: "document",
+    where: { href_matches: patterns },
+    ...options,
+  };
+}
+
+/** Creates a document-sourced rule matching CSS selectors. */
+export function createSelectorRule(
+  selector: string,
+  options: Omit<DocumentRule, "source" | "where"> = {},
+): DocumentRule {
+  return {
+    source: "document",
+    where: { selector_matches: selector },
+    ...options,
+  };
+}
+
+/** Builds speculation rules from route patterns. */
+export function buildRouteSpeculationRules(
+  routes: { pattern: string; prerender?: boolean }[],
+  base = "",
+): SpeculationRules {
+  const prefetchUrls: string[] = [];
+  const prerenderUrls: string[] = [];
+
+  for (const route of routes) {
+    // Skip dynamic routes (contain : or *)
+    if (/[:*]/.test(route.pattern)) continue;
+
+    const url = base + route.pattern;
+    if (route.prerender) {
+      prerenderUrls.push(url);
+    } else {
+      prefetchUrls.push(url);
+    }
+  }
+
+  const rules: SpeculationRules = {};
+
+  if (prefetchUrls.length > 0) {
+    rules.prefetch = [createPrefetchListRule(prefetchUrls, { eagerness: "moderate" })];
+  }
+
+  if (prerenderUrls.length > 0) {
+    rules.prerender = [createPrerenderListRule(prerenderUrls, { eagerness: "moderate" })];
+  }
+
+  return rules;
+}
+
+/** Generates inline script tag HTML for SSR. */
+export function renderSpeculationRulesTag(rules: SpeculationRules) {
+  return `<script type="speculationrules">${JSON.stringify(rules)}</script>`;
+}

package/src/store.ts

@@ -0,0 +1,78 @@
+import { signal, batch, type ReadonlySignal } from "@preact/signals";
+
+export interface ServerData<T = unknown> {
+  data: T;
+  loading: boolean;
+  error: Error | null;
+}
+
+export interface StoreConfig {
+  params?: Record<string, string>;
+  serverData?: unknown;
+}
+
+/** Route params signal. */
+const _params = signal<Record<string, string>>({});
+
+/** Server data signal. */
+const _serverData = signal<ServerData<unknown>>({
+  data: null,
+  loading: false,
+  error: null,
+});
+
+/** Pathname signal. */
+const _pathname = signal<string>("");
+
+/** Route parameters. */
+export const params: ReadonlySignal<Record<string, string>> = _params;
+
+/** Server data. */
+export const serverData: ReadonlySignal<ServerData<unknown>> = _serverData;
+
+/** Current pathname. */
+export const pathname: ReadonlySignal<string> = _pathname;
+
+/** Sets route parameters. */
+export function setParams(newParams: Record<string, string>) {
+  _params.value = newParams;
+}
+
+/** Sets server data. */
+export function setServerData<T>(data: T) {
+  _serverData.value = {
+    data,
+    loading: false,
+    error: null,
+  };
+}
+
+/** Sets current pathname. */
+export function setPathname(path: string) {
+  _pathname.value = path;
+}
+
+/** Initializes store with config. */
+export function initStore(config: StoreConfig = {}) {
+  batch(() => {
+    if (config.params) {
+      _params.value = config.params;
+    }
+    if (config.serverData !== undefined) {
+      _serverData.value = {
+        data: config.serverData,
+        loading: false,
+        error: null,
+      };
+    }
+  });
+}
+
+/** Resets store to initial state. */
+export function resetStore() {
+  batch(() => {
+    _params.value = {};
+    _serverData.value = { data: null, loading: false, error: null };
+    _pathname.value = "";
+  });
+}

package/src/stream-assets.ts

@@ -0,0 +1,135 @@
+import { getHeadContext, HEAD_MARKER } from "./head.ts";
+
+/** Marker for asset injection during streaming. */
+export const BODY_MARKER = "<!--SOLARFLARE_BODY-->";
+
+/** Generates asset HTML tags for injection. */
+export function generateAssetTags(script?: string, styles?: string[], devScripts?: string[]) {
+  let html = "";
+
+  // Add stylesheet links
+  if (styles && styles.length > 0) {
+    for (const href of styles) {
+      html += /* html */ `<link rel="stylesheet" href="${href}">`;
+    }
+  }
+
+  // Add dev mode scripts (like console forwarding)
+  if (devScripts && devScripts.length > 0) {
+    for (const src of devScripts) {
+      html += /* html */ `<script src="${src}" async></script>`;
+    }
+  }
+
+  // Add script tag
+  if (script) {
+    html += /* html */ `<script type="module" src="${script}" async></script>`;
+  }
+
+  return html;
+}
+
+/** Transforms stream to inject assets, head tags, and store hydration. */
+export function createAssetInjectionTransformer(
+  storeScript: string,
+  script?: string,
+  styles?: string[],
+  devScripts?: string[],
+): TransformStream<Uint8Array, Uint8Array> {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let doctypeInjected = false;
+  let headInjected = false;
+  const bodyMarker = /* html */ `<solarflare-body>${BODY_MARKER}</solarflare-body>`;
+  const headMarker = HEAD_MARKER;
+
+  function replaceHeadMarker(html: string) {
+    const markerIndex = html.indexOf(headMarker);
+    if (markerIndex === -1) return { html, replaced: false };
+
+    const templateStart = html.lastIndexOf("<template", markerIndex);
+    if (templateStart !== -1) {
+      const tagEnd = html.indexOf(">", templateStart);
+      if (tagEnd !== -1) {
+        const openTag = html.slice(templateStart, tagEnd + 1);
+        const templateEnd = html.indexOf("</template>", markerIndex);
+        if (openTag.includes("data-sf-head") && templateEnd !== -1) {
+          const replaced =
+            html.slice(0, templateStart) +
+            getHeadContext().renderToString() +
+            html.slice(templateEnd + "</template>".length);
+          return { html: replaced, replaced: true };
+        }
+      }
+    }
+
+    return { html: html.replace(headMarker, getHeadContext().renderToString()), replaced: true };
+  }
+
+  return new TransformStream({
+    transform(chunk, controller) {
+      buffer += decoder.decode(chunk, { stream: true });
+
+      // Inject <!doctype html> before the root <html> tag (only once)
+      if (!doctypeInjected) {
+        const htmlIndex = buffer.indexOf("<html");
+        if (htmlIndex !== -1) {
+          buffer = buffer.slice(0, htmlIndex) + "<!doctype html>" + buffer.slice(htmlIndex);
+          doctypeInjected = true;
+        }
+      }
+
+      // Inject head tags at Head marker (only once)
+      if (!headInjected) {
+        const result = replaceHeadMarker(buffer);
+        buffer = result.html;
+        headInjected = result.replaced;
+      }
+
+      // Check if we have the complete body marker
+      const markerIndex = buffer.indexOf(bodyMarker);
+      if (markerIndex !== -1) {
+        // Generate replacement content
+        const assetTags = generateAssetTags(script, styles, devScripts);
+
+        // Replace marker with assets + store hydration
+        buffer = buffer.replace(bodyMarker, assetTags + storeScript);
+
+        // Flush everything before and including the replacement
+        controller.enqueue(encoder.encode(buffer));
+        buffer = "";
+      } else if (buffer.length > bodyMarker.length * 2) {
+        // If buffer is getting large and no marker found, flush safe portion
+        const safeLength = buffer.length - bodyMarker.length;
+        controller.enqueue(encoder.encode(buffer.slice(0, safeLength)));
+        buffer = buffer.slice(safeLength);
+      }
+    },
+    flush(controller) {
+      // Flush any remaining content
+      if (buffer) {
+        // Inject doctype if not done yet (edge case: small document)
+        if (!doctypeInjected) {
+          const htmlIndex = buffer.indexOf("<html");
+          if (htmlIndex !== -1) {
+            buffer = buffer.slice(0, htmlIndex) + "<!doctype html>" + buffer.slice(htmlIndex);
+          }
+        }
+        // Final check for head marker in remaining content
+        if (!headInjected) {
+          const result = replaceHeadMarker(buffer);
+          buffer = result.html;
+          headInjected = result.replaced;
+        }
+        // Final check for body marker in remaining content
+        const markerIndex = buffer.indexOf(bodyMarker);
+        if (markerIndex !== -1) {
+          const assetTags = generateAssetTags(script, styles, devScripts);
+          buffer = buffer.replace(bodyMarker, assetTags + storeScript);
+        }
+        controller.enqueue(encoder.encode(buffer));
+      }
+    },
+  });
+}

package/src/stylesheets.ts

@@ -0,0 +1,222 @@
+/** Feature detection for Constructable Stylesheets. */
+export const supportsConstructableStylesheets = () => {
+  if (typeof window === "undefined") return false;
+  try {
+    new CSSStyleSheet();
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Stylesheet entry with metadata. */
+interface StylesheetEntry {
+  sheet: CSSStyleSheet;
+  source: string;
+  hash: string;
+  consumers: Set<string>;
+  isGlobal: boolean;
+}
+
+/** Stylesheet manager for efficient CSS handling. */
+class StylesheetManager {
+  #sheets = new Map<string, StylesheetEntry>();
+  #documentSheets: CSSStyleSheet[] = [];
+
+  /** Registers a stylesheet with the manager. */
+  register(id: string, css: string, options: { isGlobal?: boolean; consumer?: string } = {}) {
+    if (!this.#isSupported()) {
+      this.#injectStyleElement(id, css);
+      return null;
+    }
+
+    const existing = this.#sheets.get(id);
+    const hash = this.#hash(css);
+
+    if (existing) {
+      if (existing.hash !== hash) {
+        existing.sheet.replaceSync(css);
+        existing.source = css;
+        existing.hash = hash;
+      }
+      if (options.consumer) {
+        existing.consumers.add(options.consumer);
+      }
+      return existing.sheet;
+    }
+
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(css);
+
+    const entry: StylesheetEntry = {
+      sheet,
+      source: css,
+      hash,
+      consumers: new Set(options.consumer ? [options.consumer] : []),
+      isGlobal: options.isGlobal ?? false,
+    };
+
+    this.#sheets.set(id, entry);
+
+    if (entry.isGlobal) {
+      this.#adoptToDocument(sheet);
+    }
+
+    return sheet;
+  }
+
+  /** Gets a registered stylesheet. */
+  get(id: string) {
+    return this.#sheets.get(id)?.sheet ?? null;
+  }
+
+  /** Gets all stylesheets for a route/consumer. */
+  getForConsumer(consumer: string) {
+    const sheets: CSSStyleSheet[] = [];
+
+    for (const entry of this.#sheets.values()) {
+      if (entry.isGlobal || entry.consumers.has(consumer)) {
+        sheets.push(entry.sheet);
+      }
+    }
+
+    return sheets;
+  }
+
+  /** Updates a stylesheet with new CSS (for HMR). */
+  update(id: string, css: string) {
+    const entry = this.#sheets.get(id);
+    if (!entry) return false;
+
+    const hash = this.#hash(css);
+    if (entry.hash === hash) return false; // No change
+
+    // For small changes, try incremental update
+    if (this.#canIncrementalUpdate(entry.source, css)) {
+      this.#incrementalUpdate(entry.sheet, entry.source, css);
+    } else {
+      // Full replace for larger changes
+      entry.sheet.replaceSync(css);
+    }
+
+    entry.source = css;
+    entry.hash = hash;
+
+    return true;
+  }
+
+  /** Inserts a single rule into a stylesheet. */
+  insertRule(id: string, rule: string, index?: number) {
+    const entry = this.#sheets.get(id);
+    if (!entry) return -1;
+
+    try {
+      const insertIndex = index ?? entry.sheet.cssRules.length;
+      return entry.sheet.insertRule(rule, insertIndex);
+    } catch (e) {
+      console.warn(`[stylesheets] Failed to insert rule: ${rule}`, e);
+      return -1;
+    }
+  }
+
+  /** Deletes a rule from a stylesheet. */
+  deleteRule(id: string, index: number) {
+    const entry = this.#sheets.get(id);
+    if (!entry) return false;
+
+    try {
+      entry.sheet.deleteRule(index);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Adopts stylesheets to a Shadow Root. */
+  adoptToShadowRoot(shadowRoot: ShadowRoot, stylesheetIds: string[]) {
+    if (!this.#isSupported()) return;
+
+    const sheets = stylesheetIds
+      .map((id) => this.#sheets.get(id)?.sheet)
+      .filter((s): s is CSSStyleSheet => s !== null);
+
+    // Include global sheets
+    const globalSheets = [...this.#sheets.values()].filter((e) => e.isGlobal).map((e) => e.sheet);
+
+    shadowRoot.adoptedStyleSheets = [...globalSheets, ...sheets];
+  }
+
+  /** Removes a consumer from all its stylesheets. */
+  removeConsumer(consumer: string) {
+    for (const [id, entry] of this.#sheets.entries()) {
+      entry.consumers.delete(consumer);
+
+      // Clean up orphaned non-global stylesheets
+      if (!entry.isGlobal && entry.consumers.size === 0) {
+        this.#sheets.delete(id);
+      }
+    }
+  }
+
+  /** Clears all stylesheets. */
+  clear() {
+    this.#sheets.clear();
+    if (this.#isSupported()) {
+      document.adoptedStyleSheets = [];
+    }
+  }
+
+  // ========== Private Methods ==========
+
+  #adoptToDocument(sheet: CSSStyleSheet) {
+    if (!this.#documentSheets.includes(sheet)) {
+      this.#documentSheets.push(sheet);
+      document.adoptedStyleSheets = [...this.#documentSheets];
+    }
+  }
+
+  #isSupported() {
+    return supportsConstructableStylesheets();
+  }
+
+  #hash(css: string) {
+    let hash = 0;
+    for (let i = 0; i < css.length; i++) {
+      const char = css.charCodeAt(i);
+      hash = ((hash << 5) - hash + char) | 0;
+    }
+    return hash.toString(36);
+  }
+
+  #canIncrementalUpdate(oldCss: string, newCss: string) {
+    // Only do incremental updates for small changes
+    const sizeDiff = Math.abs(newCss.length - oldCss.length);
+    return sizeDiff < 500;
+  }
+
+  #incrementalUpdate(sheet: CSSStyleSheet, _oldCss: string, newCss: string) {
+    // Simple diff:  find changed rules
+    // In practice, you'd use a proper CSS parser for this
+    // For now, fall back to replaceSync
+    sheet.replaceSync(newCss);
+  }
+
+  #injectStyleElement(id: string, css: string) {
+    // Fallback for browsers without Constructable Stylesheets
+    let style = document.getElementById(`sf-style-${id}`) as HTMLStyleElement;
+
+    if (!style) {
+      style = document.createElement("style");
+      style.id = `sf-style-${id}`;
+      document.head.appendChild(style);
+    }
+
+    style.textContent = css;
+  }
+}
+
+/** Global stylesheet manager instance. */
+export const stylesheets = new StylesheetManager();
+
+// Export for testing
+export { StylesheetManager };