kuinetic 0.2.1 → 0.2.2

package/README.md

@@ -123,16 +123,23 @@ its readable, unminified twin, about twice the transfer size; use it only for de
 `kuinetic.advanced.min.js` is a tier: it needs core on the page, in either order, and never carries
 a copy of it.
 
-Every one of those browser bundles starts itself once the document is ready. `data-kui-manual` on a
-`<script>` tag turns that off for that file. Importing from npm does **not** start anything — a
-module import stays side-effect-free, which is the guarantee the bundler path is built on.
+Every one of those browser bundles starts itself once the document is ready. Importing from npm does
+**not** start anything — a module import stays side-effect-free, which is the guarantee the bundler
+path is built on.
+
+To drive it by hand, put `data-kui-manual` on the tag. On `kuinetic.js` that turns off the
+*auto-start* only: nothing is created or started until you call `kuinetic.kuinetic({ ... }).start()`,
+and any tier bundle you load (`kuinetic.advanced.js`, ...) still registers into the animator you
+build, in either tag order. On a tier's own tag it takes that tier out entirely.
 
 > **Changed in 0.2.** These bundles used to do nothing until you called
 > `kuinetic.kuinetic({ observe: true }).start()` yourself, and `kuinetic.all.js` started itself the
 > instant it parsed rather than at `DOMContentLoaded`. If you already write that call, it keeps
-> working and your animator is still the one the page uses — you will see one console line saying
-> the call is now redundant. Add `data-kui-manual` to the tag to silence it and go back to driving
-> everything by hand.
+> working and your animator is still the one the page uses. A call that names its own options — a
+> `reporter`, a scoped `root`, a `registry` — is how you configure the auto-started animator, and it
+> is adopted without comment. A call with no options, or only `{ observe: true }`, does nothing the
+> script tag has not already done, so you will see one console line saying it is now redundant. Delete
+> it, or add `data-kui-manual` to the tag to go back to driving everything by hand.
 
 ## Your first animation
 

package/dist/esm/advanced/index.mjs

