@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/apply-webgl-shaders.md

@@ -0,0 +1,239 @@
+# Apply WebGL shaders to HTML content
+
+WebGL shaders provide powerful GPU-accelerated visual effects, enabling advanced capabilities like dynamic ripple distortions, lighting models, color grading, and custom vertex transformations. The HTML-in-Canvas API allows developers to apply WebGL textures to HTML content. This enables applying high-performance fragment and vertex shaders natively to fully interactive UI components, such as buttons, input fields, and rich text, while retaining native accessibility, text selection, and DOM event handling.
+
+## 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. Add the `layoutsubtree` attribute to the `<canvas>` HTML element.
+3. Place your HTML content inside the `<canvas>` element with the `layoutsubtree` attribute.
+
+```html
+<canvas id="canvas" layoutsubtree>
+  <div id="html-content"></div>
+</canvas>
+```
+
+4. 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);
+```
+
+5. Render the HTML content to the canvas inside a `canvas.onpaint` event handler using 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);
+    }
+  }
+};
+```
+
+  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 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();
+  }
+  ```
+
+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();
+```
+
+## Example code
+
+```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>
+```
+
+## 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 `texElementImage2D` method 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.
+
+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/calculate-event-differentials.md

@@ -0,0 +1,85 @@
+# Calculating Event Differentials with Temporal
+
+Calculating the time elapsed between events (such as trial expirations, subscription durations, or prorated costs) has historically been difficult with the legacy `Date` object due to complexities with time zones, daylight saving time (DST), and inconsistent parsing.
+
+The `Temporal` API provides a modern, robust solution for date and time arithmetic. Specifically, `Temporal.ZonedDateTime` and `Temporal.Duration` enable exact, DST-safe calculations of time differences.
+
+## How to Implement
+
+To calculate differentials between two events:
+
+1.  **Obtain ZonedDateTime objects**: Convert your inputs (dates and times) into `Temporal.ZonedDateTime` objects. This ensures calculations are time-zone aware.
+2.  **Calculate active time with `.since()`**: Use `currentZonedDateTime.since(startZonedDateTime)` to find the time elapsed since a start event.
+3.  **Calculate remaining time with `.until()`**: Use `currentZonedDateTime.until(endZonedDateTime)` to find the time remaining until a future event.
+4.  **Control precision with options**: Use `largestUnit`, `smallestUnit`, and `roundingMode` to control how the resulting duration is balanced and rounded.
+
+### Example: Trial Expiration Calculation
+
+```javascript
+// 1. Get current time point in the system time zone
+const now = Temporal.Now.zonedDateTimeISO();
+const tz = now.timeZoneId;
+
+// 2. Parse inputs (assuming ISO strings from form inputs)
+const startDateStr = "2025-01-01";
+const startTimeStr = "12:00:00";
+const endDateStr = "2025-01-31";
+const endTimeStr = "12:00:00";
+
+const startDate = Temporal.PlainDate.from(startDateStr);
+const startTime = Temporal.PlainTime.from(startTimeStr);
+const start = startDate.toPlainDateTime(startTime).toZonedDateTime(tz);
+
+const endDate = Temporal.PlainDate.from(endDateStr);
+const endTime = Temporal.PlainTime.from(endTimeStr);
+const end = endDate.toPlainDateTime(endTime).toZonedDateTime(tz);
+
+// 3. Calculate difference using .since() and .until()
+// By default, units larger than hours might not wrap automatically.
+// Use largestUnit to ensure differences are expressed in larger units if applicable.
+const timeActive = now.since(start, { largestUnit: 'year' });
+const timeRemaining = now.until(end, { largestUnit: 'year' });
+
+console.log(`Active: ${timeActive.days} days, ${timeActive.hours} hours`);
+console.log(`Remaining: ${timeRemaining.days} days, ${timeRemaining.hours} hours`);
+
+// 4. Compare dates
+const isExpired = Temporal.ZonedDateTime.compare(now, end) > 0;
+if (isExpired) {
+  console.log("Subscription is expired.");
+}
+```
+
+## Strategic Implementation & Best Practices
+
+-   **DO** use `Temporal.ZonedDateTime` for calculations involving real-world events that occur in specific time zones (like subscription renewals or event scheduling).
+-   **DO** use `largestUnit` to specify the largest unit you want in the result (e.g., `'year'` or `'month'`). If you omit it, it defaults to `'auto'` which might not always sum up to years/months as expected for human-readable durations.
+-   **DO** use `.since()` when calculating time elapsed *since* a past event (e.g., `now.since(start)`), and `.until()` for time remaining *until* a future event (e.g., `now.until(end)`).
+-   **DO NOT** modify instances directly; `Temporal` objects are **immutable**. Operations like `add()`, `subtract()`, or `with()` return a *new* instance.
+-   **DO** use `Temporal.ZonedDateTime.compare` to check if one time point is after another. It returns `1` if the first is after the second, `-1` if before, and `0` if equal.
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Temporal
+
+Temporal has limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and a polyfill. The standard reference polyfill is `@js-temporal/polyfill`.
+
+Note that the polyfill does not automatically assign the `Temporal` object to the global scope to avoid conflicts. You must manually assign it if your code relies on the global `Temporal` object.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import("https://esm.sh/@js-temporal/polyfill");
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+    initializeApp();
+  }
+})();
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/calculate-with-intrinsic-sizes.md

@@ -0,0 +1,196 @@
+`calc-size()` is a CSS function for performing mathematical operations on intrinsic sizing keywords like `auto`, `min-content`, and `fit-content`. **MANDATORY**: Use `calc-size()` only when you need to modify an intrinsic size with a calculation or constraint; for simple keyword-based animations (e.g., `0` to `auto`), you must use `interpolate-size: allow-keywords`.
+
+## Implementation Steps
+
+1. **Identify the Intrinsic Basis**: Determine which intrinsic keyword (`auto`, `min-content`, etc.) should form the base of your calculation.
+2. **Define Constraints**: Use CSS math functions like `clamp()`, `min()`, or `max()` within the second argument to enforce design constraints on the intrinsic size.
+3. **MANDATORY: Provide a Fallback**: Always declare a standard sizing keyword or length immediately before the property using `calc-size()` to ensure the layout remains functional in unsupported browsers.
+4. **Apply Logical Properties**: Default to using logical properties like `inline-size` or `block-size` to ensure the calculations respect the document's writing mode.
+5. **Optional: Progressive Enhancement**: Wrap complex layout logic or animations in a `@supports (inline-size: calc-size(auto, size + 0px))` block to deliver advanced features only to capable browsers.
+
+## Basic Syntax
+
+```css
+/* calc-size(<calc-size-basis>, <calc-sum>) — mathematical operations on intrinsic sizing keywords */
+.element {
+  /* MANDATORY: Always provide a fallback for browsers that do not support calc-size() */
+  inline-size: min-content;
+  
+  /* DO: Use calc-size to modify an intrinsic basis with a calculation or function */
+  inline-size: calc-size(min-content, size + 2rem);
+}
+```
+
+### Valid Basis Arguments (`<calc-size-basis>`)
+The first argument defines the "base" size for the calculation.
+
+**Standard Keywords:**
+- `auto`: The default sizing for the element.
+- `min-content`: The smallest size the element can take without overflowing.
+- `max-content`: The size the element takes to fit all content on one line.
+- `fit-content`: Equivalent to `clamp(min-content, auto, max-content)`.
+- `content`: Only valid when `calc-size()` is used within the `flex-basis` property.
+
+**Special Arguments:**
+- `any`: A generic basis used when the specific intrinsic type is unknown or when nesting calculations.
+- Nested `calc-size()`: Allows for multi-step or conditional calculations.
+- `<calc-sum>`: A specific length, percentage, or mathematical expression (e.g., `100px` or `20%`). When a fixed value is used as the basis, the **`size` keyword is still available** (but only within the second argument) and represents the resolved value of that basis.
+
+**MANDATORY**: The `size` keyword is **not valid** within the first argument (`<calc-size-basis>`) itself. It is a local variable that only exists to refer back to the basis from within the second argument (`<calc-sum>`).
+
+### Valid Calculation Arguments (`<calc-sum>`)
+The second argument is the mathematical expression.
+- It typically uses the `size` keyword to refer to the value of the basis.
+- While the `size` keyword is technically optional, omitting it means the calculation will resolve to a fixed value, ignoring the basis entirely.
+- It can include standard math operators (`+`, `-`, `*`, `/`).
+- It can include CSS math functions like `clamp()`, `min()`, `max()`, and `round()`.
+- **MANDATORY**: `calc-size()` only allows a **single** intrinsic size value (the basis) in each calculation. You cannot mix intrinsic sizing keywords in the same `calc-size()` call.
+
+## Use Cases
+
+### Animating to and from Intrinsic Sizes
+By default, browsers cannot interpolate between a length (e.g., `0px`) and an intrinsic keyword (e.g., `auto`). Wrapping the keyword in `calc-size()` makes it an interpolatable value.
+
+#### Choosing the Right Tool for Animations
+- **MANDATORY: Use `interpolate-size: allow-keywords`**: For simple animations to or from intrinsic sizes (e.g., `height: 0` to `height: auto`) without any mathematical modifications. This is the required approach for simple keyword interpolation and should ideally be applied globally via `:root`.
+
+  ```css
+  :root {
+    /* Best practice: Enable keyword interpolation globally */
+    interpolate-size: allow-keywords;
+  }
+
+  .item {
+    height: 0;
+    transition: height 0.3s ease;
+  }
+
+  .item.open {
+    /* Simple interpolation from 0 to auto now works without calc-size() */
+    height: auto;
+  }
+  ```
+
+- **Use `calc-size()`**: ONLY when you need to perform mathematical calculations on an intrinsic size during a transition (e.g., adding padding or clamping the size).
+
+```css
+.accordion-content {
+  display: block;
+  overflow: hidden;
+  /* MANDATORY: Fallback value for closed state */
+  block-size: 0;
+  transition: block-size 0.3s ease-out;
+}
+
+.accordion-content.open {
+  /* MANDATORY: Fallback value for open state */
+  block-size: auto;
+
+  /* 
+    DO: Use calc-size(auto, ...) to enable animation from 0 to the element's 
+    intrinsic size while doing a calculation (in this case, adding a space of 2rem).
+  */
+  block-size: calc-size(auto, size + 2rem);
+}
+```
+
+**MANDATORY**: Interpolation between two intrinsic sizing keywords is not possible directly. One end of the transition must be a length or a percentage.
+
+#### Respecting User Motion Preferences
+Animations that change the size of large layout areas can be particularly disruptive for users with vestibular disorders. **MANDATORY**: Always respect user motion preferences by using the `prefers-reduced-motion` media query to simplify or minimize non-essential animations. Common strategies include disabling motion entirely, reducing duration, or replacing layout shifts with subtle opacity transitions.
+
+```css
+.accordion-content {
+  opacity: 0;
+  transition: block-size 0.3s ease, opacity 0.3s ease;
+}
+
+.accordion-content.open {
+  opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .accordion-content {
+    /* 
+       EXAMPLE: Replacing disruptive layout animations with a subtle fade-in.
+       Setting the block-size instantly and transitioning opacity 
+       provides a clear state change without large-scale motion.
+    */
+    transition: opacity 1.5s ease;
+  }
+
+  .accordion-content.open {
+    /* Jump the size instantly */
+    block-size: auto;
+  }
+}
+```
+
+
+### Applying Constraints to Intrinsic Sizes
+You can use `calc-size()` with any CSS math function—such as `min()`, `max()`, `clamp()`, or `round()`—to ensure an element's intrinsic size remains within design boundaries.
+
+```css
+.dynamic-container {
+  /* MANDATORY: Always provide a fallback for browsers that do not support calc-size() */
+  inline-size: fit-content;
+
+  /* 
+    DO: Establish a dynamic size based on content, while:
+    1. Enforcing boundaries using CSS math functions (min, clamp, etc.)
+    2. Modifying the intrinsic size with fixed or relative offsets
+  */
+  inline-size: calc-size(fit-content, min(size + var(--extra-space), var(--max-allowed)));
+}
+```
+
+## Critical Considerations
+
+- **Percentage Pitfalls**: Percentages inside the `<calc-sum>` are resolved against the **container's size**, not the `size` keyword. For example, `calc-size(auto, size + 10%)` adds 10% of the *parent's* width to the element's `auto` width, which may lead to unexpected results or overflows.
+- **Calculations requirement**: **MANDATORY**: Use `interpolate-size: allow-keywords` instead of `calc-size()` for simple animations (e.g., `0` to `auto`). `calc-size()` should only be used when the layout requires dynamic mathematical adjustments to the intrinsic base.
+- **Performance Note**: Animating box model properties like `inline-size` or `block-size` triggers layout recalculations, which can be expensive. Use `calc-size()` animations primarily for layout-critical elements where non-layout alternatives are insufficient.
+
+## Fallback strategies
+
+calc-size() has limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+interpolate-size has limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+`calc-size()` and `interpolate-size` are **progressive enhancements**. In browsers that do not support them, the properties will be ignored and the layout will remain functional, though animations to intrinsic keywords will jump instead of transitioning. Always provide a standard keyword or length as a fallback.
+
+```css
+.element {
+  /* Fallback for browsers that don't support calc-size() */
+  inline-size: fit-content; 
+  /* Modern browsers will override the fallback */
+  inline-size: calc-size(fit-content, size + 2rem);
+}
+```
+
+### Animation and Transition Fallbacks
+In browsers without support for `calc-size()` or `interpolate-size`, transitions involving intrinsic sizing keywords will fail to interpolate. 
+
+- **Graceful Degradation**: The default fallback is an "instant jump" between states (e.g., from `0` to `auto`). This is often acceptable as the layout remains functional.
+- **Enhanced Experience**: Use `@supports` to apply complex layout logic or additional styling that only makes sense when smooth intrinsic animations are possible.
+- **Avoid JS-based measurements**: While you could use JavaScript to measure elements and manually animate their dimensions, this is often unnecessary and can lead to layout thrashing. Relying on the native "instant jump" is the recommended fallback for modern web applications.
+
+For animations, the fallback experience will be an instant jump to the final size. To detect support in CSS or JavaScript:
+
+```css
+/* CSS Feature Detection */
+@supports (inline-size: calc-size(auto, size + 0px)) {
+  .element {
+    /* Apply advanced logic only when supported */
+  }
+}
+```
+
+```javascript
+/* JavaScript Feature Detection */
+if (CSS.supports('inline-size', 'calc-size(auto, size + 0px)')) {
+  // Apply advanced sizing or animations
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/capture-location-agnostic-data.md

@@ -0,0 +1,63 @@
+# Capturing Location-Agnostic Data with Temporal
+
+Recording chronological data that should remain identical regardless of the viewer's location (such as birthdates, recurring alarms, or national holidays) has historically been error-prone with the legacy `Date` object. Because `Date` objects always represent a specific instant in time and are tied to a time zone, saving a date like "1990-01-01" can result in users in different time zones seeing "1989-12-31" due to offset shifts.
+
+The `Temporal` API introduces "Plain" types—such as `Temporal.PlainDate` and `Temporal.PlainTime`—which have no concept of a time zone. These types represent calendar dates and wall-clock times exactly as you would read them off a calendar or a clock, making them ideal for location-agnostic data.
+
+## How to Implement
+
+To capture and display location-agnostic data:
+
+1.  **Use `Temporal.PlainDate` for dates**: For data like birthdates or holidays, use `Temporal.PlainDate.from()` to create an instance from an ISO 8601 string or an object.
+2.  **Use `Temporal.PlainTime` for times**: For data like a daily alarm or a preferred lunch time, use `Temporal.PlainTime.from()`.
+3.  **Display without conversion**: Since these objects are time-zone unaware, they will display the same values regardless of the user's local time zone.
+
+### Example: Capturing a Birthdate
+
+```javascript
+// 1. Parse a date string from an input (e.g., "1990-01-01")
+const birthdateStr = "1990-01-01";
+const plainDate = Temporal.PlainDate.from(birthdateStr);
+
+// 2. Display the date
+// This will output "01/01/1990" (or equivalent) in any time zone
+console.log(plainDate.toLocaleString('en-GB')); 
+
+// 3. Compare with standard Date (which might drift)
+const dateObj = new Date("1990-01-01T00:00:00Z");
+// In a UTC-5 time zone, this might print "31/12/1989"
+console.log(new Intl.DateTimeFormat('en-GB', { timeZone: 'America/New_York' }).format(dateObj));
+```
+
+## Strategic Implementation & Best Practices
+
+-   **DO** use `Temporal.PlainDate` for "calendar dates" like birthdates, anniversaries, and holidays where the specific time of day or time zone is irrelevant.
+-   **DO** use `Temporal.PlainTime` for "wall-clock times" like a daily reminder at 9:00 AM, where the time should be 9:00 AM in whatever time zone the user happens to be in.
+-   **DO NOT** use Plain types if you need to represent a specific moment in physical time (an "instant"). Use `Temporal.Instant` or `Temporal.ZonedDateTime` for logs, event timestamps, or anything requiring time zone awareness.
+-   **DO** remember that `Temporal` objects are **immutable**. Methods like `add()` or `with()` return a new instance rather than modifying the original.
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Temporal
+
+Temporal has limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and a polyfill. The standard reference polyfill is `@js-temporal/polyfill`.
+
+Note that the polyfill does not automatically assign the `Temporal` object to the global scope to avoid conflicts. You must manually assign it if your code relies on the global `Temporal` object.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import("https://esm.sh/@js-temporal/polyfill");
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+    initializeApp();
+  }
+})();
+```