@anton-gustafsson/snapshot-core 0.4.1 → 0.4.3

package/dist/neutralize-oklch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Internal to `SnapshotService.capture()` — wired up via
+ * `CaptureOptions.neutralizeColors`, not meant to be called directly. Kept
+ * in its own module (rather than inlined) so it stays independently unit
+ * testable and `colorjs.io` stays an on-demand import.
+ *
+ * html2canvas can't parse the CSS `oklch()`/`oklab()` color functions that
+ * `getComputedStyle` resolves a growing share of real-world CSS to —
+ * Tailwind v4's default palette among others — independent of how the color
+ * was originally authored. A base/reset rule commonly inherits onto
+ * virtually every element too, so this can show up on dozens of computed
+ * properties per node, not just background/text. A color mid-CSS-transition
+ * also computes to a literal `oklab(...)` (the browser interpolates colors
+ * in that space), so anything animating a color at capture time needs the
+ * same treatment.
+ *
+ * Runs on the whole document (`capture()` always passes
+ * `document.documentElement`), not just the captured element — html2canvas
+ * clones the whole document (for correct ancestor stacking/background), so
+ * a descendant could otherwise still inherit an un-neutralized color from
+ * outside the captured element. Restored once the capture settles — this
+ * rewrites real inline styles on the live page, visibly if left in place.
+ *
+ * Walks the subtree, rewrites every computed property whose value contains
+ * `oklch(...)`/`oklab(...)` to an inline `hsl()` equivalent (custom
+ * properties are skipped — they're inert until something resolves them with
+ * `var()`), set `!important` so it wins over an `!important` rule in the
+ * page's own stylesheets too, and returns a callback that restores the
+ * original inline styles.
+ *
+ * Also suppresses `transition`/`animation` on every element first. Writing
+ * a new color below is itself a style change — on an element with e.g.
+ * `transition: color 150ms`, that starts a transition, and a read of the
+ * computed value straight afterward (by html2canvas, or by any other code
+ * running after this returns) lands mid-transition rather than on the value
+ * just set. Chrome interpolates color transitions in oklab by default, so
+ * the symptom is indistinguishable from this function having done nothing
+ * at all: the computed color comes back as an oklab() this can't parse
+ * either, on a value that was never authored as oklab anywhere.
+ *
+ * `colorjs.io` is imported on demand (like html2canvas in `capture()`) so
+ * a consumer that never calls this doesn't pay for it in their initial
+ * bundle. `await`s once, up front — the DOM walk and every write below it
+ * is still one synchronous pass, which the transition/animation
+ * suppression above depends on.
+ */
+export declare function neutralizeOklchColors(root: HTMLElement): Promise<() => void>;

package/dist/neutralize-oklch.js

