vintage-frames 0.1.0

package/dist/styles/recipes/title-bar.js

@@ -0,0 +1,134 @@
+import { vfDisplayDecls as e } from "./display-face.js";
+import { css as t } from "lit";
+//#region src/styles/recipes/title-bar.ts
+var n = t`
+  .vf-title-bar {
+    position: relative;
+    /* Inert unless the frame is a flex column (vf-window); on vf-dialog's plain
+       block frame the shorthand simply doesn't apply. */
+    flex: none;
+    height: calc(var(--vf-scale, 1) * var(--vf-titlebar-height, 18px));
+    border-bottom: calc(var(--vf-scale, 1) * 1px) solid var(--vf-black, #000);
+    display: flex;
+    /* flex-start, not center: the title states its own whole-pixel row (see
+       the margin below); centering 16 into 17 would land it on a half. */
+    align-items: flex-start;
+    justify-content: center;
+    overflow: hidden;
+  }
+  .vf-title {
+    /* Chicago-style title (chrome); slotted body copy keeps the body face. */
+    ${e}
+    position: relative;
+    z-index: 1;
+    left: var(--vf-title-dx, 0px);
+    /* The face's own 16px line box on interior rows 1..16: cap band lands on
+       rows 4..12 (4px white above and below the 9px caps — the trace). The
+       inherited ratio line-height would give 20px and center fractionally. */
+    line-height: calc(var(--vf-scale, 1) * var(--vf-line-height-display, 16px));
+    margin-top: calc(var(--vf-scale, 1) * 1px);
+    /* 6px + the letters' own 1px side bearing = the traced 7px of white
+       between ink and stripes. */
+    padding: 0 calc(var(--vf-scale, 1) * 6px);
+    max-width: calc(100% - var(--vf-scale, 1) * var(--vf-title-inset, 16px));
+    background: var(--vf-white, #fff);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+`, r = t`
+  .box {
+    position: absolute;
+    /* 11×11 box with 3px of clear white above and below it (title-bar
+       interior is 17px: 3 + 11 + 3). See SPEC §5 vf-window. */
+    top: calc(var(--vf-scale, 1) * 3px);
+    z-index: 1;
+    width: calc(var(--vf-scale, 1) * 11px);
+    height: calc(var(--vf-scale, 1) * 11px);
+    padding: 0;
+    margin: 0;
+    border: calc(var(--vf-scale, 1) * 1px) solid var(--vf-black, #000000);
+    background: var(--vf-white, #ffffff);
+    /* A 1px white patch ring that interrupts the stripes around the
+       box (no bevel — flat 1-bit), same buffer the stripes keep from the
+       frame edges. --vf-widget-ring is internal geometry, not a theming
+       knob: vf-window's utility variant widens it to 2px, the clearance
+       the windoid sheet cuts into its dither. */
+    box-shadow: 0 0 0 calc(var(--vf-scale, 1) * var(--vf-widget-ring, 1px))
+      var(--vf-white, #ffffff);
+    font: inherit;
+    cursor: var(--vf-cursor, default);
+    -webkit-appearance: none;
+    appearance: none;
+  }
+  .close {
+    left: calc(var(--vf-scale, 1) * 8px);
+  }
+  .zoom {
+    right: calc(var(--vf-scale, 1) * 8px);
+  }
+  /* Pressed box (close AND zoom): the interior fills with the classic
+     radiating "go-away" sunburst — black 1-bit spokes on the white face
+     (4 orthogonal 3px spokes + 4 diagonal 2px ones around an empty center),
+     traced pixel-for-pixel from the UI kit's close-button-active-state
+     sprite. Both widgets flash the identical graphic while pressed. That
+     sprite is the whole 11×11 box; its outer ring is this element's own 1px
+     border, so the SVG draws just the 9×9 interior into the padding box. */
+  .box:active {
+    background-color: var(--vf-white, #ffffff);
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='9' height='9'%3E%3Cpath d='M4 0h1v1h-1zM1 1h1v1h-1zM4 1h1v1h-1zM7 1h1v1h-1zM2 2h1v1h-1zM4 2h1v1h-1zM6 2h1v1h-1zM0 4h3v1h-3zM6 4h3v1h-3zM2 6h1v1h-1zM4 6h1v1h-1zM6 6h1v1h-1zM1 7h1v1h-1zM4 7h1v1h-1zM7 7h1v1h-1zM4 8h1v1h-1z'/%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: center;
+    background-size: calc(var(--vf-scale, 1) * 9px) calc(var(--vf-scale, 1) * 9px);
+  }
+  .zoom::after {
+    content: '';
+    position: absolute;
+    /* A small box nested in the TOP-LEFT corner of the widget (classic
+       System 7 zoom box). It shares the widget's own top and left border, so
+       only its right and bottom edges are drawn: a 6×6 box anchored at the
+       padding-box origin whose 1px right/bottom borders land the vertical at
+       sprite col 6 and the horizontal at row 6. Traced from the UI kit
+       zoom-button rest sprite. */
+    top: 0;
+    left: 0;
+    width: calc(var(--vf-scale, 1) * 6px);
+    height: calc(var(--vf-scale, 1) * 6px);
+    border-right: calc(var(--vf-scale, 1) * 1px) solid var(--vf-black, #000000);
+    border-bottom: calc(var(--vf-scale, 1) * 1px) solid var(--vf-black, #000000);
+  }
+  /* While pressed the zoom box shows the same sunburst as the close box, so
+     its inner detail square gives way to it. */
+  .zoom:active::after {
+    display: none;
+  }
+  /* Forced colors: everything the widget draws is already token-routed —
+     Canvas face, CanvasText border — but its white patch ring is a
+     box-shadow, which forced colors never paints, leaving the box pressed
+     against the (rescued — see vfStripes) stripes. forced-color-adjust: none
+     turns the widget's own paint back on; with the tokens remapped it still
+     renders entirely in the user's pair. The one literal left is the pressed
+     sunburst tile (url() images are preserved with their black ink), so that
+     repaints as a mask over the ink token — into the padding box, where the
+     sprite's 9×9 interior already draws. */
+  @media (forced-colors: active) {
+    .box {
+      forced-color-adjust: none;
+    }
+    .box:active {
+      background-image: none;
+    }
+    .box:active::before {
+      content: '';
+      position: absolute;
+      inset: 0;
+      background: var(--vf-black, #000000);
+      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='9' height='9'%3E%3Cpath d='M4 0h1v1h-1zM1 1h1v1h-1zM4 1h1v1h-1zM7 1h1v1h-1zM2 2h1v1h-1zM4 2h1v1h-1zM6 2h1v1h-1zM0 4h3v1h-3zM6 4h3v1h-3zM2 6h1v1h-1zM4 6h1v1h-1zM6 6h1v1h-1zM1 7h1v1h-1zM4 7h1v1h-1zM7 7h1v1h-1zM4 8h1v1h-1z'/%3E%3C/svg%3E");
+      mask-repeat: no-repeat;
+      mask-position: center;
+      mask-size: calc(var(--vf-scale, 1) * 9px) calc(var(--vf-scale, 1) * 9px);
+    }
+  }
+`;
+//#endregion
+export { n as vfTitleBar, r as vfWindowWidgets };

