@k2b/ssr 0.12.0-rc.0

package/src/island-id.ts

@@ -0,0 +1,78 @@
+/**
+ * Stable island ID generation based on canonical file paths.
+ * IDs are deterministic for file-based imports and robust in monorepos.
+ */
+import { realpathSync } from "fs";
+import { isAbsolute, relative, resolve } from "path";
+
+/** Length of hashed island IDs used in data-id and generated chunk filenames */
+export const ISLAND_ID_LENGTH = 12;
+
+const canonicalFileCache = new Map<string, string>();
+const canonicalRootCache = new Map<string, string>();
+
+const toPosixPath = (value: string): string => value.replace(/\\/g, "/");
+
+/**
+ * Short deterministic hash helper used for island IDs.
+ */
+export const hash = (value: string): string =>
+  new Bun.CryptoHasher("md5").update(value).digest("hex").slice(0, ISLAND_ID_LENGTH);
+
+/**
+ * Canonicalize file path for stable hashing.
+ * Falls back to resolve() when realpath cannot be resolved.
+ */
+export const canonicalFilePath = (file: string): string => {
+  const absolutePath = resolve(file);
+  const cached = canonicalFileCache.get(absolutePath);
+  if (cached) return cached;
+
+  let canonical = absolutePath;
+  try {
+    canonical = realpathSync(absolutePath);
+  } catch {
+    // Keep resolved absolute path when the file does not exist yet.
+  }
+
+  const normalized = toPosixPath(canonical);
+  canonicalFileCache.set(absolutePath, normalized);
+  return normalized;
+};
+
+const canonicalRootPath = (rootDir: string): string => {
+  const absolutePath = resolve(rootDir);
+  const cached = canonicalRootCache.get(absolutePath);
+  if (cached) return cached;
+
+  let canonical = absolutePath;
+  try {
+    canonical = realpathSync(absolutePath);
+  } catch {
+    // Keep resolved absolute path when the directory does not exist yet.
+  }
+
+  const normalized = toPosixPath(canonical);
+  canonicalRootCache.set(absolutePath, normalized);
+  return normalized;
+};
+
+/**
+ * Convert file path to a stable key:
+ * - relative to rootDir when inside rootDir
+ * - otherwise canonical absolute path
+ */
+export const toStableKey = (file: string, rootDir: string): string => {
+  const canonicalFile = canonicalFilePath(file);
+  const root = canonicalRootPath(rootDir);
+  const rel = toPosixPath(relative(root, canonicalFile));
+  const isWithinRoot = !isAbsolute(rel) && rel !== ".." && !rel.startsWith("../");
+
+  return isWithinRoot ? rel : canonicalFile;
+};
+
+/**
+ * Build final stable island ID from canonical path key.
+ */
+export const islandIdFromFile = (file: string, rootDir: string): string =>
+  hash(toStableKey(file, rootDir));

package/src/island-resolve.ts

@@ -0,0 +1,39 @@
+import { dirname, isAbsolute, resolve } from "path";
+
+const hasScriptExtension = (value: string): boolean => /\.(tsx|jsx|ts|js)$/.test(value);
+
+export const withDefaultIslandExtension = (specifier: string): string =>
+  hasScriptExtension(specifier) ? specifier : `${specifier}.tsx`;
+
+const formatResolveError = (specifier: string, resolveDir: string, importer?: string, reason?: string): Error => {
+  const importerHint = importer ? ` from "${importer}"` : "";
+  const detail = reason ? `\nReason: ${reason}` : "";
+  return new Error(
+    `[ssr] Failed to resolve island/client import "${specifier}"${importerHint} using resolveDir "${resolveDir}".` +
+      `\nCheck your tsconfig paths/baseUrl (for aliases) or use a relative/absolute file import.${detail}`,
+  );
+};
+
+export const resolveIslandImport = (specifier: string, resolveDir: string, importer?: string): string => {
+  const normalizedSpecifier = withDefaultIslandExtension(specifier);
+  const normalizedResolveDir = resolveDir || (importer ? dirname(importer) : process.cwd());
+
+  if (specifier.startsWith(".")) {
+    return resolve(normalizedResolveDir, normalizedSpecifier);
+  }
+
+  if (isAbsolute(specifier)) {
+    return resolve(normalizedSpecifier);
+  }
+
+  try {
+    const resolved = Bun.resolveSync(normalizedSpecifier, normalizedResolveDir);
+    if (!isAbsolute(resolved)) {
+      throw formatResolveError(specifier, normalizedResolveDir, importer, `resolved to non-absolute path "${resolved}"`);
+    }
+    return resolved;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw formatResolveError(specifier, normalizedResolveDir, importer, reason);
+  }
+};

