@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.33

package/src/plugins/eco-component-meta-plugin.js

@@ -1,172 +1,414 @@
-import { cachedParseSync } from "../cache/module-parse-cache.js";
-import { prependJsxImportSourceIfMissing } from "./jsx-import-source.utils.js";
-import { rapidhash } from "../utils/hash.js";
-import {
-  createEcoBuildPluginFromSourceTransform,
-  createVitePluginFromSourceTransform
-} from "./source-transform.js";
+/**
+ * Bun plugin that auto-injects `__eco` metadata into EcoComponent config objects.
+ *
+ * This plugin uses AST parsing (via oxc-parser) to reliably inject the `__eco` property
+ * into EcoComponent config objects at import time. The injected metadata contains:
+ * - `dir`: The directory path of the component file (used for dependency resolution)
+ * - `integration`: The integration type (e.g., 'react', 'kitajs', 'ghtml', 'lit')
+ *
+ * The plugin intercepts file loading for all configured integration extensions and
+ * transforms component configs before they are executed.
+ *
+ * @example
+ * ```typescript
+ * // Before transformation:
+ * export default eco.page({
+ *   render: () => '<div>Hello</div>',
+ * });
+ *
+ * // After transformation:
+ * export default eco.page({
+ *   __eco: { id: "<hash>", file: "/path/to/pages/index.tsx", integration: "react" },
+ *   render: () => '<div>Hello</div>',
+ * });
+ * ```
+ *
+ * @module eco-component-meta-plugin
+ */
+import { cachedParseSync } from '../cache/module-parse-cache.js';
+import { prependJsxImportSourceIfMissing } from './jsx-import-source.utils.js';
+import { rapidhash } from '../utils/hash.js';
+import { createEcoBuildPluginFromSourceTransform, createVitePluginFromSourceTransform, } from './source-transform.js';
+/**
+ * Pattern to match regex special characters that need escaping.
+ * Used when building the file extension filter pattern.
+ */
 const REGEX_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
