@anton-gustafsson/snapshot-core 0.4.2 → 0.4.4

package/dist/index.d.ts

@@ -4,5 +4,3 @@ export * from './snapshot-storage';
 export * from './cached-snapshot-storage';
 export * from './encode';
 export * from './errors';
-export * from './neutralize-oklch';
-export * from './wait-for-canvases-to-paint';

package/dist/index.js

@@ -4,5 +4,3 @@ export * from './snapshot-storage';
 export * from './cached-snapshot-storage';
 export * from './encode';
 export * from './errors';
-export * from './neutralize-oklch';
-export * from './wait-for-canvases-to-paint';

package/dist/neutralize-oklch.d.ts

@@ -1,4 +1,9 @@
 /**
+ * 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
@@ -9,13 +14,12 @@
  * in that space), so anything animating a color at capture time needs the
  * same treatment.
  *
- * Call this on the *live* document, before `capture()` — not just on the
- * element being captured. html2canvas clones the whole document (for
- * correct ancestor stacking/background), not only the target element, so a
- * descendant can still inherit or otherwise resolve through an ancestor this
- * call never touched if `root` is scoped too narrowly; `document.documentElement`
- * is the safe default. Restore once the capture settles — this rewrites
- * real inline styles on the live page, visibly if left in place.
+ * 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

package/dist/neutralize-oklch.js

@@ -1,5 +1,10 @@
 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
@@ -10,13 +15,12 @@ const OKLCH_PATTERN = /okl(?:ch|ab)\([^)]*\)/gi;
  * in that space), so anything animating a color at capture time needs the
  * same treatment.
  *
- * Call this on the *live* document, before `capture()` — not just on the
- * element being captured. html2canvas clones the whole document (for
- * correct ancestor stacking/background), not only the target element, so a
- * descendant can still inherit or otherwise resolve through an ancestor this
- * call never touched if `root` is scoped too narrowly; `document.documentElement`
- * is the safe default. Restore once the capture settles — this rewrites
- * real inline styles on the live page, visibly if left in place.
+ * 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

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

@@ -4,8 +4,10 @@ export interface NavItem<T = unknown> {
     /** The snapshot id — a plain domain id. Anything else the consumer needs belongs in `data`. */
     id: string;
     label: string;
-    /** A plain-text glyph (e.g. an emoji), or markup — a string starting with `<` renders as raw HTML/SVG instead of text, so a consumer can pass its own icon (e.g. `<svg>...</svg>`). Only the placeholder frame shown before a card's first capture. */
+    /** Markup — `<svg>`, `<img>`, or any element — rendered as raw HTML in the placeholder frame shown before a card's first capture. Must start with `<`: a bare glyph or emoji is ignored (it read as an icon but rendered as a stray character at whatever the frame's font happened to be); use `placeholderText` for words. */
     icon?: string;
+    /** Per-item override of the component-level `placeholderText` — a caption in the frame shown before this card's first capture (e.g. "not visited yet"). Plain text only; pass `''` to show none where the component sets one. */
+    placeholderText?: string;
     description?: string;
     /** Arbitrary consumer payload — echoed back verbatim on `nav-select` / `nav-edit`, so no lookup-by-id is needed in the handler. */
     data?: T;
@@ -14,21 +16,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,24 +34,22 @@ 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;
+    /**
+     * Caption shown in the frame of a card with no capture yet (e.g. "no snapshot
+     * yet"), for every card at once; `NavItem.placeholderText` overrides it per
+     * row. Plain text, never markup — it's rendered as text, not HTML. Empty by
+     * default, which keeps the icon-and-hatch placeholder; set it and the frame
+     * goes see-through with a dashed edge instead.
+     */
+    placeholderText: string;
     private thumbs;
     private loadingIds;
     /**
@@ -80,14 +75,12 @@ 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;
     private renderEditButton;
+    /** The frame before a card's first capture: an icon, a caption, or both. */
+    private renderPlaceholder;
     render(): import("lit-html").TemplateResult<1>;
 }
 /** Detail type of both `nav-select` and `nav-edit` — the clicked item itself. */