package/src/nav.ts

@@ -0,0 +1,308 @@
+/**
+ * Opt-in browser navigation helpers for SSR islands.
+ *
+ * This is not a router. Links remain real anchors and apps decide whether an
+ * enhanced click can update client state before committing browser history.
+ */
+import { mergeProps, splitProps, type JSX } from "solid-js";
+import { createDynamic } from "solid-js/web";
+
+type AnchorProps = JSX.AnchorHTMLAttributes<HTMLAnchorElement>;
+
+export type NavigationScrollMode = "top" | "preserve" | "manual";
+
+export type ScrollSnapshot = {
+  window: { x: number; y: number };
+  regions: Array<{
+    key: string;
+    x: number;
+    y: number;
+  }>;
+};
+
+export type EnhancedNavigateOptions = {
+  replace?: boolean;
+  scroll?: NavigationScrollMode;
+  scrollSnapshot?: ScrollSnapshot;
+  state?: unknown;
+  viewTransition?: boolean;
+};
+
+export type PopStateNavigationEvent = {
+  event: PopStateEvent;
+  url: URL;
+  state: unknown;
+};
+
+export type LinkNavigateEvent = {
+  event: MouseEvent;
+  href: string;
+  url: URL;
+  replace: boolean;
+  scroll: NavigationScrollMode;
+  push: (href?: string, options?: EnhancedNavigateOptions) => void;
+  replaceWith: (href?: string, options?: Omit<EnhancedNavigateOptions, "replace">) => void;
+  fallback: (href?: string) => void;
+  scrollSnapshot: ScrollSnapshot;
+  captureScroll: (selector?: string) => ScrollSnapshot;
+  restoreScroll: typeof restoreScroll;
+};
+
+export type LinkProps = Omit<AnchorProps, "href" | "onClick"> & {
+  href: string;
+  replace?: boolean;
+  scroll?: NavigationScrollMode;
+  onClick?: JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent>;
+  onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
+};
+
+const SCROLL_PRESERVE_SELECTOR = "[data-scroll-preserve]";
+
+type ViewTransitionDocument = Document & {
+  startViewTransition?: (callback: () => void | Promise<void>) => unknown;
+};
+
+/**
+ * Returns the current URL path + query, without the hash.
+ */
+export const currentPathWithQuery = (): string => {
+  const url = new URL(window.location.href);
+  return `${url.pathname}${url.search}`;
+};
+
+/**
+ * Navigates to the current path + query with a full document navigation.
+ */
+export const refreshCurrentPath = (): void => {
+  window.location.assign(currentPathWithQuery());
+};
+
+/**
+ * Navigates with a full document navigation.
+ */
+export const navigateTo = (href: string): void => {
+  window.location.assign(href);
+};
+
+export const startViewTransition = (callback: () => void | Promise<void>): void => {
+  const doc = document as ViewTransitionDocument;
+  if (!doc.startViewTransition) {
+    void callback();
+    return;
+  }
+  doc.startViewTransition(callback);
+};
+
+const restoreRegionScroll = (snapshot: ScrollSnapshot): void => {
+  for (const region of snapshot.regions) {
+    const selector = `[data-scroll-preserve="${CSS.escape(region.key)}"]`;
+    const el = document.querySelector<HTMLElement>(selector);
+    if (!el) continue;
+    el.scrollLeft = region.x;
+    el.scrollTop = region.y;
+  }
+};
+
+/**
+ * Captures window scroll and keyed `[data-scroll-preserve]` regions.
+ */
+export const captureScroll = (selector = SCROLL_PRESERVE_SELECTOR): ScrollSnapshot => ({
+  window: { x: window.scrollX, y: window.scrollY },
+  regions: Array.from(document.querySelectorAll<HTMLElement>(selector))
+    .map((el) => ({
+      key: el.dataset.scrollPreserve ?? "",
+      x: el.scrollLeft,
+      y: el.scrollTop,
+    }))
+    .filter((region) => region.key.length > 0),
+});
+
+/**
+ * Restores a captured scroll snapshot.
+ */
+export const restoreScroll = (snapshot: ScrollSnapshot, options: { window?: boolean } = {}): void => {
+  restoreRegionScroll(snapshot);
+  if (options.window === false) return;
+  window.scrollTo(snapshot.window.x, snapshot.window.y);
+};
+
+/**
+ * Subscribes to browser Back/Forward navigation.
+ *
+ * The application remains responsible for reconciling its island state with
+ * the URL. This helper intentionally does not perform route matching.
+ */
+export const listenPopState = (handler: (navigation: PopStateNavigationEvent) => void): (() => void) => {
+  const listener = (event: PopStateEvent) => {
+    handler({ event, url: new URL(window.location.href), state: event.state });
+  };
+
+  window.addEventListener("popstate", listener);
+  return () => window.removeEventListener("popstate", listener);
+};
+
+const resolveNavigationUrl = (href: string): URL =>
+  new URL(href, document.baseURI || window.location.href);
+
+/**
+ * Updates browser history without a document reload.
+ *
+ * Use this after the current island has already updated its UI or when it is
+ * intentionally preserving the current DOM. It does not match routes, load
+ * data, or re-render server pages.
+ */
+export const navigate = (href: string, options: EnhancedNavigateOptions = {}): void => {
+  const url = resolveNavigationUrl(href);
+  if (url.origin !== window.location.origin) {
+    documentNavigate(url.href, { replace: options.replace });
+    return;
+  }
+
+  const scroll = options.scroll ?? "top";
+  const snapshot = scroll === "manual" ? null : (options.scrollSnapshot ?? captureScroll());
+  const target = `${url.pathname}${url.search}${url.hash}`;
+
+  const commit = () => {
+    const hasExplicitState = Object.prototype.hasOwnProperty.call(options, "state");
+    const state = hasExplicitState ? options.state : options.replace ? window.history.state : null;
+
+    if (options.replace) window.history.replaceState(state, "", target);
+    else window.history.pushState(state, "", target);
+
+    if (!snapshot) return;
+    restoreRegionScroll(snapshot);
+    if (scroll === "preserve") {
+      window.scrollTo(snapshot.window.x, snapshot.window.y);
+      return;
+    }
+    window.scrollTo(0, 0);
+  };
+
+  if (options.viewTransition === false) {
+    commit();
+    return;
+  }
+  startViewTransition(commit);
+};
+
+export const documentNavigate = (href: string, options: { replace?: boolean } = {}): void => {
+  if (options.replace) window.location.replace(href);
+  else window.location.assign(href);
+};
+
+const shouldEnhanceClick = (event: MouseEvent, anchor: HTMLAnchorElement): boolean => {
+  if (event.defaultPrevented || event.button !== 0) return false;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false;
+  if (anchor.target && anchor.target !== "_self") return false;
+  if (anchor.hasAttribute("download")) return false;
+
+  const url = new URL(anchor.href);
+  return url.origin === window.location.origin;
+};
+
+const isSameDocumentHash = (url: URL): boolean => {
+  const current = new URL(window.location.href);
+  return url.hash.length > 0 && url.pathname === current.pathname && url.search === current.search;
+};
+
+const callUserClick = (handler: LinkProps["onClick"], event: MouseEvent, anchor: HTMLAnchorElement): void => {
+  if (!handler) return;
+  const typedEvent = event as MouseEvent & { currentTarget: HTMLAnchorElement; target: Element };
+
+  if (Array.isArray(handler)) {
+    handler[0].call(anchor, handler[1], typedEvent);
+    return;
+  }
+
+  if (typeof handler === "function") {
+    handler.call(anchor, typedEvent);
+  }
+};
+
+/**
+ * SSR-safe anchor with opt-in progressive navigation.
+ */
+export function Link(props: LinkProps) {
+  const [local, anchorProps] = splitProps(props, ["href", "replace", "scroll", "onNavigate", "onClick"]);
+
+  const handleClick: JSX.EventHandler<HTMLAnchorElement, MouseEvent> = (event) => {
+    callUserClick(local.onClick, event, event.currentTarget);
+    if (!shouldEnhanceClick(event, event.currentTarget)) return;
+
+    const href = local.href;
+    const url = new URL(event.currentTarget.href);
+
+    // Preserve native target scrolling unless the application explicitly owns
+    // this hash navigation through onNavigate or a scroll option.
+    if (!local.onNavigate && local.scroll === undefined && isSameDocumentHash(url)) return;
+
+    const scroll = local.scroll ?? "top";
+    const replace = Boolean(local.replace);
+    const scrollSnapshot = captureScroll();
+
+    event.preventDefault();
+
+    if (!local.onNavigate) {
+      navigate(url.href, { replace, scroll, scrollSnapshot });
+      return;
+    }
+
+    let navigationOutcome: "none" | "history" | "document" = "none";
+    const runNavigation = async () => {
+      try {
+        await local.onNavigate!({
+          event,
+          href,
+          url,
+          replace,
+          scroll,
+          push: (nextHref = url.href, options = {}) => {
+            navigate(nextHref, {
+              ...options,
+              replace: false,
+              scroll: options.scroll ?? scroll,
+              scrollSnapshot: options.scrollSnapshot ?? scrollSnapshot,
+              viewTransition: false,
+            });
+            navigationOutcome = "history";
+          },
+          replaceWith: (nextHref = url.href, options = {}) => {
+            navigate(nextHref, {
+              ...options,
+              replace: true,
+              scroll: options.scroll ?? scroll,
+              scrollSnapshot: options.scrollSnapshot ?? scrollSnapshot,
+              viewTransition: false,
+            });
+            navigationOutcome = "history";
+          },
+          fallback: (nextHref = url.href) => {
+            documentNavigate(resolveNavigationUrl(nextHref).href, { replace });
+            navigationOutcome = "document";
+          },
+          scrollSnapshot,
+          captureScroll,
+          restoreScroll,
+        });
+      } catch (error) {
+        console.error("[@k2b/ssr/nav] onNavigate failed; falling back to document navigation.", error);
+        if (navigationOutcome === "document") return;
+        const historyCommitted = navigationOutcome === "history";
+        const fallbackHref = historyCommitted ? window.location.href : url.href;
+        documentNavigate(fallbackHref, { replace: historyCommitted || replace });
+      }
+    };
+
+    startViewTransition(runNavigation);
+  };
+
+  return createDynamic(
+    () => "a",
+    mergeProps(anchorProps, {
+      get href() {
+        return local.href;
+      },
+      onClick: handleClick,
+    }),
+  );
+}

