@textjs/app 0.0.0-stage → 1.0.3

package/src/cli/start.ts

@@ -0,0 +1,194 @@
+import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
+import { createServer, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { extname, join, normalize, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { BRAND_MARK, txError, txMessage } from "@textjs/core";
+import { normalizeBasePath, type ProxyTarget } from "../config";
+import { matchApiRoute } from "../server/scan";
+import { loadLiveProduction } from "../server/live-prod";
+import { applyRewrites, compileRewrite, isAllowedHost, isValidHostHeader, normalizeRequestTarget, proxyRequest, requestOrigin, sendWebResponse, toWebRequest, type RouteHandlerModule } from "../server/http";
+import type { RouteManifest } from "../routing";
+import { loadServerRuntime } from "../server/adapters/runtime-node";
+import { runRouteHandlerWithCache } from "../server/cache-route";
+import { runNodeMiddleware } from "../server/middleware-node";
+import { META_DIR } from "./build";
+import { loadTextConfig } from "./config";
+import { banner, color, fail, ok } from "./ui";
+
+const MIME: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".ico": "image/x-icon",
+  ".wasm": "application/wasm",
+  ".txt": "text/plain; charset=utf-8",
+  ".woff2": "font/woff2",
+  ".map": "application/json; charset=utf-8",
+};
+
+export interface StartOptions {
+  root: string;
+  port?: number;
+  host?: string;
+  log?: boolean;
+}
+
+export interface StartedServer {
+  server: Server;
+  url: string;
+  close(): Promise<void>;
+}
+
+export async function startProductionServer(opts: StartOptions): Promise<StartedServer> {
+  const started = performance.now();
+  const log = opts.log ?? true;
+  const { config } = await loadTextConfig(opts.root, "serve", "production");
+  const outDir = resolve(opts.root, config.outDir ?? "dist");
+  const indexFile = join(outDir, "index.html");
+  if (!existsSync(indexFile)) {
+    throw txError("TX017", config.outDir ?? "dist");
+  }
+  const basePath = normalizeBasePath(config.basePath);
+  const rewrites = (typeof config.rewrites === "function" ? await config.rewrites() : (config.rewrites ?? [])).map(compileRewrite);
+  const proxies = Object.entries(config.proxy ?? {}).map(([prefix, v]) => [prefix, typeof v === "string" ? { target: v } : v] as [string, ProxyTarget]);
+
+  const apiFile = join(outDir, META_DIR, "server", "api.mjs");
+  type ApiBundle = { manifest: RouteManifest; handlers: Record<string, RouteHandlerModule> };
+  const api: ApiBundle | null = existsSync(apiFile) ? ((await import(pathToFileURL(apiFile).href)) as ApiBundle) : null;
+  const indexHtml = readFileSync(indexFile);
+  // `middleware.ts` and `cacheHandler` (bundled by `text build`).
+  const runtime = await loadServerRuntime(outDir);
+  // Prerendered console shells (PPR) and server-rendered routes (`runtime = "server"`).
+  const live = await loadLiveProduction(outDir, {
+    log: log ? (m) => console.log(color.gray(m)) : undefined,
+    onError: (e) => console.error(fail(e instanceof Error ? (e.stack ?? e.message) : String(e))),
+    middleware: runtime?.middleware,
+    trustProxy: config.server?.trustProxy ?? process.env.TRUST_PROXY === "1",
+    origin: config.server?.origin ?? process.env.TEXTJS_ORIGIN,
+  });
+
+  const port = opts.port ?? 3000;
+  // Loopback only unless `--host` is passed explicitly.
+  const host = opts.host ?? "127.0.0.1";
+  const loopback = host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]";
+  const originOptions = {
+    origin: config.server?.origin ?? process.env.TEXTJS_ORIGIN,
+    trustProxy: config.server?.trustProxy ?? process.env.TRUST_PROXY === "1",
+  };
+  // DNS rebinding: a loopback-bound server only answers loopback / IP / allowed host names.
+  const allowedHosts = config.server?.allowedHosts ?? [];
+  const notFound = (res: ServerResponse): void => {
+    res.statusCode = 404;
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    res.end("404 | This page could not be found.");
+  };
+
+  const server = createServer((req, res) => {
+    const t0 = performance.now();
+    const done = (): void => {
+      if (log) console.log(color.gray(` ${req.method} ${(req.url ?? "/").split("?")[0]} ${res.statusCode} in ${Math.round(performance.now() - t0)}ms`));
+    };
+    void (async () => {
+      if (loopback ? !isAllowedHost(req.headers.host, allowedHosts) : !isValidHostHeader(req.headers.host)) {
+        res.statusCode = loopback ? 403 : 400;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end(loopback ? `${BRAND_MARK} ${txMessage("TX028", JSON.stringify((req.headers.host ?? "").replace(/:\d+$/, "")), "server.allowedHosts")}` : "400 | Bad Request");
+        return;
+      }
+      req.url = normalizeRequestTarget(req.url);
+      const origin = requestOrigin(req, originOptions);
+      let url = req.url;
+      if (basePath) {
+        if (url === basePath || url.startsWith(`${basePath}/`) || url.startsWith(`${basePath}?`)) url = url.slice(basePath.length) || "/";
+        else return notFound(res);
+      }
+      if (runtime?.middleware) {
+        const next = await runNodeMiddleware(runtime.middleware, req, res, { basePath, origin });
+        if (next === null) return;
+        url = next;
+      }
+      const rewritten = rewrites.length > 0 ? applyRewrites(rewrites, url) : null;
+      if (rewritten) {
+        if (/^[a-z]+:\/\//i.test(rewritten)) return proxyRequest(req, res, rewritten, origin);
+        url = rewritten;
+      }
+      for (const [prefix, target] of proxies) {
+        if (url.startsWith(prefix)) {
+          const path = target.rewrite ? target.rewrite(url) : url;
+          return proxyRequest(req, res, new URL(path, target.target).href, origin);
+        }
+      }
+      if (live && (await live.handle(req, res, url))) return;
+      let pathname: string;
+      try {
+        pathname = decodeURIComponent(url.split("?")[0] ?? "/");
+      } catch {
+        res.statusCode = 400;
+        return res.end("400 | Bad Request");
+      }
+      if (api) {
+        const m = matchApiRoute(api.manifest, pathname);
+        const mod = m ? api.handlers[m.file] : undefined;
+        if (m && mod) {
+          const request = toWebRequest(Object.assign(req, { url }), origin, res);
+          return sendWebResponse(res, await runRouteHandlerWithCache(mod, request, { params: m.params, pattern: m.pattern, pathname }), request.method);
+        }
+      }
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        res.statusCode = 405;
+        return res.end();
+      }
+      const filePath = normalize(join(outDir, pathname));
+      const inside = filePath === outDir || filePath.startsWith(outDir + sep);
+      const hidden = pathname.split(/[/\\]/).some((p) => p.startsWith(".") && p.length > 1);
+      if (inside && !hidden && existsSync(filePath) && statSync(filePath).isFile()) {
+        res.statusCode = 200;
+        res.setHeader("Content-Type", MIME[extname(filePath)] ?? "application/octet-stream");
+        res.setHeader("Cache-Control", pathname.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "public, max-age=0, must-revalidate");
+        if (req.method === "HEAD") return res.end();
+        createReadStream(filePath).pipe(res);
+        return;
+      }
+      const last = pathname.split("/").pop() ?? "";
+      if (last.includes(".") || hidden) return notFound(res);
+      res.statusCode = 200;
+      res.setHeader("Content-Type", MIME[".html"] as string);
+      res.setHeader("Cache-Control", "public, max-age=0, must-revalidate");
+      res.end(req.method === "HEAD" ? undefined : indexHtml);
+    })()
+      .catch((error: unknown) => {
+        if (log) console.error(fail(error instanceof Error ? (error.stack ?? error.message) : String(error)));
+        if (!res.headersSent) res.statusCode = 500;
+        res.end();
+      })
+      .finally(done);
+  });
+
+  await new Promise<void>((resolveListen, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => resolveListen());
+  });
+  const addr = server.address() as AddressInfo;
+  const url = `http://${host === "0.0.0.0" || host === "127.0.0.1" ? "localhost" : host}:${addr.port}${basePath}`;
+  if (log) {
+    console.log(`\n${banner([["Local", color.cyan(url)]])}\n`);
+    console.log(ok("Starting..."));
+    console.log(ok(`Ready in ${Math.round(performance.now() - started)}ms`));
+    console.log("");
+  }
+  return {
+    server,
+    url,
+    close: () =>
+      new Promise<void>((r) => {
+        live?.close();
+        server.close(() => r());
+      }),
+  };
+}

