vite-plugin-shopify-theme-islands 1.2.2 → 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/contract.d.ts

@@ -4,6 +4,7 @@
  * Single source of truth for the payload shape, key→tag derivation, and defaults.
  * Plugin and runtime both depend on this module in-process.
  */
+import type { InteractionEventName } from "./interaction-events.js";
 /** Loader function for one island chunk. */
 export type IslandLoader = () => Promise<unknown>;
 /** Directive config for the runtime (built-in + no plugin-only `custom` entrypoints). */
@@ -26,7 +27,7 @@ export interface RuntimeDirectivesConfig {
     };
     interaction?: {
         attribute?: string;
-        events?: string[];
+        events?: readonly InteractionEventName[];
     };
 }
 /** Retry configuration. */
@@ -111,7 +112,7 @@ export interface NormalizedReviveOptions {
         };
         interaction: {
             attribute: string;
-            events: string[];
+            events: readonly InteractionEventName[];
         };
     };
     debug: boolean;

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

@@ -5,4 +5,6 @@ export type ClientDirectiveLoader = () => Promise<void>;
 export type { ClientDirective, ClientDirectiveOptions } from "./contract.js";
 export type { ClientDirectiveDefinition, DirectivesConfig, ShopifyThemeIslandsOptions, } from "./options.js";
 export type { IslandLoadDetail, IslandErrorDetail, ReviveOptions, RetryConfig, RuntimeDirectivesConfig, } from "./contract.js";
