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

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

@@ -54,6 +54,26 @@ function collectTagNames(dir) {
   return names;
 }
 
+// src/interaction-events.ts
+var INTERACTION_EVENT_NAMES = ["mouseenter", "touchstart", "focusin"];
+var DEFAULT_INTERACTION_EVENTS = [...INTERACTION_EVENT_NAMES];
+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 invalidEvent = events.find((eventName) => !isInteractionEventName(eventName));
+  if (invalidEvent) {
+    throw new Error(`${PREFIX} "directives.interaction.events" contains unsupported event "${invalidEvent}"`);
+  }
+}
+
 // src/contract.ts
 var DEFAULT_DIRECTIVES = {
   visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
@@ -62,7 +82,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 +90,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 +126,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 +139,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 +166,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);
   }
@@ -357,5 +380,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,12 @@
+/**
+ * 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 function isInteractionEventName(value: string): value is InteractionEventName;
+export declare function validateInteractionEvents(events: readonly string[] | undefined): asserts events is readonly InteractionEventName[];

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,23 @@
+// src/interaction-events.ts
+var INTERACTION_EVENT_NAMES = ["mouseenter", "touchstart", "focusin"];
+var DEFAULT_INTERACTION_EVENTS = [...INTERACTION_EVENT_NAMES];
+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 invalidEvent = events.find((eventName) => !isInteractionEventName(eventName));
+  if (invalidEvent) {
+    throw new Error(`${PREFIX} "directives.interaction.events" contains unsupported event "${invalidEvent}"`);
+  }
+}
+
 // src/contract.ts
 var DEFAULT_DIRECTIVES = {
   visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
@@ -6,7 +26,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 +34,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,7 +181,7 @@ 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)
@@ -231,6 +252,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 +460,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 +473,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 +508,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 +534,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 +543,7 @@ function revive(islandsOrPayload, options, customDirectives) {
         directives: opts.directives,
         customDirectives: resolvedDirectives,
         directiveTimeout,
-        watchCancellable: registry.watchCancellable,
+        watchCancellable: lifecycle.watchCancellable,
         log,
         run,
         onError: handleDirectiveError
@@ -470,63 +558,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.0",
   "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.0"
 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

@@ -7,16 +7,19 @@ description: >
   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.
+  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.0"
 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 +73,12 @@ 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`.
 
 ### `client:defer` without a value uses the global default
 
@@ -243,6 +247,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,15 @@ 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.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.2"
+library_version: "1.3.0"
 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 +92,8 @@ 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.
+
 ### Raw DOM events (when type augmentation is in scope)
 
 ```ts
@@ -192,4 +196,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,19 @@ 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). 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.0"
 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
@@ -83,6 +85,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`.
 
 ### Enable automatic retry with exponential backoff
 
@@ -253,3 +256,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.0"
 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