@ecopages/core 0.2.0-alpha.2 → 0.2.0-alpha.21

package/src/eco/eco.browser.js

@@ -0,0 +1,83 @@
+function createComponentFactory(options) {
+  const component2 = ((props) => options.render(props));
+  component2.config = {
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: options.dependencies
+  };
+  return component2;
+}
+function component(options) {
+  return createComponentFactory(options);
+}
+function html(options) {
+  return createComponentFactory(options);
+}
+function layout(options) {
+  return createComponentFactory(options);
+}
+function page(options) {
+  const {
+    layout: pageLayout,
+    dependencies,
+    render,
+    staticPaths: staticPaths2,
+    staticProps: staticProps2,
+    metadata: metadata2,
+    cache,
+    requires,
+    middleware
+  } = options;
+  const pageComponent = createComponentFactory({
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: pageLayout ? {
+      ...dependencies,
+      components: [...dependencies?.components ?? [], pageLayout]
+    } : dependencies,
+    render
+  });
+  if (pageLayout && pageComponent.config) {
+    pageComponent.config.layout = pageLayout;
+  }
+  if (staticPaths2) {
+    pageComponent.staticPaths = staticPaths2;
+  }
+  if (staticProps2) {
+    pageComponent.staticProps = staticProps2;
+  }
+  if (metadata2) {
+    pageComponent.metadata = metadata2;
+  }
+  if (cache) {
+    pageComponent.cache = cache;
+  }
+  if (requires) {
+    pageComponent.requires = requires;
+  }
+  if (middleware) {
+    pageComponent.middleware = middleware;
+  }
+  return pageComponent;
+}
+function metadata(fn) {
+  return fn;
+}
+function staticPaths(fn) {
+  return fn;
+}
+function staticProps(fn) {
+  return fn;
+}
+const eco = {
+  component,
+  html,
+  layout,
+  page,
+  metadata,
+  staticPaths,
+  staticProps
+};
+export {
+  eco
+};

package/src/eco/eco.js

