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

package/README.md

@@ -221,12 +221,12 @@ export default hoverDirective;
 
 The function signature is `(load, options, el) => void | Promise<void>`:
 
-| Parameter       | Type                     | Description                                           |
-| --------------- | ------------------------ | ----------------------------------------------------- |
-| `load`          | `() => Promise<unknown>` | Call this to trigger the island module load           |
-| `options.name`  | `string`                 | The matched attribute name, e.g. `'client:hover'`     |
-| `options.value` | `string`                 | The attribute value; empty string if no value was set |
-| `el`            | `HTMLElement`            | The island element                                    |
+| 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.value` | `string`               | The attribute value; empty string if no value was set |
+| `el`            | `HTMLElement`          | The island element                                    |
 
 #### 2. Register it in the plugin config
 
@@ -268,7 +268,14 @@ 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.
 
-> Only one custom directive can be active per element. If multiple custom directive attributes are present, the first registered one is used and a console warning is emitted. Combining multiple custom directives on one element is not yet supported.
+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`:
+
+```html
+<!-- client:visible runs first (built-in); then both client:hover and client:focus must fire -->
+<quick-add client:visible client:hover client:focus>
+  <!-- ... -->
+</quick-add>
+```
 
 ## Configuration
 
@@ -276,6 +283,7 @@ The custom directive owns the `load()` call — the built-in chain never calls i
 | ------------- | -------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
 | `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.  |
 
 ### Directive defaults
@@ -338,6 +346,72 @@ export default defineConfig({
 });
 ```
 
