vintage-frames 0.3.0 → 0.5.0

package/custom-elements.json

@@ -1974,7 +1974,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vf-container>` — a box that is nothing but its declared size.\n\nThe kit's positioned-placement story (src/position.ts) ends with one line of\nCSS it can't write for you: children placed with `top`/`left` need a\npositioned ancestor, and while every kit container is one — a window body, a\nstack, a fieldset — a region of *your own* needs `position: relative` in a\nstylesheet. This component is that region as an element: declare `width` and\n`height` in whole system px, slot anything into it, place children against\nits origin. A DITL's enclosing rectangle, with nothing drawn in it.\n\n```html\n<vf-container width=\"200\" height=\"120\">\n  <vf-icon label=\"System\" width=\"64\" top=\"8\" left=\"12\">…</vf-icon>\n  <vf-icon label=\"Finder\" width=\"64\" top=\"8\" left=\"104\">…</vf-icon>\n</vf-container>\n```\n\nThe rectangle is the whole API — `width`/`height` here, plus the `top`/`left`\npair nearly every component takes (VfPositioned), so a container is\nitself placeable: inside a window, a desktop, or another container, at whole\nsystem px that keep its box on the device-pixel grid by construction.\n\n**It is not a `vf-stack`.** The stack is a flexbox with opinions — it\ndistributes children along an axis, compiles `fill-width`/`fill-height` into\nflex, defaults a cross-axis alignment. This box has no layout opinion at\nall: in-flow children get normal flow, placed children get a coordinate\nsystem, and that is the whole API. Reach for it when the stack's opinions\nare the thing in the way — a field of placed icons, a fixed stage for\nabsolutely-positioned art, a consumer's own composition that brings its\nlayout with it.\n\n**The declared size is the layout.** `width`/`height` land on the host as a\nlive `calc(var(--vf-scale, 1) * Npx)` (VfSized), so the box scales\nwith the display and sits on the device-pixel grid by construction. Content\nthat outgrows the box overflows it rather than growing it — the number is\nthe layout, and content that doesn't fit is a number to raise. Leave a\ndimension off and that axis shrink-wraps: `fit-content`, not the parent's\nwidth, because a layout box that silently claimed a size nobody declared\nwould be inventing one (the `vf-stack` rule, held here too).\n\n**It paints nothing and means nothing.** No border, background, role,\nkeyboard behavior or selection — what it holds decides what it is.\n\n**It holds its box on the device-pixel grid** — with a `GridSnapController`.\nA container's box is itself the consumer's coordinate system, including for\nnon-`vf` content that cannot correct itself, so the box is the thing to\nhold on the grid. The shadow box below owns the `position: relative` anchor\nand the `vf-snap` class together, so the correction\nmoves the whole coordinate system — everything placed against it rides\nalong instead of being re-corrected child by child. (`vf-stack` shipped\nwithout a controller on the theory that slotted `vf-*` children correct\ntheir own origins; this component is where that theory's gap — consumer\ncontent — became visible, and the stack has since adopted the same\narrangement.)\n\nLike the stack it is **typographically transparent**: `vfBase`'s chrome\ndress is returned to `inherit` on the host, so wrapping content in a sized\nbox changes nothing about how that content reads.\n\n`fill-width` / `fill-height` work here the way they do everywhere: read\nabout the host (be as big as *its* parent allows), and compiled for slotted\nchildren — `width: 100%` in normal flow, so a child filling the cross of a\ndeclared box needs no stylesheet. A height fill needs a declared `height`\nto resolve against; with none it is inert, not an error.",
+          "description": "`<vf-container>` — a box that is nothing but its declared size.\n\nThe kit's positioned-placement story (src/position.ts) ends with one line of\nCSS it can't write for you: children placed with `top`/`left` need a\npositioned ancestor, and while every kit container is one — a window body, a\nstack, a fieldset — a region of *your own* needs `position: relative` in a\nstylesheet. This component is that region as an element: declare `width` and\n`height` in whole system px, slot anything into it, place children against\nits origin. A DITL's enclosing rectangle, with nothing drawn in it.\n\n```html\n<vf-container width=\"200\" height=\"120\">\n  <vf-icon label=\"System\" width=\"64\" top=\"8\" left=\"12\">…</vf-icon>\n  <vf-icon label=\"Finder\" width=\"64\" top=\"8\" left=\"104\">…</vf-icon>\n</vf-container>\n```\n\nThe rectangle is the whole API — `width`/`height` here, plus the `top`/`left`\npair nearly every component takes (VfPositioned), so a container is\nitself placeable: inside a window, a desktop, or another container, at whole\nsystem px that keep its box on the device-pixel grid by construction.\n\n**It is not a `vf-stack`.** The stack is a flexbox with opinions — it\ndistributes children along an axis, compiles `fill-width`/`fill-height` into\nflex, defaults a cross-axis alignment. This box has no layout opinion at\nall: in-flow children get normal flow, placed children get a coordinate\nsystem, and that is the whole API. Reach for it when the stack's opinions\nare the thing in the way — a field of placed icons, a fixed stage for\nabsolutely-positioned art, a consumer's own composition that brings its\nlayout with it.\n\n**The declared size is the layout.** `width`/`height` land on the host as a\nlive `calc(var(--vf-scale, 1) * Npx)` (VfSized), so the box scales\nwith the display and sits on the device-pixel grid by construction. Content\nthat outgrows the box overflows it rather than growing it — the number is\nthe layout, and content that doesn't fit is a number to raise. Leave a\ndimension off and that axis shrink-wraps: `fit-content`, not the parent's\nwidth, because a layout box that silently claimed a size nobody declared\nwould be inventing one (the `vf-stack` rule, held here too).\n\n**It paints nothing and means nothing** — unless `pattern` says what to\npaint. No border, role, keyboard behavior or selection; what it holds\ndecides what it is.\n\n**`pattern` fills the box with a 1-bit pattern**: one of the 38 standard\nMacPaint patterns by name (`pattern=\"bricks\"`, `pattern=\"gray-50\"` —\ndocs/PATTERNS.md has the table), or sixteen hex digits stating a custom\n8×8 pattern row by row, the way a PAT resource did. It is painted as the\nbox's own background — black ink on a `--vf-white` ground, anchored at\nthe box's top-left corner, under the content — by the same whole-surface\nraster mechanism as the desktop dither, so it is 1-bit at every density\nand zoom (src/pattern-fill.ts). A declared `width`/`height` sizes the\nraster exactly; an undeclared axis (`fill-width`, a shrink-wrapped\nheight) is measured. Under forced colors the pattern goes flat Canvas.\n\n**It holds its box on the device-pixel grid** — with a `GridSnapController`.\nA container's box is itself the consumer's coordinate system, including for\nnon-`vf` content that cannot correct itself, so the box is the thing to\nhold on the grid. The shadow box below owns the `position: relative` anchor\nand the `vf-snap` class together, so the correction\nmoves the whole coordinate system — everything placed against it rides\nalong instead of being re-corrected child by child. (`vf-stack` shipped\nwithout a controller on the theory that slotted `vf-*` children correct\ntheir own origins; this component is where that theory's gap — consumer\ncontent — became visible, and the stack has since adopted the same\narrangement.)\n\nLike the stack it is **typographically transparent**: `vfBase`'s chrome\ndress is returned to `inherit` on the host, so wrapping content in a sized\nbox changes nothing about how that content reads.\n\n`fill-width` / `fill-height` work here the way they do everywhere: read\nabout the host (be as big as *its* parent allows), and compiled for slotted\nchildren — `width: 100%` in normal flow, so a child filling the cross of a\ndeclared box needs no stylesheet. A height fill needs a declared `height`\nto resolve against; with none it is inert, not an error.",
           "name": "VfContainer",
           "slots": [
             {
@@ -1983,6 +1983,45 @@
             }
           ],
           "members": [
+            {
+              "kind": "field",
+              "name": "pattern",
+              "type": {
+                "text": "string | null | undefined"
+              },
+              "description": "A 1-bit fill for the box: a library pattern by name (`bricks`,\n`gray-50`, … — the 38 standard MacPaint patterns, docs/PATTERNS.md) or\nsixteen hex digits stating a custom 8×8 pattern row by row, bit 7 the\nleftmost pixel, 1 = ink (`\"DD 77 DD 77 DD 77 DD 77\"`). Painted in black\non a `--vf-white` ground under the content, anchored at the box's\ntop-left. Unset, the container paints nothing; an unrecognized value\npaints nothing and warns once.",
+              "attribute": "pattern"
+            },
+            {
+              "kind": "field",
+              "name": "_pattern",
+              "type": {
+                "text": "Pattern | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "`pattern`, resolved — what the fill paints; null paints nothing."
+            },
+            {
+              "kind": "field",
+              "name": "#warnedPattern",
+              "privacy": "private",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "One warning per element for an unrecognized `pattern`, not per render."
+            },
+            {
+              "kind": "field",
+              "name": "box",
+              "type": {
+                "text": "HTMLDivElement"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "The shadow box the fill paints on; exists from the first render."
+            },
             {
               "kind": "field",
               "name": "scale",
@@ -1999,6 +2038,14 @@
               "default": "new GridSnapController(this)",
               "description": "Hold the box on the device-pixel grid — see the\nclass doc. The host is what gets measured; `.box` (vf-snap) is where the\ncorrection lands."
             },
+            {
+              "kind": "field",
+              "name": "patternFill",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new PatternFillController(this, { getBox: () => this.box, getPattern: () => this._pattern, getSize: () => ({ width: this.width, height: this.height }), })",
+              "description": "The pattern fill, painted on `.box` so it rides the snap correction with\nthe coordinate system. A declared axis sizes the raster exactly; an\nundeclared one is measured (src/pattern-fill.ts)."
+            },
             {
               "kind": "field",
               "name": "width",
@@ -2052,23 +2099,15 @@
               }
             }
           ],
-          "mixins": [
+          "attributes": [
             {
-              "name": "VfSized",
-              "module": "/src/size.js"
+              "name": "pattern",
+              "type": {
+                "text": "string | null | undefined"
+              },
+              "description": "A 1-bit fill for the box: a library pattern by name (`bricks`,\n`gray-50`, … — the 38 standard MacPaint patterns, docs/PATTERNS.md) or\nsixteen hex digits stating a custom 8×8 pattern row by row, bit 7 the\nleftmost pixel, 1 = ink (`\"DD 77 DD 77 DD 77 DD 77\"`). Painted in black\non a `--vf-white` ground under the content, anchored at the box's\ntop-left. Unset, the container paints nothing; an unrecognized value\npaints nothing and warns once.",
+              "fieldName": "pattern"
             },
-            {
-              "name": "VfPositioned",
-              "module": "/src/position.js"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "vf-container",
-          "customElement": true,
-          "attributes": [
             {
               "name": "width",
               "type": {
@@ -2117,7 +2156,23 @@
                 "module": "src/position.ts"
               }
             }
-          ]
+          ],
+          "mixins": [
+            {
+              "name": "VfSized",
+              "module": "/src/size.js"
+            },
+            {
+              "name": "VfPositioned",
+              "module": "/src/position.js"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "vf-container",
+          "customElement": true
         }
       ],
       "exports": [
@@ -2145,22 +2200,22 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vf-desktop>` — the full-bleed classic desktop container.\n\nRenders the 50%-dither gray desktop pattern and manages the stacking order\nand `active` state of slotted `vf-window` children: a `pointerdown` or\n`focusin` (keyboard focus) anywhere inside a window brings it to the front\nand makes it the single active window. The windows' light-DOM order is kept\nin step with the stacking order (bottom-most first, at pointer-gesture\nends), so tabbing walks the stack the way the eye does and Shift+Tab is\nits exact mirror.\n\nUtility windows (`vf-window[variant=\"utility\"]`) stack in a floating tier\nabove every document-tier window, restack only among themselves, and stand\noutside the single-active invariant entirely — clicking a palette neither\ndeactivates the active document window nor greys the palette, exactly as\nSystem 7's floating windoids behaved while their application was frontmost.\n\nThe desktop is a raster with an explicit size, always: **`width` and\n`height`**, in system px, the way a WIND resource declared a window's —\nthe host box renders at the declared screen plus `2 × bezel` per axis, a\nwhole number of system pixels by construction (default 512×342, the\ncompact Mac's screen). Pure CSS sizing is not supported; the page sets\nthe numbers — directly, or via VfDesktop.fitWithin on\n`resize`/`onScaleChange` for a viewport-filling desktop — and positions\nthe sized box with its own stylesheet, keeping any sub-system-pixel\nslack on its side. `bezel` (system px) draws the black screen surround —\nthe CRT's unlit margin — around the screen, rounding its top corners\nwith the classic corner mask.\n\nCustom properties:\n- `--vf-desktop-pattern` — the dither's tile art (default a 1-bit 50%\n  checker, opaque black-on-white on a 30-system-px tile). Overriding it\n  renders the token as a placed tile grid at that same 30-px geometry\n  (src/tile-grid.ts); a token swapped at runtime without touching the\n  component wants a `requestUpdate()`.\n- `--vf-desktop` — base color painted *under* the pattern layer (default\n  `#808080`). The default tile is opaque, so this only becomes visible when\n  `--vf-desktop-pattern` is overridden with a tile that has transparent\n  cells (or with `none`).",
+          "description": "`<vf-desktop>` — the full-bleed classic desktop container.\n\nRenders the desktop pattern — the classic 50% dither by default, or any of\nthe standard patterns by name (`pattern`, System 7's General Controls\nsetting) — and manages the stacking order and `active` state of slotted\n`vf-window` children: a `pointerdown` or\n`focusin` (keyboard focus) anywhere inside a window brings it to the front\nand makes it the single active window. The windows' light-DOM order is kept\nin step with the stacking order (bottom-most first, at pointer-gesture\nends), so tabbing walks the stack the way the eye does and Shift+Tab is\nits exact mirror.\n\nUtility windows (`vf-window[variant=\"utility\"]`) stack in a floating tier\nabove every document-tier window, restack only among themselves, and stand\noutside the single-active invariant entirely — clicking a palette neither\ndeactivates the active document window nor greys the palette, exactly as\nSystem 7's floating windoids behaved while their application was frontmost.\n\n**Deactivation.** On a real System 7 machine clicking the desktop clicked\nthe *Finder* — the frontmost application's windows lost their stripes.\nclearActive is that gesture's handler: it clears `active` from\nthe whole document tier, and **zero active windows is a legal state**,\nheld until a press or keyboard focus re-enters a document window (or a\nnew one is slotted, which activates it — opening a window brings its\napplication forward). The desktop never takes this decision itself: its\nfurniture is slotted light DOM (an icon layer, say), so only the page\nknows which of its children — or which presses on the bare dither — mean\n\"the Finder\", and it routes those through `clearActive()`. Left alone,\nthe classic always-one-active behavior is unchanged. activeWindow\nreads the current holder, and every change of holder — including to and\nfrom none — fires `vf-activate`.\n\nThe desktop is a raster with an explicit size, always: **`width` and\n`height`**, in system px, the way a WIND resource declared a window's —\nthe host box renders at the declared screen plus `2 × bezel` per axis, a\nwhole number of system pixels by construction (default 512×342, the\ncompact Mac's screen). Pure CSS sizing is not supported; the page sets\nthe numbers — directly, or via VfDesktop.fitWithin on\n`resize`/`onScaleChange` for a viewport-filling desktop — and positions\nthe sized box with its own stylesheet, keeping any sub-system-pixel\nslack on its side. `bezel` (system px) draws the black screen surround —\nthe CRT's unlit margin — around the screen, rounding its top corners\nwith the classic corner mask.\n\n**`pattern`** names the desktop pattern — `gray-50` (the dither) by\ndefault, any of the 38 standard patterns (docs/PATTERNS.md), or sixteen\nhex digits stating a custom 8×8 pattern, as on `vf-container`. It is\npainted as the screen's own background: black ink on an opaque white\npaper, one whole-surface raster at one image px per system px, 1-bit at\nevery density and zoom (src/pattern-fill.ts).\n\nCustom properties:\n- `--vf-desktop-pattern` — a consumer's own tile art in place of the\n  pattern (the kit's default is a 1-bit 50% checker, opaque\n  black-on-white on a 30-system-px tile). Set, it wins over `pattern` and\n  renders as a placed tile grid at that same 30-px geometry\n  (src/tile-grid.ts); a token swapped at runtime without touching the\n  component wants a `requestUpdate()`.\n- `--vf-desktop` — base color painted *under* the pattern (default\n  `#808080`). The pattern's paper is opaque, so this only becomes visible\n  when `--vf-desktop-pattern` is overridden with a tile that has\n  transparent cells (or with `none`).",
           "name": "VfDesktop",
           "cssProperties": [
             {
-              "description": "base color under the desktop dither — occluded by the default (opaque) tile, so it only shows through a custom `--vf-desktop-pattern`",
+              "description": "base color under the desktop pattern — occluded by the pattern's opaque paper, so it only shows through a custom `--vf-desktop-pattern`",
               "name": "--vf-desktop",
               "default": "#808080"
             },
             {
-              "description": "the desktop dither's art — a 50% checker drawn as opaque black-on-white rects, on a 30-system-px tile. Override the whole tile; consumer art renders as a placed tile grid at that same geometry (raster art magnifies nearest-neighbor, the `vf-img` idiom)",
+              "description": "a consumer's own desktop tile, in place of `pattern` — the kit's default is the 50% checker drawn as opaque black-on-white rects on a 30-system-px tile. Override the whole tile; consumer art renders as a placed tile grid at that same geometry (raster art magnifies nearest-neighbor, the `vf-img` idiom)",
               "name": "--vf-desktop-pattern"
             }
           ],
           "cssParts": [
             {
-              "description": "The dithered screen surface — the whole-system-px raster (inset by `bezel` when one is set).",
+              "description": "The patterned screen surface — the whole-system-px raster (inset by `bezel` when one is set).",
               "name": "desktop"
             }
           ],
@@ -2201,6 +2256,16 @@
               "description": "Width of the black screen bezel, in system px (`0` = none), added onto\nthe declared screen on every side — a `width=\"502\" bezel=\"5\"` desktop\nrenders a 512-system-px host box. The compact Mac's CRT showed an\nunlit black margin between the desktop's raster and the case; `bezel`\ndraws it around the screen and puts the classic screen-corner mask on\nthe screen's two *top* corners — only the top pair was rounded in the\nframebuffer. Flow, window coordinates and the drag clip all belong to\nthe screen, so windows crop at its edge. Inside a bezeled desktop a\nmenu bar needs no `rounded` of its own — the desktop's mask lands on\nthe same pixels.",
               "attribute": "bezel"
             },
+            {
+              "kind": "field",
+              "name": "pattern",
+              "type": {
+                "text": "string | null | undefined"
+              },
+              "default": "'gray-50'",
+              "description": "The desktop pattern — System 7's General Controls setting. A library\npattern by name (`gray-50`, the classic dither, by default; `gray-75`,\n`bricks`, … — docs/PATTERNS.md) or sixteen hex digits stating a custom\n8×8 pattern, as on `vf-container`. Painted black on opaque white over\nthe whole screen, 1-bit at every density and zoom. A\n`--vf-desktop-pattern` token override still wins and renders the\nconsumer's tile as a placed grid; an unrecognized value warns once and\nkeeps the dither.",
+              "attribute": "pattern"
+            },
             {
               "kind": "method",
               "name": "fitWithin",
@@ -2252,21 +2317,51 @@
             },
             {
               "kind": "field",
-              "name": "_pattern",
+              "name": "_token",
               "type": {
                 "text": "string"
               },
               "privacy": "private",
               "default": "''",
-              "description": "The consumer's `--vf-desktop-pattern` override, or `''` for the kit\ndither — which of the two exact-fill paths render() takes (see\nsrc/tile-grid.ts). Re-read every update; a token swapped at runtime\nwithout touching the component wants a `requestUpdate()`."
+              "description": "The consumer's `--vf-desktop-pattern` override, or `''` for the kit\npattern — which of the two exact-fill paths render() takes (see\nsrc/tile-grid.ts). Re-read every update; a token swapped at runtime\nwithout touching the component wants a `requestUpdate()`."
             },
             {
               "kind": "field",
-              "name": "#raster",
+              "name": "_desktopPattern",
+              "type": {
+                "text": "Pattern"
+              },
+              "privacy": "private",
+              "default": "PATTERNS[DEFAULT_PATTERN]",
+              "description": "`pattern`, resolved — the kit path's art; the dither when unset."
+            },
+            {
+              "kind": "field",
+              "name": "#warnedPattern",
+              "privacy": "private",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "One warning per element for an unrecognized `pattern`, not per render."
+            },
+            {
+              "kind": "field",
+              "name": "screen",
+              "type": {
+                "text": "HTMLDivElement"
+              },
               "privacy": "private",
               "readonly": true,
-              "default": "new TileRasterCache()",
-              "description": "The whole-surface dither raster, cached against its ceiled size."
+              "description": "The screen surface the pattern paints on; exists from the first render."
+            },
+            {
+              "kind": "field",
+              "name": "patternFill",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new PatternFillController(this, { getBox: () => this.screen, getPattern: () => (this._token ? null : this._desktopPattern), getSize: () => ({ width: this.width ?? DEFAULT_SCREEN_WIDTH, height: this.height ?? DEFAULT_SCREEN_HEIGHT, }), })",
+              "description": "The desktop pattern, painted as the screen's own background\n(src/pattern-fill.ts) from the declared raster — scale-independent, so\ndensity and zoom re-encode nothing — and silent while a consumer token\nowns the fill."
             },
             {
               "kind": "field",
@@ -2278,6 +2373,26 @@
               "default": "0",
               "description": "Monotonic z-index counter for window stacking."
             },
+            {
+              "kind": "field",
+              "name": "_activeWindow",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "The active document-tier window, or null when the tier is deactivated\n(or empty). The single change-tracked truth behind activeWindow\nand the `vf-activate` event — written only by _setActive."
+            },
+            {
+              "kind": "field",
+              "name": "_deactivated",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the document tier was *deliberately* deactivated (a\nclearActive call) — as opposed to `_activeWindow` being null\nbecause nothing has activated yet. Slot changes preserve a deliberate\ndeactivation instead of promoting a survivor; a newly slotted document\nwindow still activates (opening a window brings its application forward)."
+            },
             {
               "kind": "field",
               "name": "_awaitingUpgrade",
@@ -2353,6 +2468,25 @@
               ],
               "description": "Bring a slotted window to the front of its tier. A document-tier window\nalso becomes the single active window (clearing `active` on the other\ndocument windows); a utility window restacks within the floating tier\nand leaves every `active` state alone.\n\nThe light-DOM order of the slotted windows follows (_syncDomOrder):\nvisual stacking and sequential focus order come from independent channels\n(z-index vs DOM position), and letting them drift apart is how a desktop\ntabs front-to-back one way and back-to-front the other, with widgets\nreachable only travelling backwards. Deferred to the end of any in-flight\npointer gesture — moving a node clears the pointer capture a title-bar\ndrag or grow-box resize holds on it, and a background window must stay\ndraggable in the same gesture that raises it."
             },
+            {
+              "kind": "field",
+              "name": "activeWindow",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "description": "The active document-tier window, or null while the tier is deactivated\n(or has no windows). Utility windows are never the holder.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "clearActive",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Deactivate the whole document tier — clear `active` from every document\nwindow, leaving none the holder. Pages route \"the user clicked the\nFinder\" presses — on the bare dither, on their own desktop furniture\n(an icon layer) — through here; the deactivated state holds until a\ndocument window is pressed, focused, brought to front, or newly\nslotted."
+            },
             {
               "kind": "method",
               "name": "_restack",
@@ -2474,11 +2608,11 @@
                 {
                   "name": "win",
                   "type": {
-                    "text": "HTMLElement"
+                    "text": "HTMLElement | null"
                   }
                 }
               ],
-              "description": "Set `active` on `win` only, clearing it on every other *document-tier*\nwindow. Utility windows stand outside the invariant: a palette keeps\nwhatever `active` state it has (true by default, so its dither and\nwidgets stay drawn while document windows trade the highlight)."
+              "description": "Set `active` on `win` only, clearing it on every other *document-tier*\nwindow (`null` clears the whole tier — the deactivated state). Utility\nwindows stand outside the invariant: a palette keeps whatever `active`\nstate it has (true by default, so its dither and widgets stay drawn\nwhile document windows trade the highlight). The one write site of\n_activeWindow, so `vf-activate` fires exactly on a change of\nholder — re-asserting the current holder is silent."
             },
             {
               "kind": "method",
@@ -2573,6 +2707,12 @@
               }
             }
           ],