package/dist/styles/recipes/toggle.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared layout for the two toggle controls (vf-checkbox, vf-radio): the
+ * box-and-label row, the host focus suppressed (each control draws
+ * {@link vfFocusUnderline} under its own well instead), and the classic "dim
+ * the label, not the control" disabled treatment. The Chicago display face
+ * comes from {@link vfDisplay} (both controls compose it), so no font is set
+ * here. Each component adds only its own well (`.box`/`.circle`), glyphs,
+ * press feedback and focus rule.
+ */
+export declare const vfToggle: import("lit").CSSResult;

package/dist/styles/recipes/toggle.js

@@ -0,0 +1,20 @@
+import { css as e } from "lit";
+//#region src/styles/recipes/toggle.ts
+var t = e`
+  :host {
+    display: inline-flex;
+    align-items: center;
+    gap: calc(var(--vf-scale, 1) * 6px);
+    cursor: var(--vf-cursor, default);
+  }
+  /* The focus rule is drawn under the box/circle, not around the host. */
+  :host(:focus-visible) {
+    outline: none;
+  }
+  /* Disabled dims the label only; the box/circle glyphs stay solid black. */
+  .label.dim {
+    color: var(--vf-disabled, #c0c0c0);
+  }
+`;
+//#endregion
+export { t as vfToggle };

