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

package/README.md

@@ -190,16 +190,51 @@ Loads the island after a fixed delay. The delay in milliseconds is read from the
 
 Unlike `client:idle`, which waits for genuine browser idle time, `client:defer` always waits exactly the specified number of milliseconds.
 
+### `client:interaction`
+
+Loads the island when the user interacts with the element. Listens for `mouseenter`, `touchstart`, and `focusin` by default — the module starts downloading the moment the user moves their cursor toward or focuses the element.
+
+```html
+<cart-flyout client:interaction>
+  <!-- ... -->
+</cart-flyout>
+```
+
+The attribute value overrides the events for that element only (space-separated MDN event names):
+
+```html
+<!-- only mouseenter — touchstart and focusin are excluded -->
+<cart-flyout client:interaction="mouseenter">
+  <!-- ... -->
+</cart-flyout>
+```
+
+Combine with `client:visible` to avoid attaching listeners to off-screen elements. Because directives resolve sequentially, interaction listeners are only registered once the element has entered the viewport:
+
+```html
+<mega-menu client:visible client:interaction>
+  <!-- loads when visible, then waits for hover/touch/focus -->
+</mega-menu>
+```
+
 ### Combining directives
 
-Directives can be combined — the element waits for all conditions to be met before loading:
+Directives can be combined — the element works through each condition in sequence before loading. The resolution order is: `visible` → `media` → `idle` → `defer` → `interaction` → custom directives.
 
 ```html
+<!-- must scroll into view, then wait for user interaction -->
+<product-recommendations client:visible client:interaction>
+  <!-- ... -->
+</product-recommendations>
+
+<!-- must scroll into view, then wait for idle time -->
 <heavy-widget client:visible client:idle>
   <!-- ... -->
 </heavy-widget>
 ```
 
+Because conditions resolve sequentially, each directive is only evaluated after the previous one has passed. Interaction listeners, for example, are never attached to an element that isn't yet visible.
+
 ### Custom directives
 
 Register your own loading conditions via `directives.custom`. A custom directive is a function that receives a `load` callback and decides when to call it.
@@ -207,24 +242,28 @@ Register your own loading conditions via `directives.custom`. A custom directive
 #### 1. Write the directive
 
 ```ts
-// src/directives/hover.ts
+// src/directives/hash.ts
 import type { ClientDirective } from "vite-plugin-shopify-theme-islands";
 
-const hoverDirective: ClientDirective = (load, _opts, el) => {
-  el.addEventListener("mouseenter", load, { once: true });
+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 hoverDirective;
+export default hashDirective;
 ```
 
-`mouseenter` fires before `click`, so the module starts downloading the moment the user moves their cursor toward the element — by the time they click it's already loaded.
+Useful for anchor-linked sections — `<product-reviews client:hash="#reviews">` loads only when the URL fragment matches, so deep-links like `/products/shirt#reviews` activate the island immediately while other visitors never load it.
 
 The function signature is `(load, options, el) => void | Promise<void>`:
 
 | Parameter       | Type                   | Description                                           |
 | --------------- | ---------------------- | ----------------------------------------------------- |
 | `load`          | `() => Promise<void>`  | Call this to trigger the island module load           |
-| `options.name`  | `string`               | The matched attribute name, e.g. `'client:hover'`     |
+| `options.name`  | `string`               | The matched attribute name, e.g. `'client:hash'`      |
 | `options.value` | `string`               | The attribute value; empty string if no value was set |
 | `el`            | `HTMLElement`          | The island element                                    |
 
