vintage-frames 0.1.0

package/dist/cursor-art.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The embedded System 7 pointer set — GENERATED by `npm run embed:cursors`
+ * from `cursors/*.png`; edit the art there (or the hotspot/XOR manifest in
+ * `scripts/embed-cursor-art.mjs`) and re-run rather than editing this file.
+ *
+ * Like the bitmap faces, the art ships base64-embedded so the package needs
+ * no asset files: these are the defaults `applyCursor()` uses, exported so a
+ * consumer can pass one explicitly, remap it to another kind, or mix the set
+ * with art of their own. XOR art carries a `staticSrc` variant — the same
+ * ink under a one-pixel white halo — for the engines whose top layer cannot
+ * blend; supply `cursors/<name>-static.png` to replace the generated halo
+ * with hand-drawn art.
+ */
+import type { VfCursorArt } from './cursor.js';
+/**
+ * The System 7 arrow. Hotspot on the black tip at (1,1), inside the
+ * white outline whose corner is (0,0); the outline is what keeps it legible
+ * on any background, so it draws as-is rather than with the XOR pen.
+ */
+export declare const CURSOR_ARROW: VfCursorArt;
+/**
+ * The text-entry I-beam. Hotspot mid-stem, per the classic CURS
+ * resource; draws with the XOR pen, as System 7 drew it, with a white-halo
+ * static variant for the engines that cannot (see `staticSrc`).
+ */
+export declare const CURSOR_I_BEAM: VfCursorArt;
+/**
+ * The crosshair. Hotspot on the intersection; draws with the XOR pen,
+ * as System 7 drew it, with a white-halo static variant for the engines
+ * that cannot (see `staticSrc`).
+ */
+export declare const CURSOR_CROSSHAIR: VfCursorArt;
+/**
+ * The wristwatch, 8 frames of turning hand. Opaque white face, so it
+ * reads on any background drawn as-is.
+ */
+export declare const CURSOR_WAIT: VfCursorArt;

package/dist/cursor-art.js

