@ultimat3/render 1.0.0

package/src/router-client.ts

@@ -0,0 +1,225 @@
+/**
+ * The minimal client router. Vendored on purpose: the router is load-bearing for every
+ * app page, and a moving SolidStart alpha is not something a framework should depend on.
+ *
+ * No `solid-js` import — reactive primitives and the DOM are injected, so this file runs
+ * under `bun test` with no DOM and no framework runtime.
+ */
+
+import type { CompiledPattern } from './registry';
+import { compilePattern } from './registry';
+import type { RouteParams } from './route';
+
+export interface RouterRoute {
+  readonly path: string;
+  /** Module URL for the route chunk; used by `prefetch`. */
+  readonly chunk?: string;
+}
+
+export interface ResolvedRoute {
+  readonly route: RouterRoute;
+  readonly params: RouteParams;
+  readonly pathname: string;
+  readonly search: string;
+}
+
+/** Injected instead of imported so there is no framework runtime dependency here. */
+export interface ReactivePrimitives {
+  createSignal<T>(initial: T): readonly [() => T, (next: T) => void];
+}
+
+export interface RouterHost {
+  readonly pathname: () => string;
+  readonly search: () => string;
+  readonly pushState: (url: string) => void;
+  readonly replaceState: (url: string) => void;
+  readonly onPopState: (handler: () => void) => void;
+  readonly scrollTo: (x: number, y: number) => void;
+  readonly scrollY: () => number;
+  /** `document.startViewTransition` when present; falls back to running the update. */
+  readonly viewTransition?: (update: () => void) => void;
+  /** Warm a chunk. Defaults to a no-op host in tests. */
+  readonly preload?: (chunk: string) => void;
+}
+
+export type NavigationGuard = (
+  to: ResolvedRoute,
+  from: ResolvedRoute | null,
+) => boolean | Promise<boolean>;
+
+export interface RouterOptions {
+  readonly routes: readonly RouterRoute[];
+  readonly host: RouterHost;
+  readonly primitives: ReactivePrimitives;
+  /** Hover dwell before prefetching, ms. */
+  readonly prefetchDelayMs?: number;
+}
+
+export interface NavigateOptions {
+  readonly replace?: boolean;
+  readonly scroll?: boolean;
+}
+
+export interface Router {
+  readonly current: () => ResolvedRoute | null;
+  readonly navigate: (to: string, options?: NavigateOptions) => Promise<boolean>;
+  readonly resolve: (url: string) => ResolvedRoute | null;
+  readonly prefetch: (to: string) => void;
+  readonly guard: (guard: NavigationGuard) => () => void;
+  /** Attach hover/visible prefetch + scroll restoration to a container element. */
+  readonly attach: (container: PrefetchContainer) => () => void;
+}
+
+/** Structural view of the DOM bits the router touches, so tests can fake them. */
+export type DomEventHandler = (event: { target: unknown }) => void;
+
+export interface PrefetchContainer {
+  querySelectorAll(selector: string): Iterable<PrefetchLink>;
+  addEventListener(type: string, handler: DomEventHandler, options?: unknown): void;
+  removeEventListener(type: string, handler: DomEventHandler, options?: unknown): void;
+}
+
+export interface PrefetchLink {
+  getAttribute(name: string): string | null;
+}
+
+interface CompiledRoute {
+  readonly route: RouterRoute;
+  readonly pattern: CompiledPattern;
+}
+
+export function createRouter(options: RouterOptions): Router {
+  const compiled: readonly CompiledRoute[] = options.routes
+    .map((route) => ({ route, pattern: compilePattern(route.path) }))
+    .sort((a, b) => b.pattern.specificity - a.pattern.specificity);
+
+  const guards = new Set<NavigationGuard>();
+  const scrollPositions = new Map<string, number>();
+  const prefetched = new Set<string>();
+  const host = options.host;
+
+  const [current, setCurrent] = options.primitives.createSignal<ResolvedRoute | null>(
+    resolve(`${host.pathname()}${host.search()}`),
+  );
+
+  function resolve(url: string): ResolvedRoute | null {
+    const [rawPath = '/', rawSearch = ''] = splitUrl(url);
+    for (const candidate of compiled) {
+      const match = candidate.pattern.regex.exec(rawPath);
+      if (match === null) continue;
+      const params: Record<string, string> = {};
+      candidate.pattern.keys.forEach((key, index) => {
+        const value = match[index + 1];
+        if (value !== undefined) params[key] = decodeURIComponent(value);
+      });
+      return {
+        route: candidate.route,
+        params,
+        pathname: rawPath,
+        search: rawSearch === '' ? '' : `?${rawSearch}`,
+      };
+    }
+    return null;
+  }
+
+  async function navigate(to: string, navOptions: NavigateOptions = {}): Promise<boolean> {
+    const next = resolve(to);
+    if (next === null) return false;
+
+    const from = current();
+    for (const guard of guards) {
+      // A guard that says no is a hard stop: no history entry, no scroll change.
+      if (!(await guard(next, from))) return false;
+    }
+
+    if (from !== null) scrollPositions.set(keyOf(from), host.scrollY());
+
+    const commit = (): void => {
+      if (navOptions.replace === true) host.replaceState(to);
+      else host.pushState(to);
+      setCurrent(next);
+      if (navOptions.scroll !== false) restoreScroll(next);
+    };
+
+    if (host.viewTransition !== undefined) host.viewTransition(commit);
+    else commit();
+    return true;
+  }
+
+  function restoreScroll(route: ResolvedRoute): void {
+    host.scrollTo(0, scrollPositions.get(keyOf(route)) ?? 0);
+  }
+
+  function prefetch(to: string): void {
+    const target = resolve(to);
+    const chunk = target?.route.chunk;
+    if (chunk === undefined || prefetched.has(chunk)) return;
+    prefetched.add(chunk);
+    host.preload?.(chunk);
+  }
+
+  host.onPopState(() => {
+    const next = resolve(`${host.pathname()}${host.search()}`);
+    if (next !== null) {
+      setCurrent(next);
+      restoreScroll(next);
+    }
+  });
+
+  return {
+    current,
+    navigate,
+    resolve,
+    prefetch,
+    guard(guard) {
+      guards.add(guard);
+      return () => guards.delete(guard);
+    },
+    attach(container) {
+      let timer: ReturnType<typeof setTimeout> | null = null;
+      const onEnter = (event: { target: unknown }): void => {
+        const href = hrefOf(event.target);
+        if (href === null) return;
+        if (timer !== null) clearTimeout(timer);
+        timer = setTimeout(() => prefetch(href), options.prefetchDelayMs ?? 80);
+      };
+      const onLeave = (): void => {
+        if (timer !== null) clearTimeout(timer);
+        timer = null;
+      };
+
+      container.addEventListener('mouseenter', onEnter, true);
+      container.addEventListener('mouseleave', onLeave, true);
+
+      // Visible prefetch: everything explicitly marked, warmed once it is on screen.
+      for (const link of container.querySelectorAll('a[data-prefetch="visible"]')) {
+        const href = link.getAttribute('href');
+        if (href !== null) prefetch(href);
+      }
+
+      return () => {
+        container.removeEventListener('mouseenter', onEnter, true);
+        container.removeEventListener('mouseleave', onLeave, true);
+        onLeave();
+      };
+    },
+  };
+}
+
+function keyOf(route: ResolvedRoute): string {
+  return `${route.pathname}${route.search}`;
+}
+
+function splitUrl(url: string): readonly [string, string] {
+  const hashless = url.split('#')[0] ?? '/';
+  const index = hashless.indexOf('?');
+  if (index === -1) return [hashless === '' ? '/' : hashless, ''];
+  return [hashless.slice(0, index) || '/', hashless.slice(index + 1)];
+}
+
+function hrefOf(target: unknown): string | null {
+  if (typeof target !== 'object' || target === null) return null;
+  if (!('getAttribute' in target)) return null;
+  const link = target as PrefetchLink;
+  return link.getAttribute('href');
+}

