@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/dynamic-sibling-styling.md

@@ -0,0 +1,98 @@
+# Styling siblings based on count and index
+
+Historically, applying unique styles to each sibling in a list required complex `:nth-child` loops or JavaScript to inject inline styles. Modern CSS provides `sibling-index()` and `sibling-count()` to perform these calculations directly in your stylesheet, enabling dynamic layouts and color systems that automatically adapt as elements are added or removed.
+
+## Dynamic color systems
+
+You can create a color spectrum across a group of siblings by calculating a unique hue or lightness value for each child. This ensures a consistent gradient effect regardless of the number of items.
+
+```css
+.swatch {
+  /* Calculate hue by dividing the full 360deg circle by total siblings */
+  /* and multiplying by the current element's 1-based index */
+  background-color: hsl(
+    calc(360deg / sibling-count() * sibling-index()),
+    70%,
+    50%
+  );
+}
+```
+
+## Symmetrical layout and fan effects
+
+To create symmetrical effects (like a "fan" or centering items), use the total count to find the midpoint of the list.
+
+```css
+.card {
+  /* Find the center index (e.g., 3 if there are 5 siblings) */
+  --center: calc((sibling-count() + 1) / 2);
+
+  /* Rotate items away from the center: negative for left, positive for right */
+  /* center element gets 0deg rotation */
+  transform: rotate(calc(10deg * (sibling-index() - var(--center))));
+}
+```
+
+## Circular and complex positioning
+
+By combining these functions with CSS trigonometry (`sin()`, `cos()`), you can place elements in a perfect circle without any manual coordinates.
+
+```css
+.orb {
+  /* Calculate the angle for this item's position on a 360deg circle */
+  --angle: calc(360deg / sibling-count() * sibling-index());
+  --radius: 150px;
+
+  /* Set the pre-transformed position for all items to be centered */
+  position: absolute;
+  place-self: center;
+
+
+  /* Position each element around the parent center */
+  transform: translate(
+    calc(cos(var(--angle)) * var(--radius)),
+    calc(sin(var(--angle)) * var(--radius))
+  );
+}
+```
+
+### Fallback strategies
+
+sibling-count() and sibling-index() has limited availability.
+Supported by: Chrome 138 (Jun 2025), Edge 138 (Jun 2025), and Safari 26.2 (Dec 2025).
+Unsupported in: Firefox.
+
+If `sibling-index()` and `sibling-count()` are not supported, provide a fallback by injecting CSS custom properties via JavaScript. **MANDATORY:** Use feature detection with `CSS.supports()` to ensure the script only runs when necessary.
+
+```js
+/* MANDATORY: Check for native support before applying fallback */
+if (!CSS.supports('top: calc(sibling-index() * 1px)')) {
+  const items = document.querySelectorAll('.item');
+  items.forEach((item, index) => {
+    /* MANDATORY: Injected index must be 1-based to match native function */
+    item.style.setProperty('--sibling-index', index + 1);
+    item.style.setProperty('--sibling-count', items.length);
+  });
+}
+```
+
+In your CSS, use these variables as a base and override them with native functions inside an `@supports` block. **MANDATORY:** You MUST wrap the native function overrides in `@supports` to ensure the variables remain valid in older browsers.
+
+```css
+.item {
+  /* 1. Set base values using variables (from JS fallback) */
+  --index: var(--sibling-index);
+  --count: var(--sibling-count);
+
+  /* 2. Use the computed variables - replace this with your implementation-specific styles */
+  background-color: hsl(calc(360deg / var(--count) * var(--index)), 70%, 50%);
+}
+
+@supports (top: calc(sibling-index() * 1px)) {
+  .item {
+    /* 3. Override with native functions ONLY if supported */
+    --index: sibling-index();
+    --count: sibling-count();
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/export-html-media-from-canvas.md

@@ -0,0 +1,256 @@
+# Export HTML content from canvas
+
+Web applications frequently need to capture and export rich HTML content—such as customized dashboards, styled documents, or interactive charts—as static images or video recordings. Historically, achieving this required bulky third-party libraries that manually parse DOM nodes and CSS properties to reconstruct a visual facsimile on a canvas. This approach is computationally expensive, error-prone, and frequently fails to support modern CSS layout features. With the HTML-in-Canvas API, developers can render real DOM elements directly into the canvas context. Because the browser's native rendering engine paints the HTML subtree with pixel-perfect accuracy, capturing the exact visual output as an image or video stream is highly efficient using built-in canvas methods like `toDataURL()`, `toBlob()`, or `captureStream()`.
+
+## How to implement
+
+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 the canvas to support rendering of 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 2D context, use the `drawElementImage` method:
+
+```js
+canvas.onpaint = () => {
+  ctx.reset();
+  // Draw the form element at x:0, y:0
+  let transform = ctx.drawElementImage(form_element, 0, 0);
+};
+```
+
+- 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 drawElementImage, texElementImage2D, or copyElementImageToTexture, and update the CSS transform as shown in step 5
+    }
+  };
+  ```
+
+5. Update the CSS transform.
+
+- For the 2D context case, apply the transform returned by the rendering call to the `style.transform` property:
+
+```js
+canvas.onpaint = () => {
+  ctx.reset();
+  // Draw the form element at x:0, y:0
+  let transform = ctx.drawElementImage(form_element, 0, 0);
+
+  // Sync the DOM location with the drawn location
+  form_element.style.transform = transform.toString();
+};
+```
+
+- For the 3D case with WebGL or WebGPU, 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 WebGL 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();
+  }
+  ```
+
+6. [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();
+```
+
+7. Use regular canvas export methods like `toDataURL()`, `toBlob()`, or `captureStream()`. The exported data will include the rendered HTML content.
+
+## Example code
+
+```html
+<body>
+    <canvas id="canvas" style="width: 400px; height: 200px;" layoutsubtree>
+        <input id="element">
+    </canvas>
+    
+    <button id="download">Download Image</button>
+
+    <script>
+        const canvas = document.getElementById('canvas');
+        const ctx = canvas.getContext('2d');
+        const element = document.getElementById('element');
+        const download = document.getElementById('download');
+
+        canvas.onpaint = (event) => {
+            ctx.reset();
+            // Draw the element into the canvas
+            const transform = ctx.drawElementImage(element, 10, 10);
+            // Synchronize DOM position for hit testing (typing)
+            element.style.transform = transform.toString();
+        };
+
+        download.onclick = () => {
+            // Export the canvas content as an image
+            const dataURL = canvas.toDataURL('image/png');
+            const link = document.createElement('a');
+            link.download = 'exported-canvas.png';
+            link.href = dataURL;
+            link.click();
+        };
+
+        // Re-initialize canvas size on screen resize
+        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);
+            canvas.requestPaint();
+        });
+        const supportsDevicePixelContentBox = 
+            typeof ResizeObserverEntry !== 'undefined' && 
+            'devicePixelContentBoxSize' in ResizeObserverEntry.prototype;
+        const options = supportsDevicePixelContentBox ? { box: 'device-pixel-content-box' } : {};
+        observer.observe(canvas, options);
+    </script>
+</body>
+```
+
+## Best Practices
+
+- **MANDATORY**: Check browser support for the HTML-in-Canvas API before using it.
+- **MANDATORY**: Always add the `layoutsubtree` attribute to the `<canvas>` element.
+- **MANDATORY**: Use an `onpaint` event handler to render the HTML content to the canvas.
+- **MANDATORY**: Use the `drawElementImage`, `texElementImage2D`, or `copyElementImageToTexture` methods to render the HTML content to the canvas.
+- **MANDATORY**: 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**: Use `ResizeObserver` to observe the screen size and update the canvas size to match device pixels.
+- **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.
+
+For the use case where HTML content needs to be exported from a canvas, use libraries like `html2canvas`, `dom-to-image`, or `snapdom`. 
+
+To capture HTML interactions frame by frame, for example, for streaming, capture DOM mutations using libraries like `rrweb`. 
+
+Alternatively, implement a warning that HTML media export is not supported in the browser because it doesn't support HTML-in-Canvas.