package/dist/styles/register-embedded-font.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Register an embedded bitmap webfont on the document.
+ *
+ * WHY THIS IS JS AND NOT AN `@font-face` RULE: font faces declared inside a
+ * component's shadow root are ignored by the browser — `@font-face` resolves
+ * only against the document. Every `vf-*` element renders into its own shadow
+ * root, so a stylesheet `@font-face` would never take effect. Registering the
+ * face imperatively on `document.fonts` makes it visible inside *every* shadow
+ * root at once, which preserves the library's "components need no global CSS"
+ * promise.
+ *
+ * Each face is inlined as a base64 WOFF2 data URL by its wrapper module (e.g.
+ * `display-font.ts`), so there is no separate asset to ship or to resolve
+ * through a consumer's bundler; the font is available the moment the wrapper is
+ * imported, with no network round trip.
+ */
+/**
+ * Vertical-metric overrides for a registered face, applied via the CSS
+ * `ascent-override`/`descent-override`/`line-gap-override` descriptors.
+ * Percentages of the em (`'75%'`), same as the CSS properties.
+ */
+export interface EmbeddedFontMetrics {
+    ascentOverride?: string;
+    descentOverride?: string;
+    lineGapOverride?: string;
+}
+/**
+ * The em box both embedded bitmap faces are drawn on: a 16-design-pixel grid
+ * split 12 px above the baseline and 4 px below (the classic Chicago-12
+ * ascent/descent), no line gap.
+ *
+ * WHY OVERRIDE AT ALL: browsers place a line box's baseline from the face's
+ * hhea metrics, and the retired converter-artifact faces (ChiKareGo and
+ * FindersKeepers, both since replaced by the kit's re-drawn strikes) carried hhea
+ * values — ascender 682, descender 192, line gap 92 of the 1024 upm, i.e.
+ * 10.66 px / 3 px / 1.44 px at 16px — that are NOT on the 64-unit
+ * design-pixel grid the glyphs are drawn on. Half-leading computed from them
+ * lands the baseline ~0.5px high in every whole-pixel line box, and
+ * rasterization snaps that to a whole device pixel: all chrome/body text sat
+ * one device px above its System 7 position (first seen as fractional gaps in
+ * the vf-select pill). Today both shipped strikes' own tables carry the
+ * grid-clean em (768/256/0 = 12/4/0 px — fonts/manifest-to-font.py writes
+ * them); the overrides restate it so every face the kit registers is pinned
+ * the same way regardless of provenance or which table a platform prefers.
+ *
+ * KNOWN LIMIT (dpr 2, scale 1.5): Chrome snaps aliased text baselines to whole
+ * ABSOLUTE CSS px. A pill's ideal baseline sits 13 system px (19.5 CSS px at
+ * scale 1.5) below its border-box top, so a host at a whole CSS-px position
+ * puts it on a half pixel and the snap misses by 1 device px (⅓ system px) —
+ * no metric value can reach it; only a host at a half-CSS-px position (still
+ * on the device grid) renders it exactly. dpr 1 and 3 land exactly at whole
+ * CSS-px positions, the common case.
+ */
+export declare const PIXEL_GRID_METRICS: EmbeddedFontMetrics;
+/**
+ * Register `family` from an inlined base64 WOFF2 exactly once per session.
+ *
+ * Idempotent and environment-safe: it no-ops under SSR (no `document`), when
+ * the CSS Font Loading API is unavailable, or when the family is already
+ * present (duplicate bundles / HMR). A failed decode releases the family so a
+ * later explicit call can retry, and on any failure components simply keep the
+ * fallback stack — so this can never break rendering.
+ */
+export declare function registerEmbeddedFont(family: string, woff2Base64: string, metrics?: EmbeddedFontMetrics): void;

