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

package/README.md

@@ -306,6 +306,7 @@ Built-in directives always run first. A custom directive is only invoked after a
 ```
 
 The custom directive owns the `load()` call — the built-in chain never calls it directly when a custom directive is matched.
+If a custom directive throws or returns a rejected promise, the runtime dispatches `islands:error` and abandons that island activation attempt.
 
 Multiple custom directives on the same element use AND semantics — the island loads only once all matched directives have called `load()`. For example, given two registered custom directives `client:hash` and `client:network`:
 
@@ -316,14 +317,27 @@ Multiple custom directives on the same element use AND semantics — the island
 </product-reviews>
 ```
 
+#### Timeout guard
+
+By default, a custom directive that never calls `load()` silently keeps the island unloaded forever. Set `directiveTimeout` to fire `islands:error` and abandon the island if the directive hasn't resolved within the given window:
+
+```ts
+shopifyThemeIslands({
+  directiveTimeout: 5000, // abandon after 5 seconds
+});
+```
+
+This is useful during development to surface directives that hang due to bugs, or in production to ensure broken directives don't silently degrade the experience.
+
 ## Configuration
 
-| Option        | Type                 | Default                     | Description                                                                        |
-| ------------- | -------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
-| `directories` | `string \| string[]` | `['/frontend/js/islands/']` | Directories to scan for island files. Accepts Vite aliases.                        |
-| `directives`  | `object`             | see below                   | Per-directive configuration — attribute names, timing options, and custom entries. |
-| `retry`       | `object`             | —                           | Automatic retry behaviour for failed island loads. See [Retries](#retries).        |
-| `debug`       | `boolean`            | `false`                     | Log discovered islands at build time and directive events in the browser console.  |
+| Option             | Type                 | Default                     | Description                                                                        |
+| ------------------ | -------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
+| `directories`      | `string \| string[]` | `['/frontend/js/islands/']` | Directories to scan for island files. Accepts Vite aliases.                        |
+| `directives`       | `object`             | see below                   | Per-directive configuration — attribute names, timing options, and custom entries. |
+| `retry`            | `object`             | —                           | Automatic retry behaviour for failed island loads. See [Retries](#retries).        |
+| `debug`            | `boolean`            | `false`                     | Log discovered islands at build time and directive events in the browser console.  |
+| `directiveTimeout` | `number`             | `0` (disabled)              | Milliseconds before a custom directive that never calls `load()` is considered timed out. Fires `islands:error` and abandons the island. |
 
 ### Directive defaults
 
@@ -441,7 +455,7 @@ document.addEventListener("islands:load", (e) => {
 | Event           | Detail properties              | When it fires                                              |
 | --------------- | ------------------------------ | ---------------------------------------------------------- |
 | `islands:load`  | `tag`, `duration`, `attempt`   | Island module resolves successfully                        |
-| `islands:error` | `tag`, `error`, `attempt`      | Load or custom directive fails (alongside `console.error`) |
+| `islands:error` | `tag`, `error`, `attempt`      | Load fails, custom directive throws or rejects, or `directiveTimeout` expires (alongside `console.error`) |
 
 `islands:error` fires on each retry attempt, not just the final failure. Multiple independent listeners are supported — each receives its own event.
 

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/contract.d.ts

@@ -39,6 +39,12 @@ export interface ReviveOptions {
     directives?: RuntimeDirectivesConfig;
     debug?: boolean;
     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;
 }
 /** Options passed to a custom client directive function. */
 export interface ClientDirectiveOptions {
@@ -113,6 +119,7 @@ export interface NormalizedReviveOptions {
         retries: number;
         delay: number;
     };
+    directiveTimeout: number;
 }
 /** Default directive config. Single source of truth for plugin merge and runtime normalization. */
 export declare const DEFAULT_DIRECTIVES: NormalizedReviveOptions["directives"];

package/dist/index.d.ts

@@ -1,65 +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;
-}
 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 },
@@ -112,7 +79,8 @@ function normalizeReviveOptions(options) {
       interaction: { ...d.interaction, ...dir?.interaction }
     },
     debug: options?.debug ?? false,
-    retry: { ...r, ...options?.retry }
+    retry: { ...r, ...options?.retry },
+    directiveTimeout: options?.directiveTimeout ?? 0
   };
 }
 var basename = (key) => key.split("/").pop() ?? key;
