@taprootio/espalier 2.2.0 → 2.3.0

package/custom-elements.json

@@ -8128,6 +8128,21 @@
               "name": "itemsSlot",
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "describedCheckboxes",
+              "privacy": "private",
+              "default": "new Set<EspalierCheckbox>()"
+            },
             {
               "kind": "field",
               "name": "name",
@@ -8247,6 +8262,21 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "applyFormItemDescription",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "field",
+              "name": "handleItemsSlotChange",
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "handleChildChanged",
@@ -9048,6 +9078,12 @@
               "privacy": "private",
               "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => (this.checked ? this.value || \"on\" : null), getValidity: () => { if (this.required && !this.checked) { return { flags: { valueMissing: true }, message: this.requiredMessage || \"Please check this box to continue.\", }; } return null; }, onReset: () => { this.checked = false; this.indeterminate = false; }, onRestore: (state: string) => { this.checked = state === \"on\" || state === this.value; }, onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.shadowRoot?.querySelector<HTMLElement>(\".checkbox-control\"), })"
+            },
             {
               "kind": "field",
               "name": "checked",
@@ -10740,6 +10776,12 @@
               "privacy": "private",
               "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => this._value || null, getValidity: () => this._getValidityResult(), getValidationAnchor: (): HTMLElement => this.inputRef.value ?? this, onReset: () => { this._rangeAnchor = null; this._rangePreview = null; this._value = \"\"; this.requestUpdate(\"value\", \"\"); this._syncFromValue(); }, onRestore: (state: string) => { this.value = state; }, onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.inputRef.value, })"
+            },
             {
               "kind": "field",
               "name": "popoverCtrl",
@@ -15558,361 +15600,367 @@
     },
     {
       "kind": "javascript-module",
-      "path": "dist/font-picker/esp-font-picker.js",
+      "path": "dist/flyout/esp-flyout.js",
       "declarations": [
         {
-          "kind": "variable",
-          "name": "WEB_SAFE_FONTS",
-          "type": {
-            "text": "Array<WebSafeFont>"
-          },
-          "default": "[ { family: \"Arial / Helvetica\", stack: \"Arial, Helvetica, sans-serif\", category: \"sans-serif\", kind: \"web-safe\", }, { family: \"Georgia / Times New Roman\", stack: 'Georgia, \"Times New Roman\", Times, serif', category: \"serif\", kind: \"web-safe\", }, { family: \"Verdana / Geneva\", stack: \"Verdana, Geneva, sans-serif\", category: \"sans-serif\", kind: \"web-safe\", }, { family: \"Tahoma / Geneva\", stack: \"Tahoma, Geneva, sans-serif\", category: \"sans-serif\", kind: \"web-safe\", }, { family: \"Trebuchet MS\", stack: '\"Trebuchet MS\", Arial, sans-serif', category: \"sans-serif\", kind: \"web-safe\", }, { family: \"Courier New\", stack: '\"Courier New\", Courier, monospace', category: \"monospace\", kind: \"web-safe\", }, { family: \"System Sans\", stack: '-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif', category: \"sans-serif\", kind: \"web-safe\", }, { family: \"System Serif\", stack: 'ui-serif, Georgia, Cambria, \"Times New Roman\", Times, serif', category: \"serif\", kind: \"web-safe\", }, { family: \"System Monospace\", stack: 'ui-monospace, SFMono-Regular, Consolas, \"Liberation Mono\", \"Courier New\", monospace', category: \"monospace\", kind: \"web-safe\", }, ]"
-        },
-        {
-          "kind": "function",
-          "name": "getGoogleFonts",
-          "return": {
-            "type": {
-              "text": "Promise<Array<GoogleFont>>"
+          "kind": "class",
+          "description": "A transient panel for help, more-info, and preview content that\nclaims designed spare width before ever covering the page.\n\nPlace one `esp-flyout` in an `esp-page`'s `flyout` slot. The panel\nlives on the canvas, outside the content surface. The page decides\nwhere it goes, from widest viewport to narrowest:\n\n1. **Gutter** — the panel occupies the right canvas gutter. When the\n   gutter already has room, it claims existing spare canvas and the\n   main content does not move at all, on any alignment.\n2. **Shift** — when the gutter is not quite wide enough, the surface\n   slides toward `start` by exactly the shortfall (no more) to free\n   the difference.\n3. **Docked sidebar** — once the gutter is gone, the panel competes\n   for width with the main well; content narrows but is never\n   covered.\n4. **Overlay drawer** — below the mobile threshold (`50em`, the\n   same one the `esp-menu` drawer uses) the panel becomes a fixed\n   drawer over a vellum backdrop. Set `mode=\"overlay\"` to get this\n   presentation at every width.\n\nThe panel is styled as a tear-off piece: a dotted perforation on\nits leading edge, rounded trailing corners, and no shadow — all\noverridable through the `--esp-flyout-*` tokens below.\n\nA11y follows the presentation. In the in-grid modes (1–3) the\nflyout is a non-modal `complementary` landmark named by its\n`heading`, and opening it never steals focus. In the overlay-drawer\nmode (4) it is a true modal: `role=\"dialog\"` + `aria-modal`, the\nbackground goes inert, scroll is locked, focus moves into the drawer\nand is trapped, and focus is restored on close. `Escape` closes it\nin every mode.\n\n```html\n<style>\nesp-page.flyout-demo {\n  --esp-page-max-width: 420px;\n  --esp-page-canvas-background: var(--esp-color-layer-1);\n  &::part(wrapper) {\n    min-height: 320px;\n    height: 320px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n}\n</style>\n<esp-page class=\"flyout-demo\" align=\"center\">\n  <esp-flyout slot=\"flyout\" heading=\"More info\" id=\"demo-flyout\" standalone>\n    <p>Spare width claimed; the well shifted only enough to make room.</p>\n  </esp-flyout>\n  <div>\n    <esp-button id=\"toggle-flyout\" label=\"Toggle flyout\" collapsed></esp-button>\n  </div>\n</esp-page>\n<script>\n  const flyout = findById(\"demo-flyout\");\n  findById(\"toggle-flyout\").addEventListener(\"clicked\", () => flyout.toggle());\n</script>\n```\n\nBy default the panel is a tear-off — a dotted perforation on its\nleading edge, rounded trailing corners, no shadow. Add\n`match-surface` to lift the trailing edge with the page's surface\nedge shadow, so the flyout reads as a raised peer of the content it\nflies out from while staying attached at the leading perforation:\n\n```html\n<style>\nesp-page.flyout-match-demo {\n  --esp-page-max-width: 420px;\n  &::part(wrapper) {\n    min-height: 320px;\n    height: 320px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n}\n</style>\n<esp-page class=\"flyout-match-demo\" align=\"center\">\n  <esp-flyout slot=\"flyout\" heading=\"More info\" id=\"match-flyout\" match-surface standalone>\n    <p>Attached at the perforation, trailing edge raised like the surface.</p>\n  </esp-flyout>\n  <div>\n    <esp-button id=\"toggle-match\" label=\"Toggle flyout\" collapsed></esp-button>\n  </div>\n</esp-page>\n<script>\n  const matchFlyout = findById(\"match-flyout\");\n  findById(\"toggle-match\").addEventListener(\"clicked\", () => matchFlyout.toggle());\n</script>\n```\n\nWhen the page has no spare width to claim — a `kind=\"full\"` page,\nor a capped page on a viewport at the cap — the open flyout docks\nas a right sidebar and the content makes room:\n\n```html\n<style>\nesp-page.flyout-docked-demo {\n  &::part(wrapper) {\n    min-height: 320px;\n    height: 320px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n}\n</style>\n<esp-page class=\"flyout-docked-demo\" kind=\"full\">\n  <esp-flyout slot=\"flyout\" heading=\"Docked\" id=\"docked-flyout\" standalone>\n    <p>No gutter to claim, so the content narrows instead.</p>\n  </esp-flyout>\n  <div>\n    <p>A <code>kind=\"full\"</code> page has no canvas gutters at any\n    width — the flyout squeezes the main well and never covers it.</p>\n    <esp-button id=\"toggle-docked\" label=\"Toggle flyout\" collapsed></esp-button>\n  </div>\n</esp-page>\n<script>\n  const dockedFlyout = findById(\"docked-flyout\");\n  findById(\"toggle-docked\").addEventListener(\"clicked\", () => dockedFlyout.toggle());\n</script>\n```\n\nBelow the `50em` viewport threshold every flyout becomes a fixed\noverlay drawer over a vellum — there is no room for a side-by-side\nsplit on a phone. `mode=\"overlay\"` forces that presentation at any\nwidth (try it here; `Escape` or the vellum closes it):\n\n```html\n<style>\nesp-page.flyout-overlay-demo {\n  &::part(wrapper) {\n    min-height: 160px;\n    height: 160px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n}\n</style>\n<esp-page class=\"flyout-overlay-demo\">\n  <esp-flyout slot=\"flyout\" heading=\"Overlay drawer\" mode=\"overlay\" id=\"overlay-flyout\" standalone>\n    <p>A fixed drawer over a vellum — what every flyout becomes on\n    small viewports.</p>\n  </esp-flyout>\n  <div>\n    <esp-button id=\"open-overlay\" label=\"Open overlay flyout\" collapsed></esp-button>\n  </div>\n</esp-page>\n<script>\n  const overlayFlyout = findById(\"overlay-flyout\");\n  findById(\"open-overlay\").addEventListener(\"clicked\", () => overlayFlyout.toggle());\n</script>\n```\n\nComponents that cannot know where the flyout lives can request it\nover the bus with `showFlyout()` — the same pattern `showToast()`\nuses. A second request swaps the content in place; it never\nstacks. Content passed as a string renders as plain text; pass a\n`Node` for rich content. Pass the triggering element as `anchor` to\nalign the in-grid panel with that control and keep both in the same\nscroll flow. If the panel would cross the visible viewport's bottom,\nit shifts up only far enough to fit and returns to its natural trigger\nalignment as the page scrolls. Content taller than the viewport\nscrolls inside the panel. Overlay drawers stay viewport-fixed.\n\nThe bus is a global broadcast, so every listening flyout on the\npage answers a `showFlyout()` call. The demos above are each driven\nby their own toggle button, so they are marked `standalone` to opt\nout of the bus — leaving this one flyout as the page's shared\nsurface. In a real app you typically have a single flyout and need\nno attribute at all.\n\n```html\n<style>\nesp-page.flyout-bus-demo {\n  --esp-page-max-width: 420px;\n  &::part(wrapper) {\n    min-height: 320px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n  .flyout-demo-copy {\n    max-inline-size: 42ch;\n  }\n}\n</style>\n<esp-page class=\"flyout-bus-demo\">\n  <esp-flyout slot=\"flyout\"></esp-flyout>\n  <div>\n    <esp-button id=\"show-apples\" label=\"Apples\" collapsed></esp-button>\n    <div class=\"flyout-demo-copy\">\n      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod\n      tempor incididunt ut labore et dolore magna aliqua.</p>\n      <p>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi\n      ut aliquip ex ea commodo consequat.</p>\n      <p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum\n      dolore eu fugiat nulla pariatur.</p>\n    </div>\n    <esp-button id=\"show-pears\" label=\"Pears\" collapsed></esp-button>\n    <template id=\"pears-description\">\n      <p>Ripen pears at room temperature until the neck yields gently to\n      pressure, then refrigerate them to slow further ripening.</p>\n      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer\n      nec odio. Praesent libero. Sed cursus ante dapibus diam.</p>\n      <p>Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis\n      sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper\n      porta.</p>\n      <p>Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent\n      taciti sociosqu ad litora torquent per conubia nostra.</p>\n      <p>Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.\n      Curabitur tortor. Pellentesque nibh. Aenean quam.</p>\n      <p>In scelerisque sem at dolor. Maecenas mattis. Sed convallis\n      tristique sem. Proin ut ligula vel nunc egestas porttitor.</p>\n      <p>Morbi lectus risus, iaculis vel, suscipit quis, luctus non,\n      massa. Fusce ac turpis quis ligula lacinia aliquet.</p>\n      <p>Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed,\n      euismod in, nibh. Quisque volutpat condimentum velit.</p>\n    </template>\n    <div class=\"flyout-demo-copy\">\n      <p>Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia\n      deserunt mollit anim id est laborum.</p>\n      <p>Curabitur pretium tincidunt lacus. Nulla gravida orci a odio, nullam\n      varius, turpis et commodo pharetra.</p>\n    </div>\n  </div>\n</esp-page>\n<script>\n  const applesButton = findById(\"show-apples\");\n  applesButton.addEventListener(\"clicked\", () => {\n    showFlyout({ heading: \"Apples\", content: \"Crisp. Store cold.\", anchor: applesButton });\n  });\n  const pearsButton = findById(\"show-pears\");\n  const pearsDescription = findById(\"pears-description\");\n  pearsButton.addEventListener(\"clicked\", () => {\n    showFlyout({\n      heading: \"Pears\",\n      content: pearsDescription.content.cloneNode(true),\n      anchor: pearsButton,\n    });\n  });\n</script>\n```",
+          "name": "EspalierFlyout",
+          "cssProperties": [
+            {
+              "description": "The background color of the panel. Defaults to `var(--esp-color-background)`.",
+              "name": "--esp-flyout-background"
+            },
+            {
+              "description": "The border on the panel's leading edge. Defaults to the tear-off perforation, `1px dotted var(--esp-color-border)`.",
+              "name": "--esp-flyout-border"
+            },
+            {
+              "description": "The radius of the panel's trailing corners. Defaults to `var(--esp-size-border-radius)`; the overlay drawer squares them.",
+              "name": "--esp-flyout-radius"
+            },
+            {
+              "description": "The panel's shadow. Defaults to `none` in the gutter/docked modes (the perforation does the separating) and to a drawer shadow in overlay mode.",
+              "name": "--esp-flyout-shadow"
+            },
+            {
+              "description": "Padding inside the panel's header and content regions. Defaults to `var(--esp-size-padding)`.",
+              "name": "--esp-flyout-padding"
+            },
+            {
+              "description": "Stack order of the overlay-drawer mode. Defaults to `3000` — above page chrome, below the dialog drop zone (4000). Set it on the `esp-page` (or an ancestor), not on the flyout itself: the page reads the same token to hoist the drawer's aside above its header.",
+              "name": "--esp-flyout-z-index"
+            },
+            {
+              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "name": "--esp-field-background",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Border color of the shared field shell. Defaults to `var(--esp-color-border)`.",
+              "name": "--esp-field-border-color",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Border width of the shared field shell. Defaults to `1px`.",
+              "name": "--esp-field-border-width",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Text color used inside the shared field shell. Defaults to `var(--esp-color-text)`.",
+              "name": "--esp-field-text-color",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Hover background color of the shared field shell. Derived from `--esp-field-background`.",
+              "name": "--esp-field-hover-bg",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Focus background color of the shared field shell. Derived from `--esp-field-background`.",
+              "name": "--esp-field-focus-bg",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Shadow color used for shared field focus treatment. Defaults to `var(--esp-color-shadow)`.",
+              "name": "--esp-field-focus-shadow",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
             }
-          },
-          "description": "Load the font catalog from the build-generated `font-definitions.json`\nfile served alongside the font CSS files.  The JSON is fetched from\n`{fontCSSRoot}font-definitions.json` where `fontCSSRoot` comes from\nthe nearest `<esp-root>` element's `font-css-root` attribute.\n\nResults are cached at the module level so only one fetch occurs per page."
-        },
-        {
-          "kind": "function",
-          "name": "previewFontFamily",
-          "return": {
-            "type": {
-              "text": "string"
+          ],
+          "cssParts": [
+            {
+              "description": "The panel surface.",
+              "name": "panel"
+            },
+            {
+              "description": "The heading/close-button row.",
+              "name": "header"
+            },
+            {
+              "description": "The scrollable content region wrapping the slot.",
+              "name": "content"
             }
-          },
-          "parameters": [
+          ],
+          "slots": [
             {
-              "name": "family",
-              "type": {
-                "text": "string"
-              }
+              "description": "The flyout's content.",
+              "name": ""
             }
           ],
-          "description": "Build the CSS `font-family` value used by picker items.\nConsumers should reference this when setting `styles.fontFamily`\non picker items to match the preview `@font-face` name."
-        },
-        {
-          "kind": "class",
-          "description": "Font picker component backed by the Google Fonts catalog by default.\n\nThe font catalog is loaded at runtime from a build-generated\n`font-definitions.json` file served alongside the individual font CSS\nfiles.  Run `npm run build-fonts` to generate both assets.\n\nSet `font-source=\"web-safe\"` for email editors or other places where\nthe picker should offer only CSS font stacks that do not need font\ndownloads.\n\n**Required setup:**\n1. Serve the `css/fonts/` directory under a public path.\n2. Point `<esp-root font-css-root=\"/your/path/\">` at that path.\n\n```html\n<esp-root font-css-root=\"/css/fonts/\">\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker></esp-font-picker>\n  </esp-form-item>\n</esp-root>\n```\n\n```html\n<esp-form-item label=\"Email font\">\n  <esp-font-picker font-source=\"web-safe\"></esp-font-picker>\n</esp-form-item>\n```",
-          "name": "EspalierFontPicker",
           "members": [
             {
               "kind": "field",
-              "name": "loadedFonts",
-              "privacy": "private",
-              "default": "new Set<string>()"
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether the flyout is open. Reflected so the initial state can\nbe declared in markup; `esp-page` mirrors it (via the lifecycle\nevents and the slot) onto its own `flyout-open` attribute to\ndrive the grid.",
+              "attribute": "open",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "_rangeGeneration",
+              "name": "heading",
               "type": {
-                "text": "number"
+                "text": "string"
               },
-              "privacy": "private",
-              "default": "0",
-              "description": "Monotonically increasing counter used to detect stale\n`handleItemsInView` invocations.  Each call bumps the\ncounter; after the async font-load loop the handler checks\nwhether a newer call has started and, if so, skips the\nunload phase so it doesn't remove fonts that the newer call\njust loaded."
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "Heading text for the panel's header row. Also becomes the\nflyout's accessible name unless the author set an `aria-label`.\nAn open overlay without either uses the fallback name \"Flyout\" so\nits dialog is never exposed without an accessible name.",
+              "attribute": "heading"
             },
             {
               "kind": "field",
-              "name": "_initGeneration",
+              "name": "mode",
               "type": {
-                "text": "number"
+                "text": "\"auto\" | \"overlay\""
               },
-              "privacy": "private",
-              "default": "0",
-              "description": "Monotonically increasing counter used to detect stale `initFonts`\ninvocations when source/category changes while async catalog or\npreview-font work is in flight."
+              "privacy": "public",
+              "default": "\"auto\"",
+              "description": "Placement behavior.\n\n- `\"auto\"` (default) — the page's placement ladder: gutter,\n  docked sidebar, then overlay drawer below the `50em` viewport\n  threshold.\n- `\"overlay\"` — always the fixed overlay drawer, at any width.\n  The page never reserves a grid track for an overlay-mode\n  flyout.",
+              "attribute": "mode",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "_fontsReady",
+              "name": "anchor",
               "type": {
-                "text": "Promise<void>"
+                "text": "HTMLElement | undefined"
               },
-              "privacy": "private",
-              "description": "Promise that resolves once the async work kicked off in\n`firstUpdated` (font catalog fetch + initial CSS load)\nhas completed.  Surfaced through `getUpdateComplete()` so\nthat `await el.updateComplete` waits for the full init."
+              "privacy": "public",
+              "description": "Triggering element whose block-start edge the in-grid panel should\nalign with. Anchored panels stay in normal page flow, shift upward\nonly while needed to fit the visible scrollport, and return to their\nnatural alignment as the page scrolls. Oversized content scrolls\ninside the panel. Overlay drawers ignore this geometry and remain\nfixed to the viewport."
             },
             {
               "kind": "field",
-              "name": "fonts",
+              "name": "matchSurface",
               "type": {
-                "text": "Array<FontPickerFont>"
+                "text": "boolean"
               },
-              "privacy": "private",
-              "default": "[]"
+              "privacy": "public",
+              "default": "false",
+              "description": "When set on a flyout slotted into an `esp-page`, the panel lifts\nits **trailing** edge with the page's surface edge shadow, so it\nreads as a raised peer of the content surface it flies out from\nrather than the shadowless tear-off. The **leading** edge keeps\nits dotted perforation and casts no shadow, so the panel stays\nattached at the tear line instead of floating over the content.\nThe trailing-corner radius is still `--esp-flyout-radius`. No\neffect on a standalone flyout — there is no page surface to match.",
+              "attribute": "match-surface",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "category",
+              "name": "standalone",
               "type": {
-                "text": "FontCategory | null"
+                "text": "boolean"
               },
-              "default": "null",
-              "description": "Category of fonts to display in the picker.\n\nIf not set, all font categories are displayed.\n\n```html\n<esp-box>\n  <h2>Monospace Fonts</h2>\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker category=\"monospace\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
-              "attribute": "category"
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether this flyout ignores the shared `showFlyout()` /\n`closeFlyout()` bus and is driven only through its own\n`show()` / `close()` / `toggle()` API.\n\nBy default a flyout services the bus, so a single flyout in a\npage \"just works\" as the target of `showFlyout()` — the same\nzero-config model as `<esp-toaster>` and `showToast()`. Because\nthe bus is a global broadcast, **every** listening flyout on the\npage answers a `showFlyout()` call; set `standalone` on any\nflyout you drive directly so only your one designated help\nsurface responds.",
+              "attribute": "standalone",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "fontSource",
+              "name": "returnFocusTo",
               "type": {
-                "text": "FontSource"
+                "text": "HTMLElement | undefined"
               },
               "privacy": "public",
-              "default": "\"google\"",
-              "description": "Source of fonts to display. `google` preserves the default Google\nFonts catalog behavior. `web-safe` shows email-safe/system CSS\nfont stacks and does not load Google font assets.\n\n```html\n<esp-box>\n  <h2>Email-safe fonts</h2>\n  <esp-form-item label=\"Pick a font stack\">\n    <esp-font-picker font-source=\"web-safe\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
-              "attribute": "font-source"
+              "description": "Element to return focus to when the flyout closes. In the in-grid\nmodes it is focused only if focus is inside the flyout at close;\nin the overlay-drawer mode it overrides the modal treatment's\nautomatic restore-to-opener. Usually supplied through\n`showFlyout({ returnFocusTo })`."
             },
             {
               "kind": "field",
-              "name": "value",
+              "name": "overlayReturnFocusTo",
               "type": {
-                "text": "string"
+                "text": "HTMLElement | undefined"
               },
-              "privacy": "public",
-              "default": "\"\"",
-              "description": "The selected font family or CSS font stack.\n\nIn the default Google Fonts mode this is the font family name, such\nas `\"Aclonica\"`. In `font-source=\"web-safe\"` mode this is the full CSS\nfont stack, such as `\"Arial, Helvetica, sans-serif\"`, so pre-selection\nvia the `value` attribute must use the stack value.\n\n```html\n<esp-box>\n  <h2>Have Aclonica pre-selected</h2>\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker value=\"Aclonica\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
-              "attribute": "value"
+              "privacy": "private",
+              "description": "`returnFocusTo` captured at close time for the overlay teardown,\nwhich runs after `close()` (in `updated()`): the modal treatment\nrestores focus to the pre-open element, and this explicit target\nmust win over that."
             },
             {
               "kind": "field",
-              "name": "placeholder",
+              "name": "lastGeneratedAriaLabel",
               "type": {
-                "text": "string"
+                "text": "string | null"
               },
-              "privacy": "public",
-              "default": "\"Choose a font...\"",
-              "description": "The placeholder text for the picker input.",
-              "attribute": "placeholder"
+              "privacy": "private",
+              "default": "null",
+              "description": "The last `aria-label` this component generated from `heading` or\nthe overlay fallback, or `null` if none. The flyout only rewrites\n`aria-label` when the current value is absent or still equals what\nit last generated, so a label the author sets at any time — in\nmarkup or later — wins."
             },
             {
-              "kind": "method",
-              "name": "focus",
-              "privacy": "public",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "description": "Focus the picker input."
+              "kind": "field",
+              "name": "boundKeydown",
+              "privacy": "private"
             },
             {
-              "kind": "method",
-              "name": "getUpdateComplete",
-              "privacy": "protected",
-              "return": {
-                "type": {
-                  "text": "Promise<boolean>"
-                }
-              }
+              "kind": "field",
+              "name": "boundShowRequest",
+              "privacy": "private"
             },
             {
-              "kind": "method",
-              "name": "ensureFontLoaded",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Promise<void>"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "family",
-                  "type": {
-                    "text": "string"
-                  }
-                },
-                {
-                  "name": "previousFamily",
-                  "optional": true,
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ]
+              "kind": "field",
+              "name": "boundCloseRequest",
+              "privacy": "private"
             },
             {
-              "kind": "method",
-              "name": "initFonts",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Promise<void>"
-                }
-              }
+              "kind": "field",
+              "name": "boundOverlayMediaChange",
+              "privacy": "private"
             },
             {
-              "kind": "method",
-              "name": "handleItemsInView",
+              "kind": "field",
+              "name": "boundAnchorViewportChange",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "anchorPositionRaf",
+              "type": {
+                "text": "number"
+              },
               "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Promise<void>"
-                }
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "trackingAnchorPosition",
+              "type": {
+                "text": "boolean"
               },
-              "parameters": [
-                {
-                  "name": "range",
-                  "type": {
-                    "text": "{\n    first: number;\n    last: number;\n    items: Array<{ value: string }>;\n  }"
-                  }
-                }
-              ]
+              "privacy": "private",
+              "default": "false"
             },
             {
               "kind": "field",
-              "name": "handleItemsInViewEvent",
+              "name": "anchorResizeObserver",
+              "type": {
+                "text": "ResizeObserver | undefined"
+              },
               "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "seedColorBacker",
+              "name": "observedAnchorPanel",
               "type": {
-                "text": "string"
+                "text": "HTMLElement | undefined"
               },
-              "privacy": "private",
-              "default": "\"oklch(0.7 0.125 216)\"",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "espRoot",
+              "name": "busSubscribed",
               "type": {
-                "text": "EspalierRoot | null"
+                "text": "boolean"
               },
               "privacy": "private",
-              "default": "null",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "default": "false",
+              "description": "Whether the bus handlers are currently registered. EspBus does\nnot dedupe subscriptions, so this guards against double-adds."
             },
             {
               "kind": "field",
-              "name": "variantTokenOriginalValues",
+              "name": "panelRef",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "overlay",
               "privacy": "private",
-              "readonly": true,
-              "default": "new Map< string, { generatedPriority: string; generatedValue: string; originalPriority: string; originalValue: string | null; } >()",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "default": "new OverlayController({ host: this, getFocusTrapContainer: () => this.panelRef.value ?? null, getFocusFallback: () => this.panelRef.value ?? null, promote: false, })",
+              "description": "Modal treatment for the overlay-drawer presentation only. It does\nnot promote out of the page slot, so the flyout keeps its grid\nplacement and `flyout-state-changed` sync; inert anchors on the\nflyout's own position, making its page siblings inert."
             },
             {
               "kind": "field",
-              "name": "rootEventSubscriptionsActive",
+              "name": "overlayMediaQuery",
               "type": {
-                "text": "boolean"
+                "text": "MediaQueryList | undefined"
               },
               "privacy": "private",
-              "default": "false",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "description": "Media query matching the overlay-drawer viewport range."
             },
             {
               "kind": "field",
-              "name": "variantBacker",
+              "name": "overlayActive",
               "type": {
-                "text": "EspalierVariant"
+                "text": "boolean"
               },
-              "privacy": "protected",
-              "default": "\"primary\"",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the modal (overlay) treatment is currently applied."
             },
             {
               "kind": "field",
-              "name": "seedColor",
+              "name": "baseRole",
               "type": {
                 "text": "string"
               },
-              "privacy": "public",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "privacy": "private",
+              "default": "\"complementary\"",
+              "description": "The landmark role to restore when leaving the overlay treatment\n(the author's role, or the default `complementary`)."
             },
             {
               "kind": "field",
-              "name": "correlationId",
-              "privacy": "public",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "name": "effectiveOverlay",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the flyout is presenting as an overlay drawer — either\nforced via `mode=\"overlay\"` or below the mobile threshold. The\nmodal a11y treatment applies exactly in this state; the in-grid\nmodes stay a non-modal `complementary` landmark.",
+              "readonly": true
             },
             {
               "kind": "method",
-              "name": "focusResolvedElementAfterUpdate",
-              "privacy": "protected",
+              "name": "syncBusSubscription",
+              "privacy": "private",
               "return": {
                 "type": {
                   "text": "void"
                 }
               },
-              "parameters": [
-                {
-                  "name": "resolveTarget",
-                  "type": {
-                    "text": "() => HTMLElement | null | undefined"
-                  }
-                },
-                {
-                  "name": "options",
-                  "optional": true,
-                  "type": {
-                    "text": "FocusOptions"
-                  }
+              "description": "Subscribe to the shared bus unless `standalone`; idempotent so\nit is safe to call from both connect and a `standalone` change."
+            },
+            {
+              "kind": "method",
+              "name": "unsubscribeBus",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
                 }
-              ],
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
               }
             },
             {
               "kind": "method",
-              "name": "focusShadowElementAfterUpdate",
-              "privacy": "protected",
+              "name": "show",
+              "privacy": "public",
               "return": {
                 "type": {
                   "text": "void"
                 }
               },
-              "parameters": [
-                {
-                  "name": "selector",
-                  "type": {
-                    "text": "string"
-                  }
-                },
-                {
-                  "name": "options",
-                  "optional": true,
-                  "type": {
-                    "text": "FocusOptions"
-                  }
-                }
-              ],
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "description": "Open the flyout with its current content. In the in-grid modes it\ndoes not move focus; in the overlay-drawer mode it moves focus\ninto the drawer as a modal."
             },
             {
               "kind": "method",
-              "name": "emitValueChanged",
-              "privacy": "protected",
+              "name": "close",
+              "privacy": "public",
               "return": {
                 "type": {
                   "text": "void"
@@ -15920,16 +15968,362 @@
               },
               "parameters": [
                 {
-                  "name": "detail",
+                  "name": "reason",
+                  "default": "\"programmatic\"",
                   "type": {
-                    "text": "T"
+                    "text": "FlyoutCloseReason"
                   }
                 }
               ],
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+              "description": "Close the flyout. In the in-grid modes, if focus is inside the\nflyout it is returned to `returnFocusTo` when one was provided; in\nthe overlay-drawer mode the modal treatment restores focus to\nwherever it was when the drawer opened, unless `returnFocusTo`\nnames an explicit target — the explicit target wins."
+            },
+            {
+              "kind": "method",
+              "name": "toggle",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Toggle the flyout between open and closed."
+            },
+            {
+              "kind": "method",
+              "name": "handleShowRequest",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "config",
+                  "type": {
+                    "text": "FlyoutConfig"
+                  }
+                }
+              ],
+              "description": "Service a `\"show-flyout\"` bus request: swap in the requested\nheading/content (never stacking) and open."
+            },
+            {
+              "kind": "method",
+              "name": "handleKeydown",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "ev",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "focusIsInside",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "syncAnchorGeometry",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Position an anchored in-grid flyout at the trigger's natural\nblock-start, then shift it upward only enough to keep its bottom in\nthe visible scrollport. The shift is recalculated during scrolling,\nso it returns to zero when the panel fits at its natural top."
+            },
+            {
+              "kind": "method",
+              "name": "getVisibleBlockBounds",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ top: number; bottom: number }"
+                }
+              },
+              "description": "Intersect the visual viewport with every scrolling ancestor. This\nkeeps the flyout usable both on the document and inside a bounded\nlive-example pane such as WTFM's demo container."
+            },
+            {
+              "kind": "method",
+              "name": "composedParent",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Element | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "element",
+                  "type": {
+                    "text": "Element"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "setGeometryProperty",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "value",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "clearAnchorGeometry",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "scheduleAnchorGeometrySync",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "syncAnchorTracking",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "stopAnchorTracking",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "syncOverlayModal",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Apply modal a11y exactly when the flyout is open **and** presenting\nas an overlay drawer, and remove it otherwise. Called on open/mode\nchanges and when the viewport crosses the overlay threshold.\n\nModal treatment = background inert, scroll lock, `role=\"dialog\"` +\n`aria-modal`, focus moved into the drawer and trapped, and focus\nrestored on teardown — all via the (non-promoting) Overlay\ncontroller, so the flyout never leaves its page slot. The in-grid\nmodes stay a non-modal `complementary` landmark with no focus\nmanagement."
+            },
+            {
+              "kind": "method",
+              "name": "updateGeneratedAriaLabel",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Mirror `heading` into `aria-label`, or apply a stable fallback\nwhile this is an overlay dialog, without clobbering a label the\nauthor controls (see lastGeneratedAriaLabel)."
+            },
+            {
+              "kind": "field",
+              "name": "seedColorBacker",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "\"oklch(0.7 0.125 216)\"",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "espRoot",
+              "type": {
+                "text": "EspalierRoot | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "variantTokenOriginalValues",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Map< string, { generatedPriority: string; generatedValue: string; originalPriority: string; originalValue: string | null; } >()",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "rootEventSubscriptionsActive",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "variantBacker",
+              "type": {
+                "text": "EspalierVariant"
+              },
+              "privacy": "protected",
+              "default": "\"primary\"",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "seedColor",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "correlationId",
+              "privacy": "public",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "focusResolvedElementAfterUpdate",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "resolveTarget",
+                  "type": {
+                    "text": "() => HTMLElement | null | undefined"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "FocusOptions"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "focusShadowElementAfterUpdate",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "selector",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "FocusOptions"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "emitValueChanged",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "detail",
+                  "type": {
+                    "text": "T"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
             },
             {
               "kind": "field",
@@ -16227,12 +16621,32 @@
             }
           ],
           "events": [
+            {
+              "name": "flyout-opened",
+              "type": {
+                "text": "CustomEvent<{}>"
+              },
+              "description": "Fired by `show()` when the flyout opens."
+            },
+            {
+              "name": "flyout-closed",
+              "type": {
+                "text": "CustomEvent<{reason: FlyoutCloseReason}>"
+              },
+              "description": "Fired by `close()` when the flyout closes. `reason` is `\"escape\"`, `\"vellum\"`, `\"button\"`, or `\"programmatic\"`."
+            },
+            {
+              "name": "flyout-state-changed",
+              "type": {
+                "text": "CustomEvent<{}>"
+              },
+              "description": "Fired on every `open`, `mode`, or `anchor` change, including direct property assignment (not just `show()`/`close()`). `esp-page` uses it to keep its layout in sync; most consumers want `flyout-opened`/`flyout-closed` instead."
+            },
             {
               "name": "value-changed",
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Fired when the user selects a font",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
                 "module": "dist/shared/esp-element-base.js"
@@ -16241,40 +16655,49 @@
           ],
           "attributes": [
             {
-              "name": "category",
+              "name": "open",
               "type": {
-                "text": "FontCategory | null"
+                "text": "boolean"
               },
-              "default": "null",
-              "description": "Category of fonts to display in the picker.\n\nIf not set, all font categories are displayed.\n\n```html\n<esp-box>\n  <h2>Monospace Fonts</h2>\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker category=\"monospace\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
-              "fieldName": "category"
+              "default": "false",
+              "description": "Whether the flyout is open. Reflected so the initial state can\nbe declared in markup; `esp-page` mirrors it (via the lifecycle\nevents and the slot) onto its own `flyout-open` attribute to\ndrive the grid.",
+              "fieldName": "open"
             },
             {
-              "name": "font-source",
+              "name": "heading",
               "type": {
-                "text": "FontSource"
+                "text": "string"
               },
-              "default": "\"google\"",
-              "description": "Source of fonts to display. `google` preserves the default Google\nFonts catalog behavior. `web-safe` shows email-safe/system CSS\nfont stacks and does not load Google font assets.\n\n```html\n<esp-box>\n  <h2>Email-safe fonts</h2>\n  <esp-form-item label=\"Pick a font stack\">\n    <esp-font-picker font-source=\"web-safe\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
-              "fieldName": "fontSource"
+              "default": "\"\"",
+              "description": "Heading text for the panel's header row. Also becomes the\nflyout's accessible name unless the author set an `aria-label`.\nAn open overlay without either uses the fallback name \"Flyout\" so\nits dialog is never exposed without an accessible name.",
+              "fieldName": "heading"
             },
             {
-              "name": "value",
+              "name": "mode",
               "type": {
-                "text": "string"
+                "text": "\"auto\" | \"overlay\""
               },
-              "default": "\"\"",
-              "description": "The selected font family or CSS font stack.\n\nIn the default Google Fonts mode this is the font family name, such\nas `\"Aclonica\"`. In `font-source=\"web-safe\"` mode this is the full CSS\nfont stack, such as `\"Arial, Helvetica, sans-serif\"`, so pre-selection\nvia the `value` attribute must use the stack value.\n\n```html\n<esp-box>\n  <h2>Have Aclonica pre-selected</h2>\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker value=\"Aclonica\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
-              "fieldName": "value"
+              "default": "\"auto\"",
+              "description": "Placement behavior.\n\n- `\"auto\"` (default) — the page's placement ladder: gutter,\n  docked sidebar, then overlay drawer below the `50em` viewport\n  threshold.\n- `\"overlay\"` — always the fixed overlay drawer, at any width.\n  The page never reserves a grid track for an overlay-mode\n  flyout.",
+              "fieldName": "mode"
             },
             {
-              "name": "placeholder",
+              "name": "match-surface",
               "type": {
-                "text": "string"
+                "text": "boolean"
               },
-              "default": "\"Choose a font...\"",
-              "description": "The placeholder text for the picker input.",
-              "fieldName": "placeholder"
+              "default": "false",
+              "description": "When set on a flyout slotted into an `esp-page`, the panel lifts\nits **trailing** edge with the page's surface edge shadow, so it\nreads as a raised peer of the content surface it flies out from\nrather than the shadowless tear-off. The **leading** edge keeps\nits dotted perforation and casts no shadow, so the panel stays\nattached at the tear line instead of floating over the content.\nThe trailing-corner radius is still `--esp-flyout-radius`. No\neffect on a standalone flyout — there is no page surface to match.",
+              "fieldName": "matchSurface"
+            },
+            {
+              "name": "standalone",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this flyout ignores the shared `showFlyout()` /\n`closeFlyout()` bus and is driven only through its own\n`show()` / `close()` / `toggle()` API.\n\nBy default a flyout services the bus, so a single flyout in a\npage \"just works\" as the target of `showFlyout()` — the same\nzero-config model as `<esp-toaster>` and `showToast()`. Because\nthe bus is a global broadcast, **every** listening flyout on the\npage answers a `showFlyout()` call; set `standalone` on any\nflyout you drive directly so only your one designated help\nsurface responds.",
+              "fieldName": "standalone"
             },
             {
               "name": "scheme",
@@ -16306,490 +16729,208 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
-          "tagName": "esp-font-picker",
-          "customElement": true,
           "docPageTitle": {
-            "name": "Font",
-            "description": "Picker"
+            "name": "Flyout",
+            "description": ""
           },
           "docUrl": {
-            "name": "/components/font-picker",
+            "name": "/components/flyout",
             "description": ""
           },
           "menuGroup": {
-            "name": "Form",
-            "description": "Controls"
+            "name": "Structure",
+            "description": ""
+          },
+          "menuOrder": {
+            "name": "3",
+            "description": ""
           },
           "menuLabel": {
-            "name": "Font",
-            "description": "Picker"
+            "name": "Flyout",
+            "description": ""
           },
           "menuIcon": {
-            "name": "typography",
+            "name": "layout",
             "description": ""
           },
-          "cssProperties": [
-            {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
-              "name": "--esp-field-background",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Border color of the shared field shell. Defaults to `var(--esp-color-border)`.",
-              "name": "--esp-field-border-color",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Border width of the shared field shell. Defaults to `1px`.",
-              "name": "--esp-field-border-width",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Text color used inside the shared field shell. Defaults to `var(--esp-color-text)`.",
-              "name": "--esp-field-text-color",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Hover background color of the shared field shell. Derived from `--esp-field-background`.",
-              "name": "--esp-field-hover-bg",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Focus background color of the shared field shell. Derived from `--esp-field-background`.",
-              "name": "--esp-field-focus-bg",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Shadow color used for shared field focus treatment. Defaults to `var(--esp-color-shadow)`.",
-              "name": "--esp-field-focus-shadow",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            }
-          ]
-        },
-        {
-          "kind": "function",
-          "name": "resetFontCache",
-          "return": {
-            "type": {
-              "text": "void"
-            }
-          },
-          "description": "Reset the module-level font cache.  Exposed for test cleanup so each\ntest starts with a fresh slate."
+          "tagName": "esp-flyout",
+          "customElement": true
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "WEB_SAFE_FONTS",
-          "declaration": {
-            "name": "WEB_SAFE_FONTS",
-            "module": "dist/font-picker/esp-font-picker.js"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "getGoogleFonts",
-          "declaration": {
-            "name": "getGoogleFonts",
-            "module": "dist/font-picker/esp-font-picker.js"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "previewFontFamily",
-          "declaration": {
-            "name": "previewFontFamily",
-            "module": "dist/font-picker/esp-font-picker.js"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "EspalierFontPicker",
+          "name": "EspalierFlyout",
           "declaration": {
-            "name": "EspalierFontPicker",
-            "module": "dist/font-picker/esp-font-picker.js"
+            "name": "EspalierFlyout",
+            "module": "dist/flyout/esp-flyout.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-font-picker",
-          "declaration": {
-            "name": "EspalierFontPicker",
-            "module": "dist/font-picker/esp-font-picker.js"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "resetFontCache",
+          "name": "esp-flyout",
           "declaration": {
-            "name": "resetFontCache",
-            "module": "dist/font-picker/esp-font-picker.js"
+            "name": "EspalierFlyout",
+            "module": "dist/flyout/esp-flyout.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "dist/flyout/esp-flyout.js",
+      "path": "dist/font-picker/esp-font-picker.js",
       "declarations": [
         {
-          "kind": "class",
-          "description": "A transient panel for help, more-info, and preview content that\nclaims designed spare width before ever covering the page.\n\nPlace one `esp-flyout` in an `esp-page`'s `flyout` slot. The panel\nlives on the canvas, outside the content surface. The page decides\nwhere it goes, from widest viewport to narrowest:\n\n1. **Gutter** — the panel occupies the right canvas gutter. When the\n   gutter already has room, it claims existing spare canvas and the\n   main content does not move at all, on any alignment.\n2. **Shift** — when the gutter is not quite wide enough, the surface\n   slides toward `start` by exactly the shortfall (no more) to free\n   the difference.\n3. **Docked sidebar** — once the gutter is gone, the panel competes\n   for width with the main well; content narrows but is never\n   covered.\n4. **Overlay drawer** — below the mobile threshold (`50em`, the\n   same one the `esp-menu` drawer uses) the panel becomes a fixed\n   drawer over a vellum backdrop. Set `mode=\"overlay\"` to get this\n   presentation at every width.\n\nThe panel is styled as a tear-off piece: a dotted perforation on\nits leading edge, rounded trailing corners, and no shadow — all\noverridable through the `--esp-flyout-*` tokens below.\n\nA11y follows the presentation. In the in-grid modes (1–3) the\nflyout is a non-modal `complementary` landmark named by its\n`heading`, and opening it never steals focus. In the overlay-drawer\nmode (4) it is a true modal: `role=\"dialog\"` + `aria-modal`, the\nbackground goes inert, scroll is locked, focus moves into the drawer\nand is trapped, and focus is restored on close. `Escape` closes it\nin every mode.\n\n```html\n<style>\nesp-page.flyout-demo {\n  --esp-page-max-width: 420px;\n  --esp-page-canvas-background: var(--esp-color-layer-1);\n  &::part(wrapper) {\n    min-height: 320px;\n    height: 320px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n}\n</style>\n<esp-page class=\"flyout-demo\" align=\"center\">\n  <esp-flyout slot=\"flyout\" heading=\"More info\" id=\"demo-flyout\" standalone>\n    <p>Spare width claimed; the well shifted only enough to make room.</p>\n  </esp-flyout>\n  <div>\n    <esp-button id=\"toggle-flyout\" label=\"Toggle flyout\" collapsed></esp-button>\n  </div>\n</esp-page>\n<script>\n  const flyout = findById(\"demo-flyout\");\n  findById(\"toggle-flyout\").addEventListener(\"clicked\", () => flyout.toggle());\n</script>\n```\n\nBy default the panel is a tear-off — a dotted perforation on its\nleading edge, rounded trailing corners, no shadow. Add\n`match-surface` to lift the trailing edge with the page's surface\nedge shadow, so the flyout reads as a raised peer of the content it\nflies out from while staying attached at the leading perforation:\n\n```html\n<style>\nesp-page.flyout-match-demo {\n  --esp-page-max-width: 420px;\n  &::part(wrapper) {\n    min-height: 320px;\n    height: 320px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n}\n</style>\n<esp-page class=\"flyout-match-demo\" align=\"center\">\n  <esp-flyout slot=\"flyout\" heading=\"More info\" id=\"match-flyout\" match-surface standalone>\n    <p>Attached at the perforation, trailing edge raised like the surface.</p>\n  </esp-flyout>\n  <div>\n    <esp-button id=\"toggle-match\" label=\"Toggle flyout\" collapsed></esp-button>\n  </div>\n</esp-page>\n<script>\n  const matchFlyout = findById(\"match-flyout\");\n  findById(\"toggle-match\").addEventListener(\"clicked\", () => matchFlyout.toggle());\n</script>\n```\n\nWhen the page has no spare width to claim — a `kind=\"full\"` page,\nor a capped page on a viewport at the cap — the open flyout docks\nas a right sidebar and the content makes room:\n\n```html\n<style>\nesp-page.flyout-docked-demo {\n  &::part(wrapper) {\n    min-height: 320px;\n    height: 320px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n}\n</style>\n<esp-page class=\"flyout-docked-demo\" kind=\"full\">\n  <esp-flyout slot=\"flyout\" heading=\"Docked\" id=\"docked-flyout\" standalone>\n    <p>No gutter to claim, so the content narrows instead.</p>\n  </esp-flyout>\n  <div>\n    <p>A <code>kind=\"full\"</code> page has no canvas gutters at any\n    width — the flyout squeezes the main well and never covers it.</p>\n    <esp-button id=\"toggle-docked\" label=\"Toggle flyout\" collapsed></esp-button>\n  </div>\n</esp-page>\n<script>\n  const dockedFlyout = findById(\"docked-flyout\");\n  findById(\"toggle-docked\").addEventListener(\"clicked\", () => dockedFlyout.toggle());\n</script>\n```\n\nBelow the `50em` viewport threshold every flyout becomes a fixed\noverlay drawer over a vellum — there is no room for a side-by-side\nsplit on a phone. `mode=\"overlay\"` forces that presentation at any\nwidth (try it here; `Escape` or the vellum closes it):\n\n```html\n<style>\nesp-page.flyout-overlay-demo {\n  &::part(wrapper) {\n    min-height: 160px;\n    height: 160px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n}\n</style>\n<esp-page class=\"flyout-overlay-demo\">\n  <esp-flyout slot=\"flyout\" heading=\"Overlay drawer\" mode=\"overlay\" id=\"overlay-flyout\" standalone>\n    <p>A fixed drawer over a vellum — what every flyout becomes on\n    small viewports.</p>\n  </esp-flyout>\n  <div>\n    <esp-button id=\"open-overlay\" label=\"Open overlay flyout\" collapsed></esp-button>\n  </div>\n</esp-page>\n<script>\n  const overlayFlyout = findById(\"overlay-flyout\");\n  findById(\"open-overlay\").addEventListener(\"clicked\", () => overlayFlyout.toggle());\n</script>\n```\n\nComponents that cannot know where the flyout lives can request it\nover the bus with `showFlyout()` — the same pattern `showToast()`\nuses. A second request swaps the content in place; it never\nstacks. Content passed as a string renders as plain text; pass a\n`Node` for rich content. Pass the triggering element as `anchor` to\nalign the in-grid panel with that control and keep both in the same\nscroll flow. If the panel would cross the visible viewport's bottom,\nit shifts up only far enough to fit and returns to its natural trigger\nalignment as the page scrolls. Content taller than the viewport\nscrolls inside the panel. Overlay drawers stay viewport-fixed.\n\nThe bus is a global broadcast, so every listening flyout on the\npage answers a `showFlyout()` call. The demos above are each driven\nby their own toggle button, so they are marked `standalone` to opt\nout of the bus — leaving this one flyout as the page's shared\nsurface. In a real app you typically have a single flyout and need\nno attribute at all.\n\n```html\n<style>\nesp-page.flyout-bus-demo {\n  --esp-page-max-width: 420px;\n  &::part(wrapper) {\n    min-height: 320px;\n  }\n  > div {\n    padding: var(--esp-size-padding);\n  }\n  .flyout-demo-copy {\n    max-inline-size: 42ch;\n  }\n}\n</style>\n<esp-page class=\"flyout-bus-demo\">\n  <esp-flyout slot=\"flyout\"></esp-flyout>\n  <div>\n    <esp-button id=\"show-apples\" label=\"Apples\" collapsed></esp-button>\n    <div class=\"flyout-demo-copy\">\n      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod\n      tempor incididunt ut labore et dolore magna aliqua.</p>\n      <p>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi\n      ut aliquip ex ea commodo consequat.</p>\n      <p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum\n      dolore eu fugiat nulla pariatur.</p>\n    </div>\n    <esp-button id=\"show-pears\" label=\"Pears\" collapsed></esp-button>\n    <template id=\"pears-description\">\n      <p>Ripen pears at room temperature until the neck yields gently to\n      pressure, then refrigerate them to slow further ripening.</p>\n      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer\n      nec odio. Praesent libero. Sed cursus ante dapibus diam.</p>\n      <p>Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis\n      sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper\n      porta.</p>\n      <p>Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent\n      taciti sociosqu ad litora torquent per conubia nostra.</p>\n      <p>Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.\n      Curabitur tortor. Pellentesque nibh. Aenean quam.</p>\n      <p>In scelerisque sem at dolor. Maecenas mattis. Sed convallis\n      tristique sem. Proin ut ligula vel nunc egestas porttitor.</p>\n      <p>Morbi lectus risus, iaculis vel, suscipit quis, luctus non,\n      massa. Fusce ac turpis quis ligula lacinia aliquet.</p>\n      <p>Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed,\n      euismod in, nibh. Quisque volutpat condimentum velit.</p>\n    </template>\n    <div class=\"flyout-demo-copy\">\n      <p>Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia\n      deserunt mollit anim id est laborum.</p>\n      <p>Curabitur pretium tincidunt lacus. Nulla gravida orci a odio, nullam\n      varius, turpis et commodo pharetra.</p>\n    </div>\n  </div>\n</esp-page>\n<script>\n  const applesButton = findById(\"show-apples\");\n  applesButton.addEventListener(\"clicked\", () => {\n    showFlyout({ heading: \"Apples\", content: \"Crisp. Store cold.\", anchor: applesButton });\n  });\n  const pearsButton = findById(\"show-pears\");\n  const pearsDescription = findById(\"pears-description\");\n  pearsButton.addEventListener(\"clicked\", () => {\n    showFlyout({\n      heading: \"Pears\",\n      content: pearsDescription.content.cloneNode(true),\n      anchor: pearsButton,\n    });\n  });\n</script>\n```",
-          "name": "EspalierFlyout",
-          "cssProperties": [
-            {
-              "description": "The background color of the panel. Defaults to `var(--esp-color-background)`.",
-              "name": "--esp-flyout-background"
-            },
-            {
-              "description": "The border on the panel's leading edge. Defaults to the tear-off perforation, `1px dotted var(--esp-color-border)`.",
-              "name": "--esp-flyout-border"
-            },
-            {
-              "description": "The radius of the panel's trailing corners. Defaults to `var(--esp-size-border-radius)`; the overlay drawer squares them.",
-              "name": "--esp-flyout-radius"
-            },
-            {
-              "description": "The panel's shadow. Defaults to `none` in the gutter/docked modes (the perforation does the separating) and to a drawer shadow in overlay mode.",
-              "name": "--esp-flyout-shadow"
-            },
-            {
-              "description": "Padding inside the panel's header and content regions. Defaults to `var(--esp-size-padding)`.",
-              "name": "--esp-flyout-padding"
-            },
-            {
-              "description": "Stack order of the overlay-drawer mode. Defaults to `3000` — above page chrome, below the dialog drop zone (4000). Set it on the `esp-page` (or an ancestor), not on the flyout itself: the page reads the same token to hoist the drawer's aside above its header.",
-              "name": "--esp-flyout-z-index"
-            },
-            {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
-              "name": "--esp-field-background",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Border color of the shared field shell. Defaults to `var(--esp-color-border)`.",
-              "name": "--esp-field-border-color",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Border width of the shared field shell. Defaults to `1px`.",
-              "name": "--esp-field-border-width",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Text color used inside the shared field shell. Defaults to `var(--esp-color-text)`.",
-              "name": "--esp-field-text-color",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Hover background color of the shared field shell. Derived from `--esp-field-background`.",
-              "name": "--esp-field-hover-bg",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Focus background color of the shared field shell. Derived from `--esp-field-background`.",
-              "name": "--esp-field-focus-bg",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
-            },
-            {
-              "description": "Shadow color used for shared field focus treatment. Defaults to `var(--esp-color-shadow)`.",
-              "name": "--esp-field-focus-shadow",
-              "inheritedFrom": {
-                "name": "EspalierElementBase",
-                "module": "dist/shared/esp-element-base.js"
-              }
+          "kind": "variable",
+          "name": "WEB_SAFE_FONTS",
+          "type": {
+            "text": "Array<WebSafeFont>"
+          },
+          "default": "[ { family: \"Arial / Helvetica\", stack: \"Arial, Helvetica, sans-serif\", category: \"sans-serif\", kind: \"web-safe\", }, { family: \"Georgia / Times New Roman\", stack: 'Georgia, \"Times New Roman\", Times, serif', category: \"serif\", kind: \"web-safe\", }, { family: \"Verdana / Geneva\", stack: \"Verdana, Geneva, sans-serif\", category: \"sans-serif\", kind: \"web-safe\", }, { family: \"Tahoma / Geneva\", stack: \"Tahoma, Geneva, sans-serif\", category: \"sans-serif\", kind: \"web-safe\", }, { family: \"Trebuchet MS\", stack: '\"Trebuchet MS\", Arial, sans-serif', category: \"sans-serif\", kind: \"web-safe\", }, { family: \"Courier New\", stack: '\"Courier New\", Courier, monospace', category: \"monospace\", kind: \"web-safe\", }, { family: \"System Sans\", stack: '-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif', category: \"sans-serif\", kind: \"web-safe\", }, { family: \"System Serif\", stack: 'ui-serif, Georgia, Cambria, \"Times New Roman\", Times, serif', category: \"serif\", kind: \"web-safe\", }, { family: \"System Monospace\", stack: 'ui-monospace, SFMono-Regular, Consolas, \"Liberation Mono\", \"Courier New\", monospace', category: \"monospace\", kind: \"web-safe\", }, ]"
+        },
+        {
+          "kind": "function",
+          "name": "getGoogleFonts",
+          "return": {
+            "type": {
+              "text": "Promise<Array<GoogleFont>>"
             }
-          ],
-          "cssParts": [
-            {
-              "description": "The panel surface.",
-              "name": "panel"
-            },
-            {
-              "description": "The heading/close-button row.",
-              "name": "header"
-            },
-            {
-              "description": "The scrollable content region wrapping the slot.",
-              "name": "content"
+          },
+          "description": "Load the font catalog from the build-generated `font-definitions.json`\nfile served alongside the font CSS files.  The JSON is fetched from\n`{fontCSSRoot}font-definitions.json` where `fontCSSRoot` comes from\nthe nearest `<esp-root>` element's `font-css-root` attribute.\n\nResults are cached at the module level so only one fetch occurs per page."
+        },
+        {
+          "kind": "function",
+          "name": "previewFontFamily",
+          "return": {
+            "type": {
+              "text": "string"
             }
-          ],
-          "slots": [
+          },
+          "parameters": [
             {
-              "description": "The flyout's content.",
-              "name": ""
+              "name": "family",
+              "type": {
+                "text": "string"
+              }
             }
           ],
+          "description": "Build the CSS `font-family` value used by picker items.\nConsumers should reference this when setting `styles.fontFamily`\non picker items to match the preview `@font-face` name."
+        },
+        {
+          "kind": "class",
+          "description": "Font picker component backed by the Google Fonts catalog by default.\n\nThe font catalog is loaded at runtime from a build-generated\n`font-definitions.json` file served alongside the individual font CSS\nfiles.  Run `npm run build-fonts` to generate both assets.\n\nSet `font-source=\"web-safe\"` for email editors or other places where\nthe picker should offer only CSS font stacks that do not need font\ndownloads.\n\n**Required setup:**\n1. Serve the `css/fonts/` directory under a public path.\n2. Point `<esp-root font-css-root=\"/your/path/\">` at that path.\n\n```html\n<esp-root font-css-root=\"/css/fonts/\">\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker></esp-font-picker>\n  </esp-form-item>\n</esp-root>\n```\n\n```html\n<esp-form-item label=\"Email font\">\n  <esp-font-picker font-source=\"web-safe\"></esp-font-picker>\n</esp-form-item>\n```",
+          "name": "EspalierFontPicker",
           "members": [
             {
               "kind": "field",
-              "name": "open",
-              "type": {
-                "text": "boolean"
-              },
-              "privacy": "public",
-              "default": "false",
-              "description": "Whether the flyout is open. Reflected so the initial state can\nbe declared in markup; `esp-page` mirrors it (via the lifecycle\nevents and the slot) onto its own `flyout-open` attribute to\ndrive the grid.",
-              "attribute": "open",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "heading",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "public",
-              "default": "\"\"",
-              "description": "Heading text for the panel's header row. Also becomes the\nflyout's accessible name unless the author set an `aria-label`.\nAn open overlay without either uses the fallback name \"Flyout\" so\nits dialog is never exposed without an accessible name.",
-              "attribute": "heading"
-            },
-            {
-              "kind": "field",
-              "name": "mode",
-              "type": {
-                "text": "\"auto\" | \"overlay\""
-              },
-              "privacy": "public",
-              "default": "\"auto\"",
-              "description": "Placement behavior.\n\n- `\"auto\"` (default) — the page's placement ladder: gutter,\n  docked sidebar, then overlay drawer below the `50em` viewport\n  threshold.\n- `\"overlay\"` — always the fixed overlay drawer, at any width.\n  The page never reserves a grid track for an overlay-mode\n  flyout.",
-              "attribute": "mode",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "anchor",
-              "type": {
-                "text": "HTMLElement | undefined"
-              },
-              "privacy": "public",
-              "description": "Triggering element whose block-start edge the in-grid panel should\nalign with. Anchored panels stay in normal page flow, shift upward\nonly while needed to fit the visible scrollport, and return to their\nnatural alignment as the page scrolls. Oversized content scrolls\ninside the panel. Overlay drawers ignore this geometry and remain\nfixed to the viewport."
-            },
-            {
-              "kind": "field",
-              "name": "matchSurface",
-              "type": {
-                "text": "boolean"
-              },
-              "privacy": "public",
-              "default": "false",
-              "description": "When set on a flyout slotted into an `esp-page`, the panel lifts\nits **trailing** edge with the page's surface edge shadow, so it\nreads as a raised peer of the content surface it flies out from\nrather than the shadowless tear-off. The **leading** edge keeps\nits dotted perforation and casts no shadow, so the panel stays\nattached at the tear line instead of floating over the content.\nThe trailing-corner radius is still `--esp-flyout-radius`. No\neffect on a standalone flyout — there is no page surface to match.",
-              "attribute": "match-surface",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "standalone",
-              "type": {
-                "text": "boolean"
-              },
-              "privacy": "public",
-              "default": "false",
-              "description": "Whether this flyout ignores the shared `showFlyout()` /\n`closeFlyout()` bus and is driven only through its own\n`show()` / `close()` / `toggle()` API.\n\nBy default a flyout services the bus, so a single flyout in a\npage \"just works\" as the target of `showFlyout()` — the same\nzero-config model as `<esp-toaster>` and `showToast()`. Because\nthe bus is a global broadcast, **every** listening flyout on the\npage answers a `showFlyout()` call; set `standalone` on any\nflyout you drive directly so only your one designated help\nsurface responds.",
-              "attribute": "standalone",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "returnFocusTo",
-              "type": {
-                "text": "HTMLElement | undefined"
-              },
-              "privacy": "public",
-              "description": "Element to return focus to when the flyout closes. In the in-grid\nmodes it is focused only if focus is inside the flyout at close;\nin the overlay-drawer mode it overrides the modal treatment's\nautomatic restore-to-opener. Usually supplied through\n`showFlyout({ returnFocusTo })`."
-            },
-            {
-              "kind": "field",
-              "name": "overlayReturnFocusTo",
-              "type": {
-                "text": "HTMLElement | undefined"
-              },
+              "name": "loadedFonts",
               "privacy": "private",
-              "description": "`returnFocusTo` captured at close time for the overlay teardown,\nwhich runs after `close()` (in `updated()`): the modal treatment\nrestores focus to the pre-open element, and this explicit target\nmust win over that."
+              "default": "new Set<string>()"
             },
             {
               "kind": "field",
-              "name": "lastGeneratedAriaLabel",
+              "name": "formItemDescription",
               "type": {
                 "text": "string | null"
               },
               "privacy": "private",
-              "default": "null",
-              "description": "The last `aria-label` this component generated from `heading` or\nthe overlay fallback, or `null` if none. The flyout only rewrites\n`aria-label` when the current value is absent or still equals what\nit last generated, so a label the author sets at any time — in\nmarkup or later — wins."
-            },
-            {
-              "kind": "field",
-              "name": "boundKeydown",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "boundShowRequest",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "boundCloseRequest",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "boundOverlayMediaChange",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "boundAnchorViewportChange",
-              "privacy": "private"
+              "default": "null"
             },
             {
               "kind": "field",
-              "name": "anchorPositionRaf",
+              "name": "_rangeGeneration",
               "type": {
                 "text": "number"
               },
               "privacy": "private",
-              "default": "0"
+              "default": "0",
+              "description": "Monotonically increasing counter used to detect stale\n`handleItemsInView` invocations.  Each call bumps the\ncounter; after the async font-load loop the handler checks\nwhether a newer call has started and, if so, skips the\nunload phase so it doesn't remove fonts that the newer call\njust loaded."
             },
             {
               "kind": "field",
-              "name": "trackingAnchorPosition",
+              "name": "_initGeneration",
               "type": {
-                "text": "boolean"
+                "text": "number"
               },
               "privacy": "private",
-              "default": "false"
-            },
-            {
-              "kind": "field",
-              "name": "anchorResizeObserver",
-              "type": {
-                "text": "ResizeObserver | undefined"
-              },
-              "privacy": "private"
+              "default": "0",
+              "description": "Monotonically increasing counter used to detect stale `initFonts`\ninvocations when source/category changes while async catalog or\npreview-font work is in flight."
             },
             {
               "kind": "field",
-              "name": "observedAnchorPanel",
+              "name": "_fontsReady",
               "type": {
-                "text": "HTMLElement | undefined"
+                "text": "Promise<void>"
               },
-              "privacy": "private"
+              "privacy": "private",
+              "description": "Promise that resolves once the async work kicked off in\n`firstUpdated` (font catalog fetch + initial CSS load)\nhas completed.  Surfaced through `getUpdateComplete()` so\nthat `await el.updateComplete` waits for the full init."
             },
             {
               "kind": "field",
-              "name": "busSubscribed",
+              "name": "fonts",
               "type": {
-                "text": "boolean"
+                "text": "Array<FontPickerFont>"
               },
               "privacy": "private",
-              "default": "false",
-              "description": "Whether the bus handlers are currently registered. EspBus does\nnot dedupe subscriptions, so this guards against double-adds."
-            },
-            {
-              "kind": "field",
-              "name": "panelRef",
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "overlay",
-              "privacy": "private",
-              "default": "new OverlayController({ host: this, getFocusTrapContainer: () => this.panelRef.value ?? null, getFocusFallback: () => this.panelRef.value ?? null, promote: false, })",
-              "description": "Modal treatment for the overlay-drawer presentation only. It does\nnot promote out of the page slot, so the flyout keeps its grid\nplacement and `flyout-state-changed` sync; inert anchors on the\nflyout's own position, making its page siblings inert."
+              "default": "[]"
             },
             {
               "kind": "field",
-              "name": "overlayMediaQuery",
+              "name": "category",
               "type": {
-                "text": "MediaQueryList | undefined"
+                "text": "FontCategory | null"
               },
-              "privacy": "private",
-              "description": "Media query matching the overlay-drawer viewport range."
+              "default": "null",
+              "description": "Category of fonts to display in the picker.\n\nIf not set, all font categories are displayed.\n\n```html\n<esp-box>\n  <h2>Monospace Fonts</h2>\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker category=\"monospace\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
+              "attribute": "category"
             },
             {
               "kind": "field",
-              "name": "overlayActive",
+              "name": "fontSource",
               "type": {
-                "text": "boolean"
+                "text": "FontSource"
               },
-              "privacy": "private",
-              "default": "false",
-              "description": "Whether the modal (overlay) treatment is currently applied."
+              "privacy": "public",
+              "default": "\"google\"",
+              "description": "Source of fonts to display. `google` preserves the default Google\nFonts catalog behavior. `web-safe` shows email-safe/system CSS\nfont stacks and does not load Google font assets.\n\n```html\n<esp-box>\n  <h2>Email-safe fonts</h2>\n  <esp-form-item label=\"Pick a font stack\">\n    <esp-font-picker font-source=\"web-safe\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
+              "attribute": "font-source"
             },
             {
               "kind": "field",
-              "name": "baseRole",
+              "name": "value",
               "type": {
                 "text": "string"
               },
-              "privacy": "private",
-              "default": "\"complementary\"",
-              "description": "The landmark role to restore when leaving the overlay treatment\n(the author's role, or the default `complementary`)."
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "The selected font family or CSS font stack.\n\nIn the default Google Fonts mode this is the font family name, such\nas `\"Aclonica\"`. In `font-source=\"web-safe\"` mode this is the full CSS\nfont stack, such as `\"Arial, Helvetica, sans-serif\"`, so pre-selection\nvia the `value` attribute must use the stack value.\n\n```html\n<esp-box>\n  <h2>Have Aclonica pre-selected</h2>\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker value=\"Aclonica\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
+              "attribute": "value"
             },
             {
               "kind": "field",
-              "name": "effectiveOverlay",
+              "name": "placeholder",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "privacy": "private",
-              "description": "Whether the flyout is presenting as an overlay drawer — either\nforced via `mode=\"overlay\"` or below the mobile threshold. The\nmodal a11y treatment applies exactly in this state; the in-grid\nmodes stay a non-modal `complementary` landmark.",
-              "readonly": true
+              "privacy": "public",
+              "default": "\"Choose a font...\"",
+              "description": "The placeholder text for the picker input.",
+              "attribute": "placeholder"
             },
             {
               "kind": "method",
-              "name": "syncBusSubscription",
-              "privacy": "private",
+              "name": "focus",
+              "privacy": "public",
               "return": {
                 "type": {
                   "text": "void"
                 }
               },
-              "description": "Subscribe to the shared bus unless `standalone`; idempotent so\nit is safe to call from both connect and a `standalone` change."
+              "description": "Focus the picker input."
             },
             {
               "kind": "method",
-              "name": "unsubscribeBus",
+              "name": "syncFormItemDescription",
               "privacy": "private",
               "return": {
                 "type": {
@@ -16799,218 +16940,71 @@
             },
             {
               "kind": "method",
-              "name": "show",
-              "privacy": "public",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "description": "Open the flyout with its current content. In the in-grid modes it\ndoes not move focus; in the overlay-drawer mode it moves focus\ninto the drawer as a modal."
-            },
-            {
-              "kind": "method",
-              "name": "close",
-              "privacy": "public",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "reason",
-                  "default": "\"programmatic\"",
-                  "type": {
-                    "text": "FlyoutCloseReason"
-                  }
-                }
-              ],
-              "description": "Close the flyout. In the in-grid modes, if focus is inside the\nflyout it is returned to `returnFocusTo` when one was provided; in\nthe overlay-drawer mode the modal treatment restores focus to\nwherever it was when the drawer opened, unless `returnFocusTo`\nnames an explicit target — the explicit target wins."
-            },
-            {
-              "kind": "method",
-              "name": "toggle",
-              "privacy": "public",
+              "name": "getUpdateComplete",
+              "privacy": "protected",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "Promise<boolean>"
                 }
-              },
-              "description": "Toggle the flyout between open and closed."
+              }
             },
             {
               "kind": "method",
-              "name": "handleShowRequest",
+              "name": "ensureFontLoaded",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "Promise<void>"
                 }
               },
               "parameters": [
                 {
-                  "name": "config",
+                  "name": "family",
                   "type": {
-                    "text": "FlyoutConfig"
+                    "text": "string"
                   }
-                }
-              ],
-              "description": "Service a `\"show-flyout\"` bus request: swap in the requested\nheading/content (never stacking) and open."
-            },
-            {
-              "kind": "method",
-              "name": "handleKeydown",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
+                },
                 {
-                  "name": "ev",
+                  "name": "previousFamily",
+                  "optional": true,
                   "type": {
-                    "text": "KeyboardEvent"
+                    "text": "string"
                   }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "focusIsInside",
+              "name": "initFonts",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "boolean"
+                  "text": "Promise<void>"
                 }
               }
             },
             {
               "kind": "method",
-              "name": "syncAnchorGeometry",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "description": "Position an anchored in-grid flyout at the trigger's natural\nblock-start, then shift it upward only enough to keep its bottom in\nthe visible scrollport. The shift is recalculated during scrolling,\nso it returns to zero when the panel fits at its natural top."
-            },
-            {
-              "kind": "method",
-              "name": "getVisibleBlockBounds",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "{ top: number; bottom: number }"
-                }
-              },
-              "description": "Intersect the visual viewport with every scrolling ancestor. This\nkeeps the flyout usable both on the document and inside a bounded\nlive-example pane such as WTFM's demo container."
-            },
-            {
-              "kind": "method",
-              "name": "composedParent",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Element | null"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "element",
-                  "type": {
-                    "text": "Element"
-                  }
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "setGeometryProperty",
+              "name": "handleItemsInView",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "Promise<void>"
                 }
               },
               "parameters": [
                 {
-                  "name": "name",
-                  "type": {
-                    "text": "string"
-                  }
-                },
-                {
-                  "name": "value",
+                  "name": "range",
                   "type": {
-                    "text": "string"
+                    "text": "{\n    first: number;\n    last: number;\n    items: Array<{ value: string }>;\n  }"
                   }
                 }
               ]
             },
             {
-              "kind": "method",
-              "name": "clearAnchorGeometry",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "scheduleAnchorGeometrySync",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "syncAnchorTracking",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "stopAnchorTracking",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "syncOverlayModal",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "description": "Apply modal a11y exactly when the flyout is open **and** presenting\nas an overlay drawer, and remove it otherwise. Called on open/mode\nchanges and when the viewport crosses the overlay threshold.\n\nModal treatment = background inert, scroll lock, `role=\"dialog\"` +\n`aria-modal`, focus moved into the drawer and trapped, and focus\nrestored on teardown — all via the (non-promoting) Overlay\ncontroller, so the flyout never leaves its page slot. The in-grid\nmodes stay a non-modal `complementary` landmark with no focus\nmanagement."
-            },
-            {
-              "kind": "method",
-              "name": "updateGeneratedAriaLabel",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "description": "Mirror `heading` into `aria-label`, or apply a stable fallback\nwhile this is an overlay dialog, without clobbering a label the\nauthor controls (see lastGeneratedAriaLabel)."
+              "kind": "field",
+              "name": "handleItemsInViewEvent",
+              "privacy": "private"
             },
             {
               "kind": "field",
@@ -17472,32 +17466,12 @@
             }
           ],
           "events": [
-            {
-              "name": "flyout-opened",
-              "type": {
-                "text": "CustomEvent<{}>"
-              },
-              "description": "Fired by `show()` when the flyout opens."
-            },
-            {
-              "name": "flyout-closed",
-              "type": {
-                "text": "CustomEvent<{reason: FlyoutCloseReason}>"
-              },
-              "description": "Fired by `close()` when the flyout closes. `reason` is `\"escape\"`, `\"vellum\"`, `\"button\"`, or `\"programmatic\"`."
-            },
-            {
-              "name": "flyout-state-changed",
-              "type": {
-                "text": "CustomEvent<{}>"
-              },
-              "description": "Fired on every `open`, `mode`, or `anchor` change, including direct property assignment (not just `show()`/`close()`). `esp-page` uses it to keep its layout in sync; most consumers want `flyout-opened`/`flyout-closed` instead."
-            },
             {
               "name": "value-changed",
               "type": {
                 "text": "CustomEvent"
               },
+              "description": "Fired when the user selects a font",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
                 "module": "dist/shared/esp-element-base.js"
@@ -17506,49 +17480,40 @@
           ],
           "attributes": [
             {
-              "name": "open",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Whether the flyout is open. Reflected so the initial state can\nbe declared in markup; `esp-page` mirrors it (via the lifecycle\nevents and the slot) onto its own `flyout-open` attribute to\ndrive the grid.",
-              "fieldName": "open"
-            },
-            {
-              "name": "heading",
+              "name": "category",
               "type": {
-                "text": "string"
+                "text": "FontCategory | null"
               },
-              "default": "\"\"",
-              "description": "Heading text for the panel's header row. Also becomes the\nflyout's accessible name unless the author set an `aria-label`.\nAn open overlay without either uses the fallback name \"Flyout\" so\nits dialog is never exposed without an accessible name.",
-              "fieldName": "heading"
+              "default": "null",
+              "description": "Category of fonts to display in the picker.\n\nIf not set, all font categories are displayed.\n\n```html\n<esp-box>\n  <h2>Monospace Fonts</h2>\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker category=\"monospace\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
+              "fieldName": "category"
             },
             {
-              "name": "mode",
+              "name": "font-source",
               "type": {
-                "text": "\"auto\" | \"overlay\""
+                "text": "FontSource"
               },
-              "default": "\"auto\"",
-              "description": "Placement behavior.\n\n- `\"auto\"` (default) — the page's placement ladder: gutter,\n  docked sidebar, then overlay drawer below the `50em` viewport\n  threshold.\n- `\"overlay\"` — always the fixed overlay drawer, at any width.\n  The page never reserves a grid track for an overlay-mode\n  flyout.",
-              "fieldName": "mode"
+              "default": "\"google\"",
+              "description": "Source of fonts to display. `google` preserves the default Google\nFonts catalog behavior. `web-safe` shows email-safe/system CSS\nfont stacks and does not load Google font assets.\n\n```html\n<esp-box>\n  <h2>Email-safe fonts</h2>\n  <esp-form-item label=\"Pick a font stack\">\n    <esp-font-picker font-source=\"web-safe\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
+              "fieldName": "fontSource"
             },
             {
-              "name": "match-surface",
+              "name": "value",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "default": "false",
-              "description": "When set on a flyout slotted into an `esp-page`, the panel lifts\nits **trailing** edge with the page's surface edge shadow, so it\nreads as a raised peer of the content surface it flies out from\nrather than the shadowless tear-off. The **leading** edge keeps\nits dotted perforation and casts no shadow, so the panel stays\nattached at the tear line instead of floating over the content.\nThe trailing-corner radius is still `--esp-flyout-radius`. No\neffect on a standalone flyout — there is no page surface to match.",
-              "fieldName": "matchSurface"
+              "default": "\"\"",
+              "description": "The selected font family or CSS font stack.\n\nIn the default Google Fonts mode this is the font family name, such\nas `\"Aclonica\"`. In `font-source=\"web-safe\"` mode this is the full CSS\nfont stack, such as `\"Arial, Helvetica, sans-serif\"`, so pre-selection\nvia the `value` attribute must use the stack value.\n\n```html\n<esp-box>\n  <h2>Have Aclonica pre-selected</h2>\n  <esp-form-item label=\"Pick a font\">\n    <esp-font-picker value=\"Aclonica\"></esp-font-picker>\n  </esp-form-item>\n</esp-box>\n```",
+              "fieldName": "value"
             },
             {
-              "name": "standalone",
+              "name": "placeholder",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "default": "false",
-              "description": "Whether this flyout ignores the shared `showFlyout()` /\n`closeFlyout()` bus and is driven only through its own\n`show()` / `close()` / `toggle()` API.\n\nBy default a flyout services the bus, so a single flyout in a\npage \"just works\" as the target of `showFlyout()` — the same\nzero-config model as `<esp-toaster>` and `showToast()`. Because\nthe bus is a global broadcast, **every** listening flyout on the\npage answers a `showFlyout()` call; set `standalone` on any\nflyout you drive directly so only your one designated help\nsurface responds.",
-              "fieldName": "standalone"
+              "default": "\"Choose a font...\"",
+              "description": "The placeholder text for the picker input.",
+              "fieldName": "placeholder"
             },
             {
               "name": "scheme",
@@ -17580,49 +17545,145 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
+          "tagName": "esp-font-picker",
+          "customElement": true,
           "docPageTitle": {
-            "name": "Flyout",
-            "description": ""
+            "name": "Font",
+            "description": "Picker"
           },
           "docUrl": {
-            "name": "/components/flyout",
+            "name": "/components/font-picker",
             "description": ""
           },
           "menuGroup": {
-            "name": "Structure",
-            "description": ""
-          },
-          "menuOrder": {
-            "name": "3",
-            "description": ""
+            "name": "Form",
+            "description": "Controls"
           },
           "menuLabel": {
-            "name": "Flyout",
-            "description": ""
+            "name": "Font",
+            "description": "Picker"
           },
           "menuIcon": {
-            "name": "layout",
+            "name": "typography",
             "description": ""
           },
-          "tagName": "esp-flyout",
-          "customElement": true
+          "cssProperties": [
+            {
+              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "name": "--esp-field-background",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Border color of the shared field shell. Defaults to `var(--esp-color-border)`.",
+              "name": "--esp-field-border-color",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Border width of the shared field shell. Defaults to `1px`.",
+              "name": "--esp-field-border-width",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Text color used inside the shared field shell. Defaults to `var(--esp-color-text)`.",
+              "name": "--esp-field-text-color",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Hover background color of the shared field shell. Derived from `--esp-field-background`.",
+              "name": "--esp-field-hover-bg",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Focus background color of the shared field shell. Derived from `--esp-field-background`.",
+              "name": "--esp-field-focus-bg",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
+            {
+              "description": "Shadow color used for shared field focus treatment. Defaults to `var(--esp-color-shadow)`.",
+              "name": "--esp-field-focus-shadow",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "resetFontCache",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Reset the module-level font cache.  Exposed for test cleanup so each\ntest starts with a fresh slate."
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierFlyout",
+          "name": "WEB_SAFE_FONTS",
           "declaration": {
-            "name": "EspalierFlyout",
-            "module": "dist/flyout/esp-flyout.js"
+            "name": "WEB_SAFE_FONTS",
+            "module": "dist/font-picker/esp-font-picker.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "getGoogleFonts",
+          "declaration": {
+            "name": "getGoogleFonts",
+            "module": "dist/font-picker/esp-font-picker.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "previewFontFamily",
+          "declaration": {
+            "name": "previewFontFamily",
+            "module": "dist/font-picker/esp-font-picker.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "EspalierFontPicker",
+          "declaration": {
+            "name": "EspalierFontPicker",
+            "module": "dist/font-picker/esp-font-picker.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-flyout",
+          "name": "esp-font-picker",
           "declaration": {
-            "name": "EspalierFlyout",
-            "module": "dist/flyout/esp-flyout.js"
+            "name": "EspalierFontPicker",
+            "module": "dist/font-picker/esp-font-picker.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "resetFontCache",
+          "declaration": {
+            "name": "resetFontCache",
+            "module": "dist/font-picker/esp-font-picker.js"
           }
         }
       ]
@@ -18002,6 +18063,14 @@
               "description": "The color of the label text.",
               "name": "--esp-form-item-label-color"
             },
+            {
+              "description": "The color of the hint text. Defaults to a muted variant of the body text color.",
+              "name": "--esp-form-item-hint-color"
+            },
+            {
+              "description": "The font size of the hint text. Defaults to `var(--esp-type-tiny)`.",
+              "name": "--esp-form-item-hint-font-size"
+            },
             {
               "description": "The color of the visible error badge text.",
               "name": "--esp-form-item-error-color"
@@ -18059,6 +18128,16 @@
               "name": "--esp-form-item-font-size"
             }
           ],
+          "slots": [
+            {
+              "description": "The single form control the item wraps.",
+              "name": ""
+            },
+            {
+              "description": "Rich hint content; replaces the `hint` attribute text when present.",
+              "name": "hint"
+            }
+          ],
           "members": [
             {
               "kind": "field",
@@ -18107,6 +18186,85 @@
               "attribute": "autofocus",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "hint",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "Persistent helper text shown with the field — the bottom rung of\nthe help ladder. Hints are static authored guidance such as an\nexpected format; validation messaging belongs to `error` and\n`warning` and must not be routed through the hint. The hint stays\nvisible while an error or warning badge is showing, and is\nannounced to assistive technology as the field's description via\n`aria-describedby`.\n\n```html\n<esp-box class=\"demo-form\">\n  <esp-form-item\n    label=\"Employer ID\"\n    hint=\"Use the format XX-XXXXXXX.\">\n    <esp-input></esp-input>\n  </esp-form-item>\n  <esp-button label=\"Form Things\"></esp-button>\n</esp-box>\n```\n\nFor rich hint content, slot markup into the `hint` slot instead;\nit replaces the attribute text when present.",
+              "attribute": "hint"
+            },
+            {
+              "kind": "field",
+              "name": "hintPlacement",
+              "type": {
+                "text": "\"below\" | \"above\""
+              },
+              "privacy": "public",
+              "default": "\"below\"",
+              "description": "Where the hint renders. `below` (the default) places it directly\nunder the field, above the error/warning badge rows. `above`\nplaces it between the label text and the field. Any other value\nfalls back to `below`.\n\n```html\n<esp-box class=\"demo-form\">\n  <esp-form-item\n    label=\"Employer ID\"\n    hint=\"Use the format XX-XXXXXXX.\"\n    hint-placement=\"above\">\n    <esp-input></esp-input>\n  </esp-form-item>\n  <esp-button label=\"Form Things\"></esp-button>\n</esp-box>\n```",
+              "attribute": "hint-placement"
+            },
+            {
+              "kind": "field",
+              "name": "hintId",
+              "privacy": "private",
+              "readonly": true,
+              "default": "`esp-form-item-hint-${++hintIdCounter}`",
+              "description": "Stable id for the hint text element, referenced by the slotted\nfield's `aria-describedby`."
+            },
+            {
+              "kind": "field",
+              "name": "managedHintEl",
+              "type": {
+                "text": "HTMLSpanElement | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "The light-DOM span this component creates to carry the `hint`\nattribute text. See `syncManagedHint` for why the text cannot\nstay in the shadow root."
+            },
+            {
+              "kind": "field",
+              "name": "appliedHintTokens",
+              "type": {
+                "text": "string[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The describedby tokens this component added on the last sync."
+            },
+            {
+              "kind": "field",
+              "name": "hintContentObserver",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new MutationObserver(() => { this.syncFieldDescribedBy(); })",
+              "description": "Keep a shadow-local mirror current when rich hint text changes."
+            },
+            {
+              "kind": "field",
+              "name": "hasHint",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "A hint exists when either the attribute or the slot provides one.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "consumerHintElements",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Element[]"
+                }
+              },
+              "description": "Consumer-provided `slot=\"hint\"` elements (excluding the managed span)."
+            },
             {
               "kind": "field",
               "name": "error",
@@ -18200,6 +18358,67 @@
               "privacy": "private",
               "default": "[]"
             },
+            {
+              "kind": "field",
+              "name": "handleHintSlotChange",
+              "privacy": "private",
+              "description": "Re-evaluate hint presence when `hint` slot content changes."
+            },
+            {
+              "kind": "method",
+              "name": "observeConsumerHintContent",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Watch rich hint text and ids without observing the managed fallback span."
+            },
+            {
+              "kind": "method",
+              "name": "syncManagedHint",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Keep the `hint` attribute text in the light DOM. An\n`aria-describedby` IDREF on the slotted field cannot reach into\nthis component's shadow root (nor can ARIA element reflection —\nbrowsers drop references that point down into a shadow root), so\nthe description text must live in the field's own tree. The\nattribute text is projected through the `hint` slot via a span\nthis component owns; consumer-slotted hint content replaces the\nattribute text entirely."
+            },
+            {
+              "kind": "method",
+              "name": "hintDescriptionIds",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string[]"
+                }
+              },
+              "description": "Ids of the light-DOM elements carrying the hint text, assigning\ngenerated ids to consumer elements that lack one. Consumer ids are\nminted fresh from the module counter — never `hintId`, which is\nreserved for the managed span so a consumer element that keeps a\ngenerated id after it stops being a hint can never duplicate it."
+            },
+            {
+              "kind": "method",
+              "name": "hintDescriptionText",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string | null"
+                }
+              },
+              "description": "Plain text mirrored into an Espalier control's own shadow root."
+            },
+            {
+              "kind": "method",
+              "name": "syncFieldDescribedBy",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Mirror the hint onto the slotted field as its accessible\ndescription, preserving any consumer-set `aria-describedby`\ntokens (the same merge `esp-tooltip` performs on its trigger)."
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -18219,6 +18438,12 @@
                 }
               ],
               "description": "Focus the assigned slotted field."
+            },
+            {
+              "kind": "method",
+              "name": "renderHint",
+              "privacy": "private",
+              "description": "The hint renders inside the `<label>` when placed `above`, so it\nis wrapped in `aria-hidden` there to keep it out of the field's\naccessible-name computation — it stays announced as a description\nbecause nodes directly referenced by `aria-describedby` are\nincluded even when hidden."
             }
           ],
           "attributes": [
@@ -18240,6 +18465,24 @@
               "description": "When true, the first control where autofocus is true has\nfocus captured.",
               "fieldName": "autofocus"
             },
+            {
+              "name": "hint",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "Persistent helper text shown with the field — the bottom rung of\nthe help ladder. Hints are static authored guidance such as an\nexpected format; validation messaging belongs to `error` and\n`warning` and must not be routed through the hint. The hint stays\nvisible while an error or warning badge is showing, and is\nannounced to assistive technology as the field's description via\n`aria-describedby`.\n\n```html\n<esp-box class=\"demo-form\">\n  <esp-form-item\n    label=\"Employer ID\"\n    hint=\"Use the format XX-XXXXXXX.\">\n    <esp-input></esp-input>\n  </esp-form-item>\n  <esp-button label=\"Form Things\"></esp-button>\n</esp-box>\n```\n\nFor rich hint content, slot markup into the `hint` slot instead;\nit replaces the attribute text when present.",
+              "fieldName": "hint"
+            },
+            {
+              "name": "hint-placement",
+              "type": {
+                "text": "\"below\" | \"above\""
+              },
+              "default": "\"below\"",
+              "description": "Where the hint renders. `below` (the default) places it directly\nunder the field, above the error/warning badge rows. `above`\nplaces it between the label text and the field. Any other value\nfalls back to `below`.\n\n```html\n<esp-box class=\"demo-form\">\n  <esp-form-item\n    label=\"Employer ID\"\n    hint=\"Use the format XX-XXXXXXX.\"\n    hint-placement=\"above\">\n    <esp-input></esp-input>\n  </esp-form-item>\n  <esp-button label=\"Form Things\"></esp-button>\n</esp-box>\n```",
+              "fieldName": "hintPlacement"
+            },
             {
               "name": "error",
               "type": {
@@ -25789,6 +26032,12 @@
               "privacy": "private",
               "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => this.value || null, getValidity: () => this._getValidity(), getValidationAnchor: (): HTMLElement => this.theInput.value ?? this, onReset: () => { this.value = \"\"; this._dateDisplayText = \"\"; this._dateManaged = false; this._telDisplayText = \"\"; this._telManaged = false; this._hasVisibleError = false; }, onRestore: (state: string) => { this.value = state; if (this.inputType === \"date\" && state) { this._restoreDateDisplay(state); } if (this.inputType === \"tel\" && state) { this._restoreTelDisplay(state); } }, onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.theInput.value, })"
+            },
             {
               "kind": "field",
               "name": "_hasVisibleError",
@@ -33055,6 +33304,16 @@
                 "module": "dist/pickers/esp-picker-base.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.theInput.value, })",
+              "inheritedFrom": {
+                "name": "EspalierPickerBase",
+                "module": "dist/pickers/esp-picker-base.js"
+              }
+            },
             {
               "kind": "method",
               "name": "formResetCallback",
@@ -34430,6 +34689,16 @@
                 "module": "dist/pickers/esp-picker-base.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.theInput.value, })",
+              "inheritedFrom": {
+                "name": "EspalierPickerBase",
+                "module": "dist/pickers/esp-picker-base.js"
+              }
+            },
             {
               "kind": "method",
               "name": "formResetCallback",
@@ -35545,6 +35814,12 @@
               "privacy": "protected",
               "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => this.getPickerFormValue(), getValidity: () => this.getPickerValidity(), onReset: () => this.handlePickerReset(), onRestore: (state: string) => this.handlePickerRestore(state), onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.theInput.value, })"
+            },
             {
               "kind": "method",
               "name": "getPickerFormValue",
@@ -38840,6 +39115,21 @@
               "name": "itemsSlot",
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "describedRadios",
+              "privacy": "private",
+              "default": "new Set<EspalierRadioButton>()"
+            },
             {
               "kind": "field",
               "name": "name",
@@ -38959,6 +39249,21 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "applyFormItemDescription",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "field",
+              "name": "handleItemsSlotChange",
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "handleChildChanged",
@@ -39758,6 +40063,12 @@
             }
           ],
           "members": [
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.shadowRoot?.querySelector<HTMLElement>(\".radio-control\"), })"
+            },
             {
               "kind": "field",
               "name": "checked",
@@ -45851,6 +46162,172 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "dist/shared/form-field-description-controller.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Mirrors an `esp-form-item` hint into the same shadow root as a form\ncontrol's real focus target. ARIA ID references do not cross shadow\nboundaries, so setting `aria-describedby` on the custom-element host\nalone cannot describe an inner input, textarea, or ARIA control.",
+          "name": "FormFieldDescriptionController",
+          "members": [
+            {
+              "kind": "field",
+              "name": "descriptionId",
+              "privacy": "private",
+              "readonly": true,
+              "default": "`esp-form-field-description-${++descriptionIdCounter}`"
+            },
+            {
+              "kind": "field",
+              "name": "description",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "descriptionElement",
+              "type": {
+                "text": "HTMLSpanElement | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "target",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "method",
+              "name": "hostConnected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "hostUpdated",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "hostDisconnected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "setDescription",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "description",
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ],
+              "description": "Set or clear the description supplied by the wrapping form item."
+            },
+            {
+              "kind": "method",
+              "name": "sync",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "addDescriptionToken",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "removeDescriptionToken",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "HTMLElement | null"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "descriptionTokens",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "FormFieldDescriptionController",
+          "declaration": {
+            "name": "FormFieldDescriptionController",
+            "module": "dist/shared/form-field-description-controller.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "dist/shared/intent-values.js",
@@ -47765,6 +48242,12 @@
               "privacy": "private",
               "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => this.value || null, // A range slider always has a normalized numeric value (clamped // to [min, max] and snapped to step), so there is no // representable \"empty\" state that could trigger valueMissing. // Validity is always satisfied. getValidity: () => null, onReset: () => { this.value = String(this._low); }, onRestore: (state: string) => { this.value = state; }, onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this._thumbRef.value, })"
+            },
             {
               "kind": "field",
               "name": "min",
@@ -49848,6 +50331,12 @@
               "privacy": "private",
               "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => (this.checked ? this.value || \"on\" : null), getValidity: () => { if (this.required && !this.checked) { return { flags: { valueMissing: true }, message: this.requiredMessage || \"Please toggle this switch to continue.\", }; } return null; }, onReset: () => { this.checked = false; }, onRestore: (state: string) => { this.checked = state === \"on\" || state === this.value; }, onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.shadowRoot?.querySelector<HTMLElement>(\".switch-control\"), })"
+            },
             {
               "kind": "field",
               "name": "mode",
@@ -52244,6 +52733,12 @@
               "privacy": "private",
               "default": "new FormFieldController({ host: this, internals: this.internals, getFormValue: () => this.value || null, getValidity: () => this._getValidity(), getValidationAnchor: (): HTMLElement => this.theTextarea.value ?? this, onReset: () => { this.value = \"\"; this._hasVisibleError = false; }, onRestore: (state: string) => { this.value = state; }, onDisabled: (isDisabled: boolean) => { this.disabled = isDisabled; }, })"
             },
+            {
+              "kind": "field",
+              "name": "formItemDescription",
+              "privacy": "private",
+              "default": "new FormFieldDescriptionController({ host: this, getTarget: () => this.theTextarea.value, })"
+            },
             {
               "kind": "field",
               "name": "_hasVisibleError",