@@ -1,60 +1,27 @@
-import { createNodeId, createPropsRef, createSlotRef, getComponentRenderContext } from "./component-render-context.js";
-import { createComponentMarker, parseComponentMarkers } from "../route-renderer/component-marker.js";
-import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./eco.utils.js";
+import {
+  finalizeComponentRender,
+  interceptComponentBoundary
+} from "../route-renderer/orchestration/component-render-context.js";
+import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
 function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;
   const comp = ((props) => {
-    const renderContext = getComponentRenderContext();
-    const shouldEmitMarker = renderContext !== void 0 && renderContext.boundaryContext.decideBoundaryRender({
-      currentIntegration: renderContext.currentIntegration,
-      targetIntegration: integrationName,
-      component: comp
-    }) === "defer";
-    if (shouldEmitMarker && renderContext) {
-      const nodeId = createNodeId(renderContext);
-      const propsRef = createPropsRef(renderContext);
-      const componentRef = comp.config?.__eco?.id ?? comp.config?.__eco?.file;
-      if (!componentRef) {
-        throw new Error(
-          "[ecopages] Missing component reference metadata for cross-integration marker emission."
-        );
-      }
-      const componentProps = props ?? {};
-      renderContext.propsByRef[propsRef] = componentProps;
-      let slotRef;
-      const children = componentProps.children;
-      if (typeof children === "string" && children.includes("<eco-marker")) {
-        const childMarkers = parseComponentMarkers(children);
-        if (childMarkers.length > 0) {
-          slotRef = createSlotRef(renderContext);
-          renderContext.slotChildrenByRef[slotRef] = childMarkers.map((marker) => marker.nodeId);
-        }
-      }
-      return createComponentMarker({
-        nodeId,
-        integration: integrationName,
-        componentRef,
-        propsRef,
-        slotRef
-      });
+    const componentProps = props ?? {};
+    const renderInline = () => finalizeComponentRender(comp, options.render(props));
+    const boundaryRender = interceptComponentBoundary({
+      component: comp,
+      props: componentProps,
+      targetIntegration: integrationName
+    });
+    if (isThenable(boundaryRender)) {
+      return boundaryRender.then(
+        (resolvedBoundaryRender) => resolvedBoundaryRender !== void 0 ? resolvedBoundaryRender : renderInline()
+      );
     }
-    const content = options.render(props);
-    const lazyTriggers = comp.config?._resolvedLazyTriggers;
-    if (lazyTriggers && lazyTriggers.length > 0) {
-      const triggerId = lazyTriggers[0].triggerId;
-      if (isThenable(content)) {
-        return content.then((resolvedContent) => addTriggerAttribute(resolvedContent, triggerId));
-      }
-      return addTriggerAttribute(content, triggerId);
+    if (boundaryRender !== void 0) {
+      return boundaryRender;
     }
-    const lazyGroups = comp.config?._resolvedLazyScripts;
-    if (lazyGroups && lazyGroups.length > 0) {
-      if (isThenable(content)) {
-        return content.then((resolvedContent) => wrapWithScriptsInjector(resolvedContent, lazyGroups));
-      }
-      return wrapWithScriptsInjector(content, lazyGroups);
-    }
-    return content;
+    return renderInline();
   });
   comp.config = {
     __eco: options.__eco,
@@ -66,20 +33,26 @@ function createComponentFactory(options) {
 function component(options) {
   return createComponentFactory(options);
 }
+function html(options) {
+  return createComponentFactory(options);
+}
+function layout(options) {
+  return createComponentFactory(options);
+}
 function page(options) {
-  const { layout, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
+  const { layout: layout2, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
   const componentOptions = {
     __eco: options.__eco,
     integration: options.integration,
-    dependencies: layout ? {
+    dependencies: layout2 ? {
       ...dependencies,
-      components: [...dependencies?.components || [], layout]
+      components: [...dependencies?.components || [], layout2]
     } : dependencies,
     render
   };
   const pageComponent = createComponentFactory(componentOptions);
-  if (layout && pageComponent.config) {
-    pageComponent.config.layout = layout;
+  if (layout2 && pageComponent.config) {
+    pageComponent.config.layout = layout2;
   }
   if (staticPaths2) pageComponent.staticPaths = staticPaths2;
   if (staticProps2) pageComponent.staticProps = staticProps2;
@@ -100,6 +73,8 @@ function staticProps(fn) {
 }
 const eco = {
   component,
+  html,
+  layout,
   page,
   metadata,
   staticPaths,

package/src/eco/eco.types.d.ts

@@ -2,7 +2,7 @@
  * Type definitions for the eco namespace API
  * @module
  */
-import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoInjectedMeta, EcoPagesElement, GetMetadata, GetStaticPaths, GetStaticProps, Middleware, RequestLocals, RequestPageContext } from '../public-types.js';
+import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayoutComponent, EcoPagesElement, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, Middleware, RequestLocals, RequestPageContext } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
 type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K> & {
     [P in K]-?: Exclude<RequestLocals[P], null | undefined>;
@@ -26,6 +26,8 @@ export interface ComponentOptions<P, E = EcoPagesElement> {
     dependencies?: EcoComponentDependencies;
     render: (props: P) => E | Promise<E>;
 }
+export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
 /**
  * Base options shared by all page variants
  */
@@ -34,9 +36,7 @@ export interface PageOptionsBase<T, E = EcoPagesElement> {
     __eco?: EcoInjectedMeta;
     integration?: string;
     dependencies?: EcoComponentDependencies;
-    layout?: EcoComponent<{
-        children: E;
-    } & Partial<RequestPageContext>>;
+    layout?: EcoPageLayoutComponent<E>;
     /**
      * Define static paths for dynamic routes (e.g., [slug].tsx).
      * Returns all possible paths that should be pre-rendered at build time.
@@ -139,6 +139,14 @@ export interface Eco {
      * @template E - Element/return type (EcoPagesElement for Kita, ReactNode for React)
      */
     component: <P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>) => EcoComponent<P, E>;
+    /**
+     * Create a document shell component for the HTML wrapper.
+     */
+    html: <E = EcoPagesElement>(options: HtmlOptions<E>) => EcoHtmlComponent<E>;
+    /**
+     * Create a route layout component.
+     */
+    layout: <E = EcoPagesElement>(options: LayoutOptions<E>) => EcoLayoutComponent<E>;
     /**
      * Create a page component with type-safe props from getStaticProps.
      * Returns an EcoPageComponent with attached staticPaths, staticProps, and metadata.

package/src/eco/eco.utils.d.ts

@@ -1,40 +1 @@
-import type { EcoComponent } from '../public-types.js';
-/**
- * Returns `true` when `value` is a thenable (Promise-like) object.
- *
- * Used to transparently handle both synchronous and asynchronous component
- * render results without requiring every caller to branch on `instanceof Promise`.
- *
- * @typeParam T Expected resolved type of the thenable.
- */
-export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;
-/**
- * Injects `data-eco-trigger` into the first real HTML element opening tag of
- * a component's rendered output string.
- *
- * The scan skips over leading whitespace, HTML comments (`<!-- -->`), CDATA
- * sections, and doctype declarations so that the attribute is always placed on
- * the first actual element — not spurious markup that can precede it.
- *
- * The insertion point is the end of the element's tag name, before any existing
- * attributes or the closing `>`, which produces output like:
- *
- * ```html
- * <my-element data-eco-trigger="eco-trigger-abc123" class="foo">…</my-element>
- * ```
- *
- * When no eligible opening tag is found the original string is returned
- * unchanged so callers never receive a broken fragment.
- *
- * @param content Rendered HTML string (or any value coercible to string).
- * @param triggerId Stable trigger identifier produced by `buildResolvedLazyTriggers`.
- */
-export declare function addTriggerAttribute(content: unknown, triggerId: string): string;
-/**
- * Wraps rendered component output in a `<scripts-injector>` element that
- * carries an inline injector map for the legacy (non-global-injector) path.
- *
- * @param content Rendered component HTML.
- * @param lazyGroups Resolved lazy script groups attached to the component config.
- */
-export declare function wrapWithScriptsInjector(content: unknown, lazyGroups: NonNullable<EcoComponent['config']>['_resolvedLazyScripts']): string;
+export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/render-output.utils.js';

package/src/eco/eco.utils.js

@@ -1,38 +1,8 @@
-import { buildInjectorMapScript } from "./lazy-injector-map.js";
-function isThenable(value) {
-  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
-}
-function addTriggerAttribute(content, triggerId) {
-  const str = String(content);
-  let i = 0;
-  while (i < str.length) {
-    if (str[i] !== "<") {
-      i++;
-      continue;
-    }
-    const next = str[i + 1];
-    if (next === "!" || next === "?") {
-      const end = str.indexOf(">", i);
-      if (end === -1) break;
-      i = end + 1;
-      continue;
-    }
-    if (next && /[a-zA-Z]/.test(next)) {
-      const tagSlice = str.slice(i + 1);
-      const nameEnd = tagSlice.search(/[\s/>]/);
-      if (nameEnd === -1) break;
-      const insertAt = i + 1 + nameEnd;
-      return `${str.slice(0, insertAt)} data-eco-trigger="${triggerId}"${str.slice(insertAt)}`;
-    }
-    break;
-  }
-  return str;
-}
-function wrapWithScriptsInjector(content, lazyGroups) {
-  const wrappedContent = String(content);
-  const injectorMapScript = buildInjectorMapScript(lazyGroups ?? []);
-  return `<scripts-injector><script type="ecopages/injector-map">${injectorMapScript}<\/script>${wrappedContent}<\/scripts-injector>`;
-}
+import {
+  addTriggerAttribute,
+  isThenable,
+  wrapWithScriptsInjector
+} from "../route-renderer/orchestration/render-output.utils.js";
 export {
   addTriggerAttribute,
   isThenable,

package/src/eco/global-injector-map.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedLazyTrigger } from '../public-types.js';
+import type { ResolvedLazyTrigger } from '../types/public-types.js';
 /**
  * Serializes resolved lazy triggers into a JSON string safe for embedding
  * inside an inline `<script type="ecopages/global-injector-map">` tag.

package/src/eco/lazy-injector-map.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedLazyScriptGroup } from '../public-types.js';
+import type { ResolvedLazyScriptGroup } from '../types/public-types.js';
 /**
  * Creates a safe JSON payload string for `<script type="ecopages/injector-map">`.
  *

package/src/hmr/README.md

@@ -0,0 +1,26 @@
+# HMR Layer
+
+This directory contains the framework-owned hot-update strategy contracts used by runtime adapters and integrations.
+
+## Purpose
+
+The HMR layer separates change classification from update execution.
+
+It is responsible for:
+
+- defining the shared HMR manager and strategy contracts
+- letting integrations contribute framework-specific update strategies
+- keeping adapter transports independent from update policy
+
+## How It Fits
+
+1. `ProjectWatcher` observes file changes.
+2. `DevelopmentInvalidationService` classifies the change.
+3. The active HMR manager selects a strategy.
+4. The strategy coordinates browser rebuilds, metadata reloads, and client broadcasts.
+
+## Design Rule
+
+Generic invalidation policy belongs in core services.
+Framework-specific update behavior belongs in HMR strategies.
+Runtime-specific WebSocket or event-stream transport belongs in adapters.

package/src/hmr/client/hmr-runtime.d.ts

@@ -2,9 +2,4 @@
  * Ecopages HMR Runtime
  * Injected into the browser to handle Hot Module Replacement updates.
  */
-interface HMRPayload {
-    type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
-    path?: string;
-    message?: string;
-    timestamp?: number;
-}
+export {};

package/src/hmr/client/hmr-runtime.js

@@ -1,3 +1,4 @@
+import { getEcoNavigationRuntime } from "../../router/client/navigation-coordinator.js";
 (function() {
   const WS_URL = "ws://" + location.host + "/_hmr";
   let socket;
@@ -24,14 +25,15 @@
     });
   }
   async function handleMessage(payload) {
+    const navigationRuntime = getEcoNavigationRuntime(window);
     switch (payload.type) {
       case "reload":
+        await waitForNavigationToSettle(navigationRuntime);
         location.reload();
         break;
       case "layout-update": {
-        const reloadFn = window.__ecopages_reload_current_page__;
-        if (typeof reloadFn === "function") {
-          await reloadFn({ clearCache: true });
+        await waitForNavigationToSettle(navigationRuntime);
+        if (await navigationRuntime.reloadCurrentPage({ clearCache: true })) {
         } else {
           location.reload();
         }
@@ -55,20 +57,41 @@
   async function applyUpdate(path, timestamp) {
     try {
       const url = path + "?t=" + (timestamp || Date.now());
-      const handlers = window.__ecopages_hmr_handlers__;
+      const handlers = window.__ECO_PAGES__?.hmrHandlers;
+      const navigationRuntime = getEcoNavigationRuntime(window);
+      await waitForNavigationToSettle(navigationRuntime);
       if (handlers?.[path]) {
         await handlers[path](url);
         return;
       }
       await import(url);
-      const reloadFn = window.__ecopages_reload_current_page__;
-      if (typeof reloadFn === "function") {
-        await reloadFn({ clearCache: false });
+      if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
       }
     } catch (e) {
       console.error("[ecopages] Failed to apply HMR update:", e);
     }
   }
+  async function waitForNavigationToSettle(navigationRuntime) {
+    if (!navigationRuntime.hasPendingNavigationTransaction()) {
+      return;
+    }
+    await new Promise((resolve) => {
+      const startedAt = performance.now();
+      const timeoutMs = 2e3;
+      const poll = () => {
+        if (!navigationRuntime.hasPendingNavigationTransaction()) {
+          resolve();
+          return;
+        }
+        if (performance.now() - startedAt >= timeoutMs) {
+          resolve();
+          return;
+        }
+        requestAnimationFrame(poll);
+      };
+      requestAnimationFrame(poll);
+    });
+  }
   function refreshStylesheet(path) {
     const filename = path.split("/").pop() || "";
     const links = document.querySelectorAll('link[rel="stylesheet"]');

package/src/hmr/hmr-strategy.d.ts

@@ -1,4 +1,4 @@
-import type { ClientBridgeEvent } from '../public-types';
+import type { ClientBridgeEvent } from '../types/public-types.js';
 /**
  * HMR Strategy Pattern
  *
@@ -18,11 +18,13 @@ import type { ClientBridgeEvent } from '../public-types';
  *   async process(filePath: string): Promise<HmrAction> {
  *     return {
  *       type: 'broadcast',
- *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }]
+ *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }],
  *     };
  *   }
  * }
-
+ * ```
+ */
+/**
  * Defines the category of an HMR strategy, which determines its execution priority.
  * Strategies are evaluated in descending order: INTEGRATION → ASSET → SCRIPT → FALLBACK.
  *
@@ -30,28 +32,29 @@ import type { ClientBridgeEvent } from '../public-types';
  * The numeric values represent base priorities. Strategies can fine-tune their priority
  * using the `priorityOffset` property.
  */
-export declare enum HmrStrategyType {
+export declare const HmrStrategyType: {
     /**
      * Integration-specific strategies (React, Lit, etc.)
      * Highest priority to allow framework-specific HMR handling.
      */
-    INTEGRATION = 100,
+    readonly INTEGRATION: 100;
     /**
      * Asset processing strategies (CSS, images, etc.)
      * High priority for specialized asset handling.
      */
-    ASSET = 50,
+    readonly ASSET: 50;
     /**
      * Generic script bundling strategies (JS/TS)
      * Medium priority for standard script processing.
      */
-    SCRIPT = 25,
+    readonly SCRIPT: 25;
     /**
      * Fallback strategy for unhandled file types.
      * Lowest priority, triggers full page reload.
      */
-    FALLBACK = 0
-}
+    readonly FALLBACK: 0;
+};
+export type HmrStrategyType = (typeof HmrStrategyType)[keyof typeof HmrStrategyType];
 /**
  * Represents an action to be taken after processing a file change.
  */
@@ -62,7 +65,7 @@ export interface HmrAction {
     type: 'broadcast' | 'none';
     /**
      * The HMR events to broadcast, if type is 'broadcast'.
-     * capable of broadcasting multiple events at once.
+     * Multiple events may be broadcast in one action.
      */
     events?: ClientBridgeEvent[];
 }
@@ -74,8 +77,8 @@ export interface HmrAction {
  * whether they match the changed file path.
  *
  * @remarks
- * Strategies should be stateless and idempotent. The same file change should always
- * produce the same result when processed by the same strategy.
+ * Strategies are expected to be stateless and idempotent. The same file change
+ * should produce the same result when processed by the same strategy.
  *
  * @example
  * ```typescript
@@ -120,7 +123,7 @@ export declare abstract class HmrStrategy {
      * Determines if this strategy can handle the given file path.
      *
      * @param filePath - Absolute path to the changed file
-     * @returns True if this strategy should process the file
+     * @returns `true` when this strategy should process the file
      *
      * @example
      * ```typescript

package/src/hmr/hmr-strategy.js

@@ -1,10 +1,25 @@
-var HmrStrategyType = /* @__PURE__ */ ((HmrStrategyType2) => {
-  HmrStrategyType2[HmrStrategyType2["INTEGRATION"] = 100] = "INTEGRATION";
-  HmrStrategyType2[HmrStrategyType2["ASSET"] = 50] = "ASSET";
-  HmrStrategyType2[HmrStrategyType2["SCRIPT"] = 25] = "SCRIPT";
-  HmrStrategyType2[HmrStrategyType2["FALLBACK"] = 0] = "FALLBACK";
-  return HmrStrategyType2;
-})(HmrStrategyType || {});
+const HmrStrategyType = {
+  /**
+   * Integration-specific strategies (React, Lit, etc.)
+   * Highest priority to allow framework-specific HMR handling.
+   */
+  INTEGRATION: 100,
+  /**
+   * Asset processing strategies (CSS, images, etc.)
+   * High priority for specialized asset handling.
+   */
+  ASSET: 50,
+  /**
+   * Generic script bundling strategies (JS/TS)
+   * Medium priority for standard script processing.
+   */
+  SCRIPT: 25,
+  /**
+   * Fallback strategy for unhandled file types.
+   * Lowest priority, triggers full page reload.
+   */
+  FALLBACK: 0
+};
 class HmrStrategy {
   /**
    * Optional offset to fine-tune priority within the same category.

package/src/hmr/hmr.postcss.test.e2e.d.ts

@@ -0,0 +1 @@
+export {};

package/src/hmr/hmr.postcss.test.e2e.js

@@ -0,0 +1,31 @@
+import { test, expect } from "@playwright/test";
+import { readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+const FIXTURE_DIR = resolve(process.cwd(), "packages/core/__fixtures__/app");
+const TEST_CSS_FILE = resolve(FIXTURE_DIR, "src/pages/postcss-hmr.css");
+test.describe("HMR E2E PostCSS", () => {
+  test("should hot-update processor-owned CSS without a full page reload", async ({ page }) => {
+    const originalCss = readFileSync(TEST_CSS_FILE, "utf-8");
+    const title = page.locator(".postcss-title").first();
+    try {
+      await page.goto("/postcss-hmr", { waitUntil: "networkidle" });
+      await expect(title).toBeVisible();
+      const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
+      expect(initialColor).toBeTruthy();
+      await page.evaluate(() => {
+        window.__postcssReloadProbe = "before-change";
+      });
+      const modifiedCss = originalCss.replace(".postcss-title {", ".postcss-title {\n	color: rgb(255, 0, 0);");
+      await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+      await expect.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 1e4 }).toBe("rgb(255, 0, 0)");
+      await expect(
+        page.evaluate(
+          () => window.__postcssReloadProbe ?? null
+        )
+      ).resolves.toBe("before-change");
+    } finally {
+      await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+    }
+  });
+});