vite-plugin-shopify-theme-islands 1.2.0 → 1.2.2

package/dist/config-policy.d.ts

@@ -0,0 +1,11 @@
+import { type ReviveOptions } from "./contract.js";
+import type { ClientDirectiveDefinition, DirectivesConfig, ShopifyThemeIslandsOptions } from "./options.js";
+export interface ResolvedThemeIslandsPolicy {
+    plugin: {
+        directives: DirectivesConfig;
+        customDirectives: ClientDirectiveDefinition[];
+        debug: boolean;
+    };
+    runtime: ReviveOptions;
+}
+export declare function resolveThemeIslandsPolicy(options?: ShopifyThemeIslandsOptions): ResolvedThemeIslandsPolicy;

package/dist/directive-orchestration.d.ts

@@ -0,0 +1,27 @@
+import type { ClientDirective, NormalizedReviveOptions } from "./contract.js";
+import type { RuntimeLogger } from "./runtime-surface.js";
+export interface DirectiveWaiters {
+    waitVisible(element: Element, rootMargin: string, threshold: number, watch: (el: Element, cancel: () => void) => () => void): Promise<void>;
+    waitMedia(query: string): Promise<void>;
+    waitIdle(timeout: number): Promise<void>;
+    waitDelay(ms: number): Promise<void>;
+    waitInteraction(element: Element, events: string[], watch: (el: Element, cancel: () => void) => () => void): Promise<void>;
+}
+export interface DirectiveRunContext {
+    tagName: string;
+    element: HTMLElement;
+    directives: NormalizedReviveOptions["directives"];
+    customDirectives?: Map<string, ClientDirective>;
+    directiveTimeout: number;
+    watchCancellable: (el: Element, cancel: () => void) => () => void;
+    log: RuntimeLogger;
+    run: () => Promise<void>;
+    onError(attrName: string, err: unknown): void;
+}
+export interface DirectiveOrchestrator {
+    run(ctx: DirectiveRunContext): Promise<boolean>;
+}
+export declare class DirectiveCancelledError extends Error {
+    constructor();
+}
+export declare function createDirectiveOrchestrator(waiters?: DirectiveWaiters): DirectiveOrchestrator;

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import type { IslandLoadDetail, IslandErrorDetail } from "./index.js";
+import type { IslandLoadDetail, IslandErrorDetail } from "./contract.js";
 /**
  * Listen for successful island module loads.
  *

package/dist/events.js

@@ -1,13 +1,74 @@
+// src/runtime-surface.ts
+var SILENT_LOGGER = {
+  note() {},
+  flush() {}
+};
+function addListener(target, name, handler) {
+  const listener = (event) => handler(event.detail);
+  target.addEventListener(name, listener);
+  return () => target.removeEventListener(name, listener);
+}
+function dispatch(target, name, detail) {
+  target.dispatchEvent(new CustomEvent(name, { detail }));
+}
+function createRuntimeSurface(deps) {
+  return {
+    dispatchLoad(detail) {
+      dispatch(deps.target, "islands:load", detail);
+    },
+    dispatchError(detail) {
+      dispatch(deps.target, "islands:error", detail);
+    },
+    onLoad(handler) {
+      return addListener(deps.target, "islands:load", handler);
+    },
+    onError(handler) {
+      return addListener(deps.target, "islands:error", handler);
+    },
+    createLogger(tagName, debug) {
+      if (!debug)
+        return SILENT_LOGGER;
+      const msgs = [];
+      return {
+        note(msg) {
+          msgs.push(msg);
+        },
+        flush(summary) {
+          if (msgs.length === 0) {
+            deps.console.log("[islands]", `<${tagName}> ${summary}`);
+          } else {
+            deps.console.groupCollapsed(`[islands] <${tagName}> ${summary}`);
+            for (const msg of msgs)
+              deps.console.log(msg);
+            deps.console.groupEnd();
+          }
+          msgs.length = 0;
+        }
+      };
+    },
+    beginReadyLog(islandCount, debug) {
+      if (!debug)
+        return () => {};
+      deps.console.groupCollapsed(`[islands] ready — ${islandCount} island(s)`);
+      return () => deps.console.groupEnd();
+    }
+  };
+}
+var runtimeSurface;
+function getRuntimeSurface() {
+  runtimeSurface ??= createRuntimeSurface({
+    target: document,
+    console
+  });
+  return runtimeSurface;
+}
+
 // src/events.ts
 function onIslandLoad(handler) {
-  const listener = (e) => handler(e.detail);
-  document.addEventListener("islands:load", listener);
-  return () => document.removeEventListener("islands:load", listener);
+  return getRuntimeSurface().onLoad(handler);
 }
 function onIslandError(handler) {
-  const listener = (e) => handler(e.detail);
-  document.addEventListener("islands:error", listener);
-  return () => document.removeEventListener("islands:error", listener);
+  return getRuntimeSurface().onError(handler);
 }
 export {
   onIslandLoad,

package/dist/index.d.ts

@@ -1,71 +1,8 @@
+import type { ShopifyThemeIslandsOptions } from "./options.js";
 import type { Plugin } from "vite";
 /** A function that triggers the load of an island module. */
 export type ClientDirectiveLoader = () => Promise<void>;
 export type { ClientDirective, ClientDirectiveOptions } from "./contract.js";
