gesso-framework 0.7.0 → 0.8.1

package/dist/{render-cydQ10Nd.js → render-DlhL5y0d.js}

@@ -1,9 +1,9 @@
-import { a as InternalState, f as outputTargetOf, m as withBodyOf, n as computed, o as internalState, s as InputCell, u as isOutputTarget } from "./computed-_cYcdczA.js";
+import { a as InternalState, c as forceInput, d as isOutputTarget, h as withBodyOf, l as input, n as computed, o as internalState, p as outputTargetOf, s as InputCell } from "./computed-DyW9SPpq.js";
 import { f as formatNodePath, g as printPropValue, r as isPortErrorMessage, u as describeStream, v as applyPatches, w as viewKeys, x as isChannelHostMessage } from "./WorkerPorts-m_hLRoPj.js";
 import { n as getComponentMetadata, t as createComponent } from "./createComponent-DJads88q.js";
 import { m as designedTheme } from "./app-De3z58x7.js";
-import { EMPTY, Subject, Subscription, map } from "rxjs";
-import { AnimationDriver, Box, Canvas2DRenderer, CanvasTextMeasurer, Column, Constraints, DefaultImageResolver, DefaultSvgResolver, DefaultVideoResolver, DirtyFlags, EnvironmentNotifier, FocusNotifier, IconRasterizer, LayoutEngine, LayoutInspector, LayoutNotifier, Stack, TEXT_RUN_ID_SEPARATOR, UiEditingController, UiEnvironmentKeys, UiEventType, UiFindController, UiFocusManager, UiFrame, UiGestureRecognizer, UiGraph, UiGraphBuilder, UiHitTester, UiInputDispatcher, UiInsetRegistry, UiKeyboardController, UiManualFrameClock, UiNodeType, UiPointerController, UiPointerEvent, UiScheduler, UiSelectionController, UiSharedElements, UiSpring, UiTimerFrameClock, UiTouchScroller, UiVirtualSheet, UiVirtualWindow, UiWheelController, VIRTUAL_INDEX_PROP, VIRTUAL_LEAD_PROP, VIRTUAL_SHEET_PROP, VIRTUAL_WINDOW_PROP, WebGPURenderer, buildSemanticsSubtree, buildSemanticsTree, bumpFontStack, clearOverrideProperty, createCanvasSurface, createTween, createWebGPUSurface, defaultMotion, defineModifier, describeOverrides, diffSemantics, dragSessionFor, dropIndexShifts, easings, fade, formatExplanation, insetsEqual, isComponentLikeElement, isObservable, isUiElement, isWebGPUAvailable, lightTheme, linear, linkOf, measure, mediaLoadsInFlight, motion, noInsets, propertyEffects, recordsEqual, registerFontStack, resolveCursor, rewalkSemantics, scrollBounds, scrollRange, scrollbarThumb, scrollsFromRight, semanticsInertAbove, semanticsMemory, setPerformanceMarks, textRunOfRecordId, writeOverrideProperty } from "gesso-core";
+import { EMPTY, Subject, Subscription, concat, map, of, skip } from "rxjs";
+import { AnimationDriver, Box, Canvas2DRenderer, CanvasTextMeasurer, Column, Constraints, DefaultImageResolver, DefaultSvgResolver, DefaultVideoResolver, DirtyFlags, EnvironmentNotifier, FocusNotifier, IconRasterizer, LayoutEngine, LayoutInspector, LayoutNotifier, Stack, TEXT_RUN_ID_SEPARATOR, Text, UiEditingController, UiEnvironmentKeys, UiEventType, UiFindController, UiFocusManager, UiFrame, UiGestureRecognizer, UiGraph, UiGraphBuilder, UiHitTester, UiInputDispatcher, UiInsetRegistry, UiKeyboardController, UiManualFrameClock, UiNodeType, UiPointerController, UiPointerEvent, UiScheduler, UiSelectionController, UiSharedElements, UiSpring, UiTimerFrameClock, UiTouchScroller, UiVirtualSheet, UiVirtualWindow, UiWheelController, VIRTUAL_INDEX_PROP, VIRTUAL_LEAD_PROP, VIRTUAL_SHEET_PROP, VIRTUAL_WINDOW_PROP, WebGPURenderer, buildSemanticsSubtree, buildSemanticsTree, bumpFontStack, clearOverrideProperty, clockOf, createCanvasSurface, createEnvironmentKey, createTween, createWebGPUSurface, defaultMotion, defineModifier, describeOverrides, diffSemantics, dragSessionFor, dropIndexShifts, durationIn, easingIn, fade, findEnvironmentKey, formatExplanation, insetsEqual, isComponentLikeElement, isObservable, isUiElement, isWebGPUAvailable, lightTheme, linear, linkOf, measure, mediaLoadsInFlight, motion, noInsets, propertyEffects, provided, recordsEqual, registerFontStack, resolveCursor, rewalkSemantics, scrollBounds, scrollRange, scrollbarThumb, scrollsFromRight, semanticsInertAbove, semanticsMemory, setPerformanceMarks, springIn, textRunOfRecordId, writeOverrideProperty } from "gesso-core";
 //#region src/Component.ts
 /**
 * Base class for all Gesso framework components.
@@ -161,6 +161,33 @@ function bounds(label) {
 	return cell;
 }
 //#endregion
+//#region src/liveInput.ts
+/** Where the component whose body is running keeps its live inputs, while it runs. */
+let target = null;
+/** Runs a component's body with its live inputs going to `into`; see `liveInput`. */
+function withLiveInputs(into, run) {
+	const previous = target;
+	target = into;
+	try {
+		return run();
+	} finally {
+		target = previous;
+	}
+}
+/**
+* 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.
+*/
+function liveInput(name, read) {
+	target?.set(name, read);
+}
+//#endregion
 //#region src/decorators.ts
 /**
 * Declares a class as a Gesso component.
@@ -455,6 +482,7 @@ function isClassComponent(component) {
 * declared the entry.
 */
 function physicalPlacement(placement, rtl) {
+	if (placement === "over") return placement;
 	const [side, align] = placement.split("-");
 	if (side === "top" || side === "bottom") {
 		if (align === void 0 || !rtl) return placement;
@@ -498,6 +526,149 @@ var OverlayService = class {
 		return this.entries.value.some((entry) => entry.id === id);
 	}
 };
+/**
+* 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.
+*/
+const OverlayScopeKey = createEnvironmentKey({
+	name: "gesso.overlayScope",
+	defaultValue: null
+});
+//#endregion
+//#region src/app/FocusService.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.
+*/
+/** The nodes a trap taken inside is modal only within: each `OverlayScope`'s. */
+const focusBounds = /* @__PURE__ */ new WeakSet();
+/** Makes a node one, for `OverlayScope`. */
+function boundFocus(node) {
+	focusBounds.add(node);
+}
+var FocusService = class {
+	/** The node holding focus, or null. A control binds its focus ring to this. */
+	focused = internalState(null);
+	/** Whether focus is confined to a subtree by an open trap. */
+	trapped = internalState(false);
+	/**
+	* Whether the focus held is focus the keyboard can see: reached by Tab
+	* or an arrow key, or by code with no pointer since, rather than by a
+	* press. CSS's `:focus-visible`, for something other than a ring that
+	* should answer the keyboard and not the click that happened to focus
+	* the same control: a tooltip, say.
+	*/
+	focusVisible = internalState(false);
+	manager = null;
+	detach = null;
+	/** Actions taken before the runtime installed a manager, in order. */
+	queued = [];
+	/** Installed by the runtime; without one every action is queued. */
+	setManager(manager) {
+		this.detach?.();
+		this.detach = null;
+		this.manager = manager;
+		if (manager === null) {
+			this.queued = [];
+			return;
+		}
+		const focusChange = manager.onFocusChange((node) => {
+			this.focused.value = node;
+			this.focusVisible.value = manager.focusVisible;
+			this.trapped.value = manager.trapped;
+		});
+		manager.setFocusBounds((node) => focusBounds.has(node));
+		const scopeChange = manager.onScopeChange(() => {
+			this.trapped.value = manager.trapped;
+		});
+		this.detach = () => {
+			focusChange();
+			scopeChange();
+		};
+		const pending = this.queued;
+		this.queued = [];
+		for (const action of pending) action(manager);
+		this.sync(manager);
+	}
+	/**
+	* Gives the node keyboard focus. Non-focusable nodes are ignored.
+	*
+	* The node is scrolled into view, unless `options.preventScroll` asks
+	* for the page to stay where it is, as `element.focus({ preventScroll:
+	* true })` does in a browser.
+	*/
+	focus(node, options) {
+		this.run((manager) => manager.focus(node, "program", options));
+	}
+	/** Drops focus without moving it anywhere. */
+	blur() {
+		this.run((manager) => manager.blur());
+	}
+	/** Moves focus to the next focusable node, wrapping around. */
+	focusNext() {
+		this.run((manager) => manager.focusNext());
+	}
+	/** Moves focus to the previous focusable node, wrapping around. */
+	focusPrevious() {
+		this.run((manager) => manager.focusPrevious());
+	}
+	/**
+	* 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) {
+		return this.manager?.tabStops(within) ?? [];
+	}
+	/**
+	* Confines focus to `scope` until `releaseTrap`, moving it inside if
+	* it was elsewhere. Traps nest: a dialog opened over a dialog traps
+	* again, and each release restores its own opener.
+	*/
+	trap(scope) {
+		this.run((manager) => manager.pushScope(scope));
+	}
+	/**
+	* Ends the innermost trap and returns focus to whatever held it when
+	* the trap was taken — the button that opened the dialog. Given the
+	* node trapped in, only that trap ends, and nothing when it ended
+	* already: a trap's subtree removed releases it, and a release after
+	* that would otherwise end the trap under it.
+	*/
+	releaseTrap(scope) {
+		this.run((manager) => manager.popScope(scope));
+	}
+	run(action) {
+		const manager = this.manager;
+		if (manager === null) {
+			this.queued.push(action);
+			return;
+		}
+		action(manager);
+		this.sync(manager);
+	}
+	sync(manager) {
+		this.focused.value = manager.focusedNode;
+		this.focusVisible.value = manager.focusVisible;
+		this.trapped.value = manager.trapped;
+	}
+};
 //#endregion
 //#region \0@oxc-project+runtime@0.143.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
@@ -509,7 +680,12 @@ function __decorate(decorators, target, key, desc) {
 //#endregion
 //#region src/overlay/OverlayLayer.ts
 let OverlayLayer = class OverlayLayer extends Component {
-	overlays;
+	runtimeOverlays;
+	/** The entries to draw, when not the runtime's: an `OverlayScope`'s. */
+	service = input(null);
+	get overlays() {
+		return this.service.value ?? this.runtimeOverlays;
+	}
 	render() {
 		return Box({
 			position: "absolute",
@@ -547,6 +723,7 @@ let OverlayLayer = class OverlayLayer extends Component {
 				top: entry.top,
 				bottom: entry.bottom,
 				zIndex: entry.zIndex,
+				...entry.placement === "over" && entry.anchor != null ? { hitTestable: false } : {},
 				...centering(entry),
 				...physicalEdges(entry, readsRightToLeft(environment)),
 				...inheritedFrom(environment),
@@ -556,7 +733,8 @@ let OverlayLayer = class OverlayLayer extends Component {
 		return elements;
 	}
 };
-__decorate([Inject(OverlayService)], OverlayLayer.prototype, "overlays", void 0);
+__decorate([Inject(OverlayService)], OverlayLayer.prototype, "runtimeOverlays", void 0);
+__decorate([Input()], OverlayLayer.prototype, "service", void 0);
 OverlayLayer = __decorate([Define("gesso-overlay-layer")], OverlayLayer);
 /**
 * The dim over the page, inside the backdrop rather than on it.
@@ -646,9 +824,31 @@ function inheritedFrom(node) {
 		theme: environment.get(UiEnvironmentKeys.theme),
 		textStyle: environment.get(UiEnvironmentKeys.textStyle),
 		color: environment.get(UiEnvironmentKeys.color),
-		contentColor: environment.get(UiEnvironmentKeys.contentColor)
+		contentColor: environment.get(UiEnvironmentKeys.contentColor),
+		provide: providedFrom(environment)
 	};
 }
+/** The built-in keys an entry's box carries by props of its own, or leaves to where it is drawn. */
+const CARRIED_BY_PROPS = new Set(Object.values(UiEnvironmentKeys).map((key) => key.name).filter((name) => name !== UiEnvironmentKeys.clock.name && name !== UiEnvironmentKeys.motion.name));
+/**
+* The rest of what the entry was opened under, re-provided: the clock
+* its animations run on, so a dialog opened on a settled frame is at
+* rest there and one opened in a slowed player slows, the motion its
+* names mean, and every key the
+* application provides itself, so a component in a dialog reads with
+* `ctx.environment` what the one that opened it reads.
+*/
+function providedFrom(environment) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (let at = environment; at !== null; at = at.parent) for (const name of at.providedKeys()) {
+		if (seen.has(name) || CARRIED_BY_PROPS.has(name)) continue;
+		seen.add(name);
+		const key = findEnvironmentKey(name);
+		if (key !== void 0) out.push(provided(key, environment.get(key)));
+	}
+	return out;
+}
 /**
 * The same values again whenever they change where the entry was
 * declared, for as long as it is open.
@@ -668,6 +868,7 @@ const followEnvironmentKind = defineModifier({
 			host.set("textStyle", textStyle);
 			host.set("color", host.environment(UiEnvironmentKeys.color, from));
 			host.set("contentColor", host.environment(UiEnvironmentKeys.contentColor, from));
+			if (from.environment !== null) host.set("provide", providedFrom(from.environment));
 			if (entry !== null) {
 				const edges = physicalEdges(entry, textStyle.textDirection === "rtl");
 				host.set("placement", edges.placement);
@@ -684,6 +885,36 @@ function followEnvironment(node, entry) {
 	})];
 }
 //#endregion
+//#region src/startingInputsKey.ts
+/**
+* The inputs components under a node start with, by component name,
+* over what their parents pass; see `StartingInputs`. Empty outside one.
+*/
+const StartingInputsKey = createEnvironmentKey({
+	name: "gesso.startingInputs",
+	defaultValue: {}
+});
+/** How many of each name have been made under each set of starting inputs, for a list's next. */
+const made = /* @__PURE__ */ new WeakMap();
+/** What a component named `name`, made at `anchor`, starts with: null for nothing. */
+function startingInputsFor(anchor, name) {
+	for (let at = anchor; at !== null; at = at.parent) if (at.environment !== null) {
+		const all = at.environment.get(StartingInputsKey);
+		const given = all[name];
+		if (given === void 0) return null;
+		if (!Array.isArray(given)) return given;
+		let counts = made.get(all);
+		if (counts === void 0) {
+			counts = /* @__PURE__ */ new Map();
+			made.set(all, counts);
+		}
+		const index = counts.get(name) ?? 0;
+		counts.set(name, index + 1);
+		return given[index] ?? null;
+	}
+	return null;
+}
+//#endregion
 //#region src/ComponentHost.ts
 /**
 * Owns a single component instance and its lifecycle.
@@ -710,6 +941,7 @@ function followEnvironment(node, entry) {
 var ComponentHost = class {
 	services;
 	channels;
+	anchor;
 	/** The class instance; undefined for a functional component. */
 	instance;
 	element;
@@ -731,14 +963,34 @@ var ComponentHost = class {
 	inputSubscriptions = /* @__PURE__ */ new Map();
 	/** A functional component's cells, by prop name, as they were handed out. */
 	functionalCells = /* @__PURE__ */ new Map();
+	/**
+	* 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.
+	*/
+	started;
+	/** What the parent passed for each started input at birth: a new value from it takes over. */
+	startedOver = /* @__PURE__ */ new Map();
+	/** A started input the parent passes as a stream: the start, then the stream's changes; one per input, so it is not resubscribed. */
+	startedStreams = /* @__PURE__ */ new Map();
+	/** What the component says it holds now, by input; see `liveInput`. */
+	live = /* @__PURE__ */ new Map();
+	/** Inputs a tool draws the component with over its parent's, until it ends them; see `previewInputs`. */
+	previewed = null;
+	/** A class's input values from before they were previewed, for the ones its parent does not pass. */
+	beforePreview = /* @__PURE__ */ new Map();
 	mountHooks = [];
 	unmountHooks = [];
 	/** True only while the component function runs; hooks may register then. */
 	rendering = false;
-	constructor(element, services = new ServiceRegistry(), channels = new ChannelRegistry()) {
+	constructor(element, services = new ServiceRegistry(), channels = new ChannelRegistry(), anchor = null) {
 		this.services = services;
 		this.channels = channels;
+		this.anchor = anchor;
 		this.element = element;
+		const started = startingInputsFor(anchor, element.tag);
+		this.started = started === null ? null : { ...started };
+		for (const name of Object.keys(this.started ?? {})) this.startedOver.set(name, element.props[name]);
 		if (isClassComponent(element.component)) {
 			this.instance = new element.component();
 			this.validateInputs();
@@ -793,14 +1045,68 @@ var ComponentHost = class {
 			this.wireInputs();
 			return;
 		}
-		for (const [name, cell] of this.functionalCells) this.applyInput(name, cell, props[name], true);
+		for (const [name, cell] of this.functionalCells) this.applyInput(name, cell, this.providedFor(name), true);
+	}
+	/**
+	* 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) {
+		const names = /* @__PURE__ */ new Set([...Object.keys(this.previewed ?? {}), ...Object.keys(values ?? {})]);
+		if (this.instance !== void 0) {
+			const cells = this.instance;
+			const inputs = new Set(getComponentMetadata(this.element.component).inputs);
+			for (const name of Object.keys(values ?? {})) if (inputs.has(name) && !this.beforePreview.has(name)) this.beforePreview.set(name, cells[name].getValue());
+			this.previewed = values;
+			this.wireInputs(names);
+			for (const [name, value] of this.beforePreview) if (values === null || !Object.hasOwn(values, name)) {
+				this.beforePreview.delete(name);
+				if (this.providedFor(name) === void 0) cells[name].next(value);
+			}
+			return;
+		}
+		this.previewed = values;
+		for (const name of names) {
+			const cell = this.functionalCells.get(name);
+			if (cell !== void 0) this.applyInput(name, cell, this.providedFor(name), true, true);
+		}
+	}
+	/** What an input is fed from: a preview's value for it, else what it was started with, else the parent's prop. */
+	providedFor(name) {
+		if (this.previewed !== null && Object.hasOwn(this.previewed, name)) return this.previewed[name];
+		const parent = this.element.props[name];
+		if (this.started !== null && Object.hasOwn(this.started, name)) {
+			if (parent !== this.startedOver.get(name)) {
+				delete this.started[name];
+				this.startedStreams.delete(name);
+				return parent;
+			}
+			if (isObservable(parent)) {
+				let stream = this.startedStreams.get(name);
+				if (stream === void 0) {
+					stream = concat(of(this.started[name]), parent.pipe(skip(1)));
+					this.startedStreams.set(name, stream);
+				}
+				return stream;
+			}
+			return this.started[name];
+		}
+		return this.element.props[name];
 	}
 	renderFunction() {
 		const component = this.element.component;
 		const context = this.createContext();
 		this.rendering = true;
 		try {
-			return withBodyOf(this.element.tag, () => component(this.createInputRecord(), context));
+			return withLiveInputs(this.live, () => withBodyOf(this.element.tag, () => component(this.createInputRecord(), context)));
 		} finally {
 			this.rendering = false;
 		}
@@ -820,7 +1126,7 @@ var ComponentHost = class {
 				cell = new InputCell(void 0);
 				cell.label = `${this.element.tag}.${name}`;
 				this.functionalCells.set(name, cell);
-				this.applyInput(name, cell, this.element.props[name], true);
+				this.applyInput(name, cell, this.providedFor(name), true);
 			}
 			return cell;
 		};
@@ -863,18 +1169,25 @@ var ComponentHost = class {
 				const cell = bounds(label ?? `${this.element.tag}.bounds`);
 				this.subscriptions.add(() => cell.complete());
 				return cell;
+			},
+			environment: (key) => {
+				for (let at = this.anchor; at !== null; at = at.parent) if (at.environment !== null) return at.environment.get(key);
+				return key.defaultValue;
 			}
 		};
 	}
-	wireInputs() {
+	wireInputs(forced = /* @__PURE__ */ new Set()) {
 		const metadata = getComponentMetadata(this.element.component);
-		const props = this.element.props;
 		for (const inputName of metadata.inputs) {
 			const cell = this.instance[inputName];
 			cell.label ??= `${metadata.tag}.${inputName}`;
-			this.applyInput(inputName, cell, props[inputName], false);
+			this.applyInput(inputName, cell, this.providedFor(inputName), false, forced.has(inputName));
 		}
 	}
+	/** What the component says each of its inputs holds now; see `liveInput`. */
+	liveInputs() {
+		return new Map([...this.live].map(([name, read]) => [name, read()]));
+	}
 	/**
 	* What the parent most recently supplied for each input, as given:
 	* a value, an element or a stream, whether or not the component has
@@ -894,8 +1207,8 @@ var ComponentHost = class {
 	* fallback)` supplies one — so a prop the parent stops passing is
 	* pushed through as `undefined`, which re-applies the fallback.
 	*/
-	applyInput(inputName, cell, provided, resetWhenAbsent) {
-		if (this.inputSources.has(inputName) && this.inputSources.get(inputName) === provided) return;
+	applyInput(inputName, cell, provided, resetWhenAbsent, force = false) {
+		if (!force && this.inputSources.has(inputName) && this.inputSources.get(inputName) === provided) return;
 		const previous = this.inputSubscriptions.get(inputName);
 		if (previous !== void 0) {
 			previous.unsubscribe();
@@ -914,12 +1227,19 @@ var ComponentHost = class {
 			return;
 		}
 		if (isObservable(provided)) {
-			const subscription = provided.subscribe((value) => pushInput(cell, value));
+			let first = force;
+			const subscription = provided.subscribe((value) => {
+				if (first) {
+					first = false;
+					forceInput(cell, value);
+				} else pushInput(cell, value);
+			});
 			this.inputSubscriptions.set(inputName, subscription);
 			this.subscriptions.add(subscription);
 			return;
 		}
-		pushInput(cell, provided);
+		if (force) forceInput(cell, provided);
+		else pushInput(cell, provided);
 	}
 	validateInputs() {
 		const metadata = getComponentMetadata(this.element.component);
@@ -988,7 +1308,7 @@ var ComponentHostResolver = class {
 		this.services = services;
 		this.channels = channels;
 	}
-	resolve(element, anchorId) {
+	resolve(element, anchorId, anchor) {
 		let host = this.hosts.get(anchorId);
 		if (host !== void 0 && host.component !== element.component) {
 			host.dispose();
@@ -996,7 +1316,7 @@ var ComponentHostResolver = class {
 			host = void 0;
 		}
 		if (host === void 0) {
-			host = new ComponentHost(element, this.services, this.channels);
+			host = new ComponentHost(element, this.services, this.channels, anchor ?? null);
 			this.hosts.set(anchorId, host);
 			this.pendingMounts.push(host);
 		} else host.updateProps(element.props);
@@ -1145,6 +1465,8 @@ var ShellService = class {
 	handler = null;
 	/** What `warnOnLeave` last said. */
 	leaving = false;
+	/** What `preferColorScheme` last asked for; null until it is asked. */
+	preferred = null;
 	scheme = internalState("light");
 	contrastState = internalState("standard");
 	pointerState = internalState("fine");
@@ -1262,6 +1584,10 @@ var ShellService = class {
 			type: "leaveWarning",
 			on: true
 		});
+		if (handler !== null && this.preferred !== null) handler({
+			type: "colorScheme",
+			preference: this.preferred
+		});
 	}
 	/**
 	* Called by the runtime when the shell reports the appearance.
@@ -1478,6 +1804,33 @@ var ShellService = class {
 			on
 		});
 	}
+	/**
+	* Asks the shell to report this appearance from now on: `light` or
+	* `dark` whatever the platform says, or `auto` to follow the platform
+	* again. `colorScheme` then reports the answer, as it does when the
+	* host calls `setColorScheme`, which is the same switch.
+	*
+	* For an application whose appearance setting is its own and stored:
+	* the host reads the stored choice before the first frame and starts
+	* with it (`createApp({ colorScheme })`), and the application, where
+	* the person changes it, says so here. Without this, an application in
+	* a render worker could not take back an override the host started it
+	* with, and `auto` would keep reporting the stored choice instead of
+	* the platform's. An application that stores nothing can combine its
+	* choice with `colorScheme` instead and never call this.
+	*
+	* A request, because the media query is the window's; and a state,
+	* like `warnOnLeave`, so a shell that arrives after it was asked is
+	* told. Asking for the same thing twice sends nothing.
+	*/
+	preferColorScheme(preference) {
+		if (preference === this.preferred) return;
+		this.preferred = preference;
+		this.handler?.({
+			type: "colorScheme",
+			preference
+		});
+	}
 	/** Called by the runtime when the shell reports the state. Not for applications. */
 	applyFullscreen(active) {
 		if (this.isFullscreen.value !== active) this.isFullscreen.value = active;
@@ -1728,6 +2081,44 @@ function shellFilesUnsupported(error = "There is no shell to reach files through
 		error
 	};
 }
+//#endregion
+//#region src/app/FrameService.ts
+/**
+* Every frame the runtime draws, as a component can hear it.
+*
+* The shell already receives these as `onFrame`, for an FPS readout or
+* a profiler on the host thread. A screen that wants to show its own
+* frame gap or input latency, as a demo of the thread model does,
+* needs them on this thread, and this is where the runtime puts them.
+* Injected like any service: `ctx.inject(FrameService).frames`.
+*/
+var FrameService = class {
+	subject = new Subject();
+	flusher = null;
+	/** Emits after each frame finishes, with what it cost and what it answered. */
+	frames = this.subject.asObservable();
+	/** Called by the runtime; not for components. */
+	publish(metrics) {
+		this.subject.next(metrics);
+	}
+	/** Called by the shell that drives the frames; not for components. */
+	setFlush(flush) {
+		this.flusher = flush;
+	}
+	/**
+	* 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() {
+		this.flusher?.();
+	}
+};
 /** A text node's text as the tree shows it. */
 function treeText(text) {
 	if (typeof text !== "string" || text === "") return;
@@ -2570,6 +2961,20 @@ var EditingService = class {
 		return this.controller.caretRectOf(node, offset);
 	}
 	/**
+	* The caret position nearest a point in a field, the point given as a
+	* pointer event gives it: where a press there would put the caret.
+	*
+	* What a field opened over text the person pointed at uses to start
+	* the caret where they pointed: ask once the field is laid out, then
+	* `select` that offset. Null when the node is not an editable, when it
+	* has not been laid out yet, or before the runtime has wired the
+	* controller: "ask again next frame", as for `caretRectOf`.
+	*/
+	offsetNear(node, x, y) {
+		if (node === null || this.controller === null) return null;
+		return this.controller.offsetNear(node, x, y);
+	}
+	/**
 	* Selects from `anchor` to `focus` and focuses the field the focus is
 	* in: within one field, or across the fields of an editing group (see
 	* `UiEditingGroup`). What an editor does after a command over a
@@ -2613,124 +3018,6 @@ var ScrollService = class {
 	}
 };
 //#endregion
-//#region src/app/FocusService.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.
-*/
-var FocusService = class {
-	/** The node holding focus, or null. A control binds its focus ring to this. */
-	focused = internalState(null);
-	/** Whether focus is confined to a subtree by an open trap. */
-	trapped = internalState(false);
-	/**
-	* Whether the focus held is focus the keyboard can see: reached by Tab
-	* or an arrow key, or by code with no pointer since, rather than by a
-	* press. CSS's `:focus-visible`, for something other than a ring that
-	* should answer the keyboard and not the click that happened to focus
-	* the same control: a tooltip, say.
-	*/
-	focusVisible = internalState(false);
-	manager = null;
-	detach = null;
-	/** Actions taken before the runtime installed a manager, in order. */
-	queued = [];
-	/** Installed by the runtime; without one every action is queued. */
-	setManager(manager) {
-		this.detach?.();
-		this.detach = null;
-		this.manager = manager;
-		if (manager === null) {
-			this.queued = [];
-			return;
-		}
-		const focusChange = manager.onFocusChange((node) => {
-			this.focused.value = node;
-			this.focusVisible.value = manager.focusVisible;
-		});
-		const scopeChange = manager.onScopeChange(() => {
-			this.trapped.value = manager.trapped;
-		});
-		this.detach = () => {
-			focusChange();
-			scopeChange();
-		};
-		const pending = this.queued;
-		this.queued = [];
-		for (const action of pending) action(manager);
-		this.sync(manager);
-	}
-	/**
-	* Gives the node keyboard focus. Non-focusable nodes are ignored.
-	*
-	* The node is scrolled into view, unless `options.preventScroll` asks
-	* for the page to stay where it is, as `element.focus({ preventScroll:
-	* true })` does in a browser.
-	*/
-	focus(node, options) {
-		this.run((manager) => manager.focus(node, "program", options));
-	}
-	/** Drops focus without moving it anywhere. */
-	blur() {
-		this.run((manager) => manager.blur());
-	}
-	/** Moves focus to the next focusable node, wrapping around. */
-	focusNext() {
-		this.run((manager) => manager.focusNext());
-	}
-	/** Moves focus to the previous focusable node, wrapping around. */
-	focusPrevious() {
-		this.run((manager) => manager.focusPrevious());
-	}
-	/**
-	* Confines focus to `scope` until `releaseTrap`, moving it inside if
-	* it was elsewhere. Traps nest: a dialog opened over a dialog traps
-	* again, and each release restores its own opener.
-	*/
-	trap(scope) {
-		this.run((manager) => manager.pushScope(scope));
-	}
-	/**
-	* Ends the innermost trap and returns focus to whatever held it when
-	* the trap was taken — the button that opened the dialog. Given the
-	* node trapped in, only that trap ends, and nothing when it ended
-	* already: a trap's subtree removed releases it, and a release after
-	* that would otherwise end the trap under it.
-	*/
-	releaseTrap(scope) {
-		this.run((manager) => manager.popScope(scope));
-	}
-	run(action) {
-		const manager = this.manager;
-		if (manager === null) {
-			this.queued.push(action);
-			return;
-		}
-		action(manager);
-		this.sync(manager);
-	}
-	sync(manager) {
-		this.focused.value = manager.focusedNode;
-		this.focusVisible.value = manager.focusVisible;
-		this.trapped.value = manager.trapped;
-	}
-};
-//#endregion
 //#region src/app/MediaService.ts
 /**
 * Where an `Image` finds its bitmap, an `Icon` its raster and a
@@ -3065,6 +3352,16 @@ var AnimationService = class {
 	*/
 	setMotion(motion) {
 		this.motionVocabulary = motion;
+		this.motionListener?.(motion);
+	}
+	motionListener = null;
+	/**
+	* 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) {
+		this.motionListener = listener;
 	}
 	get motion() {
 		return this.motionVocabulary;
@@ -3115,7 +3412,7 @@ var AnimationService = class {
 			tween.snap();
 			return tween.values;
 		}
-		return driver.start(tween);
+		return driver.start(tween, options.clock ?? null);
 	}
 	/**
 	* Pulls a number towards a value on a spring, with no duration.
@@ -3124,7 +3421,7 @@ var AnimationService = class {
 	* so a flick that changes direction bends rather than restarting.
 	*/
 	spring(cell, to, options = {}) {
-		const base = typeof options.spring === "string" || options.spring === void 0 ? this.motionVocabulary.springs[options.spring ?? "snappy"] : options.spring;
+		const base = springIn(this.motionVocabulary, options.spring);
 		const driver = this.driver;
 		const previous = driver?.animationFor(cell);
 		const animation = new UiSpring(cell, to, {
@@ -3143,7 +3440,7 @@ var AnimationService = class {
 			animation.snap();
 			return animation.values;
 		}
-		return driver.start(animation);
+		return driver.start(animation, options.clock ?? null);
 	}
 	/** Stops whatever is driving a cell, leaving it where it stands. */
 	stop(cell) {
@@ -3162,31 +3459,10 @@ var AnimationService = class {
 		return this.driver?.animationFor(cell);
 	}
 	resolveDuration(duration) {
-		return typeof duration === "number" ? duration : this.motionVocabulary.durations[duration];
+		return durationIn(this.motionVocabulary, duration);
 	}
 	resolveEasing(easing) {
-		if (typeof easing === "function") return easing;
-		return this.motionVocabulary.easings[easing] ?? easings.standard;
-	}
-};
-//#endregion
-//#region src/app/FrameService.ts
-/**
-* Every frame the runtime draws, as a component can hear it.
-*
-* The shell already receives these as `onFrame`, for an FPS readout or
-* a profiler on the host thread. A screen that wants to show its own
-* frame gap or input latency, as a demo of the thread model does,
-* needs them on this thread, and this is where the runtime puts them.
-* Injected like any service: `ctx.inject(FrameService).frames`.
-*/
-var FrameService = class {
-	subject = new Subject();
-	/** Emits after each frame finishes, with what it cost and what it answered. */
-	frames = this.subject.asObservable();
-	/** Called by the runtime; not for components. */
-	publish(metrics) {
-		this.subject.next(metrics);
+		return easingIn(this.motionVocabulary, easing);
 	}
 };
 //#endregion
@@ -3228,6 +3504,17 @@ var InspectionService = class {
 		return this.host.inspect(node);
 	}
 	/**
+	* Why the node has the size it has, as the layout decided it: for
+	* each axis, the rule that fixed it (`decidedBy`: its own length, a
+	* flex share, a stretch across its parent, its content, a clamp) and
+	* the sentences that say so. What a design tool needs to tell an
+	* element that fills its parent from one that only happens to be as
+	* wide, which the box alone cannot. Null before the node is laid out.
+	*/
+	explain(node) {
+		return this.host?.explain?.(node) ?? null;
+	}
+	/**
 	* Where the node is drawn, as `inspect(node).box` reports it, without
 	* the rest of the report: for an editor that reads the boxes of many
 	* nodes as its view moves (a minimap of a board of frames), where
@@ -3238,6 +3525,19 @@ var InspectionService = class {
 		return this.host.box?.(node) ?? this.host.inspect(node).box;
 	}
 	/**
+	* 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) {
+		if (this.host === null) throw new Error("InspectionService has nothing to measure before the runtime has built its tree.");
+		return this.host.screenBox?.(node) ?? this.box(node);
+	}
+	/**
 	* Draws a node as though it declared `value` for `property`, until
 	* the preview is ended or the node leaves the tree.
 	*
@@ -3255,6 +3555,43 @@ var InspectionService = class {
 	endPreview(node, property) {
 		this.host?.endPreview?.(node, property);
 	}
+	/**
+	* 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, inputs) {
+		this.host?.previewInputs?.(anchorId, inputs);
+	}
+	/** Ends a preview of a component's inputs: its parent's are its own again. */
+	endInputPreview(anchorId) {
+		this.host?.previewInputs?.(anchorId, null);
+	}
+	/**
+	* 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, action, value) {
+		if (this.host?.act === void 0) throw new Error("InspectionService cannot act before the runtime has built its tree.");
+		return this.host.act(node, action, value);
+	}
 };
 //#endregion
 //#region src/app/InputLatency.ts
@@ -3421,7 +3758,10 @@ var SmoothScroller = class {
 		const { min, max } = this.boundsOf(node, axis);
 		const target = clamp((pending ?? from) + delta, min, max);
 		if (pending !== void 0 && target === pending) return;
-		this.animations.spring(cell, target, { spring: SCROLL_SPRING });
+		this.animations.spring(cell, target, {
+			spring: SCROLL_SPRING,
+			clock: clockOf(node)
+		});
 	}
 	/**
 	* Shifts a running scroll by a coordinate correction.
@@ -3446,7 +3786,10 @@ var SmoothScroller = class {
 		const pending = this.destinationOf(state.cell);
 		if (pending === void 0) return;
 		state.lastWritten = state.cell.value;
-		this.animations.spring(state.cell, pending + delta, { spring: SCROLL_SPRING });
+		this.animations.spring(state.cell, pending + delta, {
+			spring: SCROLL_SPRING,
+			clock: clockOf(node)
+		});
 	}
 	/** Whether this container is being animated right now. */
 	isScrolling(node) {
@@ -3654,6 +3997,8 @@ var GessoRuntime = class {
 	lastEarlyFrame = -Infinity;
 	/** When the last discrete input was routed; see `answerInput`. */
 	lastDiscreteInput = -Infinity;
+	/** The wheel's steps since the last frame, added together; see `wheel`. */
+	heldWheel = null;
 	/** The display time the frame being drawn is for; see `FrameMetrics.time`. */
 	frameTime = null;
 	/** When the frame's first phase began, before its changes were collected; see `FrameMetrics.durationMs`. */
@@ -3763,6 +4108,11 @@ var GessoRuntime = class {
 	* them. Only populated while a listener is attached.
 	*/
 	semanticsBoxes = /* @__PURE__ */ new Map();
+	/** When a frame last moved something, and when the boxes were last swept; see `updateSemantics`. */
+	semanticsMovedAt = -Infinity;
+	semanticsSweptAt = -Infinity;
+	/** The sweep owed once a run of moving frames stops. */
+	semanticsSweepTimer = null;
 	/** What each semantics walk leaves for the next; see `SemanticsMemory`. */
 	semanticsMemory = semanticsMemory();
 	lastFocusedId = null;
@@ -3809,6 +4159,10 @@ var GessoRuntime = class {
 	* lays out, whichever comes first; see `resize`.
 	*/
 	laidOutOnce = false;
+	/** Frames in a row that threw; see `reportFrameError`. */
+	framesFailed = 0;
+	/** Nodes that declare `holdUnseen`, as frames have found them; see `updateHolds`. */
+	holdable = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.services = options.services ?? new ServiceRegistry();
 		this.channels = options.channels ?? new ChannelRegistry();
@@ -3902,7 +4256,8 @@ var GessoRuntime = class {
 					width: this.width,
 					height: this.height
 				}),
-				onLayout: (node, listener) => this.layoutNotifier.add(node, listener)
+				onLayout: (node, listener) => this.layoutNotifier.add(node, listener),
+				onFlowLayout: (node, listener) => this.layoutNotifier.addFlow(node, listener)
 			},
 			animations: this.animations,
 			sharedElements: this.sharedElements
@@ -3926,6 +4281,9 @@ var GessoRuntime = class {
 		if (options.fonts !== void 0) this.services.get(FontService).declare(options.fonts);
 		if (!this.services.has(AnimationService)) this.services.register(AnimationService);
 		this.services.get(AnimationService).setDriver(this.animations);
+		this.services.get(AnimationService).setMotionListener((motion) => {
+			if (this.graph.updateNodePropertyNow(this.graph.root, "provide", [provided(UiEnvironmentKeys.motion, motion)], DirtyFlags.Environment)) this.requestRepaint();
+		});
 		this.services.get(AudioService).setAnimations(this.services.get(AnimationService));
 		this.smoothScroller = new SmoothScroller(this.graph, this.services.get(AnimationService), (node, axis) => {
 			const record = this.engine.recordFor(node);
@@ -3997,6 +4355,7 @@ var GessoRuntime = class {
 		this.services.get(InspectionService).attach({
 			nodesAt: (x, y) => this.hitTester.hitStack(x, y),
 			inspect: (node) => this.inspectNode(node),
+			explain: (node) => this.engine.explain(node),
 			box: (node) => {
 				const box = this.engine.visibleBox(node);
 				return {
@@ -4006,8 +4365,22 @@ var GessoRuntime = class {
 					height: box.height
 				};
 			},
+			screenBox: (node) => {
+				const box = this.engine.screenBox(node);
+				return {
+					x: box.x,
+					y: box.y,
+					width: box.width,
+					height: box.height
+				};
+			},
 			preview: (node, property, value) => this.previewProperty(node, property, value),
-			endPreview: (node, property) => this.endPreviews(node, property)
+			endPreview: (node, property) => this.endPreviews(node, property),
+			previewInputs: (anchorId, inputs) => this.resolver.hostFor(anchorId)?.previewInputs(inputs),
+			act: (node, action, value) => this.graph.getNode(node.id) === node && this.actOn(node, value === void 0 ? { action } : {
+				action,
+				value
+			})
 		});
 		this.services.get(FocusService).setManager(this.input.focus);
 		this.services.get(EditingService).setController(this.input.editing);
@@ -4070,6 +4443,7 @@ var GessoRuntime = class {
 		this.frameErrorListener = listener;
 	}
 	reportFrameError(error) {
+		if (this.framesFailed++ === 0) this.requestRepaint();
 		const message = error instanceof Error ? error.message : String(error);
 		const stack = error instanceof Error ? error.stack : void 0;
 		if (this.frameErrorListener !== null) {
@@ -4236,6 +4610,51 @@ var GessoRuntime = class {
 		this.lastDiscreteInput = now();
 		this.drawEarly();
 	}
+	/**
+	* 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) {
+		const held = this.heldWheel;
+		if (held !== null && !sameWheel(held, step)) this.releaseWheel();
+		if (this.heldWheel === null) {
+			this.heldWheel = step;
+			this.scheduler.wake();
+			return;
+		}
+		const [, , deltaX, deltaY, modifiers, deltaMode, wheelDeltaY] = this.heldWheel;
+		const [x, y, moreX, moreY, , , moreWheelY, at] = step;
+		const legacy = wheelDeltaY === void 0 || moreWheelY === void 0 ? moreWheelY : wheelDeltaY + moreWheelY;
+		this.heldWheel = [
+			x,
+			y,
+			deltaX + moreX,
+			deltaY + moreY,
+			modifiers,
+			deltaMode,
+			legacy,
+			at
+		];
+	}
+	/** Hands the held wheel step to the input now, before what follows it; see `wheel`. */
+	releaseWheel() {
+		const held = this.heldWheel;
+		if (held === null) return;
+		this.heldWheel = null;
+		this.input.wheel.wheel(...held);
+	}
 	/** Draws the pending frame in a task of its own, if the guards in `answerInput` allow. */
 	drawEarly() {
 		if (!this.started || !this.visible || this.earlyFrame !== null || !this.scheduler.framePending) return;
@@ -4436,7 +4855,8 @@ var GessoRuntime = class {
 			source: PREVIEW,
 			name: "preview",
 			order: Number.MAX_SAFE_INTEGER,
-			value
+			value,
+			snap: true
 		}, propertyEffects(property));
 	}
 	endPreviews(node, property) {
@@ -4780,6 +5200,7 @@ var GessoRuntime = class {
 			listens: this.dispatcher.listenerTypes(node),
 			beneath: this.beneathAtPointer(node),
 			semantics: this.semanticsOf(node),
+			...this.interactionOf(node),
 			explanation: formatExplanation(this.engine.explain(node)),
 			...this.sourceReport(node)
 		};
@@ -4827,6 +5248,27 @@ var GessoRuntime = class {
 		const source = this.builder.sourceOf(node);
 		return source === void 0 ? {} : { source };
 	}
+	/** The props the node's `interactive` modifiers write while hovered and pressed, later ones over earlier. */
+	interactionOf(node) {
+		let hovered;
+		let pressed;
+		for (const modifier of this.builder.modifiersFor(node)?.modifiers ?? []) {
+			if (modifier.kind.name !== "interactive") continue;
+			const options = modifier.args;
+			if (options.hovered !== void 0) hovered = {
+				...hovered,
+				...options.hovered
+			};
+			if (options.pressed !== void 0) pressed = {
+				...pressed,
+				...options.pressed
+			};
+		}
+		return hovered === void 0 && pressed === void 0 ? {} : { interaction: {
+			...hovered === void 0 ? {} : { hovered },
+			...pressed === void 0 ? {} : { pressed }
+		} };
+	}
 	ownersOf(node) {
 		const owners = [];
 		for (let current = node; current !== null; current = current.parent) {
@@ -4838,11 +5280,14 @@ var GessoRuntime = class {
 					const value = ownerInput(supplied);
 					if (value !== void 0) inputs[name] = value;
 				}
+				const live = {};
+				for (const [name, value] of host.liveInputs()) if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") live[name] = value;
 				owners.push({
 					name: getComponentMetadata(host.component).tag,
 					anchorId: current.id,
 					...usedAt === void 0 ? {} : { usedAt },
-					...Object.keys(inputs).length === 0 ? {} : { inputs }
+					...Object.keys(inputs).length === 0 ? {} : { inputs },
+					...Object.keys(live).length === 0 ? {} : { live }
 				});
 			}
 		}
@@ -4999,7 +5444,9 @@ var GessoRuntime = class {
 	* reconciles rather than recreating, so a component whose class is
 	* the same object as before keeps its host and its `internalState`;
 	* one whose module was replaced is a different class, and its host
-	* is disposed and mounted again. Scroll offsets on containers that
+	* is disposed and mounted again with everything it rendered: its body
+	* made new objects for its children, and a child kept from before
+	* would go on holding the old ones. Scroll offsets on containers that
 	* survive are kept, because the node is kept. Component state in a
 	* replaced module is lost, which is the honest cost and the reason
 	* this is a development tool.
@@ -5051,6 +5498,10 @@ var GessoRuntime = class {
 			clearTimeout(this.rendererTimer);
 			this.rendererTimer = null;
 		}
+		if (this.semanticsSweepTimer !== null) {
+			clearTimeout(this.semanticsSweepTimer);
+			this.semanticsSweepTimer = null;
+		}
 		this.detachViewportInsetEnvironment?.();
 		this.detachViewportInsetEnvironment = null;
 		this.viewportInsetWrite?.();
@@ -5129,7 +5580,10 @@ var GessoRuntime = class {
 		if (isObservable(definition)) throw new Error("Root definition cannot be an Observable. Wrap it in a component or static element.");
 		if (isComponentLikeElement(definition)) {
 			if (depth > MAX_ROOT_COMPONENT_DEPTH) throw new Error(`Root component chain exceeded ${MAX_ROOT_COMPONENT_DEPTH} levels without producing an element.`);
-			const output = this.resolver.resolve(definition, `app:component:${depth}`);
+			const anchorId = `app:component:${depth}`;
+			const before = this.resolver.hostFor(anchorId);
+			if (before !== void 0 && before.component !== definition.component && this.root !== void 0) this.builder.reconcileChildren(this.root, []);
+			const output = this.resolver.resolve(definition, anchorId);
 			return this.resolveRootElement(output, depth + 1);
 		}
 		return definition;
@@ -5241,7 +5695,7 @@ var GessoRuntime = class {
 				op: "add",
 				node
 			})),
-			boxes: this.collectSemanticsBoxes(),
+			boxes: this.sweepSemanticsBoxes(),
 			focused: this.focusManager.focusedNode?.id ?? null
 		});
 	}
@@ -5343,18 +5797,21 @@ var GessoRuntime = class {
 		if (this.applyTextRunAction(action)) return;
 		const node = this.graph.getNode(action.id);
 		if (node === void 0 || !this.semantics.has(action.id)) return;
-		if (action.action === "focus") {
-			this.focusManager.focus(node);
-			return;
-		}
-		if (action.action === "setValue") {
-			this.focusManager.focus(node);
-			this.input.editing.replaceText(action.value ?? "");
-			return;
-		}
+		this.actOn(node, action);
+	}
+	/**
+	* 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.
+	*/
+	actOn(node, action) {
+		if (action.action === "focus") return this.focusManager.focus(node);
+		if (action.action === "setValue") return this.focusManager.focus(node) && this.input.editing.replaceText(action.value ?? "");
 		this.focusManager.focus(node);
 		const box = this.engine.screenBox(node);
 		this.dispatcher.dispatch(new UiPointerEvent(UiEventType.Click, box.x + box.width / 2, box.y + box.height / 2, 1), node);
+		return true;
 	}
 	/**
 	* An action on an inline link, which is a run and not a node.
@@ -5398,7 +5855,7 @@ var GessoRuntime = class {
 			else patches = this.rescopeSemantics(frame) ?? this.restructureSemantics(frame) ?? this.rebuildSemantics();
 		}
 		if (listener === null) return;
-		const boxes = moved || patches.length > 0 ? this.collectSemanticsBoxes() : EMPTY_BOXES;
+		const boxes = patches.length > 0 ? this.sweepSemanticsBoxes() : moved ? this.movedSemanticsBoxes() : EMPTY_BOXES;
 		const focused = this.focusManager.focusedNode?.id ?? null;
 		const focusMoved = focused !== this.lastFocusedId;
 		this.lastFocusedId = focused;
@@ -5695,6 +6152,70 @@ var GessoRuntime = class {
 		return ids;
 	}
 	/**
+	* 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.
+	*/
+	movedSemanticsBoxes() {
+		const at = now();
+		const resting = at - this.semanticsMovedAt > SEMANTICS_SETTLE_MS;
+		this.semanticsMovedAt = at;
+		if (resting || at - this.semanticsSweptAt > SEMANTICS_MOST_STALE_MS) return this.sweepSemanticsBoxes();
+		if (this.semanticsSweepTimer === null) this.scheduleSemanticsSweep(SEMANTICS_SETTLE_MS);
+		return this.focusedSemanticsBox();
+	}
+	/** Sweeps the boxes once the moving has stopped, and sends what changed. */
+	scheduleSemanticsSweep(wait) {
+		this.semanticsSweepTimer = setTimeout(() => {
+			this.semanticsSweepTimer = null;
+			const listener = this.semanticsListener;
+			if (listener === null) return;
+			const left = this.semanticsMovedAt + SEMANTICS_SETTLE_MS - now();
+			if (left > 0) {
+				this.scheduleSemanticsSweep(left);
+				return;
+			}
+			const boxes = this.sweepSemanticsBoxes();
+			if (boxes.length > 0) listener({
+				patches: EMPTY_PATCHES,
+				boxes
+			});
+		}, Math.max(1, wait));
+	}
+	sweepSemanticsBoxes() {
+		this.semanticsSweptAt = now();
+		if (this.semanticsSweepTimer !== null) {
+			clearTimeout(this.semanticsSweepTimer);
+			this.semanticsSweepTimer = null;
+		}
+		return this.collectSemanticsBoxes();
+	}
+	/** The focused node's box when it differs from the one last sent, as `collectSemanticsBoxes` would give it. */
+	focusedSemanticsBox() {
+		const focused = this.focusManager.focusedNode;
+		if (focused === null || focused === void 0 || !this.semantics.has(focused.id) || this.engine.recordFor(focused) === void 0) return EMPTY_BOXES;
+		const box = this.engine.screenBox(focused);
+		const last = this.semanticsBoxes.get(focused.id);
+		if (last !== void 0 && boxesEqual(last, box)) return EMPTY_BOXES;
+		this.semanticsBoxes.set(focused.id, box);
+		return [{
+			id: focused.id,
+			box
+		}];
+	}
+	/**
 	* The mirrored nodes whose box differs from the one last sent, and
 	* which are on screen.
 	*
@@ -5793,6 +6314,7 @@ var GessoRuntime = class {
 					childX = x - (rec.scrollable ? rec.scrollX : 0);
 					childY = y - (rec.scrollable ? rec.scrollY : 0);
 				}
+				if (node.hold !== null && !(focused != null && focused.heldBy === node)) continue;
 				for (let child = node.lastChild; child !== null; child = child.previousSibling) stack.push([
 					child,
 					childX,
@@ -5921,6 +6443,7 @@ var GessoRuntime = class {
 		this.frameBegan = now();
 		this.phaseTimings = emptyPhaseTimings();
 		this.frameTime = time;
+		this.releaseWheel();
 		this.phaseTimings.ticks = this.timePhase(() => this.visible && this.animations.isRunning, () => this.animations.advance(time));
 		this.scheduleAnimationTick(time);
 		this.phaseTimings.patches = this.timePhase(() => this.replicas.some((replica) => replica.hasPendingPatches), () => {
@@ -6092,10 +6615,18 @@ var GessoRuntime = class {
 				scrollY: record?.scrollY ?? 0
 			};
 		};
+		const readFlow = (node) => {
+			const record = this.engine.recordFor(node);
+			return {
+				box: record === void 0 ? NO_BOX : this.engine.worldBox(node),
+				scrollX: record?.scrollX ?? 0,
+				scrollY: record?.scrollY ?? 0
+			};
+		};
 		this.deferredReveals = [];
 		try {
 			for (;;) {
-				if (!this.layoutNotifier.isEmpty()) this.layoutNotifier.notify(read);
+				if (!this.layoutNotifier.isEmpty()) this.layoutNotifier.notify(read, readFlow);
 				if (!this.layoutPending()) {
 					this.finishSettling(settled.passes > 0);
 					if (!this.layoutPending()) break;
@@ -6144,6 +6675,39 @@ var GessoRuntime = class {
 		this.warnedLayoutPasses = true;
 		console.warn(`Gesso: a frame laid out ${MAX_LAYOUT_PASSES} times and its layout listeners were still changing it, so it was painted unsettled and the rest left for the next frame. Something on \`host.onLayout\` (a breakpoint, a sizeContainer, a Responsive, a modifier of your own) is writing a property that changes the box it is listening to, back and forth. Shown once.`);
 	}
+	/**
+	* Holds each subtree that declares `holdUnseen` while it cannot be
+	* read, and lets it go on the frame it can (see `UiGraph.hold`).
+	*
+	* Decided after the frame is drawn, from where it was drawn: a subtree
+	* is only ever held once it has been laid out and painted, so what is
+	* kept of it is what it showed, and one let go catches up on the next
+	* frame, which its own marks arm. Only frames that moved or laid
+	* something out can change the answer, so the rest pay nothing.
+	*/
+	updateHolds(frame, laidOut) {
+		let found = false;
+		for (const [node, flags] of frame.entries()) if ((flags & DirtyFlags.Properties) !== 0 && node.properties.get("holdUnseen") !== void 0 && !this.holdable.has(node)) {
+			this.holdable.add(node);
+			found = true;
+		}
+		if (this.holdable.size === 0 || !laidOut && !found) return;
+		for (const node of this.holdable) {
+			const how = node.properties.get("holdUnseen");
+			if (how === void 0 || this.graph.getNode(node.id) !== node) {
+				this.graph.release(node);
+				this.holdable.delete(node);
+				continue;
+			}
+			const rec = this.engine.recordFor(node);
+			if (rec === void 0 || !(rec.width > 0) || !(rec.height > 0)) continue;
+			const box = this.engine.screenBox(node);
+			const margin = how === true ? 0 : how.margin ?? 0;
+			const below = how === true ? 0 : how.belowScale ?? 0;
+			if (box.x + box.width > -margin && box.y + box.height > -margin && box.x < this.width + margin && box.y < this.height + margin && box.width / rec.width >= below) this.graph.release(node);
+			else this.graph.hold(node);
+		}
+	}
 	handleFrame(collected) {
 		const root = this.root;
 		if (root === void 0) return;
@@ -6175,11 +6739,13 @@ var GessoRuntime = class {
 			overlay: overlay?.shapes,
 			changes
 		}));
+		this.updateHolds(frame, laidOut);
 		if (overlay !== null) {
 			if (laidOut) this.sendInspection();
 			this.scheduleInspectorRepaint(overlay.nextChange);
 		}
 		this.sendDevtoolsUpdates(frame);
+		this.framesFailed = 0;
 		const finished = now();
 		const elapsed = finished - (this.frameBegan ?? started);
 		this.frameBegan = null;
@@ -6522,6 +7088,14 @@ function semanticIndices(list) {
 * one frame still hands the mirror the rows it is about to show.
 */
 const SEMANTICS_VIEWPORT_MARGIN = 400;
+/**
+* How long a run of moving frames has to pause before the mirrored
+* boxes are swept again; see `movedSemanticsBoxes`. Longer than the gap
+* between a trackpad's wheel events, so a pan is one run.
+*/
+const SEMANTICS_SETTLE_MS = 120;
+/** The longest the mirrored boxes go unswept while something keeps moving: an endless animation still gets them. */
+const SEMANTICS_MOST_STALE_MS = 1e3;
 const EMPTY_PATCHES = [];
 const EMPTY_BOXES = [];
 function boxesEqual(a, b) {
@@ -6536,6 +7110,19 @@ function boxesEqual(a, b) {
 function frameChangedTree(frame) {
 	return frameNeedsSemantics(frame);
 }
+/** The box a node with no record reports. */
+const NO_BOX = {
+	x: 0,
+	y: 0,
+	width: 0,
+	height: 0
+};
+/** Whether two wheel steps can be added together: the same keys held, in the same unit. */
+function sameWheel(a, b) {
+	const [, , , , keysA, unitA] = a;
+	const [, , , , keysB, unitB] = b;
+	return unitA === unitB && (keysA?.ctrl ?? false) === (keysB?.ctrl ?? false) && (keysA?.shift ?? false) === (keysB?.shift ?? false) && (keysA?.alt ?? false) === (keysB?.alt ?? false) && (keysA?.meta ?? false) === (keysB?.meta ?? false);
+}
 function frameNeedsSemantics(frame) {
 	return frame.anyFlags(DirtyFlags.Semantics | DirtyFlags.Children);
 }
@@ -6752,25 +7339,58 @@ async function loadModule(module, load) {
 }
 /** The export to draw, or why none can be chosen. */
 function chooseExport(exports, wanted, module) {
-	const drawable = (value) => typeof value === "function" || isUiElement(value);
+	const drawable = (value) => typeof value === "function" || isUiElement(value) || examplesOf(value) !== null;
 	if (wanted !== void 0) {
-		if (!drawable(exports[wanted])) return `${module} has no component or element exported as ${wanted}. It exports ${list(exports, drawable)}.`;
+		const [head, ...rest] = wanted.split(".");
+		let value = exports[head];
+		for (const key of rest) value = typeof value === "object" && value !== null ? value[key] : void 0;
+		if (!drawable(value)) return `${module} has no component or element exported as ${wanted}. It exports ${list(exports, drawable)}.`;
+		const examples = examplesOf(value);
 		return {
 			name: wanted,
-			value: exports[wanted]
+			value: examples === null ? value : examplesSheet(examples)
 		};
 	}
+	const asDrawn = (value) => {
+		const examples = examplesOf(value);
+		return examples === null ? value : examplesSheet(examples);
+	};
 	if (drawable(exports.default)) return {
 		name: "default",
-		value: exports.default
+		value: asDrawn(exports.default)
 	};
 	const candidates = Object.keys(exports).filter((name) => /^[A-Z]/.test(name) && drawable(exports[name]));
 	if (candidates.length === 1) return {
 		name: candidates[0],
-		value: exports[candidates[0]]
+		value: asDrawn(exports[candidates[0]])
 	};
 	return candidates.length === 0 ? `${module} exports nothing to draw: no component, and no element.` : `${module} exports ${candidates.join(", ")}; say which with export.`;
 }
+/**
+* An object of examples, as a component's states are kept for a design
+* tool (`export const Button = { Primary: <Button … />, … }`): each
+* element by its name, or null for anything else.
+*/
+function examplesOf(value) {
+	if (typeof value !== "object" || value === null || isUiElement(value) || Array.isArray(value)) return null;
+	const entries = Object.entries(value).filter((entry) => isUiElement(entry[1]));
+	return entries.length === 0 ? null : entries;
+}
+/** Every example, each under its name, down the frame. */
+function examplesSheet(examples) {
+	return Column({
+		gap: 24,
+		padding: 16
+	}, ...examples.map(([name, element]) => Column({
+		key: name,
+		gap: 8
+	}, Text({
+		text: name,
+		fontSize: 12,
+		fontWeight: "600",
+		color: "textMuted"
+	}), element)));
+}
 function list(exports, keep) {
 	const names = Object.keys(exports).filter((name) => keep(exports[name]));
 	return names.length === 0 ? "nothing that can be drawn" : names.join(", ");
@@ -6790,6 +7410,6 @@ function failure(text) {
 	};
 }
 //#endregion
-export { modifiersFrom as A, Define as B, treeText as C, epochNow as D, epochFromEvent as E, OverlayService as F, bounds as G, Input as H, isClassComponent as I, ServiceRegistry as K, ChannelRegistry as L, ComponentHost as M, OverlayLayer as N, isDiscreteInputMessage as O, __decorate as P, ChannelReplica as R, AudioService as S, shellFilesUnsupported as T, Output as U, Inject as V, BoundsCell as W, buildPath as _, UI_FRAME_PHASES as a, parseUrl as b, AnimationService as c, MediaService as d, FocusService as f, RouterService as g, FindService as h, GessoRuntime as i, ComponentHostResolver as j, isInputMessage as k, TextService as l, EditingService as m, renderFrame as n, InspectionService as o, ScrollService as p, Component as q, isClaimedError as r, FrameService as s, renderModule as t, FontService as u, formatUrl as v, ShellService as w, RouteState as x, parsePattern as y, Channel as z };
+export { ComponentHostResolver as A, ChannelRegistry as B, ShellService as C, isDiscreteInputMessage as D, epochNow as E, FocusService as F, Input as G, Channel as H, boundFocus as I, BoundsCell as J, Output as K, OverlayScopeKey as L, StartingInputsKey as M, OverlayLayer as N, isInputMessage as O, __decorate as P, OverlayService as R, FrameService as S, epochFromEvent as T, Define as U, ChannelReplica as V, Inject as W, ServiceRegistry as X, bounds as Y, Component as Z, parsePattern as _, UI_FRAME_PHASES as a, AudioService as b, TextService as c, ScrollService as d, EditingService as f, formatUrl as g, buildPath as h, GessoRuntime as i, ComponentHost as j, modifiersFrom as k, FontService as l, RouterService as m, renderFrame as n, InspectionService as o, FindService as p, liveInput as q, isClaimedError as r, AnimationService as s, renderModule as t, MediaService as u, parseUrl as v, shellFilesUnsupported as w, treeText as x, RouteState as y, isClassComponent as z };
 
-//# sourceMappingURL=render-cydQ10Nd.js.map
+//# sourceMappingURL=render-DlhL5y0d.js.map