package/src/cli/ui.ts

@@ -0,0 +1,93 @@
+import { BRAND_MARK, ENGINE_NAME, VERSION } from "@textjs/core";
+import type { FlatRoute } from "../routing";
+
+const enabled = (): boolean => {
+  if (typeof process === "undefined") return false;
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "") return false;
+  if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0") return true;
+  return Boolean(process.stdout && process.stdout.isTTY);
+};
+
+const wrap =
+  (open: number, close: number) =>
+  (s: string): string =>
+    enabled() ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+
+export const color = {
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  cyan: wrap(36, 39),
+  magenta: wrap(35, 39),
+  gray: wrap(90, 39),
+};
+
+export function stripAnsi(s: string): string {
+  return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+export function brand(): string {
+  return `${color.bold(`${BRAND_MARK} Text.js ${VERSION}`)} ${color.dim(`(${ENGINE_NAME})`)}`;
+}
+
+export function banner(lines: Array<[string, string]>): string {
+  const out = [`   ${brand()}`];
+  for (const [k, v] of lines) out.push(`   - ${`${k}:`.padEnd(14)}${v}`);
+  return out.join("\n");
+}
+
+export const ok = (msg: string): string => ` ${color.green("✓")} ${msg}`;
+export const fail = (msg: string): string => ` ${color.red("⨯")} ${msg}`;
+export const info = (msg: string): string => ` ${color.gray("○")} ${msg}`;
+
+export interface SummaryRoute {
+  pattern: string;
+  dynamic: boolean;
+  target: string;
+  /** `export const runtime = "server"`. */
+  server?: boolean;
+}
+
+const ROUTE_COL = 37;
+const TYPE_COL = 11;
+
+/** The Next.js-style route summary table printed by `text build`. */
+export function routeTable(routes: readonly SummaryRoute[]): string {
+  const lines = [`${color.bold("Route (app)".padEnd(ROUTE_COL + 4))}${color.bold("Type".padEnd(TYPE_COL))}${color.bold("Target")}`];
+  routes.forEach((r, i) => {
+    const corner = routes.length === 1 ? "─" : i === 0 ? "┌" : i === routes.length - 1 ? "└" : "├";
+    const sym = r.server ? "◇" : r.dynamic ? "ƒ" : "○";
+    const pattern = r.pattern.length > ROUTE_COL - 1 ? `${r.pattern.slice(0, ROUTE_COL - 2)}…` : r.pattern;
+    const type = r.server ? "Server" : r.dynamic ? "Dynamic" : "Static";
+    lines.push(`${color.gray(corner)} ${sym} ${pattern.padEnd(ROUTE_COL)}${type.padEnd(TYPE_COL)}${color.gray(r.target)}`);
+  });
+  return lines.join("\n");
+}
+
+export const LEGEND = ["○  (Static)   prerendered as static console cells", "ƒ  (Dynamic)  on-demand console reconciliation"].join("\n");
+/** Appended to {@link LEGEND} when the app has server-rendered routes. */
+export const SERVER_LEGEND = "◇  (Server)   rendered on the server, streamed as frames";
+
+export function summarize(pages: readonly FlatRoute[], api: ReadonlyArray<{ pattern: string }>, serverPatterns: ReadonlySet<string> = new Set()): SummaryRoute[] {
+  const out: SummaryRoute[] = pages.map((p) =>
+    serverPatterns.has(p.pattern) ? { pattern: p.pattern, dynamic: true, server: true, target: "frame player (SSE)" } : { pattern: p.pattern, dynamic: p.dynamic, target: "console.log (%c)" },
+  );
+  if (!out.some((r) => r.pattern === "/_not-found")) {
+    const nf = { pattern: "/_not-found", dynamic: false, target: "console.log (%c)" };
+    out.splice(out[0]?.pattern === "/" ? 1 : 0, 0, nf);
+  }
+  for (const a of api) out.push({ pattern: a.pattern, dynamic: true, target: "Route Handler" });
+  return out;
+}
+
+export function formatBytes(n: number): string {
+  if (n < 1000) return `${n} B`;
+  return `${(n / 1000).toFixed(1)} kB`;
+}
+
+export function devtoolsHint(): string {
+  const keys = process.platform === "darwin" ? "⌘⌥J" : "Ctrl+Shift+J";
+  return info(`Open DevTools Console (${keys}) to view your app`);
+}

package/src/client.tsx

@@ -0,0 +1,122 @@
+/**
+ * `@textjs/app/client` — browser bootstrap used by the virtual entry that `text dev`
+ * and `text build` generate: mounts the console root, the App Router, the
+ * Dev Overlay and the DOM `<FocusPad>`.
+ */
+
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { createConsoleRoot, type ConsoleRoot } from "@textjs/react";
+import { FocusPad } from "@textjs/react/dom";
+import { toClientConfig, type ClientConfig } from "./config";
+import { connectViteHmr, devErrors, installGlobalErrorHandlers, TextDevOverlay, type HotContextLike } from "./devtools";
+import { connectFrameMirror, type MirrorHotContext } from "./frame-mirror";
+import { createBrowserHistory, type RouterHistory } from "./history";
+import { isNavigationError } from "./navigation-errors";
+import { AppRouter } from "./router";
+import type { RouteManifest } from "./routing";
+
+export interface BootOptions {
+  routes: RouteManifest;
+  config?: Partial<ClientConfig>;
+  /** `import.meta.env.DEV`. */
+  dev?: boolean;
+  /** `import.meta.hot`. */
+  hot?: HotContextLike;
+  /** Element (or id) for the DOM `<FocusPad>` (default `#__textjs`, created when missing). */
+  container?: HTMLElement | string;
+}
+
+export interface TextApp {
+  root: ConsoleRoot;
+  history: RouterHistory;
+  /** Swap the route manifest (HMR when route files change). */
+  updateRoutes(routes: RouteManifest): void;
+}
+
+declare global {
+  interface Window {
+    __TEXTJS_APP__?: TextApp;
+  }
+}
+
+function resolveContainer(container: BootOptions["container"]): HTMLElement {
+  if (container instanceof HTMLElement) return container;
+  const id = typeof container === "string" ? container : "__textjs";
+  let el = document.getElementById(id);
+  if (!el) {
+    el = document.createElement("div");
+    el.id = id;
+    document.body.appendChild(el);
+  }
+  return el;
+}
+
+/** Boot a Text.js app into `console.log`. */
+export async function bootTextApp(options: BootOptions): Promise<TextApp> {
+  const config = { ...toClientConfig({}), ...options.config };
+  const dev = options.dev ?? false;
+  const vp = config.viewport ?? {};
+  const seen = new WeakSet<object>();
+
+  const root = await createConsoleRoot({
+    // Follows the docked DevTools console by default; width × height is the
+    // size used when it can't be measured (undocked DevTools) or when `responsive: false`.
+    width: vp.width ?? 120,
+    height: vp.height ?? 36,
+    responsive: vp.responsive ?? true,
+    theme: vp.theme,
+    // A prerendered shell (PPR) already cleared the console: append below it.
+    initialClear: typeof window === "undefined" || (window as { __TEXTJS_SHELL__?: number }).__TEXTJS_SHELL__ !== 1,
+    // …and its clear opened DevTools' post-clear pacing window.
+    previousFrameAt: typeof window === "undefined" ? undefined : (window as { __TEXTJS_SHELL_AT__?: number }).__TEXTJS_SHELL_AT__,
+    onCaughtError: (error) => {
+      if (isNavigationError(error)) return;
+      if (typeof error === "object" && error !== null) {
+        if (seen.has(error)) return;
+        seen.add(error);
+      }
+      console.error(error);
+    },
+  });
+  const history = createBrowserHistory({ basePath: config.basePath });
+
+  const render = (routes: RouteManifest): void => {
+    root.render(
+      createElement(AppRouter, {
+        routes,
+        history,
+        theme: vp.theme,
+        defaultTitle: config.title || undefined,
+        errorStore: dev ? devErrors : null,
+        devOverlay: dev && config.devIndicators ? createElement(TextDevOverlay) : null,
+      }),
+    );
+  };
+  render(options.routes);
+
+  if (typeof document !== "undefined") {
+    if (!document.title && config.title) document.title = config.title;
+    const el = resolveContainer(options.container);
+    createRoot(el).render(
+      createElement(FocusPad, {
+        root,
+        title: config.title || undefined,
+        hints: config.hints,
+        action: config.action,
+        showMirrorDefault: config.showMirrorDefault,
+        style: { width: "min(960px, calc(100vw - 48px))", minHeight: "min(640px, calc(100vh - 48px))", boxSizing: "border-box" },
+      }),
+    );
+  }
+
+  if (dev) {
+    if (options.hot) connectViteHmr(options.hot);
+    if (options.hot && typeof (options.hot as Partial<MirrorHotContext>).send === "function") connectFrameMirror(root, options.hot as MirrorHotContext, history);
+    installGlobalErrorHandlers();
+  }
+
+  const app: TextApp = { root, history, updateRoutes: render };
+  if (typeof window !== "undefined") window.__TEXTJS_APP__ = app;
+  return app;
+}

package/src/config.ts

@@ -0,0 +1,155 @@
+/**
+ * `text.config.ts` and route `metadata` types.
+ *
+ * This module is imported by browser code, so Vite / Node types are referenced
+ * structurally and never imported at runtime.
+ */
+
+import type { ThemeName } from "@textjs/react";
+
+export interface ViewportConfig {
+  /** Grid width in cells when fixed, or when docked DevTools can't be measured (default `120`). */
+  width?: number;
+  /** Grid height in cells when fixed, or when docked DevTools can't be measured (default `36`). */
+  height?: number;
+  /** Follow the docked DevTools console size (default `true`); `false` pins `width × height`. */
+  responsive?: boolean;
+  /** Initial theme preset (default `"geistDark"`). */
+  theme?: ThemeName;
+}
+
+export interface Rewrite {
+  /** Path pattern: `/docs/:slug`, `/blog/:path*`. */
+  source: string;
+  /** Internal path or absolute URL (proxied). */
+  destination: string;
+}
+
+export interface ProxyTarget {
+  target: string;
+  changeOrigin?: boolean;
+  ws?: boolean;
+  rewrite?: (path: string) => string;
+  secure?: boolean;
+  headers?: Record<string, string>;
+}
+
+/** The subset of Vite's dev server the `configureServer` hook relies on. */
+export interface TextDevServer {
+  middlewares: { use(...args: unknown[]): unknown };
+  config: { root: string; server: { port?: number } };
+  [key: string]: unknown;
+}
+
+export interface TextConfig {
+  /** Console grid defaults. */
+  viewport?: ViewportConfig;
+  /** Mount the in-console Dev Overlay (the `[▼]` pill, its inspector and the Redbox) in development (default `true`). */
+  devIndicators?: boolean;
+  /** Open the FocusPad's inline console preview by default (default `false`). */
+  showMirrorDefault?: boolean;
+  /** Build output directory (default `"dist"`). */
+  outDir?: string;
+  /** App Router directory relative to the project root (default `"app"`). */
+  appDir?: string;
+  /** Mount the app under a sub-path, e.g. `"/console"`. */
+  basePath?: string;
+  /** Title shown in the FocusPad and as the default `document.title`. */
+  title?: string;
+  /** The two or three keys worth pressing, shown on the page's FocusPad, e.g. `[{ keys: "↑ ↓", label: "count" }]`. */
+  hints?: Array<{ keys: string; label: string }>;
+  /** What to do first, shown as "Then click here and …" (default: `press <first hint>`). */
+  action?: string;
+  /** Dev / start server proxy rules, keyed by path prefix. */
+  proxy?: Record<string, string | ProxyTarget>;
+  /** Rewrites applied before routing. External destinations are proxied. */
+  rewrites?: Rewrite[] | (() => Rewrite[] | Promise<Rewrite[]>);
+  /** Extend the Vite dev server (custom middleware, local service discovery, …). */
+  configureServer?: (server: TextDevServer) => void | (() => void) | Promise<void | (() => void)>;
+  /** Module (relative to the root) default-exporting a `CacheStore` for `@textjs/app/cache`. */
+  cacheHandler?: string;
+  /** Escape hatch merged into the generated Vite config. */
+  vite?: Record<string, unknown>;
+  /**
+   * Partial Prerendering: `text build` renders each static route's first frame
+   * (with `<Suspense>` fallbacks for dynamic holes) into its HTML so the console
+   * paints before JavaScript loads (default `true`).
+   */
+  ppr?: boolean;
+  /** Server-rendered routes (`export const runtime = "server"`). */
+  live?: LiveConfig;
+  /** `text start` request handling: public origin, reverse proxies and allowed hosts. */
+  server?: ServerConfig;
+}
+
+export interface ServerConfig {
+  /**
+   * The public origin (`https://console.example.com`). When set, `request.url`
+   * always uses it instead of the `Host` header. Also `TEXTJS_ORIGIN`.
+   */
+  origin?: string;
+  /**
+   * Trust `X-Forwarded-Host` / `X-Forwarded-Proto` from a reverse proxy in
+   * front of `text start` (default `false`; also `TRUST_PROXY=1`).
+   */
+  trustProxy?: boolean;
+  /**
+   * Extra `Host` names `text start` answers when bound to loopback (default:
+   * `localhost`, `*.localhost` and IP addresses). `true` disables the check.
+   * A leading `.` allows subdomains.
+   */
+  allowedHosts?: string[] | true;
+}
+
+export interface LiveConfig {
+  /** Concurrent sessions per server process (default `256`). */
+  maxSessions?: number;
+  /** How long a disconnected tab's session waits to be resumed, in ms (default `30000`). */
+  reconnectGraceMs?: number;
+}
+
+/** Type-safe `text.config.ts` helper. */
+export function defineConfig(config: TextConfig): TextConfig {
+  return config;
+}
+
+export interface MetadataTitleTemplate {
+  default: string;
+  template?: string;
+  absolute?: string;
+}
+
+export interface Metadata {
+  title?: string | MetadataTitleTemplate | { absolute: string; default?: string; template?: string };
+  description?: string;
+  [key: string]: unknown;
+}
+
+/** Client-safe configuration serialized into the browser bundle. */
+export interface ClientConfig {
+  viewport: ViewportConfig;
+  devIndicators: boolean;
+  showMirrorDefault: boolean;
+  basePath: string;
+  title: string;
+  hints?: Array<{ keys: string; label: string }>;
+  action?: string;
+}
+
+export function toClientConfig(config: TextConfig): ClientConfig {
+  return {
+    viewport: { ...config.viewport },
+    devIndicators: config.devIndicators ?? true,
+    showMirrorDefault: config.showMirrorDefault ?? false,
+    basePath: normalizeBasePath(config.basePath),
+    title: config.title ?? "",
+    ...(config.hints ? { hints: config.hints.map((h) => ({ keys: h.keys, label: h.label })) } : {}),
+    ...(config.action ? { action: config.action } : {}),
+  };
+}
+
+export function normalizeBasePath(basePath: string | undefined): string {
+  if (!basePath || basePath === "/") return "";
+  const withSlash = basePath.startsWith("/") ? basePath : `/${basePath}`;
+  return withSlash.replace(/\/+$/, "");
+}

package/src/context.ts

@@ -0,0 +1,69 @@
+import { useContext } from "react";
+import { sharedContext, type TextTheme, type ThemeName } from "@textjs/react";
+import { txError } from "@textjs/core";
+import type { RouterHistory, RouterLocation } from "./history";
+import type { ResolvedMetadata, RouteManifest, RouteMatch } from "./routing";
+
+export interface NavigateOptions {
+  /** Accepted for Next.js parity; console frames have no document scroll. */
+  scroll?: boolean;
+}
+
+export interface AppRouterInstance {
+  push(href: string, options?: NavigateOptions): void;
+  replace(href: string, options?: NavigateOptions): void;
+  back(): void;
+  forward(): void;
+  /** Re-render the current route and reset its error boundaries. */
+  refresh(): void;
+  /** Preload a lazy route's modules. */
+  prefetch(href: string): void;
+}
+
+export interface RouterState {
+  location: RouterLocation;
+  match: RouteMatch;
+  metadata: ResolvedMetadata;
+  router: AppRouterInstance;
+  history: RouterHistory;
+  manifest: RouteManifest;
+  /** Bumped by `router.refresh()`. */
+  refreshKey: number;
+}
+
+export const RouterContext = sharedContext<RouterState | null>("routerContext", null, "TextRouterContext");
+
+export function useRouterState(): RouterState {
+  const state = useContext(RouterContext);
+  if (state === null) {
+    throw txError("TX014", "Navigation hooks");
+  }
+  return state;
+}
+
+export function useOptionalRouterState(): RouterState | null {
+  return useContext(RouterContext);
+}
+
+/** App-wide shell controls (theme presets, wireframe) shared by DevTools and user settings pages. */
+export interface AppShellState {
+  theme: TextTheme;
+  themeName: ThemeName | string;
+  setTheme(theme: TextTheme | ThemeName): void;
+  cycleTheme(): void;
+  wireframe: boolean;
+  setWireframe(enabled: boolean): void;
+}
+
+export const AppShellContext = sharedContext<AppShellState | null>("appShellContext", null, "TextAppShellContext");
+
+/** Theme preset controls for the running app. */
+export function useAppTheme(): AppShellState {
+  const state = useContext(AppShellContext);
+  if (state === null) throw txError("TX014", "useAppTheme()");
+  return state;
+}
+
+export function useOptionalAppShell(): AppShellState | null {
+  return useContext(AppShellContext);
+}