package/src/surfaces.ts

@@ -0,0 +1,248 @@
+/**
+ * The three surfaces plus `shared/`, and the hard import boundary between them.
+ * `site/` must never reach `app/`, transitively, through any number of hops — that is
+ * what makes axiom 6 ("the static path never pays for the app path") real rather than
+ * aspirational. Violations are build errors, resolved through the whole chain.
+ */
+
+import { SurfaceBoundaryError } from './errors';
+import type { RenderMode } from './route';
+
+export type Surface = 'site' | 'app' | 'api' | 'shared';
+
+export const SURFACES = ['site', 'app', 'api', 'shared'] as const;
+
+export interface SurfaceSpec {
+  readonly surface: Surface;
+  readonly defaultMode: RenderMode | null;
+  readonly allowedModes: readonly RenderMode[];
+  /** Bytes of JS a route on this surface ships before any island opts in. */
+  readonly jsBaselineBytes: number;
+  /** Surfaces this one may import at runtime. */
+  readonly mayImport: readonly Surface[];
+  /** Surfaces this one may reference with `import type` only. */
+  readonly mayImportTypes: readonly Surface[];
+}
+
+export const SURFACE_SPECS: Readonly<Record<Surface, SurfaceSpec>> = Object.freeze({
+  site: {
+    surface: 'site',
+    defaultMode: 'static',
+    allowedModes: ['static', 'isr', 'ssr'],
+    jsBaselineBytes: 0,
+    mayImport: ['shared'],
+    mayImportTypes: ['shared'],
+  },
+  app: {
+    surface: 'app',
+    defaultMode: 'stream',
+    allowedModes: ['stream', 'spa', 'ssr'],
+    jsBaselineBytes: 14_336,
+    mayImport: ['shared'],
+    mayImportTypes: ['shared', 'api'],
+  },
+  api: {
+    surface: 'api',
+    defaultMode: null,
+    allowedModes: [],
+    jsBaselineBytes: 0,
+    mayImport: ['shared'],
+    mayImportTypes: ['shared'],
+  },
+  shared: {
+    surface: 'shared',
+    defaultMode: null,
+    allowedModes: [],
+    jsBaselineBytes: 0,
+    mayImport: [],
+    mayImportTypes: [],
+  },
+});
+
+const SURFACE_SEGMENT = /(?:^|\/)(site|app|api|shared)\//;
+
+/** `apps/web/site/pricing/page.tsx` → `site`. Returns null for files outside a surface. */
+export function surfaceOf(file: string): Surface | null {
+  const match = SURFACE_SEGMENT.exec(normalize(file));
+  const found = match?.[1];
+  return found === undefined ? null : (found as Surface);
+}
+
+function normalize(file: string): string {
+  return file.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+export interface ImportRef {
+  readonly file: string;
+  /** `import type` edges cost zero bytes, so they never carry the surface boundary. */
+  readonly type: boolean;
+}
+
+export type ImportGraph = ReadonlyMap<string, readonly ImportRef[]>;
+
+/** Build a graph from a plain record; a bare string is a runtime (value) import. */
+export function importGraph(
+  record: Readonly<Record<string, readonly (string | ImportRef)[]>>,
+): ImportGraph {
+  const graph = new Map<string, readonly ImportRef[]>();
+  for (const [file, imports] of Object.entries(record)) {
+    graph.set(
+      normalize(file),
+      imports.map((i) =>
+        typeof i === 'string'
+          ? { file: normalize(i), type: false }
+          : { ...i, file: normalize(i.file) },
+      ),
+    );
+  }
+  return graph;
+}
+
+export type BoundaryRule = 'site-imports-app' | 'shared-is-a-leaf' | 'app-imports-api-at-runtime';
+
+export interface BoundaryViolation {
+  readonly rule: BoundaryRule;
+  /** The file the traversal started from — the reviewed file. */
+  readonly entry: string;
+  /** The file that actually writes the offending import. */
+  readonly importer: string;
+  /** The file it imports. */
+  readonly imported: string;
+  /** Full resolved chain, `entry → … → imported`. */
+  readonly chain: readonly string[];
+  readonly cause: string;
+  readonly fix: string;
+}
+
+/**
+ * Walk value-import edges from every file and report every crossing of the boundary.
+ * Transitivity is the whole point: the import that costs you is three hops away from the
+ * file anyone reviewed, so a direct-imports-only check finds nothing.
+ */
+export function checkSurfaceBoundary(graph: ImportGraph): readonly BoundaryViolation[] {
+  const found = new Map<string, BoundaryViolation>();
+
+  for (const entry of graph.keys()) {
+    const entrySurface = surfaceOf(entry);
+    if (entrySurface === null) continue;
+    walk(graph, entry, entrySurface, found);
+  }
+
+  return [...found.values()].sort((a, b) => keyOf(a).localeCompare(keyOf(b)));
+}
+
+function keyOf(v: BoundaryViolation): string {
+  return `${v.rule}|${v.importer}|${v.imported}`;
+}
+
+function walk(
+  graph: ImportGraph,
+  entry: string,
+  entrySurface: Surface,
+  found: Map<string, BoundaryViolation>,
+): void {
+  const seen = new Set<string>([entry]);
+  const queue: string[][] = [[entry]];
+
+  while (queue.length > 0) {
+    const chain = queue.shift();
+    if (chain === undefined) break;
+    const current = chain[chain.length - 1];
+    if (current === undefined) continue;
+
+    for (const ref of graph.get(current) ?? []) {
+      const importerSurface = surfaceOf(current);
+      const importedSurface = surfaceOf(ref.file);
+      const nextChain = [...chain, ref.file];
+
+      const violation = classify({
+        entry,
+        entrySurface,
+        importer: current,
+        importerSurface,
+        imported: ref.file,
+        importedSurface,
+        typeOnly: ref.type,
+        chain: nextChain,
+      });
+      if (violation !== null) found.set(keyOf(violation), violation);
+
+      // Type-only edges are erased at build time, so they cannot carry bytes onward.
+      if (ref.type) continue;
+      if (seen.has(ref.file)) continue;
+      seen.add(ref.file);
+      queue.push(nextChain);
+    }
+  }
+}
+
+interface ClassifyInput {
+  readonly entry: string;
+  readonly entrySurface: Surface;
+  readonly importer: string;
+  readonly importerSurface: Surface | null;
+  readonly imported: string;
+  readonly importedSurface: Surface | null;
+  readonly typeOnly: boolean;
+  readonly chain: readonly string[];
+}
+
+function classify(i: ClassifyInput): BoundaryViolation | null {
+  const chainText = i.chain.join(' → ');
+
+  if (i.entrySurface === 'site' && i.importedSurface === 'app' && !i.typeOnly) {
+    return {
+      rule: 'site-imports-app',
+      entry: i.entry,
+      importer: i.importer,
+      imported: i.imported,
+      chain: i.chain,
+      cause: chainText,
+      fix: `x fix boundary ${i.entry}   (or move ${i.imported} out of the shared graph)`,
+    };
+  }
+
+  if (
+    i.importerSurface === 'shared' &&
+    (i.importedSurface === 'app' || i.importedSurface === 'site') &&
+    !i.typeOnly
+  ) {
+    return {
+      rule: 'shared-is-a-leaf',
+      entry: i.entry,
+      importer: i.importer,
+      imported: i.imported,
+      chain: i.chain,
+      cause: `${chainText}  (shared/ is a leaf — it may not import a surface)`,
+      fix: `move the shared part of ${i.imported} into shared/ and import it from ${i.importer}`,
+    };
+  }
+
+  if (i.importerSurface === 'app' && i.importedSurface === 'api' && !i.typeOnly) {
+    return {
+      rule: 'app-imports-api-at-runtime',
+      entry: i.entry,
+      importer: i.importer,
+      imported: i.imported,
+      chain: i.chain,
+      cause: `${chainText}  (app/ → api/ is types-only)`,
+      fix: `change to \`import type\` in ${i.importer} and call the typed client instead`,
+    };
+  }
+
+  return null;
+}
+
+/** Build-time gate. `x verify` and the dev server both call this. */
+export function assertSurfaceBoundary(graph: ImportGraph): void {
+  const violations = checkSurfaceBoundary(graph);
+  const first = violations[0];
+  if (first === undefined) return;
+
+  const extra = violations.length > 1 ? ` (+${violations.length - 1} more)` : '';
+  throw new SurfaceBoundaryError(`${first.cause}${extra}`, first.fix);
+}
+
+export function surfaceAllows(surface: Surface, mode: RenderMode): boolean {
+  return SURFACE_SPECS[surface].allowedModes.includes(mode);
+}