-const VALID_LOADER_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
+/**
+ * Set of valid Bun loader extensions.
+ * Only files with these base extensions can be processed by Bun's loader system.
+ */
+const VALID_LOADER_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx']);
+/**
+ * Checks if an extension can be handled by a valid Bun loader.
+ *
+ * Compound extensions like `.kita.tsx` are valid because the final
+ * extension is `.tsx`, which Bun can process.
+ *
+ * @param ext - The file extension to check (e.g., '.tsx', '.kita.tsx')
+ * @returns `true` if the extension ends with a valid loader extension
+ */
 function hasValidLoaderExtension(ext) {
-  for (const validExt of VALID_LOADER_EXTENSIONS) {
-    if (ext.endsWith(validExt)) {
-      return true;
+    for (const validExt of VALID_LOADER_EXTENSIONS) {
+        if (ext.endsWith(validExt)) {
+            return true;
+        }
     }
-  }
-  return false;
+    return false;
 }
 function buildExtensionToIntegrationMap(integrations) {
-  const mapping = [];
-  for (const integration of integrations) {
-    for (const ext of integration.extensions) {
-      mapping.push([
-        ext,
-        {
-          name: integration.name,
-          jsxImportSource: integration.jsxImportSource
+    const mapping = [];
+    for (const integration of integrations) {
+        for (const ext of integration.extensions) {
+            mapping.push([
+                ext,
+                {
+                    name: integration.name,
+                    jsxImportSource: integration.jsxImportSource,
+                },
+            ]);
         }
-      ]);
     }
-  }
-  mapping.sort((a, b) => b[0].length - a[0].length);
-  return mapping;
+    mapping.sort((a, b) => b[0].length - a[0].length);
+    return mapping;
 }
+/**
+ * Detects the integration type for a file based on its extension.
+ *
+ * Uses the pre-sorted extension-to-integration map to find the most
+ * specific matching extension.
+ *
+ * @param filePath - Absolute path to the file
+ * @param extensionToIntegration - Pre-built extension mapping from buildExtensionToIntegrationMap
+ * @returns The integration identifier (e.g., 'react', 'kitajs', 'lit', 'ghtml')
+ */
 function detectIntegration(filePath, extensionToIntegration) {
-  for (const [ext, integration] of extensionToIntegration) {
-    if (filePath.endsWith(ext)) {
-      return integration;
+    for (const [ext, integration] of extensionToIntegration) {
+        if (filePath.endsWith(ext)) {
+            return integration;
+        }
     }
-  }
-  return { name: "ghtml" };
+    return { name: 'ghtml' };
 }
+/**
+ * Creates a RegExp pattern that matches files with any of the configured extensions.
+ *
+ * The pattern also matches optional query strings (e.g., `file.tsx?update=123`)
+ * which are used for cache-busting in development mode.
+ *
+ * @param extensions - Array of file extensions to match
+ * @returns RegExp pattern for use with Bun's onLoad filter
+ * @throws Error if no extensions are provided
+ *
+ * @example
+ * ```typescript
+ * const pattern = createExtensionPattern(['.tsx', '.kita.tsx']);
+ * pattern.test('component.tsx');           // true
+ * pattern.test('component.tsx?v=123');     // true
+ * pattern.test('component.ts');            // false
+ * ```
+ */
 function createExtensionPattern(extensions) {
-  if (extensions.length === 0) {
-    throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
-  }
-  const uniqueExtensions = [...new Set(extensions)];
-  const escaped = uniqueExtensions.map((ext) => ext.replace(REGEX_SPECIAL_CHARS, "\\$&"));
-  return new RegExp(`(${escaped.join("|")})(\\?.*)?$`);
+    if (extensions.length === 0) {
+        throw new Error('[eco-component-meta-plugin] No extensions configured. At least one integration is required.');
+    }
+    const uniqueExtensions = [...new Set(extensions)];
+    const escaped = uniqueExtensions.map((ext) => ext.replace(REGEX_SPECIAL_CHARS, '\\$&'));
+    return new RegExp(`(${escaped.join('|')})(\\?.*)?$`);
 }
-function createEcoComponentMetaTransform(options) {
-  const allExtensions = options.config.integrations.flatMap((integration) => integration.extensions).filter(hasValidLoaderExtension);
-  if (allExtensions.length === 0) {
-    throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
-  }
-  const extensionPattern = createExtensionPattern(allExtensions);
-  const extensionToIntegration = buildExtensionToIntegrationMap(options.config.integrations);
-  return {
-    name: "eco-component-meta-plugin",
-    enforce: "pre",
-    filter: extensionPattern,
-    transform(code, id) {
-      const integration = detectIntegration(id, extensionToIntegration);
-      return {
-        code: prependJsxImportSourceIfMissing(
-          injectEcoMeta(code, id, integration.name),
-          integration.jsxImportSource
-        )
-      };
+/**
+ * Creates the bundler-neutral metadata transform used by Ecopages loaders and
+ * Vite-compatible adapters.
+ */
+export function createEcoComponentMetaTransform(options) {
+    const allExtensions = options.config.integrations
+        .flatMap((integration) => integration.extensions)
+        .filter(hasValidLoaderExtension);
+    if (allExtensions.length === 0) {
+        throw new Error('[eco-component-meta-plugin] No extensions configured. At least one integration is required.');
     }
-  };
+    const extensionPattern = createExtensionPattern(allExtensions);
+    const extensionToIntegration = buildExtensionToIntegrationMap(options.config.integrations);
+    return {
+        name: 'eco-component-meta-plugin',
+        enforce: 'pre',
+        filter: extensionPattern,
+        transform(code, id) {
+            const integration = detectIntegration(id, extensionToIntegration);
+            return {
+                code: prependJsxImportSourceIfMissing(injectEcoMeta(code, id, integration.name), integration.jsxImportSource),
+            };
+        },
+    };
 }
-function createEcoComponentMetaPlugin(options) {
-  return createEcoBuildPluginFromSourceTransform(createEcoComponentMetaTransform(options));
+/**
+ * Creates a build plugin that auto-injects `__eco` metadata into EcoComponent config objects.
+ *
+ * This plugin intercepts file loading for all integration-compatible files and:
+ * 1. Strips any query string from the file path (for dev mode cache-busting)
+ * 2. Reads the file contents
+ * 3. Parses the AST using oxc-parser to find injection points
+ * 4. Injects `__eco: { id: "...", file: "...", integration: "..." }` into config objects
+ * 5. Returns the transformed content with the appropriate loader
+ *
+ * Supported patterns:
+ * - `eco.page({ ... })` - Page component declarations
+ * - `eco.component({ ... })` - Reusable component declarations
+ * - `eco.html({ ... })` - HTML shell declarations
+ * - `eco.layout({ ... })` - Layout declarations
+ * - `Component.config = { ... }` - Config assignment pattern
+ * - `config: { ... }` - Config property in object literals
+ * - `export const config = { ... }` - Exported config declarations
+ *
+ * @param options - Plugin options containing the EcoPages config
+ * @returns A build plugin instance ready for registration
+ *
+ * @example
+ * ```typescript
+ * import { createEcoComponentMetaPlugin } from '@ecopages/core';
+ *
+ * const plugin = createEcoComponentMetaPlugin({ config: appConfig });
+ * appConfig.loaders.set(plugin.name, plugin);
+ * ```
+ */
+export function createEcoComponentMetaPlugin(options) {
+    return createEcoBuildPluginFromSourceTransform(createEcoComponentMetaTransform(options));
 }
-function createEcoComponentMetaVitePlugin(options) {
-  return createVitePluginFromSourceTransform(createEcoComponentMetaTransform(options));
+/**
+ * Creates a Vite-compatible metadata injection plugin from the shared
+ * Ecopages source-transform primitive.
+ */
+export function createEcoComponentMetaVitePlugin(options) {
+    return createVitePluginFromSourceTransform(createEcoComponentMetaTransform(options));
 }
+/**
+ * Recursively walks the AST (Abstract Syntax Tree) to find all injection points for `__eco` metadata.
+ *
+ * ## What is an AST?
+ *
+ * An AST is a tree representation of source code. Instead of treating code as text,
+ * a parser breaks it down into a structured tree where each node represents a
+ * syntactic construct (variable, function call, object, etc.).
+ *
+ * For example, this code:
+ * ```typescript
+ * eco.page({ render: () => 'hi' })
+ * ```
+ *
+ * Becomes an AST like:
+ * ```
+ * CallExpression
+ * ├── callee: MemberExpression
+ * │   ├── object: Identifier (name: "eco")
+ * │   └── property: Identifier (name: "page")
+ * └── arguments: [
+ *     └── ObjectExpression (start: 9)  <-- We inject here at position 10 (after "{")
+ *         └── properties: [...]
+ * ]
+ * ```
+ *
+ * ## How this function works
+ *
+ * 1. **Recursive traversal**: Visits every node in the tree, checking each one
+ * 2. **Pattern matching**: Checks if the current node matches one of our target patterns
+ * 3. **Position tracking**: When a match is found, records the `start` position of the
+ *    config object (the character index in the original source where `{` appears)
+ * 4. **Insertion offset**: Adds +1 to insert right after the opening `{`
+ *
+ * ## Supported patterns
+ *
+ * | Pattern | AST Node Type | Example | File Types |
+ * |---------|---------------|---------|------------|
+ * | `eco.page({...})` | CallExpression | `export default eco.page({ render: () => 'hi' })` | All |
+ * | `eco.component({...})` | CallExpression | `export const Btn = eco.component({ render: () => '<button/>' })` | All |
+ * | `eco.html({...})` | CallExpression | `export default eco.html({ render: () => '<html />' })` | All |
+ * | `eco.layout({...})` | CallExpression | `export const MainLayout = eco.layout({ render: () => '<main />' })` | All |
+ * | `X.config = {...}` | AssignmentExpression | `MyComponent.config = { dependencies: [] }` | All |
+ * | `config: {...}` | ObjectProperty | `const X: EcoComponent = { config: {...} }` | EcoComponent-typed only |
+ *
+ * ## Why AST over regex?
+ *
+ * Regex would fail on edge cases like:
+ * - `eco.page<ComplexType<(arg: string) => void>>({...})` - generics with arrows
+ * - `// eco.page({ commented out })` - comments
+ * - `const str = "eco.page({ in a string })"` - string literals
+ * - Nested objects that look like config patterns
+ *
+ * AST parsing understands the actual code structure, not just text patterns.
+ *
+ * @param node - Current AST node being visited (starts with the root Program node)
+ * @param insertions - Array to collect insertion points (mutated by this function)
+ * @param injection - The injection text to insert at each point (e.g., ` __eco: {...},`)
+ * @param isInsideEcoComponent - Whether we're inside an EcoComponent-typed declaration
+ */
 function findInjectionPoints(node, insertions, injection, isInsideEcoComponent = false) {
-  if (!node || typeof node !== "object") return;
-  const n = node;
-  if (n.type === "CallExpression") {
-    const callee = n.callee;
-    if (callee?.type === "MemberExpression" || callee?.type === "StaticMemberExpression") {
-      const obj = callee.object;
-      const prop = callee.property;
-      if (obj?.type === "Identifier" && obj?.name === "eco" && (prop?.name === "page" || prop?.name === "component" || prop?.name === "html" || prop?.name === "layout")) {
-        const args = n.arguments;
-        const firstArg = args?.[0];
-        if (firstArg?.type === "ObjectExpression") {
-          const start = firstArg.start;
-          if (typeof start === "number") {
-            insertions.push({ position: start + 1, text: injection });
-          }
+    if (!node || typeof node !== 'object')
+        return;
+    const n = node;
+    /**
+     * Pattern 1: eco.page({...}), eco.component({...}), eco.html({...}), or eco.layout({...})
+     * AST structure: CallExpression with MemberExpression callee where object is "eco"
+     */
+    if (n.type === 'CallExpression') {
+        const callee = n.callee;
+        /**
+         * MemberExpression represents "something.property" syntax.
+         * StaticMemberExpression is oxc's variant for computed vs non-computed access.
+         */
+        if (callee?.type === 'MemberExpression' || callee?.type === 'StaticMemberExpression') {
+            const obj = callee.object;
+            const prop = callee.property;
+            /** Check: is this `eco.page(...)`, `eco.component(...)`, `eco.html(...)`, or `eco.layout(...)`? */
+            if (obj?.type === 'Identifier' &&
+                obj?.name === 'eco' &&
+                (prop?.name === 'page' ||
+                    prop?.name === 'component' ||
+                    prop?.name === 'html' ||
+                    prop?.name === 'layout')) {
+                /** Get the first argument - should be an object literal {...} */
+                const args = n.arguments;
+                const firstArg = args?.[0];
+                if (firstArg?.type === 'ObjectExpression') {
+                    /**
+                     * `start` is the character index where this object begins (the "{").
+                     * Insert at position+1 to place content right after "{".
+                     */
+                    const start = firstArg.start;
+                    if (typeof start === 'number') {
+                        insertions.push({ position: start + 1, text: injection });
+                    }
+                }
+            }
         }
-      }
     }
-  }
-  if (n.type === "AssignmentExpression") {
-    const left = n.left;
-    const right = n.right;
-    if (left?.type === "MemberExpression" || left?.type === "StaticMemberExpression") {
-      const prop = left.property;
-      if (prop?.name === "config" && right?.type === "ObjectExpression") {
-        const start = right.start;
-        if (typeof start === "number") {
-          insertions.push({ position: start + 1, text: injection });
+    /**
+     * Pattern 2: Something.config = {...}
+     * AST structure: AssignmentExpression with MemberExpression left side ending in "config"
+     * This pattern is safe for all files because it requires a qualifier (e.g., MyComponent.config).
+     */
+    if (n.type === 'AssignmentExpression') {
+        const left = n.left;
+        const right = n.right;
+        /** Case: MyComponent.config = {...} */
+        if (left?.type === 'MemberExpression' || left?.type === 'StaticMemberExpression') {
+            const prop = left.property;
+            if (prop?.name === 'config' && right?.type === 'ObjectExpression') {
+                const start = right.start;
+                if (typeof start === 'number') {
+                    insertions.push({ position: start + 1, text: injection });
+                }
+            }
         }
-      }
     }
-  }
-  if (n.type === "ObjectProperty" || n.type === "Property") {
-    const key = n.key;
-    const value = n.value;
-    if ((key?.type === "Identifier" || key?.type === "IdentifierName") && key?.name === "config" && value?.type === "ObjectExpression" && isInsideEcoComponent) {
-      const start = value.start;
-      if (typeof start === "number") {
-        insertions.push({ position: start + 1, text: injection });
-      }
+    /**
+     * Pattern 3: { config: {...} } - config as an object property inside EcoComponent
+     * AST structure: ObjectProperty/Property with key "config" and value as ObjectExpression
+     *
+     * This pattern is matched when the parent VariableDeclarator has a type annotation
+     * containing "EcoComponent", e.g., `const X: EcoComponent = { config: {...} }`
+     *
+     * We track whether we're inside an EcoComponent-typed object via the `isInsideEcoComponent` flag.
+     */
+    if (n.type === 'ObjectProperty' || n.type === 'Property') {
+        const key = n.key;
+        const value = n.value;
+        if ((key?.type === 'Identifier' || key?.type === 'IdentifierName') &&
+            key?.name === 'config' &&
+            value?.type === 'ObjectExpression' &&
+            isInsideEcoComponent) {
+            const start = value.start;
+            if (typeof start === 'number') {
+                insertions.push({ position: start + 1, text: injection });
+            }
+        }
     }
-  }
-  let childIsInsideEcoComponent = isInsideEcoComponent;
-  if (n.type === "VariableDeclarator") {
-    const id = n.id;
-    const typeAnnotation = id?.typeAnnotation;
-    if (typeAnnotation) {
-      const typeStr = JSON.stringify(typeAnnotation);
-      if (typeStr.includes("EcoComponent")) {
-        childIsInsideEcoComponent = true;
-      }
+    /**
+     * Check if we're entering an EcoComponent-typed variable declaration.
+     * This sets a flag for child nodes to know they're inside an EcoComponent.
+     *
+     * Type annotation is on the `id` (Identifier), not the VariableDeclarator directly.
+     * e.g., `const X: EcoComponent = {...}` has the annotation on the "X" Identifier.
+     */
+    let childIsInsideEcoComponent = isInsideEcoComponent;
+    if (n.type === 'VariableDeclarator') {
+        const id = n.id;
+        const typeAnnotation = id?.typeAnnotation;
+        if (typeAnnotation) {
+            const typeStr = JSON.stringify(typeAnnotation);
+            if (typeStr.includes('EcoComponent')) {
+                childIsInsideEcoComponent = true;
+            }
+        }
     }
-  }
-  for (const key in n) {
-    if (key === "start" || key === "end" || key === "type") continue;
-    const value = n[key];
-    if (Array.isArray(value)) {
-      for (const child of value) {
-        findInjectionPoints(child, insertions, injection, childIsInsideEcoComponent);
-      }
-    } else if (typeof value === "object" && value !== null) {
-      findInjectionPoints(value, insertions, injection, childIsInsideEcoComponent);
+    /**
+     * Recursive traversal: Visit all child nodes in the AST.
+     *
+     * This is how we "walk" the tree - for each property of the current node,
+     * if it's an array (like `body` containing statements) or an object (like `callee`),
+     * we recursively call findInjectionPoints on it.
+     * We skip metadata properties (start, end, type) that don't contain child nodes.
+     */
+    for (const key in n) {
+        if (key === 'start' || key === 'end' || key === 'type')
+            continue;
+        const value = n[key];
+        if (Array.isArray(value)) {
+            for (const child of value) {
+                findInjectionPoints(child, insertions, injection, childIsInsideEcoComponent);
+            }
+        }
+        else if (typeof value === 'object' && value !== null) {
+            findInjectionPoints(value, insertions, injection, childIsInsideEcoComponent);
+        }
     }
-  }
 }
-function injectEcoMeta(contents, filePath, integration) {
-  const result = cachedParseSync(filePath, contents);
-  if (result.errors.length > 0) {
-    console.warn(`[eco-component-meta-plugin] Parse errors in ${filePath}:`, result.errors);
-    return contents;
-  }
-  const ast = result.program;
-  const id = rapidhash(filePath).toString(36);
-  const injection = ` __eco: { id: "${id}", file: "${filePath}", integration: "${integration}" },`;
-  const insertions = [];
-  findInjectionPoints(ast, insertions, injection);
-  if (insertions.length === 0) {
-    return contents;
-  }
-  insertions.sort((a, b) => b.position - a.position);
-  let transformed = contents;
-  for (const { position, text } of insertions) {
-    transformed = transformed.slice(0, position) + text + transformed.slice(position);
-  }
-  return transformed;
+/**
+ * Injects `__eco` metadata into EcoComponent config objects in file content.
+ *
+ * Uses oxc-parser for robust AST-based code analysis, which handles edge cases
+ * that regex-based approaches would miss (e.g., complex generics, nested objects,
+ * comments, string literals containing similar patterns).
+ *
+ * The injection is performed by:
+ * 1. Parsing the source code into an AST
+ * 2. Walking the AST to find all config object patterns
+ * 3. Collecting insertion points (sorted in reverse order to preserve positions)
+ * 4. Inserting the `__eco` property at each point
+ *
+ * @param contents - The source code content to transform
+ * @param filePath - Absolute path to the file (used to derive the directory)
+ * @param integration - The integration identifier for this file type
+ * @returns Transformed source code with `__eco` injected, or original if no patterns found
+ *
+ * @example
+ * ```typescript
+ * const result = injectEcoMeta(
+ *   'export default eco.page({ render: () => "<div>Hi</div>" });',
+ *   '/app/src/pages/index.tsx',
+ *   'react'
+ * );
+ * // Result: 'export default eco.page({ __eco: { id: "<hash>", file: "/app/src/pages/index.tsx", integration: "react" }, render: () => "<div>Hi</div>" });'
+ * ```
+ */
+export function injectEcoMeta(contents, filePath, integration) {
+    const result = cachedParseSync(filePath, contents);
+    if (result.errors.length > 0) {
+        console.warn(`[eco-component-meta-plugin] Parse errors in ${filePath}:`, result.errors);
+        return contents;
+    }
+    const ast = result.program;
+    const id = rapidhash(filePath).toString(36);
+    const injection = ` __eco: { id: "${id}", file: "${filePath}", integration: "${integration}" },`;
+    const insertions = [];
+    findInjectionPoints(ast, insertions, injection);
+    if (insertions.length === 0) {
+        return contents;
+    }
+    insertions.sort((a, b) => b.position - a.position);
+    let transformed = contents;
+    for (const { position, text } of insertions) {
+        transformed = transformed.slice(0, position) + text + transformed.slice(position);
+    }
+    return transformed;
 }
-var eco_component_meta_plugin_default = createEcoComponentMetaPlugin;
-export {
-  createEcoComponentMetaPlugin,
-  createEcoComponentMetaTransform,
-  createEcoComponentMetaVitePlugin,
-  eco_component_meta_plugin_default as default,
-  injectEcoMeta
-};
+export default createEcoComponentMetaPlugin;

package/src/plugins/foreign-jsx-override-plugin.js

@@ -1,39 +1,53 @@
-import { readFileSync } from "node:fs";
-import path from "node:path";
-import { createJsxImportSourcePragma, filterJsxSourceExtensions } from "./jsx-import-source.utils.js";
-function createForeignJsxOverridePlugin(options) {
-  const extensions = filterJsxSourceExtensions(options.foreignExtensions);
-  const excludedExtensions = filterJsxSourceExtensions(options.excludeExtensions ?? []);
-  if (extensions.length === 0) {
-    return {
-      name: options.name ?? "foreign-jsx-override",
-      setup() {
-      }
-    };
-  }
-  const pragma = createJsxImportSourcePragma(options.hostJsxImportSource);
-  const filter = new RegExp(`(${extensions.map((e) => e.replace(".", "\\.")).join("|")})$`);
-  return {
-    name: options.name ?? "foreign-jsx-override",
-    setup(build) {
-      build.onLoad({ filter }, (args) => {
-        if (excludedExtensions.some((extension) => args.path.endsWith(extension))) {
-          return void 0;
-        }
-        const source = readFileSync(args.path, "utf-8");
-        const loader = args.path.endsWith(".jsx") ? "jsx" : "tsx";
-        if (source.includes("@jsxImportSource")) {
-          return void 0;
-        }
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createJsxImportSourcePragma, filterJsxSourceExtensions } from './jsx-import-source.utils.js';
+/**
+ * Build plugin that prepends a `@jsxImportSource` pragma to foreign integration
+ * files bundled into a host integration's client graph.
+ *
+ * When a host integration (e.g. React) bundles a component file that belongs to
+ * another JSX integration (e.g. `.kita.tsx`), that file inherits the project
+ * `tsconfig` JSX runtime which produces the wrong output (HTML strings instead
+ * of framework elements). This plugin rewrites the source to explicitly target
+ * the host's JSX factory so the bundler compiles every JSX expression into the
+ * correct element creation calls.
+ *
+ * The plugin is intentionally framework-agnostic: any integration that does
+ * client-side bundling can use it by passing its own `jsxImportSource` and the
+ * set of foreign extensions collected from the app config.
+ *
+ * When no JSX-bearing foreign extensions are present, the returned plugin is a
+ * no-op so integrations can register it unconditionally.
+ */
+export function createForeignJsxOverridePlugin(options) {
+    const extensions = filterJsxSourceExtensions(options.foreignExtensions);
+    const excludedExtensions = filterJsxSourceExtensions(options.excludeExtensions ?? []);
+    if (extensions.length === 0) {
         return {
-          contents: pragma + source,
-          loader,
-          resolveDir: path.dirname(args.path)
+            name: options.name ?? 'foreign-jsx-override',
+            setup() { },
         };
-      });
     }
-  };
+    const pragma = createJsxImportSourcePragma(options.hostJsxImportSource);
+    const filter = new RegExp(`(${extensions.map((e) => e.replace('.', '\\.')).join('|')})$`);
+    return {
+        name: options.name ?? 'foreign-jsx-override',
+        setup(build) {
+            build.onLoad({ filter }, (args) => {
+                if (excludedExtensions.some((extension) => args.path.endsWith(extension))) {
+                    return undefined;
+                }
+                const source = readFileSync(args.path, 'utf-8');
+                const loader = args.path.endsWith('.jsx') ? 'jsx' : 'tsx';
+                if (source.includes('@jsxImportSource')) {
+                    return undefined;
+                }
+                return {
+                    contents: pragma + source,
+                    loader,
+                    resolveDir: path.dirname(args.path),
+                };
+            });
+        },
+    };
 }
-export {
-  createForeignJsxOverridePlugin
-};