npm - @olives/devos - Versions diffs - 2.1.0 - Mend

@olives/devos 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (741) hide show

package/.agents/skills/modern-web-guidance/guides/performance/improve-next-page-load-performance.md ADDED Viewed

@@ -0,0 +1,119 @@
+# Improve next page load performance
+One of the most effective ways to improve page load performance for users navigating a site is to initiate loading the next page they're about to visit *before* they visit it. This can be done through a technique called speculative loading using the Speculation Rules API.
+## How it works
+Speculative loading works by using JSON-based speculation rules to tell the browser about links that can be prefetched or prerendered improving page load performance when user clicks on them.
+The rules can either be a hardcoded list of URLs a `urls` key (known as a list rule), or with a `where` key containing a set of href and CSS selectors used to find links on the page (known as a `document` rule).
+Rules can also include an optional `eagerness` property that specifies when the page should be prefetched or prerendered. The `eagerness` property can be set to `immediate`, `eager`, `moderate`, or `conservative`. `immediate` speculates as soon as possible, while the others wait for user signals such as hovering for a short period, for a longer period, or starting to click on the page respectively.
+Rules can be combined with different eagerness settings to prefetch eagerly and then prerender when the user interacts more.
+## When to use it
+Speculative loading is especially useful for static pages, where the content is not likely to change often, and where pages are cheaper to produce—especially if cached at the edge. It can also be used for dynamic pages, but it is important to be careful about the potential for stale content.
+Speculative loading is typically used for same-origin links, though more advanced options allow for some cross-origin speculation. This guide concentrates on the more-common same-origin use case.
+More eager speculative loading is a good choice for pages that are likely to be visited next, such as a headline article or the next page in a stepped process like a learning a course.
+Less eager speculative loading is a good choice when it is less obvious what the user will do next, when there are many links on the page, each equally likely to be visited. By waiting for more signals, such as hovering, or starting to click on the page, you can get a head-start on the next page and improve the user experience, even if it is not fully prefetched or prerendered.
+Similarly, prefetch is a more conservative choice than prerender, using less resources (on both the client and the server side) but providing less benefit to the user. It is a good choice for initial implementation, expanding to prerender later when the developer explicitly requests it.
+## How to use it
+Speculation rules have a JSON-based format and can be included in a `<script type="speculationrules">` tag. The rules can be included in the `<head>` or `<body>` of the document, or can be dynamically added using JavaScript.
+A `tag` can also be used, either at a global level or on a per-rule basis. When set, this tag will be included in the `Sec-Speculation-Tags` header, and allows you to identify server-side which speculations were made.
+### Example of a simple URL list rule for prefetching predefined URLs
+```html
+<script type="speculationrules">
+  {
+    "tag": "product-page-speculations",
+    "prefetch": [
+      {
+        "urls": ["/product/1", "/product/2", "/product/3"]
+      }
+    ]
+  }
+</script>
+```
+### Example of a simple document rule for prerendering all same-origin links on a page
+```html
+<script type="speculationrules">
+  {
+    "tag": "all-links-speculations",
+    "prerender": [{
+      "where": { "href_matches": "/*" }
+    }]
+  }
+</script>
+```
+### Example of a complex document rule for prerendering links with exclusions for interactive sites
+```html
+<script type="speculationrules">
+  {
+    "tag": "speculations-with-exclusions",
+    "prerender": [{
+      "where": {
+        "and": [
+          { "href_matches": "/*" },
+          { "not": {"href_matches": "/wp-admin"}},
+          { "not": {"href_matches": "/*\\?*(^|&)add-to-cart=*"}},
+          { "not": {"selector_matches": ".do-not-prerender"}},
+          { "not": {"selector_matches": "[rel~=nofollow]"}}
+        ]
+      }
+    }]
+  }
+</script>
+```
+### Example of a mixed rule set
+This example shows a rule set that prefetches all links eagerly, and then goes further than this to prerender those same links when it gets more signals with `moderate` eagerness.
+```html
+<script type="speculationrules">
+  {
+    "prefetch": [{
+      "tag": "prefetch-speculations",
+      "where": { "href_matches": "/*" },
+      "eagerness": "eager"
+    }],
+    "prerender": [{
+      "tag": "prerender-speculations",
+      "where": { "href_matches": "/*" },
+      "eagerness": "moderate"
+    }]
+  }
+</script>
+```
+## Best Practices
+- **DO** use speculation rules to prefetch and prerender pages that the user is likely to visit next.
+- **DO** use speculation rules for static sites, where the content is not likely to change often, and where pages are cheaper to produce—especially if cached at the edge.
+- **DO** take more care when using speculation rules for dynamic pages, where the content is more likely to change often, may become out of date, and where pages are more expensive to produce.
+- **DO** prefer document rules over list rules, as they are more flexible, allow the same rule to be shared across multiple pages, and can be used to prefetch and prerender pages that are not known in advance.
+- **DO** consider the trade-offs between prefetch and prerender, and choose the appropriate one for your use case. Prerender is more expensive than prefetch and can cause more unintended side effects in complex applications that display dynamic state, but provides a better user experience. Ask the developer for their preference if unsure.
+- **DO** consider the trade-offs between the different `eagerness` levels, and choose the appropriate one for your use case. More eager speculation provides a better user experience but uses more resources and can cause more unintended side effects in complex applications that display dynamic state. Ask the developer for their preference if unsure.
+- **DO NOT** overuse speculation rules, for example, to speculate every link on the page. Browsers have limits (2 speculations for non-eager speculations). `immediate` should only be used for a very small number of links.
+- **DO NOT** speculate URLs that likely trigger state changes, like `/logout` or `/add-to-cart`, and explicitly exclude them from your speculation rules if they are likely to be included in document rules.
+- **DO NOT** use speculation rules on Single Page Applications (SPAs). Speculation rules are designed for multi-page applications (MPAs) where the browser navigates to a new document on each navigation. In SPAs, the browser does not navigate to a new document on each navigation, so speculation rules will not work as expected.
+## Browser support and fallback strategies
+Speculative loading is a new feature, and as such, is not supported in all modern browsers (Baseline limited availability).
+However, speculative loading is a progressive enhancement. It is perfectly safe to use as an enhancement, and is highly recommended given the potential performance benefits. If a browser does not support speculation rules, it will simply ignore them.

