refactor(ev): organize internal build domains

AGENT.md

@@ -101,11 +101,11 @@ npm --workspace @evjs/ev test -- tests/build-tools-graph-plan.test.ts
 
 | Surface | Primary implementation | Focused validation |
 | --- | --- | --- |
-| Page convention and graph | `packages/ev/src/_internal/build/page-route-conventions.ts`, `page-routes.ts`, `graph/*`, `plan/*` | `npx turbo run test --filter=@evjs/ev` |
-| Server routes and middleware | `server-route-conventions.ts`, `server-routes.ts`, `server-conventions.ts` | `npx turbo run test --filter=@evjs/ev` |
+| Page convention and graph | `packages/ev/src/_internal/build/conventions/page-route-conventions.ts`, `discovery/page-routes.ts`, `graph/*`, `plan/*` | `npx turbo run test --filter=@evjs/ev` |
+| Server routes and middleware | `conventions/server-route-conventions.ts`, `discovery/server-routes.ts`, `discovery/server-conventions.ts` | `npx turbo run test --filter=@evjs/ev` |
 | Config and package surface | `packages/ev/src/config`, package manifests | `npx turbo run test --filter=@evjs/ev` |
 | Shared contracts | `packages/shared/src/manifest` | `npx turbo run test --filter=@evjs/shared` |
-| Server functions | `packages/ev/src/_internal/build/server-fns.ts`, client/server function runtimes | `npx turbo run test --filter=@evjs/client --filter=@evjs/server` |
+| Server functions | `packages/ev/src/_internal/build/analysis/server-fns.ts`, client/server function runtimes | `npx turbo run test --filter=@evjs/client --filter=@evjs/server` |
 | SSR, SSG, PPR, RSC | graph/plan, client RSC, server framework rendering | `npx turbo run test --filter=@evjs/ev --filter=@evjs/client --filter=@evjs/server` |
 | Bundler mapping | `packages/bundler-*/src/adapter` and manifest generators | corresponding bundler package test |
 | Documentation | `docs/docs`, Chinese translations, package/example READMEs | `npm run lint`, `npm --workspace evjs-docs run build`, `git diff --check` |

AGENTS.md

@@ -18,11 +18,11 @@ server routes, examples, or scaffolds change.
 
 | Concern | Canonical implementation | Discovery / coverage |
 | --- | --- | --- |
-| Page markers and URL segments | `packages/ev/src/_internal/build/page-route-conventions.ts` | `page-routes.ts`, `packages/ev/tests/build-tools-page-routes.test.ts` |
-| Server request-route markers and URL segments | `packages/ev/src/_internal/build/server-route-conventions.ts` | `server-routes.ts`, `packages/ev/tests/build-tools-server-routes.test.ts` |
+| Page markers and URL segments | `packages/ev/src/_internal/build/conventions/page-route-conventions.ts` | `discovery/page-routes.ts`, `packages/ev/tests/build-tools-page-routes.test.ts` |
+| Server request-route markers and URL segments | `packages/ev/src/_internal/build/conventions/server-route-conventions.ts` | `discovery/server-routes.ts`, `packages/ev/tests/build-tools-server-routes.test.ts` |
 | Public config and SPA/MPA selection | `packages/ev/src/config/index.ts` | `packages/ev/tests/config.test.ts` |
 | Semantic graph and build plan | `packages/ev/src/_internal/build/graph/*`, `plan/*` | `packages/ev/tests/build-tools-graph-plan.test.ts` |
-| Typed plugin settings and generated Page types | `packages/ev/src/config/plugins.ts`, `_internal/build/plugin-settings.ts`, `plugin-types.ts` | `packages/ev/tests/plugin-settings.test.ts`, `plugin-types.test.ts` |
+| Typed plugin settings and generated Page types | `packages/ev/src/config/plugins.ts`, `_internal/build/plugins/settings.ts`, `typegen/plugin-types.ts` | `packages/ev/tests/plugin-settings.test.ts`, `plugin-types.test.ts` |
 | Shared graph/output contracts | `packages/shared/src/manifest` | `packages/shared/tests/manifest.test.ts` |
 
 ## Architecture Rules

ARCHITECTURE.md

@@ -85,6 +85,26 @@ Programmatic `createApp()`, client route trees, and server `createRoute()`
 declarations are runtime primitives; framework convention discovery does not
 scan them.
 
