@ecopages/react 0.2.0-alpha.9 → 0.2.1-beta.0

package/src/react.constants.d.ts

@@ -0,0 +1 @@
+export declare const REACT_PLUGIN_NAME = "react";

package/src/react.constants.js

@@ -0,0 +1,4 @@
+const REACT_PLUGIN_NAME = "react";
+export {
+  REACT_PLUGIN_NAME
+};

package/src/react.plugin.d.ts

@@ -1,93 +1,10 @@
-/**
- * This module contains the react plugin for Ecopages
- * @module
- */
-import { IntegrationPlugin } from '@ecopages/core/plugins/integration-plugin';
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
 import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
-import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
-import type { CompileOptions } from '@mdx-js/mdx';
 import type React from 'react';
 import { ReactRenderer } from './react-renderer.js';
-import type { ReactRouterAdapter } from './router-adapter.js';
-import type { ComponentBoundaryPolicyInput } from '@ecopages/core/plugins/integration-plugin';
-/**
- * MDX configuration options for the React plugin
- */
-export type ReactMdxOptions = {
-    /**
-     * Whether to enable MDX support.
-     * @default false
-     */
-    enabled: boolean;
-    /**
-     * Compiler options for MDX.
-     * @default undefined
-     */
-    compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
-    /**
-     * Remark plugins.
-     * @default undefined
-     */
-    remarkPlugins?: CompileOptions['remarkPlugins'];
-    /**
-     * Rehype plugins.
-     * @default undefined
-     */
-    rehypePlugins?: CompileOptions['rehypePlugins'];
-    /**
-     * Recma plugins.
-     * @default undefined
-     */
-    recmaPlugins?: CompileOptions['recmaPlugins'];
-    /**
-     * Custom extensions to be treated as MDX files.
-     * @default ['.mdx']
-     */
-    extensions?: string[];
-};
-/**
- * Options for the React plugin
- */
-export type ReactPluginOptions = {
-    extensions?: string[];
-    dependencies?: AssetDefinition[];
-    /**
-     * Enables explicit client graph mode for React page entries.
-     *
-     * When enabled, React page-entry bundling relies on explicit dependency declarations
-     * and skips AST-based `middleware`/`requires` stripping in the React path.
-     * @default false
-     */
-    explicitGraph?: boolean;
-    /**
-     * Router adapter for SPA navigation.
-     * When provided, pages with layouts will be wrapped in the router for client-side navigation.
-     * @example
-     * ```ts
-     * import { ecoRouter } from '@ecopages/react-router';
-     * reactPlugin({ router: ecoRouter() })
-     * ```
-     */
-    router?: ReactRouterAdapter;
-    /**
-     * MDX configuration for handling .mdx files within the React plugin.
-     * When enabled, MDX files are treated as React pages with full router support.
-     * @example
-     * ```ts
-     * reactPlugin({
-     *   router: ecoRouter(),
-     *   mdx: {
-     *     enabled: true,
-     *     extensions: ['.mdx', '.md'],
-     *     remarkPlugins: [remarkGfm],
-     *     rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
-     *   }
-     * })
-     * ```
-     */
-    mdx?: ReactMdxOptions;
-};
+import type { ReactPluginOptions } from './react.types.js';
+export type { ReactMdxOptions, ReactPluginOptions, ReactRendererConfig } from './react.types.js';
 /**
  * The name of the React plugin
  */
@@ -96,23 +13,36 @@ export declare const PLUGIN_NAME = "react";
  * The React plugin class
  * This plugin provides support for React components in Ecopages
  */
-export declare class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
+export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
     renderer: typeof ReactRenderer;
-    routerAdapter: ReactRouterAdapter | undefined;
-    private mdxEnabled;
-    private mdxCompilerOptions?;
-    private mdxExtensions;
+    private readonly routerAdapter;
+    private readonly mdxEnabled;
+    private readonly mdxCompilerOptions?;
+    private readonly mdxExtensions;
     private mdxLoaderPlugin;
-    private runtimeBundleService;
+    private readonly runtimeBundleService;
     private readonly hmrPageMetadataCache;
+    private readonly clientGraphBoundaryCache;
     private runtimeDependenciesInitialized;
     /**
      * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
      */
