@crewlethq/ui 0.35.1 → 0.37.0

package/dist/Document/Document.d.ts

@@ -1,4 +1,4 @@
-import type { HTMLAttributes, InputHTMLAttributes } from 'react';
+import { type HTMLAttributes, type TextareaHTMLAttributes } from 'react';
 export type DocumentSize = 
 /**
  * A page read on its own: the small step at the relaxed leading, sections at
@@ -61,7 +61,7 @@ export interface DocumentTitleProps extends HTMLAttributes<HTMLHeadingElement> {
  * a size of its own beside the body it heads.
  */
 export declare function DocumentTitle({ as: Tag, className, children, ...rest }: DocumentTitleProps): import("react").JSX.Element;
-export interface DocumentTitleFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
+export interface DocumentTitleFieldProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'rows' | 'cols' | 'wrap'> {
     /** Marks the title as refused. Sets `aria-invalid`, which is what a screen reader reads. */
     error?: boolean | undefined;
 }
@@ -76,5 +76,17 @@ export interface DocumentTitleFieldProps extends Omit<InputHTMLAttributes<HTMLIn
  * danger ink when the title is refused. The name is the caller's
  * (`aria-label`, or a label it points at), because a title field's visible
  * cue is its placeholder, and a placeholder is not a name.
+ *
+ * IT WRAPS, AND IT IS STILL ONE LINE OF TEXT. A title is set in the page's
+ * largest type, and an `<input>` cuts what does not fit: on a phone a long
+ * title, or the example in its placeholder, was clipped mid-word ("Weekly
+ * planning, Octobe"). So it is a textarea of one row that grows with what it
+ * holds, as the title it becomes wraps, and every way it could take a second
+ * line is closed: Enter inserts nothing (its `keydown` reaches the caller and
+ * the page exactly as an input's does, and in a form with a submit button it
+ * submits, as an input's Enter does), and a pasted, dropped or autofilled line
+ * break becomes a space before the caller's `onChange` reads the value. It is
+ * named to assistive technology as a single-line text field
+ * (`aria-multiline="false"`).
  */
-export declare function DocumentTitleField({ error, className, ...rest }: DocumentTitleFieldProps): import("react").JSX.Element;
+export declare const DocumentTitleField: import("react").ForwardRefExoticComponent<DocumentTitleFieldProps & import("react").RefAttributes<HTMLTextAreaElement>>;

package/dist/Document/index.js

@@ -1,2 +1,3 @@
-export { Document, DocumentTitle, DocumentTitleField } from '../chunk-TYKQ33CL.js';
+export { Document, DocumentTitle, DocumentTitleField } from '../chunk-P6WFZDKS.js';
+import '../chunk-YSGLEHND.js';
 import '../chunk-ODEQTPFM.js';

package/dist/{Document-JUGCSQ4L.css → Document-YFWTWXJP.css}

@@ -327,17 +327,34 @@
  * on no surface of its own, with a line along its foot that answers the
  * pointer, the focus and a refusal. The line is a border rather than a
  * shadow, because forced colours keep a border and drop a shadow.
+ *
+ * ONE PIXEL, AND A TINT, WHERE A POINTER PUT THE CARET. The line is the
+ * hairline under the pointer and the selected edge (the accent mixed toward
+ * the page) once a click has put the caret in it: the reader is already
+ * looking at the title, and a page that focuses its title on load drew a 2px
+ * accent bar under it before anybody had touched anything.
+ *
+ * TWO PIXELS IN THE FOCUS COLOUR FOR THE KEYBOARD, the area WCAG 2.2's focus
+ * appearance asks of an indicator: the border takes the focus colour and a
+ * shadow lays the second pixel under it, with a transparent outline that
+ * forced colours paints in its place. The padding takes the pixel the border
+ * no longer reserves, so the title sits where it always did.
  */
 .crewlet-document-title-field {
   display: block;
   width: 100%;
   min-width: 0;
-  padding: 0 0 var(--spacing-1);
+  padding: 0 0 calc(var(--spacing-1) + 1px);
   border: 0;
-  border-block-end: 2px solid transparent;
+  border-block-end: 1px solid transparent;
   border-radius: 0;
   background: none;
   outline: none;
+  /* A textarea of one row that grows with the title (DocumentTitleField sets
+     its height): no handle, no scrollbar, and the title's own wrapping. */
+  resize: none;
+  overflow: hidden;
+  white-space: pre-wrap;
   transition: border-color var(--motion-duration-fast) var(--motion-easing-default);
 }
 
@@ -352,12 +369,27 @@
 
 .crewlet-document-title-field:focus-visible {
   border-block-end-color: var(--color-focus);
+  box-shadow: 0 1px 0 var(--color-focus);
+  outline: 2px solid transparent;
+}
+
+:root[data-crewlet-focus='pointer'] .crewlet-document-title-field:focus-visible {
+  border-block-end-color: var(--color-border-selected);
+  box-shadow: none;
 }
 
 .crewlet-document-title-field[aria-invalid='true'] {
   border-block-end-color: var(--color-feedback-danger);
 }
 
+.crewlet-document-title-field[aria-invalid='true']:focus-visible {
+  box-shadow: 0 1px 0 var(--color-feedback-danger);
+}
+
+:root[data-crewlet-focus='pointer'] .crewlet-document-title-field[aria-invalid='true']:focus-visible {
+  border-block-end-color: var(--color-feedback-danger);
+}
+
 @media (prefers-reduced-motion: reduce) {
   .crewlet-document-title-field {
     transition: none;

package/dist/{Editor-BVQHBF7L.js → Editor-HORWMUM3.js}

@@ -2,7 +2,8 @@ import { richEditorLabels } from './chunk-CSQTDGTS.js';
 import { schema, readMarkdown, writeMarkdown } from './chunk-QH6VYJ3X.js';
 import { safeHref, MARKDOWN_CALLOUT_TONES } from './chunk-BAKPMH3S.js';
 import { Toolbar } from './chunk-PGRPNDWM.js';
-import { FormField, Input } from './chunk-6QFAK2WV.js';
+import { FormField, Input } from './chunk-IUYUS2SO.js';
+import './chunk-YSGLEHND.js';
 import './chunk-PQADV6P6.js';
 import { Menu } from './chunk-BUVCV3WI.js';
 import { placePopup, viewportBounds } from './chunk-OMV5W53A.js';

package/dist/FilterChip/index.js

@@ -1,3 +1,3 @@
-export { FILTER_CHIP_ATTRIBUTE, FilterChip, FilterChipGroup } from '../chunk-5YLON2PW.js';
+export { FILTER_CHIP_ATTRIBUTE, FilterChip, FilterChipGroup } from '../chunk-UYZZV4DZ.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/{FilterChip-EZ4QMW4E.css → FilterChip-VL33P3JL.css}

@@ -81,9 +81,13 @@
   cursor: not-allowed;
 }
 
+/* The selected fill, and the accent's lighter line rather than the selected
+   edge: on a pill this small the 0.6 edge, the fill and the accent ink were
+   three accent marks on one word. The ink is the mark that clears 4.5:1, and
+   the keyboard's 2px focus ring stays the only full-weight line. */
 .crewlet-filter-chip[aria-pressed='true'],
 .crewlet-filter-chip[aria-checked='true'] {
-  background: var(--color-brand-accent-soft);
+  background: var(--color-surface-selected);
   border-color: var(--color-brand-accent-soft-strong);
   color: var(--color-brand-accent-ink);
 }

package/dist/Input/index.js

@@ -1,4 +1,5 @@
-export { FormField, FormRow, FormSection, Input, InputAffix, Label, ReadOnlyField, Textarea } from '../chunk-6QFAK2WV.js';
+export { FormField, FormRow, FormSection, Input, InputAffix, Label, ReadOnlyField, Textarea } from '../chunk-IUYUS2SO.js';
+import '../chunk-YSGLEHND.js';
 import '../chunk-PQADV6P6.js';
 import '../chunk-4FQT6ZAY.js';
 import '../chunk-BZFWDIV6.js';

package/dist/{Input-GBZSFXLU.css → Input-ABGOFENS.css}

@@ -81,14 +81,18 @@
  * forced-colors mode drops every box-shadow and keeps outlines: a ring drawn
  * as a shadow disappears for exactly the readers who most need one.
  *
- * It is ONE PIXEL, LAID EXACTLY ON THE BOUNDARY: the field's own hairline,
- * drawn in the focus colour, which is how the console's fields say focus. At
- * two pixels it was a heavy band round every box a caret landed in, and on a
- * form of them the field being typed in read as the loudest thing on the page.
- * Drawn on the boundary rather than outside it, a scroller cannot clip it and
- * the field does not grow a halo the moment a caret lands in it, which is what
- * a filter box in a toolbar of them did to the row it sits in. Every boxed
- * field in the package rings this way (`Input.test.tsx` holds them to it).
+ * It is TWO PIXELS FOR THE KEYBOARD AND ONE FOR A POINTER, laid over the
+ * boundary. Two pixels is the area WCAG 2.2's focus appearance asks of an
+ * indicator, and one pixel (the field's own hairline in the focus colour) was
+ * half of it for every reader tabbing through a form. But at two pixels round
+ * every box a caret landed in, a click into a title or a filter box drew a
+ * heavy band round the one thing the reader was already looking at, so the
+ * rule after this one narrows the ring where the document says the last move
+ * was a pointer. Drawn over the boundary rather than outside it, a scroller
+ * cannot clip it and the field does not grow a halo the moment a caret lands
+ * in it, which is what a filter box in a toolbar of them did to the row it
+ * sits in. Every boxed field in the package rings this way (`Input.test.tsx`
+ * holds them to it).
  *
  * THE BORDER IS LEFT ALONE. Recolouring it under the ring says nothing the
  * ring has not already said, and it is what cost the error state its own
@@ -104,10 +108,28 @@
  * on a pointer press as well as on a tab.
  */
 .crewlet-input:has(.crewlet-input__control:focus-visible) {
-  outline: 1px solid var(--color-focus);
+  outline: 2px solid var(--color-focus);
   outline-offset: -1px;
 }
 
+/*
+ * NARROWED FOR A POINTER. The ring above is the keyboard's: 2px, the area
+ * WCAG 2.2's focus appearance asks of an indicator, drawn over the boundary
+ * and one pixel into the box. A field matches :focus-visible on a click as
+ * well, and a reader who put the caret there with a pointer is already looking
+ * at it, so where the document says the last move was a pointer
+ * (`data-crewlet-focus`, kept by `trackFocusModality`, which every field
+ * starts) the ring is one pixel in the selected edge, the accent mixed toward
+ * the page: a page that focuses its first field on load drew the focus colour
+ * round it before anybody had touched a key. A refused field keeps its own
+ * colour under a pointer too (below). A document that tracks nothing keeps
+ * the keyboard's ring.
+ */
+:root[data-crewlet-focus='pointer'] .crewlet-input:has(.crewlet-input__control:focus-visible) {
+  outline-width: 1px;
+  outline-color: var(--color-border-selected);
+}
+
 .crewlet-input.is-error {
   border-color: var(--color-feedback-danger);
 }
@@ -128,6 +150,10 @@
   outline-color: var(--color-feedback-danger);
 }
 
+:root[data-crewlet-focus='pointer'] .crewlet-input.is-error:has(.crewlet-input__control:focus-visible) {
+  outline-color: var(--color-feedback-danger);
+}
+
 .crewlet-input.is-disabled {
   opacity: 0.6;
   cursor: not-allowed;
@@ -364,10 +390,16 @@
    on the control itself: a textarea is the field, with nothing wrapped round
    it and nothing focusable inside it. */
 .crewlet-textarea:focus-visible {
-  outline: 1px solid var(--color-focus);
+  outline: 2px solid var(--color-focus);
   outline-offset: -1px;
 }
 
+/* Narrowed and tinted for a pointer, as the text box's ring is. See Input.css. */
+:root[data-crewlet-focus='pointer'] .crewlet-textarea:focus-visible {
+  outline-width: 1px;
+  outline-color: var(--color-border-selected);
+}
+
 .crewlet-textarea.is-error {
   border-color: var(--color-feedback-danger);
 }
@@ -376,6 +408,10 @@
   outline-color: var(--color-feedback-danger);
 }
 
+:root[data-crewlet-focus='pointer'] .crewlet-textarea.is-error:focus-visible {
+  outline-color: var(--color-feedback-danger);
+}
+
 .crewlet-textarea.is-disabled {
   opacity: 0.6;
   cursor: not-allowed;

package/dist/LayersList/index.js

@@ -1,3 +1,3 @@
-export { LAYERS_LIST_LABELS, LayersList } from '../chunk-ONL54WMH.js';
+export { LAYERS_LIST_LABELS, LayersList } from '../chunk-46RL3E54.js';
 import '../chunk-RKKO7QHH.js';
 import '../chunk-ODEQTPFM.js';

package/dist/{LayersList-NQZEIPZB.css → LayersList-TBNF4XGL.css}

@@ -68,13 +68,26 @@
   color: var(--color-text-primary);
 }
 
-/* The accent edge every current row in the system takes, in the primary ink.
-   A border, so forced colours keep it. */
+/*
+ * THE PICKED ENTRY IS A SELECTION, drawn as the package draws a chosen
+ * option: the selected fill under the primary ink, as a canvas's layers panel
+ * marks the board picked on it. It used to take the accent rail a CURRENT row
+ * takes (the outline's heading, the page in the rail), which says "you are
+ * here" and beside a canvas read as a second selection ring. The rail's room
+ * is still held, so nothing moves, and forced colours draw it in the system's
+ * own selected colour, since they drop the fill.
+ */
 .crewlet-layers-list__item[aria-current='true'] {
-  border-inline-start-color: var(--color-brand-accent);
+  background: var(--color-surface-selected);
   color: var(--color-text-primary);
 }
 
+@media (forced-colors: active) {
+  .crewlet-layers-list__item[aria-current='true'] {
+    border-inline-start-color: Highlight;
+  }
+}
+
 /* The ring lies inside the entry, where the scroller beside it cannot cut it. */
 .crewlet-layers-list__item:focus-visible {
   outline: 2px solid var(--color-focus);

package/dist/LinkInterstitial/index.js

@@ -1,6 +1,6 @@
-export { LinkInterstitial, openExternal } from '../chunk-KD2IRYCT.js';
-import '../chunk-5CLW2CXT.js';
+export { LinkInterstitial, openExternal } from '../chunk-5WDXPHEW.js';
 import '../chunk-XEGZHHRH.js';
+import '../chunk-5CLW2CXT.js';
 import '../chunk-SZZRIHGT.js';
 import '../chunk-PQADV6P6.js';
 import '../chunk-OMV5W53A.js';

package/dist/ListInput/index.js

@@ -1,5 +1,6 @@
-export { ListInput } from '../chunk-Z6VW6CXX.js';
-import '../chunk-6QFAK2WV.js';
+export { ListInput } from '../chunk-BIQDJOJZ.js';
+import '../chunk-IUYUS2SO.js';
+import '../chunk-YSGLEHND.js';
 import '../chunk-SMBKXWML.js';
 import '../chunk-PQADV6P6.js';
 import '../chunk-OMV5W53A.js';

package/dist/LivePreview/LivePreview.d.ts

@@ -1,27 +1,54 @@
 import { type ReactNode } from 'react';
 /**
- * Real content drawn small: a live, scaled-down snapshot of a page, a grid or
- * a frame inside a fixed box, the way a gallery card previews what it opens.
+ * Real content drawn small, once: a scaled-down snapshot of a page, a grid or
+ * a slide, rendered by the content's own renderer from its real data and
+ * then frozen, the way a gallery card previews what it opens.
  *
  * LAID OUT AT FULL SIZE, THEN SCALED. The content is given `width` CSS pixels
  * to lay itself out in, exactly as it would on its own page, and the whole is
  * scaled down to the box with a CSS transform, so the preview is the page
  * itself at a smaller size and never a second layout of it. Left out, the
- * content fills the box unscaled (a slide stage that scales itself).
+ * content fills the box unscaled.
  *
- * DRAWN ONLY WHEN IT CAN BE SEEN, AND ONLY SO MANY AT ONCE. The content is
- * mounted while the box is within `rootMargin` of the viewport and the
- * shared budget (`LivePreviewBudgetProvider`, twelve by default) grants it a
- * slot, and unmounted when it scrolls away, giving the slot back. Until the
- * content says it has drawn (`useLivePreview().ready()`), while it waits for a
- * slot, when it failed (`fail()`) and in a browser with no
- * IntersectionObserver, the box shows `fallback`.
+ * RENDERED ONCE, THEN A STILL COPY. The content is mounted once the box has
+ * stayed within `rootMargin` (a screen, by default) of what its scroll
+ * container shows for `dwellMs` and the shared budget
+ * (`LivePreviewBudgetProvider`) grants it one of the renders it allows at
+ * once. It reads what it needs and draws, out of sight behind the stand-in.
+ * When it says it has drawn (`useLivePreview().ready()`) its render is given
+ * to the next box, and once the page's fonts have loaded and the layout has
+ * settled, what it drew is copied (its DOM, cloned: `stills.ts`), the copy
+ * fades in over the stand-in, and the content is unmounted in the same
+ * commit. From then on the preview holds nothing live: no React tree under
+ * it, no subscription, no observer of its own and no timer, and it never
+ * reads, polls or redraws again. A copy laid out at `width` is scaled to its
+ * box by one observer the provider's copies share, so a resized window
+ * rescales it rather than drawing it again; one with no `width` is drawn
+ * again only if its box changes size.
  *
- * NEVER INTERACTIVE, NEVER ANNOUNCED. The live layer is `inert`, takes no
- * pointer and is hidden from assistive technology: nothing in it can be
- * focused or clicked, and whatever surrounds the preview (a card's link)
- * names what it shows. The swap from the stand-in to the content is a short
- * fade, and none under `prefers-reduced-motion`.
+ * KEPT FOR THE PAGE. With a `snapshot` key, the copy is kept by the provider
+ * under that key, and a preview mounted again under it (a card back after a
+ * filter, a change of shape or a page of results) shows the same copy at
+ * once, with nothing read. A page loaded afresh draws afresh.
+ *
+ * A FRAME CANNOT BE COPIED. Content that runs a page in a frame (`frame`)
+ * lives in another document: there is nothing in this one to clone, and a
+ * clone of the frame would load the page again. So a framed preview keeps its
+ * frame once drawn, fading it in over the stand-in. Kept frames are capped
+ * apart; one the reader has left is taken back only when a frame coming near
+ * needs its place, and shows its stand-in until it is drawn again.
+ *
+ * Until it has drawn, while it waits for a render, when it failed (`fail()`,
+ * or no drawing within `LIVE_PREVIEW_RENDER_MS`), and in a browser with no
+ * IntersectionObserver, the box shows `fallback`. What has drawn is shown
+ * over it, and the stand-in is hidden once the fade is done: fading the
+ * stand-in out at the same time showed both at half strength halfway through.
+ *
+ * NEVER INTERACTIVE, NEVER ANNOUNCED. The live layer and the copy are
+ * `inert`, take no pointer and are hidden from assistive technology: nothing
+ * in them can be focused or clicked, and whatever surrounds the preview (a
+ * card's link) names what it shows. Under `prefers-reduced-motion` nothing
+ * fades.
  */
 /**
  * How long a box stays near the viewport before its content is asked for: a
@@ -29,39 +56,101 @@ import { type ReactNode } from 'react';
  * past does not.
  */
 export declare const LIVE_PREVIEW_DWELL_MS = 120;
-/** Gives the previews under it a budget of their own, `max` live at once. */
-export declare function LivePreviewBudgetProvider({ max, children }: {
+/**
+ * How far ahead of what its scroll container shows a box starts rendering: a
+ * whole screen in each direction. A snapshot costs nothing once it is taken,
+ * so drawing a screen ahead is paid once, and it is what lets a reader
+ * scrolling at any pace meet every card already drawn. Measured on a gallery
+ * of 44 cards at 1440 by 900 with the CPU slowed fourfold, 200 pixels ahead
+ * left cards on screen before their first draw in about sixty samples of a
+ * scroll down and back; a screen ahead left none, and the first screen was
+ * drawn within a frame or two of the time it took before.
+ */
+export declare const LIVE_PREVIEW_MARGIN = "100% 0px";
+/**
+ * The longest a render may take before it gives up and keeps its stand-in.
+ * A preview is a glimpse: content that has not drawn in fifteen seconds is
+ * waiting on a read that is failing slowly, and holding one of the budget's
+ * few renders for it would hold the rest of a gallery up behind it. Fifteen
+ * is past the ten seconds a page in a frame is given to answer at all
+ * (`FRAME_HELLO_TIMEOUT_MS`) and its grace after, so a frame settles itself
+ * first.
+ */
+export declare const LIVE_PREVIEW_RENDER_MS = 15000;
+/**
+ * Gives the previews under it a budget and a store of their own: `max`
+ * rendering at once, `maxFrames` frames kept, and up to `kept` still copies
+ * kept by key for as long as the provider is mounted.
+ */
+export declare function LivePreviewBudgetProvider({ max, maxFrames, kept, children, }: {
     max?: number | undefined;
+    maxFrames?: number | undefined;
+    kept?: number | undefined;
     children: ReactNode;
 }): import("react").JSX.Element;
 export interface LivePreviewSignals {
-    /** The content has drawn: the stand-in gives way to it. */
+    /** The content has drawn: it is copied and the copy shown, or for a frame, the frame is shown. */
     ready: () => void;
-    /** The content has nothing to draw or could not draw: the stand-in stays, and the slot is given back. */
+    /** The content has nothing to draw or could not draw: the stand-in stays, and the render is given back. */
     fail: () => void;
 }
 /** What live content tells the preview around it. Outside one, both do nothing. */
 export declare function useLivePreview(): LivePreviewSignals;
-/** Where a preview is in its life. */
+/**
+ * Where a preview is in its life: `idle` (not asked for), `waiting` (asked,
+ * no render yet), `live` (rendering), `ready` (drawn: a still copy, or a kept
+ * frame) and `failed` (the stand-in for good).
+ */
 export type LivePreviewState = 'idle' | 'waiting' | 'live' | 'ready' | 'failed';
 export interface LivePreviewProps {
-    /** What is drawn small. Mounted only while the preview is live. */
+    /** What is drawn small. Mounted only while it renders, or for a frame while it is kept. */
     children: ReactNode;
-    /** The stand-in, drawn whenever the content is not. */
+    /** The stand-in, drawn whenever nothing else is. */
     fallback: ReactNode;
     /** The width, in CSS pixels, the content lays itself out at before it is scaled to the box. */
     width?: number | undefined;
-    /** How near the viewport the box comes before its content is mounted. */
+    /** How near what its scroll container shows the box comes before its content is rendered (`LIVE_PREVIEW_MARGIN`). */
     rootMargin?: string | undefined;
-    /** Nothing live is drawn: the stand-in only (no content to show, or a host that has turned previews off). */
+    /** Nothing is drawn: the stand-in only (no content to show, or a host that has turned previews off). */
     disabled?: boolean | undefined;
+    /**
+     * The content runs a page in a frame: it is kept rather than copied, and
+     * counts against the budget's frames for as long as it is.
+     */
+    frame?: boolean | undefined;
+    /**
+     * What is drawn, as a key: previews under one provider with the same key
+     * share one still copy, so a preview mounted again shows it at once and
+     * renders nothing. A key names a version of the content; content that has
+     * changed takes a new key and is drawn afresh.
+     */
+    snapshot?: string | undefined;
     /** How long the box stays near the viewport before its content is asked for, in ms. */
     dwellMs?: number | undefined;
     /** Told each time the state moves, for a host that measures. */
     onStateChange?: ((state: LivePreviewState) => void) | undefined;
     className?: string | undefined;
 }
-export declare function LivePreview({ children, fallback, width, rootMargin, disabled, dwellMs, onStateChange, className }: LivePreviewProps): import("react").JSX.Element;
+/**
+ * The element a box is scrolled by: the nearest ancestor that scrolls, or
+ * null for the window. An observer's margin grows its root and nothing else,
+ * and every scroller between the box and the root clips it at its own edge.
+ */
+export declare function scrollRoot(el: Element): Element | null;
+/** How a layer laid out at a size of its own is fitted to its box (`PreviewScaleProps.fit`). */
+export type PreviewFit = 'width' | 'contain' | 'fill';
+/**
+ * The most of a filled layer's content that may fall outside its box, on
+ * either axis, before `fill` contains it instead: a fifth. A laptop's board
+ * (16:10) in a card's 16:9 loses a tenth of its foot; a phone's board would
+ * lose four fifths of itself, and is shown whole.
+ */
+export declare const PREVIEW_FILL_MAX_CUT = 0.2;
+/**
+ * A preview whose `snapshot` key changes is another preview: what it holds
+ * belongs to the content it drew, so it starts again under the new key.
+ */
+export declare function LivePreview(props: LivePreviewProps): import("react").JSX.Element;
 export interface PreviewScaleProps {
     children: ReactNode;
     /** The width, in CSS pixels, the content is laid out at. */
@@ -70,10 +159,13 @@ export interface PreviewScaleProps {
     height?: number | undefined;
     /**
      * `width` scales the content to the box's width from its top (the top of a
-     * page); `contain` scales it to fit inside the box whole, centred (a board
-     * of its own size).
+     * page); `contain` scales it to fit inside the box whole, centred; `fill`
+     * covers the box edge to edge, centred across and held at the top, wherever
+     * that leaves at most [PREVIEW_FILL_MAX_CUT] of the content outside it, and
+     * contains it otherwise (a design's board, which may be a laptop's screen
+     * or a phone's). `contain` and `fill` need a `height`.
      */
-    fit?: 'width' | 'contain' | undefined;
+    fit?: PreviewFit | undefined;
 }
 /**
  * Content laid out at a size of its own and scaled to the box it is drawn in,

package/dist/LivePreview/budget.d.ts

@@ -1,34 +1,78 @@
 /**
- * How many live previews draw at once: the budget a gallery's cards share.
+ * How many live previews render at once: the budget a gallery's cards share.
  *
- * WHY A BUDGET. A live preview is real content drawn small: a page of prose,
- * a grid of cells, a slide, or a sandboxed frame running a page of its own. A
- * gallery of two hundred artifacts that drew every one would run two hundred
- * of them, most never seen. A preview asks for a slot when it comes near the
- * viewport and gives it back when it leaves; past the cap it waits, drawing
- * its stand-in, and is granted a slot the moment one is free, the oldest ask
- * first.
+ * A PREVIEW RENDERS ONCE. Real content (a page of prose, a grid of cells, a
+ * slide, a board of figures) is mounted near the viewport, reads what it
+ * needs, draws, and is then kept as a still copy with nothing live behind it.
+ * What costs is the RENDER: the reads, the mount and the layout, all at once
+ * as a row of cards scrolls near. So the budget bounds how many render at the
+ * same moment (`max`), and a slot is given back the moment its content has
+ * drawn; past the cap an ask waits, drawing its stand-in, and is granted the
+ * moment a render finishes, the oldest ask first.
+ *
+ * A FRAME IS THE EXCEPTION. A page in a frame lives in another document and
+ * cannot be copied, so a framed preview that has drawn keeps its page, and a
+ * page running in a frame is by far the dearest thing a preview holds. Frames
+ * kept are capped apart (`maxFrames`): a kept frame that leaves the viewport
+ * is parked, and taken back (`reclaim`) only when a frame coming near needs
+ * its place, the one the reader left longest ago first. One on screen is
+ * never taken back for another.
  *
  * Plain bookkeeping with no layout, so it is tested without a browser.
  */
 /**
- * The most previews live at once by default. A gallery at 1440 shows two or
- * three rows of three cards with a row of margin either side, so twelve keeps
- * everything a reader can scroll to in a moment live, and is the number of
- * pages a design's canvas already runs at once (`CANVAS_BOARD_MAX_LIVE`).
+ * The most previews rendering at once. Six is the number of connections a
+ * browser opens to one host over HTTP/1.1, which is how a preview's reads
+ * (an outline, a board and its datasets, a frame's ticket) reach their
+ * server: a seventh render would only queue its reads behind the first six,
+ * while holding its mount and layout open beside them.
+ */
+export declare const LIVE_PREVIEW_MAX = 6;
+/**
+ * The most frames kept at once. A frame is a page in another document, often
+ * in a process of its own; twelve is the number of pages a design's canvas
+ * runs at once (`CANVAS_BOARD_MAX_LIVE`).
  */
-export declare const LIVE_PREVIEW_MAX = 12;
+export declare const LIVE_PREVIEW_MAX_FRAMES = 12;
+/** One preview's hold on the budget, from its ask to its release. */
+export interface LivePreviewSlot {
+    /** Gives back everything it holds, or withdraws the ask if it was never granted. Calling it again does nothing. */
+    release(): void;
+    /**
+     * The content has drawn: its render slot is given back. A frame keeps its
+     * place among the frames until it is released or reclaimed; anything else
+     * holds nothing more, as if released.
+     */
+    drawn(): void;
+    /**
+     * A kept frame left the viewport: it stays, and may be reclaimed when a
+     * frame coming near needs its place. Before the grant the ask is
+     * withdrawn, since nothing was drawn. A render that is not a frame runs on
+     * to its end wherever it is, so for one this does nothing.
+     */
+    park(): void;
+    /** Back near the viewport: answers whether the slot is still held, and if so it is no longer reclaimable. */
+    resume(): boolean;
+}
 export interface LivePreviewBudget {
-    /** The most slots granted at once. */
+    /** The most renders at once. */
     readonly max: number;
+    /** The most frames kept at once. */
+    readonly maxFrames: number;
     /**
-     * Asks for a slot. `grant` is called once, now or when a slot frees. The
-     * answer gives the slot back, or withdraws the ask if it was never granted;
-     * calling it again does nothing.
+     * Asks for a slot. `grant` is called once, now or when a slot frees.
+     * `reclaim` is called if a parked frame is taken back, so the holder tears
+     * its page down; nothing else is ever reclaimed. `frame` says the content
+     * runs a page in a frame, which counts against `maxFrames` for as long as
+     * it is kept.
      */
-    request(grant: () => void): () => void;
-    /** Slots held now, for a test or a measurement. */
+    request(grant: () => void, reclaim?: () => void, frame?: boolean): LivePreviewSlot;
+    /** Renders in progress, for a test or a measurement. */
     live(): number;
+    /** Frames kept, rendering or drawn. */
+    frames(): number;
+    /** Kept frames that left the viewport. */
+    parked(): number;
     /** Asks waiting now. */
     waiting(): number;
 }
@@ -47,4 +91,4 @@ export declare const immediately: LivePreviewSchedule;
  * preview does.
  */
 export declare const perFrame: LivePreviewSchedule;
-export declare function createLivePreviewBudget(max?: number, schedule?: LivePreviewSchedule): LivePreviewBudget;
+export declare function createLivePreviewBudget(max?: number, schedule?: LivePreviewSchedule, maxFrames?: number): LivePreviewBudget;

package/dist/LivePreview/index.d.ts

@@ -1,5 +1,7 @@
 import './LivePreview.css';
-export { LIVE_PREVIEW_DWELL_MS, LivePreview, LivePreviewBudgetProvider, PreviewScale, useLivePreview } from './LivePreview.js';
-export type { LivePreviewProps, LivePreviewSignals, LivePreviewState, PreviewScaleProps } from './LivePreview.js';
-export { createLivePreviewBudget, immediately, LIVE_PREVIEW_MAX, perFrame } from './budget.js';
-export type { LivePreviewBudget, LivePreviewSchedule } from './budget.js';
+export { LIVE_PREVIEW_DWELL_MS, LIVE_PREVIEW_MARGIN, LIVE_PREVIEW_RENDER_MS, LivePreview, LivePreviewBudgetProvider, PREVIEW_FILL_MAX_CUT, PreviewScale, useLivePreview } from './LivePreview.js';
+export type { LivePreviewProps, LivePreviewSignals, LivePreviewState, PreviewFit, PreviewScaleProps } from './LivePreview.js';
+export { createLivePreviewBudget, immediately, LIVE_PREVIEW_MAX, LIVE_PREVIEW_MAX_FRAMES, perFrame } from './budget.js';
+export type { LivePreviewBudget, LivePreviewSchedule, LivePreviewSlot } from './budget.js';
+export { createLivePreviewStills, LIVE_PREVIEW_STILLS_KEPT } from './stills.js';
+export type { LivePreviewKept, LivePreviewStill, LivePreviewStills } from './stills.js';

package/dist/LivePreview/index.js

@@ -1,2 +1,2 @@
-export { LIVE_PREVIEW_DWELL_MS, LIVE_PREVIEW_MAX, LivePreview, LivePreviewBudgetProvider, PreviewScale, createLivePreviewBudget, immediately, perFrame, useLivePreview } from '../chunk-KF6YGL4B.js';
+export { LIVE_PREVIEW_DWELL_MS, LIVE_PREVIEW_MARGIN, LIVE_PREVIEW_MAX, LIVE_PREVIEW_MAX_FRAMES, LIVE_PREVIEW_RENDER_MS, LIVE_PREVIEW_STILLS_KEPT, LivePreview, LivePreviewBudgetProvider, PREVIEW_FILL_MAX_CUT, PreviewScale, createLivePreviewBudget, createLivePreviewStills, immediately, perFrame, useLivePreview } from '../chunk-WYKWXRJ4.js';
 import '../chunk-ODEQTPFM.js';