package/src/transform.ts

@@ -0,0 +1,157 @@
+/**
+ * Babel transform for SSR - wraps island/client components in custom elements
+ * with serialized props. Handles both SSR (server) and DOM (client) modes.
+ */
+import { transformAsync, types as t } from "@babel/core";
+// @ts-ignore - no types are available for this package
+import solidPreset from "babel-preset-solid";
+// @ts-ignore - no types are available for this package
+import tsPreset from "@babel/preset-typescript";
+import { dirname } from "path";
+import { islandIdFromFile } from "./island-id";
+import { resolveIslandImport } from "./island-resolve";
+
+export { hash } from "./island-id";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+// JSX AST helpers
+const jsx = (tag: string, attrs: any[], children: any[] = []) =>
+  t.jsxElement(
+    t.jsxOpeningElement(t.jsxIdentifier(tag), attrs, children.length === 0),
+    children.length ? t.jsxClosingElement(t.jsxIdentifier(tag)) : null,
+    children,
+    children.length === 0,
+  );
+
+const attr = (name: string, value: any) =>
+  t.jsxAttribute(
+    t.jsxIdentifier(name),
+    typeof value === "string" ? t.stringLiteral(value) : t.jsxExpressionContainer(value),
+  );
+
+// ============================================================================
+// Babel Plugin - Wraps island/client components
+// ============================================================================
+
+type ComponentType = "island" | "client";
+
+const getComponentType = (path: string): ComponentType | null =>
+  path.includes(".island") ? "island" : path.includes(".client") ? "client" : null;
+
+const componentWrapperPlugin = (filename: string, rootDir: string, dev: boolean) => {
+  const parentType = getComponentType(filename);
+
+  return {
+    visitor: {
+      Program(programPath: any) {
+        const componentImports = new Map<string, { path: string; type: ComponentType; id: string }>();
+
+        // Inject seroval serialize helper at the top
+        programPath.node.body.unshift(
+          t.importDeclaration(
+            [t.importSpecifier(t.identifier("serialize"), t.identifier("serialize"))],
+            t.stringLiteral("seroval"),
+          ),
+          t.variableDeclaration("const", [
+            t.variableDeclarator(t.identifier("__seroval_serialize"), t.identifier("serialize")),
+          ]),
+        );
+
+        programPath.traverse({
+          ImportDeclaration(path: any) {
+            const source: string = path.node.source.value;
+            const type = getComponentType(source);
+            if (!type) return;
+
+            if (parentType) {
+              console.warn(
+                `[ssr] Warning: ${parentType} imports ${type} (${source}) - nested islands/clients are not supported`,
+              );
+            }
+
+            const spec = path.node.specifiers.find((s: any) => s.type === "ImportDefaultSpecifier");
+            if (!spec) return;
+
+            const resolvedPath = resolveIslandImport(source, dirname(filename), filename);
+            const componentPath = resolvedPath;
+            const id = islandIdFromFile(resolvedPath, rootDir);
+
+            componentImports.set(spec.local.name, { path: componentPath, type, id });
+          },
+
+          JSXElement(path: any) {
+            const name = path.node.openingElement.name.name;
+            const component = componentImports.get(name);
+            if (!component) return;
+
+            const wrapperTag = component.type === "island" ? "solid-island" : "solid-client";
+
+            const props = t.objectExpression(
+              path.node.openingElement.attributes
+                .filter((a: any) => a.type === "JSXAttribute")
+                .map((a: any) =>
+                  t.objectProperty(
+                    t.identifier(a.name.name),
+                    a.value?.type === "JSXExpressionContainer" ? a.value.expression : a.value || t.booleanLiteral(true),
+                  ),
+                ),
+            );
+
+            // For islands: wrap the component, for client: empty wrapper (no SSR)
+            const children = component.type === "island" ? [path.node] : [];
+
+            // Extract filename from path (e.g., "Counter.island.tsx")
+            const file = component.path.split("/").pop() || "";
+
+            const attrs = [
+              attr("data-id", component.id),
+              attr("data-props", t.callExpression(t.identifier("__seroval_serialize"), [props])),
+            ];
+
+            // Add file attribute in dev mode
+            if (dev) {
+              attrs.push(attr("data-file", file));
+            }
+
+            const wrapper = jsx(wrapperTag, attrs, children);
+
+            path.replaceWith(wrapper);
+            path.skip();
+          },
+        });
+
+        // Client wrappers remove their original JSX usage. Refresh bindings so
+        // later presets can discard imports that became unused in this pass.
+        programPath.scope.crawl();
+      },
+    },
+  };
+};
+
+// ============================================================================
+// Transform function
+// ============================================================================
+
+export const transform = async (
+  source: string,
+  filename: string,
+  mode: "ssr" | "dom",
+  dev: boolean = false,
+  rootDir: string = process.cwd(),
+): Promise<string> => {
+  const result = await transformAsync(source, {
+    filename,
+    parserOpts: mode === "ssr" ? { plugins: ["jsx", "typescript"] } : undefined,
+    plugins: mode === "ssr" ? [() => componentWrapperPlugin(filename, rootDir, dev)] : [],
+    presets: [
+      [tsPreset, {}],
+      [solidPreset, { generate: mode, hydratable: false }],
+    ],
+  });
+
+  if (!result?.code) throw new Error(`Transform failed: ${filename}`);
+  return result.code;
+};