-    private explicitGraphEnabled;
-    constructor(options?: Omit<ReactPluginOptions, 'name'>);
+    private readonly explicitGraphEnabled;
+    private readonly rendererConfig;
+    constructor(options?: ReactPluginOptions);
+    /**
+     * Creates a React renderer with instance-owned runtime configuration.
+     *
+     * React renderers depend on plugin-owned router, MDX, and HMR metadata state.
+     * Keeping that state on the instance avoids cross-plugin static mutation while
+     * preserving the same runtime services the base initializer wires up.
+     */
+    initializeRenderer(options?: {
+        rendererModules?: unknown;
+    }): ReactRenderer;
     private ensureRuntimeDependencies;
     get plugins(): EcoBuildPlugin[];
+    get browserRuntimeManifest(): BrowserRuntimeManifest;
     /**
      * Ensures the optional React MDX loader exists before either config-time
      * manifest sealing or runtime setup needs it.
@@ -138,18 +68,6 @@ export declare class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
      * @returns ReactHmrStrategy instance for handling React component updates
      */
     getHmrStrategy(): HmrStrategy | undefined;
-    getRuntimeSpecifierMap(): Record<string, string>;
-    /**
-     * Declares React's boundary deferral rule for cross-integration rendering.
-     *
-     * React defers when a render pass owned by another integration enters a React
-     * component boundary. That boundary is then resolved later through the marker
-     * graph stage using the React renderer.
-     *
-     * @param input Boundary metadata for the active render pass.
-     * @returns `true` when the boundary should be deferred into the marker pass.
-     */
-    shouldDeferComponentBoundary(input: ComponentBoundaryPolicyInput): boolean;
 }
 /**
  * Factory function to create a React plugin instance

package/src/react.plugin.js

@@ -1,11 +1,69 @@
-import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
+import {
+  IntegrationPlugin
+} from "@ecopages/core/plugins/integration-plugin";
 import { Logger } from "@ecopages/logger";
+import { REACT_PLUGIN_NAME } from "./react.constants.js";
 import { ReactRenderer } from "./react-renderer.js";
 import { ReactHmrStrategy } from "./react-hmr-strategy.js";
 import { ReactRuntimeBundleService } from "./services/react-runtime-bundle.service.js";
 import { ReactHmrPageMetadataCache } from "./services/react-hmr-page-metadata-cache.js";
+import { createReactMdxLoaderPlugin } from "./utils/react-mdx-loader-plugin.js";
+import { ClientGraphBoundaryCache } from "./utils/client-graph-boundary-cache.js";
 const appLogger = new Logger("[ReactPlugin]");
-const PLUGIN_NAME = "react";
+const PLUGIN_NAME = REACT_PLUGIN_NAME;
+const mergePluginLists = (...lists) => {
+  const merged = lists.flatMap((list) => list ? [...list] : []);
+  return merged.length > 0 ? merged : void 0;
+};
+const appendMdxExtensions = (target, mdxExtensions) => {
+  for (const extension of mdxExtensions) {
+    if (!target.includes(extension)) {
+      target.push(extension);
+    }
+  }
+};
+const resolveReactMdxCompilerOptions = (mdxOptions) => {
+  const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = mdxOptions;
+  const resolved = {
+    ...compilerOptions,
+    jsxImportSource: "react",
+    jsxRuntime: "automatic",
+    development: process.env.NODE_ENV === "development"
+  };
+  const mergedRemark = mergePluginLists(compilerOptions?.remarkPlugins, remarkPlugins);
+  const mergedRehype = mergePluginLists(compilerOptions?.rehypePlugins, rehypePlugins);
+  const mergedRecma = mergePluginLists(compilerOptions?.recmaPlugins, recmaPlugins);
+  if (mergedRemark) resolved.remarkPlugins = mergedRemark;
+  if (mergedRehype) resolved.rehypePlugins = mergedRehype;
+  if (mergedRecma) resolved.recmaPlugins = mergedRecma;
+  return resolved;
+};
+const resolveReactPluginOptions = (options) => {
+  const { extensions: userExtensions, router, mdx, explicitGraph, dependencies, ...baseConfig } = options ?? {};
+  const extensions = [...userExtensions ?? [".tsx"]];
+  const mdxEnabled = mdx?.enabled ?? false;
+  const mdxExtensions = mdx?.extensions ?? [".mdx"];
+  if (mdxEnabled) {
+    appendMdxExtensions(extensions, mdxExtensions);
+  } else if (mdx?.extensions?.length) {
+    appLogger.warn(
+      "MDX extensions provided but MDX is disabled. MDX files will not be processed. Set mdx.enabled to true to enable MDX support."
+    );
+  }
+  const rendererConfig = {
+    routerAdapter: router,
+    mdxCompilerOptions: mdxEnabled && mdx ? resolveReactMdxCompilerOptions(mdx) : void 0,
+    mdxExtensions,
+    hmrPageMetadataCache: new ReactHmrPageMetadataCache(),
+    explicitGraphEnabled: explicitGraph ?? false
+  };
+  return {
+    ...baseConfig,
+    extensions,
+    integrationDependencies: dependencies,
+    rendererConfig
+  };
+};
 class ReactPlugin extends IntegrationPlugin {
   renderer = ReactRenderer;
   routerAdapter;
@@ -14,62 +72,63 @@ class ReactPlugin extends IntegrationPlugin {
   mdxExtensions;
   mdxLoaderPlugin;
   runtimeBundleService;
-  hmrPageMetadataCache = new ReactHmrPageMetadataCache();
+  hmrPageMetadataCache;
+  clientGraphBoundaryCache;
   runtimeDependenciesInitialized = false;
   /**
    * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
    */
   explicitGraphEnabled;
