vintage-frames 0.1.0

package/dist/pixel-frame.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Pixel-exact stepped silhouettes for variable-size 1-bit chrome — the
+ * `clip-path` analog of the fixed-size sprite glyphs in `glyphs.ts`.
+ *
+ * A System 7 rounded rectangle is not a curve: it is a staircase of whole
+ * pixels. Native `border-radius` renders those corners as antialiased arcs,
+ * which is exactly the gray smudge the kit forbids. Instead we author each
+ * silhouette as a *corner trace* — the per-row left inset of the shape, in
+ * system pixels, read straight off the reference sheet
+ * read off the 1x button reference sheet — and compile it into a
+ * stepped `polygon()` whose every vertex is a `calc(var(--vf-scale, 1) * Npx)`
+ * multiple. Under display scaling each system pixel is a whole number of
+ * device pixels, so every edge lands on the device grid and nothing
+ * antialiases; the element's own `background` supplies the color, so the
+ * result stays `var(--vf-*)`-themeable like everything else (SPEC §1).
+ *
+ * Corners are anchored to their own edges (left/right via `100% - …`), so one
+ * polygon fits any width and height: the straight runs stretch, the traced
+ * corners never distort — the CSS equivalent of a 9-slice.
+ *
+ * A frame is drawn as a *difference of silhouettes*, exactly like QuickDraw's
+ * `FrameRoundRect`: paint the outer silhouette in the frame color, then paint
+ * the face silhouette (inset one pixel, with its own traced corners) on top.
+ * The 1px outline — including the 2px-wide diagonal step pixels at the
+ * corners — is simply the region the face doesn't cover. The reference's
+ * border pixels reproduce exactly; nothing is stroked.
+ */
+/** A stepped silhouette: per-row corner insets traced from the reference. */
+export interface SteppedProfile {
+    /**
+     * Left inset (system px) of each corner row, topmost first. Mirrored to all
+     * four corners; must be non-increasing (each row steps outward).
+     */
+    readonly corner: readonly number[];
+    /** Inset of the straight edges once the corner rows are exhausted. */
+    readonly edge: number;
+    /** Row (system px from the box top) where the silhouette begins. */
+    readonly start: number;
+}
+/**
+ * The push button's outer silhouette. Reference rows (80×20 sample, pressed
+ * state is solid ink so the trace is unambiguous): y0 inset 3, y1–y2 inset 1,
+ * then straight. Identical on the short row-3 buttons, so it holds for any
+ * control height.
+ */
+export declare const BUTTON_FRAME: SteppedProfile;
+/**
+ * The button's face (the white fill inside the 1px frame). Starts one row
+ * down: y1 from x3, y2 from x2, then 1px inside the straight edges. Painting
+ * this over {@link BUTTON_FRAME} leaves the reference's exact border pixels —
+ * row 0 full-width, `##`/`#` corner steps, 1px sides.
+ */
+export declare const BUTTON_FACE: SteppedProfile;
+/**
+ * Outer silhouette of the default-button ring. The reference ring box is the
+ * button box outset by {@link RING_INSET} on every side (88×28 around 80×20):
+ * y0 inset 5, y1 3, y2 2, y3–y4 1, then straight.
+ */
+export declare const RING_FRAME: SteppedProfile;
+/**
+ * The transparent hole inside the ring. The band is 3px thick: the hole opens
+ * at row 3 (inset 6, then 4, 4, then 3px inside the straight edges). Kept as
+ * a hole — not painted over — so the 1px gap between ring and button shows
+ * the surface behind, exactly like the sheet's alpha-0 gap pixels.
+ */
+export declare const RING_HOLE: SteppedProfile;
+/** How far the ring box outsets the button box on each side (system px). */
+export declare const RING_INSET = 4;
+/**
+ * The screen-corner mask: per-row width (system px) of the black staircase a
+ * compact Mac's ROM painted over the rounded corners of its CRT — what makes
+ * the System 7 menu bar's top corners read as rounded. Traced from a 1x
+ * screen capture (5×5 corner crop): y0 run 5, y1 3, y2 2, y3–y4 1. The same
+ * radius-5 staircase as {@link RING_FRAME}'s corner — QuickDraw had one
+ * vocabulary for round corners — but the opposite *object*: this is the ink
+ * outside the silhouette, not the silhouette, so it compiles through
+ * {@link steppedCornerClip} rather than the rect compilers.
+ */
+export declare const SCREEN_CORNER: readonly number[];
+/** Compile a profile into a stepped `polygon()` clip-path value. */
+export declare const steppedRectClip: (p: SteppedProfile) => string;
+/**
+ * Compile a corner-mask run list into the ink polygon for one *top* corner —
+ * the corner box minus the rounded silhouette, i.e. the region the screen
+ * mask blacked out. Runs are the mask's per-row width, topmost first; `side`
+ * mirrors the staircase (via `100% - …`) for the top-right corner. Clip an
+ * element `runs[0]` wide × `runs.length` tall (system px), anchored into its
+ * corner, and let its `background` supply the ink.
+ */
+export declare const steppedCornerClip: (runs: readonly number[], side: "left" | "right") => string;
+/**
+ * Compile an outer profile and a hole profile into a ring (a stepped donut).
+ *
+ * `polygon()` has no subpaths, so the hole uses the keyhole technique: walk
+ * the outer loop clockwise from the top-center, bridge straight down to the
+ * hole's top edge, walk the hole counter-clockwise, and bridge back up. The
+ * two bridge edges are coincident verticals at x 50%, so with the `evenodd`
+ * fill rule they cancel exactly — no visible seam — and the enclosed hole
+ * (crossed twice) stays transparent, keeping the classic gap between the
+ * default ring and the button see-through.
+ */
+export declare const steppedRingClip: (outer: SteppedProfile, hole: SteppedProfile) => string;

