@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/interactive-content-in-3d-scenes.md

@@ -0,0 +1,383 @@
+# Enable interactive HTML content in 3D scenes
+
+The HTML-in-Canvas API allows rendering real DOM directly inside a canvas element. When applied to 3D rendering contexts like WebGL, WebGPU, or Three.js, adding the `layoutsubtree` attribute enables descendant HTML elements to be seamlessly projected into the 3D scene. Crucially, because the HTML elements remain part of the active DOM layout tree, they retain full interactivity—allowing users to click buttons, select text, and trigger focus states natively without requiring complex raycasting or custom event handling.
+
+## How to implement
+
+### WebGL and WebGPU
+When using WebGL or WebGPU, follow these steps:
+
+1. Check if HTML-in-Canvas is supported in the browser:
+
+```
+if ('requestPaint' in HTMLCanvasElement.prototype) {
+  // Use HTML in Canvas API
+} else {
+  // Use fallback strategy
+}
+```
+
+2. Initialize `<canvas>` to support descendant HTML elements by adding the `layoutsubtree` attribute to the `<canvas>` HTML element. Place your HTML content inside the `<canvas>` element with the `layoutsubtree` attribute.
+
+```html
+<canvas id="canvas" layoutsubtree>
+  <div id="html-content"></div>
+</canvas>
+```
+
+3. Scale your canvas grid to match the device scale factor to prevent blurriness:
+
+```js
+const observer = new ResizeObserver(([entry]) => {
+  const dpc = entry.devicePixelContentBoxSize;
+  canvas.width = dpc
+    ? dpc[0].inlineSize
+    : Math.round(entry.contentRect.width * window.devicePixelRatio);
+  canvas.height = dpc
+    ? dpc[0].blockSize
+    : Math.round(entry.contentRect.height * window.devicePixelRatio);
+});
+
+const supportsDevicePixelContentBox =
+  typeof ResizeObserverEntry !== "undefined" &&
+  "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
+const options = supportsDevicePixelContentBox
+  ? { box: "device-pixel-content-box" }
+  : {};
+observer.observe(canvas, options);
+```
+
+4. Render the HTML content to the canvas inside a `canvas.onpaint` event handler:
+
+- In WebGL context, use the `texElementImage2D` method:
+
+```js
+canvas.onpaint = () => {
+  if (gl.texElementImage2D) {
+    try {
+      gl.texElementImage2D(gl.TEXTURE_2D, gl.RGBA8, uiElement);
+    } catch (err) {
+      console.error('texElementImage2D copy failed:', err);
+    }
+  }
+};
+```
+
+- In WebGPU context, use the `copyElementImageToTexture` method:
+
+```js
+canvas.onpaint = () => {
+  if (root.device.queue.copyElementImageToTexture) {
+    try {
+      const sourceDict = { source: valueElement };
+      const destDict = {
+        destination: { texture: targetTexture },
+        width: 512,
+        height: 128,
+      };
+      root.device.queue.copyElementImageToTexture(sourceDict, destDict);
+    } catch (err) {
+      console.error('copyElementImageToTexture copy failed:', err);
+    }
+  }
+};
+```
+
+When using a `requestAnimationFrame` loop to render the scene, call `canvas.requestPaint()` within the loop to ensure that the HTML content is rendered to the canvas. Make sure you only re-render the canvas if there has been an update to the descendant HTML elements:
+
+```js
+function render() {
+  // Request to update the canvas
+  canvas.requestPaint();
+  requestAnimationFrame(render);
+}
+requestAnimationFrame(render);
+
+canvas.onpaint = (event) => {
+  if (event.changedElements && event.changedElements.length > 0) {
+    // Update the texture with texElementImage2D, and update the CSS transform as shown in step 6
+  }
+};
+```
+
+6. Update the CSS transform.
+
+The browser needs to map from the 3D coordinate space into the CSS coordinate space using a viewport transform. To facilitate this, do the following:
+
+- Convert the MVP Matrix to DOM Matrix.
+- Normalize the HTML element. HTML elements are sized in pixels (for example, 200px wide). WebGL, however, usually treats objects as "unit squares", for example, ranging from 0 to 1. If you don't normalize, your 200px button will look 200 times larger.
+- Map to the canvas viewport. This step is the "re-scaling" phase: it stretches that unit-space math back out to match the actual pixel dimensions of your `<canvas>` element on the screen. It also flips the Y-axis, because in WebGL, up is positive, but in CSS, down is positive.
+- Calculate the final transform. Multiply the matrices in order: Viewport * MVP * Normalization. Combining them into one final transform produces a "map" that tells the browser exactly where that HTML element layer should sit to align with the 3D drawing.
+- Apply the transform to the HTML element. This moves the HTML element layer to sit directly on top of its rendered pixels. This ensures that when a user clicks a button or selects text, they are actually hitting the real HTML element.
+
+```js
+if (canvas.getElementTransform) {
+  // 1. Convert WebGL MVP Matrix to DOM Matrix
+  const mvpDOM = new DOMMatrix(Array.from(htmlElementMVP));
+
+  // 2. Normalize the HTML element (Canvas Grid pixels -> WebGL Model Space)
+  const dprX = canvas.width / canvas.clientWidth;
+  const dprY = canvas.height / canvas.clientHeight;
+  const gridWidth = targetHTMLElement.offsetWidth * dprX;
+  const gridHeight = targetHTMLElement.offsetHeight * dprY;
+
+  const toGLModel = new DOMMatrix()
+    // Scale pixels to 1 unit, flip Y (as in CSS it points down, and in WebGL it points up)
+    .scale(1 / gridWidth, -1 / gridHeight, 1 / gridHeight)
+    // Center the origin: (0,0) becomes (-width/2, -height/2) before scaling
+    .translate(-gridWidth / 2, -gridHeight / 2);
+
+  // 3. Map to the canvas viewport
+  const clipToCanvasViewport = new DOMMatrix()
+    // Move center (0,0) to center of canvas
+    .translate(canvas.width / 2, canvas.height / 2)
+    // Scale normalized clip (-1..1) to viewport size
+    .scale(canvas.width / 2, -canvas.height / 2, canvas.height / 2);
+
+  // 4. Multiply: (Clip -> Pixels) * (MVP) * (pixels -> unit square)
+  const screenSpaceTransform = clipToCanvasViewport
+    .multiply(mvpDOM)
+    .multiply(toGLModel);
+
+  // 5. Apply to the transform
+  const computedTransform = canvas.getElementTransform(
+    targetHTMLElement,
+    screenSpaceTransform,
+  );
+  targetHTMLElement.style.transform = computedTransform.toString();
+}
+```
+
+7. [Troubleshooting] If the developer is experiencing a mismatch in the DOM logical layout in 3D even after applying the CSS transform from step 5, check if the developer is experiencing the issue in Chromium 148 or earlier. If that's the case, check if `transform.is2D` is correctly set to false for a 3D DOMMatrix. If not, re-initialize the DOMMatrix which corrects `is2D` to be false before applying the transform to the target HTML element. This issue is fixed in Chromium 149+, and if the developer is experiencing it in newer Chromium versions, the is2D value is not the cause:
+
+```js
+if (transform.is2D) {
+  // Workaround for Chromium bug https://crbug.com/512171941
+  // affecting Chrome versions under 149 where `transform.is2D`
+  // is incorrectly true for a 3D DOMMatrix. The assignment
+  // below re-initializes the DOMMatrix which corrects is2D to be false.
+  transform = DOMMatrix.fromFloat64Array(transform.toFloat64Array());
+}
+targetHTMLElement.style.transform = computedTransform.toString();
+```
+
+### Three.js
+
+1. Check if HTML-in-Canvas is supported in the browser:
+
+```
+if ('requestPaint' in HTMLCanvasElement.prototype) {
+  // Use HTML in Canvas API
+} else {
+  // Use fallback strategy
+}
+```
+
+2. Create a custom geometry and material for the HTML content.
+
+3. Pass the DOM element into THREE.HTMLTexture:
+```js
+  material.map = new THREE.HTMLTexture(element);
+  mesh = new THREE.Mesh( geometry, material );
+  scene.add( mesh );
+```
+
+## Example code
+
+### WebGL Canvas
+
+```html
+<canvas id="canvas" layoutsubtree style="width: 400px; height: 400px;">
+  <div id="ui-element">
+    <p>WebGL UI Element</p>
+    <button>Action</button>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const gl = canvas.getContext("webgl");
+  const uiElement = document.getElementById("ui-element");
+
+  // Setup WebGL texture...
+  const texture = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+
+  canvas.onpaint = () => {
+    // 1. Update texture with HTML content
+    if (gl.texElementImage2D) {
+      try {
+        gl.texElementImage2D(gl.TEXTURE_2D, gl.RGBA8, uiElement);
+      } catch (err) {
+        console.error('texElementImage2D copy failed:', err);
+      }
+    }
+
+    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...
+
+    // 2. Sync DOM position with 3D scene
+    if (canvas.getElementTransform) {
+      const mvpDOM = new DOMMatrix(Array.from(htmlElementMVP));
+
+      // Recalculate the DPR compensation mapping
+      const dprX = canvas.width / canvas.clientWidth;
+      const dprY = canvas.height / canvas.clientHeight;
+      const gridWidth = uiElement.offsetWidth * dprX;
+      const gridHeight = uiElement.offsetHeight * dprY;
+
+      const cssToUnitSpace = new DOMMatrix()
+        .scale(1 / gridWidth, -1 / gridHeight, 1 / gridHeight)
+        .translate(-gridWidth / 2, -gridHeight / 2);
+
+      const clipToCanvasViewport = new DOMMatrix()
+        .translate(canvas.width / 2, canvas.height / 2)
+        .scale(canvas.width / 2, -canvas.height / 2, canvas.height / 2);
+
+      const screenSpaceTransform = clipToCanvasViewport
+        .multiply(mvpDOM)
+        .multiply(cssToUnitSpace);
+
+      const computedTransform = canvas.getElementTransform(
+        uiElement,
+        screenSpaceTransform,
+      );
+      uiElement.style.transform = computedTransform.toString();
+    }
+  };
+</script>
+```
+
+### WebGPU Canvas
+
+```html
+<canvas id="canvas" layoutsubtree style="width: 400px; height: 400px;">
+  <div id="ui-element">
+    <p>WebGPU UI Element</p>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const context = canvas.getContext("webgpu");
+  const uiElement = document.getElementById("ui-element");
+
+  // Setup WebGPU...
+  // const device = ...
+  // const targetTexture = ...
+
+  canvas.onpaint = () => {
+    // 1. Copy HTML content to texture
+    if (device.queue.copyElementImageToTexture) {
+      try {
+        const sourceDict = { source: uiElement };
+        const destDict = {
+          destination: { texture: targetTexture },
+          width: width,
+          height: height,
+        };
+        device.queue.copyElementImageToTexture(sourceDict, destDict);
+      } catch (err) {
+        console.error('copyElementImageToTexture copy failed:', err);
+      }
+    }
+
+    // 2. Sync DOM position (same matrix math as WebGL)
+    if (canvas.getElementTransform) {
+      const mvpDOM = new DOMMatrix(Array.from(htmlElementMVP));
+
+      // Recalculate the DPR compensation mapping
+      const dprX = canvas.width / canvas.clientWidth;
+      const dprY = canvas.height / canvas.clientHeight;
+      const gridWidth = uiElement.offsetWidth * dprX;
+      const gridHeight = uiElement.offsetHeight * dprY;
+
+      const cssToUnitSpace = new DOMMatrix()
+        .scale(1 / gridWidth, -1 / gridHeight, 1 / gridHeight) // Retain Z scale
+        .translate(-gridWidth / 2, -gridHeight / 2);
+
+      const clipToCanvasViewport = new DOMMatrix()
+        .translate(canvas.width / 2, canvas.height / 2)
+        .scale(canvas.width / 2, -canvas.height / 2, canvas.height / 2); // Retain Z scale
+
+      const screenSpaceTransform = clipToCanvasViewport
+        .multiply(mvpDOM)
+        .multiply(cssToUnitSpace);
+
+      const computedTransform = canvas.getElementTransform(
+        uiElement,
+        screenSpaceTransform,
+      );
+      uiElement.style.transform = computedTransform.toString();
+    }
+  };
+</script>
+```
+
+### Three.js
+
+```js
+// 1. Initialize Three.js camera, scene, renderer, mesh, interactions;
+
+// 2. Ensure HTML-in-Canvas feature support
+if (!('requestPaint' in HTMLCanvasElement.prototype)) {
+  // Use a fallback strategy
+}
+
+// 3. Initialize the source HTML DOM element
+const element = document.createElement('div');
+element.innerHTML = '<h1>Hello World</h1>';
+
+// 4. Create geometry and material
+const geometry = new RoundedBoxGeometry( 100, 100, 100, 10, 10 );
+const material = new THREE.MeshStandardMaterial( { roughness: 0, metalness: 0.5 } );
+
+// 5. Pass the DOM element into THREE.HTMLTexture
+material.map = new THREE.HTMLTexture(element);
+
+mesh = new THREE.Mesh( geometry, material );
+scene.add( mesh );
+
+// 6. Render Loop
+function animate() {
+  renderer.render(scene, camera);
+}
+```
+
+## Best Practices
+
+- **MANDATORY**: Check browser support for the HTML-in-Canvas API before using it.
+- **MANDATORY**: When using WebGL or WebGPU, always add the `layoutsubtree` attribute to the `<canvas>` element.
+- **MANDATORY**: When using WebGL or WebGPU, use an `onpaint` event handler to render the HTML content to the canvas.
+- **MANDATORY**: Use the `texElementImage2D` for WebGL, or `copyElementImageToTexture` for WebGPU methods to render the HTML content to the canvas.
+- **MANDATORY**: When using WebGL or WebGPU, update the CSS transform of the HTML element to match the transform of the rendered content by setting the `style.transform` property of the HTML element.
+- **MANDATORY**: Observe the screen size and update the canvas size to match device pixels, for example, by using `ResizeObserver`.
+- **DO NOT** embed cross-origin content in a canvas, as it is not supported.
+- **DO NOT** initialize `ResizeObserver` within the `onpaint` event handler, as it may lead to memory leaks.
+
+### Fallback strategies
+
+HTML in canvas is not natively supported by any major browser yet.
+
+The HTML-in-Canvas API is not currently supported in all modern browsers, thus a fallback strategy is typically required.
+
+However, given the improved performance benefits of this API, HTML-in-Canvas should be used if the browser supports it.
+
+The fallback strategy depends on the use case. For example, for an interactive HTML content in canvas, if HTML-in-Canvas is not supported, place the HTML content on top of the canvas using CSS.
+
+### HTML-in-Canvas polyfill
+
+Use the following polyfill script to mimic the HTML-in-Canvas API in browsers that do not support it.
+
+1. Install or embed the library:
+
+```
+# Install
+npm install three-html-render
+```
+
+```
+# Embed
+<script src="https://cdn.jsdelivr.net/npm/three-html-render/dist/polyfill.js"></script>
+```
+
+2. Run the `installHtmlInCanvasPolyfill()` method to translate HTML-in-Canvas.

package/.agents/skills/modern-web-guidance/guides/user-experience/interactive-content-reveal.md

@@ -0,0 +1,118 @@
+Add performant, interactive reveal effects to your site with CSS masks and registered custom properties. By using a radial gradient as a mask and registering its stop values, we can smoothly transition the entry and exit, while following a user's pointer with minimal JavaScript. 
+
+## Implementation
+
+### 1. Register Custom Properties
+To enable smooth interpolation of gradient stop values, you must register the variables using `@property`. This informs the browser's engine about the data type, allowing it to transition between values during updates.
+
+```css
+/* Register the spotlight inner and outer sizes to enable interpolation */
+ @property --inner-size{
+  syntax: "<length-percentage>";
+  inherits: true;
+  initial-value: 0px;
+}
+@property --outer-size{
+  syntax: "<length-percentage>";
+  inherits: true;
+  initial-value: 0px;
+}
+```
+
+The custom properties tracking the pointer position do not need to be transitioned, so it is not required to register them.
+
+### 2. Define the Masking Layer
+Apply the `mask-image` to the element you want to reveal. Use a `radial-gradient` that references the registered properties.
+
+```css
+.reveal-layer {
+  /* Only transition the size properties, NOT the position variables */
+  transition: --inner-size 0.2s ease-in-out, --outer-size 0.2s ease-in-out;  
+
+  /* The spotlight is defined by the transparent center of the mask */
+  mask-image: radial-gradient(
+    circle at var(--mouse-x) var(--mouse-y),
+    black var(--inner-size, 0%),
+    transparent var(--outer-size, 0%)
+  );
+
+  /* Ensure the mask doesn't repeat if the element is large */
+  mask-repeat: no-repeat;
+
+  /* Make the mask layer non-interactive */
+  pointer-events: none;
+}
+
+/* Update the gradients stops on interaction */
+.reveal-layer:hover {
+  --inner-size: 100px;
+  --outer-size: 120px;
+}  
+```
+
+### 3. Update Coordinates with JavaScript
+Track the pointer position and update the CSS variables. Because the properties are registered and have a `transition` defined, the spotlight will move smoothly even if the pointer events are infrequent.
+
+```javascript
+const container = document.querySelector('.container');
+// Store the container's bounding rect
+let rect = container.getBoundingClientRect();
+// Update the rect when the container is resized
+const resizeObserver = new ResizeObserver(()=>{
+  rect = container.getBoundingClientRect();
+})
+resizeObserver.observe(container);
+
+container.addEventListener('pointermove', (e) => {
+  // Calculate position as a percentage of the container.
+  const x = ((e.clientX - rect.left) / rect.width) * 100;
+  const y = ((e.clientY - rect.top) / rect.height) * 100;
+
+  // Update the registered properties
+  container.style.setProperty('--mouse-x', `${x}%`);
+  container.style.setProperty('--mouse-y', `${y}%`);
+});
+```
+
+### 4. Accessibility and Interaction
+**MANDATORY Accessibility Guarantee:** This pattern relies on pointer interactions to reveal a visual spotlight. You MUST guarantee that all underlying content remains fully visible, legible, and independently keyboard-reachable by default in the underlying layout, using the spotlight layer purely as a non-essential visual enhancement for pointer users. Never use this effect to obscure or gate essential content from keyboard-only or assistive technology users.
+
+* **Pointer Events:** Set `pointer-events: none` on the mask overlay layer to allow standard click and touch interactions to pass through to controls underneath.
+* **Reduced Motion Override:** Disable smooth transition interpolation for users requesting reduced motion.
+
+```css
+/* MANDATORY Copy-Paste Safety: Disable transition scaling for motion-sensitive users */
+@media (prefers-reduced-motion: reduce) {
+  .reveal-layer {
+    transition: none !important;
+  }
+}
+```
+
+## Fallback strategies
+
+Baseline status for Registered custom properties: Newly available. It's been Baseline since 2024-07-09.
+Supported by: Chrome 85 (Aug 2020), Edge 85 (Aug 2020), Firefox 128 (Jul 2024), and Safari 16.4 (Mar 2023).
+
+### Non-registered Property Fallback
+Browsers that support `mask-image` but not `@property` will still show the spotlight, but the movement will jump between on and off states because they cannot interpolate values inside a `radial-gradient`. Provide fallback values when using `var()`.
+
+```css
+.reveal-layer {
+  mask-image: radial-gradient(
+    circle at var(--mouse-x) var(--mouse-y),
+    /* Use fallback values when using the `var()` function for browsers that don't get an initial value from the @property registration. */
+    black var(--inner-size, 0%),
+    transparent var(--outer-size, 0%)
+  );
+}
+```
+
+Baseline status for Masks: Newly available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+### Basic Mask Support
+
+For browsers that do not support CSS masking at all:
+1. **Prefixed property:** Use the `-webkit-mask-image` prefixed property for broader browser support.
+2. **Progressive Enhancement:** Design the base state of the UI to be fully functional and legible without the reveal effect. This is useful when the effect is only adds visual flair, and not a requirement for reading content.

package/.agents/skills/modern-web-guidance/guides/user-experience/interest-triggered-action-previews.md

@@ -0,0 +1,79 @@
+It can be beneficial to provide users a preview of their actions before they commit to them. Interest invokers are an experimental web platform feature that provides a declarative-based way of creating interest relationships between an interest source (i.e. a button or a link) and an interest target. Once the declarative relationship has been established there are a number of methods a developer can respond to based on interest and loss of interest using both CSS and JavaScript. For this use case, we can leverage the `interest` and `loseinterest` events to preview various effects for an interest target.
+
+## How to implement
+
+An interest relationship is created by setting the `interestfor` attribute on a button or link (i.e. the interest source). The attribute takes an ID reference to another element (i.e. the interest target). Interest invokers or sources can only have a single interest target, but an interest target can have multiple interest invokers.
+
+```html
+<!-- MANDATORY: interest relationships must be established with the `interestfor` attribute on a button or a link -->
+<button interestfor="interestingElement" data-effect="A">Some effect</button>
+<button interestfor="interestingElement" data-effect="B">Some other effect</button>
+<div id="interestingElement">Something interesting</div>
+```
+
+For the sake of this use case, we can leverage the `interest` and `loseinterest` events to preview various effects for an interest target. Both of these events are `InterestEvent`s which has a `source` property which is the source of the interest (i.e. the element with the `interestfor` attribute).
+
+```javascript
+interestingElement.addEventListener("interest", event => {
+  // Apply the preview based on `event.source`
+  event.target.dataset.preview = event.source.dataset.effect;
+});
+
+interestingElement.addEventListener("loseinterest", event => {
+  // Unapply the preview
+  delete event.target.dataset.preview;
+});
+```
+
+> [!NOTE]
+> **Don't announce interest-driven previews via a live region.** Interest can be triggered just by moving the pointer across the page or tabbing through nearby buttons, so apply/unapply announcements quickly become noise that can drown out content the user actually cares about. The preview itself is the affordance; users who can perceive it benefit directly, and those who can't will not benefit from a verbal echo of "Previewing effect: A". If you decide you genuinely need an announcement for a specific case, make sure to test it carefully with users.
+
+Active interest sources and targets can be selected with CSS using the `:interest-source` and `:interest-target` pseudo-selectors respectively.
+
+```css
+/* Styles to apply when the effect is being previewed */
+:interest-source {}
+:interest-target {}
+```
+
+The start and end delay for an interest invoker (i.e. the element with the `interestfor` attribute) can be set with the `interest-delay-start` and `interest-delay-end` CSS properties or the shorthand `interest-delay` property.
+
+```css
+[interestfor] {
+  interest-delay-start: 0.2s;
+  interest-delay-end: 0.1s;
+}
+```
+
+### Fallback strategies
+
+Interest invokers has limited availability.
+Supported by: Chrome 142 (Oct 2025) and Edge 142 (Oct 2025).
+Unsupported in: Firefox and Safari.
+
+Interest invokers must be conditionally polyfilled using the `interestfor` polyfill package from NPM. Do prefer bundling the polyfill over using the CDN.
+
+```html
+<script type="module">
+  if(!HTMLButtonElement.prototype.hasOwnProperty("interestForElement")){
+    // CDN link only used for example, prefer bundling.
+    await import("https://unpkg.com/interestfor@latest");
+  }
+</script>
+```
+
+When using the polyfill the CSS API changes slightly for the `:interest-source` and `:interest-target` pseudo-classes, as well as, the `interest-delay`, `interest-delay-start`, and `interest-delay-end` properties:
+
+```css
+/* Styles to apply when the effect is being previewed */
+:is(:interest-source, .interest-source) {}
+:is(:interest-target, .interest-target) {}
+
+/* Adjust the start and end delay for interest invokers */
+[interestfor] {
+  --interest-delay-start: 0.2ms;
+  interest-delay-start: 0.2ms;
+  --interest-delay-end: 0.1ms;
+  interest-delay-end: 0.1ms;
+}
+```