@@ -136,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) {
@@ -179,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 + "/";
@@ -197,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();
@@ -283,23 +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 }
+      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.js

@@ -23,7 +23,8 @@ function normalizeReviveOptions(options) {
       interaction: { ...d.interaction, ...dir?.interaction }
     },
     debug: options?.debug ?? false,
-    retry: { ...r, ...options?.retry }
+    retry: { ...r, ...options?.retry },
+    directiveTimeout: options?.directiveTimeout ?? 0
   };
 }
 var basename = (key) => key.split("/").pop() ?? key;
@@ -58,39 +59,49 @@ function media(query) {
       m.addEventListener("change", () => resolve(), { once: true });
   });
 }
-function visible(element, rootMargin, threshold, pending) {
+function visible(element, rootMargin, threshold, watch) {
   return new Promise((resolve, reject) => {
+    let settled = false;
+    let unwatch = () => {};
+    const finish = (done) => {
+      if (settled)
+        return;
+      settled = true;
+      unwatch();
+      io.disconnect();
+      done();
+    };
     const io = new IntersectionObserver(([entry]) => {
       if (entry.isIntersecting) {
-        io.disconnect();
-        pending.delete(element);
-        resolve();
+        finish(resolve);
       }
     }, { rootMargin, threshold });
     io.observe(element);
-    pending.set(element, () => {
-      io.disconnect();
-      reject();
-    });
+    unwatch = watch(element, () => finish(() => reject(new DirectiveCancelledError)));
   });
 }
-function interaction(element, events, pending) {
+function interaction(element, events, watch) {
   return new Promise((resolve, reject) => {
+    let settled = false;
+    let unwatch = () => {};
     const cleanup = () => {
       for (const name of events)
         element.removeEventListener(name, handler);
-      pending.delete(element);
     };
-    const handler = () => {
+    const finish = (done) => {
+      if (settled)
+        return;
+      settled = true;
+      unwatch();
       cleanup();
-      resolve();
+      done();
+    };
+    const handler = () => {
+      finish(resolve);
     };
     for (const name of events)
       element.addEventListener(name, handler);
-    pending.set(element, () => {
-      cleanup();
-      reject();
-    });
+    unwatch = watch(element, () => finish(() => reject(new DirectiveCancelledError)));
   });
 }
 function defer(ms) {
@@ -104,10 +115,103 @@ function idle(timeout) {
       setTimeout(resolve, timeout);
   });
 }
-var noop = (..._) => {};
+var SILENT_LOGGER = {
+  note() {},
+  flush() {}
+};
+function createIslandLogger(tagName, debug) {
+  if (!debug)
+    return SILENT_LOGGER;
+  const msgs = [];
+  return {
+    note(msg) {
+      msgs.push(msg);
+    },
+    flush(summary) {
+      if (msgs.length === 0) {
+        console.log("[islands]", `<${tagName}> ${summary}`);
+      } else {
+        console.groupCollapsed(`[islands] <${tagName}> ${summary}`);
+        for (const m of msgs)
+          console.log(m);
+        console.groupEnd();
+      }
+      msgs.length = 0;
+    }
+  };
+}
+
+class DirectiveCancelledError extends Error {
+  constructor() {
+    super("[islands] directive cancelled: element removed from DOM");
+    this.name = "DirectiveCancelledError";
+  }
+}
 function isRevivePayload(v) {
   return typeof v === "object" && v !== null && "islands" in v && !Array.isArray(v);
 }
+function createIslandRegistry(opts) {
+  const queued = new Set;
+  const loaded = new Set;
+  const retryCount = new Map;
+  const cancellableElements = new Map;
+  let initialWalkComplete = false;
+  return {
+    queue(tag) {
+      if (queued.has(tag) || loaded.has(tag))
+        return false;
+      queued.add(tag);
+      return true;
+    },
+    settleSuccess(tag) {
+      const attempt = (retryCount.get(tag) ?? 0) + 1;
+      queued.delete(tag);
+      loaded.add(tag);
+      retryCount.delete(tag);
+      return attempt;
+    },
+    settleFailure(tag) {
+      const attempt = (retryCount.get(tag) ?? 0) + 1;
+      if (attempt <= opts.retries) {
+        retryCount.set(tag, attempt);
+        return { retryDelayMs: opts.retryDelay * 2 ** (attempt - 1), attempt };
+      } else {
+        retryCount.delete(tag);
+        queued.delete(tag);
+        return { retryDelayMs: null, attempt };
+      }
+    },
+    evict(tag) {
+      retryCount.delete(tag);
+      queued.delete(tag);
+    },
+    isQueued(tag) {
+      return queued.has(tag);
+    },
+    get initialWalkComplete() {
+      return initialWalkComplete;
+    },
+    markInitialWalkComplete() {
+      initialWalkComplete = true;
+    },
+    watchCancellable(el, cancel) {
+      cancellableElements.set(el, cancel);
+      return () => {
+        cancellableElements.delete(el);
+      };
+    },
+    cancelDetached() {
+      if (cancellableElements.size === 0)
+        return;
+      for (const [el, cancel] of cancellableElements) {
+        if (!el.isConnected) {
+          cancellableElements.delete(el);
+          cancel();
+        }
+      }
+    }
+  };
+}
 function revive(islandsOrPayload, options, customDirectives) {
   const payload = isRevivePayload(islandsOrPayload) ? islandsOrPayload : { islands: islandsOrPayload, options, customDirectives };
   const opts = normalizeReviveOptions(payload.options);
@@ -124,27 +228,125 @@ function revive(islandsOrPayload, options, customDirectives) {
   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;
-  const pendingCancellable = new Map;
-  const retryCount = new Map;
-  const isUnloadedIsland = (tag) => queued.has(tag) && !loaded.has(tag);
+  const directiveTimeout = opts.directiveTimeout;
+  const registry = createIslandRegistry({
+    retries: opts.retry.retries,
+    retryDelay: opts.retry.delay
+  });
   const customElementFilter = {
     acceptNode: (node) => {
       const tag = node.tagName;
       if (!tag.includes("-"))
         return NodeFilter.FILTER_SKIP;
       const lowerTag = tag.toLowerCase();
-      if (isUnloadedIsland(lowerTag))
+      if (registry.isQueued(lowerTag))
         return NodeFilter.FILTER_REJECT;
       return NodeFilter.FILTER_ACCEPT;
     }
   };
+  function makeDirectiveOutcomeHandler(tagName) {
+    return (outcome) => {
+      if (outcome.kind === "builtin-catch" && outcome.err instanceof DirectiveCancelledError) {
+        return;
+      }
+      const err = outcome.err;
+      if (outcome.kind === "directive-error") {
+        console.error(`[islands] Custom directive ${outcome.attrName} failed for <${tagName}>:`, err);
+      } else {
+        console.error(`[islands] Built-in directive failed for <${tagName}>:`, err);
+      }
+      dispatch("islands:error", { tag: tagName, error: err, attempt: 1 });
+      registry.evict(tagName);
+    };
+  }
+  async function applyBuiltInDirectives(tagName, el, log) {
+    const visibleAttr = el.getAttribute(attrVisible);
+    if (visibleAttr !== null) {
+      log.note(`waiting for ${attrVisible}`);
+      await visible(el, visibleAttr || rootMargin, threshold, registry.watchCancellable);
+    }
+    const query = el.getAttribute(attrMedia);
+    if (query === "") {
+      console.warn(`[islands] <${tagName}> ${attrMedia} has no value — media check skipped, island will load immediately`);
+    } else if (query) {
+      log.note(`waiting for ${attrMedia}="${query}"`);
+      await media(query);
+    }
+    const idleAttr = el.getAttribute(attrIdle);
+    if (idleAttr !== null) {
+      const raw = parseInt(idleAttr, 10);
+      const elTimeout = Number.isNaN(raw) ? idleTimeout : raw;
+      log.note(`waiting for ${attrIdle} (${elTimeout}ms)`);
+      await idle(elTimeout);
+    }
+    const d = el.getAttribute(attrDefer);
+    if (d !== null) {
+      const dMs = parseInt(d, 10);
+      if (d !== "" && Number.isNaN(dMs)) {
+        console.warn(`[islands] <${tagName}> invalid ${attrDefer} value "${d}" — using default ${deferDelay}ms`);
+      }
+      const ms = Number.isNaN(dMs) ? deferDelay : dMs;
+      log.note(`waiting for ${attrDefer} (${ms}ms)`);
+      await defer(ms);
+    }
+    const interactionAttr = el.getAttribute(attrInteraction);
+    if (interactionAttr !== null) {
+      let events = interactionEvents;
+      if (interactionAttr) {
+        const tokens = interactionAttr.split(/\s+/).filter(Boolean);
+        if (tokens.length > 0)
+          events = tokens;
+        else
+          console.warn(`[islands] <${tagName}> ${attrInteraction} has no valid event tokens — using default events`);
+      }
+      log.note(`waiting for ${attrInteraction} (${events.join(", ")})`);
+      await interaction(el, events, registry.watchCancellable);
+    }
+  }
+  function applyCustomDirectives(tagName, el, matched, run, handleDirectiveError, log) {
+    if (matched.length === 0)
+      return false;
+    const attrNames = matched.map(([a]) => a).join(", ");
+    log.flush(`dispatching to custom directive${matched.length === 1 ? "" : "s"} ${attrNames}`);
+    let remaining = matched.length;
+    let fired = false;
+    let aborted = false;
+    const loadOnce = () => {
+      if (fired || aborted)
+        return Promise.resolve();
+      if (--remaining === 0) {
+        clearTimeout(timer);
+        fired = true;
+        return run();
+      }
+      return Promise.resolve();
+    };
+    let timer;
+    if (directiveTimeout > 0) {
+      timer = setTimeout(() => {
+        if (fired || aborted)
+          return;
+        aborted = true;
+        handleDirectiveError(attrNames, new Error(`[islands] Custom directive timed out after ${directiveTimeout}ms for <${tagName}>`));
+      }, directiveTimeout);
+    }
+    for (const [attrName, directiveFn, value] of matched) {
+      try {
+        Promise.resolve(directiveFn(loadOnce, { name: attrName, value }, el)).catch((err) => {
+          clearTimeout(timer);
+          aborted = true;
+          handleDirectiveError(attrName, err);
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        aborted = true;
+        handleDirectiveError(attrName, err);
+      }
+    }
+    return true;
+  }
   async function loadIsland(tagName, el, loader) {
-    if (debug && !initDone) {
+    if (debug && !registry.initialWalkComplete) {
       const parts = [];
       const pushAttr = (attr, val) => {
         if (val !== null)
@@ -166,63 +368,13 @@ function revive(islandsOrPayload, options, customDirectives) {
       if (parts.length > 0)
         console.log("[islands]", `<${tagName}> waiting · ${parts.join(", ")}`);
     }
-    const msgs = debug ? [] : null;
-    const note = msgs ? (msg) => msgs.push(msg) : noop;
-    const flush = msgs ? (final) => {
-      if (msgs.length === 0) {
-        console.log("[islands]", `<${tagName}> ${final}`);
-      } else {
-        console.groupCollapsed(`[islands] <${tagName}> ${final}`);
-        for (const m of msgs)
-          console.log(m);
-        console.groupEnd();
-      }
-    } : noop;
+    const log = createIslandLogger(tagName, debug);
+    const handleOutcome = makeDirectiveOutcomeHandler(tagName);
     try {
-      const visibleAttr = el.getAttribute(attrVisible);
-      if (visibleAttr !== null) {
-        note(`waiting for ${attrVisible}`);
-        await visible(el, visibleAttr || rootMargin, threshold, pendingCancellable);
-      }
-      const query = el.getAttribute(attrMedia);
-      if (query === "") {
-        console.warn(`[islands] <${tagName}> ${attrMedia} has no value — media check skipped, island will load immediately`);
-      } else if (query) {
-        note(`waiting for ${attrMedia}="${query}"`);
-        await media(query);
-      }
-      const idleAttr = el.getAttribute(attrIdle);
-      if (idleAttr !== null) {
-        const raw = parseInt(idleAttr, 10);
-        const elTimeout = Number.isNaN(raw) ? idleTimeout : raw;
-        note(`waiting for ${attrIdle} (${elTimeout}ms)`);
-        await idle(elTimeout);
-      }
-      const d = el.getAttribute(attrDefer);
-      if (d !== null) {
-        const dMs = parseInt(d, 10);
-        if (d !== "" && Number.isNaN(dMs)) {
-          console.warn(`[islands] <${tagName}> invalid ${attrDefer} value "${d}" — using default ${deferDelay}ms`);
-        }
-        const ms = Number.isNaN(dMs) ? deferDelay : dMs;
-        note(`waiting for ${attrDefer} (${ms}ms)`);
-        await defer(ms);
-      }
-      const interactionAttr = el.getAttribute(attrInteraction);
-      if (interactionAttr !== null) {
-        let events = interactionEvents;
-        if (interactionAttr) {
-          const tokens = interactionAttr.split(/\s+/).filter(Boolean);
-          if (tokens.length > 0)
-            events = tokens;
-          else
-            console.warn(`[islands] <${tagName}> ${attrInteraction} has no valid event tokens — using default events`);
-        }
-        note(`waiting for ${attrInteraction} (${events.join(", ")})`);
-        await interaction(el, events, pendingCancellable);
-      }
-    } catch {
-      flush("aborted (element removed)");
+      await applyBuiltInDirectives(tagName, el, log);
+    } catch (err) {
+      handleOutcome({ kind: "builtin-catch", err });
+      log.flush(err instanceof DirectiveCancelledError ? "aborted (element removed)" : "aborted (directive error)");
       return;
     }
     const run = () => {
@@ -230,9 +382,7 @@ function revive(islandsOrPayload, options, customDirectives) {
         return Promise.resolve();
       const t0 = performance.now();
       return loader().then(() => {
-        const attempt = (retryCount.get(tagName) ?? 0) + 1;
-        loaded.add(tagName);
-        retryCount.delete(tagName);
+        const attempt = registry.settleSuccess(tagName);
         dispatch("islands:load", {
           tag: tagName,
           duration: performance.now() - t0,
@@ -242,23 +392,14 @@ function revive(islandsOrPayload, options, customDirectives) {
           walk(el);
       }).catch((err) => {
         console.error(`[islands] Failed to load <${tagName}>:`, err);
-        const attempt = retryCount.get(tagName) ?? 0;
-        dispatch("islands:error", { tag: tagName, error: err, attempt: attempt + 1 });
-        if (attempt < retries) {
-          retryCount.set(tagName, attempt + 1);
-          setTimeout(run, retryDelay * 2 ** attempt);
-        } else {
-          retryCount.delete(tagName);
-          queued.delete(tagName);
+        const { retryDelayMs, attempt } = registry.settleFailure(tagName);
+        dispatch("islands:error", { tag: tagName, error: err, attempt });
+        if (retryDelayMs !== null) {
+          setTimeout(run, retryDelayMs);
         }
       });
     };
-    const handleDirectiveError = (attrName, err) => {
-      console.error(`[islands] Custom directive ${attrName} failed for <${tagName}>:`, err);
-      dispatch("islands:error", { tag: tagName, error: err, attempt: 1 });
-      retryCount.delete(tagName);
-      queued.delete(tagName);
-    };
+    const handleDirectiveError = (attrName, err) => handleOutcome({ kind: "directive-error", attrName, err });
     if (resolvedDirectives?.size) {
       const matched = [];
       for (const [attrName, directiveFn] of resolvedDirectives) {
@@ -266,51 +407,25 @@ function revive(islandsOrPayload, options, customDirectives) {
         if (value !== null)
           matched.push([attrName, directiveFn, value]);
       }
-      if (matched.length > 0) {
-        flush(`dispatching to custom directive${matched.length === 1 ? "" : "s"} ${matched.map(([a]) => a).join(", ")}`);
-        let remaining = matched.length;
-        let fired = false;
-        let aborted = false;
-        const loadOnce = () => {
-          if (fired || aborted)
-            return Promise.resolve();
-          if (--remaining === 0) {
-            fired = true;
-            return run();
-          }
-          return Promise.resolve();
-        };
-        for (const [attrName, directiveFn, value] of matched) {
-          try {
-            Promise.resolve(directiveFn(loadOnce, { name: attrName, value }, el)).catch((err) => {
-              aborted = true;
-              handleDirectiveError(attrName, err);
-            });
-          } catch (err) {
-            aborted = true;
-            handleDirectiveError(attrName, err);
-          }
-        }
+      if (applyCustomDirectives(tagName, el, matched, run, handleDirectiveError, log))
         return;
-      }
     }
-    flush("triggered");
+    log.flush("triggered");
     run();
   }
   function activate(el) {
     const tagName = el.tagName.toLowerCase();
-    if (queued.has(tagName))
-      return;
     const loader = islandMap.get(tagName);
     if (!loader)
       return;
     let ancestor = el.parentElement;
     while (ancestor) {
-      if (isUnloadedIsland(ancestor.tagName.toLowerCase()))
+      if (registry.isQueued(ancestor.tagName.toLowerCase()))
         return;
       ancestor = ancestor.parentElement;
     }
-    queued.add(tagName);
+    if (!registry.queue(tagName))
+      return;
     loadIsland(tagName, el, loader);
   }
   function walk(el) {
@@ -320,27 +435,23 @@ function revive(islandsOrPayload, options, customDirectives) {
     while (node = walker.nextNode())
       activate(node);
   }
-  const observer = new MutationObserver((mutations) => {
-    if (pendingCancellable.size > 0 && mutations.some((m) => m.removedNodes.length > 0)) {
-      for (const [el, cancel] of pendingCancellable) {
-        if (!el.isConnected) {
-          pendingCancellable.delete(el);
-          cancel();
-        }
-      }
-    }
+  function handleAdditions(mutations) {
     for (const { addedNodes } of mutations) {
       for (const node of addedNodes) {
         if (node.nodeType === Node.ELEMENT_NODE)
           walk(node);
       }
     }
+  }
+  const observer = new MutationObserver((mutations) => {
+    registry.cancelDetached();
+    handleAdditions(mutations);
   });
   function init() {
     if (debug)
       console.groupCollapsed(`[islands] ready — ${islandMap.size} island(s)`);
     walk(document.body);
-    initDone = true;
+    registry.markInitialWalkComplete();
     if (debug)
       console.groupEnd();
     observer.observe(document.body, { childList: true, subtree: true });

package/package.json

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

package/skills/custom-directives/SKILL.md

@@ -4,15 +4,17 @@ description: >
   Custom client directives registered via directives.custom in vite.config.ts.
   ClientDirective function signature (load, options, el). AND-latch: when
   multiple custom directives match the same element, all must call load() before
-  the island activates. Error handling — thrown errors fire islands:error.
-  Custom directives run after all built-in conditions resolve.
+  the island activates. Error handling — thrown errors, rejected promises, and
+  directiveTimeout expiry fire islands:error. Custom directives run after all
+  built-in conditions resolve.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.1"
+library_version: "1.2.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
+  - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
 ---
 
 ## Setup
@@ -99,6 +101,16 @@ const networkDirective: ClientDirective = async (load, _opts, el) => {
 
 The directive function can be async. Unhandled rejections fire the document-level `islands:error` event, so `onIslandError()` observers still see directive failures.
 
+### Timeout guard for hung directives
+
+```ts
+shopifyThemeIslands({
+  directiveTimeout: 5000,
+});
+```
+
+If a matched custom directive never calls `load()`, the runtime normally waits forever. Setting `directiveTimeout` turns that hang into an `islands:error` event and abandons the activation attempt after the configured delay.
+
 ### AND-latch with multiple matching directives
 
 ```html
@@ -129,7 +141,7 @@ const myDirective: ClientDirective = (load, _opts, el) => {
 };
 ```
 
-No error is thrown and no timeout fires — the island is silently never loaded.
+No immediate error is thrown by default, so the island is silently never loaded unless you configure `directiveTimeout`.
 
 Source: src/runtime.ts — directive owns the `run()` call path
 
@@ -211,7 +223,7 @@ shopifyThemeIslands({
 
 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
+Source: src/config-policy.ts — validateOptions() duplicate and built-in conflict checks
 
 ### HIGH Entrypoint path missing `./` prefix
 

package/skills/directives/SKILL.md

@@ -9,10 +9,11 @@ description: >
   client:interaction values warn and fall back to default events.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.1"
+library_version: "1.2.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/options.ts
 ---
 
 ## Setup
@@ -114,6 +115,15 @@ shopifyThemeIslands({
 });
 ```
 
+### Removed elements abort waiting directives silently
+
+```html
+<hero-banner client:visible></hero-banner>
+<cart-flyout client:interaction></cart-flyout>
+```
+
+If either element is removed from the DOM before its directive resolves, the runtime cancels that activation attempt and does not dispatch `islands:error`. This is expected teardown behavior, not a load failure.
+
 ## Common Mistakes
 
 ### HIGH `client:media=""` skips the media check entirely
@@ -214,7 +224,7 @@ Correct:
 
 The attribute value is passed directly to `IntersectionObserver` as `rootMargin`, fully replacing the global default.
 
-Source: src/runtime.ts — `await visible(el, visibleAttr || rootMargin, threshold, pendingCancellable)`
+Source: src/runtime.ts — `await visible(el, visibleAttr || rootMargin, threshold, registry.watchCancellable)`
 
 ### HIGH Directive attribute typo — island loads without condition
 
@@ -252,4 +262,4 @@ Correct:
 
 When `directives.visible.attribute` (or any directive's `attribute` option) is overridden in `vite.config.ts`, all Liquid templates must use the configured name. The default `client:*` names no longer apply. Always read `vite.config.ts` to check for overridden attribute names before writing directives in Liquid.
 
-Source: src/index.ts:DirectivesConfig — `attribute` field per directive; src/runtime.ts reads configured attribute names at runtime
+Source: src/options.ts:DirectivesConfig — `attribute` field per directive; src/runtime.ts reads configured attribute names at runtime

package/skills/lifecycle/SKILL.md

@@ -6,15 +6,17 @@ description: >
   raw document.addEventListener for guaranteed type safety. Raw DOM events
   islands:load and islands:error on document. islands:load detail includes tag,
   duration (ms), and attempt (1-based). islands:error detail includes tag,
-  error, and attempt. disconnect() from the virtual module revive for SPA
-  navigation teardown.
+  error, and attempt, including custom directive failures and directiveTimeout
+  expiry. disconnect() from the virtual module revive for SPA navigation
+  teardown.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.1"
+library_version: "1.2.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/events.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/revive-module.ts
 ---
 
 ## Setup
@@ -73,7 +75,7 @@ onIslandError(({ tag, error, attempt }) => {
 });
 ```
 
-`onIslandError` fires on each retry attempt and on custom directive failures. `attempt` tells you which attempt failed — 1 is the initial load, 2 is the first retry, etc.
+`onIslandError` fires on each retry attempt, on custom directive failures, and when `directiveTimeout` expires. `attempt` tells you which attempt failed — 1 is the initial load, 2 is the first retry, etc.
 
 ### Teardown for SPA navigation
 
@@ -143,7 +145,7 @@ import { disconnect } from "vite-plugin-shopify-theme-islands/revive";
 
 Only the virtual module (`/revive`) exports the `disconnect` bound to the plugin-managed `revive()` instance. Importing from other entry points references a different or nonexistent instance.
 
-Source: src/index.ts — virtual module `export const { disconnect } = _islands(...)`
+Source: src/revive-module.ts — buildReviveModuleSource() emits `export const { disconnect } = _islands(payload)`
 
 ### MEDIUM `onIslandError` fires on every retry, not just final failure
 
@@ -182,6 +184,10 @@ onIslandError(({ tag, error }) => {
 });
 ```
 
-`islands:error` fires when any custom directive throws or rejects, not only when the island module's `import()` fails. The `error` value may be a directive error rather than a network or chunk error.
+`islands:error` fires when any custom directive throws, rejects, or times out, not only when the island module's `import()` fails. The `error` value may be a directive error rather than a network or chunk error.
 
 Source: src/runtime.ts — handleDirectiveError dispatches `islands:error`
+
+### LOW Removed elements waiting on `client:visible` / `client:interaction` do not emit `islands:error`
+
+If an element is removed from the DOM before a cancellable built-in directive resolves, the runtime treats that as expected teardown and aborts silently. Use `onIslandError` for real failures, not DOM-removal cancellations.

package/skills/setup/SKILL.md

@@ -4,15 +4,18 @@ description: >
   Getting-started journey and plugin configuration. Covers the full path from
   install to first working island. shopifyThemeIslands() options: directories
   (string | string[]), debug, directives deep-merge (visible, idle, media,
-  defer, interaction, custom), and retry (retries, delay with exponential
-  backoff). Load when setting up the plugin, configuring island scan
-  directories, or enabling retry.
+  defer, interaction, custom), retry (retries, delay with exponential
+  backoff), and directiveTimeout for hung custom directives. Load when setting
+  up the plugin, configuring island scan directories, or enabling retry /
+  directive timeout.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.1"
+library_version: "1.2.1"
 sources:
   - 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/options.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
 ---
 
 ## Setup
@@ -91,6 +94,16 @@ shopifyThemeIslands({
 
 `retries` is the number of attempts after the first failure. `delay` is the base ms — each subsequent retry doubles it (1000ms → 2000ms → 4000ms).
 
+### Guard against hung custom directives
+
+```ts
+shopifyThemeIslands({
+  directiveTimeout: 5000,
+});
+```
+
+When a custom directive never calls `load()`, the runtime normally waits forever. `directiveTimeout` turns that into an `islands:error` event and abandons the activation attempt after the configured number of milliseconds.
+
 ### Enable console debug output
 
 ```ts
@@ -196,7 +209,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/options.ts — ShopifyThemeIslandsOptions
 
 ### HIGH Wrong key name for retry count
 
@@ -216,3 +229,27 @@ shopifyThemeIslands({ retry: { retries: 3 } });
 Unknown keys are silently ignored. The correct field is `retries`.
 
 Source: src/contract.ts — RetryConfig
+
+### HIGH `directiveTimeout` nested inside `directives` — timeout guard never applies
+
+Wrong:
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    directiveTimeout: 5000,
+  },
+});
+```
+
+Correct:
+
+```ts
+shopifyThemeIslands({
+  directiveTimeout: 5000,
+});
+```
+
+`directiveTimeout` is a top-level plugin option, not part of the per-directive config object.
+
+Source: src/options.ts — ShopifyThemeIslandsOptions

package/skills/writing-islands/SKILL.md

@@ -8,7 +8,7 @@ description: >
   base class, and child island cascade behaviour.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.1.1"
+library_version: "1.2.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/discovery.ts