+export type { InteractionEventName } from "./interaction-events.js";
+export { DEFAULT_INTERACTION_EVENTS, INTERACTION_EVENT_NAMES, isInteractionEventName, } from "./interaction-events.js";
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;

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,6 +67,101 @@ 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) {
+  return INTERACTION_EVENT_NAME_SET.has(value);
+}
+function validateInteractionEvents(events) {
+  if (events === undefined)
+    return;
+  if (events.length === 0) {
+    throw new Error(`${PREFIX} "directives.interaction.events" must not be empty`);
+  }
+  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 = {
@@ -62,7 +171,7 @@ var DEFAULT_DIRECTIVES = {
   defer: { attribute: "client:defer", delay: 3000 },
   interaction: {
     attribute: "client:interaction",
-    events: ["mouseenter", "touchstart", "focusin"]
+    events: [...DEFAULT_INTERACTION_EVENTS]
   }
 };
 var DEFAULT_RETRY = { retries: 0, delay: 1000 };
@@ -70,6 +179,7 @@ function normalizeReviveOptions(options) {
   const d = DEFAULT_DIRECTIVES;
   const r = DEFAULT_RETRY;
   const dir = options?.directives;
+  validateInteractionEvents(dir?.interaction?.events);
   return {
     directives: {
       visible: { ...d.visible, ...dir?.visible },
@@ -105,7 +215,7 @@ function buildIslandMap(payload) {
 }
 
 // src/config-policy.ts
-var PREFIX = "[vite-plugin-shopify-theme-islands]";
+var PREFIX2 = "[vite-plugin-shopify-theme-islands]";
 function mergeDirectives(directives) {
   return {
     visible: { ...DEFAULT_DIRECTIVES.visible, ...directives?.visible },
@@ -118,19 +228,21 @@ function mergeDirectives(directives) {
 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`);
+    throw new Error(`${PREFIX2} "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}`);
+    throw new Error(`${PREFIX2} "directives.visible.threshold" must be between 0 and 1, got ${threshold}`);
   }
+  const interactionEvents = options.directives?.interaction?.events;
+  validateInteractionEvents(interactionEvents);
   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}`);
+      throw new Error(`${PREFIX2} "retry.retries" must be >= 0, got ${retries}`);
     }
     if (delay !== undefined && delay < 0) {
-      throw new Error(`${PREFIX} "retry.delay" must be >= 0, got ${delay}`);
+      throw new Error(`${PREFIX2} "retry.delay" must be >= 0, got ${delay}`);
     }
   }
   const builtinAttributes = new Set([
@@ -143,10 +255,10 @@ function validateOptions(options, directives) {
   const seen = new Set;
   for (const def of customDefs) {
     if (seen.has(def.name)) {
-      throw new Error(`${PREFIX} Duplicate custom directive name: "${def.name}"`);
+      throw new Error(`${PREFIX2} 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`);
+      throw new Error(`${PREFIX2} Custom directive "${def.name}" conflicts with a built-in directive`);
     }
     seen.add(def.name);
   }
@@ -211,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
@@ -242,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)
@@ -346,9 +427,7 @@ function shopifyThemeIslands(options = {}) {
         toLoadPaths: getIslandPathsForLoad
       }, runtimePath);
       const plan = await compiler.plan({
-        root,
-        directories: resolvedDirs,
-        islandFiles,
+        ...inventory.getBootstrapState(),
         customDirectives: clientDirectiveDefinitions,
         reviveOptions
       });
@@ -357,5 +436,8 @@ function shopifyThemeIslands(options = {}) {
   };
 }
 export {
-  shopifyThemeIslands as default
+  isInteractionEventName,
+  shopifyThemeIslands as default,
+  INTERACTION_EVENT_NAMES,
+  DEFAULT_INTERACTION_EVENTS
 };

package/dist/interaction-events.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Curated interaction events accepted by `client:interaction`.
+ *
+ * The list is intentionally narrow: these are the user-intent signals the
+ * plugin supports for now, and they are exposed as a package-owned union so
+ * config can be type-checked without relying on the DOM lib surface.
+ */
+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/lifecycle.d.ts

@@ -0,0 +1,27 @@
+import type { IslandLoader } from "./contract.js";
+export interface IslandLifecycleStartInput {
+    getRoot(): HTMLElement | null;
+    islandMap: Map<string, IslandLoader>;
+    onActivate(tagName: string, el: HTMLElement, loader: () => Promise<unknown>): void;
+    onBeforeInitialWalk?: () => void;
+    onInitialWalkComplete?: () => void;
+}
+export interface IslandLifecycle {
+    settleSuccess(tag: string): number;
+    settleFailure(tag: string): {
+        retryDelayMs: number | null;
+        attempt: number;
+    };
+    evict(tag: string): void;
+    isQueued(tag: string): boolean;
+    readonly initialWalkComplete: boolean;
+    watchCancellable(el: Element, cancel: () => void): () => void;
+    walk(root: HTMLElement): void;
+    start(input: IslandLifecycleStartInput): {
+        disconnect: () => void;
+    };
+}
+export declare function createIslandLifecycleCoordinator(opts: {
+    retries: number;
+    retryDelay: number;
+}): IslandLifecycle;

package/dist/options.d.ts

@@ -1,4 +1,5 @@
 import type { RetryConfig } from "./contract.js";
+import type { InteractionEventName } from "./interaction-events.js";
 /** Plugin option entry for registering a custom client directive. */
 export interface ClientDirectiveDefinition {
     /** HTML attribute name, e.g. `'client:on-click'` */
@@ -40,8 +41,8 @@ export interface DirectivesConfig {
     interaction?: {
         /** HTML attribute name. Default: `'client:interaction'` */
         attribute?: string;
-        /** DOM event names to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
-        events?: string[];
+        /** Curated intent events to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
+        events?: readonly InteractionEventName[];
     };
     /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
     custom?: ClientDirectiveDefinition[];

package/dist/runtime.js

@@ -1,3 +1,36 @@
+// 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) {
+  return INTERACTION_EVENT_NAME_SET.has(value);
+}
+function validateInteractionEvents(events) {
+  if (events === undefined)
+    return;
+  if (events.length === 0) {
+    throw new Error(`${PREFIX} "directives.interaction.events" must not be empty`);
+  }
+  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 = {
   visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
@@ -6,7 +39,7 @@ var DEFAULT_DIRECTIVES = {
   defer: { attribute: "client:defer", delay: 3000 },
   interaction: {
     attribute: "client:interaction",
-    events: ["mouseenter", "touchstart", "focusin"]
+    events: [...DEFAULT_INTERACTION_EVENTS]
   }
 };
 var DEFAULT_RETRY = { retries: 0, delay: 1000 };
@@ -14,6 +47,7 @@ function normalizeReviveOptions(options) {
   const d = DEFAULT_DIRECTIVES;
   const r = DEFAULT_RETRY;
   const dir = options?.directives;
+  validateInteractionEvents(dir?.interaction?.events);
   return {
     directives: {
       visible: { ...d.visible, ...dir?.visible },
@@ -160,13 +194,22 @@ function createDirectiveOrchestrator(waiters = {
     }
     const interactionAttr = el.getAttribute(directives.interaction.attribute);
     if (interactionAttr !== null) {
-      let events = directives.interaction.events;
+      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(", ")})`);
@@ -231,6 +274,145 @@ function createDirectiveOrchestrator(waiters = {
   };
 }
 
+// src/lifecycle.ts
+function createIslandLifecycleCoordinator(opts) {
+  const queued = new Set;
+  const loaded = new Set;
+  const retryCount = new Map;
+  const cancellableElements = new Map;
+  let initialWalkComplete = false;
+  let walkImpl;
+  const queue = (tag) => {
+    if (queued.has(tag) || loaded.has(tag))
+      return false;
+    queued.add(tag);
+    return true;
+  };
+  const settleSuccess = (tag) => {
+    const attempt = (retryCount.get(tag) ?? 0) + 1;
+    queued.delete(tag);
+    loaded.add(tag);
+    retryCount.delete(tag);
+    return attempt;
+  };
+  const settleFailure = (tag) => {
+    const attempt = (retryCount.get(tag) ?? 0) + 1;
+    if (attempt <= opts.retries) {
+      retryCount.set(tag, attempt);
+      return { retryDelayMs: opts.retryDelay * 2 ** (attempt - 1), attempt };
+    }
+    retryCount.delete(tag);
+    queued.delete(tag);
+    return { retryDelayMs: null, attempt };
+  };
+  const evict = (tag) => {
+    retryCount.delete(tag);
+    queued.delete(tag);
+  };
+  const isQueued = (tag) => queued.has(tag);
+  const watchCancellable = (el, cancel) => {
+    cancellableElements.set(el, cancel);
+    return () => {
+      cancellableElements.delete(el);
+    };
+  };
+  const cancelDetached = () => {
+    if (cancellableElements.size === 0)
+      return;
+    for (const [el, cancel] of cancellableElements) {
+      if (!el.isConnected) {
+        cancellableElements.delete(el);
+        cancel();
+      }
+    }
+  };
+  const start = (input) => {
+    let disconnected = false;
+    let initialized = false;
+    const customElementFilter = {
+      acceptNode: (node) => {
+        const tag = node.tagName;
+        if (!tag.includes("-"))
+          return NodeFilter.FILTER_SKIP;
+        return isQueued(tag.toLowerCase()) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT;
+      }
+    };
+    const activate = (el) => {
+      const tagName = el.tagName.toLowerCase();
+      const loader = input.islandMap.get(tagName);
+      if (!loader)
+        return;
+      let ancestor = el.parentElement;
+      while (ancestor) {
+        if (isQueued(ancestor.tagName.toLowerCase()))
+          return;
+        ancestor = ancestor.parentElement;
+      }
+      if (!queue(tagName))
+        return;
+      input.onActivate(tagName, el, loader);
+    };
+    const walk = (el) => {
+      activate(el);
+      const walker = document.createTreeWalker(el, NodeFilter.SHOW_ELEMENT, customElementFilter);
+      let node;
+      while (node = walker.nextNode())
+        activate(node);
+    };
+    walkImpl = walk;
+    const handleAdditions = (mutations) => {
+      for (const { addedNodes } of mutations) {
+        for (const node of addedNodes) {
+          if (node.nodeType === Node.ELEMENT_NODE)
+            walk(node);
+        }
+      }
+    };
+    const observer = new MutationObserver((mutations) => {
+      cancelDetached();
+      handleAdditions(mutations);
+    });
+    const init = () => {
+      if (disconnected || initialized)
+        return;
+      const root = input.getRoot();
+      if (!root)
+        return;
+      initialized = true;
+      input.onBeforeInitialWalk?.();
+      walk(root);
+      initialWalkComplete = true;
+      input.onInitialWalkComplete?.();
+      observer.observe(root, { childList: true, subtree: true });
+    };
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", init, { once: true });
+    } else {
+      init();
+    }
+    const disconnect = () => {
+      disconnected = true;
+      document.removeEventListener("DOMContentLoaded", init);
+      observer.disconnect();
+    };
+    return { disconnect };
+  };
+  return {
+    settleSuccess,
+    settleFailure,
+    evict,
+    isQueued,
+    get initialWalkComplete() {
+      return initialWalkComplete;
+    },
+    watchCancellable,
+    walk(root) {
+      walkImpl?.(root);
+    },
+    start
+  };
+}
+
 // src/runtime-surface.ts
 var SILENT_LOGGER = {
   note() {},
@@ -300,68 +482,6 @@ function getRuntimeSurface() {
 function isRevivePayload(v) {
   return typeof v === "object" && v !== null && "islands" in v && !Array.isArray(v);
 }
-function createIslandRegistry(opts) {
-  const queued = new Set;
-  const loaded = new Set;
-  const retryCount = new Map;
-  const cancellableElements = new Map;
-  let initialWalkComplete = false;
-  return {
-    queue(tag) {
-      if (queued.has(tag) || loaded.has(tag))
-        return false;
-      queued.add(tag);
-      return true;
-    },
-    settleSuccess(tag) {
-      const attempt = (retryCount.get(tag) ?? 0) + 1;
-      queued.delete(tag);
-      loaded.add(tag);
-      retryCount.delete(tag);
-      return attempt;
-    },
-    settleFailure(tag) {
-      const attempt = (retryCount.get(tag) ?? 0) + 1;
-      if (attempt <= opts.retries) {
-        retryCount.set(tag, attempt);
-        return { retryDelayMs: opts.retryDelay * 2 ** (attempt - 1), attempt };
-      } else {
-        retryCount.delete(tag);
-        queued.delete(tag);
-        return { retryDelayMs: null, attempt };
-      }
-    },
-    evict(tag) {
-      retryCount.delete(tag);
-      queued.delete(tag);
-    },
-    isQueued(tag) {
-      return queued.has(tag);
-    },
-    get initialWalkComplete() {
-      return initialWalkComplete;
-    },
-    markInitialWalkComplete() {
-      initialWalkComplete = true;
-    },
-    watchCancellable(el, cancel) {
-      cancellableElements.set(el, cancel);
-      return () => {
-        cancellableElements.delete(el);
-      };
-    },
-    cancelDetached() {
-      if (cancellableElements.size === 0)
-        return;
-      for (const [el, cancel] of cancellableElements) {
-        if (!el.isConnected) {
-          cancellableElements.delete(el);
-          cancel();
-        }
-      }
-    }
-  };
-}
 function revive(islandsOrPayload, options, customDirectives) {
   const runtimeSurface2 = getRuntimeSurface();
   const payload = isRevivePayload(islandsOrPayload) ? islandsOrPayload : { islands: islandsOrPayload, options, customDirectives };
@@ -375,24 +495,14 @@ function revive(islandsOrPayload, options, customDirectives) {
   const attrInteraction = opts.directives.interaction.attribute;
   const debug = opts.debug;
   const directiveTimeout = opts.directiveTimeout;
-  const registry = createIslandRegistry({
+  const lifecycle = createIslandLifecycleCoordinator({
     retries: opts.retry.retries,
     retryDelay: opts.retry.delay
   });
   const directiveOrchestrator = createDirectiveOrchestrator();
-  const customElementFilter = {
-    acceptNode: (node) => {
-      const tag = node.tagName;
-      if (!tag.includes("-"))
-        return NodeFilter.FILTER_SKIP;
-      const lowerTag = tag.toLowerCase();
-      if (registry.isQueued(lowerTag))
-        return NodeFilter.FILTER_REJECT;
-      return NodeFilter.FILTER_ACCEPT;
-    }
-  };
+  let disconnected = false;
   async function loadIsland(tagName, el, loader) {
-    if (debug && !registry.initialWalkComplete) {
+    if (debug && !lifecycle.initialWalkComplete) {
       const parts = [];
       const pushAttr = (attr, val) => {
         if (val !== null)
@@ -420,17 +530,17 @@ function revive(islandsOrPayload, options, customDirectives) {
         return Promise.resolve();
       const t0 = performance.now();
       return loader().then(() => {
-        const attempt = registry.settleSuccess(tagName);
+        const attempt = lifecycle.settleSuccess(tagName);
         runtimeSurface2.dispatchLoad({
           tag: tagName,
           duration: performance.now() - t0,
           attempt
         });
-        if (el.children.length)
-          walk(el);
+        if (!disconnected && el.children.length)
+          lifecycle.walk(el);
       }).catch((err) => {
         console.error(`[islands] Failed to load <${tagName}>:`, err);
-        const { retryDelayMs, attempt } = registry.settleFailure(tagName);
+        const { retryDelayMs, attempt } = lifecycle.settleFailure(tagName);
         runtimeSurface2.dispatchError({ tag: tagName, error: err, attempt });
         if (retryDelayMs !== null) {
           setTimeout(run, retryDelayMs);
@@ -446,7 +556,7 @@ function revive(islandsOrPayload, options, customDirectives) {
         console.error(`[islands] Built-in directive failed for <${tagName}>:`, err);
       }
       runtimeSurface2.dispatchError({ tag: tagName, error: err, attempt: 1 });
-      registry.evict(tagName);
+      lifecycle.evict(tagName);
     };
     try {
       const matchedCustomDirectives = await directiveOrchestrator.run({
@@ -455,7 +565,7 @@ function revive(islandsOrPayload, options, customDirectives) {
         directives: opts.directives,
         customDirectives: resolvedDirectives,
         directiveTimeout,
-        watchCancellable: registry.watchCancellable,
+        watchCancellable: lifecycle.watchCancellable,
         log,
         run,
         onError: handleDirectiveError
@@ -470,63 +580,27 @@ function revive(islandsOrPayload, options, customDirectives) {
     log.flush("triggered");
     run();
   }
-  function activate(el) {
-    const tagName = el.tagName.toLowerCase();
-    const loader = islandMap.get(tagName);
-    if (!loader)
-      return;
-    let ancestor = el.parentElement;
-    while (ancestor) {
-      if (registry.isQueued(ancestor.tagName.toLowerCase()))
-        return;
-      ancestor = ancestor.parentElement;
-    }
-    if (!registry.queue(tagName))
-      return;
-    loadIsland(tagName, el, loader);
-  }
-  function walk(el) {
-    activate(el);
-    const walker = document.createTreeWalker(el, NodeFilter.SHOW_ELEMENT, customElementFilter);
-    let node;
-    while (node = walker.nextNode())
-      activate(node);
-  }
-  function handleAdditions(mutations) {
-    for (const { addedNodes } of mutations) {
-      for (const node of addedNodes) {
-        if (node.nodeType === Node.ELEMENT_NODE)
-          walk(node);
-      }
+  let endReadyLog;
+  const disconnectLifecycle = lifecycle.start({
+    getRoot: () => document.body,
+    islandMap,
+    onActivate: loadIsland,
+    onBeforeInitialWalk: () => {
+      endReadyLog = runtimeSurface2.beginReadyLog(islandMap.size, debug);
+    },
+    onInitialWalkComplete: () => {
+      endReadyLog?.();
+      endReadyLog = undefined;
     }
-  }
-  const observer = new MutationObserver((mutations) => {
-    registry.cancelDetached();
-    handleAdditions(mutations);
   });
-  let disconnected = false;
-  let initialized = false;
-  function init() {
-    if (disconnected || initialized)
-      return;
-    initialized = true;
-    const endReadyLog = runtimeSurface2.beginReadyLog(islandMap.size, debug);
-    walk(document.body);
-    registry.markInitialWalkComplete();
-    endReadyLog();
-    observer.observe(document.body, { childList: true, subtree: true });
-  }
-  if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", init, { once: true });
-  } else {
-    init();
-  }
-  const disconnect = () => {
-    disconnected = true;
-    document.removeEventListener("DOMContentLoaded", init);
-    observer.disconnect();
+  return {
+    disconnect() {
+      disconnected = true;
+      endReadyLog?.();
+      endReadyLog = undefined;
+      disconnectLifecycle.disconnect();
+    }
   };
-  return { disconnect };
 }
 export {
   revive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-shopify-theme-islands",
-  "version": "1.2.2",
+  "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.2.2"
+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,17 +6,22 @@ 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. 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.2.2"
+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
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/interaction-events.ts
 ---
 
 ## Setup
@@ -70,11 +75,13 @@ 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) -->
+<!-- Override interaction events for this element only -->
 <cart-flyout client:interaction="mouseenter"></cart-flyout>
 ```
 
 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
 
@@ -102,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
@@ -165,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:
@@ -243,6 +281,32 @@ Directive attributes are case-sensitive. An unrecognised attribute is silently i
 
 Source: src/directive-orchestration.ts — built-ins read exact configured attribute names
 
+### HIGH Unsupported interaction events in config fail plugin setup
+
+Wrong:
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    interaction: { events: ["click"] as never[] },
+  },
+});
+```
+
+Correct:
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    interaction: { events: ["mouseenter", "focusin"] },
+  },
+});
+```
+
+The package now owns a curated interaction-event vocabulary for config. Supported values are `mouseenter`, `touchstart`, and `focusin`; unsupported names and empty arrays are rejected during config resolution.
+
+Source: src/interaction-events.ts — validateInteractionEvents()
+
 ### HIGH Agent uses default attribute name when developer has configured a custom one
 
 Wrong:

package/skills/lifecycle/SKILL.md

@@ -9,13 +9,16 @@ description: >
   error, and attempt, including custom directive failures and directiveTimeout
   expiry. disconnect() from the virtual module revive for SPA navigation
   teardown, including before DOMContentLoaded — it now prevents init from ever
-  starting if called early.
+  starting if called early. Startup, DOM walking, mutation observation, and
+  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.2.2"
+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
+  - Rees1993/vite-plugin-shopify-theme-islands:src/lifecycle.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/revive-module.ts
@@ -90,6 +93,10 @@ disconnect();
 
 `disconnect()` stops the MutationObserver and prevents new islands from activating. If the runtime has not initialized yet because the document is still loading, `disconnect()` also unregisters the pending DOMContentLoaded startup listener so init never runs later. Call it before SPA page transitions to avoid activating islands from the previous page's DOM.
 
+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
@@ -192,4 +199,6 @@ Source: src/runtime.ts — handleDirectiveError dispatches `islands:error`
 
 ### LOW Removed elements waiting on `client:visible` / `client:interaction` do not emit `islands:error`
 
-If an element is removed from the DOM before a cancellable built-in directive resolves, the runtime treats that as expected teardown and aborts silently. Use `onIslandError` for real failures, not DOM-removal cancellations.
+If an element is removed from the DOM before a cancellable built-in directive resolves, the lifecycle coordinator cancels that activation attempt and the runtime treats it as expected teardown. No `islands:error` event is dispatched.
+
+Source: src/lifecycle.ts — cancelDetached() with watchCancellable() ownership

package/skills/setup/SKILL.md

@@ -5,17 +5,22 @@ description: >
   install to first working island. shopifyThemeIslands() options: directories
   (string | string[]), debug, directives deep-merge (visible, idle, media,
   defer, interaction, custom), retry (retries, delay with exponential
-  backoff), and directiveTimeout for hung custom directives. Load when setting
-  up the plugin, configuring island scan directories, or enabling retry /
-  directive timeout.
+  backoff), directiveTimeout for hung custom directives, and the curated
+  interaction-event config policy (`mouseenter`, `touchstart`, `focusin`; empty
+  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.2.2"
+library_version: "1.3.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/options.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/interaction-events.ts
 ---
 
 ## Setup
@@ -49,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
@@ -83,6 +92,8 @@ 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
 
@@ -253,3 +264,35 @@ shopifyThemeIslands({
 `directiveTimeout` is a top-level plugin option, not part of the per-directive config object.
 
 Source: src/options.ts — ShopifyThemeIslandsOptions
+
+### HIGH Empty or unsupported `directives.interaction.events` values fail config resolution
+
+Wrong:
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    interaction: { events: [] },
+  },
+});
+
+shopifyThemeIslands({
+  directives: {
+    interaction: { events: ["click"] as never[] },
+  },
+});
+```
+
+Correct:
+
+```ts
+shopifyThemeIslands({
+  directives: {
+    interaction: { events: ["mouseenter", "focusin"] },
+  },
+});
+```
+
+The typed config surface only supports the package-owned interaction events `mouseenter`, `touchstart`, and `focusin`. An empty array is rejected because it would otherwise create an interaction gate that never resolves.
+
+Source: src/interaction-events.ts — validateInteractionEvents()

package/skills/writing-islands/SKILL.md

@@ -5,14 +5,16 @@ description: >
   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.
+  base class, and child island cascade behaviour now owned by
+  src/lifecycle.ts.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.2"
+library_version: "1.3.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/discovery.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/lifecycle.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
 ---
 
@@ -82,6 +84,7 @@ Required when multiple entry points might import the same island file.
 ```
 
 `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.
+That parent/child gating now lives in the lifecycle coordinator, but the user-facing behavior is the same: nested islands wait for the queued parent to settle before their own activation starts.
 
 ### Vite alias in directories
 
@@ -188,4 +191,4 @@ Wrong assumption:
 
 `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
+Source: src/lifecycle.ts — customElementFilter NodeFilter.FILTER_REJECT, walk() after parent loads