package/dist/pixel-frame.js

@@ -0,0 +1,77 @@
+//#region src/pixel-frame.ts
+var e = {
+	corner: [
+		3,
+		1,
+		1
+	],
+	edge: 0,
+	start: 0
+}, t = {
+	corner: [3, 2],
+	edge: 1,
+	start: 1
+}, n = {
+	corner: [
+		5,
+		3,
+		2,
+		1,
+		1
+	],
+	edge: 0,
+	start: 0
+}, r = {
+	corner: [
+		6,
+		4,
+		4
+	],
+	edge: 3,
+	start: 3
+}, i = 4, a = [
+	5,
+	3,
+	2,
+	1,
+	1
+], o = (e) => e === 0 ? "0" : `calc(var(--vf-scale, 1) * ${e}px)`, s = (e) => e === 0 ? "100%" : `calc(100% - var(--vf-scale, 1) * ${e}px)`, c = (e) => {
+	let t = [], n = e.corner[0] ?? e.edge;
+	for (let r = 1; r <= e.corner.length; r++) {
+		let i = e.corner[r] ?? e.edge;
+		i !== n && (t.push({
+			y: e.start + r,
+			from: n,
+			to: i
+		}), n = i);
+	}
+	return t;
+}, l = (e) => {
+	let t = e.corner[0] ?? e.edge, n = c(e), r = [...n].reverse(), i = [];
+	i.push(`${o(t)} ${o(e.start)}`, `${s(t)} ${o(e.start)}`);
+	for (let e of n) i.push(`${s(e.from)} ${o(e.y)}`, `${s(e.to)} ${o(e.y)}`);
+	for (let e of r) i.push(`${s(e.to)} ${s(e.y)}`, `${s(e.from)} ${s(e.y)}`);
+	i.push(`${s(t)} ${s(e.start)}`, `${o(t)} ${s(e.start)}`);
+	for (let e of n) i.push(`${o(e.from)} ${s(e.y)}`, `${o(e.to)} ${s(e.y)}`);
+	for (let e of r) i.push(`${o(e.to)} ${o(e.y)}`, `${o(e.from)} ${o(e.y)}`);
+	return i;
+}, u = (e) => `polygon(${l(e).join(", ")})`, d = (e, t) => {
+	let n = t === "left" ? o : s, r = e[0] ?? 0, i = [`${n(0)} ${o(0)}`, `${n(r)} ${o(0)}`];
+	for (let t = 1; t <= e.length; t++) {
+		let a = e[t] ?? 0;
+		a !== r && (i.push(`${n(r)} ${o(t)}`, `${n(a)} ${o(t)}`), r = a);
+	}
+	return `polygon(${i.join(", ")})`;
+}, f = (e, t) => {
+	let n = l(e), r = l(t), i = `50% ${o(e.start)}`, a = `50% ${o(t.start)}`, s = [...n.slice(1), n[0]], c = [r[0], ...r.slice(1).reverse()];
+	return `polygon(evenodd, ${[
+		i,
+		...s,
+		i,
+		a,
+		...c,
+		a
+	].join(", ")})`;
+};
+//#endregion
+export { t as BUTTON_FACE, e as BUTTON_FRAME, n as RING_FRAME, r as RING_HOLE, i as RING_INSET, a as SCREEN_CORNER, d as steppedCornerClip, u as steppedRectClip, f as steppedRingClip };

