@ecopages/core 0.2.0-beta.35 → 0.2.0-beta.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.35",
+  "version": "0.2.0-beta.37",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,14 +17,14 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.35",
+    "@ecopages/file-system": "0.2.0-beta.37",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
-    "@oxc-project/runtime": "0.134.0",
+    "@oxc-project/runtime": "0.141.0",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
     "chokidar": "^5.0.0",
     "ghtml": "^4.0.2",
-    "oxc-parser": "^0.124.0",
+    "oxc-parser": "^0.141.0",
     "oxc-resolver": "^11.24.2",
     "rolldown": "^1.1.0",
     "ws": "^8.20.1",
@@ -32,7 +32,7 @@
     "@standard-schema/utils": "^0.3.0"
   },
   "peerDependencies": {
-    "@ecopages/dev-toolbar": "0.2.0-beta.35"
+    "@ecopages/dev-toolbar": "0.2.0-beta.37"
   },
   "peerDependenciesMeta": {
     "@ecopages/dev-toolbar": {
@@ -319,6 +319,10 @@
       "types": "./src/dev-toolbar/define-dev-tool.d.ts",
       "default": "./src/dev-toolbar/define-dev-tool.js"
     },
+    "./dev-toolbar/dev-toolbar-manifest-contract": {
+      "types": "./src/dev-toolbar/dev-toolbar-manifest-contract.d.ts",
+      "default": "./src/dev-toolbar/dev-toolbar-manifest-contract.js"
+    },
     "./create-app.ts": {
       "import": "./src/adapters/create-app.js",
       "types": "./src/adapters/create-app.d.ts",
@@ -591,6 +595,10 @@
     "./dev-toolbar/define-dev-tool.ts": {
       "types": "./src/dev-toolbar/define-dev-tool.d.ts",
       "default": "./src/dev-toolbar/define-dev-tool.js"
+    },
+    "./dev-toolbar/dev-toolbar-manifest-contract.ts": {
+      "types": "./src/dev-toolbar/dev-toolbar-manifest-contract.d.ts",
+      "default": "./src/dev-toolbar/dev-toolbar-manifest-contract.js"
     }
   },
   "types": "./src/index.d.ts"

package/src/dev/transform-server/dev-transform-import-rewriter.js

@@ -1,7 +1,23 @@
 import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
 import { cachedParseSync } from '../../cache/module-parse-cache.js';
 import { isBarePackageImportSpecifier, resolveProjectModulePath } from '../../plugins/tsconfig-import-resolver.js';
 import { resolveDevTransformModuleUrl } from './dev-transform-url.js';
+/**
+ * Builds a browser-importable dev-transform URL that changes when the source changes.
+ *
+ * @remarks
+ * Soft HMR reloads cache-bust the active page module, but transitive layout/component
+ * imports keep stable pathnames. A content hash query makes the browser ESM module map
+ * treat the updated dependency as a new module without a full page reload.
+ */
+function resolveVersionedDevTransformModuleUrl(srcDir, resolvedPath) {
+    const baseUrl = resolveDevTransformModuleUrl(srcDir, resolvedPath);
+    if (!fileSystem.exists(resolvedPath)) {
+        return baseUrl;
+    }
+    return `${baseUrl}?v=${fileSystem.hash(resolvedPath)}`;
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object';
 }
@@ -104,7 +120,7 @@ async function resolveImportSpecifier(options) {
             return undefined;
         }
         options.dependencies.add(resolvedPath);
-        return resolveDevTransformModuleUrl(options.srcDir, resolvedPath);
+        return resolveVersionedDevTransformModuleUrl(options.srcDir, resolvedPath);
     }
     return options.resolveVendorUrl(options.specifier);
 }

package/src/dev-toolbar/README.md

