gesso-framework 0.7.0 → 0.8.0

package/dist/{index-BENndtaH.d.ts → index-DocVauCS.d.ts}

@@ -1,7 +1,7 @@
-import { L as ChannelToken, R as Command, a as ComponentType, c as Inputs, i as ComponentProps, j as Patch, n as ComponentArgs, p as InternalState, r as ComponentContext, u as Component, v as InputCell, x as ReadableCell, y as OutputCell } from "./FunctionComponent-Czkex8fp.js";
-import { C as ServiceRegistry, E as DesignThemes, O as AgentConfirmation, U as ChannelSource, X as WorkerHandle, b as ComponentElement, s as UiHost, t as AgentToolDefinition, w as ChannelRegistry, x as FrameworkChild } from "./tools-BFBwuinE.js";
+import { L as ChannelToken, R as Command, a as ComponentType, c as Inputs, i as ComponentProps, j as Patch, n as ComponentArgs, p as InternalState, r as ComponentContext, u as Component, v as InputCell, x as ReadableCell, y as OutputCell } from "./FunctionComponent-BDVrANP0.js";
+import { C as ServiceRegistry, E as DesignThemes, O as AgentConfirmation, U as ChannelSource, X as WorkerHandle, b as ComponentElement, s as UiHost, t as AgentToolDefinition, w as ChannelRegistry, x as FrameworkChild } from "./tools-Bl8LZ7LR.js";
 import { BehaviorSubject, Observable, Subscription } from "rxjs";
-import { AnimatedCell, AnimationDriver, CanvasHost, CaretRect, ComponentLikeElement, ComponentResolver, EditingState, EditingState as EditingState$1, FocusOptions, IconRasterizer, ImageResolver, LayoutExplanation, LayoutInspector, MARK_PREFIX, MotionStateInput, MotionTiming, Reactive, RendererBackend, Size, SvgResolver, TextMeasureRequest, TextMeasurer, UI_ROLES, UI_SEMANTIC_STATES, UiAnimation, UiChild, UiContrast, UiDurationToken, UiEasing, UiEasingToken, UiEditingController, UiElement, UiFileDropMessage, UiFindController, UiFocusManager, UiFrameClockFactory, UiInputDispatcher, UiInsets, UiKeyModifiers, UiKeyboardController, UiLength, UiModifier, UiMotion, UiNode, UiPlatformAdapter, UiPointer, UiPointerController, UiPointerDevice, UiReducedMotionPolicy, UiRole, UiScrollability, UiSelectionController, UiSemanticState, UiSemanticsAction, UiSemanticsMap, UiSemanticsMap as UiSemanticsMap$1, UiSemanticsPatch, UiSemanticsRecord, UiSemanticsRecord as UiSemanticsRecord$1, UiSemanticsUpdate, UiShortcutRegistry, UiSourceLocation, UiSpringSpec, UiSpringToken, UiTextPosition, UiTheme, UiThemeExtension, UiTouchScroller, UiWheelController, VideoClock, VideoResolver, markInstant, markNow, measureSpan, performanceMarksEnabled, setPerformanceMarks as setPerformanceMarks$1 } from "gesso-core";
+import { AnimatedCell, AnimationDriver, CanvasHost, CaretRect, ComponentLikeElement, ComponentResolver, EditingState, EditingState as EditingState$1, FocusOptions, IconRasterizer, ImageResolver, LayoutExplanation, LayoutInspector, MARK_PREFIX, MotionStateInput, MotionTiming, Reactive, RendererBackend, Size, SvgResolver, TextMeasureRequest, TextMeasurer, UI_ROLES, UI_SEMANTIC_STATES, UiAnimation, UiChild, UiClock, UiContrast, UiDurationToken, UiEasing, UiEasingToken, UiEditingController, UiElement, UiEnvironmentKey, UiFileDropMessage, UiFindController, UiFocusManager, UiFrameClockFactory, UiInputDispatcher, UiInsets, UiKeyModifiers, UiKeyboardController, UiLength, UiModifier, UiMotion, UiNode, UiPlatformAdapter, UiPointer, UiPointerController, UiPointerDevice, UiReducedMotionPolicy, UiRole, UiScrollability, UiSelectionController, UiSemanticState, UiSemanticsAction, UiSemanticsMap, UiSemanticsMap as UiSemanticsMap$1, UiSemanticsPatch, UiSemanticsRecord, UiSemanticsRecord as UiSemanticsRecord$1, UiSemanticsUpdate, UiShortcutRegistry, UiSourceLocation, UiSpringSpec, UiSpringToken, UiTextPosition, UiTheme, UiThemeExtension, UiTouchScroller, UiWheelController, VideoClock, VideoResolver, markInstant, markNow, measureSpan, performanceMarksEnabled, setPerformanceMarks as setPerformanceMarks$1 } from "gesso-core";
 //#region src/derive.d.ts
 /** How `derive` decides that a new value is not a change. */
 type Equality<T> = 'reference' | 'structural' | ((a: T, b: T) => boolean);
@@ -883,6 +883,12 @@ interface ControlledOptions<T> {
   readonly fallback: T;
   /** Fired on every change in either form. */
   readonly onChange: OutputCell<[next: T]>;
+  /**
+   * Other outputs a parent may hear the change through instead: a
+   * drawer's `onClose` beside its `onOpenChange`. A parent listening on
+   * any of them owns the value, as one passing `onChange` does.
+   */
+  readonly heardBy?: readonly OutputCell<never>[];
 }
 /**
  * Controlled by default, self-managing when given only an initial value.
@@ -893,9 +899,58 @@ interface ControlledOptions<T> {
  * `defaultValue` and the control owns it, still reporting changes;
  * pass both and it throws, because two owners is a bug. `bind(cell)` is
  * the spread for the first form when the owner is a local cell.
+ *
+ * A `value` with no `onChange` beside it has nobody to own it, so it is
+ * where the control starts, and the control owns it from there; a new
+ * value from the parent starts it again. A screen written as a picture
+ * of a moment, `<Switch checked={true} />`, is then one a person can
+ * use: the design tool's Play mode runs mocks written exactly so, and a
+ * value that only the parent may change is what `readOnly` and
+ * `disabled` say, not a missing handler.
  */
 declare function controlled<T>(options: ControlledOptions<T>): ControlledValue<T>;
 //#endregion
