@ecopages/core 0.2.0-alpha.9 → 0.2.1

package/src/{adapters/node/bootstrap-dependency-resolver.js → services/module-loading/node-bootstrap-plugin.js}

@@ -1,20 +1,8 @@
 import path from "node:path";
 import { existsSync, mkdirSync, readFileSync, symlinkSync } from "node:fs";
 import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
-function getNodeRuntimeNodeModulesDir(manifest) {
-  return path.join(
-    resolveInternalExecutionDir({
-      rootDir: manifest.appRootDir,
-      workDir: manifest.workDir,
-      absolutePaths: {
-        workDir: manifest.workDir,
-        distDir: manifest.distDir
-      }
-    }),
-    "node_modules"
-  );
-}
 function getAppRuntimeNodeModulesDir(appConfig) {
   return path.join(resolveInternalExecutionDir(appConfig), "node_modules");
 }
@@ -50,11 +38,21 @@ function ensureRuntimePackageLink(nodeModulesDir, specifier, resolvedPath) {
   symlinkSync(packageRoot, linkPath, "dir");
 }
 function getNodeUnsupportedBuiltinError(specifier, importer) {
-  return `Node thin-host bootstrap does not support Bun builtin specifier ${JSON.stringify(specifier)}${importer ? ` imported from ${importer}` : ""}.`;
+  return `Node bootstrap transpilation does not support Bun builtin specifier ${JSON.stringify(specifier)}${importer ? ` imported from ${importer}` : ""}.`;
 }
 function shouldResolveFromImporter(importer) {
   return Boolean(importer && importer.includes(`${path.sep}node_modules${path.sep}`));
 }