-/** Plugin option entry for registering a custom client directive. */
-export interface ClientDirectiveDefinition {
-    /** HTML attribute name, e.g. `'client:on-click'` */
-    name: string;
-    /** Path to the directive module (supports Vite aliases) */
-    entrypoint: string;
-}
-/** Shared directive configuration shape used by both the plugin and the runtime. */
-export interface DirectivesConfig {
-    /** Configuration for the `client:visible` directive (IntersectionObserver). */
-    visible?: {
-        /** HTML attribute name. Default: `'client:visible'` */
-        attribute?: string;
-        /** Passed to IntersectionObserver — loads islands before they scroll into view. Default: `'200px'` */
-        rootMargin?: string;
-        /** Passed to IntersectionObserver — ratio of element that must be visible. Default: `0` */
-        threshold?: number;
-    };
-    /** Configuration for the `client:idle` directive (requestIdleCallback). */
-    idle?: {
-        /** HTML attribute name. Default: `'client:idle'` */
-        attribute?: string;
-        /** Deadline (ms) passed to requestIdleCallback; also used as the setTimeout fallback delay. Default: `500` */
-        timeout?: number;
-    };
-    /** Configuration for the `client:media` directive (matchMedia). */
-    media?: {
-        /** HTML attribute name. Default: `'client:media'` */
-        attribute?: string;
-    };
-    /** Configuration for the `client:defer` directive (fixed setTimeout delay). */
-    defer?: {
-        /** HTML attribute name. Default: `'client:defer'` */
-        attribute?: string;
-        /** Fallback delay (ms) when the attribute has no value. Default: `3000` */
-        delay?: number;
-    };
-    /** Configuration for the `client:interaction` directive (mouseenter/touchstart/focusin). */
-    interaction?: {
-        /** HTML attribute name. Default: `'client:interaction'` */
-        attribute?: string;
-        /** DOM event names to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
-        events?: string[];
-    };
-    /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
-    custom?: ClientDirectiveDefinition[];
-}
-/** Event detail and runtime options (single source of truth in contract). */
-import type { RetryConfig } from "./contract.js";
+export type { ClientDirectiveDefinition, DirectivesConfig, ShopifyThemeIslandsOptions, } from "./options.js";
 export type { IslandLoadDetail, IslandErrorDetail, ReviveOptions, RetryConfig, RuntimeDirectivesConfig, } from "./contract.js";
-export interface ShopifyThemeIslandsOptions {
-    /** Directories to scan for island files. Accepts paths or Vite aliases. Default: `['/frontend/js/islands/']` */
-    directories?: string | string[];
-    /** Log discovered islands and generated virtual module. Default: `false` */
-    debug?: boolean;
-    /** Per-directive configuration. */
-    directives?: DirectivesConfig;
-    /** Automatic retry behaviour for failed island loads. */
-    retry?: RetryConfig;
-    /**
-     * Milliseconds before a custom directive that never calls `load()` is considered timed out.
-     * When exceeded, `islands:error` is dispatched and the island is abandoned.
-     * Default: `0` (disabled).
-     */
-    directiveTimeout?: number;
-}
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;

package/dist/index.js

@@ -54,39 +54,6 @@ function collectTagNames(dir) {
   return names;
 }
 
-// src/revive-module.ts
-function buildReviveModuleSource(params) {
-  const { runtimePath, directoryGlobs, islandPaths, customDirectives, reviveOptions } = params;
-  const directiveImportLines = customDirectives?.map(({ entrypoint }, index) => `import _directive${index} from ${JSON.stringify(entrypoint)};`) ?? [];
-  const globEntries = [
-    `{ ${directoryGlobs.map((glob) => `...import.meta.glob(${JSON.stringify(glob)})`).join(", ")} }`
-  ];
-  if (islandPaths?.length)
-    globEntries.push(`import.meta.glob(${JSON.stringify(islandPaths)})`);
-  const lines = [
-    ...directiveImportLines,
-    `import { revive as _islands } from ${JSON.stringify(runtimePath)};`,
-    `const islands = Object.assign({}, ${globEntries.join(", ")});`,
-    `const options = ${JSON.stringify(reviveOptions)};`
-  ];
-  if (customDirectives?.length) {
-    const customDirectivesMapLines = customDirectives.map(({ name }, index) => `  [${JSON.stringify(name)}, _directive${index}]`);
-    lines.push(`const customDirectives = new Map([
-${customDirectivesMapLines.join(`,
-`)}
-]);`);
-    lines.push(`const payload = { islands, options, customDirectives };`);
-  } else {
-    lines.push(`const payload = { islands, options };`);
-  }
-  lines.push(`export const { disconnect } = _islands(payload);`);
-  return lines.join(`
-`);
-}
-
-// src/index.ts
-import { fileURLToPath } from "node:url";
-
 // src/contract.ts
 var DEFAULT_DIRECTIVES = {
   visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
@@ -137,13 +104,17 @@ function buildIslandMap(payload) {
   return map;
 }
 
-// src/index.ts
-var VIRTUAL_ID = "vite-plugin-shopify-theme-islands/revive";
-var RESOLVED_ID = "\x00" + VIRTUAL_ID;
-var ISLAND_ID = "vite-plugin-shopify-theme-islands/island";
-var runtimePath = fileURLToPath(new URL("./runtime.js", import.meta.url));
-var islandPath = fileURLToPath(new URL("./island.js", import.meta.url));
+// src/config-policy.ts
 var PREFIX = "[vite-plugin-shopify-theme-islands]";
+function mergeDirectives(directives) {
+  return {
+    visible: { ...DEFAULT_DIRECTIVES.visible, ...directives?.visible },
+    idle: { ...DEFAULT_DIRECTIVES.idle, ...directives?.idle },
+    media: { ...DEFAULT_DIRECTIVES.media, ...directives?.media },
+    defer: { ...DEFAULT_DIRECTIVES.defer, ...directives?.defer },
+    interaction: { ...DEFAULT_DIRECTIVES.interaction, ...directives?.interaction }
+  };
+}
 function validateOptions(options, directives) {
   const customDefs = options.directives?.custom ?? [];
   if (Array.isArray(options.directories) && options.directories.length === 0) {
@@ -180,6 +151,93 @@ function validateOptions(options, directives) {
     seen.add(def.name);
   }
 }
+function resolveThemeIslandsPolicy(options = {}) {
+  const directives = mergeDirectives(options.directives);
+  validateOptions(options, directives);
+  const customDirectives = options.directives?.custom ?? [];
+  const debug = options.debug ?? false;
+  const runtime = {
+    directives,
+    debug,
+    ...options.retry !== undefined ? { retry: options.retry } : {},
+    ...options.directiveTimeout !== undefined ? { directiveTimeout: options.directiveTimeout } : {}
+  };
+  return {
+    plugin: {
+      directives,
+      customDirectives,
+      debug
+    },
+    runtime
+  };
+}
+
+// src/revive-module.ts
+function buildReviveModuleSource(params) {
+  const { runtimePath, directoryGlobs, islandPaths, customDirectives, reviveOptions } = params;
+  const directiveImportLines = customDirectives?.map(({ entrypoint }, index) => `import _directive${index} from ${JSON.stringify(entrypoint)};`) ?? [];
+  const globEntries = [
+    `{ ${directoryGlobs.map((glob) => `...import.meta.glob(${JSON.stringify(glob)})`).join(", ")} }`
+  ];
+  if (islandPaths?.length)
+    globEntries.push(`import.meta.glob(${JSON.stringify(islandPaths)})`);
+  const lines = [
+    ...directiveImportLines,
+    `import { revive as _islands } from ${JSON.stringify(runtimePath)};`,
+    `const islands = Object.assign({}, ${globEntries.join(", ")});`,
+    `const options = ${JSON.stringify(reviveOptions)};`
+  ];
+  if (customDirectives?.length) {
+    const customDirectivesMapLines = customDirectives.map(({ name }, index) => `  [${JSON.stringify(name)}, _directive${index}]`);
+    lines.push(`const customDirectives = new Map([
+${customDirectivesMapLines.join(`,
+`)}
+]);`);
+    lines.push(`const payload = { islands, options, customDirectives };`);
+  } else {
+    lines.push(`const payload = { islands, options };`);
+  }
+  lines.push(`export const { disconnect } = _islands(payload);`);
+  return lines.join(`
+`);
+}
+
+// src/revive-bootstrap.ts
+function createReviveBootstrapCompiler(ports, runtimePath) {
+  return {
+    async plan(input) {
+      const islandPaths = input.islandFiles.size > 0 ? ports.toLoadPaths(input.islandFiles, input.root) : null;
+      const customDirectives = input.customDirectives?.length ? await Promise.all(input.customDirectives.map(async ({ name, entrypoint }) => ({
+        name,
+        entrypoint: await ports.resolveEntrypoint(entrypoint)
+      }))) : null;
+      return {
+        runtimePath,
+        directoryGlobs: input.directories.map((dir) => dir + "**/*.{ts,js}"),
+        islandPaths,
+        customDirectives,
+        reviveOptions: input.reviveOptions
+      };
+    },
+    emit(plan) {
+      return buildReviveModuleSource({
+        runtimePath: plan.runtimePath,
+        directoryGlobs: plan.directoryGlobs,
+        islandPaths: plan.islandPaths,
+        customDirectives: plan.customDirectives?.length ? plan.customDirectives : undefined,
+        reviveOptions: plan.reviveOptions
+      });
+    }
+  };
+}
+
+// src/index.ts
+import { fileURLToPath } from "node:url";
+var VIRTUAL_ID = "vite-plugin-shopify-theme-islands/revive";
+var RESOLVED_ID = "\x00" + VIRTUAL_ID;
+var ISLAND_ID = "vite-plugin-shopify-theme-islands/island";
+var runtimePath = fileURLToPath(new URL("./runtime.js", import.meta.url));
+var islandPath = fileURLToPath(new URL("./island.js", import.meta.url));
 var defaultDirectories = ["/frontend/js/islands/"];
 function normalizeDir(dir) {
   return dir.endsWith("/") ? dir : dir + "/";
@@ -198,16 +256,9 @@ function resolveAliases(dirs, config) {
 }
 function shopifyThemeIslands(options = {}) {
   const rawDirs = (Array.isArray(options.directories) ? options.directories : [options.directories ?? defaultDirectories[0]]).map(normalizeDir);
-  const directives = {
-    visible: { ...DEFAULT_DIRECTIVES.visible, ...options.directives?.visible },
-    idle: { ...DEFAULT_DIRECTIVES.idle, ...options.directives?.idle },
-    media: { ...DEFAULT_DIRECTIVES.media, ...options.directives?.media },
-    defer: { ...DEFAULT_DIRECTIVES.defer, ...options.directives?.defer },
-    interaction: { ...DEFAULT_DIRECTIVES.interaction, ...options.directives?.interaction }
-  };
-  const clientDirectiveDefinitions = options.directives?.custom ?? [];
-  validateOptions(options, directives);
-  const debug = options.debug ?? false;
+  const policy = resolveThemeIslandsPolicy(options);
+  const { directives, customDirectives: clientDirectiveDefinitions, debug } = policy.plugin;
+  const { runtime: reviveOptions } = policy;
   const log = debug ? (...args) => console.log("[islands]", ...args) : () => {};
   let resolvedDirs = rawDirs;
   let root = process.cwd();
@@ -284,28 +335,24 @@ function shopifyThemeIslands(options = {}) {
     async load(id) {
       if (id !== RESOLVED_ID)
         return;
-      const directoryGlobs = resolvedDirs.map((dir) => dir + "**/*.{ts,js}");
-      const islandPaths = islandFiles.size > 0 ? getIslandPathsForLoad(islandFiles, root) : null;
-      const customDirectives = [];
-      for (const def of clientDirectiveDefinitions) {
-        const resolved = await this.resolve(def.entrypoint);
-        if (!resolved) {
-          throw new Error(`[vite-plugin-shopify-theme-islands] Cannot resolve custom directive entrypoint: "${def.entrypoint}"`);
-        }
-        customDirectives.push({ name: def.name, entrypoint: resolved.id });
-      }
-      return buildReviveModuleSource({
-        runtimePath,
-        directoryGlobs,
-        islandPaths,
-        customDirectives,
-        reviveOptions: {
-          directives,
-          debug,
-          retry: options.retry,
-          directiveTimeout: options.directiveTimeout
-        }
+      const compiler = createReviveBootstrapCompiler({
+        resolveEntrypoint: async (entrypoint) => {
+          const resolved = await this.resolve(entrypoint);
+          if (!resolved) {
+            throw new Error(`[vite-plugin-shopify-theme-islands] Cannot resolve custom directive entrypoint: "${entrypoint}"`);
+          }
+          return resolved.id;
+        },
+        toLoadPaths: getIslandPathsForLoad
+      }, runtimePath);
+      const plan = await compiler.plan({
+        root,
+        directories: resolvedDirs,
+        islandFiles,
+        customDirectives: clientDirectiveDefinitions,
+        reviveOptions
       });
+      return compiler.emit(plan);
     }
   };
 }

package/dist/options.d.ts

@@ -0,0 +1,64 @@
+import type { RetryConfig } from "./contract.js";
+/** Plugin option entry for registering a custom client directive. */
+export interface ClientDirectiveDefinition {
+    /** HTML attribute name, e.g. `'client:on-click'` */
+    name: string;
+    /** Path to the directive module (supports Vite aliases) */
+    entrypoint: string;
+}
+/** Shared directive configuration shape used by both the plugin and the runtime. */
+export interface DirectivesConfig {
+    /** Configuration for the `client:visible` directive (IntersectionObserver). */
+    visible?: {
+        /** HTML attribute name. Default: `'client:visible'` */
+        attribute?: string;
+        /** Passed to IntersectionObserver — loads islands before they scroll into view. Default: `'200px'` */
+        rootMargin?: string;
+        /** Passed to IntersectionObserver — ratio of element that must be visible. Default: `0` */
+        threshold?: number;
+    };
+    /** Configuration for the `client:idle` directive (requestIdleCallback). */
+    idle?: {
+        /** HTML attribute name. Default: `'client:idle'` */
+        attribute?: string;
+        /** Deadline (ms) passed to requestIdleCallback; also used as the setTimeout fallback delay. Default: `500` */
+        timeout?: number;
+    };
+    /** Configuration for the `client:media` directive (matchMedia). */
+    media?: {
+        /** HTML attribute name. Default: `'client:media'` */
+        attribute?: string;
+    };
+    /** Configuration for the `client:defer` directive (fixed setTimeout delay). */
+    defer?: {
+        /** HTML attribute name. Default: `'client:defer'` */
+        attribute?: string;
+        /** Fallback delay (ms) when the attribute has no value. Default: `3000` */
+        delay?: number;
+    };
+    /** Configuration for the `client:interaction` directive (mouseenter/touchstart/focusin). */
+    interaction?: {
+        /** HTML attribute name. Default: `'client:interaction'` */
+        attribute?: string;
+        /** DOM event names to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
+        events?: string[];
+    };
+    /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
+    custom?: ClientDirectiveDefinition[];
+}
+export interface ShopifyThemeIslandsOptions {
+    /** Directories to scan for island files. Accepts paths or Vite aliases. Default: `['/frontend/js/islands/']` */
+    directories?: string | string[];
+    /** Log discovered islands and generated virtual module. Default: `false` */
+    debug?: boolean;
+    /** Per-directive configuration. */
+    directives?: DirectivesConfig;
+    /** Automatic retry behaviour for failed island loads. */
+    retry?: RetryConfig;
+    /**
+     * Milliseconds before a custom directive that never calls `load()` is considered timed out.
+     * When exceeded, `islands:error` is dispatched and the island is abandoned.
+     * Default: `0` (disabled).
+     */
+    directiveTimeout?: number;
+}

package/dist/revive-bootstrap.d.ts

@@ -0,0 +1,31 @@
+import type { ReviveOptions } from "./contract.js";
+export interface ResolvedCustomDirective {
+    name: string;
+    entrypoint: string;
+}
+export interface ReviveBootstrapInputs {
+    root: string;
+    directories: string[];
+    islandFiles: Set<string>;
+    customDirectives?: Array<{
+        name: string;
+        entrypoint: string;
+    }>;
+    reviveOptions: ReviveOptions;
+}
+export interface ReviveBootstrapPlan {
+    runtimePath: string;
+    directoryGlobs: string[];
+    islandPaths: string[] | null;
+    customDirectives: ResolvedCustomDirective[] | null;
+    reviveOptions: ReviveOptions;
+}
+export interface ReviveBootstrapCompilerPorts {
+    resolveEntrypoint(entrypoint: string): Promise<string>;
+    toLoadPaths(islandFiles: Set<string>, root: string): string[];
+}
+export interface ReviveBootstrapCompiler {
+    plan(input: ReviveBootstrapInputs): Promise<ReviveBootstrapPlan>;
+    emit(plan: ReviveBootstrapPlan): string;
+}
+export declare function createReviveBootstrapCompiler(ports: ReviveBootstrapCompilerPorts, runtimePath: string): ReviveBootstrapCompiler;

package/dist/runtime-surface.d.ts

@@ -0,0 +1,20 @@
+import type { IslandErrorDetail, IslandLoadDetail } from "./contract.js";
+export interface RuntimeLogger {
+    note(msg: string): void;
+    flush(summary: string): void;
+}
+export interface RuntimeSurface {
+    dispatchLoad(detail: IslandLoadDetail): void;
+    dispatchError(detail: IslandErrorDetail): void;
+    onLoad(handler: (detail: IslandLoadDetail) => void): () => void;
+    onError(handler: (detail: IslandErrorDetail) => void): () => void;
+    createLogger(tagName: string, debug: boolean): RuntimeLogger;
+    beginReadyLog(islandCount: number, debug: boolean): () => void;
+}
+interface RuntimeSurfaceDeps {
+    target: Document;
+    console: Pick<Console, "log" | "groupCollapsed" | "groupEnd">;
+}
+export declare function createRuntimeSurface(deps: RuntimeSurfaceDeps): RuntimeSurface;
+export declare function getRuntimeSurface(): RuntimeSurface;
+export {};