package/dist/snapshot-nav-list.js

@@ -6,45 +6,55 @@ 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) {
     return icon.trimStart().startsWith('<');
 }
+const warnedTextIcons = new Set();
+/**
+ * `NavItem.icon` is markup-only, so a plain-text glyph renders as nothing —
+ * silently, without this, since the old behavior was to paint it as text.
+ * Warns once per distinct value: `items` re-renders on every thumbnail that
+ * lands, and a whole list of glyph icons would otherwise flood the console.
+ */
+function markupIconOrWarn(icon) {
+    if (isMarkupIcon(icon))
+        return icon;
+    if (!warnedTextIcons.has(icon)) {
+        warnedTextIcons.add(icon);
+        console.warn(`<snapshot-nav-list>: NavItem.icon takes markup (e.g. '<svg>...</svg>'), not text — ignoring ${JSON.stringify(icon)}. Use placeholderText for a caption.`);
+    }
+    return undefined;
+}
 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;
+        /**
+         * Caption shown in the frame of a card with no capture yet (e.g. "no snapshot
+         * yet"), for every card at once; `NavItem.placeholderText` overrides it per
+         * row. Plain text, never markup — it's rendered as text, not HTML. Empty by
+         * default, which keeps the icon-and-hatch placeholder; set it and the frame
+         * goes see-through with a dashed edge instead.
+         */
+        this.placeholderText = '';
         this.thumbs = new Map();
         this.loadingIds = new Set();
         /**
@@ -77,66 +87,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,34 +137,82 @@ 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;
     }
     /* unexposed frame: fine diagonal hatch instead of a generic gradient blob */
     .thumb-placeholder {
+      box-sizing: border-box;
       display: flex;
+      flex-direction: column;
       align-items: center;
       justify-content: center;
-      background-color: color-mix(in srgb, currentColor 7%, transparent);
-      background-image: repeating-linear-gradient(
-        135deg,
-        color-mix(in srgb, currentColor 16%, transparent) 0px,
-        color-mix(in srgb, currentColor 16%, transparent) 1.5px,
-        transparent 1.5px,
-        transparent 7px
+      gap: 0.4rem;
+      padding: 0.45rem 0;
+      background-color: var(--snapshot-nav-list-placeholder-bg, color-mix(in srgb, currentColor 7%, transparent));
+      /* var-driven so a plain 'none' turns the hatch off on its own — a card
+         showing real fallback art wants the frame plain behind it. */
+      background-image: var(
+        --snapshot-nav-list-placeholder-hatch,
+        repeating-linear-gradient(
+          135deg,
+          color-mix(in srgb, currentColor 16%, transparent) 0px,
+          color-mix(in srgb, currentColor 16%, transparent) 1.5px,
+          transparent 1.5px,
+          transparent 7px
+        )
       );
     }
+    /* A caption carries the "nothing here yet" meaning on its own, so the hatch
+       (and the tint under it) would only fight it — the frame goes see-through,
+       marked out by a dashed edge instead. */
+    .thumb-placeholder.has-text {
+      background-color: var(--snapshot-nav-list-placeholder-bg, transparent);
+      background-image: none;
+      border: 1px dashed var(--snapshot-nav-list-placeholder-border, color-mix(in srgb, currentColor 22%, transparent));
+      border-radius: inherit;
+    }
+    .placeholder-text {
+      font-family: var(--snapshot-nav-list-placeholder-font, ui-monospace, SFMono-Regular, Menlo, monospace);
+      font-size: var(--snapshot-nav-list-placeholder-font-size, 0.75rem);
+      letter-spacing: var(--snapshot-nav-list-placeholder-letter-spacing, 0.02em);
+      color: var(--snapshot-nav-list-placeholder-color, color-mix(in srgb, currentColor 55%, transparent));
+      max-width: 100%;
+      padding: 0 0.5rem;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      text-align: center;
+    }
+    /* Spans the frame (minus the caption, if any) rather than shrinking to the
+       glyph: a percentage width/height on a fallback <img> then has a real box
+       to resolve against, while a default-sized icon still sits centered. */
     .icon-lg {
-      font-size: 1.6rem;
-      opacity: 0.4;
+      flex: 1 1 auto;
+      min-height: 0;
+      width: 100%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      opacity: var(--snapshot-nav-list-placeholder-icon-opacity, 0.4);
+    }
+    /* Sized off one var so a card using a real fallback image (rather than a
+       small glyph-sized icon) can grow it to fill the frame from outside the
+       shadow root. */
+    .icon-lg svg,
+    .icon-lg img {
+      width: var(--snapshot-nav-list-placeholder-icon-size, 1.6rem);
+      height: var(--snapshot-nav-list-placeholder-icon-size, 1.6rem);
+      display: block;
     }
     .icon-lg svg {
-      width: 1.6rem;
-      height: 1.6rem;
-      display: block;
       fill: currentColor;
     }
+    .icon-lg img {
+      object-fit: var(--snapshot-nav-list-placeholder-icon-fit, contain);
+    }
     .thumb-loading {
       display: flex;
       align-items: center;
@@ -198,41 +238,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 +301,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 +318,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 +332,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 +379,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 +439,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) {
@@ -589,12 +463,17 @@ export class SnapshotNavList extends LitElement {
       ${isMarkupIcon(icon) ? unsafeHTML(icon) : icon}
     </button>`;
     }
+    /** The frame before a card's first capture: an icon, a caption, or both. */
+    renderPlaceholder(item) {
+        const text = item.placeholderText ?? this.placeholderText;
+        const icon = item.icon ? markupIconOrWarn(item.icon) : undefined;
+        return html `<div class="thumb thumb-placeholder ${text ? 'has-text' : ''}" part="thumb" aria-hidden="true">
+      ${icon ? html `<span class="icon-lg" part="placeholder-icon">${unsafeHTML(icon)}</span>` : ''}
+      ${text ? html `<span class="placeholder-text" part="placeholder-text">${text}</span>` : ''}
+    </div>`;
+    }
     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 `
@@ -612,15 +491,10 @@ export class SnapshotNavList extends LitElement {
                 ? html `<div class="thumb thumb-loading" part="thumb" aria-hidden="true">
                         <span class="spinner" part="spinner"></span>
                       </div>`
-                : html `<div class="thumb thumb-placeholder" part="thumb" aria-hidden="true">
-                        <span class="icon-lg"
-                          >${item.icon ? (isMarkupIcon(item.icon) ? unsafeHTML(item.icon) : item.icon) : ''}</span
-                        >
-                      </div>`}
-                <div class="image-overlay" part="overlay" style=${styleMap(imageOverlayStyle)}></div>
+                : this.renderPlaceholder(item)}
                 ${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 +510,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);
@@ -672,6 +528,9 @@ __decorate([
 __decorate([
     property({ attribute: 'edit-icon' })
 ], SnapshotNavList.prototype, "editIcon", void 0);
+__decorate([
+    property({ attribute: 'placeholder-text' })
+], SnapshotNavList.prototype, "placeholderText", void 0);
 __decorate([
     state()
 ], SnapshotNavList.prototype, "thumbs", void 0);

package/dist/snapshot-service.d.ts

@@ -40,14 +40,72 @@ export interface CaptureOptions extends VariantOptions {
      * (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.
-     *
-     * For colors specifically, prefer `neutralizeOklchColors` called on the
-     * *live* document before `capture()` (see its own docs) — html2canvas
-     * clones the whole document, not just `el`, so a fix scoped to `element`
-     * here can still miss a color a descendant inherits from outside it.
      */
     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,
@@ -152,6 +224,10 @@ export class SnapshotService {
             // 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.2",
+  "version": "0.4.4",
   "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": {

package/dist/wait-for-canvases-to-paint.d.ts

@@ -1,20 +0,0 @@
-/**
- * A `<canvas>`-based chart (Chart.js, and most others) typically paints
- * through its own `ResizeObserver` + `requestAnimationFrame` cycle, entirely
- * decoupled from the framework's own change detection — so the tick-plus-
- * one-frame `injectSnapshotCapture()` waits for can still race a chart's own
- * pending redraw. html2canvas only ever copies whatever is currently in a
- * canvas's pixel buffer, so losing that race produces a capture with a fully
- * blank chart: no error, nothing logged, just an empty rectangle where the
- * chart should be.
- *
- * Polls every `<canvas>` under `root` (one requestAnimationFrame per
- * attempt) until each either has non-transparent pixel data or `maxFrames`
- * is exhausted, whichever comes first. Best-effort: a canvas that's still
- * blank after `maxFrames` is left as-is rather than blocking the capture
- * indefinitely — a bad thumbnail isn't worth stalling navigation over. Call
- * this before `capture()`, on the live element (unlike `neutralizeOklchColors`,
- * which needs the clone — this needs the canvas that's actually still
- * painting).
- */
-export declare function waitForCanvasesToPaint(root: HTMLElement, maxFrames?: number): Promise<void>;

package/dist/wait-for-canvases-to-paint.js

@@ -1,53 +0,0 @@
-/**
- * A `<canvas>`-based chart (Chart.js, and most others) typically paints
- * through its own `ResizeObserver` + `requestAnimationFrame` cycle, entirely
- * decoupled from the framework's own change detection — so the tick-plus-
- * one-frame `injectSnapshotCapture()` waits for can still race a chart's own
- * pending redraw. html2canvas only ever copies whatever is currently in a
- * canvas's pixel buffer, so losing that race produces a capture with a fully
- * blank chart: no error, nothing logged, just an empty rectangle where the
- * chart should be.
- *
- * Polls every `<canvas>` under `root` (one requestAnimationFrame per
- * attempt) until each either has non-transparent pixel data or `maxFrames`
- * is exhausted, whichever comes first. Best-effort: a canvas that's still
- * blank after `maxFrames` is left as-is rather than blocking the capture
- * indefinitely — a bad thumbnail isn't worth stalling navigation over. Call
- * this before `capture()`, on the live element (unlike `neutralizeOklchColors`,
- * which needs the clone — this needs the canvas that's actually still
- * painting).
- */
-export async function waitForCanvasesToPaint(root, maxFrames = 6) {
-    const canvases = Array.from(root.querySelectorAll('canvas'));
-    if (canvases.length === 0)
-        return;
-    for (let frame = 0; frame < maxFrames; frame++) {
-        if (canvases.every((canvas) => !isBlank(canvas)))
-            return;
-        await new Promise((resolve) => requestAnimationFrame(() => resolve()));
-    }
-}
-function isBlank(canvas) {
-    if (canvas.width === 0 || canvas.height === 0)
-        return false;
-    try {
-        // Only 2D canvases can be cheaply inspected this way — a WebGL canvas
-        // with `preserveDrawingBuffer: false` reads back as empty regardless of
-        // what's on screen, so treat anything non-2D as "can't tell, assume it's
-        // fine" rather than waiting forever.
-        const ctx = canvas.getContext('2d');
-        if (!ctx)
-            return false;
-        const data = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
-        for (let i = 0; i < data.length; i++) {
-            if (data[i] !== 0)
-                return false;
-        }
-        return true;
-    }
-    catch {
-        // A tainted canvas throws on getImageData — not something this check
-        // can resolve either way, so don't block the capture over it.
-        return false;
-    }
-}