vintage-frames 0.1.0

package/dist/components/vf-icon.js

@@ -0,0 +1,507 @@
+import { vfElement as e } from "../define.js";
+import { ScaleController as t, effectiveScale as n, toSysExact as r } from "../scale.js";
+import i from "../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { PlacementController as a, VfPositioned as o, warnMovableContract as s } from "../position.js";
+import { vfBodyDecls as c } from "../styles/recipes/body-face.js";
+import { vfBase as l } from "../styles/recipes/host.js";
+import { vfFocusUnderline as u } from "../styles/recipes/focus.js";
+import { GridSnapController as d } from "../grid-snap.js";
+import { DocumentListenersController as f } from "../document-listeners.js";
+import { DragController as p } from "../drag.js";
+import { emit as m } from "../events.js";
+import "../motion.js";
+import { FocusRuleController as h } from "../focus-modality.js";
+import { deriveOpenArt as g } from "../open-art.js";
+import { LitElement as _, css as v, html as y, nothing as b } from "lit";
+import { property as x, state as S } from "lit/decorators.js";
+//#region src/components/vf-icon.ts
+var C = {
+	large: 32,
+	small: 16
+}, w = 1, T = 8, E = (e, t) => t <= 0 ? Math.max(e, 0) : Math.min(Math.max(e, 0), t), D = class extends o(_) {
+	constructor(...e) {
+		super(...e), this.label = "", this.size = "large", this.selectable = !1, this.selected = !1, this.open = !1, this.movable = !1, this.editable = !1, this.maxlength = 31, this.scale = new t(this), this.gridSnap = new d(this), this.focusRule = new h(this), this._editing = !1, this._draft = "", this.#e = 0, this._ghost = null, this.#t = null, this.#n = this.attachInternals(), this.#i = "", this.#a = "", this.#o = 0, this.#s = -Infinity, this.#c = new f(this, () => [[
+			document,
+			"pointerdown",
+			this.#A,
+			!0
+		]]), this.#l = (e, t, n) => ({
+			x: E(e, n.width - r(this.offsetWidth, this)),
+			y: E(t, n.height - r(this.offsetHeight, this))
+		}), this.#u = new a(this, (e, t, n) => this.#l(e, t, n)), this.#d = {
+			x: 0,
+			y: 0
+		}, this.#f = new p(this, {
+			onDragStart: (e) => !this.movable || e.button !== 0 || this._editing ? null : (this.#m(), this.#d = this.#u.seed()),
+			onDrag: (e, t) => {
+				(e !== this.#d.x || t !== this.#d.y) && this.#S(), this.#u.moveTo(e, t);
+			}
+		}), this.#p = !1, this.#_ = () => {
+			this.#y(), this.#C();
+		}, this.#v = () => {
+			this.#b();
+		}, this.#O = (e) => {
+			if (e.button !== 0 || this._editing) return;
+			let t = e.composedPath().some((e) => e instanceof HTMLElement && e.classList.contains("label")), n = this.selected, r = e.timeStamp - this.#s < 800;
+			this.#s = e.timeStamp, this.#S(), this.selectable && (e.shiftKey || e.metaKey ? this.#D(!this.selected) : this.#D(!0)), this.editable && t && n && !r && !e.shiftKey && !e.metaKey && this.#x(), this.#T && (this.focus({ preventScroll: !0 }), this.focusRule.suppress()), this.#f.onPointerDown(e);
+		}, this.#k = () => {
+			this._editing || m(this, "vf-open", {});
+		}, this.#A = (e) => {
+			e.composedPath().includes(this) || (this.#S(), !(e.shiftKey || e.metaKey) && this.#D(!1));
+		}, this.#j = (e) => {
+			let t = e.target, n = e.data ?? e.dataTransfer?.getData("text") ?? "";
+			if (n === "") return;
+			let r = t.selectionStart ?? t.value.length, i = t.selectionEnd ?? r, a = t.value.slice(0, r) + n + t.value.slice(i);
+			a.length > this.maxlength && this.#N(a);
+		}, this.#M = (e) => {
+			let t = e.target;
+			if (t.value.length > this.maxlength) {
+				let e = t.value, n = Math.min(t.selectionStart ?? this.maxlength, this.maxlength);
+				t.value = e.slice(0, this.maxlength), t.setSelectionRange(n, n), this.#N(e);
+			}
+			this._draft = t.value;
+		}, this.#P = (e) => {
+			e.key === "Enter" ? (e.preventDefault(), this.commitEditing(), this.focus()) : e.key === "Escape" && (e.preventDefault(), e.stopPropagation(), this.cancelEditing(), this.focus());
+		}, this.#F = (e) => {
+			if (this.#S(), !(this._editing || e.defaultPrevented)) {
+				if ((e.metaKey || e.ctrlKey) && !e.altKey && (e.key.toLowerCase() === "o" || e.key === "ArrowDown")) {
+					e.preventDefault(), m(this, "vf-open", {});
+					return;
+				}
+				switch (e.key) {
+					case "Enter":
+						if (!this.editable) return;
+						e.preventDefault(), this.startEditing();
+						return;
+					case " ":
+						if (!this.selectable) return;
+						e.preventDefault(), this.focusRule.reveal(), this.#D(!this.selected);
+						return;
+					case "ArrowLeft":
+					case "ArrowRight":
+					case "ArrowUp":
+					case "ArrowDown": {
+						if (!this.movable) return;
+						e.preventDefault(), this.focusRule.reveal();
+						let t = e.shiftKey ? T : w, n = e.key === "ArrowLeft" ? -t : e.key === "ArrowRight" ? t : 0, r = e.key === "ArrowUp" ? -t : e.key === "ArrowDown" ? t : 0;
+						this.#m();
+						let i = this.#u.seed();
+						this.#u.moveTo(i.x + n, i.y + r);
+					}
+				}
+			}
+		};
+	}
+	static {
+		this.styles = [l, v`
+      :host {
+        display: inline-block;
+        cursor: var(--vf-cursor, default);
+        /* The reserved cell, resolved once so the art box and the no-label
+           focus rule share one definition. Not a public token: the two sizes
+           are the two icon resources, not a taste. */
+        --_cell: 32px;
+      }
+      :host([size='small']) {
+        --_cell: 16px;
+      }
+      .frame {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+      }
+      .art {
+        position: relative;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: calc(var(--vf-scale, 1) * var(--_cell));
+        height: calc(var(--vf-scale, 1) * var(--_cell));
+        /* Art larger than its cell is clipped rather than allowed to collide
+           with the plate — a wrong-size asset stays a visibly wrong asset. */
+        overflow: hidden;
+      }
+      /* The classic selected icon: the art is ink and opaque white on a
+         transparent surround, so inverting flips the two and the surround
+         stays out of it (see the class doc). The open ghost keeps exactly
+         that shape, so the same rule is the whole of selected-open too. */
+      :host([selected]) .art {
+        filter: invert(1);
+      }
+      /* The open ghost replaces the slotted art while there is one — the
+         slot stays in the tree (it is where the art loads and re-loads
+         from) but paints nothing. Gated on the class, not :host([open]):
+         art the pipeline cannot draw keeps rendering as itself rather than
+         vanishing behind a state it cannot show. */
+      .art.open slot {
+        display: none;
+      }
+      /* The derived raster displays on the terms vf-img gives the art it
+         came from: natural size in system px (the inline style it carries),
+         nearest-neighbor on whole device pixels. */
+      .ghost {
+        display: block;
+        image-rendering: pixelated;
+      }
+      /* Sized by the plate, and deliberately NOT clamped to the frame: a name
+         wider than the cell has to straddle the centre line, not start at the
+         cell's left edge and run off to the right. Clamping it left the art
+         and the name on two different axes — and since the plate is even and
+         the cell is even, the negative offset a wider caption gets from the
+         centring below is still a whole number of system px. */
+      .caption {
+        position: relative;
+        margin-top: calc(var(--vf-scale, 1) * var(--vf-icon-gap, 2px));
+      }
+      .label {
+        ${c}
+        font-weight: var(--vf-font-weight, 700);
+        /* Whole system px, never a ratio — layout contract rule 2. 12, not
+           the face's 16px em: the Finder's plate is 12 system px tall, and
+           the em centered in it lands the ink exactly where the Finder put
+           it — 3px above the ascenders, descenders on the bottom edge. The
+           half-leading is (12 − 16) / 2, so an override must keep the box's
+           parity even for the baseline to stay on a whole pixel. */
+        line-height: calc(
+          var(--vf-scale, 1) * var(--vf-icon-label-height, 12px)
+        );
+        /* One line, always. A name is never abbreviated and never wrapped: it
+           is at most 31 characters, and it overflows its cell rather than
+           folding — which is also what keeps its x whole (see the class doc). */
+        white-space: nowrap;
+        text-align: center;
+      }
+      /* Inline, not block, so the plate hugs each line separately — a wrapped
+         name reads as stacked bars of different widths, which is how System 7
+         drew it. The clone value is what repeats the 1px side padding onto
+         every fragment instead of only the first and last. */
+      /* The plate: an inline-block sized to a whole EVEN number of system px
+         (see #measurePlate). That parity is the whole alignment argument —
+         with it, both things the frame centers land on a whole pixel by
+         construction rather than by correction. */
+      .name {
+        display: inline-block;
+        /* The plate is opaque white in its own right, not the surrounding
+           surface: on the desktop dither the name reads because it sits on a
+           plate, and --vf-surface is unset out there. */
+        background: var(--vf-white, #fff);
+        color: var(--vf-black, #000);
+        /* Whole system px, and NOT centered inside the plate: the text starts
+           at the padding edge, so its own x is the plate's x plus one whole
+           pixel. Centering here would re-introduce the half pixel the even
+           width just removed, one level down. Any slack from rounding up to
+           even lands after the text, where it is a hairline of extra plate. */
+        padding: 0 calc(var(--vf-scale, 1) * 1px);
+        text-align: left;
+      }
+      :host([selected]) .name {
+        /* Forced colors: exempt the inverted plate from the mode's text
+           backplate, which would land a Canvas slab on the highlight bar —
+           see vf-list-item's forced-colors note. The pair is already the
+           user's own via the vfBase token remap. */
+        @media (forced-colors: active) {
+          forced-color-adjust: none;
+        }
+        background: var(--vf-highlight, #000);
+        color: var(--vf-highlight-text, #fff);
+      }
+      /* Editing: the plate keeps rendering the draft — still measured, still
+         even — so the box tracks the typed width the way the Finder's rename
+         box grew, while handing its pixels to the field overlaying it.
+         white-space: pre holds the spaces a name may legitimately end in,
+         which the collapsing default would drop from the measurement. */
+      .caption.editing .label {
+        visibility: hidden;
+        white-space: pre;
+      }
+      /* The rename box: a 1px border with a 1px white well inside it, boxing
+         the highlighted name rather than letting it touch the rule, the way
+         the classic rename box did. The border and well are a wrapper rather
+         than the input's own border and padding, because the selection behind
+         a highlighted name paints at the face's full 16px em and is clipped
+         only at the input's own edge — on one element the em-tall selection
+         floods the padding and lands on the border. Splitting them sizes the
+         input to the plate's line box, which clips the selection to the same
+         12px the plate stands, and keeps the well white outside it.
+         Out by the border sideways, and by border-plus-well top and bottom:
+         border + well comes to 1px in from the caption horizontally against
+         the plate's 1px padding, and 2px in vertically against the 2px it
+         was pushed out by, so the run sits exactly where the plate put it
+         and nothing shifts when the field opens. */
+      .rename-box {
+        position: absolute;
+        inset: calc(var(--vf-scale, 1) * -2px) calc(var(--vf-scale, 1) * -1px);
+        background: var(--vf-white, #fff);
+        border: calc(var(--vf-scale, 1) * 1px) solid var(--vf-black, #000);
+        padding: calc(var(--vf-scale, 1) * 1px);
+      }
+      .rename {
+        display: block;
+        width: 100%;
+        /* The plate's own line box, stated as height too: the input clips its
+           selection paint at this edge, which is the whole reason it has no
+           border of its own (see .rename-box). */
+        height: calc(var(--vf-scale, 1) * var(--vf-icon-label-height, 12px));
+        ${c}
+        font-weight: var(--vf-font-weight, 700);
+        line-height: calc(
+          var(--vf-scale, 1) * var(--vf-icon-label-height, 12px)
+        );
+        /* Hand-rolled rather than composed from vfField: that recipe sets the
+           Chicago display face, and pulling it in would ship the whole chrome
+           WOFF2 with an element that otherwise sets only body type (see the
+           note at the top of styles/base.ts). The Finder renamed in the same
+           face it labelled in, so this is the faithful reading too. */
+        background: none;
+        color: var(--vf-black, #000);
+        border: none;
+        border-radius: 0;
+        padding: 0;
+        margin: 0;
+        /* Left, matching the plate it overlays: same text x, so the name does
+           not shift by half a pixel the moment you start typing — and the
+           field's own run stays on the grid for the same reason the plate's
+           does. */
+        text-align: left;
+        user-select: text;
+        -webkit-user-select: text;
+        outline: none;
+        -webkit-appearance: none;
+        appearance: none;
+      }
+      .rename::selection {
+        background-color: var(--vf-highlight, #000);
+        color: var(--vf-highlight-text, #fff);
+      }
+      /* Keyboard focus is the kit's dashed rule below the plate, not a ring
+         around the icon (see vfFocusUnderline). Below rather than inside it:
+         every pixel of the plate is either the name or the fill inverting
+         behind it, so there is no interior to lend — the vf-select placement,
+         for the same reason. -2px puts it in the second row under a box whose
+         ink runs to its own edge. Drawn in currentColor, so it turns white
+         along with the name on a selected plate.
+         Gated on a class, not :focus-visible: the host takes focus from its own
+         pointerdown so a press-drag can own the pointer, and Blink reads that
+         as a visible focus (see focus-modality.ts). */
+      .caption.focus-rule .label::after {
+        --vf-focus-underline-offset: -2px;
+        ${u}
+      }
+      /* No name, no plate — the rule falls back to the art cell. */
+      .art.focus-rule::after {
+        --vf-focus-underline-offset: -2px;
+        ${u}
+      }
+      :host(:focus) {
+        outline: none;
+      }
+    `];
+	}
+	#e;
+	#t;
+	#n;
+	get #r() {
+		return this.closest("[role=\"listbox\"]") !== null;
+	}
+	#i;
+	#a;
+	#o;
+	#s;
+	#c;
+	#l;
+	#u;
+	#d;
+	#f;
+	connectedCallback() {
+		super.connectedCallback(), this.#E(), this.#C(), this.addEventListener("keydown", this.#F);
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback(), this.removeEventListener("keydown", this.#F), this.#S();
+	}
+	updated(e) {
+		if (e.has("selectable") && this.#E(), (e.has("selectable") || e.has("selected") || e.has("label")) && this.#C(), (e.has("selected") || e.has("selectable")) && (this.selectable && this.selected ? this.#c.attach() : this.#c.detach()), e.has("_editing") && this._editing) {
+			let e = this.renderRoot.querySelector("input");
+			e?.focus(), e?.select();
+		}
+		(e.has("label") || e.has("_draft") || e.has("_editing")) && this.#h(), (e.has("open") || e.has("size")) && this.#y();
+	}
+	#p;
+	#m() {
+		this.#p ||= s(this, `vf-icon${this.label ? ` ("${this.label}")` : ""}`, "<vf-icon movable label=\"Read Me\" width=\"64\" top=\"16\" left=\"16\">");
+	}
+	firstUpdated() {
+		document.fonts.ready.then(() => this.#h());
+	}
+	#h() {
+		let e = this.renderRoot?.querySelector(".name");
+		if (!e) {
+			this.#e = 0;
+			return;
+		}
+		let t = 0;
+		if (e.firstChild) {
+			let n = document.createRange();
+			n.selectNodeContents(e), t = n.getBoundingClientRect().width, n.detach();
+		}
+		let r = t / n(this) + 2, i = Math.max(2, Math.ceil(r / 2) * 2);
+		this.#e = this._editing && t === 0 ? Math.max(i, C[this.size]) : i, e.style.width = this.#g;
+	}
+	get #g() {
+		return this.#e ? `calc(var(--vf-scale, 1) * ${this.#e}px)` : "";
+	}
+	#_;
+	#v;
+	#y() {
+		let e = this.renderRoot?.querySelector(`slot[name='${this.size}']`), t = null;
+		for (let n of e?.assignedElements({ flatten: !0 }) ?? []) {
+			let e = n instanceof HTMLImageElement || n instanceof HTMLCanvasElement ? n : n.querySelector("img, canvas");
+			if (e instanceof HTMLImageElement || e instanceof HTMLCanvasElement) {
+				t = e;
+				break;
+			}
+		}
+		t !== this.#t && (this.#t?.removeEventListener("load", this.#v), this.#t?.removeEventListener("error", this.#v), this.#t = t, t?.addEventListener("load", this.#v), t?.addEventListener("error", this.#v)), this.#b();
+	}
+	#b() {
+		let e = this.#t, t = e instanceof HTMLImageElement ? e.complete && e.naturalWidth > 0 : e != null && e.width > 0;
+		if (!this.open || e == null || !t) {
+			this._ghost = null, this.#i = "";
+			return;
+		}
+		let n = e instanceof HTMLImageElement ? `${this.size} ${e.currentSrc}` : "";
+		if (n !== "" && n === this.#i && this._ghost) return;
+		let r = g(e);
+		if (r) {
+			r.className = "ghost", r.style.width = `calc(var(--vf-scale, 1) * ${r.width}px)`, r.style.height = `calc(var(--vf-scale, 1) * ${r.height}px)`;
+			let t = e instanceof HTMLImageElement ? e.alt : "";
+			t && (r.setAttribute("role", "img"), r.setAttribute("aria-label", t));
+		}
+		this._ghost = r, this.#i = r ? n : "";
+	}
+	#x() {
+		this.#S(), this.#o = window.setTimeout(() => {
+			this.#o = 0, this.startEditing();
+		}, 800);
+	}
+	#S() {
+		this.#o &&= (clearTimeout(this.#o), 0);
+	}
+	startEditing() {
+		this.#S(), !(!this.editable || this._editing) && (this.#a = this.label, this._draft = this.label, this._editing = !0);
+	}
+	commitEditing() {
+		if (!this._editing) return;
+		this._editing = !1;
+		let e = this.#a, t = this._draft;
+		if (t.trim() === "") {
+			this._draft = e, t !== e && m(this, "vf-name-rejected", {
+				attempted: t,
+				kept: e,
+				reason: "empty"
+			});
+			return;
+		}
+		t !== e && (this.label = t, m(this, "vf-change", {
+			label: t,
+			previous: e
+		}));
+	}
+	cancelEditing() {
+		this._editing && (this._editing = !1, this._draft = this.#a);
+	}
+	render() {
+		let e = this._editing, t = e ? this._draft : this.label, n = this.focusRule.marked && !e, r = t !== "" || e, i = `caption${e ? " editing" : ""}${n && t ? " focus-rule" : ""}`, a = `art${this.open && this._ghost ? " open" : ""}${n && !t ? " focus-rule" : ""}`, o = this.width ? `width: calc(var(--vf-scale, 1) * ${this.width}px)` : "";
+		return y`<div
+      class="frame vf-snap"
+      part="frame"
+      style=${o}
+      @pointerdown=${this.#O}
+      @pointermove=${this.#f.onPointerMove}
+      @pointerup=${this.#f.onPointerUp}
+      @pointercancel=${this.#f.onPointerUp}
+      @dblclick=${this.#k}
+    >
+      <div class=${a} part="icon">
+        ${this.size === "small" ? y`<slot name="small" @slotchange=${this.#_}></slot>` : y`<slot name="large" @slotchange=${this.#_}></slot>`}${this._ghost ?? b}
+      </div>
+      ${r ? y`<div class=${i}>
+            <!-- No whitespace around the span: it is the measured run, and a
+                 stray space would widen it. -->
+            <div class="label" part="label"><span
+              class="name"
+              part="plate"
+              style=${this.#e ? `width: ${this.#g}` : ""}
+              >${t}</span
+            ></div>
+            ${e ? y`<div class="rename-box">
+                  <input
+                    class="rename"
+                    part="input"
+                    type="text"
+                    maxlength=${this.maxlength}
+                    .value=${this._draft}
+                    @beforeinput=${this.#j}
+                    @input=${this.#M}
+                    @keydown=${this.#P}
+                    @blur=${this.commitEditing}
+                  />
+                </div>` : b}
+          </div>` : b}
+    </div>`;
+	}
+	#C() {
+		if (!this.selectable) {
+			this.#n.role = null, this.#n.ariaSelected = null, this.#n.ariaLabel = null;
+			return;
+		}
+		if (this.#r) {
+			this.#n.role = "option", this.#n.ariaSelected = this.selected ? "true" : "false", this.#n.ariaLabel = null;
+			return;
+		}
+		this.#n.role = "img", this.#n.ariaSelected = null, this.#n.ariaLabel = this.label || this.#w || null;
+	}
+	get #w() {
+		return this.#t instanceof HTMLImageElement ? this.#t.alt : "";
+	}
+	get #T() {
+		return this.selectable;
+	}
+	#E() {
+		this.hasAttribute("tabindex") || (this.#T ? this.tabIndex = 0 : this.removeAttribute("tabindex"));
+	}
+	#D(e) {
+		e !== this.selected && (this.selected = e, m(this, "vf-select", { selected: e }));
+	}
+	#O;
+	#k;
+	#A;
+	#j;
+	#M;
+	#N(e) {
+		m(this, "vf-name-too-long", {
+			attempted: e,
+			accepted: e.slice(0, this.maxlength),
+			limit: this.maxlength
+		});
+	}
+	#P;
+	#F;
+};
+i([x()], D.prototype, "label", void 0), i([x({ reflect: !0 })], D.prototype, "size", void 0), i([x({
+	type: Boolean,
+	reflect: !0
+})], D.prototype, "selectable", void 0), i([x({
+	type: Boolean,
+	reflect: !0
+})], D.prototype, "selected", void 0), i([x({
+	type: Boolean,
+	reflect: !0
+})], D.prototype, "open", void 0), i([x({
+	type: Boolean,
+	reflect: !0
+})], D.prototype, "movable", void 0), i([x({
+	type: Boolean,
+	reflect: !0
+})], D.prototype, "editable", void 0), i([x({ type: Number })], D.prototype, "width", void 0), i([x({ type: Number })], D.prototype, "maxlength", void 0), i([S()], D.prototype, "_editing", void 0), i([S()], D.prototype, "_draft", void 0), i([S()], D.prototype, "_ghost", void 0), D = i([e("vf-icon")], D);
+//#endregion
+export { D as VfIcon };

