@typed/app 1.0.0-beta.1

package/src/internal/routeIdentifiers.ts

@@ -0,0 +1,93 @@
+import { stripScriptExtension, toPosixPath } from "./path.js";
+
+/**
+ * Sanitize a path segment for use in a JS identifier: strip _ and brackets, keep only [a-zA-Z0-9], capitalize.
+ * Empty after sanitization is skipped (returns "").
+ */
+function segmentToIdentifierPart(seg: string): string {
+  let name = seg.trim().startsWith("_") ? seg.trim().slice(1) : seg.trim();
+  name = name.replace(/[[\]]/g, "").replace(/[^a-zA-Z0-9]/g, "");
+  if (!name) return "";
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+/**
+ * Path relative to baseDir → valid JS identifier.
+ * Safe for special chars in filenames; never emits invalid identifiers.
+ */
+export function pathToIdentifier(relativeFilePath: string): string {
+  const posix = toPosixPath(relativeFilePath);
+  const withoutExt = stripScriptExtension(posix);
+  const raw =
+    withoutExt.split("/").filter(Boolean).map(segmentToIdentifierPart).filter(Boolean).join("") ||
+    "Module";
+  const safe = raw.replace(/[^a-zA-Z0-9_$]/g, "");
+  if (!safe) return "Module";
+  if (/^\d/.test(safe)) return `M${safe}`;
+  return safe;
+}
+
+/** Final guard: ensure a string is a valid JS identifier (no spaces, brackets, or leading digit). */
+function toSafeIdentifier(s: string): string {
+  const cleaned = s.replace(/[\s[\]]/g, "").replace(/[^a-zA-Z0-9_$]/g, "");
+  if (!cleaned) return "Module";
+  if (/^\d/.test(cleaned)) return `M${cleaned}`;
+  return cleaned;
+}
+
+const RESERVED_NAMES = new Set(["Router", "Fx", "Effect", "Stream"]);
+
+/**
+ * Route module identifier: prefix with M to avoid clashing with Router/Fx/Effect/Stream.
+ */
+export function routeModuleIdentifier(relativeFilePath: string): string {
+  const base = pathToIdentifier(relativeFilePath);
+  return RESERVED_NAMES.has(base) ? `M${base}` : base;
+}
+
+/** True if the path has a dynamic segment (bracket). */
+function pathHasParamSegment(relativePath: string): boolean {
+  return /\[[^\]]*\]/.test(relativePath);
+}
+
+/**
+ * Assign unique var names when proposed names collide (e.g. users/[id].ts and users/id.ts both → UsersId).
+ * First occurrence keeps the base name; others get base + "Param" (if path has [x]), "Literal", or numeric suffix.
+ */
+export function makeUniqueVarNames(
+  entries: readonly { path: string; proposedName: string }[],
+): Map<string, string> {
+  const sorted = [...entries].sort((a, b) => a.path.localeCompare(b.path));
+  const nameToPaths = new Map<string, string[]>();
+  for (const { path, proposedName } of sorted) {
+    const base = toSafeIdentifier(proposedName);
+    const list = nameToPaths.get(base) ?? [];
+    list.push(path);
+    nameToPaths.set(base, list);
+  }
+  const pathToUnique = new Map<string, string>();
+  const used = new Set<string>();
+  for (const [base, paths] of nameToPaths) {
+    for (let i = 0; i < paths.length; i++) {
+      const path = paths[i]!;
+      let name: string;
+      if (paths.length === 1) {
+        name = base;
+      } else if (i === 0) {
+        name = base;
+      } else {
+        const suffix = pathHasParamSegment(path) ? "Param" : "Literal";
+        let candidate = base + suffix;
+        let n = 0;
+        while (used.has(candidate)) {
+          n += 1;
+          candidate = base + String(n);
+        }
+        name = candidate;
+      }
+      used.add(name);
+      pathToUnique.set(path, name);
+    }
+  }
+  return pathToUnique;
+}

package/src/internal/routeTypeNode.ts

