vite-plugin-shopify-theme-islands 1.1.0 → 1.1.1

package/dist/contract.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Plugin ↔ Runtime contract (deep module).
+ *
+ * Single source of truth for the payload shape, key→tag derivation, and defaults.
+ * Plugin and runtime both depend on this module in-process.
+ */
+/** Loader function for one island chunk. */
+export type IslandLoader = () => Promise<unknown>;
+/** Directive config for the runtime (built-in + no plugin-only `custom` entrypoints). */
+export interface RuntimeDirectivesConfig {
+    visible?: {
+        attribute?: string;
+        rootMargin?: string;
+        threshold?: number;
+    };
+    idle?: {
+        attribute?: string;
+        timeout?: number;
+    };
+    media?: {
+        attribute?: string;
+    };
+    defer?: {
+        attribute?: string;
+        delay?: number;
+    };
+    interaction?: {
+        attribute?: string;
+        events?: string[];
+    };
+}
+/** Retry configuration. */
+export interface RetryConfig {
+    retries?: number;
+    delay?: number;
+}
+/** Options passed from plugin to runtime (subset of plugin options). */
+export interface ReviveOptions {
+    directives?: RuntimeDirectivesConfig;
+    debug?: boolean;
+    retry?: RetryConfig;
+}
+/** Options passed to a custom client directive function. */
+export interface ClientDirectiveOptions {
+    /** The matched attribute name, e.g. `'client:on-click'` */
+    name: string;
+    /** The attribute value; empty string if no value was set */
+    value: string;
+}
+/** Custom directive function at runtime (load, opts, element). */
+export type ClientDirective = (load: () => Promise<void>, options: ClientDirectiveOptions, el: HTMLElement) => void | Promise<void>;
+/** Event detail for the `islands:load` DOM event. */
+export interface IslandLoadDetail {
+    /** The custom element tag name, e.g. `'product-form'` */
+    tag: string;
+    /** Milliseconds from directive resolution to successful module load (chunk fetch time). */
+    duration: number;
+    /** Which attempt succeeded. 1 = first try, 2 = first retry, etc. */
+    attempt: number;
+}
+/** Event detail for the `islands:error` DOM event. */
+export interface IslandErrorDetail {
+    /** The custom element tag name, e.g. `'product-form'` */
+    tag: string;
+    /** The error thrown by the loader or custom directive */
+    error: unknown;
+    /** Which attempt failed. 1 = initial attempt, 2 = first retry, etc. */
+    attempt: number;
+}
+declare global {
+    interface DocumentEventMap {
+        "islands:load": CustomEvent<IslandLoadDetail>;
+        "islands:error": CustomEvent<IslandErrorDetail>;
+    }
+}
+/**
+ * Payload the plugin emits and the runtime consumes.
+ * Islands: glob key → loader (e.g. "/frontend/js/islands/product-form.ts" → loader).
+ * Custom directives: attribute name → directive implementation (resolved at build).
+ * Options may be partial; runtime uses normalizeReviveOptions() to fill defaults.
+ */
+export interface RevivePayload {
+    islands: Record<string, IslandLoader>;
+    options?: ReviveOptions;
+    customDirectives?: Map<string, ClientDirective>;
+}
+/** Fully resolved options; all directive and retry fields have defaults applied. */
+export interface NormalizedReviveOptions {
+    directives: {
+        visible: {
+            attribute: string;
+            rootMargin: string;
+            threshold: number;
+        };
+        idle: {
+            attribute: string;
+            timeout: number;
+        };
+        media: {
+            attribute: string;
+        };
+        defer: {
+            attribute: string;
+            delay: number;
+        };
+        interaction: {
+            attribute: string;
+            events: string[];
+        };
+    };
+    debug: boolean;
+    retry: {
+        retries: number;
+        delay: number;
+    };
+}
+/** Default directive config. Single source of truth for plugin merge and runtime normalization. */
+export declare const DEFAULT_DIRECTIVES: NormalizedReviveOptions["directives"];
+/**
+ * Applies default values for all runtime options.
+ * Single source of truth so plugin and runtime do not duplicate defaults.
+ */
+export declare function normalizeReviveOptions(options?: ReviveOptions): NormalizedReviveOptions;
+export type KeyToTagResult = {
+    tag: string;
+    skip?: boolean;
+};
+/**
+ * Maps a glob key (e.g. "/frontend/js/islands/product-form.ts") to a custom element tag.
+ * Return { tag, skip: true } to exclude this entry from the island map.
+ */
+export type KeyToTagFn = (key: string) => KeyToTagResult;
+/** Default: last path segment, extension stripped; skip (and warn) when tag has no hyphen. */
+export declare function defaultKeyToTag(key: string): KeyToTagResult;
+/**
+ * Builds tag → loader map from payload.
+ * Applies the default key→tag derivation and deduplicates by tag (first wins).
+ */
+export declare function buildIslandMap(payload: RevivePayload): Map<string, IslandLoader>;