@@ -238,7 +277,7 @@ export default defineConfig({
   plugins: [
     shopifyThemeIslands({
       directives: {
-        custom: [{ name: "client:hover", entrypoint: "./src/directives/hover.ts" }],
+        custom: [{ name: "client:hash", entrypoint: "./src/directives/hash.ts" }],
       },
     }),
   ],
@@ -250,9 +289,9 @@ The `entrypoint` supports Vite aliases.
 #### 3. Use it in Liquid
 
 ```html
-<quick-add client:hover>
+<product-reviews client:hash="#reviews">
   <!-- ... -->
-</quick-add>
+</product-reviews>
 ```
 
 #### Ordering
@@ -260,21 +299,21 @@ The `entrypoint` supports Vite aliases.
 Built-in directives always run first. A custom directive is only invoked after all built-in conditions on the element have been met. This means you can gate a custom directive behind `client:visible` to avoid wiring event listeners for off-screen elements:
 
 ```html
-<!-- element must enter the viewport before the hover handler is registered -->
-<quick-add client:visible client:hover>
+<!-- element must enter the viewport before the hash handler is registered -->
+<product-reviews client:visible client:hash="#reviews">
   <!-- ... -->
-</quick-add>
+</product-reviews>
 ```
 
 The custom directive owns the `load()` call — the built-in chain never calls it directly when a custom directive is matched.
 
-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:hover` and `client:focus`:
+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`:
 
 ```html
-<!-- client:visible runs first (built-in); then both client:hover and client:focus must fire -->
-<quick-add client:visible client:hover client:focus>
+<!-- client:visible runs first (built-in); then both client:hash and client:network must fire -->
+<product-reviews client:visible client:hash="#reviews" client:network="4g">
   <!-- ... -->
-</quick-add>
+</product-reviews>
 ```
 
 ## Configuration
@@ -307,6 +346,10 @@ shopifyThemeIslands({
       attribute: "client:defer", // HTML attribute name
       delay: 3000, // fallback delay (ms) when the attribute has no value
     },
+    interaction: {
+      attribute: "client:interaction", // HTML attribute name
+      events: ["mouseenter", "touchstart", "focusin"], // DOM events that trigger load
+    },
     custom: [], // custom directives — see Custom directives above
   },
 });
@@ -372,12 +415,12 @@ The `/events` entry point provides typed helpers that unwrap `e.detail` for you
 ```ts
 import { onIslandLoad, onIslandError } from "vite-plugin-shopify-theme-islands/events";
 
-const offLoad = onIslandLoad(({ tag }) => {
-  analytics.track("island_loaded", { tag });
+const offLoad = onIslandLoad(({ tag, duration, attempt }) => {
+  analytics.track("island_loaded", { tag, duration, attempt });
 });
 
-const offError = onIslandError(({ tag, error }) => {
-  errorReporter.capture(error, { context: tag });
+const offError = onIslandError(({ tag, error, attempt }) => {
+  errorReporter.capture(error, { context: tag, attempt });
 });
 
 // Remove listeners when no longer needed (e.g. SPA teardown)
@@ -395,10 +438,10 @@ document.addEventListener("islands:load", (e) => {
 });
 ```
 
-| Event           | Detail properties | When it fires                                              |
-| --------------- | ----------------- | ---------------------------------------------------------- |
-| `islands:load`  | `tag`             | Island module resolves successfully                        |
-| `islands:error` | `tag`, `error`    | Load or custom directive fails (alongside `console.error`) |
+| 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` fires on each retry attempt, not just the final failure. Multiple independent listeners are supported — each receives its own event.
 

package/dist/index.d.ts

@@ -16,21 +16,25 @@ export interface ClientDirectiveOptions {
  *
  * @example
  * ```ts
- * // src/directives/hover.ts
+ * // src/directives/hash.ts
  * import type { ClientDirective } from 'vite-plugin-shopify-theme-islands';
  *
