kuinetic 0.1.0

package/dist/esm/chunk-R3TGDJKA.mjs

@@ -0,0 +1,1264 @@
+import {
+  Registry,
+  createAttributeLedger,
+  createCssInstance,
+  createRootResolver,
+  createScrollScheduler,
+  createStyleLedger,
+  readEffectParams,
+  readEffectTiming,
+  resolveParams,
+  suggest,
+  timingProperty
+} from "./chunk-LWS4OSLX.mjs";
+
+// src/core/attrs.ts
+var ATTR = {
+  /** Authored. The rich grammar. */
+  source: "data-kui",
+  /** Library-owned and unstable: normalized effect names, for CSS hooks and debugging. */
+  normalized: "data-kui-fx",
+  state: "data-kui-state",
+  on: "data-kui-on",
+  timeline: "data-kui-timeline",
+  threshold: "data-kui-threshold",
+  stagger: "data-kui-stagger",
+  cloak: "data-kui-cloak",
+  /** Reduced-motion policy, stamped from the primitive so the CSS layer can act on it. */
+  rm: "data-kui-rm"
+};
+
+// src/core/element-config.ts
+var ACTIVATIONS = /* @__PURE__ */ new Set(["load", "enter", "hover", "focus", "click", "manual"]);
+var TIMELINES = /* @__PURE__ */ new Set(["time", "view", "scroll", "pointer"]);
+function readAttributes(el) {
+  return {
+    source: el.getAttribute(ATTR.source) ?? "",
+    on: el.getAttribute(ATTR.on),
+    timeline: el.getAttribute(ATTR.timeline),
+    threshold: el.getAttribute(ATTR.threshold)
+  };
+}
+function resolveConfig(attributes, parsed) {
+  const rawTimeline = parsed.timeline ?? attributes.timeline ?? "time";
+  const [head = "time", ...rest] = rawTimeline.trim().split(/\s+/);
+  const authored = parsed.activation ?? readActivation(attributes.on);
+  return {
+    activation: authored ?? "enter",
+    activationAuthored: authored !== void 0,
+    timeline: TIMELINES.has(head) ? head : "time",
+    range: rest.join(" "),
+    threshold: parsed.threshold ?? attributes.threshold ?? "0%"
+  };
+}
+function readActivation(attribute) {
+  return attribute && ACTIVATIONS.has(attribute) ? attribute : void 0;
+}
+function toThresholdRatio(raw) {
+  const value = Number.parseFloat(raw);
+  if (Number.isNaN(value)) return 0;
+  const ratio = raw.includes("%") ? value / 100 : value;
+  return Math.min(1, Math.max(0, ratio));
+}
+
+// src/core/activation.ts
+var NOOP = () => {
+};
+var ACTIVATION_EVENTS = {
+  load: [],
+  enter: [],
+  manual: [],
+  hover: ["pointerenter", "focusin"],
+  focus: ["focusin"],
+  click: ["click"]
+};
+function createActivationBinder(options = {}) {
+  const observers = /* @__PURE__ */ new Map();
+  const callbacks = /* @__PURE__ */ new WeakMap();
+  const createObserver = options.createObserver ?? defaultObserverFactory();
+  function observerFor(threshold) {
+    if (!createObserver) return void 0;
+    const ratio = toThresholdRatio(threshold);
+    const key = String(ratio);
+    const existing = observers.get(key);
+    if (existing) return { key, shared: existing };
+    const observer = createObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (!entry.isIntersecting) continue;
+          const binding = callbacks.get(entry.target);
+          binding?.activate();
+          binding?.release();
+        }
+      },
+      { threshold: ratio }
+    );
+    const shared = { observer, count: 0 };
+    observers.set(key, shared);
+    return { key, shared };
+  }
+  function bindObserved(el, threshold, onActivate) {
+    const binding = observerFor(threshold);
+    if (!binding) {
+      onActivate();
+      return NOOP;
+    }
+    const { key, shared } = binding;
+    let active = true;
+    const release = () => {
+      if (!active) return;
+      active = false;
+      callbacks.delete(el);
+      shared.observer.unobserve(el);
+      shared.count--;
+      if (shared.count > 0) return;
+      shared.observer.disconnect();
+      observers.delete(key);
+    };
+    callbacks.set(el, { activate: onActivate, release });
+    shared.count++;
+    shared.observer.observe(el);
+    return release;
+  }
+  function bindEvents(el, activation, onActivate) {
+    const types = ACTIVATION_EVENTS[activation];
+    if (types.length === 0) return NOOP;
+    const handler = () => onActivate();
+    for (const type of types) el.addEventListener(type, handler, { passive: true });
+    return () => {
+      for (const type of types) el.removeEventListener(type, handler);
+    };
+  }
+  return {
+    bind(el, activation, threshold, onActivate) {
+      if (activation === "load") {
+        onActivate();
+        return NOOP;
+      }
+      if (activation === "enter") return bindObserved(el, threshold, onActivate);
+      return bindEvents(el, activation, onActivate);
+    },
+    destroy() {
+      for (const { observer } of observers.values()) observer.disconnect();
+      observers.clear();
+    }
+  };
+}
+function defaultObserverFactory() {
+  if (typeof IntersectionObserver === "undefined") return void 0;
+  return (callback, init) => new IntersectionObserver(callback, init);
+}
+
+// src/core/capabilities.ts
+function supports(property, value) {
+  if (typeof CSS === "undefined" || typeof CSS.supports !== "function") return false;
+  try {
+    return CSS.supports(property, value);
+  } catch {
+    return false;
+  }
+}
+var cached;
+function detect(force = false) {
+  if (cached && !force) return cached;
+  cached = {
+    viewTimeline: supports("animation-timeline", "view()"),
+    scrollTimeline: supports("animation-timeline", "scroll()"),
+    animationRange: supports("animation-range", "entry 0% cover 30%"),
+    // `translate`/`rotate`/`scale` as independent properties is what makes the channel model
+    // possible at all — under the `transform` shorthand every effect would collide.
+    individualTransforms: supports("translate", "0 10px") && supports("scale", "1.1"),
+    scrollTimelineName: supports("scroll-timeline-name", "--x"),
+    viewTransitions: typeof document !== "undefined" && "startViewTransition" in document,
+    intersectionObserver: typeof IntersectionObserver !== "undefined",
+    reducedMotion: typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches
+  };
+  return cached;
+}
+
+// src/core/channels.ts
+function findConflicts(claims) {
+  const conflicts = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const claim of claims) {
+    for (const channel of claim.channels) {
+      const owner = seen.get(channel);
+      if (owner === void 0) {
+        seen.set(channel, claim.name);
+        continue;
+      }
+      conflicts.push({ channel, effects: [owner, claim.name] });
+    }
+  }
+  return conflicts;
+}
+function describeConflicts(conflicts) {
+  return conflicts.map((c) => `"${c.effects[0]}" and "${c.effects[1]}" both animate ${c.channel}`).join("; ");
+}
+
+// src/core/compile.ts
+var NATIVE_EASINGS = /* @__PURE__ */ new Set([
+  "linear",
+  "ease",
+  "ease-in",
+  "ease-out",
+  "ease-in-out",
+  "step-start",
+  "step-end"
+]);
+var RM_RANK = { shorten: 0, crossfade: 1, disable: 2 };
+function compile(parsed, registry, timeline) {
+  const warnings = [...parsed.warnings];
+  const { entries, unknown } = resolveEntries(parsed.specs, registry, warnings);
+  if (entries.length === 0) {
+    return emptyPlan(unknown, warnings);
+  }
+  const composed = resolveComposition(entries, registry, warnings);
+  return buildPlan(composed, timeline, unknown, warnings);
+}
+function emptyPlan(unknown, warnings) {
+  return {
+    fxNames: [],
+    vars: {},
+    declarations: {},
+    jsEffects: [],
+    unknown,
+    reducedMotion: "shorten",
+    supportedActivations: [],
+    supportedTimelines: [],
+    channels: [],
+    warnings
+  };
+}
+function resolveEntries(specs, registry, warnings) {
+  const entries = [];
+  const unknown = [];
+  for (const spec of specs) {
+    const resolved = registry.resolve(spec.name);
+    if (resolved) {
+      entries.push({ spec, resolved });
+      continue;
+    }
+    unknown.push(spec.name);
+    const hint = suggest(spec.name, registry.names());
+    const suffix = hint ? ` \u2014 did you mean "${hint}"?` : "";
+    warnings.push(`unknown effect "${spec.name}"${suffix}`);
+  }
+  return { entries, unknown };
+}
+function resolveComposition(entries, registry, warnings) {
+  if (entries.length <= 1) return entries;
+  const conflicts = findConflicts(
+    entries.map((e) => ({ name: e.spec.name, channels: e.resolved.primitive.channels }))
+  );
+  if (conflicts.length === 0) return entries;
+  const combo = registry.findCombo(entries.map((e) => e.spec.name));
+  const remedy = combo ? `Use the "${combo.preset.name}" effect instead.` : "Apply them to nested elements, or register a combined effect.";
+  warnings.push(`cannot compose: ${describeConflicts(conflicts)}. ${remedy}`);
+  return [entries[0]];
+}
+function buildPlan(entries, timeline, unknown, warnings) {
+  const plan = emptyPlan(unknown, warnings);
+  const tracks = {
+    names: [],
+    durations: [],
+    delays: [],
+    easings: [],
+    iterationCounts: []
+  };
+  const channels = /* @__PURE__ */ new Set();
+  let activations;
+  let timelines;
+  for (const entry of entries) {
+    const { preset, primitive } = entry.resolved;
+    plan.fxNames.push(preset.name);
+    plan.reducedMotion = strictestPolicy(plan.reducedMotion, primitive.reducedMotion);
+    plan.defaultActivation ??= primitive.defaultActivation;
+    activations = intersect(activations, primitive.supportedActivations);
+    timelines = intersect(timelines, primitive.supportedTimelines);
+    for (const channel of primitive.channels) channels.add(channel);
+    warnUnsupportedTimeline(preset.name, primitive.supportedTimelines, timeline, warnings);
+    Object.assign(
+      plan.vars,
+      resolveParams(entry.spec.params, primitive.parameters, (m) => warnings.push(m))
+    );
+    if (primitive.renderer === "css-keyframes") pushTrack(tracks, entry);
+    else plan.jsEffects.push(entry);
+  }
+  Object.assign(plan.declarations, declarationsFor(tracks));
+  plan.supportedActivations = activations;
+  plan.supportedTimelines = timelines;
+  plan.channels = [...channels];
+  return plan;
+}
+function intersect(accumulated, supported) {
+  if (!accumulated) return [...supported];
+  return accumulated.filter((value) => supported.includes(value));
+}
+function iterationCountProperty(presetName) {
+  return `--kui-fx-${presetName}-iterations`;
+}
+function pushTrack(tracks, entry) {
+  const { spec, resolved } = entry;
+  const id = resolved.primitive.id;
+  tracks.names.push(resolved.preset.keyframes ?? `kui-${resolved.preset.name}`);
+  tracks.durations.push(spec.duration ?? `var(${timingProperty(id, "duration")}, 600ms)`);
+  tracks.delays.push(staggerDelay(spec.delay, id));
+  tracks.easings.push(easingValue(spec.easing, id));
+  tracks.iterationCounts.push(`var(${iterationCountProperty(resolved.preset.name)}, 1)`);
+}
+function declarationsFor(tracks) {
+  if (tracks.names.length === 0) return {};
+  return {
+    "animation-name": tracks.names.join(", "),
+    "animation-duration": tracks.durations.join(", "),
+    "animation-delay": tracks.delays.join(", "),
+    "animation-timing-function": tracks.easings.join(", "),
+    "animation-iteration-count": tracks.iterationCounts.join(", "),
+    "animation-fill-mode": tracks.names.map(() => "both").join(", ")
+  };
+}
+function strictestPolicy(a, b) {
+  return RM_RANK[b] > RM_RANK[a] ? b : a;
+}
+function warnUnsupportedTimeline(name, supported, timeline, warnings) {
+  if (supported.includes(timeline)) return;
+  warnings.push(
+    `"${name}" does not support timeline "${timeline}" (supports: ${supported.join(", ")})`
+  );
+}
+function staggerDelay(delay, primitiveId) {
+  const base = delay ?? `var(${timingProperty(primitiveId, "delay")}, 0ms)`;
+  return `calc(${base} + var(--kui-i, 0) * var(--kui-stagger, 0ms))`;
+}
+function easingValue(easing, primitiveId) {
+  if (!easing) return `var(${timingProperty(primitiveId, "ease")}, ease-out)`;
+  if (NATIVE_EASINGS.has(easing)) return easing;
+  if (easing.includes("(")) return easing;
+  return `var(--kui-ease-${easing}, ease-out)`;
+}
+
+// src/core/dom-watcher.ts
+var WORK_BUDGET = 100;
+function createDomWatcher(options) {
+  const { root, onElementAdded, onElementRemoved, onAttributeChanged } = options;
+  const schedule = options.schedule ?? scheduleFrame;
+  const createObserver = options.createObserver ?? defaultObserverFactory2();
+  const added = /* @__PURE__ */ new Set();
+  const removed = /* @__PURE__ */ new Set();
+  const changed = /* @__PURE__ */ new Set();
+  let observer;
+  let scheduled = false;
+  let destroyed = false;
+  function collect(record) {
+    if (record.type === "attributes") {
+      const target = asElement(record.target);
+      if (target) changed.add(target);
+      return;
+    }
+    for (const node of record.addedNodes) queueRoot(added, asElement(node));
+    for (const node of record.removedNodes) queueRoot(removed, asElement(node));
+  }
+  function queueWork(records) {
+    for (const record of records) collect(record);
+    if (scheduled) return;
+    scheduled = true;
+    schedule(flush);
+  }
+  function flush() {
+    scheduled = false;
+    if (destroyed) return;
+    let remaining = WORK_BUDGET;
+    remaining = drain(removed, onElementRemoved, remaining);
+    remaining = drain(added, onElementAdded, remaining);
+    drain(changed, onAttributeChanged, remaining);
+    if (added.size + removed.size + changed.size > 0) {
+      scheduled = true;
+      schedule(flush);
+    }
+  }
+  return {
+    watch() {
+      if (!createObserver) return;
+      destroyed = false;
+      observer = createObserver(queueWork);
+      observer.observe(root, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: [ATTR.source, ATTR.on, ATTR.timeline, ATTR.threshold]
+      });
+    },
+    destroy() {
+      destroyed = true;
+      observer?.disconnect();
+      added.clear();
+      removed.clear();
+      changed.clear();
+    }
+  };
+}
+function queueRoot(roots, candidate) {
+  if (!candidate) return;
+  for (const root of roots) {
+    if (root.contains(candidate)) return;
+    if (candidate.contains(root)) roots.delete(root);
+  }
+  roots.add(candidate);
+}
+function drain(roots, callback, budget) {
+  for (const root of roots) {
+    if (budget === 0) break;
+    roots.delete(root);
+    callback(root);
+    budget--;
+  }
+  return budget;
+}
+function asElement(node) {
+  return node.nodeType === 1 ? node : null;
+}
+function scheduleFrame(callback) {
+  const requestFrame = globalThis.requestAnimationFrame;
+  if (typeof requestFrame === "function") requestFrame(() => callback());
+  else queueMicrotask(callback);
+}
+function defaultObserverFactory2() {
+  if (typeof MutationObserver === "undefined") return void 0;
+  return (callback) => new MutationObserver(callback);
+}
+
+// src/core/js-effect-preparer.ts
+function createJsEffectPreparer(options) {
+  const { scheduler, rootResolver, capabilities, reporter, respectReducedMotion } = options;
+  function contextFor(el, signal, ledger) {
+    const doc = el.ownerDocument;
+    return {
+      doc,
+      win: doc.defaultView ?? globalThis,
+      scheduler,
+      rootFor: rootResolver,
+      capabilities,
+      invalidate: () => scheduler.invalidate(),
+      warn: (message) => reporter.warn(message, el),
+      reducedMotion: respectReducedMotion && capabilities.reducedMotion,
+      signal,
+      style: ledger
+    };
+  }
+  return {
+    prepare({ el, plan, signal, ledger }) {
+      const instances = [];
+      if (plan.jsEffects.length === 0) return instances;
+      const ctx = contextFor(el, signal, ledger);
+      for (const { spec, resolved } of plan.jsEffects) {
+        const prepare = resolved.primitive.prepare;
+        if (!prepare) continue;
+        const warn = (message) => reporter.warn(message, el);
+        const params = readEffectParams(
+          { ...resolved.preset.params, ...spec.params },
+          resolved.primitive.parameters,
+          warn,
+          readEffectTiming(spec, warn)
+        );
+        try {
+          instances.push(prepare(el, params, ctx));
+        } catch (error) {
+          reporter.warn(`"${spec.name}" failed to initialise: ${String(error)}`, el);
+        }
+      }
+      return instances;
+    }
+  };
+}
+
+// src/core/parse.ts
+var TIME_RE = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:ms|s)$/;
+var EASING_FUNCTIONS = ["cubic-bezier(", "steps(", "linear("];
+var ACTIVATIONS2 = /* @__PURE__ */ new Set([
+  "load",
+  "enter",
+  "hover",
+  "focus",
+  "click",
+  "manual"
+]);
+var EASING_KEYWORDS = /* @__PURE__ */ new Set([
+  "linear",
+  "ease",
+  "ease-in",
+  "ease-out",
+  "ease-in-out",
+  "step-start",
+  "step-end",
+  "expo-in",
+  "expo-out",
+  "expo-in-out",
+  "back-in",
+  "back-out",
+  "back-in-out",
+  "quart-out",
+  "circ-out",
+  "spring"
+]);
+function splitTopLevel(input, delimiter, warnings = []) {
+  const parts = [];
+  const scanner = { depth: 0, quote: null, escaped: false };
+  let buffer = "";
+  for (const char of input) {
+    if (isSeparator(char, delimiter, scanner)) {
+      if (buffer.trim()) parts.push(buffer.trim());
+      buffer = "";
+      continue;
+    }
+    buffer += char;
+  }
+  if (buffer.trim()) parts.push(buffer.trim());
+  if (scanner.quote) warnings.push(`unterminated ${scanner.quote} quote in "${input}"`);
+  else if (scanner.depth > 0) warnings.push(`unclosed "(" in "${input}"`);
+  return parts;
+}
+function isSeparator(char, delimiter, scanner) {
+  if (scanner.quote) return advanceQuote(char, scanner);
+  if (char === '"' || char === "'") {
+    scanner.quote = char;
+    return false;
+  }
+  if (char === "(") scanner.depth++;
+  else if (char === ")") scanner.depth = Math.max(0, scanner.depth - 1);
+  if (scanner.depth !== 0) return false;
+  return delimiter === " " ? /\s/.test(char) : char === delimiter;
+}
+function advanceQuote(char, scanner) {
+  if (scanner.escaped) scanner.escaped = false;
+  else if (char === "\\") scanner.escaped = true;
+  else if (char === scanner.quote) scanner.quote = null;
+  return false;
+}
+function splitPair(token) {
+  let depth = 0;
+  for (let i = 0; i < token.length; i++) {
+    const char = token[i];
+    if (char === "(") depth++;
+    else if (char === ")") depth = Math.max(0, depth - 1);
+    else if (char === ":" && depth === 0) {
+      const key = token.slice(0, i).trim();
+      const value = unquote(token.slice(i + 1).trim());
+      return key && value ? [key, value] : null;
+    }
+  }
+  return null;
+}
+function unquote(value) {
+  const first = value[0];
+  if ((first === '"' || first === "'") && value.endsWith(first) && value.length > 1) {
+    return value.slice(1, -1).replaceAll(`\\${first}`, first);
+  }
+  return value;
+}
+function classify(token) {
+  const pair = splitPair(token);
+  if (pair) return { kind: "pair", key: pair[0], value: pair[1] };
+  if (TIME_RE.test(token)) return { kind: "time", value: token };
+  if (isEasing(token)) return { kind: "easing", value: token };
+  return { kind: "unknown", value: token };
+}
+function isEasing(token) {
+  if (EASING_KEYWORDS.has(token)) return true;
+  return EASING_FUNCTIONS.some((fn) => token.startsWith(fn) && token.endsWith(")"));
+}
+function parse(input) {
+  const result = { specs: [], warnings: [] };
+  for (const segment of splitTopLevel(input ?? "", ",", result.warnings)) {
+    const spec = parseSegment(segment, result);
+    if (spec) result.specs.push(spec);
+  }
+  return result;
+}
+function parseSegment(segment, result) {
+  const tokens = splitTopLevel(segment, " ", result.warnings);
+  const name = tokens.shift();
+  if (splitPair(name)) {
+    result.warnings.push(`effect name expected, got "${name}"`);
+    return null;
+  }
+  const spec = { name, params: {} };
+  let timeCount = 0;
+  for (const raw of tokens) {
+    const token = classify(raw);
+    if (token.kind === "time") timeCount = applyTime(spec, token.value, timeCount, result.warnings);
+    else applyToken(token, spec, segment, result);
+  }
+  return spec;
+}
+function applyTime(spec, value, seen, warnings) {
+  if (seen === 0) spec.duration = value;
+  else if (seen === 1) spec.delay = value;
+  else warnings.push(`third time value "${value}" ignored (expected duration then delay)`);
+  return seen + 1;
+}
+function applyToken(token, spec, segment, result) {
+  if (token.kind === "easing") {
+    if (spec.easing) result.warnings.push(`duplicate easing "${token.value}" in "${segment}"`);
+    spec.easing = token.value;
+    return;
+  }
+  if (token.kind === "unknown") {
+    result.warnings.push(
+      `unrecognised token "${token.value}" in "${segment}" \u2014 expected [duration] [delay] [easing] or key:value`
+    );
+    return;
+  }
+  if (Object.hasOwn(HOISTS, token.key)) {
+    HOISTS[token.key](result, token.value);
+    return;
+  }
+  if (token.key in spec.params) {
+    result.warnings.push(`duplicate parameter "${token.key}" in "${segment}"`);
+  }
+  spec.params[token.key] = token.value;
+}
+var HOISTS = {
+  on(result, value) {
+    if (!ACTIVATIONS2.has(value)) {
+      result.warnings.push(`unknown activation "${value}"`);
+      return;
+    }
+    assignOnce(result, "activation", value, "activations");
+  },
+  timeline(result, value) {
+    assignOnce(result, "timeline", value, "timelines");
+  },
+  threshold(result, value) {
+    assignOnce(result, "threshold", value, "thresholds");
+  }
+};
+function assignOnce(result, key, value, label) {
+  const current = result[key];
+  if (current === void 0) {
+    result[key] = value;
+    return;
+  }
+  if (current !== value) {
+    result.warnings.push(`conflicting ${label} "${String(current)}" and "${String(value)}"`);
+  }
+}
+
+// src/core/play.ts
+function resolveTargets(target, root) {
+  if (typeof target === "string") return [...root.querySelectorAll(target)];
+  if (target instanceof Element) return [target];
+  return [...target];
+}
+function time(value) {
+  if (value === void 0) return void 0;
+  return typeof value === "number" ? `${value}ms` : value;
+}
+var STRUCTURAL_RE = /[\s,()"']/;
+function quoteIfNeeded(value) {
+  if (!STRUCTURAL_RE.test(value)) return value;
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
+function hasTopLevelColon(value) {
+  let depth = 0;
+  for (const char of value) {
+    if (char === "(") depth++;
+    else if (char === ")") depth = Math.max(0, depth - 1);
+    else if (char === ":" && depth === 0) return true;
+  }
+  return false;
+}
+function assertBareToken(label, value) {
+  const warnings = [];
+  const bySpace = splitTopLevel(value, " ", warnings);
+  const byComma = splitTopLevel(value, ",", warnings);
+  const isSingleToken = bySpace.length === 1 && bySpace[0] === value;
+  const safe = warnings.length === 0 && isSingleToken && byComma.length === 1 && !hasTopLevelColon(value);
+  if (!safe) {
+    throw new Error(
+      `play(): ${label} "${value}" cannot be serialized \u2014 it contains a space, comma, colon, quote, or unbalanced parenthesis the parser cannot read back as one token`
+    );
+  }
+}
+function toAttributeValue(effect, options = {}) {
+  assertBareToken("effect", effect);
+  const { duration, delay, ease, ...rest } = options;
+  delete rest.stagger;
+  const parts = [effect];
+  const resolvedDelay = time(delay);
+  const resolvedDuration = time(duration) ?? (resolvedDelay ? "0ms" : void 0);
+  if (resolvedDuration) {
+    assertBareToken("duration", resolvedDuration);
+    parts.push(resolvedDuration);
+  }
+  if (resolvedDelay) {
+    assertBareToken("delay", resolvedDelay);
+    parts.push(resolvedDelay);
+  }
+  if (ease) {
+    assertBareToken("easing", ease);
+    parts.push(ease);
+  }
+  for (const [key, value] of Object.entries(rest)) {
+    if (value === void 0) continue;
+    assertBareToken("parameter name", key);
+    parts.push(`${key}:${quoteIfNeeded(String(value))}`);
+  }
+  return parts.join(" ");
+}
+function play(request, options = {}) {
+  const { animator, root, target, effect } = request;
+  const elements = resolveTargets(target, root);
+  const stagger = time(options.stagger);
+  const source = toAttributeValue(effect, options);
+  for (const [index, el] of elements.entries()) {
+    if (stagger) {
+      ;
+      el.style.setProperty("--kui-stagger", stagger);
+      el.style.setProperty("--kui-i", String(index));
+    }
+    animator.reset(el);
+    if (!el.hasAttribute(ATTR.on)) el.setAttribute(ATTR.on, "manual");
+    el.setAttribute(ATTR.source, source);
+    animator.process(el);
+    animator.activate(el);
+  }
+  const instancesOf = (el) => animator.stateOf(el)?.instances ?? [];
+  const finished = Promise.all(
+    elements.flatMap((el) => instancesOf(el).map((instance) => instance.finished))
+  ).then(() => void 0);
+  return {
+    elements,
+    finished,
+    cancel() {
+      for (const el of elements) for (const instance of instancesOf(el)) instance.cancel();
+    },
+    finish() {
+      for (const el of elements) for (const instance of instancesOf(el)) instance.finish();
+    }
+  };
+}
+
+// src/core/reporter.ts
+function consoleReporter() {
+  return {
+    warn(message, subject) {
+      if (subject === void 0) console.warn(`[kuinetic] ${message}`);
+      else console.warn(`[kuinetic] ${message}`, subject);
+    }
+  };
+}
+function silentReporter() {
+  return { warn() {
+  } };
+}
+function collectingReporter() {
+  const messages = [];
+  return {
+    messages,
+    warn(message) {
+      messages.push(message);
+    }
+  };
+}
+
+// src/core/stagger.ts
+function indexStaggerGroup(group) {
+  const step = group.getAttribute(ATTR.stagger);
+  if (step) group.style.setProperty("--kui-stagger", step);
+  let index = 0;
+  for (const child of group.children) {
+    if (child.hasAttribute(ATTR.source)) {
+      ;
+      child.style.setProperty("--kui-i", String(index));
+      index++;
+    }
+  }
+}
+function applyStagger(root) {
+  const selector = `[${ATTR.stagger}]`;
+  if (root instanceof Element && root.matches(selector)) indexStaggerGroup(root);
+  for (const group of root.querySelectorAll(selector)) indexStaggerGroup(group);
+}
+
+// src/core/style-plan.ts
+function planStyles(input) {
+  const { plan, config, capabilities, respectReducedMotion } = input;
+  const reduce = respectReducedMotion && capabilities.reducedMotion;
+  const useNativeTimeline = supportsTimeline(config.timeline, capabilities) && plan.supportedTimelines.includes(config.timeline);
+  const properties = { ...plan.vars, ...plan.declarations };
+  Object.assign(properties, timelineProperties(config, capabilities, useNativeTimeline));
+  const hasCssAnimation = Object.keys(plan.declarations).length > 0;
+  const gate = resolveGate({
+    useNativeTimeline,
+    reduce,
+    activation: config.activation,
+    // JS effects are gated too. They emit no `animation` declaration, so only the play-state
+    // write is skipped — the activation itself still has to be bound, or `on:enter` and
+    // `on:click` would silently do nothing for every pinned, dragged, or morphing element.
+    hasWork: hasCssAnimation || plan.jsEffects.length > 0,
+    hasCssAnimation,
+    // A browser lacking standalone translate/rotate/scale support silently ignores any
+    // `@keyframes` step written in those properties — the animation never visibly completes. An
+    // effect deferred on that promise would sit paused (or, for an entrance reveal, invisible)
+    // forever, so it must reach its final state immediately instead, the same fail-open rule
+    // already applied under reduced motion.
+    unsupportedTransform: needsIndividualTransforms(plan.channels, capabilities)
+  });
+  if (gate === "deferred") properties["animation-play-state"] = "paused";
+  return {
+    properties,
+    attributes: {
+      [ATTR.normalized]: plan.fxNames.join(" "),
+      [ATTR.rm]: plan.reducedMotion,
+      [ATTR.state]: "ready"
+    },
+    gate,
+    activation: gate === "deferred" ? effectiveActivation(config) : null
+  };
+}
+function timelineProperties(config, capabilities, useNativeTimeline) {
+  if (!useNativeTimeline) return {};
+  const properties = {
+    "animation-timeline": config.timeline === "scroll" ? "scroll()" : "view()"
+  };
+  if (capabilities.animationRange) {
+    properties["animation-range"] = config.range || "entry 0% cover 60%";
+  }
+  return properties;
+}
+function resolveGate(input) {
+  if (input.useNativeTimeline) return "native-timeline";
+  if (!input.hasWork) return "immediate";
+  if (input.reduce || input.activation === "load" || input.unsupportedTransform) return "immediate";
+  return "deferred";
+}
+function needsIndividualTransforms(channels, capabilities) {
+  if (capabilities.individualTransforms) return false;
+  return channels.some((c) => c === "translate" || c === "rotate" || c === "scale");
+}
+function supportsTimeline(timeline, capabilities) {
+  if (timeline === "view") return capabilities.viewTimeline;
+  if (timeline === "scroll") return capabilities.scrollTimeline;
+  return false;
+}
+function effectiveActivation(config) {
+  if (config.timeline !== "time" && config.activation === "manual") return "enter";
+  return config.activation;
+}
+function applyStylePlan(request) {
+  const { plan, ledger, attributes } = request;
+  for (const [property, value] of Object.entries(plan.properties)) ledger.set(property, value);
+  for (const [attribute, value] of Object.entries(plan.attributes)) attributes.set(attribute, value);
+  ledger.claim("animation-play-state");
+}
+
+// src/core/animator.ts
+var CLOAK_WATCHDOG_MS = 3e3;
+function fingerprintOf(attributes) {
+  return [attributes.source, attributes.on, attributes.timeline, attributes.threshold].join("\0");
+}
+function isElementNode(node) {
+  return typeof Element !== "undefined" && node instanceof Element;
+}
+var Animator = class {
+  registry;
+  capabilities;
+  root;
+  reporter;
+  binder;
+  scheduler;
+  rootResolver;
+  jsEffectPreparer;
+  respectReducedMotion;
+  shouldObserve;
+  /** Runtime truth. Attributes are for CSS and debugging; they make a poor state machine. */
+  states = /* @__PURE__ */ new WeakMap();
+  /** Iterable lifecycle index; the WeakMap remains the fast state lookup. */
+  liveElements = /* @__PURE__ */ new Set();
+  /** Built lazily by `watch()` when not injected, so nothing observes until `start()` needs it. */
+  domWatcher;
+  started = false;
+  constructor(options = {}) {
+    const resolved = resolveCollaborators(options);
+    this.registry = resolved.registry;
+    this.capabilities = resolved.capabilities;
+    this.root = resolved.root;
+    this.reporter = resolved.reporter;
+    this.binder = resolved.binder;
+    this.scheduler = resolved.scheduler;
+    this.rootResolver = resolved.rootResolver;
+    this.jsEffectPreparer = resolved.jsEffectPreparer;
+    this.domWatcher = resolved.domWatcher;
+    this.respectReducedMotion = resolved.respectReducedMotion;
+    this.shouldObserve = resolved.shouldObserve;
+  }
+  /**
+   * Explicit entry point. Importing the library never touches the document, which keeps SSR,
+   * hydration, and tests deterministic.
+   *
+   * @complexity O(n) time in the number of elements scanned.
+   * @overallScore 100
+   */
+  start() {
+    if (this.started) return this;
+    this.started = true;
+    const watchdog = globalThis.setTimeout(() => this.uncloak(), CLOAK_WATCHDOG_MS);
+    try {
+      this.scan(this.root);
+      if (this.shouldObserve) this.watch();
+    } finally {
+      globalThis.clearTimeout(watchdog);
+      this.uncloak();
+    }
+    return this;
+  }
+  /**
+   * Process every unprocessed element in a subtree, including the root.
+   *
+   * `querySelectorAll` excludes the root, but an inserted subtree very often carries the
+   * attribute on its top node — skipping it silently drops those animations.
+   *
+   * @param root - Subtree to scan. Defaults to the animator's root.
+   * @complexity O(n) time in the subtree size; O(1) extra space.
+   * @overallScore 100
+   */
+  scan(root = this.root) {
+    if (!root) return this;
+    const selector = `[${ATTR.source}]`;
+    if (isElementNode(root) && root.matches(selector)) this.process(root);
+    for (const el of root.querySelectorAll(selector)) this.process(el);
+    applyStagger(root);
+    return this;
+  }
+  /**
+   * Compile and install one element's effects, recompiling if its attribute changed.
+   *
+   * @param el - Element carrying `data-kui`.
+   * @complexity O(e) time in the number of composed effects; O(e) space for the plan.
+   * @overallScore 100
+   */
+  process(el) {
+    const attributes = readAttributes(el);
+    const fingerprint = fingerprintOf(attributes);
+    const existing = this.states.get(el);
+    if (existing?.fingerprint === fingerprint) return;
+    if (existing) this.release(el);
+    const parsed = parse(attributes.source);
+    const config = resolveConfig(attributes, parsed);
+    const plan = compile(parsed, this.registry, config.timeline);
+    config.activation = this.resolveActivation(el, config, plan);
+    for (const warning of plan.warnings) this.reporter.warn(warning, el);
+    if (plan.fxNames.length === 0) {
+      el.setAttribute(ATTR.state, plan.unknown.length > 0 ? "pending" : "failed");
+      return;
+    }
+    this.install({ el, fingerprint, parsed, config, plan });
+  }
+  /**
+   * Apply a compiled plan and bind its activation.
+   *
+   * @complexity O(e) time in composed effects; O(e) space for retained cleanups.
+   * @overallScore 100
+   */
+  /**
+   * Choose the activation, letting a primitive's preference fill in only when the author named
+   * none, and warning when an authored activation is not one the effect supports.
+   *
+   * Declared capability metadata was previously never checked anywhere, which made
+   * `supportedActivations` documentation rather than a contract.
+   *
+   * @complexity O(a) time in supported activations; O(1) space.
+   * @overallScore 100
+   */
+  resolveActivation(el, config, plan) {
+    if (!config.activationAuthored) return plan.defaultActivation ?? config.activation;
+    const supported = plan.supportedActivations;
+    if (supported.length > 0 && !supported.includes(config.activation)) {
+      this.reporter.warn(
+        `activation "${config.activation}" is not supported by this effect (supports: ${supported.join(", ")})`,
+        el
+      );
+    }
+    return config.activation;
+  }
+  install(request) {
+    const { el, fingerprint, parsed, config, plan } = request;
+    const stylePlan = planStyles({
+      plan,
+      config,
+      capabilities: this.capabilities,
+      respectReducedMotion: this.respectReducedMotion
+    });
+    const ledger = createStyleLedger(el);
+    const attributes = createAttributeLedger(el);
+    const controller = new AbortController();
+    applyStylePlan({ el, plan: stylePlan, ledger, attributes });
+    const state = {
+      fingerprint,
+      specs: parsed.specs,
+      activation: config.activation,
+      timeline: config.timeline,
+      instances: [],
+      ledger,
+      attributes,
+      controller,
+      status: "ready"
+    };
+    this.states.set(el, state);
+    this.liveElements.add(el);
+    if (Object.keys(stylePlan.properties).some((property) => property.startsWith("animation-"))) {
+      const animationNames = (plan.declarations["animation-name"] ?? "").split(",").map((name) => name.trim()).filter(Boolean);
+      state.instances.push(createCssInstance(el, ledger, animationNames));
+    }
+    state.instances.push(
+      ...this.jsEffectPreparer.prepare({ el, plan, signal: controller.signal, ledger })
+    );
+    this.openGate({ el, state, stylePlan, config, plan });
+  }
+  /**
+   * Decide whether, and when, the effects on this element are allowed to start.
+   *
+   * The single place any effect begins. Routing both renderers through it is what makes
+   * `on:enter`, `on:click`, `manual`, and `reducedMotion: 'disable'` mean the same thing for a
+   * pinned section as for a fade — previously JS effects started during `prepare` and honoured
+   * none of them.
+   *
+   * @complexity O(n) time in the number of instances; O(1) space.
+   * @overallScore 100
+   */
+  openGate(request) {
+    const { el, state, stylePlan, config, plan } = request;
+    const reduce = this.respectReducedMotion && this.capabilities.reducedMotion;
+    if (reduce && plan.reducedMotion === "disable") {
+      state.status = "finished";
+      state.attributes.set(ATTR.state, "finished");
+      return;
+    }
+    if (stylePlan.gate !== "deferred") {
+      this.activate(el);
+      return;
+    }
+    state.controller.signal.addEventListener(
+      "abort",
+      this.binder.bind(el, stylePlan.activation, config.threshold, () => this.activate(el))
+    );
+  }
+  /**
+   * Start a deferred animation.
+   *
+   * A JS-rendered effect's real setup work is postponed until this call — `deferPrepare` in
+   * `instances.ts` only wires up an inert instance during `prepare` — so a broken primitive (a bad
+   * selector, a malformed param) first throws here, not while the plan was being built. `scan()`
+   * reaches this synchronously for every `on:load` element, inside the very loop that processes
+   * every other element on the page; an uncaught throw here previously unwound that loop and
+   * silently orphaned every element after the broken one — the same blast radius the `__proto__`
+   * scan-crash fix closed for a different door. Each instance is isolated so one effect's failure
+   * can neither strand a sibling effect on the same element nor abort the rest of the scan.
+   *
+   * @complexity O(n) time in composed instances; O(1) space.
+   * @overallScore 100
+   */
+  activate(el) {
+    const state = this.states.get(el);
+    if (!state || state.status === "running") return;
+    state.status = "running";
+    state.attributes.set(ATTR.state, "running");
+    const started = state.instances.filter((instance) => this.startInstance(instance, el));
+    if (started.length === 0 && state.instances.length > 0) {
+      state.status = "failed";
+      state.attributes.set(ATTR.state, "failed");
+      return;
+    }
+    void Promise.all(started.map((instance) => instance.finished)).then(() => {
+      if (this.states.get(el) !== state || state.status !== "running") return;
+      state.status = "finished";
+      state.attributes.set(ATTR.state, "finished");
+    });
+  }
+  /**
+   * Activate one instance, isolating a throw from its (possibly deferred) setup.
+   *
+   * @returns Whether the instance actually started — a failed instance is excluded from the
+   * `finished` gate in `activate()`, since something that never started can never legitimately
+   * finish (see `EffectInstance.finished`'s "resolves, never rejects" contract in `types.ts`).
+   * @complexity O(1) time, O(1) space.
+   * @overallScore 100
+   */
+  startInstance(instance, el) {
+    try {
+      instance.activate();
+      return true;
+    } catch (error) {
+      this.reporter.warn(`effect failed to activate: ${String(error)}`, el);
+      return false;
+    }
+  }
+  /**
+   * Programmatic entry point. Accepts a selector, an Element, a NodeList, or any iterable, so
+   * `getElementById`, `getElementsByClassName`, and `querySelectorAll` all work directly.
+   *
+   * @complexity O(n) time in selected elements.
+   * @overallScore 100
+   */
+  play(target, effect, options = {}) {
+    return play({ animator: this, root: this.root, target, effect }, options);
+  }
+  /**
+   * Remove the opt-in cloak so a stalled or failed initialisation can never leave a page hidden.
+   *
+   * @complexity O(1) time, O(1) space.
+   * @overallScore 100
+   */
+  uncloak() {
+    const doc = isElementNode(this.root) ? this.root.ownerDocument : this.root;
+    doc?.documentElement?.removeAttribute(ATTR.cloak);
+  }
+  stateOf(el) {
+    return this.states.get(el);
+  }
+  /**
+   * Tear an element's effects down so the next `process()` reinstalls from scratch.
+   *
+   * Needed for replay: `process()` short-circuits when the configuration fingerprint is
+   * unchanged, so playing the same effect twice was previously a no-op.
+   *
+   * @complexity O(c) time in retained instances; O(1) space.
+   * @overallScore 100
+   */
+  reset(el) {
+    this.release(el);
+  }
+  /**
+   * Tear down one element's effects and clear its library-owned attributes.
+   *
+   * @complexity O(c) time in retained cleanups; O(1) extra space.
+   * @overallScore 100
+   */
+  release(el) {
+    const state = this.states.get(el);
+    if (!state) return;
+    state.controller.abort();
+    for (const instance of state.instances) runQuietly(() => instance.destroy());
+    this.states.delete(el);
+    this.liveElements.delete(el);
+    state.ledger.restore();
+    state.attributes.restore();
+  }
+  /**
+   * Tear down every tracked element inside a removed subtree.
+   *
+   * Scoped to `node`'s own descendants rather than re-scanning `liveElements` against the whole
+   * page, so a removal event costs O(removed subtree), not O(every animated element alive
+   * anywhere) — `dom-watcher.ts` can queue up to 100 removed roots per frame, and `liveElements`
+   * only shrinks on release, so it stays large on a scroll-reveal-heavy page.
+   *
+   * Membership is checked against `liveElements` (the ground truth) rather than re-querying
+   * `[${ATTR.source}]` the way `scan()` does: `dom-watcher.ts`'s `flush()` drains removed roots
+   * before attribute-change roots, so if calling code strips `data-kui` and removes the element in
+   * the same tick, a selector-based query would already miss it here and leak its teardown.
+   *
+   * `node` is typed `Element`, not `ParentNode`: `dom-watcher.ts`'s `onElementRemoved` — this
+   * method's only caller — is itself typed `(el: Element) => void`, so there is no runtime case
+   * where `node` is a `Document`/`DocumentFragment` to guard against.
+   *
+   * @complexity O(s) time in the removed subtree's element count; O(1) per candidate via the
+   * `liveElements` Set lookup.
+   * @overallScore 100
+   */
+  releaseTree(node) {
+    if (this.liveElements.has(node)) this.release(node);
+    for (const el of node.querySelectorAll("*")) {
+      if (this.liveElements.has(el)) this.release(el);
+    }
+  }
+  destroy() {
+    this.domWatcher?.destroy();
+    for (const el of [...this.liveElements]) this.release(el);
+    this.binder.destroy();
+    this.scheduler.destroy();
+    this.started = false;
+  }
+  /**
+   * Start watching for DOM insertions, removals, and attribute changes.
+   *
+   * Attribute changes recompile in place; insertions scan; removals tear down so listeners and
+   * observers do not outlive their elements.
+   *
+   * @complexity O(1) time and space to build and start; the watcher's own callback runs O(n) time
+   * in the nodes one mutation record carries.
+   * @overallScore 100
+   */
+  watch() {
+    this.domWatcher ??= createDomWatcher({
+      root: this.root,
+      onElementAdded: (el) => this.scan(el),
+      onElementRemoved: (el) => this.releaseTree(el),
+      onAttributeChanged: (el) => this.process(el)
+    });
+    this.domWatcher.watch();
+  }
+};
+function createAnimator(options = {}) {
+  return new Animator(options);
+}
+function resolveCollaborators(options) {
+  const root = options.root ?? globalThis.document;
+  const capabilities = options.capabilities ?? detect();
+  const reporter = options.reporter ?? silentReporter();
+  const scheduler = options.scheduler ?? createScrollScheduler();
+  const rootResolver = options.rootResolver ?? defaultRootResolver(root);
+  const respectReducedMotion = (options.reducedMotion ?? "respect") === "respect";
+  return {
+    registry: options.registry ?? new Registry(),
+    capabilities,
+    root,
+    reporter,
+    binder: options.binder ?? createActivationBinder(),
+    scheduler,
+    rootResolver,
+    jsEffectPreparer: resolveJsEffectPreparer(options.jsEffectPreparer, {
+      scheduler,
+      rootResolver,
+      capabilities,
+      reporter,
+      respectReducedMotion
+    }),
+    // Not defaulted here (unlike the other collaborators above): building the real watcher needs
+    // `this.scan`/`this.process`/`this.releaseTree`, which don't exist yet inside this free
+    // function. `Animator.watch()` builds it lazily instead, so nothing observes — and no
+    // `MutationObserver` is ever constructed — unless `shouldObserve` is true and `start()` runs.
+    domWatcher: options.domWatcher,
+    respectReducedMotion,
+    shouldObserve: options.observe ?? false
+  };
+}
+function resolveJsEffectPreparer(provided, deps) {
+  return provided ?? createJsEffectPreparer(deps);
+}
+function defaultRootResolver(root) {
+  const doc = isElementNode(root) ? root.ownerDocument : root;
+  const win = doc?.defaultView ?? globalThis;
+  return createRootResolver({ win });
+}
+function runQuietly(cleanup) {
+  try {
+    cleanup();
+  } catch {
+  }
+}
+
+export {
+  ATTR,
+  createActivationBinder,
+  detect,
+  resolveTargets,
+  toAttributeValue,
+  play,
+  consoleReporter,
+  silentReporter,
+  collectingReporter,
+  Animator,
+  createAnimator
+};