@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

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;

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

@@ -0,0 +1,78 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+const SOURCE_CLIENT_FILE = 'src/bootstrap.ts';
+const COMPILED_CLIENT_FILE = 'src/bootstrap.js';
+/**
+ * Returns the configured dev-toolbar client package specifier, if any.
+ */
+export function getDevToolbarPackageSpec(appConfig) {
+    const spec = appConfig.devToolbar?.package?.trim();
+    return spec || 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 function resolveDevToolbarPackageRoot(rootDir, packageSpec) {
+    const require = createRequire(path.join(rootDir, 'package.json'));
+    let dir = path.dirname(require.resolve(packageSpec));
+    while (dir !== path.dirname(dir)) {
+        if (fileSystem.exists(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    throw new Error(`Could not resolve package root for ${packageSpec}`);
+}
+/**
+ * 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 function resolveDevToolbarClient(rootDir, packageSpec) {
+    const require = createRequire(path.join(rootDir, 'package.json'));
+    const packageRoot = resolveDevToolbarPackageRoot(rootDir, packageSpec);
+    const entryCandidates = [path.join(packageRoot, COMPILED_CLIENT_FILE), path.join(packageRoot, SOURCE_CLIENT_FILE)];
+    for (const entryPath of entryCandidates) {
+        if (fileSystem.exists(entryPath)) {
+            return { entryPath };
+        }
+    }
+    try {
+        return { entryPath: require.resolve(packageSpec) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves the configured dev-toolbar client for an app config, when present.
+ */
+export function resolveConfiguredDevToolbarClient(appConfig) {
+    const packageSpec = getDevToolbarPackageSpec(appConfig);
+    if (!packageSpec) {
+        return undefined;
+    }
+    return resolveDevToolbarClient(appConfig.absolutePaths.projectDir, packageSpec);
+}
+/**
+ * Resolves a dev-toolbar client entry module from the application project root.
+ */
+export function resolveDevToolbarPackageEntry(rootDir, packageSpec) {
+    const client = resolveDevToolbarClient(rootDir, packageSpec);
+    if (!client) {
+        const require = createRequire(path.join(rootDir, 'package.json'));
+        return require.resolve(packageSpec);
+    }
+    return client.entryPath;
+}
+/**
+ * Resolves the configured dev-toolbar entry for an app config, when present.
+ */
+export function resolveConfiguredDevToolbarEntry(appConfig) {
+    return resolveConfiguredDevToolbarClient(appConfig)?.entryPath;
+}

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

@@ -0,0 +1,10 @@
+/** On-disk work directory segment for the bundled dev toolbar client runtime. */
+export declare const DEV_TOOLBAR_RUNTIME_WORK_DIR_SEGMENT = "dev-toolbar-runtime";
+/** Browser URL for the bundled dev toolbar client runtime script. */
+export declare const DEV_TOOLBAR_RUNTIME_SCRIPT_URL = "/_dev_toolbar.js";
+/** Module import emitted into dev HTML responses. */
+export declare const DEV_TOOLBAR_RUNTIME_IMPORT = "import '/_dev_toolbar.js'";
+/**
+ * Absolute work-directory path for dev toolbar runtime artifacts under an app work dir.
+ */
+export declare function resolveDevToolbarRuntimeWorkDir(workDir: string): string;

package/src/dev-toolbar/dev-toolbar-runtime-paths.js

@@ -0,0 +1,13 @@
+import { RESOLVED_ASSETS_DIR } from '../config/constants.js';
+/** On-disk work directory segment for the bundled dev toolbar client runtime. */
+export const DEV_TOOLBAR_RUNTIME_WORK_DIR_SEGMENT = 'dev-toolbar-runtime';
+/** Browser URL for the bundled dev toolbar client runtime script. */
+export const DEV_TOOLBAR_RUNTIME_SCRIPT_URL = '/_dev_toolbar.js';
+/** Module import emitted into dev HTML responses. */
+export const DEV_TOOLBAR_RUNTIME_IMPORT = `import '${DEV_TOOLBAR_RUNTIME_SCRIPT_URL}'`;
+/**
+ * Absolute work-directory path for dev toolbar runtime artifacts under an app work dir.
+ */
+export function resolveDevToolbarRuntimeWorkDir(workDir) {
+    return `${workDir}/${RESOLVED_ASSETS_DIR}/${DEV_TOOLBAR_RUNTIME_WORK_DIR_SEGMENT}`;
+}

package/src/diagnostics/request-build-dedupe.d.ts

@@ -0,0 +1,18 @@
+import type { BuildResult } from '../build/build-adapter.js';
+/**
+ * Per-request browser build dedupe cache.
+ *
+ * @remarks
+ * `DedupingBuildExecutor` only coalesces concurrent identical builds. Asset
+ * processing can call the same logical bundle several times in one request
+ * (page graph, HMR, content scripts) after the first build settles. This cache
+ * reuses the settled result until the request scope ends.
+ */
+declare class RequestBuildDedupe {
+    private readonly storage;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    dedupeBuild(key: string, build: () => Promise<BuildResult>): Promise<BuildResult>;
+    getCachedCountForTests(): number;
+}
+export declare const requestBuildDedupe: RequestBuildDedupe;
+export {};

package/src/diagnostics/request-build-dedupe.js

@@ -0,0 +1,39 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Per-request browser build dedupe cache.
+ *
+ * @remarks
+ * `DedupingBuildExecutor` only coalesces concurrent identical builds. Asset
+ * processing can call the same logical bundle several times in one request
+ * (page graph, HMR, content scripts) after the first build settles. This cache
+ * reuses the settled result until the request scope ends.
+ */
+class RequestBuildDedupe {
+    storage = new AsyncLocalStorage();
+    run(fn) {
+        if (this.storage.getStore()) {
+            return fn();
+        }
+        return this.storage.run(new Map(), fn);
+    }
+    dedupeBuild(key, build) {
+        const store = this.storage.getStore();
+        if (!store) {
+            return build();
+        }
+        const existing = store.get(key);
+        if (existing) {
+            return existing;
+        }
+        const buildPromise = build().catch((error) => {
+            store.delete(key);
+            throw error;
+        });
+        store.set(key, buildPromise);
+        return buildPromise;
+    }
+    getCachedCountForTests() {
+        return this.storage.getStore()?.size ?? 0;
+    }
+}
+export const requestBuildDedupe = new RequestBuildDedupe();