package/dist/popup-overflow.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Popup overflow — the geometry of a menu taller than the screen.
+ *
+ * System 7 never put a scrollbar on a menu. A popup whose list doesn't fit is
+ * **clipped**: the panel is drawn once, the overflowing items are simply not on
+ * screen, and the edge slot that has items beyond it shows a solid black arrow
+ * in place of a row. Resting the pointer on the arrow rolls the items through
+ * the panel one row at a time; once the last item is in view the arrow
+ * disappears. A list can overflow both edges at once, and the panel box itself
+ * never moves or resizes while open — scrolling rolls the items *inside* it.
+ *
+ * This module is the arithmetic of that, kept out of the component for the same
+ * reason `zoom.ts` is: it is pure, it is testable without a browser, and
+ * `vf-menu` will want the identical model when pull-down clamping lands (System
+ * 7 scrolled long pull-downs with the very same mechanism).
+ *
+ * Three ideas carry the whole thing.
+ *
+ * **The pill lattice.** A popup opens with the selected row's cell laid over
+ * the closed pill, which fixes an `idealTop` — the panel top at which that
+ * overlay is exact. Every clamp here is quantized to *whole rows* off that
+ * lattice, so a panel forced away from the screen edge lands one, two, five
+ * rows down rather than an arbitrary number of pixels: the row grid never
+ * shifts relative to the pill, and a clamped popup keeps the closed↔open label
+ * alignment that an un-quantized pixel clamp destroys.
+ *
+ * **The panel is as tall as the list wants, not as tall as the items it can
+ * currently show.** This is the part that looks wrong until you scroll it. A
+ * 12-item list that has to sit somewhere other than where the pill would put it
+ * keeps all 12 slots and slides whole rows to fit the screen; the item strip
+ * stays welded to the pill, so the slots the strip doesn't reach are drawn as
+ * empty white. That blank is not filler — it is the exact travel the list will
+ * roll through, so that scrolling to the end lands the strip flush with the
+ * panel, *precisely* full, both arrows retired. The kit reproduces it because
+ * System 7 did: it is visible in a screenshot of Find File's criteria popup
+ * (5 empty rows above `name`) and of the Character Set font menu (2 above
+ * `Athens`). Only when the whole list cannot fit the screen band at all does
+ * the panel stop at the band's capacity and keep an arrow permanently.
+ *
+ * **The two directions are one rule.** A panel pushed *up* the screen (the pill
+ * is low) reserves its blank at the **top** and rolls down into it; a panel
+ * pushed *down* (the pill is high, with a late item selected) reserves it at
+ * the **bottom** and rolls up into it. Nothing below distinguishes the cases —
+ * the sign of one integer does.
+ *
+ * **One integer.** `scroll` is how many rows the strip is rolled up past the
+ * panel's top edge, and slot `i` shows row `scroll + i`. It is free to leave
+ * the range `[0, rowCount − visibleSlots]` that would keep every slot filled,
+ * and *that* is the reserved blank: below 0 the first `−scroll` slots are
+ * empty, above `rowCount − visibleSlots` the last few are. The up arrow shows
+ * when `scroll > 0` (rows really are hidden above), the down arrow when
+ * `scroll < rowCount − visibleSlots` (rows really are hidden below).
+ * Everything else — which rows are pickable, where the highlight may legally
+ * sit, how far a keypress must roll the list — falls out of that. Note what the
+ * two conditions say about the opening state: whichever end the blank is on,
+ * the arrow pointing back at it is the one that is *off*. The blank is a
+ * one-way starting position, not somewhere the user can scroll back to.
+ */
+/**
+ * The fewest row slots a clamped panel is drawn with. With both arrows shown,
+ * three slots is the minimum that leaves one *pickable* row between them — at
+ * two, the panel offers nothing to choose. A viewport too short for three rows
+ * (48 system px) is already outside the kit's world, so the floor is allowed to
+ * intrude on the screen-edge insets: a shaved inset beats a menu you cannot
+ * pick from.
+ */
+export declare const MIN_VISIBLE_SLOTS = 3;
+/** Inputs to {@link layoutClampedPopup}. Lengths in CSS px, already scaled. */
+export interface PopupClampArgs {
+    /** Panel top at which the selected row overlays the pill exactly. */
+    idealTop: number;
+    /** Height of one option row. */
+    rowHeight: number;
+    /** The panel's border width (one side). */
+    border: number;
+    /** How many options the list holds. */
+    rowCount: number;
+    /** Top of the usable screen band (the top inset). */
+    viewTop: number;
+    /** Bottom of the usable screen band (viewport height minus the bottom inset). */
+    viewBottom: number;
+}
+/** The panel box and the scroll state a clamped popup opens with. */
+export interface PopupLayout {
+    /** Panel border-box top, a whole number of rows off the pill lattice. */
+    panelTop: number;
+    /** Panel border-box height — a whole number of row slots plus both borders. */
+    panelHeight: number;
+    /** Row slots the panel is drawn with (`R`). */
+    visibleSlots: number;
+    /** Opening scroll (`S`) — negative when the panel opens with blank above. */
+    initialScroll: number;
+}
+/**
+ * Fit a popup's panel into the usable screen band, quantized to the pill
+ * lattice.
+ *
+ * The panel wants every row it has (`rowCount` slots) and wants to sit at
+ * `idealTop`. Both wishes bend a whole row at a time:
+ *
+ *  - **Position** first. `scroll` *is* the panel's row offset from `idealTop`
+ *    (`panelTop = idealTop + scroll × rowHeight`), because sliding the box
+ *    while the strip stays on the lattice is the same act as scrolling the
+ *    strip while the box stays put. So the search is for the integer `scroll`
+ *    nearest 0 that puts the whole box inside the band — negative to slide the
+ *    box up, positive to slide it down, with the reserved blank falling out at
+ *    whichever end the strip no longer reaches.
+ *  - **Height** only if position alone can't do it. Each row given up buys one
+ *    row of freedom for `scroll`, so the loop hands back one slot at a time
+ *    until an integer fits — which is at most a couple of iterations, and is
+ *    also how a list far taller than the screen settles at the band's capacity.
+ *
+ * When neither has to bend — `initialScroll` 0 and `visibleSlots === rowCount`
+ * — the result is exactly the unclamped placement the popup has always used, so
+ * a list that fits is untouched by any of this.
+ */
+export declare function layoutClampedPopup(args: PopupClampArgs): PopupLayout;
+/**
+ * The lowest row index the user can pick right now. An arrow *overlays* the
+ * slot it occupies — an opaque white row covering the item beneath, which is
+ * the whole mechanism — so a shown up arrow costs the first slot its row. With
+ * blank reserved above (`scroll` negative) there is no up arrow and no hidden
+ * row, so the first item is simply row 0.
+ */
+export declare function firstPickableRow(scroll: number): number;
+/**
+ * The highest row index the user can pick right now — the mirror of the above,
+ * ending at the last row when the down arrow is absent (which covers both the
+ * flush case and blank reserved below).
+ */
+export declare function lastPickableRow(scroll: number, rowCount: number, visibleSlots: number): number;
+/**
+ * The scroll position that brings row `index` into a pickable slot, leaving it
+ * one slot clear of whichever arrow will still be showing. Already-pickable
+ * rows give the scroll back unchanged — including one outside the flush range,
+ * so opening a panel with reserved blank and then merely moving the highlight
+ * doesn't scrub that blank away.
+ *
+ * The two endpoints are the reason for the `+ 2` / `− 1` rather than the
+ * obvious `+ 1` / `− 0`: row 0 and row `rowCount − 1` are reached at
+ * `scroll = 0` and `scroll = rowCount − visibleSlots`, where the arrow in
+ * question has just disappeared and the row may take the edge slot itself.
+ *
+ * A deliberate move never re-enters the reserved blank at either end — it is a
+ * starting position the list rolls out of, not one it can roll back into.
+ */
+export declare function ensureVisibleScroll(index: number, scroll: number, rowCount: number, visibleSlots: number): number;
+/**
+ * Hold a scroll inside its legal range. Normally that is `0` (row 0 in slot 0)
+ * to `rowCount − visibleSlots` (the last row in the last slot) — but a panel
+ * that opened with reserved blank starts *outside* that range at whichever end
+ * the blank is on, and the widened bound (`min(from, 0)`, `max(from, …)`) is
+ * what lets it roll out of the blank while never letting it roll back in.
+ * Symmetric in both directions, and it narrows to the normal range the moment
+ * the list reaches it.
+ */
+export declare function clampScroll(scroll: number, from: number, rowCount: number, visibleSlots: number): number;

