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/user-experience/consistent-cross-document-transitions.md ADDED Viewed

@@ -0,0 +1,226 @@
+# Consistent Cross-Document Transitions
+## The Problem
+Cross-document view transitions animate elements between two pages during a same-origin navigation. The browser captures a snapshot of the old page, navigates, then animates from the snapshot to the new page. If the new page has not finished loading critical resources — stylesheets, layout scripts, or key DOM elements — the transition animates to an incomplete or unstyled state. This causes visual glitches such as elements morphing to wrong positions, content reflowing mid-animation, or fallback fonts flashing to web fonts after the transition completes.
+## The Solution
+Use `blocking="render"` on critical `<link>` and `<script>` elements in the new page's `<head>`, and use `<link rel="expect">` to block rendering until specific DOM elements have been parsed. This ensures the browser does not begin the view transition animation until the new page's visual state is stable. The browser continues parsing the HTML in the background — only painting is deferred.
+### Implementation Strategy
+1. **MANDATORY:** Opt in to cross-document view transitions with the `@view-transition` CSS at-rule on both pages.
+2. **MANDATORY:** Ensure critical stylesheets are in the `<head>`. Stylesheets in the `<head>` are render-blocking by default. Dynamically injected stylesheets require explicit `blocking="render"`.
+3. **DO** use `blocking="render"` on `<script>` elements that must execute before the transition animates (e.g., scripts that apply a theme or affect the layout).
+4. **DO** use `<link rel="expect" href="#element-id" blocking="render">` to block rendering until above-the-fold content has been parsed. This applies to all transition types: full-page cross-fades (to avoid animating to a blank page), morph animations (to ensure named elements exist in the DOM), and script-dependent layouts (to ensure styled content is parsed).
+5. **DO NOT** block rendering on non-critical content. Only block on resources and elements that affect the initial viewport. Blocking on too much content delays the transition and degrades perceived performance.
+## Implementation Guide
+### Step 1: Opt in to Cross-Document View Transitions
+MANDATORY: Both the source and destination pages must include the `@view-transition` at-rule. Without this, no cross-document transition occurs.
+```css
+/*
+  MANDATORY: Include this rule in every page that participates
+  in cross-document view transitions.
+  `navigation: auto` enables transitions for standard navigations
+  (link clicks, form submissions, back/forward).
+*/
+@view-transition {
+  navigation: auto;
+}
+/* MANDATORY Copy-Paste Safety: Disable cross-document view transitions for users requesting reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  @view-transition {
+    navigation: none;
+  }
+}
+```
+### Step 2: Block Rendering Until Critical Scripts Execute
+If a non-blocking script in the `<head>` must run before the transition animates (e.g., to apply a theme class or affect the layout), mark it with `blocking="render"`. Without this, `async`, `defer`, or `type="module"` scripts may execute after the transition has already started.
+```html
+<head>
+  <!--
+    DO: Mark layout-critical scripts with blocking="render".
+  -->
+  <script type=module blocking="render">
+    // Example: apply a stored theme before the page renders,
+    // so the transition snapshot reflects the correct theme.
+    document.documentElement.dataset.theme =
+      localStorage.getItem('theme') || 'light';
+  </script>
+</head>
+```
+### Step 3: Block Rendering Until Key DOM Elements Are Parsed
+Stylesheets and `blocking="render"` scripts in the `<head>` only guarantee that the `<head>` has been fully processed. They do **not** wait for any `<body>` content to be parsed. Without additional blocking, the browser may take the new-page snapshot before above-the-fold elements exist in the DOM — resulting in a transition that animates to a blank or partially rendered page.
+`<link rel="expect">` solves this by blocking rendering until a specific element (identified by its `id`) has been parsed. The `href` value must be a fragment identifier (e.g., `#hero`) matching the target element's `id` attribute. Once that element's closing tag is parsed, the render block is released.
+**DO** use `<link rel="expect">` in all of the following scenarios:
+#### Use Case 1: Full-Page Cross-Fade
+Even when no individual elements have a `view-transition-name`, the default `root` transition cross-fades the entire page. If the new page's snapshot is taken before above-the-fold content is parsed, the cross-fade animates from the old page to a blank or incomplete page. Block rendering on an element that marks the end of the visible above-the-fold content.
+```html
+<head>
+  <link rel="stylesheet" href="/css/styles.css">
+  <!--
+    DO: Block rendering until the main content area is parsed,
+    even for a simple cross-fade. Without this, the browser may
+    snapshot the page before visible content exists in the DOM,
+    causing the cross-fade to reveal a blank or partial page.
+  -->
+  <link rel="expect" href="#main-content" blocking="render">
+</head>
+<body>
+  <header>...</header>
+  <main id="main-content">
+    <h1>Page Title</h1>
+    <p>Above-the-fold content the user should see immediately.</p>
+  </main>
+  <!-- Content below the fold does NOT need to be blocked on -->
+  <section>...</section>
+</body>
+```
+#### Use Case 2: Morph Animations Between Specific Elements
+When elements on both pages share a `view-transition-name`, the browser morphs them smoothly across the navigation. If the target element has not been parsed when the transition starts, the browser cannot find it — the morph degrades to separate exit and entry animations. Block rendering until the element with the `view-transition-name` has been parsed.
+```html
+<head>
+  <link rel="stylesheet" href="/css/styles.css">
+  <!--
+    DO: Block rendering until the element participating in the
+    morph animation has been parsed. Without this, the browser
+    may start the transition before #hero exists, causing the
+    morph to degrade to a fade-out/fade-in.
+  -->
+  <link rel="expect" href="#hero" blocking="render">
+  <!--
+    When multiple blocking="render" resources are present,
+    rendering is blocked until ALL of them are satisfied.
+    Here, the browser waits for both the script to execute
+    AND the #hero element to be parsed — whichever comes last.
+  -->
+  <script async blocking="render" src="/js/transition-setup.js"></script>
+</head>
+<body>
+  <header>...</header>
+  <section id="hero">
+    <h1 style="view-transition-name: page-title">Product Name</h1>
+    <img style="view-transition-name: hero-image" src="/img/product.webp" alt="Product">
+  </section>
+</body>
+```
+### Step 4: Use Media Queries for Responsive Render Blocking
+Different viewport sizes may show different amounts of content above the fold. Use the `media` attribute on `<link rel="expect">` to block rendering only for the content visible at a given viewport width.
+```html
+<head>
+  <!--
+    DO: Use media queries to conditionally block rendering.
+    On wide screens, both the hero and the sidebar are visible,
+    so block until both are parsed. On narrow screens, only the
+    hero is visible initially.
+  -->
+  <link
+    rel="expect"
+    href="#hero"
+    blocking="render"
+    media="screen and (width <= 768px)"
+  >
+  <link
+    rel="expect"
+    href="#sidebar"
+    blocking="render"
+    media="screen and (width > 768px)"
+  >
+</head>
+```
+### Step 5: Use pagereveal for Context-Dependent Transitions (Optional)
+The `pagereveal` event is **not required** for the core render-blocking strategy. It is only needed when `view-transition-name` values must be assigned dynamically based on where the user navigated from — for example, morphing a specific list item to a detail page heading.
+If `view-transition-name` values are assigned statically in CSS, or if you are only using the default full-page cross-fade, skip this step entirely.
+```html
+<head>
+  <!--
+    MANDATORY: The pagereveal listener must be registered before
+    the page renders. Use an async script with blocking="render"
+    so the listener is registered early without blocking parsing.
+    If the listener is registered too late (e.g., in a deferred
+    script), the event may have already fired.
+  -->
+  <script async blocking="render" src="/js/transition-setup.js"></script>
+</head>
+```
+```javascript
+// transition-setup.js
+window.addEventListener('pagereveal', async (event) => {
+  if (!event.viewTransition) return;
+  const from = navigation.activation?.from;
+  if (!from) return;
+  const fromUrl = new URL(from.url);
+  // DO: Assign view-transition-name based on navigation context.
+  // This enables a morph animation from the product card on the
+  // list page to the heading on the detail page.
+  if (fromUrl.pathname === '/products/') {
+    const heading = document.querySelector('main h1');
+    if (heading) {
+      heading.style.viewTransitionName = 'product-title';
+    }
+    // MANDATORY: Remove the temporary name after the transition
+    // finishes. Stale names interfere with subsequent navigations
+    // and prevent the page from entering the bfcache.
+    await event.viewTransition.finished;
+    heading.style.viewTransitionName = '';
+  }
+});
+```
+## Best Practices
+- **DO** assign `view-transition-name` via CSS whenever possible. Reserve JavaScript assignment (via `pagereveal`) for cases where the name depends on navigation context.
+- **DO** keep render-blocking scripts small and fast. The browser has a built-in timeout (around 4 seconds), after which the transition is skipped entirely with a `TimeoutError`.
+- **DO NOT** use `<link rel="expect">` to block on elements deep in the page that are not visible in the initial viewport. This delays the transition without visual benefit.
+- **DO NOT** assign the same `view-transition-name` to multiple elements on the same page. Duplicate names cause the entire transition to be skipped.
+- **Assistive Technology Timing Impact**: Using `blocking="render"` delays visual updates and initial paint. While this prevents visual glitches for sighted users, it can cause processing latency or deferred initialization for screen readers and other assistive technologies that depend on rendered accessibility trees. Weigh the visual continuity benefits against the initial read latency for non-visual users, and ensure render-blocking scripts are minimal and extremely optimized.
+## Fallback Strategies
+Cross-document view transitions has limited availability.
+Supported by: Chrome 126 (Jun 2024), Edge 126 (Jun 2024), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+Cross-document view transitions are an excellent candidate for progressive enhancement. In browsers that do not support them, the `@view-transition` rule is ignored and standard same-origin navigations occurs exactly as they would without the feature. Supporting browsers get smooth transitions; all others get standard navigation. Limited browser support is not a reason to avoid adoption.
+All browsers that support cross-document view transitions also support `blocking="render"` and `<link rel="expect">`, so no separate fallback is needed for the render-blocking features described in this guide.
+## Other Considerations
+1. **Performance Impact**: Every render-blocking resource delays the view transition animation start. Minimize the number of render-blocking scripts and use `<link rel="expect">` only for elements that are above the fold. Prerender destination pages using the Speculation Rules API to eliminate loading delays entirely.
+2. **Timeout Behavior**: If the combined render-blocking time exceeds approximately 4 seconds, the browser skips the transition with a `TimeoutError`. Ensure critical resources load well within this window.
+3. **bfcache Compatibility**: Temporary `view-transition-name` assignments that are not cleaned up after the transition can prevent the page from entering the bfcache. Always remove dynamically assigned names in the `finished` callback.

