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

package/dist/directive-orchestration.d.ts

@@ -0,0 +1,27 @@
+import type { ClientDirective, NormalizedReviveOptions } from "./contract.js";
+import type { RuntimeLogger } from "./runtime-surface.js";
+export interface DirectiveWaiters {
+    waitVisible(element: Element, rootMargin: string, threshold: number, watch: (el: Element, cancel: () => void) => () => void): Promise<void>;
+    waitMedia(query: string): Promise<void>;
+    waitIdle(timeout: number): Promise<void>;
+    waitDelay(ms: number): Promise<void>;
+    waitInteraction(element: Element, events: string[], watch: (el: Element, cancel: () => void) => () => void): Promise<void>;
+}
+export interface DirectiveRunContext {
+    tagName: string;
+    element: HTMLElement;
+    directives: NormalizedReviveOptions["directives"];
+    customDirectives?: Map<string, ClientDirective>;
+    directiveTimeout: number;
+    watchCancellable: (el: Element, cancel: () => void) => () => void;
+    log: RuntimeLogger;
+    run: () => Promise<void>;
+    onError(attrName: string, err: unknown): void;
+}
+export interface DirectiveOrchestrator {
+    run(ctx: DirectiveRunContext): Promise<boolean>;
+}
+export declare class DirectiveCancelledError extends Error {
+    constructor();
+}
+export declare function createDirectiveOrchestrator(waiters?: DirectiveWaiters): DirectiveOrchestrator;

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import type { IslandLoadDetail, IslandErrorDetail } from "./index.js";
+import type { IslandLoadDetail, IslandErrorDetail } from "./contract.js";
 /**
  * Listen for successful island module loads.
  *

package/dist/events.js

@@ -1,13 +1,74 @@
+// src/runtime-surface.ts
+var SILENT_LOGGER = {
+  note() {},
+  flush() {}
+};
+function addListener(target, name, handler) {
+  const listener = (event) => handler(event.detail);
+  target.addEventListener(name, listener);
+  return () => target.removeEventListener(name, listener);
+}
+function dispatch(target, name, detail) {
+  target.dispatchEvent(new CustomEvent(name, { detail }));
+}
+function createRuntimeSurface(deps) {
+  return {
+    dispatchLoad(detail) {
+      dispatch(deps.target, "islands:load", detail);
+    },
+    dispatchError(detail) {
+      dispatch(deps.target, "islands:error", detail);
+    },
+    onLoad(handler) {
+      return addListener(deps.target, "islands:load", handler);
+    },
+    onError(handler) {
+      return addListener(deps.target, "islands:error", handler);
+    },
+    createLogger(tagName, debug) {
+      if (!debug)
+        return SILENT_LOGGER;
+      const msgs = [];
+      return {
+        note(msg) {
+          msgs.push(msg);
+        },
+        flush(summary) {
+          if (msgs.length === 0) {
+            deps.console.log("[islands]", `<${tagName}> ${summary}`);
+          } else {
+            deps.console.groupCollapsed(`[islands] <${tagName}> ${summary}`);
+            for (const msg of msgs)
+              deps.console.log(msg);
+            deps.console.groupEnd();
+          }
+          msgs.length = 0;
+        }
+      };
+    },
+    beginReadyLog(islandCount, debug) {
+      if (!debug)
+        return () => {};
+      deps.console.groupCollapsed(`[islands] ready — ${islandCount} island(s)`);
+      return () => deps.console.groupEnd();
+    }
+  };
+}
+var runtimeSurface;
+function getRuntimeSurface() {
+  runtimeSurface ??= createRuntimeSurface({
+    target: document,
+    console
+  });
+  return runtimeSurface;
+}
+
 // src/events.ts
 function onIslandLoad(handler) {
-  const listener = (e) => handler(e.detail);
-  document.addEventListener("islands:load", listener);
-  return () => document.removeEventListener("islands:load", listener);
+  return getRuntimeSurface().onLoad(handler);
 }
 function onIslandError(handler) {
-  const listener = (e) => handler(e.detail);
-  document.addEventListener("islands:error", listener);
-  return () => document.removeEventListener("islands:error", listener);
+  return getRuntimeSurface().onError(handler);
 }
 export {
   onIslandLoad,

package/dist/runtime-surface.d.ts

@@ -0,0 +1,20 @@
+import type { IslandErrorDetail, IslandLoadDetail } from "./contract.js";
+export interface RuntimeLogger {
+    note(msg: string): void;
+    flush(summary: string): void;
+}
+export interface RuntimeSurface {
+    dispatchLoad(detail: IslandLoadDetail): void;
+    dispatchError(detail: IslandErrorDetail): void;
+    onLoad(handler: (detail: IslandLoadDetail) => void): () => void;
+    onError(handler: (detail: IslandErrorDetail) => void): () => void;
+    createLogger(tagName: string, debug: boolean): RuntimeLogger;
+    beginReadyLog(islandCount: number, debug: boolean): () => void;
+}
+interface RuntimeSurfaceDeps {
+    target: Document;
+    console: Pick<Console, "log" | "groupCollapsed" | "groupEnd">;
+}
+export declare function createRuntimeSurface(deps: RuntimeSurfaceDeps): RuntimeSurface;
+export declare function getRuntimeSurface(): RuntimeSurface;
+export {};

package/dist/runtime.js

@@ -48,18 +48,14 @@ function buildIslandMap(payload) {
   return map;
 }
 
-// src/runtime.ts
-var dispatch = (name, detail) => document.dispatchEvent(new CustomEvent(name, { detail }));
-function media(query) {
-  const m = window.matchMedia(query);
-  return new Promise((resolve) => {
-    if (m.matches)
-      resolve();
-    else
-      m.addEventListener("change", () => resolve(), { once: true });
-  });
+// src/directive-orchestration.ts
+class DirectiveCancelledError extends Error {
+  constructor() {
+    super("[islands] directive cancelled: element removed from DOM");
+    this.name = "DirectiveCancelledError";
+  }
 }
-function visible(element, rootMargin, threshold, watch) {
+function waitVisible(element, rootMargin, threshold, watch) {
   return new Promise((resolve, reject) => {
     let settled = false;
     let unwatch = () => {};
@@ -80,7 +76,7 @@ function visible(element, rootMargin, threshold, watch) {
     unwatch = watch(element, () => finish(() => reject(new DirectiveCancelledError)));
   });
 }
-function interaction(element, events, watch) {
+function waitInteraction(element, events, watch) {
   return new Promise((resolve, reject) => {
     let settled = false;
     let unwatch = () => {};
@@ -104,10 +100,10 @@ function interaction(element, events, watch) {
     unwatch = watch(element, () => finish(() => reject(new DirectiveCancelledError)));
   });
 }
-function defer(ms) {
+function waitDelay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function idle(timeout) {
+function waitIdle(timeout) {
   return new Promise((resolve) => {
     if ("requestIdleCallback" in window)
       window.requestIdleCallback(() => resolve(), { timeout });
@@ -115,38 +111,192 @@ function idle(timeout) {
       setTimeout(resolve, timeout);
   });
 }
+function waitMedia(query) {
+  const m = window.matchMedia(query);
+  return new Promise((resolve) => {
+    if (m.matches)
+      resolve();
+    else
+      m.addEventListener("change", () => resolve(), { once: true });
+  });
+}
+function createDirectiveOrchestrator(waiters = {
+  waitVisible,
+  waitMedia,
+  waitIdle,
+  waitDelay,
+  waitInteraction
+}) {
+  async function runBuiltIns(ctx) {
+    const { tagName, element: el, directives, log, watchCancellable } = ctx;
+    const visibleAttr = directives.visible.attribute;
+    if (el.getAttribute(visibleAttr) !== null) {
+      log.note(`waiting for ${visibleAttr}`);
+      await waiters.waitVisible(el, el.getAttribute(visibleAttr) || directives.visible.rootMargin, directives.visible.threshold, watchCancellable);
+    }
+    const query = el.getAttribute(directives.media.attribute);
+    if (query === "") {
+      console.warn(`[islands] <${tagName}> ${directives.media.attribute} has no value — media check skipped, island will load immediately`);
+    } else if (query) {
+      log.note(`waiting for ${directives.media.attribute}="${query}"`);
+      await waiters.waitMedia(query);
+    }
+    const idleAttr = el.getAttribute(directives.idle.attribute);
+    if (idleAttr !== null) {
+      const raw = parseInt(idleAttr, 10);
+      const elTimeout = Number.isNaN(raw) ? directives.idle.timeout : raw;
+      log.note(`waiting for ${directives.idle.attribute} (${elTimeout}ms)`);
+      await waiters.waitIdle(elTimeout);
+    }
+    const deferAttr = el.getAttribute(directives.defer.attribute);
+    if (deferAttr !== null) {
+      const msParsed = parseInt(deferAttr, 10);
+      if (deferAttr !== "" && Number.isNaN(msParsed)) {
+        console.warn(`[islands] <${tagName}> invalid ${directives.defer.attribute} value "${deferAttr}" — using default ${directives.defer.delay}ms`);
+      }
+      const ms = Number.isNaN(msParsed) ? directives.defer.delay : msParsed;
+      log.note(`waiting for ${directives.defer.attribute} (${ms}ms)`);
+      await waiters.waitDelay(ms);
+    }
+    const interactionAttr = el.getAttribute(directives.interaction.attribute);
+    if (interactionAttr !== null) {
+      let events = directives.interaction.events;
+      if (interactionAttr) {
+        const tokens = interactionAttr.split(/\s+/).filter(Boolean);
+        if (tokens.length > 0)
+          events = tokens;
+        else {
+          console.warn(`[islands] <${tagName}> ${directives.interaction.attribute} has no valid event tokens — using default events`);
+        }
+      }
+      log.note(`waiting for ${directives.interaction.attribute} (${events.join(", ")})`);
+      await waiters.waitInteraction(el, events, watchCancellable);
+    }
+  }
+  function runCustomDirectives(ctx) {
+    const matched = [];
+    if (ctx.customDirectives) {
+      for (const [attrName, directiveFn] of ctx.customDirectives) {
+        const value = ctx.element.getAttribute(attrName);
+        if (value !== null)
+          matched.push([attrName, directiveFn, value]);
+      }
+    }
+    if (matched.length === 0)
+      return false;
+    const attrNames = matched.map(([attrName]) => attrName).join(", ");
+    ctx.log.flush(`dispatching to custom directive${matched.length === 1 ? "" : "s"} ${attrNames}`);
+    let remaining = matched.length;
+    let fired = false;
+    let aborted = false;
+    let timer;
+    const loadOnce = () => {
+      if (fired || aborted)
+        return Promise.resolve();
+      if (--remaining === 0) {
+        clearTimeout(timer);
+        fired = true;
+        return ctx.run();
+      }
+      return Promise.resolve();
+    };
+    if (ctx.directiveTimeout > 0) {
+      timer = setTimeout(() => {
+        if (fired || aborted)
+          return;
+        aborted = true;
+        ctx.onError(attrNames, new Error(`[islands] Custom directive timed out after ${ctx.directiveTimeout}ms for <${ctx.tagName}>`));
+      }, ctx.directiveTimeout);
+    }
+    for (const [attrName, directiveFn, value] of matched) {
+      try {
+        Promise.resolve(directiveFn(loadOnce, { name: attrName, value }, ctx.element)).catch((err) => {
+          clearTimeout(timer);
+          aborted = true;
+          ctx.onError(attrName, err);
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        aborted = true;
+        ctx.onError(attrName, err);
+      }
+    }
+    return true;
+  }
+  return {
+    async run(ctx) {
+      await runBuiltIns(ctx);
+      return runCustomDirectives(ctx);
+    }
+  };
+}
+
+// src/runtime-surface.ts
 var SILENT_LOGGER = {
   note() {},
   flush() {}
 };
-function createIslandLogger(tagName, debug) {
-  if (!debug)
-    return SILENT_LOGGER;
-  const msgs = [];
+function addListener(target, name, handler) {
+  const listener = (event) => handler(event.detail);
+  target.addEventListener(name, listener);
+  return () => target.removeEventListener(name, listener);
+}
+function dispatch(target, name, detail) {
+  target.dispatchEvent(new CustomEvent(name, { detail }));
+}
+function createRuntimeSurface(deps) {
   return {
-    note(msg) {
-      msgs.push(msg);
+    dispatchLoad(detail) {
+      dispatch(deps.target, "islands:load", detail);
     },
-    flush(summary) {
-      if (msgs.length === 0) {
-        console.log("[islands]", `<${tagName}> ${summary}`);
-      } else {
-        console.groupCollapsed(`[islands] <${tagName}> ${summary}`);
-        for (const m of msgs)
-          console.log(m);
-        console.groupEnd();
-      }
-      msgs.length = 0;
+    dispatchError(detail) {
+      dispatch(deps.target, "islands:error", detail);
+    },
+    onLoad(handler) {
+      return addListener(deps.target, "islands:load", handler);
+    },
+    onError(handler) {
+      return addListener(deps.target, "islands:error", handler);
+    },
+    createLogger(tagName, debug) {
+      if (!debug)
+        return SILENT_LOGGER;
+      const msgs = [];
+      return {
+        note(msg) {
+          msgs.push(msg);
+        },
+        flush(summary) {
+          if (msgs.length === 0) {
+            deps.console.log("[islands]", `<${tagName}> ${summary}`);
+          } else {
+            deps.console.groupCollapsed(`[islands] <${tagName}> ${summary}`);
+            for (const msg of msgs)
+              deps.console.log(msg);
+            deps.console.groupEnd();
+          }
+          msgs.length = 0;
+        }
+      };
+    },
+    beginReadyLog(islandCount, debug) {
+      if (!debug)
+        return () => {};
+      deps.console.groupCollapsed(`[islands] ready — ${islandCount} island(s)`);
+      return () => deps.console.groupEnd();
     }
   };
 }
-
-class DirectiveCancelledError extends Error {
-  constructor() {
-    super("[islands] directive cancelled: element removed from DOM");
-    this.name = "DirectiveCancelledError";
-  }
+var runtimeSurface;
+function getRuntimeSurface() {
+  runtimeSurface ??= createRuntimeSurface({
+    target: document,
+    console
+  });
+  return runtimeSurface;
 }
+
+// src/runtime.ts
 function isRevivePayload(v) {
   return typeof v === "object" && v !== null && "islands" in v && !Array.isArray(v);
 }
@@ -213,6 +363,7 @@ function createIslandRegistry(opts) {
   };
 }
 function revive(islandsOrPayload, options, customDirectives) {
+  const runtimeSurface2 = getRuntimeSurface();
   const payload = isRevivePayload(islandsOrPayload) ? islandsOrPayload : { islands: islandsOrPayload, options, customDirectives };
   const opts = normalizeReviveOptions(payload.options);
   const islandMap = buildIslandMap(payload);
@@ -222,17 +373,13 @@ function revive(islandsOrPayload, options, customDirectives) {
   const attrIdle = opts.directives.idle.attribute;
   const attrDefer = opts.directives.defer.attribute;
   const attrInteraction = opts.directives.interaction.attribute;
-  const interactionEvents = opts.directives.interaction.events;
-  const rootMargin = opts.directives.visible.rootMargin;
-  const threshold = opts.directives.visible.threshold;
-  const idleTimeout = opts.directives.idle.timeout;
-  const deferDelay = opts.directives.defer.delay;
   const debug = opts.debug;
   const directiveTimeout = opts.directiveTimeout;
   const registry = createIslandRegistry({
     retries: opts.retry.retries,
     retryDelay: opts.retry.delay
   });
+  const directiveOrchestrator = createDirectiveOrchestrator();
   const customElementFilter = {
     acceptNode: (node) => {
       const tag = node.tagName;
@@ -244,107 +391,6 @@ function revive(islandsOrPayload, options, customDirectives) {
       return NodeFilter.FILTER_ACCEPT;
     }
   };
-  function makeDirectiveOutcomeHandler(tagName) {
-    return (outcome) => {
-      if (outcome.kind === "builtin-catch" && outcome.err instanceof DirectiveCancelledError) {
-        return;
-      }
-      const err = outcome.err;
-      if (outcome.kind === "directive-error") {
-        console.error(`[islands] Custom directive ${outcome.attrName} failed for <${tagName}>:`, err);
-      } else {
-        console.error(`[islands] Built-in directive failed for <${tagName}>:`, err);
-      }
-      dispatch("islands:error", { tag: tagName, error: err, attempt: 1 });
-      registry.evict(tagName);
-    };
-  }
-  async function applyBuiltInDirectives(tagName, el, log) {
-    const visibleAttr = el.getAttribute(attrVisible);
-    if (visibleAttr !== null) {
-      log.note(`waiting for ${attrVisible}`);
-      await visible(el, visibleAttr || rootMargin, threshold, registry.watchCancellable);
-    }
-    const query = el.getAttribute(attrMedia);
-    if (query === "") {
-      console.warn(`[islands] <${tagName}> ${attrMedia} has no value — media check skipped, island will load immediately`);
-    } else if (query) {
-      log.note(`waiting for ${attrMedia}="${query}"`);
-      await media(query);
-    }
-    const idleAttr = el.getAttribute(attrIdle);
-    if (idleAttr !== null) {
-      const raw = parseInt(idleAttr, 10);
-      const elTimeout = Number.isNaN(raw) ? idleTimeout : raw;
-      log.note(`waiting for ${attrIdle} (${elTimeout}ms)`);
-      await idle(elTimeout);
-    }
-    const d = el.getAttribute(attrDefer);
-    if (d !== null) {
-      const dMs = parseInt(d, 10);
-      if (d !== "" && Number.isNaN(dMs)) {
-        console.warn(`[islands] <${tagName}> invalid ${attrDefer} value "${d}" — using default ${deferDelay}ms`);
-      }
-      const ms = Number.isNaN(dMs) ? deferDelay : dMs;
-      log.note(`waiting for ${attrDefer} (${ms}ms)`);
-      await defer(ms);
-    }
-    const interactionAttr = el.getAttribute(attrInteraction);
-    if (interactionAttr !== null) {
-      let events = interactionEvents;
-      if (interactionAttr) {
-        const tokens = interactionAttr.split(/\s+/).filter(Boolean);
-        if (tokens.length > 0)
-          events = tokens;
-        else
-          console.warn(`[islands] <${tagName}> ${attrInteraction} has no valid event tokens — using default events`);
-      }
-      log.note(`waiting for ${attrInteraction} (${events.join(", ")})`);
-      await interaction(el, events, registry.watchCancellable);
-    }
-  }
-  function applyCustomDirectives(tagName, el, matched, run, handleDirectiveError, log) {
-    if (matched.length === 0)
-      return false;
-    const attrNames = matched.map(([a]) => a).join(", ");
-    log.flush(`dispatching to custom directive${matched.length === 1 ? "" : "s"} ${attrNames}`);
-    let remaining = matched.length;
-    let fired = false;
-    let aborted = false;
-    const loadOnce = () => {
-      if (fired || aborted)
-        return Promise.resolve();
-      if (--remaining === 0) {
-        clearTimeout(timer);
-        fired = true;
-        return run();
-      }
-      return Promise.resolve();
-    };
-    let timer;
-    if (directiveTimeout > 0) {
-      timer = setTimeout(() => {
-        if (fired || aborted)
-          return;
-        aborted = true;
-        handleDirectiveError(attrNames, new Error(`[islands] Custom directive timed out after ${directiveTimeout}ms for <${tagName}>`));
-      }, directiveTimeout);
-    }
-    for (const [attrName, directiveFn, value] of matched) {
-      try {
-        Promise.resolve(directiveFn(loadOnce, { name: attrName, value }, el)).catch((err) => {
-          clearTimeout(timer);
-          aborted = true;
-          handleDirectiveError(attrName, err);
-        });
-      } catch (err) {
-        clearTimeout(timer);
-        aborted = true;
-        handleDirectiveError(attrName, err);
-      }
-    }
-    return true;
-  }
   async function loadIsland(tagName, el, loader) {
     if (debug && !registry.initialWalkComplete) {
       const parts = [];
@@ -368,22 +414,14 @@ function revive(islandsOrPayload, options, customDirectives) {
       if (parts.length > 0)
         console.log("[islands]", `<${tagName}> waiting · ${parts.join(", ")}`);
     }
-    const log = createIslandLogger(tagName, debug);
-    const handleOutcome = makeDirectiveOutcomeHandler(tagName);
-    try {
-      await applyBuiltInDirectives(tagName, el, log);
-    } catch (err) {
-      handleOutcome({ kind: "builtin-catch", err });
-      log.flush(err instanceof DirectiveCancelledError ? "aborted (element removed)" : "aborted (directive error)");
-      return;
-    }
+    const log = runtimeSurface2.createLogger(tagName, debug);
     const run = () => {
       if (disconnected)
         return Promise.resolve();
       const t0 = performance.now();
       return loader().then(() => {
         const attempt = registry.settleSuccess(tagName);
-        dispatch("islands:load", {
+        runtimeSurface2.dispatchLoad({
           tag: tagName,
           duration: performance.now() - t0,
           attempt
@@ -393,22 +431,41 @@ function revive(islandsOrPayload, options, customDirectives) {
       }).catch((err) => {
         console.error(`[islands] Failed to load <${tagName}>:`, err);
         const { retryDelayMs, attempt } = registry.settleFailure(tagName);
-        dispatch("islands:error", { tag: tagName, error: err, attempt });
+        runtimeSurface2.dispatchError({ tag: tagName, error: err, attempt });
         if (retryDelayMs !== null) {
           setTimeout(run, retryDelayMs);
         }
       });
     };
-    const handleDirectiveError = (attrName, err) => handleOutcome({ kind: "directive-error", attrName, err });
-    if (resolvedDirectives?.size) {
-      const matched = [];
-      for (const [attrName, directiveFn] of resolvedDirectives) {
-        const value = el.getAttribute(attrName);
-        if (value !== null)
-          matched.push([attrName, directiveFn, value]);
+    const handleDirectiveError = (attrName, err) => {
+      if (attrName === null && err instanceof DirectiveCancelledError)
+        return;
+      if (attrName !== null) {
+        console.error(`[islands] Custom directive ${attrName} failed for <${tagName}>:`, err);
+      } else {
+        console.error(`[islands] Built-in directive failed for <${tagName}>:`, err);
       }
-      if (applyCustomDirectives(tagName, el, matched, run, handleDirectiveError, log))
+      runtimeSurface2.dispatchError({ tag: tagName, error: err, attempt: 1 });
+      registry.evict(tagName);
+    };
+    try {
+      const matchedCustomDirectives = await directiveOrchestrator.run({
+        tagName,
+        element: el,
+        directives: opts.directives,
+        customDirectives: resolvedDirectives,
+        directiveTimeout,
+        watchCancellable: registry.watchCancellable,
+        log,
+        run,
+        onError: handleDirectiveError
+      });
+      if (matchedCustomDirectives)
         return;
+    } catch (err) {
+      handleDirectiveError(null, err);
+      log.flush(err instanceof DirectiveCancelledError ? "aborted (element removed)" : "aborted (directive error)");
+      return;
     }
     log.flush("triggered");
     run();
@@ -447,16 +504,18 @@ function revive(islandsOrPayload, options, customDirectives) {
     registry.cancelDetached();
     handleAdditions(mutations);
   });
+  let disconnected = false;
+  let initialized = false;
   function init() {
-    if (debug)
-      console.groupCollapsed(`[islands] ready — ${islandMap.size} island(s)`);
+    if (disconnected || initialized)
+      return;
+    initialized = true;
+    const endReadyLog = runtimeSurface2.beginReadyLog(islandMap.size, debug);
     walk(document.body);
     registry.markInitialWalkComplete();
-    if (debug)
-      console.groupEnd();
+    endReadyLog();
     observer.observe(document.body, { childList: true, subtree: true });
   }
-  let disconnected = false;
   if (document.readyState === "loading") {
     document.addEventListener("DOMContentLoaded", init, { once: true });
   } else {
@@ -464,6 +523,7 @@ function revive(islandsOrPayload, options, customDirectives) {
   }
   const disconnect = () => {
     disconnected = true;
+    document.removeEventListener("DOMContentLoaded", init);
     observer.disconnect();
   };
   return { disconnect };

package/package.json

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

package/skills/custom-directives/SKILL.md

@@ -6,15 +6,17 @@ description: >
   multiple custom directives match the same element, all must call load() before
   the island activates. Error handling — thrown errors, rejected promises, and
   directiveTimeout expiry fire islands:error. Custom directives run after all
-  built-in conditions resolve.
+  built-in conditions resolve. Current matching, AND-latch, and timeout policy
+  are owned by src/directive-orchestration.ts.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.1"
+library_version: "1.2.2"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/directive-orchestration.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
-  - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
 ---
 
 ## Setup
@@ -143,7 +145,7 @@ const myDirective: ClientDirective = (load, _opts, el) => {
 
 No immediate error is thrown by default, so the island is silently never loaded unless you configure `directiveTimeout`.
 
-Source: src/runtime.ts — directive owns the `run()` call path
+Source: src/directive-orchestration.ts — matched custom directives own the `run()` call path
 
 ### HIGH Writing a custom directive for mouseenter/touchstart/focusin — use `client:interaction` instead
 
@@ -168,7 +170,7 @@ Correct:
 
 `client:interaction` is a built-in directive that handles `mouseenter`, `touchstart`, and `focusin`. Custom directives are for conditions the built-ins cannot express (e.g. URL hash matching, network conditions, feature flags).
 
-Source: src/runtime.ts — `interaction()` built-in handles the hover/touch/focus pattern
+Source: src/directive-orchestration.ts — built-in interaction handling covers the hover/touch/focus pattern
 
 ### HIGH AND-latch: both matched directives must call `load()`
 
@@ -191,7 +193,7 @@ Correct:
 
 With two matching custom directives, `remaining = 2`. Each `load()` call decrements it. The island activates only when `remaining === 0`.
 
-Source: src/runtime.ts — `let remaining = matched.length`
+Source: src/directive-orchestration.ts — `let remaining = matched.length`
 
 ### HIGH Duplicate custom directive names or collisions with built-ins fail plugin setup
 
@@ -247,7 +249,7 @@ Correct:
 
 Custom directive entrypoints are resolved through Vite. Relative local files should usually use `./...`; unresolved entrypoints fail the build.
 
-Source: src/index.ts — `this.resolve(def.entrypoint)` throws on null
+Source: src/index.ts — `this.resolve(entrypoint)` throws on null during revive bootstrap planning
 
 ### MEDIUM Custom directives run after all built-in directive awaits
 
@@ -260,7 +262,7 @@ Wrong expectation:
 
 The runtime awaits built-ins in order (`visible → media → idle → defer → interaction`) first, then passes control to matched custom directives. Custom directives cannot short-circuit or replace built-in awaits.
 
-Source: src/runtime.ts — built-in awaits precede `if (customDirectives?.size)` block
+Source: src/directive-orchestration.ts — runBuiltIns() completes before runCustomDirectives()
 
 ### MEDIUM Calling `load()` multiple times has no effect after the first
 
@@ -282,4 +284,4 @@ const retryDirective: ClientDirective = (load, _opts, el) => {
 
 The `loadOnce` wrapper ignores all calls after the first (`fired` guard). Use `{ once: true }` on event listeners to avoid unnecessary calls.
 
-Source: src/runtime.ts — `if (fired || aborted) return Promise.resolve()`
+Source: src/directive-orchestration.ts — `if (fired || aborted) return Promise.resolve()`

package/skills/directives/SKILL.md

@@ -4,16 +4,19 @@ description: >
   Built-in client directives: client:visible (IntersectionObserver, rootMargin),
   client:media (matchMedia query), client:idle (requestIdleCallback),
   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.
+  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.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.1"
+library_version: "1.2.2"
 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/index.ts
-  - Rees1993/vite-plugin-shopify-theme-islands:src/options.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
 ---
 
 ## Setup
@@ -50,10 +53,7 @@ Directives resolve in a fixed order: `visible → media → idle → defer → i
 <mega-menu client:visible client:interaction></mega-menu>
 
 <!-- Loads when visible AND the media query matches -->
-<product-recommendations
-  client:visible
-  client:media="(min-width: 768px)"
-></product-recommendations>
+<product-recommendations client:visible client:media="(min-width: 768px)"></product-recommendations>
 ```
 
 Combined directives are AND-latched. The island loads only after every condition resolves. There is no OR mode.
@@ -100,7 +100,7 @@ An empty `client:defer` attribute is NOT zero — it falls back to the configure
 
 An empty `client:interaction` attribute uses the configured default events with no warning. A whitespace-only value such as `client:interaction="   "` emits a warning and still falls back to the default events.
 
-Source: src/runtime.ts — interaction token parsing and fallback warning
+Source: src/directive-orchestration.ts — interaction token parsing and fallback warning
 
 ### Changing built-in directive defaults globally
 
@@ -118,8 +118,7 @@ shopifyThemeIslands({
 ### Removed elements abort waiting directives silently
 
 ```html
-<hero-banner client:visible></hero-banner>
-<cart-flyout client:interaction></cart-flyout>
+<hero-banner client:visible></hero-banner> <cart-flyout client:interaction></cart-flyout>
 ```
 
 If either element is removed from the DOM before its directive resolves, the runtime cancels that activation attempt and does not dispatch `islands:error`. This is expected teardown behavior, not a load failure.
@@ -142,7 +141,7 @@ Correct:
 
 An empty `client:media` value emits a console warning and skips the media check — the island loads immediately. Provide a valid media query string.
 
-Source: src/runtime.ts — `if (query === "")` branch
+Source: src/directive-orchestration.ts — `if (query === "")` branch
 
 ### MEDIUM Whitespace-only `client:interaction` value warns and falls back
 
@@ -164,7 +163,7 @@ Correct:
 
 Whitespace-only values are not treated the same as an empty attribute. The runtime warns and falls back to the configured default events.
 
-Source: src/runtime.ts — `interactionAttr.split(/\s+/).filter(Boolean)`
+Source: src/directive-orchestration.ts — `interactionAttr.split(/\s+/).filter(Boolean)`
 
 ### HIGH Multiple directives are AND, not OR
 
@@ -184,7 +183,7 @@ Correct understanding:
 
 The runtime awaits each directive sequentially. There is no way to express OR semantics with built-in directives — use a custom directive for that.
 
-Source: src/runtime.ts — loadIsland sequential awaits
+Source: src/directive-orchestration.ts — runBuiltIns() sequential awaits
 
 ### MEDIUM `client:defer` without value ≠ immediate load
 
@@ -204,7 +203,7 @@ Correct:
 
 `client:defer` with no value uses the global `defer.delay` default (3000ms). `parseInt("", 10)` produces `NaN`, which the runtime replaces with the configured default.
 
-Source: src/runtime.ts — `const ms = Number.isNaN(raw) ? deferDelay : raw`
+Source: src/directive-orchestration.ts — defer parsing and fallback to directives.defer.delay
 
 ### MEDIUM Per-element visible value replaces rootMargin, not adds to it
 
@@ -224,15 +223,14 @@ Correct:
 
 The attribute value is passed directly to `IntersectionObserver` as `rootMargin`, fully replacing the global default.
 
-Source: src/runtime.ts — `await visible(el, visibleAttr || rootMargin, threshold, registry.watchCancellable)`
+Source: src/directive-orchestration.ts — visible attribute value replaces directives.visible.rootMargin
 
 ### HIGH Directive attribute typo — island loads without condition
 
 Wrong:
 
 ```html
-<product-form client:visibled></product-form>
-<product-form client:Visible></product-form>
+<product-form client:visibled></product-form> <product-form client:Visible></product-form>
 ```
 
 Correct:
@@ -243,7 +241,7 @@ Correct:
 
 Directive attributes are case-sensitive. An unrecognised attribute is silently ignored — the island loads immediately as if no directive were set. No warning is emitted. Check for typos if an island activates earlier than expected.
 
-Source: src/runtime.ts — runtime checks exact attribute names from plugin config
+Source: src/directive-orchestration.ts — built-ins read exact configured attribute names
 
 ### HIGH Agent uses default attribute name when developer has configured a custom one
 

package/skills/lifecycle/SKILL.md

@@ -8,12 +8,14 @@ description: >
   duration (ms), and attempt (1-based). islands:error detail includes tag,
   error, and attempt, including custom directive failures and directiveTimeout
   expiry. disconnect() from the virtual module revive for SPA navigation
-  teardown.
+  teardown, including before DOMContentLoaded — it now prevents init from ever
+  starting if called early.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.1"
+library_version: "1.2.2"
 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/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/revive-module.ts
@@ -86,7 +88,7 @@ import { disconnect } from "vite-plugin-shopify-theme-islands/revive";
 disconnect();
 ```
 
-`disconnect()` stops the MutationObserver and prevents new islands from activating. Call it before SPA page transitions to avoid activating islands from the previous page's DOM.
+`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.
 
 ### Raw DOM events (when type augmentation is in scope)
 
@@ -171,7 +173,7 @@ onIslandError(({ tag, error, attempt }) => {
 
 With `retry: { retries: 3 }`, a single island can fire `islands:error` up to 4 times before exhausting retries. Use `attempt` to distinguish the initial failure from retries.
 
-Source: src/runtime.ts — `dispatch("islands:error", ...)` inside `.catch()` before retry check
+Source: src/runtime.ts — runtimeSurface.dispatchError(...) inside the loader failure path before retry check
 
 ### MEDIUM `islands:error` fires for custom directive failures too
 

package/skills/setup/SKILL.md

@@ -10,7 +10,7 @@ description: >
   directive timeout.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.1"
+library_version: "1.2.2"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts

package/skills/writing-islands/SKILL.md

@@ -8,7 +8,7 @@ description: >
   base class, and child island cascade behaviour.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.1"
+library_version: "1.2.2"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/discovery.ts