@@ -0,0 +1,120 @@
+import type {
+  ConstructorTypeNode,
+  FunctionTypeNode,
+  OverloadSetTypeNode,
+  TypeInfoApi,
+  TypeNode,
+} from "@typed/virtual-modules";
+
+/** True when the node represents a callable (function, overload set, or constructor). */
+export function isCallableNode(
+  node: TypeNode,
+): node is FunctionTypeNode | OverloadSetTypeNode | ConstructorTypeNode {
+  return node.kind === "function" || node.kind === "overloadSet" || node.kind === "constructor";
+}
+
+/** First signature's parameters for function-like nodes; undefined otherwise. */
+function getCallableParameters(
+  node: TypeNode,
+): readonly { name: string; optional: boolean; type: unknown }[] | undefined {
+  if (node.kind === "function") return (node as FunctionTypeNode).parameters;
+  if (node.kind === "overloadSet") {
+    const sigs = (node as OverloadSetTypeNode).signatures;
+    return sigs[0]?.parameters;
+  }
+  if (node.kind === "constructor") return (node as ConstructorTypeNode).parameters;
+  return undefined;
+}
+
+/** First signature's return type for function-like nodes; undefined otherwise. */
+export function getCallableReturnType(node: TypeNode): TypeNode | undefined {
+  if (node.kind === "function") return (node as FunctionTypeNode).returnType;
+  if (node.kind === "overloadSet") {
+    const sigs = (node as OverloadSetTypeNode).signatures;
+    return sigs[0]?.returnType;
+  }
+  if (node.kind === "constructor") return (node as ConstructorTypeNode).returnType;
+  return undefined;
+}
+
+/**
+ * True iff the type is structurally assignable to Route.
+ */
+export function typeNodeIsRouteCompatible(node: TypeNode, api: TypeInfoApi): boolean {
+  return api.isAssignableTo(node, "Route");
+}
+
+export type RuntimeKind = "fx" | "effect" | "stream" | "plain" | "unknown";
+
+/**
+ * Structurally determines runtime kind via api.isAssignableTo. No fallbacks.
+ * Never returns "unknown"; use callers' failWhenNoTargetsResolved for that.
+ */
+export function typeNodeToRuntimeKind(node: TypeNode, api: TypeInfoApi): RuntimeKind {
+  if (api.isAssignableTo(node, "Fx")) return "fx";
+  if (api.isAssignableTo(node, "Effect")) return "effect";
+  if (api.isAssignableTo(node, "Stream")) return "stream";
+  return "plain";
+}
+
+/** Dependency export form for targeted .provide() lifts. */
+export type DepsExportKind = "layer" | "servicemap" | "array";
+
+/** Result of classifyDepsExport; "unknown" means validation must fail. */
+export type DepsExportClassification = DepsExportKind | "unknown";
+
+/** Classify dependency default export for optimal provide lift. Uses api; node.kind "array" for T[]. */
+export function classifyDepsExport(
+  node: TypeNode,
+  api: TypeInfoApi,
+): DepsExportClassification {
+  if (api.isAssignableTo(node, "Layer")) return "layer";
+  if (api.isAssignableTo(node, "ServiceMap")) return "servicemap";
+  if (node.kind === "array") return "array";
+  return "unknown";
+}
+
+/** True iff the type node is a function whose first parameter expects RefSubject. */
+export function typeNodeExpectsRefSubjectParam(node: TypeNode, api: TypeInfoApi): boolean {
+  if (!isCallableNode(node)) return false;
+  const params = getCallableParameters(node);
+  if (!params || params.length === 0) return false;
+  return api.isAssignableTo(node, "RefSubject", [{ kind: "param", index: 0 }]);
+}
+
+/**
+ * True iff the function's return type is Effect and Effect's success type (first type arg) is assignable to Option.
+ */
+export function typeNodeIsEffectOptionReturn(node: TypeNode, api: TypeInfoApi): boolean {
+  return api.isAssignableTo(node, "Option", [
+    { kind: "returnType" },
+    { kind: "ensure", targetId: "Effect" },
+    { kind: "typeArg", index: 0 },
+  ]);
+}
+
+/**
+ * Classify catch handler form: native (RefSubject=>Fx), fn-cause ((Cause)=>...), fn-error ((E)=>...), or value.
+ */
+export type CatchForm =
+  | { form: "native"; returnKind: RuntimeKind }
+  | { form: "value"; returnKind: RuntimeKind }
+  | { form: "fn-cause"; returnKind: RuntimeKind }
+  | { form: "fn-error"; returnKind: RuntimeKind };
+
+export function classifyCatchForm(node: TypeNode, api: TypeInfoApi): CatchForm {
+  const returnType = getCallableReturnType(node);
+  const returnKind = returnType
+    ? typeNodeToRuntimeKind(returnType, api)
+    : typeNodeToRuntimeKind(node, api);
+  if (!isCallableNode(node)) {
+    return { form: "value", returnKind };
+  }
+  const params = getCallableParameters(node);
+  if (!params || params.length === 0) return { form: "fn-error", returnKind };
+  if (api.isAssignableTo(node, "RefSubject", [{ kind: "param", index: 0 }]))
+    return { form: "native", returnKind };
+  if (api.isAssignableTo(node, "Cause", [{ kind: "param", index: 0 }]))
+    return { form: "fn-cause", returnKind };
+  return { form: "fn-error", returnKind };
+}