package/.agents/skills/modern-web-guidance/guides/user-experience/content-based-styling.md ADDED Viewed

@@ -0,0 +1,118 @@
+Historically, applying different layouts to a component based on its content required either JavaScript or conditional logic in your HTML templating language to inject modifier classes (like `.card--has-image` or `.card--text-only`).
+The `:has()` pseudo-class eliminates this need by acting as a parent selector. It allows you to conditionally style a container element based on the presence or absence of specific descendant elements.
+Using `:has()`, you can easily define distinct layout variations entirely in CSS based on a component's actual DOM content. You can also optionally combine it with `:not()` to explicitly target the *absence* of content to define default layouts.
+### Implementing content-based container styling
+**MANDATORY**: You must use the `:has()` selector on the container element to detect the presence of specific child content.
+To build a component that changes its layout based on its content:
+1. **Define the default styling**: Apply the base layout styles to the container element (e.g., a simple single-column stack).
+2. **Apply content-based overrides**: Target the container with `:has([child-selector])` and apply the new layout styles for when that content is present (e.g., a multi-column grid).
+*Example: A card component that switches to a side-by-side layout if an image is present.*
+```css
+/* 1. Define the default state on the component container */
+/* This applies when there is NO image */
+.article-card {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  padding: 1.5rem;
+  border: 1px solid #ccc;
+  border-radius: 8px;
+}
+/* 2. Apply styles when a specific child element is present */
+/* MANDATORY: Target the container and use :has() to check for the descendant */
+.article-card:has(img) {
+  /* Change the layout to a row if an image exists */
+  flex-direction: row;
+  align-items: center;
+}
+/* Optional: Style the image itself (no :has() needed here) */
+.article-card img {
+  width: 150px;
+  height: auto;
+  border-radius: 4px;
+}
+/* You can also combine :has() and :not() to explicitly target the ABSENCE of content */
+/* This selects a card that DOES NOT have an image */
+.article-card:not(:has(img)) {
+  /* E.g., apply a different background color for text-only cards */
+  background-color: #f9f9f9;
+}
+```
+```html
+<!-- Assume an <h1> precedes these components in the document layout -->
+<!-- A card WITH an image (will use row layout) -->
+<article class="article-card">
+  <img src="thumbnail.jpg" alt="Article thumbnail" />
+  <div class="content">
+    <h2>Card With Image</h2>
+    <p>This card lays out its content horizontally.</p>
+  </div>
+</article>
+<!-- A card WITHOUT an image (will use default column layout) -->
+<article class="article-card">
+  <div class="content">
+    <h2>Text-Only Card</h2>
+    <p>This card lays out its content vertically, and gets its background color from the :not(:has()) rule.</p>
+  </div>
+</article>
+```
+**Performance tip**: When using `:has()`, scope the selector to the most specific component container possible (like `.article-card`). Avoid anchoring it to very high-level elements like `body:has(img)` if the styling changes are highly localized, as broad `:has()` queries can trigger more layout recalculations.
+### Fallback strategies
+Baseline status for :has(): Newly available. It's been Baseline since 2023-12-19.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 121 (Dec 2023), and Safari 15.4 (Mar 2022).
+If the content-based layout styling is critical to the user experience or page design, you must provide a fallback for browsers that do not support the `:has()` selector. For purely decorative effects, `:has()` can be used as a progressive enhancement without a fallback.
+**MANDATORY**: When implementing a fallback for critical layouts, you must use `@supports not selector(:has(*))` in your CSS to define a traditional class-based fallback (e.g., `.has-image`).
+Unlike interactive state-based styling, content presence is typically known at render time. The most robust fallback is to have your server-side templating engine (or static site generator) inject a class like `.has-image` onto the container if the child element (like an image) exists in the data.
+If server-side rendering is not an option, you must use a small script with `CSS.supports()` to detect the content and append the class on load or after dynamic content injection.
+```css
+/* Fallback CSS for older browsers */
+/* We check if the browser DOES NOT support the :has() selector */
+@supports not selector(:has(*)) {
+  /* Define a traditional modifier class that applies the exact same layout overrides */
+  .article-card.has-image {
+    flex-direction: row;
+    align-items: center;
+  }
+  .article-card:not(.has-image) {
+    background-color: #f9f9f9;
+  }
+}
+```
+```javascript
+/* Fallback JavaScript for older browsers (if not using SSR to add the class) */
+/* Check for support before running the script to avoid unnecessary work in modern browsers */
+if (!CSS.supports('selector(:has(*))')) {
+  // Find all components that need checking
+  const cards = document.querySelectorAll('.article-card');
+  cards.forEach(card => {
+    // If the critical content exists, manually add the fallback class
+    if (card.querySelector('img')) {
+      card.classList.add('has-image');
+    }
+  });
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/coordinate-global-events.md ADDED Viewed

@@ -0,0 +1,79 @@
+# Coordinating Global Events with Temporal
+Scheduling events across different time zones is notoriously difficult with the legacy `Date` object, especially around Daylight Saving Time (DST) transitions when hours can be skipped or repeated.
+The `Temporal` API provides `Temporal.ZonedDateTime` to represent a date and time in a specific time zone, handling DST transitions automatically and predictably.
+## How to Implement
+To coordinate global events and handle potential DST conflicts:
+1. **MANDATORY:** **Create a ZonedDateTime**: Use `Temporal.ZonedDateTime.from()` to create a time-zone-aware date-time object.
+2. **MANDATORY:** **Handle Ambiguity**: Use the `disambiguation` option to control behavior when a time is ambiguous or does not exist (e.g., during clock changes).
+3. **MANDATORY:** **Convert Time Zones**: Use `.withTimeZone()` to see the equivalent time in another location.
+### Example: Scheduling and Conflict Detection
+```javascript
+// 1. Define the event time and target time zone
+const date = "2025-03-09";
+const time = "02:30"; // This time is skipped in New York during Spring Forward
+const timeZone = "America/New_York";
+const inputStr = `${date}T${time}[${timeZone}]`;
+// 2. Detect conflicts using 'reject'
+let hasConflict = false;
+try {
+  // 'reject' throws RangeError if the time is ambiguous or does not exist
+  Temporal.ZonedDateTime.from(inputStr, { disambiguation: 'reject' });
+} catch (e) {
+  if (e instanceof RangeError) {
+    hasConflict = true;
+    console.log("This time falls in a DST transition gap or overlap.");
+  }
+}
+// 3. Resolve the time safely using 'compatible' (default)
+// 'compatible' will resolve to a valid time even if skipped or repeated
+const hostTime = Temporal.ZonedDateTime.from(inputStr, { disambiguation: 'compatible' });
+console.log(`Resolved time: ${hostTime.toString()}`);
+// 4. Convert to another time zone (e.g., Tokyo)
+const tokyoTime = hostTime.withTimeZone("Asia/Tokyo");
+console.log(`Tokyo time: ${tokyoTime.toString()}`);
+```
+## Strategic Implementation & Best Practices
+-   **DO** use `Temporal.ZonedDateTime` for events that are bound to a specific geographical location (like a meeting in a specific city).
+-   **DO** use `disambiguation: 'reject'` if you need to detect and warn users about scheduling conflicts during DST transitions.
+-   **DO** use `disambiguation: 'compatible'` (the default) when you want the system to automatically pick a sensible time when conflicts occur.
+-   **DO NOT** use `Temporal.PlainDateTime` for global events, as it does not carry time zone information and cannot account for DST changes.
+-   **DO** use `.withTimeZone()` to calculate the equivalent time in other locations without mutating the original object (Temporal objects are immutable).
+### Fallback strategies
+Temporal has limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+For environments without native `Temporal` support, you must conditionally load the `@js-temporal/polyfill`.
+```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();
+  }
+})();
+function initializeApp() {
+  // Your app logic here
+  console.log("Temporal is ready:", typeof Temporal);
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/cross-document-transitions.md ADDED Viewed

@@ -0,0 +1,127 @@
+Cross-document view transitions allow you to create smooth, app-like transitions between different pages of a Multi-Page Application (MPA). By default, the browser performs a cross-fade, but you can customize this to match your site's aesthetic.
+### Implementation Steps
+#### 1. Opt-in to Cross-Document View Transitions
+Both the source and destination pages must opt-in to view transitions for the browser to trigger them on navigation.
+```css
+/* Respect user's preference for reduced motion */
+@media (prefers-reduced-motion: no-preference) {
+  /* Add to a global stylesheet shared by both pages */
+  @view-transition {
+    /* Enables transitions for same-origin navigations */
+    navigation: auto;
+  }
+}
+```
+#### 2. Customize Transition Animations (Optional)
+You can target the old and new states of the transition using pseudo-elements to create effects like slides or reveals.
+```css
+/* Customizing the outgoing page animation */
+::view-transition-old(root) {
+  /* Move the old page out to the left */
+  animation: 0.4s ease-in both slide-out;
+}
+/* Customizing the incoming page animation */
+::view-transition-new(root) {
+  /* Move the new page in from the right */
+  animation: 0.4s ease-out both slide-in;
+}
+@keyframes slide-out {
+  to { transform: translateX(-20%); opacity: 0; }
+}
+@keyframes slide-in {
+  from { transform: translateX(100%); }
+}
+```
+#### 3. Create Directional Transitions (Optional)
+You may want different transition effects depending on the pages you are navigating between. For instance, when navigating from a home page to a contact page, you may want the effect of new content coming from the right. When navigating back to the home page, it wouldn't make sense to have the same effect.
+If the page you are navigating to will always have the same transition type, regardless of how you get to the page, you can specify it with `types` in the `@view-transition` rule.
+```css
+@media (prefers-reduced-motion: no-preference) {
+  @view-transition {
+    navigation: auto;
+    /* Specify the types of view transitions that will always be used on this page. */
+    types: previous;
+  }
+}
+```
+You can also conditionally specify transition types inside of an event listener for `pagereveal`.
+```js
+window.addEventListener("pagereveal", async (e) => {
+  if (e.viewTransition && window.navigation?.activation) {
+    // Use application-specific logic to compute a transition type
+     const transitionType = yourTransitionTypeLogic(navigation.activation.from, navigation.activation.entry);
+    e.viewTransition.types.add(transitionType);
+  }
+});
+```
+Then, use the `:active-view-transition-type()` pseudo selector to apply the different animations for each type.
+```css
+:active-view-transition-type(next) {
+  &::view-transition-old(root) {
+    animation-name: slide-out-next;
+  }
+  &::view-transition-new(root) {
+    animation-name: slide-in-next;
+  }
+}
+:active-view-transition-type(previous) {
+  &::view-transition-old(root) {
+    animation-name: slide-out-previous;
+  }
+  &::view-transition-new(root) {
+    animation-name: slide-in-previous;
+  }
+}
+```
+### Fallback strategies
+Baseline status for View transitions: Newly available. It's been Baseline since 2025-10-14.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 144 (Oct 2025), and Safari 18 (Sep 2024).
+Cross-document view transitions has limited availability.
+Supported by: Chrome 126 (Jun 2024), Edge 126 (Jun 2024), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+If a browser does not support view transitions, or cross-document view transitions, it will perform a standard instant page navigation. Cross-document view transitions are a progressive enhancement; the core functionality of the site remains unaffected.
+To check for support in JavaScript:
+```javascript
+if ('onpagereveal' in window) {
+  // Browser supports cross-document view transitions
+}
+```
+Baseline status for Navigation API: Newly available. It's been Baseline since 2026-01-13.
+Supported by: Chrome 102 (May 2022), Edge 102 (May 2022), Firefox 147 (Jan 2026), and Safari 26.2 (Dec 2025).
+If a browser does not support the Navigation API, you will not be able to use it to determine a transition type. Use an alternate method for determining the transition type, or provide a fallback transition type. Otherwise, the browser will perform a standard instant page navigation.
+To check for support in JavaScript:
+```javascript
+if (window.navigation?.activation) {
+  // Browser supports the Navigation API
+}
+```