@textjs/app 0.0.0-stage → 1.0.2

package/src/server/scan.ts

@@ -0,0 +1,190 @@
+/**
+ * File-system scanner for the `app/` directory (Node only).
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { flattenRoutes, matchAppRoutes, ROUTE_FILE_KINDS, type FlatRoute, type RouteFileKind, type RouteManifest, type RouteParams, type RouteSegmentNode } from "../routing";
+
+export const ROUTE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"] as const;
+
+export interface ScannedSegment {
+  segment: string;
+  dir: string;
+  /** Absolute file paths. */
+  files: Partial<Record<RouteFileKind, string>>;
+  /** Absolute `route.ts` path (API handler). */
+  route?: string;
+  children: ScannedSegment[];
+}
+
+export interface AppScan {
+  root: string;
+  appDir: string;
+  tree: ScannedSegment;
+}
+
+export function toPosix(p: string): string {
+  return sep === "\\" ? p.split(sep).join("/") : p;
+}
+
+function findFile(dir: string, base: string, entries: Set<string>): string | undefined {
+  for (const ext of ROUTE_EXTENSIONS) if (entries.has(base + ext)) return join(dir, base + ext);
+  return undefined;
+}
+
+function scanDir(dir: string, segment: string): ScannedSegment {
+  const entries = new Set(readdirSync(dir));
+  const files: Partial<Record<RouteFileKind, string>> = {};
+  for (const kind of ROUTE_FILE_KINDS) {
+    const f = findFile(dir, kind, entries);
+    if (f) files[kind] = f;
+  }
+  const node: ScannedSegment = { segment, dir, files, route: findFile(dir, "route", entries), children: [] };
+  for (const name of [...entries].sort()) {
+    if (name.startsWith(".") || name.startsWith("_") || name === "node_modules") continue;
+    const full = join(dir, name);
+    let isDir = false;
+    try {
+      isDir = statSync(full).isDirectory();
+    } catch {
+      continue;
+    }
+    if (isDir) node.children.push(scanDir(full, name));
+  }
+  return node;
+}
+
+/** Scan `<root>/<appDir>` into a segment tree. */
+export function scanApp(root: string, appDir = "app"): AppScan {
+  const dir = join(root, appDir);
+  if (!existsSync(dir)) return { root, appDir: dir, tree: { segment: "", dir, files: {}, children: [] } };
+  return { root, appDir: dir, tree: scanDir(dir, "") };
+}
+
+/** `true` when `file` is a route file the manifest depends on. */
+export function isRouteFile(file: string, appDir: string): boolean {
+  const rel = toPosix(relative(appDir, file));
+  if (rel.startsWith("..")) return false;
+  const base = rel.split("/").pop() ?? "";
+  const name = base.replace(/\.(tsx|ts|jsx|js)$/, "");
+  if (name === base) return false;
+  return (ROUTE_FILE_KINDS as readonly string[]).includes(name) || name === "route";
+}
+
+const FORCE_DYNAMIC = /export\s+const\s+dynamic\s*=\s*["']force-dynamic["']/;
+
+function isForceDynamicFile(file: string | undefined): boolean {
+  if (!file) return false;
+  try {
+    return FORCE_DYNAMIC.test(readFileSync(file, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/** A manifest with placeholder modules (for summaries and matching on the server). */
+export function toStaticManifest(scan: AppScan): RouteManifest {
+  const convert = (s: ScannedSegment): RouteSegmentNode => {
+    const node: RouteSegmentNode = { segment: s.segment, files: {} };
+    for (const kind of ROUTE_FILE_KINDS) {
+      const f = s.files[kind];
+      if (!f) continue;
+      const key = kind === "not-found" ? "notFound" : kind;
+      (node as unknown as Record<string, unknown>)[key] = isForceDynamicFile(f) ? { dynamic: "force-dynamic" } : {};
+      (node.files as Record<string, string>)[kind] = toPosix(relative(scan.root, f));
+    }
+    const children = s.children.map(convert).filter((c) => hasContent(c));
+    if (children.length > 0) node.children = children;
+    return node;
+  };
+  return convert(scan.tree);
+}
+
+function hasContent(n: RouteSegmentNode): boolean {
+  return Boolean(n.page || n.layout || n.loading || n.error || n.notFound || (n.children && n.children.length > 0));
+}
+
+export interface ApiRoute {
+  pattern: string;
+  file: string;
+}
+
+/** API route handlers as a manifest (route files stand in for pages). */
+export function toApiManifest(scan: AppScan): RouteManifest {
+  const convert = (s: ScannedSegment): RouteSegmentNode => {
+    const node: RouteSegmentNode = { segment: s.segment };
+    if (s.route) {
+      node.page = {};
+      node.files = { page: s.route };
+    }
+    const children = s.children.map(convert).filter((c) => c.page || (c.children && c.children.length > 0));
+    if (children.length > 0) node.children = children;
+    return node;
+  };
+  return convert(scan.tree);
+}
+
+export function listApiRoutes(scan: AppScan): ApiRoute[] {
+  return flattenRoutes(toApiManifest(scan)).map((r) => ({ pattern: r.pattern, file: r.file as string }));
+}
+
+export function matchApiRoute(api: RouteManifest, pathname: string): { file: string; params: RouteParams; pattern: string } | null {
+  const m = matchAppRoutes(api, pathname);
+  if (!m) return null;
+  const leaf = m.chain[m.chain.length - 1] as RouteSegmentNode;
+  const file = leaf.files?.page;
+  return file ? { file, params: m.params, pattern: m.pattern } : null;
+}
+
+export function listPages(scan: AppScan): FlatRoute[] {
+  return flattenRoutes(toStaticManifest(scan));
+}
+
+export interface GenerateOptions {
+  /** Emit `() => import()` for pages (code-split) instead of static imports. */
+  lazyPages?: boolean;
+  /** Add the self-accepting HMR footer. */
+  hmr?: boolean;
+}
+
+/** Generate the `virtual:textjs/routes` module source. */
+export function generateRoutesModule(scan: AppScan, options: GenerateOptions = {}): string {
+  const imports: string[] = [];
+  let n = 0;
+  const ref = (file: string, lazy: boolean): string => {
+    const spec = JSON.stringify(toPosix(file));
+    if (lazy) return `() => import(${spec})`;
+    const id = `m${n++}`;
+    imports.push(`import * as ${id} from ${spec};`);
+    return id;
+  };
+  const emit = (s: ScannedSegment, indent: string): string | null => {
+    const props: string[] = [`segment: ${JSON.stringify(s.segment)}`];
+    const files: string[] = [];
+    for (const kind of ROUTE_FILE_KINDS) {
+      const f = s.files[kind];
+      if (!f) continue;
+      const key = kind === "not-found" ? "notFound" : kind;
+      props.push(`${key}: ${ref(f, kind === "page" && options.lazyPages === true)}`);
+      files.push(`${JSON.stringify(kind)}: ${JSON.stringify(toPosix(relative(scan.root, f)))}`);
+    }
+    if (files.length > 0) props.push(`files: { ${files.join(", ")} }`);
+    const kids = s.children.map((c) => emit(c, `${indent}  `)).filter((c): c is string => c !== null);
+    if (kids.length > 0) props.push(`children: [\n${kids.map((k) => `${indent}  ${k}`).join(",\n")}\n${indent}]`);
+    if (files.length === 0 && kids.length === 0 && s.segment !== "") return null;
+    return `{ ${props.join(", ")} }`;
+  };
+  const body = emit(scan.tree, "") ?? `{ segment: "" }`;
+  const lines = [...imports, "", `export const routes = ${body};`, "export default routes;"];
+  if (options.hmr) {
+    lines.push(
+      "if (import.meta.hot) {",
+      "  import.meta.hot.accept((mod) => {",
+      "    if (mod && typeof window !== 'undefined' && window.__TEXTJS_APP__) window.__TEXTJS_APP__.updateRoutes(mod.routes);",
+      "  });",
+      "}",
+    );
+  }
+  return lines.join("\n");
+}

package/src/server/server-components.ts

@@ -0,0 +1,224 @@
+/**
+ * Async Server Components for server-rendered console routes.
+ *
+ * React's client reconciler (which the console renderer is) re-runs an
+ * `async function` component on every retry, creating a fresh promise each
+ * time, so it never settles. On the server, `text dev` / `text build` alias
+ * `react/jsx-runtime` to {@link ./jsx-runtime}, which swaps every async
+ * component for a wrapper that memoizes its promise per session, navigation
+ * and props, then unwraps it with `use()` (suspending to the nearest
+ * `<Suspense>` / `loading.tsx` meanwhile). The data access stays on the server:
+ * these modules never ship to the frame player.
+ */
+
+import { createElement, use, useContext, type ComponentType, type ReactNode } from "react";
+import { sharedContext } from "@textjs/react";
+import { RouterContext } from "../context";
+
+type AnyComponent = (props: any) => unknown;
+
+/** Promises kept per cache (least recently used are dropped first). */
+export const SERVER_COMPONENT_CACHE_SIZE = 256;
+
+/** Per-session promise cache, cleared whenever the route or `router.refresh()` generation changes. */
+export class ServerComponentCache {
+  private generation = "";
+  private readonly entries = new Map<string, Promise<ReactNode>>();
+  private readonly ids = new WeakMap<object, number>();
+  private nextId = 1;
+  private inflight = 0;
+  private settledAt = 0;
+  private readonly maxEntries: number;
+  private readonly onActivity: (() => void) | undefined;
+
+  /** `onActivity` runs whenever a component's promise starts or settles (idle tracking). */
+  constructor(options: { maxEntries?: number; onActivity?: () => void } = {}) {
+    this.maxEntries = options.maxEntries ?? SERVER_COMPONENT_CACHE_SIZE;
+    this.onActivity = options.onActivity;
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** Component promises that have not settled yet. */
+  get pending(): number {
+    return this.inflight;
+  }
+
+  /** `Date.now()` when a component promise last settled (0 = never). */
+  get lastSettled(): number {
+    return this.settledAt;
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+
+  /** Stable identity id for functions, symbols-as-objects and non-plain objects. */
+  idOf(value: object): number {
+    let id = this.ids.get(value);
+    if (id === undefined) {
+      id = this.nextId++;
+      this.ids.set(value, id);
+    }
+    return id;
+  }
+
+  read(component: AnyComponent, props: object, generation: string): Promise<ReactNode> {
+    if (generation !== this.generation) {
+      this.generation = generation;
+      this.entries.clear();
+    }
+    const key = `${this.idOf(component)}|${stableKey(props, this, 0)}`;
+    let p = this.entries.get(key);
+    if (p !== undefined) {
+      // Most recently used last.
+      this.entries.delete(key);
+      this.entries.set(key, p);
+    } else {
+      try {
+        p = Promise.resolve(component(props) as ReactNode | Promise<ReactNode>);
+      } catch (error) {
+        p = Promise.reject(error);
+      }
+      // Rejections surface through `use()` to the nearest error boundary.
+      this.inflight++;
+      this.onActivity?.();
+      const settled = (): void => {
+        this.inflight--;
+        this.settledAt = Date.now();
+        this.onActivity?.();
+      };
+      p.then(settled, settled);
+      this.entries.set(key, p);
+      for (const k of this.entries.keys()) {
+        if (this.entries.size <= this.maxEntries) break;
+        this.entries.delete(k);
+      }
+    }
+    return p;
+  }
+}
+
+const MAX_DEPTH = 64;
+const REACT_ELEMENT = Symbol.for("react.transitional.element");
+const REACT_ELEMENT_LEGACY = Symbol.for("react.element");
+
+let warnedFunctionProp = false;
+
+/**
+ * Structural key for props: primitives, plain objects, arrays, `Date`, `URL`,
+ * `URLSearchParams`, `RegExp`, `Map`, `Set`, class instances (by constructor
+ * and own fields) and React elements by value; component types by identity
+ * (they're module-level). Function props aren't part of the key: a callback
+ * rebuilt on every render would otherwise miss on every retry and suspend
+ * forever. Props rebuilt on every parent render keep the same key, so a
+ * retried render reuses the in-flight promise.
+ */
+export function stableKey(value: unknown, cache: ServerComponentCache, depth: number, seen: WeakSet<object> = new WeakSet()): string {
+  switch (typeof value) {
+    case "string":
+      return JSON.stringify(value);
+    case "number":
+    case "boolean":
+    case "bigint":
+      return `${typeof value}:${String(value)}`;
+    case "undefined":
+      return "u";
+    case "symbol":
+      return `s:${String(value)}`;
+    case "function":
+      if (!warnedFunctionProp) {
+        warnedFunctionProp = true;
+        console.warn("▼ Text.js: an async server component received a function prop. Functions aren't part of its cache key; pass data instead of callbacks.");
+      }
+      return "f";
+  }
+  if (value === null) return "n";
+  const obj = value as Record<string | symbol, unknown>;
+  if (seen.has(obj)) return "cycle";
+  if (depth >= MAX_DEPTH) return `o#${cache.idOf(obj)}`;
+  seen.add(obj);
+  try {
+    const next = (v: unknown): string => stableKey(v, cache, depth + 1, seen);
+    if (Array.isArray(obj)) return `[${obj.map(next).join(",")}]`;
+    const tag = obj.$$typeof;
+    if (tag === REACT_ELEMENT || tag === REACT_ELEMENT_LEGACY) {
+      const type = obj.type;
+      const t = typeof type === "string" ? type : typeof type === "object" || typeof type === "function" ? `#${cache.idOf(type as object)}` : String(type);
+      return `<${t}:${String(obj.key)}:${next(obj.props)}>`;
+    }
+    if (obj instanceof Date) return `d:${obj.getTime()}`;
+    if (obj instanceof URL) return `url:${JSON.stringify(obj.href)}`;
+    if (obj instanceof URLSearchParams) return `qs:${JSON.stringify(obj.toString())}`;
+    if (obj instanceof RegExp) return `re:${JSON.stringify(obj.toString())}`;
+    if (obj instanceof Map) return `map{${[...obj].map(([k, v]) => `${next(k)}=>${next(v)}`).sort().join(",")}}`;
+    if (obj instanceof Set) return `set{${[...obj].map(next).sort().join(",")}}`;
+    const proto = Object.getPrototypeOf(obj) as { constructor?: { name?: string } } | null;
+    const prefix = proto !== Object.prototype && proto !== null ? `${proto.constructor?.name ?? "?"}` : "";
+    const keys = Object.keys(obj).sort();
+    return `${prefix}{${keys.map((k) => `${JSON.stringify(k)}:${next(obj[k])}`).join(",")}}`;
+  } finally {
+    seen.delete(obj);
+  }
+}
+
+export const ServerComponentCacheContext = sharedContext<ServerComponentCache | null>("serverComponentCache", null, "TextServerComponentCache");
+
+/** Used when an async component renders outside a live session (tests, `text run`); bounded like a session's. */
+const fallbackCache = new ServerComponentCache();
+
+/** Drop every promise cached outside live sessions (`text run` between apps, tests). */
+export function clearFallbackServerComponentCache(): void {
+  fallbackCache.clear();
+}
+
+const AsyncFunction = (async () => undefined).constructor;
+
+export function isAsyncComponent(type: unknown): type is AnyComponent {
+  return typeof type === "function" && type instanceof AsyncFunction;
+}
+
+const wrappers = new WeakMap<AnyComponent, ComponentType<any>>();
+
+/** Wrap an `async function` component so it renders on the console reconciler. */
+export function serverComponent<P extends object>(component: (props: P) => Promise<ReactNode>): ComponentType<P> {
+  const fn = component as AnyComponent;
+  let wrapped = wrappers.get(fn);
+  if (wrapped === undefined) {
+    const Wrapped = (props: P): ReactNode => {
+      const cache = useContext(ServerComponentCacheContext) ?? fallbackCache;
+      const router = useContext(RouterContext);
+      const generation = router ? `${router.location.key}:${router.refreshKey}` : "";
+      return use(cache.read(fn, props, generation));
+    };
+    Wrapped.displayName = fn.name ? `${fn.name}` : "ServerComponent";
+    wrapped = Wrapped as ComponentType<any>;
+    wrappers.set(fn, wrapped);
+  }
+  return wrapped as ComponentType<P>;
+}
+
+/** `type` with async function components swapped for their wrappers. */
+const REACT_MEMO = Symbol.for("react.memo");
+const memoWrappers = new WeakMap<object, object>();
+
+export function resolveServerType<T>(type: T): T {
+  if (isAsyncComponent(type)) return serverComponent(type as never) as T;
+  // `React.memo(async function …)`: wrap the inner component, keep the memo.
+  if (typeof type === "object" && type !== null && (type as { $$typeof?: symbol }).$$typeof === REACT_MEMO && isAsyncComponent((type as { type?: unknown }).type)) {
+    let wrapped = memoWrappers.get(type);
+    if (wrapped === undefined) {
+      wrapped = { ...(type as object), type: serverComponent((type as unknown as { type: never }).type) };
+      memoWrappers.set(type, wrapped);
+    }
+    return wrapped as T;
+  }
+  return type;
+}
+
+/** Provide a session's cache to every async component below. */
+export function ServerComponentsProvider({ cache, children }: { cache: ServerComponentCache; children?: ReactNode }): ReactNode {
+  return createElement(ServerComponentCacheContext, { value: cache }, children);
+}

package/src/terminal.ts

@@ -0,0 +1,5 @@
+/**
+ * `@textjs/app/terminal` — render the same app in a real terminal.
+ */
+
+export * from "@textjs/react/terminal";

package/src/testing.ts

@@ -0,0 +1,5 @@
+/**
+ * `@textjs/app/testing` — render apps offscreen and drive them with keys.
+ */
+
+export * from "@textjs/react/testing";