@@ -0,0 +1,41 @@
+//#region src/cursor-art.ts
+var e = {
+	src: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAsAAAAQCAYAAADAvYV+AAAAS0lEQVR42q2SMQ4AMAgC/f+n20WTliowlNW7RA2xMuEkQU8o2BJOWAoIU6GDR2GCW4HBj6DgS2A7Y7o/6wNrSAXshoS/VcAuGK64ASXf4R9SU/euAAAAAElFTkSuQmCC",
+	width: 11,
+	height: 16,
+	hotspotX: 1,
+	hotspotY: 1
+}, t = {
+	src: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAkAAAASCAYAAACJgPRIAAAAJElEQVR42mNgIAH8h2JCYnAJBlyS2BSOKhpaivBGMElJBSsAAPlIF+m2BB32AAAAAElFTkSuQmCC",
+	staticSrc: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAkAAAASCAYAAACJgPRIAAAAOklEQVR42mP4jwYYGBgYMMSgEv/R5ZDFGNAlkGlk0xmQrUBWwIANoJnGMKqIlorwRgtREUxyUsGV6AB8JyboJ0V9MQAAAABJRU5ErkJggg==",
+	width: 9,
+	height: 18,
+	hotspotX: 4,
+	hotspotY: 8,
+	invert: !0
+}, n = {
+	src: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAHElEQVR42mNgoDH4P2oAHQ34TyYeDcSRYQBBAAA+6BrmCTIofgAAAABJRU5ErkJggg==",
+	staticSrc: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAMElEQVR42mNgwAH+IwEGcgBU46gBxBjwHw8gIA1RA1NIDoYbQJELRqNxsBtATHYGAOqhCgWyPk7UAAAAAElFTkSuQmCC",
+	width: 16,
+	height: 16,
+	hotspotX: 7,
+	hotspotY: 7,
+	invert: !0
+}, r = {
+	src: [
+		"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAANElEQVR42mNgwA7+48BEgyFuwH9cgBhDsGoixRC6GfCfoAHIgUeWAeQGJMUGUByNIzEvAAD+3h7wGXnswAAAAABJRU5ErkJggg==",
+		"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAOUlEQVR42mNgwA7+48BEgyFuwH9cgBhD/hMChAzBq5FsA5DFCYUHNoXYvPCf/mFAlZggKS2MoLwAABZGIe0u7mf5AAAAAElFTkSuQmCC",
+		"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAMklEQVR42mNgwA7+48BEgyFuwH9cgBhD/hMChAyhmwH/CRqALRBJMmDAwoDiaByJeQEAXRsh7d6Ez7cAAAAASUVORK5CYII=",
+		"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAANElEQVR42mNgwA7+48BEgyFuwH9cgBhD/hMChAyhmwH/CRqAHHhkGYCuiW5hQHE0jsS8AAC0GCTqSlaRPQAAAABJRU5ErkJggg==",
+		"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAANklEQVR42mNgwA7+48BEgyFuwH9cgBhD/hMChAyhmwH/CRqAHHhkGYCsgSIvkGoAxdE4EvMCAIAUIe3WmwVMAAAAAElFTkSuQmCC",
+		"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAOUlEQVR42mNgwA7+48BEgyFuwH9cgBhD/hMChAyhmwH/CRqAHHhkGQBTTLYXcHmHopggKS2MoLwAAFw4Ie372GT7AAAAAElFTkSuQmCC",
+		"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAMklEQVR42mNgwA7+48BEgyFuwH9cgBhD/hMChAyhmwH/8RqAHngkGzCgYUBxNI7EvAAAwfwk6qpQGA8AAAAASUVORK5CYII=",
+		"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAOElEQVR42mNgwA7+48BEgyFuwH9cgBhD/hMChAxBUUiRAbgMIRQe2BSSZwDFYUCTmCApLYygvAAAzn8h7Z3ZHmwAAAAASUVORK5CYII="
+	],
+	width: 16,
+	height: 16,
+	hotspotX: 8,
+	hotspotY: 8
+};
+//#endregion
+export { e as CURSOR_ARROW, n as CURSOR_CROSSHAIR, t as CURSOR_I_BEAM, r as CURSOR_WAIT };

package/dist/cursor.d.ts

@@ -0,0 +1,49 @@
+export interface VfCursorArt {
+    /** Frame URL(s), drawn at one image px = one system px; several animate. */
+    src: string | string[];
+    /** Art width in image px. */
+    width: number;
+    /** Art height in image px. */
+    height: number;
+    /** The art pixel that lands on the cell under the pointer (tip, stem, …). */
+    hotspotX?: number;
+    hotspotY?: number;
+    /** Draw with the XOR pen — per-pixel inversion of whatever is beneath. */
+    invert?: boolean;
+    /**
+     * The variant an engine that cannot XOR draws as-is (stable Safari — see
+     * `XOR_UNAVAILABLE`): same box and hotspot as `src`, but carrying its own
+     * legibility, e.g. a white outline. Only consulted when `invert` is set;
+     * without one, such an engine draws `src` itself, un-inverted.
+     */
+    staticSrc?: string | string[];
+}
+export type VfCursorKind = 'arrow' | 'text' | 'crosshair' | 'wait';
+export interface VfCursorOptions {
+    /** The default pointer. Defaults to the embedded System 7 arrow. */
+    arrow?: VfCursorArt;
+    /** Over editable text. Defaults to the embedded I-beam; `null` disables. */
+    text?: VfCursorArt | null;
+    /** For `data-vf-cursor="crosshair"` claims. Defaults to the embedded
+     *  crosshair; `null` disables. */
+    crosshair?: VfCursorArt | null;
+    /** While `aria-busy`. Defaults to the embedded wristwatch; `null`
+     *  disables. */
+    wait?: VfCursorArt | null;
+    /**
+     * Element whose top-left corner anchors the system-pixel lattice the
+     * cursor snaps to. Defaults to the page's `vf-desktop` (else the document
+     * root), so on a faux desktop the cursor's pixels land on the same grid
+     * as the raster's dither.
+     */
+    anchor?: HTMLElement;
+    /** ms per `wait` frame (default 250 — a full turn of 8 hands in 2s). */
+    waitFrameMs?: number;
+}
+/**
+ * Replace the native pointer with the kit's system-pixel-locked cursor art
+ * (or the consumer's own, per kind). Strictly opt-in — call it once from
+ * your app. Returns a cleanup function that removes the overlay and
+ * restores the native pointer.
+ */
+export declare function applyCursor(options?: VfCursorOptions): () => void;

