@ericrisco/rsc 3.1.3 → 3.1.4

package/skills/scroll-film/assets/scrub-engine.js

@@ -0,0 +1,352 @@
+/*!
+ * scroll-film scrub engine — part of rsc-harness (MIT).
+ * Scroll position becomes the playhead of a chain of pre-rendered clips.
+ * Vanilla JS, no dependencies, no framework. API and wiring: ../references/engine.md
+ */
+(function (root, factory) {
+  var api = factory();
+  if (typeof module === 'object' && module && module.exports) module.exports = api;
+  if (root) root.ScrollFilm = api;
+})(typeof window !== 'undefined' ? window : this, function () {
+  'use strict';
+
+  var TOUCH_QUERY = '(hover: none) and (pointer: coarse)';
+
+  function clamp(x, lo, hi) { return Math.min(hi, Math.max(lo, x)); }
+  function smoothstep(x) { x = clamp(x, 0, 1); return x * x * (3 - 2 * x); }
+
+  // Remaps a shot's progress so the camera slows in the middle (where the copy sits) and
+  // hurries near the seams. f(0)=0 and f(1)=1 for every strength, so seam frames never move.
+  // Monotone up to strength 1, which is a momentary stop at the midpoint.
+  function hold(x, strength) {
+    var s = clamp(strength || 0, 0, 1);
+    if (!s) return x;
+    return x + (s * Math.sin(2 * Math.PI * x)) / (2 * Math.PI);
+  }
+
+  // Lays the shots end to end on the scroll axis. lengths are in viewport heights.
+  function planBands(lengths, viewport) {
+    var at = 0;
+    return lengths.map(function (len) {
+      var band = { start: at, end: at + len * viewport };
+      at = band.end;
+      return band;
+    });
+  }
+
+  // A shot dissolves in over `fade` px centred on its start seam, on top of its predecessor,
+  // and stays opaque underneath its successor until that one is fully in. So the stack never
+  // shows the page through it, and the dissolve blends the two frames the seam handed off.
+  function shotOpacity(i, y, bands, fade) {
+    var band = bands[i];
+    var half = fade / 2;
+    var enter = 1;
+    if (i > 0) enter = fade > 0 ? smoothstep((y - (band.start - half)) / fade) : (y >= band.start ? 1 : 0);
+    var leave = i === bands.length - 1 || y < band.end + half ? 1 : 0;
+    return Math.min(enter, leave);
+  }
+
+  function mount(container, options) {
+    var opts = options || {};
+    var shots = (opts.shots || []).filter(Boolean);
+    if (!container || !shots.length) throw new Error('scroll-film: mount needs a container and at least one shot');
+
+    var doc = container.ownerDocument;
+    var win = doc.defaultView;
+    var touch = win.matchMedia(TOUCH_QUERY).matches;
+    var phone = touch || win.innerWidth <= (opts.phoneWidth || 860);
+    var reduce = win.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    var saveData = !!(win.navigator.connection && win.navigator.connection.saveData);
+    var stillsOnly = !!opts.stillsOnly || reduce || saveData;
+    var fadeVh = opts.fade == null ? 0.1 : opts.fade;
+    var preloadVh = opts.preload == null ? 1.5 : opts.preload;
+    var ease = opts.ease == null ? 0.2 : clamp(opts.ease, 0.01, 1);
+    var minStep = phone ? 1 / 24 : 1 / 120; // seconds; a phone never seeks for less than a frame
+
+    injectStyles(doc);
+    container.classList.add('sf-root');
+    var stage = element(doc, 'div', 'sf-stage');
+    var layer = element(doc, 'div', 'sf-shots');
+    layer.setAttribute('aria-hidden', 'true');
+    var overlay = element(doc, 'div', 'sf-overlay');
+    stage.appendChild(layer);
+    stage.appendChild(overlay);
+    var track = element(doc, 'div', 'sf-track');
+    container.insertBefore(stage, container.firstChild);
+    container.appendChild(track);
+
+    var items = shots.map(function (shot, i) {
+      var node = element(doc, 'div', 'sf-shot');
+      node.style.zIndex = String(i + 1);
+      var img = element(doc, 'img', 'sf-poster');
+      img.alt = '';
+      img.decoding = 'async';
+      node.appendChild(img);
+      layer.appendChild(node);
+      return {
+        shot: shot,
+        section: shot.section == null ? i : shot.section,
+        node: node,
+        img: img,
+        poster: (phone && shot.posterMobile) || shot.poster || '',
+        src: (phone && shot.srcMobile) || shot.src || '',
+        video: null,
+        url: '',
+        state: 'idle',
+        cur: -1,
+        target: 0,
+        opacity: -1,
+      };
+    });
+    if (items[0].poster) {
+      items[0].img.setAttribute('fetchpriority', 'high');
+      showPoster(items[0]);
+    }
+
+    var aborter = typeof AbortController === 'function' ? new AbortController() : null;
+    var destroyed = false;
+    var raf = 0;
+    var vh = 0;
+    var top = 0;
+    var laidOutWidth = 0;
+    var bands = [];
+    var sections = [];
+    var lastState = '';
+
+    function showPoster(item) {
+      if (item.poster && !item.img.getAttribute('src')) item.img.src = item.poster;
+    }
+
+    function load(item) {
+      if (stillsOnly || item.state !== 'idle' || !item.src) return;
+      item.state = 'loading';
+      // A Blob is always fully seekable. Streaming from a host that ignores byte-range
+      // requests pins video.seekable to [0, 0] and every seek lands on frame 0.
+      win.fetch(item.src, aborter ? { signal: aborter.signal } : undefined)
+        .then(function (res) {
+          if (!res.ok) throw new Error('HTTP ' + res.status);
+          return res.blob();
+        })
+        .then(function (blob) {
+          if (destroyed) return;
+          var video = doc.createElement('video');
+          video.className = 'sf-video';
+          video.muted = true;
+          video.defaultMuted = true;
+          video.playsInline = true;
+          video.preload = 'auto';
+          // The attributes, not just the properties: iOS reads them to allow inline decode.
+          video.setAttribute('muted', '');
+          video.setAttribute('playsinline', '');
+          video.setAttribute('disablepictureinpicture', '');
+          video.setAttribute('disableremoteplayback', '');
+          item.url = win.URL.createObjectURL(blob);
+          video.addEventListener('loadedmetadata', function () { item.state = 'ready'; wake(); });
+          video.addEventListener('seeked', wake);
+          video.src = item.url;
+          item.node.appendChild(video);
+          item.video = video;
+          watchFirstPaint(item);
+          prime(video);
+        })
+        .catch(function () {
+          if (!destroyed) item.state = 'failed'; // the poster stays up: degraded, never blank
+        });
+    }
+
+    // Keep the poster until the video has really painted. iOS reports a seek as done on a
+    // muted video that never played and still shows nothing, so 'seeked' alone is not proof.
+    function watchFirstPaint(item) {
+      var live = function () { item.node.classList.add('is-live'); };
+      if (typeof item.video.requestVideoFrameCallback === 'function') item.video.requestVideoFrameCallback(live);
+      else item.video.addEventListener('seeked', live, { once: true });
+    }
+
+    // A muted play()+pause() unlocks decoding on iOS. Rejected before a user gesture in some
+    // power modes; the first-gesture handler below retries every loaded clip.
+    function prime(video) {
+      var p;
+      try { p = video.play(); } catch (err) { return; }
+      if (p && typeof p.then === 'function') p.then(function () { video.pause(); }, function () {});
+      else video.pause();
+    }
+
+    function dropGestureListeners() {
+      win.removeEventListener('pointerdown', onFirstGesture);
+      win.removeEventListener('touchstart', onFirstGesture);
+    }
+
+    function onFirstGesture() {
+      dropGestureListeners();
+      items.forEach(function (item) { if (item.video) prime(item.video); });
+    }
+
+    function scrollOffset() { return (win.scrollY || win.pageYOffset || 0) - top; }
+
+    function layout() {
+      vh = stage.clientHeight || win.innerHeight;
+      laidOutWidth = win.innerWidth;
+      bands = planBands(items.map(function (item) { return item.shot.length || 1; }), vh);
+      track.style.height = bands[bands.length - 1].end + 'px';
+      top = container.getBoundingClientRect().top + (win.scrollY || win.pageYOffset || 0);
+      sections = [];
+      items.forEach(function (item, i) {
+        var s = sections[item.section];
+        if (!s) sections[item.section] = { start: bands[i].start, end: bands[i].end };
+        else { s.start = Math.min(s.start, bands[i].start); s.end = Math.max(s.end, bands[i].end); }
+      });
+      wake();
+    }
+
+    // Phones fire resize whenever the URL bar slides. Re-laying out on a height-only change
+    // rewrites the track height mid-scroll and the page jumps, so touch only reacts to width.
+    function onResize() {
+      if (touch && win.innerWidth === laidOutWidth) return;
+      layout();
+    }
+
+    function wake() {
+      if (!raf && !destroyed) raf = win.requestAnimationFrame(frame);
+    }
+
+    function frame() {
+      raf = 0;
+      if (destroyed) return;
+      var y = scrollOffset();
+      var fade = fadeVh * vh;
+      var reach = preloadVh * vh;
+      var moving = false;
+
+      for (var i = 0; i < items.length; i++) {
+        var item = items[i];
+        var band = bands[i];
+        var near = y > band.start - reach && y < band.end + reach;
+        if (near) { showPoster(item); load(item); }
+
+        var opacity = shotOpacity(i, y, bands, fade);
+        if (opacity !== item.opacity) {
+          item.opacity = opacity;
+          item.node.style.opacity = String(opacity);
+          item.node.style.visibility = opacity > 0 ? 'visible' : 'hidden';
+        }
+
+        item.target = hold(clamp((y - band.start) / (band.end - band.start), 0, 1), item.shot.hold);
+        if (!near) { item.cur = -1; continue; } // out of reach: snap, don't glide, on return
+        if (item.state !== 'ready') continue;
+
+        var video = item.video;
+        var duration = video.duration;
+        if (!isFinite(duration) || duration <= 0) continue;
+        if (item.cur < 0) item.cur = item.target;
+        else item.cur += (item.target - item.cur) * ease;
+        if (Math.abs(item.target - item.cur) * duration < 0.002) item.cur = item.target;
+        if (item.cur !== item.target) moving = true;
+
+        // One seek in flight per clip. Queuing more while the decoder works is what freezes
+        // a phone on a fast flick; 'seeked' wakes the loop and it takes the latest target.
+        if (video.seeking) { moving = true; continue; }
+        var t = Math.min(item.cur * duration, duration - 0.01);
+        var gap = Math.abs(video.currentTime - t);
+        if (gap >= minStep || (gap > 0.001 && item.cur === item.target)) {
+          try { video.currentTime = t; } catch (err) { /* not seekable yet; next frame retries */ }
+        }
+      }
+
+      report(y);
+      if (moving) wake();
+    }
+
+    function report(y) {
+      if (typeof opts.onChange !== 'function') return;
+      var index = 0;
+      for (var i = 0; i < bands.length; i++) if (y >= bands[i].start) index = i;
+      var section = items[index].section;
+      var span = sections[section];
+      var total = bands[bands.length - 1].end;
+      var state = {
+        shot: index,
+        section: section,
+        sectionProgress: clamp((y - span.start) / (span.end - span.start), 0, 1),
+        progress: clamp(y / total, 0, 1),
+      };
+      var key = [state.shot, state.section, state.sectionProgress.toFixed(4), state.progress.toFixed(4)].join('|');
+      if (key === lastState) return;
+      lastState = key;
+      opts.onChange(state);
+    }
+
+    function jumpTo(section) {
+      var span = sections[section];
+      if (!span) return;
+      win.scrollTo({ top: top + (span.start + span.end) / 2, behavior: reduce ? 'auto' : 'smooth' });
+    }
+
+    function destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      if (raf) win.cancelAnimationFrame(raf);
+      if (aborter) aborter.abort();
+      win.removeEventListener('scroll', wake);
+      win.removeEventListener('resize', onResize);
+      win.removeEventListener('orientationchange', layout);
+      win.removeEventListener('load', layout);
+      dropGestureListeners();
+      items.forEach(function (item) {
+        if (item.video) { item.video.removeAttribute('src'); item.video.load(); }
+        if (item.url) win.URL.revokeObjectURL(item.url);
+      });
+      stage.remove();
+      track.remove();
+      container.classList.remove('sf-root');
+    }
+
+    // Passive, and it only requests a frame: the per-frame work happens in rAF. Hosts that
+    // already own a scroll source (GSAP ScrollTrigger, motion's useScroll) pass listen:false
+    // and call update() from it instead.
+    if (opts.listen !== false) win.addEventListener('scroll', wake, { passive: true });
+    win.addEventListener('resize', onResize);
+    win.addEventListener('orientationchange', layout);
+    win.addEventListener('load', layout);
+    win.addEventListener('pointerdown', onFirstGesture, { passive: true });
+    win.addEventListener('touchstart', onFirstGesture, { passive: true });
+    layout();
+
+    return {
+      stage: stage,
+      overlay: overlay,
+      stillsOnly: stillsOnly,
+      update: wake,
+      relayout: layout,
+      jumpTo: jumpTo,
+      destroy: destroy,
+    };
+  }
+
+  function element(doc, tag, className) {
+    var node = doc.createElement(tag);
+    node.className = className;
+    return node;
+  }
+
+  // Layered, so any unlayered page rule (theme tokens, focus position) wins without a fight.
+  function injectStyles(doc) {
+    if (doc.getElementById('scroll-film-css')) return;
+    var style = doc.createElement('style');
+    style.id = 'scroll-film-css';
+    style.textContent = [
+      '@layer scroll-film {',
+      '.sf-root{position:relative;background:var(--film-bg,#0d0d0f)}',
+      '.sf-stage{position:sticky;top:0;height:100vh;height:100lvh;overflow:hidden}',
+      '.sf-shots,.sf-shot,.sf-overlay{position:absolute;inset:0}',
+      '.sf-shot{opacity:0;visibility:hidden}',
+      '.sf-poster,.sf-video{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;object-position:var(--film-focus,50% 45%)}',
+      '.sf-video{opacity:0}',
+      '.sf-shot.is-live .sf-video{opacity:1}',
+      '.sf-overlay{z-index:1000;pointer-events:none}',
+      '}',
+    ].join('\n');
+    doc.head.appendChild(style);
+  }
+
+  return { mount: mount, hold: hold, planBands: planBands, shotOpacity: shotOpacity };
+});

