@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

package/src/dev/transform-server/dev-transform-vendor-registry.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { RESOLVED_ASSETS_VENDORS_DIR } from '../../config/constants.js';
+import { getAppBrowserBuildPlugins } from '../../build/build-adapter.js';
+import { resolveBarePackageBrowserEntry } from '../../plugins/tsconfig-import-resolver.js';
+import { toPackageRootSpecifier } from '../../plugins/package-specifier.js';
+import { resolveRuntimeSpecifierPublicPath } from '../../build/browser/browser-runtime-manifest.js';
+import { BrowserBundleService } from '../../services/assets/browser-bundle.service.js';
+const BROWSER_FIRST_VENDOR_CONDITIONS = ['browser', 'module', 'import', 'default'];
+const MODULE_FIRST_VENDOR_CONDITIONS = ['module', 'import', 'default'];
+const BROWSER_NODE_BUILTIN_GUARD_MARKER = '[browser-build] Node builtin';
+function getVendorBundleConditions(specifier) {
+    return toPackageRootSpecifier(specifier) === '@ecopages/core'
+        ? BROWSER_FIRST_VENDOR_CONDITIONS
+        : MODULE_FIRST_VENDOR_CONDITIONS;
+}
+/**
+ * Lazily prebundles bare npm imports into cacheable `/assets/vendors/*` chunks.
+ */
+export class DevTransformVendorRegistry {
+    appConfig;
+    browserBundleService;
+    getRuntimeSpecifierMap;
+    resolveVendorBundlePlugins;
+    vendorsDir;
+    cache = new Map();
+    inFlight = new Map();
+    constructor(options) {
+        this.appConfig = options.appConfig;
+        this.browserBundleService = new BrowserBundleService(options.appConfig);
+        this.getRuntimeSpecifierMap = options.getRuntimeSpecifierMap;
+        this.resolveVendorBundlePlugins = options.resolveVendorBundlePlugins;
+        const distDir = options.appConfig.absolutePaths?.distDir ?? path.join(options.appConfig.rootDir, '.eco');
+        this.vendorsDir = path.join(distDir, RESOLVED_ASSETS_VENDORS_DIR);
+    }
+    resolveKnownVendorUrl(specifier) {
+        return resolveRuntimeSpecifierPublicPath(specifier, this.getRuntimeSpecifierMap());
+    }
+    async resolveVendorUrl(specifier) {
+        const known = this.resolveKnownVendorUrl(specifier);
+        if (known && this.resolveExistingVendorPath(known)) {
+            return known;
+        }
+        const cached = this.cache.get(specifier);
+        if (cached) {
+            return cached.url;
+        }
+        const pending = this.inFlight.get(specifier);
+        if (pending) {
+            return (await pending).url;
+        }
+        const promise = this.prebundleSpecifier(specifier).finally(() => {
+            this.inFlight.delete(specifier);
+        });
+        this.inFlight.set(specifier, promise);
+        return (await promise).url;
+    }
+    tryHandleVendorRequest(pathname) {
+        const prefix = `/${RESOLVED_ASSETS_VENDORS_DIR}/`;
+        if (!pathname.startsWith(prefix)) {
+            return null;
+        }
+        const fileName = pathname.slice(prefix.length);
+        if (!fileName || fileName.includes('..')) {
+            return null;
+        }
+        const filePath = path.join(this.vendorsDir, fileName);
+        if (!fileSystem.exists(filePath)) {
+            for (const entry of this.cache.values()) {
+                if (entry.url === pathname && fileSystem.exists(entry.filePath)) {
+                    return this.createVendorResponse(entry.filePath);
+                }
+            }
+            return null;
+        }
+        return this.createVendorResponse(filePath);
+    }
+    invalidateAll() {
+        this.cache.clear();
+        this.inFlight.clear();
+    }
+    createVendorResponse(filePath) {
+        return new Response(fileSystem.readFileSync(filePath), {
+            headers: {
+                'Content-Type': 'application/javascript',
+                'Cache-Control': 'public, max-age=31536000, immutable',
+            },
+        });
+    }
+    resolveExistingVendorPath(url) {
+        const prefix = `/${RESOLVED_ASSETS_VENDORS_DIR}/`;
+        const pathname = new URL(url, 'http://ecopages.local').pathname;
+        if (!pathname.startsWith(prefix)) {
+            return undefined;
+        }
+        const fileName = pathname.slice(prefix.length);
+        if (!fileName || fileName.includes('..')) {
+            return undefined;
+        }
+        const filePath = path.join(this.vendorsDir, fileName);
+        return fileSystem.exists(filePath) ? filePath : undefined;
+    }
+    async prebundleSpecifier(specifier) {
+        const resolvedEntry = this.resolvePackageEntry(specifier);
+        fileSystem.ensureDir(this.vendorsDir);
+        const fileName = `${sanitizeSpecifierForFileName(specifier)}.${hashVendorEntry(specifier, resolvedEntry)}.js`;
+        const outPath = path.join(this.vendorsDir, fileName);
+        const url = `/${RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
+        if (fileSystem.exists(outPath)) {
+            const entry = { url, filePath: outPath };
+            this.cache.set(specifier, entry);
+            return entry;
+        }
+        const vendorPlugins = this.resolveVendorBundlePlugins ? await this.resolveVendorBundlePlugins() : [];
+        const result = await this.browserBundleService.bundle({
+            profile: 'browser-script',
+            entrypoints: [resolvedEntry],
+            outdir: this.vendorsDir,
+            naming: fileName,
+            minify: false,
+            externalPackages: false,
+            treeshaking: true,
+            splitting: false,
+            conditions: [...getVendorBundleConditions(specifier)],
+            excludeAppBuildPlugins: getAppBrowserBuildPlugins(this.appConfig).map((plugin) => plugin.name),
+            plugins: [...vendorPlugins],
+        });
+        if (!result.success) {
+            const details = result.logs.map((log) => log.message).join('\n');
+            throw new Error(formatVendorPrebundleError(specifier, details));
+        }
+        const outputPath = result.outputs[0]?.path ?? outPath;
+        const entry = { url, filePath: outputPath };
+        this.cache.set(specifier, entry);
+        return entry;
+    }
+    resolvePackageEntry(specifier) {
+        const resolved = resolveBarePackageBrowserEntry(this.appConfig.rootDir, specifier);
+        if (!resolved) {
+            throw new Error(`[dev-transform] Unable to resolve bare import "${specifier}" for vendor prebundle`);
+        }
+        return resolved;
+    }
+}
+function formatVendorPrebundleError(specifier, details) {
+    if (details.includes(BROWSER_NODE_BUILTIN_GUARD_MARKER)) {
+        return (`[dev-transform] Bare import "${specifier}" resolved to a server-only entry. ` +
+            `Import a browser subpath or register the package in the browser runtime manifest.` +
+            (details ? `\n${details}` : ''));
+    }
+    return details
+        ? `[dev-transform] Vendor prebundle failed for ${specifier}:\n${details}`
+        : `[dev-transform] Vendor prebundle failed for ${specifier}`;
+}
+function sanitizeSpecifierForFileName(specifier) {
+    return specifier.replaceAll(/^@/gu, '').replaceAll(/[/:@]/gu, '-');
+}
+function hashVendorEntry(specifier, entryPath) {
+    return createHash('sha256')
+        .update(specifier)
+        .update('\0')
+        .update(fileSystem.readFileSync(entryPath))
+        .digest('hex')
+        .slice(0, 8);
+}

package/src/dev/transform-server/index.d.ts

@@ -0,0 +1,6 @@
+export { DevTransformServer } from './dev-transform-server.js';
+export type { DevTransformServerOptions } from './dev-transform-server.js';
+export { DevTransformBundler } from './dev-transform-bundler.js';
+export type { DevTransformBundleContributor, DevTransformBundleResult } from './types.js';
+export { DevTransformVendorRegistry } from './dev-transform-vendor-registry.js';
+export { resolveDevTransformModuleUrl, DEV_TRANSFORM_URL_PREFIX } from './dev-transform-url.js';

package/src/dev/transform-server/index.js

@@ -0,0 +1,4 @@
+export { DevTransformServer } from './dev-transform-server.js';
+export { DevTransformBundler } from './dev-transform-bundler.js';
+export { DevTransformVendorRegistry } from './dev-transform-vendor-registry.js';
+export { resolveDevTransformModuleUrl, DEV_TRANSFORM_URL_PREFIX } from './dev-transform-url.js';

package/src/dev/transform-server/types.d.ts

@@ -0,0 +1,15 @@
+import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
+export type DevTransformBundleResult = {
+    code: string;
+    dependencies?: string[];
+};
+export type DevTransformBundleContributor = {
+    /** Returns whether this contributor owns the source module path. */
+    ownsModule(sourcePath: string): boolean;
+    /** Integration-owned plugins for one dev-transform module (boundary, MDX, etc.). */
+    getModulePlugins(sourcePath: string): Promise<readonly EcoBuildPlugin[]>;
+    /** Runtime manifest specifiers already served from `/assets/vendors/*`. */
+    getRuntimeSpecifierMap?(): ReadonlyMap<string, string>;
+    /** Plugins applied to lazy vendor prebundles (client-graph boundary, runtime rewrites). */
+    getVendorBundlePlugins?(): Promise<readonly EcoBuildPlugin[]>;
+};

package/src/dev/transform-server/types.js

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

package/src/dev-toolbar/README.md

@@ -0,0 +1,52 @@
+# Dev toolbar (core)
+
+Server-side wiring for the development-only in-browser inspector. Public docs: [Dev toolbar](/docs/core/dev-toolbar).
+
+## Boundaries
+
+| Layer                                     | Owns                                                                                              |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| **Core** (`DevToolbarHost`)               | Enablement, `/_dev_toolbar.js` delivery, per-route `#__ECO_DEV_MANIFEST__`, HTML script injection |
+| **Client package** (`devToolbar.package`) | Dock UI, panels, and any extra apps                                                               |
+| **Integrations**                          | Page rendering and browser assets — not toolbar 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-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
+
+1. Route HTML is finalized with `#__ECO_DEV_MANIFEST__` appended to `<body>` (`route-html-finalization.service.ts`).
+2. The server adapter injects `import '/_dev_toolbar.js'` before `</html>` when the toolbar is enabled (`server-adapter.ts` → `DevToolbarHost.injectHtmlResponse`).
+3. HMR manager copies or bundles the configured client package to `/_dev_toolbar.js` during watch mode (`shared-hmr-manager.ts`).
+
+## Config
+
+```ts
+import { devToolbar } from '@ecopages/dev-toolbar/config';
+
+.setDevToolbar(devToolbar())
+```
+
+Bring-your-own client:
+
+```ts
+import { defineDevTool } from '@ecopages/core/dev-toolbar/define-dev-tool';
+
+.setDevToolbar(defineDevTool('@acme/my-dev-toolbar'))
+```
+
+Disable per project with `devToolbar: { enabled: false }`, or per process with `ECOPAGES_DEV_TOOLBAR=false`.
+
+Parent index: [dev/README.md](../dev/README.md).

package/src/dev-toolbar/define-dev-tool.d.ts

@@ -0,0 +1,21 @@
+import type { DevToolbarConfig } from './dev-toolbar-config.js';
+export type DefineDevToolOptions = {
+    /**
+     * Client package resolved from the application project.
+     *
+     * @example '@ecopages/dev-toolbar'
+     */
+    package: string;
+    /** @default true */
+    enabled?: boolean;
+};
+/**
+ * Builds a `devToolbar` config block for bring-your-own client packages.
+ *
+ * @remarks
+ * Prefer importing `devToolbar` from `@ecopages/dev-toolbar/config` for the
+ * official toolbar. Keep server config limited to package resolution and
+ * enablement; UI preferences stay in the client package.
+ */
+export declare function defineDevTool(packageName: string): DevToolbarConfig;
+export declare function defineDevTool(options: DefineDevToolOptions): DevToolbarConfig;

package/src/dev-toolbar/define-dev-tool.js

@@ -0,0 +1,9 @@
+export function defineDevTool(packageNameOrOptions) {
+    if (typeof packageNameOrOptions === 'string') {
+        return { package: packageNameOrOptions };
+    }
+    return {
+        package: packageNameOrOptions.package,
+        ...(packageNameOrOptions.enabled === undefined ? {} : { enabled: packageNameOrOptions.enabled }),
+    };
+}

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

@@ -0,0 +1,25 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+export type DevToolbarConfig = {
+    /**
+     * Whether the in-browser dev toolbar is enabled during development.
+     *
+     * @default true when `package` is configured
+     */
+    enabled?: boolean;
+    /**
+     * Client package entry resolved from the application project.
+     *
+     * @remarks
+     * Install the package in the app (for example `@ecopages/dev-toolbar`) and
+     * point `package` at its browser bootstrap export. Core bundles that module
+     * to `/_dev_toolbar.js` during watch mode.
+     */
+    package?: string;
+};
+/**
+ * Returns whether the dev toolbar should be injected for the current process.
+ */
+export declare function isDevToolbarEnabled(appConfig: Pick<EcoPagesAppConfig, 'devToolbar'>, options: {
+    watch: boolean;
+    hostOwnsDevClient?: boolean;
+}): boolean;

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

@@ -0,0 +1,19 @@
+import { getDevToolbarPackageSpec } from './dev-toolbar-package.js';
+/**
+ * Returns whether the dev toolbar should be injected for the current process.
+ */
+export function isDevToolbarEnabled(appConfig, options) {
+    if (options.hostOwnsDevClient) {
+        return false;
+    }
+    if (!options.watch) {
+        return false;
+    }
+    if (process.env.ECOPAGES_DEV_TOOLBAR === 'false') {
+        return false;
+    }
+    if (!getDevToolbarPackageSpec(appConfig)) {
+        return false;
+    }
+    return appConfig.devToolbar?.enabled !== false;
+}

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

@@ -0,0 +1,49 @@
+import type { HtmlDocumentContribution } from '../services/html/html-transformer.service.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { PagePackageResult } from '../types/public-types.js';
+export type DevToolbarHostOptions = {
+    watch: boolean;
+    hostOwnsDevClient?: boolean;
+};
+type DevToolbarBundleService = {
+    bundle: (options: {
+        profile: 'hmr-runtime';
+        entrypoints: string[];
+        outdir: string;
+        naming: string;
+        minify: boolean;
+    }) => Promise<{
+        success: boolean;
+        logs: unknown;
+        outputs: Array<{
+            path: string;
+        }>;
+    }>;
+};
+/**
+ * Server-side entry point for dev toolbar config, HTML injection, manifest, and runtime bundling.
+ */
+export declare class DevToolbarHost {
+    private readonly appConfig;
+    private readonly options;
+    constructor(appConfig: EcoPagesAppConfig, options: DevToolbarHostOptions);
+    static forApp(appConfig: EcoPagesAppConfig, options: DevToolbarHostOptions): DevToolbarHost;
+    isEnabled(): boolean;
+    getRuntimeScriptUrl(): string;
+    getRuntimeScriptImport(): string;
+    resolveRuntimeWorkDir(workDir: string): string;
+    shouldInjectHtml(): boolean;
+    injectHtmlResponse(response: Response): Promise<Response>;
+    buildRouteManifestContribution(input: {
+        routeFile: string;
+        integrationName: string;
+        pagePackage?: PagePackageResult;
+    }): HtmlDocumentContribution | undefined;
+    bundleClientRuntime(options: {
+        browserBundleService: DevToolbarBundleService;
+        workDir: string;
+        onFailure: (error: unknown) => void;
+    }): Promise<boolean>;
+    readBundledRuntime(workDir: string): Response | null;
+}
+export {};

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

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { removeStaleHmrEntrypointOutput } from '../hmr/hmr-entrypoint-output.js';
+import { isDevToolbarEnabled } from './dev-toolbar-config.js';
+import { resolveConfiguredDevToolbarClient } from './dev-toolbar-package.js';
+import { buildDevToolbarManifestPayload, serializeDevToolbarManifestScript } from './dev-toolbar-manifest.js';
+import { DEV_TOOLBAR_RUNTIME_IMPORT, DEV_TOOLBAR_RUNTIME_SCRIPT_URL, resolveDevToolbarRuntimeWorkDir, } from './dev-toolbar-runtime-paths.js';
+/**
+ * Server-side entry point for dev toolbar config, HTML injection, manifest, and runtime bundling.
+ */
+export class DevToolbarHost {
+    appConfig;
+    options;
+    constructor(appConfig, options) {
+        this.appConfig = appConfig;
+        this.options = options;
+    }
+    static forApp(appConfig, options) {
+        return new DevToolbarHost(appConfig, options);
+    }
+    isEnabled() {
+        return isDevToolbarEnabled(this.appConfig, this.options);
+    }
+    getRuntimeScriptUrl() {
+        return DEV_TOOLBAR_RUNTIME_SCRIPT_URL;
+    }
+    getRuntimeScriptImport() {
+        return DEV_TOOLBAR_RUNTIME_IMPORT;
+    }
+    resolveRuntimeWorkDir(workDir) {
+        return resolveDevToolbarRuntimeWorkDir(workDir);
+    }
+    shouldInjectHtml() {
+        return this.isEnabled();
+    }
+    async injectHtmlResponse(response) {
+        const html = await response.text();
+        const headers = new Headers(response.headers);
+        headers.set('Cache-Control', 'no-store, must-revalidate');
+        headers.delete('Content-Length');
+        if (html.includes(this.getRuntimeScriptImport())) {
+            return new Response(html, {
+                status: response.status,
+                statusText: response.statusText,
+                headers,
+            });
+        }
+        const script = `<script type="module">${this.getRuntimeScriptImport()};</script>`;
+        const updatedHtml = html.replace(/<\/html>/i, `${script}</html>`);
+        return new Response(updatedHtml, {
+            status: response.status,
+            statusText: response.statusText,
+            headers,
+        });
+    }
+    buildRouteManifestContribution(input) {
+        if (!this.isEnabled()) {
+            return undefined;
+        }
+        const payload = buildDevToolbarManifestPayload({
+            routeFile: input.routeFile,
+            integrationName: input.integrationName,
+            pagePackage: input.pagePackage,
+        });
+        return {
+            placement: 'body-append',
+            html: serializeDevToolbarManifestScript(payload),
+        };
+    }
+    async bundleClientRuntime(options) {
+        if (!this.isEnabled()) {
+            return true;
+        }
+        const client = resolveConfiguredDevToolbarClient(this.appConfig);
+        if (!client) {
+            options.onFailure(new Error('[DevToolbar] No client package configured. Set devToolbar.package in your app config.'));
+            return false;
+        }
+        const runtimePath = path.join(options.workDir, path.basename(DEV_TOOLBAR_RUNTIME_SCRIPT_URL));
+        removeStaleHmrEntrypointOutput(runtimePath, 'DevToolbar');
+        try {
+            const result = await options.browserBundleService.bundle({
+                profile: 'hmr-runtime',
+                entrypoints: [client.entryPath],
+                outdir: options.workDir,
+                naming: path.basename(DEV_TOOLBAR_RUNTIME_SCRIPT_URL),
+                minify: false,
+            });
+            if (!result.success) {
+                options.onFailure(result.logs);
+                return false;
+            }
+            const emittedRuntime = result.outputs.find((output) => path.resolve(output.path) === path.resolve(runtimePath));
+            if (!emittedRuntime || !fileSystem.exists(runtimePath)) {
+                options.onFailure(new Error(`[DevToolbar] Runtime bundle missing expected output at ${runtimePath}`));
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            options.onFailure(error);
+            return false;
+        }
+    }
+    readBundledRuntime(workDir) {
+        const runtimePath = path.join(workDir, path.basename(DEV_TOOLBAR_RUNTIME_SCRIPT_URL));
+        if (!fileSystem.exists(runtimePath)) {
+            return null;
+        }
+        return new Response(fileSystem.readFileAsBuffer(runtimePath), {
+            headers: {
+                'Content-Type': 'application/javascript',
+                'Cache-Control': 'no-store, must-revalidate',
+            },
+        });
+    }
+}

package/src/dev-toolbar/dev-toolbar-html-response.d.ts

@@ -0,0 +1,11 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import { type DevToolbarHostOptions } from './dev-toolbar-host.js';
+export { DEV_TOOLBAR_RUNTIME_IMPORT } from './dev-toolbar-runtime-paths.js';
+/**
+ * Returns whether HTML responses should receive the dev toolbar bootstrap.
+ */
+export declare function shouldInjectDevToolbarHtmlResponse(appConfig: EcoPagesAppConfig, options: DevToolbarHostOptions): boolean;
+/**
+ * Injects the development dev toolbar runtime script into an HTML response if it is not already present.
+ */
+export declare function injectDevToolbarIntoHtmlResponse(appConfig: EcoPagesAppConfig, options: DevToolbarHostOptions, response: Response): Promise<Response>;

package/src/dev-toolbar/dev-toolbar-html-response.js

@@ -0,0 +1,14 @@
+import { DevToolbarHost } from './dev-toolbar-host.js';
+export { DEV_TOOLBAR_RUNTIME_IMPORT } from './dev-toolbar-runtime-paths.js';
+/**
+ * Returns whether HTML responses should receive the dev toolbar bootstrap.
+ */
+export function shouldInjectDevToolbarHtmlResponse(appConfig, options) {
+    return DevToolbarHost.forApp(appConfig, options).shouldInjectHtml();
+}
+/**
+ * Injects the development dev toolbar runtime script into an HTML response if it is not already present.
+ */
+export async function injectDevToolbarIntoHtmlResponse(appConfig, options, response) {
+    return DevToolbarHost.forApp(appConfig, options).injectHtmlResponse(response);
+}

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

@@ -0,0 +1,15 @@
+import type { PagePackageResult } from '../types/public-types.js';
+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.
+ */
+export declare function buildDevToolbarManifestPayload(input: {
+    routeFile: string;
+    integrationName?: string;
+    pagePackage?: PagePackageResult;
+}): EcoDevManifest;
+/**
+ * Serializes the dev toolbar manifest as an HTML contribution snippet.
+ */
+export declare function serializeDevToolbarManifestScript(payload: EcoDevManifest): string;

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

@@ -0,0 +1,52 @@
+import { DEV_TRANSFORM_URL_PREFIX, VENDOR_URL_PREFIX } from '../hmr/hmr-asset-paths.js';
+import { DEV_MANIFEST_ELEMENT_ID, } from './dev-toolbar-manifest-contract.js';
+export { DEV_MANIFEST_ELEMENT_ID, };
+function serializeAsset(asset) {
+    if (!asset.srcUrl) {
+        return undefined;
+    }
+    return {
+        srcUrl: asset.srcUrl,
+        kind: asset.kind,
+        packageRole: asset.packageRole,
+        inline: asset.inline,
+    };
+}
+function collectUrlsFromAssets(assets, prefix) {
+    const urls = new Set();
+    for (const asset of assets) {
+        if (asset.srcUrl?.startsWith(prefix)) {
+            urls.add(asset.srcUrl);
+        }
+    }
+    return [...urls];
+}
+/**
+ * Builds the dev toolbar manifest payload for one rendered page.
+ */
+export function buildDevToolbarManifestPayload(input) {
+    const assets = input.pagePackage?.assets ?? [];
+    const graph = input.pagePackage?.pageBrowserGraph;
+    return {
+        route: input.routeFile,
+        integration: input.integrationName,
+        pageBrowserGraph: graph
+            ? {
+                entryAssets: graph.entryAssets
+                    .map((asset) => serializeAsset(asset))
+                    .filter((asset) => asset !== undefined),
+                chunkAssets: graph.chunkAssets
+                    .map((asset) => serializeAsset(asset))
+                    .filter((asset) => asset !== undefined),
+            }
+            : undefined,
+        vendorUrls: collectUrlsFromAssets(assets, VENDOR_URL_PREFIX),
+        devTransformUrls: collectUrlsFromAssets(assets, DEV_TRANSFORM_URL_PREFIX),
+    };
+}
+/**
+ * Serializes the dev toolbar manifest as an HTML contribution snippet.
+ */
+export function serializeDevToolbarManifestScript(payload) {
+    return `<script type="application/json" id="${DEV_MANIFEST_ELEMENT_ID}">${JSON.stringify(payload)}</script>`;
+}

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

@@ -0,0 +1,34 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+export type DevToolbarClientResolution = {
+    entryPath: string;
+};
+/**
+ * Returns the configured dev-toolbar client package specifier, if any.
+ */
+export declare function getDevToolbarPackageSpec(appConfig: Pick<EcoPagesAppConfig, 'devToolbar'>): string | undefined;
+/**
+ * Resolves the dev-toolbar package root from an application project directory.
+ *
+ * @remarks Walks up from the package entry rather than resolving `package.json`
+ * directly so packages with strict `exports` (no `./package.json` subpath) still work.
+ */
+export declare function resolveDevToolbarPackageRoot(rootDir: string, packageSpec: string): string;
+/**
+ * Resolves the browser entrypoint core bundles into `/_dev_toolbar.js`.
+ *
+ * @remarks Prefers `src/bootstrap.js` when present (published npm or `file:` to
+ * `dist`), then `bootstrap.ts` for workspace source checkouts.
+ */
+export declare function resolveDevToolbarClient(rootDir: string, packageSpec: string): DevToolbarClientResolution | undefined;
+/**
+ * Resolves the configured dev-toolbar client for an app config, when present.
+ */
+export declare function resolveConfiguredDevToolbarClient(appConfig: EcoPagesAppConfig): DevToolbarClientResolution | undefined;
+/**
+ * Resolves a dev-toolbar client entry module from the application project root.
+ */
+export declare function resolveDevToolbarPackageEntry(rootDir: string, packageSpec: string): string;
+/**
+ * Resolves the configured dev-toolbar entry for an app config, when present.
+ */
+export declare function resolveConfiguredDevToolbarEntry(appConfig: EcoPagesAppConfig): string | undefined;