package/dist/cursor.js

@@ -0,0 +1,171 @@
+import { truePixelRatio as e } from "./zoom.js";
+import { effectiveScale as t, onScaleChange as n } from "./scale.js";
+import { prefersReducedMotion as r } from "./motion.js";
+import { VfModalDialog as i } from "./modal-dialog.js";
+import { CURSOR_ARROW as a, CURSOR_CROSSHAIR as o, CURSOR_I_BEAM as s, CURSOR_WAIT as c } from "./cursor-art.js";
+//#region src/cursor.ts
+var l = [
+	"arrow",
+	"text",
+	"crosshair",
+	"wait"
+], u = typeof navigator < "u" && (navigator.vendor ?? "").startsWith("Apple"), d = /* @__PURE__ */ new Set([
+	"text",
+	"password",
+	"search",
+	"email",
+	"url",
+	"tel",
+	"number"
+]);
+function f(e) {
+	return e instanceof HTMLTextAreaElement ? !e.disabled : e instanceof HTMLInputElement ? !e.disabled && d.has(e.type) : e instanceof HTMLElement && e.isContentEditable;
+}
+function p(e, t) {
+	let n = document.elementFromPoint(e, t);
+	for (; n?.shadowRoot;) {
+		let r = n.shadowRoot.elementFromPoint(e, t);
+		if (!r || r === n) break;
+		n = r;
+	}
+	return n;
+}
+function m(e) {
+	let t = [];
+	for (; e;) {
+		t.push(e);
+		let n = e.getRootNode();
+		e = e.parentElement ?? (n instanceof ShadowRoot ? n.host : null);
+	}
+	return t;
+}
+function h() {
+	for (let e of document.querySelectorAll("[aria-busy=\"true\"]")) if (e instanceof i && e.open) return !0;
+	return !1;
+}
+function g(d = {}) {
+	let { anchor: g = document.querySelector("vf-desktop") ?? document.documentElement, waitFrameMs: _ = 250, arrow: v = a, text: y = s, crosshair: b = o, wait: x = c } = d, S = {
+		arrow: v,
+		text: y,
+		crosshair: b,
+		wait: x
+	}, C = document.documentElement, w = new AbortController(), { signal: T } = w, E = document.createElement("style");
+	E.textContent = "* { cursor: none !important }";
+	let D = document.createElement("img");
+	D.alt = "", D.setAttribute("aria-hidden", "true");
+	let O = "showPopover" in D;
+	O && D.setAttribute("popover", "manual"), Object.assign(D.style, {
+		position: "fixed",
+		inset: "0 auto auto 0",
+		margin: "0",
+		padding: "0",
+		border: "0",
+		background: "transparent",
+		overflow: "visible",
+		pointerEvents: "none",
+		imageRendering: "pixelated",
+		visibility: "hidden",
+		zIndex: "2147483647"
+	});
+	let k = /* @__PURE__ */ new Map();
+	for (let e of l) {
+		let t = S[e];
+		if (!t) continue;
+		let n = t.invert && u ? t.staticSrc ?? t.src : t.src, r = Array.isArray(n) ? n : [n], i = r.map((e) => {
+			let t = new Image();
+			return t.src = e, t;
+		});
+		k.set(e, {
+			art: t,
+			frames: r,
+			xor: !!t.invert && !u,
+			images: i,
+			ready: !1
+		});
+	}
+	let A = (e) => Promise.all(e.images.map((e) => e.decode())).then(() => {
+		e.ready = !0;
+	}), j = 1, M = 3, N = 0, P = 0, F = -1, I = -1, L = "arrow", R = k.get("arrow"), z = 0, B = 0, V = () => {
+		if (F < 0) return;
+		let { hotspotX: e = 0, hotspotY: t = 0 } = R.art, n = Math.floor((F * j - N) / M), r = Math.floor((I * j - P) / M), i = (N + (n - e) * M) / j, a = (P + (r - t) * M) / j;
+		D.style.transform = `translate(${i}px, ${a}px)`;
+	}, H = () => {
+		j = e() || 1, M = Math.max(1, Math.round(t(g) * j));
+		let n = g.getBoundingClientRect();
+		N = Math.round(n.left * j), P = Math.round(n.top * j), D.style.width = `${R.art.width * M / j}px`, D.style.height = `${R.art.height * M / j}px`, V();
+	}, U = (e) => {
+		let t = k.get(e), n = t?.ready ? t : k.get("arrow");
+		(e !== L || n !== R) && (L = e, R = n, D.dataset.kind = e, window.clearInterval(B), z = 0, D.src = R.frames[0], D.style.filter = R.xor ? "invert(1)" : "", D.style.mixBlendMode = R.xor ? "difference" : "", R.frames.length > 1 && !r() && (B = window.setInterval(() => {
+			z = (z + 1) % R.frames.length, D.src = R.frames[z];
+		}, _)), H());
+	}, W = () => {
+		if (h()) return "wait";
+		let e = m(p(F, I));
+		if (e.some((e) => e.getAttribute("aria-busy") === "true")) return "wait";
+		for (let t of e) {
+			let e = t.getAttribute("data-vf-cursor");
+			if (e && l.includes(e)) return e;
+		}
+		return e[0] && f(e[0]) ? "text" : "arrow";
+	}, G = () => {
+		F < 0 || U(W());
+	}, K = 0, q = () => {
+		cancelAnimationFrame(K), K = requestAnimationFrame(() => {
+			K = requestAnimationFrame(H);
+		});
+	}, J = () => {
+		if (!(!O || !D.isConnected)) try {
+			D.hidePopover(), D.showPopover();
+		} catch {}
+	}, Y = new MutationObserver((e) => {
+		for (let t of e) {
+			let e = t.target;
+			if (t.attributeName === "open" && e instanceof i && e.open) {
+				J();
+				break;
+			}
+		}
+		G();
+	}), X = () => {
+		D.style.visibility = "hidden";
+	}, Z = (e) => {
+		if (e.pointerType === "touch") {
+			X();
+			return;
+		}
+		F = e.clientX, I = e.clientY, G(), V(), D.style.visibility = "visible";
+	}, Q = !1, $ = () => {
+		if (Q) return;
+		document.body.append(D), O && D.showPopover(), D.dataset.kind = "arrow", H(), document.head.append(E), C.style.setProperty("--vf-cursor", "none");
+		let e = {
+			capture: !0,
+			passive: !0,
+			signal: T
+		};
+		window.addEventListener("pointermove", Z, e), window.addEventListener("pointerdown", Z, e), window.addEventListener("pointercancel", X, e), document.addEventListener("mouseleave", X, { signal: T }), window.addEventListener("blur", X, { signal: T }), document.addEventListener("visibilitychange", () => {
+			document.hidden && X();
+		}, { signal: T }), window.addEventListener("resize", q, { signal: T }), Y.observe(document.body, {
+			subtree: !0,
+			attributes: !0,
+			attributeFilter: [
+				"open",
+				"aria-busy",
+				"data-vf-cursor"
+			]
+		});
+	}, ee = n(q);
+	A(k.get("arrow")).then(() => (D.src = R.frames[0], D.decode())).then($, () => {
+		console.warn("applyCursor: could not load the arrow art; keeping the native pointer");
+	});
+	for (let [e, t] of k) e !== "arrow" && A(t).then(() => G(), () => {
+		console.warn(`applyCursor: could not load the "${e}" art; it will fall back to the arrow`);
+	});
+	return () => {
+		if (Q = !0, w.abort(), Y.disconnect(), ee(), cancelAnimationFrame(K), window.clearInterval(B), O && D.isConnected) try {
+			D.hidePopover();
+		} catch {}
+		D.remove(), E.remove(), C.style.removeProperty("--vf-cursor");
+	};
+}
+//#endregion
+export { g as applyCursor };