@@ -1836,7 +1836,7 @@ function parseAngleRadians(raw) {
   if (!match) return 0;
   const value = parseFloat(match[1]);
   if (!Number.isFinite(value)) return 0;
-  return value * (ANGLE_UNITS[(match[2] ?? "deg").toLowerCase()] ?? ANGLE_UNITS.deg);
+  return value * ANGLE_UNITS[(match[2] ?? "deg").toLowerCase()];
 }
 var PALETTE_SIZE = 5;
 var DEFAULT_PALETTE = [
@@ -2067,7 +2067,7 @@ function paintBoxOf(content, natural, cs) {
   if (bw <= 0 || bh <= 0) return content;
   const [dw, dh] = fittedSize(cs.objectFit || "fill", bw, bh, natural);
   const tokens = (cs.objectPosition || "50% 50%").trim().split(/\s+/);
-  const left = content.left + positionOffset(tokens[0] ?? "50%", bw - dw);
+  const left = content.left + positionOffset(tokens[0], bw - dw);
   const top = content.top + positionOffset(tokens[1] ?? "50%", bh - dh);
   return { left, top, right: left + dw, bottom: top + dh };
 }
@@ -2333,7 +2333,7 @@ function extractShaderOptions(params, createCanvas) {
     ...readDuotoneColors(c1Text, c2Text, createCanvas),
     blendMode: blendMap[params.text("blend", "normal")] ?? 0,
     to: params.text("to", ""),
-    progress: params.num ? params.num("progress", -1) : -1,
+    progress: params.num("progress", -1),
     // Compared against the one enabling word rather than "not `off`", so — exactly as with
     // `audioBand` below — a caller passing an unvalidated accessor, or an author who typed
     // `scrub: scrol`, cannot turn the bridge on by accident.
@@ -2770,7 +2770,7 @@ function restoreInstanceOpacity(el, state) {
   if (!state.hiddenByRenderer) return;
   state.hiddenByRenderer = false;
   const style = styleOf(state.ledgers, el);
-  if (style) style.set("opacity", style.peek("opacity") ?? "");
+  if (style) style.set("opacity", style.peek("opacity"));
 }
 var SHADER_TEXTURE_GRACE_MS = 5e3;
 function acquireRenderer(info, held) {
@@ -3938,7 +3938,7 @@ function prepareCameraScene(el, params, ctx) {
   const controller = new CameraController(htmlEl, options, resolvedEnv);
   const layerEls = ownedDescendants(htmlEl, "camera-scene", "camera-layer");
   for (const layer of layerEls) {
-    const kui = layer.getAttribute("data-kui") || "";
+    const kui = layer.getAttribute("data-kui");
     const zMatch = /z:([+-]?[0-9.]+)(?:px)?/.exec(kui);
     const depthZ = zMatch ? parseDepth(zMatch[1]) : 0;
     controller.addLayer(layer, depthZ);

package/dist/esm/{chunk-RVTYN6NZ.mjs → chunk-BBQ22D7A.mjs}

@@ -41,7 +41,7 @@ import {
   toMilliseconds,
   warnAboutActivation,
   warnAboutToggleActions
-} from "./chunk-U43BX5O2.mjs";
+} from "./chunk-K2M7O6W5.mjs";
 import {
   createLedgerSet
 } from "./chunk-AEQGC2KM.mjs";
@@ -900,6 +900,7 @@ function emptyPlan(unknown, warnings) {
     unknown,
     reducedMotion: "shorten",
     supportedActivations: [],
+    activationClaims: [],
     supportedTimelines: [],
     channels: [],
     warnings
@@ -1033,6 +1034,10 @@ function buildPlan(entries, timeline, unknown, warnings) {
     plan.fxNames.push(preset.name);
     plan.reducedMotion = strictestPolicy(plan.reducedMotion, primitive.reducedMotion);
     activations = intersect(activations, primitive.supportedActivations);
+    plan.activationClaims.push({
+      supported: primitive.supportedActivations,
+      entrance: phaseOf(entry) === "entrance"
+    });
     timelines = intersect(timelines, primitive.supportedTimelines);
     for (const channel of channelsFor(entry)) channels.add(channel);
     warnUnsupportedTimeline(preset.name, primitive.supportedTimelines, timeline, warnings);
@@ -2533,6 +2538,7 @@ var Animator = class {
       el,
       spec: resolveActivationSpec(config.activation),
       supported: plan.supportedActivations,
+      claims: plan.activationClaims,
       reporter: this.reporter
     });
     return config.activation;

package/dist/esm/{chunk-U43BX5O2.mjs → chunk-K2M7O6W5.mjs}

@@ -541,18 +541,25 @@ function defaultObserverFactory() {
   if (typeof IntersectionObserver === "undefined") return void 0;
   return (callback, init) => new IntersectionObserver(callback, init);
 }
+function onlyBoundLate(name, claims) {
+  const authorising = authorisingActivations(name);
+  if (!authorising.includes("enter")) return false;
+  const suits = (claim) => authorising.some((named) => claim.supported.includes(named));
+  if (!claims.some((claim) => claim.entrance && suits(claim))) return false;
+  return claims.every((claim) => suits(claim) || claim.supported.includes("load"));
+}
 function warnAboutActivation(request) {
   warnUnsupported(request);
   warnUnknownEvents(request);
 }
-function warnUnsupported({ el, spec, supported, reporter }) {
-  if (supported.length === 0) return;
+function warnUnsupported({ el, spec, supported, claims, reporter }) {
+  const declaredAny = supported.length > 0 || (claims?.some((claim) => claim.supported.length > 0) ?? false);
+  if (!declaredAny) return;
+  const shared = supported.length > 0 ? supported.join(", ") : "none in common across the composed effects";
   for (const name of spec.names) {
     if (authorisingActivations(name).some((named) => supported.includes(named))) continue;
-    reporter.warn(
-      `activation "${name}" is not supported by this effect (supports: ${supported.join(", ")})`,
-      el
-    );
+    if (claims && onlyBoundLate(name, claims)) continue;
+    reporter.warn(`activation "${name}" is not supported by this effect (supports: ${shared})`, el);
   }
 }
 function warnUnknownEvents({ el, spec, reporter }) {
@@ -2682,11 +2689,20 @@ function createRootResolver(options) {
   const windowRoot = windowScrollRoot(win);
   return (el) => {
     for (let node = el.parentElement; node; node = node.parentElement) {
+      if (scrollsTheViewport(node, win)) return windowRoot;
       if (isScrollable(node)) return elementScrollRoot(node, win);
     }
     return windowRoot;
   };
 }
+function scrollsTheViewport(node, win) {
+  const root = win.document.documentElement;
+  if (node === root) return true;
+  if (node !== win.document.body) return false;
+  const rootStyle = win.getComputedStyle(root);
+  return !CLIPPING_OVERFLOW.has(rootStyle.overflowX) && !CLIPPING_OVERFLOW.has(rootStyle.overflowY);
+}
+var CLIPPING_OVERFLOW = /* @__PURE__ */ new Set(["auto", "scroll", "overlay", "hidden", "clip"]);
 var SCROLLABLE_OVERFLOW = /* @__PURE__ */ new Set(["auto", "scroll", "overlay"]);
 function defaultIsScrollable(win) {
   return (el) => {

package/dist/esm/{chunk-BN2Y4UKB.mjs → chunk-XDDJVANU.mjs}

@@ -26,7 +26,7 @@ import {
   toPixels,
   validate,
   waapiEasingValue
-} from "./chunk-U43BX5O2.mjs";
+} from "./chunk-K2M7O6W5.mjs";
 import {
   createAttributeLedger,
   createStyleLedger
@@ -4643,6 +4643,10 @@ function recognise(el, handlers, options = {}, deps = defaultGestureDeps()) {
   let active = false;
   let longPressTimer = null;
   let longPressFired = false;
+  let captured = false;
+  let pointerId = null;
+  let lastHandled = null;
+  let documentListening = null;
   function sampleOf(event) {
     return { x: event.clientX, y: event.clientY, time: deps.now() };
   }
@@ -4660,7 +4664,9 @@ function recognise(el, handlers, options = {}, deps = defaultGestureDeps()) {
     samples = [origin];
     active = false;
     longPressFired = false;
-    if (capturePointer) el.setPointerCapture?.(event.pointerId);
+    pointerId = event.pointerId;
+    captured = capturePointer === true && takeCapture(event.pointerId);
+    if (!captured) listenOnDocument();
     if (longPressMs > 0) {
       longPressTimer = deps.setTimer(() => {
         longPressFired = true;
@@ -4668,8 +4674,43 @@ function recognise(el, handlers, options = {}, deps = defaultGestureDeps()) {
       }, longPressMs);
     }
   }
+  function takeCapture(id) {
+    if (typeof el.setPointerCapture !== "function") return false;
+    try {
+      el.setPointerCapture(id);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  function captureOnDrag(event) {
+    if (capturePointer !== "drag") return;
+    captured = takeCapture(event.pointerId);
+    if (captured) stopListeningOnDocument();
+  }
+  function listenOnDocument() {
+    const doc = el.ownerDocument;
+    if (!doc || documentListening) return;
+    documentListening = doc;
+    doc.addEventListener("pointermove", onMove, { passive: true });
+    doc.addEventListener("pointerup", onUp, { passive: true });
+    doc.addEventListener("pointercancel", onUp, { passive: true });
+  }
+  function stopListeningOnDocument() {
+    const doc = documentListening;
+    if (!doc) return;
+    documentListening = null;
+    doc.removeEventListener("pointermove", onMove);
+    doc.removeEventListener("pointerup", onUp);
+    doc.removeEventListener("pointercancel", onUp);
+  }
+  function firstHearing(event) {
+    if (event === lastHandled) return false;
+    lastHandled = event;
+    return true;
+  }
   function onMove(event) {
-    if (!origin) return;
+    if (!origin || !firstHearing(event)) return;
     const sample = sampleOf(event);
     samples.push(sample);
     if (samples.length > MAX_SAMPLES) samples.shift();
@@ -4678,17 +4719,17 @@ function recognise(el, handlers, options = {}, deps = defaultGestureDeps()) {
     if (!active) {
       active = true;
       clearLongPress();
+      captureOnDrag(event);
       handlers.onStart?.(origin);
     }
     handlers.onMove?.(vector, sample);
   }
-  function onUp(event) {
-    clearLongPress();
-    if (capturePointer) el.releasePointerCapture?.(event.pointerId);
-    if (!origin) return;
-    const sample = sampleOf(event);
-    samples.push(sample);
-    const vector = vectorNow(sample);
+  function releaseCapture(id) {
+    if (captured) el.releasePointerCapture?.(id);
+    captured = false;
+    pointerId = null;
+  }
+  function reportEnd(vector, sample) {
     if (active) {
       handlers.onEnd?.(vector, sample);
       const direction = swipeDirection(vector, swipeVelocity);
@@ -4696,21 +4737,38 @@ function recognise(el, handlers, options = {}, deps = defaultGestureDeps()) {
     } else if (longPressFired) {
       handlers.onEnd?.(vector, sample);
     }
+  }
+  function onUp(event) {
+    clearLongPress();
+    stopListeningOnDocument();
+    releaseCapture(event.pointerId);
+    if (!origin) return;
+    const sample = sampleOf(event);
+    samples.push(sample);
+    reportEnd(vectorNow(sample), sample);
     origin = null;
     active = false;
     longPressFired = false;
     samples = [];
   }
+  function onLostCapture(event) {
+    if (!captured || event.pointerId !== pointerId) return;
+    captured = false;
+    onUp(event);
+  }
   el.addEventListener("pointerdown", onDown);
   el.addEventListener("pointermove", onMove, { passive: true });
   el.addEventListener("pointerup", onUp, { passive: true });
   el.addEventListener("pointercancel", onUp, { passive: true });
+  el.addEventListener("lostpointercapture", onLostCapture, { passive: true });
   return () => {
     clearLongPress();
+    stopListeningOnDocument();
     el.removeEventListener("pointerdown", onDown);
     el.removeEventListener("pointermove", onMove);
     el.removeEventListener("pointerup", onUp);
     el.removeEventListener("pointercancel", onUp);
+    el.removeEventListener("lostpointercapture", onLostCapture);
   };
 }
 function defaultGestureDeps() {
@@ -4859,11 +4917,12 @@ function prepareSwipeable(el, params) {
     {
       axis: params.text("axis", "both"),
       swipeVelocity: params.num("velocity", 300),
-      // This primitive publishes an attribute and moves nothing, so it has no reason to hold the
-      // pointer — and holding it retargets the following `click` at this element, which silently
-      // breaks every interactive child. A `swipe-x` on a carousel shell killed its own dots and
-      // buttons that way. See `capturePointer` in `core/gesture.ts`.
-      capturePointer: false
+      // This primitive moves nothing, so it must not hold the pointer from `pointerdown` — that
+      // retargets the following `click` at this element and kills every interactive child (a
+      // `swipe-x` on a carousel shell killed its own dots and buttons). But a flick that leaves a
+      // small element never delivers `pointerup` to it unless captured, so capture only once the
+      // drag starts. See `capturePointer` in `core/gesture.ts`.
+      capturePointer: "drag"
     }
   );
   return () => {
@@ -8937,7 +8996,7 @@ function bindSwipe(el, params, index) {
   return recognise(el, { onSwipe: (direction) => {
     if (direction === "left") index.next();
     if (direction === "right") index.prev();
-  } }, { axis: "x", capturePointer: false });
+  } }, { axis: "x", capturePointer: "drag" });
 }
 function prepareSlideshow(el, params, ctx) {
   const selector = resolveTarget(

package/dist/esm/core/index.mjs

@@ -5,7 +5,7 @@ import {
   createAnimator,
   detect,
   silentReporter
-} from "../chunk-RVTYN6NZ.mjs";
+} from "../chunk-BBQ22D7A.mjs";
 import {
   ATTR,
   CHANNEL,
@@ -18,7 +18,7 @@ import {
   resolveActivationSpec,
   resolveTargets,
   toAttributeValue
-} from "../chunk-U43BX5O2.mjs";
+} from "../chunk-K2M7O6W5.mjs";
 import "../chunk-AEQGC2KM.mjs";
 export {
   ATTR,

package/dist/esm/effects/index.mjs

@@ -17,8 +17,8 @@ import {
   registerThreeD,
   registerTween,
   registerViewTransitions
-} from "../chunk-BN2Y4UKB.mjs";
-import "../chunk-U43BX5O2.mjs";
+} from "../chunk-XDDJVANU.mjs";
+import "../chunk-K2M7O6W5.mjs";
 import "../chunk-AEQGC2KM.mjs";
 export {
   COMBOS,

package/dist/esm/index.mjs

@@ -5,13 +5,13 @@ import {
   createAnimator,
   detect,
   silentReporter
-} from "./chunk-RVTYN6NZ.mjs";
+} from "./chunk-BBQ22D7A.mjs";
 import {
   COMBOS,
   PRESETS,
   PRIMITIVES,
   createRegistry
-} from "./chunk-BN2Y4UKB.mjs";
+} from "./chunk-XDDJVANU.mjs";
 import {
   ATTR,
   CHANNEL,
@@ -24,7 +24,7 @@ import {
   resolveActivationSpec,
   resolveTargets,
   toAttributeValue
-} from "./chunk-U43BX5O2.mjs";
+} from "./chunk-K2M7O6W5.mjs";
 import "./chunk-AEQGC2KM.mjs";
 
 // src/index.ts

package/dist/kuinetic.advanced.js

@@ -2005,7 +2005,7 @@ void main() {
     if (!match) return 0;
     const value = parseFloat(match[1]);
     if (!Number.isFinite(value)) return 0;
-    return value * (ANGLE_UNITS[(match[2] ?? "deg").toLowerCase()] ?? ANGLE_UNITS.deg);
+    return value * ANGLE_UNITS[(match[2] ?? "deg").toLowerCase()];
   }
   var PALETTE_SIZE = 5;
   var DEFAULT_PALETTE = [
@@ -2236,7 +2236,7 @@ void main() {
     if (bw <= 0 || bh <= 0) return content;
     const [dw, dh] = fittedSize(cs.objectFit || "fill", bw, bh, natural);
     const tokens = (cs.objectPosition || "50% 50%").trim().split(/\s+/);
-    const left = content.left + positionOffset(tokens[0] ?? "50%", bw - dw);
+    const left = content.left + positionOffset(tokens[0], bw - dw);
     const top = content.top + positionOffset(tokens[1] ?? "50%", bh - dh);
     return { left, top, right: left + dw, bottom: top + dh };
   }
@@ -2502,7 +2502,7 @@ void main() {
       ...readDuotoneColors(c1Text, c2Text, createCanvas),
       blendMode: blendMap[params.text("blend", "normal")] ?? 0,
       to: params.text("to", ""),
-      progress: params.num ? params.num("progress", -1) : -1,
+      progress: params.num("progress", -1),
       // Compared against the one enabling word rather than "not `off`", so — exactly as with
       // `audioBand` below — a caller passing an unvalidated accessor, or an author who typed
       // `scrub: scrol`, cannot turn the bridge on by accident.
@@ -2939,7 +2939,7 @@ void main() {
     if (!state.hiddenByRenderer) return;
     state.hiddenByRenderer = false;
     const style = styleOf(state.ledgers, el);
-    if (style) style.set("opacity", style.peek("opacity") ?? "");
+    if (style) style.set("opacity", style.peek("opacity"));
   }
   var SHADER_TEXTURE_GRACE_MS = 5e3;
   function acquireRenderer(info, held) {
@@ -4107,7 +4107,7 @@ void main() {
     const controller = new CameraController(htmlEl, options, resolvedEnv);
     const layerEls = ownedDescendants(htmlEl, "camera-scene", "camera-layer");
     for (const layer of layerEls) {
-      const kui = layer.getAttribute("data-kui") || "";
+      const kui = layer.getAttribute("data-kui");
       const zMatch = /z:([+-]?[0-9.]+)(?:px)?/.exec(kui);
       const depthZ = zMatch ? parseDepth(zMatch[1]) : 0;
       controller.addLayer(layer, depthZ);
@@ -4945,17 +4945,24 @@ var __kuineticBoot = (() => {
     }
   }
   function guarded(runtime, original, core, options) {
+    const wantsShared = !options || Object.entries(options).every(([key, value]) => key === "observe" && value === true);
+    if (runtime.manual) {
+      const made = original.call(core, options);
+      adoptManual(runtime, made);
+      return made;
+    }
     if (!runtime.started) {
       const replacement = original.call(core, options);
       adopt(runtime, replacement);
-      warnManualCall(
-        runtime,
-        "yours is now the one this page uses, exactly as it would have been before the script tag started one, so the call is safe to delete"
-      );
+      if (wantsShared) {
+        warnManualCall(
+          runtime,
+          "yours is now the one this page uses, exactly as it would have been before the script tag started one, so the call is safe to delete"
+        );
+      }
       return replacement;
     }
     const shared = runtime.animator;
-    const wantsShared = !options || Object.entries(options).every(([key, value]) => key === "observe" && value === true);
     if (shared && wantsShared) {
       warnManualCall(runtime, "you have been handed the one it already made, so this call is safe to delete");
       return shared;
@@ -4982,6 +4989,40 @@ var __kuineticBoot = (() => {
     runtime.animator = animator;
     globalScope().__kuinetic = animator;
   }
+  function adoptManual(runtime, animator) {
+    if (!runtime.animator) adopt(runtime, animator);
+    const entry = { animator, started: false };
+    const list = runtime.handBuilt ??= [];
+    list.push(entry);
+    const start = animator.start.bind(animator);
+    animator.start = () => {
+      entry.started = true;
+      return start();
+    };
+    if (typeof animator.destroy === "function") {
+      const destroy = animator.destroy.bind(animator);
+      animator.destroy = () => {
+        const at = list.indexOf(entry);
+        if (at >= 0) list.splice(at, 1);
+        return destroy();
+      };
+    }
+    for (const tier of runtime.pending) registerTier(tier, animator);
+  }
+  function registerTier(entry, animator) {
+    try {
+      entry.register(animator);
+    } catch (error) {
+      warn(`the "${entry.tier}" tier failed to register: ${String(error)}`);
+    }
+  }
+  function enlistOnManual(runtime, entry) {
+    runtime.pending.push(entry);
+    for (const { animator, started } of [...runtime.handBuilt ?? []]) {
+      registerTier(entry, animator);
+      if (started) recompile(animator);
+    }
+  }
   function createAnimator(runtime, core) {
     adopt(runtime, core.kuinetic({ observe: true }));
   }
@@ -5011,13 +5052,7 @@ var __kuineticBoot = (() => {
   }
   function drain(runtime, animator) {
     const pending = runtime.pending.splice(0, runtime.pending.length);
-    for (const entry of pending) {
-      try {
-        entry.register(animator);
-      } catch (error) {
-        warn(`the "${entry.tier}" tier failed to register: ${String(error)}`);
-      }
-    }
+    for (const entry of pending) registerTier(entry, animator);
     return pending.length;
   }
   function runBoot(runtime) {
@@ -5039,13 +5074,6 @@ var __kuineticBoot = (() => {
     }
     if (registered) recompile(animator);
   }
-  function optedOut(runtime, options) {
-    if (taggedManual()) {
-      if (options.core) runtime.manual = true;
-      return true;
-    }
-    return runtime.manual;
-  }
   function enlist(runtime, options) {
     if (options.core) {
       if (runtime.animator) return;
@@ -5059,7 +5087,17 @@ var __kuineticBoot = (() => {
     if (typeof document === "undefined" || typeof globalThis === "undefined") return;
     const runtime = getRuntime();
     checkVersion(runtime, options.tier);
-    if (optedOut(runtime, options)) return;
+    if (taggedManual()) {
+      if (options.core) {
+        runtime.manual = true;
+        installGuard(runtime, options.core, options.globalName);
+      }
+      return;
+    }
+    if (runtime.manual) {
+      if (options.register) enlistOnManual(runtime, { tier: options.tier, register: options.register });
+      return;
+    }
     enlist(runtime, options);
     schedule(runtime);
   }