@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.8

package/src/services/module-loading/server-module-transpiler.service.js

@@ -0,0 +1,61 @@
+import { PageModuleImportService } from "./page-module-import.service.js";
+class ServerModuleTranspiler {
+  pageModuleImportService;
+  getRootDir;
+  getBuildExecutor;
+  getInvalidationVersion;
+  invalidateModules;
+  getDefaultPlugins;
+  /**
+   * Creates one explicit server-transpiler boundary for a given execution
+   * context.
+   */
+  constructor(args) {
+    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService();
+    this.getRootDir = () => args.rootDir;
+    this.getBuildExecutor = args.getBuildExecutor;
+    this.getInvalidationVersion = () => args.getInvalidationVersion?.();
+    this.getDefaultPlugins = args.getDefaultPlugins ?? (() => []);
+    this.invalidateModules = (changedFiles) => {
+      if (args.invalidateModules) {
+        args.invalidateModules(changedFiles);
+        return;
+      }
+      this.pageModuleImportService.invalidateDevelopmentGraph();
+    };
+  }
+  /**
+   * Loads a server-side source module through the caller-owned transpile
+   * context.
+   */
+  async importModule(options) {
+    const mergedPlugins = [...this.getDefaultPlugins(), ...options.plugins ?? []];
+    const { plugins: _plugins, ...baseOptions } = options;
+    return await this.pageModuleImportService.importModule({
+      ...baseOptions,
+      ...mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {},
+      rootDir: this.getRootDir(),
+      buildExecutor: this.getBuildExecutor(),
+      invalidationVersion: this.getInvalidationVersion()
+    });
+  }
+  /**
+   * Invalidates cached module state for development reloads.
+   */
+  invalidate(changedFiles) {
+    this.invalidateModules(changedFiles);
+  }
+  /**
+   * Releases transpiler-owned resources.
+   *
+   * @remarks
+   * The current implementation delegates cache ownership to lower-level module
+   * loading services, so disposal is intentionally a no-op for now.
+   */
+  async dispose() {
+    return;
+  }
+}
+export {
+  ServerModuleTranspiler
+};

package/src/services/runtime-manifest/node-runtime-manifest.service.d.ts

@@ -0,0 +1,35 @@
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+export interface NodeRuntimeManifest {
+    runtime: 'node';
+    appRootDir: string;
+    sourceRootDir: string;
+    distDir: string;
+    workDir?: string;
+    modulePaths: {
+        config: string;
+        entry?: string;
+    };
+}
+/**
+ * Returns the default file handoff location for the Node runtime manifest.
+ */
+export declare function getNodeRuntimeManifestPath(appConfig: EcoPagesAppConfig): string;
+export declare function createNodeRuntimeManifest(appConfig: EcoPagesAppConfig, options?: {
+    entryModulePath?: string;
+}): NodeRuntimeManifest;
+/**
+ * Serializes a Node runtime manifest to the file boundary used by the thin host.
+ */
+export declare function writeNodeRuntimeManifestFile(manifest: NodeRuntimeManifest, manifestFilePath: string): string;
+/**
+ * Derives the app-owned Node manifest and writes it to the runtime handoff path.
+ */
+export declare function writeAppNodeRuntimeManifest(appConfig: EcoPagesAppConfig, options?: {
+    entryModulePath?: string;
+    manifestFilePath?: string;
+}): {
+    manifest: NodeRuntimeManifest;
+    manifestFilePath: string;
+};
+export declare function getAppNodeRuntimeManifest(appConfig: EcoPagesAppConfig): NodeRuntimeManifest;
+export declare function setAppNodeRuntimeManifest(appConfig: EcoPagesAppConfig, nodeRuntimeManifest: NodeRuntimeManifest): void;

package/src/services/runtime-manifest/node-runtime-manifest.service.js