+## Internal Build Layout
+
+`packages/ev/src/_internal/build` is grouped by capability instead of build
+phase. Its root contains only the curated `index.ts`, the command façade, and
+the small shared `types.ts` / `utils.ts` modules.
+
+| Domain | Responsibility |
+| --- | --- |
+| `analysis`, `discovery`, `conventions` | Parse framework semantics, discover positive anchors, and own filesystem naming rules. |
+| `graph`, `plan` | Project discovered semantics into `CoreGraph` and `BuildPlan`; each `index.ts` is a thin façade over implementation and contract modules. |
+| `generated-ir`, `typegen` | Materialize `.ev` inputs and authored-source declaration files. |
+| `bundler`, `plugins` | Define adapter contracts and orchestrate plugin settings and lifecycle state. |
+| `output` | Validate, link, transform, and transactionally publish framework-owned output, including HTML. |
+| `config-loading`, `operations`, `dev` | Load observed configuration, coordinate commands, and own development runtime/watch state. |
+| `transforms` | Rewrite client and server modules at bundler boundaries. |
+
+Domain implementations import focused leaf modules. They do not import a
+domain's broad `index.ts` façade internally; façades exist for stable consumers
+and should not become implementation owners.
+
 ## Build Flow
 
 ```mermaid

e2e/cases/render-modes.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import type { PageMetadata } from "@evjs/shared/manifest";
 import { expect, type Page } from "@playwright/test";
-import { createRscPageBuildEntryName } from "../../packages/ev/src/_internal/build/build-entry-conventions.js";
+import { createRscPageBuildEntryName } from "../../packages/ev/src/_internal/build/conventions/build-entry-conventions.js";
 import { createExampleTest } from "../fixtures";
 
 const exampleDir = path.resolve(

packages/bundler-utoopack/tests/adapter.test.ts

@@ -28,8 +28,8 @@ import {
 } from "@evjs/shared/manifest";
 import type { ConfigComplete } from "@utoo/pack";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { withPageRoutingDefaults } from "../../ev/esm/_internal/build/convention-config.js";
-import { createClientRuntime } from "../../ev/src/_internal/build/framework-runtime.js";
+import { withPageRoutingDefaults } from "../../ev/esm/_internal/build/discovery/convention-config.js";
+import { createClientRuntime } from "../../ev/src/_internal/build/output/framework-runtime.js";
 import {
   utoopackAdapter,
   __testing as utoopackAdapterTesting,

packages/bundler-webpack/tests/adapter.test.ts

@@ -28,14 +28,14 @@ import {
 import { Volume } from "memfs";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { Compiler } from "webpack";
-import { withPageRoutingDefaults } from "../../ev/esm/_internal/build/convention-config.js";
-import { createPageClientBuildEntryName } from "../../ev/src/_internal/build/build-entry-conventions.js";
-import { linkAndEmitBuildOutput } from "../../ev/src/_internal/build/framework-output.js";
+import { withPageRoutingDefaults } from "../../ev/esm/_internal/build/discovery/convention-config.js";
+import { createPageClientBuildEntryName } from "../../ev/src/_internal/build/conventions/build-entry-conventions.js";
+import { linkAndEmitBuildOutput } from "../../ev/src/_internal/build/output/framework-output.js";
 import {
   createClientRuntime,
   createFrameworkRuntime,
   type FrameworkRuntimeOutput,
-} from "../../ev/src/_internal/build/framework-runtime.js";
+} from "../../ev/src/_internal/build/output/framework-runtime.js";
 import type { WebpackConfigs } from "../src/adapter/create-config.js";
 import { __testing as webpackAdapterTesting } from "../src/adapter/index.js";
 import { __testing as serverPublicAssetTesting } from "../src/adapter/server-public-assets.js";

packages/ev/src/_internal/build/page-module-exports.ts → packages/ev/src/_internal/build/analysis/page-module-exports.ts

@@ -1,5 +1,5 @@
 import { collectModuleExportNames } from "./module-exports.js";
-import { parseRouteModuleWithError } from "./routes/shared.js";
+import { parseRouteModuleWithError } from "./route-module.js";
 
 const PAGE_RENDERING_CONFIG_EXPORTS = [
   "render",

packages/ev/src/_internal/build/ppr-regions.ts → packages/ev/src/_internal/build/analysis/ppr-regions.ts

@@ -9,6 +9,7 @@ import type {
   ModuleItem,
   ObjectExpression,
 } from "@swc/types";
+import { toPosixPath } from "../utils.js";
 import {
   collectExportedVariableValueAnalysis,
   collectModuleExportNames,
@@ -20,8 +21,7 @@ import {
   parseRouteModule,
   parseRouteModuleWithError,
   type RouteAst,
-} from "./routes/shared.js";
-import { toPosixPath } from "./utils.js";
+} from "./route-module.js";
 
 export interface PprRegionAnalysis {
   regions: Record<string, PprRegionConfig>;

packages/ev/src/_internal/build/routes/shared.ts → packages/ev/src/_internal/build/analysis/route-module.ts

@@ -1,6 +1,6 @@
 import { parseSync } from "@swc/core";
 import type { Expression, KeyValueProperty, MethodProperty } from "@swc/types";
-import { collectModuleExportNames } from "../module-exports.js";
+import { collectModuleExportNames } from "./module-exports.js";
 
 export type RouteAst = ReturnType<typeof parseSync>;
 

packages/ev/src/_internal/build/rsc-refs.ts → packages/ev/src/_internal/build/analysis/rsc-refs.ts

@@ -6,24 +6,24 @@ import type {
 } from "@evjs/shared/manifest";
 import { parseSync } from "@swc/core";
 import type { ModuleItem } from "@swc/types";
+import type { TransformResult } from "../transforms/types.js";
+import {
+  CONFLICTING_FRAMEWORK_DIRECTIVES_MESSAGE,
+  detectConflictingFrameworkDirectives,
+  detectFrameworkDirective,
+  detectUseServer,
+  hashServerFunction,
+} from "../utils.js";
 import {
   collectModuleExportNames,
   formatModuleExportName,
 } from "./module-exports.js";
-import { formatParseErrorMessage } from "./routes/shared.js";
+import { formatParseErrorMessage } from "./route-module.js";
 import {
   analyzeServerFunctionExportsFromAst,
   formatServerFunctionParseDiagnostic,
   isServerFunctionParseDiagnostic,
 } from "./server-fns.js";
-import type { TransformResult } from "./transforms/index.js";
-import {
-  CONFLICTING_FRAMEWORK_DIRECTIVES_MESSAGE,
-  detectConflictingFrameworkDirectives,
-  detectFrameworkDirective,
-  detectUseServer,
-  hashServerFunction,
-} from "./utils.js";
 
 type RscReferenceAst = ReturnType<typeof parseSync>;
 

packages/ev/src/_internal/build/server-fns.ts → packages/ev/src/_internal/build/analysis/server-fns.ts

@@ -7,12 +7,12 @@ import type {
   Param,
   Pattern,
 } from "@swc/types";
+import { detectUseServer } from "../utils.js";
 import {
   getIdentifierExportName,
   getModuleExportName,
 } from "./module-exports.js";
-import { formatParseErrorMessage } from "./routes/shared.js";
-import { detectUseServer } from "./utils.js";
+import { formatParseErrorMessage } from "./route-module.js";
 
 type ServerFunctionAst = ReturnType<typeof parseSync>;
 

packages/ev/src/_internal/build/bundler-config.ts → packages/ev/src/_internal/build/bundler/config.ts

@@ -1,6 +1,6 @@
-import type { ResolvedConfig } from "../../config/index.js";
-import { resolveBundlerConfig } from "../../config/index.js";
-import type { BundlerAdapter } from "./bundler.js";
+import type { ResolvedConfig } from "../../../config/index.js";
+import { resolveBundlerConfig } from "../../../config/index.js";
+import type { BundlerAdapter } from "./contracts.js";
 
 export function resolveBundler<TBundlerCfg>(
   configBundler: BundlerAdapter<TBundlerCfg> | undefined,

packages/ev/src/_internal/build/bundler.ts → packages/ev/src/_internal/build/bundler/contracts.ts

@@ -7,8 +7,8 @@ import {
   assertPortableRelativeBrowserArtifactPath,
   assertServerRelativeArtifactPath,
 } from "@evjs/shared/manifest";
-import type { ResolvedFrameworkConfig } from "../../config/index.js";
-import type { PluginHooks } from "../../plugin/index.js";
+import type { ResolvedFrameworkConfig } from "../../../config/index.js";
+import type { PluginHooks } from "../../../plugin/index.js";
 
 export interface BundlerEmittedFiles {
   client?: readonly string[];

packages/ev/src/_internal/build/bundler-output-files.ts → packages/ev/src/_internal/build/bundler/output-files.ts

@@ -1,11 +1,11 @@
 import type { BuildPlan } from "@evjs/shared/manifest";
-import type { BundlerEmittedFiles } from "./bundler.js";
 import {
   assertPortableRelativeArtifactPath,
   assertPortableRelativeBrowserArtifactPath,
   canonicalPortableArtifactPathKey,
   portableArtifactPathsConflict,
-} from "./portable-artifact-path.js";
+} from "../output/portable-artifact-path.js";
+import type { BundlerEmittedFiles } from "./contracts.js";
 
 interface PortableOutputFile {
   fileName: string;