kuinetic 0.1.2 → 0.1.3

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

@@ -3,6 +3,7 @@ import {
   CHANNEL,
   Registry,
   clamp01,
+  continuousSetup,
   createAttributeLedger,
   createMeasureCache,
   createStyleLedger,
@@ -11,7 +12,7 @@ import {
   inertInstance,
   isSameOriginPath,
   toPixels
-} from "./chunk-LWS4OSLX.mjs";
+} from "./chunk-JT4PZL3A.mjs";
 
 // src/effects/shared.ts
 var COMMON = {
@@ -51,6 +52,13 @@ var float = {
   ease: { type: "easing", default: "ease-in-out", cssProperty: "--kui-ease" },
   distance: { type: "length", default: "14px", cssProperty: "--kui-distance" }
 };
+var orbit = {
+  duration: { type: "time", default: "3.5s", cssProperty: "--kui-duration" },
+  // `linear` by default, unlike every other ambient primitive: a continuous rotation that eases
+  // visibly stutters once per revolution, because the ease restarts at each iteration boundary.
+  ease: { type: "easing", default: "linear", cssProperty: "--kui-ease" },
+  angle: { type: "angle", default: "360deg", cssProperty: "--kui-to-angle" }
+};
 var pulse = {
   duration: { type: "time", default: "2.2s", cssProperty: "--kui-duration" },
   ease: { type: "easing", default: "ease-in-out", cssProperty: "--kui-ease" },
@@ -69,6 +77,12 @@ var AMBIENT_PRIMITIVES = [
     reducedMotion: "disable",
     perfClass: "continuous"
   }),
+  cssPrimitive("ambient-orbit", [CHANNEL.rotate], {
+    parameters: orbit,
+    defaultActivation: "load",
+    reducedMotion: "disable",
+    perfClass: "continuous"
+  }),
   cssPrimitive("ambient-pulse", [CHANNEL.scale, CHANNEL.opacity], {
     parameters: pulse,
     defaultActivation: "load",
@@ -140,6 +154,7 @@ var AMBIENT_PRESETS = [
     keyframes: "kui-floating-shapes",
     params: { duration: "6s", distance: "10px" }
   },
+  { name: "orbit", primitive: "ambient-orbit", keyframes: "kui-orbit" },
   { name: "glow-pulse", primitive: "ambient-pulse", keyframes: "kui-glow-pulse" }
 ];
 function registerAmbient(registry) {
@@ -456,6 +471,9 @@ var hoverTiming = {
 var liftParams = {
   distance: { type: "length", default: "6px", cssProperty: "--kui-lift-distance" }
 };
+var popParams = {
+  scale: { type: "number", default: "1.06", cssProperty: "--kui-pop-scale", finite: true, minimum: 0 }
+};
 function hoverPrimitive(id, channels, extraParams = {}) {
   return {
     id,
@@ -477,6 +495,7 @@ function hoverPrimitive(id, channels, extraParams = {}) {
 }
 var HOVER_PRIMITIVES = [
   hoverPrimitive("lift", ["translate"], liftParams),
+  hoverPrimitive("pop", ["scale"], popParams),
   hoverPrimitive("lift-shadow", ["translate", "shadow"], liftParams),
   hoverPrimitive("shine-sweep", ["sweep"]),
   hoverPrimitive("split-flap", ["rotate"]),
@@ -787,12 +806,173 @@ function registerInteraction(registry) {
   return registry.registerPrimitives(INTERACTION_PRIMITIVES).registerPresets(INTERACTION_PRESETS);
 }
 
+// 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 };
+var BAND_OVERLAP_PX = 1;
+var STAGE_CLASS = "kui-slat-stage";
+var SLAT_CLASS = "kui-slat-item";
+var GOLDEN_RATIO_CONJUGATE = 0.6180339887498949;
+function slatOrder(index, count, from) {
+  if (count <= 1) return 0;
+  switch (from) {
+    case "start":
+      return index;
+    case "end":
+      return count - 1 - index;
+    case "edges":
+      return Math.min(index, count - 1 - index);
+    case "random-ish":
+      return Math.floor(index * GOLDEN_RATIO_CONJUGATE % 1 * count);
+    case "alternate":
+    default:
+      return zigzagRank(index, count);
+  }
+}
+function zigzagRank(index, count) {
+  const fromStart = index;
+  const fromEnd = count - 1 - index;
+  const pair = Math.min(fromStart, fromEnd);
+  return fromStart <= fromEnd ? pair * 2 : pair * 2 + 1;
+}
+function slatAngleDegrees(authored, axis) {
+  const trimmed = authored.trim();
+  if (!trimmed) return AXIS_DEGREES[axis];
+  const match = /^(-?(?:\d+(?:\.\d+)?|\.\d+))(deg|rad|grad|turn)?$/.exec(trimmed);
+  if (!match) return AXIS_DEGREES[axis];
+  const value = Number(match[1]);
+  if (!Number.isFinite(value)) return AXIS_DEGREES[axis];
+  const unit = match[2] ?? "deg";
+  const degrees = value * UNIT_DEGREES[unit];
+  return (degrees % 180 + 180) % 180;
+}
+function slatTravelVector(angleDegrees) {
+  const theta = angleDegrees * Math.PI / 180;
+  return { x: -Math.sin(theta), y: Math.cos(theta) };
+}
+function slatBandClip(index, count, angleDegrees, box) {
+  const { width, height } = box;
+  const theta = angleDegrees * Math.PI / 180;
+  const nx = Math.cos(theta);
+  const ny = Math.sin(theta);
+  const { x: dx, y: dy } = slatTravelVector(angleDegrees);
+  const span = Math.abs(nx) * width + Math.abs(ny) * height;
+  const centreX = width / 2;
+  const centreY = height / 2;
+  const step = span / count;
+  const near = index * step - span / 2 - BAND_OVERLAP_PX;
+  const far = (index + 1) * step - span / 2 + BAND_OVERLAP_PX;
+  const reach = width + height;
+  const corner = (along, across) => `${(centreX + along * nx + across * dx).toFixed(2)}px ${(centreY + along * ny + across * dy).toFixed(2)}px`;
+  return `polygon(${corner(near, reach)}, ${corner(near, -reach)}, ${corner(far, -reach)}, ${corner(far, reach)})`;
+}
+function axisLabel(angleDegrees) {
+  if (angleDegrees === 0) return "vertical";
+  if (angleDegrees === 90) return "horizontal";
+  return "diagonal";
+}
+function syncStageToImage(stage, img, bands) {
+  const { slats, angleDegrees } = bands;
+  const width = img.offsetWidth;
+  const height = img.offsetHeight;
+  stage.style.top = `${img.offsetTop}px`;
+  stage.style.left = `${img.offsetLeft}px`;
+  stage.style.width = `${width}px`;
+  stage.style.height = `${height}px`;
+  slats.forEach((slat, index) => {
+    slat.style.clipPath = slatBandClip(index, slats.length, angleDegrees, { width, height });
+  });
+}
+function watchImageBox(stage, img, win, bands) {
+  const handler = () => syncStageToImage(stage, img, bands);
+  win.addEventListener("resize", handler, { passive: true });
+  const stopWindow = () => win.removeEventListener("resize", handler);
+  const ResizeObserverCtor = win.ResizeObserver;
+  if (!ResizeObserverCtor) return stopWindow;
+  const observer = new ResizeObserverCtor(handler);
+  observer.observe(img);
+  return () => {
+    stopWindow();
+    observer.disconnect();
+  };
+}
+function imagePaintStyle(img, win) {
+  const computed = win.getComputedStyle(img);
+  const position = computed.objectPosition || "50% 50%";
+  const fit = computed.objectFit;
+  if (fit === "cover") return { size: "cover", position };
+  if (fit === "contain" || fit === "scale-down") return { size: "contain", position };
+  if (fit === "none") return { size: "auto", position };
+  return { size: "100% 100%", position };
+}
+function installSlatStage(el, doc, win, options) {
+  const img = el.querySelector("img");
+  if (!img) return null;
+  const url = img.currentSrc || img.getAttribute("src") || "";
+  if (!url) return null;
+  const { count, angleDegrees, from, fold } = options;
+  const travel = slatTravelVector(angleDegrees);
+  const stage = doc.createElement("div");
+  stage.className = STAGE_CLASS;
+  stage.setAttribute("aria-hidden", "true");
+  stage.dataset.kuiSlatAxis = axisLabel(angleDegrees);
+  stage.dataset.kuiSlatAngle = String(angleDegrees);
+  stage.dataset.kuiSlatFold = String(fold);
+  stage.style.setProperty("--kui-slat-count", String(count));
+  stage.style.setProperty("--kui-slat-dx", travel.x.toFixed(4));
+  stage.style.setProperty("--kui-slat-dy", travel.y.toFixed(4));
+  const paint = imagePaintStyle(img, win);
+  const slats = [];
+  for (let index = 0; index < count; index++) {
+    const slat = doc.createElement("div");
+    slat.className = SLAT_CLASS;
+    slat.style.setProperty("--kui-slat-index", String(index));
+    slat.style.setProperty("--kui-i", String(slatOrder(index, count, from)));
+    slat.style.backgroundImage = `url("${url}")`;
+    slat.style.backgroundSize = paint.size;
+    slat.style.backgroundPosition = paint.position;
+    stage.append(slat);
+    slats.push(slat);
+  }
+  el.append(stage);
+  const bands = { slats, angleDegrees };
+  syncStageToImage(stage, img, bands);
+  const stopWatching = watchImageBox(stage, img, win, bands);
+  const imageStyles = createStyleLedger(img);
+  imageStyles.set("visibility", "hidden");
+  return {
+    stage,
+    slats,
+    restore: () => {
+      stopWatching();
+      imageStyles.restore();
+      stage.remove();
+    }
+  };
+}
+function applySlatTimingVars(stage, params) {
+  const { durationMs, delayMs, easing } = params.timing;
+  const duration = durationMs === void 0 ? params.text("duration", "500ms") : `${durationMs}ms`;
+  const delay = delayMs === void 0 ? params.text("delay", "0ms") : `${delayMs}ms`;
+  stage.style.setProperty("--kui-duration", duration);
+  stage.style.setProperty("--kui-delay", delay);
+  stage.style.setProperty("--kui-ease", easing ?? params.text("ease", "ease-out"));
+  stage.style.setProperty("--kui-stagger", params.text("stagger", "60ms"));
+}
+function slatAssembleFinishMs(params, count) {
+  if (count === 0) return 0;
+  const durationMs = params.timing.durationMs ?? params.ms("duration", 500);
+  const delayMs = params.timing.delayMs ?? params.ms("delay", 0);
+  const staggerMs = params.ms("stagger", 60);
+  return delayMs + (count - 1) * staggerMs + durationMs;
+}
+
 // src/effects/catalog/media.ts
 var geometry = {
   distance: { type: "length", default: "24px", cssProperty: "--kui-distance" },
   scale: { type: "number", default: "1.12", cssProperty: "--kui-to-scale" }
 };
-var MEDIA_PRIMITIVES = [
+var MEDIA_CSS_PRIMITIVES = [
   cssPrimitive("media-wipe", [CHANNEL.clip]),
   cssPrimitive("media-mask", ["mask"], { perfClass: "paint" }),
   // Not `reducedMotion: 'disable'` — that policy means "no finite duration would make sense,
@@ -813,33 +993,66 @@ var MEDIA_PRIMITIVES = [
     defaultActivation: "hover",
     perfClass: "paint"
   }),
+  // `geometry.distance` only, not `...geometry`: `kui-blur-up` (media.css) reads `--kui-distance`
+  // and `--kui-blur` but never `--kui-to-scale` — this primitive doesn't even declare
+  // `CHANNEL.scale`. Spreading the whole shared object used to expose `scale:` as an
+  // apparently-valid, silently-inert parameter, the same shape `flip-3d`'s dead `perspective`
+  // parameter was (`entrance.css`'s comment on `kui-flip-in-x`).
   cssPrimitive("media-blur-up", [CHANNEL.translate, CHANNEL.filter], {
-    parameters: { ...geometry, blur: { type: "length", default: "16px", cssProperty: "--kui-blur" } },
+    parameters: {
+      distance: geometry.distance,
+      blur: { type: "length", default: "16px", cssProperty: "--kui-blur" }
+    },
     perfClass: "paint"
   }),
+  // No `defaultActivation` — same convention `core.ts`'s `parallax`/`parallax-scale`/
+  // `parallax-rotate`/`scroll-fade`/`desaturate`/`skew`/`progress`/`progress-stroke` already use
+  // for every other `timelines: ['view', 'scroll', ...]` primitive. `resolveActivation`
+  // (`animator.ts`) only consults `defaultActivation` when the author named no activation, and
+  // falls through to `element-config.ts`'s hardcoded `'enter'` when a primitive declares none.
+  // Setting it to `'manual'` here (matching `activations: ['manual']`) looked like the obviously
+  // correct pairing, but it is what actually broke the effect: `effectiveActivation`
+  // (`style-plan.ts`) only converts a stuck `'manual'` into `'enter'` when `config.timeline !==
+  // 'time'` — i.e. only once the author has actually written `timeline:view`/`timeline:scroll`.
+  // Authored bare (no `timeline:`, the sweep's own probe and the likely first thing anyone
+  // tries), `config.timeline` stays the default `'time'`, that conversion never fires, and the
+  // element sits at `data-kui-state="ready"` forever — which is also the state
+  // `entrance.css`'s `[data-kui-state='ready'] { --kui-distance: 0px !important; }` targets, so
+  // every sample read the same permanently-zeroed `--kui-distance`: not a paused animation, a
+  // zeroed one. `timeline:view`/`timeline:scroll` usage is unaffected either way, since a native
+  // timeline resolves to the `'native-timeline'` gate before activation is even consulted.
+  // `geometry.distance` only: `kui-image-parallax-frame` never reads `--kui-to-scale` and this
+  // primitive doesn't declare `CHANNEL.scale` — same dead-parameter shape as `media-blur-up` above.
   cssPrimitive("media-parallax-frame", [CHANNEL.translate], {
-    parameters: geometry,
+    parameters: { distance: geometry.distance },
     timelines: ["view", "scroll"],
     activations: ["manual"],
-    defaultActivation: "manual",
     reducedMotion: "disable"
   }),
+  // Its own `scale` parameter, not `geometry`: `kui-lightbox-open` opens from a fixed 0.92, never
+  // reading `--kui-to-scale` (or any `distance`, since this primitive doesn't animate position at
+  // all) — the whole shared object was dead weight here. Unlike `media-blur-up`/
+  // `media-parallax-frame`, this primitive *does* declare `CHANNEL.scale`, so the fix is to wire
+  // the keyframe up to a real parameter rather than remove the promise: `--kui-from-scale`, the
+  // same name and "starts at this scale, animates to 1" meaning `scale`/`scale-move`
+  // (`catalog/core.ts`) already use, so `lightbox-open scale:0.8` now does what it looks like it
+  // should. See `kui-lightbox-open` in `media.css`.
   cssPrimitive("media-lightbox", [CHANNEL.opacity, CHANNEL.scale], {
-    parameters: geometry
+    parameters: { scale: { type: "number", default: "0.92", cssProperty: "--kui-from-scale" } }
   })
 ];
-var MEDIA_PRESETS = [
-  { name: "wipe-up", primitive: "media-wipe", keyframes: "kui-wipe-up" },
-  { name: "wipe-down", primitive: "media-wipe", keyframes: "kui-wipe-down" },
-  { name: "wipe-left", primitive: "media-wipe", keyframes: "kui-wipe-left" },
-  { name: "wipe-right", primitive: "media-wipe", keyframes: "kui-wipe-right" },
-  { name: "wipe-circle", primitive: "media-wipe", keyframes: "kui-wipe-circle" },
-  { name: "wipe-diagonal", primitive: "media-wipe", keyframes: "kui-wipe-diagonal" },
-  { name: "mask-reveal", primitive: "media-mask", keyframes: "kui-mask-reveal" },
-  { name: "curtain-reveal", primitive: "media-wipe", keyframes: "kui-curtain-reveal" },
+var MEDIA_CSS_PRESETS = [
+  { name: "wipe-up", primitive: "media-wipe", keyframes: "kui-wipe-up", cloak: true },
+  { name: "wipe-down", primitive: "media-wipe", keyframes: "kui-wipe-down", cloak: true },
+  { name: "wipe-left", primitive: "media-wipe", keyframes: "kui-wipe-left", cloak: true },
+  { name: "wipe-right", primitive: "media-wipe", keyframes: "kui-wipe-right", cloak: true },
+  { name: "wipe-circle", primitive: "media-wipe", keyframes: "kui-wipe-circle", cloak: true },
+  { name: "wipe-diagonal", primitive: "media-wipe", keyframes: "kui-wipe-diagonal", cloak: true },
+  { name: "mask-reveal", primitive: "media-mask", keyframes: "kui-mask-reveal", cloak: true },
+  { name: "curtain-reveal", primitive: "media-wipe", keyframes: "kui-curtain-reveal", cloak: true },
   { name: "ken-burns", primitive: "media-ken-burns", keyframes: "kui-ken-burns" },
   { name: "ken-burns-out", primitive: "media-ken-burns", keyframes: "kui-ken-burns-out" },
-  { name: "blur-up", primitive: "media-blur-up", keyframes: "kui-blur-up" },
+  { name: "blur-up", primitive: "media-blur-up", keyframes: "kui-blur-up", cloak: true },
   { name: "duotone-hover", primitive: "media-filter", keyframes: "kui-duotone-hover" },
   { name: "grayscale-hover", primitive: "media-filter", keyframes: "kui-grayscale-hover" },
   { name: "saturate-hover", primitive: "media-filter", keyframes: "kui-saturate-hover" },
@@ -851,14 +1064,131 @@ var MEDIA_PRESETS = [
   { name: "before-after-wipe", primitive: "media-wipe", keyframes: "kui-before-after-wipe" },
   { name: "lightbox-open", primitive: "media-lightbox", keyframes: "kui-lightbox-open" }
 ];
+var slatParams = {
+  slats: {
+    type: "number",
+    default: "8",
+    cssProperty: "--kui-slats",
+    minimum: 2,
+    maximum: 24,
+    integer: true
+  },
+  axis: {
+    type: "keyword",
+    default: "vertical",
+    cssProperty: "--kui-axis",
+    values: ["vertical", "horizontal"]
+  },
+  /*
+   * The general form of `axis:`, in degrees: `0deg` is `axis:vertical`, `90deg` is
+   * `axis:horizontal`, and anything between cuts the picture into diagonal bands. An authored
+   * angle wins; leaving it off reads `axis:`, so every existing attribute keeps its meaning.
+   *
+   * `text`, not `angle`, for one reason: `readParams` pre-fills every declared parameter with its
+   * schema default, so a typed default is indistinguishable from an authored value and there would
+   * be no way to tell `angle:0deg` from "no angle, use the axis". An empty default is only possible
+   * on a type that is never written to a stylesheet, which is exactly what `text` is for — and this
+   * value never reaches CSS anyway. `slatAngleDegrees` does the parsing and the range clamp.
+   */
+  angle: { type: "text", default: "", cssProperty: "--kui-slat-angle" },
+  from: {
+    type: "keyword",
+    default: "alternate",
+    cssProperty: "--kui-from",
+    values: ["alternate", "start", "end", "edges", "random-ish"]
+  },
+  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" },
+  ease: { type: "easing", default: "ease-out", cssProperty: "--kui-ease" },
+  stagger: { type: "time", default: "60ms", cssProperty: "--kui-stagger" }
+};
+function prepareSlatAssemble(el, params, ctx) {
+  const doc = el.ownerDocument;
+  const count = Math.min(24, Math.max(2, Math.round(params.num("slats", 8))));
+  const axis = params.text("axis", "vertical");
+  const angleDegrees = slatAngleDegrees(params.text("angle", ""), axis);
+  const from = params.text("from", "alternate");
+  const fold = params.is("fold");
+  const node = el;
+  if (ctx.win.getComputedStyle(node).position === "static") ctx.style.set("position", "relative");
+  const built = installSlatStage(el, doc, ctx.win, { count, angleDegrees, from, fold });
+  if (!built) return () => {
+  };
+  const { stage } = built;
+  applySlatTimingVars(stage, params);
+  stage.classList.add("kui-slat-animating");
+  let settle2;
+  const finished = new Promise((resolve) => {
+    settle2 = resolve;
+  });
+  let landed = false;
+  const land = () => {
+    if (landed) return;
+    landed = true;
+    stage.classList.remove("kui-slat-animating");
+    built.restore();
+    settle2();
+  };
+  const timer = ctx.win.setTimeout(land, slatAssembleFinishMs(params, count));
+  return {
+    cleanup: () => {
+      ctx.win.clearTimeout(timer);
+      if (landed) return;
+      landed = true;
+      built.restore();
+    },
+    finished,
+    finish: () => {
+      ctx.win.clearTimeout(timer);
+      land();
+    }
+  };
+}
+var MEDIA_JS_PRIMITIVES = [
+  {
+    id: "slat-assemble",
+    renderer: "javascript",
+    channels: [CHANNEL.opacity, CHANNEL.translate, CHANNEL.rotate],
+    parameters: slatParams,
+    supportedTimelines: ["time"],
+    supportedActivations: ["load", "enter", "hover", "focus", "click", "manual"],
+    defaultActivation: "enter",
+    perfClass: "dom-transform",
+    // Same reasoning as every JS-rendered primitive in `text.ts`: nothing here declares a CSS
+    // `animation-duration` the reduced-motion policy layer could shorten, and `disable` is what
+    // stops `installSlatStage`'s DOM surgery from ever running at all under reduced motion — the
+    // animator never calls `activate()`, so the wrapped `<img>` is simply left exactly as authored.
+    reducedMotion: "disable",
+    // Land()ing hands the picture back to the real `<img>` and tears down every slat — see
+    // `prepareSlatAssemble`'s `land()`. Declared, not assumed: see `restoresOnFinish`'s own comment
+    // in `core/types.ts` for why the catalog's default is the opposite of this.
+    restoresOnFinish: true,
+    prepare: deferPrepare(prepareSlatAssemble)
+  }
+];
+var MEDIA_JS_PRESETS = [
+  { name: "slat-assemble", primitive: "slat-assemble", cloak: true }
+];
+var MEDIA_PRIMITIVES = [...MEDIA_CSS_PRIMITIVES, ...MEDIA_JS_PRIMITIVES];
+var MEDIA_PRESETS = [...MEDIA_CSS_PRESETS, ...MEDIA_JS_PRESETS];
 function registerMedia(registry) {
   return registry.registerPrimitives(MEDIA_PRIMITIVES).registerPresets(MEDIA_PRESETS);
 }
 
+// src/effects/catalog/subtree-capture.ts
+function captureChildren(el) {
+  const authored = Array.from(el.childNodes);
+  return () => {
+    el.replaceChildren(...authored);
+  };
+}
+
 // src/effects/catalog/numbers-shared.ts
 var SR_ONLY_CLASS = "kui-sr-only";
 var DECORATIVE_CLASS = "kui-count-decorative";
 function installCountLayers(el, doc) {
+  const restoreChildren = captureChildren(el);
   const decorative = doc.createElement("span");
   decorative.setAttribute("aria-hidden", "true");
   decorative.className = DECORATIVE_CLASS;
@@ -870,9 +1200,7 @@ function installCountLayers(el, doc) {
   return {
     decorative,
     srOnly,
-    restore: () => {
-      el.textContent = srOnly.textContent;
-    }
+    restore: restoreChildren
   };
 }
 function easeOutCubic(t) {
@@ -1182,7 +1510,12 @@ var COUNT_PRESETS = [
 ];
 var METER_PRIMITIVES = [
   cssPrimitive("stroke-sweep", [CHANNEL.stroke]),
-  cssPrimitive("meter-bar", [CHANNEL.scale]),
+  // `from` gives `progress-bar` a real knob on its start scale — it had none before. `--kui-bar-from`
+  // is also what the `[data-kui-fx~='progress-bar'][data-kui-state='ready']` gate in numbers.css
+  // neutralizes; see that rule's comment for the on:enter fix this parameter doubles as.
+  cssPrimitive("meter-bar", [CHANNEL.scale], {
+    parameters: { from: { type: "number", default: "0", cssProperty: "--kui-bar-from" } }
+  }),
   cssPrimitive("meter-segments", [CHANNEL.opacity]),
   cssPrimitive("meter-stars", [CHANNEL.clip])
 ];
@@ -1191,7 +1524,13 @@ var METER_PRESETS = [
   { name: "gauge-sweep", primitive: "stroke-sweep", keyframes: "kui-gauge-sweep" },
   { name: "donut-sweep", primitive: "stroke-sweep", keyframes: "kui-donut-sweep" },
   { name: "sparkline-draw", primitive: "stroke-sweep", keyframes: "kui-sparkline-draw" },
-  { name: "progress-bar", primitive: "meter-bar", keyframes: "kui-progress-bar" },
+  // `cloak: true`: `kui-progress-bar`'s `from { scale: 0 1 }` (numbers.css) is a zero-width box
+  // while paused, not just an invisible one — so while it waits it occupies no space in layout at
+  // all. Not, despite the tidier story, because an observer refuses to fire on it: Chromium was
+  // measured resolving a zero-area target's `intersectionRatio` to `1`. See numbers.css's
+  // `[data-kui-fx~='progress-bar'][data-kui-state='ready']` rule for the geometry half of the fix;
+  // `cloak` keeps the pre-JS and post-JS "waiting" look the same (invisible) either side of it.
+  { name: "progress-bar", primitive: "meter-bar", keyframes: "kui-progress-bar", cloak: true },
   { name: "progress-segments", primitive: "meter-segments", keyframes: "kui-progress-segments" },
   { name: "star-rating-fill", primitive: "meter-stars", keyframes: "kui-star-rating-fill" }
 ];
@@ -1206,6 +1545,7 @@ var SR_ONLY_CLASS2 = "kui-sr-only";
 var DECORATIVE_CLASS2 = "kui-split-decorative";
 function installSplitLayers(el, doc) {
   const originalText = el.textContent.trim();
+  const restoreChildren = captureChildren(el);
   const decorative = doc.createElement("span");
   decorative.setAttribute("aria-hidden", "true");
   decorative.className = DECORATIVE_CLASS2;
@@ -1217,9 +1557,7 @@ function installSplitLayers(el, doc) {
   return {
     decorative,
     originalText,
-    restore: () => {
-      el.textContent = originalText;
-    }
+    restore: restoreChildren
   };
 }
 function segmentGraphemes(text) {
@@ -1387,14 +1725,43 @@ var extrudeParams = {
   distance: { type: "length", default: "32px", cssProperty: "--kui-distance" }
 };
 var TEXT_CSS_PRIMITIVES = [
-  cssPrimitive("text-shimmer", [CHANNEL.background], { reducedMotion: "disable" }),
+  // `color`, alongside `background`: both presets' unconditional rule sets `-webkit-text-fill-color:
+  // transparent` so the `background-image` gradient shows through the glyphs (the standard
+  // gradient-text technique). That is a real claim on the glyph fill, the same physical property
+  // `text-outline-fill` animates on its own `color` channel below — without this, the two looked
+  // disjoint to the compiler (`background` vs `stroke`+`color`) and composing them would let
+  // whichever applied last silently win the glyph fill instead of being flagged as a conflict.
+  cssPrimitive("text-shimmer", [CHANNEL.background, CHANNEL.color], { reducedMotion: "disable" }),
+  // `gradient-sweep` is the only one of the three `text-sweep`-family presets whose keyframe
+  // touches `-webkit-text-fill-color` (see text.css) — `highlight-sweep` and `underline-draw` only
+  // paint a `background-image`. Claiming `color` for all three made the compiler reject compositions
+  // like `underline-draw, text-outline-fill` as a glyph-fill conflict even though they touch disjoint
+  // properties. Split so only the preset that actually claims the fill declares the channel.
+  cssPrimitive("text-gradient-sweep", [CHANNEL.background, CHANNEL.color], { parameters: textSweepParams }),
   cssPrimitive("text-sweep", [CHANNEL.background], { parameters: textSweepParams }),
   cssPrimitive("text-outline-fill", [CHANNEL.stroke, CHANNEL.color]),
   cssPrimitive("var-weight", ["font"], { parameters: fontWeightParams }),
   cssPrimitive("var-width", ["font"], { parameters: fontWidthParams }),
   cssPrimitive("var-slant", ["font"], { parameters: fontSlantParams }),
+  /*
+   * `defaultActivation: 'load'` for the same reason every ambient primitive declares it, and it
+   * was missing here: a marquee is continuous motion, so `reducedMotion: 'disable'` is only half
+   * the rule `ambient.ts` spells out — the other half is starting on `load` rather than waiting on
+   * a scroll-triggered `enter`.
+   *
+   * Without it, a bare `data-kui="marquee 42s"` resolved to `enter`, which `style-plan.ts`'s
+   * `resolveGate` sends down the `deferred` path and stamps `animation-play-state: paused`. It
+   * compiled correctly, reported `data-kui-state="ready"`, and never ran — measured on a marquee
+   * fully in view, so this was not an observer that had simply not fired yet. Every page carrying
+   * one had to know to write `on:load`, which is exactly the kind of thing an author cannot be
+   * expected to guess.
+   *
+   * `marquee-scroll-linked` is unaffected: its position comes from `animation-timeline: scroll()`,
+   * not from an activation.
+   */
   cssPrimitive("text-marquee", [CHANNEL.translate], {
     timelines: ["time", "scroll"],
+    defaultActivation: "load",
     reducedMotion: "disable"
   }),
   cssPrimitive("redaction-reveal", [CHANNEL.clip]),
@@ -1402,7 +1769,7 @@ var TEXT_CSS_PRIMITIVES = [
 ];
 var TEXT_CSS_PRESETS = [
   { name: "gradient-shimmer", primitive: "text-shimmer", keyframes: "kui-gradient-shimmer" },
-  { name: "gradient-sweep", primitive: "text-sweep", keyframes: "kui-gradient-sweep" },
+  { name: "gradient-sweep", primitive: "text-gradient-sweep", keyframes: "kui-gradient-sweep" },
   {
     name: "highlight-sweep",
     primitive: "text-sweep",
@@ -1565,9 +1932,10 @@ function prepareScramble(el, params, ctx) {
     layers.decorative.textContent = scrambledFrame(graphemes, resolved, charset, Math.random);
   };
   render();
+  const totalTicks = Math.max(1, graphemes.length * revealEvery);
   const run = createStepRunner(ctx.win, {
     delayMs: params.timing.delayMs ?? 0,
-    stepMs: stepMsFor(params, graphemes.length * revealEvery, 40),
+    stepMs: stepMsFor(params, totalTicks, Math.max(1, 700 / totalTicks)),
     tick: () => {
       ticks++;
       if (ticks % revealEvery === 0) resolved++;
@@ -1592,7 +1960,7 @@ function prepareWordCycler(el, params, ctx) {
   const words = params.text("words", "").split("|").map((word) => word.trim()).filter(Boolean);
   if (words.length === 0) return () => {
   };
-  const original = el.textContent;
+  const restoreChildren = captureChildren(el);
   const swapMs = 150;
   let index = 0;
   el.textContent = words[0];
@@ -1613,7 +1981,7 @@ function prepareWordCycler(el, params, ctx) {
     cleanup: () => {
       run.stop();
       el.classList.remove("kui-word-cycler-swap");
-      el.textContent = original;
+      restoreChildren();
     },
     finished: run.finished,
     finish: () => run.stop()
@@ -1649,9 +2017,9 @@ 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" } },
-  { name: "text-reveal-down", primitive: "split-text", params: { unit: "words", direction: "down" } },
-  { name: "text-reveal-mask", primitive: "split-text", params: { unit: "lines", direction: "mask" } },
+  { 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: "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" } },
@@ -1683,66 +2051,130 @@ var distance = {
   distance: { type: "length", default: "24px", cssProperty: "--kui-distance" },
   opacity: { type: "number", default: "0", cssProperty: "--kui-from-opacity" }
 };
+var ENTRANCE_TIMELINES = ["time", "view", "scroll", "pin"];
 var PRIMITIVES = [
   // --- entrance / exit -------------------------------------------------------------------
-  cssPrimitive("reveal", [CHANNEL.opacity, CHANNEL.translate], { parameters: distance }),
+  cssPrimitive("reveal", [CHANNEL.opacity, CHANNEL.translate], { timelines: ENTRANCE_TIMELINES, parameters: distance }),
   cssPrimitive("scale", [CHANNEL.scale], {
+    timelines: ENTRANCE_TIMELINES,
     parameters: { scale: { type: "number", default: "0.92", cssProperty: "--kui-from-scale" } }
   }),
   // Separate from `scale` because it claims translate as well and so composes differently.
+  // `distance.distance` only, not `...distance`: `kui-zoom-in-up`/`-down` (entrance.css) read
+  // `--kui-distance` and `--kui-from-scale` but never `--kui-from-opacity` — this primitive
+  // doesn't declare `CHANNEL.opacity`. Spreading the whole shared `distance` object used to expose
+  // `opacity:` as an apparently-valid, silently-inert parameter (same dead-parameter shape as
+  // `flip-3d`'s old `perspective`, fixed above).
   cssPrimitive("scale-move", [CHANNEL.scale, CHANNEL.translate], {
+    timelines: ENTRANCE_TIMELINES,
     parameters: {
-      ...distance,
+      distance: distance.distance,
       scale: { type: "number", default: "0.92", cssProperty: "--kui-from-scale" }
     }
   }),
   cssPrimitive("rotate", [CHANNEL.rotate], {
+    timelines: ENTRANCE_TIMELINES,
     parameters: { angle: { type: "angle", default: "-8deg", cssProperty: "--kui-from-angle" } }
   }),
+  // `distance.distance` only, not `...distance`: `kui-roll-in`/`-out` (entrance.css) write
+  // `rotate`/`translate`, never `opacity` — this primitive doesn't declare `CHANNEL.opacity`. Same
+  // dead-parameter shape as `scale-move` above.
   cssPrimitive("roll", [CHANNEL.rotate, CHANNEL.translate], {
+    timelines: ENTRANCE_TIMELINES,
     parameters: {
-      ...distance,
+      distance: distance.distance,
       angle: { type: "angle", default: "-120deg", cssProperty: "--kui-from-angle" }
     }
   }),
-  cssPrimitive("flip-3d", [CHANNEL.rotate], {
+  // `skew`, not `rotate`: entrance.css's keyframes write `transform: perspective(...)
+  // rotateX/Y(...)`, not the individual `rotate:` property — the `perspective` parameter below
+  // used to compile cleanly and do nothing, because nothing read it. See entrance.css's own
+  // comment on `kui-flip-in-x` for the fix; `CHANNEL.skew` is this catalog's name for "claims the
+  // whole `transform` shorthand" (`core/types.ts`), shared with `scroll-skew` and `flip-face`.
+  cssPrimitive("flip-3d", [CHANNEL.skew], {
+    timelines: ENTRANCE_TIMELINES,
     parameters: {
       angle: { type: "angle", default: "90deg", cssProperty: "--kui-from-angle" },
       perspective: { type: "length", default: "1200px", cssProperty: "--kui-perspective" }
     }
   }),
   cssPrimitive("blur", [CHANNEL.filter], {
+    timelines: ENTRANCE_TIMELINES,
     parameters: { blur: { type: "length", default: "12px", cssProperty: "--kui-blur" } }
   }),
   // Purpose-built combination: one keyframe, so opacity is written once instead of twice.
   cssPrimitive("reveal-blur", [CHANNEL.opacity, CHANNEL.translate, CHANNEL.filter], {
+    timelines: ENTRANCE_TIMELINES,
     parameters: { ...distance, blur: { type: "length", default: "12px", cssProperty: "--kui-blur" } }
   }),
   // --- scroll-linked ---------------------------------------------------------------------
   // These are progress-linked, not time-triggered: they reverse as the user scrolls back.
   // That is by design and is why `timeline:` is a different axis from `on:`.
+  // `distance.distance` only, not the whole `distance` object: `kui-parallax-y`/`-x` (scroll.css)
+  // write only `translate` — this primitive doesn't declare `CHANNEL.opacity`. Same dead-parameter
+  // shape as `scale-move`/`roll` above; `parallax-y`/`parallax-x`/`depth-layer` never read
+  // `--kui-from-opacity`.
   cssPrimitive("parallax", [CHANNEL.translate], {
-    parameters: distance,
-    timelines: ["view", "scroll"],
+    parameters: { distance: distance.distance },
+    timelines: ["view", "scroll", "pin"],
     activations: ["manual"],
     reducedMotion: "disable",
     perfClass: "compositor"
   }),
+  // `from` exists because the resting end was hardcoded (scale 1 / rotate 0deg), which fixed
+  // these to "grow slightly" and "tilt slightly" — a scroll-driven element that should sweep in
+  // from a quarter-size or from half a turn away had no way to say so. Same `--kui-from-*`
+  // properties the entrance primitives already use, so the two stay spellable the same way.
   cssPrimitive("parallax-scale", [CHANNEL.scale], {
-    parameters: { scale: { type: "number", default: "1.2", cssProperty: "--kui-to-scale" } },
-    timelines: ["view", "scroll"],
+    parameters: {
+      scale: { type: "number", default: "1.2", cssProperty: "--kui-to-scale" },
+      from: { type: "number", default: "1", cssProperty: "--kui-from-scale" }
+    },
+    timelines: ["view", "scroll", "pin"],
     activations: ["manual"],
     reducedMotion: "disable"
   }),
   cssPrimitive("parallax-rotate", [CHANNEL.rotate], {
-    parameters: { angle: { type: "angle", default: "12deg", cssProperty: "--kui-to-angle" } },
-    timelines: ["view", "scroll"],
+    parameters: {
+      angle: { type: "angle", default: "12deg", cssProperty: "--kui-to-angle" },
+      from: { type: "angle", default: "0deg", cssProperty: "--kui-from-angle" }
+    },
+    timelines: ["view", "scroll", "pin"],
     activations: ["manual"],
     reducedMotion: "disable"
   }),
   cssPrimitive("scroll-fade", [CHANNEL.opacity], {
     parameters: { opacity: { type: "number", default: "0", cssProperty: "--kui-from-opacity" } },
-    timelines: ["view", "scroll"],
+    timelines: ["view", "scroll", "pin"],
+    activations: ["manual"],
+    reducedMotion: "disable"
+  }),
+  // `filter`, not `opacity` — it collides with `blur`, and declaring the real channel is what
+  // makes `channels.ts` say so instead of letting the two silently overwrite each other's
+  // `filter` declaration.
+  cssPrimitive("desaturate", [CHANNEL.filter], {
+    parameters: {
+      from: { type: "percentage", default: "100%", cssProperty: "--kui-from-grayscale" },
+      to: { type: "percentage", default: "0%", cssProperty: "--kui-to-grayscale" }
+    },
+    timelines: ["view", "scroll", "pin"],
+    activations: ["manual"],
+    reducedMotion: "disable",
+    perfClass: "paint"
+  }),
+  /*
+   * `transform`, not one of the independent transform properties, because CSS never shipped a
+   * standalone `skew:`. That is also why `skew` is its own channel rather than folded in with
+   * `rotate`: writing `transform` replaces the entire shorthand, so a skew composed with anything
+   * else that wrote `transform` would silently win. Nothing else in the catalog does — every other
+   * transform in the library goes through `translate`/`rotate`/`scale` — so the shorthand is free.
+   */
+  cssPrimitive("skew", [CHANNEL.skew], {
+    parameters: {
+      from: { type: "angle", default: "8deg", cssProperty: "--kui-from-skew" },
+      to: { type: "angle", default: "0deg", cssProperty: "--kui-to-skew" }
+    },
+    timelines: ["view", "scroll", "pin"],
     activations: ["manual"],
     reducedMotion: "disable"
   }),
@@ -1762,13 +2194,14 @@ var PRIMITIVES = [
   })
 ];
 var p = (name, primitive, keyframes, params) => ({ name, primitive, keyframes, ...params ? { params } : {} });
+var pIn = (name, primitive, keyframes, params) => ({ ...p(name, primitive, keyframes, params), cloak: true });
 var FADE = [
-  p("fade-in", "reveal", "kui-in"),
+  pIn("fade-in", "reveal", "kui-in"),
   p("fade-out", "reveal", "kui-out"),
-  p("fade-up", "reveal", "kui-in-up"),
-  p("fade-down", "reveal", "kui-in-down"),
-  p("fade-left", "reveal", "kui-in-left"),
-  p("fade-right", "reveal", "kui-in-right"),
+  pIn("fade-up", "reveal", "kui-in-up"),
+  pIn("fade-down", "reveal", "kui-in-down"),
+  pIn("fade-left", "reveal", "kui-in-left"),
+  pIn("fade-right", "reveal", "kui-in-right"),
   p("fade-out-up", "reveal", "kui-out-up"),
   p("fade-out-down", "reveal", "kui-out-down"),
   p("fade-out-left", "reveal", "kui-out-left"),
@@ -1776,56 +2209,56 @@ var FADE = [
 ];
 var SLIDE_PARAMS = { distance: "100px", opacity: "1" };
 var SLIDE = [
-  p("slide-up", "reveal", "kui-in-up", SLIDE_PARAMS),
-  p("slide-down", "reveal", "kui-in-down", SLIDE_PARAMS),
-  p("slide-left", "reveal", "kui-in-left", SLIDE_PARAMS),
-  p("slide-right", "reveal", "kui-in-right", SLIDE_PARAMS),
+  pIn("slide-up", "reveal", "kui-in-up", SLIDE_PARAMS),
+  pIn("slide-down", "reveal", "kui-in-down", SLIDE_PARAMS),
+  pIn("slide-left", "reveal", "kui-in-left", SLIDE_PARAMS),
+  pIn("slide-right", "reveal", "kui-in-right", SLIDE_PARAMS),
   p("slide-out-up", "reveal", "kui-out-up", SLIDE_PARAMS),
   p("slide-out-down", "reveal", "kui-out-down", SLIDE_PARAMS),
   p("slide-out-left", "reveal", "kui-out-left", SLIDE_PARAMS),
   p("slide-out-right", "reveal", "kui-out-right", SLIDE_PARAMS)
 ];
 var LOGICAL = [
-  p("slide-inline-start", "reveal", "kui-in-inline-start", SLIDE_PARAMS),
-  p("slide-inline-end", "reveal", "kui-in-inline-end", SLIDE_PARAMS),
-  p("slide-block-start", "reveal", "kui-in-up", SLIDE_PARAMS),
-  p("slide-block-end", "reveal", "kui-in-down", SLIDE_PARAMS)
+  pIn("slide-inline-start", "reveal", "kui-in-inline-start", SLIDE_PARAMS),
+  pIn("slide-inline-end", "reveal", "kui-in-inline-end", SLIDE_PARAMS),
+  pIn("slide-block-start", "reveal", "kui-in-up", SLIDE_PARAMS),
+  pIn("slide-block-end", "reveal", "kui-in-down", SLIDE_PARAMS)
 ];
 var ZOOM = [
-  p("zoom-in", "scale", "kui-zoom-in"),
+  pIn("zoom-in", "scale", "kui-zoom-in"),
   p("zoom-out", "scale", "kui-zoom-out"),
-  p("pop-in", "scale", "kui-zoom-in", { scale: "0.6", ease: "back-out" }),
+  pIn("pop-in", "scale", "kui-zoom-in", { scale: "0.6", ease: "back-out" }),
   p("pop-out", "scale", "kui-zoom-out", { scale: "0.6", ease: "back-in" }),
-  p("zoom-in-up", "scale-move", "kui-zoom-in-up"),
-  p("zoom-in-down", "scale-move", "kui-zoom-in-down")
+  pIn("zoom-in-up", "scale-move", "kui-zoom-in-up"),
+  pIn("zoom-in-down", "scale-move", "kui-zoom-in-down")
 ];
 var FLIP = [
-  p("flip-in-x", "flip-3d", "kui-flip-in-x"),
-  p("flip-in-y", "flip-3d", "kui-flip-in-y"),
+  pIn("flip-in-x", "flip-3d", "kui-flip-in-x"),
+  pIn("flip-in-y", "flip-3d", "kui-flip-in-y"),
   p("flip-out-x", "flip-3d", "kui-flip-out-x"),
   p("flip-out-y", "flip-3d", "kui-flip-out-y")
 ];
 var ROTATE = [
-  p("rotate-in", "rotate", "kui-rotate-in"),
+  pIn("rotate-in", "rotate", "kui-rotate-in"),
   p("rotate-out", "rotate", "kui-rotate-out"),
-  p("rotate-in-left", "rotate", "kui-rotate-in", { angle: "-45deg" }),
-  p("rotate-in-right", "rotate", "kui-rotate-in", { angle: "45deg" }),
-  p("roll-in", "roll", "kui-roll-in"),
+  pIn("rotate-in-left", "rotate", "kui-rotate-in", { angle: "-45deg" }),
+  pIn("rotate-in-right", "rotate", "kui-rotate-in", { angle: "45deg" }),
+  pIn("roll-in", "roll", "kui-roll-in"),
   p("roll-out", "roll", "kui-roll-out"),
-  p("swing-in", "rotate", "kui-swing-in", { angle: "-15deg", ease: "back-out" })
+  pIn("swing-in", "rotate", "kui-swing-in", { angle: "-15deg", ease: "back-out" })
 ];
 var BLUR = [
-  p("blur-in", "blur", "kui-blur-in"),
+  pIn("blur-in", "blur", "kui-blur-in"),
   p("blur-out", "blur", "kui-blur-out"),
-  p("fade-blur-up", "reveal-blur", "kui-fade-blur-up"),
-  p("fade-blur-in", "reveal-blur", "kui-fade-blur-in")
+  pIn("fade-blur-up", "reveal-blur", "kui-fade-blur-up"),
+  pIn("fade-blur-in", "reveal-blur", "kui-fade-blur-in")
 ];
 var CHARACTER = [
-  p("bounce-in", "scale", "kui-zoom-in", { scale: "0.3", ease: "back-out" }),
-  p("bounce-in-up", "reveal", "kui-in-up", { distance: "60px", ease: "back-out" }),
-  p("bounce-in-down", "reveal", "kui-in-down", { distance: "60px", ease: "back-out" }),
-  p("back-in-up", "reveal", "kui-in-up", { distance: "120px", ease: "expo-out" }),
-  p("back-in-down", "reveal", "kui-in-down", { distance: "120px", ease: "expo-out" })
+  pIn("bounce-in", "scale", "kui-zoom-in", { scale: "0.3", ease: "bounce" }),
+  pIn("bounce-in-up", "reveal", "kui-in-up", { distance: "60px", ease: "back-out" }),
+  pIn("bounce-in-down", "reveal", "kui-in-down", { distance: "60px", ease: "back-out" }),
+  pIn("back-in-up", "reveal", "kui-in-up", { distance: "120px", ease: "expo-out" }),
+  pIn("back-in-down", "reveal", "kui-in-down", { distance: "120px", ease: "expo-out" })
 ];
 var SCROLL = [
   p("parallax-y", "parallax", "kui-parallax-y"),
@@ -1834,11 +2267,14 @@ var SCROLL = [
   p("parallax-rotate", "parallax-rotate", "kui-parallax-rotate"),
   p("depth-layer", "parallax", "kui-parallax-y", { distance: "200px" }),
   p("scroll-fade", "scroll-fade", "kui-scroll-fade"),
+  p("scroll-desaturate", "desaturate", "kui-desaturate"),
+  p("scroll-skew", "skew", "kui-scroll-skew"),
   p("scroll-progress-bar", "progress", "kui-progress-x"),
+  p("scroll-progress-bar-y", "progress", "kui-progress-y"),
   p("scroll-progress-ring", "progress-stroke", "kui-progress-ring"),
   // `reveal-repeat` was removed: it was byte-identical to `reveal-once`, and the activation
   // binder unobserves after first entry, so a repeating reveal is not implementable yet.
-  p("reveal-once", "reveal", "kui-in-up")
+  pIn("reveal-once", "reveal", "kui-in-up")
 ];
 var PRESETS = [
   ...FADE,
@@ -1861,6 +2297,59 @@ function registerCore(registry) {
   return registry;
 }
 
+// src/effects/step-marking.ts
+var STEP_STATE_ATTR = "data-kui-step-state";
+function selectorBreadth(selector, doc) {
+  try {
+    if (doc.documentElement.matches(selector)) return "document-wide";
+    if (doc.body?.matches(selector)) return "document-wide";
+    return "ok";
+  } catch {
+    return "invalid";
+  }
+}
+function resolveTarget(selector, ctx, effect) {
+  if (!selector) return selector;
+  const breadth = selectorBreadth(selector, ctx.doc);
+  if (breadth === "invalid") {
+    ctx.warn(`${effect} target "${selector}" is not a valid selector and will be ignored`);
+    return "";
+  }
+  if (breadth === "document-wide") {
+    ctx.warn(`${effect} target "${selector}" matches the whole document and will be ignored`);
+    return "";
+  }
+  return selector;
+}
+function createStepMarker(resolve) {
+  const ledgers = /* @__PURE__ */ new Map();
+  return {
+    mark(index) {
+      const seen = /* @__PURE__ */ new Map();
+      for (const node of resolve()) {
+        const parent = node.parentElement;
+        const position = seen.get(parent) ?? 0;
+        seen.set(parent, position + 1);
+        let ledger = ledgers.get(node);
+        if (!ledger) {
+          ledger = createAttributeLedger(node);
+          ledgers.set(node, ledger);
+        }
+        ledger.set(STEP_STATE_ATTR, stepStateFor(position, index));
+      }
+    },
+    restore() {
+      for (const ledger of ledgers.values()) ledger.restore();
+      ledgers.clear();
+    }
+  };
+}
+function stepStateFor(position, index) {
+  if (position < index) return "before";
+  if (position === index) return "active";
+  return "after";
+}
+
 // src/effects/forms/primitives.ts
 var timing = {
   duration: { type: "time", default: "400ms", cssProperty: "--kui-duration" },
@@ -1979,10 +2468,18 @@ var RANGE_FILL_PRIMITIVE = jsInputPrimitive(
 function nextStep(step, total) {
   return total > 0 ? (step + 1) % total : 0;
 }
-function prepareStepProgress(el, params) {
+function prepareStepProgress(el, params, ctx) {
   const total = Math.max(1, Math.round(params.num("steps", 4)));
+  const selector = resolveTarget(params.text("target"), ctx, "step-progress");
+  const marker = createStepMarker(
+    () => selector ? ctx.doc.querySelectorAll(selector) : el.children
+  );
+  const self = createAttributeLedger(el);
   let step = 0;
-  const render = () => el.setAttribute("data-kui-step", String(step));
+  const render = () => {
+    self.set("data-kui-step", String(step));
+    marker.mark(step);
+  };
   const advance = () => {
     step = nextStep(step, total);
     render();
@@ -1991,13 +2488,17 @@ function prepareStepProgress(el, params) {
   render();
   return () => {
     el.removeEventListener("click", advance);
-    el.removeAttribute("data-kui-step");
+    self.restore();
+    marker.restore();
   };
 }
 var STEP_PROGRESS_PRIMITIVE = jsInputPrimitive(
   "step-progress",
   ["state"],
-  { steps: { type: "number", default: "4", cssProperty: "--kui-steps", minimum: 1, maximum: 20, integer: true } },
+  {
+    steps: { type: "number", default: "4", cssProperty: "--kui-steps", minimum: 1, maximum: 20, integer: true },
+    target: { type: "text", default: "", cssProperty: "--kui-target" }
+  },
   deferPrepare(prepareStepProgress)
 );
 function nextSubmitStage(stage) {
@@ -2254,6 +2755,7 @@ function prepareDraggable(el, params, ctx) {
   const resistance = params.num("resistance", 0.55);
   const momentum = params.num("momentum", 0.2);
   const offset = { x: 0, y: 0 };
+  const pickup = { x: 0, y: 0 };
   const deps = springDeps(ctx);
   const runners = {
     x: createSpringRunner(config, (value) => write({ ...offset, x: value }), deps),
@@ -2270,10 +2772,15 @@ function prepareDraggable(el, params, ctx) {
       onStart() {
         runners.x.stop();
         runners.y.stop();
+        pickup.x = offset.x;
+        pickup.y = offset.y;
         el.setAttribute("data-kui-dragging", "true");
       },
       onMove(vector) {
-        write({ x: resist(vector.dx, bounds, resistance), y: resist(vector.dy, bounds, resistance) });
+        write({
+          x: resist(pickup.x + vector.dx, bounds, resistance),
+          y: resist(pickup.y + vector.dy, bounds, resistance)
+        });
       },
       onEnd(vector) {
         el.setAttribute("data-kui-dragging", "false");
@@ -2301,8 +2808,9 @@ function settle(runners, offset, vector, mode) {
     runners.y.to(0);
     return;
   }
-  runners.x.to(offset.x + vector.vx * mode.momentum);
-  runners.y.to(offset.y + vector.vy * mode.momentum);
+  const carry = mode.inertia ? mode.momentum : 0;
+  runners.x.to(offset.x + vector.vx * carry);
+  runners.y.to(offset.y + vector.vy * carry);
 }
 function prepareSwipeable(el, params) {
   const stop = recognise(
@@ -2586,9 +3094,12 @@ function prepareAutoHeight(el, params, ctx) {
   ctx.style.claim("height");
   const duration = effectDurationMs(params, 400);
   let animation = null;
+  let previous = node.getBoundingClientRect().height;
   const observer = watchAttribute(node, params.text("attribute"), () => {
     animation?.cancel();
-    animation = animateHeight(node, duration, params.text("ease"));
+    const endpoints = heightEndpoints(node, previous);
+    previous = endpoints.to;
+    animation = animateHeight(node, endpoints, duration, params.text("ease"));
   });
   ctx.invalidate();
   return () => {
@@ -2596,13 +3107,19 @@ function prepareAutoHeight(el, params, ctx) {
     animation?.cancel();
   };
 }
-function animateHeight(node, duration, easing) {
-  const from = `${node.getBoundingClientRect().height}px`;
+function heightEndpoints(node, previous) {
   node.style.removeProperty("height");
-  const to = `${node.scrollHeight}px`;
+  const to = node.getBoundingClientRect().height;
+  return { from: previous, to };
+}
+function animateHeight(node, endpoints, duration, easing) {
   const animate = node.animate;
   if (typeof animate !== "function") return null;
-  return animate.call(node, [{ height: from }, { height: to }], { duration, easing, fill: "none" });
+  return animate.call(
+    node,
+    [{ height: `${endpoints.from}px` }, { height: `${endpoints.to}px` }],
+    { duration, easing, fill: "none" }
+  );
 }
 function prepareIndicator(el, params, ctx) {
   const node = el;
@@ -2732,27 +3249,42 @@ function subscribeScrollTop(el, ctx, onScrollTop) {
 }
 function prepareHeaderShrink(el, params, ctx) {
   const offset = params.num("offset", 120);
-  return subscribeScrollTop(el, ctx, (top) => {
+  const state = createAttributeLedger(el);
+  const unsubscribe = subscribeScrollTop(el, ctx, (top) => {
     const progress = offset > 0 ? Math.min(1, Math.max(0, top / offset)) : 1;
     ctx.style.set("--kui-shrink", progress.toFixed(4));
-    el.setAttribute("data-kui-shrunk", String(progress >= 1));
+    state.set("data-kui-shrunk", String(progress >= 1));
   });
+  return () => {
+    unsubscribe();
+    state.restore();
+  };
 }
 function prepareHeaderHide(el, params, ctx) {
   const minDelta = params.num("offset", 8);
   let last = 0;
-  return subscribeScrollTop(el, ctx, (top) => {
+  const state = createAttributeLedger(el);
+  const unsubscribe = subscribeScrollTop(el, ctx, (top) => {
     const delta = top - last;
     if (Math.abs(delta) < minDelta) return;
-    el.setAttribute("data-kui-hidden", String(delta > 0 && top > minDelta));
+    state.set("data-kui-hidden", String(delta > 0 && top > minDelta));
     last = top;
   });
+  return () => {
+    unsubscribe();
+    state.restore();
+  };
 }
 function prepareBackToTop(el, params, ctx) {
   const offset = params.num("offset", 400);
-  return subscribeScrollTop(el, ctx, (top) => {
-    el.setAttribute("data-kui-visible", String(top > offset));
+  const state = createAttributeLedger(el);
+  const unsubscribe = subscribeScrollTop(el, ctx, (top) => {
+    state.set("data-kui-visible", String(top > offset));
   });
+  return () => {
+    unsubscribe();
+    state.restore();
+  };
 }
 var NAV_JS_PRIMITIVES = [
   navPrimitive(
@@ -2790,13 +3322,38 @@ var domGeometry = (el) => {
   const rect = el.getBoundingClientRect();
   return { top: rect.top, height: rect.height };
 };
+var domPosition = (el) => {
+  const view = el.ownerDocument?.defaultView;
+  return view ? view.getComputedStyle(el).position : "static";
+};
+var domOffsetTop = (el) => {
+  const view = el.ownerDocument?.defaultView;
+  if (!view) return 0;
+  const parsed = Number.parseFloat(view.getComputedStyle(el).top);
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+function geometrySource(el, positionOf) {
+  let outermostSticky = null;
+  for (let node = el; node; node = node.parentElement) {
+    if (positionOf(node) === "sticky") outermostSticky = node;
+  }
+  return outermostSticky?.parentElement ?? el;
+}
+function sourceTop(el, box, measure, positionOf) {
+  const source = geometrySource(el, positionOf);
+  return source === el ? box.top : measure(source).top;
+}
 function trackProgress(el, ctx, options, onProgress) {
   const measure = options.measure ?? domGeometry;
+  const positionOf = options.positionOf ?? domPosition;
+  const offsetOf = options.offsetOf ?? domOffsetTop;
   let scrollTop = 0;
   let scrollportTop = 0;
   const geometry2 = createMeasureCache(() => {
     const box = measure(el);
-    return { contentTop: box.top - scrollportTop + scrollTop, height: box.height };
+    const top = options.contentAnchor ? measure(options.contentAnchor).top - box.height : sourceTop(el, box, measure, positionOf);
+    const stickyOffset = options.stickyEl ? offsetOf(options.stickyEl) : 0;
+    return { contentTop: top - stickyOffset - scrollportTop + scrollTop, height: box.height };
   });
   return ctx.scheduler.subscribe(ctx.rootFor(el), (frame) => {
     scrollTop = frame.metrics.scrollTop;
@@ -2822,11 +3379,167 @@ function progressFrom(top, span) {
   return clamp01(-top / span);
 }
 
+// src/effects/scroll-mechanics/scroll-spy.ts
+function prepareScrollSpy(el, params, ctx) {
+  const sectionsAuthored = params.text("sections");
+  if (sectionsAuthored) {
+    const sectionsSelector = resolveTarget(sectionsAuthored, ctx, "scroll-spy sections");
+    return prepareScrollSpyContainer(el, params, ctx, sectionsSelector);
+  }
+  return prepareScrollSpySingle(el, params, ctx);
+}
+function prepareScrollSpySingle(el, params, ctx) {
+  if (params.text("offset-top", "0px") !== "0px") {
+    ctx.warn('scroll-spy "offset-top" has no effect without sections: and is ignored here');
+  }
+  const selector = resolveTarget(params.text("target"), ctx, "scroll-spy");
+  const links = /* @__PURE__ */ new Map();
+  const self = createAttributeLedger(el);
+  let last;
+  const untrack = trackProgress(el, ctx, { distance: params.text("distance") }, (progress) => {
+    const active = progress > 0 && progress < 1;
+    if (active === last) return;
+    last = active;
+    self.set("data-kui-active", String(active));
+    if (selector) markLinks(ctx.doc, selector, active, links);
+  });
+  return continuousSetup(() => {
+    untrack();
+    self.restore();
+    for (const ledger of links.values()) ledger.restore();
+  });
+}
+function markLinks(doc, selector, active, links) {
+  for (const link of doc.querySelectorAll(selector)) {
+    let ledger = links.get(link);
+    if (!ledger) {
+      ledger = createAttributeLedger(link);
+      links.set(link, ledger);
+    }
+    ledger.set("data-kui-active", String(active));
+  }
+}
+function hrefHash(link) {
+  const href = link.getAttribute("href") ?? "";
+  const at = href.indexOf("#");
+  return at === -1 ? "" : href.slice(at);
+}
+function pairSectionsWithLinks(sections, links, ctx, sectionsSelector) {
+  const linksByHash = /* @__PURE__ */ new Map();
+  for (const link of links) {
+    const hash = hrefHash(link);
+    if (hash) linksByHash.set(hash, link);
+  }
+  const claimed = /* @__PURE__ */ new Set();
+  const pairs = sections.map((section) => {
+    if (!section.id) {
+      ctx.warn(
+        `scroll-spy: a section matched by sections:"${sectionsSelector}" has no id and cannot be paired with a link`
+      );
+      return { section, link: null };
+    }
+    const hash = `#${section.id}`;
+    const link = linksByHash.get(hash) ?? null;
+    if (link) claimed.add(hash);
+    return { section, link };
+  });
+  for (const [hash, link] of linksByHash) {
+    if (!claimed.has(hash)) {
+      ctx.warn(`scroll-spy: link "${link.getAttribute("href")}" matches no section id in sections:"${sectionsSelector}"`);
+    }
+  }
+  return pairs;
+}
+function offsetTopPixels(authored, frame) {
+  return toPixels(
+    authored,
+    {
+      viewportWidth: frame.metrics.viewportWidth,
+      viewportHeight: frame.metrics.viewportHeight,
+      percentBasis: 0,
+      fontSize: 16,
+      rootFontSize: 16
+    },
+    0
+  );
+}
+function highestReachedIndex(tops, scrollTop, line) {
+  let index = -1;
+  for (let i = 0; i < tops.length; i++) {
+    if (tops[i] - scrollTop - line <= 0) index = i;
+  }
+  return index;
+}
+function prepareScrollSpyContainer(el, params, ctx, sectionsSelector) {
+  if (params.text("distance", "100vh") !== "100vh") {
+    ctx.warn('scroll-spy "distance" has no effect with sections: \u2014 each section measures its own height');
+  }
+  const linksSelector = resolveTarget(params.text("target"), ctx, "scroll-spy target");
+  const sections = sectionsSelector ? [...el.querySelectorAll(sectionsSelector)] : [];
+  if (sectionsSelector && sections.length === 0) {
+    ctx.warn(`scroll-spy sections:"${sectionsSelector}" matched nothing inside this element`);
+  }
+  const links = linksSelector ? [...el.querySelectorAll(linksSelector)] : [];
+  const pairs = pairSectionsWithLinks(sections, links, ctx, sectionsSelector);
+  const sectionLedgers = pairs.map((pair) => createAttributeLedger(pair.section));
+  const linkLedgers = /* @__PURE__ */ new Map();
+  for (const { link } of pairs) {
+    if (link && !linkLedgers.has(link)) linkLedgers.set(link, createAttributeLedger(link));
+  }
+  const offsetAuthored = params.text("offset-top", "0px");
+  let scrollTop = 0;
+  let scrollportTop = 0;
+  const contentTops = createMeasureCache(
+    () => pairs.map(({ section }) => domGeometry(section).top - scrollportTop + scrollTop)
+  );
+  let active = -1;
+  function setActive(index, value) {
+    const pair = pairs[index];
+    sectionLedgers[index].set("data-kui-active", String(value));
+    if (pair.link) linkLedgers.get(pair.link).set("data-kui-active", String(value));
+  }
+  const untrack = ctx.scheduler.subscribe(ctx.rootFor(el), (frame) => {
+    scrollTop = frame.metrics.scrollTop;
+    scrollportTop = frame.metrics.viewportTop;
+    const tops = contentTops.read(frame.epoch);
+    const line = offsetTopPixels(offsetAuthored, frame);
+    const next = highestReachedIndex(tops, scrollTop, line);
+    if (next === active) return;
+    if (active !== -1) setActive(active, false);
+    if (next !== -1) setActive(next, true);
+    active = next;
+  });
+  return continuousSetup(() => {
+    untrack();
+    for (const ledger of sectionLedgers) ledger.restore();
+    for (const ledger of linkLedgers.values()) ledger.restore();
+  });
+}
+
 // src/effects/scroll-mechanics/primitives.ts
 var PROGRESS_VAR = "--kui-progress";
 var distanceParam = {
   distance: { type: "length", default: "100vh", cssProperty: "--kui-distance" }
 };
+var stickyParams = {
+  "offset-top": {
+    type: "length",
+    default: "var(--kui-pin-offset, 0px)",
+    cssProperty: "--kui-offset-top"
+  },
+  spacer: {
+    type: "keyword",
+    default: "false",
+    cssProperty: "--kui-spacer",
+    values: ["true", "false"]
+  }
+};
+function installSticky(node, params, ctx) {
+  ctx.style.set("position", "sticky");
+  ctx.style.set("top", params.text("offset-top", "var(--kui-pin-offset, 0px)"));
+  const inserted = params.is("spacer") ? insertSpacer(node, params.text("distance"), ctx) : null;
+  return { spacer: inserted?.spacer ?? null, dispose: () => inserted?.remove() };
+}
 function scrollPrimitive(spec) {
   const { id, channels, parameters, prepare, perfClass = "compositor" } = spec;
   return {
@@ -2834,7 +3547,12 @@ function scrollPrimitive(spec) {
     renderer: "javascript",
     channels,
     parameters,
-    supportedTimelines: ["time", "view", "scroll"],
+    // `'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"],
     supportedActivations: ["manual", "load", "enter"],
     defaultActivation: "load",
     perfClass,
@@ -2847,19 +3565,17 @@ function writeProgress(ctx, progress) {
 }
 function preparePin(el, params, ctx) {
   const node = el;
-  ctx.style.set("position", "sticky");
-  ctx.style.set("top", params.text("offset", "0px"));
-  const removeSpacer = params.is("spacer") ? insertSpacer(node, params.text("distance"), ctx) : null;
+  const { dispose: unstick } = installSticky(node, params, ctx);
   const tracked = node.parentElement ?? el;
-  const untrack = trackProgress(tracked, ctx, { distance: params.text("distance") }, (progress) => {
+  const untrack = trackProgress(tracked, ctx, { distance: params.text("distance"), stickyEl: node }, (progress) => {
     writeProgress(ctx, progress);
     el.setAttribute("data-kui-pinned", progress > 0 && progress < 1 ? "true" : "false");
   });
-  return () => {
+  return continuousSetup(() => {
     untrack();
-    removeSpacer?.();
+    unstick();
     el.removeAttribute("data-kui-pinned");
-  };
+  });
 }
 function insertSpacer(node, distance2, ctx) {
   const spacer = ctx.doc.createElement("div");
@@ -2869,34 +3585,81 @@ function insertSpacer(node, distance2, ctx) {
   spacer.style.pointerEvents = "none";
   node.after(spacer);
   ctx.invalidate();
-  return () => {
-    spacer.remove();
-    ctx.invalidate();
+  return {
+    spacer,
+    remove: () => {
+      spacer.remove();
+      ctx.invalidate();
+    }
   };
 }
 function prepareProgress(el, params, ctx) {
   const steps = Math.max(0, Math.round(params.num("steps", 0)));
+  const selector = resolveTarget(params.text("target"), ctx, "scrollytelling-step");
+  const marker = createStepMarker(() => ctx.doc.querySelectorAll(selector));
+  const self = createAttributeLedger(el);
+  let lastIndex;
   const untrack = trackProgress(el, ctx, { distance: params.text("distance") }, (progress) => {
     writeProgress(ctx, progress);
-    if (steps > 0) {
-      const index = Math.min(steps - 1, Math.floor(progress * steps));
-      el.setAttribute("data-kui-step", String(index));
-    }
+    if (steps === 0) return;
+    const index = Math.min(steps - 1, Math.floor(progress * steps));
+    if (index === lastIndex) return;
+    lastIndex = index;
+    self.set("data-kui-step", String(index));
+    ctx.style.set("--kui-step", String(index));
+    if (selector) marker.mark(index);
   });
-  return () => {
+  return continuousSetup(() => {
     untrack();
-    el.removeAttribute("data-kui-step");
-  };
+    self.restore();
+    marker.restore();
+  });
 }
 function prepareHorizontal(el, params, ctx) {
-  const node = el;
+  const selector = resolveTarget(params.text("target"), ctx, "horizontal-scroll");
+  if (!selector) return prepareBareTrack(el, params, ctx);
+  const track = el.querySelector(selector);
+  if (!track) {
+    ctx.warn(`horizontal-scroll target "${selector}" matched nothing inside this element`);
+    return () => {
+    };
+  }
+  return prepareManagedTrack(el, track, params, ctx);
+}
+function prepareBareTrack(node, params, ctx) {
   const authored = params.text("travel", "auto");
   const travel = createMeasureCache(() => trackTravel(node, authored, node.ownerDocument));
-  const untrack = trackProgress(el, ctx, { distance: params.text("distance") }, (progress, frame) => {
-    ctx.style.set("translate", `${-progress * travel.read(frame.epoch)}px 0`);
+  return continuousSetup(
+    trackProgress(node, ctx, { distance: params.text("distance") }, (progress, frame) => {
+      ctx.style.set("translate", `${-progress * travel.read(frame.epoch)}px 0`);
+      writeProgress(ctx, progress);
+    })
+  );
+}
+function prepareManagedTrack(host, track, params, ctx) {
+  const offsetTop = params.text("offset-top", "var(--kui-pin-offset, 0px)");
+  ctx.style.set("position", "sticky");
+  ctx.style.set("top", offsetTop);
+  ctx.style.set("height", `calc(100vh - ${offsetTop})`);
+  ctx.style.set("overflow", "hidden");
+  ctx.style.set("display", "grid");
+  ctx.style.set("align-content", "center");
+  const { remove: removeSpacer } = insertSpacer(host, params.text("distance"), ctx);
+  const rail = createStyleLedger(track);
+  rail.set("display", "flex");
+  rail.set("width", "max-content");
+  const authored = params.text("travel", "auto");
+  const travel = createMeasureCache(() => trackTravel(track, authored, track.ownerDocument));
+  const tracked = host.parentElement ?? host;
+  const untrack = trackProgress(tracked, ctx, { distance: params.text("distance"), stickyEl: host }, (progress, frame) => {
+    rail.set("translate", `${-progress * travel.read(frame.epoch)}px 0`);
     writeProgress(ctx, progress);
   });
-  return untrack;
+  return continuousSetup(() => {
+    untrack();
+    rail.restore();
+    removeSpacer();
+  });
 }
 function trackTravel(node, authored, doc) {
   if (authored && authored !== "auto") return toPixels(authored, ABSOLUTE_BASIS, 0);
@@ -2906,11 +3669,41 @@ function trackTravel(node, authored, doc) {
   return Math.max(0, node.scrollWidth - viewportWidth);
 }
 function prepareMediaScrub(el, params, ctx) {
+  const managed = params.is("spacer") ? installSticky(el, params, ctx) : null;
+  const contentAnchor = managed?.spacer ?? void 0;
+  const stickyEl = managed ? el : void 0;
+  const selector = resolveTarget(params.text("target"), ctx, "media-scrub");
+  const scrub = selector ? prepareTargetScrub(el, params, ctx, { selector, contentAnchor, stickyEl }) : prepareSrcScrub(el, params, ctx, { contentAnchor, stickyEl });
+  return continuousSetup(() => {
+    scrub();
+    managed?.dispose();
+  });
+}
+function prepareTargetScrub(el, params, ctx, authored) {
+  const { selector, contentAnchor, stickyEl } = authored;
+  const marker = createStepMarker(() => ctx.doc.querySelectorAll(selector));
+  const frames = Math.max(1, ctx.doc.querySelectorAll(selector).length);
+  let lastIndex;
+  const untrack = trackProgress(el, ctx, { distance: params.text("distance"), contentAnchor, stickyEl }, (progress) => {
+    writeProgress(ctx, progress);
+    const index = Math.min(frames - 1, Math.floor(progress * frames));
+    if (index === lastIndex) return;
+    lastIndex = index;
+    marker.mark(index);
+  });
+  marker.mark(0);
+  return () => {
+    untrack();
+    marker.restore();
+  };
+}
+function prepareSrcScrub(el, params, ctx, anchors) {
+  const { contentAnchor, stickyEl } = anchors;
   const frames = Math.max(1, Math.round(params.num("frames", 1)));
   const pattern = mediaSrcPattern(params.text("src"), ctx);
   const media = el;
   let lastIndex = -1;
-  const untrack = trackProgress(el, ctx, { distance: params.text("distance") }, (progress) => {
+  const untrack = trackProgress(el, ctx, { distance: params.text("distance"), contentAnchor, stickyEl }, (progress) => {
     writeProgress(ctx, progress);
     const index = Math.min(frames - 1, Math.floor(progress * frames));
     if (index === lastIndex) return;
@@ -2934,80 +3727,37 @@ function applyFrame(media, write) {
   if (media.tagName !== "IMG") return;
   if (pattern) media.src = pattern.replace("{i}", String(index).padStart(String(frames).length, "0"));
 }
-function prepareScrollSpy(el, params, ctx) {
-  const selector = spyTarget(params.text("target"), ctx);
-  const links = /* @__PURE__ */ new Map();
-  const self = createAttributeLedger(el);
-  let last;
-  const untrack = trackProgress(el, ctx, { distance: params.text("distance") }, (progress) => {
-    const active = progress > 0 && progress < 1;
-    if (active === last) return;
-    last = active;
-    self.set("data-kui-active", String(active));
-    if (selector) markLinks(ctx.doc, selector, active, links);
-  });
+function prepareSmoothScroll(el, params, ctx) {
+  ctx.style.set("scroll-behavior", params.text("behavior", "smooth"));
   return () => {
-    untrack();
-    self.restore();
-    for (const ledger of links.values()) ledger.restore();
   };
 }
-function spyTarget(selector, ctx) {
-  if (!selector) return selector;
-  const breadth = selectorBreadth(selector, ctx.doc);
-  if (breadth === "invalid") {
-    ctx.warn(`scroll-spy target "${selector}" is not a valid selector and will be ignored`);
-    return "";
-  }
-  if (breadth === "document-wide") {
-    ctx.warn(`scroll-spy target "${selector}" matches the whole document and will be ignored`);
-    return "";
-  }
-  return selector;
-}
-function selectorBreadth(selector, doc) {
-  try {
-    if (doc.documentElement.matches(selector)) return "document-wide";
-    if (doc.body?.matches(selector)) return "document-wide";
-    return "ok";
-  } catch {
-    return "invalid";
-  }
-}
-function markLinks(doc, selector, active, links) {
-  for (const link of doc.querySelectorAll(selector)) {
-    let ledger = links.get(link);
-    if (!ledger) {
-      ledger = createAttributeLedger(link);
-      links.set(link, ledger);
-    }
-    ledger.set("data-kui-active", String(active));
-  }
-}
 function prepareSnap(el, params, ctx) {
-  ctx.style.set(
-    "scroll-snap-type",
-    `${params.is("axis", "x") ? "x" : "y"} ${params.text("strictness", "mandatory")}`
-  );
-  const childLedgers = [...el.children].map((child) => createStyleLedger(child));
+  const axis = params.is("axis", "x") ? "x" : "y";
+  ctx.style.set("scroll-snap-type", `${axis} ${params.text("strictness", "mandatory")}`);
+  const selector = resolveTarget(params.text("target"), ctx, "scroll-snap");
+  const items = selector ? [...el.querySelectorAll(selector)] : [...el.children];
+  if (selector && items.length === 0) {
+    ctx.warn(`scroll-snap target "${selector}" matched nothing inside this element`);
+  }
+  if (selector) installSnapContainer(axis, ctx);
+  const childLedgers = items.map((child) => createStyleLedger(child));
   for (const ledger of childLedgers) ledger.set("scroll-snap-align", params.text("align", "start"));
   return () => {
     for (const ledger of childLedgers) ledger.restore();
   };
 }
+function installSnapContainer(axis, ctx) {
+  ctx.style.set(axis === "x" ? "overflow-x" : "overflow-y", "auto");
+  if (axis === "x") ctx.style.set("display", "flex");
+}
 var SCROLL_PRIMITIVES = [
   scrollPrimitive({
     id: "pin",
     channels: ["layout", "progress"],
     parameters: {
       ...distanceParam,
-      offset: { type: "length", default: "0px", cssProperty: "--kui-offset" },
-      spacer: {
-        type: "keyword",
-        default: "false",
-        cssProperty: "--kui-spacer",
-        values: ["true", "false"]
-      }
+      ...stickyParams
     },
     prepare: deferPrepare(preparePin),
     perfClass: "layout"
@@ -3017,7 +3767,10 @@ var SCROLL_PRIMITIVES = [
     channels: ["progress"],
     parameters: {
       ...distanceParam,
-      steps: { type: "number", default: "0", cssProperty: "--kui-steps" }
+      steps: { type: "number", default: "0", cssProperty: "--kui-steps" },
+      // Same name, same shape and the same validation as scroll-spy's: one `target:` convention
+      // across the library rather than a second word for "the elements this effect marks".
+      target: { type: "text", default: "", cssProperty: "--kui-target" }
     },
     prepare: deferPrepare(prepareProgress)
   }),
@@ -3026,7 +3779,16 @@ var SCROLL_PRIMITIVES = [
     channels: ["translate", "progress"],
     parameters: {
       ...distanceParam,
-      travel: { type: "text", default: "auto", cssProperty: "--kui-travel" }
+      travel: { type: "text", default: "auto", cssProperty: "--kui-travel" },
+      // Same name, same shape and the same validation as scroll-spy's and media-scrub's: one
+      // `target:` convention across the library. Naming the row that moves is also what opts this
+      // primitive into owning the stage, the sticky window and the row's layout itself.
+      target: { type: "text", default: "", cssProperty: "--kui-target" },
+      "offset-top": {
+        type: "length",
+        default: "var(--kui-pin-offset, 0px)",
+        cssProperty: "--kui-offset-top"
+      }
     },
     prepare: deferPrepare(prepareHorizontal)
   }),
@@ -3035,8 +3797,13 @@ var SCROLL_PRIMITIVES = [
     channels: ["media", "progress"],
     parameters: {
       ...distanceParam,
+      // A scrub is a hold, so it needs the same two knobs a pin does. Declaring them here is what
+      // lets `sequence-scrub` become one attribute with no wrapper at all.
+      ...stickyParams,
       frames: { type: "number", default: "1", cssProperty: "--kui-frames" },
-      src: { type: "text", default: "", cssProperty: "--kui-src" }
+      src: { type: "text", default: "", cssProperty: "--kui-src" },
+      // The preferred form. `frames:`/`src:` remain for sequences too long to author as tags.
+      target: { type: "text", default: "", cssProperty: "--kui-target" }
     },
     prepare: deferPrepare(prepareMediaScrub),
     perfClass: "paint"
@@ -3045,11 +3812,30 @@ var SCROLL_PRIMITIVES = [
     id: "scroll-spy",
     channels: ["state"],
     parameters: {
+      // `distance`: the per-section form only. `offset-top`: the container form only. Each is a
+      // no-op — warned, not silent — in the other; see `prepareScrollSpySingle` and
+      // `prepareScrollSpyContainer`.
       ...distanceParam,
-      target: { type: "text", default: "", cssProperty: "--kui-target" }
+      // Same name and meaning in both forms: the link(s) this instance marks. Per-section, the
+      // one link this section names; with `sections:`, every link `target:` matches, each paired
+      // to its own section by `href`. See `prepareScrollSpyContainer`.
+      target: { type: "text", default: "", cssProperty: "--kui-target" },
+      // Presence, not value, selects the container form: authoring this at all switches
+      // `prepareScrollSpy` from one-section-per-instance to one-instance-on-the-shared-ancestor.
+      sections: { type: "text", default: "", cssProperty: "--kui-sections" },
+      "offset-top": { type: "length", default: "0px", cssProperty: "--kui-offset-top" }
     },
     prepare: deferPrepare(prepareScrollSpy)
   }),
+  scrollPrimitive({
+    id: "smooth-scroll",
+    channels: ["layout"],
+    parameters: {
+      behavior: { type: "keyword", default: "smooth", cssProperty: "--kui-scroll-behavior", values: ["smooth", "auto"] }
+    },
+    prepare: deferPrepare(prepareSmoothScroll),
+    perfClass: "layout"
+  }),
   scrollPrimitive({
     id: "scroll-snap",
     channels: ["layout"],
@@ -3066,7 +3852,11 @@ var SCROLL_PRIMITIVES = [
         default: "start",
         cssProperty: "--kui-snap-align",
         values: ["start", "center", "end"]
-      }
+      },
+      // Names the snap items. Also what opts this primitive into owning the scroll container
+      // itself — see `installSnapContainer`. Without it, the direct children are the items and
+      // the page keeps its own `overflow`, exactly as before.
+      target: { type: "text", default: "", cssProperty: "--kui-target" }
     },
     prepare: deferPrepare(prepareSnap),
     perfClass: "layout"
@@ -3089,11 +3879,28 @@ var SCROLL_PRESETS = [
   // --- travel ------------------------------------------------------------------------------
   { name: "horizontal-scroll", primitive: "horizontal-track" },
   // --- media -------------------------------------------------------------------------------
-  { name: "sequence-scrub", primitive: "media-scrub" },
+  /*
+   * `spacer:true` is what deletes the `.scrub-stage` wrapper a page used to hand-write.
+   *
+   * It could not be switched on until the tracker stopped measuring against the parent. A scrub
+   * makes itself sticky, and `geometrySource` escapes a sticky subtree by taking its parent — so
+   * with the wrapper gone the scrub was measured against whatever section contained it. Measured
+   * on `demo/scroll.html`: the parent started 926px above the scrub against a 1817px distance, so
+   * progress reached 51% before the element had even stuck and half the sequence played off
+   * screen. The wrapper was not ceremony; it was the tight box that made the parent honest.
+   *
+   * `trackProgress`'s `contentAnchor` is the fix. Progress is read from the spacer, which the
+   * library inserts, is exactly `distance` tall, is never sticky, and moves with the content — so
+   * there is no wrapper to write and nothing to disagree with.
+   *
+   * `video-scrub` stays off: a video positioned by the page is not asking the library for a box.
+   */
+  { name: "sequence-scrub", primitive: "media-scrub", params: { spacer: "true" } },
   { name: "video-scrub", primitive: "media-scrub" },
   // --- navigation --------------------------------------------------------------------------
   { name: "scroll-spy", primitive: "scroll-spy" },
   // --- native CSS passthroughs ---------------------------------------------------------------
+  { name: "smooth-scroll-to", primitive: "smooth-scroll" },
   { name: "scroll-snap-x", primitive: "scroll-snap", params: { axis: "x" } },
   { name: "scroll-snap-y", primitive: "scroll-snap", params: { axis: "y" } }
 ];
@@ -3108,11 +3915,16 @@ var COMMAND = /([mlhvcz])|(-?(?:\d+(?:\.\d+)?|\.\d+))/gi;
 var UNSUPPORTED = /[AaSsQqTt]/;
 function parsePath(d) {
   if (UNSUPPORTED.test(d)) {
-    return { segments: [], reason: "arc and shorthand commands (A S Q T) are not supported" };
+    return {
+      segments: [],
+      subpaths: [],
+      reason: "arc and shorthand commands (A S Q T) are not supported"
+    };
   }
   const tokens = [...d.matchAll(COMMAND)].map((m) => m[1] ?? m[2]);
   const state = {
-    segments: [],
+    subpaths: [],
+    open: void 0,
     current: { x: 0, y: 0 },
     start: { x: 0, y: 0 },
     command: ""
@@ -3126,18 +3938,33 @@ function parsePath(d) {
       index++;
       continue;
     }
-    if (!state.command) return { segments: [], reason: "path must start with a command letter" };
+    if (!state.command) {
+      return { segments: [], subpaths: [], reason: "path must start with a command letter" };
+    }
     index = consume(tokens, index, state);
   }
-  if (state.segments.length === 0) return { segments: [], reason: "no drawable segments" };
-  return { segments: state.segments };
+  if (state.subpaths.length === 0) {
+    return { segments: [], subpaths: [], reason: "no drawable segments" };
+  }
+  return { segments: state.subpaths.flatMap((sub) => sub.segments), subpaths: state.subpaths };
+}
+function pushSegment(state, segment) {
+  if (!state.open) {
+    state.open = { segments: [], closed: false };
+    state.subpaths.push(state.open);
+  }
+  state.open.segments.push(segment);
 }
 var ARITY = { m: 2, l: 2, h: 1, v: 1, c: 6, z: 0 };
 function closeSubpath(state) {
-  const { current, start } = state;
-  if (Math.abs(current.x - start.x) < 1e-6 && Math.abs(current.y - start.y) < 1e-6) return;
-  state.segments.push(lineToCubic(current, start));
+  const { current, start, open } = state;
+  if (!open) return;
+  if (Math.abs(current.x - start.x) >= 1e-6 || Math.abs(current.y - start.y) >= 1e-6) {
+    open.segments.push(lineToCubic(current, start));
+  }
+  open.closed = true;
   state.current = { ...start };
+  state.open = void 0;
 }
 function consume(tokens, index, state) {
   const key = state.command.toLowerCase();
@@ -3149,10 +3976,11 @@ function consume(tokens, index, state) {
   if (key === "m") {
     state.current = next;
     state.start = next;
+    state.open = void 0;
     state.command = relative ? "l" : "L";
     return index + arity;
   }
-  state.segments.push(straightOrCubic({ key, args, from: state.current, relative }, next));
+  pushSegment(state, straightOrCubic({ key, args, from: state.current, relative }, next));
   state.current = next;
   return index + arity;
 }
@@ -3215,34 +4043,78 @@ function normaliseCount(segments, target) {
 function chordLength(segment) {
   return Math.hypot(segment.to.x - segment.from.x, segment.to.y - segment.from.y);
 }
-function toPathData(segments) {
-  if (segments.length === 0) return "";
-  const head = segments[0];
-  const parts = [`M${round(head.from.x)},${round(head.from.y)}`];
-  for (const s of segments) {
-    parts.push(
-      `C${round(s.c1.x)},${round(s.c1.y)} ${round(s.c2.x)},${round(s.c2.y)} ${round(s.to.x)},${round(s.to.y)}`
-    );
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+function subpathsToPathData(subpaths) {
+  const parts = [];
+  for (const sub of subpaths) {
+    const head = sub.segments[0];
+    parts.push(`M${round(head.from.x)},${round(head.from.y)}`);
+    for (const s of sub.segments) {
+      parts.push(
+        `C${round(s.c1.x)},${round(s.c1.y)} ${round(s.c2.x)},${round(s.c2.y)} ${round(s.to.x)},${round(s.to.y)}`
+      );
+    }
+    if (sub.closed) parts.push("Z");
   }
   return parts.join(" ");
 }
-function round(value) {
-  return Math.round(value * 100) / 100;
+function centroidOf(subpath) {
+  let x = 0;
+  let y = 0;
+  for (const s of subpath.segments) {
+    x += s.from.x;
+    y += s.from.y;
+  }
+  return { x: x / subpath.segments.length, y: y / subpath.segments.length };
+}
+function collapsedLike(partner) {
+  const at = centroidOf(partner);
+  return {
+    segments: partner.segments.map(() => ({
+      from: { ...at },
+      c1: { ...at },
+      c2: { ...at },
+      to: { ...at }
+    })),
+    closed: partner.closed
+  };
+}
+function normaliseSubpaths(a, b) {
+  const count = Math.max(a.length, b.length);
+  const from = [];
+  const to = [];
+  for (let i = 0; i < count; i++) {
+    const left = a[i] ?? collapsedLike(b[i]);
+    const right = b[i] ?? collapsedLike(a[i]);
+    const target = Math.max(left.segments.length, right.segments.length);
+    const closed = left.closed && right.closed;
+    from.push({ segments: normaliseCount(left.segments, target), closed });
+    to.push({ segments: normaliseCount(right.segments, target), closed });
+  }
+  return { from, to };
 }
 function createMorph(fromPath, toPath) {
   const a = parsePath(fromPath);
   const b = parsePath(toPath);
   if (a.reason) return { reason: `start path: ${a.reason}` };
   if (b.reason) return { reason: `end path: ${b.reason}` };
-  const count = Math.max(a.segments.length, b.segments.length);
-  const from = normaliseCount(a.segments, count);
-  const to = normaliseCount(b.segments, count);
+  const { from, to } = normaliseSubpaths(a.subpaths, b.subpaths);
+  const count = from.reduce((total, sub) => total + sub.segments.length, 0);
   return {
     morph: {
       segmentCount: count,
       at(t) {
         const clamped = Math.min(1, Math.max(0, t));
-        return toPathData(from.map((segment, i) => lerpCubic(segment, to[i], clamped)));
+        return subpathsToPathData(
+          from.map((sub, i) => ({
+            segments: sub.segments.map(
+              (segment, j) => lerpCubic(segment, to[i].segments[j], clamped)
+            ),
+            closed: sub.closed
+          }))
+        );
       }
     }
   };
@@ -3299,6 +4171,35 @@ function prepareMorph(el, params, ctx) {
     path.setAttribute("d", startPath);
   };
 }
+var PATH_DRAW_PRIMITIVE = cssPrimitive("path-draw", [CHANNEL.stroke], {
+  parameters: {
+    length: { type: "number", default: "100", cssProperty: "--kui-path-length", finite: true }
+  }
+});
+var SHAPE_FILL_PRIMITIVE = cssPrimitive("shape-fill", [CHANNEL.clip]);
+var BAR_GROW_PRIMITIVE = cssPrimitive("bar-grow", [CHANNEL.scale], {
+  parameters: { from: { type: "number", default: "0", cssProperty: "--kui-bar-from" } }
+});
+var LOGO_BUILD_PRIMITIVE = cssPrimitive("logo-assemble", [
+  CHANNEL.opacity,
+  CHANNEL.scale,
+  CHANNEL.rotate
+]);
+var ICON_TOGGLE_PRIMITIVE = {
+  id: "icon-toggle",
+  renderer: "javascript",
+  channels: [CHANNEL.translate, CHANNEL.rotate, CHANNEL.scale, CHANNEL.opacity, CHANNEL.clip],
+  parameters: {
+    duration: { type: "time", default: "260ms", cssProperty: "--kui-duration" },
+    ease: { type: "easing", default: "ease-out", cssProperty: "--kui-ease" }
+  },
+  supportedTimelines: ["time"],
+  supportedActivations: ["load"],
+  defaultActivation: "load",
+  perfClass: "compositor",
+  reducedMotion: "disable",
+  prepare: () => inertInstance()
+};
 var SVG_PRIMITIVES = [
   {
     id: "path-morph",
@@ -3318,19 +4219,77 @@ var SVG_PRIMITIVES = [
     perfClass: "paint",
     reducedMotion: "disable",
     prepare: deferPrepare(prepareMorph)
-  }
+  },
+  PATH_DRAW_PRIMITIVE,
+  SHAPE_FILL_PRIMITIVE,
+  BAR_GROW_PRIMITIVE,
+  LOGO_BUILD_PRIMITIVE,
+  ICON_TOGGLE_PRIMITIVE
 ];
 var SVG_PRESETS = [
   { name: "icon-morph", primitive: "path-morph" },
-  { name: "blob-morph", primitive: "path-morph", params: { duration: "800ms" } }
+  { name: "blob-morph", primitive: "path-morph", params: { duration: "800ms" } },
+  // Stroke draws. One keyframe block each rather than one shared block, matching the
+  // progress-ring/gauge-sweep/donut-sweep/sparkline-draw group in numbers.ts: identical bodies
+  // today, but each name is free to diverge and a consumer can restyle one without the others.
+  { name: "draw-stroke", primitive: "path-draw", keyframes: "kui-draw-stroke", params: { duration: "800ms", ease: "ease-in-out" } },
+  { name: "draw-signature", primitive: "path-draw", keyframes: "kui-draw-signature", params: { duration: "1600ms", ease: "ease-in-out" } },
+  { name: "draw-underline", primitive: "path-draw", keyframes: "kui-draw-underline", params: { duration: "420ms" } },
+  { name: "checkmark-draw", primitive: "path-draw", keyframes: "kui-checkmark-draw", params: { duration: "320ms" } },
+  { name: "cross-draw", primitive: "path-draw", keyframes: "kui-cross-draw", params: { duration: "260ms" } },
+  { name: "chart-line-draw", primitive: "path-draw", keyframes: "kui-chart-line-draw", params: { duration: "1200ms", ease: "ease-in-out" } },
+  { name: "gradient-stroke", primitive: "path-draw", keyframes: "kui-gradient-stroke", params: { duration: "2400ms", ease: "ease-in-out" } },
+  // Fills.
+  { name: "heart-fill", primitive: "shape-fill", keyframes: "kui-heart-fill", params: { duration: "420ms" } },
+  { name: "bookmark-fill", primitive: "shape-fill", keyframes: "kui-bookmark-fill", params: { duration: "360ms" } },
+  { name: "chart-area-fill", primitive: "shape-fill", keyframes: "kui-chart-area-fill", params: { duration: "900ms" } },
+  // `cloak: true`: `kui-chart-bar-grow`'s `from { scale: 1 0 }` (svg.css) is a zero-height box
+  // while paused, not just an invisible one — so it occupies no space in layout for the whole
+  // wait. Same defect `fold-panel` has, and the same fix shape: see svg.css's
+  // `[data-kui-fx~='chart-bar-grow'][data-kui-state='ready']` rule.
+  {
+    name: "chart-bar-grow",
+    primitive: "bar-grow",
+    keyframes: "kui-chart-bar-grow",
+    params: { duration: "700ms", ease: "back-out" },
+    cloak: true
+  },
+  { name: "logo-build", primitive: "logo-assemble", keyframes: "kui-logo-build", params: { duration: "520ms", ease: "back-out" } },
+  // Icon toggles — no `keyframes`, because their motion is a CSS transition in svg.css keyed off
+  // aria state, not a compiled animation. Same shape as forms.ts's native-state presets.
+  { name: "hamburger-to-x", primitive: "icon-toggle" },
+  { name: "play-to-pause", primitive: "icon-toggle" },
+  { name: "plus-to-minus", primitive: "icon-toggle" }
 ];
 function registerSvg(registry) {
   return registry.registerPrimitives(SVG_PRIMITIVES).registerPresets(SVG_PRESETS);
 }
 
 // src/effects/three-d/index.ts
+var CARD_TOGGLE_PRIMITIVE = {
+  id: "card-toggle",
+  renderer: "javascript",
+  channels: [CHANNEL.rotate],
+  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" }
+  },
+  supportedTimelines: ["time"],
+  supportedActivations: ["load"],
+  defaultActivation: "load",
+  perfClass: "compositor",
+  reducedMotion: "disable",
+  prepare: () => inertInstance()
+};
 var THREE_D_PRIMITIVES = [
-  cssPrimitive("flip-face", [CHANNEL.rotate], {
+  // `skew`, not `rotate`: the keyframes in three-d.css write `transform: perspective(...)
+  // rotateX/Y(...)`, not the individual `rotate:` property — `perspective` only creates depth for
+  // an element's *children*, so giving one of these effects its own depth means reaching for the
+  // `perspective()` transform *function*, which only exists inside the `transform` shorthand.
+  // `CHANNEL.skew` is this catalog's name for "claims the whole `transform` shorthand"; see the
+  // comment on it in `core/types.ts`.
+  cssPrimitive("flip-face", [CHANNEL.skew], {
     parameters: {
       angle: { type: "angle", default: "180deg", cssProperty: "--kui-from-angle" },
       perspective: { type: "length", default: "1200px", cssProperty: "--kui-perspective" }
@@ -3340,12 +4299,19 @@ var THREE_D_PRIMITIVES = [
     parameters: { distance: { type: "length", default: "40px", cssProperty: "--kui-distance" } }
   }),
   cssPrimitive("wipe", [CHANNEL.clip]),
-  cssPrimitive("bar", [CHANNEL.scale])
+  // `from` gives `loading-bar` a real knob on its start scale — it had none before, unlike
+  // `flip-face`'s `angle:` two rows up. `--kui-bar-from` is also what the fold-panel-style
+  // `[data-kui-fx~='loading-bar'][data-kui-state='ready']` gate neutralizes in three-d.css; see
+  // that rule's comment for the on:enter fix this parameter doubles as.
+  cssPrimitive("bar", [CHANNEL.scale], {
+    parameters: { from: { type: "number", default: "0", cssProperty: "--kui-bar-from" } }
+  }),
+  CARD_TOGGLE_PRIMITIVE
 ];
 var THREE_D_PRESETS = [
   // --- 3D & perspective ---
-  { name: "card-flip-y", primitive: "flip-face", keyframes: "kui-card-flip-y" },
-  { name: "card-flip-x", primitive: "flip-face", keyframes: "kui-card-flip-x" },
+  { name: "card-flip-y", primitive: "flip-face", keyframes: "kui-card-flip-y", cloak: true },
+  { name: "card-flip-x", primitive: "flip-face", keyframes: "kui-card-flip-x", cloak: true },
   { name: "cube-rotate", primitive: "flip-face", keyframes: "kui-cube-rotate", params: { angle: "90deg" } },
   {
     name: "book-page-turn",
@@ -3353,17 +4319,32 @@ var THREE_D_PRESETS = [
     keyframes: "kui-book-page-turn",
     params: { angle: "-160deg", duration: "900ms" }
   },
+  // `cloak: true`, unlike its `flip-face` siblings above: those are `to`-only keyframes, so their
+  // paused/waiting box is the ordinary, untransformed rest state. `fold-panel` is `from`-only —
+  // its `rotateX(-90deg)` (three-d.css) *is* the paused box, edge-on and zero-height, so it holds
+  // no space in layout for the whole wait; see the
+  // `[data-kui-fx~='fold-panel'][data-kui-state='ready']` rule in three-d.css for the other half
+  // of that fix. `cloak` only ever hid the pre-JS flash, not this, but adding it here keeps the
+  // pre-JS and post-JS "ready" appearances the same (invisible) instead of trading one flash for
+  // the other.
   {
     name: "fold-panel",
     primitive: "flip-face",
     keyframes: "kui-fold-panel",
-    params: { angle: "-90deg" }
+    params: { angle: "-90deg" },
+    cloak: true
   },
   // --- page transitions ---
   { name: "page-fade", primitive: "page-reveal", keyframes: "kui-page-fade" },
   { name: "page-slide", primitive: "page-reveal", keyframes: "kui-page-slide" },
   { name: "curtain-wipe", primitive: "wipe", keyframes: "kui-curtain-wipe", params: { duration: "800ms" } },
-  { name: "loading-bar", primitive: "bar", keyframes: "kui-loading-bar" }
+  // `cloak: true` for the same reason as `fold-panel`: `kui-loading-bar`'s `from { scale: 0 1 }`
+  // (three-d.css) is a zero-width box, not just an invisible one — see that file's
+  // `[data-kui-fx~='loading-bar'][data-kui-state='ready']` rule.
+  { name: "loading-bar", primitive: "bar", keyframes: "kui-loading-bar", cloak: true },
+  // No `keyframes`: its motion is a CSS transition in three-d.css keyed off the control's
+  // aria-pressed, not a compiled animation. Same shape as the icon toggles in svg.ts.
+  { name: "flip-card", primitive: "card-toggle" }
 ];
 function registerThreeD(registry) {
   return registry.registerPrimitives(THREE_D_PRIMITIVES).registerPresets(THREE_D_PRESETS);