package/skills/scroll-film/evals/README.md

@@ -0,0 +1,26 @@
+# Evals — scroll-film
+
+`cases.yaml` holds the trigger boundary and two capability rubrics. None of it is deterministic CI:
+routing and capability are judged by a model or a person.
+
+**Triggering.** Load only this skill and its nearest siblings (`design`, `ai-media`,
+`landing-copy`, `performance`) so routing is honest. Run each `should_trigger` prompt in 3 fresh
+sessions; it passes when scroll-film fires in the majority. Each `should_not_trigger` passes when
+scroll-film does not fire; check that the named `route_to` sibling really owns it. Bar: at least
+90% of all trigger cases correct. `npm run routing:audit` adds a lexical check across the whole
+catalog, which is a floor, not proof.
+
+**Capability.** A/B on each scenario: the same prompt without the skill (baseline) and with it,
+3 trials each, one grader for both arms. Grade every `must_include` line pass/fail. The skill
+ships when the treatment clears 8.5/10 and beats the baseline by at least +1.0
+(`scripts/skill-behavior-rubric.md`). Items both arms miss are suspect; rewrite them as behaviour
+or remove them (`../../author-skill/references/eval-authoring.md`).
+
+**The artifact checks are deterministic.** `scripts/verify.sh` (encode and seam checks) and the
+engine's pure functions (`hold`, `planBands`, `shotOpacity`) are covered by
+`tests/scroll-film.test.js` in `npm test`. The browser behaviour of the engine (Blob seeking on a
+host without range support, seek coalescing under CPU throttle, phone sources, height-only resize,
+reduced motion, no-JS copy) was checked by hand in headless Chrome with generated clips. It is not
+in CI, which has no browser. Re-run it after any change to `assets/scrub-engine.js`.
+
+Re-run both axes after any edit to the description or the body: both are wording-sensitive.

