@tyndall/dev 0.0.1

package/README.md

@@ -0,0 +1,37 @@
+# @tyndall/dev
+
+## Overview
+Development server package with watcher integration, route rendering, and HMR transport orchestration.
+
+## Responsibilities
+- Serve development routes and public assets
+- Coordinate file invalidation and route cache invalidation
+- Broadcast HMR updates and dev errors
+- Surface dev/runtime failures through structured console logging with configurable severity
+- Support SSR-first entry with optional client-side navigation takeover via bootstrap policy
+- Emit adapter-driven client runtime scripts for route hydration in dev mode
+- Serve route runtime chunk assets (`/_hyper/dev-client/*`) so client route modules can load on demand after navigation
+- Preserve hydration during HMR fallback by applying route payload updates through a mounted-root-safe rerender bridge
+- Filter broad `routesDir` scans so internal artifacts (`.hyper`, cache, `node_modules`, `outDir`, `.git`) never become file routes
+- Stabilize Bun dev runtime bundling by aliasing critical React/runtime dependencies to cache-local concrete files (not workspace symlink paths)
+- Track nested layout files as route dependencies for dev snapshotting and HMR invalidation
+- Inject build version metadata into dev HTML when configured
+
+## Public API Highlights
+- startDevServer
+- createFileWatcher
+- createHmrServer
+
+## Development
+- Build: bun run --filter @tyndall/dev build
+- Test (from workspace root): bun test
+
+## Documentation
+- Package specification: [spec.md](./spec.md)
+- Package architecture: [architecture.md](./architecture.md)
+- Package changes: [CHANGELOG.md](./CHANGELOG.md)
+
+## Maintenance Rules
+- Keep this document aligned with implemented package behavior.
+- Update spec.md and architecture.md whenever package contracts or design boundaries change.
+- Record user-visible package changes in CHANGELOG.md.

package/dist/hmr.d.ts

@@ -0,0 +1,57 @@
+import type { Server } from "node:http";
+export declare const HMR_WS_PATH = "/__hyper_hmr";
+export declare const HMR_CLIENT_PATH = "/_hyper/hmr.js";
+export type HmrMessage = {
+    type: "connected";
+    sessionId: string;
+    timestamp: number;
+} | {
+    type: "full-reload";
+    paths?: string[];
+    routes?: string[];
+    timestamp: number;
+} | {
+    type: "css-update";
+    paths: string[];
+    timestamp: number;
+} | {
+    type: "react-refresh";
+    paths?: string[];
+    routes?: string[];
+    timestamp: number;
+} | {
+    type: "error";
+    message: string;
+    stack?: string;
+    timestamp: number;
+};
+export interface HmrServer {
+    path: string;
+    broadcast: (message: HmrMessage) => void;
+    broadcastFullReload: (paths?: string[], routes?: string[]) => void;
+    broadcastCssUpdate: (paths: string[]) => void;
+    broadcastReactRefresh: (paths?: string[], routes?: string[]) => void;
+    broadcastError: (message: string, stack?: string) => void;
+    clientCount: () => number;
+    close: () => void;
+}
+export interface WebSocketLike {
+    readyState: number;
+    send: (payload: string) => void;
+    close: () => void;
+    on: (event: "close" | "error", handler: () => void) => void;
+}
+export interface WebSocketServerLike {
+    on: (event: "connection", handler: (socket: WebSocketLike) => void) => void;
+    close: () => void;
+}
+export interface HmrServerOptions {
+    path?: string;
+    createWebSocketServer?: (server: Server, path: string) => WebSocketServerLike;
+}
+export declare const createHmrServer: (server: Server, options?: HmrServerOptions) => HmrServer;
+export interface HmrClientScriptOptions {
+    wsPath?: string;
+}
+export declare const getHmrClientScript: (options?: HmrClientScriptOptions) => string;
+//# sourceMappingURL=hmr.d.ts.map

package/dist/hmr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr.d.ts","sourceRoot":"","sources":["../src/hmr.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAC1C,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IACzC,mBAAmB,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACnE,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC9C,qBAAqB,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACrE,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,KAAK,IAAI,CAAC;IAC5E,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,mBAAmB,CAAC;CAC/E;AAED,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,EAAE,UAAS,gBAAqB,KAAG,SA6EhF,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,kBAAkB,GAAI,UAAS,sBAA2B,KAAG,MAuTzE,CAAC"}

package/dist/hmr.js