+//#region src/sharedValue.d.ts
+/**
+ * Named values the components under one node share, with no
+ * application behind them: what one screen of a prototype was given
+ * (an email typed on Forgot password), shown by the next (Check email),
+ * or a wizard's steps passing on what was filled in.
+ *
+ * A node provides a store to what it holds,
+ * `provide={[provided(SharedValuesKey, values)]}`, and a component asks
+ * for a value by name with `sharedValue(ctx, name, start)`. Under a
+ * store, every component asking for the same name has the same cell;
+ * with none above, each has its own, at its own start. So a design tool
+ * can draw a screen on its board as written, each frame alone, and play
+ * it with the screens before it.
+ *
+ * It is not where an application's state goes. That survives a reload
+ * and is on a channel, written by a command; these are cells, written
+ * by whatever holds one, and gone with the store.
+ */
+declare class SharedValues {
+  private readonly cells;
+  /** Every value by name, as it is now, in the order each was first asked for. */
+  readonly values: InternalState<ReadonlyMap<string, unknown>>;
+  /** The value named `name`: made at `start` by the first to ask, and the same cell for each after. */
+  cell<T>(name: string, start: T): InternalState<T>;
+  /** Writes a value by name, as a component holding it would; a name nobody has asked for is ignored. */
+  set(name: string, value: unknown): void;
+  /** Every value back at the start it was made with. */
+  reset(): void;
+  private publish;
+}
+/** Where a node provides a `SharedValues` to what it holds. */
+declare const SharedValuesKey: import("gesso-core").UiEnvironmentKey<SharedValues | null>;
+/**
+ * A value by name: the cell the nearest `SharedValues` above holds for
+ * it, shared with every component asking for it there; with none
+ * above, a cell of this component's own, at `start`. Bind it as any
+ * cell: `<TextInput {...bind(email)} />`.
+ */
+declare function sharedValue<T>(ctx: ComponentContext, name: string, start: T): InternalState<T>;
+//#endregion
 //#region src/decorators.d.ts
 /**
  * Declares a class as a Gesso component.
@@ -1093,10 +1148,14 @@ declare function createComponent<C extends ComponentType>(component: C, ...args:
  * edge of the screen whatever the language: an arrow drawn on a
  * diagram, a tooltip on a panel that is always on the left.
  *
+ * `over` lays the entry over the anchor at its size, grown by the
+ * offset on every side: the hole a spotlight leaves around what it
+ * shows. No direction turns it.
+ *
  * The direction is the entry's: the one its content reads in, which is
  * where its theme comes from too. See `OverlayEntry.environment`.
  */