@@ -10,19 +10,20 @@ Server-side wiring for the development-only in-browser inspector. Public docs: [
 | **Client package** (`devToolbar.package`) | Dock UI, panels, and any extra apps                                                               |
 | **Integrations**                          | Page rendering and browser assets — not toolbar dock apps                                         |
 
-Extend the toolbar by setting `devToolbar.package` to your own client package (or `@ecopages/dev-toolbar`). Integrations do not register dock apps.
+`@ecopages/dev-toolbar` is an optional peer. Core does not import it at runtime unless `devToolbar.package` is configured. The dev manifest contract (`dev-toolbar-manifest-contract.ts`) lives in core so apps and custom toolbar clients can type the payload without installing the reference toolbar package.
 
 ## Module map
 
-| File                           | Role                                                                       |
-| ------------------------------ | -------------------------------------------------------------------------- |
-| `dev-toolbar-host.ts`          | Enablement, manifest contribution, runtime bundling, HTML injection        |
-| `dev-toolbar-manifest.ts`      | Builds and serializes the per-page dev manifest                            |
-| `dev-toolbar-package.ts`       | Resolves `devToolbar.package` bootstrap entry (`bootstrap.js`, then `.ts`) |
-| `dev-toolbar-config.ts`        | `isDevToolbarEnabled` — watch mode, env var, package required              |
-| `dev-toolbar-html-response.ts` | Adapter helpers for injecting `import '/_dev_toolbar.js'`                  |
-| `dev-toolbar-runtime-paths.ts` | `/_dev_toolbar.js` URL and work-dir paths                                  |
-| `define-dev-tool.ts`           | Config helper for bring-your-own client packages                           |
+| File                               | Role                                                                                                                                                                        |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dev-toolbar-host.ts`              | Enablement, manifest contribution, runtime bundling, HTML injection                                                                                                         |
+| `dev-toolbar-manifest-contract.ts` | `#__ECO_DEV_MANIFEST__` id and payload types (public: `@ecopages/core/dev-toolbar/dev-toolbar-manifest-contract`; mirrored in `@ecopages/dev-toolbar` for browser bundling) |
+| `dev-toolbar-manifest.ts`          | Builds and serializes the per-page dev manifest                                                                                                                             |
+| `dev-toolbar-package.ts`           | Resolves `devToolbar.package` bootstrap entry (`bootstrap.js`, then `.ts`)                                                                                                  |
+| `dev-toolbar-config.ts`            | `isDevToolbarEnabled` — watch mode, env var, package required                                                                                                               |
+| `dev-toolbar-html-response.ts`     | Adapter helpers for injecting `import '/_dev_toolbar.js'`                                                                                                                   |
+| `dev-toolbar-runtime-paths.ts`     | `/_dev_toolbar.js` URL and work-dir paths                                                                                                                                   |
+| `define-dev-tool.ts`               | Config helper for bring-your-own client packages                                                                                                                            |
 
 ## Injection order
 

package/src/dev-toolbar/dev-toolbar-manifest-contract.d.ts

@@ -0,0 +1,22 @@
+/** DOM id core uses when injecting `#__ECO_DEV_MANIFEST__` during watch mode. */
+export declare const DEV_MANIFEST_ELEMENT_ID = "__ECO_DEV_MANIFEST__";
+export type DevManifestAsset = {
+    srcUrl?: string;
+    kind: 'script' | 'stylesheet';
+    packageRole?: string;
+    inline?: boolean;
+};
+export type DevManifestPageBrowserGraph = {
+    entryAssets: DevManifestAsset[];
+    chunkAssets: DevManifestAsset[];
+};
+/**
+ * Server-serialized development metadata injected into HTML responses.
+ */
+export type EcoDevManifest = {
+    route: string;
+    integration?: string;
+    pageBrowserGraph?: DevManifestPageBrowserGraph;
+    vendorUrls: string[];
+    devTransformUrls: string[];
+};

package/src/dev-toolbar/dev-toolbar-manifest-contract.js

@@ -0,0 +1,2 @@
+/** DOM id core uses when injecting `#__ECO_DEV_MANIFEST__` during watch mode. */
+export const DEV_MANIFEST_ELEMENT_ID = '__ECO_DEV_MANIFEST__';

package/src/dev-toolbar/dev-toolbar-manifest.d.ts

@@ -1,6 +1,6 @@
 import type { PagePackageResult } from '../types/public-types.js';
-export { DEV_MANIFEST_ELEMENT_ID, type DevManifestAsset as DevToolbarManifestAsset, type EcoDevManifest as DevToolbarManifestPayload, } from '@ecopages/dev-toolbar/manifest';
-import { type EcoDevManifest } from '@ecopages/dev-toolbar/manifest';
+import { DEV_MANIFEST_ELEMENT_ID, type DevManifestAsset, type EcoDevManifest } from './dev-toolbar-manifest-contract.js';
+export { DEV_MANIFEST_ELEMENT_ID, type DevManifestAsset as DevToolbarManifestAsset, type EcoDevManifest as DevToolbarManifestPayload, };
 /**
  * Builds the dev toolbar manifest payload for one rendered page.
  */

package/src/dev-toolbar/dev-toolbar-manifest.js

@@ -1,6 +1,6 @@
 import { DEV_TRANSFORM_URL_PREFIX, VENDOR_URL_PREFIX } from '../hmr/hmr-asset-paths.js';
-export { DEV_MANIFEST_ELEMENT_ID, } from '@ecopages/dev-toolbar/manifest';
-import { DEV_MANIFEST_ELEMENT_ID } from '@ecopages/dev-toolbar/manifest';
+import { DEV_MANIFEST_ELEMENT_ID, } from './dev-toolbar-manifest-contract.js';
+export { DEV_MANIFEST_ELEMENT_ID, };
 function serializeAsset(asset) {
     if (!asset.srcUrl) {
         return undefined;

package/src/hmr/README.md

@@ -34,3 +34,14 @@ Dev client modules are served on demand through `DevTransformServer` (`src/dev/`
 `BrowserBundleService` is the sole browser-plugin resolver for HMR builds. HMR managers route `hmr-runtime` and `hmr-entrypoint` rebuilds through the `browser-hmr` executor profile.
 
 Hosts call `prepareHmrFileChange()` before HMR dispatch (`hmr/hmr-file-change-prep.ts`) so page browser graph sessions invalidate consistently with file changes.
+
+## Client events
+
+| Event           | Client behavior                                                                                                                                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `update`        | Cache-bust and re-import the changed module URL (or reload the active page module)                                                                                                                         |
+| `css-update`    | Refresh matching stylesheet `link` hrefs                                                                                                                                                                   |
+| `layout-update` | Soft current-page reload with layout cache cleared (`persistLayouts` remounts the updated layout without a full document reload). Falls back to `location.reload()` only if no navigation owner handles it |
+| `reload`        | Full `location.reload()`                                                                                                                                                                                   |
+
+Dev-transform local imports are rewritten with a content-hash query (`?v=…`) so transitive layout/component modules get a new ESM module-map key after invalidation. Soft `layout-update` then picks up the new layout while shared outer layout persistence still applies across normal SPA navigations.

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

@@ -48,10 +48,12 @@ import { applyModuleUpdate, resolveActiveModuleUrl } from './module-update.js';
                     clearCache: true,
                     moduleUrl: getActiveHmrModuleUrl(),
                 })) {
+                    break;
                 }
-                else if (!window.__ECOPAGES_HOST_OWNS_RELOAD__) {
-                    location.reload();
+                if (window.__ECOPAGES_HOST_OWNS_RELOAD__) {
+                    break;
                 }
+                location.reload();
                 break;
             }
             case 'error':