@@ -0,0 +1,60 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../../constants.js";
+const NODE_RUNTIME_MANIFEST_DIRNAME = "runtime";
+const NODE_RUNTIME_MANIFEST_FILENAME = "node-runtime-manifest.json";
+function getNodeRuntimeManifestPath(appConfig) {
+  return path.join(resolveWorkDir(appConfig), NODE_RUNTIME_MANIFEST_DIRNAME, NODE_RUNTIME_MANIFEST_FILENAME);
+}
+function resolveWorkDir(appConfig) {
+  return appConfig.absolutePaths?.workDir ?? path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+}
+function createNodeRuntimeManifest(appConfig, options) {
+  return {
+    runtime: "node",
+    appRootDir: appConfig.rootDir,
+    sourceRootDir: appConfig.absolutePaths.srcDir,
+    distDir: appConfig.absolutePaths.distDir,
+    workDir: resolveWorkDir(appConfig),
+    modulePaths: {
+      config: appConfig.absolutePaths.config,
+      ...options?.entryModulePath ? { entry: options.entryModulePath } : {}
+    }
+  };
+}
+function writeNodeRuntimeManifestFile(manifest, manifestFilePath) {
+  mkdirSync(path.dirname(manifestFilePath), { recursive: true });
+  writeFileSync(manifestFilePath, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+  return manifestFilePath;
+}
+function writeAppNodeRuntimeManifest(appConfig, options) {
+  const manifest = createNodeRuntimeManifest(appConfig, {
+    entryModulePath: options?.entryModulePath
+  });
+  const manifestFilePath = writeNodeRuntimeManifestFile(
+    manifest,
+    options?.manifestFilePath ?? getNodeRuntimeManifestPath(appConfig)
+  );
+  return {
+    manifest,
+    manifestFilePath
+  };
+}
+function getAppNodeRuntimeManifest(appConfig) {
+  return appConfig.runtime?.nodeRuntimeManifest ?? createNodeRuntimeManifest(appConfig);
+}
+function setAppNodeRuntimeManifest(appConfig, nodeRuntimeManifest) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    nodeRuntimeManifest
+  };
+}
+export {
+  createNodeRuntimeManifest,
+  getAppNodeRuntimeManifest,
+  getNodeRuntimeManifestPath,
+  setAppNodeRuntimeManifest,
+  writeAppNodeRuntimeManifest,
+  writeNodeRuntimeManifestFile
+};

package/src/services/runtime-state/dev-graph.service.d.ts

@@ -0,0 +1,118 @@
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import { type ServerInvalidationState } from './server-invalidation-state.service.js';
+import { type EntrypointDependencyGraph } from './entrypoint-dependency-graph.service.js';
+/**
+ * Tracks development-time dependency relationships and invalidation state for
+ * one Ecopages app instance.
+ *
+ * @remarks
+ * The current contract stays intentionally small. It supports today's needs for
+ * server-module cache invalidation and entrypoint-to-dependency lookups without
+ * forcing the rest of the runtime to know about one specific graph
+ * implementation.
+ */
+export interface DevGraphService extends ServerInvalidationState, EntrypointDependencyGraph {
+}
+/**
+ * Minimal dev-graph implementation used when an app has no selective graph
+ * metadata available.
+ *
+ * @remarks
+ * This preserves correct behavior by using coarse invalidation version bumps.
+ * Callers still pass changed-file information through the interface now so a
+ * richer graph can become more selective later without changing call sites.
+ */
+export declare class NoopDevGraphService implements DevGraphService {
+    private readonly invalidationState;
+    private readonly dependencyGraph;
+    /**
+     * Returns the current coarse invalidation version.
+     */
+    getServerInvalidationVersion(): number;
+    /**
+     * Invalidates all server-side module state by incrementing the shared version.
+     */
+    invalidateServerModules(_changedFiles?: string[]): void;
+    /**
+     * Indicates that this graph cannot target invalidation to one entrypoint set.
+     */
+    supportsSelectiveInvalidation(): boolean;
+    /**
+     * Returns an empty entrypoint set because this implementation stores no
+     * dependency graph metadata.
+     */
+    getDependencyEntrypoints(_filePath: string): Set<string>;
+    /**
+     * Accepts dependency updates to preserve interface compatibility, but stores no
+     * graph state in the noop implementation.
+     */
+    setEntrypointDependencies(_entrypointPath: string, _dependencies: string[]): void;
+    /**
+     * Clears one entrypoint from the graph.
+     *
+     * @remarks
+     * There is no stored graph state in this implementation, so this is a no-op.
+     */
+    clearEntrypointDependencies(_entrypointPath: string): void;
+    /**
+     * Resets graph-owned state for a fresh runtime cycle.
+     */
+    reset(): void;
+}
+/**
+ * In-memory development graph with entrypoint-to-dependency reverse lookups.
+ *
+ * @remarks
+ * This is the current selective graph implementation used by development flows
+ * that need to answer which entrypoints depend on a changed file while still
+ * keeping invalidation state app-local.
+ */
+export declare class InMemoryDevGraphService implements DevGraphService {
+    private readonly invalidationState;
+    private readonly dependencyGraph;
+    /**
+     * Returns the current app-local server invalidation version.
+     */
+    getServerInvalidationVersion(): number;
+    /**
+     * Invalidates the current server-module cache generation.
+     *
+     * @remarks
+     * The current implementation still uses a coarse generation bump for server
+     * modules. Selective dependency lookups are used by callers that need to limit
+     * browser rebuild work.
+     */
+    invalidateServerModules(_changedFiles?: string[]): void;
+    /**
+     * Indicates that this graph can answer dependency-to-entrypoint lookups.
+     */
+    supportsSelectiveInvalidation(): boolean;
+    /**
+     * Returns all known entrypoints that currently depend on the given file.
+     */
+    getDependencyEntrypoints(filePath: string): Set<string>;
+    /**
+     * Replaces the stored dependency set for one entrypoint.
+     *
+     * @remarks
+     * The entrypoint itself is always included in its own dependency set so reverse
+     * lookups can map a changed entry file back to that same entrypoint.
+     */
+    setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void;
+    /**
+     * Removes one entrypoint and all of its reverse dependency edges.
+     */
+    clearEntrypointDependencies(entrypointPath: string): void;
+    /**
+     * Clears all graph state and starts a fresh invalidation generation.
+     */
+    reset(): void;
+}
+/**
+ * Returns the dev-graph service owned by one app instance.
+ */
+export declare function getAppDevGraphService(appConfig: EcoPagesAppConfig): DevGraphService;
+/**
+ * Installs the dev-graph service that should back one app/runtime instance.
+ */
+export declare function setAppDevGraphService(appConfig: EcoPagesAppConfig, devGraphService: DevGraphService): void;