package/dist/styles/register-embedded-font.js

@@ -0,0 +1,30 @@
+//#region src/styles/register-embedded-font.ts
+var e = /* @__PURE__ */ new Set(), t = {
+	ascentOverride: "75%",
+	descentOverride: "25%",
+	lineGapOverride: "0%"
+};
+function n(t, n, r) {
+	if (e.has(t) || typeof document > "u" || !("fonts" in document)) return;
+	for (let n of document.fonts) if (n.family === t) {
+		e.add(t);
+		return;
+	}
+	e.add(t);
+	let i = `url(data:font/woff2;base64,${n}) format('woff2')`;
+	try {
+		let n = new FontFace(t, i, {
+			style: "normal",
+			weight: "100 900",
+			display: "swap",
+			...r
+		});
+		document.fonts.add(n), n.load().then(() => {}, () => {
+			document.fonts.delete(n), e.delete(t);
+		});
+	} catch {
+		e.delete(t);
+	}
+}
+//#endregion
+export { t as PIXEL_GRID_METRICS, n as registerEmbeddedFont };

package/dist/text-control.d.ts

@@ -0,0 +1,131 @@
+import { nothing } from 'lit';
+import type { PropertyValues } from 'lit';
+import { ScaleController } from './scale.js';
+import { GridSnapController } from './grid-snap.js';
+import { VfShadowRoleControl } from './form-control.js';
+import { FocusRuleController } from './focus-modality.js';
+/**
+ * Shared base for the kit's editable text fields — `vf-text-field`,
+ * `vf-text-area` and `vf-number-field`. Builds on
+ * {@link VfShadowRoleControl} (form association, the disabled-value guard and
+ * the name/description bridge every field needs, its role sitting on the inner
+ * native control) and adds the value/label scaffolding
+ * every field repeated: the reflected `name`, the `value`/`placeholder`/
+ * `readonly`/`label` props, the captured default restored on form reset, the
+ * `updated()` → {@link VfShadowRoleControl.syncFormValue} funnel, and the display-
+ * scaling controller. Pairs with the `vfField` css fragment (the white-well
+ * skin) in styles/base.ts.
+ *
+ * Subclasses render their own native control (`<input>`/`<textarea>` plus any
+ * adornments), tag it `class="vf-field"`, and may enrich the emitted event
+ * detail via {@link emitValue}.
+ */
+export declare class VfTextControlBase extends VfShadowRoleControl {
+    /** Focus delegates into the inner native control. */
+    static shadowRootOptions: ShadowRootInit;
+    /** Current value. Synced on every keystroke and submitted with forms. */
+    value: string;
+    /** Placeholder text shown when the field is empty. */
+    placeholder: string;
+    /** Makes the field read-only (focusable, not editable). */
+    readonly: boolean;
+    /** Form field name used when submitting the associated form. */
+    name: string;
+    /**
+     * Accessible name, applied as `aria-label` on the inner native control (the
+     * element that receives focus and is announced by screen readers — a host
+     * attribute cannot reach it on its own). Left empty, the name falls back to
+     * whatever the host carries — `aria-labelledby`, `aria-label` or an
+     * associated `<label for>` — via {@link VfShadowRoleControl.hostLabel}, so the
+     * platform's own labeling vocabulary works on these controls too.
+     */
+    label: string;
+    /** A field is empty for `required`'s purposes when its value is `''`. */
+    protected get valueMissing(): boolean;
+    /**
+     * Host attributes forwarded verbatim onto the inner native control — the
+     * input-behavior vocabulary the platform only honors on the element that
+     * actually takes the input. `<vf-text-field autocomplete="email">` used to
+     * put the token on a custom element the browser ignores for autofill while
+     * the shadow `<input>` never received it; same story for the mobile-keyboard
+     * pair (`inputmode`, `enterkeyhint`) and the rest. These are deliberately
+     * *not* reactive properties: four of them are global attributes with IDL
+     * accessors already on `HTMLElement` (`spellcheck`, `autocapitalize`,
+     * `inputMode`, `enterKeyHint`), and a Lit `@property` would shadow the
+     * platform member — the kit's own `align`/`draggable` trap. Instead the
+     * attributes are observed (see `observedAttributes`) and read at render
+     * time via {@link forwardedAttr}. Subclasses may extend the list
+     * (`vf-text-field` adds `pattern`) or override a default in their template
+     * (`vf-number-field` keeps `inputmode="decimal"` unless told otherwise).
+     */
+    protected static readonly forwardedAttributes: readonly string[];
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /**
+     * The forwarded value of a host attribute for the inner control's template
+     * binding, or `nothing` (remove the attribute) while the host doesn't
+     * carry it.
+     */
+    protected forwardedAttr(name: string): string | typeof nothing;
+    /** Default-on display scaling (true 72dpi size); see src/scale.ts. */
+    protected readonly scale: ScaleController;
+    /** Device-pixel grid snapping (opt in with applyGridSnap()); see src/grid-snap.ts. */
+    protected readonly gridSnap: GridSnapController;
+    /**
+     * Whether the well wears the kit's dashed focus rule — keyboard focus only.
+     * See {@link FocusRuleController} for why a field cannot get this from
+     * `:focus-visible` the way most of the kit does. Typing does NOT reveal the
+     * rule after a click: the click already showed where the insertion point
+     * went, which is the whole reason a field marks keyboard focus and not every
+     * focus, so the field never calls the controller's `reveal()`.
+     */
+    protected readonly focusRule: FocusRuleController;
+    /**
+     * Classes for the `.vf-field-well` wrapper every field renders around its
+     * native control: the shared skin hook (`vfField`), the grid-snap target, and
+     * the focus rule's own gate. Assembled here so the three fields state the
+     * wrapper once and can't drift on what turns the rule on.
+     */
+    protected get wellClass(): string;
+    connectedCallback(): void;
+    /**
+     * Re-submit the value only when it (or the disabled state gating it) actually
+     * changed. Unrelated re-renders would otherwise re-run this — `vf-number-field`
+     * re-renders on every stepper press and release for its `pressed` state alone.
+     * On the first update `value` is in `changed` (class-field defaults are, with
+     * `undefined` as the old value), so the initial form value is still set.
+     */
+    protected updated(changed: PropertyValues<this>): void;
+    /** Restores the initial value when the associated form resets. */
+    formResetCallback(): void;
+    /**
+     * True for a plain Enter press (no modifiers, not IME-composing) — the key
+     * that triggers a form's implicit submission. The native control is
+     * shadow-encapsulated (null form owner), so single-line fields call
+     * `internals.form?.requestSubmit()` themselves; this centralises the guard.
+     */
+    protected isSubmitEnter(event: KeyboardEvent): boolean;
+    /**
+     * Emulates the form's implicit submission for a plain Enter press. HTML
+     * defines it as *activating the form's default button* — the first submit
+     * button in tree order — so the submission carries that button's submitter
+     * identity and name/value. A bare `requestSubmit()` carries neither
+     * (`event.submitter === null`), which made Enter and a click on the same
+     * form produce different payloads. `click()` is the activation: a native
+     * button becomes the real submitter, and a `vf-button` forwards it to its
+     * inner button, which runs the same transient-proxy path a pointer does. A
+     * 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.
+     */
+    protected requestImplicitSubmit(): void;
+    /**
+     * Dispatch a bubbling, composed value event (SPEC §4). Text fields use the
+     * default `{ value }` detail; `vf-number-field` passes an enriched detail that
+     * also carries `valueAsNumber`.
+     */
+    protected emitValue(type: 'vf-input' | 'vf-change', detail?: Record<string, unknown>): void;
+    /** Mirror the native control's value into `value` and announce a keystroke. */
+    protected handleInput(event: Event): void;
+    /** Mirror the native control's value into `value` and announce a commit. */
+    protected handleChange(event: Event): void;
+}

