[fand]

Closes #266.

Summary

vfx.capture(el, opts) captures an element as a texture without drawing it, so any effect of the same VFX instance can read it.

const page = await vfx.capture(article, { hide: true });

page.texture; // EffectTexture, stays valid while the GL texture behind it is replaced
page.rect;    // where the element is, and the size the texture was captured at
await page.update();
page.dispose();

await vfx.add(minimap, { effect, uniforms: { page: page.texture } });

The spec and the plan are in docs/tasks/capture/.

What it does

• Sources. <img> (uploaded once), <video> and <canvas> (every frame), and any HTML: html-in-canvas when supported, or one DOM snapshot as fallback.
• hide. false (default) keeps the element visible; with html-in-canvas the wrapper canvas keeps showing the latest capture. true hides it; it keeps its layout and stays interactive.
• texture. A stable EffectTexture, premultiplied like ctx.src. After dispose() it samples as transparent and warns once.
• rect. Viewport CSS px. x / y are measured once per rendered frame; width / height are the size when the current texture was captured, so the texture is not stretched for a frame after a resize.
• uniforms. VFXUniformValue gains EffectTexture, so capture.texture reaches effects through ctx.uniforms.

Rules

• One capture per element. capture() rejects for an element that addHTML or a transition wraps (or is wrapping), and addHTML rejects for a captured element.
• Effect path only. With shader, a texture uniform is ignored with one warning. Shader-path support waits for Shader path: make element shaders premultiplied alpha #271.
• A post effect cannot take a capture through its uniforms, since those are fixed in the VFX constructor. Set the capture on the effect after await vfx.capture().
• Drawing a texture from another VFX instance now throws.
• With reduced motion, capture() resolves to a handle that leaves the element alone and samples as transparent.

Differences from the issue

• rect is not a pure "rect at capture time": a viewport rect goes stale on scroll, and scrolling does not re-capture. Position follows the frame, size follows the texture.
• uniforms accepts capture.texture only, not the VFXCapture object.
• A second capture() of the same element rejects instead of returning the same handle, so no ref counting is needed.

Changes

• capture.ts (new): one driver per source kind, the handle, and the per-frame tick. Dependencies are injected, so it is tested without WebGL.
• html-in-canvas.ts: keepDrawn on setupCapture, for hide: false.
• vfx-player.ts / vfx.ts: addCapture, VFX.capture, tick in render(), re-snapshot on window resize, conflict checks, cleanup in destroy().
• effect-host.ts: the cross-instance check.
• gl/program.ts: uploadUniforms skips texture handles on the shader path, with one warning.
• Stories: Capture/Minimap, Capture/HiddenSource, Capture/Sources.
• Docs: skill, docs/html-in-canvas.md, the custom effects page, doc comments, changeset.

Testing

• pnpm run build, pnpm run lint, pnpm test and pnpm --filter docs test pass (core: 516 tests).
• Checked in Chromium 153 (headless, swiftshader), with html-in-canvas on and off:
  • A captured element is drawn by an effect on another element, with the right orientation; dispose() restores the DOM.
  • The three stories draw. Minimap follows scroll and content changes; HiddenSource lines up with the element under the default scroll padding, and its link and input still work.
  • With hide: false, a resize shows no blank frame and the still copy is gone when capture() resolves.
  • Captures come back after a WebGL context loss.
  • Paint timing: in one frame the order is rAF, ResizeObserver, paint, so effects see a re-capture from the next frame.

Not covered

• Chrome 159+ (content="drawable") was not available for the browser checks.
• The VFXPlayer wiring (tick, resize, destroy order) has no unit tests; it is covered by the browser checks only.
• The demo from the issue was not ported.

[github-actions]

🚀 Cloudflare Pages preview — fb41f9e

Page	URL
Top	https://claude-tender-goldberg-1z1nd.vfx-js.pages.dev/vfx-js/
Examples	https://claude-tender-goldberg-1z1nd.vfx-js.pages.dev/vfx-js/examples/
Storybook	https://claude-tender-goldberg-1z1nd.vfx-js.pages.dev/vfx-js/storybook/
Docs	https://claude-tender-goldberg-1z1nd.vfx-js.pages.dev/vfx-js/docs/
Transition	https://claude-tender-goldberg-1z1nd.vfx-js.pages.dev/vfx-js-transitions/

_{This branch URL stays the same across pushes. Latest deploy: https://1a37c417.vfx-js.pages.dev}