@@ -0,0 +1,384 @@
+import { randomUUID } from "node:crypto";
+import WebSocket, { WebSocketServer } from "ws";
+export const HMR_WS_PATH = "/__hyper_hmr";
+export const HMR_CLIENT_PATH = "/_hyper/hmr.js";
+export const createHmrServer = (server, options = {}) => {
+    const path = options.path ?? HMR_WS_PATH;
+    const createWebSocketServer = options.createWebSocketServer ??
+        ((srv, wsPath) => new WebSocketServer({
+            server: srv,
+            path: wsPath,
+        }));
+    const wss = createWebSocketServer(server, path);
+    const clients = new Set();
+    const openState = WebSocket.OPEN ?? 1;
+    wss.on("connection", (socket) => {
+        clients.add(socket);
+        socket.on("close", () => clients.delete(socket));
+        socket.on("error", () => clients.delete(socket));
+        const sessionId = randomUUID();
+        const payload = JSON.stringify({
+            type: "connected",
+            sessionId,
+            timestamp: Date.now(),
+        });
+        if (socket.readyState === openState) {
+            socket.send(payload);
+        }
+    });
+    const broadcast = (message) => {
+        const payload = JSON.stringify(message);
+        for (const socket of clients) {
+            if (socket.readyState === openState) {
+                socket.send(payload);
+            }
+        }
+    };
+    return {
+        path,
+        broadcast,
+        broadcastFullReload: (paths, routes) => broadcast({
+            type: "full-reload",
+            paths,
+            routes,
+            timestamp: Date.now(),
+        }),
+        broadcastCssUpdate: (paths) => broadcast({
+            type: "css-update",
+            paths,
+            timestamp: Date.now(),
+        }),
+        broadcastReactRefresh: (paths, routes) => broadcast({
+            type: "react-refresh",
+            paths,
+            routes,
+            timestamp: Date.now(),
+        }),
+        broadcastError: (message, stack) => broadcast({
+            type: "error",
+            message,
+            stack,
+            timestamp: Date.now(),
+        }),
+        clientCount: () => Array.from(clients).filter((socket) => socket.readyState === WebSocket.OPEN).length,
+        close: () => {
+            for (const socket of clients) {
+                socket.close();
+            }
+            clients.clear();
+            wss.close();
+        },
+    };
+};
+export const getHmrClientScript = (options = {}) => {
+    const wsPath = options.wsPath ?? HMR_WS_PATH;
+    return `(() => {
+  if (window.__HYPER_HMR__) return;
+  window.__HYPER_HMR__ = true;
+
+  const wsPath = ${JSON.stringify(wsPath)};
+  const protocol = location.protocol === "https:" ? "wss" : "ws";
+  const socketUrl = protocol + "://" + location.host + wsPath;
+
+  const log = (...args) => console.log("[hyper-hmr]", ...args);
+  const warn = (...args) => console.warn("[hyper-hmr]", ...args);
+  const resolveRouteId = () => {
+    const direct = window.__HYPER_ROUTE_ID__;
+    if (typeof direct === "string") {
+      return direct;
+    }
+    const el = document.querySelector("[data-hyper-route]");
+    if (el) {
+      return el.getAttribute("data-hyper-route");
+    }
+    return null;
+  };
+  const shouldApply = (message) => {
+    if (message && Array.isArray(message.routes) && message.routes.length > 0) {
+      const current = resolveRouteId();
+      if (!current) {
+        return true;
+      }
+      return message.routes.includes(current);
+    }
+    return true;
+  };
+
+  const ensureOverlay = () => {
+    let overlay = document.getElementById("hyper-error-overlay");
+    if (overlay) return overlay;
+    overlay = document.createElement("div");
+    overlay.id = "hyper-error-overlay";
+    overlay.style.position = "fixed";
+    overlay.style.inset = "0";
+    overlay.style.background = "rgba(0, 0, 0, 0.85)";
+    overlay.style.color = "#f8f8f2";
+    overlay.style.fontFamily = "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace";
+    overlay.style.fontSize = "13px";
+    overlay.style.lineHeight = "1.5";
+    overlay.style.zIndex = "99999";
+    overlay.style.padding = "24px";
+    overlay.style.display = "none";
+    overlay.style.overflow = "auto";
+    document.body.appendChild(overlay);
+    return overlay;
+  };
+
+  const showErrorOverlay = (message, stack) => {
+    const overlay = ensureOverlay();
+    overlay.innerHTML = "";
+    const title = document.createElement("div");
+    title.textContent = "Hyper Dev Error";
+    title.style.fontWeight = "600";
+    title.style.marginBottom = "12px";
+    const body = document.createElement("div");
+    body.textContent = message || "Unknown error";
+    body.style.marginBottom = "12px";
+    overlay.appendChild(title);
+    overlay.appendChild(body);
+    if (stack) {
+      const pre = document.createElement("pre");
+      pre.textContent = stack;
+      pre.style.whiteSpace = "pre-wrap";
+      overlay.appendChild(pre);
+    }
+    overlay.style.display = "block";
+  };
+
+  const clearErrorOverlay = () => {
+    const overlay = document.getElementById("hyper-error-overlay");
+    if (overlay) {
+      overlay.style.display = "none";
+      overlay.innerHTML = "";
+    }
+  };
+
+  const installRefreshHooks = () => {
+    const runtime = window.$RefreshRuntime$ || window.__REACT_REFRESH_RUNTIME__;
+    if (!runtime) {
+      window.$RefreshReg$ = () => {};
+      window.$RefreshSig$ = () => (type) => type;
+      return;
+    }
+    if (runtime.injectIntoGlobalHook) {
+      runtime.injectIntoGlobalHook(window);
+    }
+    window.$RefreshReg$ = (type, id) => runtime.register?.(type, id);
+    window.$RefreshSig$ =
+      runtime.createSignatureFunctionForTransform?.bind(runtime) || (() => (type) => type);
+  };
+
+  const updateStyles = (paths) => {
+    const links = Array.from(document.querySelectorAll('link[rel="stylesheet"]'));
+    for (const path of paths) {
+      for (const link of links) {
+        const href = link.getAttribute("href");
+        if (!href || !href.includes(path)) continue;
+        const url = new URL(href, location.origin);
+        url.searchParams.set("t", String(Date.now()));
+        link.setAttribute("href", url.toString());
+      }
+    }
+  };
+
+  const performReactRefresh = () => {
+    const runtime = window.$RefreshRuntime$ || window.__REACT_REFRESH_RUNTIME__;
+    if (runtime && typeof runtime.performReactRefresh === "function") {
+      runtime.performReactRefresh();
+      return true;
+    }
+    return false;
+  };
+
+  const HEAD_ATTR = "data-hyper-head";
+  const ROUTE_PAYLOAD_EVENT = "hyper:route-payload-applied";
+  const removeManagedHead = () => {
+    const head = document.head;
+    if (!head) {
+      return;
+    }
+    const managed = head.querySelectorAll('[' + HEAD_ATTR + ']');
+    for (const node of managed) {
+      node.remove();
+    }
+  };
+  const appendHeadEntries = (tag, entries) => {
+    if (!Array.isArray(entries)) {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry || typeof entry !== "object") {
+        continue;
+      }
+      const element = document.createElement(tag);
+      for (const [key, value] of Object.entries(entry)) {
+        element.setAttribute(key, String(value));
+      }
+      element.setAttribute(HEAD_ATTR, "");
+      document.head.appendChild(element);
+    }
+  };
+  const applyHeadDescriptor = (descriptor) => {
+    if (!descriptor || typeof descriptor !== "object") {
+      return;
+    }
+    if (typeof descriptor.title === "string") {
+      document.title = descriptor.title;
+    }
+    removeManagedHead();
+    appendHeadEntries("meta", descriptor.meta);
+    appendHeadEntries("link", descriptor.link);
+    appendHeadEntries("script", descriptor.script);
+  };
+  const applyRoutePayload = (payload, message) => {
+    if (
+      !payload ||
+      payload.kind !== "hyper-route-payload" ||
+      typeof payload.routeId !== "string" ||
+      typeof payload.appHtml !== "string" ||
+      typeof payload.propsPayload !== "string"
+    ) {
+      return false;
+    }
+    const app = document.getElementById("app");
+    const hasMountedClientApp =
+      payload.hydration !== "islands" && Boolean(window.__HYPER_CLIENT_APP_MOUNTED__);
+    if (app) {
+      // Keep React-owned root stable: mounted full hydration root should rerender via event bridge.
+      if (!hasMountedClientApp) {
+        app.innerHTML = payload.appHtml;
+      }
+      app.setAttribute("data-hyper-route", payload.routeId);
+      app.setAttribute("data-hyper-hydrated", "false");
+      if (payload.hydration === "islands" || payload.hydration === "full") {
+        app.setAttribute("data-hyper-hydration", payload.hydration);
+        if (payload.hydration === "islands") {
+          app.setAttribute("data-hyper-island-root", "router");
+        } else {
+          app.removeAttribute("data-hyper-island-root");
+        }
+      }
+    }
+    const propsScript = document.getElementById("__HYPER_PROPS__");
+    if (propsScript) {
+      propsScript.textContent = payload.propsPayload;
+    }
+    applyHeadDescriptor(payload.head);
+    window.__HYPER_ROUTE_ID__ = payload.routeId;
+    window.__HYPER_HYDRATED__ = false;
+    try {
+      window.dispatchEvent(
+        new CustomEvent(ROUTE_PAYLOAD_EVENT, {
+          detail: {
+            routeId: payload.routeId,
+            paths: Array.isArray(message?.paths) ? message.paths : undefined,
+            routes: Array.isArray(message?.routes) ? message.routes : undefined,
+            source: "hmr",
+          },
+        }),
+      );
+    } catch {
+      // Keep HMR fallback resilient when event APIs are unavailable.
+    }
+    return true;
+  };
+  const loadRuntimeEntry = async (scriptPath) => {
+    if (typeof scriptPath !== "string" || scriptPath.length === 0) {
+      return true;
+    }
+    try {
+      const url = new URL(scriptPath, location.origin);
+      url.searchParams.set("hmr", String(Date.now()));
+      await import(url.toString());
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const refreshCurrentRoute = async (message) => {
+    try {
+      const response = await fetch(location.href, {
+        method: "GET",
+        headers: {
+          "x-hyper-navigation": "csr",
+          accept: "application/json",
+        },
+      });
+      if (!response.ok) {
+        return false;
+      }
+      const contentType = response.headers.get("content-type") || "";
+      if (!contentType.includes("application/json")) {
+        return false;
+      }
+      const payload = await response.json();
+      const runtimeLoaded = await loadRuntimeEntry(payload?.clientRuntimeScriptPath);
+      if (!runtimeLoaded) {
+        return false;
+      }
+      return applyRoutePayload(payload, message);
+    } catch {
+      return false;
+    }
+  };
+
+  const handleMessage = (message) => {
+    switch (message?.type) {
+      case "connected":
+        log("connected", message.sessionId);
+        clearErrorOverlay();
+        return;
+      case "css-update":
+        if (Array.isArray(message.paths)) {
+          updateStyles(message.paths);
+        }
+        return;
+      case "react-refresh":
+        clearErrorOverlay();
+        if (!shouldApply(message)) {
+          return;
+        }
+        if (!performReactRefresh()) {
+          void refreshCurrentRoute(message).then((applied) => {
+            if (!applied) {
+              location.reload();
+            }
+          });
+        }
+        return;
+      case "full-reload":
+        if (!shouldApply(message)) {
+          return;
+        }
+        location.reload();
+        return;
+      case "error":
+        warn(message.message || "Unknown HMR error", message.stack || "");
+        showErrorOverlay(message.message, message.stack);
+        return;
+      default:
+        return;
+    }
+  };
+
+  const connect = () => {
+    const socket = new WebSocket(socketUrl);
+    socket.addEventListener("open", installRefreshHooks);
+    socket.addEventListener("message", (event) => {
+      try {
+        handleMessage(JSON.parse(event.data));
+      } catch (error) {
+        warn("Failed to parse HMR message", error);
+      }
+    });
+    socket.addEventListener("close", () => {
+      setTimeout(connect, 1000);
+    });
+    socket.addEventListener("error", () => {
+      socket.close();
+    });
+  };
+
+  connect();
+})();`;
+};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { type DynamicPageApiProvider, type ResolverFallbackPolicy, type UIAdapterRegistry } from "@tyndall/core";
+import type { Logger } from "@tyndall/shared";
+import { type HmrServer } from "./hmr.js";
+export { createFileWatcher } from "./watcher.js";
+export { createHmrServer, getHmrClientScript, HMR_CLIENT_PATH, HMR_WS_PATH } from "./hmr.js";
+export interface DevServerOptions {
+    port?: number;
+    host?: string;
+    open?: boolean;
+    ssr?: boolean;
+    rootDir?: string;
+    routesDir?: string;
+    publicDir?: string;
+    prefetchPath?: string;
+    dynamicPageApi?: DynamicPageApiProvider;
+    adapterRegistry?: UIAdapterRegistry;
+    fallbackPolicy?: ResolverFallbackPolicy;
+    logger?: Logger;
+}
+export interface DevServer {
+    host: string;
+    port: number;
+    url: string;
+    close: () => Promise<void>;
+    hmr?: HmrServer;
+    invalidate?: (paths: string[]) => void;
+}
+export declare const startDevServer: (options?: DevServerOptions) => Promise<DevServer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAaL,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAG3B,KAAK,iBAAiB,EAGvB,MAAM,eAAe,CAAC;AAWvB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAU9C,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE7F,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACxC;AA4WD,eAAO,MAAM,cAAc,GAAU,UAAS,gBAAqB,KAAG,OAAO,CAAC,SAAS,CAyyCtF,CAAC"}