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

package/src/hmr/strategies/js-hmr-strategy.js

@@ -1,226 +1,113 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
-import { appLogger } from "../../global/app-logger.js";
-import {
-  removeStaleHmrEntrypointOutput,
-  resolveHmrEntrypointOutputPaths,
-  isRegisteredScriptEntrypoint,
-  isHmrOutputFresh,
-  isHmrOutputOlderThanSource
-} from "../hmr-entrypoint-output.js";
-class JsHmrStrategy extends HmrStrategy {
-  type = HmrStrategyType.SCRIPT;
-  context;
-  constructor(context) {
-    super();
-    this.context = context;
-  }
-  /**
-   * Determines if the file is a JS/TS file that could affect registered entrypoints.
-   *
-   * Matches if:
-   * 1. There are registered entrypoints to rebuild
-   * 2. The changed file is a JS/TS file in the src directory
-   * 3. Registered entrypoints always match, even when they share an integration template extension
-   *
-   * @param filePath - Absolute path to the changed file
-   * @returns True if this file should trigger entrypoint rebuilds
-   */
-  matches(filePath) {
-    const watchedFiles = this.context.getWatchedFiles();
-    const resolvedPath = path.resolve(filePath);
-    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(resolvedPath);
-    const srcDir = path.resolve(this.context.getSrcDir());
-    const isInSrc = resolvedPath.startsWith(`${srcDir}${path.sep}`) || resolvedPath === srcDir;
-    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => resolvedPath.endsWith(extension));
-    if (watchedFiles.size === 0) {
-      return false;
+/**
+ * JavaScript HMR Strategy
+ *
+ * Handles hot module replacement for JavaScript and TypeScript entrypoints.
+ * Invalidates dev-transform modules and decides whether the browser can hot-accept
+ * the change or must reload.
+ *
+ * @module
+ */
+import path from 'node:path';
+import { HmrStrategy, HmrStrategyType } from '../hmr-strategy.js';
+import { appLogger } from '../../global/app-logger.js';
+import { isRegisteredDevTransformEntrypoint, isRegisteredScriptEntrypoint } from '../hmr-entrypoint-output.js';
+import { isDevTransformModuleUrl } from '../hmr-asset-paths.js';
+/**
+ * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
+ */
+export class JsHmrStrategy extends HmrStrategy {
+    type = HmrStrategyType.SCRIPT;
+    context;
+    constructor(context) {
+        super();
+        this.context = context;
     }
-    if (!isJsTs || !isInSrc) {
-      return false;
-    }
-    if (watchedFiles.has(resolvedPath)) {
-      return true;
-    }
-    if (isIntegrationTemplate) {
-      return false;
-    }
-    return true;
-  }
-  /**
-   * Processes a file change by rebuilding affected entrypoints.
-   *
-   * @param filePath - Absolute path to the changed file
-   *
-   * @remarks
-   * If runtime-specific dependency graph hooks are unavailable, this strategy
-   * falls back to rebuilding all watched entrypoints.
-   * When multiple entrypoints are impacted they are bundled in a single
-   * invocation to share AST parsing and chunk deduplication.
-   * @returns Action to broadcast update events
-   */
-  async process(filePath) {
-    appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
-    const watchedFiles = this.context.getWatchedFiles();
-    const resolvedChanged = path.resolve(filePath);
-    const isRegisteredEntrypointEdit = isRegisteredScriptEntrypoint(watchedFiles, resolvedChanged);
-    if (watchedFiles.size === 0) {
-      appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
-      return { type: "none" };
-    }
-    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
-    const hasDependencyHit = dependencyHits.size > 0;
-    const impactedEntrypoints = isRegisteredEntrypointEdit ? [resolvedChanged] : hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(path.resolve(entrypoint))) : Array.from(watchedFiles.keys());
-    const buildableEntrypoints = impactedEntrypoints.filter(
-      (entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true
-    );
-    if (!hasDependencyHit && !isRegisteredEntrypointEdit) {
-      appLogger.debug("[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints");
-    }
-    if (buildableEntrypoints.length === 0) {
-      return { type: "none" };
-    }
-    for (const entrypoint of buildableEntrypoints) {
-      this.removeStaleEntrypointOutput(this.resolveEntrypointOutputPath(entrypoint));
-    }
-    const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
-    if (!buildResult.success) {
-      return { type: "none" };
-    }
-    const updates = [];
-    let reloadRequired = false;
-    for (const entrypoint of buildableEntrypoints) {
-      const resolvedEntrypoint = path.resolve(entrypoint);
-      const derivedOutput = resolveHmrEntrypointOutputPaths(
-        this.context.getSrcDir(),
-        this.context.getDistDir(),
-        resolvedEntrypoint
-      );
-      const outputUrl = watchedFiles.get(resolvedEntrypoint) ?? derivedOutput.outputUrl;
-      const outputPath = this.resolveEntrypointOutputPath(resolvedEntrypoint);
-      if (buildResult.dependencies) {
-        const entrypointDeps = buildResult.dependencies.get(resolvedEntrypoint) ?? [];
-        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(resolvedEntrypoint, entrypointDeps);
-      }
-      const result = await this.processOutput(outputPath, outputUrl, resolvedEntrypoint);
-      if (result.success) {
-        updates.push(outputUrl);
-        if (result.requiresReload) {
-          reloadRequired = true;
+    matches(filePath) {
+        const watchedFiles = this.context.getWatchedFiles();
+        const resolvedPath = path.resolve(filePath);
+        const isJsTs = /\.(ts|tsx|js|jsx)$/.test(resolvedPath);
+        const srcDir = path.resolve(this.context.getSrcDir());
+        const isInSrc = resolvedPath.startsWith(`${srcDir}${path.sep}`) || resolvedPath === srcDir;
+        const isIntegrationTemplate = this.context
+            .getTemplateExtensions()
+            .some((extension) => resolvedPath.endsWith(extension));
+        if (watchedFiles.size === 0) {
+            return false;
         }
-      }
-    }
-    if (updates.length > 0) {
-      if (reloadRequired) {
-        appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
-        return {
-          type: "broadcast",
-          events: [{ type: "reload" }]
-        };
-      }
-      return {
-        type: "broadcast",
-        events: updates.map((p) => ({
-          type: "update",
-          path: p,
-          timestamp: Date.now()
-        }))
-      };
-    }
-    return { type: "none" };
-  }
-  resolveEntrypointOutputPath(entrypointPath) {
-    return resolveHmrEntrypointOutputPaths(this.context.getSrcDir(), this.context.getDistDir(), entrypointPath).outputPath;
-  }
-  removeStaleEntrypointOutput(outputPath) {
-    removeStaleHmrEntrypointOutput(outputPath, "JsHmrStrategy");
-  }
-  /**
-   * Bundles one or more entrypoints in a single build invocation.
-   * Uses the source directory as the output base so that the directory structure
-   * is preserved under the HMR dist folder.
-   */
-  async bundleEntrypoints(entrypoints) {
-    try {
-      if (entrypoints.length === 1) {
-        const entrypoint = entrypoints[0];
-        const outputPath = this.resolveEntrypointOutputPath(entrypoint);
-        const naming = path.relative(this.context.getDistDir(), outputPath).split(path.sep).join("/");
-        const result2 = await this.context.getBrowserBundleService().bundle({
-          profile: "hmr-entrypoint",
-          entrypoints: [entrypoint],
-          outdir: this.context.getDistDir(),
-          naming,
-          minify: false
-        });
-        if (!result2.success) {
-          appLogger.error("[JsHmrStrategy] Entrypoint build failed:", result2.logs);
-          return { success: false };
+        if (!isJsTs || !isInSrc) {
+            return false;
         }
-        const dependencies2 = /* @__PURE__ */ new Map();
-        if (result2.dependencyGraph?.entrypoints) {
-          for (const [resolvedEntrypoint, deps] of Object.entries(result2.dependencyGraph.entrypoints)) {
-            dependencies2.set(path.resolve(resolvedEntrypoint), deps);
-          }
+        if (watchedFiles.has(resolvedPath)) {
+            return true;
         }
-        return { success: true, dependencies: dependencies2 };
-      }
-      const result = await this.context.getBrowserBundleService().bundle({
-        profile: "hmr-entrypoint",
-        entrypoints,
-        outdir: this.context.getDistDir(),
-        outbase: this.context.getSrcDir(),
-        naming: "[dir]/[name]",
-        minify: false
-      });
-      if (!result.success) {
-        appLogger.error("[JsHmrStrategy] Batched build failed:", result.logs);
-        return { success: false };
-      }
-      const dependencies = /* @__PURE__ */ new Map();
-      if (result.dependencyGraph?.entrypoints) {
-        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
-          dependencies.set(path.resolve(entrypoint), deps);
+        if (isIntegrationTemplate) {
+            return false;
         }
-      }
-      return { success: true, dependencies };
-    } catch (error) {
-      appLogger.error("[JsHmrStrategy] Error in batched build:", error);
-      return { success: false };
+        return true;
     }
-  }
-  /**
-   * Processes bundled output and determines whether the browser can hot-accept
-   * the update or must fall back to a full reload.
-   *
-   * @param filepath - Path to the bundled output file
-   * @param url - URL path for the bundled file
-   * @returns True if processing was successful and update should be broadcast
-   */
-  async processOutput(filepath, url, sourcePath) {
-    try {
-      if (sourcePath && !isHmrOutputFresh(filepath, sourcePath)) {
-        if (isHmrOutputOlderThanSource(filepath, sourcePath)) {
-          appLogger.warn(
-            `[JsHmrStrategy] HMR output is older than source after rebuild; skipping broadcast for ${url}`
-          );
+    async process(filePath) {
+        appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
+        const watchedFiles = this.context.getWatchedFiles();
+        const resolvedChanged = path.resolve(filePath);
+        const registeredEntrypoints = this.context.getRegisteredEntrypoints();
+        const isRegisteredEntrypointEdit = isRegisteredDevTransformEntrypoint(registeredEntrypoints, resolvedChanged);
+        if (watchedFiles.size === 0) {
+            appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
+            return { type: 'none' };
+        }
+        const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
+        const hasDependencyHit = dependencyHits.size > 0;
+        const impactedEntrypoints = isRegisteredEntrypointEdit
+            ? [resolvedChanged]
+            : hasDependencyHit
+                ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(path.resolve(entrypoint)))
+                : Array.from(watchedFiles.keys());
+        const buildableEntrypoints = impactedEntrypoints.filter((entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true);
+        if (!hasDependencyHit && !isRegisteredEntrypointEdit) {
+            appLogger.debug('[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints');
+        }
+        if (buildableEntrypoints.length === 0) {
+            return { type: 'none' };
+        }
+        const devTransformUpdates = [];
+        let devTransformReloadRequired = false;
+        for (const entrypoint of buildableEntrypoints) {
+            const resolvedEntrypoint = path.resolve(entrypoint);
+            const outputUrl = watchedFiles.get(resolvedEntrypoint);
+            if (!outputUrl || !isDevTransformModuleUrl(outputUrl)) {
+                appLogger.debug(`[JsHmrStrategy] Skipping non-dev-transform entrypoint ${resolvedEntrypoint}: ${outputUrl ?? 'unregistered'}`);
+                continue;
+            }
+            this.context.invalidateDevTransformSource?.(resolvedEntrypoint);
+            if (isRegisteredScriptEntrypoint(registeredEntrypoints, resolvedEntrypoint)) {
+                if (this.context.consumeRegisteredScriptReloadRequired?.(resolvedEntrypoint)) {
+                    devTransformReloadRequired = true;
+                }
+                else {
+                    devTransformUpdates.push(outputUrl);
+                }
+            }
+            else {
+                devTransformUpdates.push(outputUrl);
+            }
+        }
+        if (devTransformReloadRequired) {
+            appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
+            return {
+                type: 'broadcast',
+                events: [{ type: 'reload' }],
+            };
+        }
+        if (devTransformUpdates.length > 0) {
+            return {
+                type: 'broadcast',
+                events: devTransformUpdates.map((p) => ({
+                    type: 'update',
+                    path: p,
+                    timestamp: Date.now(),
+                })),
+            };
         }
-        return { success: false, requiresReload: false };
-      }
-      const code = await fileSystem.readFile(filepath);
-      if (code.includes("/* [ecopages] hmr */")) {
-        return { success: true, requiresReload: !code.includes("import.meta.hot.accept") };
-      }
-      appLogger.debug(`[JsHmrStrategy] Processed ${url}`);
-      const hasHmrAccept = code.includes("import.meta.hot.accept");
-      return { success: true, requiresReload: !hasHmrAccept };
-    } catch (error) {
-      appLogger.error(`[JsHmrStrategy] Error processing output for ${url}:`, error);
-      return { success: false, requiresReload: false };
+        return { type: 'none' };
     }
-  }
 }
-export {
-  JsHmrStrategy
-};

package/src/hmr/strategies/server-rendered-template-hmr-strategy.js

@@ -1,29 +1,35 @@
-import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
+/**
+ * HMR strategy for server-rendered include templates and explicit server views.
+ *
+ * These files affect SSR output (head, layout shell, explicit views) but are not
+ * client HMR entrypoints. Broadcast a layout-update so the active navigation
+ * runtime can refresh the current page without a full document reload.
+ */
+import { HmrStrategy, HmrStrategyType } from '../hmr-strategy.js';
+/** Outranks integration-owned strategies that may also match shared dependencies. */
 const SERVER_RENDERED_TEMPLATE_PRIORITY_OFFSET = 50;
-class ServerRenderedTemplateHmrStrategy extends HmrStrategy {
-  constructor(invalidationService) {
-    super();
-    this.invalidationService = invalidationService;
-  }
-  invalidationService;
-  type = HmrStrategyType.INTEGRATION;
-  priorityOffset = SERVER_RENDERED_TEMPLATE_PRIORITY_OFFSET;
-  matches(filePath) {
-    return this.invalidationService.isIncludeSourceFile(filePath) || this.invalidationService.isExplicitServerViewFile(filePath);
-  }
-  async process(filePath) {
-    return {
-      type: "broadcast",
-      events: [
-        {
-          type: "layout-update",
-          path: filePath,
-          timestamp: Date.now()
-        }
-      ]
-    };
-  }
+export class ServerRenderedTemplateHmrStrategy extends HmrStrategy {
+    invalidationService;
+    type = HmrStrategyType.INTEGRATION;
+    priorityOffset = SERVER_RENDERED_TEMPLATE_PRIORITY_OFFSET;
+    constructor(invalidationService) {
+        super();
+        this.invalidationService = invalidationService;
+    }
+    matches(filePath) {
+        return (this.invalidationService.isIncludeSourceFile(filePath) ||
+            this.invalidationService.isExplicitServerViewFile(filePath));
+    }
+    async process(filePath) {
+        return {
+            type: 'broadcast',
+            events: [
+                {
+                    type: 'layout-update',
+                    path: filePath,
+                    timestamp: Date.now(),
+                },
+            ],
+        };
+    }
 }
-export {
-  ServerRenderedTemplateHmrStrategy
-};

package/src/index.browser.js

@@ -1,4 +1 @@
-import { eco } from "./eco/eco.browser.js";
-export {
-  eco
-};
+export { eco } from './eco/eco.browser.js';

package/src/index.d.ts

@@ -5,3 +5,4 @@ export { defineApiHandler, defineGroupHandler, defineGet, definePost, definePut,
 export { createEcoBuildPluginFromSourceTransform, createVitePluginsFromAppSourceTransforms, getAppSourceTransforms, createVitePluginFromSourceTransform, normalizeTransformId, type EcoSourceTransform, type EcoSourceTransformResult, type EcoViteCompatiblePlugin, } from './plugins/source-transform.js';
 export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.js';
 export { SchemaError, validateStandardSchema } from './services/validation/validate-standard-schema.js';
+export { buildIslandHostAttributes, ECO_ISLAND_HOST_ATTRIBUTE, ECO_ISLAND_INTEGRATION_ATTRIBUTE, finalizeIslandComponentRender, isIslandHostElement, mergeIslandHostAttributes, } from './islands/island-host.js';

package/src/index.js

@@ -1,47 +1,6 @@
-import { eco } from "./eco/eco.js";
-import {
-  defineApiHandler,
-  defineGroupHandler,
-  defineGet,
-  definePost,
-  definePut,
-  defineDelete,
-  definePatch,
-  defineOptions,
-  defineHead,
-  json,
-  html,
-  redirect
-} from "./adapters/shared/http/define-api-handler.js";
-import {
-  createEcoBuildPluginFromSourceTransform,
-  createVitePluginsFromAppSourceTransforms,
-  getAppSourceTransforms,
-  createVitePluginFromSourceTransform,
-  normalizeTransformId
-} from "./plugins/source-transform.js";
-import { createEcoComponentMetaTransform } from "./plugins/eco-component-meta-plugin.js";
-import { SchemaError, validateStandardSchema } from "./services/validation/validate-standard-schema.js";
-export {
-  SchemaError,
-  createEcoBuildPluginFromSourceTransform,
-  createEcoComponentMetaTransform,
-  createVitePluginFromSourceTransform,
-  createVitePluginsFromAppSourceTransforms,
-  defineApiHandler,
-  defineDelete,
-  defineGet,
-  defineGroupHandler,
-  defineHead,
-  defineOptions,
-  definePatch,
-  definePost,
-  definePut,
-  eco,
-  getAppSourceTransforms,
-  html,
-  json,
-  normalizeTransformId,
-  redirect,
-  validateStandardSchema
-};
+export { eco } from './eco/eco.js';
+export { defineApiHandler, defineGroupHandler, defineGet, definePost, definePut, defineDelete, definePatch, defineOptions, defineHead, json, html, redirect, } from './adapters/shared/http/define-api-handler.js';
+export { createEcoBuildPluginFromSourceTransform, createVitePluginsFromAppSourceTransforms, getAppSourceTransforms, createVitePluginFromSourceTransform, normalizeTransformId, } from './plugins/source-transform.js';
+export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.js';
+export { SchemaError, validateStandardSchema } from './services/validation/validate-standard-schema.js';
+export { buildIslandHostAttributes, ECO_ISLAND_HOST_ATTRIBUTE, ECO_ISLAND_INTEGRATION_ATTRIBUTE, finalizeIslandComponentRender, isIslandHostElement, mergeIslandHostAttributes, } from './islands/island-host.js';

package/src/integrations/ghtml/ghtml-renderer.js

@@ -1,8 +1,13 @@
-import { StringMarkupRenderer } from "../../route-renderer/orchestration/string-markup-renderer.js";
-import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
-class GhtmlRenderer extends StringMarkupRenderer {
-  name = GHTML_PLUGIN_NAME;
+/**
+ * This module contains the ghtml renderer
+ * @module
+ */
+import { StringMarkupRenderer } from '../../route-renderer/orchestration/string-markup-renderer.js';
+import { GHTML_PLUGIN_NAME } from './ghtml.constants.js';
+/**
+ * A renderer for the ghtml integration.
+ * It renders a page using the HtmlTemplate and Page components.
+ */
+export class GhtmlRenderer extends StringMarkupRenderer {
+    name = GHTML_PLUGIN_NAME;
 }
-export {
-  GhtmlRenderer
-};

package/src/integrations/ghtml/ghtml.constants.js

@@ -1,4 +1 @@
-const GHTML_PLUGIN_NAME = "ghtml";
-export {
-  GHTML_PLUGIN_NAME
-};
+export const GHTML_PLUGIN_NAME = 'ghtml';

package/src/integrations/ghtml/ghtml.plugin.js

@@ -1,13 +1,10 @@
-import { defineIntegration } from "../../plugins/define-integration.js";
-import { GhtmlRenderer } from "./ghtml-renderer.js";
-import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
-const ghtmlPlugin = defineIntegration({
-  name: GHTML_PLUGIN_NAME,
-  extensions: [".ghtml.ts", ".ghtml.tsx", ".ghtml"],
-  renderer: GhtmlRenderer
+import { defineIntegration } from '../../plugins/define-integration.js';
+import { GhtmlRenderer } from './ghtml-renderer.js';
+import { GHTML_PLUGIN_NAME } from './ghtml.constants.js';
+export const ghtmlPlugin = defineIntegration({
+    name: GHTML_PLUGIN_NAME,
+    extensions: ['.ghtml.ts', '.ghtml.tsx', '.ghtml'],
+    renderer: GhtmlRenderer,
 });
-const GhtmlPlugin = ghtmlPlugin.Plugin;
-export {
-  GhtmlPlugin,
-  ghtmlPlugin
-};
+/** @deprecated Use {@link ghtmlPlugin.Plugin} or {@link ghtmlPlugin} instead. */
+export const GhtmlPlugin = ghtmlPlugin.Plugin;

package/src/islands/README.md

@@ -0,0 +1,25 @@
+# Island host contract
+
+Hydratable component instances stamp a small, integration-agnostic attribute set on their SSR root so devtools (and future runtime features) can discover islands without integration-specific selectors.
+
+## Attributes
+
+| Attribute                     | Purpose                                              |
+| ----------------------------- | ---------------------------------------------------- |
+| `data-eco-island`             | Marks the element as an interactive island host      |
+| `data-eco-island-integration` | Owning integration (`react`, `lit`, `kitajs`, …)     |
+| `data-eco-component-id`       | Stable instance id from the render pipeline          |
+| `data-eco-component-key`      | Optional module key used by client hydration (React) |
+| `data-eco-props`              | Optional base64 JSON props snapshot for hydration    |
+
+React may still replace the SSR host with `<eco-island>` after hydration; the marker is applied at SSR time on the component root.
+
+## Where stamping happens
+
+`finalizeIslandComponentRender()` in `island-host.ts` is called from integration renderers when:
+
+1. `integrationContext.componentInstanceId` is present
+2. The render result can attach attributes to a single root element
+3. The render emits at least one client `script` asset
+
+Integrations with custom island metadata (for example React's component key) should build on `buildIslandHostAttributes()` rather than inventing per-demo selectors.

package/src/islands/island-host.d.ts

@@ -0,0 +1,37 @@
+export declare const ECO_ISLAND_HOST_ATTRIBUTE = "data-eco-island";
+export declare const ECO_ISLAND_INTEGRATION_ATTRIBUTE = "data-eco-island-integration";
+export declare const ECO_ISLAND_COMPONENT_ID_ATTRIBUTE = "data-eco-component-id";
+export declare const ECO_ISLAND_COMPONENT_KEY_ATTRIBUTE = "data-eco-component-key";
+export declare const ECO_ISLAND_PROPS_ATTRIBUTE = "data-eco-props";
+export type IslandHostAttributesInput = {
+    integrationName: string;
+    componentInstanceId: string;
+    componentKey?: string;
+    props?: Record<string, unknown>;
+    existing?: Record<string, string>;
+};
+/**
+ * @remarks Presence marker for hydratable component hosts, similar in spirit to Astro's `astro-island`.
+ */
+export declare function mergeIslandHostAttributes(input: {
+    integrationName: string;
+    componentInstanceId: string;
+    existing?: Record<string, string>;
+}): Record<string, string>;
+export declare function buildIslandHostAttributes(input: IslandHostAttributesInput): Record<string, string>;
+export declare function isIslandHostElement(element: Element): boolean;
+export declare function componentRenderHasIslandBootstrap(assets: Array<{
+    kind: string;
+}> | undefined): boolean;
+export declare function finalizeIslandComponentRender<T extends {
+    canAttachAttributes: boolean;
+    integrationName: string;
+    rootAttributes?: Record<string, string>;
+    assets?: Array<{
+        kind: string;
+    }>;
+}>(input: {
+    integrationContext?: {
+        componentInstanceId?: string;
+    };
+}, result: T): T;

package/src/islands/island-host.js

@@ -0,0 +1,55 @@
+export const ECO_ISLAND_HOST_ATTRIBUTE = 'data-eco-island';
+export const ECO_ISLAND_INTEGRATION_ATTRIBUTE = 'data-eco-island-integration';
+export const ECO_ISLAND_COMPONENT_ID_ATTRIBUTE = 'data-eco-component-id';
+export const ECO_ISLAND_COMPONENT_KEY_ATTRIBUTE = 'data-eco-component-key';
+export const ECO_ISLAND_PROPS_ATTRIBUTE = 'data-eco-props';
+/**
+ * @remarks Presence marker for hydratable component hosts, similar in spirit to Astro's `astro-island`.
+ */
+export function mergeIslandHostAttributes(input) {
+    return {
+        ...input.existing,
+        [ECO_ISLAND_HOST_ATTRIBUTE]: '',
+        [ECO_ISLAND_COMPONENT_ID_ATTRIBUTE]: input.existing?.[ECO_ISLAND_COMPONENT_ID_ATTRIBUTE] ?? input.componentInstanceId,
+        [ECO_ISLAND_INTEGRATION_ATTRIBUTE]: input.integrationName,
+    };
+}
+export function buildIslandHostAttributes(input) {
+    const attributes = mergeIslandHostAttributes(input);
+    if (input.componentKey) {
+        attributes[ECO_ISLAND_COMPONENT_KEY_ATTRIBUTE] = input.componentKey;
+    }
+    if (input.props !== undefined) {
+        attributes[ECO_ISLAND_PROPS_ATTRIBUTE] = btoa(JSON.stringify(input.props));
+    }
+    return attributes;
+}
+export function isIslandHostElement(element) {
+    if (element.hasAttribute(ECO_ISLAND_HOST_ATTRIBUTE)) {
+        return true;
+    }
+    if (element.hasAttribute(ECO_ISLAND_COMPONENT_KEY_ATTRIBUTE)) {
+        return true;
+    }
+    if (element.tagName.toLowerCase() === 'eco-island') {
+        return true;
+    }
+    return element.hasAttribute(ECO_ISLAND_COMPONENT_ID_ATTRIBUTE) && element.hasAttribute(ECO_ISLAND_PROPS_ATTRIBUTE);
+}
+export function componentRenderHasIslandBootstrap(assets) {
+    return (assets ?? []).some((asset) => asset.kind === 'script');
+}
+export function finalizeIslandComponentRender(input, result) {
+    const componentInstanceId = input.integrationContext?.componentInstanceId;
+    if (!componentInstanceId || !result.canAttachAttributes || !componentRenderHasIslandBootstrap(result.assets)) {
+        return result;
+    }
+    return {
+        ...result,
+        rootAttributes: mergeIslandHostAttributes({
+            integrationName: result.integrationName,
+            componentInstanceId,
+            existing: result.rootAttributes,
+        }),
+    };
+}