package/src/services/runtime-state/dev-graph.service.js

@@ -0,0 +1,162 @@
+import {
+  CounterServerInvalidationState,
+  getAppServerInvalidationState,
+  setAppServerInvalidationState
+} from "./server-invalidation-state.service.js";
+import {
+  getAppEntrypointDependencyGraph,
+  InMemoryEntrypointDependencyGraph,
+  NoopEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+} from "./entrypoint-dependency-graph.service.js";
+class NoopDevGraphService {
+  invalidationState = new CounterServerInvalidationState();
+  dependencyGraph = new NoopEntrypointDependencyGraph();
+  /**
+   * Returns the current coarse invalidation version.
+   */
+  getServerInvalidationVersion() {
+    return this.invalidationState.getServerInvalidationVersion();
+  }
+  /**
+   * Invalidates all server-side module state by incrementing the shared version.
+   */
+  invalidateServerModules(_changedFiles) {
+    this.invalidationState.invalidateServerModules(_changedFiles);
+  }
+  /**
+   * Indicates that this graph cannot target invalidation to one entrypoint set.
+   */
+  supportsSelectiveInvalidation() {
+    return this.dependencyGraph.supportsSelectiveInvalidation();
+  }
+  /**
+   * Returns an empty entrypoint set because this implementation stores no
+   * dependency graph metadata.
+   */
+  getDependencyEntrypoints(_filePath) {
+    return this.dependencyGraph.getDependencyEntrypoints(_filePath);
+  }
+  /**
+   * Accepts dependency updates to preserve interface compatibility, but stores no
+   * graph state in the noop implementation.
+   */
+  setEntrypointDependencies(_entrypointPath, _dependencies) {
+    this.dependencyGraph.setEntrypointDependencies(_entrypointPath, _dependencies);
+  }
+  /**
+   * Clears one entrypoint from the graph.
+   *
+   * @remarks
+   * There is no stored graph state in this implementation, so this is a no-op.
+   */
+  clearEntrypointDependencies(_entrypointPath) {
+    this.dependencyGraph.clearEntrypointDependencies(_entrypointPath);
+  }
+  /**
+   * Resets graph-owned state for a fresh runtime cycle.
+   */
+  reset() {
+    this.invalidationState.reset();
+    this.dependencyGraph.reset();
+  }
+}
+class InMemoryDevGraphService {
+  invalidationState = new CounterServerInvalidationState();
+  dependencyGraph = new InMemoryEntrypointDependencyGraph();
+  /**
+   * Returns the current app-local server invalidation version.
+   */
+  getServerInvalidationVersion() {
+    return this.invalidationState.getServerInvalidationVersion();
+  }
+  /**
+   * Invalidates the current server-module cache generation.
+   *
+   * @remarks
+   * The current implementation still uses a coarse generation bump for server
+   * modules. Selective dependency lookups are used by callers that need to limit
+   * browser rebuild work.
+   */
+  invalidateServerModules(_changedFiles) {
+    this.invalidationState.invalidateServerModules(_changedFiles);
+  }
+  /**
+   * Indicates that this graph can answer dependency-to-entrypoint lookups.
+   */
+  supportsSelectiveInvalidation() {
+    return this.dependencyGraph.supportsSelectiveInvalidation();
+  }
+  /**
+   * Returns all known entrypoints that currently depend on the given file.
+   */
+  getDependencyEntrypoints(filePath) {
+    return this.dependencyGraph.getDependencyEntrypoints(filePath);
+  }
+  /**
+   * Replaces the stored dependency set for one entrypoint.
+   *
+   * @remarks
+   * The entrypoint itself is always included in its own dependency set so reverse
+   * lookups can map a changed entry file back to that same entrypoint.
+   */
+  setEntrypointDependencies(entrypointPath, dependencies) {
+    this.dependencyGraph.setEntrypointDependencies(entrypointPath, dependencies);
+  }
+  /**
+   * Removes one entrypoint and all of its reverse dependency edges.
+   */
+  clearEntrypointDependencies(entrypointPath) {
+    this.dependencyGraph.clearEntrypointDependencies(entrypointPath);
+  }
+  /**
+   * Clears all graph state and starts a fresh invalidation generation.
+   */
+  reset() {
+    this.invalidationState.reset();
+    this.dependencyGraph.reset();
+  }
+}
+function getAppDevGraphService(appConfig) {
+  if (appConfig.runtime?.devGraphService) {
+    return appConfig.runtime.devGraphService;
+  }
+  const serverInvalidationState = getAppServerInvalidationState(appConfig);
+  const entrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
+  return {
+    getServerInvalidationVersion: () => serverInvalidationState.getServerInvalidationVersion(),
+    invalidateServerModules: (changedFiles) => serverInvalidationState.invalidateServerModules(changedFiles),
+    supportsSelectiveInvalidation: () => entrypointDependencyGraph.supportsSelectiveInvalidation(),
+    getDependencyEntrypoints: (filePath) => entrypointDependencyGraph.getDependencyEntrypoints(filePath),
+    setEntrypointDependencies: (entrypointPath, dependencies) => entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, dependencies),
+    clearEntrypointDependencies: (entrypointPath) => entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath),
+    reset: () => {
+      serverInvalidationState.reset();
+      entrypointDependencyGraph.reset();
+    }
+  };
+}
+function setAppDevGraphService(appConfig, devGraphService) {
+  setAppServerInvalidationState(appConfig, {
+    getServerInvalidationVersion: () => devGraphService.getServerInvalidationVersion(),
+    invalidateServerModules: (changedFiles) => devGraphService.invalidateServerModules(changedFiles),
+    reset: () => devGraphService.reset()
+  });
+  setAppEntrypointDependencyGraph(appConfig, {
+    supportsSelectiveInvalidation: () => devGraphService.supportsSelectiveInvalidation(),
+    getDependencyEntrypoints: (filePath) => devGraphService.getDependencyEntrypoints(filePath),
+    setEntrypointDependencies: (entrypointPath, dependencies) => devGraphService.setEntrypointDependencies(entrypointPath, dependencies),
+    clearEntrypointDependencies: (entrypointPath) => devGraphService.clearEntrypointDependencies(entrypointPath),
+    reset: () => devGraphService.reset()
+  });
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    devGraphService
+  };
+}
+export {
+  InMemoryDevGraphService,
+  NoopDevGraphService,
+  getAppDevGraphService,
+  setAppDevGraphService
+};