package/dist/popup-overflow.js

@@ -0,0 +1,45 @@
+//#region src/popup-overflow.ts
+var e = .001;
+function t(t) {
+	let { idealTop: n, rowHeight: r, border: i, rowCount: a, viewTop: o, viewBottom: s } = t;
+	if (a <= 0 || r <= 0) return {
+		panelTop: n,
+		panelHeight: 2 * i,
+		visibleSlots: 0,
+		initialScroll: 0
+	};
+	let c = Math.min(a, 3), l = Math.floor((s - o - 2 * i) / r + e), u = Math.min(a, Math.max(l, c)), d = 0;
+	for (;;) {
+		let t = u * r + 2 * i, a = Math.ceil((o - n) / r - e), l = Math.floor((s - t - n) / r + e);
+		if (a <= l) {
+			d = Math.min(Math.max(0, a), l);
+			break;
+		}
+		if (u <= c) {
+			d = Math.max(0, a);
+			break;
+		}
+		--u;
+	}
+	return {
+		panelTop: n + d * r,
+		panelHeight: u * r + 2 * i,
+		visibleSlots: u,
+		initialScroll: d
+	};
+}
+function n(e) {
+	return e > 0 ? e + 1 : 0;
+}
+function r(e, t, n) {
+	return e < t - n ? e + n - 2 : t - 1;
+}
+function i(e, t, i, o) {
+	let s = t;
+	return e < n(t) ? s = e === 0 ? 0 : e - 1 : e > r(t, i, o) && (s = e === i - 1 ? i - o : e - o + 2), a(s, t, i, o);
+}
+function a(e, t, n, r) {
+	return Math.max(Math.min(t, 0), Math.min(e, Math.max(t, n - r)));
+}
+//#endregion
+export { a as clampScroll, i as ensureVisibleScroll, n as firstPickableRow, r as lastPickableRow, t as layoutClampedPopup };