package/dist/define.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Element registration, guarded against a second copy of the library.
+ *
+ * `customElements.define()` throws `NotSupportedError` if the name is taken,
+ * and an uncaught throw during module evaluation takes the whole import graph
+ * with it — one duplicated dependency and the consumer's page is blank. That is
+ * a plausible thing to happen by accident: a bundle that loads the kit
+ * alongside a micro-frontend that also bundles it, an app pinned to two
+ * versions through a nested dependency, a `<script type="module">` on a page
+ * whose framework already imported the package.
+ *
+ * So registration checks first and warns instead. The first copy wins — it owns
+ * the tag and the elements already upgraded against it — and the page keeps
+ * working. The warning matters as much as the guard, because a duplicated copy
+ * is not benign even once the page survives it: the scaling, grid-snapping and
+ * focus-modality registries are all module-scoped singletons, so the second
+ * copy's `applyGridSnap()` reaches none of the first copy's components and the
+ * two disagree silently. Better to say so than to let it look fine.
+ */
+/**
+ * Register `ctor` under `tagName` unless the name is already taken.
+ *
+ * Re-registering the identical constructor (the same module evaluated twice) is
+ * a silent no-op; a *different* constructor warns and leaves the incumbent in
+ * place. Use it directly when you define a control without the decorator:
+ *
+ * ```ts
+ * defineElement('my-control', MyControl)
+ * ```
+ */
+export declare const defineElement: (tagName: string, ctor: CustomElementConstructor) => void;
+/**
+ * The kit's replacement for Lit's `@customElement`, registering through
+ * {@link defineElement} so a duplicated copy warns rather than throwing.
+ * Identical to use:
+ *
+ * ```ts
+ * @vfElement('my-control')
+ * export class MyControl extends LitElement {}
+ * ```
+ *
+ * Handles both decorator dialects the way Lit's own does, so it keeps working
+ * if the project moves off `experimentalDecorators`.
+ */
+export declare const vfElement: (tagName: string) => <T extends CustomElementConstructor>(classOrTarget: T, context?: ClassDecoratorContext<T>) => T;