package/dist/discovery.d.ts

@@ -0,0 +1,12 @@
+/** Matches .ts or .js extension. Exported for plugin transform/watch filters. */
+export declare const TS_JS_RE: RegExp;
+/** Matches the island mixin import. Exported for plugin transform/watch detection. */
+export declare const ISLAND_IMPORT_RE: RegExp;
+/** True if file is under any of the given absolute directory paths. */
+export declare function inDirectory(file: string, absDirs: string[]): boolean;
+/** Paths for load() virtual module: "/relative/to/root" form, forward slashes. */
+export declare function getIslandPathsForLoad(islandFiles: Set<string>, root: string): string[];
+/** Scan from root for files containing the island import; returns paths (not in absDirs). */
+export declare function discoverIslandFiles(root: string, absDirs: string[]): Set<string>;
+/** Tag names (filename without extension) for TS/JS files in a directory. Used for debug logging. */
+export declare function collectTagNames(dir: string): string[];

package/dist/index.d.ts

@@ -1,45 +1,7 @@
 import type { Plugin } from "vite";
 /** A function that triggers the load of an island module. */
 export type ClientDirectiveLoader = () => Promise<void>;
-/** Options passed to a custom client directive function. */
-export interface ClientDirectiveOptions {
-    /** The matched attribute name, e.g. `'client:on-click'` */
-    name: string;
-    /** The attribute value; empty string if no value was set */
-    value: string;
-}
-/**
- * A custom client directive function.
- *
- * Called by the runtime when a matching attribute is found on an island element.
- * The function is responsible for calling `load()` when the desired condition is met.
- *
- * @example
- * ```ts
- * // src/directives/hash.ts
- * import type { ClientDirective } from 'vite-plugin-shopify-theme-islands';
- *
- * const hashDirective: ClientDirective = (load, opts) => {
- *   const target = opts.value;
- *   if (location.hash === target) { load(); return; }
- *   window.addEventListener('hashchange', () => {
- *     if (location.hash === target) load();
- *   });
- * };
- *
- * export default hashDirective;
- * ```
- *
- * Register it in `vite.config.ts`:
- * ```ts
- * shopifyThemeIslands({
- *   directives: {
- *     custom: [{ name: 'client:hash', entrypoint: './src/directives/hash.ts' }],
- *   },
- * })
- * ```
- */
-export type ClientDirective = (load: ClientDirectiveLoader, options: ClientDirectiveOptions, el: HTMLElement) => void | 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'` */
@@ -87,41 +49,9 @@ export interface DirectivesConfig {
     /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
     custom?: ClientDirectiveDefinition[];
 }
-/** Runtime-facing directive configuration — omits plugin-only `custom` directives. */
-export type RuntimeDirectivesConfig = Omit<DirectivesConfig, "custom">;
-/** Retry configuration for failed island loads. */
-export interface RetryConfig {
-    /** Number of times to retry after the initial failure. Default: `0` (no auto-retry) */
-    retries?: number;
-    /** Base delay in ms between retries; doubles each attempt. Default: `1000` */
-    delay?: number;
-}
-/** Event detail for the `islands:load` DOM event. */
-export interface IslandLoadDetail {
-    /** The custom element tag name, e.g. `'product-form'` */
-    tag: string;
-    /** Milliseconds from directive resolution to successful module load (chunk fetch time). */
-    duration: number;
-    /** Which attempt succeeded. 1 = first try, 2 = first retry, etc. */
-    attempt: number;
-}
-/** Event detail for the `islands:error` DOM event. */
-export interface IslandErrorDetail {
-    /** The custom element tag name, e.g. `'product-form'` */
-    tag: string;
-    /** The error thrown by the loader or custom directive */
-    error: unknown;
-    /** Which attempt failed. 1 = initial attempt, 2 = first retry, etc. */
-    attempt: number;
-}
-declare global {
-    interface DocumentEventMap {
-        /** Fired after an island module resolves successfully. */
-        "islands:load": CustomEvent<IslandLoadDetail>;
-        /** Fired when an island load or custom directive fails. Fired on each retry attempt. */
-        "islands:error": CustomEvent<IslandErrorDetail>;
-    }
-}
+/** Event detail and runtime options (single source of truth in contract). */
+import type { RetryConfig } from "./contract.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[];
@@ -132,11 +62,4 @@ export interface ShopifyThemeIslandsOptions {
     /** Automatic retry behaviour for failed island loads. */
     retry?: RetryConfig;
 }