package/.agents/skills/modern-web-guidance/guides/performance/interactions-in-complex-layouts.md ADDED Viewed

@@ -0,0 +1,78 @@
+# Optimizing Interactions in Complex Layouts
+Maintain high frame rates (60FPS) and eliminate interaction latency during drag-and-drop or heavy mutations in complex, multi-column layouts like Kanban boards or massive data grids.
+## Overview
+In complex layouts, performing a minor change to a single item—such as dragging a card or editing a cell—can trigger a chain reaction of style and layout calculations that forces the browser to reflow the entire page. This results in dropped frames and high Interaction to Next Paint (INP) latency.
+By applying `content-visibility: auto` to self-contained layout regions (like columns in a Kanban board), you can isolate rendering work.
+### Mechanism for On-Screen Elements
+It is important to understand how `content-visibility: auto` benefits elements that are **already visible on the screen**:
+*   For visible elements, the browser **does not** skip rendering.
+*   Instead, the performance benefit comes entirely from the **CSS containments** that the property automatically enforces (i.e., layout, style, and paint).
+*   This containment acts as a boundary. If a mutation occurs inside a container with containment applied, the browser knows that the changes cannot affect the geometry or styles of elements outside that container. The page reflow is isolated, preventing a global layout recalculation.
+## Implementation
+### 1. Identify Containment Regions
+Apply `content-visibility: auto` to large, self-contained containers that represent isolated layout units (e.g., grid columns, board lists).
+```css
+.board-column {
+  /* Apply containment boundaries */
+  content-visibility: auto;
+  /* Mandatory: Provide a placeholder size to prevent layouts shifts.
+     For a vertical column, define a reasonable width and height.
+     - '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.
+     - '300px' is the estimated width of this element. This can be any valid
+      CSS <length> value. Replace it with the expected width of your
+      component.
+     - '800px' is the estimated height of this element. This can be any valid
+      CSS <length> value. Replace it with the expected height of your
+      component.
+   */
+  contain-intrinsic-size: auto 300px auto 800px;
+}
+```
+### 2. Manage Interactions
+Ensure that interactions occurring inside the column benefit from the containment.
+```javascript
+// Example: Drag and drop item movement
+function moveItemToColumn(itemId, columnId) {
+  const item = document.getElementById(itemId);
+  const column = document.getElementById(columnId);
+  // The browser will only reflow this specific column,
+  // not the entire board layout!
+  column.appendChild(item);
+}
+```
+### Fallback strategies
+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).
+The property degrades gracefully. In unsupported browsers:
+*   The property is ignored, and mutations will cause the standard global reflow.
+*   To achieve a similar isolation effect in older browsers, you can fall back to applying containment manually:
+```css
+@supports not (content-visibility: auto) {
+  .board-column {
+    /* Manual fallback for containment */
+    contain: layout style paint;
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/performance/optimize-image-priority.md ADDED Viewed

@@ -0,0 +1,61 @@
+# Optimize image priority
+Browsers use heuristics to assign loading priorities to images, but these defaults may not always align with your page's Largest Contentful Paint (LCP). Using `fetchpriority` on an `<img>` element allows you to explicitly signal an image's importance to the browser, ensuring critical images load faster while non-essential ones don't compete for bandwidth.
+## How to implement
+1. **Identify the LCP image**: Determine which image is the most likely candidate for the Largest Contentful Paint (usually the hero image at the top of the page).
+2. **Elevate LCP priority**: Add `fetchpriority="high"` to the `<img>` element for the LCP candidate.
+3. **Deprioritize non-critical images**: For images that are part of a secondary UI or are only revealed after user interaction (like mega menus, modals, or off-screen carousel slides), add `fetchpriority="low"`.
+4. **Optimize lazy loading**: Never use `loading="lazy"` on the LCP image. For standard below-the-fold images, `loading="lazy"` is sufficient to defer the request until the user scrolls near them. Avoid adding `fetchpriority="low"` to these images, as you want them to load at normal priority once the user scrolls to them. Reserve `fetchpriority="low"` for images that are technically "above the fold" but not initially visible (e.g., hidden carousel slides or mega menus). For these hidden images, it is acceptable to use `loading="lazy"` as well; the browser will handle the request timing while respecting the low priority.
+5. **Prefer default priorities**: If an image should have normal loading priority, omit the `fetchpriority` attribute entirely rather than setting it to `auto`. This is a stylistic convention to keep your HTML cleaner while relying on the browser's native heuristics.
+## Example code
+```html
+<!-- Elevate priority for the LCP image -->
+<img src="/images/hero-lcp.jpg"
+     alt="Main Banner"
+     fetchpriority="high"
+     width="800" height="400">
+<!-- Deprioritize initially hidden images above the fold -->
+<img src="/images/gallery-alt.jpg"
+     alt="Gallery Image"
+     fetchpriority="low"
+     width="400" height="300">
+<!-- Deprioritize images revealed only after user interaction -->
+<img src="/images/mega-menu-promo.jpg"
+     alt="Special Offer"
+     fetchpriority="low"
+     width="300" height="150">
+<!-- Use lazy loading ALONE for standard below-the-fold images -->
+<img src="/images/footer-logo.png"
+     alt="Footer Logo"
+     loading="lazy"
+     width="120" height="60">
+<!-- Omit fetchpriority for images with standard priority -->
+<img src="/images/standard-image.jpg"
+     alt="Standard Image"
+     width="400" height="300">
+```
+## Best practices
+- **MANDATORY**: Always apply `fetchpriority="high"` to the LCP image.
+- **MANDATORY**: Only use `fetchpriority="high"` on at most 1-2 critical images to avoid network contention and diluting the priority boost.
+- **MANDATORY**: Use `fetchpriority="low"` for images that are technically "above the fold" but initially hidden (e.g., hidden carousel slides, mega menu images).
+- **MANDATORY**: **Do not** use `fetchpriority="low"` on standard below-the-fold images that are already using `loading="lazy"`. These images should load at normal priority once they enter the viewport.
+- **RECOMMENDED**: Avoid using `fetchpriority="auto"`. If you want the default priority, omit the attribute entirely to keep your HTML clean.
+- **DO NOT** combine `fetchpriority="high"` with `loading="lazy"` for the LCP image.
+- **DO NOT** use the deprecated `importance` attribute. It has been replaced by `fetchpriority` and is not supported by any browser.
+## 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 `fetchpriority` attribute is a progressive enhancement for the `<img>` element. If a browser does not support it, the attribute is ignored, and the browser uses its default priority heuristics.

package/.agents/skills/modern-web-guidance/guides/performance/optimize-preload-priority.md ADDED Viewed

@@ -0,0 +1,41 @@
+# Optimize preload priority
+Preloading resources with `<link rel="preload">` signals to the browser that a resource will be needed soon. However, preloads inherit the default priority for the resource type and for images in particular this is low. Using `fetchpriority` allows you to refine this relative priority, in particular ensuring image preloads are preloaded with a high priority allowing them to start earlier and use get more bandwidth resources.
+## How to implement
+1. **Identify preload candidates**: Find resources that are not discovered early by the browser (e.g., video poster images or background images in CSS) but are essential for the page's appearance.
+2. **Elevate critical image preloads**: For the LCP image or other critical images that are not prioritized by default, use `<link rel="preload" fetchpriority="high">` to ensure they are prioritized above other preloads. Note that fonts are already high priority by default.
+3. **Deprioritize non-critical preloads**: For resources that aren't critical for the initial render (e.g., a background video or secondary fonts), use `<link rel="preload" fetchpriority="low">`.
+4. **Coordinate with resource types**: Note that different `as` types have different default priorities; use `fetchpriority` to override these defaults when necessary.
+## Example code
+```html
+<!-- Elevate priority for a video poster image that acts as the LCP candidate -->
+<link rel="preload" href="/images/video-poster.jpg" as="image" fetchpriority="high">
+<!-- Elevate priority for a critical LCP image that is hidden in CSS -->
+<link rel="preload" href="/images/hero-background.jpg" as="image" fetchpriority="high">
+<!-- Deprioritize a secondary font to avoid network contention -->
+<link rel="preload" href="/fonts/secondary-font.woff2" as="font" type="font/woff2" fetchpriority="low" crossorigin>
+```
+## Best Practices
+- **MANDATORY**: Only use `fetchpriority="high"` on at most 1-2 critical image preloads to avoid network contention and diluting the priority boost.
+- **MANDATORY**: Use `fetchpriority="high"` on Largest Contentful Paint (LCP) images.
+- **DO**: Limit the total number of preloads on a page to at most 2 images and 2-3 essential fonts to prevent bandwidth contention.
+- **DO** use `fetchpriority="low"` for preloads that you want the browser to start early but not at the expense of critical resources (especially non-critical fonts).
+- **DO** specify the `as` attribute correctly to ensure the preload will be used.
+- **DO** prefer making critical resources (like LCP images) statically discoverable in HTML via `<img>` tags rather than relying on preloads for background images.
+- **DO** ensure that font preloads always have the `crossorigin` attribute (even if same-origin).
+- **DO NOT** use the deprecated `importance` attribute. It has been replaced by `fetchpriority`.
+## 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 `fetchpriority` attribute on `<link rel="preload">` is a progressive enhancement. Browsers that do not support it will still preload the resource using their default priority for that resource type. To ensure compatibility, always provide correct `as` and `type` attributes.

package/.agents/skills/modern-web-guidance/guides/performance/optimize-script-priority.md ADDED Viewed

@@ -0,0 +1,38 @@
+# Optimize script priority
+Browsers assign default priorities to scripts based on where they appear in the document and whether they have attributes like `async` or `defer`. Using `fetchpriority` gives developers explicit control to ensure critical scripts load first, while non-essential scripts stay out of the way.
+## How to implement
+1. **Identify critical scripts**: Determine which scripts are essential for the page's core functionality or initial user interaction.
+2. **Elevate critical async scripts**: For critical scripts loaded with `async` or `defer`, add the `fetchpriority="high"` attribute to ensure they are prioritized during the discovery phase.
+3. **Deprioritize non-essential scripts**: For scripts that are not needed immediately (e.g., analytics, ads, or below-the-fold widgets), add `fetchpriority="low"` and ensure they have a `async`, `defer`, or `module` attribute to avoid blocking.
+4. **Sequence parser-blocking scripts**: Use `fetchpriority="low"` on parser-blocking scripts at the end of the body to prevent them from contending for bandwidth with more critical resources.
+## Example code
+```html
+<!-- Elevate the priority of the critical app logic -->
+<script src="/js/app.js" async fetchpriority="high"></script>
+<!-- Deprioritize non-essential tracking scripts -->
+<script src="/js/tracker.js" async fetchpriority="low"></script>
+<!-- Deprioritize late-body scripts to favor critical images or CSS -->
+<script src="/js/legacy-widgets.js" fetchpriority="low"></script>
+```
+## Best Practices
+- **MANDATORY**: Only use `fetchpriority="high"` on at most 1-2 critical scripts to avoid network contention and diluting the priority boost.
+- **DO** use `fetchpriority="high"` specifically for `async` scripts that are known to be critical for Interaction to Next Paint (INP).
+- **DO** deprioritize scripts that are not required for the initial user experience using `fetchpriority="low"`.
+- **DO NOT** use `fetchpriority` on every script tag; it should only be used to change the browser's default heuristic when it is known to be sub-optimal.
+- **DO NOT** use the deprecated `importance` attribute. It has been replaced by `fetchpriority`.
+## 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 `fetchpriority` attribute is a progressive enhancement. Browsers that do not support it will ignore the attribute and use their internal scheduling logic without error. No explicit feature detection or fallback logic is required for basic usage.