package/dist/define.js

@@ -0,0 +1,15 @@
+//#region src/define.ts
+var e = (e, t) => {
+	let n = customElements.get(e);
+	if (n !== t) {
+		if (n !== void 0) {
+			console.warn(`[vintage-frames] <${e}> is already registered on this page, so this second registration was skipped and the first one kept. Two copies of the library also mean two of every module-scoped singleton — applyGridSnap(), applyScale() and the focus-modality tracker each only reach the components built from their own copy. Dedupe vintage-frames to a single version.`);
+			return;
+		}
+		customElements.define(e, t);
+	}
+}, t = (t) => (n, r) => (r === void 0 ? e(t, n) : r.addInitializer(() => {
+	e(t, n);
+}), n);
+//#endregion
+export { e as defineElement, t as vfElement };

package/dist/document-listeners.d.ts

@@ -0,0 +1,62 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * One managed listener: target, event type, handler, and capture/options —
+ * exactly the arguments the add/remove pair is made with. The handler's event
+ * parameter is typed `never` (the bottom type) so a handler narrowed to its
+ * real event (`(event: PointerEvent) => void`) is accepted without a cast;
+ * the single widening cast lives inside the controller.
+ */
+export type DocumentListenerSpec = readonly [
+    target: EventTarget,
+    type: string,
+    handler: (event: never) => void,
+    options?: boolean | AddEventListenerOptions
+];
+/**
+ * Document-level listeners scoped to a transient state — an open panel, an
+ * in-flight gesture.
+ *
+ * The kit's transient surfaces (`vf-menu`, `vf-menu-bar`, `vf-select`) listen
+ * outside their own shadow root while open: capture-phase `pointerdown` for
+ * outside dismissal, `scroll`/`resize` to keep a fixed-position panel honest,
+ * document-wide keyboard navigation, a press gesture tracked to its release
+ * anywhere on the page. Each of them hand-rolled the same bookkeeping —
+ * add/remove calls that must mirror each other exactly, an attached guard
+ * making both idempotent, and a disconnect cleanup so a host torn down
+ * mid-open can't leak listeners onto the document. This controller owns that
+ * bookkeeping; the handlers, and when to {@link attach}, stay the host's.
+ *
+ * The spec list is a thunk, evaluated at attach time, so a controller field
+ * may sit above the handler fields it references without capturing their
+ * pre-initialization `undefined`. {@link detach} removes exactly the specs
+ * the last {@link attach} added.
+ *
+ * Listeners are detached on host disconnect and are NOT re-attached on
+ * reconnect: the state that warranted them (an open panel, a pressed pointer)
+ * is itself torn down by the host on disconnect.
+ */
+/**
+ * Runs `release` once the in-flight press gesture is over — its trailing
+ * `click`, wherever that lands, or a `pointercancel` if no click ever comes.
+ *
+ * A swallow-click latch armed on `pointerdown` cannot be cleared by the
+ * element's own click handler alone: per UI Events, the click after a
+ * press-drag-release is dispatched at the nearest common inclusive ancestor of
+ * the pointerdown and pointerup targets, so a press that releases elsewhere
+ * lands it *above* the pressed element, the clearing handler never runs, and
+ * the stuck latch silently swallows the next synthetic (assistive-tech)
+ * click. One-shot and bubble-phase, so the element's own click handler — the
+ * swallow itself — always runs first.
+ */
+export declare function releaseAfterGesture(release: () => void): void;
+export declare class DocumentListenersController implements ReactiveController {
+    private readonly listeners;
+    /** The specs currently attached; null while detached. */
+    private active;
+    constructor(host: ReactiveControllerHost, listeners: () => readonly DocumentListenerSpec[]);
+    /** Add every listener. A no-op while already attached. */
+    attach(): void;
+    /** Remove every listener the last {@link attach} added. A no-op while detached. */
+    detach(): void;
+    hostDisconnected(): void;
+}