package/dist/text-control.js

@@ -0,0 +1,83 @@
+import { ScaleController as e } from "./scale.js";
+import t from "./_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { GridSnapController as n } from "./grid-snap.js";
+import { emit as r, emitNative as i } from "./events.js";
+import { VfShadowRoleControl as a } from "./form-control.js";
+import { FocusRuleController as o } from "./focus-modality.js";
+import { nothing as s } from "lit";
+import { property as c } from "lit/decorators.js";
+//#region src/text-control.ts
+var l = class extends a {
+	constructor(...t) {
+		super(...t), this.value = "", this.placeholder = "", this.readonly = !1, this.name = "", this.label = "", this.scale = new e(this), this.gridSnap = new n(this), this.focusRule = new o(this);
+	}
+	static {
+		this.shadowRootOptions = {
+			...a.shadowRootOptions,
+			delegatesFocus: !0
+		};
+	}
+	get valueMissing() {
+		return this.value === "";
+	}
+	static {
+		this.forwardedAttributes = [
+			"autocomplete",
+			"inputmode",
+			"enterkeyhint",
+			"maxlength",
+			"spellcheck",
+			"autocapitalize"
+		];
+	}
+	static get observedAttributes() {
+		return [...super.observedAttributes, ...this.forwardedAttributes];
+	}
+	attributeChangedCallback(e, t, n) {
+		super.attributeChangedCallback(e, t, n), this.constructor.forwardedAttributes.includes(e) && this.requestUpdate();
+	}
+	forwardedAttr(e) {
+		return this.getAttribute(e) ?? s;
+	}
+	get wellClass() {
+		return `vf-field-well vf-snap${this.focusRule.marked ? " vf-focus-rule" : ""}`;
+	}
+	connectedCallback() {
+		super.connectedCallback(), this.latchFormDefault(this.value);
+	}
+	updated(e) {
+		(e.has("value") || this.disabledChanged(e)) && this.syncFormValue(this.value);
+	}
+	formResetCallback() {
+		this.value = this.formDefault("");
+	}
+	isSubmitEnter(e) {
+		return e.key === "Enter" && !e.isComposing && !e.shiftKey && !e.ctrlKey && !e.metaKey && !e.altKey;
+	}
+	requestImplicitSubmit() {
+		let e = this.internals.form;
+		if (!e) return;
+		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.type?.toLowerCase() === "submit");
+		if (t) {
+			if (t.matches(":disabled")) return;
+			t.click();
+			return;
+		}
+		e.requestSubmit();
+	}
+	emitValue(e, t = { value: this.value }) {
+		r(this, e, t);
+	}
+	handleInput(e) {
+		this.value = e.target.value, this.emitValue("vf-input");
+	}
+	handleChange(e) {
+		this.value = e.target.value, this.emitValue("vf-change"), i(this, "change");
+	}
+};
+t([c()], l.prototype, "value", void 0), t([c()], l.prototype, "placeholder", void 0), t([c({
+	type: Boolean,
+	reflect: !0
+})], l.prototype, "readonly", void 0), t([c({ reflect: !0 })], l.prototype, "name", void 0), t([c()], l.prototype, "label", void 0);
+//#endregion
+export { l as VfTextControlBase };