package/src/services/runtime-state/entrypoint-dependency-graph.service.d.ts

@@ -0,0 +1,41 @@
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+/**
+ * App-owned dependency graph used to target browser entrypoint rebuilds.
+ */
+export interface EntrypointDependencyGraph {
+    supportsSelectiveInvalidation(): boolean;
+    getDependencyEntrypoints(filePath: string): Set<string>;
+    setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void;
+    clearEntrypointDependencies(entrypointPath: string): void;
+    reset(): void;
+}
+/**
+ * Graph implementation for runtimes that rebuild every watched entrypoint.
+ */
+export declare class NoopEntrypointDependencyGraph implements EntrypointDependencyGraph {
+    supportsSelectiveInvalidation(): boolean;
+    getDependencyEntrypoints(_filePath: string): Set<string>;
+    setEntrypointDependencies(_entrypointPath: string, _dependencies: string[]): void;
+    clearEntrypointDependencies(_entrypointPath: string): void;
+    reset(): void;
+}
+/**
+ * In-memory entrypoint-to-dependency graph with reverse dependency lookups.
+ */
+export declare class InMemoryEntrypointDependencyGraph implements EntrypointDependencyGraph {
+    private readonly dependencyEntrypoints;
+    private readonly entrypointDependencies;
+    supportsSelectiveInvalidation(): boolean;
+    getDependencyEntrypoints(filePath: string): Set<string>;
+    setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void;
+    clearEntrypointDependencies(entrypointPath: string): void;
+    reset(): void;
+}
+/**
+ * Returns the app-owned entrypoint dependency graph.
+ */
+export declare function getAppEntrypointDependencyGraph(appConfig: EcoPagesAppConfig): EntrypointDependencyGraph;
+/**
+ * Installs the dependency graph used by one app instance.
+ */
+export declare function setAppEntrypointDependencyGraph(appConfig: EcoPagesAppConfig, entrypointDependencyGraph: EntrypointDependencyGraph): void;