package/skills/scroll-film/evals/cases.yaml

@@ -0,0 +1,81 @@
+skill: scroll-film
+
+# scroll-film owns one job end to end: a page section whose picture is a chain of pre-rendered
+# clips scrubbed by scroll — the chain (seams handed off as real frames), the encode (short GOP,
+# Blob-seekable), the page (engine that holds up on phones) and the seam QA. It is NOT scroll
+# animation without video (design), NOT a finished MP4 (ai-media), NOT the words (landing-copy),
+# NOT a still image (replicate-images), NOT the provider call mechanics (fal), NOT page speed in
+# general (performance), NOT a video rendered from code (remotion-video).
+
+should_trigger:
+  - prompt: "Quiero una landing en la que, al hacer scroll, la cámara vuele por las fases de nuestro negocio sin cortes, como las webs de Apple, con vídeos generados con IA."
+    why: "The core job in Spanish: a scroll-scrubbed camera flight built from AI clips, from the brief to the page."
+
+  - prompt: "Build a scroll-driven hero where the camera flies from the tea farm into the kitchen and then into our shop, all AI-generated video, no visible cuts."
+    why: "The core job in English: ordered scenes, one continuous flight, generated clips that must chain without seams."
+
+  - prompt: "Our scroll-scrubbed hero video works on localhost but in production it is stuck on the first frame whatever I scroll."
+    why: "Non-obvious symptom: a host that ignores byte-range requests leaves the streamed video unseekable. The fix is the engine's Blob loading."
+
+  - prompt: "Every time the scroll passes from one AI clip to the next there's a jump: the kitchen at the end of the transition doesn't look like the kitchen at the start of the next clip."
+    why: "Non-obvious symptom of the seam law: the transition ended on the original still instead of the next clip's real first frame."
+
+  - prompt: "On iPhone our scroll video is black until I touch the screen, and on Android a fast flick freezes it."
+    why: "Phone failures specific to scrubbing: iOS paints nothing for a never-played video; queued seeks on a long-GOP master freeze the decoder."
+
+  - prompt: "Convierte la web de la inmobiliaria en un recorrido: al bajar, la cámara entra por la puerta, cruza el salón y sale a la terraza, todo con imágenes generadas."
+    why: "Photoreal walkthrough phrased as a tour, not as 'scroll video': it needs the forward-take chain shape and frame handoffs."
+
+  - prompt: "Vull que el hero de la web sigui un vol de càmera per un món en miniatura que avança amb l'scroll."
+    why: "Catalan, diorama look: the dive-and-hop chain shape scrubbed by scroll."
+
+should_not_trigger:
+  - prompt: "On our Next.js landing page, make each section fade and rise in as it scrolls into view, and pin the pricing block while its cards slide in."
+    route_to: design
+    why: "Scroll-linked animation of DOM elements, with no video: CSS scroll timelines and ScrollTrigger pinning belong to design."
+
+  - prompt: "Take these five Kling clips, stitch them into one 30-second MP4, and lay a voiceover and music under them."
+    route_to: ai-media
+    why: "A finished media file assembled with ffmpeg, not a page scrubbed by scroll."
+
+  - prompt: "Write the headline, subhead and call to action for the hero of our bubble tea landing page."
+    route_to: landing-copy
+    why: "The words on the page; scroll-film hands its copy slots to landing-copy."
+
+  - prompt: "Generate a photorealistic product image of our bottle on a marble counter for the homepage."
+    route_to: replicate-images
+    why: "One still image, no chain and no scrubbing."
+
+  - prompt: "Our homepage LCP is 4.8 seconds because of a 6 MB hero image. How do we get it under 2.5?"
+    route_to: performance
+    why: "A Core Web Vitals fix from a measurement; nothing about scrubbed video."
+
+  - prompt: "How do I submit a video job to fal's queue and verify the webhook signature when it finishes?"
+    route_to: fal
+    why: "Provider call mechanics; scroll-film only defines what the clip must be and delegates the call."
+
+  - prompt: "Render an animated explainer from our monthly metrics JSON in React and export it as an MP4."
+    route_to: remotion-video
+    why: "A video rendered from code and data, not a generated chain scrubbed on a page."
+
+capability:
+  - scenario: "A boutique hotel wants its homepage hero to be a photoreal scroll-through: lobby, then a guest room, then the rooftop pool, then the restaurant, on desktop and phones. Money is tight. Their image-to-video endpoint on fal accepts a prompt, an image_url and an end_image_url, and its page lists a price per second of video. Nothing has been generated yet. Write the plan an engineer will follow, from the first question to the last check, including the commands for the steps that need them."
+    must_include:
+      - "Prices the chain before anything renders — the clip count follows from the chosen shape (one leg per scene for a forward take, doubled by a native 9:16 phone chain) times seconds times the provider's current price, plus re-roll headroom — and waits for the client's approval"
+      - "Chooses a continuous forward take for this photoreal walkthrough, and says that a pull-out-and-fly-over transition would reverse the camera at every seam and read as a rewind"
+      - "Starts each leg from the previous leg's actual rendered last frame, extracted from the video file, and gives legs no end frame"
+      - "Extracts the real last frame (decoding to the end, e.g. -update 1) rather than an approximate seek a few frames from the end"
+      - "Probes the endpoint with one cheap clip before batching, checking that frame 0 reproduces the start image rather than re-rendering the scene"
+      - "Keeps one model for the whole chain, and plans for the rooftop pool clip tripping a content filter (re-roll, neutral wording) instead of switching the whole chain"
+      - "Encodes for seeking: a keyframe every few frames (about 8 on desktop, about 4 on phones), no audio track, faststart, native resolution"
+      - "Renders a native 9:16 chain for phones, or labels a centre crop as a stopgap if the budget cannot cover it"
+      - "Loads clips so seeking works on hosts without byte-range support (as Blobs), keeps the poster until a frame paints for iOS, and falls back to stills under reduced motion"
+      - "Verifies every seam by comparing the two boundary frames and by scrolling across it, including a throttled phone emulation"
+
+  - scenario: "A team built their own scroll video: a single <video src='hero.mp4' muted> whose currentTime is set to scrollProgress * duration inside a scroll event listener. It worked in development. In production behind nginx the video never moves from the first frame, on iPhone it shows black until the user taps, and on a mid-range Android a fast flick freezes it for seconds. The MP4 is a 1080p export from an editor with default settings and an audio track. Diagnose each symptom and give the fixes."
+    must_include:
+      - "Attributes the stuck first frame to the server not honouring byte-range requests (video.seekable stuck at [0, 0]) and fixes it by loading the file as a Blob (or by enabling range support), not by re-encoding alone"
+      - "Attributes the Android freeze to seeks queued while the decoder is still seeking plus a long keyframe interval, and fixes both: one seek in flight (skip while video.seeking) and a re-encode with a short GOP"
+      - "Attributes the black iPhone video to iOS not painting a muted video that never played, and fixes it with the poster kept until a frame paints plus a muted play/pause prime (muted and playsinline attributes kept)"
+      - "Re-encodes with no audio track and faststart, at a keyframe every few frames"
+      - "Moves the per-frame work out of the scroll handler: a passive listener that only requests an animation frame"