package/src/internal/routerDescriptorTree.ts

@@ -0,0 +1,366 @@
+/**
+ * Declarative descriptor tree for router virtual module emission.
+ * Describes ALL route structure and metadata; rendering is a separate phase.
+ *
+ * Optimizations in renderer:
+ * - Router.merge only when 2+ siblings
+ * - No Router.merge() for single child
+ * - Parens only when chaining on multi-arg call expressions
+ * - Positional match when no extra opts
+ */
+
+import type { CatchForm, DepsExportKind, RuntimeKind } from "./routeTypeNode.js";
+
+/** Resolved companion paths per concern (guard, deps, layout, catch). */
+export type ComposedConcernsShape = {
+  readonly guard: readonly string[];
+  readonly dependencies: readonly string[];
+  readonly layout: readonly string[];
+  readonly catch: readonly string[];
+};
+
+/** Path-based refs (relative to baseDir); var names resolved at render time. */
+export type PathRef = string;
+
+/** Per-route match configuration (declarative, path-based). */
+export type RouteMatchDescriptor = {
+  readonly routePath: PathRef;
+  readonly entrypointExport: "handler" | "template" | "default";
+  readonly runtimeKind: RuntimeKind;
+  readonly entrypointIsFunction: boolean;
+  readonly entrypointExpectsRefSubject: boolean;
+  readonly inFileConcerns: {
+    readonly layout?: boolean;
+    readonly dependencies?: boolean;
+    readonly catch?: boolean;
+    readonly guard?: boolean;
+  };
+  readonly composedConcerns: ComposedConcernsShape;
+  /** Guard from in-file, sibling, or directory (path). */
+  readonly guardPath?: PathRef;
+  /** Catch from in-file or sibling (path). */
+  readonly catchPath?: PathRef;
+  readonly catchExport?: "catch" | "catchFn";
+  readonly catchForm?: CatchForm;
+  /** Layout from in-file or sibling (path). */
+  readonly layoutPath?: PathRef;
+  /** Dependencies from in-file or sibling (path). */
+  readonly depsPath?: PathRef;
+};
+
+/** Directory companions (path-based). */
+export type DirectoryCompanions = {
+  readonly layout?: PathRef;
+  readonly catch?: PathRef;
+  readonly dependencies?: PathRef;
+};
+
+/** Declarative tree node: route leaf or directory with children. */
+export type RouterDescriptorNode =
+  | {
+      readonly type: "route";
+      readonly match: RouteMatchDescriptor;
+    }
+  | {
+      readonly type: "directory";
+      readonly dirPath: string;
+      readonly children: readonly RouterDescriptorNode[];
+      readonly companions?: DirectoryCompanions;
+    };
+
+/** Root descriptor tree. */
+export type RouterDescriptorTree = {
+  readonly root: RouterDescriptorNode;
+  readonly rootCompanions?: Pick<DirectoryCompanions, "dependencies">;
+};
+
+/** Input for building the descriptor tree from route descriptors. */
+export type BuildDescriptorTreeInput = {
+  readonly descriptors: readonly {
+    readonly filePath: string;
+    readonly entrypointExport: "handler" | "template" | "default";
+    readonly runtimeKind: RuntimeKind;
+    readonly entrypointIsFunction: boolean;
+    readonly entrypointExpectsRefSubject: boolean;
+    readonly composedConcerns: ComposedConcernsShape;
+    readonly inFileConcerns: {
+      layout?: boolean;
+      dependencies?: boolean;
+      catch?: boolean;
+      guard?: boolean;
+    };
+  }[];
+  readonly dirToCompanions: ReadonlyMap<
+    string,
+    { layout?: string; dependencies?: string; catch?: string }
+  >;
+  readonly guardExportByPath: Readonly<Record<string, "default" | "guard">>;
+  readonly catchExportByPath: Readonly<Record<string, "catch" | "catchFn">>;
+  readonly catchFormByPath: Readonly<Record<string, CatchForm>>;
+  readonly normalizeDir: (dir: string) => string;
+  readonly isDirectoryCompanion: (path: string) => boolean;
+  readonly siblingCompanionPath: (
+    leafPath: string,
+    kind: "guard" | "dependencies" | "layout" | "catch",
+  ) => string;
+};
+
+/** Build declarative tree from route descriptors. */
+export function buildRouterDescriptorTree(input: BuildDescriptorTreeInput): RouterDescriptorTree {
+  const {
+    descriptors,
+    dirToCompanions,
+    catchExportByPath,
+    catchFormByPath,
+    normalizeDir,
+    isDirectoryCompanion,
+    siblingCompanionPath,
+  } = input;
+
+  const toMatchDescriptor = (
+    d: BuildDescriptorTreeInput["descriptors"][number],
+  ): RouteMatchDescriptor => {
+    const sibling = (k: "guard" | "dependencies" | "layout" | "catch") =>
+      siblingCompanionPath(d.filePath, k);
+    const hasSibling = (k: "guard" | "dependencies" | "layout" | "catch") =>
+      d.composedConcerns[k].includes(sibling(k));
+    const dirGuardPath = d.composedConcerns.guard.find(isDirectoryCompanion);
+
+    const guardPath = d.inFileConcerns.guard
+      ? d.filePath
+      : hasSibling("guard")
+        ? sibling("guard")
+        : dirGuardPath;
+    const catchPath = d.inFileConcerns.catch
+      ? d.filePath
+      : hasSibling("catch")
+        ? sibling("catch")
+        : undefined;
+    return {
+      routePath: d.filePath,
+      entrypointExport: d.entrypointExport,
+      runtimeKind: d.runtimeKind,
+      entrypointIsFunction: d.entrypointIsFunction,
+      entrypointExpectsRefSubject: d.entrypointExpectsRefSubject,
+      inFileConcerns: d.inFileConcerns,
+      composedConcerns: d.composedConcerns,
+      guardPath,
+      catchPath,
+      catchExport: catchPath
+        ? (() => {
+            const exp = catchExportByPath[catchPath];
+            if (!exp) throw new Error(`RVM: catch export missing for ${catchPath}`);
+            return exp;
+          })()
+        : undefined,
+      catchForm: catchPath
+        ? (() => {
+            const form = catchFormByPath[catchPath];
+            if (!form) throw new Error(`RVM: catch form missing for ${catchPath}`);
+            return form;
+          })()
+        : undefined,
+      layoutPath: d.inFileConcerns.layout
+        ? d.filePath
+        : hasSibling("layout")
+          ? sibling("layout")
+          : undefined,
+      depsPath: d.inFileConcerns.dependencies
+        ? d.filePath
+        : hasSibling("dependencies")
+          ? sibling("dependencies")
+          : undefined,
+    };
+  };
+
+  const allDirs = new Set(descriptors.map((d) => normalizeDir(dirname(d.filePath))));
+  for (const [dir] of dirToCompanions) allDirs.add(dir);
+  if (allDirs.size > 0) allDirs.add("");
+  const sortedDirs = [...allDirs].sort(
+    (a, b) => b.split("/").filter(Boolean).length - a.split("/").filter(Boolean).length,
+  );
+
+  const dirNodeByPath = new Map<string, RouterDescriptorNode>();
+
+  for (const dir of sortedDirs) {
+    const directRoutes = descriptors.filter((d) => normalizeDir(dirname(d.filePath)) === dir);
+    const isImmediateChild = (s: string) =>
+      s !== dir &&
+      (dir === ""
+        ? s.indexOf("/") === -1
+        : s.startsWith(dir + "/") && s.slice((dir + "/").length).indexOf("/") === -1);
+    const childDirs = sortedDirs.filter(isImmediateChild);
+    const routeChildren: RouterDescriptorNode[] = directRoutes.map((d) => ({
+      type: "route",
+      match: toMatchDescriptor(d),
+    }));
+    const dirChildren: RouterDescriptorNode[] = childDirs.map((s) => dirNodeByPath.get(s)!);
+    const children: RouterDescriptorNode[] = [...routeChildren, ...dirChildren];
+
+    const companions = dirToCompanions.get(dir);
+    const hasCompanions =
+      companions &&
+      (companions.layout || companions.catch || (dir !== "" && companions.dependencies));
+    const node: RouterDescriptorNode =
+      children.length === 0
+        ? {
+            type: "directory",
+            dirPath: dir,
+            children: [],
+            companions: hasCompanions
+              ? {
+                  layout: companions!.layout,
+                  catch: companions!.catch,
+                  dependencies: dir !== "" ? companions!.dependencies : undefined,
+                }
+              : undefined,
+          }
+        : children.length === 1 && !hasCompanions
+          ? children[0]!
+          : {
+              type: "directory",
+              dirPath: dir,
+              children,
+              companions: hasCompanions
+                ? {
+                    layout: companions!.layout,
+                    catch: companions!.catch,
+                    dependencies: dir !== "" ? companions!.dependencies : undefined,
+                  }
+                : undefined,
+            };
+    dirNodeByPath.set(dir, node);
+  }
+
+  let root = dirNodeByPath.get("");
+  if (!root || (root.type === "directory" && root.children.length === 0)) {
+    const flatChildren: RouterDescriptorNode[] = descriptors.map((d) => ({
+      type: "route",
+      match: toMatchDescriptor(d),
+    }));
+    root =
+      flatChildren.length === 0
+        ? { type: "directory", dirPath: "", children: [] }
+        : flatChildren.length === 1
+          ? flatChildren[0]!
+          : { type: "directory", dirPath: "", children: flatChildren };
+  }
+  const rootCompanions = dirToCompanions.get("");
+  return {
+    root,
+    rootCompanions: rootCompanions?.dependencies
+      ? { dependencies: rootCompanions.dependencies }
+      : undefined,
+  };
+}
+
+function dirname(p: string): string {
+  const i = p.lastIndexOf("/");
+  return i < 0 ? "" : p.slice(0, i);
+}
+
+/** Context for rendering: var names and expr generators. */
+export type RenderContext = {
+  readonly varNameByPath: ReadonlyMap<string, string>;
+  readonly guardExportByPath: Readonly<Record<string, "default" | "guard">>;
+  readonly catchExportByPath: Readonly<Record<string, "catch" | "catchFn">>;
+  readonly catchFormByPath: Readonly<Record<string, CatchForm>>;
+  readonly depsFormByPath: Readonly<Record<string, DepsExportKind>>;
+  readonly handlerExprFor: (match: RouteMatchDescriptor, varName: string) => string;
+  readonly catchExprFor: (form: CatchForm, varName: string, exportName: string) => string;
+  readonly depsExprFor: (kind: DepsExportKind, varName: string) => string;
+};
+
+/** Render tree to source. Optimizes: no merge for single child, minimal parens. */
+export function renderRouterDescriptorTree(tree: RouterDescriptorTree, ctx: RenderContext): string {
+  const emit = (node: RouterDescriptorNode): string => {
+    if (node.type === "route") {
+      return emitRoute(node.match, ctx);
+    }
+    const { children, companions } = node;
+    let inner: string;
+    if (children.length === 0) {
+      throw new Error("RVM: directory node with no children should not be rendered");
+    }
+    if (children.length === 1) {
+      inner = emit(children[0]!);
+    } else {
+      inner = `Router.merge(\n  ${children.map((c) => emit(c)).join(",\n  ")}\n)`;
+    }
+    if (companions?.layout) {
+      const v = ctx.varNameByPath.get(companions.layout)!;
+      inner = `${inner}.layout(${v}.layout)`;
+    }
+    if (companions?.catch) {
+      const v = ctx.varNameByPath.get(companions.catch)!;
+      const exp = ctx.catchExportByPath[companions.catch];
+      if (!exp) throw new Error(`RVM: catch export missing for ${companions.catch}`);
+      const form = ctx.catchFormByPath[companions.catch];
+      if (!form) throw new Error(`RVM: catch form missing for ${companions.catch}`);
+      const catchExpr = ctx.catchExprFor(form, v, exp);
+      inner = `${inner}.catchCause(${catchExpr})`;
+    }
+    if (companions?.dependencies) {
+      const v = ctx.varNameByPath.get(companions.dependencies)!;
+      const depsKind = ctx.depsFormByPath[companions.dependencies];
+      if (depsKind === undefined)
+        throw new Error(
+          `RVM: dependency form unknown for ${companions.dependencies}; validation should have failed (RVM-DEPS-001)`,
+        );
+      const depsExpr = ctx.depsExprFor(depsKind, v);
+      inner = `${inner}.provide(${depsExpr})`;
+    }
+    return inner;
+  };
+
+  let result = emit(tree.root);
+  if (tree.rootCompanions?.dependencies) {
+    const v = ctx.varNameByPath.get(tree.rootCompanions.dependencies)!;
+    const depsKind = ctx.depsFormByPath[tree.rootCompanions.dependencies];
+    if (depsKind === undefined)
+      throw new Error(
+        `RVM: dependency form unknown for ${tree.rootCompanions.dependencies}; validation should have failed (RVM-DEPS-001)`,
+      );
+    const depsExpr = ctx.depsExprFor(depsKind, v);
+    result = `${result}.provide(${depsExpr})`;
+  }
+  return result;
+}
+
+/** Emit Router.match(...) for a route. Favors positional when no extra opts. */
+function emitRoute(match: RouteMatchDescriptor, ctx: RenderContext): string {
+  const routeVar = ctx.varNameByPath.get(match.routePath)!;
+  const routeRef = `${routeVar}.route`;
+  const handlerExpr = ctx.handlerExprFor(match, routeVar);
+  const hasExtraOpts = match.layoutPath || match.depsPath || match.catchPath;
+  const guardPath = match.guardPath;
+  const guardExport = guardPath ? ctx.guardExportByPath[guardPath] : undefined;
+  const guardExpr =
+    guardPath && guardExport ? `${ctx.varNameByPath.get(guardPath)!}.${guardExport}` : undefined;
+
+  const opts: string[] = [`handler: ${handlerExpr}`];
+  if (match.depsPath) {
+    opts.push(`dependencies: ${ctx.varNameByPath.get(match.depsPath)!}.dependencies`);
+  }
+  if (match.layoutPath) {
+    opts.push(`layout: ${ctx.varNameByPath.get(match.layoutPath)!}.layout`);
+  }
+  if (match.catchPath && match.catchExport) {
+    const catchVar = ctx.varNameByPath.get(match.catchPath)!;
+    const form = match.catchForm;
+    if (!form) throw new Error(`RVM: catch form missing for ${match.catchPath}`);
+    opts.push(`catch: ${ctx.catchExprFor(form, catchVar, match.catchExport)}`);
+  }
+
+  if (guardExpr && !hasExtraOpts) {
+    return `Router.match(${routeRef}, ${guardExpr}, ${handlerExpr})`;
+  }
+  if (guardExpr && hasExtraOpts) {
+    opts.unshift(`guard: ${guardExpr}`);
+    return `Router.match(${routeRef}, ${guardExpr}, { ${opts.join(", ")} })`;
+  }
+  if (!hasExtraOpts) {
+    return `Router.match(${routeRef}, ${handlerExpr})`;
+  }
+  return `Router.match(${routeRef}, { ${opts.join(", ")} })`;
+}