+function resolveSpecifier(specifier, parentPath) {
+  try {
+    return createRequire(parentPath).resolve(specifier);
+  } catch {
+    return fileURLToPath(import.meta.resolve(specifier, pathToFileURL(parentPath).href));
+  }
+}
+function resolveFromCore(specifier) {
+  return createRequire(import.meta.url).resolve(specifier);
+}
 function getBootstrapBuildLoaderForPath(filePath) {
   switch (path.extname(filePath).toLowerCase()) {
     case ".ts":
@@ -100,14 +98,37 @@ function resolveNodeBootstrapDependency(args, options) {
   if (args.path.startsWith("./") || args.path.startsWith("../") || args.path.startsWith("@/") || args.path.startsWith("/") || args.path.startsWith("node:")) {
     return void 0;
   }
-  const projectRequire = createRequire(path.join(options.projectDir, "package.json"));
-  const requireFromImporter = args.importer && path.isAbsolute(args.importer) && shouldResolveFromImporter(args.importer) ? createRequire(args.importer) : projectRequire;
+  const resolveParent = args.importer && path.isAbsolute(args.importer) && shouldResolveFromImporter(args.importer) ? args.importer : path.join(options.projectDir, "package.json");
   if (args.path.startsWith("@ecopages/")) {
-    return {
-      path: requireFromImporter.resolve(args.path)
-    };
+    let resolvedPath2;
+    try {
+      resolvedPath2 = resolveFromCore(args.path);
+    } catch {
+      try {
+        resolvedPath2 = resolveSpecifier(args.path, resolveParent);
+      } catch {
+        const packageName = getPackageNameFromSpecifier(args.path);
+        const candidatePath = path.join(options.projectDir, "node_modules", packageName);
+        const candidatePackageJson = path.join(candidatePath, "package.json");
+        if (existsSync(candidatePackageJson)) {
+          ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, candidatePackageJson);
+          return { path: args.path, external: true };
+        }
+      }
+    }
+    if (!resolvedPath2) {
+      return void 0;
+    }
+    if (resolvedPath2.includes(`${path.sep}node_modules${path.sep}`)) {
+      ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, resolvedPath2);
+      return {
+        path: args.path,
+        external: true
+      };
+    }
+    return { path: resolvedPath2 };
   }
-  const resolvedPath = requireFromImporter.resolve(args.path);
+  const resolvedPath = resolveSpecifier(args.path, resolveParent);
   ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, resolvedPath);
   return {
     path: args.path,
@@ -120,7 +141,7 @@ function createNodeBootstrapPlugin(options) {
     (options.preserveImportMetaPaths ?? []).map((filePath) => path.resolve(filePath))
   );
   return {
-    name: "node-thin-host-bundle-workspace-packages",
+    name: "node-bootstrap-plugin",
     setup(build) {
       build.onResolve({ filter: /^bun:/ }, (args) => {
         throw new Error(getNodeUnsupportedBuiltinError(args.path, args.importer));
@@ -166,7 +187,6 @@ export {
   createAppNodeBootstrapPlugin,
   createNodeBootstrapPlugin,
   getAppRuntimeNodeModulesDir,
-  getNodeRuntimeNodeModulesDir,
   getNodeUnsupportedBuiltinError,
   resolveNodeBootstrapDependency
 };

package/src/services/module-loading/page-module-import.service.d.ts

@@ -1,9 +1,11 @@
 import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { SourceModuleLoaderFactory } from './module-loading-types.js';
 export interface PageModuleImportOptions {
     filePath: string;
     rootDir: string;
     outdir: string;
+    bypassCache?: boolean;
     buildExecutor?: BuildExecutor;
     invalidationVersion?: number;
     splitting?: boolean;
@@ -23,6 +25,8 @@ export interface PageModuleImportOptions {
 export interface PageModuleImportDependencies {
     hashFile(filePath: string): string;
     buildModule(options: Parameters<typeof build>[0], buildExecutor?: BuildExecutor): Promise<BuildResult>;
+    canLoadSourceModuleFromHost(filePath: string): boolean;
+    getHostModuleLoader: SourceModuleLoaderFactory;
 }
 /**
  * Loads source page modules in a runtime-agnostic way.

package/src/services/module-loading/page-module-import.service.js

@@ -9,7 +9,9 @@ class PageModuleImportService {
   constructor(dependencies) {
     this.dependencies = {
       hashFile: dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath)),
-      buildModule: dependencies?.buildModule ?? ((options, buildExecutor) => build(options, buildExecutor))
+      buildModule: dependencies?.buildModule ?? ((options, buildExecutor) => build(options, buildExecutor)),
+      canLoadSourceModuleFromHost: dependencies?.canLoadSourceModuleFromHost ?? supportsHostSourceModuleLoading,
+      getHostModuleLoader: dependencies?.getHostModuleLoader ?? (() => void 0)
     };
   }
   /**
@@ -47,7 +49,20 @@ class PageModuleImportService {
     const { filePath, rootDir, externalPackages, splitting } = options;
     const invalidationVersion = options.invalidationVersion ?? this.developmentInvalidationVersion;
     const fileHash = this.dependencies.hashFile(filePath);
-    const runtime = typeof Bun !== "undefined" ? "bun" : "node";
+    const hostModuleLoader = typeof Bun === "undefined" && process.env.NODE_ENV === "development" && this.dependencies.canLoadSourceModuleFromHost(filePath) ? this.dependencies.getHostModuleLoader() : void 0;
+    if (hostModuleLoader) {
+      const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion);
+      return await hostModuleLoader(sourceModuleUrl.href);
+    }
+    if (options.bypassCache) {
+      this.developmentInvalidationVersion += 1;
+      return await this.loadModule({
+        ...options,
+        invalidationVersion: this.developmentInvalidationVersion,
+        fileHash
+      });
+    }
+    const runtime = typeof Bun !== "undefined" ? "bun" : "node-build";
     const cacheKey = [
       runtime,
       filePath,
@@ -85,12 +100,12 @@ class PageModuleImportService {
       noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
       fileHash
     } = options;
+    const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion);
     if (typeof Bun !== "undefined") {
-      const moduleUrl = pathToFileURL(filePath);
-      if (process.env.NODE_ENV === "development") {
-        moduleUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
-      }
-      return await import(moduleUrl.href);
+      return await import(
+        /* @vite-ignore */
+        sourceModuleUrl.href
+      );
     }
     const fileBaseName = path.basename(filePath, path.extname(filePath));
     const outputFileName = `${fileBaseName}-${fileHash}.js`;
@@ -99,7 +114,7 @@ class PageModuleImportService {
         entrypoints: [filePath],
         root: rootDir,
         outdir,
-        target: "node",
+        target: "es2022",
         format: "esm",
         sourcemap: "none",
         splitting: splitting ?? true,
@@ -124,9 +139,23 @@ class PageModuleImportService {
     if (process.env.NODE_ENV === "development") {
       compiledOutputUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
     }
-    return await import(compiledOutputUrl.href);
+    return await import(
+      /* @vite-ignore */
+      compiledOutputUrl.href
+    );
   }
 }
+function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion) {
+  const moduleUrl = pathToFileURL(filePath);
+  if (process.env.NODE_ENV === "development") {
+    moduleUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
+  }
+  return moduleUrl;
+}
+function supportsHostSourceModuleLoading(filePath) {
+  const extension = path.extname(filePath);
+  return extension === ".js" || extension === ".jsx" || extension === ".ts" || extension === ".tsx" || extension === ".mjs" || extension === ".mts" || extension === ".cjs" || extension === ".cts";
+}
 export {
   PageModuleImportService
 };

package/src/services/module-loading/server-module-transpiler.service.d.ts

@@ -1,6 +1,7 @@
 import type { BuildExecutor } from '../../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
 import { type PageModuleImportOptions } from './page-module-import.service.js';
+import type { SourceModuleLoaderFactory } from './module-loading-types.js';
 export type ServerModuleTranspilerOptions = Omit<PageModuleImportOptions, 'rootDir' | 'buildExecutor'>;
 /**
  * Minimal import-service dependency required by the server module transpiler.
@@ -24,6 +25,8 @@ export interface ServerModuleImportDependency {
 export type ServerModuleTranspilerBootstrapArgs = {
     rootDir: string;
     getBuildExecutor: () => BuildExecutor | undefined;
+    canLoadSourceModuleFromHost?: (filePath: string) => boolean;
+    getHostModuleLoader?: SourceModuleLoaderFactory;
     getInvalidationVersion?: () => number;
     invalidateModules?: (changedFiles?: string[]) => void;
     pageModuleImportService?: ServerModuleImportDependency;

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

@@ -11,7 +11,10 @@ class ServerModuleTranspiler {
    * context.
    */
   constructor(args) {
-    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService();
+    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService({
+      canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
+      getHostModuleLoader: args.getHostModuleLoader
+    });
     this.getRootDir = () => args.rootDir;
     this.getBuildExecutor = args.getBuildExecutor;
     this.getInvalidationVersion = () => args.getInvalidationVersion?.();

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

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import { type ServerInvalidationState } from './server-invalidation-state.service.js';
 import { type EntrypointDependencyGraph } from './entrypoint-dependency-graph.service.js';
 /**
@@ -32,7 +32,7 @@ export declare class NoopDevGraphService implements DevGraphService {
     /**
      * Invalidates all server-side module state by incrementing the shared version.
      */
-    invalidateServerModules(_changedFiles?: string[]): void;
+    invalidateServerModules(changedFiles?: string[]): void;
     /**
      * Indicates that this graph cannot target invalidation to one entrypoint set.
      */
@@ -41,19 +41,19 @@ export declare class NoopDevGraphService implements DevGraphService {
      * Returns an empty entrypoint set because this implementation stores no
      * dependency graph metadata.
      */
-    getDependencyEntrypoints(_filePath: string): Set<string>;
+    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;
+    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;
+    clearEntrypointDependencies(entrypointPath: string): void;
     /**
      * Resets graph-owned state for a fresh runtime cycle.
      */
@@ -82,7 +82,7 @@ export declare class InMemoryDevGraphService implements DevGraphService {
      * modules. Selective dependency lookups are used by callers that need to limit
      * browser rebuild work.
      */
-    invalidateServerModules(_changedFiles?: string[]): void;
+    invalidateServerModules(changedFiles?: string[]): void;
     /**
      * Indicates that this graph can answer dependency-to-entrypoint lookups.
      */

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

@@ -21,8 +21,8 @@ class NoopDevGraphService {
   /**
    * Invalidates all server-side module state by incrementing the shared version.
    */
-  invalidateServerModules(_changedFiles) {
-    this.invalidationState.invalidateServerModules(_changedFiles);
+  invalidateServerModules(changedFiles) {
+    this.invalidationState.invalidateServerModules(changedFiles);
   }
   /**
    * Indicates that this graph cannot target invalidation to one entrypoint set.
@@ -34,15 +34,15 @@ class NoopDevGraphService {
    * Returns an empty entrypoint set because this implementation stores no
    * dependency graph metadata.
    */
-  getDependencyEntrypoints(_filePath) {
-    return this.dependencyGraph.getDependencyEntrypoints(_filePath);
+  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);
+  setEntrypointDependencies(entrypointPath, dependencies) {
+    this.dependencyGraph.setEntrypointDependencies(entrypointPath, dependencies);
   }
   /**
    * Clears one entrypoint from the graph.
@@ -50,8 +50,8 @@ class NoopDevGraphService {
    * @remarks
    * There is no stored graph state in this implementation, so this is a no-op.
    */
-  clearEntrypointDependencies(_entrypointPath) {
-    this.dependencyGraph.clearEntrypointDependencies(_entrypointPath);
+  clearEntrypointDependencies(entrypointPath) {
+    this.dependencyGraph.clearEntrypointDependencies(entrypointPath);
   }
   /**
    * Resets graph-owned state for a fresh runtime cycle.
@@ -78,8 +78,8 @@ class InMemoryDevGraphService {
    * modules. Selective dependency lookups are used by callers that need to limit
    * browser rebuild work.
    */
-  invalidateServerModules(_changedFiles) {
-    this.invalidationState.invalidateServerModules(_changedFiles);
+  invalidateServerModules(changedFiles) {
+    this.invalidationState.invalidateServerModules(changedFiles);
   }
   /**
    * Indicates that this graph can answer dependency-to-entrypoint lookups.

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

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 /**
  * App-owned dependency graph used to target browser entrypoint rebuilds.
  */

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

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 /**
  * Stores runtime-visible bare-specifier mappings for one app instance.
  *

package/src/services/runtime-state/server-invalidation-state.service.d.ts

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 /**
  * App-owned coarse invalidation state for server-executed modules.
  */

package/src/static-site-generator/static-site-generator.d.ts

@@ -1,5 +1,5 @@
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { StaticRoute } from '../public-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { StaticRoute } from '../types/public-types.js';
 import type { RouteRendererFactory } from '../route-renderer/route-renderer.js';
 import type { FSRouter } from '../router/server/fs-router.js';
 export declare const STATIC_SITE_GENERATOR_ERRORS: {

package/src/static-site-generator/static-site-generator.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { DEFAULT_ECOPAGES_WORK_DIR } from "../constants.js";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
 import { appLogger } from "../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
 import { PathUtils } from "../utils/path-utils.module.js";

package/src/{internal-types.d.ts → types/internal-types.d.ts}

@@ -1,17 +1,19 @@
-import type { EcoBuildPlugin } from './build/build-types.js';
-import type { AppBuildManifest } from './build/build-manifest.js';
-import type { BuildAdapter, BuildExecutor } from './build/build-adapter.js';
-import type { IntegrationPlugin } from './plugins/integration-plugin.js';
-import type { Processor } from './plugins/processor.js';
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { AppBuildManifest } from '../build/build-manifest.js';
+import type { BuildAdapter, BuildExecutor, BuildOwnership } from '../build/build-adapter.js';
+import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { Processor } from '../plugins/processor.js';
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
 import type { PageMetadataProps } from './public-types.js';
-import type { FSRouter } from './router/server/fs-router.js';
-import type { CacheConfig } from './services/cache/cache.types.js';
-import type { DevGraphService } from './services/runtime-state/dev-graph.service.js';
-import type { EntrypointDependencyGraph } from './services/runtime-state/entrypoint-dependency-graph.service.js';
-import type { NodeRuntimeManifest } from './services/runtime-manifest/node-runtime-manifest.service.js';
-import type { RuntimeSpecifierRegistry } from './services/runtime-state/runtime-specifier-registry.service.js';
-import type { ServerInvalidationState } from './services/runtime-state/server-invalidation-state.service.js';
-import type { ServerModuleTranspiler } from './services/module-loading/server-module-transpiler.service.js';
+import type { FSRouter } from '../router/server/fs-router.js';
+import type { CacheConfig } from '../services/cache/cache.types.js';
+import type { DevGraphService } from '../services/runtime-state/dev-graph.service.js';
+import type { AppModuleLoader } from '../services/module-loading/app-module-loader.service.js';
+import type { SourceModuleLoader } from '../services/module-loading/module-loading-types.js';
+import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { RuntimeSpecifierRegistry } from '../services/runtime-state/runtime-specifier-registry.service.js';
+import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.js';
+import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
 export interface RobotsPreference {
     /**
      * The user agent
@@ -126,6 +128,11 @@ export type EcoPagesAppConfig = {
      * Loaders to be used in the app, these are used to process the files when importing them
      */
     loaders: Map<string, EcoBuildPlugin>;
+    /**
+     * App-owned source transforms that can be adapted into Vite or other
+     * transform-first bundlers without going through the legacy loader bridge.
+     */
+    sourceTransforms: Map<string, EcoSourceTransform>;
     /**
      * Cache configuration for ISR and page caching.
      * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
@@ -139,12 +146,15 @@ export type EcoPagesAppConfig = {
      * process-global registries.
      */
     runtime?: {
+        appModuleLoader?: AppModuleLoader;
+        buildOwnership?: BuildOwnership;
         buildAdapter?: BuildAdapter;
         buildManifest?: AppBuildManifest;
         buildExecutor?: BuildExecutor;
         devGraphService?: DevGraphService;
         entrypointDependencyGraph?: EntrypointDependencyGraph;
-        nodeRuntimeManifest?: NodeRuntimeManifest;
+        hostModuleLoader?: SourceModuleLoader;
+        rendererModuleContext?: unknown;
         runtimeSpecifierRegistry?: RuntimeSpecifierRegistry;
         serverInvalidationState?: ServerInvalidationState;
         serverModuleTranspiler?: ServerModuleTranspiler;

package/src/{public-types.d.ts → types/public-types.d.ts}

@@ -1,19 +1,20 @@
 import type { Readable } from 'node:stream';
-import type { ApiResponseBuilder } from './adapters/shared/api-response.js';
-import type { BuildExecutor } from './build/build-adapter.js';
-import type { EcoBuildPlugin } from './build/build-types.js';
-import type { EcoPageComponent } from './eco/eco.types.js';
+import type { ApiResponseBuilder } from '../adapters/shared/api-response.js';
+import type { BuildExecutor } from '../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { ComponentBoundaryRuntime } from '../route-renderer/orchestration/component-render-context.js';
+import type { EcoPageComponent } from '../eco/eco.types.js';
 import type { EcoPagesAppConfig } from './internal-types.js';
-import type { HmrStrategy } from './hmr/hmr-strategy.js';
-import type { BrowserBundleExecutor } from './services/assets/browser-bundle.service.js';
-import type { ProcessedAsset } from './services/assets/asset-processing-service/assets.types.js';
-import type { CacheStats, CacheStrategy } from './services/cache/cache.types.js';
+import type { HmrStrategy } from '../hmr/hmr-strategy.js';
+import type { BrowserBundleExecutor } from '../services/assets/browser-bundle.service.js';
+import type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { CacheStats, CacheStrategy } from '../services/cache/cache.types.js';
 import type { InteractionEventsString as ScriptsInjectorInteractionEventsString } from '@ecopages/scripts-injector/types';
-export type { EcoPageComponent } from './eco/eco.types.js';
-export type { MarkerGraphContext } from './route-renderer/component-graph/marker-graph-resolver.js';
-export type { ProcessedAsset } from './services/assets/asset-processing-service/assets.types.js';
-import type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput } from './services/validation/standard-schema.types.js';
-export type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, };
+export type { EcoPagesAppConfig } from './internal-types.js';
+export type { EcoPageComponent } from '../eco/eco.types.js';
+export type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput } from '../services/validation/standard-schema.types.js';
+export type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, ComponentBoundaryRuntime, };
 export type InteractionEventsString = ScriptsInjectorInteractionEventsString;
 export type DependencyLazyTrigger = {
     'on:idle': true;
@@ -261,6 +262,21 @@ export type EcoComponentDependencies = {
     components?: EcoComponent[];
 };
 export type EcoPagesElement = string | Promise<string>;
+/**
+ * Serializable child payloads accepted by cross-integration deferred rendering.
+ *
+ * This models the broad value shapes that EcoPages already flattens when a
+ * foreign component boundary serializes its children for another integration.
+ * It is intentionally transport-oriented rather than framework-native, so it
+ * can be shared across Kita, Lit, React, and Ecopages JSX authoring surfaces
+ * without coupling core types to any one renderer.
+ */
+export type EcoChildren = string | Promise<string> | number | bigint | boolean | null | undefined | readonly EcoChildren[] | {
+    strings: readonly string[];
+    values?: readonly EcoChildren[];
+} | {
+    [key: string]: EcoChildren;
+};
 /**
  * Represents the input configuration for EcoPages.
  */
@@ -666,7 +682,7 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
 export interface ComponentRenderInput {
     component: EcoComponent;
     props: Record<string, unknown>;
-    children?: string;
+    children?: unknown;
     integrationContext?: unknown;
 }
 export interface ComponentRenderResult {

package/src/utils/html-escaping.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Escapes a string for safe use inside a double-quoted HTML attribute value.
+ *
+ * @param value Raw attribute value.
+ * @returns Escaped attribute-safe string.
+ */
+export declare function escapeHtmlAttribute(value: string): string;

package/src/utils/html-escaping.js

@@ -0,0 +1,6 @@
+function escapeHtmlAttribute(value) {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export {
+  escapeHtmlAttribute
+};

package/src/utils/locals-utils.d.ts

@@ -1,4 +1,4 @@
-import type { ApiHandlerContext } from '../public-types.js';
+import type { ApiHandlerContext } from '../types/public-types.js';
 /**
  * Creates a require function for validating and retrieving request locals.
  * Supports both single key access and multiple keys with type safety.

package/src/utils/parse-cli-args.d.ts

@@ -17,8 +17,11 @@ export type ReturnParseCliArgs = {
     hostname?: string;
     reactFastRefresh?: boolean;
 };
+export type ParseCliArgsOptions = {
+    embeddedRuntime?: boolean;
+};
 /**
  * Parses command line arguments for the server.
  * It returns {@link ReturnParseCliArgs}
  */
-export declare function parseCliArgs(): ReturnParseCliArgs;
+export declare function parseCliArgs(options?: ParseCliArgsOptions): ReturnParseCliArgs;

package/src/utils/parse-cli-args.js

@@ -1,8 +1,23 @@
 import { parseArgs } from "node:util";
 import { getRuntimeArgv } from "./runtime.js";
+function getEmbeddedRuntimeCommandOptions() {
+  const isDevelopment = process.env.NODE_ENV === "development";
+  return {
+    preview: false,
+    build: false,
+    start: !isDevelopment,
+    dev: isDevelopment,
+    port: void 0,
+    hostname: void 0,
+    reactFastRefresh: void 0
+  };
+}
 const ECOPAGES_BIN_FILES = ["ecopages.ts", "ecopages.js", "cli.js"];
 const ECOPAGES_AVAILABLE_COMMANDS = ["dev", "build", "start", "preview"];
-function parseCliArgs() {
+function parseCliArgs(options = {}) {
+  if (options.embeddedRuntime || process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME === "true") {
+    return getEmbeddedRuntimeCommandOptions();
+  }
   const runtimeArgv = getRuntimeArgv();
   const { values } = parseArgs({
     args: runtimeArgv,

package/src/utils/resolve-work-dir.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { DEFAULT_ECOPAGES_WORK_DIR } from "../constants.js";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
 function isInsideNodeModules(directory) {
   return path.normalize(directory).split(path.sep).includes("node_modules");
 }

package/src/watchers/project-watcher.d.ts

@@ -1,16 +1,16 @@
 import { type FSWatcher } from 'chokidar';
-import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../internal-types.js';
+import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../types/internal-types.js';
 /**
  * Configuration options for the ProjectWatcher
  * @interface ProjectWatcherConfig
  * @property {EcoPagesAppConfig} config - The application configuration
- * @property {() => void} refreshRouterRoutesCallback - Callback to refresh router routes
+ * @property {() => Promise<void>} refreshRouterRoutesCallback - Callback to refresh router routes
  * @property {IHmrManager} hmrManager - The HMR manager instance
  * @property {ClientBridge} bridge - The client bridge instance
  */
 export interface ProjectWatcherConfig {
     config: EcoPagesAppConfig;
-    refreshRouterRoutesCallback: () => void;
+    refreshRouterRoutesCallback: () => Promise<void>;
     hmrManager: IHmrManager;
     bridge: IClientBridge;
 }
@@ -112,7 +112,7 @@ export declare class ProjectWatcher {
      *
      * @param {string} path - Path of the changed directory
      */
-    triggerRouterRefresh(changedPath: string): void;
+    triggerRouterRefresh(changedPath: string): Promise<void>;
     /**
      * Handles and logs errors that occur during file watching.
      *