package/dist/document-listeners.js

@@ -0,0 +1,29 @@
+//#region src/document-listeners.ts
+function e(e) {
+	let t = () => {
+		document.removeEventListener("click", t), document.removeEventListener("pointercancel", t), e();
+	};
+	document.addEventListener("click", t), document.addEventListener("pointercancel", t);
+}
+var t = class {
+	constructor(e, t) {
+		this.listeners = t, this.active = null, e.addController(this);
+	}
+	attach() {
+		if (!this.active) {
+			this.active = this.listeners();
+			for (let [e, t, n, r] of this.active) e.addEventListener(t, n, r);
+		}
+	}
+	detach() {
+		if (this.active) {
+			for (let [e, t, n, r] of this.active) e.removeEventListener(t, n, r);
+			this.active = null;
+		}
+	}
+	hostDisconnected() {
+		this.detach();
+	}
+};
+//#endregion
+export { t as DocumentListenersController, e as releaseAfterGesture };

package/dist/drag.d.ts

@@ -0,0 +1,49 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * The moving side of a pointer drag. A component supplies these callbacks; the
+ * {@link DragController} owns the pointer bookkeeping (which button, capture,
+ * delta tracking, system-pixel snapping) so window, dialog and icon dragging
+ * stay identical.
+ *
+ * Every coordinate here is in **system px** — the art's own unit, and the unit
+ * a placement is stored in, so that a dropped host is still where it was
+ * dropped after a zoom. The controller does the one conversion: pointer events
+ * arrive in CSS px, and only the *delta* is converted.
+ */
+export interface DragTarget {
+    /**
+     * A press landed on the drag handle. Return the origin in system px, the
+     * space {@link onDrag} writes back in, to begin the drag — or `null` to
+     * ignore this press (wrong button, landed on a widget, the host isn't
+     * movable). Seed any positioning state here before returning the origin.
+     */
+    onDragStart(event: PointerEvent): {
+        x: number;
+        y: number;
+    } | null;
+    /** Apply a moved origin, in system px, already snapped onto the lattice. */
+    onDrag(x: number, y: number): void;
+    /** Optional: the drag ended (pointer released or cancelled). */
+    onDragEnd?(): void;
+}
+/**
+ * Drag-to-move for 1-bit chrome. Bind {@link onPointerDown} / {@link onPointerMove}
+ * / {@link onPointerUp} to a handle element (`vf-window`'s title bar,
+ * `vf-dialog`'s title bar); the controller captures the pointer on that handle,
+ * tracks the delta from the press point, and hands the {@link DragTarget} a new
+ * origin in system px, snapped onto the placement lattice — whole art pixels,
+ * the way QuickDraw moved windows, which is also what keeps the pixel art
+ * inside fringe-free (see {@link snapSys}). The target decides how to apply
+ * it; all three write it through `top`/`left` (`src/position.ts`).
+ */
+export declare class DragController implements ReactiveController {
+    #private;
+    private readonly host;
+    private readonly target;
+    constructor(host: ReactiveControllerHost & Element, target: DragTarget);
+    /** Abandon an in-flight drag if the host is torn down mid-gesture. */
+    hostDisconnected(): void;
+    onPointerDown: (event: PointerEvent) => void;
+    onPointerMove: (event: PointerEvent) => void;
+    onPointerUp: (event: PointerEvent) => void;
+}