package/src/internal/typeTargetBootstrap.ts

@@ -0,0 +1,24 @@
+/**
+ * Bootstrap file for TypeInfoApi type target resolution in tests.
+ * Exists so resolveTypeTargetsFromSpecs can find canonical Effect/Fx/RefSubject/Stream/Route types
+ * when the program includes this file. Do not use; for test harness only.
+ */
+import * as Effect from "effect/Effect";
+import * as Fx from "@typed/fx/Fx";
+import * as RefSubject from "@typed/fx/RefSubject";
+import * as Stream from "effect/Stream";
+import * as Route from "@typed/router";
+import * as Option from "effect/Option";
+import * as Cause from "effect/Cause";
+import * as Layer from "effect/Layer";
+import * as ServiceMap from "effect/ServiceMap";
+void Effect;
+void Fx;
+void RefSubject;
+void Stream;
+void Route;
+void Option;
+void Cause;
+void Layer;
+void ServiceMap;
+export {};

package/src/internal/typeTargetBootstrapHttpApi.ts

@@ -0,0 +1,22 @@
+/**
+ * Bootstrap file for TypeInfoApi type target resolution in HttpApi tests.
+ * Exists so resolveTypeTargetsFromSpecs can find canonical HttpApi/Route/Effect/Schema types
+ * when the program includes this file. Do not use; for test harness only.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Route from "@typed/router";
+import * as HttpApiModule from "effect/unstable/httpapi/HttpApi";
+import * as HttpApiGroupModule from "effect/unstable/httpapi/HttpApiGroup";
+import * as HttpApiEndpointModule from "effect/unstable/httpapi/HttpApiEndpoint";
+import * as HttpApiBuilderModule from "effect/unstable/httpapi/HttpApiBuilder";
+import * as HttpServerResponseModule from "effect/unstable/http/HttpServerResponse";
+void Effect;
+void Schema;
+void Route;
+void HttpApiModule;
+void HttpApiGroupModule;
+void HttpApiEndpointModule;
+void HttpApiBuilderModule;
+void HttpServerResponseModule;
+export {};

package/src/internal/typeTargetSpecs.ts

@@ -0,0 +1,35 @@
+import type { TypeTargetSpec } from "@typed/virtual-modules";
+
+/**
+ * Type target specs for router virtual module structural validation.
+ * Pass to createTypeInfoApiSession typeTargetSpecs option.
+ *
+ * IMPORTANT: Each spec's `module` must exactly match the import string in user source.
+ * Specs are canonical-only (no fallbacks or alternate import paths).
+ */
+export const ROUTER_TYPE_TARGET_SPECS: readonly TypeTargetSpec[] = [
+  { id: "Fx", module: "@typed/fx/Fx", exportName: "Fx" },
+  { id: "Effect", module: "effect/Effect", exportName: "Effect" },
+  { id: "Stream", module: "effect/Stream", exportName: "Stream" },
+  { id: "RefSubject", module: "@typed/fx/RefSubject", exportName: "RefSubject" },
+  { id: "Cause", module: "effect/Cause", exportName: "Cause" },
+  { id: "Option", module: "effect/Option", exportName: "Option" },
+  { id: "Layer", module: "effect/Layer", exportName: "Layer" },
+  { id: "ServiceMap", module: "effect/ServiceMap", exportName: "ServiceMap" },
+  { id: "Route", module: "@typed/router", exportName: "Route" },
+];
+
+/**
+ * Type target specs for HttpApi virtual module structural validation.
+ * Pass to createTypeInfoApiSession typeTargetSpecs option.
+ */
+export const HTTPAPI_TYPE_TARGET_SPECS: readonly TypeTargetSpec[] = [
+  { id: "HttpApi", module: "effect/unstable/httpapi/HttpApi", exportName: "HttpApi" },
+  { id: "HttpApiGroup", module: "effect/unstable/httpapi/HttpApiGroup", exportName: "HttpApiGroup" },
+  { id: "HttpApiEndpoint", module: "effect/unstable/httpapi/HttpApiEndpoint", exportName: "HttpApiEndpoint" },
+  { id: "HttpApiBuilder", module: "effect/unstable/httpapi/HttpApiBuilder", exportName: "HttpApiBuilder" },
+  { id: "Schema", module: "effect/Schema", exportName: "Top" },
+  { id: "Effect", module: "effect/Effect", exportName: "Effect" },
+  { id: "Route", module: "@typed/router", exportName: "Route" },
+  { id: "HttpServerResponse", module: "effect/unstable/http/HttpServerResponse", exportName: "HttpServerResponse" },
+];