+  rendererConfig;
   constructor(options) {
-    const { extensions: _ignoredExtensions, ...restOptions } = options ?? {};
-    const extensions = [...options?.extensions ?? [".tsx"]];
-    const mdxExtensions = options?.mdx?.extensions ?? [".mdx"];
-    if (options?.mdx?.enabled) {
-      for (const extension of mdxExtensions) {
-        if (!extensions.includes(extension)) {
-          extensions.push(extension);
-        }
-      }
-    } else if (options?.mdx?.extensions?.length) {
-      appLogger.warn(
-        "MDX extensions provided but MDX is disabled. MDX files will not be processed. Set mdx.enabled to true to enable MDX support."
-      );
-    }
+    const config = resolveReactPluginOptions(options);
+    const { extensions, rendererConfig, integrationDependencies, ...baseConfig } = config;
     super({
       name: PLUGIN_NAME,
       extensions,
-      ...restOptions
+      jsxImportSource: "react",
+      integrationDependencies,
+      ...baseConfig
     });
-    this.mdxEnabled = options?.mdx?.enabled ?? false;
-    this.mdxExtensions = mdxExtensions;
+    this.routerAdapter = rendererConfig.routerAdapter;
+    this.mdxCompilerOptions = rendererConfig.mdxCompilerOptions;
+    this.mdxEnabled = Boolean(rendererConfig.mdxCompilerOptions);
+    this.mdxExtensions = rendererConfig.mdxExtensions ?? [".mdx"];
+    this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new ReactHmrPageMetadataCache();
+    this.clientGraphBoundaryCache = new ClientGraphBoundaryCache();
+    this.explicitGraphEnabled = rendererConfig.explicitGraphEnabled ?? false;
+    this.rendererConfig = {
+      ...rendererConfig,
+      mdxExtensions: this.mdxExtensions,
+      hmrPageMetadataCache: this.hmrPageMetadataCache,
+      explicitGraphEnabled: this.explicitGraphEnabled
+    };
     if (this.mdxEnabled) {
-      const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = options?.mdx || {};
-      this.mdxCompilerOptions = {
-        ...compilerOptions,
-        remarkPlugins: [...compilerOptions?.remarkPlugins || [], ...remarkPlugins || []],
-        rehypePlugins: [...compilerOptions?.rehypePlugins || [], ...rehypePlugins || []],
-        recmaPlugins: [...compilerOptions?.recmaPlugins || [], ...recmaPlugins || []],
-        jsxImportSource: "react",
-        jsxRuntime: "automatic",
-        development: process.env.NODE_ENV === "development"
-      };
       appLogger.debug("MDX mode enabled with React jsx runtime");
     }
-    this.routerAdapter = options?.router;
     this.runtimeBundleService = new ReactRuntimeBundleService({
       routerAdapter: this.routerAdapter
     });
-    this.explicitGraphEnabled = options?.explicitGraph ?? false;
-    ReactRenderer.routerAdapter = this.routerAdapter;
-    ReactRenderer.mdxCompilerOptions = this.mdxCompilerOptions;
-    ReactRenderer.mdxExtensions = this.mdxExtensions;
-    ReactRenderer.explicitGraphEnabled = this.explicitGraphEnabled;
-    ReactRenderer.hmrPageMetadataCache = this.hmrPageMetadataCache;
+  }
+  /**
+   * Creates a React renderer with instance-owned runtime configuration.
+   *
+   * React renderers depend on plugin-owned router, MDX, and HMR metadata state.
+   * Keeping that state on the instance avoids cross-plugin static mutation while
+   * preserving the same runtime services the base initializer wires up.
+   */
+  initializeRenderer(options) {
+    const renderer = new this.renderer({
+      ...this.createRendererOptions(options),
+      reactConfig: this.rendererConfig
+    });
+    return this.attachRendererRuntimeServices(renderer);
   }
   ensureRuntimeDependencies() {
     if (this.runtimeDependenciesInitialized) {
       return;
     }
+    this.runtimeBundleService.setRootDir(this.appConfig?.rootDir);
     this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
     this.runtimeDependenciesInitialized = true;
   }
