refactor: replace overloaded surface terminology

packages/client/modules/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/modules/README.md
-README.md: a1d578850c2518a85dc32f048768b78caf5ffec4
+README.md: efaff699839b977cc45f89f3c164402241b90dc2
 README.zh.md: 772a4870f7ef6730d9d3d4db434ed771d97984f0

packages/client/modules/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` through its `internal` contract — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.
 
-Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → export surface, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id name the same surface (a plugin bundle IS its package's client half).
+Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → exports, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id resolve to the same exports (a plugin bundle IS its package's client half).
 
 Resolution branch order (`import(specifier)`): platform seed word → shell instance; memoized record → surface; shell-own static registry (`registerStatic`, app-shell) → module; registered factory → materialize; graph row (`window.__DSH_BOOT__`) → load its external classic script + materialize; anything else throws — the runtime mirror of the build-time bundle purity gate. The synchronous `require` handed to factories walks the same order minus the asynchronous load branch and records observed edges into the module record. `prefetch` is the stage-one arrival hook (script load and factory registration only; concurrent calls share one in-flight task); `invalidate` drops the factory and materialized record so the next prefetch/import reloads the script (the HMR hook).
 

packages/client/modules/src/client/manifest.ts

@@ -10,13 +10,13 @@
  * factory (`window.__ModuleLoader__.load({id, factory})`); every module body
  * side effect — including CSS injection — lives inside the factory closure
  * and runs at materialization, not at script execution. Materialization
- * (factory(require) → export surface) happens on first import/require and is
+ * (factory(require) → exports) happens on first import/require and is
  * memoized in {@link ClientModuleLoader.loadCache}; a factory that requires
  * another registered-but-unmaterialized module materializes it recursively,
  * so load order needs no external sequencing.
  *
  * Resolution branch order (import): seed word → shell instance; memoized
- * record → surface; static registry (shell-own modules, e.g. app-shell) →
+ * record → exports; static registry (shell-own modules, e.g. app-shell) →
  * module; registered factory → materialize; graph row → load + materialize;
  * anything else → throw (loud — the runtime mirror of the
  * build-time bundle purity gate). The synchronous `require` handed to
@@ -149,13 +149,13 @@ export interface ClientPluginHandoff {
   id: string
   /**
    * Closure factory holding the whole bundle body: receives the synchronous
-   * require bound to the module table and returns the bundle's export
-   * surface. Runs once, at materialization.
+   * require bound to the module table and returns the bundle's exports. Runs
+   * once, at materialization.
    */
   factory: (require: (spec: string) => unknown) => Record<string, unknown>
 }
 
-/** Window surface of the web boot protocol: the host-injected graph, the registration sink, and the kernel handoff slot. */
+/** Window API of the web boot protocol: the host-injected graph, registration sink, and kernel handoff slot. */
 export interface DshWindow {
   /** Host-composed entry graph, injected before the shell bundle runs; wire-boundary raw until {@link parseBootManifest}. */
   __DSH_BOOT__?: unknown
@@ -174,8 +174,8 @@ export interface DshWindow {
 export interface ClientModuleRecord {
   /** Module id (entry name / package name). */
   id: string
-  /** The materialized export surface (factory `module.exports`, or the shell module for static registrations). */
-  surface: unknown
+  /** Materialized exports (`module.exports` from a factory, or a statically registered shell module). */
+  exports: unknown
   /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
   styles: string[]
   /** Observed `require()` edges (module-graph boundary; only table words can appear today). */
@@ -190,7 +190,7 @@ export interface ClientModuleRecord {
 export interface ClientModuleLoader {
   /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
   version: 'client'
-  /** Materialized-module registry: id → record. The governance-side read face for entry export surfaces. */
+  /** Materialized-module registry: id → record. The governance-side read API for entry exports. */
   loadCache: Map<string, ClientModuleRecord>
   /**
    * Internal contract consumed by the vendored Loader's `tree.import`. Resolves
@@ -199,7 +199,7 @@ export interface ClientModuleLoader {
    * @param specifier - module specifier (entry name or table word).
    * @param parentURL - importer URL (unused — the client module graph is flat).
    * @param attrs - Import attributes (unused; interface parity with Node's loader contract).
-   * @returns the module's export surface.
+   * @returns the module's exports.
    */
   import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>
   /**

packages/client/modules/src/client/system.ts

@@ -28,7 +28,7 @@ const defaultLoadBundle = (url: string): Promise<void> => new Promise((resolve,
 /**
  * A plugin bundle IS its package's client half: `<id>/client` (the exports
  * subpath external bundles emit) and the bare graph id name the same
- * surface, so table lookups normalize the suffix away.
+ * exports, so table lookups normalize the suffix away.
  */
 const stripClientSuffix = (spec: string): string =>
   spec.endsWith('/client') ? spec.slice(0, -'/client'.length) : spec
@@ -123,8 +123,8 @@ export class ClientModuleSystem implements ClientModuleLoader {
     this.materializing.add(id)
     try {
       const edges = new Set<string>()
-      const surface = registered(this.makeRequire(edges))
-      const record: ClientModuleRecord = { id, surface, styles: claimStyles(id), edges }
+      const exports = registered(this.makeRequire(edges))
+      const record: ClientModuleRecord = { id, exports, styles: claimStyles(id), edges }
       this.loadCache.set(id, record)
       return record
     } finally {
@@ -146,8 +146,8 @@ export class ClientModuleSystem implements ClientModuleLoader {
       if (this.statics.has(spec)) return this.statics.get(spec)
       const id = stripClientSuffix(spec)
       const record = this.loadCache.get(id)
-      if (record !== undefined) return record.surface
-      if (this.factories.has(id)) return this.materialize(id).surface
+      if (record !== undefined) return record.exports
+      if (this.factories.has(id)) return this.materialize(id).exports
       throw new Error(
         `client-modules: require("${spec}") missed the module table — not a platform seed word, not a shell-own module, `
         + 'and no registered factory (a build-time externals drift, or a forbidden cross-plugin value import)',
@@ -158,11 +158,11 @@ export class ClientModuleSystem implements ClientModuleLoader {
   async import(specifier: string): Promise<unknown> {
     if (this.seed.has(specifier)) return this.seed.get(specifier)
     const existing = this.loadCache.get(specifier)
-    if (existing !== undefined) return existing.surface
+    if (existing !== undefined) return existing.exports
     if (this.statics.has(specifier)) {
-      const surface = this.statics.get(specifier)
-      this.loadCache.set(specifier, { id: specifier, surface, styles: [], edges: new Set() })
-      return surface
+      const exports = this.statics.get(specifier)
+      this.loadCache.set(specifier, { id: specifier, exports, styles: [], edges: new Set() })
+      return exports
     }
     if (!this.factories.has(specifier)) {
       const row = this.graphRows.get(specifier)
@@ -174,7 +174,7 @@ export class ClientModuleSystem implements ClientModuleLoader {
       }
       await this.arrive(row)
     }
-    return this.materialize(specifier).surface
+    return this.materialize(specifier).exports
   }
 
   registerStatic(id: string, module: unknown): void {

packages/client/modules/tests/loader.spec.ts

@@ -70,7 +70,7 @@ describe('lazy CJS arrival', () => {
     expect(b.loader.loadCache.size).toBe(0)
   })
 
-  it('import materializes once and memoizes the export surface', async () => {
+  it('import materializes once and memoizes the exports', async () => {
     const ran: string[] = []
     const b = bench([row('a')], { a: () => { ran.push('a'); return { marker: 'a' } } })
     const first = await b.loader.import('a', '', {})
@@ -83,8 +83,8 @@ describe('lazy CJS arrival', () => {
 
   it('import without prefetch loads, registers, and materializes in one call', async () => {
     const b = bench([row('a')], { a: () => ({ marker: 'direct' }) })
-    const surface = await b.loader.import('a', '', {})
-    expect((surface as { marker: string }).marker).toBe('direct')
+    const exports = await b.loader.import('a', '', {})
+    expect((exports as { marker: string }).marker).toBe('direct')
     expect(b.fetched).toHaveLength(1)
   })
 
@@ -123,8 +123,8 @@ describe('require resolution', () => {
     })
     await b.loader.prefetch('a')
     await b.loader.prefetch('b')
-    const surface = await b.loader.import('a', '', {})
-    expect((surface as { got: string }).got).toBe('from-b')
+    const exports = await b.loader.import('a', '', {})
+    expect((exports as { got: string }).got).toBe('from-b')
     expect(order).toEqual(['a', 'b'])
     expect(b.loader.loadCache.get('a')?.edges.has('b/client')).toBe(true)
     expect(b.loader.loadCache.has('b')).toBe(true)
@@ -135,8 +135,8 @@ describe('require resolution', () => {
     const b = bench([row('a')], {
       a: req => ({ dep: req('react') }),
     }, { seed: { react } })
-    const surface = await b.loader.import('a', '', {})
-    expect((surface as { dep: unknown }).dep).toBe(react)
+    const exports = await b.loader.import('a', '', {})
+    expect((exports as { dep: unknown }).dep).toBe(react)
     expect(await b.loader.import('react', '', {})).toBe(react)
     expect(b.loader.loadCache.has('react')).toBe(false)
   })
@@ -284,8 +284,8 @@ describe('default transport seam', () => {
       })
     })
     const loader: ClientModuleLoader = new ClientModuleSystem({ modules: [row('dee')], staticModules: {} })
-    const surface = await loader.import('dee', '', {})
-    expect((surface as { marker: string }).marker).toBe('via-script')
+    const exports = await loader.import('dee', '', {})
+    expect((exports as { marker: string }).marker).toBe('via-script')
     expect(append).toHaveBeenCalledOnce()
     expect([...document.querySelectorAll('script')]).toEqual([])
   })