package/dist/tile-grid.d.ts

@@ -0,0 +1,111 @@
+import { type CSSResult, type TemplateResult } from 'lit';
+import { type TileRect } from './styles/recipes/tile.js';
+/**
+ * The tiled-fill machinery that replaces CSS `background-repeat` on the kit's
+ * convertible tiled surfaces (the desktop dither, the windoid dots, the swatch
+ * checker, the barber stripes).
+ *
+ * A CSS repeating fill is ONE paint-snapped box holding N *unsnapped* repeats,
+ * each placed at `k × tileSize` where the tile size is a single stored length
+ * the engine quantizes to its layout grid (Chromium 1/64 CSS px, Gecko 1/60).
+ * The error compounds linearly with `k` until a motif boundary has walked a
+ * whole device pixel and the 1-bit art smears to gray. The span construction
+ * (`tileSpan`, src/styles/recipes/tile.ts) makes the stored length exact for
+ * every scale the *density* ladder derives — but zoom mints scales with
+ * arbitrary prime denominators (20/17 at Safari's 85%, 30/23 at its 115%),
+ * and no finite lattice can hold those. ZOOM-TILE-DRIFT.md is the analysis;
+ * TILE-GRID-PLAN.md the plan this module implements.
+ *
+ * Two rendering paths, chosen by whether the surface's pattern token is
+ * overridden ({@link patternOverride}):
+ *
+ * **Kit art (token unset): one whole-surface raster** — a single `.vf-tile-raster`
+ * element carrying the motif tiled over the surface's declared system-px size
+ * as a raster image at one image px per system px (`tileRaster`), stretched
+ * `background-size: 100% 100%` under `image-rendering: pixelated`. Exact at
+ * every scale, holdable or not, for two measured reasons: nearest-neighbor
+ * sampling can only produce source colors, and ONE box has no interior
+ * boundaries — Chromium paints an image background to the box's *unsnapped*
+ * layout rect with antialiased edges, so any fill assembled from several
+ * boxes blends a one-device-px line at every interior seam at a zoom-minted
+ * scale, no matter how exactly the boxes were placed. (That measurement is
+ * what buried both this plan's original per-tile form and SVG art of any
+ * kind: Chromium rasterizes SVG images at the fractional layout size and
+ * ignores `image-rendering` for them.) The box's own edge is the one place a
+ * partial device pixel remains — the same status every component box already
+ * has. The sampling stays exact because the box's stored length errs at most
+ * 1/128 CSS px over the WHOLE surface: the relative error shrinks as the
+ * surface grows, so the nearest-neighbor grid cannot slip a pixel at any
+ * realistic size.
+ *
+ * **Consumer art (token set): the placed tile grid** — a flat set of
+ * absolutely positioned `.vf-tile` boxes, each `T × T` system px at
+ * `left: calc(var(--vf-scale, 1) * kT px)`: one single-multiplication length
+ * per tile, quantized once, so each box paint-snaps onto the device grid
+ * independently and the documented tile geometry (`--vf-*-pattern` art on a
+ * 30- or 60-system-px tile) renders verbatim. Positions never accumulate
+ * error; at a zoom-minted scale what remains is the bounded per-seam blend
+ * above — a hairline per tile boundary, never surface-wide smear. Raster
+ * consumer art additionally magnifies nearest-neighbor (the `vf-img` idiom).
+ *
+ * The trap that must not come back: NEVER lay tiles out with CSS grid,
+ * flexbox, inline-block flow, or nested row containers. Track and flow
+ * layouts accumulate quantized box sizes — the position of column `k` becomes
+ * a *sum* of `k` quantized lengths, error `k/64` CSS px, and the disease
+ * returns. Flat absolute placement with one multiplication per tile is the
+ * correctness, not a style choice.
+ *
+ * Wiring: the *container* — the layer the fill used to paint on, or a
+ * dedicated child filling it — takes the `vf-tile-grid` class (clip and
+ * pointer transparency; it must be positioned, which every kit layer already
+ * is). For the grid path it resolves `--_vf-tile-image` — the pattern-token
+ * `var()` each tile stretches over its box, stated once so no data URI is
+ * repeated per tile — and {@link tileGrid} renders the tiles. For the raster
+ * path the component renders a `.vf-tile-raster` child whose
+ * `background-image` it writes from `tileRaster(...)`, regenerated only when
+ * the declared system-px size changes (density and zoom re-render nothing:
+ * the box lengths are live against `--vf-scale`).
+ *
+ * Forced colors keeps each surface's existing layer-level branches (flat
+ * Canvas desktop, span-masked dots and barber, the swatch's
+ * forced-color-adjust) — no mask pipeline rasterizes exactly at a zoom-minted
+ * scale (image-rendering does not reach masks), so forced-colors-plus-zoom
+ * remains the one accepted residual, unchanged from before this work.
+ */
+export declare const vfTileGrid: CSSResult;
+/**
+ * The flat set of tiles covering `cols × rows` boxes of `tile` system px each,
+ * to render inside a `vf-tile-grid` container — the consumer-pattern path.
+ * Each tile carries its own single-multiplication `calc()` position and size,
+ * live against `--vf-scale` — so a density or zoom change re-renders nothing,
+ * and the count changes only when the caller's *declared system-px size*
+ * does. Compute `cols`/`rows` from that declared size with `Math.ceil`; the
+ * clipped last row and column are absorbed by the container's clip.
+ */
+export declare function tileGrid({ cols, rows, tile, }: {
+    cols: number;
+    rows: number;
+    tile: number;
+}): TemplateResult[];
+/**
+ * The consumer's override of a pattern token, or `''` when the token is unset
+ * and the surface should paint its own art — how a converted surface picks
+ * between its whole-surface raster (kit art) and its placed tile grid
+ * (consumer art at the documented tile geometry).
+ *
+ * Read with `getComputedStyle` at update time, not observed live: a pattern
+ * token swapped at runtime without touching the component wants a nudge (any
+ * property write, or `requestUpdate()`) — the same re-check-on-update
+ * contract the component's other measured inputs follow.
+ */
+export declare function patternOverride(el: Element, token: string): string;
+/**
+ * A one-entry cache for a surface's whole-surface raster, keyed by its
+ * system-px size — so every render with an unchanged size (all of them except
+ * a declared-size change) reuses the encoded image instead of re-running
+ * `tileRaster`'s canvas encode.
+ */
+export declare class TileRasterCache {
+    #private;
+    for(motifWidth: number, motifHeight: number, rects: readonly TileRect[], width: number, height: number): string;
+}

