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

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.0",
+  "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,12 +6,15 @@ 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.0"
+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
 ---
@@ -142,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
 
@@ -167,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()`
 
@@ -190,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
 
@@ -222,7 +225,7 @@ shopifyThemeIslands({
 
 Custom directive names must be unique and must not collide with any built-in directive name, including renamed built-ins.
 
-Source: src/index.ts — validateOptions duplicate and built-in conflict checks
+Source: src/config-policy.ts — validateOptions() duplicate and built-in conflict checks
 
 ### HIGH Entrypoint path missing `./` prefix
 
@@ -246,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
 
@@ -259,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
 
@@ -281,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()`