@taprootio/espalier 2.9.0 → 2.11.0

package/custom-elements.json

@@ -6186,6 +6186,147 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "dist/burger/esp-burger.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Animated burger button for showing and hiding navigation\ncomponents.\n\n```html\n<esp-burger></esp-burger>\n```",
+          "name": "EspalierBurger",
+          "cssProperties": [
+            {
+              "description": "The color of the burger lines when closed.",
+              "name": "--esp-color-burger"
+            },
+            {
+              "description": "The hover color of the burger lines when closed.",
+              "name": "--esp-color-burger-hover"
+            },
+            {
+              "description": "The color of the burger lines when open.",
+              "name": "--esp-color-burger-opened"
+            },
+            {
+              "description": "The hover color of the burger lines when open.",
+              "name": "--esp-color-burger-opened-hover"
+            },
+            {
+              "description": "The stroke width of the burger lines.",
+              "name": "--esp-size-burger-stroke"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "menuOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether or not the burger indicates an open state.",
+              "attribute": "menu-open"
+            },
+            {
+              "kind": "field",
+              "name": "presentationOnly",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Render only the animated burger graphic. Use this when an\nouter control owns activation, labeling, and expanded state.",
+              "attribute": "presentation-only"
+            },
+            {
+              "kind": "method",
+              "name": "toggleMenu"
+            }
+          ],
+          "events": [
+            {
+              "name": "opened",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Emitted when the button is clicked and the image changes from a burger to an X."
+            },
+            {
+              "name": "closed",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Emitted when the button is clicked and the image changes from an X to a burger. ```html <esp-burger></esp-burger> <script> const theBurger = findByTagName(\"esp-burger\")[0]; theBurger.addEventListener(\"opened\", () => { showToast({ message: \"It would be a good time to show the menu. This message will self-destruct in 4 seconds...\", icon: \"info-i\", duration: 4 }); }); theBurger.addEventListener(\"closed\", () => { showToast({ message: \"It would be a good time to hide the menu. This message will self-destruct in 4 seconds...\", icon: \"info-i\", duration: 4 }); }); </script> ```"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "menu-open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether or not the burger indicates an open state.",
+              "fieldName": "menuOpen"
+            },
+            {
+              "name": "presentation-only",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Render only the animated burger graphic. Use this when an\nouter control owns activation, labeling, and expanded state.",
+              "fieldName": "presentationOnly"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "docPageTitle": {
+            "name": "Burger",
+            "description": ""
+          },
+          "docUrl": {
+            "name": "/components/burger",
+            "description": ""
+          },
+          "menuGroup": {
+            "name": "Interaction",
+            "description": ""
+          },
+          "menuLabel": {
+            "name": "Burger",
+            "description": ""
+          },
+          "menuIcon": {
+            "name": "burger",
+            "description": ""
+          },
+          "tagName": "esp-burger",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "EspalierBurger",
+          "declaration": {
+            "name": "EspalierBurger",
+            "module": "dist/burger/esp-burger.js"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "esp-burger",
+          "declaration": {
+            "name": "EspalierBurger",
+            "module": "dist/burger/esp-burger.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "dist/breadcrumbs/esp-breadcrumb.js",
@@ -7001,147 +7142,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "dist/burger/esp-burger.js",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "Animated burger button for showing and hiding navigation\ncomponents.\n\n```html\n<esp-burger></esp-burger>\n```",
-          "name": "EspalierBurger",
-          "cssProperties": [
-            {
-              "description": "The color of the burger lines when closed.",
-              "name": "--esp-color-burger"
-            },
-            {
-              "description": "The hover color of the burger lines when closed.",
-              "name": "--esp-color-burger-hover"
-            },
-            {
-              "description": "The color of the burger lines when open.",
-              "name": "--esp-color-burger-opened"
-            },
-            {
-              "description": "The hover color of the burger lines when open.",
-              "name": "--esp-color-burger-opened-hover"
-            },
-            {
-              "description": "The stroke width of the burger lines.",
-              "name": "--esp-size-burger-stroke"
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "menuOpen",
-              "type": {
-                "text": "boolean"
-              },
-              "privacy": "public",
-              "default": "false",
-              "description": "Whether or not the burger indicates an open state.",
-              "attribute": "menu-open"
-            },
-            {
-              "kind": "field",
-              "name": "presentationOnly",
-              "type": {
-                "text": "boolean"
-              },
-              "privacy": "public",
-              "default": "false",
-              "description": "Render only the animated burger graphic. Use this when an\nouter control owns activation, labeling, and expanded state.",
-              "attribute": "presentation-only"
-            },
-            {
-              "kind": "method",
-              "name": "toggleMenu"
-            }
-          ],
-          "events": [
-            {
-              "name": "opened",
-              "type": {
-                "text": "CustomEvent"
-              },
-              "description": "Emitted when the button is clicked and the image changes from a burger to an X."
-            },
-            {
-              "name": "closed",
-              "type": {
-                "text": "CustomEvent"
-              },
-              "description": "Emitted when the button is clicked and the image changes from an X to a burger. ```html <esp-burger></esp-burger> <script> const theBurger = findByTagName(\"esp-burger\")[0]; theBurger.addEventListener(\"opened\", () => { showToast({ message: \"It would be a good time to show the menu. This message will self-destruct in 4 seconds...\", icon: \"info-i\", duration: 4 }); }); theBurger.addEventListener(\"closed\", () => { showToast({ message: \"It would be a good time to hide the menu. This message will self-destruct in 4 seconds...\", icon: \"info-i\", duration: 4 }); }); </script> ```"
-            }
-          ],
-          "attributes": [
-            {
-              "name": "menu-open",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Whether or not the burger indicates an open state.",
-              "fieldName": "menuOpen"
-            },
-            {
-              "name": "presentation-only",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Render only the animated burger graphic. Use this when an\nouter control owns activation, labeling, and expanded state.",
-              "fieldName": "presentationOnly"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "docPageTitle": {
-            "name": "Burger",
-            "description": ""
-          },
-          "docUrl": {
-            "name": "/components/burger",
-            "description": ""
-          },
-          "menuGroup": {
-            "name": "Interaction",
-            "description": ""
-          },
-          "menuLabel": {
-            "name": "Burger",
-            "description": ""
-          },
-          "menuIcon": {
-            "name": "burger",
-            "description": ""
-          },
-          "tagName": "esp-burger",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "EspalierBurger",
-          "declaration": {
-            "name": "EspalierBurger",
-            "module": "dist/burger/esp-burger.js"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "esp-burger",
-          "declaration": {
-            "name": "EspalierBurger",
-            "module": "dist/burger/esp-burger.js"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "dist/checkbox/esp-checkbox-group.js",
@@ -16276,7 +16276,7 @@
       "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. Pass `fullHeight: true` (or set the\n`full-height` attribute) when a reading surface should fill the visible\nblock-size even when its content is short. Overlay drawers stay\nviewport-fixed.\n\nBus requests anchored inside nested pages are presented by the\noutermost containing page's flyout by default. This keeps previews,\nembedded tools, and nested layouts from trapping application-level\nhelp or detail panels. Set `scope=\"nearest\"` on a nested flyout when\nthat page should explicitly own requests originating inside it.\nThe demos above are each driven by their own toggle button, so they\nare marked `standalone` to opt out of the bus entirely.\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```",
+          "description": "A transient panel for help and more-info content that claims designed spare\nwidth before ever covering the page.\n\nPlace one `esp-flyout` in an `esp-page`'s `flyout` slot. The panel\nlives on the canvas after any persistent preview, outside the content\nsurface. It negotiates between `--esp-page-flyout-min-width` and\n`--esp-page-flyout-max-width`; preview receives flexible room first. The page\ndecides where help 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** — when the complete sidebar + main + help\n   minimums do not fit, or 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.\nAn anchored panel shown with preview keeps its caret at the main/preview\nedge and receives a non-interactive dotted bridge across preview from the\npage. A short, thick terminus on the preview/help seam completes that\nconnection; no consumer positioning is required.\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`, opening it never steals focus, and boundary scrolling chains\nback to the main document. In the overlay-drawer mode (4) it is a true\nmodal: `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-main-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-main-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. Pass `fullHeight: true` (or set the\n`full-height` attribute) when a reading surface should fill the visible\nblock-size even when its content is short. Overlay drawers stay\nviewport-fixed.\n\nBus requests anchored inside nested pages are presented by the\noutermost containing page's flyout by default. This keeps previews,\nembedded tools, and nested layouts from trapping application-level\nhelp or detail panels. Set `scope=\"nearest\"` on a nested flyout when\nthat page should explicitly own requests originating inside it.\nThe demos above are each driven by their own toggle button, so they\nare marked `standalone` to opt out of the bus entirely.\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": [
             {
@@ -16412,7 +16412,7 @@
               },
               "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.",
+              "description": "Placement behavior.\n\n- `\"auto\"` (default) — the page's placement ladder: gutter,\n  docked sidebar, then overlay drawer when the complete in-grid\n  minimums do not fit or below the `50em` viewport 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
             },
@@ -17467,7 +17467,7 @@
                 "text": "\"auto\" | \"overlay\""
               },
               "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.",
+              "description": "Placement behavior.\n\n- `\"auto\"` (default) — the page's placement ladder: gutter,\n  docked sidebar, then overlay drawer when the complete in-grid\n  minimums do not fit or below the `50em` viewport 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"
             },
             {
@@ -39937,6 +39937,14 @@
               "privacy": "private",
               "default": "null"
             },
+            {
+              "kind": "field",
+              "name": "topOffsetOverride",
+              "type": {
+                "text": "() => number | undefined | undefined"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_pendingSetup",
@@ -40025,7 +40033,15 @@
               "name": "--esp-page-background"
             },
             {
-              "description": "The maximum width of the main content well. Set automatically by the `kind` attribute: `1536px` (wide), `768px` (narrow), or `none` (full). This cap now sizes the main grid track; surplus width beyond it becomes the canvas gutters.",
+              "description": "Minimum width of the main content well while preview or in-grid help competes for space. Defaults to `30rem`.",
+              "name": "--esp-page-main-min-width"
+            },
+            {
+              "description": "Maximum width of the main content well. Defaults from `kind`: `1536px` (wide), `768px` (narrow), or unbounded (full). Surplus width beyond it becomes canvas gutters.",
+              "name": "--esp-page-main-max-width"
+            },
+            {
+              "description": "Legacy fallback for `--esp-page-main-max-width`.",
               "name": "--esp-page-max-width"
             },
             {
@@ -40061,9 +40077,45 @@
               "name": "--esp-page-main-background"
             },
             {
-              "description": "The width of the open flyout track (and of the `esp-flyout` overlay drawer). Defaults to `20rem`.",
+              "description": "Background of the persistent preview surface. Defaults to the main background, then the page background.",
+              "name": "--esp-page-preview-background"
+            },
+            {
+              "description": "Leading tear-off edge between main and preview. Defaults to `1px dotted var(--esp-color-border)`.",
+              "name": "--esp-page-preview-border"
+            },
+            {
+              "description": "Shadow cast from the preview's trailing edge. Defaults to the page surface edge shadow. Set to `none` for a flat additive surface.",
+              "name": "--esp-page-preview-shadow"
+            },
+            {
+              "description": "Minimum preview width. Defaults to `22.5rem` (360px, a reasonable mobile-device surface).",
+              "name": "--esp-page-preview-min-width"
+            },
+            {
+              "description": "Maximum preview width. Defaults to `48rem`. Preview receives flexible trailing space before help grows.",
+              "name": "--esp-page-preview-max-width"
+            },
+            {
+              "description": "Minimum in-grid help width. Defaults to `20rem`.",
+              "name": "--esp-page-flyout-min-width"
+            },
+            {
+              "description": "Maximum help width and overlay drawer cap before the `85vw` viewport cap. Defaults to `30rem`.",
+              "name": "--esp-page-flyout-max-width"
+            },
+            {
+              "description": "Legacy fixed-width alias that pins both preview bounds.",
+              "name": "--esp-page-preview-width"
+            },
+            {
+              "description": "Legacy fixed-width alias that pins both help bounds.",
               "name": "--esp-page-flyout-width"
             },
+            {
+              "description": "Legacy fallback for `--esp-page-main-min-width`.",
+              "name": "--esp-page-preview-min-main-width"
+            },
             {
               "description": "Offset reserved for fixed headers. Defaults to `var(--esp-header-height)`.",
               "name": "--esp-page-fixed-header-offset"
@@ -40143,13 +40195,21 @@
               "name": "canvas"
             },
             {
-              "description": "The surface backdrop carrying the edge shadow/border. ```html <style> esp-page.with-background { --esp-page-background-image: url(/assets/espalier-paper-texture.png); --esp-page-background-image-opacity: .5; } </style> <esp-page class=\"docs with-background\"> <div slot=\"header\" style=\"background-color: red;\">header</div> <div slot=\"sidebar\" style=\"background-color: green;\">sidebar</div> <div slot=\"right\" style=\"background-color: purple;\">right</div> <esp-footer slot=\"footer\" brand-text=\"Espalier\"></esp-footer> <div style=\"overflow: hidden;\"> <h2>With background image</h2> </div> </esp-page> ``` Use `align` to place the surface within the page once it hits its cap, and the canvas tokens to style the gutters. A low `--esp-page-max-width` is set here only so the gutters are visible inside the narrow demo frame; the surface edge shadow is on by default. ```html <style> esp-page.align-demo { --esp-page-max-width: 520px; --esp-page-canvas-background: var(--esp-color-layer-1); } </style> <esp-page class=\"docs align-demo\" align=\"center\"> <div slot=\"header\" style=\"background-color: red;\">header</div> <div slot=\"sidebar\" style=\"background-color: green;\">sidebar</div> <div slot=\"right\" style=\"background-color: purple;\">right</div> <esp-footer slot=\"footer\" brand-text=\"Espalier\"></esp-footer> <div style=\"background-color: black; overflow: hidden;\"> content </div> </esp-page> ```",
+              "description": "The surface backdrop carrying the edge shadow/border.",
               "name": "surface"
+            },
+            {
+              "description": "The persistent preview complementary landmark.",
+              "name": "preview"
+            },
+            {
+              "description": "The sticky wrapper around preview content. ```html <style> esp-page.with-background { --esp-page-background-image: url(/assets/espalier-paper-texture.png); --esp-page-background-image-opacity: .5; } </style> <esp-page class=\"docs with-background\"> <div slot=\"header\" style=\"background-color: red;\">header</div> <div slot=\"sidebar\" style=\"background-color: green;\">sidebar</div> <div slot=\"right\" style=\"background-color: purple;\">right</div> <esp-footer slot=\"footer\" brand-text=\"Espalier\"></esp-footer> <div style=\"overflow: hidden;\"> <h2>With background image</h2> </div> </esp-page> ``` Use `align` to place the surface within the page once it hits its cap, and the canvas tokens to style the gutters. A low `--esp-page-max-width` is set here only so the gutters are visible inside the narrow demo frame; the surface edge shadow is on by default. ```html <style> esp-page.align-demo { --esp-page-max-width: 520px; --esp-page-canvas-background: var(--esp-color-layer-1); } </style> <esp-page class=\"docs align-demo\" align=\"center\"> <div slot=\"header\" style=\"background-color: red;\">header</div> <div slot=\"sidebar\" style=\"background-color: green;\">sidebar</div> <div slot=\"right\" style=\"background-color: purple;\">right</div> <esp-footer slot=\"footer\" brand-text=\"Espalier\"></esp-footer> <div style=\"background-color: black; overflow: hidden;\"> content </div> </esp-page> ```",
+              "name": "preview-content"
             }
           ],
           "slots": [
             {
-              "description": "Global navigation content (typically an `esp-header`). ```html <esp-page class=\"docs\"> <esp-header slot=\"header\"> <a href=\"#\" slot=\"brand\" class=\"nav-logo\"> <svg> <use href=\"/assets/icons.svg#taproot-logo\" /> </svg> </a> <esp-menu slot=\"menu\" mode=\"horizontal\"> <esp-menu-item label=\"Mammals\" url=\"#\"></esp-menu-item> <esp-menu-item label=\"Reptiles\" url=\"#\"></esp-menu-item> <esp-menu-item label=\"Amphibians\" url=\"#\"></esp-menu-item> </esp-menu> <esp-header-button slot=\"buttons\" icon=\"cog\" aria-label=\"Settings\"></esp-header-button> </esp-header> <esp-menu slot=\"sidebar\" mode=\"drawer\"></esp-menu> <div slot=\"right\" style=\"background-color: purple;\">right</div> <esp-footer slot=\"footer\" brand-text=\"Espalier\"></esp-footer> <div style=\"background-color: black; overflow: hidden;\"> content </div> </esp-page> ```",
+              "description": "Global navigation content (typically an `esp-header`). ```html <esp-page class=\"docs\"> <esp-header slot=\"header\"> <a href=\"#\" slot=\"brand\" class=\"nav-logo\"> <svg> <use href=\"/assets/icons.svg#taproot-logo\" /> </svg> </a> <esp-menu slot=\"menu\" mode=\"horizontal\"> <esp-menu-item label=\"Mammals\" url=\"#\"></esp-menu-item> <esp-menu-item label=\"Reptiles\" url=\"#\"></esp-menu-item> <esp-menu-item label=\"Amphibians\" url=\"#\"></esp-menu-item> </esp-menu> <esp-header-button slot=\"buttons\" icon=\"cog\" aria-label=\"Settings\"></esp-header-button> </esp-header> <esp-menu slot=\"sidebar\" mode=\"drawer\"></esp-menu> <div slot=\"right\" style=\"background-color: purple;\">right</div> <esp-footer slot=\"footer\" brand-text=\"Espalier\"></esp-footer> <div style=\"background-color: black; overflow: hidden;\"> content </div> </esp-page> ``` The authoring workspace is ordered main, preview, then help. Each region negotiates between public minimum and maximum widths; preview grows first, then help. Opt into collapsing a directly paired header/sidebar navigation to its accessible burger/drawer mode when the combined workspace needs it.",
               "name": "header"
             },
             {
@@ -40161,7 +40221,11 @@
               "name": "right"
             },
             {
-              "description": "A transient `esp-flyout` panel that lives on the canvas, outside the content surface. Closed it costs no width; open it claims the right canvas gutter first — the surface keeps its alignment weighting and shifts only as far as the flyout's width requires — then docks as a width-competing right sidebar when no gutter exists, and becomes an overlay drawer on small viewports. The persistent `right` aside and the transient flyout are complementary, not alternatives. A flyout opened with an `anchor` aligns to that trigger and stays in the same document scroll flow.",
+              "description": "Persistent preview content placed after the main surface and before help. It grows from `--esp-page-preview-min-width` to `--esp-page-preview-max-width`, starts at viewport top, and gives its content an independent `100dvh` vertical scroller. At either scroll boundary, wheel and trackpad motion chains back to the main document. Unlike flyout content, preview content is never replaced by the flyout request bus.",
+              "name": "preview"
+            },
+            {
+              "description": "A transient `esp-flyout` panel that lives on the canvas after preview. Closed it costs no width; open it grows from `--esp-page-flyout-min-width` to `--esp-page-flyout-max-width` after preview receives flexible space, then docks as a width-competing right sidebar when no gutter exists, and becomes an overlay drawer on small viewports. The persistent `right` aside and the transient flyout are complementary, not alternatives. A flyout opened with an `anchor` aligns to that trigger and stays in the same document scroll flow. When a preview is visible, its caret and non-interactive dotted bridge cross the preview back to the anchor, ending at a short thick marker on the preview/help seam.",
               "name": "flyout"
             },
             {
@@ -40189,6 +40253,152 @@
               "name": "footerSlot",
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "previewSlot",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "previewSpace",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "previewMinWidthProbe",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "previewMaxWidthProbe",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "flyoutMinWidthProbe",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "flyoutMaxWidthProbe",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "mainMinWidthProbe",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "previewResizeObserver",
+              "type": {
+                "text": "ResizeObserver | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "previewObservedWidths",
+              "privacy": "private",
+              "default": "new WeakMap<Element, number>()"
+            },
+            {
+              "kind": "field",
+              "name": "previewMediaQuery",
+              "type": {
+                "text": "MediaQueryList | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "previewSyncRaf",
+              "type": {
+                "text": "number | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "previewSyncGeneration",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "previewSyncTask",
+              "type": {
+                "text": "Promise<void>"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "previewOverlayRecoveryRequested",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "previewHeader",
+              "type": {
+                "text": "PreviewCompactHeader | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "previewMenu",
+              "type": {
+                "text": "PreviewCompactMenu | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "previewCollapsedSidebarWidth",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "flyoutOverlayPromotionWidth",
+              "type": {
+                "text": "number | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "flyoutOverlayRecoveryReady",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "flyoutOverlayRecoveryGeneration",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
             {
               "kind": "field",
               "name": "footerWrapperIsLandmark",
@@ -40218,6 +40428,559 @@
               ],
               "description": "Mirror the slotted flyout's open, overlay, and anchor state onto\nhost attributes read by the grid CSS. State is recomputed from the\nslot so multiple flyouts and slot changes stay correct."
             },
+            {
+              "kind": "method",
+              "name": "syncDescendantFlyoutOverlayState",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "A modal flyout owned by a nested page cannot escape this page's main\nstacking context. Mirror that descendant state so the containing main\nregion rises above this page's header while the drawer is open."
+            },
+            {
+              "kind": "method",
+              "name": "assignedFlyouts",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "PageManagedFlyout[]"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "openAutoFlyouts",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "PageManagedFlyout[]"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "setPageFlyoutOverlay",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<boolean>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "requested",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "clearFlyoutOverlayRecovery",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "armFlyoutOverlayRecovery",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "previewHasContent",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getPreviewNavigationPair",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{\n    header: PreviewCompactHeader;\n    menu: PreviewCompactMenu;\n  } | null"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "setPreviewNavigationCollapse",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<boolean>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "requested",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "setPreviewLayoutState",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "visible",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "reclaiming",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "setWorkspaceWidths",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "previewWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "visiblePageInlineBounds",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ left: number; right: number; width: number }"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "visibleSpaceWidth",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "description": "The gutter's layout box can extend past the visible page bounds — most\ncommonly a page laid out wider than the visual viewport beside a classic\nscrollbar. Allocation must draw from the same visible geometry the fit\nchecks validate against, or a scrollbar-sized overhang makes the\nallocated widths permanently unfittable and help is promoted to a modal\ndrawer over a sliver of hidden canvas."
+            },
+            {
+              "kind": "method",
+              "name": "probeWidth",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "probe",
+                  "type": {
+                    "text": "ReturnType<typeof createRef<HTMLDivElement>>"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "allocateWorkspaceWidths",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ previewWidth: number; flyoutWidth: number }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "availableWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "previewRequested",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "flyoutOpen",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "previewMinWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "previewMaxWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutMinWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutMaxWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "previewFitsWithinPage",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "minMainWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "previewMinWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "previewMaxWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutOpen",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "flyoutMinWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutMaxWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "flyoutFitsWithinPage",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "minMainWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutMinWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutMaxWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "workspaceMinimumsCanFit",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "minMainWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "previewRequested",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "previewMinWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutRequested",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "flyoutMinWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "workspaceGeometrySample",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number[]"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "workspaceGeometryMatches",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "left",
+                  "type": {
+                    "text": "number[]"
+                  }
+                },
+                {
+                  "name": "right",
+                  "type": {
+                    "text": "number[]"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "workspaceCandidateIsMeasurable",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "previewRequested",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "flyoutRequested",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "candidateFitsAfterLayoutSettles",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<boolean | null>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "generation",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "fits",
+                  "type": {
+                    "text": "() => boolean"
+                  }
+                },
+                {
+                  "name": "isMeasurable",
+                  "type": {
+                    "text": "() => boolean"
+                  }
+                }
+              ],
+              "description": "Validate one mounted candidate rather than scheduling a new negotiation\npass. A new pass starts by removing preview and zeroing its tracks, which\nmade the old retry repeatedly measure its own teardown on slower browsers.\nLit reflection is completed first; valid geometry returns immediately,\nwhile invalid geometry must remain unchanged across several rendered\nframes before it can request the overlay fallback."
+            },
+            {
+              "kind": "method",
+              "name": "promoteFlyoutIfClipped",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<boolean>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "generation",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "minMainWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutMinWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "flyoutMaxWidth",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "promoteFlyoutToOverlay",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "syncPreviewLayout",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "generation",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "allowOverlayRecovery",
+                  "default": "true"
+                }
+              ]
+            },
+            {
+              "kind": "field",
+              "name": "schedulePreviewLayout",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "onPreviewMediaChange",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "onPreviewResize",
+              "type": {
+                "text": "ResizeObserverCallback"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "setupPreviewLayoutObserver",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "footerElementProvidesLandmark",
@@ -40307,6 +41070,99 @@
               "attribute": "fixed-menus",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "previewOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether the persistent preview is logically open. The page may keep the\npreview hidden while space is unavailable; `preview-visible` reflects its\nactual presentation and the preview restores automatically when room returns.",
+              "attribute": "preview-open",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "previewLabel",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "\"Preview\"",
+              "description": "Accessible name for the preview's complementary landmark.",
+              "attribute": "preview-label",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "previewCollapseSidebar",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Allow a directly slotted, safely linked vertical menu/header pair to\ncollapse to its burger/drawer presentation when preview needs more room.",
+              "attribute": "preview-collapse-sidebar",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "previewVisible",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether preview content is currently rendered. Managed by the page's\nspace negotiation; consumers should treat this reflected property as read-only.",
+              "attribute": "preview-visible",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "previewReclaiming",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether preview is currently reserving width and allowing the main well\nto shrink toward `--esp-page-main-min-width`. Managed by the page.",
+              "attribute": "preview-reclaiming",
+              "reflects": true
+            },
+            {
+              "kind": "method",
+              "name": "showPreview",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Request the persistent preview without moving focus."
+            },
+            {
+              "kind": "method",
+              "name": "closePreview",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Close the persistent preview without moving focus."
+            },
+            {
+              "kind": "method",
+              "name": "togglePreview",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Toggle the persistent preview without moving focus."
+            },
             {
               "kind": "method",
               "name": "AddDialog",
@@ -40861,6 +41717,51 @@
               "description": "Compatibility alias for the original fixed header/sidebar behavior.\nPrefer `header-position=\"fixed\"` for new code.",
               "fieldName": "fixedMenus"
             },
+            {
+              "name": "preview-open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the persistent preview is logically open. The page may keep the\npreview hidden while space is unavailable; `preview-visible` reflects its\nactual presentation and the preview restores automatically when room returns.",
+              "fieldName": "previewOpen"
+            },
+            {
+              "name": "preview-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"Preview\"",
+              "description": "Accessible name for the preview's complementary landmark.",
+              "fieldName": "previewLabel"
+            },
+            {
+              "name": "preview-collapse-sidebar",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Allow a directly slotted, safely linked vertical menu/header pair to\ncollapse to its burger/drawer presentation when preview needs more room.",
+              "fieldName": "previewCollapseSidebar"
+            },
+            {
+              "name": "preview-visible",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether preview content is currently rendered. Managed by the page's\nspace negotiation; consumers should treat this reflected property as read-only.",
+              "fieldName": "previewVisible"
+            },
+            {
+              "name": "preview-reclaiming",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether preview is currently reserving width and allowing the main well\nto shrink toward `--esp-page-main-min-width`. Managed by the page.",
+              "fieldName": "previewReclaiming"
+            },
             {
               "name": "scheme",
               "type": {
@@ -40928,6 +41829,12 @@
                 "module": "dist/shared/esp-element-base.js"
               }
             }
+          ],
+          "examples": [
+            {
+              "title": "Main, preview, and contextual help",
+              "body": "```html\n<style>\n.page-workspace-demo {\n--esp-page-main-min-width: 26rem;\n--esp-page-main-max-width: 48rem;\n--esp-page-preview-min-width: 18rem;\n--esp-page-preview-max-width: 26rem;\n--esp-page-flyout-min-width: 18rem;\n--esp-page-flyout-max-width: 22rem;\n}\n\n.page-workspace-demo > main,\n.page-workspace-demo > [slot=\"preview\"] {\nbox-sizing: border-box;\npadding: var(--esp-size-padding-page);\n}\n\n.page-workspace-demo > main {\nmin-block-size: 120vh;\n}\n</style>\n\n<esp-page\nid=\"page-workspace-demo\"\nclass=\"page-workspace-demo\"\npreview-open\npreview-label=\"Rendered page preview\"\n>\n<main>\n<h2>Page details</h2>\n<esp-form-item label=\"Site title\">\n<esp-input id=\"page-workspace-title\" name=\"title\" value=\"Field notes\"></esp-input>\n</esp-form-item>\n<p>\nHelp is anchored to the title field in this main editor. Its caret and\ndotted connector cross the persistent preview without blocking it.\n</p>\n<esp-button id=\"page-workspace-preview-toggle\" label=\"Toggle preview\"></esp-button>\n<esp-button id=\"page-workspace-help-toggle\" label=\"Toggle title help\"></esp-button>\n</main>\n\n<article slot=\"preview\">\n<h2>Field notes</h2>\n<p>This preview is a full-viewport secondary surface with its own scroller.</p>\n</article>\n\n<esp-flyout\nid=\"page-workspace-help\"\nslot=\"flyout\"\nheading=\"Site title help\"\nstandalone\n>\n<p>Use a short, recognizable title. It appears in navigation and browser tabs.</p>\n</esp-flyout>\n</esp-page>\n\n<script>\nconst page = findById(\"page-workspace-demo\");\nconst title = findById(\"page-workspace-title\");\nconst help = findById(\"page-workspace-help\");\nhelp.anchor = title;\n\nconst syncMainWidth = () => {\npage.kind = page.previewOpen || help.open ? \"wide\" : \"full\";\n};\n\nfindById(\"page-workspace-preview-toggle\").addEventListener(\"clicked\", () => {\npage.togglePreview();\nsyncMainWidth();\n});\nfindById(\"page-workspace-help-toggle\").addEventListener(\"clicked\", () => {\nhelp.anchor = title;\nhelp.toggle();\nsyncMainWidth();\n});\nhelp.addEventListener(\"flyout-opened\", syncMainWidth);\nhelp.addEventListener(\"flyout-closed\", syncMainWidth);\nsyncMainWidth();\n</script>\n```"
+            }
           ]
         }
       ],