package/dist/position.d.ts

@@ -0,0 +1,187 @@
+import type { LitElement } from 'lit';
+type Constructor<T = object> = new (...args: any[]) => T;
+/**
+ * The mixin's surface, as a `declare class` for the same TS4094 reason
+ * {@link VfToggleControlInterface} states: TypeScript cannot name the
+ * anonymous class a mixin returns when emitting declarations. Keep it in sync
+ * with the implementation below.
+ */
+export declare abstract class VfPositionedInterface extends LitElement {
+    top?: number | null;
+    left?: number | null;
+}
+/**
+ * Explicit placement — `top`/`left` in whole system px, on (nearly) every
+ * component.
+ *
+ * A DITL resource laid a dialog out as a list of items, each with a rectangle
+ * in the window's own coordinates; arranging controls by stating where they go
+ * is as native to System 7 as stacking them. This mixin is that mechanism:
+ * declaring `top` or `left` takes the element out of normal flow and
+ * absolutely positions it within its parent, both coordinates in the art's own
+ * unit so the position scales with the display like every other metric. A
+ * window or dialog body can be laid out either way — a tree of `vf-stack`s, or
+ * positioned children — with no stylesheet in either case.
+ *
+ * Mechanics, mirroring how `vf-stack` writes its declared size:
+ *
+ * - Setting either property writes `position: absolute` and both offsets onto
+ *   the host's inline style as `calc(var(--vf-scale, 1) * Npx)` — live against
+ *   the display, resolved at paint time. The coordinate left unset is 0.
+ * - `right`/`bottom` are released to `auto` and `margin` zeroed, so the stated
+ *   offsets are the whole story — an auto-width box with both edges set would
+ *   stretch rather than sit (the `vf-icon` seed logic, generalized).
+ * - Unsetting both returns the element to normal flow: every inline
+ *   declaration this wrote is removed, and stylesheet values resume.
+ *
+ * The anchor is CSS's own: the nearest positioned ancestor's padding box. The
+ * kit's containers are all deliberate anchors — a desktop's raster, a window's
+ * content region (the frame's inner edge, below the title bar — the 12px body
+ * inset governs flow content only, exactly the DITL convention), a dialog's
+ * content area, a stack's box, a fieldset's border box, a scroll area's
+ * scrolled plane. In a non-kit parent, give the parent `position: relative`,
+ * the one line of CSS this feature can't write for you.
+ *
+ * The writing rides a {@link ReactiveController} (`hostUpdated`) rather than
+ * an `updated()` override, for a lifecycle reason worth keeping in the source:
+ * the mixin sits *under* each component class, and most components override
+ * `updated()` without calling `super.updated()` — Lit's base is a no-op, so
+ * nothing ever forced the call — which would silently shadow a mixin-level
+ * override. A controller is invoked by ReactiveElement itself, after every
+ * update, no matter what the subclass does.
+ *
+ * A gesture writes **through these properties**: `vf-window`'s title-bar drag
+ * and `vf-icon`'s drag and arrow nudge hand their new origin to a
+ * {@link PlacementController}, which snaps it onto the placement lattice and
+ * sets `left`/`top`. A moved element is therefore placed exactly the way an
+ * authored one is — a live `calc()` in the art's own unit — and stays where it
+ * was dropped when the zoom or the display changes what a system px costs.
+ *
+ * It did not always. Writing the resolved CSS px straight to the inline style
+ * froze the coordinate in the wrong unit: `--vf-scale` moved under it at every
+ * zoom step and the same constant read back as a different number of system px,
+ * so moved windows and icons slid off the grid the rest of the kit stayed on
+ * (by `3z / round(3z)` — 10% at 110% zoom, where nothing else moves at all).
+ *
+ * Setting a property yourself is still the deliberate way to re-place a moved
+ * element. The controller re-applies **only when the values changed**, so an
+ * unrelated update — a heading change, a desktop toggling `active` — never
+ * re-asserts a coordinate and costs nothing.
+ */
+export declare const VfPositioned: <T extends Constructor<LitElement>>(Base: T) => Constructor<VfPositionedInterface> & T;
+/** The box a gesture is clamped into, in system px — see {@link PlacementClamp}. */
+export type PlacementBounds = {
+    width: number;
+    height: number;
+};
+/**
+ * A moved host's own containment rule, in system px, against the box measured
+ * once at the start of the gesture.
+ */
+export type PlacementClamp = (x: number, y: number, bounds: PlacementBounds) => {
+    x: number;
+    y: number;
+};
+/**
+ * The gesture half of placement: the piece a *movable* host adds on top of
+ * {@link VfPositioned}, so a drag ends up in the same `top`/`left` system-px
+ * properties an author would have written.
+ *
+ * Two things it owns, both consequences of storing the origin in the art's own
+ * unit rather than in resolved CSS px:
+ *
+ * - **Seeding.** A gesture starts from wherever the host already is, which may
+ *   be a coordinate nobody stated in system px — an authored `left: 10%`, a
+ *   `right`-anchored Trash icon, or plain normal flow. {@link seed} reads the
+ *   *used* position and converts it once; from then on the properties are the
+ *   whole truth.
+ * - **The lattice.** Every write is snapped to {@link snapSys} — whole art
+ *   pixels, the way QuickDraw moved windows, and the k-system-px run that also
+ *   lands the edge on a whole CSS px (scale.ts explains why that second half
+ *   matters to a scroll rail).
+ *
+ * It holds no state the host's own properties don't already hold, so it takes
+ * no lifecycle and is not a {@link ReactiveController}: the writes it makes are
+ * ordinary property sets, and `VfPositioned`'s controller renders them.
+ *
+ * And one thing it deliberately does **not** do: re-snap a placed host when the
+ * scale changes. The lattice moves with the scale (k is 2 at dpr 2, 3 at that
+ * display's 150%), so a coordinate dropped on one rung sits between two on the
+ * next — but re-rounding it there is worse than leaving it. It is lossy, and it
+ * compounds: 62 → 63 at 150% → 64 at 200%, a window walking away from where it
+ * was dropped one zoom step at a time, which is a milder version of the exact
+ * bug this class exists to fix (`verify:zoom` group (e) fails on it). Whole
+ * system px is whole *device* px at every rung by the scale contract, so the
+ * art stays crisp regardless; only the whole-CSS-px edge is given up, and an
+ * authored `left="10"` gives that up already. A dropped coordinate is therefore
+ * as immutable as an authored one — which is the whole claim.
+ */
+export declare class PlacementController {
+    #private;
+    constructor(host: HTMLElement & {
+        top?: number | null;
+        left?: number | null;
+    }, clamp: PlacementClamp);
+    /** Whether a gesture has placed this host (as opposed to markup or CSS). */
+    get placed(): boolean;
+    /**
+     * The origin a move adds its delta to, in system px.
+     *
+     * A stated coordinate is authoritative and needs no measuring — including
+     * the one this controller wrote last time. Otherwise the host is wherever
+     * layout or a stylesheet put it, so the *used* position is read and
+     * converted: absolutely positioned hosts through their computed offsets
+     * (`left: 10%` and `left: 1em` are perfectly good ways to place one, and
+     * both resolve to px here), everything else through its in-flow offset,
+     * which is measured against the same padding box `left`/`top` will be.
+     */
+    seed(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Place the host at a system-px origin, clamped by its own rule and snapped.
+     *
+     * The clamp runs *here*, during the gesture, which is the moment the user is
+     * actually pushing against an edge — and nowhere else. Re-clamping later, on
+     * a parent that shrank under a zoom, would move a host nobody moved and would
+     * not give the position back when the parent grew again.
+     *
+     * It runs against the box {@link seed} measured, not a fresh one. The
+     * difference only shows when the movable contract is unmet: a host with no
+     * stated origin is in normal flow, so its first move takes it out — and an
+     * auto-height parent then collapses to whatever is left, which is a box the
+     * host never actually sat in. Re-measuring per move would clamp the rest of
+     * the gesture into that phantom, walking the host to the parent's origin
+     * while the user drags away from it. The box at the moment of the press is
+     * the one the user is pushing against.
+     */
+    moveTo(x: number, y: number): void;
+}
+/**
+ * The movable contract, as a one-time console warning.
+ *
+ * A host that moves under a gesture states its own origin, and its positioning
+ * parent is a box with a size. Neither half is something the component can
+ * supply for itself, and both fail quietly rather than loudly:
+ *
+ * - **Unplaced.** A host still in normal flow has to be taken out of it by its
+ *   first move — which reflows everything after it and can collapse the very
+ *   parent the clamp is about to measure. What matters is being out of flow,
+ *   not which mechanism did it: `top`/`left` are the kit's way and the one that
+ *   scales, but a stylesheet's own `position: absolute` satisfies it too, and
+ *   {@link PlacementController.seed} reads that case from the computed offsets.
+ * - **Unsized parent.** A positioning parent with no box gives the clamp no
+ *   range, and the host cannot be dragged away from the parent's origin at all.
+ *   Only checked for a real ancestor: with no positioned ancestor the host
+ *   resolves against the initial containing block and the clamp falls back to
+ *   the viewport, which agree with each other and need no warning.
+ *
+ * Returns whether it warned, so the caller can latch — one warning per element,
+ * not per render.
+ */
+export declare function warnMovableContract(host: HTMLElement & {
+    top?: number | null;
+    left?: number | null;
+}, what: string, example: string): boolean;
+export {};

package/dist/position.js

@@ -0,0 +1,74 @@
+import { snapSys as e, sysLength as t, toSysExact as n } from "./scale.js";
+import r from "./_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { property as i } from "lit/decorators.js";
+//#region src/position.ts
+var a = (e) => {
+	class t extends e {
+		constructor(...e) {
+			super(...e), new o(this);
+		}
+	}
+	return r([i({ type: Number })], t.prototype, "top", void 0), r([i({ type: Number })], t.prototype, "left", void 0), t;
+}, o = class {
+	#e;
+	#t = null;
+	#n = null;
+	#r = !1;
+	constructor(e) {
+		this.#e = e, e.addController(this);
+	}
+	hostUpdated() {
+		let e = this.#e.top ?? null, n = this.#e.left ?? null, r = this.#e.style;
+		if (e === null && n === null) {
+			if (!this.#r) return;
+			this.#r = !1, r.removeProperty("position"), r.removeProperty("top"), r.removeProperty("left"), r.removeProperty("right"), r.removeProperty("bottom"), r.removeProperty("margin");
+			return;
+		}
+		this.#r && e === this.#t && n === this.#n || (this.#r = !0, this.#t = e, this.#n = n, r.position = "absolute", r.top = t(e ?? 0), r.left = t(n ?? 0), r.right = "auto", r.bottom = "auto", r.margin = "0");
+	}
+}, s = class {
+	#e;
+	#t;
+	#n = !1;
+	#r = null;
+	constructor(e, t) {
+		this.#e = e, this.#t = t;
+	}
+	get placed() {
+		return this.#n;
+	}
+	seed() {
+		let t = this.#e;
+		if (this.#r = this.#i(), t.left != null || t.top != null) return {
+			x: t.left ?? 0,
+			y: t.top ?? 0
+		};
+		let r = getComputedStyle(t), i = r.position === "absolute" || r.position === "fixed", a = i ? parseFloat(r.left) || 0 : t.offsetLeft, o = i ? parseFloat(r.top) || 0 : t.offsetTop;
+		return {
+			x: e(n(a, t), t),
+			y: e(n(o, t), t)
+		};
+	}
+	moveTo(t, n) {
+		let r = this.#e, i = this.#t(t, n, this.#r ?? this.#i());
+		r.left = e(i.x, r), r.top = e(i.y, r), this.#n = !0;
+	}
+	#i() {
+		let e = this.#e, t = e.offsetParent, r = t && t.clientWidth > 0 && t.clientHeight > 0 ? t : null;
+		return {
+			width: n(r?.clientWidth ?? window.innerWidth, e),
+			height: n(r?.clientHeight ?? window.innerHeight, e)
+		};
+	}
+};
+function c(e, t, n) {
+	let r = e.top != null || e.left != null, i = getComputedStyle(e).position, a = i === "absolute" || i === "fixed", o = null;
+	if (!r && !a) o = "unplaced";
+	else {
+		let t = e.offsetParent;
+		t && t !== e.ownerDocument.body && (t.clientWidth === 0 || t.clientHeight === 0) && (o = "unsized-parent");
+	}
+	return o !== null && (console.warn(o === "unplaced" ? `${t}: movable, but in normal flow — so the first drag has to pull it out, reflowing everything after it on the page. State the origin in system px and it never was in flow: ${n}` : `${t}: the positioning parent has no box, so there is nowhere to drag to. Give it a size (and \`position: relative\`, if it is not a kit container) — the clamp is falling back to the viewport meanwhile.`), !0);
+}
+//#endregion
+export { s as PlacementController, a as VfPositioned, c as warnMovableContract };