-type OverlayPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | 'start' | 'start-start' | 'start-end' | 'end' | 'end-start' | 'end-end';
+type OverlayPlacement = 'over' | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | 'start' | 'start-start' | 'start-end' | 'end' | 'end-start' | 'end-end';
 /** A rectangle inside an anchor, from its border box's top left. */
 interface OverlayRect {
   readonly x: number;
@@ -1230,6 +1289,104 @@ declare class OverlayService {
   closeAll(): void;
   isOpen(id: string): boolean;
 }
+/**
+ * The overlays of the `OverlayScope` a node is in: where an entry
+ * opened there goes instead of the runtime's layer. Null outside every
+ * scope.
+ */
+declare const OverlayScopeKey: import("gesso-core").UiEnvironmentKey<OverlayService | null>;
+//#endregion
+//#region src/overlay/OverlayScope.d.ts
+interface OverlayScopeProps {
+  children?: UiChild;
+}
+/**
+ * A part of the tree that holds its own overlays: a dialog, menu or
+ * tooltip opened inside it is drawn inside it, over its content and
+ * nowhere else.
+ *
+ * What a design tool's player needs from the screen it plays: a dialog
+ * on that screen dims the screen, centres in it and is clipped by it,
+ * is scaled with it when the screen is drawn smaller than its own size,
+ * and leaves the tool around it pressable. A menu is placed and flipped
+ * within it, since an anchored entry stays inside the box its layer
+ * covers. Outside a scope, entries open in the runtime's own layer
+ * above the whole application, as they always have.
+ *
+ * It fills what holds it, and is the containing block of what it
+ * holds. `useOverlay` finds the nearest scope above the component that
+ * opens the entry; with none, it uses the runtime's `OverlayService`.
+ *
+ * A dialog's trap inside it holds the keyboard inside it only: the
+ * tool around it, and every other scope, keep their focus, and none is
+ * taken from them when it opens or handed to them when it closes.
+ */
+declare function OverlayScope(inputs: Inputs<OverlayScopeProps>, _ctx: ComponentContext): UiChild;
+//#endregion
+//#region src/startingInputsKey.d.ts
+/** One component's starting inputs: input names to values. */
+type StartingInputsRecord = Readonly<Record<string, unknown>>;
+/**
+ * Starting inputs by component name: one record for every instance of
+ * it, or a list for each in the order they are made (`null` for one
+ * left as written), so the second of three switches can start on.
+ */
+type StartingInputsByName = Readonly<Record<string, StartingInputsRecord | readonly (StartingInputsRecord | null)[]>>;
+/**
+ * The inputs components under a node start with, by component name,
+ * over what their parents pass; see `StartingInputs`. Empty outside one.
+ */
+declare const StartingInputsKey: UiEnvironmentKey<StartingInputsByName>;
+//#endregion
+//#region src/StartingInputs.d.ts
+interface StartingInputsProps {
+  /**
+   * Inputs by component name: `{ ScrollArea: { scrollY: 600 }, Tour: { step: 1 } }`;
+   * or a list for each instance in the order they are made, `null` for
+   * one left as written: `{ Toggle: [null, { on: true }] }`.
+   */
+  of?: StartingInputsByName;
+  children?: UiChild;
+}
+/**
+ * Draws what it holds with the components in it started from given
+ * inputs, named by component, over what their parents pass: every
+ * `ScrollArea` in it scrolled to 600, every `Tour` at its second step.
+ *
+ * What a design tool draws a moment of a screen with, beside the
+ * screen as written, without a copy of the screen to drift from it: a
+ * list scrolled far enough for its back-to-top button, a dialog open,
+ * a tour on its second step. A component reads them as it would its
+ * parent's props, so one that takes a value without a handler beside
+ * it starts there and is then the person's to change, in a design
+ * tool's player as anywhere. A preview of inputs (`InspectionService.
+ * previewInputs`) goes over them, and ending it comes back to them.
+ *
+ * They are read as each component is made, so they start a component
+ * rather than steer one: a new `of` reaches components made after it,
+ * and once the parent passes something new for an input, it is the
+ * parent's again, as a dialog saved open closes when its owner closes
+ * it.
+ * Nested, the outer one wins for an input both give a component, and
+ * the inner one's other inputs and names still reach in: what draws a
+ * screen at a moment decides over what the screen starts itself with,
+ * so a moment saved from a moment is the later one. A list per instance
+ * is taken whole. It fills what holds it.
+ */
+declare function StartingInputs(inputs: Inputs<StartingInputsProps>, ctx: ComponentContext): UiChild;
+//#endregion
+//#region src/liveInput.d.ts
+/**
+ * Says what an input of the component whose body is running holds now,
+ * as the component keeps it, and how to read it again: a switch turned
+ * on, a field typed in, a list scrolled to 600. The inspector reports it
+ * on the component's owner report (`live`), and a design tool saves a
+ * moment of a played screen from it, to start the screen there again
+ * (`StartingInputs`). `controlled` calls it for its value, so a control
+ * written by its contract reports itself; outside a component's body it
+ * does nothing.
+ */
+declare function liveInput(name: string, read: () => unknown): void;
 //#endregion
 //#region src/overlay/OverlayLayer.d.ts
 /**
@@ -1258,7 +1415,10 @@ declare class OverlayService {
  * why that node and not always the anchor.
  */
 declare class OverlayLayer extends Component {
-  overlays: OverlayService;
+  runtimeOverlays: OverlayService;
+  /** The entries to draw, when not the runtime's: an `OverlayScope`'s. */
+  service: InputCell<OverlayService | null>;
+  private get overlays();
   render(): UiElement;
   private renderEntries;
 }
@@ -1289,6 +1449,8 @@ declare class OverlayLayer extends Component {
 declare class ComponentHost<P extends Record<string, unknown> = Record<string, unknown>> {
   private readonly services;
   private readonly channels;
+  /** The slot's node, under its parent, for `ctx.environment`; null for a host made outside a tree. */
+  private readonly anchor;
   /** The class instance; undefined for a functional component. */
   readonly instance: Component | undefined;
   readonly element: ComponentElement<P>;
@@ -1310,11 +1472,29 @@ declare class ComponentHost<P extends Record<string, unknown> = Record<string, u
   private readonly inputSubscriptions;
   /** A functional component's cells, by prop name, as they were handed out. */
   private readonly functionalCells;
+  /**
+   * Inputs it is drawn with over its parent's, from a `StartingInputs`
+   * above it when it was made: a moment of a screen, a tour's second
+   * step. A preview goes over these, and ending one comes back to them.
+   */
+  private started;
+  /** What the parent passed for each started input at birth: a new value from it takes over. */
+  private readonly startedOver;
+  /** A started input the parent passes as a stream: the start, then the stream's changes; one per input, so it is not resubscribed. */
+  private readonly startedStreams;
+  /** What the component says it holds now, by input; see `liveInput`. */
+  private readonly live;
+  /** Inputs a tool draws the component with over its parent's, until it ends them; see `previewInputs`. */
+  private previewed;
+  /** A class's input values from before they were previewed, for the ones its parent does not pass. */
+  private readonly beforePreview;
   private readonly mountHooks;
   private readonly unmountHooks;
   /** True only while the component function runs; hooks may register then. */
   private rendering;
-  constructor(element: ComponentElement<P>, services?: ServiceRegistry, channels?: ChannelRegistry);
+  constructor(element: ComponentElement<P>, services?: ServiceRegistry, channels?: ChannelRegistry,
+  /** The slot's node, under its parent, for `ctx.environment`; null for a host made outside a tree. */
+  anchor?: UiNode | null);
   /** The class or function this host mounts. */
   get component(): ComponentType;
   /**
@@ -1338,6 +1518,21 @@ declare class ComponentHost<P extends Record<string, unknown> = Record<string, u
    * cell is what updates the output.
    */
   updateProps(props: P): void;
+  /**
+   * Feeds the inputs `values` names from them instead of from the
+   * parent, until a call with null hands them back to the parent: a
+   * design tool showing one of a component's states on the live tree.
+   * A later call replaces the earlier one; a new prop from the parent
+   * for a previewed input waits until the preview ends.
+   *
+   * Each input a preview starts or ends is handed its value even when
+   * it holds that value already, as a new value from the parent is: a
+   * control that owns what it was started at (`controlled`) starts
+   * again from it, rather than keeping what a person turned it to.
+   */
+  previewInputs(values: Readonly<Record<string, unknown>> | null): void;
+  /** What an input is fed from: a preview's value for it, else what it was started with, else the parent's prop. */
+  private providedFor;
   private renderFunction;
   /**
    * The props record a functional component reads: a cell per name,
@@ -1350,6 +1545,8 @@ declare class ComponentHost<P extends Record<string, unknown> = Record<string, u
   private createInputRecord;
   private createContext;
   private wireInputs;
+  /** What the component says each of its inputs holds now; see `liveInput`. */
+  liveInputs(): ReadonlyMap<string, unknown>;
   /**
    * What the parent most recently supplied for each input, as given:
    * a value, an element or a stream, whether or not the component has
@@ -1398,7 +1595,7 @@ declare class ComponentHostResolver implements ComponentResolver {
   private readonly hosts;
   private pendingMounts;
   constructor(services?: ServiceRegistry, channels?: ChannelRegistry);
-  resolve(element: ComponentLikeElement, anchorId: string): UiChild;
+  resolve(element: ComponentLikeElement, anchorId: string, anchor?: UiNode): UiChild;
   release(anchorId: string): void;
   flushMounts(): void;
   /**
@@ -1477,6 +1674,13 @@ interface UiNodeReport {
    */
   readonly beneath: readonly UiBeneathReport[];
   readonly semantics?: UiSemanticsReport;
+  /**
+   * What the node draws while hovered and while pressed, from its
+   * `interactive` modifiers: the props it writes then, as the element
+   * would write them. For a design tool's handoff, which writes them
+   * as `:hover` and `:active`. Absent when it changes nothing.
+   */
+  readonly interaction?: UiInteractionReport;
   /** `formatExplanation` of the node's layout, which is L8's answer. */
   readonly explanation: string;
   /**
@@ -1510,6 +1714,13 @@ interface UiOwnerReport {
    * needs to write a component's use back as code: `label="Email"`.
    */
   readonly inputs?: Readonly<Record<string, UiOwnerInput>>;
+  /**
+   * What the component says its inputs hold now, as it keeps them
+   * (`liveInput`): a switch a person turned on, a list scrolled to 600.
+   * Plain values only. What a design tool saves a moment of a played
+   * screen from.
+   */
+  readonly live?: Readonly<Record<string, string | number | boolean | null>>;
 }
 /** One input's value in an owner report; see `UiOwnerReport.inputs`. */
 type UiOwnerInput = string | number | boolean | null | {
@@ -1625,6 +1836,10 @@ interface UiEnvironmentReport {
   /** Whether this node provides the value rather than inheriting it. */
   readonly provided: boolean;
 }
+interface UiInteractionReport {
+  readonly hovered?: Readonly<Record<string, unknown>>;
+  readonly pressed?: Readonly<Record<string, unknown>>;
+}
 interface UiSemanticsReport {
   readonly role?: string;
   readonly label?: string;
@@ -2329,6 +2544,11 @@ interface AnimateOptions {
   reducedMotion?: UiReducedMotionPolicy;
   /** Wait this long before the first sample; see `UiAnimationOptions.delay`. */
   delay?: number;
+  /**
+   * The clock it runs on, where it is drawn: `ctx.environment(UiEnvironmentKeys.clock)`
+   * in a component, `clockOf(node)` from a node. Real time without one. See `UiClock`.
+   */
+  clock?: UiClock | null;
 }
 interface SpringOptions {
   /** A named spring, or one given outright. Defaults to `snappy`. */
@@ -2343,6 +2563,11 @@ interface SpringOptions {
   reducedMotion?: UiReducedMotionPolicy;
   /** Wait this long before the first sample; see `UiAnimationOptions.delay`. */
   delay?: number;
+  /**
+   * The clock it runs on, where it is drawn: `ctx.environment(UiEnvironmentKeys.clock)`
+   * in a component, `clockOf(node)` from a node. Real time without one. See `UiClock`.
+   */
+  clock?: UiClock | null;
 }
 /**
  * Animation, as a store components can inject.
@@ -2382,6 +2607,13 @@ declare class AnimationService {
    * animation drives a cell, which has no node — see `UiMotion`.
    */
   setMotion(motion: UiMotion): void;
+  private motionListener;
+  /**
+   * Called by the runtime, which provides the vocabulary at its root so
+   * a name in a `transition` or a `motion` state resolves to it too; a
+   * part of the tree may provide its own over it (`UiEnvironmentKeys.motion`).
+   */
+  setMotionListener(listener: ((motion: UiMotion) => void) | null): void;
   get motion(): UiMotion;
   /**
    * Turns reduced motion on or off for this runtime.
@@ -3476,6 +3708,8 @@ declare class GessoRuntime {
   private lastEarlyFrame;
   /** When the last discrete input was routed; see `answerInput`. */
   private lastDiscreteInput;
+  /** The wheel's steps since the last frame, added together; see `wheel`. */
+  private heldWheel;
   /** The display time the frame being drawn is for; see `FrameMetrics.time`. */
   private frameTime;
   /** When the frame's first phase began, before its changes were collected; see `FrameMetrics.durationMs`. */
@@ -3580,6 +3814,11 @@ declare class GessoRuntime {
    * them. Only populated while a listener is attached.
    */
   private semanticsBoxes;
+  /** When a frame last moved something, and when the boxes were last swept; see `updateSemantics`. */
+  private semanticsMovedAt;
+  private semanticsSweptAt;
+  /** The sweep owed once a run of moving frames stops. */
+  private semanticsSweepTimer;
   /** What each semantics walk leaves for the next; see `SemanticsMemory`. */
   private readonly semanticsMemory;
   private lastFocusedId;
@@ -3761,6 +4000,25 @@ declare class GessoRuntime {
    * refresh either.
    */
   answerInput(): void;
+  /**
+   * A step of the wheel, or of a trackpad's two fingers or its pinch,
+   * held until the frame and added to the others that arrive before it.
+   *
+   * A trackpad sends a step on every refresh, and a handler that takes
+   * longer than a refresh over one (a design tool's board zoomed over
+   * hundreds of frames, each of whose names it scales) fell behind for
+   * good: each step waited for the one before it, the frame waited for
+   * them all, and a pinch drew nothing until the fingers stopped, then
+   * jumped. Held, the steps that queue while the handler runs are one
+   * step at the next frame, so the handler runs once a frame however
+   * many arrive, and what it draws follows the fingers a frame at a
+   * time. A step with other modifiers or in another unit is not added
+   * to the held one but follows it, and any other input lets the held
+   * step go first (`releaseWheel`), so nothing is answered out of order.
+   */
+  wheel(...step: Parameters<UiWheelController['wheel']>): void;
+  /** Hands the held wheel step to the input now, before what follows it; see `wheel`. */
+  releaseWheel(): void;
   /** Draws the pending frame in a task of its own, if the guards in `answerInput` allow. */
   private drawEarly;
   /**
@@ -4089,6 +4347,8 @@ declare class GessoRuntime {
   private pathOf;
   /** The components that rendered a node, nearest first. */
   private sourceReport;
+  /** The props the node's `interactive` modifiers write while hovered and pressed, later ones over earlier. */
+  private interactionOf;
   private ownersOf;
   private propsOf;
   /**
@@ -4273,6 +4533,13 @@ declare class GessoRuntime {
    */
   applyFileDrop(message: UiFileDropMessage): void;
   applySemanticsAction(action: UiSemanticsAction): void;
+  /**
+   * A semantics action on a node: the mirror's, or `InspectionService.act`'s
+   * on a node with no record of its own. False when it did not take: focus
+   * refused (an open dialog's trap holds it elsewhere), or a field that
+   * takes no text.
+   */
+  private actOn;
   /**
    * An action on an inline link, which is a run and not a node.
    *
@@ -4381,6 +4648,29 @@ declare class GessoRuntime {
    * missing, rather than by scanning every key for the prefix.
    */
   private semanticIdsUnder;
+  /**
+   * The boxes for a frame that moved something but changed no meaning:
+   * all of them when it is the first move after a rest, and otherwise
+   * only the focused node's, with the sweep owed for when the moving
+   * stops (`SEMANTICS_SETTLE_MS`), or for when the boxes have been stale
+   * too long (`SEMANTICS_MOST_STALE_MS`).
+   *
+   * A pan or a zoom moves every box under the camera on every frame. In
+   * Atelier, a board of three dozen screens panned at 15%, the sweep was
+   * 3 to 4 ms of a 4 to 6 ms frame, with frames to 13 ms, past a 120 Hz
+   * display's 8.3; and the main thread wrote four styles on each of 545
+   * elements per frame, which in Chromium was 45% of that thread while
+   * it also had the wheel events to deliver. Nobody reads the rectangle
+   * of an element that is moving under a pan: a screen reader's cursor
+   * is on what it rests on. The focused node is the exception, since its
+   * focus ring is drawn from its element, so it moves every frame.
+   */
+  private movedSemanticsBoxes;
+  /** Sweeps the boxes once the moving has stopped, and sends what changed. */
+  private scheduleSemanticsSweep;
+  private sweepSemanticsBoxes;
+  /** The focused node's box when it differs from the one last sent, as `collectSemanticsBoxes` would give it. */
+  private focusedSemanticsBox;
   /**
    * The mirrored nodes whose box differs from the one last sent, and
    * which are on screen.
@@ -6730,6 +7020,8 @@ declare class GessoApp {
   /** The appearance this shell reports; watched or overridden. */
   private colorSchemePreference;
   constructor(options: GessoAppOptions);
+  /** Runs a pending frame now: see `FrameService.flush`. */
+  private flushFrame;
   /**
    * The running app, as the agent's screen tools need it: its semantics
    * tree and focus, the mirror's actions, keys, and a way to run a
@@ -7619,10 +7911,24 @@ declare function persisted<T>(adapter: StorageAdapter, key: string, options: Per
  */
 declare class FrameService {
   private readonly subject;
+  private flusher;
   /** Emits after each frame finishes, with what it cost and what it answered. */
   readonly frames: Observable<FrameMetrics>;
   /** Called by the runtime; not for components. */
   publish(metrics: FrameMetrics): void;
+  /** Called by the shell that drives the frames; not for components. */
+  setFlush(flush: (() => void) | null): void;
+  /**
+   * Draws a pending frame now, rather than when the display next asks
+   * for one; nothing when none is pending.
+   *
+   * A tab in the background is sent no frames. A design editor's tool,
+   * called by an agent while the editor's window is behind another,
+   * changes the screen and waits for it to be drawn before reading it:
+   * without this, it waits for a frame that never comes. The agent's
+   * own screen tools (`uiSurface`) do the same after each action.
+   */
+  flush(): void;
 }
 //#endregion
 //#region src/app/InspectionService.d.ts
@@ -7667,6 +7973,21 @@ declare class InspectionService {
     readonly width: number;
     readonly height: number;
   };
+  /**
+   * Where the node is seen on the screen: `box` with every transform
+   * above it applied, so a node in a frame drawn at half its size is
+   * half its size, where it is drawn. What an overlay laid over the
+   * live tree is placed by (an outline on the component under the
+   * pointer). `box` keeps the untransformed box, which is where the
+   * node is in the layout: what an editor reading a zoomed board in
+   * the board's own coordinates (a minimap) needs.
+   */
+  screenBox(node: UiNode): {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+  };
   /**
    * Draws a node as though it declared `value` for `property`, until
    * the preview is ended or the node leaves the tree.
@@ -7681,6 +8002,36 @@ declare class InspectionService {
   preview(node: UiNode, property: string, value: unknown): void;
   /** Ends a preview of one property, or of every property previewed on the node. */
   endPreview(node: UiNode, property?: string): void;
+  /**
+   * Draws a component as though its parent passed `inputs`, over what
+   * the parent did pass, until the preview is ended or the component
+   * leaves the tree. The component is named by its anchor, as
+   * `inspect(node).owners[].anchorId` gives it.
+   *
+   * What a design editor shows when a component on a played screen is
+   * jumped to one of its states (Filled, Error, Disabled): the same
+   * instance, still live, given that state's inputs, and the inputs it
+   * was written with back when the preview ends. A later preview of the
+   * same component replaces this one. The names and values are props',
+   * as JSX would write them. An anchor no component holds is ignored.
+   */
+  previewInputs(anchorId: string, inputs: Readonly<Record<string, unknown>>): void;
+  /** Ends a preview of a component's inputs: its parent's are its own again. */
+  endInputPreview(anchorId: string): void;
+  /**
+   * Presses a node, or replaces the text of the field it is, as a
+   * person would: a click at the middle of where it is drawn, which
+   * its handlers and every handler above it get, or the edit a
+   * keyboard makes once it has focus. The path the accessibility
+   * mirror's actions take, for any node in the tree, record or not.
+   *
+   * What a design editor's agent does to play a prototype in its live
+   * frames: a row pressed, an email typed, by a node it found with
+   * `nodesAt` or by walking the tree. False when it did not take: a
+   * node no longer in the tree, or a field that could not have focus
+   * because an open dialog's trap holds it, or takes no text.
+   */
+  act(node: UiNode, action: 'click' | 'setValue', value?: string): boolean;
 }
 /** What the runtime gives the service. */
 interface InspectionHost {
@@ -7693,8 +8044,18 @@ interface InspectionHost {
     readonly width: number;
     readonly height: number;
   };
+  /** The node's box with the transforms above it applied. */
+  screenBox?(node: UiNode): {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+  };
   preview?(node: UiNode, property: string, value: unknown): void;
   endPreview?(node: UiNode, property?: string): void;
+  /** Null ends the preview. */
+  previewInputs?(anchorId: string, inputs: Readonly<Record<string, unknown>> | null): void;
+  act?(node: UiNode, action: 'click' | 'setValue', value?: string): boolean;
 }
 //#endregion
 //#region src/app/videoClock.d.ts
@@ -8274,25 +8635,6 @@ declare class ScrollService {
 }
 //#endregion
 //#region src/app/FocusService.d.ts
-/**
- * Keyboard focus, as a store components can inject.
- *
- * `UiFocusManager` lives in the runtime and a component cannot reach
- * it — components reach the world through stores, as they do for the
- * clipboard (`ShellService`), overlays (`OverlayService`) and find
- * (`FindService`). Without this a component cannot autofocus a field,
- * trap the keyboard in a dialog, or put the caret in the input that
- * failed validation.
- *
- * Nodes come from a `ref` prop. A tree's refs fire before the runtime
- * installs the manager, so an action taken during the first build is
- * queued and replayed once there is one; that is the same problem
- * `FindService` solves for its query field, and the reason `autoFocus`
- * in a dialog works on the frame it mounts.
- *
- * It must stay on the render thread: its actions take `UiNode`s, which
- * never cross a worker boundary.
- */
 declare class FocusService {
   /** The node holding focus, or null. A control binds its focus ring to this. */
   readonly focused: InternalState<UiNode | null>;
@@ -8326,6 +8668,12 @@ declare class FocusService {
   focusNext(): void;
   /** Moves focus to the previous focusable node, wrapping around. */
   focusPrevious(): void;
+  /**
+   * The tab stops under `within` (the whole tree when not given), in
+   * the order Tab visits them: what a design tool numbers to show a
+   * screen's keyboard order. Empty before the runtime has a manager.
+   */
+  tabStops(within?: UiNode): UiNode[];
   /**
    * Confines focus to `scope` until `releaseTrap`, moving it inside if
    * it was elsewhere. Traps nest: a dialog opened over a dialog traps
@@ -8988,5 +9336,5 @@ declare class RenderWorkerApp {
   private initialize;
 }
 //#endregion
-export { OpfsStorageOptions as $, BoundStream as $n, Mutation as $r, RendererChoice as $t, observeReducedMotion as A, AudioMetadata as An, findUnplainPath as Ar, ShellHistory as At, InspectionHost as B, UiEasingChoice as Bn, ThemeTokenCell as Br, DevtoolsRequest as Bt, writeClipboard as C, route as Cn, createComponent as Cr, GessoAppBuilder as Ct, TextService as D, formatUrl as Dn, ChannelRegistration as Dr, AppLogicEndpoint as Dt, EditingService as E, buildPath as En, pickKeys as Er, createApp as Et, AudioSink as F, AudioStatus as Fn, Input as Fr, ActionEntry as Ft, persisted as G, ShellRecentFile as Gn, show as Gr, treeText as Gt, FrameService as H, ShellFileRequest as Hn, bind as Hr, PatchEntry as Ht, AudioSinkOptions as I, AnimateOptions as In, Output as Ir, ChannelErrorEntry as It, IndexedDbStorage as J, ShellStorageOp as Jn, EachProps as Jr, ShellToRuntimeMessage as Jt, ShellStorage as K, ShellRequest as Kn, Each as Kr, RuntimeErrorSource as Kt, AudioSinkOutput as L, AnimationService as Ln, ControlledOptions as Lr, CommandEntry as Lt, PresenceProps as M, AudioSample as Mn, Channel as Mr, ShellHistoryOptions as Mt, RouterOutlet as N, AudioService as Nn, Define as Nr, createShellHistory as Nt, FindService as O, parseUrl as On, ChannelRegistryHandle as Or, WorkerApp as Ot, AudioElementLike as P, AudioState as Pn, Inject as Pr, ActionCause as Pt, OpfsStorage as Q, observeColorScheme as Qn, MutateOptions as Qr, GessoRuntimeOptions as Qt, MediaSessionLike as R, SpringOptions as Rn, ControlledValue as Rr, ConsoleEntry as Rt, EditingProxySink as S, RouteTarget as Sn, OverlayService as Sr, createSyncApp as St, ScrollService as T, RouteParams as Tn, pick as Tr, CreateAppOptions as Tt, PersistedOptions as U, ShellFileResult as Un, Show as Ur, UiTreeNode as Ut, InspectionService as V, ShellFile as Vn, themeTokenCell as Vr, FrameEntry as Vt, PersistedState as W, ShellFileType as Wn, ShowProps as Wr, UiTreeSnapshot as Wt, OpfsDirectory as X, ColorScheme as Xn, debounced as Xr, FramePhaseTimings as Xt, IndexedDbStorageOptions as Y, ShellStorageResult as Yn, each as Yr, FrameMetrics as Yt, OpfsFileHandle as Z, ColorSchemePreference as Zn, throttled as Zr, GessoRuntime as Zt, renderRoot as _, DeriveOptions as _i, OutletProps as _n, ComponentHost as _r, ShellLocalStore as _t, UiRole as a, resource as ai, FontFamilyDeclaration as an, UiPropOrigin as ar, classifyStorageError as at, SemanticsMirrorSink as b, RouteGuard as bn, OverlayPlacement as br, GessoApp as bt, UiSemanticsPatch as c, FanCell as ci, FontService as cn, UiStreamReport as cr, storageReadValue as ct, markNow as d, FanOutOptions as di, RouteAnswer as dn, formatNodePath as dr, UndoableOptions as dt, mutate as ei, RuntimeInput as en, NodePathTarget as er, OpfsWritable as et, measureSpan as f, fanOut as fi, RouteMatch as fn, formatNodeReport as fr, undoable as ft, RenderWorkerError as g, computed as gi, RouteState as gn, ComponentHostResolver as gr, rememberedDirectory as gt, RenderWorkerApp as h, ReadSource as hi, RouterService as hn, printPropValue as hr, UndoTransaction as ht, UI_SEMANTIC_STATES as i, ResourceStatus as ii, FontFaceLike as in, UiOwnerReport as ir, StorageRead as it, Presence as j, AudioRequest as jn, requirePlainData as jr, ShellHistoryMode as jt, observeMediaQuery as k, AudioAction as kn, createChannelRegistry as kr, WorkerAppOptions as kt, UiSemanticsRecord$1 as l, FanKey as li, MediaOptions as ln, describeStream as lr, UndoShortcutOptions as lt, setPerformanceMarks$1 as m, ComputedOptions as mi, RouterRoutes as mn, formatStream as mr, UndoStackOptions as mt, MARK_PREFIX as n, ResourceOptions as ni, UiFramePhase as nn, UiNodeReport as nr, StorageAdapter as nt, UiSemanticState as o, SelectOptions as oi, FontFamilyStatus as on, UiPropReport as or, storageErrorMessage as ot, performanceMarksEnabled as p, ComputedCell as pi, RouterHistorySink as pn, formatSourceLocation as pr, UndoStack as pt, ShellStorageOptions as q, ShellService as qn, EachKey as qr, RuntimeToShellMessage as qt, UI_ROLES as r, ResourceState as ri, FontFaceDeclaration as rn, UiOwnerInput as rr, StorageOutcome as rt, UiSemanticsMap$1 as s, select as si, FontHost as sn, UiSemanticsReport as sr, storageReadFailure as st, EditingState$1 as t, Resource as ti, UI_FRAME_PHASES as tn, UiEnvironmentReport as tr, MemoryStorage as tt, markInstant as u, FanOut as ui, MediaService as un, formatAge as ur, registerUndoShortcuts as ut, EditingMirrorTarget as v, Equality as vi, RouteContext as vn, OverlayLayer as vr, performShellStorage as vt, FocusService as w, to as wn, structurallyEqual as wr, WebMcpChoice as wt, EditingProxy as x, RouteOptions as xn, OverlayRect as xr, GessoAppOptions as xt, SemanticsMirror as y, derive as yi, RouteDefinition as yn, OverlayEntry as yr, shellStorageDenied as yt, audioClock as z, UiDuration as zn, controlled as zr, DevtoolsEvent as zt };
-//# sourceMappingURL=index-BENndtaH.d.ts.map
+export { OpfsStorageOptions as $, BoundStream as $n, ThemeTokenCell as $r, RendererChoice as $t, observeReducedMotion as A, DeriveOptions as Ai, AudioMetadata as An, OverlayRect as Ar, ShellHistory as At, InspectionHost as B, UiEasingChoice as Bn, findUnplainPath as Br, DevtoolsRequest as Bt, writeClipboard as C, FanOut as Ci, route as Cn, StartingInputsByName as Cr, GessoAppBuilder as Ct, TextService as D, ComputedOptions as Di, formatUrl as Dn, OverlayScopeProps as Dr, AppLogicEndpoint as Dt, EditingService as E, ComputedCell as Ei, buildPath as En, OverlayScope as Er, createApp as Et, AudioSink as F, AudioStatus as Fn, pick as Fr, ActionEntry as Ft, persisted as G, ShellRecentFile as Gn, Input as Gr, treeText as Gt, FrameService as H, ShellFileRequest as Hn, Channel as Hr, PatchEntry as Ht, AudioSinkOptions as I, AnimateOptions as In, pickKeys as Ir, ChannelErrorEntry as It, IndexedDbStorage as J, ShellStorageOp as Jn, SharedValuesKey as Jr, ShellToRuntimeMessage as Jt, ShellStorage as K, ShellRequest as Kn, Output as Kr, RuntimeErrorSource as Kt, AudioSinkOutput as L, AnimationService as Ln, ChannelRegistration as Lr, CommandEntry as Lt, PresenceProps as M, derive as Mi, AudioSample as Mn, OverlayService as Mr, ShellHistoryOptions as Mt, RouterOutlet as N, AudioService as Nn, createComponent as Nr, createShellHistory as Nt, FindService as O, ReadSource as Oi, parseUrl as On, OverlayEntry as Or, WorkerApp as Ot, AudioElementLike as P, AudioState as Pn, structurallyEqual as Pr, ActionCause as Pt, OpfsStorage as Q, observeColorScheme as Qn, controlled as Qr, GessoRuntimeOptions as Qt, MediaSessionLike as R, SpringOptions as Rn, ChannelRegistryHandle as Rr, ConsoleEntry as Rt, EditingProxySink as S, FanKey as Si, RouteTarget as Sn, StartingInputsProps as Sr, createSyncApp as St, ScrollService as T, fanOut as Ti, RouteParams as Tn, StartingInputsRecord as Tr, CreateAppOptions as Tt, PersistedOptions as U, ShellFileResult as Un, Define as Ur, UiTreeNode as Ut, InspectionService as V, ShellFile as Vn, requirePlainData as Vr, FrameEntry as Vt, PersistedState as W, ShellFileType as Wn, Inject as Wr, UiTreeSnapshot as Wt, OpfsDirectory as X, ColorScheme as Xn, ControlledOptions as Xr, FramePhaseTimings as Xt, IndexedDbStorageOptions as Y, ShellStorageResult as Yn, sharedValue as Yr, FrameMetrics as Yt, OpfsFileHandle as Z, ColorSchemePreference as Zn, ControlledValue as Zr, GessoRuntime as Zt, renderRoot as _, ResourceStatus as _i, OutletProps as _n, ComponentHostResolver as _r, ShellLocalStore as _t, UiRole as a, Each as ai, FontFamilyDeclaration as an, UiOwnerReport as ar, classifyStorageError as at, SemanticsMirrorSink as b, select as bi, RouteGuard as bn, liveInput as br, GessoApp as bt, UiSemanticsPatch as c, each as ci, FontService as cn, UiSemanticsReport as cr, storageReadValue as ct, markNow as d, MutateOptions as di, RouteAnswer as dn, formatAge as dr, UndoableOptions as dt, themeTokenCell as ei, RuntimeInput as en, NodePathTarget as er, OpfsWritable as et, measureSpan as f, Mutation as fi, RouteMatch as fn, formatNodePath as fr, undoable as ft, RenderWorkerError as g, ResourceState as gi, RouteState as gn, printPropValue as gr, rememberedDirectory as gt, RenderWorkerApp as h, ResourceOptions as hi, RouterService as hn, formatStream as hr, UndoTransaction as ht, UI_SEMANTIC_STATES as i, show as ii, FontFaceLike as in, UiOwnerInput as ir, StorageRead as it, Presence as j, Equality as ji, AudioRequest as jn, OverlayScopeKey as jr, ShellHistoryMode as jt, observeMediaQuery as k, computed as ki, AudioAction as kn, OverlayPlacement as kr, WorkerAppOptions as kt, UiSemanticsRecord$1 as l, debounced as li, MediaOptions as ln, UiStreamReport as lr, UndoShortcutOptions as lt, setPerformanceMarks$1 as m, Resource as mi, RouterRoutes as mn, formatSourceLocation as mr, UndoStackOptions as mt, MARK_PREFIX as n, Show as ni, UiFramePhase as nn, UiInteractionReport as nr, StorageAdapter as nt, UiSemanticState as o, EachKey as oi, FontFamilyStatus as on, UiPropOrigin as or, storageErrorMessage as ot, performanceMarksEnabled as p, mutate as pi, RouterHistorySink as pn, formatNodeReport as pr, UndoStack as pt, ShellStorageOptions as q, ShellService as qn, SharedValues as qr, RuntimeToShellMessage as qt, UI_ROLES as r, ShowProps as ri, FontFaceDeclaration as rn, UiNodeReport as rr, StorageOutcome as rt, UiSemanticsMap$1 as s, EachProps as si, FontHost as sn, UiPropReport as sr, storageReadFailure as st, EditingState$1 as t, bind as ti, UI_FRAME_PHASES as tn, UiEnvironmentReport as tr, MemoryStorage as tt, markInstant as u, throttled as ui, MediaService as un, describeStream as ur, registerUndoShortcuts as ut, EditingMirrorTarget as v, resource as vi, RouteContext as vn, ComponentHost as vr, performShellStorage as vt, FocusService as w, FanOutOptions as wi, to as wn, StartingInputsKey as wr, WebMcpChoice as wt, EditingProxy as x, FanCell as xi, RouteOptions as xn, StartingInputs as xr, GessoAppOptions as xt, SemanticsMirror as y, SelectOptions as yi, RouteDefinition as yn, OverlayLayer as yr, shellStorageDenied as yt, audioClock as z, UiDuration as zn, createChannelRegistry as zr, DevtoolsEvent as zt };
+//# sourceMappingURL=index-DocVauCS.d.ts.map