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

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/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

@@ -61,5 +61,11 @@ export interface ShopifyThemeIslandsOptions {
     directives?: DirectivesConfig;
     /** Automatic retry behaviour for failed island loads. */
     retry?: RetryConfig;
+    /**
+     * Milliseconds before a custom directive that never calls `load()` is considered timed out.
+     * When exceeded, `islands:error` is dispatched and the island is abandoned.
+     * Default: `0` (disabled).
+     */
+    directiveTimeout?: number;
 }
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;

package/dist/index.js

@@ -112,7 +112,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;
@@ -298,7 +299,12 @@ function shopifyThemeIslands(options = {}) {
         directoryGlobs,
         islandPaths,
         customDirectives,
-        reviveOptions: { directives, debug, retry: options.retry }
+        reviveOptions: {
+          directives,
+          debug,
+          retry: options.retry,
+          directiveTimeout: options.directiveTimeout
+        }
       });
     }
   };

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.0",
   "description": "Vite plugin for island architecture in Shopify themes",
   "type": "module",
   "packageManager": "bun@1.3.10",

package/skills/custom-directives/SKILL.md

@@ -4,11 +4,12 @@ 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.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
@@ -99,6 +100,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 +140,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
 

package/skills/directives/SKILL.md

@@ -9,7 +9,7 @@ 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.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
@@ -114,6 +114,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 +223,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
 

package/skills/lifecycle/SKILL.md

@@ -6,11 +6,12 @@ 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.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/events.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
@@ -73,7 +74,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
 
@@ -182,6 +183,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,12 +4,13 @@ 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.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
@@ -91,6 +92,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
@@ -216,3 +227,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/index.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.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/discovery.ts