-export interface ReviveOptions {
-    directives?: RuntimeDirectivesConfig;
-    /** Log island activation and directive events to the console. Default: `false` */
-    debug?: boolean;
-    /** Automatic retry behaviour for failed island loads. */
-    retry?: RetryConfig;
-}
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;

package/dist/index.js

@@ -1,15 +1,147 @@
 // src/index.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { join as join2, relative as relative2 } from "node:path";
+
+// src/discovery.ts
 import { readFileSync, readdirSync } from "node:fs";
-import { join, relative } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
+var TS_JS_RE = /\.(ts|js)$/;
+var SKIP_DIRS = new Set(["node_modules", "dist", "build", "public", "assets", ".cache"]);
+var ISLAND_IMPORT_RE = /from\s+['"]vite-plugin-shopify-theme-islands\/island['"]/;
+function inDirectory(file, absDirs) {
+  const resolvedFile = resolve(file);
+  return absDirs.some((dir) => {
+    const rel = relative(resolve(dir), resolvedFile);
+    return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+  });
+}
+function getIslandPathsForLoad(islandFiles, root) {
+  return [...islandFiles].map((file) => "/" + relative(root, file).replace(/\\/g, "/"));
+}
+function walkDir(dir, visitor) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name))
+      continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory())
+      walkDir(full, visitor);
+    else if (TS_JS_RE.test(entry.name))
+      visitor(entry.name, full);
+  }
+}
+function discoverIslandFiles(root, absDirs) {
+  const found = new Set;
+  walkDir(root, (_, full) => {
+    try {
+      if (ISLAND_IMPORT_RE.test(readFileSync(full, "utf-8")))
+        found.add(full);
+    } catch {}
+  });
+  for (const f of [...found])
+    if (inDirectory(f, absDirs))
+      found.delete(f);
+  return found;
+}
+function collectTagNames(dir) {
+  const names = [];
+  walkDir(dir, (name) => names.push(name.replace(TS_JS_RE, "")));
+  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 },
+  idle: { attribute: "client:idle", timeout: 500 },
+  media: { attribute: "client:media" },
+  defer: { attribute: "client:defer", delay: 3000 },
+  interaction: {
+    attribute: "client:interaction",
+    events: ["mouseenter", "touchstart", "focusin"]
+  }
+};
+var DEFAULT_RETRY = { retries: 0, delay: 1000 };
+function normalizeReviveOptions(options) {
+  const d = DEFAULT_DIRECTIVES;
+  const r = DEFAULT_RETRY;
+  const dir = options?.directives;
+  return {
+    directives: {
+      visible: { ...d.visible, ...dir?.visible },
+      idle: { ...d.idle, ...dir?.idle },
+      media: { ...d.media, ...dir?.media },
+      defer: { ...d.defer, ...dir?.defer },
+      interaction: { ...d.interaction, ...dir?.interaction }
+    },
+    debug: options?.debug ?? false,
+    retry: { ...r, ...options?.retry }
+  };
+}
+var basename = (key) => key.split("/").pop() ?? key;
+function defaultKeyToTag(key) {
+  const filename = basename(key);
+  const tag = filename.replace(/\.(ts|js)$/, "");
+  const skip = !tag.includes("-");
+  if (skip && tag)
+    console.warn(`[islands] Skipping "${filename}" — filename must contain a hyphen to match a valid custom element tag (e.g. rename to "${tag}-island.ts")`);
+  return { tag, skip };
+}
+function buildIslandMap(payload) {
+  const map = new Map;
+  for (const [key, loader] of Object.entries(payload.islands)) {
+    const { tag, skip } = defaultKeyToTag(key);
+    if (skip)
+      continue;
+    if (!map.has(tag))
+      map.set(tag, loader);
+  }
+  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));
-var ISLAND_IMPORT_RE = /from\s+['"]vite-plugin-shopify-theme-islands\/island['"]/;
-var TS_JS_RE = /\.(ts|js)$/;
-var SKIP_DIRS = new Set(["node_modules", "dist", "build", "public", "assets", ".cache"]);
 var PREFIX = "[vite-plugin-shopify-theme-islands]";
 function validateOptions(options, directives) {
   const customDefs = options.directives?.custom ?? [];
@@ -47,19 +179,7 @@ function validateOptions(options, directives) {
     seen.add(def.name);
   }
 }
-var defaults = {
-  directories: ["/frontend/js/islands/"],
-  directives: {
-    visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
-    idle: { attribute: "client:idle", timeout: 500 },
-    media: { attribute: "client:media" },
-    defer: { attribute: "client:defer", delay: 3000 },
-    interaction: {
-      attribute: "client:interaction",
-      events: ["mouseenter", "touchstart", "focusin"]
-    }
-  }
-};
+var defaultDirectories = ["/frontend/js/islands/"];
 function normalizeDir(dir) {
   return dir.endsWith("/") ? dir : dir + "/";
 }
@@ -75,42 +195,14 @@ function resolveAliases(dirs, config) {
     return dir;
   });
 }
