vintage-frames 0.4.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\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\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",
@@ -2640,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": {
@@ -2704,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": [
             {
@@ -2726,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"
             },
             {
@@ -2822,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
             },
@@ -3377,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-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 {

package/dist/components/vf-container.js

@@ -3,16 +3,29 @@ 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 { VfSized as o } from "../size.js";
-import { LitElement as s, css as c, html as l } from "lit";
+import { parsePattern as a } from "../patterns.js";
+import { PatternFillController as o, vfPatternFill as s } from "../pattern-fill.js";
+import { GridSnapController as c } from "../grid-snap.js";
+import { VfSized as l } from "../size.js";
+import { LitElement as u, css as d, html as f } from "lit";
+import { property as p, query as m } from "lit/decorators.js";
 //#region src/components/vf-container.ts
-var u = class extends o(r(s)) {
+var h = class extends l(r(u)) {
 	constructor(...e) {
-		super(...e), this.scale = new t(this), this.gridSnap = new a(this);
+		super(...e), this._pattern = null, this.#e = !1, this.scale = new t(this), this.gridSnap = new c(this), this.patternFill = new o(this, {
+			getBox: () => this.box,
+			getPattern: () => this._pattern,
+			getSize: () => ({
+				width: this.width,
+				height: this.height
+			})
+		});
 	}
 	static {
-		this.styles = [i, c`
+		this.styles = [
+			i,
+			s,
+			d`
       :host {
         display: block;
         /* Shrink-wrap an undeclared axis rather than claim the parent's
@@ -75,12 +88,21 @@ var u = class extends o(r(s)) {
       ::slotted([fill-height]) {
         height: 100%;
       }
-    `];
+    `
+		];
+	}
+	#e;
+	willUpdate(e) {
+		super.willUpdate(e), e.has("pattern") && (this._pattern = a(this.pattern), this._pattern === null && this.pattern?.trim() && !this.#e && (this.#e = !0, console.warn(`vf-container: unknown pattern "${this.pattern}" — a library name (docs/PATTERNS.md) or sixteen hex digits. Painting nothing.`)));
 	}
 	render() {
-		return l`<div class="vf-snap box"><slot></slot></div>`;
+		return f`<div
+      class="vf-snap box vf-pattern-fill${this._pattern ? " vf-patterned" : ""}"
+    >
+      <slot></slot>
+    </div>`;
 	}
 };
-u = n([e("vf-container")], u);
+n([p()], h.prototype, "pattern", void 0), n([m(".box")], h.prototype, "box", void 0), h = n([e("vf-container")], h);
 //#endregion
-export { u as VfContainer };
+export { h as VfContainer };

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

@@ -3,8 +3,10 @@ declare const VfDesktop_base: (new (...args: any[]) => import("../position.js").
 /**
  * `<vf-desktop>` — the full-bleed classic desktop container.
  *
- * Renders the 50%-dither gray desktop pattern and manages the stacking order
- * and `active` state of slotted `vf-window` children: a `pointerdown` or
+ * Renders the desktop pattern — the classic 50% dither by default, or any of
+ * the standard patterns by name (`pattern`, System 7's General Controls
+ * setting) — and manages the stacking order and `active` state of slotted
+ * `vf-window` children: a `pointerdown` or
  * `focusin` (keyboard focus) anywhere inside a window brings it to the front
  * and makes it the single active window. The windows' light-DOM order is kept
  * in step with the stacking order (bottom-most first, at pointer-gesture
@@ -43,16 +45,24 @@ declare const VfDesktop_base: (new (...args: any[]) => import("../position.js").
  * the CRT's unlit margin — around the screen, rounding its top corners
  * with the classic corner mask.
  *
+ * **`pattern`** names the desktop pattern — `gray-50` (the dither) by
+ * default, any of the 38 standard patterns (docs/PATTERNS.md), or sixteen
+ * hex digits stating a custom 8×8 pattern, as on `vf-container`. It is
+ * painted as the screen's own background: black ink on an opaque white
+ * paper, one whole-surface raster at one image px per system px, 1-bit at
+ * every density and zoom (src/pattern-fill.ts).
+ *
  * Custom properties:
- * - `--vf-desktop-pattern` — the dither's tile art (default a 1-bit 50%
- *   checker, opaque black-on-white on a 30-system-px tile). Overriding it
- *   renders the token as a placed tile grid at that same 30-px geometry
+ * - `--vf-desktop-pattern` — a consumer's own tile art in place of the
+ *   pattern (the kit's default is a 1-bit 50% checker, opaque
+ *   black-on-white on a 30-system-px tile). Set, it wins over `pattern` and
+ *   renders as a placed tile grid at that same 30-px geometry
  *   (src/tile-grid.ts); a token swapped at runtime without touching the
  *   component wants a `requestUpdate()`.
- * - `--vf-desktop` — base color painted *under* the pattern layer (default
- *   `#808080`). The default tile is opaque, so this only becomes visible when
- *   `--vf-desktop-pattern` is overridden with a tile that has transparent
- *   cells (or with `none`).
+ * - `--vf-desktop` — base color painted *under* the pattern (default
+ *   `#808080`). The pattern's paper is opaque, so this only becomes visible
+ *   when `--vf-desktop-pattern` is overridden with a tile that has
+ *   transparent cells (or with `none`).
  *
  * @slot - Default slot: menu bar, windows, anything.
  * @fires vf-activate - The active document-tier window changed. Detail
@@ -60,15 +70,16 @@ declare const VfDesktop_base: (new (...args: any[]) => import("../position.js").
  *   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.
- * @csspart desktop - The dithered screen surface — the whole-system-px
+ * @csspart desktop - The patterned screen surface — the whole-system-px
  *   raster (inset by `bezel` when one is set).
- * @cssprop [--vf-desktop=#808080] - base color under the desktop dither —
- *   occluded by the default (opaque) tile, so it only shows through a custom
- *   `--vf-desktop-pattern`
- * @cssprop --vf-desktop-pattern - 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)
+ * @cssprop [--vf-desktop=#808080] - base color under the desktop pattern —
+ *   occluded by the pattern's opaque paper, so it only shows through a
+ *   custom `--vf-desktop-pattern`
+ * @cssprop --vf-desktop-pattern - 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)
  */
 export declare class VfDesktop extends VfDesktop_base {
     #private;
@@ -98,6 +109,17 @@ export declare class VfDesktop extends VfDesktop_base {
      * the same pixels.
      */
     bezel: number;
+    /**
+     * The desktop pattern — System 7's General Controls setting. A library
+     * pattern by name (`gray-50`, the classic dither, by default; `gray-75`,
+     * `bricks`, … — docs/PATTERNS.md) or sixteen hex digits stating a custom
+     * 8×8 pattern, as on `vf-container`. Painted black on opaque white over
+     * the whole screen, 1-bit at every density and zoom. A
+     * `--vf-desktop-pattern` token override still wins and renders the
+     * consumer's tile as a placed grid; an unrecognized value warns once and
+     * keeps the dither.
+     */
+    pattern: string | null | undefined;
     /**
      * Size the screen to the largest whole-system-px raster whose host box —
      * bezel included — fits a CSS-px bound, and return what was set. The
@@ -120,11 +142,22 @@ export declare class VfDesktop extends VfDesktop_base {
     private readonly gridSnap;
     /**
      * The consumer's `--vf-desktop-pattern` override, or `''` for the kit
-     * dither — which of the two exact-fill paths render() takes (see
+     * pattern — which of the two exact-fill paths render() takes (see
      * src/tile-grid.ts). Re-read every update; a token swapped at runtime
      * without touching the component wants a `requestUpdate()`.
      */
-    private _pattern;
+    private _token;
+    /** `pattern`, resolved — the kit path's art; the dither when unset. */
+    private _desktopPattern;
+    /** The screen surface the pattern paints on; exists from the first render. */
+    private readonly screen;
+    /**
+     * The desktop pattern, painted as the screen's own background
+     * (src/pattern-fill.ts) from the declared raster — scale-independent, so
+     * density and zoom re-encode nothing — and silent while a consumer token
+     * owns the fill.
+     */
+    private readonly patternFill;
     /** Monotonic z-index counter for window stacking. */
     private _zCounter;
     /**