@@ -79,6 +138,10 @@ class ReactPlugin extends IntegrationPlugin {
     }
     return [];
   }
+  get browserRuntimeManifest() {
+    this.ensureRuntimeDependencies();
+    return this.runtimeBundleService.getRuntimeManifest();
+  }
   /**
    * Ensures the optional React MDX loader exists before either config-time
    * manifest sealing or runtime setup needs it.
@@ -87,7 +150,6 @@ class ReactPlugin extends IntegrationPlugin {
     if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
       return;
     }
-    const { createReactMdxLoaderPlugin } = await import("./utils/react-mdx-loader-plugin.js");
     this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
   }
   /**
@@ -121,30 +183,16 @@ class ReactPlugin extends IntegrationPlugin {
       return void 0;
     }
     const context = this.hmrManager.getDefaultContext();
-    return new ReactHmrStrategy(
+    return new ReactHmrStrategy({
       context,
-      this.hmrPageMetadataCache,
-      this.mdxCompilerOptions,
-      this.extensions,
-      this.appConfig.templatesExt,
-      this.explicitGraphEnabled
-    );
-  }
-  getRuntimeSpecifierMap() {
-    return this.runtimeBundleService.getSpecifierMap();
-  }
-  /**
-   * Declares React's boundary deferral rule for cross-integration rendering.
-   *
-   * React defers when a render pass owned by another integration enters a React
-   * component boundary. That boundary is then resolved later through the marker
-   * graph stage using the React renderer.
-   *
-   * @param input Boundary metadata for the active render pass.
-   * @returns `true` when the boundary should be deferred into the marker pass.
-   */
-  shouldDeferComponentBoundary(input) {
-    return input.targetIntegration === this.name && input.currentIntegration !== this.name;
+      pageMetadataCache: this.hmrPageMetadataCache,
+      runtimeManifest: this.runtimeBundleService.getRuntimeManifest("development"),
+      mdxCompilerOptions: this.mdxCompilerOptions,
+      ownedTemplateExtensions: this.extensions,
+      allTemplateExtensions: this.appConfig.templatesExt,
+      explicitGraphEnabled: this.explicitGraphEnabled,
+      clientGraphBoundaryCache: this.clientGraphBoundaryCache
+    });
   }
 }
 function reactPlugin(options) {

package/src/react.types.d.ts

@@ -0,0 +1,88 @@
+import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+import type { CompileOptions } from '@mdx-js/mdx';
+import type { ReactRouterAdapter } from './router-adapter.js';
+import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
+/**
+ * MDX configuration options for the React plugin.
+ */
+export type ReactMdxOptions = {
+    /**
+     * Whether to enable MDX support.
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Compiler options for MDX.
+     * @default undefined
+     */
+    compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
+    /**
+     * Remark plugins.
+     * @default undefined
+     */
+    remarkPlugins?: CompileOptions['remarkPlugins'];
+    /**
+     * Rehype plugins.
+     * @default undefined
+     */
+    rehypePlugins?: CompileOptions['rehypePlugins'];
+    /**
+     * Recma plugins.
+     * @default undefined
+     */
+    recmaPlugins?: CompileOptions['recmaPlugins'];
+    /**
+     * Custom extensions to be treated as MDX files.
+     * @default ['.mdx']
+     */
+    extensions?: string[];
+};
+/**
+ * Options for the React plugin.
+ */
+export type ReactPluginOptions = {
+    extensions?: string[];
+    dependencies?: AssetDefinition[];
+    /**
+     * Enables explicit client graph mode for React page entries.
+     *
+     * When enabled, React page-entry bundling relies on explicit dependency declarations
+     * and skips AST-based `middleware`/`requires` stripping in the React path.
+     * @default false
+     */
+    explicitGraph?: boolean;
+    /**
+     * Router adapter for SPA navigation.
+     * When provided, pages with layouts will be wrapped in the router for client-side navigation.
+     * @example
+     * ```ts
+     * import { ecoRouter } from '@ecopages/react-router';
+     * reactPlugin({ router: ecoRouter() })
+     * ```
+     */
+    router?: ReactRouterAdapter;
+    /**
+     * MDX configuration for handling .mdx files within the React plugin.
+     * When enabled, MDX files are treated as React pages with full router support.
+     * @example
+     * ```ts
+     * reactPlugin({
+     *   router: ecoRouter(),
+     *   mdx: {
+     *     enabled: true,
+     *     extensions: ['.mdx', '.md'],
+     *     remarkPlugins: [remarkGfm],
+     *     rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
+     *   }
+     * })
+     * ```
+     */
+    mdx?: ReactMdxOptions;
+};
+export type ReactRendererConfig = {
+    routerAdapter?: ReactRouterAdapter;
+    mdxCompilerOptions?: CompileOptions;
+    mdxExtensions?: string[];
+    hmrPageMetadataCache?: ReactHmrPageMetadataCache;
+    explicitGraphEnabled?: boolean;
+};

package/src/router-adapter.d.ts

@@ -12,11 +12,10 @@
  * const myRouter: ReactRouterAdapter = {
  *   name: 'my-router',
  *   bundle: {
- *     importPath: '@my/router/browser.ts',
+ *     importPath: '@my/router/browser',
  *     outputName: 'my-router',
  *     externals: ['react', 'react-dom'],
  *   },
- *   importMapKey: '@my/router',
  *   components: {
  *     router: 'MyRouter',
  *     pageContent: 'PageOutlet',
@@ -36,39 +35,33 @@ export interface ReactRouterAdapter {
     bundle: {
         /**
          * Node module import path for the browser-compatible entry.
-         * @example '@ecopages/react-router/browser.ts'
+         * @example '@ecopages/react-router/browser'
          */
         importPath: string;
         /**
          * Output filename (without extension).
-         * @example 'react-router-esm'
+         * @example 'my-router'
          */
         outputName: string;
         /**
          * Packages to externalize when bundling.
-         * These should be available through the runtime bare-specifier map.
-         * @example ['react', 'react-dom', 'react/jsx-runtime']
+         * These should stay as bare runtime dependencies for the router bundle.
+         * @example ['react', 'react-dom']
          */
         externals: string[];
     };
-    /**
-     * Bare specifier for the runtime mapping entry.
-     * This is what the hydration script will import from.
-     * @example '@ecopages/react-router'
-     */
-    importMapKey: string;
     /**
      * Component names to import from the router package.
      */
     components: {
         /**
          * The router component that wraps the layout.
-         * @example 'EcoRouter'
+         * @example 'MyRouter'
          */
         router: string;
         /**
          * The component that renders the current page content.
-         * @example 'PageContent'
+         * @example 'PageOutlet'
          */
         pageContent: string;
     };

package/src/runtime/use-sync-external-store-with-selector.d.ts

@@ -0,0 +1,3 @@
+type Subscribe = (onStoreChange: () => void) => () => void;
+export declare function useSyncExternalStoreWithSelector<Snapshot, Selection>(subscribe: Subscribe, getSnapshot: () => Snapshot, getServerSnapshot: (() => Snapshot) | undefined, selector: (snapshot: Snapshot) => Selection, isEqual?: (left: Selection, right: Selection) => boolean): Selection;
+export {};

package/src/runtime/use-sync-external-store-with-selector.js

@@ -0,0 +1,56 @@
+import { useDebugValue, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+const objectIs = Object.is;
+function useSyncExternalStoreWithSelector(subscribe, getSnapshot, getServerSnapshot, selector, isEqual) {
+  const instRef = useRef({ hasValue: false, value: void 0 });
+  const memoizedSelectionRef = useMemo(() => {
+    let hasMemo = false;
+    let memoizedSnapshot;
+    let memoizedSelection;
+    const maybeGetServerSnapshot = getServerSnapshot === void 0 ? null : getServerSnapshot;
+    const memoizedSelector = (nextSnapshot) => {
+      if (!hasMemo) {
+        hasMemo = true;
+        memoizedSnapshot = nextSnapshot;
+        const nextSelection2 = selector(nextSnapshot);
+        const inst = instRef.current;
+        if (isEqual !== void 0 && inst.hasValue) {
+          const currentSelection2 = inst.value;
+          if (isEqual(currentSelection2, nextSelection2)) {
+            memoizedSelection = currentSelection2;
+            return currentSelection2;
+          }
+        }
+        memoizedSelection = nextSelection2;
+        return nextSelection2;
+      }
+      const currentSelection = memoizedSelection;
+      if (objectIs(memoizedSnapshot, nextSnapshot)) {
+        return currentSelection;
+      }
+      const nextSelection = selector(nextSnapshot);
+      if (isEqual !== void 0 && isEqual(currentSelection, nextSelection)) {
+        memoizedSnapshot = nextSnapshot;
+        return currentSelection;
+      }
+      memoizedSnapshot = nextSnapshot;
+      memoizedSelection = nextSelection;
+      return nextSelection;
+    };
+    return [
+      () => memoizedSelector(getSnapshot()),
+      maybeGetServerSnapshot === null ? void 0 : () => memoizedSelector(maybeGetServerSnapshot())
+    ];
+  }, [getSnapshot, getServerSnapshot, selector, isEqual]);
+  const value = useSyncExternalStore(subscribe, memoizedSelectionRef[0], memoizedSelectionRef[1]);
+  useEffect(() => {
+    instRef.current = {
+      hasValue: true,
+      value
+    };
+  }, [value]);
+  useDebugValue(value);
+  return value;
+}
+export {
+  useSyncExternalStoreWithSelector
+};

package/src/services/pages-index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Per-app index of React-owned page entrypoints.
+ *
+ * @remarks
+ * The HMR strategy previously called `fileSystem.glob` on every
+ * layout change. For apps with many pages this is wasteful: O(pages)
+ * on every HMR event, and the result rarely changes between HMR
+ * rebuilds.
+ *
+ * `PagesIndex` maintains a `Set` of owned page entrypoint paths. The
+ * initial population is a single glob; subsequent mutations go through
+ * `add` / `remove` (called by the HMR strategy when it observes a
+ * file create/delete under `pagesDir`). The strategy reads via
+ * `list()` for an O(1) snapshot of the current set.
+ *
+ * Phase 1 ships the class and the `list()` consumer. Watcher-driven
+ * `add` / `remove` integration lands in a follow-up — for now the
+ * strategy calls `refresh()` lazily, which is equivalent to the old
+ * glob behavior but with a stable API for the future incremental
+ * path.
+ */
+export type PagesIndexOptions = {
+    pagesDir: string;
+    extensions?: string[];
+    /**
+     * Optional predicate to filter out non-page entrypoints (e.g.
+     * test fixtures, generated files). Defaults to including every
+     * file matching an extension.
+     */
+    isPageEntrypoint?: (absolutePath: string) => boolean;
+};
+export declare class PagesIndex {
+    private readonly pagesDir;
+    private readonly extensions;
+    private readonly isPageEntrypoint;
+    private readonly pages;
+    private lastRefreshAt;
+    constructor(options: PagesIndexOptions);
+    /**
+     * Rescan the pages directory and rebuild the index.
+     *
+     * Cheap to call multiple times in sequence (just a glob). The
+     * real value of `PagesIndex` is the `add` / `remove` path that
+     * callers can wire to the file watcher; for now this is the
+     * fallback used on layout changes.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Add a single entrypoint. Idempotent.
+     */
+    add(absolutePath: string): void;
+    /**
+     * Remove a single entrypoint. Idempotent.
+     */
+    remove(absolutePath: string): void;
+    /** True if the index contains `absolutePath`. */
+    has(absolutePath: string): boolean;
+    /** Snapshot of the current set, sorted by absolute path. */
+    list(): string[];
+    /** Number of indexed entrypoints. */
+    get size(): number;
+    /** Last refresh timestamp (ms since epoch). */
+    get refreshedAt(): number;
+}