-function walkDir(dir, visitor) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name))
-      continue;
-    const full = join(dir, entry.name);
-    if (entry.isDirectory())
-      walkDir(full, visitor);
-    else if (TS_JS_RE.test(entry.name))
-      visitor(entry.name, full);
-  }
-}
-function collectTagNames(dir, names) {
-  walkDir(dir, (name) => names.push(name.replace(TS_JS_RE, "")));
-}
-function scanForIslandFiles(dir, found) {
-  walkDir(dir, (_, full) => {
-    try {
-      if (ISLAND_IMPORT_RE.test(readFileSync(full, "utf-8")))
-        found.add(full);
-    } catch {}
-  });
-}
 function shopifyThemeIslands(options = {}) {
-  const rawDirs = (Array.isArray(options.directories) ? options.directories : [options.directories ?? defaults.directories[0]]).map(normalizeDir);
+  const rawDirs = (Array.isArray(options.directories) ? options.directories : [options.directories ?? defaultDirectories[0]]).map(normalizeDir);
   const directives = {
-    visible: { ...defaults.directives.visible, ...options.directives?.visible },
-    idle: { ...defaults.directives.idle, ...options.directives?.idle },
-    media: { ...defaults.directives.media, ...options.directives?.media },
-    defer: { ...defaults.directives.defer, ...options.directives?.defer },
-    interaction: { ...defaults.directives.interaction, ...options.directives?.interaction }
+    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);
@@ -121,37 +213,33 @@ function shopifyThemeIslands(options = {}) {
   let absDirs = rawDirs;
   const islandFiles = new Set;
   let scanned = false;
-  const inDirectory = (file) => absDirs.some((dir) => file.startsWith(dir));
   return {
     name: "vite-plugin-shopify-theme-islands",
     enforce: "pre",
     configResolved(config) {
       root = config.root;
       resolvedDirs = resolveAliases(rawDirs, config);
-      absDirs = resolvedDirs.map((d) => d.startsWith(root) ? d : join(root, d.replace(/^\//, "")));
+      absDirs = resolvedDirs.map((d) => d.startsWith(root) ? d : join2(root, d.replace(/^\//, "")));
     },
     buildStart() {
       if (scanned)
         return;
       scanned = true;
       const t0 = performance.now();
-      scanForIslandFiles(root, islandFiles);
-      const scanMs = (performance.now() - t0).toFixed(1);
-      for (const f of islandFiles)
-        if (inDirectory(f))
-          islandFiles.delete(f);
+      const initial = discoverIslandFiles(root, absDirs);
+      islandFiles.clear();
+      initial.forEach((f) => islandFiles.add(f));
       if (debug) {
+        const scanMs = (performance.now() - t0).toFixed(1);
         log(`Scanned in ${scanMs}ms`);
         log("Scanning directories:", resolvedDirs.map((d) => d + "**/*.{ts,js}").join(", "));
-        const dirNames = [];
-        for (const dir of absDirs)
-          collectTagNames(dir, dirNames);
+        const dirNames = absDirs.flatMap((dir) => collectTagNames(dir));
         if (dirNames.length)
           log(`Found ${dirNames.length} directory island(s): [${dirNames.join(", ")}]`);
         if (islandFiles.size) {
           log(`Found ${islandFiles.size} island file(s) via mixin import:`);
           for (const f of islandFiles)
-            log(" ", relative(root, f));
+            log(" ", relative2(root, f));
         }
         log("Directives:", directives);
       }
@@ -159,12 +247,12 @@ function shopifyThemeIslands(options = {}) {
     transform(code, id) {
       if (!TS_JS_RE.test(id))
         return;
-      if (code.includes("shopify-theme-islands/island") && ISLAND_IMPORT_RE.test(code) && !inDirectory(id)) {
+      if (code.includes("shopify-theme-islands/island") && ISLAND_IMPORT_RE.test(code) && !inDirectory(id, absDirs)) {
         islandFiles.add(id);
-        log("Detected island:", relative(root, id));
+        log("Detected island:", relative2(root, id));
       } else {
         if (islandFiles.delete(id))
-          log("Removed island:", relative(root, id));
+          log("Removed island:", relative2(root, id));
       }
     },
     watchChange(id, { event }) {
@@ -172,16 +260,16 @@ function shopifyThemeIslands(options = {}) {
         return;
       if (event === "delete") {
         if (islandFiles.delete(id))
-          log("Removed island (deleted):", relative(root, id));
+          log("Removed island (deleted):", relative2(root, id));
       } else {
         try {
-          const content = readFileSync(id, "utf-8");
-          if (ISLAND_IMPORT_RE.test(content) && !inDirectory(id)) {
+          const content = readFileSync2(id, "utf-8");
+          if (ISLAND_IMPORT_RE.test(content) && !inDirectory(id, absDirs)) {
             islandFiles.add(id);
-            log("Detected island (watchChange):", relative(root, id));
+            log("Detected island (watchChange):", relative2(root, id));
           } else {
             if (islandFiles.delete(id))
-              log("Removed island (watchChange):", relative(root, id));
+              log("Removed island (watchChange):", relative2(root, id));
           }
         } catch {}
       }
@@ -195,38 +283,23 @@ function shopifyThemeIslands(options = {}) {
     async load(id) {
       if (id !== RESOLVED_ID)
         return;
-      const globs = resolvedDirs.map((dir) => `...import.meta.glob(${JSON.stringify(dir + "**/*.{ts,js}")})`);
-      const islandPaths = islandFiles.size ? [...islandFiles].map((file) => "/" + relative(root, file).replace(/\\/g, "/")) : null;
-      const islandsEntries = [`{ ${globs.join(", ")} }`];
-      if (islandPaths)
-        islandsEntries.push(`import.meta.glob(${JSON.stringify(islandPaths)})`);
-      const directiveImports = [];
-      const mapEntries = [];
-      for (const [i, def] of clientDirectiveDefinitions.entries()) {
+      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}"`);
         }
-        directiveImports.push(`import _directive${i} from ${JSON.stringify(resolved.id)};`);
-        mapEntries.push(`  [${JSON.stringify(def.name)}, _directive${i}]`);
+        customDirectives.push({ name: def.name, entrypoint: resolved.id });
       }
-      const lines = [
-        ...directiveImports,
-        `import { revive as _islands } from ${JSON.stringify(runtimePath)};`,
-        `const islands = Object.assign({}, ${islandsEntries.join(", ")});`,
-        `const options = ${JSON.stringify({ directives, debug, retry: options.retry })};`
-      ];
-      if (mapEntries.length) {
-        lines.push(`const customDirectives = new Map([
-${mapEntries.join(`,
-`)}
-]);`);
-        lines.push(`export const { disconnect } = _islands(islands, options, customDirectives);`);
-      } else {
-        lines.push(`export const { disconnect } = _islands(islands, options);`);
-      }
-      return lines.join(`
-`);
+      return buildReviveModuleSource({
+        runtimePath,
+        directoryGlobs,
+        islandPaths,
+        customDirectives,
+        reviveOptions: { directives, debug, retry: options.retry }
+      });
     }
   };
 }

package/dist/revive-module.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Virtual revive module source generator.
+ * Single place for "what the client receives" when loading the revive virtual module.
+ */
+import type { ReviveOptions } from "./contract.js";
+export interface BuildReviveModuleSourceParams {
+    /** Resolved path to the runtime module (revive export). */
+    runtimePath: string;
+    /** import.meta.glob expressions for configured island directories. */
+    directoryGlobs: string[];
+    /** Additional discovered island paths outside the configured directories. */
+    islandPaths?: string[] | null;
+    /** Resolved custom directive modules keyed by attribute name. */
+    customDirectives?: Array<{
+        name: string;
+        entrypoint: string;
+    }>;
+    /** Options object passed to revive (JSON-serialized in output). */
+    reviveOptions: ReviveOptions;
+}
+/**
+ * Builds the source code for the virtual revive module.
+ * Used by the plugin's load() so the emitted shape is defined and testable in one place.
+ */
+export declare function buildReviveModuleSource(params: BuildReviveModuleSourceParams): string;

package/dist/runtime.d.ts

@@ -13,7 +13,11 @@
  * Directives can be combined; all conditions must be met before loading.
  * A MutationObserver re-runs the same logic for elements added dynamically.
  */
-import type { ClientDirective, ReviveOptions } from "./index.js";
-export declare function revive(islands: Record<string, () => Promise<unknown>>, options?: ReviveOptions, customDirectives?: Map<string, ClientDirective>): {
+import { type ClientDirective, type IslandLoader, type ReviveOptions, type RevivePayload } from "./contract.js";
+export declare function revive(payload: RevivePayload): {
+    disconnect: () => void;
+};
+/** @deprecated Pass a RevivePayload object instead. Will be removed in v2.0. */
+export declare function revive(islands: Record<string, IslandLoader>, options?: ReviveOptions, customDirectives?: Map<string, ClientDirective>): {
     disconnect: () => void;
 };

package/dist/runtime.js

@@ -1,3 +1,52 @@
+// src/contract.ts
+var DEFAULT_DIRECTIVES = {
+  visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
+  idle: { attribute: "client:idle", timeout: 500 },
+  media: { attribute: "client:media" },
+  defer: { attribute: "client:defer", delay: 3000 },
+  interaction: {
+    attribute: "client:interaction",
+    events: ["mouseenter", "touchstart", "focusin"]
+  }
+};
+var DEFAULT_RETRY = { retries: 0, delay: 1000 };
+function normalizeReviveOptions(options) {
+  const d = DEFAULT_DIRECTIVES;
+  const r = DEFAULT_RETRY;
+  const dir = options?.directives;
+  return {
+    directives: {
+      visible: { ...d.visible, ...dir?.visible },
+      idle: { ...d.idle, ...dir?.idle },
+      media: { ...d.media, ...dir?.media },
+      defer: { ...d.defer, ...dir?.defer },
+      interaction: { ...d.interaction, ...dir?.interaction }
+    },
+    debug: options?.debug ?? false,
+    retry: { ...r, ...options?.retry }
+  };
+}
+var basename = (key) => key.split("/").pop() ?? key;
+function defaultKeyToTag(key) {
+  const filename = basename(key);
+  const tag = filename.replace(/\.(ts|js)$/, "");
+  const skip = !tag.includes("-");
+  if (skip && tag)
+    console.warn(`[islands] Skipping "${filename}" — filename must contain a hyphen to match a valid custom element tag (e.g. rename to "${tag}-island.ts")`);
+  return { tag, skip };
+}
+function buildIslandMap(payload) {
+  const map = new Map;
+  for (const [key, loader] of Object.entries(payload.islands)) {
+    const { tag, skip } = defaultKeyToTag(key);
+    if (skip)
+      continue;
+    if (!map.has(tag))
+      map.set(tag, loader);
+  }
+  return map;
+}
+
 // src/runtime.ts
 var dispatch = (name, detail) => document.dispatchEvent(new CustomEvent(name, { detail }));
 function media(query) {
@@ -56,35 +105,27 @@ function idle(timeout) {
   });
 }
 var noop = (..._) => {};
-function revive(islands, options, customDirectives) {
-  const attrVisible = options?.directives?.visible?.attribute ?? "client:visible";
-  const attrMedia = options?.directives?.media?.attribute ?? "client:media";
-  const attrIdle = options?.directives?.idle?.attribute ?? "client:idle";
-  const attrDefer = options?.directives?.defer?.attribute ?? "client:defer";
-  const attrInteraction = options?.directives?.interaction?.attribute ?? "client:interaction";
-  const interactionEvents = options?.directives?.interaction?.events ?? [
-    "mouseenter",
-    "touchstart",
-    "focusin"
-  ];
-  const rootMargin = options?.directives?.visible?.rootMargin ?? "200px";
-  const threshold = options?.directives?.visible?.threshold ?? 0;
-  const idleTimeout = options?.directives?.idle?.timeout ?? 500;
-  const deferDelay = options?.directives?.defer?.delay ?? 3000;
-  const debug = options?.debug ?? false;
-  const retries = options?.retry?.retries ?? 0;
-  const retryDelay = options?.retry?.delay ?? 1000;
-  const islandMap = new Map;
-  for (const [key, loader] of Object.entries(islands)) {
-    const filename = key.split("/").pop();
-    const tagName = filename.replace(/\.(ts|js)$/, "");
-    if (!tagName.includes("-")) {
-      console.warn(`[islands] Skipping "${filename}" — filename must contain a hyphen to match a valid custom element tag name (e.g. rename to "${tagName}-island.ts")`);
-      continue;
-    }
-    if (!islandMap.has(tagName))
-      islandMap.set(tagName, loader);
-  }
+function isRevivePayload(v) {
+  return typeof v === "object" && v !== null && "islands" in v && !Array.isArray(v);
+}
+function revive(islandsOrPayload, options, customDirectives) {
+  const payload = isRevivePayload(islandsOrPayload) ? islandsOrPayload : { islands: islandsOrPayload, options, customDirectives };
+  const opts = normalizeReviveOptions(payload.options);
+  const islandMap = buildIslandMap(payload);
+  const resolvedDirectives = payload.customDirectives;
+  const attrVisible = opts.directives.visible.attribute;
+  const attrMedia = opts.directives.media.attribute;
+  const attrIdle = opts.directives.idle.attribute;
+  const attrDefer = opts.directives.defer.attribute;
+  const attrInteraction = opts.directives.interaction.attribute;
+  const interactionEvents = opts.directives.interaction.events;
+  const rootMargin = opts.directives.visible.rootMargin;
+  const threshold = opts.directives.visible.threshold;
+  const idleTimeout = opts.directives.idle.timeout;
+  const deferDelay = opts.directives.defer.delay;
+  const debug = opts.debug;
+  const retries = opts.retry.retries;
+  const retryDelay = opts.retry.delay;
   const queued = new Set;
   let initDone = false;
   const loaded = new Set;
@@ -116,8 +157,8 @@ function revive(islands, options, customDirectives) {
       pushAttr(attrIdle, el.getAttribute(attrIdle));
       pushAttr(attrDefer, el.getAttribute(attrDefer));
       pushAttr(attrInteraction, el.getAttribute(attrInteraction));
-      if (customDirectives?.size) {
-        for (const a of customDirectives.keys()) {
+      if (resolvedDirectives?.size) {
+        for (const a of resolvedDirectives.keys()) {
           if (el.hasAttribute(a))
             parts.push(a);
         }
@@ -218,9 +259,9 @@ function revive(islands, options, customDirectives) {
       retryCount.delete(tagName);
       queued.delete(tagName);
     };
-    if (customDirectives?.size) {
+    if (resolvedDirectives?.size) {
       const matched = [];
-      for (const [attrName, directiveFn] of customDirectives) {
+      for (const [attrName, directiveFn] of resolvedDirectives) {
         const value = el.getAttribute(attrName);
         if (value !== null)
           matched.push([attrName, directiveFn, value]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-shopify-theme-islands",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Vite plugin for island architecture in Shopify themes",
   "type": "module",
   "packageManager": "bun@1.3.10",

package/skills/custom-directives/SKILL.md

@@ -8,8 +8,9 @@ description: >
   Custom directives run after all built-in conditions resolve.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.0"
+library_version: "1.1.1"
 sources:
+  - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
 ---
@@ -96,7 +97,7 @@ const networkDirective: ClientDirective = async (load, _opts, el) => {
 };
 ```
 
-The directive function can be async. Unhandled rejections fire `islands:error` on the element.
+The directive function can be async. Unhandled rejections fire the document-level `islands:error` event, so `onIslandError()` observers still see directive failures.
 
 ### AND-latch with multiple matching directives
 
@@ -180,6 +181,38 @@ With two matching custom directives, `remaining = 2`. Each `load()` call decreme
 
 Source: src/runtime.ts — `let remaining = matched.length`
 
+### HIGH Duplicate custom directive names or collisions with built-ins fail plugin setup
+
+Wrong:
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    visible: { attribute: "data:visible" },
+    custom: [
+      { name: "client:hash", entrypoint: "./src/directives/hash.ts" },
+      { name: "data:visible", entrypoint: "./src/directives/other.ts" },
+      { name: "client:hash", entrypoint: "./src/directives/duplicate.ts" },
+    ],
+  },
+});
+```
+
+Correct:
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    visible: { attribute: "data:visible" },
+    custom: [{ name: "client:hash", entrypoint: "./src/directives/hash.ts" }],
+  },
+});
+```
+
+Custom directive names must be unique and must not collide with any built-in directive name, including renamed built-ins.
+
+Source: src/index.ts — validateOptions duplicate and built-in conflict checks
+
 ### HIGH Entrypoint path missing `./` prefix
 
 Wrong:
@@ -200,7 +233,7 @@ Correct:
 }
 ```
 
-Vite's resolver may fail to locate the file without the `./` relative prefix. The plugin throws a build error if the entrypoint cannot be resolved.
+Custom directive entrypoints are resolved through Vite. Relative local files should usually use `./...`; unresolved entrypoints fail the build.
 
 Source: src/index.ts — `this.resolve(def.entrypoint)` throws on null
 

package/skills/directives/SKILL.md

@@ -5,10 +5,11 @@ description: >
   client:media (matchMedia query), client:idle (requestIdleCallback),
   client:defer (setTimeout delay), client:interaction (mouseenter/touchstart/focusin).
   Directives resolve sequentially — visible → media → idle → defer → interaction → custom.
-  Per-element value overrides. Empty client:media warning.
+  Per-element value overrides. Empty client:media warning. Whitespace-only
+  client:interaction values warn and fall back to default events.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.0"
+library_version: "1.1.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
@@ -96,7 +97,9 @@ An empty `client:defer` attribute is NOT zero — it falls back to the configure
 <cart-flyout client:interaction="mouseenter"></cart-flyout>
 ```
 
-An empty `client:interaction` attribute silently uses the configured default events — no warning is emitted (unlike `client:media`).
+An empty `client:interaction` attribute uses the configured default events with no warning. A whitespace-only value such as `client:interaction="   "` emits a warning and still falls back to the default events.
+
+Source: src/runtime.ts — interaction token parsing and fallback warning
 
 ### Changing built-in directive defaults globally
 
@@ -131,6 +134,28 @@ An empty `client:media` value emits a console warning and skips the media check
 
 Source: src/runtime.ts — `if (query === "")` branch
 
+### MEDIUM Whitespace-only `client:interaction` value warns and falls back
+
+Wrong:
+
+```html
+<cart-flyout client:interaction="   "></cart-flyout>
+```
+
+Correct:
+
+```html
+<!-- Either omit the value entirely for defaults... -->
+<cart-flyout client:interaction></cart-flyout>
+
+<!-- ...or provide explicit event names -->
+<cart-flyout client:interaction="mouseenter focusin"></cart-flyout>
+```
+
+Whitespace-only values are not treated the same as an empty attribute. The runtime warns and falls back to the configured default events.
+
+Source: src/runtime.ts — `interactionAttr.split(/\s+/).filter(Boolean)`
+
 ### HIGH Multiple directives are AND, not OR
 
 Wrong assumption:

package/skills/lifecycle/SKILL.md

@@ -10,10 +10,10 @@ description: >
   navigation teardown.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.0"
+library_version: "1.1.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/events.ts
-  - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
 ---
 
@@ -97,7 +97,7 @@ document.addEventListener("islands:load", (e) => {
 });
 ```
 
-The `DocumentEventMap` augmentation is declared in the main package's `index.ts`. It is only in scope when the import is present in the same tsconfig compilation.
+The `DocumentEventMap` augmentation is declared in `contract.ts` and re-exported via the main package entry. It is only in scope when the import is present in the same tsconfig compilation.
 
 ## Common Mistakes
 

package/skills/setup/SKILL.md

@@ -9,9 +9,10 @@ description: >
   directories, or enabling retry.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.0"
+library_version: "1.1.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
 ---
 
 ## Setup
@@ -195,7 +196,7 @@ shopifyThemeIslands({
 
 `directives` accepts only `visible`, `idle`, `media`, `defer`, `interaction`, and `custom`. `retry` at `directives.retry` is silently ignored.
 
-Source: src/index.ts:ShopifyThemeIslandsOptions
+Source: src/index.ts — ShopifyThemeIslandsOptions
 
 ### HIGH Wrong key name for retry count
 
@@ -214,4 +215,4 @@ shopifyThemeIslands({ retry: { retries: 3 } });
 
 Unknown keys are silently ignored. The correct field is `retries`.
 
-Source: src/index.ts:RetryConfig
+Source: src/contract.ts — RetryConfig

package/skills/writing-islands/SKILL.md

@@ -8,9 +8,11 @@ description: >
   base class, and child island cascade behaviour.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.0"
+library_version: "1.1.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/discovery.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
 ---
 
@@ -119,7 +121,7 @@ customElements.define("search-bar", SearchBar);
 
 Without the `Island` import the plugin cannot detect the file. The element appears in the DOM but the module is never lazy-loaded.
 
-Source: src/index.ts — ISLAND_IMPORT_RE, scanForIslandFiles
+Source: src/discovery.ts — ISLAND_IMPORT_RE, discoverIslandFiles
 
 ### HIGH Missing `customElements.define` call
 
@@ -148,6 +150,31 @@ The plugin loads the module but the custom element never upgrades without `custo
 
 Source: src/runtime.ts — loader() is called but registration is the file's responsibility
 
+### HIGH Filename without a hyphen is skipped as an invalid custom element tag
+
+Wrong:
+
+```ts
+// frontend/js/islands/cartdrawer.ts
+class CartDrawer extends HTMLElement {}
+customElements.define("cartdrawer", CartDrawer);
+```
+
+Correct:
+
+```ts
+// frontend/js/islands/cart-drawer.ts
+class CartDrawer extends HTMLElement {}
+
+if (!customElements.get("cart-drawer")) {
+  customElements.define("cart-drawer", CartDrawer);
+}
+```
+
+The runtime derives the tag name from the filename and skips non-hyphenated names with a warning. Use valid custom element tag names in filenames.
+
+Source: src/contract.ts — defaultKeyToTag()
+
 ### MEDIUM Child island activates before parent is ready
 
 Wrong assumption: