@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/passkeys/passkeys.md

@@ -0,0 +1,38 @@
+# Passkeys Orientation Guide
+
+This guide provides high-density, action-oriented orientation for implementing secure, framework-agnostic passkey authentication and credential management in modern web applications.
+
+## 1. Core Prerequisites for Passkeys
+
+Passkeys rely on the Web Authentication API (WebAuthn), which imposes strict cross-cutting security constraints that must be satisfied before any implementation attempt:
+*   **Secure Contexts**: WebAuthn methods (`navigator.credentials.create` and `navigator.credentials.get`) are strictly gated behind Secure Contexts. Applications MUST run on `https://` in production, or `http://localhost` for local development.
+*   **Relying Party (RP) ID**: Every credential is tied to an RP ID (essentially the domain name of the application). The RP ID passed in the server-side options MUST match or be a valid suffix of the current origin's domain name (e.g., `example.com` is valid for `login.example.com`). Mismatches result in `SecurityError` exceptions on the client side.
+
+## 2. The AAGUID UX Caveat
+
+The Authenticator Attestation Globally Unique Identifier (AAGUID) is a 128-bit identifier returned in the registration attestation data that represents the model/provider of the authenticator (e.g., Google Password Manager, iCloud Keychain, 1Password).
+*   **UX Hinting Only**: Relying Parties MUST use the AAGUID exclusively for UX hints (such as rendering the passkey provider name and icon in a management list to help the user).
+*   **No Security Dependencies**: applications MUST NOT use AAGUID for cryptographic security or access decisions. Platform passkeys do not currently provide cryptographic attestation for their AAGUIDs, meaning it can be altered or simulated by user agents.
+
+## 3. Decoupled Library Recommendations
+
+For backend FIDO2/WebAuthn options generation and signature verification, developers MUST rely on vetted open source libraries per language instead of hand-rolling cryptography:
+*   **JavaScript/TypeScript**: SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
+*   **Python**: py_webauthn (github.com/duo-labs/py_webauthn)
+*   **Java**: Java WebAuthn Server (github.com/Yubico/java-webauthn-server), WebAuthn4J (github.com/webauthn4j/webauthn4j)
+*   **.NET**: .NET library for FIDO2 (github.com/abergs/fido2-net-lib)
+*   **Go**: WebAuthn Go Library (github.com/go-webauthn/webauthn)
+*   **Ruby**: WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
+*   **PHP**: WebAuthn Framework (github.com/web-auth/webauthn-framework)
+
+## 4. Use Case Reference Matrix
+
+Identify the matching use case below and retrieve its full implementation guide. Every use case has critical APIs (`PublicKeyCredential.parseCreationOptionsFromJSON`, `parseRequestOptionsFromJSON`, `signalAllAcceptedCredentials`, `signalCurrentUserDetails`, `signalUnknownCredential`, conditional mediation, AAGUID handling, etc.) that are documented only in the per-use-case guide. Do NOT skip this retrieval step, and do NOT substitute third-party library wrappers (such as SimpleWebAuthn's `startAuthentication`/`startRegistration`) on the client — call the native WebAuthn browser APIs directly. Library recommendations in Section 3 apply to the **server-side** (backend FIDO2 verification) only.
+
+Specific passkey and WebAuthn implementation details are mapped to the following guides:
+*   **Passkey Registration**: `passkey-registration` (via `npx -y modern-web-guidance@latest retrieve "passkey-registration"`) — Offering new passkey registration and promotions.
+*   **Passkey Conditional Create**: `passkey-conditional-create` (via `npx -y modern-web-guidance@latest retrieve "passkey-conditional-create"`) — Silently registering passkeys immediately after successful password login.
+*   **Passkey Authentication**: `passkey-authentication` (via `npx -y modern-web-guidance@latest retrieve "passkey-authentication"`) — Discoverable-autofill and button sign-ins.
+*   **Passkey Management**: `passkey-management` (via `npx -y modern-web-guidance@latest retrieve "passkey-management"`) — Syncing lists, renames, and deletions with password managers.
+*   **Passkey Reauthentication**: `passkey-reauthentication` (via `npx -y modern-web-guidance@latest retrieve "passkey-reauthentication"`) — Re-verifying returning signed-in users for sensitive steps.
+

package/.agents/skills/modern-web-guidance/guides/performance/batch-analytics-events.md

@@ -0,0 +1,154 @@
+# Debounce and batch multiple analytics events
+
+Most analytics and telemetry data is low priority and you can safely defer sending it until the user leaves the page. The exception to this is if you need to deliver real-time updates, in which case timeliness matters.
+
+The optimal way to provide real-time analytics updates, while still minimizing beacons, is to use `fetchLater()` with the `activateAfter` configuration option. This allows you to effectively debounce and batch all analytics events that occur within a given time window into a single beacon, that is reliably sent even if the user leaves the page before the timeout expires.
+
+## How to implement
+
+1. **Schedule the request:** As soon as any relevant analytics data is available, call `fetchLater()` with your data payload and pass an `activateAfter` value. This queues the data to be sent after that amount of time passes, or if the user leaves the page beforehand.
+
+2. **Batch multiple events together:** If a new analytics event occurs before the `activateAfter` timeout expires, abort the previously scheduled request and call `fetchLater()` again (with the same `activateAfter` value) with the full event queue in a single payload.
+
+3. **Reset the event queue when the timeout expires:** If a new analytics event occurs after the scheduled beacon has successfully sent (i.e. the `fetchLater()` result's `activated` value is `true`), reset the event queue.
+
+3. **Let the browser handle the rest:** If the user navigates away or closes the tab before the `activateAfter` timeout expires, the browser will still reliably send the payload from your most recent `fetchLater()` call.
+
+## Example code
+
+This code tracks all `load` and `click` events on a page, and batches together all events that occur within a 10-second timeout.
+
+```javascript
+// Replace with your analytics endpoint.
+const ANALYTICS_ENDPOINT = '/path/to/analytics/endpoint';
+
+// Replace with a time window of your choice. All analytics events that
+// occur within this time window will be batched together.
+const BATCH_WINDOW = 10 * 1000;
+
+// The maximum number of events to batch. Pick a number that is unlikely
+// to overflow the fetchLater() quota for the page.
+const MAX_QUEUE_SIZE = 100;
+
+const eventQueue = [];
+let fetchLaterResult;
+let fetchLaterController;
+
+function trackEvent(eventData) {
+  // If the previously queued beacon has already been sent, or if the
+  // max queue size has been met, reset the queue.
+  if (fetchLaterResult?.activated || eventQueue.length > MAX_QUEUE_SIZE) {
+    fetchLaterController = null;
+    fetchLaterResult = null;
+    eventQueue.length = 0;
+  }
+
+  eventQueue.push(eventData);
+
+  // Abort any pending beacons before creating a new one.
+  if (fetchLaterController) {
+    fetchLaterController.abort();
+  }
+  fetchLaterController = new AbortController();
+
+  // Schedule a fetch for the events to be sent when the batch window expires.
+  // IMPORTANT: wrap the call in a try/catch to handle quota errors.
+  try {
+    fetchLaterResult = fetchLater(ANALYTICS_ENDPOINT, {
+      method: 'POST',
+      headers: {'content-type': 'application/json'},
+      body: JSON.stringify(eventQueue),
+      signal: fetchLaterController.signal,
+      activateAfter: BATCH_WINDOW,
+    });
+  } catch (error) {
+    // Handle errors as needed.
+  }
+}
+
+// Track page loads.
+window.addEventListener('load', () => {
+  trackEvent({type: 'page_load'});
+});
+
+// Track click events.
+window.addEventListener('click', (event) => {
+  trackEvent({type: 'click', target: serializeElement(event.target)});
+});
+```
+
+## Best Practices
+
+- **DO** use `fetchLater()` with the `activateAfter` option set to batch multiple analytics events that occur within close proximity of each other.
+- **DO** use an `AbortController` to cancel the pending fetch in cases where a new analytics event occurs.
+- **DO** check to ensure you do not batch too many events together and exceed the `fetchLater()` quota (currently roughly 64KB per origin).
+- **DO** wrap calls to `fetchLater()` in a `try/catch` to handle quota errors.
+- **DO** feature detect the presence of `fetchLater()` on `globalThis` and implement a fallback strategy for browsers that don't support the API.
+- **DO NOT** use a `ReadableStream` object for the request body, as that will error.
+
+## Browser support and fallback strategies
+
+fetchLater has limited availability.
+Supported by: Chrome 135 (Apr 2025) and Edge 135 (Apr 2025).
+Unsupported in: Firefox and Safari.. Therefore, a fallback strategy is typically required.
+
+However, given the improved reliability and performance benefits of this API, `fetchLater()` should be used if the browser supports it.
+
+### `fetchLater()` polyfill
+
+Use the following minimal `fetchLater()` polyfill, which implements the API as closely as possible in unsupporting browsers.
+
+The only notable behavior difference with this polyfill is instead of sending the payload when the user leaves the page, it sends it whenever the page's `visibilityState` changes to "hidden", since this is the most reliable end-of-session signal that's widely available today.
+
+```js
+globalThis.fetchLater ??= function fetchLater(url, init = {}) {
+  let timeoutHandle;
+  let activated = false;
+
+  function sendNow() {
+    if (!(init.signal && init.signal.aborted)) {
+      // Use fetch keepalive if the browser supports it or if custom fetch
+      // parameters are specified (e.g. custom headers or methods).
+      // Otherwise fall back to `navigator.sendBeacon()`.
+      if (
+        'keepalive' in Request.prototype ||
+        init.method !== 'POST' ||
+        init.headers
+      ) {
+        fetch(url, Object.assign({}, init, {keepalive: true}));
+        activated = true;
+      } else {
+        activated = navigator.sendBeacon(url, init.body);
+      }
+    }
+    destroy();
+  }
+
+  function destroy() {
+    document.removeEventListener('visibilitychange', sendNow);
+    clearTimeout(timeoutHandle);
+  }
+
+  if (document.visibilityState === 'hidden') {
+    // If the beacon was created while the page is already hidden, send data
+    // ASAP but wait until the next microtask to allow all sync code to run.
+    queueMicrotask(sendNow);
+  } else {
+    document.addEventListener('visibilitychange', sendNow);
+
+    if (typeof init.activateAfter === 'number' && init.activateAfter >= 0) {
+      timeoutHandle = setTimeout(sendNow, init.activateAfter);
+    }
+  }
+
+  if (init.signal) {
+    init.signal.addEventListener('abort', destroy);
+  }
+
+  return {
+    get activated() {
+      return activated;
+    },
+  };
+};
+```

package/.agents/skills/modern-web-guidance/guides/performance/break-up-long-tasks.md

@@ -0,0 +1,60 @@
+Heavy computations or long loops can block the main thread, causing the page to become unresponsive. To prevent this, you should yield control back to the browser periodically. The `scheduler.yield()` API allows you to pause a long task and let the browser handle user input or rendering before continuing.
+
+### Breaking up long tasks
+
+Use `scheduler.yield()` inside async functions to break up work.
+
+```javascript
+async function processLargeArray(items) {
+  // DO: Set a time-based deadline 50 milliseconds into the future. 50
+  // milliseconds is the boundary for when a task becomes a long task.
+  let deadline = performance.now() + 50; // 50ms budget
+
+  for (const item of items) {
+    // Process the item
+    processItem(item);
+    
+    // MANDATORY: Yield to the main thread periodically to keep the UI
+    // responsive. This can be done by checking if the deadline set earlier
+    // has been exceeded. When it has been, yield, then reset the deadline
+    // another 50 milliseconds into the future.
+    if (performance.now() >= deadline) {
+      await scheduler.yield();
+      deadline = performance.now() + 50;
+    }
+  }
+}
+```
+
+### Fallback strategies
+
+Scheduler API has limited availability.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), and Firefox 142 (Aug 2025).
+Unsupported in: Safari.
+
+Some browsers may not support the `scheduler` API. You MUST implement a fallback using `setTimeout` to ensure code executes without breaking.
+
+#### Fallback for `scheduler.yield()`
+
+```javascript
+async function processLargeArrayWithFallback(items) {
+  // DO: Set a time-based deadline 50 milliseconds into the future.
+  let deadline = performance.now() + 50;
+
+  for (const item of items) {
+    processItem(item);
+    
+    // MANDATORY: Yield to the main thread periodically to keep the UI responsive.
+    if (performance.now() >= deadline) {
+      // DO: Feature detect scheduler.yield
+      if ('scheduler' in window && 'yield' in window.scheduler) {
+        await scheduler.yield();
+      } else {
+        // DO: Fallback to setTimeout for older browsers
+        await new Promise(resolve => setTimeout(resolve, 0));
+      }
+      deadline = performance.now() + 50;
+    }
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/performance/calculate-total-foreground-time.md

@@ -0,0 +1,69 @@
+# Calculate total foreground time
+
+This guide details how to accurately calculate the total time a user spends actively viewing a page. Traditional metrics like time-on-page often incorrectly include time spent with the page in the background. By using the `VisibilityStateEntry` API, you can measure only the "foreground time," providing a better metric of user engagement.
+
+## Implementing foreground time calculation
+
+The `PerformanceTimeline` API exposes visibility state changes as performance entries. Rather than reacting to `visibilitychange` events and manually accumulating time throughout a session, you can query the entire visibility history at any time.
+
+MANDATORY: You must query the `visibility-state` performance entries to calculate the true foreground time.
+
+```javascript
+/**
+ * Calculates total time the page was in the visible state.
+ *
+ * @returns {number} Total foreground time in milliseconds.
+ */
+function getTotalForegroundTime() {
+  // MANDATORY: Query the visibility-state entries from the performance timeline.
+  const entries = performance.getEntriesByType('visibility-state');
+
+  // Fallback: If the browser does not support VisibilityStateEntry,
+  // the API will gracefully return an empty array.
+  if (entries.length === 0) {
+    // Return total time since navigation start as a fallback.
+    return performance.now();
+  }
+
+  let totalForegroundTime = 0;
+
+  for (let i = 0; i < entries.length; i++) {
+    // Only calculate duration for periods where the state was 'visible'
+    if (entries[i].name === 'visible') {
+      const start = entries[i].startTime;
+
+      // The end time is the start time of the next state change,
+      // or the current time if this is the final entry.
+      const end = i + 1 < entries.length
+          ? entries[i + 1].startTime
+          : performance.now();
+
+      totalForegroundTime += (end - start);
+    }
+  }
+
+  return totalForegroundTime;
+}
+```
+
+## Fallbacks & browser support
+
+Page visibility state has limited availability.
+Supported by: Chrome 115 (Jul 2023) and Edge 115 (Jul 2023).
+Unsupported in: Firefox and Safari.
+
+The `VisibilityStateEntry` API is a modern addition to the Performance Timeline and may not be supported in all browsers.
+
+Because `performance.getEntriesByType('visibility-state')` returns an empty array in unsupported browsers, feature detection is built into the calculation flow. You should always check if entries are returned before proceeding.
+
+If the API is unsupported, the recommended fallback is to return `performance.now()`. This represents the total time since navigation, which serves as a reasonable upper bound for engagement time when visibility state history is unavailable.
+
+```javascript
+const entries = performance.getEntriesByType('visibility-state');
+
+// If the array is empty, the API is likely unsupported.
+if (entries.length === 0) {
+  // Fallback: Return total time since page load.
+  return performance.now();
+}
+```

package/.agents/skills/modern-web-guidance/guides/performance/conditional-async-dependencies.md

@@ -0,0 +1,71 @@
+Top-level `await` allows modules to act as asynchronous functions, meaning they can pause module execution to await promises. This is extremely useful for conditionally loading async dependencies—like polyfills or heavy secondary libraries—only when required by the browser. 
+
+By utilizing top-level await, you can encapsulate the conditional loading logic inside a single module, effectively preventing downstream consumer modules from executing until the dependency is fully loaded and ready.
+
+### Conditional polyfill pattern
+
+While top-level `await` can be used to conditionally load any async dependency that's a module, a good use of the conditional depenency loading pattern is to conditionally load polyfills for browsers that don't support a specific feature. This approach encapsulates feature detection and the dynamic import inside a single dependency module.
+
+In the following case, the `popover` attribute polyfill is conditionally loaded if it isn't present on `HTMLElement.prototype`:
+
+```javascript
+// conditionally-load-polyfill.js
+
+// Check if the feature is missing before doing work.
+// MANDATORY: Prefer checking HTMLElement.prototype over window or document
+// when checking for a global DOM attribute or property like popover.
+if (!('popover' in HTMLElement.prototype)) {
+  // Use top-level await to pause the execution of any module that imports this file 
+  // until the polyfill finishes downloading and executing.
+  await import('/path/to/popover-polyfill.js');
+}
+
+// Export a marker if needed by your application
+export const polyfillLoaded = true;
+```
+
+```javascript
+// main.js
+
+// MANDATORY: Because conditionally-load-polyfill.js uses top-level await, 
+// this import will block execution of main.js until the polyfill is ready.
+import './conditionally-load-polyfill.js';
+
+// Now it is safe to use the feature (e.g., showing a popover)
+const myPopover = document.getElementById('my-popover');
+if (myPopover) {
+  myPopover.showPopover();
+}
+```
+
+### Avoiding the Safari top-level `await` bug
+
+**MANDATORY:** You must structure your imports carefully to avoid a bug where top-level await doesn't behave as expected in Webkit, which occurs when multiple modules *simultaneously* import a module that contains a top-level `await`:
+
+```javascript
+// DO NOT do this: importing the top-level await module from multiple sibling modules
+// simultaneously will crash in Safari.
+// 
+// a.js: import './conditionally-load-polyfill.js';
+// b.js: import './conditionally-load-polyfill.js';
+// main.js: import './a.js'; import './b.js'; // CRASH!
+
+// INSTEAD, guarantee a single entry point:
+// Import the top-level await module ONCE at the very top of your application tree.
+import './conditionally-load-polyfill.js';
+
+// Then import the rest of your application code, ensuring the await resolves first.
+import './app.js';
+```
+
+### Fallback strategies
+
+Top-level await has limited availability.
+Supported by: Chrome 89 (Mar 2021), Edge 89 (Mar 2021), and Firefox 89 (Jun 2021).
+Unsupported in: Safari.
+
+Top-level `await` has been supported in all major browsers since 2021 (Chrome 89, Firefox 89, Safari 15). Because of this broad support, **you do not need to implement a fallback strategy for modern web applications.**
+
+As long as you follow the guidance in the previous section to **avoid the Safari execution order bug**, you can safely rely on top-level `await` directly to manage your async dependencies.
+
+You only need to avoid top-level `await` and fall back to standard asynchronous functions or dynamic `import()` orchestration if your application is explicitly required to support legacy browsers released before 2021.

package/.agents/skills/modern-web-guidance/guides/performance/defer-rendering-heavy-content.md

@@ -0,0 +1,106 @@
+# Defer rendering heavy content
+
+Web pages with extensive content—such as infinite scrolls, complex dashboards, or dense articles can suffer from slow initial rendering and sluggish interactions. Modern web technologies allow you to defer the rendering workload for content that is not immediately visible, significantly boosting performance without breaking accessibility or user expectations.
+
+To optimize rendering, you can utilize the CSS `content-visibility` property and the HTML `hidden="until-found"` attribute. While both aid performance, they serve distinct use cases.
+
+## When to use which
+
+| Scenario / Example | Feature Applied | Performance Benefit |
+| :--- | :--- | :--- |
+| **1. Below the fold** (Delay initial load) | **`content-visibility: auto`** | Browser automatically offloads layout/paint workload until the container scrolls close to view, keeping standard page load speed frictionless. |
+| **2. Toggle State** (Fast view switching) | **`content-visibility: hidden`** | Skips layout calculations for hidden divs but preserves style containment state, allowing for instantaneous toggling without structural shifts (superior to `display: none`). |
+| **3. Searchable & Deferred** (Collapsible disclosures) | **`hidden="until-found"`** | For detailed instructions on combining rendering performance with find-in-page search accessibility, see `search-hidden-content` (via `npx -y modern-web-guidance@latest retrieve "search-hidden-content"`). |
+
+## How to implement `content-visibility: auto`
+
+### Choosing off-screen content
+
+**MANDATORY**: You MUST carefully identify which elements receive `content-visibility: auto`.
+- **DO** target large, self-contained layout blocks that are strictly **below the initial fold** (e.g., card items in an infinite feed, trailing comments, or bottom-heavy layout sections).
+- **DO NOT** apply this property to elements within the initial, above-the-fold viewport. Doing so forces the browser to evaluate visibility boundaries before rendering, which paradoxically delays critical page load performance.
+- **DO** target elements with deep or complex internal DOM structures to maximize rendering cost savings.
+
+### Implementation steps
+
+1. **MANDATORY**: Identify heavy sections that are confirmed to be off-screen on initial load.
+2. **MANDATORY**: Apply `content-visibility: auto` to each of these off-screen elements.
+3. **MANDATORY**: Provide an estimated layout structure size using `contain-intrinsic-size` on each element.
+
+### How to use `contain-intrinsic-size`
+
+**MANDATORY**: You MUST pair `content-visibility: auto` with `contain-intrinsic-size`. Failure to do so forces the browser to collapse the element to a 0px height when off-screen, causing severe layout shifting and scrollbar jumping as the user scrolls.
+
+The `contain-intrinsic-size` CSS shorthand property acts as a placeholder dimension. Using the `auto` keyword enables the browser to "remember" the exact size once the element is finally rendered, using that calculated size over the placeholder if the element goes off-screen again.
+
+### Example code
+
+```css
+/* DO ONLY apply this class to items OUTSIDE the initial layout viewport */
+.heavy-section-deferred {
+  /* MANDATORY: Skips rendering calculations when off-screen */
+  content-visibility: auto;
+  
+  /* Mandatory: Provide an estimated size to prevent layouts shifts.
+    - 'auto' is optional and enables the browser to remember the actual size
+      once rendered. It must be paired with a <length> value to be used for
+      the first render.
+    - 'none' tells the browser not to apply any intrinsic width to this element.
+      It can be used for either the height or the width value.
+    - '150px' is the estimated height of this element. This can be any valid
+      CSS <length> value.
+   */
+  contain-intrinsic-size: auto none auto 150px; 
+}
+```
+
+## How to implement `content-visibility: hidden`
+
+1. **Identify heavy sections:** Locate layout blocks that are initially hidden (e.g., extra rows in a large data table).
+2. **Apply CSS:** Add `content-visibility: hidden` to the element.
+3. **Reveal the element:** When the element should be revealed, change the `content-visibility` property to `visible` or `auto`.
+
+### Example code
+
+```css
+.cached-view {
+  /* Hides content but caches rendering state */
+  content-visibility: hidden;
+}
+
+.cached-view.is-active {
+  content-visibility: visible;
+}
+```
+
+Because `content-visibility: hidden` excludes the element and its children from the accessibility tree and find-in-page search, **DO NOT** use it if the content must remain discoverable while hidden. If you need hidden content to remain searchable via native Find-in-page, use `hidden="until-found"` as described in `search-hidden-content` (via `npx -y modern-web-guidance@latest retrieve "search-hidden-content"`).
+
+## Best Practices
+
+- **DO** use `contain-intrinsic-size` with `content-visibility: auto`. Failure to do so forces height recalculations on scroll, causing viewport layout jumping or visual glitches.
+- **DO NOT** apply `content-visibility: auto` to elements inside the initial fold viewport, as this delays critical page rendering.
+- **MANDATORY Accessibility Verification**: When applying `content-visibility: auto`, you MUST verify sequential keyboard reachability. In certain assistive technology configurations, off-screen nodes utilizing `content-visibility: auto` may be excluded from the accessibility tree or sequential navigation routes until focus is forcibly moved inside them. Test linear navigation across off-screen boundaries using keyboard alone.
+
+## Fallback strategies
+
+### `content-visibility` fallback
+
+Baseline status for content-visibility: Newly available. It's been Baseline since 2025-09-15.
+Supported by: Chrome 108 (Nov 2022), Edge 108 (Dec 2022), Firefox 130 (Sep 2024), and Safari 26 (Sep 2025).
+
+When `content-visibility` is not supported it will be ignored by the browser. In most cases `content-visibility: auto` will not need a fallback, though without it performance gains will be lost. An unsupported browser will leave `content-visibility: hidden` elements completely visible. Use feature detection to implement a fallback.
+
+```css
+/* Default for everyone */
+.inactive {
+  display: none;
+}
+
+/* Modern Browsers only */
+@supports (content-visibility: hidden) {
+ .inactive {
+    display: block; /* Turn the layout box back on */
+    content-visibility: hidden;
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/performance/defer-work-until-scroll-ends.md

@@ -0,0 +1,78 @@
+# Defer Work Until Scroll Ends
+
+Scrolling on the web should be smooth and responsive. Executing heavy tasks—such as layout recalculations, analytics data beacons tracking, or dynamic DOM updates—during scrolling can saturate the main thread, resulting in dropped frames and layout thrashing.
+
+Historically, developers have relied on debouncing the `scroll` event using `setTimeout()` to guess when a scroll is finished. However, these debounced functions are notoriously unreliable. They may trigger while the user’s is still scrolling.
+
+The `scrollend` event offers a highly reliable, performance-driven solution. The browser fires a `scrollend` event exactly when a scroll has rested, all transitions are finished, and a touch gesture has been released.
+
+## How to Implement
+
+To implement a defer-work pattern:
+
+1. **Set Up a Scrollable Container**: Create a container with `overflow: auto` or `overflow: scroll`.
+2. **Listen for `scroll` events**: Only use this listener for basic dynamic metrics or informative layout styling. Do not execute heavy work here.
+3. **Listen for `scrollend` events**: Register a `scrollend` callback on the scroll container or the document itself.
+4. **Execute Expensive work in the callback**: This is where it's safe to fetch dynamic content or trigger comprehensive DOM layouts.
+
+## Example Code
+
+```css
+.scroll-container {
+  height: 300px;
+  overflow-y: auto;
+}
+```
+
+```javascript
+const scroller = document.querySelector('.scroll-container');
+
+// 1. Informative feedback during scroll
+scroller.addEventListener('scroll', () => {
+  // Avoid dynamic heavier data updates here
+  console.log('Scrolling dynamically... updates deferred');
+});
+
+// 2. Safe callback when scrolling rests
+scroller.addEventListener('scrollend', () => {
+  // Run layout recalculations or analytical beacons updates here
+  const currentVisibleSection = findMostVisibleSection(scroller);
+  fetchAdditionalData(currentVisibleSection);
+});
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `scrollend` instead of debounced `scroll` events when firing layout data beacons or fetching new content content layout dynamically. 
+- **DO** consider pairing this with `scrollSnapChange` or `scrollSnapChanging` snap interactions if you're building carousels or testimonial galleries slides.
+- **DO NOT** bundle layout-dependent dynamic updates inside dynamic visual scroll callbacks.
+- **DO** consider that visual viewport zooming and scrolling triggers the `scrollend` event correctly.
+
+## Fallback Strategy
+
+Baseline status for scrollend: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 114 (May 2023), Edge 114 (Jun 2023), Firefox 109 (Jan 2023), and Safari 26.2 (Dec 2025).
+
+For unsupported browsers, fall back to a debounced `scroll` event with `setTimeout` to dispatch a custom `scrollend` event.
+
+```javascript
+function initializeDemo() {
+  const scroller = document.querySelector('#scroller');
+  scroller.addEventListener('scrollend', () => {
+    // Safe execution
+  });
+}
+
+if ('onscrollend' in window) {
+  initializeDemo();
+} else {
+  initializeDemo();
+  const scroller = document.querySelector('#scroller');
+  scroller.addEventListener('scroll', () => {
+    clearTimeout(window.scrollendtimer);
+    window.scrollendtimer = setTimeout(() => {
+      scroller.dispatchEvent(new CustomEvent('scrollend'));
+    }, 100);
+  });
+}
+```

package/.agents/skills/modern-web-guidance/guides/performance/deprioritize-background-fetches.md

@@ -0,0 +1,37 @@
+# Deprioritize background fetches
+
+When a page performs multiple simultaneous network requests, they often compete for the same bandwidth. Non-critical data such as analytics, logging, or background synchronization should be deprioritized so that user-initiated or critical data fetches can complete more quickly.
+
+## How to implement
+
+1. **Identify background requests**: Determine which `fetch()` calls are for non-essential data that doesn't impact the immediate user experience.
+2. **Apply fetch priority**: Add the `priority: 'low'` option to the `fetch()` initialization object.
+
+## Example code
+
+```javascript
+// Use high priority (default) for critical UI updates
+const criticalData = await fetch('/api/data');
+
+// Explicitly deprioritize background analytics
+fetch('/api/analytics', {
+  method: 'POST',
+  body: JSON.stringify(eventData),
+  // Lower the priority to prevent network contention
+  priority: 'low'
+});
+```
+
+## Best practices
+
+- **DO** use `priority: 'low'` for analytics, beacons, or telemetry data that isn't required for the current view.
+- **DO** use `priority: 'low'` for "prefetching" data that the user *might* need later, ensuring it doesn't slow down what they need *now*.
+- **DO NOT** use `priority: 'low'` for fetches that are critical to the user experience.
+- **DO NOT** use the deprecated `importance` key in the fetch options object. The correct key is `priority`.
+
+## Fallback strategy
+
+Baseline status for Fetch priority: Newly available. It's been Baseline since 2024-10-29.
+Supported by: Chrome 103 (Jun 2022), Edge 103 (Jun 2022), Firefox 132 (Oct 2024), and Safari 17.2 (Dec 2023).
+
+The `priority` option in the Fetch API is a progressive enhancement. Browsers that do not support it will ignore the option and treat the request with default priority. No explicit feature detection or fallback logic is required for basic usage.