docs(bundler): sync manifest loader fs notes

tools/egg-bundler/README.md

@@ -100,8 +100,10 @@ cd dist-bundle
 node worker.js
 ```
 
-The generated worker entry runs the app in Egg's single-process mode and serves
-framework file discovery/module resolution from the inlined bundle map.
+The generated worker entry runs the app in Egg's single-process mode with a
+manifest-backed loader filesystem, so framework file discovery and module
+resolution are served from the inlined bundle map before falling back to the
+real filesystem.
 
 See [output-structure.md](./docs/output-structure.md) for artifact layout,
 externals behavior, and current limitations.

tools/egg-bundler/docs/output-structure.md

@@ -33,14 +33,17 @@ node worker.js
 ```
 
 The worker entry installs `ManifestStore.setBundleStore(...)` and
-`globalThis.__EGG_BUNDLE_MODULE_LOADER__` before calling
-`startEgg({ baseDir: outputDir, framework, mode: 'single' })`, so framework
-specifier lookup is served by the already imported bundled framework module,
-without adding framework path aliases. Runtime lookup keeps
-the deploy output directory separate from the original app paths: the bundle map
-is keyed by relKey, output-dir absolute paths, precomputed original app absolute
-paths, and manifest `resolveCache` request aliases. Application code and plugins
-may still use `fs` for resources such as config, views, or assets.
+`globalThis.__EGG_BUNDLE_MODULE_LOADER__`, creates a `ManifestLoaderFS` from the
+startup manifest, then calls
+`startEgg({ baseDir: outputDir, framework, mode: 'single', loaderFS })`.
+Framework specifier lookup is served by the already imported bundled framework
+module, without adding framework path aliases. Runtime lookup keeps the deploy
+output directory separate from the original app paths: the bundle map is keyed
+by relKey, output-dir absolute paths, precomputed original app absolute paths,
+and manifest `resolveCache` request aliases. Loader file discovery, JSON reads,
+and module loading use the manifest-backed loader filesystem first and fall back
+to the real filesystem when a path is outside the manifest. Application code and
+plugins may still use `fs` for resources such as config, views, or assets.
 
 ## Runtime assets
 

wiki/index.md

@@ -20,7 +20,7 @@ Read this file before exploring raw sources.
 
 - [Core Package](./packages/core.md) - Loader, lifecycle, and application core primitives used by Egg runtime packages.
 - [Egg Bundler](./packages/egg-bundler.md) - Tooling package that bundles Egg applications and backs `egg-bin bundle`.
-- [Loader FS Package](./packages/loader-fs.md) - Shared loader-facing filesystem boundary for Egg loaders and future bundled runtimes.
+- [Loader FS Package](./packages/loader-fs.md) - Shared loader-facing filesystem boundary for Egg loaders and bundled runtimes.
 - [Onerror Plugin](./packages/onerror.md) - Default Egg error-handling plugin and configurable response negotiation layer.
 - [Typings Package](./packages/typings.md) - Shared TypeScript type surface for cross-package Egg typings.
 - [Utils Package](./packages/utils.md) - Shared utility package for module loading and bundled module-loader integration.

wiki/log.md

@@ -2,6 +2,12 @@
 
 Dates use the workspace-local Asia/Shanghai calendar date.
 
+## [2026-06-02] package | sync manifest-backed loader FS docs
+
+- sources touched: `packages/core/src/loader/loader_fs.ts`, `packages/core/src/index.ts`, `tools/egg-bundler/src/lib/EntryGenerator.ts`, `packages/egg/src/lib/start.ts`
+- pages updated: `tools/egg-bundler/README.md`, `tools/egg-bundler/docs/output-structure.md`, `wiki/log.md`, `wiki/packages/core.md`, `wiki/packages/egg-bundler.md`, `wiki/packages/loader-fs.md`
+- note: Recorded that bundled workers now create `ManifestLoaderFS`, pass it into `startEgg()`, and serve loader discovery/module loading from manifest data before falling back to the real filesystem.
+
 ## [2026-05-10] package | extract shared LoaderFS package
 
 - sources touched: `packages/loader-fs/src/index.ts`, `packages/loader-fs/package.json`, `packages/core/src/index.ts`, `packages/core/src/loader/file_loader.ts`, `packages/core/src/loader/egg_loader.ts`

wiki/packages/core.md

@@ -4,10 +4,11 @@ type: package
 summary: Loader, lifecycle, and application core primitives used by Egg runtime packages.
 source_files:
   - packages/core/src/index.ts
+  - packages/core/src/loader/loader_fs.ts
   - packages/core/src/loader/file_loader.ts
   - packages/core/src/loader/context_loader.ts
   - packages/core/src/loader/egg_loader.ts