package/dist/tile-grid.js

@@ -0,0 +1,53 @@
+import { sysLength as e } from "./scale.js";
+import { tileRaster as t } from "./styles/recipes/tile.js";
+import { css as n, html as r } from "lit";
+//#region src/tile-grid.ts
+var i = n`
+  .vf-tile-grid {
+    /* Clip the overdraw: a fill overdrawn past a box that is not a whole
+       number of tiles (or a raster ceiled up to one) crops here. */
+    overflow: hidden;
+    pointer-events: none;
+  }
+  .vf-tile,
+  .vf-tile-raster {
+    position: absolute;
+    /* The box IS the size — never the image's intrinsic size, and never an
+       intra-box repeat: a consumer tile smaller than its box repeating
+       inside it would re-import the accumulation this module removes. */
+    background-size: 100% 100%;
+    background-repeat: no-repeat;
+    /* Raster art samples nearest-neighbor — the exactness mechanism for the
+       kit's own tiles and the vf-img idiom for consumer raster art. A no-op
+       for SVG (which is why kit art is raster; see tileRaster). */
+    image-rendering: pixelated;
+  }
+  .vf-tile {
+    background-image: var(--_vf-tile-image);
+  }
+  .vf-tile-raster {
+    top: 0;
+    left: 0;
+  }
+`;
+function a({ cols: t, rows: n, tile: i }) {
+	let a = e(i), o = [];
+	for (let s = 0; s < n; s++) for (let n = 0; n < t; n++) o.push(r`<span
+          class="vf-tile"
+          style="left:${e(n * i)};top:${e(s * i)};width:${a};height:${a}"
+        ></span>`);
+	return o;
+}
+function o(e, t) {
+	return typeof getComputedStyle > "u" ? "" : getComputedStyle(e).getPropertyValue(t).trim();
+}
+var s = class {
+	#e = "";
+	#t = "";
+	for(e, n, r, i, a) {
+		let o = `${i}x${a}`;
+		return this.#e !== o && (this.#e = o, this.#t = t(e, n, r, i, a)), this.#t;
+	}
+};
+//#endregion
+export { s as TileRasterCache, o as patternOverride, a as tileGrid, i as vfTileGrid };