kuinetic 0.1.3 → 0.1.4

package/dist/esm/{chunk-5DON3UFQ.mjs → chunk-7WMNPIOZ.mjs}

@@ -15,9 +15,13 @@ import {
 } from "./chunk-JT4PZL3A.mjs";
 
 // src/effects/shared.ts
+var TRIGGER_DELAY_PARAM = {
+  delay: { type: "time", default: "0ms", cssProperty: "--kui-delay" }
+};
+var TIMELINE_AGNOSTIC = ["time", "view", "scroll", "pin"];
 var COMMON = {
   duration: { type: "time", default: "600ms", cssProperty: "--kui-duration" },
-  delay: { type: "time", default: "0ms", cssProperty: "--kui-delay" },
+  ...TRIGGER_DELAY_PARAM,
   ease: { type: "easing", default: "ease-out", cssProperty: "--kui-ease" },
   stagger: { type: "time", default: "0ms", cssProperty: "--kui-stagger" }
 };
@@ -45,7 +49,14 @@ function cssPrimitive(id, channels, options = {}) {
 // src/effects/catalog/ambient.ts
 var drift = {
   duration: { type: "time", default: "10s", cssProperty: "--kui-duration" },
-  ease: { type: "easing", default: "ease-in-out", cssProperty: "--kui-ease" }
+  ease: { type: "easing", default: "ease-in-out", cssProperty: "--kui-ease" },
+  from: { type: "color", default: "", cssProperty: "--kui-ambient-c1" },
+  to: { type: "color", default: "", cssProperty: "--kui-ambient-c2" }
+};
+var tint = {
+  duration: { type: "time", default: "10s", cssProperty: "--kui-duration" },
+  ease: { type: "easing", default: "ease-in-out", cssProperty: "--kui-ease" },
+  from: { type: "color", default: "", cssProperty: "--kui-ambient-c1" }
 };
 var float = {
   duration: { type: "time", default: "4s", cssProperty: "--kui-duration" },
@@ -71,6 +82,34 @@ var AMBIENT_PRIMITIVES = [
     reducedMotion: "disable",
     perfClass: "continuous"
   }),
+  /*
+   * `gradient-rotate-border` and `gradient-border` are not background fills, and a second
+   * primitive is how this catalog says so — the same reason `ambient-tint` exists beside
+   * `ambient-gradient` above. Channels are per-primitive, so a different channel set means a
+   * different primitive; folding these into `ambient-gradient` would make `gradient-mesh` and
+   * `aurora` claim a mask and a box they never touch, and `aurora, pin` would start reporting a
+   * conflict that isn't there.
+   *
+   * What the ring rules actually write (`ambient.css`) beyond the gradient: `mask` +
+   * `mask-composite`, which subtract the element's own content box to leave a ring — the same
+   * physical property `media-mask` claims under the `'mask'` channel — and `position: relative`
+   * plus a `padding` that *is* the ring's thickness, which is a claim on the host's box in the
+   * sense `pin` and `background-media` already use `'layout'` for. Declared only as
+   * `background`, a `gradient-border, pin-section` pair composed silently while both decided the
+   * host's `position`, and `gradient-border, mask-reveal` while both wrote `mask`.
+   */
+  cssPrimitive("ambient-gradient-ring", [CHANNEL.background, "mask", "layout"], {
+    parameters: drift,
+    defaultActivation: "load",
+    reducedMotion: "disable",
+    perfClass: "continuous"
+  }),
+  cssPrimitive("ambient-tint", [CHANNEL.background], {
+    parameters: tint,
+    defaultActivation: "load",
+    reducedMotion: "disable",
+    perfClass: "continuous"
+  }),
   cssPrimitive("ambient-float", [CHANNEL.translate], {
     parameters: float,
     defaultActivation: "load",
@@ -95,49 +134,58 @@ var AMBIENT_PRESETS = [
   { name: "aurora", primitive: "ambient-gradient", keyframes: "kui-aurora" },
   {
     name: "gradient-rotate-border",
-    primitive: "ambient-gradient",
+    primitive: "ambient-gradient-ring",
     keyframes: "kui-gradient-rotate-border",
     params: { duration: "6s", ease: "linear" }
   },
+  {
+    // Not `gradient`: this rule masks its own content box away (`mask-composite: exclude`) to leave
+    // a ring, so putting the name on real content deletes the content. `-border` says that out loud,
+    // matching `gradient-rotate-border` and `beam-border`.
+    name: "gradient-border",
+    primitive: "ambient-gradient-ring",
+    keyframes: "kui-gradient-border",
+    params: { duration: "6s", ease: "linear" }
+  },
   {
     name: "noise-overlay",
-    primitive: "ambient-gradient",
+    primitive: "ambient-tint",
     keyframes: "kui-noise-overlay",
     params: { duration: "650ms", ease: "steps(6)" }
   },
   {
     name: "scanline",
-    primitive: "ambient-gradient",
+    primitive: "ambient-tint",
     keyframes: "kui-scanline",
     params: { duration: "3.5s", ease: "linear" }
   },
   {
     name: "dot-grid-drift",
-    primitive: "ambient-gradient",
+    primitive: "ambient-tint",
     keyframes: "kui-dot-grid-drift",
     params: { duration: "16s", ease: "linear" }
   },
   {
     name: "line-grid-drift",
-    primitive: "ambient-gradient",
+    primitive: "ambient-tint",
     keyframes: "kui-line-grid-drift",
     params: { duration: "16s", ease: "linear" }
   },
   {
     name: "starfield",
-    primitive: "ambient-gradient",
+    primitive: "ambient-tint",
     keyframes: "kui-starfield",
     params: { duration: "40s", ease: "linear" }
   },
   {
     name: "spotlight-follow",
-    primitive: "ambient-gradient",
+    primitive: "ambient-tint",
     keyframes: "kui-spotlight-follow",
     params: { duration: "9s" }
   },
   {
     name: "wave-blob",
-    primitive: "ambient-gradient",
+    primitive: "ambient-tint",
     keyframes: "kui-wave-blob",
     params: { duration: "12s" }
   },
@@ -474,6 +522,10 @@ var liftParams = {
 var popParams = {
   scale: { type: "number", default: "1.06", cssProperty: "--kui-pop-scale", finite: true, minimum: 0 }
 };
+var beamParams = {
+  color: { type: "color", default: "", cssProperty: "--kui-beam-border-c1" },
+  outset: { type: "length", default: "", cssProperty: "--kui-beam-border-outset" }
+};
 function hoverPrimitive(id, channels, extraParams = {}) {
   return {
     id,
@@ -501,7 +553,7 @@ var HOVER_PRIMITIVES = [
   hoverPrimitive("split-flap", ["rotate"]),
   hoverPrimitive("border-draw", ["border"]),
   hoverPrimitive("border-glow", ["shadow"]),
-  hoverPrimitive("beam-border", ["border"]),
+  hoverPrimitive("beam-border", ["border"], beamParams),
   hoverPrimitive("underline-slide", ["scale"]),
   hoverPrimitive("underline-center", ["scale"]),
   hoverPrimitive("icon-wiggle", ["rotate"]),
@@ -517,7 +569,7 @@ var CONTINUOUS_BORDER_PRIMITIVES = [
     id: "beam-border-auto",
     renderer: "javascript",
     channels: ["border"],
-    parameters: hoverTiming,
+    parameters: { ...hoverTiming, ...beamParams },
     supportedTimelines: ["time"],
     supportedActivations: ["load"],
     defaultActivation: "load",
@@ -806,6 +858,177 @@ function registerInteraction(registry) {
   return registry.registerPrimitives(INTERACTION_PRIMITIVES).registerPresets(INTERACTION_PRESETS);
 }
 
+// src/effects/catalog/background-media.ts
+var VIDEO_EXTENSIONS = /* @__PURE__ */ new Set(["mp4", "webm", "mov", "m4v", "ogv"]);
+var VIDEO_PAGE_HOSTS = /* @__PURE__ */ new Set([
+  "youtube.com",
+  "www.youtube.com",
+  "m.youtube.com",
+  "youtube-nocookie.com",
+  "www.youtube-nocookie.com",
+  "youtu.be",
+  "www.youtu.be"
+]);
+function normalizeUrl(value) {
+  const stripped = value.replace(/[\t\n\r]/g, "");
+  let start = 0;
+  while (start < stripped.length && stripped.charCodeAt(start) <= 32) start += 1;
+  return stripped.slice(start);
+}
+function hostOf(value) {
+  const withoutScheme = normalizeUrl(value).replace(/^[a-z][a-z0-9+.-]*:/i, "").replace(/^\/\//, "");
+  const end = withoutScheme.search(/[/?#]/);
+  const authority = end === -1 ? withoutScheme : withoutScheme.slice(0, end);
+  return authority.slice(authority.lastIndexOf("@") + 1).toLowerCase();
+}
+function isVideoPageUrl(value) {
+  return VIDEO_PAGE_HOSTS.has(hostOf(value));
+}
+var FOCAL_POINTS = {
+  center: "50% 50%",
+  top: "50% 0%",
+  bottom: "50% 100%",
+  left: "0% 50%",
+  right: "100% 50%",
+  "top-left": "0% 0%",
+  "top-right": "100% 0%",
+  "bottom-left": "0% 100%",
+  "bottom-right": "100% 100%"
+};
+var FOCAL_POINT_NAMES = Object.keys(FOCAL_POINTS);
+function focalPosition(focus) {
+  return FOCAL_POINTS[focus] ?? FOCAL_POINTS.center;
+}
+function paintsOverlay(options) {
+  return options.overlay !== "transparent" && options.overlayOpacity > 0;
+}
+function isVideoSource(src) {
+  const path = src.split("?")[0].split("#")[0];
+  const dot = path.lastIndexOf(".");
+  if (dot <= path.lastIndexOf("/")) return false;
+  return VIDEO_EXTENSIONS.has(path.slice(dot + 1).toLowerCase());
+}
+var ALLOWED_SCHEMES = /* @__PURE__ */ new Set(["http", "https"]);
+function schemeOf(value) {
+  const match = /^([a-z][a-z0-9+.-]*):/i.exec(normalizeUrl(value));
+  return match ? match[1].toLowerCase() : "";
+}
+function mediaSource(authored, name, ctx) {
+  if (!authored) return authored;
+  if (isVideoPageUrl(authored)) {
+    ctx.warn(
+      `background-media "${name}": "${authored}" is a video *page*, not a media file \u2014 a YouTube URL cannot be played by <video> and needs an iframe embed instead. Point "${name}" at an .mp4/.webm file, or use a YouTube facade alongside this effect.`
+    );
+    return "";
+  }
+  const scheme = schemeOf(authored);
+  if (!scheme || ALLOWED_SCHEMES.has(scheme)) return authored;
+  ctx.warn(
+    `background-media "${name}": "${scheme}:" URLs are not allowed \u2014 use https:, http:, or a path such as "/media/hero.mp4".`
+  );
+  return "";
+}
+function styleLayer(node) {
+  const { style } = node;
+  style.setProperty("position", "absolute");
+  style.setProperty("top", "0");
+  style.setProperty("left", "0");
+  style.setProperty("width", "100%");
+  style.setProperty("height", "100%");
+  style.setProperty("border-radius", "inherit");
+  style.setProperty("pointer-events", "none");
+  style.setProperty("z-index", "-1");
+}
+function createOverlay(doc, options) {
+  const scrim = doc.createElement("div");
+  styleLayer(scrim);
+  scrim.style.setProperty("background", options.overlay);
+  scrim.style.setProperty("opacity", String(options.overlayOpacity));
+  scrim.setAttribute("aria-hidden", "true");
+  return scrim;
+}
+function createVideo(doc, options) {
+  const video = doc.createElement("video");
+  video.muted = true;
+  video.setAttribute("muted", "");
+  video.playsInline = true;
+  video.setAttribute("playsinline", "");
+  video.loop = options.loop;
+  video.defaultPlaybackRate = options.rate;
+  video.playbackRate = options.rate;
+  video.preload = "metadata";
+  if (options.poster) video.poster = options.poster;
+  video.src = options.src;
+  return video;
+}
+function play(video) {
+  const started = video.play();
+  if (started) void started.catch(() => {
+  });
+}
+function startPlayback(video, win, options) {
+  if (options.reducedMotion || options.autoplay === "never") return () => {
+  };
+  if (options.autoplay === "always") {
+    play(video);
+    return () => {
+      if (!video.paused) video.pause();
+    };
+  }
+  return autoplayInView(video, win);
+}
+function createImage(doc, options) {
+  const image = doc.createElement("img");
+  image.alt = "";
+  image.decoding = "async";
+  image.src = options.src;
+  return image;
+}
+function autoplayInView(video, win) {
+  const Observer = win.IntersectionObserver;
+  if (!Observer) return () => {
+  };
+  const observer = new Observer(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) play(video);
+        else if (!video.paused) video.pause();
+      }
+    },
+    { threshold: 0 }
+  );
+  observer.observe(video);
+  return () => {
+    observer.disconnect();
+    if (!video.paused) video.pause();
+  };
+}
+function installBackgroundMedia(el, ctx, options) {
+  const doc = el.ownerDocument;
+  const video = isVideoSource(options.src) ? createVideo(doc, options) : null;
+  const node = video ?? createImage(doc, options);
+  styleLayer(node);
+  node.style.setProperty("object-fit", options.fit);
+  node.style.setProperty("object-position", options.position);
+  node.setAttribute("aria-hidden", "true");
+  node.setAttribute("data-kui-background", "");
+  el.append(node);
+  const overlay = paintsOverlay(options) ? createOverlay(doc, options) : null;
+  if (overlay) {
+    overlay.setAttribute("data-kui-background-overlay", "");
+    el.append(overlay);
+  }
+  const stopPlayback = video ? startPlayback(video, ctx.win, options) : () => {
+  };
+  return {
+    remove: () => {
+      stopPlayback();
+      node.remove();
+      overlay?.remove();
+    }
+  };
+}
+
 // src/effects/catalog/media-shared.ts
 var AXIS_DEGREES = { vertical: 0, horizontal: 90 };
 var UNIT_DEGREES = { deg: 1, grad: 0.9, rad: 180 / Math.PI, turn: 360 };
@@ -1099,7 +1322,7 @@ var slatParams = {
   },
   fold: { type: "keyword", default: "false", cssProperty: "--kui-fold", values: ["true", "false"] },
   duration: { type: "time", default: "500ms", cssProperty: "--kui-duration" },
-  delay: { type: "time", default: "0ms", cssProperty: "--kui-delay" },
+  ...TRIGGER_DELAY_PARAM,
   ease: { type: "easing", default: "ease-out", cssProperty: "--kui-ease" },
   stagger: { type: "time", default: "60ms", cssProperty: "--kui-stagger" }
 };
@@ -1145,6 +1368,133 @@ function prepareSlatAssemble(el, params, ctx) {
     }
   };
 }
+var backgroundMediaParams = {
+  /*
+   * `text`, and same-origin-checked at the point of use rather than by the type — identical
+   * shape and identical reasoning to `media-scrub`'s own `src` (`scroll-mechanics/primitives.ts`).
+   * A URL has no lexical shape to validate against, and `type: 'text'` is the one type that never
+   * reaches a stylesheet, which is what makes accepting arbitrary path characters safe.
+   */
+  src: { type: "text", default: "", cssProperty: "--kui-src" },
+  /*
+   * The still a `<video>` shows before its first frame decodes. Not optional polish: without it a
+   * background clip paints as an empty box for as long as the network takes, and that box is the
+   * backdrop to the author's text — the one place on the page where a flash of nothing is most
+   * visible. Every background video in this repo's own demo pages is authored with one.
+   */
+  poster: { type: "text", default: "", cssProperty: "--kui-poster" },
+  /*
+   * `fill`, `none` and `scale-down` are deliberately absent. `fill` is the only `object-fit` value
+   * that distorts — it stretches the picture to the box rather than cropping it — and the standing
+   * rule for imagery in this project is to crop, never stretch. The other two leave the media at
+   * its intrinsic size inside a box sized to something else, which for a *backdrop* is a gap, not
+   * a layout. Adding them would be offering three ways to get a broken background.
+   */
+  fit: {
+    type: "keyword",
+    default: "cover",
+    cssProperty: "--kui-fit",
+    values: ["cover", "contain"]
+  },
+  /*
+   * Which part of the picture a `cover` crop keeps. Nine named points rather than a free
+   * `object-position` string, because a free string would have to be `type: 'text'` — the one type
+   * that is explicitly never written to a stylesheet (see `core/params.ts`) — and this value is
+   * written to one. A keyword list is validated against its own `values`, so the author gets real
+   * focal control and the CSS surface stays closed.
+   */
+  focus: {
+    type: "keyword",
+    default: "center",
+    cssProperty: "--kui-focus",
+    values: FOCAL_POINT_NAMES
+  },
+  /*
+   * The scrim. This is the parameter that makes the whole effect usable, because the point of a
+   * backdrop here is animated text on top of it, and text over unmodified footage is illegible
+   * about half the time — a light frame arrives and the headline vanishes for those seconds.
+   *
+   * `type: 'color'` so it goes through the same validator every other colour does. `transparent`
+   * as the default rather than an empty string for the same reason: `''` is not a colour, and a
+   * default that its own type would reject is a lie the schema cannot catch. It is also the honest
+   * spelling of "no scrim", and no scrim node is created for it.
+   */
+  overlay: { type: "color", default: "transparent", cssProperty: "--kui-overlay" },
+  /*
+   * Separate from the colour rather than folded into it. `overlay:rgb(0 0 0 / 45%)` does parse —
+   * the tokenizer is paren-aware — but `overlay:black overlay-opacity:45%` is the spelling someone
+   * reaches for while tuning legibility, and tuning is exactly what this value is for.
+   */
+  "overlay-opacity": { type: "percentage", default: "100%", cssProperty: "--kui-overlay-opacity" },
+  /*
+   * The opt-out for the play-while-visible behaviour. `in-view` pairs the clip with the viewport
+   * and is right for a long section. `always` is for a short hero clip that must never be caught
+   * mid-stall by a visibility heuristic. `never` installs the clip and leaves it on its poster,
+   * which is also where any mode lands under a reduced-motion preference.
+   */
+  autoplay: {
+    type: "keyword",
+    default: "in-view",
+    cssProperty: "--kui-autoplay",
+    values: ["in-view", "always", "never"]
+  },
+  /*
+   * Bounded at both ends: `0` is a clip that is loaded, decoding, and permanently frozen — worse
+   * than `autoplay:never`, which at least says so — and browsers stop honouring rates past roughly
+   * 4 anyway, so a larger number is a silent no-op rather than a faster clip.
+   */
+  rate: {
+    type: "number",
+    default: "1",
+    cssProperty: "--kui-rate",
+    finite: true,
+    minimum: 0.25,
+    maximum: 4
+  },
+  loop: { type: "keyword", default: "true", cssProperty: "--kui-loop", values: ["true", "false"] }
+  /*
+   * There is deliberately no `controls:`. The layer this primitive builds paints at `z-index: -1`
+   * behind the author's own children, so a native control bar there is focusable by keyboard and
+   * occluded by whatever the page happens to put over it — a player you can tab into and cannot
+   * see. A clip meant to be controlled is a content `<video controls>` the author writes, not a
+   * background one.
+   */
+};
+function prepareBackgroundMedia(el, params, ctx) {
+  const authored = params.text("src");
+  if (!authored) {
+    ctx.warn('background-media needs a "src:" \u2014 nothing installed');
+    return () => {
+    };
+  }
+  const src = mediaSource(authored, "src", ctx);
+  if (!src) return () => {
+  };
+  const node = el;
+  if (ctx.win.getComputedStyle(node).position === "static") ctx.style.set("position", "relative");
+  ctx.style.set("isolation", "isolate");
+  const layer = installBackgroundMedia(el, ctx, {
+    src,
+    poster: mediaSource(params.text("poster"), "poster", ctx),
+    fit: params.is("fit", "contain") ? "contain" : "cover",
+    position: focalPosition(params.text("focus", "center")),
+    overlay: params.text("overlay", "transparent"),
+    // `num` returns a percentage as a 0–1 ratio, which is exactly what `opacity` takes.
+    overlayOpacity: Math.min(1, Math.max(0, params.num("overlay-opacity", 1))),
+    autoplay: params.text("autoplay", "in-view"),
+    rate: params.num("rate", 1),
+    // `!is('loop', 'false')`, not `is('loop')`. Every other read here names its own fallback, and
+    // this one has to as well: `is()` takes no fallback argument, so a bare `is('loop')` is only
+    // true when something already filled the schema default in. That holds on the animator's path
+    // (`readEffectParams` pre-fills every declared parameter) and not on `createParams`, so the
+    // positive spelling silently defaulted a true-by-default parameter to false for any caller
+    // handing over raw values. Reading it as "loop unless explicitly told not to" states the
+    // default at the point of use, where it cannot drift.
+    loop: !params.is("loop", "false"),
+    reducedMotion: ctx.reducedMotion
+  });
+  return continuousSetup(layer.remove);
+}
 var MEDIA_JS_PRIMITIVES = [
   {
     id: "slat-assemble",
@@ -1165,10 +1515,68 @@ var MEDIA_JS_PRIMITIVES = [
     // in `core/types.ts` for why the catalog's default is the opposite of this.
     restoresOnFinish: true,
     prepare: deferPrepare(prepareSlatAssemble)
+  },
+  {
+    id: "background-media",
+    /*
+     * `media` is the same word `media-scrub` uses for "this effect owns what the element shows",
+     * and it is what makes `background-media, video-scrub` on one element a reported conflict
+     * rather than two effects silently fighting over the same picture.
+     *
+     * `layout` is claimed for the same reason `pin` claims it: preparation writes `position` and
+     * `isolation` on the *host*, which is a stacking-context claim on someone else's element. Left
+     * undeclared, `background-media, pin-section` composed silently while both decided what
+     * `position` the host has — the conflict detector cannot report a claim it was never told about.
+     */
+    channels: ["media", "layout"],
+    renderer: "javascript",
+    parameters: backgroundMediaParams,
+    // Not a claim to support four timelines — an abstention. A backdrop is not driven by progress
+    // of any kind and this primitive never reads `Timeline`; the list exists only so that
+    // `data-kui="background-media src:/hero.mp4, parallax"` plus a `timeline:view` survives
+    // `compile.ts`'s `intersect`. See `TIMELINE_AGNOSTIC` (`effects/shared.ts`), shared with the
+    // scroll-mechanics drivers, which abstain for the same reason.
+    supportedTimelines: TIMELINE_AGNOSTIC,
+    supportedActivations: ["load", "enter", "manual"],
+    /*
+     * `'load'`, not the catalog's usual `'enter'`, and this is the difference between working and
+     * not. A backdrop is the element's appearance, so gating it on an IntersectionObserver means a
+     * section that is already on screen at page load, one in a background tab (no IO callbacks
+     * fire at all until the tab is foregrounded), or one whose own box is still zero-area waits an
+     * unbounded time to have any background — and unlike a missed reveal, that is a visibly broken
+     * page. An author who *wants* a heavy clip deferred can still write `on:enter`.
+     */
+    defaultActivation: "load",
+    perfClass: "paint",
+    /*
+     * `'shorten'`, unlike every other JS-rendered primitive in this file and in `text.ts`, and
+     * deliberately so. `'disable'` means the animator never calls `activate()` under a reduced
+     * motion preference, which for an animation is exactly right and for this is not: it would
+     * leave the element with no backdrop at all rather than a calmer one. There is no CSS duration
+     * here for `'shorten'` to shorten, so the policy is inert and the effect installs normally;
+     * `ctx.reducedMotion` is then read inside, where it suppresses the one genuinely motion-y part
+     * — a clip's autoplay — and leaves the poster frame standing. See `autoplayInView`.
+     */
+    reducedMotion: "shorten",
+    prepare: deferPrepare(prepareBackgroundMedia)
   }
 ];
 var MEDIA_JS_PRESETS = [
-  { name: "slat-assemble", primitive: "slat-assemble", cloak: true }
+  { name: "slat-assemble", primitive: "slat-assemble", cloak: true },
+  /*
+   * Two names, one primitive — the alias shape the catalog already uses everywhere (`pin-until`,
+   * `pin-spacer` and `stacking-cards` are three names over the one `pin` primitive; six `wipe-*`
+   * names share `media-wipe`). A preset row is the alias mechanism, so a second spelling costs a
+   * table entry and nothing else: no duplicated implementation to keep in sync, and both names
+   * resolve to the same `prepare`.
+   *
+   * No `cloak` on either: the pre-JS cloak rule hides an element until the runtime installs the
+   * effect's from-state, and this element is the author's own content. Cloaking it would blank
+   * their text for as long as the bundle takes to arrive, to hide a backdrop that has no
+   * from-state at all.
+   */
+  { name: "bg", primitive: "background-media" },
+  { name: "background", primitive: "background-media" }
 ];
 var MEDIA_PRIMITIVES = [...MEDIA_CSS_PRIMITIVES, ...MEDIA_JS_PRIMITIVES];
 var MEDIA_PRESETS = [...MEDIA_CSS_PRESETS, ...MEDIA_JS_PRESETS];
@@ -1311,6 +1719,7 @@ var COUNT_STEP_MS = 16;
 var REDUCED_MOTION_DURATION_MS = 1;
 var countParams = {
   duration: { type: "time", default: "1600ms", cssProperty: "--kui-duration" },
+  ...TRIGGER_DELAY_PARAM,
   from: { type: "number", default: "0", cssProperty: "--kui-from" },
   to: { type: "number", default: "100", cssProperty: "--kui-to" },
   decimals: {
@@ -1331,6 +1740,7 @@ var countParams = {
 };
 var odometerParams = {
   duration: { type: "time", default: "1600ms", cssProperty: "--kui-duration" },
+  ...TRIGGER_DELAY_PARAM,
   from: { type: "number", default: "0", cssProperty: "--kui-from" },
   to: { type: "number", default: "100", cssProperty: "--kui-to" }
 };
@@ -1357,7 +1767,9 @@ function tweenDurationMs(params, ctx) {
 function tweenTimingFor(params, ctx) {
   return {
     durationMs: tweenDurationMs(params, ctx),
-    delayMs: Math.max(0, params.timing.delayMs ?? 0),
+    // Positional first, then the same-named parameter — the two-spellings rule `effectDurationMs`
+    // applies to `duration` just above, now applied to `delay` as well.
+    delayMs: Math.max(0, params.timing.delayMs ?? params.ms("delay", 0)),
     easing: resolveEasing(params.timing.easing, ctx.warn)
   };
 }
@@ -1617,15 +2029,22 @@ function createStepRunner(win, options) {
 function appendCharSpans(container, doc, text) {
   const spans = [];
   let index = 0;
+  let wordWrapper = null;
   for (const grapheme of segmentGraphemes(text)) {
     if (grapheme.trim() === "") {
       container.append(doc.createTextNode(grapheme));
+      wordWrapper = null;
       continue;
     }
+    if (!wordWrapper) {
+      wordWrapper = doc.createElement("span");
+      wordWrapper.className = "kui-split-word";
+      container.append(wordWrapper);
+    }
     const span = doc.createElement("span");
     markItem(span, index);
     span.textContent = grapheme;
-    container.append(span);
+    wordWrapper.append(span);
     spans.push(span);
     index++;
   }
@@ -1672,7 +2091,13 @@ function appendLineSpans(container, doc, text) {
   return buckets.map((nodes, index) => {
     const line = doc.createElement("span");
     markItem(line, index, "kui-split-line");
-    for (const node of nodes) line.append(node);
+    for (const node of nodes) {
+      if (node instanceof HTMLElement) {
+        node.removeAttribute("class");
+        node.style.removeProperty("--kui-i");
+      }
+      line.append(node);
+    }
     container.append(line);
     return line;
   });
@@ -1806,7 +2231,7 @@ function jsTextPrimitive(id, channels, options) {
 }
 var splitTiming = {
   duration: { type: "time", default: "500ms", cssProperty: "--kui-duration" },
-  delay: { type: "time", default: "0ms", cssProperty: "--kui-delay" },
+  ...TRIGGER_DELAY_PARAM,
   ease: { type: "easing", default: "ease-out", cssProperty: "--kui-ease" },
   stagger: { type: "time", default: "30ms", cssProperty: "--kui-stagger" },
   unit: {
@@ -1824,6 +2249,11 @@ var splitTiming = {
 };
 var motionParams = {
   stagger: { type: "time", default: "40ms", cssProperty: "--kui-stagger" },
+  // `duration`/`ease` are deliberately *not* declared beside the delay: text.css pins both for
+  // wave and jitter on a higher-specificity `[data-kui-split-fx='wave'] .kui-split-item` rule, so
+  // declaring them would advertise two knobs that the stylesheet then overrides. `animation-delay`
+  // is the one the phase-start rule leaves alone, which is what lets `applyStaggerVars` honour it.
+  ...TRIGGER_DELAY_PARAM,
   motion: {
     type: "keyword",
     default: "wave",
@@ -1833,10 +2263,15 @@ var motionParams = {
 };
 var typewriterParams = {
   step: { type: "time", default: "55ms", cssProperty: "--kui-step" },
-  loop: { type: "keyword", default: "false", cssProperty: "--kui-loop", values: ["true", "false"] }
+  loop: { type: "keyword", default: "false", cssProperty: "--kui-loop", values: ["true", "false"] },
+  ...TRIGGER_DELAY_PARAM
 };
 var scrambleParams = {
   step: { type: "time", default: "40ms", cssProperty: "--kui-step" },
+  // `duration` gets no such shared declaration: `stepMsFor` reads its authored-or-not distinction
+  // to decide between a whole-effect time and a per-tick `step:`, and a schema default would erase
+  // that distinction. A `0ms` delay default has no equivalent problem.
+  ...TRIGGER_DELAY_PARAM,
   revealEvery: {
     type: "number",
     default: "2",
@@ -1853,7 +2288,11 @@ var scrambleParams = {
 };
 var wordCyclerParams = {
   words: { type: "text", default: "", cssProperty: "--kui-words" },
-  interval: { type: "time", default: "2200ms", cssProperty: "--kui-interval" }
+  interval: { type: "time", default: "2200ms", cssProperty: "--kui-interval" },
+  // Load-bearing here, not just for symmetry: a cycler has no authored `duration` — `interval:`
+  // paces it — so the positional "duration then delay" slot only reached a delay when the author
+  // wrote a throwaway first value, `word-cycler 0ms 300ms`.
+  ...TRIGGER_DELAY_PARAM
 };
 function prepareSplitText(el, params, ctx) {
   const doc = el.ownerDocument;
@@ -1899,7 +2338,7 @@ function prepareTypewriter(el, params, ctx) {
     layers.decorative.textContent = graphemes.slice(0, count).join("");
   };
   const run = createStepRunner(ctx.win, {
-    delayMs: params.timing.delayMs ?? 0,
+    delayMs: params.timing.delayMs ?? params.ms("delay", 0),
     stepMs: stepMsFor(params, graphemes.length, 55),
     tick: () => {
       const step = nextTypeState(state, graphemes.length, loop2);
@@ -1923,6 +2362,16 @@ function prepareTypewriter(el, params, ctx) {
 function prepareScramble(el, params, ctx) {
   const charset = SCRAMBLE_CHARSETS[params.text("charset", "upper")];
   const revealEvery = Math.max(1, Math.round(params.num("revealEvery", 2)));
+  const node = el;
+  const authoredMinWidth = node.style.getPropertyValue("min-width");
+  const authoredMinHeight = node.style.getPropertyValue("min-height");
+  const restRect = el.getBoundingClientRect();
+  ctx.style.set("min-width", `${restRect.width}px`);
+  ctx.style.set("min-height", `${restRect.height}px`);
+  const releaseSizeLock = () => {
+    ctx.style.set("min-width", authoredMinWidth);
+    ctx.style.set("min-height", authoredMinHeight);
+  };
   const layers = installSplitLayers(el, el.ownerDocument);
   layers.decorative.classList.add("kui-scramble");
   const graphemes = segmentGraphemes(layers.originalText);
@@ -1934,25 +2383,29 @@ function prepareScramble(el, params, ctx) {
   render();
   const totalTicks = Math.max(1, graphemes.length * revealEvery);
   const run = createStepRunner(ctx.win, {
-    delayMs: params.timing.delayMs ?? 0,
+    delayMs: params.timing.delayMs ?? params.ms("delay", 0),
     stepMs: stepMsFor(params, totalTicks, Math.max(1, 700 / totalTicks)),
     tick: () => {
       ticks++;
       if (ticks % revealEvery === 0) resolved++;
       render();
-      return resolved >= graphemes.length;
+      const done = resolved >= graphemes.length;
+      if (done) releaseSizeLock();
+      return done;
     }
   });
   return {
     cleanup: () => {
       run.stop();
       layers.restore();
+      releaseSizeLock();
     },
     finished: run.finished,
     finish: () => {
       run.stop();
       resolved = graphemes.length;
       render();
+      releaseSizeLock();
     }
   };
 }
@@ -1965,7 +2418,7 @@ function prepareWordCycler(el, params, ctx) {
   let index = 0;
   el.textContent = words[0];
   const run = createStepRunner(ctx.win, {
-    delayMs: params.timing.delayMs ?? 0,
+    delayMs: params.timing.delayMs ?? params.ms("delay", 0),
     stepMs: params.ms("interval", 2200),
     tick: () => {
       el.classList.add("kui-word-cycler-swap");
@@ -2013,13 +2466,16 @@ var TEXT_JS_PRIMITIVES = [
     perfClass: "continuous"
   })
 ];
+var CHARS_STAGGER = "30ms";
+var WORDS_STAGGER = "90ms";
+var LINES_STAGGER = "160ms";
 var TEXT_JS_PRESETS = [
-  { name: "split-chars", primitive: "split-text", params: { unit: "chars", direction: "fade" } },
-  { name: "split-words", primitive: "split-text", params: { unit: "words", direction: "fade" } },
-  { name: "split-lines", primitive: "split-text", params: { unit: "lines", direction: "fade" } },
-  { name: "text-reveal-up", primitive: "split-text", params: { unit: "words", direction: "up" }, cloak: true },
-  { name: "text-reveal-down", primitive: "split-text", params: { unit: "words", direction: "down" }, cloak: true },
-  { name: "text-reveal-mask", primitive: "split-text", params: { unit: "lines", direction: "mask" }, cloak: true },
+  { name: "split-chars", primitive: "split-text", params: { unit: "chars", direction: "fade", stagger: CHARS_STAGGER } },
+  { name: "split-words", primitive: "split-text", params: { unit: "words", direction: "fade", stagger: WORDS_STAGGER } },
+  { name: "split-lines", primitive: "split-text", params: { unit: "lines", direction: "fade", stagger: LINES_STAGGER } },
+  { name: "text-reveal-up", primitive: "split-text", params: { unit: "words", direction: "up", stagger: WORDS_STAGGER }, cloak: true },
+  { name: "text-reveal-down", primitive: "split-text", params: { unit: "words", direction: "down", stagger: WORDS_STAGGER }, cloak: true },
+  { name: "text-reveal-mask", primitive: "split-text", params: { unit: "lines", direction: "mask", stagger: LINES_STAGGER }, cloak: true },
   { name: "text-wave", primitive: "split-text-motion", params: { motion: "wave" } },
   { name: "text-jitter", primitive: "split-text-motion", params: { motion: "jitter" } },
   { name: "typewriter", primitive: "typewriter", params: { loop: "false" } },
@@ -2353,7 +2809,7 @@ function stepStateFor(position, index) {
 // src/effects/forms/primitives.ts
 var timing = {
   duration: { type: "time", default: "400ms", cssProperty: "--kui-duration" },
-  delay: { type: "time", default: "0ms", cssProperty: "--kui-delay" },
+  ...TRIGGER_DELAY_PARAM,
   ease: { type: "easing", default: "ease-out", cssProperty: "--kui-ease" }
 };
 var NATIVE_STATE_PRIMITIVE = {
@@ -3547,12 +4003,13 @@ function scrollPrimitive(spec) {
     renderer: "javascript",
     channels,
     parameters,
-    // `'pin'` is accepted but ignored: these primitives read scroll position themselves and are
-    // never driven by an `animation-timeline`. It is listed so that composing the driver with the
-    // effects it drives — `data-kui="pin-section distance:200vh, parallax-rotate ... "` plus
-    // `timeline:pin` — survives `compile.ts`'s `intersect`. Without it the intersection empties,
-    // `style-plan.ts` refuses the timeline, and the scrub silently degrades to a one-shot.
-    supportedTimelines: ["time", "view", "scroll", "pin"],
+    // Accepted, never read: these primitives read scroll position themselves and are never driven
+    // by an `animation-timeline`. The list exists so that composing the driver with the effects it
+    // drives — `data-kui="pin-section distance:200vh, parallax-rotate ... "` plus `timeline:pin` —
+    // survives `compile.ts`'s `intersect`. Without it the intersection empties, `style-plan.ts`
+    // refuses the timeline, and the scrub silently degrades to a one-shot. See `TIMELINE_AGNOSTIC`
+    // (`effects/shared.ts`) for why the name says abstention rather than support.
+    supportedTimelines: TIMELINE_AGNOSTIC,
     supportedActivations: ["manual", "load", "enter"],
     defaultActivation: "load",
     perfClass,
@@ -3829,7 +4286,21 @@ var SCROLL_PRIMITIVES = [
   }),
   scrollPrimitive({
     id: "smooth-scroll",
-    channels: ["layout"],
+    /*
+     * Its own channel, not the `'layout'` it used to share with `pin`, `stacking-cards` and
+     * `scroll-snap`. The channel model exists to stop two effects fighting over the same CSS
+     * property, and this one writes exactly `scroll-behavior` — a property that describes how a
+     * *user-or-script-initiated* scroll is performed, and that no other primitive touches.
+     *
+     * On `'layout'` it made a legitimate pairing impossible. Both `smooth-scroll` and
+     * `scroll-snap` have to sit on the document element to have any effect at all — neither
+     * `scroll-behavior` nor `scroll-snap-type` is propagated to the viewport from `<body>` — so
+     * "apply them to nested elements", the advice the conflict message gives, has no valid
+     * nesting to offer here. `data-kui="smooth-scroll-to, scroll-snap-y"` on `<html>` is the
+     * ordinary way to ask for smooth anchor jumps on a page that also snaps, and it was refused
+     * for a collision that cannot happen: the two write disjoint properties.
+     */
+    channels: ["scroll-behavior"],
     parameters: {
       behavior: { type: "keyword", default: "smooth", cssProperty: "--kui-scroll-behavior", values: ["smooth", "auto"] }
     },
@@ -4266,6 +4737,32 @@ function registerSvg(registry) {
 }
 
 // src/effects/three-d/index.ts
+var FLIP_CONTROL_SELECTOR = ":scope > .kui-flip-control";
+function prepareCardToggle(el, params, ctx) {
+  const trigger = params.text("trigger", "click");
+  if (trigger === "click") return () => {
+  };
+  if (!supportsFineHover(ctx.win)) return () => {
+  };
+  const control = el.querySelector(FLIP_CONTROL_SELECTOR);
+  if (!control) {
+    ctx.warn(`flip-card trigger:${trigger} found no direct-child .kui-flip-control \u2014 the card will not flip`);
+    return () => {
+    };
+  }
+  const set = (flipped) => control.setAttribute("aria-pressed", String(flipped));
+  const isFlipped = () => control.getAttribute("aria-pressed") === "true";
+  const onEnter = () => {
+    set(trigger === "hover-toggle" ? !isFlipped() : true);
+  };
+  const onLeave = () => set(false);
+  el.addEventListener("pointerenter", onEnter, { passive: true });
+  if (trigger === "hover") el.addEventListener("pointerleave", onLeave, { passive: true });
+  return () => {
+    el.removeEventListener("pointerenter", onEnter);
+    el.removeEventListener("pointerleave", onLeave);
+  };
+}
 var CARD_TOGGLE_PRIMITIVE = {
   id: "card-toggle",
   renderer: "javascript",
@@ -4273,14 +4770,20 @@ var CARD_TOGGLE_PRIMITIVE = {
   parameters: {
     duration: { type: "time", default: "700ms", cssProperty: "--kui-duration" },
     ease: { type: "easing", default: "ease-in-out", cssProperty: "--kui-ease" },
-    perspective: { type: "length", default: "1600px", cssProperty: "--kui-perspective" }
+    perspective: { type: "length", default: "1600px", cssProperty: "--kui-perspective" },
+    trigger: {
+      type: "keyword",
+      default: "click",
+      cssProperty: "--kui-flip-trigger",
+      values: ["click", "hover", "hover-latch", "hover-toggle"]
+    }
   },
   supportedTimelines: ["time"],
   supportedActivations: ["load"],
   defaultActivation: "load",
   perfClass: "compositor",
   reducedMotion: "disable",
-  prepare: () => inertInstance()
+  prepare: deferPrepare(prepareCardToggle)
 };
 var THREE_D_PRIMITIVES = [
   // `skew`, not `rotate`: the keyframes in three-d.css write `transform: perspective(...)