+## Retries
+
+Automatically retry failed island loads with exponential backoff:
+
+```ts
+shopifyThemeIslands({
+  retry: {
+    retries: 2,   // number of retries after the initial failure. Default: 0 (no retry)
+    delay: 1000,  // base delay in ms; doubles each attempt (1s, 2s, 4s…). Default: 1000
+  },
+});
+```
+
+Once retries are exhausted the island is dequeued — a fresh activation requires a new element instance.
+
+## Lifecycle events
+
+The runtime dispatches DOM events on `document` for observability use cases such as analytics and error reporting.
+
+### Typed helpers
+
+The `/events` entry point provides typed helpers that unwrap `e.detail` for you and return a cleanup function:
+
+```ts
+import { onIslandLoad, onIslandError } from "vite-plugin-shopify-theme-islands/events";
+
+const offLoad = onIslandLoad(({ tag }) => {
+  analytics.track("island_loaded", { tag });
+});
+
+const offError = onIslandError(({ tag, error }) => {
+  errorReporter.capture(error, { context: tag });
+});
+
+// Remove listeners when no longer needed (e.g. SPA teardown)
+offLoad();
+offError();
+```
+
+### Raw DOM events
+
+The events are also available via the standard `document.addEventListener` API. Event types are fully typed via `DocumentEventMap` augmentation — available automatically when `vite-plugin-shopify-theme-islands` is present in your TypeScript compilation (e.g. via `vite.config.ts` or a directive type import).
+
+```ts
+document.addEventListener("islands:load", (e) => {
+  analytics.track("island_loaded", { tag: e.detail.tag });
+});
+```
+
+| 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`) |
+
+`islands:error` fires on each retry attempt, not just the final failure. Multiple independent listeners are supported — each receives its own event.
+
+## AI Agents
+
+If you use an AI coding agent (Claude Code, Cursor, Copilot, etc.), run once after installing:
+
+```bash
+npx @tanstack/intent@latest install
+```
+
+This maps the bundled skills to your agent config so your agent gets accurate v1 API guidance. Skills update automatically with npm updates — no re-run needed.
+
 ## License
 
 MIT

package/dist/events.d.ts

@@ -0,0 +1,32 @@
+import type { IslandLoadDetail, IslandErrorDetail } from "./index.js";
+/**
+ * Listen for successful island module loads.
+ *
+ * Returns a cleanup function that removes the listener.
+ *
+ * @example
+ * ```ts
+ * import { onIslandLoad } from "vite-plugin-shopify-theme-islands/events";
+ *
+ * const off = onIslandLoad(({ tag }) => {
+ *   analytics.track("island_loaded", { tag });
+ * });
+ * ```
+ */
+export declare function onIslandLoad(handler: (detail: IslandLoadDetail) => void): () => void;
+/**
+ * Listen for island load or custom directive failures.
+ *
+ * Fires on each retry attempt, not just the final failure.
+ * Returns a cleanup function that removes the listener.
+ *
+ * @example
+ * ```ts
+ * import { onIslandError } from "vite-plugin-shopify-theme-islands/events";
+ *
+ * const off = onIslandError(({ tag, error }) => {
+ *   errorReporter.capture(error, { context: tag });
+ * });
+ * ```
+ */
+export declare function onIslandError(handler: (detail: IslandErrorDetail) => void): () => void;

package/dist/events.js

@@ -0,0 +1,15 @@
+// src/events.ts
+function onIslandLoad(handler) {
+  const listener = (e) => handler(e.detail);
+  document.addEventListener("islands:load", listener);
+  return () => document.removeEventListener("islands:load", listener);
+}
+function onIslandError(handler) {
+  const listener = (e) => handler(e.detail);
+  document.addEventListener("islands:error", listener);
+  return () => document.removeEventListener("islands:error", listener);
+}
+export {
+  onIslandLoad,
+  onIslandError
+};

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { Plugin } from "vite";
 /** A function that triggers the load of an island module. */
-export type ClientDirectiveLoader = () => Promise<unknown>;
+export type ClientDirectiveLoader = () => Promise<void>;
 /** Options passed to a custom client directive function. */
 export interface ClientDirectiveOptions {
     /** The matched attribute name, e.g. `'client:on-click'` */
@@ -76,6 +76,35 @@ export interface DirectivesConfig {
     /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
     custom?: ClientDirectiveDefinition[];
 }
+/** Runtime-facing directive configuration — omits plugin-only `custom` directives. */
+export type RuntimeDirectivesConfig = Omit<DirectivesConfig, "custom">;
+/** Retry configuration for failed island loads. */
+export interface RetryConfig {
+    /** Number of times to retry after the initial failure. Default: `0` (no auto-retry) */
+    retries?: number;
+    /** Base delay in ms between retries; doubles each attempt. Default: `1000` */
+    delay?: number;
+}
+/** Event detail for the `islands:load` DOM event. */
+export interface IslandLoadDetail {
+    /** The custom element tag name, e.g. `'product-form'` */
+    tag: string;
+}
+/** Event detail for the `islands:error` DOM event. */
+export interface IslandErrorDetail {
+    /** The custom element tag name, e.g. `'product-form'` */
+    tag: string;
+    /** The error thrown by the loader or custom directive */
+    error: unknown;
+}
+declare global {
+    interface DocumentEventMap {
+        /** Fired after an island module resolves successfully. */
+        "islands:load": CustomEvent<IslandLoadDetail>;
+        /** Fired when an island load or custom directive fails. Fired on each retry attempt. */
+        "islands:error": CustomEvent<IslandErrorDetail>;
+    }
+}
 export interface ShopifyThemeIslandsOptions {
     /** Directories to scan for island files. Accepts paths or Vite aliases. Default: `['/frontend/js/islands/']` */
     directories?: string | string[];
@@ -83,10 +112,14 @@ export interface ShopifyThemeIslandsOptions {
     debug?: boolean;
     /** Per-directive configuration. */
     directives?: DirectivesConfig;
+    /** Automatic retry behaviour for failed island loads. */
+    retry?: RetryConfig;
 }
 export interface ReviveOptions {
-    directives?: DirectivesConfig;
+    directives?: RuntimeDirectivesConfig;
     /** Log island activation and directive events to the console. Default: `false` */
     debug?: boolean;
+    /** Automatic retry behaviour for failed island loads. */
+    retry?: RetryConfig;
 }
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;

package/dist/index.js

@@ -171,7 +171,7 @@ function shopifyThemeIslands(options = {}) {
         ...directiveImports,
         `import { revive as _islands } from ${JSON.stringify(runtimePath)};`,
         `const islands = Object.assign({}, ${islandsEntries.join(", ")});`,
-        `const options = ${JSON.stringify({ directives, debug })};`
+        `const options = ${JSON.stringify({ directives, debug, retry: options.retry })};`
       ];
       if (mapEntries.length) {
         lines.push(`const customDirectives = new Map([
@@ -179,7 +179,7 @@ ${mapEntries.join(`,
 `)}
 ]);`);
       }
-      lines.push(`export const disconnect = _islands(islands, options${mapEntries.length ? ", customDirectives" : ""});`);
+      lines.push(`export const { disconnect } = _islands(islands, options${mapEntries.length ? ", customDirectives" : ""});`);
       return lines.join(`
 `);
     }

package/dist/runtime.d.ts

@@ -13,4 +13,6 @@
  * A MutationObserver re-runs the same logic for elements added dynamically.
  */
 import type { ClientDirective, ReviveOptions } from "./index.js";
-export declare function revive(islands: Record<string, () => Promise<unknown>>, options?: ReviveOptions, customDirectives?: Map<string, ClientDirective>): () => void;
+export declare function revive(islands: Record<string, () => Promise<unknown>>, options?: ReviveOptions, customDirectives?: Map<string, ClientDirective>): {
+    disconnect: () => void;
+};

package/dist/runtime.js

@@ -1,4 +1,5 @@
 // src/runtime.ts
+var dispatch = (name, detail) => document.dispatchEvent(new CustomEvent(name, { detail }));
 function media(query) {
   const m = window.matchMedia(query);
   return new Promise((resolve) => {
@@ -45,6 +46,8 @@ function revive(islands, options, customDirectives) {
   const idleTimeout = options?.directives?.idle?.timeout ?? 500;
   const deferDelay = options?.directives?.defer?.delay ?? 3000;
   const debug = options?.debug ?? false;
+  const retries = options?.retry?.retries ?? 0;
+  const retryDelay = options?.retry?.delay ?? 1000;
   const islandMap = new Map;
   for (const [key, loader] of Object.entries(islands)) {
     const filename = key.split("/").pop();
@@ -60,6 +63,7 @@ function revive(islands, options, customDirectives) {
   let initDone = false;
   const loaded = new Set;
   const pendingVisible = new Map;
+  const retryCount = new Map;
   const isUnloadedIsland = (tag) => queued.has(tag) && !loaded.has(tag);
   const customElementFilter = {
     acceptNode: (node) => {
@@ -142,34 +146,65 @@ function revive(islands, options, customDirectives) {
       flush("aborted (element removed)");
       return;
     }
-    const run = () => loader().then(() => {
-      loaded.add(tagName);
-      if (el.children.length)
-        walk(el);
-    }).catch((err) => {
-      console.error(`[islands] Failed to load <${tagName}>:`, err);
-      queued.delete(tagName);
-    });
+    const run = () => {
+      if (disconnected)
+        return Promise.resolve();
+      return loader().then(() => {
+        loaded.add(tagName);
+        retryCount.delete(tagName);
+        dispatch("islands:load", { tag: tagName });
+        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;
+        if (attempt < retries) {
+          retryCount.set(tagName, attempt + 1);
+          setTimeout(run, retryDelay * 2 ** attempt);
+        } else {
+          retryCount.delete(tagName);
+          queued.delete(tagName);
+        }
+      });
+    };
     const handleDirectiveError = (attrName, err) => {
       console.error(`[islands] Custom directive ${attrName} failed for <${tagName}>:`, err);
+      dispatch("islands:error", { tag: tagName, error: err });
+      retryCount.delete(tagName);
       queued.delete(tagName);
     };
     if (customDirectives?.size) {
       const matched = [];
       for (const [attrName, directiveFn] of customDirectives) {
-        if (el.hasAttribute(attrName))
-          matched.push([attrName, directiveFn]);
-      }
-      if (matched.length > 1) {
-        console.warn(`[islands] <${tagName}> has multiple custom directives (${matched.map(([a]) => a).join(", ")}) — only "${matched[0][0]}" will be used. Combining custom directives is not yet supported.`);
+        const value = el.getAttribute(attrName);
+        if (value !== null)
+          matched.push([attrName, directiveFn, value]);
       }
       if (matched.length > 0) {
-        const [attrName, directiveFn] = matched[0];
-        flush(`dispatching to custom directive ${attrName}`);
-        try {
-          Promise.resolve(directiveFn(run, { name: attrName, value: el.getAttribute(attrName) }, el)).catch((err) => handleDirectiveError(attrName, err));
-        } catch (err) {
-          handleDirectiveError(attrName, err);
+        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);
+          }
         }
         return;
       }
@@ -201,10 +236,12 @@ function revive(islands, options, customDirectives) {
       activate(node);
   }
   const observer = new MutationObserver((mutations) => {
-    for (const [el, cancel] of pendingVisible) {
-      if (!el.isConnected) {
-        pendingVisible.delete(el);
-        cancel();
+    if (pendingVisible.size > 0 && mutations.some((m) => m.removedNodes.length > 0)) {
+      for (const [el, cancel] of pendingVisible) {
+        if (!el.isConnected) {
+          pendingVisible.delete(el);
+          cancel();
+        }
       }
     }
     for (const { addedNodes } of mutations) {
@@ -223,12 +260,17 @@ function revive(islands, options, customDirectives) {
       console.groupEnd();
     observer.observe(document.body, { childList: true, subtree: true });
   }
+  let disconnected = false;
   if (document.readyState === "loading") {
     document.addEventListener("DOMContentLoaded", init, { once: true });
   } else {
     init();
   }
-  return () => observer.disconnect();
+  const disconnect = () => {
+    disconnected = true;
+    observer.disconnect();
+  };
+  return { disconnect };
 }
 export {
   revive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-shopify-theme-islands",
-  "version": "0.7.2",
+  "version": "1.0.1",
   "description": "Vite plugin for island architecture in Shopify themes",
   "type": "module",
   "packageManager": "bun@1.3.10",
@@ -14,14 +14,24 @@
     "./revive": {
       "types": "./revive.d.ts"
     },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
     "./island": {
       "types": "./dist/island.d.ts",
       "import": "./dist/island.js"
+    },
+    "./events": {
+      "types": "./dist/events.d.ts",
+      "import": "./dist/events.js"
     }
   },
   "files": [
     "dist",
-    "revive.d.ts"
+    "revive.d.ts",
+    "skills",
+    "!skills/_artifacts"
   ],
   "sideEffects": [
     "./dist/runtime.js"
@@ -30,7 +40,8 @@
     "vite",
     "shopify",
     "islands",
-    "vite-plugin"
+    "vite-plugin",
+    "tanstack-intent"
   ],
   "license": "MIT",
   "author": {
@@ -47,10 +58,10 @@
     "url": "https://github.com/Rees1993/vite-plugin-shopify-theme-islands/issues"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "scripts": {
-    "build:js": "bun build src/index.ts src/runtime.ts src/island.ts --outdir dist --format esm --target node",
+    "build:js": "bun build src/index.ts src/runtime.ts src/island.ts src/events.ts --outdir dist --format esm --target node",
     "build:types": "tsc -p tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist",
     "build": "rm -rf dist && bun run build:js && bun run build:types",
     "check": "tsc --noEmit",
@@ -60,18 +71,18 @@
     "test": "bun test",
     "test:watch": "bun test --watch",
     "lint": "oxlint src/",
-    "format": "oxfmt src/",
-    "release:version": "node ./scripts/update-release-package-version.mjs"
+    "format": "oxfmt src/"
   },
   "peerDependencies": {
     "vite": ">=6"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.4",
+    "@tanstack/intent": "0.0.21",
     "@types/bun": "^1.3.10",
-    "@types/node": "^24.0.0",
-    "oxfmt": "^0.40.0",
-    "oxlint": "^1.55.0",
+    "@types/node": "^22.0.0",
+    "oxfmt": "0.41.0",
+    "oxlint": "1.56.0",
     "typescript": "^5.0.0",
     "vite": "^8.0.0"
   }

package/revive.d.ts

@@ -1,4 +1,4 @@
 declare module "vite-plugin-shopify-theme-islands/revive" {
-  /** Stops the island MutationObserver. Call during SPA navigation teardown. */
+  /** Stops the island MutationObserver. */
   export const disconnect: () => void;
 }

package/skills/custom-directives/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: custom-directives
+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.
+type: core
+library: vite-plugin-shopify-theme-islands
+library_version: "1.0.0"
+sources:
+  - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
+---
+
+## Setup
+
+```ts
+// src/directives/hover.ts
+import type { ClientDirective } from "vite-plugin-shopify-theme-islands";
+
+const hoverDirective: ClientDirective = (load, _opts, el) => {
+  el.addEventListener("mouseenter", load, { once: true });
+};
+
+export default hoverDirective;
+```
+
+```ts
+// vite.config.ts
+import shopifyThemeIslands from "vite-plugin-shopify-theme-islands";
+
+export default defineConfig({
+  plugins: [
+    shopifyThemeIslands({
+      directives: {
+        custom: [
+          {
+            name: "client:hover",
+            entrypoint: "./src/directives/hover.ts",
+          },
+        ],
+      },
+    }),
+  ],
+});
+```
+
+```html
+<quick-add client:hover></quick-add>
+```
+
+## Core Patterns
+
+### Directive signature
+
+```ts
+import type {
+  ClientDirective,
+  ClientDirectiveLoader,
+  ClientDirectiveOptions,
+} from "vite-plugin-shopify-theme-islands";
+
+const myDirective: ClientDirective = (
+  load: ClientDirectiveLoader,   // call this to trigger the island load
+  options: ClientDirectiveOptions, // { name: "client:my-attr", value: "..." }
+  el: HTMLElement,               // the island element
+) => {
+  // Set up your condition, then call load() when ready
+  el.addEventListener("click", load, { once: true });
+};
+```
+
+### Read the attribute value
+
+```ts
+const timedDirective: ClientDirective = (load, options, el) => {
+  const ms = parseInt(options.value, 10) || 2000;
+  setTimeout(load, ms);
+};
+```
+
+`options.value` is the attribute value, or `""` if the attribute has no value.
+
+### Async directive
+
+```ts
+const networkDirective: ClientDirective = async (load, _opts, el) => {
+  await fetch("/api/check-feature");
+  load();
+};
+```
+
+The directive function can be async. Unhandled rejections fire `islands:error` on the element.
+
+### AND-latch with multiple matching directives
+
+```html
+<product-form client:hover client:visible></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()`.
+
+## Common Mistakes
+
+### CRITICAL Directive never calls `load()` — island never activates
+
+Wrong:
+
+```ts
+const hoverDirective: ClientDirective = (load, _opts, el) => {
+  el.addEventListener("mouseenter", () => {
+    console.log("hovered"); // forgot to call load
+  });
+};
+```
+
+Correct:
+
+```ts
+const hoverDirective: ClientDirective = (load, _opts, el) => {
+  el.addEventListener("mouseenter", load, { once: true });
+};
+```
+
+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 AND-latch: both matched directives must call `load()`
+
+Wrong assumption:
+
+```html
+<product-form client:hover client:auth-check></product-form>
+```
+
+```ts
+// Expecting: loads as soon as either hover or auth-check calls load()
+```
+
+Correct:
+
+```ts
+// Both client:hover AND client:auth-check must call load() before activation.
+// remaining starts at 2; island fires when it reaches 0.
+```
+
+With two matching custom directives, `remaining = 2`. Each `load()` call decrements it. The island activates only when `remaining === 0`.
+
+Source: src/runtime.ts — `let remaining = matched.length`
+
+### HIGH Entrypoint path missing `./` prefix
+
+Wrong:
+
+```ts
+{
+  name: "client:hover",
+  entrypoint: "src/directives/hover.ts", // ← no ./
+}
+```
+
+Correct:
+
+```ts
+{
+  name: "client:hover",
+  entrypoint: "./src/directives/hover.ts",
+}
+```
+
+Vite's resolver may fail to locate the file without the `./` relative prefix. The plugin throws a build error if the entrypoint cannot be resolved.
+
+Source: src/index.ts — `this.resolve(def.entrypoint)` throws on null
+
+### MEDIUM Custom directives run after built-in directive awaits
+
+Wrong expectation:
+
+```html
+<!-- Expecting custom directive to intercept before client:visible -->
+<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.
+
+Source: src/runtime.ts — built-in awaits precede `if (customDirectives?.size)` block
+
+### MEDIUM Calling `load()` multiple times has no effect after the first
+
+Wrong:
+
+```ts
+const retryDirective: ClientDirective = (load, _opts, el) => {
+  setInterval(load, 1000); // calls load every second
+};
+```
+
+Correct:
+
+```ts
+const retryDirective: ClientDirective = (load, _opts, el) => {
+  el.addEventListener("click", load, { once: true }); // fires once
+};
+```
+
+The `loadOnce` wrapper ignores all calls after the first (`fired` guard). Use `{ once: true }` on event listeners to avoid unnecessary calls.
+
+Source: src/runtime.ts — `if (fired || aborted) return Promise.resolve()`

package/skills/directives/SKILL.md

@@ -0,0 +1,167 @@
+---
+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.
+type: core
+library: vite-plugin-shopify-theme-islands
+library_version: "1.0.0"
+sources:
+  - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
+---
+
+## Setup
+
+Add one or more directives as HTML attributes on any custom element:
+
+```html
+<!-- Load when element scrolls into view (200px pre-load margin by default) -->
+<product-form client:visible></product-form>
+
+<!-- Load when CSS media query matches -->
+<mobile-nav client:media="(max-width: 768px)"></mobile-nav>
+
+<!-- Load during browser idle time -->
+<site-footer client:idle></site-footer>
+
+<!-- Load after a fixed delay (ms) -->
+<chat-widget client:defer="5000"></chat-widget>
+```
+
+No JS changes needed — the runtime reads these attributes during DOM walk.
+
+## Core Patterns
+
+### Combining directives — all conditions must pass
+
+```html
+<!-- Loads only when BOTH visible AND the media query match -->
+<product-recommendations
+  client:visible
+  client:media="(min-width: 768px)"
+></product-recommendations>
+```
+
+Combined directives are AND-latched. The island loads only after every condition resolves. There is no OR mode.
+
+### Per-element value overrides
+
+```html
+<!-- Override global rootMargin for this element only -->
+<hero-banner client:visible="0px"></hero-banner>
+
+<!-- Override global idle timeout for this element (ms) -->
+<analytics-widget client:idle="2000"></analytics-widget>
+
+<!-- Fixed delay in ms; empty attribute uses the global default (3000ms) -->
+<chat-widget client:defer="8000"></chat-widget>
+```
+
+The attribute value overrides the globally configured default for that element. Other elements are unaffected.
+
+### `client:defer` without a value uses the global default
+
+```html
+<!-- Uses global defer.delay (default 3000ms) -->
+<chat-widget client:defer></chat-widget>
+
+<!-- Uses 0ms delay — loads on next tick -->
+<chat-widget client:defer="0"></chat-widget>
+```
+
+An empty `client:defer` attribute is NOT zero — it falls back to the configured `defer.delay` (default 3000ms).
+
+### Changing built-in directive defaults globally
+
+```ts
+// vite.config.ts
+shopifyThemeIslands({
+  directives: {
+    visible: { rootMargin: "0px" },
+    defer: { delay: 5000 },
+  },
+});
+```
+
+## Common Mistakes
+
+### HIGH `client:media=""` skips the media check entirely
+
+Wrong:
+
+```html
+<mobile-nav client:media=""></mobile-nav>
+```
+
+Correct:
+
+```html
+<mobile-nav client:media="(max-width: 768px)"></mobile-nav>
+```
+
+An empty `client:media` value emits a console warning and skips the media check — the island loads immediately. Provide a valid media query string.
+
+Source: src/runtime.ts — `if (query === "")` branch
+
+### HIGH Multiple directives are AND, not OR
+
+Wrong assumption:
+
+```html
+<!-- Expecting: load when visible OR when media matches -->
+<product-recs client:visible client:media="(min-width: 768px)"></product-recs>
+```
+
+Correct understanding:
+
+```html
+<!-- Loads only when BOTH visible AND media match -->
+<product-recs client:visible client:media="(min-width: 768px)"></product-recs>
+```
+
+The runtime awaits each directive sequentially. There is no way to express OR semantics with built-in directives — use a custom directive for that.
+
+Source: src/runtime.ts — loadIsland sequential awaits
+
+### MEDIUM `client:defer` without value ≠ immediate load
+
+Wrong:
+
+```html
+<!-- Expecting 0ms or immediate load -->
+<chat-widget client:defer></chat-widget>
+```
+
+Correct:
+
+```html
+<!-- Explicit 0ms for immediate load after current call stack -->
+<chat-widget client:defer="0"></chat-widget>
+```
+
+`client:defer` with no value uses the global `defer.delay` default (3000ms). `parseInt("", 10)` produces `NaN`, which the runtime replaces with the configured default.
+
+Source: src/runtime.ts — `const ms = Number.isNaN(raw) ? deferDelay : raw`
+
+### MEDIUM Per-element visible value replaces rootMargin, not adds to it
+
+Wrong:
+
+```html
+<!-- Expecting 200px (global) + 100px = 300px effective margin -->
+<hero-banner client:visible="100px"></hero-banner>
+```
+
+Correct:
+
+```html
+<!-- "100px" replaces the global rootMargin entirely -->
+<hero-banner client:visible="100px"></hero-banner>
+```
+
+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)`

package/skills/lifecycle/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: lifecycle
+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.
+type: core
+library: vite-plugin-shopify-theme-islands
+library_version: "1.0.0"
+sources:
+  - Rees1993/vite-plugin-shopify-theme-islands:src/events.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
+---
+
+## Setup
+
+```ts
+import { onIslandLoad, onIslandError } from "vite-plugin-shopify-theme-islands/events";
+
+const offLoad = onIslandLoad(({ tag }) => {
+  console.log("loaded:", tag);
+});
+
+const offError = onIslandError(({ tag, error }) => {
+  console.error("failed:", tag, error);
+});
+
+// Remove listeners when no longer needed
+offLoad();
+offError();
+```
+
+## Core Patterns
+
+### Track island load for analytics
+
+```ts
+import { onIslandLoad } from "vite-plugin-shopify-theme-islands/events";
+
+onIslandLoad(({ tag }) => {
+  analytics.track("island_loaded", { component: tag });
+});
+```
+
+`tag` is the lowercased custom element tag name (e.g. `"product-form"`).
+
+### 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` 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.
+
+### Teardown for SPA navigation
+
+```ts
+import { disconnect } from "vite-plugin-shopify-theme-islands/revive";
+
+// Before navigating away / unmounting the page
+disconnect();
+```
+
+`disconnect()` stops the MutationObserver and prevents new islands from activating. Call it before SPA page transitions to avoid activating islands from the previous page's DOM.
+
+### Raw DOM events (when type augmentation is in scope)
+
+```ts
+// DocumentEventMap augmentation is exported from the main package
+import type {} from "vite-plugin-shopify-theme-islands";
+
+document.addEventListener("islands:load", (e) => {
+  console.log(e.detail.tag); // typed as string
+});
+```
+
+The `DocumentEventMap` augmentation is declared in the main package's `index.ts`. It is only in scope when the import is present in the same tsconfig compilation.
+
+## Common Mistakes
+
+### HIGH Raw `addEventListener` without types — `e.detail` is untyped
+
+Wrong:
+
+```ts
+// No import from the package — e is Event, detail is unknown
+document.addEventListener("islands:load", (e) => {
+  console.log(e.detail.tag); // TypeScript error or any
+});
+```
+
+Correct:
+
+```ts
+import { onIslandLoad } from "vite-plugin-shopify-theme-islands/events";
+
+onIslandLoad(({ tag }) => {
+  console.log(tag); // string, always typed
+});
+```
+
+`onIslandLoad` and `onIslandError` are typed unconditionally regardless of tsconfig setup. Use them instead of raw `document.addEventListener` unless the `DocumentEventMap` augmentation is confirmed to be in scope.
+
+Source: src/events.ts
+
+### CRITICAL `disconnect` imported from wrong entry point
+
+Wrong:
+
+```ts
+import { disconnect } from "vite-plugin-shopify-theme-islands/runtime";
+import { disconnect } from "vite-plugin-shopify-theme-islands/island";
+```
+
+Correct:
+
+```ts
+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(...)`
+
+### MEDIUM `onIslandError` fires on every retry, not just final failure
+
+Wrong:
+
+```ts
+onIslandError(({ tag }) => {
+  // Assuming this fires once when the island permanently fails
+  markIslandBroken(tag);
+});
+```
+
+Correct:
+
+```ts
+const seen = new Set<string>();
+onIslandError(({ tag, error }) => {
+  if (!seen.has(tag)) {
+    seen.add(tag);
+    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.
+
+Source: src/runtime.ts — `dispatch("islands:error", ...)` inside `.catch()` before retry check
+
+### MEDIUM `islands:error` fires for custom directive failures too
+
+Wrong assumption:
+
+```ts
+onIslandError(({ tag, error }) => {
+  // Assuming this only fires for failed dynamic import()
+  reportChunkLoadFailure(tag);
+});
+```
+
+`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.
+
+Source: src/runtime.ts — handleDirectiveError dispatches `islands:error`

package/skills/setup/SKILL.md

@@ -0,0 +1,145 @@
+---
+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.
+type: core
+library: vite-plugin-shopify-theme-islands
+library_version: "1.0.0"
+sources:
+  - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
+---
+
+## Setup
+
+```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 },
+    }),
+  ],
+});
+```
+
+Import the virtual module in the theme JS entry point to activate islands:
+
+```ts
+// frontend/js/theme.ts
+import "vite-plugin-shopify-theme-islands/revive";
+```
+
+## Core Patterns
+
+### Configure multiple island directories
+
+```ts
+shopifyThemeIslands({
+  directories: ["/frontend/js/islands/", "/frontend/js/components/"],
+});
+```
+
+### Override built-in directive defaults
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    visible: { rootMargin: "0px", threshold: 0.5 },
+    idle: { timeout: 2000 },
+    defer: { delay: 5000 },
+  },
+});
+```
+
+Per-directive options are deep-merged — overriding `visible.rootMargin` preserves `visible.threshold` at its default of `0`.
+
+### Enable automatic retry with exponential backoff
+
+```ts
+shopifyThemeIslands({
+  retry: { retries: 3, delay: 1000 },
+});
+```
+
+`retries` is the number of attempts after the first failure. `delay` is the base ms — each subsequent retry doubles it (1000ms → 2000ms → 4000ms).
+
+### Enable console debug output
+
+```ts
+shopifyThemeIslands({ debug: true });
+```
+
+Logs discovered islands, active directives per element, and load/error events at startup.
+
+## Common Mistakes
+
+### CRITICAL Virtual module not imported — islands never activate
+
+Wrong:
+
+```ts
+// vite.config.ts — plugin configured but virtual module never imported
+shopifyThemeIslands({ directories: ["/frontend/js/islands/"] });
+```
+
+Correct:
+
+```ts
+// frontend/js/theme.ts
+import "vite-plugin-shopify-theme-islands/revive";
+```
+
+The plugin generates the virtual module but has no effect until it is imported in the browser entry point. Islands are silently never activated.
+
+Source: src/index.ts — VIRTUAL_ID / RESOLVED_ID
+
+### HIGH `retry` nested inside `directives` — no retries happen
+
+Wrong:
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    retry: { retries: 2 }, // ← wrong nesting
+  },
+});
+```
+
+Correct:
+
+```ts
+shopifyThemeIslands({
+  retry: { retries: 2 }, // ← top-level option
+});
+```
+
+`directives` accepts only `visible`, `idle`, `media`, `defer`, and `custom`. `retry` at `directives.retry` is silently ignored.
+
+Source: src/index.ts:ShopifyThemeIslandsOptions
+
+### HIGH Wrong key name for retry count
+
+Wrong:
+
+```ts
+shopifyThemeIslands({ retry: { count: 3 } });
+shopifyThemeIslands({ retry: { attempts: 3 } });
+```
+
+Correct:
+
+```ts
+shopifyThemeIslands({ retry: { retries: 3 } });
+```
+
+Unknown keys are silently ignored. The correct field is `retries`.
+
+Source: src/index.ts:RetryConfig

package/skills/writing-islands/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: writing-islands
+description: >
+  Writing island files. Two discovery modes: directory scanning (files in
+  configured directories auto-discovered by tag name = filename) and Island
+  mixin (import Island from vite-plugin-shopify-theme-islands/island to mark
+  files anywhere in the project). Covers customElements.define, the Island
+  base class, and child island cascade behaviour.
+type: core
+library: vite-plugin-shopify-theme-islands
+library_version: "1.0.0"
+sources:
+  - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
+---
+
+## Setup
+
+### Directory-based island (simplest)
+
+Place the file in a configured island directory. The filename (minus extension) becomes the tag name.
+
+```ts
+// frontend/js/islands/product-form.ts
+class ProductForm extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = "<p>Loaded</p>";
+  }
+}
+
+if (!customElements.get("product-form")) {
+  customElements.define("product-form", ProductForm);
+}
+```
+
+```html
+<!-- In Shopify theme template -->
+<product-form client:visible></product-form>
+```
+
+### Island mixin (file outside islands directory)
+
+Use the `Island` mixin to mark a component for auto-discovery without moving it.
+
+```ts
+// frontend/js/components/cart-drawer.ts
+import Island from "vite-plugin-shopify-theme-islands/island";
+
+class CartDrawer extends Island(HTMLElement) {
+  connectedCallback() {
+    this.innerHTML = "<p>Cart loaded</p>";
+  }
+}
+
+if (!customElements.get("cart-drawer")) {
+  customElements.define("cart-drawer", CartDrawer);
+}
+```
+
+The plugin scans all TS/JS files for the `Island` import at build time and includes matches as lazy chunks.
+
+## Core Patterns
+
+### Guard against duplicate registration
+
+```ts
+if (!customElements.get("product-form")) {
+  customElements.define("product-form", ProductForm);
+}
+```
+
+Required when multiple entry points might import the same island file.
+
+### Child islands activate after their parent
+
+```html
+<cart-drawer client:visible>
+  <cart-line-item client:idle></cart-line-item>
+</cart-drawer>
+```
+
+`cart-line-item` is not activated until `cart-drawer`'s module has resolved. The runtime's TreeWalker rejects subtrees of unloaded parent islands and re-walks them after the parent loads.
+
+### Vite alias in directories
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  resolve: { alias: { "@islands": "/frontend/js/islands" } },
+  plugins: [
+    shopifyThemeIslands({ directories: ["@islands/"] }),
+  ],
+});
+```
+
+The plugin resolves Vite aliases in `directories` during `configResolved`.
+
+## Common Mistakes
+
+### HIGH Island file outside directories without Island mixin
+
+Wrong:
+
+```ts
+// frontend/js/components/search-bar.ts — not in islands directory
+class SearchBar extends HTMLElement {}
+customElements.define("search-bar", SearchBar);
+```
+
+Correct:
+
+```ts
+// frontend/js/components/search-bar.ts
+import Island from "vite-plugin-shopify-theme-islands/island";
+
+class SearchBar extends Island(HTMLElement) {}
+customElements.define("search-bar", SearchBar);
+```
+
+Without the `Island` import the plugin cannot detect the file. The element appears in the DOM but the module is never lazy-loaded.
+
+Source: src/index.ts — ISLAND_IMPORT_RE, scanForIslandFiles
+
+### HIGH Missing `customElements.define` call
+
+Wrong:
+
+```ts
+// frontend/js/islands/mini-cart.ts
+export class MiniCart extends HTMLElement {
+  connectedCallback() {}
+}
+```
+
+Correct:
+
+```ts
+export class MiniCart extends HTMLElement {
+  connectedCallback() {}
+}
+
+if (!customElements.get("mini-cart")) {
+  customElements.define("mini-cart", MiniCart);
+}
+```
+
+The plugin loads the module but the custom element never upgrades without `customElements.define`.
+
+Source: src/runtime.ts — loader() is called but registration is the file's responsibility
+
+### MEDIUM Child island activates before parent is ready
+
+Wrong assumption:
+
+```html
+<!-- Expecting cart-line-item to start its own directive wait immediately -->
+<cart-drawer client:visible>
+  <cart-line-item client:idle></cart-line-item>
+</cart-drawer>
+```
+
+`cart-line-item`'s `client:idle` wait does **not** begin until `cart-drawer` has finished loading. The cascade is sequential, not parallel.
+
+Source: src/runtime.ts — customElementFilter NodeFilter.FILTER_REJECT, walk() after parent loads