- * const hoverDirective: ClientDirective = (load, _opts, el) => {
- *   el.addEventListener('mouseenter', load, { once: true });
+ * 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 hoverDirective;
+ * export default hashDirective;
  * ```
  *
  * Register it in `vite.config.ts`:
  * ```ts
  * shopifyThemeIslands({
  *   directives: {
- *     custom: [{ name: 'client:hover', entrypoint: './src/directives/hover.ts' }],
+ *     custom: [{ name: 'client:hash', entrypoint: './src/directives/hash.ts' }],
  *   },
  * })
  * ```
@@ -73,6 +77,13 @@ export interface DirectivesConfig {
         /** 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[];
 }
@@ -89,6 +100,10 @@ export interface RetryConfig {
 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 {
@@ -96,6 +111,8 @@ export interface IslandErrorDetail {
     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 {

package/dist/index.js

@@ -10,20 +10,61 @@ 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 ?? [];
+  if (Array.isArray(options.directories) && options.directories.length === 0) {
+    throw new Error(`${PREFIX} "directories" must not be empty`);
+  }
+  const threshold = options.directives?.visible?.threshold;
+  if (threshold !== undefined && (threshold < 0 || threshold > 1)) {
+    throw new Error(`${PREFIX} "directives.visible.threshold" must be between 0 and 1, got ${threshold}`);
+  }
+  if (options.retry !== undefined) {
+    const { retries, delay } = options.retry;
+    if (retries !== undefined && retries < 0) {
+      throw new Error(`${PREFIX} "retry.retries" must be >= 0, got ${retries}`);
+    }
+    if (delay !== undefined && delay < 0) {
+      throw new Error(`${PREFIX} "retry.delay" must be >= 0, got ${delay}`);
+    }
+  }
+  const builtinAttributes = new Set([
+    directives.visible.attribute,
+    directives.idle.attribute,
+    directives.media.attribute,
+    directives.defer.attribute,
+    directives.interaction.attribute
+  ]);
+  const seen = new Set;
+  for (const def of customDefs) {
+    if (seen.has(def.name)) {
+      throw new Error(`${PREFIX} Duplicate custom directive name: "${def.name}"`);
+    }
+    if (builtinAttributes.has(def.name)) {
+      throw new Error(`${PREFIX} Custom directive "${def.name}" conflicts with a built-in directive`);
+    }
+    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 }
+    defer: { attribute: "client:defer", delay: 3000 },
+    interaction: {
+      attribute: "client:interaction",
+      events: ["mouseenter", "touchstart", "focusin"]
+    }
   }
 };
 function normalizeDir(dir) {
   return dir.endsWith("/") ? dir : dir + "/";
 }
 function resolveAliases(dirs, config) {
-  const aliases = config.resolve.alias;
+  const aliases = [...config.resolve.alias].sort((a, b) => (typeof b.find === "string" ? b.find.length : 0) - (typeof a.find === "string" ? a.find.length : 0));
   return dirs.map((dir) => {
     for (const { find, replacement } of aliases) {
       if (typeof find === "string" && dir.startsWith(find))
@@ -68,9 +109,11 @@ function shopifyThemeIslands(options = {}) {
     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 }
+    defer: { ...defaults.directives.defer, ...options.directives?.defer },
+    interaction: { ...defaults.directives.interaction, ...options.directives?.interaction }
   };
   const clientDirectiveDefinitions = options.directives?.custom ?? [];
+  validateOptions(options, directives);
   const debug = options.debug ?? false;
   const log = debug ? (...args) => console.log("[islands]", ...args) : () => {};
   let resolvedDirs = rawDirs;
@@ -178,8 +221,10 @@ function shopifyThemeIslands(options = {}) {
 ${mapEntries.join(`,
 `)}
 ]);`);
+        lines.push(`export const { disconnect } = _islands(islands, options, customDirectives);`);
+      } else {
+        lines.push(`export const { disconnect } = _islands(islands, options);`);
       }
-      lines.push(`export const { disconnect } = _islands(islands, options${mapEntries.length ? ", customDirectives" : ""});`);
       return lines.join(`
 `);
     }

package/dist/runtime.d.ts

@@ -4,10 +4,11 @@
  * Walks the DOM for custom elements that match island files, then loads them
  * lazily based on client directives:
  *
- *   client:visible  — load when the element scrolls into view
- *   client:media    — load when a CSS media query matches
- *   client:idle     — load when the browser has idle time
- *   client:defer    — load after a fixed delay (ms value on the attribute)
+ *   client:visible     — load when the element scrolls into view
+ *   client:media       — load when a CSS media query matches
+ *   client:idle        — load when the browser has idle time
+ *   client:defer       — load after a fixed delay (ms value on the attribute)
+ *   client:interaction — load on mouseenter / touchstart / focusin (or custom events)
  *
  * Directives can be combined; all conditions must be met before loading.
  * A MutationObserver re-runs the same logic for elements added dynamically.

package/dist/runtime.js

@@ -25,6 +25,25 @@ function visible(element, rootMargin, threshold, pending) {
     });
   });
 }