package/src/services/runtime-state/entrypoint-dependency-graph.service.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+class NoopEntrypointDependencyGraph {
+  supportsSelectiveInvalidation() {
+    return false;
+  }
+  getDependencyEntrypoints(_filePath) {
+    return /* @__PURE__ */ new Set();
+  }
+  setEntrypointDependencies(_entrypointPath, _dependencies) {
+  }
+  clearEntrypointDependencies(_entrypointPath) {
+  }
+  reset() {
+  }
+}
+class InMemoryEntrypointDependencyGraph {
+  dependencyEntrypoints = /* @__PURE__ */ new Map();
+  entrypointDependencies = /* @__PURE__ */ new Map();
+  supportsSelectiveInvalidation() {
+    return true;
+  }
+  getDependencyEntrypoints(filePath) {
+    return new Set(this.dependencyEntrypoints.get(path.resolve(filePath)) ?? []);
+  }
+  setEntrypointDependencies(entrypointPath, dependencies) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    this.clearEntrypointDependencies(normalizedEntrypoint);
+    const normalizedDependencies = /* @__PURE__ */ new Set([
+      normalizedEntrypoint,
+      ...dependencies.map((dependencyPath) => path.resolve(dependencyPath))
+    ]);
+    this.entrypointDependencies.set(normalizedEntrypoint, normalizedDependencies);
+    for (const dependencyPath of normalizedDependencies) {
+      const entrypoints = this.dependencyEntrypoints.get(dependencyPath) ?? /* @__PURE__ */ new Set();
+      entrypoints.add(normalizedEntrypoint);
+      this.dependencyEntrypoints.set(dependencyPath, entrypoints);
+    }
+  }
+  clearEntrypointDependencies(entrypointPath) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const previousDependencies = this.entrypointDependencies.get(normalizedEntrypoint);
+    if (!previousDependencies) {
+      return;
+    }
+    for (const dependencyPath of previousDependencies) {
+      const entrypoints = this.dependencyEntrypoints.get(dependencyPath);
+      if (!entrypoints) {
+        continue;
+      }
+      entrypoints.delete(normalizedEntrypoint);
+      if (entrypoints.size === 0) {
+        this.dependencyEntrypoints.delete(dependencyPath);
+      }
+    }
+    this.entrypointDependencies.delete(normalizedEntrypoint);
+  }
+  reset() {
+    this.dependencyEntrypoints.clear();
+    this.entrypointDependencies.clear();
+  }
+}
+function isLegacyEntrypointDependencyGraph(value) {
+  return Boolean(value) && typeof value === "object" && typeof value.supportsSelectiveInvalidation === "function" && typeof value.getDependencyEntrypoints === "function" && typeof value.setEntrypointDependencies === "function" && typeof value.clearEntrypointDependencies === "function" && typeof value.reset === "function";
+}
+function getAppEntrypointDependencyGraph(appConfig) {
+  if (appConfig.runtime?.entrypointDependencyGraph) {
+    return appConfig.runtime.entrypointDependencyGraph;
+  }
+  if (isLegacyEntrypointDependencyGraph(appConfig.runtime?.devGraphService)) {
+    return appConfig.runtime.devGraphService;
+  }
+  return new NoopEntrypointDependencyGraph();
+}
+function setAppEntrypointDependencyGraph(appConfig, entrypointDependencyGraph) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    entrypointDependencyGraph
+  };
+}
+export {
+  InMemoryEntrypointDependencyGraph,
+  NoopEntrypointDependencyGraph,
+  getAppEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+};