-updated_at: 2026-05-10
+updated_at: 2026-06-02
 status: active
 ---
 
@@ -20,11 +21,18 @@ support, lifecycle, and base context classes.
 ## LoaderFS
 
 `@eggjs/core` consumes and re-exports `LoaderFS` and `RealLoaderFS` from
-`@eggjs/loader-fs`. The abstraction remains the minimal filesystem boundary for
-loader-facing file access: `exists`, `stat`, `realpath`, `readJSON`, `glob`, and
-`loadFile`, without trying to polyfill the full Node.js `fs` module.
+`@eggjs/loader-fs`, and also exports `ManifestLoaderFS` from its manifest-aware
+loader implementation. The abstraction remains the minimal filesystem boundary
+for loader-facing file access: `exists`, `stat`, `realpath`, `readJSON`,
+`glob`, and `loadFile`, without trying to polyfill the full Node.js `fs` module.
 
 `EggLoaderOptions`, `FileLoaderOptions`, and `ContextLoaderOptions` can carry a
 custom `loaderFS`. `EggLoader` passes its loader FS into `loadToApp()` and
-`loadToContext()` so later bundled loaders can replace file discovery and module
+`loadToContext()` so bundled loaders can replace file discovery and module
 loading without changing the public loader call sites.
+
+`ManifestLoaderFS` adapts a `ManifestStore` into that loader boundary for
+bundled runtimes. It answers `exists`, `stat`, `realpath`, and `glob` from
+manifest `fileDiscovery` and `resolveCache` data, loads bundled modules through
+`globalThis.__EGG_BUNDLE_MODULE_LOADER__`, and delegates to a fallback
+`LoaderFS` for paths not covered by the manifest.

wiki/packages/egg-bundler.md

@@ -9,7 +9,7 @@ source_files:
   - tools/egg-bundler/src/lib/ExternalsResolver.ts
   - tools/egg-bin/src/commands/bundle.ts
   - tools/egg-bundler/docs/output-structure.md
-updated_at: 2026-05-06
+updated_at: 2026-06-02
 status: active
 ---
 
@@ -32,7 +32,8 @@ CommonJS artifact from an Egg application.
    `<baseDir>/.egg/manifest.json`.
 2. `ExternalsResolver` classifies packages that should stay external.
 3. `EntryGenerator` writes a synthetic worker entry that installs the bundle
-   manifest/module loader before starting Egg.
+   manifest/module loader, creates a `ManifestLoaderFS`, and passes it into
+   `startEgg()`.
 4. `PackRunner` invokes `@utoo/pack`.
 5. `Bundler` writes `bundle-manifest.json` and returns absolute output paths.
 
@@ -47,10 +48,11 @@ CommonJS artifact from an Egg application.
   not run.
 - The generated app runs in Egg single-process mode. Its worker entry treats the
   deploy output directory as the runtime Egg `baseDir`, passes the framework
-  specifier explicitly to `startEgg`, maps that specifier to the already bundled
-  framework module, and precomputes original app absolute aliases so bundled
-  module lookup can serve relKeys, output-dir absolute paths, original app
-  absolute paths, and manifest `resolveCache` request aliases.
+  specifier and manifest-backed `loaderFS` explicitly to `startEgg`, maps that
+  specifier to the already bundled framework module, and precomputes original
+  app absolute aliases so bundled module lookup can serve relKeys, output-dir
+  absolute paths, original app absolute paths, and manifest `resolveCache`
+  request aliases.
 - Explicit `externals.force` entries are external, and `ExternalsResolver`
   auto-detects root `peerDependencies`, root `optionalDependencies`, root
   dependency packages with native addons, root dependency packages whose optional

wiki/packages/loader-fs.md

@@ -1,11 +1,11 @@
 ---
 title: Loader FS Package
 type: package
-summary: Shared loader-facing filesystem boundary for Egg loaders and future bundled runtimes.
+summary: Shared loader-facing filesystem boundary for Egg loaders and bundled runtimes.
 source_files:
   - packages/loader-fs/src/index.ts
   - packages/loader-fs/package.json
-updated_at: 2026-05-10
+updated_at: 2026-06-02
 status: active
 ---
 
@@ -25,5 +25,7 @@ discovery to `globby.sync`, and module loading to the same `@eggjs/utils`
 
 `@eggjs/core` depends on this package and re-exports its public API so existing
 core consumers can still import the loader filesystem boundary from core while
-tegg and later bundled runtime packages can depend on the smaller package
-directly.
+tegg and bundled runtime packages can depend on the smaller package directly.
+The manifest-backed implementation used by bundle workers lives in
+`@eggjs/core` as `ManifestLoaderFS`; this package remains the shared interface
+and real-filesystem implementation.