package/dist/components/vf-img.d.ts

@@ -0,0 +1,63 @@
+import { LitElement } from 'lit';
+declare const VfImg_base: (new (...args: any[]) => import("../position.js").VfPositionedInterface) & typeof LitElement;
+/**
+ * `<vf-img>` — a raster image on the kit's pixel grid.
+ *
+ * The reference art is full of small pixel graphics that are *pictures*, not
+ * glyphs: the Apple menu's logo, desk-accessory and document icons, the
+ * about-box machine portrait. This component displays one — a slotted native
+ * `<img>` — at the kit's own magnification, treating **one image pixel as one
+ * system pixel**:
+ *
+ * - the image is sized to `naturalWidth × naturalHeight` system px, multiplied
+ *   by `--vf-scale` in `calc()` like every other metric, so a source pixel
+ *   covers exactly `scale × dpr` device pixels (a whole number, per layout
+ *   contract rule 1);
+ * - `image-rendering: pixelated` keeps the resampling nearest-neighbor, and on
+ *   a whole-device-pixel box that is bit-exact magnification — no smoothing,
+ *   no half-covered edge rows;
+ * - its own {@link GridSnapController}, so the image's origin holds the device
+ *   grid wherever the page puts it (a fractional origin would slide the whole
+ *   box across device pixels and shear every source pixel's coverage).
+ *
+ * The graphic stays a real `<img>` in the consumer's light DOM — it keeps
+ * native loading, `alt` text (use `alt=""` for a decorative icon) and the
+ * consumer's own asset URLs; the kit ships no raster files. `width`/`height`
+ * (in system px, whole numbers) state the box up front so the page doesn't
+ * shift when the file lands — until a size is known the box is 0×0, never a
+ * flash of the image at some other scale. They also override the natural size
+ * deliberately: a whole multiple (`width="32"` on 16-px art) magnifies on the
+ * same grid.
+ *
+ * @slot - The image: a single `<img>` element.
+ * @csspart frame - The sized box the image fills.
+ */
+export declare class VfImg extends VfImg_base {
+    #private;
+    static styles: import("lit").CSSResult[];
+    /** Default-on display scaling (true 72dpi size); see src/scale.ts. */
+    private readonly scale;
+    /** Device-pixel grid snapping (opt in with applyGridSnap()); see src/grid-snap.ts. */
+    private readonly gridSnap;
+    /**
+     * The displayed width in system px — a whole number. Defaults to the slotted
+     * image's `naturalWidth` (one image px = one system px); state it explicitly
+     * to reserve the box before the file loads, or a whole multiple to magnify.
+     */
+    width?: number;
+    /** The displayed height in system px; see {@link width}. */
+    height?: number;
+    /** The slotted image's intrinsic size, 0 until it has one. */
+    private _naturalWidth;
+    private _naturalHeight;
+    /** True when the slotted image has settled with no natural size (a failed
+     *  load); see {@link #measure}. */
+    private _failed;
+    protected render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'vf-img': VfImg;
+    }
+}
+export {};