+function interaction(element, events, pending) {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      for (const name of events)
+        element.removeEventListener(name, handler);
+      pending.delete(element);
+    };
+    const handler = () => {
+      cleanup();
+      resolve();
+    };
+    for (const name of events)
+      element.addEventListener(name, handler);
+    pending.set(element, () => {
+      cleanup();
+      reject();
+    });
+  });
+}
 function defer(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -36,11 +55,18 @@ function idle(timeout) {
       setTimeout(resolve, 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;
@@ -62,7 +88,7 @@ function revive(islands, options, customDirectives) {
   const queued = new Set;
   let initDone = false;
   const loaded = new Set;
-  const pendingVisible = new Map;
+  const pendingCancellable = new Map;
   const retryCount = new Map;
   const isUnloadedIsland = (tag) => queued.has(tag) && !loaded.has(tag);
   const customElementFilter = {
@@ -79,18 +105,17 @@ function revive(islands, options, customDirectives) {
   async function loadIsland(tagName, el, loader) {
     if (debug && !initDone) {
       const parts = [];
-      const visibleVal = el.getAttribute(attrVisible);
-      if (visibleVal !== null)
-        parts.push(visibleVal ? `${attrVisible}="${visibleVal}"` : attrVisible);
+      const pushAttr = (attr, val) => {
+        if (val !== null)
+          parts.push(val ? `${attr}="${val}"` : attr);
+      };
+      pushAttr(attrVisible, el.getAttribute(attrVisible));
       const mediaVal = el.getAttribute(attrMedia);
       if (mediaVal)
         parts.push(`${attrMedia}="${mediaVal}"`);
-      const idleVal = el.getAttribute(attrIdle);
-      if (idleVal !== null)
-        parts.push(idleVal ? `${attrIdle}="${idleVal}"` : attrIdle);
-      const deferVal = el.getAttribute(attrDefer);
-      if (deferVal !== null)
-        parts.push(deferVal ? `${attrDefer}="${deferVal}"` : attrDefer);
+      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 (el.hasAttribute(a))
@@ -100,9 +125,9 @@ function revive(islands, options, customDirectives) {
       if (parts.length > 0)
         console.log("[islands]", `<${tagName}> waiting · ${parts.join(", ")}`);
     }
-    const msgs = [];
-    const note = debug ? (msg) => msgs.push(msg) : () => {};
-    const flush = debug ? (final) => {
+    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 {
@@ -111,16 +136,16 @@ function revive(islands, options, customDirectives) {
           console.log(m);
         console.groupEnd();
       }
-    } : () => {};
+    } : noop;
     try {
       const visibleAttr = el.getAttribute(attrVisible);
       if (visibleAttr !== null) {
         note(`waiting for ${attrVisible}`);
-        await visible(el, visibleAttr || rootMargin, threshold, pendingVisible);
+        await visible(el, visibleAttr || rootMargin, threshold, pendingCancellable);
       }
       const query = el.getAttribute(attrMedia);
       if (query === "") {
-        console.warn(`[islands] <${tagName}> ${attrMedia} has no value — skipping media check`);
+        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);
@@ -134,14 +159,27 @@ function revive(islands, options, customDirectives) {
       }
       const d = el.getAttribute(attrDefer);
       if (d !== null) {
-        const raw = parseInt(d, 10);
-        const ms = Number.isNaN(raw) ? deferDelay : raw;
-        if (d !== "" && Number.isNaN(raw)) {
+        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)");
       return;
@@ -149,16 +187,22 @@ function revive(islands, options, customDirectives) {
     const run = () => {
       if (disconnected)
         return Promise.resolve();
+      const t0 = performance.now();
       return loader().then(() => {
+        const attempt = (retryCount.get(tagName) ?? 0) + 1;
         loaded.add(tagName);
         retryCount.delete(tagName);
-        dispatch("islands:load", { tag: tagName });
+        dispatch("islands:load", {
+          tag: tagName,
+          duration: performance.now() - t0,
+          attempt
+        });
         if (el.children.length)
           walk(el);
       }).catch((err) => {
         console.error(`[islands] Failed to load <${tagName}>:`, err);
-        dispatch("islands:error", { tag: tagName, error: 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);
@@ -170,7 +214,7 @@ function revive(islands, options, customDirectives) {
     };
     const handleDirectiveError = (attrName, err) => {
       console.error(`[islands] Custom directive ${attrName} failed for <${tagName}>:`, err);
-      dispatch("islands:error", { tag: tagName, error: err });
+      dispatch("islands:error", { tag: tagName, error: err, attempt: 1 });
       retryCount.delete(tagName);
       queued.delete(tagName);
     };
@@ -236,10 +280,10 @@ function revive(islands, options, customDirectives) {
       activate(node);
   }
   const observer = new MutationObserver((mutations) => {
-    if (pendingVisible.size > 0 && mutations.some((m) => m.removedNodes.length > 0)) {
-      for (const [el, cancel] of pendingVisible) {
+    if (pendingCancellable.size > 0 && mutations.some((m) => m.removedNodes.length > 0)) {
+      for (const [el, cancel] of pendingCancellable) {
         if (!el.isConnected) {
-          pendingVisible.delete(el);
+          pendingCancellable.delete(el);
           cancel();
         }
       }

package/package.json

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

package/skills/custom-directives/SKILL.md

@@ -5,9 +5,10 @@ description: >
   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.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.1.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
@@ -16,14 +17,18 @@ sources:
 ## Setup
 
 ```ts
-// src/directives/hover.ts
+// src/directives/hash.ts
 import type { ClientDirective } from "vite-plugin-shopify-theme-islands";
 
-const hoverDirective: ClientDirective = (load, _opts, el) => {
-  el.addEventListener("mouseenter", load, { once: true });
+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 hoverDirective;
+export default hashDirective;
 ```
 
 ```ts
@@ -36,8 +41,8 @@ export default defineConfig({
       directives: {
         custom: [
           {
-            name: "client:hover",
-            entrypoint: "./src/directives/hover.ts",
+            name: "client:hash",
+            entrypoint: "./src/directives/hash.ts",
           },
         ],
       },
@@ -47,7 +52,7 @@ export default defineConfig({
 ```
 
 ```html
-<quick-add client:hover></quick-add>
+<product-reviews client:hash="#reviews"></product-reviews>
 ```
 
 ## Core Patterns
@@ -96,10 +101,10 @@ The directive function can be async. Unhandled rejections fire `islands:error` o
 ### AND-latch with multiple matching directives
 
 ```html
-<product-form client:hover client:visible></product-form>
+<product-form client:hash="#details" client:auth-check></product-form>
 ```
 
-If both `client:hover` and `client:visible` are registered as custom directives and both match, **both** must call `load()` before the island activates. The runtime tracks a `remaining` counter; it reaches 0 only when every matched directive has called `load()`.
+If both `client:hash` and `client:auth-check` are registered as custom directives and both match, **both** must call `load()` before the island activates. The runtime tracks a `remaining` counter; it reaches 0 only when every matched directive has called `load()`.
 
 ## Common Mistakes
 
@@ -108,9 +113,9 @@ If both `client:hover` and `client:visible` are registered as custom directives
 Wrong:
 
 ```ts
-const hoverDirective: ClientDirective = (load, _opts, el) => {
-  el.addEventListener("mouseenter", () => {
-    console.log("hovered"); // forgot to call load
+const myDirective: ClientDirective = (load, _opts, el) => {
+  el.addEventListener("click", () => {
+    console.log("clicked"); // forgot to call load
   });
 };
 ```
@@ -118,8 +123,8 @@ const hoverDirective: ClientDirective = (load, _opts, el) => {
 Correct:
 
 ```ts
-const hoverDirective: ClientDirective = (load, _opts, el) => {
-  el.addEventListener("mouseenter", load, { once: true });
+const myDirective: ClientDirective = (load, _opts, el) => {
+  el.addEventListener("click", load, { once: true });
 };
 ```
 
@@ -127,22 +132,47 @@ No error is thrown and no timeout fires — the island is silently never loaded.
 
 Source: src/runtime.ts — directive owns the `run()` call path
 
+### HIGH Writing a custom directive for mouseenter/touchstart/focusin — use `client:interaction` instead
+
+Wrong:
+
+```ts
+// Reimplementing what the built-in already does
+const hoverDirective: ClientDirective = (load, _opts, el) => {
+  el.addEventListener("mouseenter", load, { once: true });
+};
+```
+
+Correct:
+
+```html
+<!-- Use the built-in client:interaction directive -->
+<cart-flyout client:interaction></cart-flyout>
+
+<!-- Or with a specific event -->
+<cart-flyout client:interaction="mouseenter"></cart-flyout>
+```
+
+`client:interaction` is a built-in directive that handles `mouseenter`, `touchstart`, and `focusin`. Custom directives are for conditions the built-ins cannot express (e.g. URL hash matching, network conditions, feature flags).
+
+Source: src/runtime.ts — `interaction()` built-in handles the hover/touch/focus pattern
+
 ### HIGH AND-latch: both matched directives must call `load()`
 
 Wrong assumption:
 
 ```html
-<product-form client:hover client:auth-check></product-form>
+<product-form client:hash="#details" client:auth-check></product-form>
 ```
 
 ```ts
-// Expecting: loads as soon as either hover or auth-check calls load()
+// Expecting: loads as soon as either hash or auth-check calls load()
 ```
 
 Correct:
 
 ```ts
-// Both client:hover AND client:auth-check must call load() before activation.
+// Both client:hash AND client:auth-check must call load() before activation.
 // remaining starts at 2; island fires when it reaches 0.
 ```
 
@@ -156,8 +186,8 @@ Wrong:
 
 ```ts
 {
-  name: "client:hover",
-  entrypoint: "src/directives/hover.ts", // ← no ./
+  name: "client:hash",
+  entrypoint: "src/directives/hash.ts", // ← no ./
 }
 ```
 
@@ -165,8 +195,8 @@ Correct:
 
 ```ts
 {
-  name: "client:hover",
-  entrypoint: "./src/directives/hover.ts",
+  name: "client:hash",
+  entrypoint: "./src/directives/hash.ts",
 }
 ```
 
@@ -174,7 +204,7 @@ Vite's resolver may fail to locate the file without the `./` relative prefix. Th
 
 Source: src/index.ts — `this.resolve(def.entrypoint)` throws on null
 
-### MEDIUM Custom directives run after built-in directive awaits
+### MEDIUM Custom directives run after all built-in directive awaits
 
 Wrong expectation:
 
@@ -183,7 +213,7 @@ Wrong expectation:
 <cart-drawer client:visible client:auth></cart-drawer>
 ```
 
-The runtime awaits `client:visible` first, then passes control to the `client:auth` custom directive. Custom directives cannot short-circuit or replace built-in awaits.
+The runtime awaits built-ins in order (`visible → media → idle → defer → interaction`) first, then passes control to matched custom directives. Custom directives cannot short-circuit or replace built-in awaits.
 
 Source: src/runtime.ts — built-in awaits precede `if (customDirectives?.size)` block
 

package/skills/directives/SKILL.md

@@ -3,11 +3,12 @@ name: directives
 description: >
   Built-in client directives: client:visible (IntersectionObserver, rootMargin),
   client:media (matchMedia query), client:idle (requestIdleCallback),
-  client:defer (setTimeout delay). Combining directives uses AND semantics —
-  all must resolve. Per-element value overrides. Empty client:media warning.
+  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.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.1.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
@@ -29,16 +30,24 @@ Add one or more directives as HTML attributes on any custom element:
 
 <!-- Load after a fixed delay (ms) -->
 <chat-widget client:defer="5000"></chat-widget>
+
+<!-- Load on mouseenter, touchstart, or focusin (hover/touch/keyboard intent) -->
+<cart-flyout client:interaction></cart-flyout>
 ```
 
 No JS changes needed — the runtime reads these attributes during DOM walk.
 
 ## Core Patterns
 
-### Combining directives — all conditions must pass
+### Combining directives — sequential resolution order
+
+Directives resolve in a fixed order: `visible → media → idle → defer → interaction → custom`. Each condition is only evaluated after the previous one has passed.
 
 ```html
-<!-- Loads only when BOTH visible AND the media query match -->
+<!-- Loads when visible AND on interaction — interaction listeners only attach after scroll-in -->
+<mega-menu client:visible client:interaction></mega-menu>
+
+<!-- Loads when visible AND the media query matches -->
 <product-recommendations
   client:visible
   client:media="(min-width: 768px)"
@@ -58,6 +67,9 @@ Combined directives are AND-latched. The island loads only after every condition
 
 <!-- Fixed delay in ms; empty attribute uses the global default (3000ms) -->
 <chat-widget client:defer="8000"></chat-widget>
+
+<!-- Override interaction events for this element only (space-separated MDN event names) -->
+<cart-flyout client:interaction="mouseenter"></cart-flyout>
 ```
 
 The attribute value overrides the globally configured default for that element. Other elements are unaffected.
@@ -74,6 +86,18 @@ The attribute value overrides the globally configured default for that element.
 
 An empty `client:defer` attribute is NOT zero — it falls back to the configured `defer.delay` (default 3000ms).
 
+### `client:interaction` with no value uses the default events
+
+```html
+<!-- Uses default events: mouseenter, touchstart, focusin -->
+<cart-flyout client:interaction></cart-flyout>
+
+<!-- Uses only mouseenter -->
+<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`).
+
 ### Changing built-in directive defaults globally
 
 ```ts
@@ -82,6 +106,7 @@ shopifyThemeIslands({
   directives: {
     visible: { rootMargin: "0px" },
     defer: { delay: 5000 },
+    interaction: { events: ["mouseenter"] },
   },
 });
 ```
@@ -164,4 +189,42 @@ 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, pendingVisible)`
+Source: src/runtime.ts — `await visible(el, visibleAttr || rootMargin, threshold, pendingCancellable)`
+
+### HIGH Directive attribute typo — island loads without condition
+
+Wrong:
+
+```html
+<product-form client:visibled></product-form>
+<product-form client:Visible></product-form>
+```
+
+Correct:
+
+```html
+<product-form client:visible></product-form>
+```
+
+Directive attributes are case-sensitive. An unrecognised attribute is silently ignored — the island loads immediately as if no directive were set. No warning is emitted. Check for typos if an island activates earlier than expected.
+
+Source: src/runtime.ts — runtime checks exact attribute names from plugin config
+
+### HIGH Agent uses default attribute name when developer has configured a custom one
+
+Wrong:
+
+```html
+<!-- developer has set visible.attribute: "data:visible" in vite.config.ts -->
+<product-form client:visible></product-form>
+```
+
+Correct:
+
+```html
+<product-form data:visible></product-form>
+```
+
+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

package/skills/lifecycle/SKILL.md

@@ -4,11 +4,13 @@ description: >
   Island lifecycle events and SPA teardown. onIslandLoad and onIslandError
   helpers from vite-plugin-shopify-theme-islands/events — prefer these over
   raw document.addEventListener for guaranteed type safety. Raw DOM events
-  islands:load and islands:error on document. disconnect() from the virtual
-  module revive for SPA navigation teardown.
+  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.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.1.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/events.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
@@ -20,12 +22,12 @@ sources:
 ```ts
 import { onIslandLoad, onIslandError } from "vite-plugin-shopify-theme-islands/events";
 
-const offLoad = onIslandLoad(({ tag }) => {
-  console.log("loaded:", tag);
+const offLoad = onIslandLoad(({ tag, duration, attempt }) => {
+  console.log("loaded:", tag, `${duration.toFixed(1)}ms`, `attempt ${attempt}`);
 });
 
-const offError = onIslandError(({ tag, error }) => {
-  console.error("failed:", tag, error);
+const offError = onIslandError(({ tag, error, attempt }) => {
+  console.error("failed:", tag, `attempt ${attempt}`, error);
 });
 
 // Remove listeners when no longer needed
@@ -40,24 +42,38 @@ offError();
 ```ts
 import { onIslandLoad } from "vite-plugin-shopify-theme-islands/events";
 
-onIslandLoad(({ tag }) => {
-  analytics.track("island_loaded", { component: tag });
+onIslandLoad(({ tag, duration, attempt }) => {
+  analytics.track("island_loaded", { component: tag, duration, attempt });
+});
+```
+
+`tag` is the lowercased custom element tag name (e.g. `"product-form"`). `duration` is the time in milliseconds from when all directives resolved to when the module finished loading. `attempt` is 1 on the first successful load, 2 if it succeeded on the first retry, etc.
+
+### Track load performance
+
+```ts
+import { onIslandLoad } from "vite-plugin-shopify-theme-islands/events";
+
+onIslandLoad(({ tag, duration }) => {
+  if (duration > 3000) {
+    performance.mark(`island-slow:${tag}`);
+  }
 });
 ```
 
-`tag` is the lowercased custom element tag name (e.g. `"product-form"`).
+`duration` measures only the chunk fetch time — time spent waiting on directives (e.g. `client:visible`) is not included.
 
 ### Report errors to a monitoring service
 
 ```ts
 import { onIslandError } from "vite-plugin-shopify-theme-islands/events";
 
-onIslandError(({ tag, error }) => {
-  Sentry.captureException(error, { extra: { island: tag } });
+onIslandError(({ tag, error, attempt }) => {
+  Sentry.captureException(error, { extra: { island: tag, attempt } });
 });
 ```
 
-`onIslandError` fires on each retry attempt and on custom directive failures. If retry is enabled, a single island may produce multiple error events before succeeding or exhausting retries.
+`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.
 
 ### Teardown for SPA navigation
 
@@ -77,7 +93,7 @@ disconnect();
 import type {} from "vite-plugin-shopify-theme-islands";
 
 document.addEventListener("islands:load", (e) => {
-  console.log(e.detail.tag); // typed as string
+  console.log(e.detail.tag, e.detail.duration, e.detail.attempt);
 });
 ```
 
@@ -143,16 +159,15 @@ onIslandError(({ tag }) => {
 Correct:
 
 ```ts
-const seen = new Set<string>();
-onIslandError(({ tag, error }) => {
-  if (!seen.has(tag)) {
-    seen.add(tag);
+onIslandError(({ tag, error, attempt }) => {
+  // attempt === 1 is the first failure; higher values are retries
+  if (attempt === 1) {
     reportFirstFailure(tag, error);
   }
 });
 ```
 
-With `retry: { retries: 3 }`, a single island can fire `islands:error` up to 4 times before exhausting retries. Deduplicate by `tag` if only the first failure matters.
+With `retry: { retries: 3 }`, a single island can fire `islands:error` up to 4 times before exhausting retries. Use `attempt` to distinguish the initial failure from retries.
 
 Source: src/runtime.ts — `dispatch("islands:error", ...)` inside `.catch()` before retry check
 

package/skills/setup/SKILL.md

@@ -1,42 +1,60 @@
 ---
 name: setup
 description: >
-  Plugin install and vite.config.ts configuration. Covers shopifyThemeIslands()
-  options: directories (string | string[]), debug, directives deep-merge, and
-  retry (retries, delay with exponential backoff). Load when configuring the
-  plugin, setting island scan directories, or enabling retry.
+  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.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.1.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
 ---
 
 ## Setup
 
+This plugin is framework-agnostic but designed for Shopify themes. Most Shopify
+projects also use
+[vite-plugin-shopify](https://github.com/barrel/vite-plugin-shopify) to handle
+Shopify-specific asset serving — if the project uses it, add this plugin
+alongside it in the existing `plugins` array.
+
+### 1. Add the plugin to `vite.config.ts`
+
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
 import shopifyThemeIslands from "vite-plugin-shopify-theme-islands";
 
 export default defineConfig({
-  plugins: [
-    shopifyThemeIslands({
-      directories: ["/frontend/js/islands/"],
-      debug: false,
-      retry: { retries: 2, delay: 500 },
-    }),
-  ],
+  plugins: [shopifyThemeIslands()],
 });
 ```
 
-Import the virtual module in the theme JS entry point to activate islands:
+All options are optional. The default islands directory is `/frontend/js/islands/`.
+
+### 2. Import the virtual module in the theme JS entry point
 
 ```ts
 // frontend/js/theme.ts
 import "vite-plugin-shopify-theme-islands/revive";
 ```
 
+This activates the runtime — islands are never loaded without this import.
+
+### 3. Add directives to Liquid templates
+
+```html
+<!-- sections/product.liquid -->
+<product-form client:visible></product-form>
+```
+
+That's a working setup. Islands in `/frontend/js/islands/` matching the tag
+name are loaded lazily when the directive condition is met.
+
 ## Core Patterns
 
 ### Configure multiple island directories
@@ -55,6 +73,7 @@ shopifyThemeIslands({
     visible: { rootMargin: "0px", threshold: 0.5 },
     idle: { timeout: 2000 },
     defer: { delay: 5000 },
+    interaction: { events: ["mouseenter"] },
   },
 });
 ```
@@ -101,6 +120,59 @@ The plugin generates the virtual module but has no effect until it is imported i
 
 Source: src/index.ts — VIRTUAL_ID / RESOLVED_ID
 
+### HIGH Agent hardcodes default values — unnecessary noise
+
+Wrong:
+
+```ts
+shopifyThemeIslands({
+  directories: ["/frontend/js/islands/"],
+  debug: false,
+  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"] },
+  },
+});
+```
+
+Correct:
+
+```ts
+shopifyThemeIslands();
+```
+
+All options are optional and default to sensible values. Only include options that differ from the defaults.
+
+### HIGH Agent overwrites existing `vite.config.ts` instead of appending
+
+Before adding the plugin, read the existing `vite.config.ts`. Projects commonly
+already have `vite-plugin-shopify` or other plugins — the island plugin must be
+added to the existing `plugins` array, not replace it.
+
+Wrong:
+
+```ts
+// Replaces existing plugins
+export default defineConfig({
+  plugins: [shopifyThemeIslands()],
+});
+```
+
+Correct:
+
+```ts
+// Appends to existing plugins
+export default defineConfig({
+  plugins: [
+    shopify(), // pre-existing plugin preserved
+    shopifyThemeIslands(),
+  ],
+});
+```
+
 ### HIGH `retry` nested inside `directives` — no retries happen
 
 Wrong:
@@ -121,7 +193,7 @@ shopifyThemeIslands({
 });
 ```
 
-`directives` accepts only `visible`, `idle`, `media`, `defer`, and `custom`. `retry` at `directives.retry` is silently ignored.
+`directives` accepts only `visible`, `idle`, `media`, `defer`, `interaction`, and `custom`. `retry` at `directives.retry` is silently ignored.
 
 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.0.0"
+library_version: "1.1.0"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts