vite-plugin-shopify-theme-islands 1.3.0 → 1.3.1

package/README.md

@@ -44,6 +44,8 @@ import { disconnect } from "vite-plugin-shopify-theme-islands/revive";
 disconnect();
 ```
 
+If `disconnect()` is called before `DOMContentLoaded`, the runtime also cancels its pending startup listener so islands never initialize later against stale DOM.
+
 ## Writing islands
 
 Two approaches — use either or both.
@@ -200,7 +202,7 @@ Loads the island when the user interacts with the element. Listens for `mouseent
 </cart-flyout>
 ```
 
-The attribute value overrides the events for that element only (space-separated MDN event names):
+The attribute value overrides the events for that element only:
 
 ```html
 <!-- only mouseenter — touchstart and focusin are excluded -->
@@ -209,6 +211,10 @@ The attribute value overrides the events for that element only (space-separated
 </cart-flyout>
 ```
 
+In plugin config, `directives.interaction.events` is intentionally narrower than the raw HTML attribute surface. The typed config only accepts the curated package-owned set `mouseenter`, `touchstart`, and `focusin`, and rejects empty arrays.
+
+Per-element `client:interaction="..."` values are also validated at runtime against that same curated set. Unsupported tokens log a warning and are ignored. If no supported tokens remain, the runtime logs a warning and falls back to the configured default interaction events instead of attaching unsupported listeners.
+
 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
@@ -362,7 +368,7 @@ shopifyThemeIslands({
     },
     interaction: {
       attribute: "client:interaction", // HTML attribute name
-      events: ["mouseenter", "touchstart", "focusin"], // DOM events that trigger load
+      events: ["mouseenter", "touchstart", "focusin"], // curated config events that trigger load
     },
     custom: [], // custom directives — see Custom directives above
   },
@@ -380,6 +386,8 @@ shopifyThemeIslands({
 });
 ```
 
+For `directives.interaction.events`, supported config values are currently limited to `mouseenter`, `touchstart`, and `focusin`. Passing `[]` or unsupported names causes config resolution to fail.
+
 ### Multiple island directories
 
 ```ts
@@ -442,6 +450,8 @@ offLoad();
 offError();
 ```
 
+For SPA teardown, the virtual `/revive` module also exports `disconnect()`, which stops further lifecycle observation and cancels pending startup before init has run.
+
 ### 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).

package/dist/discovery.d.ts

@@ -2,6 +2,28 @@
 export declare const TS_JS_RE: RegExp;
 /** Matches the island mixin import. Exported for plugin transform/watch detection. */
 export declare const ISLAND_IMPORT_RE: RegExp;
+export interface AliasLike {
+    find: string | RegExp;
+    replacement: string;
+}
+export interface IslandInventoryConfig {
+    root: string;
+    aliases: readonly AliasLike[];
+}
+export interface IslandInventorySnapshot {
+    resolvedDirectories: string[];
+    islandFiles: string[];
+    directoryTagNames: string[];
+}
+export interface IslandInventoryChange {
+    type: "detected" | "removed";
+    file: string;
+}
+export interface IslandInventoryBootstrapState {
+    root: string;
+    directories: string[];
+    islandFiles: Set<string>;
+}
 /** True if file is under any of the given absolute directory paths. */
 export declare function inDirectory(file: string, absDirs: string[]): boolean;
 /** Paths for load() virtual module: "/relative/to/root" form, forward slashes. */
@@ -10,3 +32,11 @@ export declare function getIslandPathsForLoad(islandFiles: Set<string>, root: st
 export declare function discoverIslandFiles(root: string, absDirs: string[]): Set<string>;
 /** Tag names (filename without extension) for TS/JS files in a directory. Used for debug logging. */
 export declare function collectTagNames(dir: string): string[];
+export declare function createIslandInventory(rawDirectories: string[]): {
+    configure(config: IslandInventoryConfig): void;
+    scan(): IslandInventorySnapshot | null;
+    applyTransform(id: string, code: string): IslandInventoryChange | null;
+    applyWatchChange(id: string, event: string): IslandInventoryChange | null;
+    getBootstrapState(): IslandInventoryBootstrapState;
+    getRoot(): string;
+};

package/dist/index.js

@@ -1,6 +1,5 @@
 // src/index.ts
-import { readFileSync as readFileSync2 } from "node:fs";
-import { join as join2, relative as relative2 } from "node:path";
+import { relative as relative2 } from "node:path";
 
 // src/discovery.ts
 import { readFileSync, readdirSync } from "node:fs";
@@ -35,6 +34,21 @@ function walkDir(dir, visitor) {
       visitor(entry.name, full);
   }
 }
+function resolveAliases(dirs, aliasesInput) {
+  const aliases = [...aliasesInput].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))
+        return dir.replace(find, replacement);
+      if (find instanceof RegExp && find.test(dir))
+        return dir.replace(find, replacement);
+    }
+    return dir;
+  });
+}
+function toAbsoluteDirs(root, resolvedDirs) {
+  return resolvedDirs.map((dir) => dir.startsWith(root) ? dir : join(root, dir.replace(/^\//, "")));
+}
 function discoverIslandFiles(root, absDirs) {
   const found = new Set;
   walkDir(root, (_, full) => {
@@ -53,10 +67,73 @@ function collectTagNames(dir) {
   walkDir(dir, (name) => names.push(name.replace(TS_JS_RE, "")));
   return names;
 }
+function createIslandInventory(rawDirectories) {
+  let root = process.cwd();
+  let resolvedDirs = [...rawDirectories];
+  let absDirs = [...rawDirectories];
+  const islandFiles = new Set;
+  let scanned = false;
+  const buildSnapshot = () => ({
+    resolvedDirectories: [...resolvedDirs],
+    islandFiles: [...islandFiles],
+    directoryTagNames: absDirs.flatMap((dir) => collectTagNames(dir))
+  });
+  const updateIslandFile = (id, code) => {
+    if (!TS_JS_RE.test(id))
+      return null;
+    if (code.includes("shopify-theme-islands/island") && ISLAND_IMPORT_RE.test(code) && !inDirectory(id, absDirs)) {
+      const sizeBefore = islandFiles.size;
+      islandFiles.add(id);
+      return islandFiles.size !== sizeBefore ? { type: "detected", file: id } : null;
+    }
+    return islandFiles.delete(id) ? { type: "removed", file: id } : null;
+  };
+  return {
+    configure(config) {
+      root = config.root;
+      resolvedDirs = resolveAliases(rawDirectories, config.aliases);
+      absDirs = toAbsoluteDirs(root, resolvedDirs);
+    },
+    scan() {
+      if (scanned)
+        return null;
+      scanned = true;
+      islandFiles.clear();
+      discoverIslandFiles(root, absDirs).forEach((file) => islandFiles.add(file));
+      return buildSnapshot();
+    },
+    applyTransform(id, code) {
+      return updateIslandFile(id, code);
+    },
+    applyWatchChange(id, event) {
+      if (!TS_JS_RE.test(id))
+        return null;
+      if (event === "delete") {
+        return islandFiles.delete(id) ? { type: "removed", file: id } : null;
+      }
+      try {
+        return updateIslandFile(id, readFileSync(id, "utf-8"));
+      } catch {
+        return null;
+      }
+    },
+    getBootstrapState() {
+      return {
+        root,
+        directories: [...resolvedDirs],
+        islandFiles: new Set(islandFiles)
+      };
+    },
+    getRoot() {
+      return root;
+    }
+  };
+}
 
 // src/interaction-events.ts
 var INTERACTION_EVENT_NAMES = ["mouseenter", "touchstart", "focusin"];
 var DEFAULT_INTERACTION_EVENTS = [...INTERACTION_EVENT_NAMES];
+var INTERACTION_EVENT_NAMES_LABEL = INTERACTION_EVENT_NAMES.join(", ");
 var INTERACTION_EVENT_NAME_SET = new Set(INTERACTION_EVENT_NAMES);
 var PREFIX = "[vite-plugin-shopify-theme-islands]";
 function isInteractionEventName(value) {
@@ -68,11 +145,23 @@ function validateInteractionEvents(events) {
   if (events.length === 0) {
     throw new Error(`${PREFIX} "directives.interaction.events" must not be empty`);
   }
-  const invalidEvent = events.find((eventName) => !isInteractionEventName(eventName));
+  const { invalid } = partitionInteractionEventTokens(events);
+  const invalidEvent = invalid[0];
   if (invalidEvent) {
     throw new Error(`${PREFIX} "directives.interaction.events" contains unsupported event "${invalidEvent}"`);
   }
 }
+function partitionInteractionEventTokens(tokens) {
+  const valid = [];
+  const invalid = [];
+  for (const token of tokens) {
+    if (isInteractionEventName(token))
+      valid.push(token);
+    else
+      invalid.push(token);
+  }
+  return { valid, invalid };
+}
 
 // src/contract.ts
 var DEFAULT_DIRECTIVES = {
@@ -234,9 +323,10 @@ function createReviveBootstrapCompiler(ports, runtimePath) {
         name,
         entrypoint: await ports.resolveEntrypoint(entrypoint)
       }))) : null;
+      const directoryGlobs = input.directories.map((dir) => dir + "**/*.{ts,js}");
       return {
         runtimePath,
-        directoryGlobs: input.directories.map((dir) => dir + "**/*.{ts,js}"),
+        directoryGlobs,
         islandPaths,
         customDirectives,
         reviveOptions: input.reviveOptions
@@ -265,89 +355,57 @@ var defaultDirectories = ["/frontend/js/islands/"];
 function normalizeDir(dir) {
   return dir.endsWith("/") ? dir : dir + "/";
 }
-function resolveAliases(dirs, config) {
-  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))
-        return dir.replace(find, replacement);
-      if (find instanceof RegExp && find.test(dir))
-        return dir.replace(find, replacement);
-    }
-    return dir;
-  });
-}
 function shopifyThemeIslands(options = {}) {
   const rawDirs = (Array.isArray(options.directories) ? options.directories : [options.directories ?? defaultDirectories[0]]).map(normalizeDir);
   const policy = resolveThemeIslandsPolicy(options);
   const { directives, customDirectives: clientDirectiveDefinitions, debug } = policy.plugin;
   const { runtime: reviveOptions } = policy;
   const log = debug ? (...args) => console.log("[islands]", ...args) : () => {};
-  let resolvedDirs = rawDirs;
-  let root = process.cwd();
-  let absDirs = rawDirs;
-  const islandFiles = new Set;
-  let scanned = false;
+  const inventory = createIslandInventory(rawDirs);
   return {
     name: "vite-plugin-shopify-theme-islands",
     enforce: "pre",
     configResolved(config) {
-      root = config.root;
-      resolvedDirs = resolveAliases(rawDirs, config);
-      absDirs = resolvedDirs.map((d) => d.startsWith(root) ? d : join2(root, d.replace(/^\//, "")));
+      inventory.configure({
+        root: config.root,
+        aliases: config.resolve.alias
+      });
     },
     buildStart() {
-      if (scanned)
-        return;
-      scanned = true;
       const t0 = performance.now();
-      const initial = discoverIslandFiles(root, absDirs);
-      islandFiles.clear();
-      initial.forEach((f) => islandFiles.add(f));
+      const snapshot = inventory.scan();
+      if (!snapshot)
+        return;
       if (debug) {
         const scanMs = (performance.now() - t0).toFixed(1);
         log(`Scanned in ${scanMs}ms`);
-        log("Scanning directories:", resolvedDirs.map((d) => d + "**/*.{ts,js}").join(", "));
-        const dirNames = absDirs.flatMap((dir) => collectTagNames(dir));
-        if (dirNames.length)
-          log(`Found ${dirNames.length} directory island(s): [${dirNames.join(", ")}]`);
-        if (islandFiles.size) {
-          log(`Found ${islandFiles.size} island file(s) via mixin import:`);
-          for (const f of islandFiles)
-            log(" ", relative2(root, f));
+        log("Scanning directories:", snapshot.resolvedDirectories.map((dir) => dir + "**/*.{ts,js}").join(", "));
+        if (snapshot.directoryTagNames.length) {
+          log(`Found ${snapshot.directoryTagNames.length} directory island(s): [${snapshot.directoryTagNames.join(", ")}]`);
+        }
+        if (snapshot.islandFiles.length) {
+          const root = inventory.getRoot();
+          log(`Found ${snapshot.islandFiles.length} island file(s) via mixin import:`);
+          for (const file of snapshot.islandFiles)
+            log(" ", relative2(root, file));
         }
         log("Directives:", directives);
       }
     },
     transform(code, id) {
-      if (!TS_JS_RE.test(id))
+      const change = inventory.applyTransform(id, code);
+      if (!change)
         return;
-      if (code.includes("shopify-theme-islands/island") && ISLAND_IMPORT_RE.test(code) && !inDirectory(id, absDirs)) {
-        islandFiles.add(id);
-        log("Detected island:", relative2(root, id));
-      } else {
-        if (islandFiles.delete(id))
-          log("Removed island:", relative2(root, id));
-      }
+      const root = inventory.getRoot();
+      log(change.type === "detected" ? "Detected island:" : "Removed island:", relative2(root, change.file));
     },
     watchChange(id, { event }) {
-      if (!TS_JS_RE.test(id))
+      const change = inventory.applyWatchChange(id, event);
+      if (!change)
         return;
-      if (event === "delete") {
-        if (islandFiles.delete(id))
-          log("Removed island (deleted):", relative2(root, id));
-      } else {
-        try {
-          const content = readFileSync2(id, "utf-8");
-          if (ISLAND_IMPORT_RE.test(content) && !inDirectory(id, absDirs)) {
-            islandFiles.add(id);
-            log("Detected island (watchChange):", relative2(root, id));
-          } else {
-            if (islandFiles.delete(id))
-              log("Removed island (watchChange):", relative2(root, id));
-          }
-        } catch {}
-      }
+      const root = inventory.getRoot();
+      const prefix = event === "delete" ? "Removed island (deleted):" : change.type === "detected" ? "Detected island (watchChange):" : "Removed island (watchChange):";
+      log(prefix, relative2(root, change.file));
     },
     resolveId(id) {
       if (id === VIRTUAL_ID)
@@ -369,9 +427,7 @@ function shopifyThemeIslands(options = {}) {
         toLoadPaths: getIslandPathsForLoad
       }, runtimePath);
       const plan = await compiler.plan({
-        root,
-        directories: resolvedDirs,
-        islandFiles,
+        ...inventory.getBootstrapState(),
         customDirectives: clientDirectiveDefinitions,
         reviveOptions
       });

package/dist/interaction-events.d.ts

@@ -8,5 +8,11 @@
 export declare const INTERACTION_EVENT_NAMES: readonly ["mouseenter", "touchstart", "focusin"];
 export type InteractionEventName = (typeof INTERACTION_EVENT_NAMES)[number];
 export declare const DEFAULT_INTERACTION_EVENTS: readonly ["mouseenter", "touchstart", "focusin"];
+export declare const INTERACTION_EVENT_NAMES_LABEL: string;
+export interface InteractionEventTokenPartition {
+    valid: InteractionEventName[];
+    invalid: string[];
+}
 export declare function isInteractionEventName(value: string): value is InteractionEventName;
 export declare function validateInteractionEvents(events: readonly string[] | undefined): asserts events is readonly InteractionEventName[];
+export declare function partitionInteractionEventTokens(tokens: readonly string[]): InteractionEventTokenPartition;

package/dist/runtime.js

@@ -1,6 +1,7 @@
 // src/interaction-events.ts
 var INTERACTION_EVENT_NAMES = ["mouseenter", "touchstart", "focusin"];
 var DEFAULT_INTERACTION_EVENTS = [...INTERACTION_EVENT_NAMES];
+var INTERACTION_EVENT_NAMES_LABEL = INTERACTION_EVENT_NAMES.join(", ");
 var INTERACTION_EVENT_NAME_SET = new Set(INTERACTION_EVENT_NAMES);
 var PREFIX = "[vite-plugin-shopify-theme-islands]";
 function isInteractionEventName(value) {
@@ -12,11 +13,23 @@ function validateInteractionEvents(events) {
   if (events.length === 0) {
     throw new Error(`${PREFIX} "directives.interaction.events" must not be empty`);
   }
-  const invalidEvent = events.find((eventName) => !isInteractionEventName(eventName));
+  const { invalid } = partitionInteractionEventTokens(events);
+  const invalidEvent = invalid[0];
   if (invalidEvent) {
     throw new Error(`${PREFIX} "directives.interaction.events" contains unsupported event "${invalidEvent}"`);
   }
 }
+function partitionInteractionEventTokens(tokens) {
+  const valid = [];
+  const invalid = [];
+  for (const token of tokens) {
+    if (isInteractionEventName(token))
+      valid.push(token);
+    else
+      invalid.push(token);
+  }
+  return { valid, invalid };
+}
 
 // src/contract.ts
 var DEFAULT_DIRECTIVES = {
@@ -184,10 +197,19 @@ function createDirectiveOrchestrator(waiters = {
       let events = [...directives.interaction.events];
       if (interactionAttr) {
         const tokens = interactionAttr.split(/\s+/).filter(Boolean);
-        if (tokens.length > 0)
-          events = tokens;
-        else {
+        if (tokens.length === 0) {
           console.warn(`[islands] <${tagName}> ${directives.interaction.attribute} has no valid event tokens — using default events`);
+        } else {
+          const { valid, invalid } = partitionInteractionEventTokens(tokens);
+          if (invalid.length > 0) {
+            if (valid.length > 0) {
+              console.warn(`[islands] <${tagName}> ${directives.interaction.attribute} contains unsupported event token${invalid.length === 1 ? "" : "s"} (${invalid.join(", ")}) — ignoring invalid token${invalid.length === 1 ? "" : "s"}; supported tokens: ${INTERACTION_EVENT_NAMES_LABEL}`);
+            } else {
+              console.warn(`[islands] <${tagName}> ${directives.interaction.attribute} contains no supported event tokens (${invalid.join(", ")}) — using default events; supported tokens: ${INTERACTION_EVENT_NAMES_LABEL}`);
+            }
+          }
+          if (valid.length > 0)
+            events = valid;
         }
       }
       log.note(`waiting for ${directives.interaction.attribute} (${events.join(", ")})`);

package/package.json

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

package/skills/custom-directives/SKILL.md

@@ -10,7 +10,7 @@ description: >
   are owned by src/directive-orchestration.ts.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.3.0"
+library_version: "1.3.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/directive-orchestration.ts

package/skills/directives/SKILL.md

@@ -6,14 +6,16 @@ description: >
   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. Whitespace-only client:interaction values warn and fall back to
-  default events. Global `directives.interaction.events` config is intentionally
-  narrowed to the curated set `mouseenter`, `touchstart`, and `focusin`.
-  Current directive sequencing and custom-directive latching are owned by
-  src/directive-orchestration.ts.
+  warning. `client:interaction` now validates per-element tokens at runtime:
+  whitespace-only values warn and fall back; mixed supported/unsupported values
+  warn and ignore the unsupported tokens; fully unsupported values warn and fall
+  back to default events. Global `directives.interaction.events` config is
+  intentionally narrowed to the curated set `mouseenter`, `touchstart`, and
+  `focusin`. Current directive sequencing and custom-directive latching are
+  owned by src/directive-orchestration.ts.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.3.0"
+library_version: "1.3.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/directive-orchestration.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
@@ -79,6 +81,7 @@ Combined directives are AND-latched. The island loads only after every condition
 
 The attribute value overrides the globally configured default for that element. Other elements are unaffected.
 In config, `directives.interaction.events` is stricter and only accepts the curated package-owned list: `mouseenter`, `touchstart`, and `focusin`.
+At runtime, per-element `client:interaction` values use that same curated set. Unsupported tokens are ignored with a warning; if no supported tokens remain, the runtime warns and falls back to the default interaction events.
 
 ### `client:defer` without a value uses the global default
 
@@ -106,6 +109,18 @@ An empty `client:interaction` attribute uses the configured default events with
 
 Source: src/directive-orchestration.ts — interaction token parsing and fallback warning
 
+### Mixed supported and unsupported interaction tokens
+
+```html
+<!-- "click" is ignored with a warning; "mouseenter" still triggers load -->
+<cart-flyout client:interaction="mouseenter click"></cart-flyout>
+
+<!-- No supported tokens remain; warns and falls back to default events -->
+<cart-flyout client:interaction="click submit"></cart-flyout>
+```
+
+Per-element values are no longer treated as an unconstrained event surface. The runtime filters them against the curated package-owned set.
+
 ### Changing built-in directive defaults globally
 
 ```ts
@@ -169,6 +184,25 @@ Whitespace-only values are not treated the same as an empty attribute. The runti
 
 Source: src/directive-orchestration.ts — `interactionAttr.split(/\s+/).filter(Boolean)`
 
+### MEDIUM Unsupported per-element interaction tokens are warned and ignored
+
+Wrong:
+
+```html
+<cart-flyout client:interaction="mouseenter click"></cart-flyout>
+```
+
+Correct:
+
+```html
+<!-- Use only the curated supported tokens -->
+<cart-flyout client:interaction="mouseenter focusin"></cart-flyout>
+```
+
+The runtime no longer attaches arbitrary listeners for unsupported per-element tokens. Supported tokens still work; unsupported ones are ignored with a warning. If no supported tokens remain, the runtime falls back to the configured default events.
+
+Source: src/directive-orchestration.ts — `partitionInteractionEventTokens()` handling
+
 ### HIGH Multiple directives are AND, not OR
 
 Wrong assumption:

package/skills/lifecycle/SKILL.md

@@ -10,10 +10,11 @@ description: >
   expiry. disconnect() from the virtual module revive for SPA navigation
   teardown, including before DOMContentLoaded — it now prevents init from ever
   starting if called early. Startup, DOM walking, mutation observation, and
-  parent/child activation gating are now owned by src/lifecycle.ts.
+  parent/child activation gating are now owned by src/lifecycle.ts, while
+  runtime observability and event dispatch are routed through src/runtime-surface.ts.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.3.0"
+library_version: "1.3.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/events.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime-surface.ts
@@ -94,6 +95,8 @@ disconnect();
 
 The startup walk itself is now lifecycle-owned. The runtime resolves the root lazily at init time, then the lifecycle coordinator performs the initial walk, begins observing subtree additions, and keeps child islands gated behind queued parents until the parent resolves.
 
+Load/error events and debug-ready groups are dispatched through the runtime surface, but the user-facing lifecycle behavior remains the same: startup is lazy, activation is subtree-aware, and teardown prevents later observation.
+
 ### Raw DOM events (when type augmentation is in scope)
 
 ```ts

package/skills/setup/SKILL.md

@@ -7,11 +7,14 @@ description: >
   defer, interaction, custom), retry (retries, delay with exponential
   backoff), directiveTimeout for hung custom directives, and the curated
   interaction-event config policy (`mouseenter`, `touchstart`, `focusin`; empty
-  arrays rejected). Load when setting up the plugin, configuring island scan
-  directories, or enabling retry / directive timeout.
+  arrays rejected). Per-element `client:interaction` values are runtime-validated
+  against the same curated set: unsupported tokens warn and are ignored; if no
+  supported tokens remain, the runtime falls back to the configured default
+  events. 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.3.0"
+library_version: "1.3.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
@@ -51,6 +54,10 @@ import "vite-plugin-shopify-theme-islands/revive";
 
 This activates the runtime — islands are never loaded without this import.
 
+For SPA teardown, the virtual `/revive` module also exports `disconnect()`.
+If it is called before `DOMContentLoaded`, the runtime cancels its pending
+startup listener so islands never initialize later against stale DOM.
+
 ### 3. Add directives to Liquid templates
 
 ```html
@@ -86,6 +93,7 @@ shopifyThemeIslands({
 
 Per-directive options are deep-merged — overriding `visible.rootMargin` preserves `visible.threshold` at its default of `0`.
 For config, `directives.interaction.events` is intentionally narrow and only accepts `mouseenter`, `touchstart`, and `focusin`.
+Per-element `client:interaction="..."` values are checked at runtime against that same set. Unsupported tokens warn and are ignored; if all tokens are unsupported, the runtime warns and falls back to the configured default events.
 
 ### Enable automatic retry with exponential backoff
 

package/skills/writing-islands/SKILL.md

@@ -9,7 +9,7 @@ description: >
   src/lifecycle.ts.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.3.0"
+library_version: "1.3.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/discovery.ts