@@ -0,0 +1,100 @@
+const OKLCH_PATTERN = /okl(?:ch|ab)\([^)]*\)/gi;
+/**
+ * Internal to `SnapshotService.capture()` — wired up via
+ * `CaptureOptions.neutralizeColors`, not meant to be called directly. Kept
+ * in its own module (rather than inlined) so it stays independently unit
+ * testable and `colorjs.io` stays an on-demand import.
+ *
+ * html2canvas can't parse the CSS `oklch()`/`oklab()` color functions that
+ * `getComputedStyle` resolves a growing share of real-world CSS to —
+ * Tailwind v4's default palette among others — independent of how the color
+ * was originally authored. A base/reset rule commonly inherits onto
+ * virtually every element too, so this can show up on dozens of computed
+ * properties per node, not just background/text. A color mid-CSS-transition
+ * also computes to a literal `oklab(...)` (the browser interpolates colors
+ * in that space), so anything animating a color at capture time needs the
+ * same treatment.
+ *
+ * Runs on the whole document (`capture()` always passes
+ * `document.documentElement`), not just the captured element — html2canvas
+ * clones the whole document (for correct ancestor stacking/background), so
+ * a descendant could otherwise still inherit an un-neutralized color from
+ * outside the captured element. Restored once the capture settles — this
+ * rewrites real inline styles on the live page, visibly if left in place.
+ *
+ * Walks the subtree, rewrites every computed property whose value contains
+ * `oklch(...)`/`oklab(...)` to an inline `hsl()` equivalent (custom
+ * properties are skipped — they're inert until something resolves them with
+ * `var()`), set `!important` so it wins over an `!important` rule in the
+ * page's own stylesheets too, and returns a callback that restores the
+ * original inline styles.
+ *
+ * Also suppresses `transition`/`animation` on every element first. Writing
+ * a new color below is itself a style change — on an element with e.g.
+ * `transition: color 150ms`, that starts a transition, and a read of the
+ * computed value straight afterward (by html2canvas, or by any other code
+ * running after this returns) lands mid-transition rather than on the value
+ * just set. Chrome interpolates color transitions in oklab by default, so
+ * the symptom is indistinguishable from this function having done nothing
+ * at all: the computed color comes back as an oklab() this can't parse
+ * either, on a value that was never authored as oklab anywhere.
+ *
+ * `colorjs.io` is imported on demand (like html2canvas in `capture()`) so
+ * a consumer that never calls this doesn't pay for it in their initial
+ * bundle. `await`s once, up front — the DOM walk and every write below it
+ * is still one synchronous pass, which the transition/animation
+ * suppression above depends on.
+ */
+export async function neutralizeOklchColors(root) {
+    const { default: Color } = await import('colorjs.io');
+    const elements = [root, ...Array.from(root.querySelectorAll('*'))];
+    const restores = [];
+    for (const element of elements) {
+        for (const prop of ['transition', 'animation']) {
+            const previousValue = element.style.getPropertyValue(prop);
+            const previousPriority = element.style.getPropertyPriority(prop);
+            element.style.setProperty(prop, 'none', 'important');
+            restores.push(() => {
+                if (previousValue)
+                    element.style.setProperty(prop, previousValue, previousPriority);
+                else
+                    element.style.removeProperty(prop);
+            });
+        }
+        const computed = getComputedStyle(element);
+        for (let i = 0; i < computed.length; i++) {
+            const property = computed[i];
+            if (property.startsWith('--'))
+                continue;
+            const value = computed.getPropertyValue(property);
+            if (!value.includes('oklch(') && !value.includes('oklab('))
+                continue;
+            const replaced = value.replace(OKLCH_PATTERN, (match) => toHslString(Color, match) ?? match);
+            if (replaced === value)
+                continue;
+            const previousValue = element.style.getPropertyValue(property);
+            const previousPriority = element.style.getPropertyPriority(property);
+            element.style.setProperty(property, replaced, 'important');
+            restores.push(() => {
+                if (previousValue) {
+                    element.style.setProperty(property, previousValue, previousPriority);
+                }
+                else {
+                    element.style.removeProperty(property);
+                }
+            });
+        }
+    }
+    return () => restores.forEach((restore) => restore());
+}
+function toHslString(ColorCtor, cssColor) {
+    try {
+        const color = new ColorCtor(cssColor);
+        const [h, s, l] = color.hsl;
+        const alpha = color.alpha ?? 1;
+        return alpha < 1 ? `hsla(${h}, ${s}%, ${l}%, ${alpha})` : `hsl(${h}, ${s}%, ${l}%)`;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/snapshot-nav-list.d.ts

@@ -14,21 +14,16 @@ export interface NavItem<T = unknown> {
     /** @deprecated Put the route in `data` and read it off the emitted item. Kept for one release. */
     route?: string;
 }
-/** `'icon-only'` is the old name for `'tile'`; it still works and normalises to `'tile'`. */
-export type SnapshotNavListVariant = 'list' | 'tile' | 'card' | 'icon-only';
 /** `overlay` floats the edit button over the thumbnail (top-right, reveals on hover); `meta` pins it to the right edge of the title's line (description below), always visible. */
 export type SnapshotNavListEditButtonPosition = 'overlay' | 'meta';
 /**
- * Visual identity: a contact sheet. Every tile is a "frame" — numbered like a strip
- * of negatives — because that's literally what a snapshot thumbnail is. All colors
- * come from CSS custom properties (themeable) with sensible fallbacks derived from
- * `currentColor`, so an unstyled host still looks intentional.
+ * A grid of preview cards: a contained (never-cropped) screenshot above real
+ * title/description text below it — the text never sits on top of the
+ * image, so it needs no overlay tint to stay legible.
  */
 export declare class SnapshotNavList extends LitElement {
     static styles: import("lit").CSSResult;
     items: NavItem[];
-    /** `card` by default — a framed preview with title/description underneath. `tile` is the compact contact-sheet grid, `list` a sidebar row. */
-    variant: SnapshotNavListVariant;
     /**
      * Second dimension on every id — typically the active theme, so a light and a
      * dark capture of the same view are stored (and read) separately. Passed
@@ -37,21 +32,11 @@ export declare class SnapshotNavList extends LitElement {
     variantKey?: string;
     /** Lets the host itself scroll (see `--snapshot-nav-list-max-height`) instead of growing unbounded. */
     scrollable: boolean;
-    /** tile overlay: tint behind the title so it stays legible over any image. Transparent by default — opt into a scrim explicitly. */
-    overlayTint: 'dark' | 'light' | 'none';
-    /** caption background tint strength, 0-1 */
-    textOverlayOpacity: number;
-    /** image scrim tint strength, 0-1 — 0 keeps the image clear (blur only) */
-    imageOverlayOpacity: number;
-    /** backdrop blur behind the title, in px */
-    overlayBlur: number;
-    /** tile only: 'bottom' is the caption strip (default), 'center' centers a larger title. */
-    labelPosition: 'bottom' | 'center';
     /** Defaults to the shared singleton — set your own instance (e.g. a namespaced or custom-storage SnapshotService) per <snapshot-nav-list> if needed. */
     snapshotService: SnapshotService;
     /** Shows an edit button per card. Off by default — clicking it fires `nav-edit` instead of `nav-select`; the host decides what "edit" means (e.g. open its own dialog component). Overridable per row via `NavItem.editable`. */
     editable: boolean;
-    /** Where the edit button sits: `overlay` (default) floats it over the thumbnail; `meta` pins it to the right edge of the title row, with the description below. Ignored by the icon-only variant, whose caption is itself an overlay. */
+    /** Where the edit button sits: `overlay` (default) floats it over the thumbnail; `meta` pins it to the right edge of the title row, with the description below. */
     editButtonPosition: SnapshotNavListEditButtonPosition;
     /** Edit button glyph. Same convention as `NavItem.icon`: a plain-text glyph (e.g. an emoji), or markup — a string starting with `<` renders as raw HTML/SVG, so a consumer can pass its own icon (e.g. `<svg>...</svg>`). */
     editIcon: string;
@@ -80,10 +65,6 @@ export declare class SnapshotNavList extends LitElement {
      * mid-flight doesn't re-request what's already coming.
      */
     private loadThumbs;
-    /** image scrim: blur + its own (usually 0) tint strength — independent of the caption's. */
-    private get imageOverlayStyle();
-    /** caption background: tint (to pop the text) + the same blur. */
-    private get metaStyle();
     private select;
     private edit;
     private isEditable;

package/dist/snapshot-nav-list.js

@@ -6,7 +6,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { LitElement, html, css } from 'lit';
 import { property, state } from 'lit/decorators.js';
-import { styleMap } from 'lit/directives/style-map.js';
 import { unsafeHTML } from 'lit/directives/unsafe-html.js';
 import { snapshotService as defaultSnapshotService } from './snapshot-service';
 function isMarkupIcon(icon) {
@@ -14,34 +13,21 @@ function isMarkupIcon(icon) {
 }
 const DEFAULT_EDIT_ICON = '✎';
 /**
- * Visual identity: a contact sheet. Every tile is a "frame" — numbered like a strip
- * of negatives — because that's literally what a snapshot thumbnail is. All colors
- * come from CSS custom properties (themeable) with sensible fallbacks derived from
- * `currentColor`, so an unstyled host still looks intentional.
+ * A grid of preview cards: a contained (never-cropped) screenshot above real
+ * title/description text below it — the text never sits on top of the
+ * image, so it needs no overlay tint to stay legible.
  */
 export class SnapshotNavList extends LitElement {
     constructor() {
         super(...arguments);
         this.items = [];
-        /** `card` by default — a framed preview with title/description underneath. `tile` is the compact contact-sheet grid, `list` a sidebar row. */
-        this.variant = 'card';
         /** Lets the host itself scroll (see `--snapshot-nav-list-max-height`) instead of growing unbounded. */
         this.scrollable = false;
-        /** tile overlay: tint behind the title so it stays legible over any image. Transparent by default — opt into a scrim explicitly. */
-        this.overlayTint = 'none';
-        /** caption background tint strength, 0-1 */
-        this.textOverlayOpacity = 0.35;
-        /** image scrim tint strength, 0-1 — 0 keeps the image clear (blur only) */
-        this.imageOverlayOpacity = 0;
-        /** backdrop blur behind the title, in px */
-        this.overlayBlur = 0;
-        /** tile only: 'bottom' is the caption strip (default), 'center' centers a larger title. */
-        this.labelPosition = 'bottom';
         /** Defaults to the shared singleton — set your own instance (e.g. a namespaced or custom-storage SnapshotService) per <snapshot-nav-list> if needed. */
         this.snapshotService = defaultSnapshotService;
         /** Shows an edit button per card. Off by default — clicking it fires `nav-edit` instead of `nav-select`; the host decides what "edit" means (e.g. open its own dialog component). Overridable per row via `NavItem.editable`. */
         this.editable = false;
-        /** Where the edit button sits: `overlay` (default) floats it over the thumbnail; `meta` pins it to the right edge of the title row, with the description below. Ignored by the icon-only variant, whose caption is itself an overlay. */
+        /** Where the edit button sits: `overlay` (default) floats it over the thumbnail; `meta` pins it to the right edge of the title row, with the description below. */
         this.editButtonPosition = 'overlay';
         /** Edit button glyph. Same convention as `NavItem.icon`: a plain-text glyph (e.g. an emoji), or markup — a string starting with `<` renders as raw HTML/SVG, so a consumer can pass its own icon (e.g. `<svg>...</svg>`). */
         this.editIcon = DEFAULT_EDIT_ICON;
@@ -77,66 +63,48 @@ export class SnapshotNavList extends LitElement {
       list-style: none;
       margin: 0;
       padding: 0;
-      display: flex;
-      flex-direction: column;
-      gap: var(--snapshot-nav-list-gap, 0.3rem);
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(var(--snapshot-nav-list-card-min-width, 220px), 1fr));
+      gap: var(--snapshot-nav-list-card-gap, 1.25rem);
     }
     li {
       display: flex;
-      align-items: center;
-      gap: 0.7rem;
+      flex-direction: column;
+      align-items: stretch;
+      gap: 0;
       cursor: pointer;
-      padding: 0.45rem 0.55rem;
+      padding: var(--snapshot-nav-list-card-padding, 0.5rem);
       border-radius: var(--snapshot-nav-list-radius, 10px);
+      background: var(--snapshot-nav-list-card-bg, transparent);
+      border: 1px solid color-mix(in srgb, currentColor 12%, transparent);
+      box-shadow: none;
+      transition:
+        box-shadow var(--snapshot-nav-list-card-transition-dur, 0.15s) ease,
+        border-color var(--snapshot-nav-list-card-transition-dur, 0.15s) ease;
     }
     li:hover,
     li:focus-visible {
-      background: color-mix(in srgb, currentColor 7%, transparent);
+      background: var(--snapshot-nav-list-card-bg, transparent);
+      box-shadow: var(--snapshot-nav-list-card-shadow, 0 2px 8px color-mix(in srgb, currentColor 18%, transparent));
+      border-color: color-mix(in srgb, currentColor 22%, transparent);
       outline: none;
     }
-    li:focus-visible .thumb-wrap {
-      outline: 2px solid var(--frame-accent);
-      outline-offset: 2px;
+    li:focus-visible {
+      outline: none;
+      box-shadow: 0 0 0 3px color-mix(in srgb, var(--frame-accent) 55%, transparent);
     }
 
     .thumb-wrap {
       position: relative;
-      width: 160px;
-      height: 100px;
+      width: 100%;
+      height: auto;
+      aspect-ratio: 2 / 1;
       border-radius: var(--snapshot-nav-list-radius-sm, 7px);
-      flex-shrink: 0;
+      box-shadow: inset 0 0 0 1px color-mix(in srgb, currentColor 12%, transparent);
+      background: color-mix(in srgb, currentColor 4%, transparent);
+      display: grid;
+      place-items: center;
       overflow: hidden;
-      box-shadow: inset 0 0 0 1px color-mix(in srgb, currentColor 16%, transparent);
-    }
-    /* signature: registration-mark corners, like a photo mount */
-    .thumb-wrap::before,
-    .thumb-wrap::after {
-      content: '';
-      position: absolute;
-      width: 9px;
-      height: 9px;
-      pointer-events: none;
-      opacity: 0;
-      transition: opacity 0.15s ease;
-      z-index: 2;
-    }
-    .thumb-wrap::before {
-      top: 4px;
-      left: 4px;
-      border-top: 2px solid var(--frame-accent);
-      border-left: 2px solid var(--frame-accent);
-    }
-    .thumb-wrap::after {
-      bottom: 4px;
-      right: 4px;
-      border-bottom: 2px solid var(--frame-accent);
-      border-right: 2px solid var(--frame-accent);
-    }
-    li:hover .thumb-wrap::before,
-    li:hover .thumb-wrap::after,
-    li:focus-visible .thumb-wrap::before,
-    li:focus-visible .thumb-wrap::after {
-      opacity: 1;
     }
 
     .thumb {
@@ -145,7 +113,8 @@ export class SnapshotNavList extends LitElement {
       display: block;
     }
     img.thumb {
-      object-fit: cover;
+      /* contain, not cover — the whole preview stays readable, nothing cropped */
+      object-fit: contain;
       object-position: center;
       background: transparent;
     }
@@ -198,41 +167,27 @@ export class SnapshotNavList extends LitElement {
       }
     }
 
-    /* independent from .meta's tint — image-overlay-opacity defaults to 0 so the image stays clear (blur only) */
-    .image-overlay {
-      position: absolute;
-      inset: 0;
-      background: var(--overlay-bg, transparent);
-      backdrop-filter: blur(var(--overlay-blur, 0px));
-      -webkit-backdrop-filter: blur(var(--overlay-blur, 0px));
-      pointer-events: none;
-    }
-    /* the overlay exists so a tile's overlaid title stays legible — list
-       variant shows the label beside the thumb, not on top of it, so the
-       tint has nothing to do there. */
-    :host(:not([variant='tile'])) .image-overlay {
-      display: none;
-    }
-
     .meta {
       display: flex;
       flex-direction: column;
-      gap: 0.15rem;
+      gap: 0.25rem;
       min-width: 0;
+      padding: 0.75rem 0.5rem 0.5rem;
     }
     .label {
       overflow: hidden;
       text-overflow: ellipsis;
-      white-space: nowrap;
+      white-space: normal;
       color: inherit;
-      font-weight: 500;
+      font-weight: 600;
+      font-size: 1rem;
     }
     .description {
       overflow: hidden;
       text-overflow: ellipsis;
-      white-space: nowrap;
+      white-space: normal;
       color: color-mix(in srgb, currentColor 60%, transparent);
-      font-size: 0.75rem;
+      font-size: 0.8125rem;
     }
 
     .edit-button {
@@ -275,18 +230,15 @@ export class SnapshotNavList extends LitElement {
       fill: currentColor;
     }
 
-    /* Transparent by default (display: contents) so the existing per-variant
-       .label/.meta rules — including icon-only's absolute caption strip —
-       keep applying unchanged; it only becomes a real row when the edit
-       button moves in beside the title. */
+    /* Transparent by default (display: contents) so .label/.meta keep applying
+       unchanged; it only becomes a real row when the edit button moves in
+       beside the title. */
     .label-row {
       display: contents;
     }
     /* edit-button-position="meta": button on the title's line, description
-       still on its own line underneath. Not offered for icon-only, whose
-       .meta is an absolutely positioned overlay strip — the overlay button is
-       already the right place there. */
-    :host([edit-button-position='meta']:not([variant='icon-only'])) .label-row {
+       still on its own line underneath. */
+    :host([edit-button-position='meta']) .label-row {
       display: flex;
       align-items: center;
       gap: 0.5rem;
@@ -295,11 +247,11 @@ export class SnapshotNavList extends LitElement {
     /* the title takes the whole row so the button lands on the card's right
        edge, still on the title's own line (the description sits below it);
        min-width: 0 keeps a long title ellipsising instead of pushing out. */
-    :host([edit-button-position='meta']:not([variant='icon-only'])) .label {
+    :host([edit-button-position='meta']) .label {
       flex: 1;
       min-width: 0;
     }
-    :host([edit-button-position='meta']:not([variant='icon-only'])) .edit-button {
+    :host([edit-button-position='meta']) .edit-button {
       position: static;
       flex-shrink: 0;
       /* in-flow, over the host's own background: currentColor-derived instead
@@ -309,132 +261,9 @@ export class SnapshotNavList extends LitElement {
       color: inherit;
       opacity: 1;
     }
-    :host([edit-button-position='meta']:not([variant='icon-only'])) .edit-button:hover {
+    :host([edit-button-position='meta']) .edit-button:hover {
       background: color-mix(in srgb, currentColor 20%, transparent);
     }
-
-    /* list: a compact thumb reads better in a narrow sidebar than the grid's 160x100 */
-    :host([variant='list']) .thumb-wrap {
-      width: 108px;
-      height: 68px;
-    }
-
-    /* tile: contact-sheet grid, caption strip pinned to the bottom of each frame */
-    :host([variant='tile']) ul {
-      flex-direction: row;
-      flex-wrap: wrap;
-      gap: 0.6rem;
-    }
-    :host([variant='tile']) li {
-      position: relative;
-      width: var(--snapshot-nav-list-tile-width, 160px);
-      height: var(--snapshot-nav-list-tile-height, 100px);
-      padding: 0;
-      overflow: hidden;
-    }
-    :host([variant='tile']) .thumb-wrap {
-      width: 100%;
-      height: 100%;
-      border-radius: var(--snapshot-nav-list-radius, 10px);
-    }
-    :host([variant='tile']) .meta {
-      position: absolute;
-      inset: auto 0 0 0;
-      margin: var(--snapshot-nav-list-overlay-margin, 0);
-      border-radius: var(--snapshot-nav-list-overlay-radius, 0);
-      align-items: flex-start;
-      gap: 0.15rem;
-      padding: 0.4rem 0.5rem;
-      color: var(--overlay-text, #fff);
-      background: var(--overlay-bg, transparent);
-      backdrop-filter: blur(var(--overlay-blur, 0px));
-      -webkit-backdrop-filter: blur(var(--overlay-blur, 0px));
-    }
-    :host([variant='tile']) .label {
-      white-space: normal;
-    }
-    :host([variant='tile']) .description {
-      color: color-mix(in srgb, var(--overlay-text, #fff) 75%, transparent);
-    }
-
-    /* label-position="center": title big and centered */
-    :host([variant='tile'][label-position='center']) .meta {
-      inset: 0;
-      align-items: center;
-      justify-content: center;
-      padding: 0.6rem;
-    }
-    :host([variant='tile'][label-position='center']) .label {
-      font-size: 1.15rem;
-      font-weight: 600;
-      text-align: center;
-    }
-
-    /* card: a contained (never cropped) preview above real body text below it —
-       text never sits on top of the image, so unlike a tile it needs no
-       overlay tint to stay legible. Modeled on a typical "preview card"
-       pattern: framed shot, title + description underneath, shadow on hover. */
-    :host([variant='card']) ul {
-      display: grid;
-      grid-template-columns: repeat(auto-fill, minmax(var(--snapshot-nav-list-card-min-width, 220px), 1fr));
-      gap: var(--snapshot-nav-list-card-gap, 1.25rem);
-    }
-    :host([variant='card']) li {
-      flex-direction: column;
-      align-items: stretch;
-      gap: 0;
-      padding: var(--snapshot-nav-list-card-padding, 0.5rem);
-      background: var(--snapshot-nav-list-card-bg, transparent);
-      border: 1px solid color-mix(in srgb, currentColor 12%, transparent);
-      box-shadow: none;
-      transition:
-        box-shadow var(--snapshot-nav-list-card-transition-dur, 0.15s) ease,
-        border-color var(--snapshot-nav-list-card-transition-dur, 0.15s) ease;
-    }
-    :host([variant='card']) li:hover,
-    :host([variant='card']) li:focus-visible {
-      background: var(--snapshot-nav-list-card-bg, transparent);
-      box-shadow: var(--snapshot-nav-list-card-shadow, 0 2px 8px color-mix(in srgb, currentColor 18%, transparent));
-      border-color: color-mix(in srgb, currentColor 22%, transparent);
-    }
-    :host([variant='card']) li:focus-visible {
-      outline: none;
-      box-shadow: 0 0 0 3px color-mix(in srgb, var(--frame-accent) 55%, transparent);
-    }
-    :host([variant='card']) li:focus-visible .thumb-wrap {
-      outline: none;
-    }
-    :host([variant='card']) .thumb-wrap {
-      width: 100%;
-      height: auto;
-      aspect-ratio: 2 / 1;
-      border-radius: var(--snapshot-nav-list-radius-sm, 7px);
-      box-shadow: inset 0 0 0 1px color-mix(in srgb, currentColor 12%, transparent);
-      background: color-mix(in srgb, currentColor 4%, transparent);
-      display: grid;
-      place-items: center;
-    }
-    :host([variant='card']) .thumb-wrap::before,
-    :host([variant='card']) .thumb-wrap::after {
-      display: none;
-    }
-    :host([variant='card']) img.thumb {
-      /* contain, not cover — the whole dashboard stays readable, nothing cropped */
-      object-fit: contain;
-    }
-    :host([variant='card']) .meta {
-      padding: 0.75rem 0.5rem 0.5rem;
-      gap: 0.25rem;
-    }
-    :host([variant='card']) .label {
-      white-space: normal;
-      font-size: 1rem;
-      font-weight: 600;
-    }
-    :host([variant='card']) .description {
-      white-space: normal;
-      font-size: 0.8125rem;
-    }
   `; }
     fetchKey(variant, id) {
         return `${variant ?? ''}\0${id}`;
@@ -479,11 +308,6 @@ export class SnapshotNavList extends LitElement {
     // update instead of triggering Lit's "update scheduled from updated()"
     // warning that came from doing this same flip inside updated().
     willUpdate(changed) {
-        // 'icon-only' is the pre-0.3 name for 'tile'. Normalising here (rather
-        // than in a setter) keeps the reflected attribute — and therefore every
-        // CSS selector — on the one canonical value.
-        if (this.variant === 'icon-only')
-            this.variant = 'tile';
         // A variant-key switch (e.g. light -> dark) invalidates every thumbnail:
         // they're separate snapshots under separate keys.
         if (changed.has('variantKey'))
@@ -544,27 +368,6 @@ export class SnapshotNavList extends LitElement {
             this.requestUpdate();
         }
     }
-    /** image scrim: blur + its own (usually 0) tint strength — independent of the caption's. */
-    get imageOverlayStyle() {
-        const blur = `${this.overlayBlur}px`;
-        if (this.overlayTint === 'none' || this.imageOverlayOpacity === 0) {
-            return { '--overlay-blur': blur };
-        }
-        const tintColor = this.overlayTint === 'light' ? '#fff' : '#000';
-        const bg = `color-mix(in srgb, ${tintColor} ${Math.round(this.imageOverlayOpacity * 100)}%, transparent)`;
-        return { '--overlay-bg': bg, '--overlay-blur': blur };
-    }
-    /** caption background: tint (to pop the text) + the same blur. */
-    get metaStyle() {
-        const blur = `${this.overlayBlur}px`;
-        if (this.overlayTint === 'none') {
-            return { '--overlay-bg': 'transparent', '--overlay-text': 'inherit', '--overlay-blur': blur };
-        }
-        const tintColor = this.overlayTint === 'light' ? '#fff' : '#000';
-        const bg = `color-mix(in srgb, ${tintColor} ${Math.round(this.textOverlayOpacity * 100)}%, transparent)`;
-        const text = this.overlayTint === 'light' ? '#111' : '#fff';
-        return { '--overlay-bg': bg, '--overlay-text': text, '--overlay-blur': blur };
-    }
     // Both events carry the whole item — including `data` — so a handler never
     // has to look the item back up by id.
     select(item) {
@@ -590,11 +393,7 @@ export class SnapshotNavList extends LitElement {
     </button>`;
     }
     render() {
-        const imageOverlayStyle = this.imageOverlayStyle;
-        const metaStyle = this.metaStyle;
-        // icon-only's caption is itself an overlay strip on the image, so there's
-        // no in-flow text row to put the button in — fall back to the overlay.
-        const editInMeta = this.editButtonPosition === 'meta' && this.variant !== 'icon-only';
+        const editInMeta = this.editButtonPosition === 'meta';
         return html `
       <ul role="listbox">
         ${this.items.map((item) => html `
@@ -617,10 +416,9 @@ export class SnapshotNavList extends LitElement {
                           >${item.icon ? (isMarkupIcon(item.icon) ? unsafeHTML(item.icon) : item.icon) : ''}</span
                         >
                       </div>`}
-                <div class="image-overlay" part="overlay" style=${styleMap(imageOverlayStyle)}></div>
                 ${this.isEditable(item) && !editInMeta ? this.renderEditButton(item) : ''}
               </div>
-              <div class="meta" part="meta" style=${styleMap(metaStyle)}>
+              <div class="meta" part="meta">
                 <div class="label-row" part="label-row">
                   <span class="label" part="label">${item.label}</span>
                   ${this.isEditable(item) && editInMeta ? this.renderEditButton(item) : ''}
@@ -636,30 +434,12 @@ export class SnapshotNavList extends LitElement {
 __decorate([
     property({ type: Array })
 ], SnapshotNavList.prototype, "items", void 0);
-__decorate([
-    property({ reflect: true })
-], SnapshotNavList.prototype, "variant", void 0);
 __decorate([
     property({ attribute: 'variant-key' })
 ], SnapshotNavList.prototype, "variantKey", void 0);
 __decorate([
     property({ type: Boolean, reflect: true })
 ], SnapshotNavList.prototype, "scrollable", void 0);
-__decorate([
-    property({ attribute: 'overlay-tint' })
-], SnapshotNavList.prototype, "overlayTint", void 0);
-__decorate([
-    property({ type: Number, attribute: 'text-overlay-opacity' })
-], SnapshotNavList.prototype, "textOverlayOpacity", void 0);
-__decorate([
-    property({ type: Number, attribute: 'image-overlay-opacity' })
-], SnapshotNavList.prototype, "imageOverlayOpacity", void 0);
-__decorate([
-    property({ type: Number, attribute: 'overlay-blur' })
-], SnapshotNavList.prototype, "overlayBlur", void 0);
-__decorate([
-    property({ reflect: true, attribute: 'label-position' })
-], SnapshotNavList.prototype, "labelPosition", void 0);
 __decorate([
     property({ attribute: false })
 ], SnapshotNavList.prototype, "snapshotService", void 0);

package/dist/snapshot-service.d.ts

@@ -35,7 +35,77 @@ export interface CaptureOptions extends VariantOptions {
     scale?: number;
     /** Per-call override of the instance `encode`. */
     encode?: EncodeOptions;
+    /**
+     * Passed straight through to html2canvas: called with the cloned document
+     * (and the clone of `el`) it's about to render, before it renders it. The
+     * escape hatch for anything that needs to touch the clone specifically. A
+     * returned promise is awaited.
+     */
+    onclone?: (document: Document, element: HTMLElement) => void | Promise<void>;
+    /**
+     * Target output size in CSS px. Required to use `fit`; ignored otherwise.
+     */
+    width?: number;
+    height?: number;
+    /**
+     * How to fit `el`'s content into `width`×`height`:
+     * - `'contain'` — scale to fit entirely inside the box, letterboxed (filled
+     *   with `background`) if the aspect ratio doesn't match.
+     * - `'cover'` — scale to fill the box, cropping the overflow, centered.
+     *   Upscales content smaller than the target — this is a thumbnail, not a
+     *   lossless copy.
+     *
+     * Implemented by cloning `el` off-screen into a `width`×`height` frame and
+     * capturing that instead, so it works the same for any caller — no
+     * framework-specific lifetime handling. `contentCrop` defaults to `false`
+     * whenever `fit` is set, since the frame is already the exact requested
+     * size.
+     */
+    fit?: 'contain' | 'cover';
+    /** Fill color behind letterboxing or undersized content. Defaults to html2canvas's own default (white). */
+    background?: string;
+    /**
+     * Every capture crops to the bounding box of `el`'s visible children (see
+     * `CONTENT_PADDING`), so a container much bigger than its content doesn't
+     * capture as mostly empty space. Pass `false` to capture `el` at its own
+     * full size instead — needed for exact, pre-sized output (`fit` does this
+     * automatically).
+     */
+    contentCrop?: boolean;
+    /**
+     * Rewrites resolved `oklch()`/`oklab()` colors (anywhere in the document,
+     * not just `el`) to `hsl()` for the duration of the capture, then restores
+     * them. html2canvas can't parse either function, and `getComputedStyle`
+     * resolves a growing share of ordinary CSS to one of them regardless of
+     * how the color was authored — Tailwind v4's default palette included.
+     * Off by default: it's a full-document style walk plus an on-demand import
+     * of `colorjs.io`, so only pay for it on a page that actually hits this.
+     */
+    neutralizeColors?: boolean;
 }
+/**
+ * The padding (in CSS px) applied around the bounding box of `el`'s visible
+ * children when the default content-crop runs — see `CaptureOptions.contentCrop`.
+ */
+export declare const CONTENT_PADDING = 16;
+/**
+ * Scale + centered-crop-offset for fitting a `natural` box into a `target`
+ * box. `'cover'` uses `Math.max` (fills the target, overflow gets cropped,
+ * offsets can go negative to center that overflow); `'contain'` uses
+ * `Math.min` (fits entirely inside, offsets are never negative — the
+ * shortfall is left for the caller to fill as letterboxing).
+ */
+export declare function computeFit(natural: {
+    width: number;
+    height: number;
+}, target: {
+    width: number;
+    height: number;
+}, fit: 'contain' | 'cover'): {
+    scale: number;
+    offsetX: number;
+    offsetY: number;
+};
 export declare class SnapshotService {
     private storage;
     private scale;

package/dist/snapshot-service.js

@@ -1,7 +1,12 @@
 import { encodeSnapshot } from './encode';
 import { SnapshotDetachedElementError, SnapshotRenderError, SnapshotTaintedCanvasError } from './errors';
+import { neutralizeOklchColors } from './neutralize-oklch';
 import { IndexedDbSnapshotStorage } from './snapshot-storage';
-const CONTENT_PADDING = 16;
+/**
+ * The padding (in CSS px) applied around the bounding box of `el`'s visible
+ * children when the default content-crop runs — see `CaptureOptions.contentCrop`.
+ */
+export const CONTENT_PADDING = 16;
 const VARIANT_SEPARATOR = '@';
 // Tracks keyPrefixes already claimed by a live SnapshotService instance, so
 // two instances that both forget to set one (or pick the same one) get a
@@ -45,6 +50,57 @@ function getContentBounds(el) {
         return full;
     return { x, y, width, height };
 }
+/**
+ * Scale + centered-crop-offset for fitting a `natural` box into a `target`
+ * box. `'cover'` uses `Math.max` (fills the target, overflow gets cropped,
+ * offsets can go negative to center that overflow); `'contain'` uses
+ * `Math.min` (fits entirely inside, offsets are never negative — the
+ * shortfall is left for the caller to fill as letterboxing).
+ */
+export function computeFit(natural, target, fit) {
+    const scale = fit === 'cover'
+        ? Math.max(target.width / natural.width, target.height / natural.height)
+        : Math.min(target.width / natural.width, target.height / natural.height);
+    const scaledWidth = natural.width * scale;
+    const scaledHeight = natural.height * scale;
+    return {
+        scale,
+        offsetX: (scaledWidth - target.width) / 2,
+        offsetY: (scaledHeight - target.height) / 2,
+    };
+}
+/**
+ * Clones `el` into an off-screen `width`×`height` frame, scaled per `fit`
+ * and centered. Returns the frame (to capture instead of `el`) and a cleanup
+ * that removes it from the document — always call it, capture or not.
+ */
+function buildFitFrame(el, width, height, fit, background) {
+    const naturalWidth = el.scrollWidth;
+    const naturalHeight = el.scrollHeight;
+    const frame = document.createElement('div');
+    frame.style.position = 'fixed';
+    frame.style.top = '0';
+    frame.style.left = '-99999px';
+    frame.style.width = `${width}px`;
+    frame.style.height = `${height}px`;
+    frame.style.overflow = 'hidden';
+    if (background)
+        frame.style.background = background;
+    if (naturalWidth > 0 && naturalHeight > 0) {
+        const { scale, offsetX, offsetY } = computeFit({ width: naturalWidth, height: naturalHeight }, { width, height }, fit);
+        const clone = el.cloneNode(true);
+        clone.style.position = 'absolute';
+        clone.style.top = `${-offsetY}px`;
+        clone.style.left = `${-offsetX}px`;
+        clone.style.transformOrigin = 'top left';
+        clone.style.transform = `scale(${scale})`;
+        clone.style.width = `${naturalWidth}px`;
+        clone.style.height = `${naturalHeight}px`;
+        frame.appendChild(clone);
+    }
+    document.body.appendChild(frame);
+    return { frame, cleanup: () => frame.remove() };
+}
 export class SnapshotService {
     constructor(config = {}) {
         this.listeners = new Set();
@@ -130,14 +186,30 @@ export class SnapshotService {
         // storing a blank thumbnail over a good one.
         if (!el.isConnected)
             throw new SnapshotDetachedElementError(key.id);
-        const crop = getContentBounds(el);
+        const useFit = opts.width !== undefined && opts.height !== undefined && opts.fit !== undefined;
+        const fitFrame = useFit
+            ? buildFitFrame(el, opts.width, opts.height, opts.fit, opts.background)
+            : undefined;
+        const target = fitFrame?.frame ?? el;
+        // `fit` already produced an exactly-sized frame — the default content-crop
+        // would only fight that (see CaptureOptions.contentCrop), so it's off by
+        // default here unless the caller explicitly asks for it back.
+        const contentCrop = opts.contentCrop ?? !useFit;
+        const crop = contentCrop
+            ? getContentBounds(target)
+            : useFit
+                // Known exactly — no need to round-trip through layout (`clientWidth`)
+                // for the one size `buildFitFrame` was already asked to produce.
+                ? { x: 0, y: 0, width: opts.width, height: opts.height }
+                : { x: 0, y: 0, width: target.clientWidth, height: target.clientHeight };
+        const restoreColors = opts.neutralizeColors ? await neutralizeOklchColors(document.documentElement) : undefined;
         // Imported on demand so `import '@anton-gustafsson/snapshot-core'` doesn't
         // pull a DOM-only dependency into a Node/SSR/Jest process that only wants
         // the types or a storage.
         const { default: html2canvas } = await import('html2canvas');
         let canvas;
         try {
-            canvas = await html2canvas(el, {
+            canvas = await html2canvas(target, {
                 scale: opts.scale ?? this.scale,
                 logging: false,
                 useCORS: true,
@@ -145,12 +217,17 @@ export class SnapshotService {
                 y: crop.y,
                 width: crop.width,
                 height: crop.height,
+                onclone: opts.onclone,
             });
         }
         catch (err) {
             // errors.ts documents every rejection from this library as a SnapshotError.
             throw new SnapshotRenderError(key.id, err);
         }
+        finally {
+            restoreColors?.();
+            fitFrame?.cleanup();
+        }
         const raw = await new Promise((resolve, reject) => canvas.toBlob((b) => (b ? resolve(b) : reject(new SnapshotTaintedCanvasError(key.id))), 'image/png'));
         const encode = opts.encode ?? this.encode;
         const blob = encode ? await encodeSnapshot(raw, encode) : raw;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anton-gustafsson/snapshot-core",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A pluggable snapshot service that turns any DOM element into a stored, shareable image, plus an optional <snapshot-nav-list> web component to display them.",
   "license": "MIT",
   "repository": {
@@ -24,9 +24,10 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "lit": "^3.2.0",
+    "colorjs.io": "^0.7.1",
     "html2canvas": "^1.4.1",
-    "idb-keyval": "^6.2.1"
+    "idb-keyval": "^6.2.1",
+    "lit": "^3.2.0"
   },
   "devDependencies": {
     "jsdom": "^28.0.0",