package/dist/drag.js

@@ -0,0 +1,30 @@
+import { effectiveScale as e, snapSys as t } from "./scale.js";
+//#region src/drag.ts
+var n = class {
+	#e;
+	#t;
+	#n;
+	#r;
+	#i;
+	constructor(n, r) {
+		this.host = n, this.target = r, this.#e = null, this.#t = 0, this.#n = 0, this.#r = 0, this.#i = 0, this.onPointerDown = (e) => {
+			if (this.#e !== null) return;
+			let t = this.target.onDragStart(e);
+			t && (this.#e = e.pointerId, this.#t = e.clientX, this.#n = e.clientY, this.#r = t.x, this.#i = t.y, e.currentTarget.setPointerCapture(e.pointerId), e.preventDefault());
+		}, this.onPointerMove = (n) => {
+			if (n.pointerId !== this.#e) return;
+			let r = e(this.host);
+			this.target.onDrag(t(this.#r + (n.clientX - this.#t) / r, this.host), t(this.#i + (n.clientY - this.#n) / r, this.host));
+		}, this.onPointerUp = (e) => {
+			if (e.pointerId !== this.#e) return;
+			this.#e = null;
+			let t = e.currentTarget;
+			t.hasPointerCapture(e.pointerId) && t.releasePointerCapture(e.pointerId), this.target.onDragEnd?.();
+		}, n.addController(this);
+	}
+	hostDisconnected() {
+		this.#e = null;
+	}
+};
+//#endregion
+export { n as DragController };

package/dist/events.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Dispatch a `vf-*` CustomEvent following the kit's SPEC §4 convention: every
+ * public component event bubbles and crosses shadow roots (`bubbles: true`,
+ * `composed: true`) so an ancestor listener in the light DOM can hear it.
+ *
+ * Centralises the boilerplate that was hand-rolled at 30+ call sites (and in
+ * three near-identical private `#emit`/`_emit` wrappers). Returns
+ * `dispatchEvent`'s result — `false` when a `cancelable` event was canceled
+ * (used by the internal `vf-menu-toggle-request` handshake), otherwise `true`.
+ *
+ * The *internal* coordination events (the menu handshakes, the list-item
+ * disabled notice) pass `composed: false`: parent and child share one light
+ * tree, so crossing shadow roots buys them nothing — and leaking a private,
+ * cancelable protocol out of a consumer's own shadow boundary hands their
+ * delegated listeners an event they can break the kit by cancelling.
+ *
+ * @param host      element to dispatch from (the event's `target`)
+ * @param name      event type, e.g. `'vf-change'`
+ * @param detail    optional `event.detail` payload
+ * @param options   set `cancelable` to allow a listener to `preventDefault()`;
+ *                  set `composed: false` to keep an internal event inside the
+ *                  dispatching tree
+ */
+export declare function emit<T = unknown>(host: EventTarget, name: string, detail?: T, options?: {
+    cancelable?: boolean;
+    composed?: boolean;
+}): boolean;
+/**
+ * Dispatch the *native* `input`/`change` event a form control's host owes the
+ * platform, alongside the kit's `vf-input`/`vf-change`.
+ *
+ * A form-associated custom element that contributes to `FormData` but never
+ * fires `change` is half a native control: `form.addEventListener('change')`
+ * delegation hears nothing, and framework bindings (React's `onChange`, Vue's
+ * `v-model`) have nothing to bind to. Each control calls this from its **user
+ * interaction** paths only — a programmatic `value` set fires nothing, exactly
+ * as a native control fires nothing.
+ *
+ * The flags mirror the platform's own: both bubble; `input` is composed and
+ * `change` is not (UI Events). That composed split is also why the kit's
+ * *fields* only bridge `change`: their inner native control's own `input`
+ * already crosses the shadow boundary and retargets to the host, so
+ * re-dispatching it would double-fire every keystroke.
+ */
+export declare function emitNative(host: EventTarget, type: 'input' | 'change'): void;
+/**
+ * Run a control's **activation behavior** the way HTML runs a native one's: at
+ * the *end* of the click's propagation, and not at all if anything on the path
+ * called `preventDefault()`.
+ *
+ * This is what makes `preventDefault()` on a native checkbox — or on any
+ * ancestor — actually stop it from checking. A handler that acts where it sits
+ * cannot reproduce it: a listener on the control (or, worse, one registered in
+ * the constructor, which is first in the host's own listener list) beats every
+ * listener a consumer can write, so only a capture-phase cancel ever landed —
+ * and even that needs someone to *read* `defaultPrevented`, which is the half
+ * that is easy to forget.
+ *
+ * The deferral works because each node's listener list is read as that node is
+ * reached, so a listener added to the window *during* dispatch still runs when
+ * the event gets there — by which point `defaultPrevented` is final. The one
+ * ordering HTML has that this doesn't: a window listener registered before this
+ * one still runs before the action.
+ *
+ * `stopPropagation()` cancels nothing in HTML — a native button still submits —
+ * but it does stop the event ever reaching the window, so a task picks the
+ * action up in that case. A task and **never** a microtask: microtasks
+ * interleave *between* the listeners of a trusted dispatch, which would put the
+ * action back before the path is done.
+ *
+ * Callers keep their own guards (disabled, re-entrancy, gesture latches) — this
+ * owns the timing alone. `vf-button` runs the same shape inline, with the
+ * submit proxy's re-entrancy guard woven through it.
+ *
+ * @param host    the element whose ownerDocument supplies the window to defer on
+ * @param event   the click being deferred; its `defaultPrevented` is the verdict
+ * @param action  run once, at the end of the path, unless cancelled
+ */
+export declare function deferActivation(host: Element, event: Event, action: () => void): void;

package/dist/events.js

@@ -0,0 +1,25 @@
+//#region src/events.ts
+function e(e, t, n, r) {
+	return e.dispatchEvent(new CustomEvent(t, {
+		detail: n,
+		bubbles: !0,
+		composed: r?.composed ?? !0,
+		cancelable: r?.cancelable ?? !1
+	}));
+}
+function t(e, t) {
+	e.dispatchEvent(new Event(t, {
+		bubbles: !0,
+		composed: t === "input"
+	}));
+}
+function n(e, t, n) {
+	let r = e.ownerDocument.defaultView;
+	if (!r) return;
+	let i = 0, a = () => {
+		r.removeEventListener("click", a), r.clearTimeout(i), !t.defaultPrevented && n();
+	};
+	r.addEventListener("click", a), i = r.setTimeout(a, 0);
+}
+//#endregion
+export { n as deferActivation, e as emit, t as emitNative };