package/src/services/runtime-state/runtime-specifier-registry.service.d.ts

@@ -0,0 +1,69 @@
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+/**
+ * Stores runtime-visible bare-specifier mappings for one app instance.
+ *
+ * @remarks
+ * Integrations populate this registry during runtime setup when they expose
+ * browser runtime modules through stable bare imports. Build and HMR code later
+ * consume the collected map to create aliasing and bootstrap behavior without
+ * forcing integrations to own global registry state.
+ */
+export interface RuntimeSpecifierRegistry {
+    /**
+     * Merges a new batch of specifier mappings into the registry.
+     *
+     * @remarks
+     * Later registrations replace earlier URLs for the same specifier. This keeps
+     * runtime setup deterministic while still allowing an integration to refresh
+     * its own declarations during one app session.
+     */
+    register(map: Record<string, string>): void;
+    /**
+     * Returns the current registry contents.
+     *
+     * @remarks
+     * The returned map is the live backing map for the registry implementation, so
+     * callers should treat it as read-only unless they intentionally own registry
+     * mutation semantics.
+     */
+    getAll(): Map<string, string>;
+    /**
+     * Removes all registered specifiers for the current app/runtime instance.
+     */
+    clear(): void;
+}
+/**
+ * Default in-memory runtime specifier registry used by core.
+ *
+ * @remarks
+ * Runtime specifier maps are app-local bootstrap metadata, not durable build
+ * artifacts, so the default implementation stays intentionally small.
+ */
+export declare class InMemoryRuntimeSpecifierRegistry implements RuntimeSpecifierRegistry {
+    private readonly specifierMap;
+    /**
+     * Merges one integration-provided mapping set into the app registry.
+     */
+    register(map: Record<string, string>): void;
+    /**
+     * Returns the live app-owned mapping table.
+     */
+    getAll(): Map<string, string>;
+    /**
+     * Clears all mappings for the current runtime session.
+     */
+    clear(): void;
+}
+/**
+ * Returns the runtime specifier registry owned by one app instance.
+ *
+ * @remarks
+ * Older tests and helpers may not seed runtime state explicitly yet, so this
+ * helper still provides an in-memory fallback when the app runtime has not been
+ * initialized.
+ */
+export declare function getAppRuntimeSpecifierRegistry(appConfig: EcoPagesAppConfig): RuntimeSpecifierRegistry;
+/**
+ * Installs the runtime specifier registry that should back one app instance.
+ */
+export declare function setAppRuntimeSpecifierRegistry(appConfig: EcoPagesAppConfig, runtimeSpecifierRegistry: RuntimeSpecifierRegistry): void;

package/src/services/runtime-state/runtime-specifier-registry.service.js

@@ -0,0 +1,37 @@
+class InMemoryRuntimeSpecifierRegistry {
+  specifierMap = /* @__PURE__ */ new Map();
+  /**
+   * Merges one integration-provided mapping set into the app registry.
+   */
+  register(map) {
+    for (const [specifier, url] of Object.entries(map)) {
+      this.specifierMap.set(specifier, url);
+    }
+  }
+  /**
+   * Returns the live app-owned mapping table.
+   */
+  getAll() {
+    return this.specifierMap;
+  }
+  /**
+   * Clears all mappings for the current runtime session.
+   */
+  clear() {
+    this.specifierMap.clear();
+  }
+}
+function getAppRuntimeSpecifierRegistry(appConfig) {
+  return appConfig.runtime?.runtimeSpecifierRegistry ?? new InMemoryRuntimeSpecifierRegistry();
+}
+function setAppRuntimeSpecifierRegistry(appConfig, runtimeSpecifierRegistry) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    runtimeSpecifierRegistry
+  };
+}
+export {
+  InMemoryRuntimeSpecifierRegistry,
+  getAppRuntimeSpecifierRegistry,
+  setAppRuntimeSpecifierRegistry
+};