package/dist/components/vf-img.js

@@ -0,0 +1,65 @@
+import { vfElement as e } from "../define.js";
+import { ScaleController as t } from "../scale.js";
+import n from "../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { VfPositioned as r } from "../position.js";
+import { vfBase as i } from "../styles/recipes/host.js";
+import { GridSnapController as a } from "../grid-snap.js";
+import { LitElement as o, css as s, html as c, nothing as l } from "lit";
+import { property as u, state as d } from "lit/decorators.js";
+//#region src/components/vf-img.ts
+var f = class extends r(o) {
+	constructor(...e) {
+		super(...e), this.scale = new t(this), this.gridSnap = new a(this), this._naturalWidth = 0, this._naturalHeight = 0, this._failed = !1, this.#e = null, this.#t = (e) => {
+			let t = e.target.assignedElements({ flatten: !0 }).find((e) => e instanceof HTMLImageElement) ?? null;
+			t !== this.#e && (this.#e?.removeEventListener("load", this.#n), this.#e?.removeEventListener("error", this.#n), this.#e = t, t?.addEventListener("load", this.#n), t?.addEventListener("error", this.#n)), this.#r();
+		}, this.#n = () => {
+			this.#r();
+		};
+	}
+	static {
+		this.styles = [i, s`
+      :host {
+        display: inline-block;
+      }
+      .frame {
+        display: block;
+      }
+      ::slotted(img) {
+        display: block;
+        width: 100%;
+        height: 100%;
+        /* Nearest-neighbor: the whole point. The box is whole device px, so
+           magnification is bit-exact and no edge row is half-covered. */
+        image-rendering: pixelated;
+        /* Chrome, not content: System 7 icons don't drag out of the UI. */
+        -webkit-user-drag: none;
+      }
+      /* A failed, undeclared image (see render()): released from the stretch
+         so the browser renders it as a native broken <img> — alt text at its
+         own size — instead of scaling it into a 0×0 frame. */
+      .frame.failed ::slotted(img) {
+        width: auto;
+        height: auto;
+      }
+    `];
+	}
+	#e;
+	render() {
+		let e = this.width ?? this._naturalWidth, t = this.height ?? this._naturalHeight, n = this._failed && this.width == null && this.height == null;
+		return c`<span
+      class="frame vf-snap ${n ? "failed" : ""}"
+      part="frame"
+      style=${n ? l : `width: calc(var(--vf-scale, 1) * ${e}px); height: calc(var(--vf-scale, 1) * ${t}px)`}
+      ><slot @slotchange=${this.#t}></slot
+    ></span>`;
+	}
+	#t;
+	#n;
+	#r() {
+		let e = this.#e;
+		this._naturalWidth = e?.naturalWidth ?? 0, this._naturalHeight = e?.naturalHeight ?? 0, this._failed = e != null && e.complete && e.naturalWidth === 0 && e.src !== "";
+	}
+};
+n([u({ type: Number })], f.prototype, "width", void 0), n([u({ type: Number })], f.prototype, "height", void 0), n([d()], f.prototype, "_naturalWidth", void 0), n([d()], f.prototype, "_naturalHeight", void 0), n([d()], f.prototype, "_failed", void 0), f = n([e("vf-img")], f);
+//#endregion
+export { f as VfImg };