vintage-frames 0.14.1 → 0.15.0

package/dist/shell/windows.js

@@ -27,19 +27,29 @@ async function g(e, { when: t } = {}) {
 	for (let t of n) if (!(t.closest("[hidden]") || !t.checkVisibility()) && !(t.tabIndex < 0 && !t.localName.startsWith("vf-")) && (t.focus({ preventScroll: !0 }), h(e))) return !0;
 	return !1;
 }
-function _(m, _) {
-	let { defaultApp: v, savedPin: ee = () => null } = _, y = [], b = (e, t, n) => {
-		e.addEventListener(t, n), y.push(() => e.removeEventListener(t, n));
-	}, x = () => ({
+function ee(m, ee) {
+	let { defaultApp: te, savedPin: ne = () => null } = ee, _ = [], v = (e, t, n) => {
+		e.addEventListener(t, n), _.push(() => e.removeEventListener(t, n));
+	}, y = () => ({
 		width: m.width,
 		height: m.height
-	}), S = () => m.windowArea, C = /* @__PURE__ */ new Map(), w = /* @__PURE__ */ new Map(), T = /* @__PURE__ */ new Map(), E = /* @__PURE__ */ new Map(), D = /* @__PURE__ */ new Map(), O = /* @__PURE__ */ new WeakMap(), k = {}, A = () => a(S().top, k), j = /* @__PURE__ */ new Set(), M = !1, N = () => {
-		if (!M) for (let e of [...j]) e();
-	}, P = /* @__PURE__ */ new Set(), F = () => {
-		for (let e of [...P]) e();
-	}, I = /* @__PURE__ */ new Set(), L = /* @__PURE__ */ new Set(), R = /* @__PURE__ */ new Set(), z = () => null, B = () => !1;
-	function V(n, r) {
-		let i = S(), a = t(n), o = (e) => Math.floor(e / a) * a, s = Math.ceil(i.top / a) * a, c = i.left + i.width, l = i.top + i.height, { width: u, height: d } = r;
+	}), b = () => m.windowArea, x = /* @__PURE__ */ new Map(), S = /* @__PURE__ */ new Map(), C = /* @__PURE__ */ new Map(), w = /* @__PURE__ */ new Map(), T = /* @__PURE__ */ new Map(), E = /* @__PURE__ */ new WeakMap(), D = {}, O = () => a(b().top, D), k = /* @__PURE__ */ new Set(), A = !1, j = () => {
+		if (!A) for (let e of [...k]) e();
+	}, M = /* @__PURE__ */ new Set(), N = () => {
+		for (let e of [...M]) e();
+	}, P = /* @__PURE__ */ new Set(), F = /* @__PURE__ */ new Set(), I = /* @__PURE__ */ new Set(), L = /* @__PURE__ */ new Set(), R = /* @__PURE__ */ new Map(), z = [], re = (e) => {
+		for (let t = e; t; t = t.parentElement) if (R.has(t)) return t;
+		return null;
+	}, B = (e) => e.isConnected && (e.matches("vf-dialog[open]") || !!e.querySelector("vf-dialog[open]")), V = () => {
+		let e = z.filter((e) => R.has(e) && B(e));
+		for (let t of R.keys()) !e.includes(t) && B(t) && e.push(t);
+		if (!(e.length === z.length && e.every((e, t) => e === z[t]))) {
+			z = e;
+			for (let e of [...L]) e();
+		}
+	}, H = () => null, U = () => !1;
+	function W(n, r) {
+		let i = b(), a = t(n), o = (e) => Math.floor(e / a) * a, s = Math.ceil(i.top / a) * a, c = i.left + i.width, l = i.top + i.height, { width: u, height: d } = r;
 		n.resizable && (u != null && Number.isFinite(u) && (u = Math.min(u, o(i.width))), d != null && Number.isFinite(d) && (d = Math.min(d, o(Math.max(0, l - s)))));
 		let p = u ?? n.width ?? 0, m = d ?? n.height ?? 0;
 		return {
@@ -49,13 +59,13 @@ function _(m, _) {
 			height: d
 		};
 	}
-	let H = (t, n) => {
-		t.left = e(n.left, t), t.top = e(n.top, t), n.width != null && Number.isFinite(n.width) && (t.width = n.width), n.height != null && Number.isFinite(n.height) && (t.height = n.height), O.delete(t);
-	}, U = (e) => {
-		let t = C.get(e)?.place;
-		return t ? V(e, t(S())) : null;
-	}, W = (e, t) => {
-		let n = C.get(e)?.policy;
+	let G = (t, n) => {
+		t.left = e(n.left, t), t.top = e(n.top, t), n.width != null && Number.isFinite(n.width) && (t.width = n.width), n.height != null && Number.isFinite(n.height) && (t.height = n.height), E.delete(t);
+	}, K = (e) => {
+		let t = x.get(e)?.place;
+		return t ? W(e, t(b())) : null;
+	}, q = (e, t) => {
+		let n = x.get(e)?.policy;
 		if (n) return n(t);
 		if (!e.resizable) return { size: {
 			width: t.width,
@@ -66,7 +76,7 @@ function _(m, _) {
 			width: r,
 			height: i
 		} };
-	}, G = (e, t, n = W(e, p(e))) => V(e, c(t, x(), A(), n)), te = (e, t) => {
+	}, J = (e, t, n = q(e, p(e))) => W(e, c(t, y(), O(), n)), ie = (e, t) => {
 		let n = p(e);
 		return [
 			"left",
@@ -77,71 +87,71 @@ function _(m, _) {
 			let r = t[e];
 			return r == null || !Number.isFinite(r) || n[e] === r;
 		});
-	}, ne = (e) => {
-		let t = [...C].filter(([t, n]) => t !== e && !t.hidden && !n.palette).map(([e]) => p(e));
-		return r(l(S()), t).slot;
-	}, K = v, q = (e) => e instanceof n && C.get(e)?.app || v;
-	function J() {
+	}, ae = (e) => {
+		let t = [...x].filter(([t, n]) => t !== e && !t.hidden && !n.palette).map(([e]) => p(e));
+		return r(l(b()), t).slot;
+	}, Y = te, X = (e) => e instanceof n && x.get(e)?.app || te;
+	function oe() {
 		let e = !1;
-		for (let [t, n] of C) {
+		for (let [t, n] of x) {
 			if (!n.palette) continue;
-			let r = n.app === K && n.palette();
+			let r = n.app === Y && n.palette();
 			t.hidden !== !r && (t.hidden = !r, r && m.bringToFront(t), e = !0);
 		}
-		e && N();
+		e && j();
 	}
-	let re = (e) => {
+	let se = (e) => {
 		let t = document.activeElement?.closest("vf-window");
-		!(t instanceof n) || t === e || !C.has(t) || C.get(t).palette || (e ? Y(e) : B(null, null));
-	}, Y = (e) => void g(e, { when: () => m.activeWindow === e }), X = (e) => {
-		re(e);
-		for (let t of [...L]) t(e);
-		let t = q(e);
-		if (t !== K) {
-			K = t, J();
-			for (let e of [...R]) e(K);
+		!(t instanceof n) || t === e || !x.has(t) || x.get(t).palette || (e ? Z(e) : U(null, null));
+	}, Z = (e) => void g(e, { when: () => m.activeWindow === e }), ce = (e) => {
+		se(e);
+		for (let t of [...F]) t(e);
+		let t = X(e);
+		if (t !== Y) {
+			Y = t, oe();
+			for (let e of [...I]) e(Y);
 		}
 	};
-	b(m, "vf-activate", (e) => X(e.detail.window)), b(m, "vf-close", (e) => {
+	v(m, "vf-activate", (e) => ce(e.detail.window)), v(m, "vf-close", (e) => {
 		let t = e.target;
-		t instanceof n && C.has(t) && $.requestClose(t);
+		t instanceof n && x.has(t) && $.requestClose(t);
 	});
-	let Z = 0, Q = (e) => {
-		!(e.target instanceof n) || !C.has(e.target) || Z || (Z = window.setTimeout(() => {
-			Z = 0, N();
+	let Q = 0, le = (e) => {
+		!(e.target instanceof n) || !x.has(e.target) || Q || (Q = window.setTimeout(() => {
+			Q = 0, j();
 		}, 0));
 	};
-	m.addEventListener("vf-placement-change", Q), y.push(() => m.removeEventListener("vf-placement-change", Q)), b(m, "vf-resize", (e) => {
-		e.detail?.commit && N();
+	m.addEventListener("vf-placement-change", le), _.push(() => m.removeEventListener("vf-placement-change", le)), v(m, "vf-resize", (e) => {
+		e.detail?.commit && j();
 	});
-	let ie = (e) => {
-		let t = C.get(e);
-		t && (C.delete(e), O.delete(e), t.palette || F(), N());
-	}, ae = (n, r, i, a) => {
-		let l = p(n), u = C.get(n);
+	let ue = (e) => {
+		let t = x.get(e);
+		t && (x.delete(e), E.delete(e), t.palette || N(), j());
+	}, de = (n, r, i, a) => {
+		let l = p(n), u = x.get(n);
 		if (u?.keep && o(l, u.keep(a))) {
-			H(n, V(n, u.keep(S())));
+			G(n, W(n, u.keep(b())));
 			return;
 		}
-		let d = O.get(n), f = !!d && n.resizable && (d.width !== l.width || d.height !== l.height), m = !d || d.left !== l.left || d.top !== l.top || f || !d ? s(l, r, A()) : d.pin, h = c(m, i, A(), W(n, l));
+		let d = E.get(n), f = !!d && n.resizable && (d.width !== l.width || d.height !== l.height), m = !d || d.left !== l.left || d.top !== l.top || f || !d ? s(l, r, O()) : d.pin, h = c(m, i, O(), q(n, l));
 		if (n.left = e(h.left, n), n.top = e(h.top, n), n.resizable) {
-			let r = t(n), i = S(), a = Math.ceil(i.top / r) * r, o = Math.floor(i.width / r) * r, s = Math.floor(Math.max(0, i.top + i.height - a) / r) * r;
+			let r = t(n), i = b(), a = Math.ceil(i.top / r) * r, o = Math.floor(i.width / r) * r, s = Math.floor(Math.max(0, i.top + i.height - a) / r) * r;
 			n.width = Math.min(e(h.width, n), o), n.height = Math.min(e(h.height, n), s);
 		}
-		O.set(n, {
+		E.set(n, {
 			pin: m,
 			...p(n)
 		});
 	}, $ = {
 		get area() {
-			return S();
+			return b();
 		},
 		get front() {
-			return K;
+			return Y;
 		},
 		adopt(e, t) {
 			let n = t.palette;
-			if (C.set(e, {
+			if (x.set(e, {
 				app: t.app,
 				item: t.item ?? null,
 				place: t.place ?? null,
@@ -149,151 +159,180 @@ function _(m, _) {
 				keep: t.keep ?? null,
 				palette: n ? n === !0 ? () => !0 : n : null,
 				close: t.close ?? null
-			}), t.pin) H(e, G(e, t.pin));
+			}), t.pin) G(e, J(e, t.pin));
 			else {
-				let t = U(e);
-				t && H(e, t);
+				let t = K(e);
+				t && G(e, t);
 			}
 			if (n) {
-				let t = C.get(e);
-				e.hidden = !(t.app === K && t.palette());
+				let t = x.get(e);
+				e.hidden = !(t.app === Y && t.palette());
 			}
-			m.activeWindow === e && X(e), n || F(), N();
+			m.activeWindow === e && ce(e), n || N(), j();
 		},
 		open(e) {
 			let t = e.item == null ? null : $.windowFor(e.item);
-			if (t) return m.bringToFront(t), Y(t), t;
+			if (t) return m.bringToFront(t), Z(t), t;
 			let n = e.create(), r = {
 				width: n.width ?? 0,
 				height: n.height ?? 0
-			}, a = ne();
+			}, a = ae();
 			m.append(n);
 			let o = e.item ?? null;
 			return $.adopt(n, {
 				app: e.app,
 				item: o,
 				place: e.place ?? ((e) => i(e, r, l(e), a)),
-				pin: o == null ? null : T.get(o)?.pin ?? ee(o),
+				pin: o == null ? null : C.get(o)?.pin ?? ne(o),
 				policy: e.policy ?? null,
 				keep: e.keep ?? null,
 				close: e.close ?? null
-			}), o != null && T.delete(o), m.bringToFront(n), e.from && n.show({ from: e.from }), Y(n), n;
+			}), o != null && C.delete(o), m.bringToFront(n), e.from && n.show({ from: e.from }), Z(n), n;
 		},
 		close(e, { to: t } = {}) {
-			let n = C.get(e), r = n?.item ?? null, i = n?.app ?? null, a = t === void 0 ? i == null ? null : z(r, i) : t, o = m.activeWindow === e || h(e);
-			r != null && i != null && T.set(r, {
+			let n = x.get(e), r = n?.item ?? null, i = n?.app ?? null, a = t === void 0 ? i == null ? null : H(r, i) : t, o = m.activeWindow === e || h(e);
+			r != null && i != null && C.set(r, {
 				app: i,
-				pin: s(p(e), x(), A())
+				pin: s(p(e), y(), O())
 			});
 			let c = e.hide({ to: a });
-			r != null && u(E, r), i != null && !n?.palette && u(D, i);
+			r != null && u(w, r), i != null && !n?.palette && u(T, i);
 			let l = () => {
-				r != null && d(E, r), i != null && !n?.palette && d(D, i), F();
+				r != null && d(w, r), i != null && !n?.palette && d(T, i), N();
 			};
-			return c.then(l, l), ie(e), e.remove(), o && queueMicrotask(() => {
+			return c.then(l, l), ue(e), e.remove(), o && queueMicrotask(() => {
 				let e = m.activeWindow;
-				e ? Y(e) : B(r, i) || B(null, null);
+				e ? Z(e) : U(r, i) || U(null, null);
 			}), c;
 		},
 		requestClose(e) {
-			let t = C.get(e)?.close;
+			let t = x.get(e)?.close;
 			t ? t(e) : $.close(e);
 		},
 		windowFor(e) {
-			for (let [t, n] of C) if (n.item === e) return t;
+			for (let [t, n] of x) if (n.item === e) return t;
 			return null;
 		},
 		windowsOf(e) {
-			return m.stackingOrder.filter((t) => t instanceof n && C.get(t)?.app === e);
+			return m.stackingOrder.filter((t) => t instanceof n && x.get(t)?.app === e);
 		},
 		itemOf(e) {
-			return e instanceof n ? C.get(e)?.item ?? null : null;
+			return e instanceof n ? x.get(e)?.item ?? null : null;
 		},
 		appOf(e) {
-			return e instanceof n ? C.get(e)?.app ?? null : null;
+			if (e instanceof n) return x.get(e)?.app ?? null;
+			let t = re(e);
+			return t ? R.get(t).app : null;
+		},
+		holdDialog(e, { app: t }) {
+			let n = R.get(e);
+			if (n) n.app = t;
+			else {
+				let n = new MutationObserver(V);
+				n.observe(e, {
+					attributes: !0,
+					attributeFilter: ["open"],
+					subtree: !0
+				}), R.set(e, {
+					app: t,
+					observer: n
+				});
+			}
+			m.contains(e) || m.append(e), V();
+		},
+		releaseDialog(e) {
+			let t = R.get(e);
+			t && (t.observer.disconnect(), R.delete(e), V());
+		},
+		dialogsOf(e) {
+			return [...R].filter(([, t]) => t.app === e).map(([e]) => e);
+		},
+		get asking() {
+			let e = z[z.length - 1];
+			return e ? R.get(e).app : null;
 		},
 		isPalette(e) {
-			return e instanceof n && !!C.get(e)?.palette;
+			return e instanceof n && !!x.get(e)?.palette;
 		},
 		setItem(e, t) {
-			let n = C.get(e);
-			!n || n.item === t || (n.item = t, F());
+			let n = x.get(e);
+			!n || n.item === t || (n.item = t, N());
 		},
 		isOpen(e) {
-			return E.has(e) || $.windowFor(e) !== null;
+			return w.has(e) || $.windowFor(e) !== null;
 		},
 		hasWindows(e) {
-			if (D.has(e)) return !0;
-			for (let [, t] of C) if (t.app === e && !t.palette) return !0;
+			if (T.has(e)) return !0;
+			for (let [, t] of x) if (t.app === e && !t.palette) return !0;
 			return !1;
 		},
 		palettesChanged() {
-			J();
+			oe();
 		},
 		write(e, t) {
-			H(e, t), N();
+			G(e, t), j();
 		},
 		clamped(e, t) {
-			return V(e, t);
+			return W(e, t);
 		},
 		placed(e) {
-			return U(e);
+			return K(e);
 		},
 		pinOf(e) {
-			return s(p(e), x(), A());
+			return s(p(e), y(), O());
 		},
 		fromPin(e, t, n) {
-			return G(e, t, n);
+			return J(e, t, n);
 		},
 		setFrameBands(e) {
-			k = { ...e }, O = /* @__PURE__ */ new WeakMap();
+			D = { ...e }, E = /* @__PURE__ */ new WeakMap();
 		},
 		arrangeWith(e, t) {
-			return w.set(e, t), N(), () => {
-				w.get(e) === t && w.delete(e), N();
+			return S.set(e, t), j(), () => {
+				S.get(e) === t && S.delete(e), j();
 			};
 		},
 		arrange() {
-			M = !0;
+			A = !0;
 			try {
-				for (let e of w.values()) e.arrange();
-				for (let e of C.keys()) {
-					let t = U(e);
-					t && H(e, t);
+				for (let e of S.values()) e.arrange();
+				for (let e of x.keys()) {
+					let t = K(e);
+					t && G(e, t);
 				}
 			} finally {
-				M = !1;
+				A = !1;
 			}
-			N();
+			j();
 		},
 		arranged() {
-			for (let e of w.values()) if (!e.arranged()) return !1;
-			for (let e of C.keys()) {
-				let t = U(e);
-				if (t && !e.hidden && !te(e, t)) return !1;
+			for (let e of S.values()) if (!e.arranged()) return !1;
+			for (let e of x.keys()) {
+				let t = K(e);
+				if (t && !e.hidden && !ie(e, t)) return !1;
 			}
 			return !0;
 		},
 		resized(e) {
-			let t = x();
+			let t = y();
 			if (e.width === t.width && e.height === t.height) return;
-			let n = S(), r = {
+			let n = b(), r = {
 				left: n.left,
 				top: n.top,
 				width: e.width - n.left,
 				height: Math.max(0, e.height - n.top)
 			};
-			for (let n of C.keys()) ae(n, e, t, r);
-			for (let n of [...I]) n(e, t);
-			N();
+			for (let n of x.keys()) de(n, e, t, r);
+			for (let n of [...P]) n(e, t);
+			j();
 		},
 		snapshot() {
 			let e = {};
-			for (let [t, n] of T) e[t] = { ...n };
+			for (let [t, n] of C) e[t] = { ...n };
 			let t = m.stackingOrder;
-			for (let [n, r] of C) {
+			for (let [n, r] of x) {
 				if (r.item == null) continue;
-				let i = s(p(n), x(), A());
+				let i = s(p(n), y(), O());
 				e[r.item] = r.palette ? {
 					app: r.app,
 					pin: i
@@ -306,38 +345,43 @@ function _(m, _) {
 			return e;
 		},
 		rememberedPin(e) {
-			return T.get(e)?.pin ?? null;
+			return C.get(e)?.pin ?? null;
 		},
 		layoutChanged() {
-			N();
+			j();
 		},
 		setHome(e, t) {
-			return z = e, B = t, () => {
-				z = () => null, B = () => !1;
+			return H = e, U = t, () => {
+				H = () => null, U = () => !1;
 			};
 		},
 		onLayout(e) {
-			return j.add(e), () => void j.delete(e);
+			return k.add(e), () => void k.delete(e);
 		},
 		onWindows(e) {
-			return P.add(e), () => void P.delete(e);
+			return M.add(e), () => void M.delete(e);
 		},
 		onRaster(e) {
-			return I.add(e), () => void I.delete(e);
+			return P.add(e), () => void P.delete(e);
 		},
 		beforeFront(e) {
-			return L.add(e), () => void L.delete(e);
+			return F.add(e), () => void F.delete(e);
 		},
 		onFront(e) {
-			return R.add(e), () => void R.delete(e);
+			return I.add(e), () => void I.delete(e);
+		},
+		onDialogs(e) {
+			return L.add(e), () => void L.delete(e);
 		},
 		dispose() {
-			clearTimeout(Z);
-			for (let e of y) e();
-			j.clear(), P.clear(), I.clear(), L.clear(), R.clear(), w.clear(), C.clear();
+			clearTimeout(Q);
+			for (let e of _) e();
+			k.clear(), M.clear(), P.clear(), F.clear(), I.clear(), L.clear();
+			for (let { observer: e } of R.values()) e.disconnect();
+			R.clear(), z = [], S.clear(), x.clear();
 		}
 	};
-	return K = q(m.activeWindow), $;
+	return Y = X(m.activeWindow), $;
 }
 //#endregion
-export { _ as createWindowManager, m as deepActiveElement, g as focusInto };
+export { ee as createWindowManager, m as deepActiveElement, g as focusInto };

package/dist/text-control.d.ts

@@ -117,6 +117,12 @@ export declare class VfTextControlBase extends VfShadowRoleControl {
      * disabled default button means no submission at all, as in HTML; a form
      * with no submit button falls back to the bare call, also as in HTML.
      *
+     * One departure: a submit `vf-button variant="default"`, the button with
+     * the ring, is the default button when the form has one, ahead of the
+     * first in tree order. A Cancel/OK row puts Cancel first, and Return
+     * should press the button the ring marks — the one a modal's own Return
+     * rule presses (`VfModalDialog`).
+     *
      * Returns whether a form owner took the press — true even when a disabled
      * default button meant no submission, since HTML gave the press to the form
      * either way. The callers cancel the keydown on true, so a modal shell

package/dist/text-control.js

@@ -57,8 +57,8 @@ var l = class extends a {
 	requestImplicitSubmit() {
 		let e = this.internals.form;
 		if (!e) return !1;
-		let t = [...e.elements].find((e) => e instanceof HTMLButtonElement && e.type === "submit" || e instanceof HTMLInputElement && (e.type === "submit" || e.type === "image") || e.localName === "vf-button" && !e.href && e.type?.toLowerCase() === "submit");
-		return t ? (t.matches(":disabled") || t.click(), !0) : (e.requestSubmit(), !0);
+		let t = [...e.elements].filter((e) => e instanceof HTMLButtonElement && e.type === "submit" || e instanceof HTMLInputElement && (e.type === "submit" || e.type === "image") || e.localName === "vf-button" && !e.href && e.type?.toLowerCase() === "submit"), n = t.find((e) => e.localName === "vf-button" && e.variant === "default") ?? t[0];
+		return n ? (n.matches(":disabled") || n.click(), !0) : (e.requestSubmit(), !0);
 	}
 	emitValue(t, n = { value: this.value }) {
 		e(this, t, n);

package/docs/SPEC.md

@@ -46,7 +46,7 @@ Modern requirements that we deliberately keep (accessibility over purity):
 - **The name/description bridge** (`VfShadowRoleControl`, src/form-control.ts). On the controls whose role lives on a shadow-internal node (the three fields, `vf-select`, `vf-swatch`, `vf-button`), a host-level `aria-labelledby`, `aria-label` or associated `<label for>` resolves — in html-aam precedence — to the inner focusable element's `aria-label` whenever the `label` property is empty (`hostLabel`). Those six extend `VfShadowRoleControl`; the host-role controls (`vf-checkbox`, `vf-radio-group`, `vf-slider`) extend the plain `VfFormControl` and so never *carry* the bridge's API at all — an inherited `description` that renders nothing is the advertised-but-inert shape this split removes, and `verify:manifest` enforces it (a tag whose manifest lists `description` must call `renderDescription()`). `vf-button` takes the ARIA half alone (`hostAriaLabel`): a `<button>` is not a labelable element, so no caption names a native one and none names this one either — its slotted content is the name a bridge doesn't override. A `description` property (or, when it's empty, a host-level `aria-describedby`) renders as a hidden span in the control's own shadow root with the inner control's `aria-describedby` pointing at it — the shadow-internal IDREF idiom `vf-dialog`'s title patch uses — and a failing constraint's `validationMessage` joins the same node. Referenced text is flattened at render time, so an edit to a referenced element's *text* lands on the next render rather than instantly — the one divergence from native. Controls whose role sits on the host (the toggles, slider, radio group, bars) need none of this: the platform reads their host attributes directly.
 - **Constraint validation** (`VfFormControl`): a reflected `required` fails validation with `valueMissing` while the control is empty by its own definition (fields/select `value === ''`, checkbox unchecked, radio group unselected — each with its native counterpart's message), through one `syncValidity()` funnel run before each render. The native surface is complete — `checkValidity`/`reportValidity`/`validity`/`validationMessage`/ `willValidate`/`setCustomValidity` — `:invalid` matches on the host, `form.reportValidity()` blocks, and `disabled`/`readonly` bar validation per HTML's own rules. One divergence the platform imposes: `willValidate` is `true` on a `vf-button type="button"`, where a native button is barred from constraint validation. A form-associated custom element cannot opt out of the candidate set, so this is a platform limit. AT wiring is `aria-required`/`aria-invalid` on the inner control (plus internals mirrors for host-role controls) — never a forwarded native `required`, which would put UA `:user-invalid` styling on the artwork. Enter's implicit submission routes through the browser's validation, so it cannot submit past a failing constraint.
 - Components must render nothing surprising outside their box: no margins on `:host` by default.
-- **Explicit placement** (`VfPositioned`, src/position.ts): every component takes `top`/`left` in whole system px — set either and the host is absolutely positioned within its parent (`position: absolute` plus both offsets as live `calc(var(--vf-scale, 1) * Npx)` inline styles; the unset coordinate is 0; `right`/`bottom` released to `auto` and `margin` zeroed). Set neither and the element renders in flow; removing both unwinds every inline declaration. The DITL model: a dialog can be laid out by positioning its items just as validly as by stacking them. **No component is excluded** — the rows a container normally owns (`vf-option`, `vf-menu-item`, `vf-list-item`) and a bar's `vf-menu` take the pair on the same terms, because a consumer may stand one of them up on its own and the kit does not get to rule that out. Placing such a row *inside* its managing parent takes it out of that parent's flow, so the parent stops measuring it (a `vf-select`/`vf-menu` panel is as wide as its widest **flowed** row, and `popup-overflow`'s clamp counts the same set) and the rows after it close the gap — the documented consequence of the placement, not a failure of it; each component's own doc comment states what its container stops doing. Containers are deliberate anchors — the desktop raster, a window's or a dialog's *content region* (the frame's inner edge below any title bar, with no inset of its own — flow content starts there too), a stack's box, a fieldset's border interior, a scroll area's scrolled plane. The style writing rides a ReactiveController (`hostUpdated`), not an `updated()` override — component subclasses routinely skip `super.updated()` — and re-applies only when the property values changed, so an unrelated update never re-asserts a coordinate. **`origin`** (reflected string: one of nine keywords, vertical then horizontal — `top left` the default, `top center`, `top right`, `center left`, `center`, `center right`, `bottom left`, `bottom center`, `bottom right`) names which point of the host's own box the pair places. With a non-default origin the controller measures the host's border box in whole system px (w × h) and writes `left` as `calc(var(--vf-scale, 1) * (L − ⌈w·fx⌉)px)` with `fx` 0, ½ or 1, `top` likewise — the ceiling sends an odd size's leftover half toward the start, the tie rule `vf-stack`'s centering and the title patch use — and keeps the offset current with a ResizeObserver (a relabel, a late font; a zoom step changes CSS px, not system px, so the same offset comes back and nothing is rewritten), each rewrite announced as `vf-placement-change`. Never a transform: a percentage of an odd width is half a pixel, and a transform would make the host the containing block for a `position: fixed` descendant (`vf-select`'s list). `top left` is the plain path — no observer, no measurement, the same inline style. The pair is the origin point throughout: `PlacementController.seed()` returns it (the corner read from flow plus the offset, for a host with no stated pair), `moveTo()` takes the offset off before the clamp and puts it back after, so a gesture writes the point's pair and the clamp holds the box; `placementAt(clientX, clientY, child?)` on the three shadow-anchored containers folds `child`'s offset in; `fixed` folds it into its sticky thresholds. `vf-dialog` has no `origin` — its pair is the viewport's, and unset centers it. An unknown value places as `top left` and warns once per element; on its own the attribute places nothing. **`fixed`** (bare attribute, reflected) holds the placement against the *visible* region of the nearest scrolling ancestor instead of its scrolled plane: `position: sticky` in place of `absolute`, the same live offsets, the flag alone at (0,0). Sticky boxes stay in flow, so the controller erases the footprint — the host is blockified (the outer display change `absolute` makes on its own: `inline-block` → `block`, `inline-flex` → `flex`, …), `max-width: fit-content`, `z-index: 1` (over the plane's placed children), and a negative right/bottom margin equal to its own border box, kept exact by a ResizeObserver — a 0×0 margin box that flow content lays out as if it weren't there. Two engine facts stated as rules: sticky only ever pushes a box *down* from where the flow put it, so a fixed child precedes the flow content in its parent; and a scroll container that never scrolls (a plain window body is `overflow: hidden`) holds it exactly where placement would. Removing the flag returns the host to ordinary placement with the recipe unwound. `npm run verify:position`.
+- **Explicit placement** (`VfPositioned`, src/position.ts): every component takes `top`/`left` in whole system px — set either and the host is absolutely positioned within its parent (`position: absolute` plus both offsets as live `calc(var(--vf-scale, 1) * Npx)` inline styles; the unset coordinate is 0; `right`/`bottom` released to `auto` and `margin` zeroed). Set neither and the element renders in flow; removing both unwinds every inline declaration. The DITL model: a dialog can be laid out by positioning its items just as validly as by stacking them. **No component is excluded** — the rows a container normally owns (`vf-option`, `vf-menu-item`, `vf-list-item`) and a bar's `vf-menu` take the pair on the same terms, because a consumer may stand one of them up on its own and the kit does not get to rule that out. Placing such a row *inside* its managing parent takes it out of that parent's flow, so the parent stops measuring it (a `vf-select`/`vf-menu` panel is as wide as its widest **flowed** row, and `popup-overflow`'s clamp counts the same set) and the rows after it close the gap — the documented consequence of the placement, not a failure of it; each component's own doc comment states what its container stops doing. Containers are deliberate anchors — the desktop raster, a window's or a dialog's *content region* (the frame's inner edge below any title bar, with no inset of its own — flow content starts there too), a stack's box, a fieldset's border interior, a scroll area's scrolled plane. The style writing rides a ReactiveController (`hostUpdated`), not an `updated()` override — component subclasses routinely skip `super.updated()` — and re-applies only when the property values changed, so an unrelated update never re-asserts a coordinate. **`origin`** (reflected string: one of nine keywords, vertical then horizontal — `top left` the default, `top center`, `top right`, `center left`, `center`, `center right`, `bottom left`, `bottom center`, `bottom right`) names which point of the host's own box the pair places. With a non-default origin the controller measures the host's border box in whole system px (w × h) and writes `left` as `calc(var(--vf-scale, 1) * (L − ⌈w·fx⌉)px)` with `fx` 0, ½ or 1, `top` likewise — the ceiling sends an odd size's leftover half toward the start, the tie rule `vf-stack`'s centering and the title patch use — and keeps the offset current with a ResizeObserver (a relabel, a late font; a zoom step changes CSS px, not system px, so the same offset comes back and nothing is rewritten), each rewrite announced as `vf-placement-change`. A box with no layout (0×0, inside a closed dialog) keeps the offset it had, so it shows again in place. The width measured is the box's own wherever its corner lands: a placed box without a declared width shrinks to the room between its `left` and its parent's far edge, and the offset moves that `left`, so a first measurement with the corner at the stated point squeezed the box, and each re-measure freed a little more room — a row walked for frames after every show and could stop short. A negative right margin as wide as the written `left` gives the box its parent's whole width wherever it sits, so the first measurement is the last; a declared width is untouched (not for `fixed`, whose margins are its footprint). Never a transform: a percentage of an odd width is half a pixel, and a transform would make the host the containing block for a `position: fixed` descendant (`vf-select`'s list). `top left` is the plain path — no observer, no measurement, the same inline style. The pair is the origin point throughout: `PlacementController.seed()` returns it (the corner read from flow plus the offset, for a host with no stated pair), `moveTo()` takes the offset off before the clamp and puts it back after, so a gesture writes the point's pair and the clamp holds the box; `placementAt(clientX, clientY, child?)` on the three shadow-anchored containers folds `child`'s offset in; `fixed` folds it into its sticky thresholds. `vf-dialog` has no `origin` — its pair is the viewport's, and unset centers it. An unknown value places as `top left` and warns once per element; on its own the attribute places nothing. **`fixed`** (bare attribute, reflected) holds the placement against the *visible* region of the nearest scrolling ancestor instead of its scrolled plane: `position: sticky` in place of `absolute`, the same live offsets, the flag alone at (0,0). Sticky boxes stay in flow, so the controller erases the footprint — the host is blockified (the outer display change `absolute` makes on its own: `inline-block` → `block`, `inline-flex` → `flex`, …), `max-width: fit-content`, `z-index: 1` (over the plane's placed children), and a negative right/bottom margin equal to its own border box, kept exact by a ResizeObserver — a 0×0 margin box that flow content lays out as if it weren't there. Two engine facts stated as rules: sticky only ever pushes a box *down* from where the flow put it, so a fixed child precedes the flow content in its parent; and a scroll container that never scrolls (a plain window body is `overflow: hidden`) holds it exactly where placement would. Removing the flag returns the host to ordinary placement with the recipe unwound. `npm run verify:position`.
   - `vf-dialog` takes the pair in **viewport** coordinates: `showModal()` puts the box in the top layer, whose containing block is the viewport rather than the nearest positioned ancestor. Unset means centered — recomputed on open and on every box/viewport/scale change, so a modal whose content upgrades after opening is never stranded; `position` is left to the UA and only the four inset/margin declarations are written.
   - **Gestures write through the same properties** (`PlacementController`): a `vf-window`/`vf-dialog` title-bar drag and a `vf-icon` drag or arrow nudge state `top`/`left`, and `vf-window`'s grow box states `width`/`height` (`VfSized`) — all in whole system px, so a moved element is placed the way an authored one is and holds its spot through a zoom. Writing resolved CSS px instead was the bug: `--vf-scale` moved under the constant and every zoom step re-read it as a different number of system px (by the ratio the scale itself moved — visible even at zoom levels where the target does not change, and nothing else on the page does). Values are snapped to `snapSys` at gesture time and never re-snapped afterwards: re-rounding onto each new lattice compounds (62 → 63 → 64), and whole system px is whole device px at every rung regardless. `npm run verify:zoom` group (e). Every placement write the controller makes is announced as `vf-placement-change` (bubbles, `composed: false`, `{ left, top }`, nulls on a return to flow), a public event: a page hears every move through it — a title-bar drag's steps and its release (an `outline-drag` writes once, on the release), an arrow nudge, a drop, a walk's landing, an `origin` re-measure and its own property writes — and so does a `vf-scroll-area`, which re-measures under a child dropped, nudged or set past its viewport with no code on the page. It is dispatched from the host's update with the new pair already written, so a handler that writes the pair again takes effect on the next update. `npm run verify:position` (EVENT), `npm run verify:window` (PLACEMENT EVENT). `npm run verify:icon-drag` (RE-MEASURE).
   - **The movable contract.** A host that moves under a gesture states its own rectangle, and its positioning parent is a box with a size. Both halves are the consumer's — a component can supply neither for itself — and both used to fail quietly, so each is a one-time `console.warn` (`warnMovableContract`, latched per element like `vf-window`'s size warning). `npm run verify:position` group CONTRACT.
@@ -233,18 +233,18 @@ The desktop-window shell: the classic document window (see DragThing screenshot)
 
 #### `vf-dialog` (`VfDialog`, vf-dialog.ts)
 The modal-dialog shell: movable modal by default (the dBoxProc double frame with the striped title bar set into it — traced from a 2× System 7 capture of a movable modal), the modal dialog box with `frame="plain"` (the bare double frame; see the Group A recipe table).
-- **Attributes/props:** `open: boolean` (reflect), `heading: string`, `top: number` / `left: number` (whole system px, in **viewport** coordinates — see §1 Explicit placement; unset means centered), `width: number` / `height: number` (**declare them both** — whole system px, the same fixed box `vf-window` is. A native `<dialog>` is `width: fit-content` measured against the space left beside its own offsets, and stating an offset is how the movable modal is positioned, so an undeclared dialog squeezes itself and reflows as it is dragged toward an edge. The two fall back differently — width to 260 system px, height to the content — and it names whichever are missing, once, on the open that first shows it), `label: string` (accessible name for a dialog with no `heading`), `closable: boolean` (default **false** — the bare movable-modal bar; the close box is opt-in because the HIG's Chapter 6 text denies a movable modal one while its Figure 5-1 grants it — the parameter enables either reading), `light-dismiss: boolean` (`lightDismiss`; default **false** — a click outside the frame closes the dialog with `vf-close` reason `'outside'`. Off by default because the classic modal ignored an outside click, and a dialog that asks a question should keep ignoring it; opt in for the About box and the splash, which the classic Mac did dismiss on a click. Reflected, and read at the release, so it can be toggled on an open dialog), `frame?: 'plain'`.
-- **Implementation:** wraps a native `<dialog>` (for top-layer + focus trap). `show()` → `showModal()`; `close()` closes. Keep `open` attr in sync both directions. Drag the title bar to move it (shared `DragController` with `vf-window`), stating `top`/`left` in system px; drags starting on the close widget are ignored (same composedPath guard as `vf-window`). Escape → close + `vf-close` detail `{ reason: 'escape' }`; close box/programmatic/close() → `{ reason: 'close' }`; a click outside under `light-dismiss` → `{ reason: 'outside' }`. No backdrop dimming: `::backdrop { background: transparent; }`. **Light dismiss is target identity, not geometry** (`VfModalDialog`): the `::backdrop` hit-tests as its `<dialog>`, and the frame fills the dialog's box, so the dialog is a pointer event's *target* exactly when the pointer was outside the frame — the listeners sit on the `<dialog>` itself, attached while open. It takes both halves of the click: a `pointerdown` on the backdrop arms (any other press disarms, so a right-click macOS never releases can't leave a stale arm), and a `pointerup` on the backdrop with the same `pointerId` closes — the platform's own `closedby="any"` two-step, so a press that starts on a control and slides off, or a title-bar drag released past the frame, leaves the dialog open. Deliberately not the `click` event: UI Events dispatches a press-drag-release click at the common ancestor of the two targets, which for a press on the frame released outside is the dialog itself. The platform's `closedby` attribute is not used because its dismissal arrives as `cancel`, which the base already reads as Escape. The press is consumed either way — a modal's backdrop lets nothing beneath it see the click — which is what lets a page dismiss its About box without also selecting the icon under the pointer. `npm run verify:dialog`. **Keyboard: the Dialog Manager's two rules** (`VfModalDialog`). *Initial focus:* right after `showModal()`'s own focusing steps, focus is handed to `initialFocusTarget` — a slotted control carrying `autofocus`, else the first enabled text-entry control (`vf-text-field`, `vf-number-field`, `vf-text-area`, or a native text input/textarea), else the default button (`defaultButton`: the first enabled `vf-button[variant="default"]`, looked for among the slotted content and then the shadow tree), else nothing, leaving the browser's pick. The classic dialog put the insertion point in its first text item and gave nothing else focus; the web needs a focused control, and the default button is the one that makes Return and Space work without a Tab. Left alone, `showModal()` focuses the first focusable thing in flat-tree order — Cancel in a Cancel/OK row, or a link in the body — so Return pressed the wrong thing. Both getters are `protected`, for a consumer's own modal to override. *Return/Enter:* a `keydown` listener on the `<dialog>`, bubble phase, attached while open with the light-dismiss trio. An uncancelled, unmodified Enter activates `defaultButton` (its `click()`, so a `type="submit"` default runs its proxy path) and cancels the keydown, which is what keeps a focused Cancel from firing itself — Space presses the focused control, as on the classic Mac. Anything that took Enter for itself cancelled the keydown first and is left alone: `vf-select`'s list, `vf-list`, an icon's rename, and a text field whose form ran its implicit submission (`requestImplicitSubmit` now reports whether a form owner took the press, and the fields cancel on true — so the submission runs once, not once per layer). A link keeps its own Enter. A multi-line editor (`<textarea>`, contenteditable) keeps Return for the newline; only `code === 'NumpadEnter'` fires the button there — the split a TextEdit item drew between the two keys. With no enabled default button the press is left native. Escape is unchanged (the `cancel` path above). **Removal while open is a close path** (`VfModalDialog.disconnectedCallback`): HTML's dialog removing steps skip the close algorithm entirely, which is exactly what a framework unmount does — the teardown routes through the same native-`close` funnel (`vf-close` fires on the removed element; nothing bubbles, it left the tree), `open` and the written origin reconcile so a re-append mounts closed, and focus returns to the element focused at open time. **The placement re-settles while open** whenever the dialog's own box resizes — slotted content upgrading after `showModal()`, `--vf-scale` moving under zoom — the viewport resizes, or the scale changes. What survives depends on how the modal got where it is: an unplaced one re-centers (it never claimed a spot, and the stranded case is exactly this one), while a dragged or authored origin is kept and only re-clamped on screen.
+- **Attributes/props:** `open: boolean` (reflect), `heading: string`, `top: number` / `left: number` (whole system px, in **viewport** coordinates — see §1 Explicit placement; unset means centered), `width: number` / `height: number` (**declare them both** — whole system px, the same fixed box `vf-window` is. A native `<dialog>` is `width: fit-content` measured against the space left beside its own offsets, and stating an offset is how the movable modal is positioned, so an undeclared dialog squeezes itself and reflows as it is dragged toward an edge. The two fall back differently — width to 260 system px, height to the content — and it names whichever are missing, once, on the open that first shows it), `label: string` (accessible name for a dialog with no `heading`), `closable: boolean` (default **false** — the bare movable-modal bar; the close box is opt-in because the HIG's Chapter 6 text denies a movable modal one while its Figure 5-1 grants it — the parameter enables either reading), `light-dismiss: boolean` (`lightDismiss`; default **false** — a click outside the frame closes the dialog with `vf-close` reason `'outside'`. Off by default because the classic modal ignored an outside click, and a dialog that asks a question should keep ignoring it; opt in for the About box and the splash, which the classic Mac did dismiss on a click. Reflected, and read at the release, so it can be toggled on an open dialog), `frame?: 'plain'`, `returnValue: string` (property only, as on `<dialog>`: the dialog's answer, cleared on each open).
+- **Implementation:** wraps a native `<dialog>` (for top-layer + focus trap). `show()` → `showModal()`; `close()` closes. Keep `open` attr in sync both directions. Drag the title bar to move it (shared `DragController` with `vf-window`), stating `top`/`left` in system px; drags starting on the close widget are ignored (same composedPath guard as `vf-window`). Escape → close + `vf-close` detail `{ reason: 'escape' }`; close box/programmatic/close() → `{ reason: 'close' }`; a click outside under `light-dismiss` → `{ reason: 'outside' }`. **Answers** (`VfModalDialog`): `close(value)` closes with `value` as `returnValue`, and a `<form method="dialog">` inside the dialog closes it on submit with the submitter's `value`, a submitter's `formmethod="dialog"` too. The platform's own rule looks for a `<dialog>` around the form, and this one is in the shadow root, so the base listens for `submit` on the host and closes at the end of the submit's path (`deferActivation`), not at all if anything cancelled it. `vf-button`'s submit proxy carries its `value` with or without a `name`. `vf-close`'s detail carries `returnValue`: the value that close carried, or null (Escape, a click outside, the close box, `close()` alone, removal). Return in a text field runs the form's implicit submission through the ringed `variant="default"` submit button when the form has one, ahead of the first in tree order, so a Cancel/OK row answers OK (`requestImplicitSubmit`). `npm run verify:dialog`, ANSWERS. No backdrop dimming: `::backdrop { background: transparent; }`. **Light dismiss is target identity, not geometry** (`VfModalDialog`): the `::backdrop` hit-tests as its `<dialog>`, and the frame fills the dialog's box, so the dialog is a pointer event's *target* exactly when the pointer was outside the frame — the listeners sit on the `<dialog>` itself, attached while open. It takes both halves of the click: a `pointerdown` on the backdrop arms (any other press disarms, so a right-click macOS never releases can't leave a stale arm), and a `pointerup` on the backdrop with the same `pointerId` closes — the platform's own `closedby="any"` two-step, so a press that starts on a control and slides off, or a title-bar drag released past the frame, leaves the dialog open. Deliberately not the `click` event: UI Events dispatches a press-drag-release click at the common ancestor of the two targets, which for a press on the frame released outside is the dialog itself. The platform's `closedby` attribute is not used because its dismissal arrives as `cancel`, which the base already reads as Escape. The press is consumed either way — a modal's backdrop lets nothing beneath it see the click — which is what lets a page dismiss its About box without also selecting the icon under the pointer. `npm run verify:dialog`. **Keyboard: the Dialog Manager's two rules** (`VfModalDialog`). *Initial focus:* right after `showModal()`'s own focusing steps, focus is handed to `initialFocusTarget` — a slotted control carrying `autofocus`, else the first enabled text-entry control (`vf-text-field`, `vf-number-field`, `vf-text-area`, or a native text input/textarea), else the default button (`defaultButton`: the first enabled `vf-button[variant="default"]`, looked for among the slotted content and then the shadow tree), else nothing, leaving the browser's pick. The classic dialog put the insertion point in its first text item and gave nothing else focus; the web needs a focused control, and the default button is the one that makes Return and Space work without a Tab. Left alone, `showModal()` focuses the first focusable thing in flat-tree order — Cancel in a Cancel/OK row, or a link in the body — so Return pressed the wrong thing. Both getters are `protected`, for a consumer's own modal to override. *Return/Enter:* a `keydown` listener on the `<dialog>`, bubble phase, attached while open with the light-dismiss trio. An uncancelled, unmodified Enter activates `defaultButton` (its `click()`, so a `type="submit"` default runs its proxy path) and cancels the keydown, which is what keeps a focused Cancel from firing itself — Space presses the focused control, as on the classic Mac. Anything that took Enter for itself cancelled the keydown first and is left alone: `vf-select`'s list, `vf-list`, an icon's rename, and a text field whose form ran its implicit submission (`requestImplicitSubmit` now reports whether a form owner took the press, and the fields cancel on true — so the submission runs once, not once per layer). A link keeps its own Enter. A multi-line editor (`<textarea>`, contenteditable) keeps Return for the newline; only `code === 'NumpadEnter'` fires the button there — the split a TextEdit item drew between the two keys. With no enabled default button the press is left native. Escape is unchanged (the `cancel` path above). **Removal while open is a close path** (`VfModalDialog.disconnectedCallback`): HTML's dialog removing steps skip the close algorithm entirely, which is exactly what a framework unmount does — the teardown routes through the same native-`close` funnel (`vf-close` fires on the removed element; nothing bubbles, it left the tree), `open` and the written origin reconcile so a re-append mounts closed, and focus returns to the element focused at open time. **The placement re-settles while open** whenever the dialog's own box resizes — slotted content upgrading after `showModal()`, `--vf-scale` moving under zoom — the viewport resizes, or the scale changes. What survives depends on how the modal got where it is: an unplaced one re-centers (it never claimed a spot, and the stranded case is exactly this one), while a dragged or authored origin is kept and only re-clamped on screen.
 - **Visual (default chrome):** `vfModalFrame` with `vfTitleBar` set into it (§4) — the bar is literally the recipe `vf-window` uses, so it is identical by construction (stripes + centered title) rather than by matching copies; the frame is the modal double frame, **not** the window's shadowed `vfChromeFrame`. Outside → in: 1px outer rule; the 18px bar directly under it, 2px in at either end with its stripes starting 2px from the rule; the 2px band as the bar's floor (the bar's rule + the inner box's 1px top border); 2px gap + 2px band down the sides and along the bottom; no shadow. The body begins 20px below the dialog's top and 5px inside its other three edges. The bar takes the default `--vf-title-inset` (16px) — 60px when `closable`, the same clearance as `vf-window`, since the centered title needs symmetric room for the widget — and sets `touch-action: none` unconditionally, having no immovable state. `closable` renders the shared close box (`vfWindowWidgets` + `closeBox()` — byte-identical to `vf-window`'s, per the `moveable modal dialog.png` reference). Body is WHITE (`--vf-surface: #fff`) and is the content region, with no inset of its own: the positioning anchor, so a child placed with `top`/`left` measures from the frame's inner edge, and flow content starts at the same corner. Both chromes are full-height flex columns and the body takes the slack, for the same reason `vf-window`'s frame is: the declared `height` lands on the `<dialog>` (see `dialogSize`), and the recipes are skin only. The frame is the flex child of the `<dialog>` itself (`dialog[open]` is a flex column in `modalDialogStyles` — `[open]`-scoped, or it would out-cascade the UA's `dialog:not([open]) { display: none }`), not a `height: 100%` block: a percentage can't resolve against the undeclared-height dialog that only the UA's `dialog:modal` max-height caps, and that spill was how a viewport-tall modal stranded its buttons off-screen. **The box never grows, but over-stuffed content scrolls instead of clipping**: the body holds a `.content` scroll region (the default slot; part `content`). Placed children anchor to the body, outside that scroller, so they hold still while it scrolls. While the content fits, nothing matches. Once it overflows (`ScrollStateController`, the always-a-rail machinery), the region reserves the rail's 15px as its own right padding, wears the drawn `vfScrollRail` rail (§4) flush against the frame's inner band, which supplies the cell's outer line, and becomes a keyboard stop (`tabindex="0"`, `role="group"`, the kit's dotted ring) so the copy is scrollable without a pointer. The rail rides the body as an overlay pinned to its right edge, deliberately out of the layout flow: a rail *column*'s two fixed 15px arrow cells would hand the region a 32px minimum height, and a short dialog would then measure as fitting with the rail shown and overflowing without it — flip-flopping forever. The drop-open exemption is unchanged.
   - **The CSS and the controller state the same thing.** `.content` is `overflow-y: hidden` until the controller flags overflow, then `overflow-y: scroll`. It is deliberately never `auto`: the controller ignores the body face's negative half-leading (`LEADING_SPILL_SYS`, src/scroll-state.ts — `vf-paragraph` sets a 12-system-px line box under a 16-system-px em, so the inline box spills 2 inkless system px past the block box and `scrollHeight` counts it), and `auto` has no way to know that. With `auto` the two disagreed, and a fixed info dialog whose copy ends in a `vf-paragraph` rubber-banded under the wheel with no rail shown — 6 CSS px at scale 3. `hidden` still scrolls programmatically, so `scrollIntoView` on a focused control is unaffected. `npm run verify:contract`, OVERFLOW group.
 - **Visual (`frame="plain"`):** the same `vfModalFrame` (§4 — 1px outer, 2px gap, 2px inner band, no shadow, per `Windows/modal dialog.png`) with no title bar, and immovable like the original dBoxProc dialog (nothing renders a drag handle). The body begins 5px inside every edge. With no bar, `heading` only names the dialog and `closable` is ignored; a title in the body is the composer's, placed like any other item.
 - **A11y:** the default chrome is named by its title patch (`id="title"`) via `aria-labelledby` when `heading` is set. Otherwise — no heading, or the plain frame, which has no patch to point at — it falls back to `aria-label`: `label` if given, else `heading`, else `'Dialog'`. An explicit `label` wins over `heading`. The close box is labeled `Close ${heading}` like `vf-window`'s.
 - **Slots:** default.
 - **Parts:** `frame`, `title-bar` and `title` (default chrome), `close-box` (when `closable`), `body`, `content`.
-- **Events:** `vf-close` (detail `{ reason: 'escape' | 'close' | 'outside' }`).
+- **Events:** `vf-close` (detail `{ reason: 'escape' | 'close' | 'outside', returnValue: string | null }`).
 
 #### The alert box (composed — no component)
-System 7's fixed modal alert (double frame: 2px outer, 2px gap, 1px inner rule, *with* the hard shadow) is deliberately not shipped as a component. What separates an alert from a modal dialog is a *picture* — the 32×32 icon — and pictures are the consumer's assets, never the library's (see the glyph-sprites note at the top of this spec). An alert box is composed from the shells above: `vf-dialog frame="plain"` with `label` stated (there is no title bar to name it), a row `vf-stack` slotting the consumer's own 32×32 art through `vf-img`, display-face copy (System 7 alerts used chrome type), and a `vf-button-group`, each placed with `top`/`left`. The reference page carries the live recipe, composed from `demo/icons/alert.png`.
+System 7's fixed modal alert (double frame: 2px outer, 2px gap, 1px inner rule, *with* the hard shadow) is deliberately not shipped as a component. What separates an alert from a modal dialog is a *picture* — the 32×32 icon — and pictures are the consumer's assets, never the library's (see the glyph-sprites note at the top of this spec). An alert box is composed from the shells above: `vf-dialog frame="plain"` with `label` stated (there is no title bar to name it), a row `vf-stack` slotting the consumer's own 32×32 art through `vf-img`, display-face copy (System 7 alerts used chrome type), and a `vf-button-group`, each placed with `top`/`left`, all inside a `<form method="dialog">` whose buttons are `type="submit"` with a `value` each, so the alert answers with the pressed button's value. The reference page carries the live recipe, composed from `demo/icons/alert.png`.
 
 #### `vf-separator` (`VfSeparator`, vf-separator.ts)
 - 1px black rule. `vertical: boolean` attr → 1px wide, auto height. Horizontal default: `display: block; height: 1px`, the line the inner element's own background, `var(--vf-separator-color, var(--vf-black, #000))`. `--vf-separator-style` is `solid` (default) or `dotted` — one system px on, one off, from the rule's start, a `repeating-linear-gradient` selected by a style query on the token. Inside menus it renders as the classic dimmed **dotted** rule spanning the full panel width (see Menus.png): the menu panel sets the two props to `--vf-disabled` / `dotted`, and spends a full `--vf-menu-row-height` on the divider: 8px margin above the rule, 7 below. Under forced colors the line is a border in the token's style, as every stroke is. `role="separator"`.

package/editor/vscode.html-custom-data.json

@@ -64,7 +64,7 @@
         },
         {
           "name": "value",
-          "description": "Value submitted under `name` when `type=\"submit\"`.",
+          "description": "Value submitted under `name` when `type=\"submit\"`. In a\n`<form method=\"dialog\">` inside a `vf-dialog`, the dialog's answer\n(`returnValue`), with or without a `name`.",
           "values": []
         },
         {
@@ -303,7 +303,7 @@
     },
     {
       "name": "vf-dialog",
-      "description": "`<vf-dialog>` — the System 7 modal dialog shell.\n\nTwo chromes, one modal lifecycle (native `<dialog>` for top-layer rendering\nand focus trapping, with a fully transparent backdrop — no dimming). Both\nare the same dBoxProc double frame — 1px outer rule, 2px gap, 2px inner\nband, no shadow (vfModalFrame):\n\n- **Default:** the movable modal (movableDBoxProc) — the striped title bar\n  set into the top of that frame, with a centered title over a white body.\n  Drag the title bar to move it. `closable` adds the standard close box\n  (left of the bar) — the HIG's own figures disagree on whether a movable\n  modal carries one (Figure 5-1 says yes, Figure 6-1 and the Chapter 6 text\n  say no), so the component enables either reading rather than enforcing\n  one.\n- **`frame=\"plain\"`:** the modal dialog box — the bare frame, no title bar —\n  and immovable, like the original. With no bar, `heading` only names the\n  dialog and `closable` is ignored.\n\nOpen it with `show()` (or set the `open` attribute/property); close with\n`close()`. Escape closes it and fires `vf-close` with\n`{ reason: 'escape' }`; the close box and programmatic closing fire\n`{ reason: 'close' }`. With `light-dismiss`, a click outside the frame\ncloses it too, with `{ reason: 'outside' }` — for the About box; off by\ndefault, since the classic modal ignored an outside click.\n\nKeyboard, the classic Dialog Manager's two rules (VfModalDialog):\non open, focus goes to the first text-entry control — a slotted control\nwith `autofocus` first — or, with none, to the default button\n(`vf-button variant=\"default\"`). Return or Enter activates the default\nbutton from anywhere in the dialog, a focused Cancel included; Space\npresses the focused control. A link keeps its own Enter, and in a\nmulti-line editor Return inserts the newline while the keypad's Enter\nactivates the button.\n\nSlotted children placed with `top`/`left` measure from the content region's\ncorner — the frame's inner edge, below the title bar — and flow content\nstarts at the same corner.\n---\n\n\n### **Events:**\n - **vf-close** - Dialog closed. Detail `{ reason: 'escape' | 'close' | 'outside' }` — `'outside'` only under `light-dismiss`.\n\n### **Slots:**\n - _default_ - Default slot: the dialog's content.\n\n### **CSS Properties:**\n - **--vf-dots-pattern** - the windoid bar's dot-grid dither — a 2×2 tile, one black pixel at the origin (`vfDots`; override the whole pattern like `--vf-desktop-pattern`) _(default: undefined)_\n- **--vf-titlebar-height** - window/dialog title bars _(default: undefined)_\n- **--vf-scrollbar-thumb** - scrollbar thumb/elevator (white) _(default: undefined)_\n- **--vf-scrollbar-track** - the scroll trough's base color under the dot-dither (white) _(default: undefined)_\n\n### **CSS Parts:**\n - **frame** - The outer frame (the double frame's 1px rule; the bar and the inner band sit inside it).\n- **title-bar** - The striped title bar (default chrome only).\n- **title** - The centered title patch (default chrome only).\n- **close-box** - The close widget (`closable`, default chrome only).\n- **body** - The white content region.\n- **content** - The scrolling region inside the body (the slotted content). Inert while the content fits; over-stuffed, it scrolls under a System 7 rail and becomes a keyboard stop.",
+      "description": "`<vf-dialog>` — the System 7 modal dialog shell.\n\nTwo chromes, one modal lifecycle (native `<dialog>` for top-layer rendering\nand focus trapping, with a fully transparent backdrop — no dimming). Both\nare the same dBoxProc double frame — 1px outer rule, 2px gap, 2px inner\nband, no shadow (vfModalFrame):\n\n- **Default:** the movable modal (movableDBoxProc) — the striped title bar\n  set into the top of that frame, with a centered title over a white body.\n  Drag the title bar to move it. `closable` adds the standard close box\n  (left of the bar) — the HIG's own figures disagree on whether a movable\n  modal carries one (Figure 5-1 says yes, Figure 6-1 and the Chapter 6 text\n  say no), so the component enables either reading rather than enforcing\n  one.\n- **`frame=\"plain\"`:** the modal dialog box — the bare frame, no title bar —\n  and immovable, like the original. With no bar, `heading` only names the\n  dialog and `closable` is ignored.\n\nOpen it with `show()` (or set the `open` attribute/property); close with\n`close()`. Escape closes it and fires `vf-close` with\n`{ reason: 'escape' }`; the close box and programmatic closing fire\n`{ reason: 'close' }`. With `light-dismiss`, a click outside the frame\ncloses it too, with `{ reason: 'outside' }` — for the About box; off by\ndefault, since the classic modal ignored an outside click.\n\nAnswers: a `<form method=\"dialog\">` inside it closes it with the\nsubmitting button's `value` as `returnValue`, and `close(value)` does the\nsame. `vf-close` carries it as `detail.returnValue`, null when the close\ncarried none (Escape, a click outside, the close box).\n\nKeyboard, the classic Dialog Manager's two rules (VfModalDialog):\non open, focus goes to the first text-entry control — a slotted control\nwith `autofocus` first — or, with none, to the default button\n(`vf-button variant=\"default\"`). Return or Enter activates the default\nbutton from anywhere in the dialog, a focused Cancel included; Space\npresses the focused control. A link keeps its own Enter, and in a\nmulti-line editor Return inserts the newline while the keypad's Enter\nactivates the button.\n\nSlotted children placed with `top`/`left` measure from the content region's\ncorner — the frame's inner edge, below the title bar — and flow content\nstarts at the same corner.\n---\n\n\n### **Events:**\n - **vf-close** - Dialog closed. Detail `{ reason: 'escape' | 'close' | 'outside', returnValue: string | null }` — `'outside'` only under `light-dismiss`.\n\n### **Slots:**\n - _default_ - Default slot: the dialog's content.\n\n### **CSS Properties:**\n - **--vf-dots-pattern** - the windoid bar's dot-grid dither — a 2×2 tile, one black pixel at the origin (`vfDots`; override the whole pattern like `--vf-desktop-pattern`) _(default: undefined)_\n- **--vf-titlebar-height** - window/dialog title bars _(default: undefined)_\n- **--vf-scrollbar-thumb** - scrollbar thumb/elevator (white) _(default: undefined)_\n- **--vf-scrollbar-track** - the scroll trough's base color under the dot-dither (white) _(default: undefined)_\n\n### **CSS Parts:**\n - **frame** - The outer frame (the double frame's 1px rule; the bar and the inner band sit inside it).\n- **title-bar** - The striped title bar (default chrome only).\n- **title** - The centered title patch (default chrome only).\n- **close-box** - The close widget (`closable`, default chrome only).\n- **body** - The white content region.\n- **content** - The scrolling region inside the body (the slotted content). Inert while the content fits; over-stuffed, it scrolls under a System 7 rail and becomes a keyboard stop.",
       "attributes": [
         {
           "name": "heading",