+          "events": [
+            {
+              "description": "The active document-tier window changed. Detail `{ window: HTMLElement | null }` — the new holder, or `null` when the document tier deactivated (a {@link clearActive} call, or the active window leaving the DOM with none behind it). Fired once per change of holder, never for a re-assertion of the same one.",
+              "name": "vf-activate"
+            }
+          ],
           "attributes": [
             {
               "name": "width",
@@ -2595,6 +2735,15 @@
               "description": "Width of the black screen bezel, in system px (`0` = none), added onto\nthe declared screen on every side — a `width=\"502\" bezel=\"5\"` desktop\nrenders a 512-system-px host box. The compact Mac's CRT showed an\nunlit black margin between the desktop's raster and the case; `bezel`\ndraws it around the screen and puts the classic screen-corner mask on\nthe screen's two *top* corners — only the top pair was rounded in the\nframebuffer. Flow, window coordinates and the drag clip all belong to\nthe screen, so windows crop at its edge. Inside a bezeled desktop a\nmenu bar needs no `rounded` of its own — the desktop's mask lands on\nthe same pixels.",
               "fieldName": "bezel"
             },
+            {
+              "name": "pattern",
+              "type": {
+                "text": "string | null | undefined"
+              },
+              "default": "DEFAULT_PATTERN",
+              "description": "The desktop pattern — System 7's General Controls setting. A library\npattern by name (`gray-50`, the classic dither, by default; `gray-75`,\n`bricks`, … — docs/PATTERNS.md) or sixteen hex digits stating a custom\n8×8 pattern, as on `vf-container`. Painted black on opaque white over\nthe whole screen, 1-bit at every density and zoom. A\n`--vf-desktop-pattern` token override still wins and renders the\nconsumer's tile as a placed grid; an unrecognized value warns once and\nkeeps the dither.",
+              "fieldName": "pattern"
+            },
             {
               "name": "top",
               "type": {
@@ -2659,7 +2808,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vf-dialog>` — the System 7 modal dialog shell.\n\nTwo chromes, one modal lifecycle (native `<dialog>` for top-layer rendering\nand focus trapping, with a fully transparent backdrop — no dimming):\n\n- **Default:** a striped title bar with a centered title over a white body —\n  the movable-modal look. Drag the title bar to move it. `closable` adds the\n  standard close box (left of the bar) — the HIG's own figures disagree on\n  whether a movable modal carries one (Figure 5-1 says yes, Figure 6-1 and\n  the Chapter 6 text say no), so the component enables either reading rather\n  than enforcing one.\n- **`frame=\"plain\"`:** the classic dBoxProc modal-dialog frame — 1px outer\n  border, 2px gap, 2px inner band, no shadow, no title bar — and immovable,\n  like the original. A `heading` renders as a centered display-face heading\n  at the top of the body (the reference art's \"Dialog title\"); `closable` is\n  ignored, there being no bar to carry the widget.\n\nOpen it with `show()` (or set the `open` attribute/property); close with\n`close()`. Escape closes it and fires `vf-close` with\n`{ reason: 'escape' }`; the close box and programmatic closing fire\n`{ reason: 'close' }`.",
+          "description": "`<vf-dialog>` — the System 7 modal dialog shell.\n\nTwo chromes, one modal lifecycle (native `<dialog>` for top-layer rendering\nand focus trapping, with a fully transparent backdrop — no dimming). Both\nare the same dBoxProc double frame — 1px outer rule, 2px gap, 2px inner\nband, no shadow (vfModalFrame):\n\n- **Default:** the movable modal (movableDBoxProc) — the striped title bar\n  set into the top of that frame, with a centered title over a white body.\n  Drag the title bar to move it. `closable` adds the standard close box\n  (left of the bar) — the HIG's own figures disagree on whether a movable\n  modal carries one (Figure 5-1 says yes, Figure 6-1 and the Chapter 6 text\n  say no), so the component enables either reading rather than enforcing\n  one.\n- **`frame=\"plain\"`:** the modal dialog box — the bare frame, no title bar —\n  and immovable, like the original. A `heading` renders as a centered\n  display-face heading at the top of the body (the reference art's \"Dialog\n  title\"); `closable` is ignored, there being no bar to carry the widget.\n\nOpen it with `show()` (or set the `open` attribute/property); close with\n`close()`. Escape closes it and fires `vf-close` with\n`{ reason: 'escape' }`; the close box and programmatic closing fire\n`{ reason: 'close' }`.",
           "name": "VfDialog",
           "cssProperties": [
             {
@@ -2681,7 +2830,7 @@
           ],
           "cssParts": [
             {
-              "description": "The outer chrome frame (striped-bar or plain).",
+              "description": "The outer frame (the double frame's 1px rule; the bar and the inner band sit inside it).",
               "name": "frame"
             },
             {
@@ -2777,7 +2926,7 @@
               "type": {
                 "text": "'plain' | undefined"
               },
-              "description": "Frame chrome. Omit for the striped title bar (movable modal); `'plain'`\nfor the immovable dBoxProc double frame with no bar (modal dialog box).",
+              "description": "Frame chrome. Omit for the movable modal (the double frame with the\nstriped title bar set into it); `'plain'` for the immovable modal dialog\nbox (the bare double frame, no bar).",
               "attribute": "frame",
               "reflects": true
             },
@@ -3332,7 +3481,7 @@
               "type": {
                 "text": "'plain' | undefined"
               },
-              "description": "Frame chrome. Omit for the striped title bar (movable modal); `'plain'`\nfor the immovable dBoxProc double frame with no bar (modal dialog box).",
+              "description": "Frame chrome. Omit for the movable modal (the double frame with the\nstriped title bar set into it); `'plain'` for the immovable modal dialog\nbox (the bare double frame, no bar).",
               "fieldName": "frame"
             },
             {

package/dist/components/vf-button.js

@@ -1,21 +1,21 @@
-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 { vfDisplay as i } from "../styles/recipes/display-face.js";
-import { vfBase as a } from "../styles/recipes/host.js";
-import { vfFocusUnderline as o } from "../styles/recipes/focus.js";
-import { GridSnapController as s } from "../grid-snap.js";
-import { BUTTON_FACE as c, BUTTON_FRAME as l, RING_FRAME as u, RING_HOLE as d, steppedRectClip as f, steppedRingClip as p } from "../pixel-frame.js";
-import { deferActivation as m } from "../events.js";
+import { deferActivation as e } from "../events.js";
+import { vfElement as t } from "../define.js";
+import { ScaleController as n } from "../scale.js";
+import r from "../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { VfPositioned as i } from "../position.js";
+import { vfDisplay as a } from "../styles/recipes/display-face.js";
+import { vfBase as o } from "../styles/recipes/host.js";
+import { vfFocusUnderline as s } from "../styles/recipes/focus.js";
+import { GridSnapController as c } from "../grid-snap.js";
+import { BUTTON_FACE as l, BUTTON_FRAME as u, RING_FRAME as d, RING_HOLE as f, steppedRectClip as p, steppedRingClip as m } from "../pixel-frame.js";
 import { VfShadowRoleControl as h } from "../form-control.js";
 import { css as g, html as _, nothing as v, unsafeCSS as y } from "lit";
 import { property as b, query as x } from "lit/decorators.js";
 //#region src/components/vf-button.ts
-var S = "vf-submitter", C = class extends r(h) {
-	constructor(...e) {
-		super(...e), this.type = "button", this.name = "", this.value = "", this.formAction = "", this.formEnctype = "", this.formMethod = "", this.formNoValidate = !1, this.formTarget = "", this.scale = new t(this), this.gridSnap = new s(this), this.#e = !1, this.handleClick = (e) => {
-			this.isDisabled || this.#e || this.resolvedType !== "button" && m(this, e, () => this.activate());
+var S = "vf-submitter", C = class extends i(h) {
+	constructor(...t) {
+		super(...t), this.type = "button", this.name = "", this.value = "", this.formAction = "", this.formEnctype = "", this.formMethod = "", this.formNoValidate = !1, this.formTarget = "", this.scale = new n(this), this.gridSnap = new c(this), this.#e = !1, this.handleClick = (t) => {
+			this.isDisabled || this.#e || this.resolvedType !== "button" && e(this, t, () => this.activate());
 		};
 	}
 	static {
@@ -26,8 +26,8 @@ var S = "vf-submitter", C = class extends r(h) {
 	}
 	static {
 		this.styles = [
+			o,
 			a,
-			i,
 			g`
       :host {
         display: inline-flex;
@@ -61,7 +61,7 @@ var S = "vf-submitter", C = class extends r(h) {
         bottom: calc(var(--vf-scale, 1) * -${4}px - var(--vf-snap-dy, 0px));
         right: calc(var(--vf-scale, 1) * -${4}px - var(--vf-snap-dx, 0px));
         background: var(--vf-black, #000);
-        clip-path: ${y(p(u, d))};
+        clip-path: ${y(m(d, f))};
         pointer-events: none;
       }
       /* Disabled default: the fat outer ring dims to gray; the inner button
@@ -131,12 +131,12 @@ var S = "vf-submitter", C = class extends r(h) {
       }
       button::before {
         background: var(--vf-black, #000);
-        clip-path: ${y(f(l))};
+        clip-path: ${y(p(u))};
       }
       /* Face: white fill inset one pixel, with its own traced corner steps. */
       button::after {
         background: var(--vf-white, #fff);
-        clip-path: ${y(f(c))};
+        clip-path: ${y(p(l))};
       }
       /* Pressed: instant white-on-black inversion. */
       button:active:not(:disabled) {
@@ -167,7 +167,7 @@ var S = "vf-submitter", C = class extends r(h) {
         outline: none;
       }
       button:focus-visible .label::after {
-        ${o}
+        ${s}
       }
       /* Disabled: only the label dims to gray; the solid black border stays. */
       button:disabled {
@@ -213,22 +213,22 @@ var S = "vf-submitter", C = class extends r(h) {
 		}
 	}
 };
-n([b({ reflect: !0 })], C.prototype, "variant", void 0), n([b({ reflect: !0 })], C.prototype, "type", void 0), n([b({ reflect: !0 })], C.prototype, "name", void 0), n([b({ reflect: !0 })], C.prototype, "value", void 0), n([b({
+r([b({ reflect: !0 })], C.prototype, "variant", void 0), r([b({ reflect: !0 })], C.prototype, "type", void 0), r([b({ reflect: !0 })], C.prototype, "name", void 0), r([b({ reflect: !0 })], C.prototype, "value", void 0), r([b({
 	attribute: "formaction",
 	reflect: !0
-})], C.prototype, "formAction", void 0), n([b({
+})], C.prototype, "formAction", void 0), r([b({
 	attribute: "formenctype",
 	reflect: !0
-})], C.prototype, "formEnctype", void 0), n([b({
+})], C.prototype, "formEnctype", void 0), r([b({
 	attribute: "formmethod",
 	reflect: !0
-})], C.prototype, "formMethod", void 0), n([b({
+})], C.prototype, "formMethod", void 0), r([b({
 	type: Boolean,
 	attribute: "formnovalidate",
 	reflect: !0
-})], C.prototype, "formNoValidate", void 0), n([b({
+})], C.prototype, "formNoValidate", void 0), r([b({
 	attribute: "formtarget",
 	reflect: !0
-})], C.prototype, "formTarget", void 0), n([x("button")], C.prototype, "buttonEl", void 0), C = n([e("vf-button")], C);
+})], C.prototype, "formTarget", void 0), r([x("button")], C.prototype, "buttonEl", void 0), C = r([t("vf-button")], C);
 //#endregion
 export { C as VfButton };

package/dist/components/vf-checkbox.js

@@ -1,11 +1,11 @@
-import { vfElement as e } from "../define.js";
-import t from "../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
-import { VfPositioned as n } from "../position.js";
-import { vfDisplay as r } from "../styles/recipes/display-face.js";
-import { vfBase as i } from "../styles/recipes/host.js";
-import { vfFocusUnderline as a } from "../styles/recipes/focus.js";
-import { vfToggle as o } from "../styles/recipes/toggle.js";
-import { emit as s, emitNative as c } from "../events.js";
+import { emit as e, emitNative as t } from "../events.js";
+import { vfElement as n } from "../define.js";
+import r from "../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { VfPositioned as i } from "../position.js";
+import { vfDisplay as a } from "../styles/recipes/display-face.js";
+import { vfBase as o } from "../styles/recipes/host.js";
+import { vfFocusUnderline as s } from "../styles/recipes/focus.js";
+import { vfToggle as c } from "../styles/recipes/toggle.js";
 import { CHECKBOX_X as l, glyphSvg as u } from "../glyphs.js";
 import { VfFormControl as d } from "../form-control.js";
 import { VfToggleControl as f } from "../toggle-control.js";
@@ -13,12 +13,12 @@ import { css as p, html as m } from "lit";
 import { property as h, state as g } from "lit/decorators.js";
 import { classMap as _ } from "lit/directives/class-map.js";
 //#region src/components/vf-checkbox.ts
-var v = class extends n(f(d)) {
+var v = class extends i(f(d)) {
 	static {
 		this.styles = [
-			i,
-			r,
 			o,
+			a,
+			c,
 			p`
       /* Keyboard focus underlines the box itself — not the label, and not a
          ring around either (see vfFocusUnderline). Both adjustments below are
@@ -28,7 +28,7 @@ var v = class extends n(f(d)) {
          blank row and the rule itself: −(1 + 1 + 1). */
       :host(:focus-visible) .box::after {
         --vf-focus-underline-offset: -3px;
-        ${a}
+        ${s}
         left: calc(var(--vf-scale, 1) * -1px);
         right: calc(var(--vf-scale, 1) * -1px);
       }
@@ -132,12 +132,12 @@ var v = class extends n(f(d)) {
 		this.checked = !0;
 	}
 	activate() {
-		this.checked = !this.checked, this.focus(), s(this, "vf-change", { checked: this.checked }), c(this, "input"), c(this, "change");
+		this.checked = !this.checked, this.focus(), e(this, "vf-change", { checked: this.checked }), t(this, "input"), t(this, "change");
 	}
 };
-t([h({
+r([h({
 	type: Boolean,
 	reflect: !0
-})], v.prototype, "checked", void 0), t([h({ reflect: !0 })], v.prototype, "name", void 0), t([h()], v.prototype, "value", void 0), t([g()], v.prototype, "_hasLabel", void 0), v = t([e("vf-checkbox")], v);
+})], v.prototype, "checked", void 0), r([h({ reflect: !0 })], v.prototype, "name", void 0), r([h()], v.prototype, "value", void 0), r([g()], v.prototype, "_hasLabel", void 0), v = r([n("vf-checkbox")], v);
 //#endregion
 export { v as VfCheckbox };

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

@@ -1,4 +1,4 @@
-import { LitElement } from 'lit';
+import { LitElement, type PropertyValues } from 'lit';
 declare const VfContainer_base: (new (...args: any[]) => import("../size.js").VfSizedInterface) & (new (...args: any[]) => import("../position.js").VfPositionedInterface) & typeof LitElement;
 /**
  * `<vf-container>` — a box that is nothing but its declared size.
@@ -41,8 +41,20 @@ declare const VfContainer_base: (new (...args: any[]) => import("../size.js").Vf
  * width, because a layout box that silently claimed a size nobody declared
  * would be inventing one (the `vf-stack` rule, held here too).
  *
- * **It paints nothing and means nothing.** No border, background, role,
- * keyboard behavior or selection — what it holds decides what it is.
+ * **It paints nothing and means nothing** — unless `pattern` says what to
+ * paint. No border, role, keyboard behavior or selection; what it holds
+ * decides what it is.
+ *
+ * **`pattern` fills the box with a 1-bit pattern**: one of the 38 standard
+ * MacPaint patterns by name (`pattern="bricks"`, `pattern="gray-50"` —
+ * docs/PATTERNS.md has the table), or sixteen hex digits stating a custom
+ * 8×8 pattern row by row, the way a PAT resource did. It is painted as the
+ * box's own background — black ink on a `--vf-white` ground, anchored at
+ * the box's top-left corner, under the content — by the same whole-surface
+ * raster mechanism as the desktop dither, so it is 1-bit at every density
+ * and zoom (src/pattern-fill.ts). A declared `width`/`height` sizes the
+ * raster exactly; an undeclared axis (`fill-width`, a shrink-wrapped
+ * height) is measured. Under forced colors the pattern goes flat Canvas.
  *
  * **It holds its box on the device-pixel grid** — with a `GridSnapController`.
  * A container's box is itself the consumer's coordinate system, including for
@@ -71,7 +83,22 @@ declare const VfContainer_base: (new (...args: any[]) => import("../size.js").Vf
  *   fills it to the declared box.
  */
 export declare class VfContainer extends VfContainer_base {
+    #private;
     static styles: import("lit").CSSResult[];
+    /**
+     * A 1-bit fill for the box: a library pattern by name (`bricks`,
+     * `gray-50`, … — the 38 standard MacPaint patterns, docs/PATTERNS.md) or
+     * sixteen hex digits stating a custom 8×8 pattern row by row, bit 7 the
+     * leftmost pixel, 1 = ink (`"DD 77 DD 77 DD 77 DD 77"`). Painted in black
+     * on a `--vf-white` ground under the content, anchored at the box's
+     * top-left. Unset, the container paints nothing; an unrecognized value
+     * paints nothing and warns once.
+     */
+    pattern?: string | null;
+    /** `pattern`, resolved — what the fill paints; null paints nothing. */
+    private _pattern;
+    /** The shadow box the fill paints on; exists from the first render. */
+    private readonly box;
     /**
      * Default-on display scaling (true 72dpi size); see src/scale.ts. Without
      * one, a lone container on a plain page would resolve its declared size
@@ -85,6 +112,13 @@ export declare class VfContainer extends VfContainer_base {
      * correction lands.
      */
     private readonly gridSnap;
+    /**
+     * The pattern fill, painted on `.box` so it rides the snap correction with
+     * the coordinate system. A declared axis sizes the raster exactly; an
+     * undeclared one is measured (src/pattern-fill.ts).
+     */
+    private readonly patternFill;
+    protected willUpdate(changed: PropertyValues<this>): void;
     protected render(): import("lit-html").TemplateResult<1>;
 }
 declare global {