@taprootio/espalier 6.2.0 → 6.4.0

package/custom-elements.json

@@ -1967,7 +1967,7 @@
               "name": "--esp-action-menu-item-icon-border-color"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -2909,6 +2909,17 @@
               "description": "Where the optional icon slot is positioned within the item.\n\nUse `\"right\"` for Taproot-style action rows where the icon sits\nin a differentiated trailing cell with a dotted divider.",
               "fieldName": "iconPosition"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -3020,7 +3031,7 @@
               "name": "--esp-action-menu-min-width"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -4202,6 +4213,17 @@
               "description": "Controls where item icons appear inside the menu.\n\n`\"left\"` keeps icons before labels. `\"right\"` moves icons into\na trailing cell with a differentiated background and dotted divider.",
               "fieldName": "iconPosition"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -4454,7 +4476,7 @@
               "name": "--esp-avatar-size"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -5472,6 +5494,17 @@
               "description": "Referrer policy forwarded to the internal image. Defaults to\n`no-referrer`.",
               "fieldName": "referrerPolicy"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -5612,7 +5645,7 @@
               "name": "--esp-avatar-border-radius"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -6521,6 +6554,17 @@
               "description": "Optional presence state passed to the internal avatar.",
               "fieldName": "presence"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -6621,7 +6665,7 @@
               "name": "--esp-badge-border-radius"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -7468,6 +7512,17 @@
               "description": "Badge size.",
               "fieldName": "size"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -7560,7 +7615,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Used as a base to group context visually. `esp-box`\nhas a css part of `box` that can be styled to create cards,\nforms, and other UI elements.\n\n```html\n<esp-box>\n  <h2>Box things</h2>\n  <p>Things grouped visually.</p>\n</esp-box>\n```\n\n**What esp-box is not:** a full-bleed page band. The box is a *card* —\nit paints its own raised surface (`--esp-color-layer-1`), carries\npadding, and fills its container's height. A band is\n[`esp-section`](/components/section): it paints the local canvas edge\nto edge with a centered well and hosts a theme zone (`context=\"…\"`)\nwith nothing to neutralize. Keep boxes for what they are for — cards,\npanels, and form surfaces — and replace any pre-3.2 \"neutralized box\"\nband with a bare section.",
+          "description": "Groups related content in a themed container. Style its `box` CSS part\nto create cards, forms, or other grouped regions.\n\nA field fills one layer above the surface it sits on.\nUse `surface-layer=\"1|2|3|4\"` to select the default painted layer.\n\n```html\n<esp-box>\n  <h2>Box things</h2>\n  <p>Things grouped visually.</p>\n</esp-box>\n```\n\n**What esp-box is not:** a full-bleed page band. The box is a *card* —\nit paints its own raised surface (`--esp-color-layer-1`), carries\npadding, and fills its container's height. A band is\n[`esp-section`](/components/section): it paints the local canvas edge\nto edge with a centered well and hosts a theme zone (`context=\"…\"`)\nwith nothing to neutralize. Keep boxes for what they are for — cards,\npanels, and form surfaces — and replace any pre-3.2 \"neutralized box\"\nband with a bare section.\n\nSelect a raised form surface with `surface-layer`; fields follow it automatically.\n\n```html\n<esp-box surface-layer=\"2\">\n  <esp-input placeholder=\"Search\"></esp-input>\n  <esp-input readonly value=\"A read-only value\"></esp-input>\n</esp-box>\n```",
           "name": "EspalierBox",
           "cssProperties": [
             {
@@ -7584,7 +7639,7 @@
               "name": "--esp-box-shadow"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -7661,7 +7716,7 @@
               },
               "privacy": "public",
               "default": "false",
-              "description": "Whether the box should take up the full screen. Useful when\ndisplaying a dialog in full-screen mode.\n\n```html\n<esp-box>\n  <h2>Box things</h2>\n  <esp-box>\n    <h2>Box in box</h2>\n    <esp-button label=\"Toggle full screen\"></esp-button>\n  </esp-box>\n</esp-box>\n<script>\n  let fullScreen = false;\n  const theBox = findByTagName(\"esp-box\")[0];\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n    fullScreen = !fullScreen;\n\n    if(fullScreen) {\n      theBox.setAttribute(\"full-screen\", true);\n    } else {\n      theBox.removeAttribute(\"full-screen\");\n    }\n  });\n</script>\n```",
+              "description": "Whether the box should take up the full screen. Useful when\ndisplaying a dialog in full-screen mode.\n\n```html\n<esp-box>\n  <h2>Box things</h2>\n  <esp-box>\n    <h2>Box in box</h2>\n    <esp-button label=\"Toggle full screen\"></esp-button>\n  </esp-box>\n</esp-box>\n<script>\n  let fullScreen = false;\n  const theBox = findByTagName(\"esp-box\")[0];\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n    fullScreen = !fullScreen;\n\n    if(fullScreen) {\n      theBox.setAttribute(\"full-screen\", true);\n    } else {\n      theBox.removeAttribute(\"full-screen\");\n    }\n  });\n</script>\n```\n\nA full-screen box fills the viewport. Inside a\n[bounded dialog](/components/dialog) it fills exactly the dialog's\nrectangle instead: it takes its position and size from the same\n`--esp-dialog-inset-*` custom properties, set on the `esp-dialog` or any\nancestor of the box.\n\n```html\n<style>\n  esp-dialog.bounded-box {\n    --esp-dialog-inset-block-start: 6rem;\n    --esp-dialog-inset-inline-start: 3rem;\n    --esp-dialog-inset-inline-end: 3rem;\n    --esp-dialog-inset-block-end: 2rem;\n  }\n</style>\n<esp-dialog class=\"bounded-box\" full-screen>\n  <esp-box full-screen>\n    <h2>Box in a bounded dialog</h2>\n    <p>This box fills the rectangle the dialog is bounded to.</p>\n    <esp-button intent=\"danger\" label=\"Close\"></esp-button>\n  </esp-box>\n</esp-dialog>\n<esp-button label=\"Show Dialog\"></esp-button>\n<script>\n  const theDialog = findByTagName(\"esp-dialog\")[0];\n  const buttons = findByTagName(\"esp-button\");\n  buttons[0].addEventListener(\"esp-clicked\", () => {\n    theDialog.toggleOpen();\n  });\n  buttons[1].addEventListener(\"esp-clicked\", () => {\n    theDialog.toggleOpen();\n  });\n</script>\n```",
               "attribute": "full-screen"
             },
             {
@@ -8396,9 +8451,20 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the box should take up the full screen. Useful when\ndisplaying a dialog in full-screen mode.\n\n```html\n<esp-box>\n  <h2>Box things</h2>\n  <esp-box>\n    <h2>Box in box</h2>\n    <esp-button label=\"Toggle full screen\"></esp-button>\n  </esp-box>\n</esp-box>\n<script>\n  let fullScreen = false;\n  const theBox = findByTagName(\"esp-box\")[0];\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n    fullScreen = !fullScreen;\n\n    if(fullScreen) {\n      theBox.setAttribute(\"full-screen\", true);\n    } else {\n      theBox.removeAttribute(\"full-screen\");\n    }\n  });\n</script>\n```",
+              "description": "Whether the box should take up the full screen. Useful when\ndisplaying a dialog in full-screen mode.\n\n```html\n<esp-box>\n  <h2>Box things</h2>\n  <esp-box>\n    <h2>Box in box</h2>\n    <esp-button label=\"Toggle full screen\"></esp-button>\n  </esp-box>\n</esp-box>\n<script>\n  let fullScreen = false;\n  const theBox = findByTagName(\"esp-box\")[0];\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n    fullScreen = !fullScreen;\n\n    if(fullScreen) {\n      theBox.setAttribute(\"full-screen\", true);\n    } else {\n      theBox.removeAttribute(\"full-screen\");\n    }\n  });\n</script>\n```\n\nA full-screen box fills the viewport. Inside a\n[bounded dialog](/components/dialog) it fills exactly the dialog's\nrectangle instead: it takes its position and size from the same\n`--esp-dialog-inset-*` custom properties, set on the `esp-dialog` or any\nancestor of the box.\n\n```html\n<style>\n  esp-dialog.bounded-box {\n    --esp-dialog-inset-block-start: 6rem;\n    --esp-dialog-inset-inline-start: 3rem;\n    --esp-dialog-inset-inline-end: 3rem;\n    --esp-dialog-inset-block-end: 2rem;\n  }\n</style>\n<esp-dialog class=\"bounded-box\" full-screen>\n  <esp-box full-screen>\n    <h2>Box in a bounded dialog</h2>\n    <p>This box fills the rectangle the dialog is bounded to.</p>\n    <esp-button intent=\"danger\" label=\"Close\"></esp-button>\n  </esp-box>\n</esp-dialog>\n<esp-button label=\"Show Dialog\"></esp-button>\n<script>\n  const theDialog = findByTagName(\"esp-dialog\")[0];\n  const buttons = findByTagName(\"esp-button\");\n  buttons[0].addEventListener(\"esp-clicked\", () => {\n    theDialog.toggleOpen();\n  });\n  buttons[1].addEventListener(\"esp-clicked\", () => {\n    theDialog.toggleOpen();\n  });\n</script>\n```",
               "fieldName": "fullScreen"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -8662,7 +8728,7 @@
               "name": "--esp-breadcrumb-separator-color"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -8739,7 +8805,7 @@
                   "text": "void"
                 }
               },
-              "description": "Point every crumb's arrow at the next one and mark the end of the\ntrail.\n\n`isLastElement` is set for every crumb, including one that supplies\nits own separator — that flag drives the current-crumb styling, not\njust the arrow, so skipping it left a custom-separator crumb unable\nto end a trail. Only the arrow itself defers to a custom separator.\n\nA crumb already carrying one of the two arrows below is one this\nelement wrote, so re-pointing it is safe; anything else is the\nconsumer's and is left alone, whenever they set it.\n\nThe emptiness test is a truthiness check rather than a length: Lit\nsets a `type: String` property to `null` when its attribute is\nremoved, and reading `.length` off that throws — reachable as soon\nas this runs again on a slot change."
+              "description": "Keep the end-of-trail state current without replacing custom separators.\n\nEvery crumb needs `isLastElement`, even when it supplies a custom separator.\nOnly separators this component wrote may be repointed. Check emptiness by\ntruthiness: Lit sets a removed String attribute to `null`."
             },
             {
               "kind": "field",
@@ -9493,6 +9559,17 @@
             "description": ""
           },
           "attributes": [
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -10010,7 +10087,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Used to initiate a user action or link to another page.\n\n```html\n<esp-button label=\"Hello there!\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n    showToast({\n      message: `You clicked the button!`,\n      icon: \"info-i\",\n      duration: 2\n    });\n  });\n</script>\n```\n\nHere is each of the button intents:\n\n```html\n<div style=\"display: flex; flex-wrap: wrap; gap: var(--esp-size-padding);\">\n  <esp-button label=\"Neutral\" intent=\"neutral\" collapsed></esp-button>\n  <esp-button label=\"Success\" intent=\"success\" collapsed></esp-button>\n  <esp-button label=\"Warning\" intent=\"warning\" collapsed></esp-button>\n  <esp-button label=\"Danger\" intent=\"danger\" collapsed></esp-button>\n  <esp-button label=\"Info\" intent=\"info\" collapsed></esp-button>\n</div>\n```\n\nUse `icon-position=\"left\"` for a leading icon. The default `\"right\"`\nposition keeps the icon trailing; both positions follow writing direction\nand therefore mirror in RTL.\n\n```html\n<div style=\"display: flex; gap: var(--esp-size-padding);\">\n  <esp-button\n    collapsed\n    label=\"Save\"\n    icon=\"save\"\n    icon-position=\"left\">\n  </esp-button>\n  <esp-button\n    collapsed\n    label=\"Next\"\n    icon=\"arrow-big-right\"\n    icon-position=\"right\">\n  </esp-button>\n</div>\n```",
+          "description": "Triggers an action or links to another page.\n\n```html\n<esp-button label=\"Hello there!\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n    showToast({\n      message: `You clicked the button!`,\n      icon: \"info-i\",\n      duration: 2\n    });\n  });\n</script>\n```\n\nChoose an intent to express the action's status:\n\n```html\n<div style=\"display: flex; flex-wrap: wrap; gap: var(--esp-size-padding);\">\n  <esp-button label=\"Neutral\" intent=\"neutral\" collapsed></esp-button>\n  <esp-button label=\"Success\" intent=\"success\" collapsed></esp-button>\n  <esp-button label=\"Warning\" intent=\"warning\" collapsed></esp-button>\n  <esp-button label=\"Danger\" intent=\"danger\" collapsed></esp-button>\n  <esp-button label=\"Info\" intent=\"info\" collapsed></esp-button>\n</div>\n```\n\nUse `icon-position=\"left\"` for a leading icon. The default `\"right\"`\nposition keeps the icon trailing; both positions follow writing direction\nand therefore mirror in RTL.\n\n```html\n<div style=\"display: flex; gap: var(--esp-size-padding);\">\n  <esp-button\n    collapsed\n    label=\"Save\"\n    icon=\"save\"\n    icon-position=\"left\">\n  </esp-button>\n  <esp-button\n    collapsed\n    label=\"Next\"\n    icon=\"arrow-big-right\"\n    icon-position=\"right\">\n  </esp-button>\n</div>\n```",
           "name": "EspalierButton",
           "cssProperties": [
             {
@@ -10022,7 +10099,7 @@
               "name": "--esp-button-incognito-padding"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -10196,7 +10273,7 @@
               },
               "privacy": "public",
               "default": "false",
-              "description": "Controls whether or not the button is disabled.\n\n```html\n<esp-button disabled label=\"Disabled\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n  alert(\"We will not get here...\");\n});\n</script>\n```",
+              "description": "Disables the button.\n\n```html\n<esp-button disabled label=\"Disabled\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n  alert(\"We will not get here...\");\n});\n</script>\n```",
               "attribute": "disabled",
               "reflects": true
             },
@@ -10275,7 +10352,7 @@
               },
               "privacy": "public",
               "default": "false",
-              "description": "Controls whether or not the button is in a loading state.\nThe button will be disabled and show a spinner while loading\nis true.\n\n```html\n<esp-button label=\"Click me...\" icon=\"save\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", async () => {\n    theButton.loading = true;\n    setTimeout(function() {\n      theButton.loading = false;\n    }, 5000);\n  });\n</script>\n```",
+              "description": "Shows the button's loading state.\nThe button will be disabled and show a spinner while loading\nis true.\n\n```html\n<esp-button label=\"Click me...\" icon=\"save\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", async () => {\n    theButton.loading = true;\n    setTimeout(function() {\n      theButton.loading = false;\n    }, 5000);\n  });\n</script>\n```",
               "attribute": "loading",
               "reflects": true
             },
@@ -11105,7 +11182,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Controls whether or not the button is disabled.\n\n```html\n<esp-button disabled label=\"Disabled\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n  alert(\"We will not get here...\");\n});\n</script>\n```",
+              "description": "Disables the button.\n\n```html\n<esp-button disabled label=\"Disabled\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", () => {\n  alert(\"We will not get here...\");\n});\n</script>\n```",
               "fieldName": "disabled"
             },
             {
@@ -11159,7 +11236,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Controls whether or not the button is in a loading state.\nThe button will be disabled and show a spinner while loading\nis true.\n\n```html\n<esp-button label=\"Click me...\" icon=\"save\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", async () => {\n    theButton.loading = true;\n    setTimeout(function() {\n      theButton.loading = false;\n    }, 5000);\n  });\n</script>\n```",
+              "description": "Shows the button's loading state.\nThe button will be disabled and show a spinner while loading\nis true.\n\n```html\n<esp-button label=\"Click me...\" icon=\"save\"></esp-button>\n<script>\n  const theButton = findByTagName(\"esp-button\")[0];\n  theButton.addEventListener(\"esp-clicked\", async () => {\n    theButton.loading = true;\n    setTimeout(function() {\n      theButton.loading = false;\n    }, 5000);\n  });\n</script>\n```",
               "fieldName": "loading"
             },
             {
@@ -11189,6 +11266,17 @@
               "description": "When true and `button-type` is `\"submit\"`, the enclosing\nform is submitted without running constraint validation.\n\n```html\n<esp-button button-type=\"submit\" formnovalidate label=\"Save Draft\"></esp-button>\n```",
               "fieldName": "formNoValidate"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -12292,6 +12380,17 @@
               "description": "Disables all child checkboxes in the group.",
               "fieldName": "disabled"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -12350,7 +12449,7 @@
           "customElement": true,
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -12449,7 +12548,7 @@
               "name": "--esp-checkbox-focus-shadow"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -13551,6 +13650,17 @@
               "description": "Displays the checkbox in an indeterminate (partial) state.\nClicking the checkbox clears the indeterminate state.",
               "fieldName": "indeterminate"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -14651,6 +14761,17 @@
               "description": "Truncates both text lines to a single ellipsized line.",
               "fieldName": "truncate"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -14717,7 +14838,7 @@
           "customElement": true,
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -17055,6 +17176,17 @@
               "description": "A custom message to display when the picker is required but no\ndate is selected. Defaults to `\"Please select a date.\"` when\nnot set.\n\n```html\n<esp-date-picker required required-message=\"A departure date is required.\"></esp-date-picker>\n```",
               "fieldName": "requiredMessage"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -17121,7 +17253,7 @@
           },
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -17250,7 +17382,7 @@
               "name": "--esp-details-group-color-border"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -18121,6 +18253,17 @@
               "description": "When true (the default), only one item can be open at a\ntime. Set to false to allow multiple items open\nsimultaneously while keeping the grouped visual treatment.",
               "fieldName": "exclusive"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -18208,7 +18351,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A disclosure widget that wraps the native `<details>` and\n`<summary>` elements. Provides themed styling with a custom\nopen/close indicator and smooth transitions. Use\n[esp-details-group](/components/details/group) to create an\naccordion where only one item is open at a time.\n\n```html\n<esp-details summary=\"What is Espalier?\">\n  <p>Espalier is a design system and component library\n  built on Web Components and Lit.</p>\n</esp-details>\n```\n\nDetails pick up zone theming from a `context` attribute on the group\nor any ancestor — see the [theming guide](/espalier-guides/):\n\n```html\n<esp-details-group context=\"quiet\">\n  <esp-details summary=\"Inside the quiet zone\">\n    <p>Zone-correct tokens, contrast enforced by the theme engine.</p>\n  </esp-details>\n</esp-details-group>\n```\n\n### Pre-opened details\n\nSet the `open` attribute to render the details expanded by\ndefault:\n\n```html\n<esp-details summary=\"I start open\" open>\n  <p>This content is visible from the start.</p>\n</esp-details>\n```\n\n### Disabled details\n\n```html\n<esp-details summary=\"Cannot toggle me\" disabled>\n  <p>This content cannot be revealed.</p>\n</esp-details>\n```",
+          "description": "A disclosure widget that wraps the native `<details>` and\n`<summary>` elements. Provides themed styling with a custom\nopen/close indicator and smooth transitions. Use\n[esp-details-group](/components/details/group) to create an\naccordion where only one item is open at a time.\n\nA field fills one layer above the surface it sits on.\nUse `surface-layer=\"1|2|3|4\"` to select the default painted layer.\n\n```html\n<esp-details summary=\"What is Espalier?\">\n  <p>Espalier is a design system and component library\n  built on Web Components and Lit.</p>\n</esp-details>\n```\n\nDetails pick up zone theming from a `context` attribute on the group\nor any ancestor — see the [theming guide](/espalier-guides/):\n\n```html\n<esp-details-group context=\"quiet\">\n  <esp-details summary=\"Inside the quiet zone\">\n    <p>Zone-correct tokens, contrast enforced by the theme engine.</p>\n  </esp-details>\n</esp-details-group>\n```\n\n### Pre-opened details\n\nSet the `open` attribute to render the details expanded by\ndefault:\n\n```html\n<esp-details summary=\"I start open\" open>\n  <p>This content is visible from the start.</p>\n</esp-details>\n```\n\n### Disabled details\n\n```html\n<esp-details summary=\"Cannot toggle me\" disabled>\n  <p>This content cannot be revealed.</p>\n</esp-details>\n```",
           "name": "EspalierDetails",
           "cssProperties": [
             {
@@ -18240,7 +18383,7 @@
               "name": "--esp-details-size-padding"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -19168,6 +19311,17 @@
               "description": "Whether the details element is disabled (cannot be toggled).\n\n```html\n<esp-details summary=\"Locked\" disabled>\n  <p>Cannot be toggled.</p>\n</esp-details>\n```",
               "fieldName": "disabled"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -19263,7 +19417,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Used to focus content modally. By default, on large screens the\ndialog content is centered horizontally near the top of the\nscreen. On small screens, the content always tries to take up\nthe full screen width.\n\nWhen opened, the dialog:\n- Moves focus to the first `[autofocus]` element inside the slotted\n  content, then the first focusable element (or the dialog container\n  itself if none is found).\n- Traps focus so that `Tab` and `Shift+Tab` cycle only through\n  elements inside the dialog.\n- Closes when the user presses `Escape`.\n- Marks all sibling content as `inert` to prevent screen reader\n  and keyboard access to the page behind the overlay.\n- Restores focus to the element that was focused before the\n  dialog was opened.",
+          "description": "Shows content in a modal dialog. By default, on large screens the\ndialog content is centered horizontally near the top of the\nscreen. On small screens, the content always tries to take up\nthe full screen width.\n\nA field fills one layer above the surface it sits on.\nUse `surface-layer=\"1|2|3|4\"` to select the default painted layer.\n\nWhen opened, the dialog:\n- Moves focus to the first `[autofocus]` element inside the slotted\n  content, then the first focusable element (or the dialog container\n  itself if none is found).\n- Traps focus so that `Tab` and `Shift+Tab` cycle only through\n  elements inside the dialog.\n- Closes when the user presses `Escape`.\n- Marks all sibling content as `inert` to prevent screen reader\n  and keyboard access to the page behind the overlay.\n- Restores focus to the element that was focused before the\n  dialog was opened.\n\n### Bounded dialog\n\nA dialog covers the whole viewport by default. Set the four inset custom\nproperties on the `esp-dialog` host to confine it to a rectangle and leave\nthe rest of the page visible, for example to keep a header or a live preview\non screen while a full-screen editor is open. The vellum (the dialog's\nscrolling surface) and its backdrop paint only inside the rectangle, and a\nslotted `esp-box full-screen` fills exactly that rectangle.\n\nThe insets are lengths (`0px`, `4rem`, `var(--header-height)`), not unitless\nnumbers, and they are measured from the viewport edges. They are logical, so\n\"inline start\" is the left edge in left-to-right text and the right edge in\nright-to-left text. Because custom properties inherit, a dialog nested inside\na bounded dialog's markup is bounded the same way unless it sets its own\ninsets.\n\nBounds change only where the dialog paints. What stays reachable is decided\nby the same rules as an unbounded dialog:\n\n- The dialog has no click-outside dismissal, bounded or not. It closes on\n  `Escape`, an `esp-form-dialog-close-requested` event, or `toggleOpen()`, so\n  a click on the uncovered region never counts as an \"outside\" click.\n- The dialog marks `inert` the siblings of its anchor element, not the\n  regions its bounds leave uncovered. The anchor is `esp-page`'s dialog drop\n  zone when the dialog sits in the page's markup, so there the page's\n  internal tracks (header, menus, preview, help, footer) are inert and not\n  clickable even where the dialog does not cover them. A dialog that is a\n  direct child of another component's shadow root is anchored on the nearest\n  ancestor host that has a light-DOM parent, and only that host's siblings\n  go inert; the page around it stays live. A dialog wrapped in an element\n  inside that shadow root is anchored on itself, so its siblings in the\n  wrapper go inert instead.\n- A region that is not inert receives clicks and keyboard focus. The focus\n  trap wraps `Tab` and `Shift+Tab` at the dialog's first and last focusable\n  elements, and `Escape` is handled on the dialog, both only while focus is\n  inside it. A click on an uncovered control moves focus there, and from then\n  on `Tab` continues through the page and `Escape` no longer closes the\n  dialog. Set `inert` on the uncovered regions that must not be reachable\n  while the dialog is open (an inert region is also skipped by screen\n  readers).\n- Bounds assume a horizontal writing mode: the insets are logical, but the\n  dialog's width and height are physical.\n\n```html\n<style>\n  esp-dialog.bounded {\n    --esp-dialog-inset-block-start: 6rem;\n    --esp-dialog-inset-inline-start: 3rem;\n    --esp-dialog-inset-inline-end: 3rem;\n    --esp-dialog-inset-block-end: 2rem;\n  }\n</style>\n<esp-dialog class=\"bounded\" full-screen>\n  <esp-box full-screen>\n    <h2>Bounded dialog</h2>\n    <p>The page above and around this box stays visible.</p>\n    <esp-button intent=\"danger\" label=\"Close\"></esp-button>\n  </esp-box>\n</esp-dialog>\n<esp-button label=\"Show Dialog\"></esp-button>\n<script>\n  const theDialog = findByTagName(\"esp-dialog\")[0];\n  const buttons = findByTagName(\"esp-button\");\n  buttons[0].addEventListener(\"esp-clicked\", () => {\n    theDialog.toggleOpen();\n  });\n  buttons[1].addEventListener(\"esp-clicked\", () => {\n    theDialog.toggleOpen();\n  });\n</script>\n```",
           "name": "EspalierDialog",
           "cssProperties": [
             {
@@ -19273,6 +19427,22 @@
             {
               "description": "The opacity of the dialog overlay background.",
               "name": "--esp-dialog-bg-opacity"
+            },
+            {
+              "description": "The top edge of the area the dialog covers, as a length from the viewport top. Defaults to `0px`.",
+              "name": "--esp-dialog-inset-block-start"
+            },
+            {
+              "description": "The leading edge (left in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`.",
+              "name": "--esp-dialog-inset-inline-start"
+            },
+            {
+              "description": "The trailing edge (right in left-to-right text) of the area the dialog covers, as a length from the viewport edge. Defaults to `0px`.",
+              "name": "--esp-dialog-inset-inline-end"
+            },
+            {
+              "description": "The bottom edge of the area the dialog covers, as a length from the viewport bottom. Defaults to `0px`.",
+              "name": "--esp-dialog-inset-block-end"
             }
           ],
           "slots": [
@@ -19398,6 +19568,13 @@
             }
           ],
           "attributes": [
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth; defaults to layer 3.",
+              "name": "surface-layer"
+            },
             {
               "name": "full-screen",
               "type": {
@@ -19461,71 +19638,87 @@
     },
     {
       "kind": "javascript-module",
-      "path": "dist/file-upload/esp-file-upload.js",
+      "path": "dist/empty-state/esp-empty-state.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "Used to upload files.\n\n```html\n<esp-file-upload choose-text=\"Upload Document\"></esp-file-upload>\n<script>\n  const theFileUpload = findByTagName(\"esp-file-upload\")[0];\n  theFileUpload.addEventListener(\"esp-file-upload-files-selected\", () => {\n    showToast({\n      message: `You selected a file!`,\n      icon: \"info-i\",\n      duration: 2,\n      onClosed: () => {\n        theFileUpload.finishedProcessingFiles();\n      },\n    });\n  });\n</script>\n```",
-          "name": "EspalierFileUpload",
+          "description": "A centered empty-state layout for list, grid, and page-level\nzero-item states.\n\n```html\n<esp-empty-state icon=\"photo-up\">\n  <span slot=\"heading\">No images yet</span>\n  Upload the first image to start building this library.\n  <esp-button slot=\"action\" label=\"Upload Image\"></esp-button>\n</esp-empty-state>\n\n<esp-empty-state size=\"large\" icon=\"users\">\n  <span slot=\"heading\">No members yet</span>\n  Invite teammates when you are ready to collaborate.\n</esp-empty-state>\n```",
+          "name": "EspalierEmptyState",
+          "slots": [
+            {
+              "description": "Primary empty-state message.",
+              "name": "heading"
+            },
+            {
+              "description": "Supporting body text.",
+              "name": ""
+            },
+            {
+              "description": "Optional custom icon. When provided, it overrides the generated SVG from the `icon` attribute.",
+              "name": "icon"
+            },
+            {
+              "description": "Optional call-to-action button or link.",
+              "name": "action"
+            }
+          ],
           "members": [
             {
               "kind": "field",
-              "name": "uploadInput",
+              "name": "iconSlot",
+              "privacy": "private",
+              "default": "new SlottedIconController(this)"
+            },
+            {
+              "kind": "field",
+              "name": "actionSlot",
               "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "processingFiles",
+              "name": "sizeBacker",
               "type": {
-                "text": "boolean"
+                "text": "EspalierEmptyStateSize"
               },
               "privacy": "private",
-              "default": "false"
+              "default": "\"medium\""
             },
             {
               "kind": "field",
-              "name": "accept",
+              "name": "hasSlottedAction",
               "type": {
-                "text": "string"
+                "text": "boolean"
               },
-              "privacy": "public",
-              "default": "\"*\"",
-              "description": "The accepted file types. For example, to allow JPEG, PNG, and WebP images:\n\n`image/jpeg, image/png, image/webp`",
-              "attribute": "accept"
+              "privacy": "private",
+              "default": "false"
             },
             {
               "kind": "field",
-              "name": "chooseText",
+              "name": "icon",
               "type": {
                 "text": "string"
               },
               "privacy": "public",
-              "default": "\"Choose File\"",
-              "description": "The text to display on the button.",
-              "attribute": "choose-text"
+              "default": "\"\"",
+              "description": "Optional icon name from the Espalier SVG sprite.",
+              "attribute": "icon"
             },
             {
               "kind": "field",
-              "name": "multiple",
+              "name": "size",
               "type": {
-                "text": "boolean"
+                "text": "EspalierEmptyStateSize"
               },
               "privacy": "public",
-              "default": "false",
-              "description": "Allow multiple files to be selected.",
-              "attribute": "multiple"
+              "description": "Empty-state scale.",
+              "attribute": "size",
+              "reflects": true
             },
             {
               "kind": "field",
-              "name": "filesSelected",
+              "name": "handleActionSlotChange",
               "privacy": "private"
             },
-            {
-              "kind": "method",
-              "name": "finishedProcessingFiles",
-              "privacy": "public",
-              "description": "The `esp-file-upload-files-selected` event sets the file upload to a processing state.\nCall this method when you have finished processing the selected files\nto reset the file upload."
-            },
             {
               "kind": "field",
               "name": "seedColorBacker",
@@ -20251,42 +20444,34 @@
               }
             }
           ],
-          "events": [
-            {
-              "type": {
-                "text": "CustomEvent<FileList>"
-              },
-              "description": "Fired after the user selects one or more files.",
-              "name": "esp-file-upload-files-selected"
-            }
-          ],
           "attributes": [
             {
-              "name": "accept",
+              "name": "icon",
               "type": {
                 "text": "string"
               },
-              "default": "\"*\"",
-              "description": "The accepted file types. For example, to allow JPEG, PNG, and WebP images:\n\n`image/jpeg, image/png, image/webp`",
-              "fieldName": "accept"
+              "default": "\"\"",
+              "description": "Optional icon name from the Espalier SVG sprite.",
+              "fieldName": "icon"
             },
             {
-              "name": "choose-text",
+              "name": "size",
               "type": {
-                "text": "string"
+                "text": "EspalierEmptyStateSize"
               },
-              "default": "\"Choose File\"",
-              "description": "The text to display on the button.",
-              "fieldName": "chooseText"
+              "description": "Empty-state scale.",
+              "fieldName": "size"
             },
             {
-              "name": "multiple",
               "type": {
-                "text": "boolean"
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
               },
-              "default": "false",
-              "description": "Allow multiple files to be selected.",
-              "fieldName": "multiple"
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
             },
             {
               "name": "scheme",
@@ -20330,31 +20515,31 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
-          "tagName": "esp-file-upload",
-          "customElement": true,
           "docPageTitle": {
-            "name": "File",
-            "description": "Upload"
+            "name": "Empty",
+            "description": "State"
           },
           "docUrl": {
-            "name": "/components/file-upload",
+            "name": "/components/empty-state",
             "description": ""
           },
           "menuGroup": {
-            "name": "Form",
-            "description": "Controls"
+            "name": "Feedback",
+            "description": ""
           },
           "menuLabel": {
-            "name": "File",
-            "description": "Upload"
+            "name": "Empty",
+            "description": "State"
           },
           "menuIcon": {
-            "name": "upload",
+            "name": "box",
             "description": ""
           },
+          "tagName": "esp-empty-state",
+          "customElement": true,
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -20409,111 +20594,96 @@
                 "module": "dist/shared/esp-element-base.js"
               }
             }
-          ]
+          ],
+          "events": []
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierFileUpload",
+          "name": "EspalierEmptyState",
           "declaration": {
-            "name": "EspalierFileUpload",
-            "module": "dist/file-upload/esp-file-upload.js"
+            "name": "EspalierEmptyState",
+            "module": "dist/empty-state/esp-empty-state.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-file-upload",
+          "name": "esp-empty-state",
           "declaration": {
-            "name": "EspalierFileUpload",
-            "module": "dist/file-upload/esp-file-upload.js"
+            "name": "EspalierEmptyState",
+            "module": "dist/empty-state/esp-empty-state.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "dist/empty-state/esp-empty-state.js",
+      "path": "dist/file-upload/esp-file-upload.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "A centered empty-state layout for list, grid, and page-level\nzero-item states.\n\n```html\n<esp-empty-state icon=\"photo-up\">\n  <span slot=\"heading\">No images yet</span>\n  Upload the first image to start building this library.\n  <esp-button slot=\"action\" label=\"Upload Image\"></esp-button>\n</esp-empty-state>\n\n<esp-empty-state size=\"large\" icon=\"users\">\n  <span slot=\"heading\">No members yet</span>\n  Invite teammates when you are ready to collaborate.\n</esp-empty-state>\n```",
-          "name": "EspalierEmptyState",
-          "slots": [
-            {
-              "description": "Primary empty-state message.",
-              "name": "heading"
-            },
-            {
-              "description": "Supporting body text.",
-              "name": ""
-            },
-            {
-              "description": "Optional custom icon. When provided, it overrides the generated SVG from the `icon` attribute.",
-              "name": "icon"
-            },
-            {
-              "description": "Optional call-to-action button or link.",
-              "name": "action"
-            }
-          ],
+          "description": "Used to upload files.\n\n```html\n<esp-file-upload choose-text=\"Upload Document\"></esp-file-upload>\n<script>\n  const theFileUpload = findByTagName(\"esp-file-upload\")[0];\n  theFileUpload.addEventListener(\"esp-file-upload-files-selected\", () => {\n    showToast({\n      message: `You selected a file!`,\n      icon: \"info-i\",\n      duration: 2,\n      onClosed: () => {\n        theFileUpload.finishedProcessingFiles();\n      },\n    });\n  });\n</script>\n```",
+          "name": "EspalierFileUpload",
           "members": [
             {
               "kind": "field",
-              "name": "iconSlot",
-              "privacy": "private",
-              "default": "new SlottedIconController(this)"
-            },
-            {
-              "kind": "field",
-              "name": "actionSlot",
+              "name": "uploadInput",
               "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "sizeBacker",
+              "name": "processingFiles",
               "type": {
-                "text": "EspalierEmptyStateSize"
+                "text": "boolean"
               },
               "privacy": "private",
-              "default": "\"medium\""
+              "default": "false"
             },
             {
               "kind": "field",
-              "name": "hasSlottedAction",
+              "name": "accept",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "privacy": "private",
-              "default": "false"
+              "privacy": "public",
+              "default": "\"*\"",
+              "description": "The accepted file types. For example, to allow JPEG, PNG, and WebP images:\n\n`image/jpeg, image/png, image/webp`",
+              "attribute": "accept"
             },
             {
               "kind": "field",
-              "name": "icon",
+              "name": "chooseText",
               "type": {
                 "text": "string"
               },
               "privacy": "public",
-              "default": "\"\"",
-              "description": "Optional icon name from the Espalier SVG sprite.",
-              "attribute": "icon"
+              "default": "\"Choose File\"",
+              "description": "The text to display on the button.",
+              "attribute": "choose-text"
             },
             {
               "kind": "field",
-              "name": "size",
+              "name": "multiple",
               "type": {
-                "text": "EspalierEmptyStateSize"
+                "text": "boolean"
               },
               "privacy": "public",
-              "description": "Empty-state scale.",
-              "attribute": "size",
-              "reflects": true
+              "default": "false",
+              "description": "Allow multiple files to be selected.",
+              "attribute": "multiple"
             },
             {
               "kind": "field",
-              "name": "handleActionSlotChange",
+              "name": "filesSelected",
               "privacy": "private"
             },
+            {
+              "kind": "method",
+              "name": "finishedProcessingFiles",
+              "privacy": "public",
+              "description": "The `esp-file-upload-files-selected` event sets the file upload to a processing state.\nCall this method when you have finished processing the selected files\nto reset the file upload."
+            },
             {
               "kind": "field",
               "name": "seedColorBacker",
@@ -21239,23 +21409,53 @@
               }
             }
           ],
+          "events": [
+            {
+              "type": {
+                "text": "CustomEvent<FileList>"
+              },
+              "description": "Fired after the user selects one or more files.",
+              "name": "esp-file-upload-files-selected"
+            }
+          ],
           "attributes": [
             {
-              "name": "icon",
+              "name": "accept",
               "type": {
                 "text": "string"
               },
-              "default": "\"\"",
-              "description": "Optional icon name from the Espalier SVG sprite.",
-              "fieldName": "icon"
+              "default": "\"*\"",
+              "description": "The accepted file types. For example, to allow JPEG, PNG, and WebP images:\n\n`image/jpeg, image/png, image/webp`",
+              "fieldName": "accept"
             },
             {
-              "name": "size",
+              "name": "choose-text",
               "type": {
-                "text": "EspalierEmptyStateSize"
+                "text": "string"
               },
-              "description": "Empty-state scale.",
-              "fieldName": "size"
+              "default": "\"Choose File\"",
+              "description": "The text to display on the button.",
+              "fieldName": "chooseText"
+            },
+            {
+              "name": "multiple",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Allow multiple files to be selected.",
+              "fieldName": "multiple"
+            },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
             },
             {
               "name": "scheme",
@@ -21299,31 +21499,31 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
+          "tagName": "esp-file-upload",
+          "customElement": true,
           "docPageTitle": {
-            "name": "Empty",
-            "description": "State"
+            "name": "File",
+            "description": "Upload"
           },
           "docUrl": {
-            "name": "/components/empty-state",
+            "name": "/components/file-upload",
             "description": ""
           },
           "menuGroup": {
-            "name": "Feedback",
-            "description": ""
+            "name": "Form",
+            "description": "Controls"
           },
           "menuLabel": {
-            "name": "Empty",
-            "description": "State"
+            "name": "File",
+            "description": "Upload"
           },
           "menuIcon": {
-            "name": "box",
+            "name": "upload",
             "description": ""
           },
-          "tagName": "esp-empty-state",
-          "customElement": true,
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -21378,25 +21578,24 @@
                 "module": "dist/shared/esp-element-base.js"
               }
             }
-          ],
-          "events": []
+          ]
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierEmptyState",
+          "name": "EspalierFileUpload",
           "declaration": {
-            "name": "EspalierEmptyState",
-            "module": "dist/empty-state/esp-empty-state.js"
+            "name": "EspalierFileUpload",
+            "module": "dist/file-upload/esp-file-upload.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-empty-state",
+          "name": "esp-file-upload",
           "declaration": {
-            "name": "EspalierEmptyState",
-            "module": "dist/empty-state/esp-empty-state.js"
+            "name": "EspalierFileUpload",
+            "module": "dist/file-upload/esp-file-upload.js"
           }
         }
       ]
@@ -21407,7 +21606,7 @@
       "declarations": [
         {
           "kind": "class",
-          "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 `COMPACT_VIEWPORT_MEDIA_QUERY` (the\n   same breakpoint 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(\"esp-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(\"esp-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(\"esp-clicked\", () => dockedFlyout.toggle());\n</script>\n```\n\nBelow `COMPACT_VIEWPORT_MEDIA_QUERY` 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(\"esp-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-main-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(\"esp-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(\"esp-clicked\", () => {\n    showFlyout({\n      heading: \"Pears\",\n      content: pearsDescription.content.cloneNode(true),\n      anchor: pearsButton,\n    });\n  });\n</script>\n```",
+          "description": "A panel for help and additional information. Uses spare page width when\navailable and switches to an overlay when the workspace cannot fit it.\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 `COMPACT_VIEWPORT_MEDIA_QUERY` (the\n   same breakpoint 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(\"esp-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(\"esp-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(\"esp-clicked\", () => dockedFlyout.toggle());\n</script>\n```\n\nBelow `COMPACT_VIEWPORT_MEDIA_QUERY` 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(\"esp-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-main-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(\"esp-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(\"esp-clicked\", () => {\n    showFlyout({\n      heading: \"Pears\",\n      content: pearsDescription.content.cloneNode(true),\n      anchor: pearsButton,\n    });\n  });\n</script>\n```",
           "name": "EspalierFlyout",
           "cssProperties": [
             {
@@ -21435,7 +21634,7 @@
               "name": "--esp-flyout-z-index"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -22866,6 +23065,17 @@
               "description": "Which containing page owns anchored bus requests.\n\n- `\"outermost\"` (default) routes to the flyout in the outermost\n  `esp-page` containing the request trigger.\n- `\"nearest\"` explicitly gives this flyout precedence for requests\n  originating in its own page or nested descendants.\n\nA `scope=\"nearest\"` flyout must be a light-DOM descendant of the\n`esp-page` whose requests it owns so that page can discover it.\n\nRequests without an `anchor` or `returnFocusTo` have no local context,\nso only outermost page flyouts service them. Use the instance API for\na directly controlled nested flyout.",
               "fieldName": "scope"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -22997,7 +23207,7 @@
               "name": "--esp-focus-picker-focus-outline"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -23981,6 +24191,17 @@
               "description": "Aspect ratio for the compact live preview.",
               "fieldName": "compactRatio"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -25108,6 +25329,17 @@
               "description": "The placeholder text for the picker input.",
               "fieldName": "placeholder"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -25174,7 +25406,7 @@
           },
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -25472,7 +25704,7 @@
               "name": "--esp-footer-row-gap"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -26287,6 +26519,17 @@
             "description": ""
           },
           "attributes": [
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -27122,6 +27365,17 @@
               "description": "Visible heading for the link group. It also labels the navigation\nlandmark. When omitted, the landmark receives the fallback label\n“Footer links” without rendering an empty heading.",
               "fieldName": "heading"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -27184,7 +27438,7 @@
           },
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -27268,7 +27522,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A responsive site footer with structured spaces for branding, feature\nartwork, link groups, supporting actions, and legal or utility content.\nIts background remains full-bleed while its content automatically aligns\nto the surface of a containing [`<esp-page>`](/components/page/).\nThe decorative background uses the same internal visual-layer primitive as\n`esp-image` banners; the footer's public background tokens are unchanged.\n\nUse bare [`<esp-footer-link-group>`](/components/footer/link-group/) children\nwhen navigation groups should auto-flow independently through the grid.\n`columns` is a maximum: the grid always drops columns when they no longer fit.\n\n```html\n<esp-footer\n  light-brand-logo=\"/assets/logo-light.svg\"\n  dark-brand-logo=\"/assets/logo-dark.svg\"\n  brand-text=\"Espalier\"\n  brand-href=\"/\"\n  brand-alt=\"Espalier logo\"\n  light-brand-color=\"oklch(0.35 0.12 216)\"\n  dark-brand-color=\"oklch(0.9 0.08 216)\"\n  columns=\"3\">\n  <esp-footer-link-group heading=\"Explore\">\n    <a href=\"/components\">Components</a>\n    <a href=\"/api\">API</a>\n  </esp-footer-link-group>\n  <esp-footer-link-group heading=\"Learn\">\n    <a href=\"/guides/getting-started\">Getting started</a>\n    <a href=\"/guides/styling\">Styling</a>\n  </esp-footer-link-group>\n  <p slot=\"aside\">Themeable web components built on web standards.</p>\n  <div slot=\"bottom\">Copyright 2026 Example Organization</div>\n</esp-footer>\n```\n\nFor creator-controlled columns, wrap each ordered stack of groups in\n[`<esp-footer-column>`](/components/footer/column/). Each wrapper is one grid\nitem at wide sizes; below the footer's compact container breakpoint, the\ncolumns become full-width rows in their slotted order. `columns` remains the\nmaximum number of grid items per row:\n\n```html\n<esp-footer columns=\"3\">\n  <esp-footer-column>\n    <esp-footer-link-group heading=\"Product\">\n      <a href=\"/features\">Features</a>\n      <a href=\"/pricing\">Pricing</a>\n    </esp-footer-link-group>\n    <esp-footer-link-group heading=\"Company\">\n      <a href=\"/about\">About</a>\n      <a href=\"/careers\">Careers</a>\n    </esp-footer-link-group>\n  </esp-footer-column>\n  <esp-footer-column>\n    <esp-footer-link-group heading=\"Resources\">\n      <a href=\"/docs\">Documentation</a>\n      <a href=\"/support\">Support</a>\n    </esp-footer-link-group>\n  </esp-footer-column>\n</esp-footer>\n```\n\nA slotted brand replaces configured branding, while the media slot accepts\na responsive `picture`, native image, or `esp-image`. Media spans the\nsurface-aligned content well; use the decorative background layer for\nedge-to-edge artwork:\n\n```html\n<esp-footer columns=\"4\">\n  <picture slot=\"media\">\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"/assets/canvas-bg-dark.jpg\" />\n    <img\n      src=\"/assets/canvas-bg.jpg\"\n      alt=\"A colorful floral pattern\"\n      style=\"display: block; width: 100%; height: auto;\" />\n  </picture>\n  <a slot=\"brand\" href=\"/\" aria-label=\"Espalier home\">\n    <img src=\"/assets/espalier-logo.svg\" alt=\"Espalier\" />\n  </a>\n  <esp-footer-link-group heading=\"Product\">\n    <a href=\"/components\">Components</a>\n  </esp-footer-link-group>\n</esp-footer>\n```\n\nDecorative art uses an image layer independent of the base color. The same\nAPI supports a repeating landscape band or one large cover image:\n\n```html\n<style>\n  esp-footer.mountains {\n    --esp-footer-background: oklch(0.48 0.12 145);\n    --esp-footer-background-image-opacity: 0.55;\n    --esp-footer-background-image:\n      linear-gradient(to bottom, transparent 8rem, oklch(0.48 0.12 145)),\n      url(\"/assets/espalier-geometric-texture.png\");\n    --esp-footer-background-repeat: no-repeat, repeat-x;\n    --esp-footer-background-position: 0 0, top;\n    --esp-footer-background-size: 100% 100%, auto 10rem;\n    --esp-footer-padding-block: 6rem;\n  }\n\n  esp-footer.photo {\n    --esp-footer-background: oklch(0.2 0.04 216);\n    --esp-footer-heading-color: white;\n    --esp-footer-background-image:\n      linear-gradient(oklch(0.1 0 0 / 0.55), oklch(0.1 0 0 / 0.55)),\n      url(\"/assets/canvas-bg.jpg\");\n    --esp-footer-background-repeat: no-repeat;\n    --esp-footer-background-position: center;\n    --esp-footer-background-size: cover;\n  }\n</style>\n<esp-footer class=\"mountains\" brand-text=\"Mountain Studio\"></esp-footer>\n<esp-footer class=\"photo\" brand-text=\"Photo Studio\"></esp-footer>\n```\n\nSurface alignment is automatic inside `esp-page`; opt out only when the\nfooter's content should also span the entire bar:\n\n```html\n<esp-page align=\"center\" style=\"--esp-page-main-max-width: 36rem;\">\n  <main>Surface-aligned page content</main>\n  <esp-footer slot=\"footer\" brand-text=\"Aligned Studio\" columns=\"3\">\n    <esp-footer-link-group heading=\"Explore\">\n      <a href=\"/work\">Work</a>\n      <a href=\"/about\">About</a>\n    </esp-footer-link-group>\n  </esp-footer>\n</esp-page>\n\n<esp-footer full-bleed-content brand-text=\"Full-width Studio\"></esp-footer>\n```",
+          "description": "A responsive site footer with structured spaces for branding, feature\nartwork, link groups, supporting actions, and legal or utility content.\nIts background remains full-bleed while its content automatically aligns\nto the surface of a containing [`<esp-page>`](/components/page/).\nUse bare [`<esp-footer-link-group>`](/components/footer/link-group/) children\nwhen navigation groups should auto-flow independently through the grid.\n`columns` is a maximum: the grid always drops columns when they no longer fit.\n\nA field fills one layer above the surface it sits on.\nUse `surface-layer=\"1|2|3|4\"` to select the default painted layer.\n\n```html\n<esp-footer\n  light-brand-logo=\"/assets/logo-light.svg\"\n  dark-brand-logo=\"/assets/logo-dark.svg\"\n  brand-text=\"Espalier\"\n  brand-href=\"/\"\n  brand-alt=\"Espalier logo\"\n  light-brand-color=\"oklch(0.35 0.12 216)\"\n  dark-brand-color=\"oklch(0.9 0.08 216)\"\n  columns=\"3\">\n  <esp-footer-link-group heading=\"Explore\">\n    <a href=\"/components\">Components</a>\n    <a href=\"/api\">API</a>\n  </esp-footer-link-group>\n  <esp-footer-link-group heading=\"Learn\">\n    <a href=\"/guides/getting-started\">Getting started</a>\n    <a href=\"/guides/styling\">Styling</a>\n  </esp-footer-link-group>\n  <p slot=\"aside\">Themeable web components built on web standards.</p>\n  <div slot=\"bottom\">Copyright 2026 Example Organization</div>\n</esp-footer>\n```\n\nFor creator-controlled columns, wrap each ordered stack of groups in\n[`<esp-footer-column>`](/components/footer/column/). Each wrapper is one grid\nitem at wide sizes; below the footer's compact container breakpoint, the\ncolumns become full-width rows in their slotted order. `columns` remains the\nmaximum number of grid items per row:\n\n```html\n<esp-footer columns=\"3\">\n  <esp-footer-column>\n    <esp-footer-link-group heading=\"Product\">\n      <a href=\"/features\">Features</a>\n      <a href=\"/pricing\">Pricing</a>\n    </esp-footer-link-group>\n    <esp-footer-link-group heading=\"Company\">\n      <a href=\"/about\">About</a>\n      <a href=\"/careers\">Careers</a>\n    </esp-footer-link-group>\n  </esp-footer-column>\n  <esp-footer-column>\n    <esp-footer-link-group heading=\"Resources\">\n      <a href=\"/docs\">Documentation</a>\n      <a href=\"/support\">Support</a>\n    </esp-footer-link-group>\n  </esp-footer-column>\n</esp-footer>\n```\n\nA slotted brand replaces configured branding, while the media slot accepts\na responsive `picture`, native image, or `esp-image`. Media spans the\nsurface-aligned content well; use the decorative background layer for\nedge-to-edge artwork:\n\n```html\n<esp-footer columns=\"4\">\n  <picture slot=\"media\">\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"/assets/canvas-bg-dark.jpg\" />\n    <img\n      src=\"/assets/canvas-bg.jpg\"\n      alt=\"A colorful floral pattern\"\n      style=\"display: block; width: 100%; height: auto;\" />\n  </picture>\n  <a slot=\"brand\" href=\"/\" aria-label=\"Espalier home\">\n    <img src=\"/assets/espalier-logo.svg\" alt=\"Espalier\" />\n  </a>\n  <esp-footer-link-group heading=\"Product\">\n    <a href=\"/components\">Components</a>\n  </esp-footer-link-group>\n</esp-footer>\n```\n\nDecorative art uses an image layer independent of the base color. The same\nAPI supports a repeating landscape band or one large cover image:\n\n```html\n<style>\n  esp-footer.mountains {\n    --esp-footer-background: oklch(0.48 0.12 145);\n    --esp-footer-background-image-opacity: 0.55;\n    --esp-footer-background-image:\n      linear-gradient(to bottom, transparent 8rem, oklch(0.48 0.12 145)),\n      url(\"/assets/espalier-geometric-texture.png\");\n    --esp-footer-background-repeat: no-repeat, repeat-x;\n    --esp-footer-background-position: 0 0, top;\n    --esp-footer-background-size: 100% 100%, auto 10rem;\n    --esp-footer-padding-block: 6rem;\n  }\n\n  esp-footer.photo {\n    --esp-footer-background: oklch(0.2 0.04 216);\n    --esp-footer-heading-color: white;\n    --esp-footer-background-image:\n      linear-gradient(oklch(0.1 0 0 / 0.55), oklch(0.1 0 0 / 0.55)),\n      url(\"/assets/canvas-bg.jpg\");\n    --esp-footer-background-repeat: no-repeat;\n    --esp-footer-background-position: center;\n    --esp-footer-background-size: cover;\n  }\n</style>\n<esp-footer class=\"mountains\" brand-text=\"Mountain Studio\"></esp-footer>\n<esp-footer class=\"photo\" brand-text=\"Photo Studio\"></esp-footer>\n```\n\nSurface alignment is automatic inside `esp-page`; opt out only when the\nfooter's content should also span the entire bar:\n\n```html\n<esp-page align=\"center\" style=\"--esp-page-main-max-width: 36rem;\">\n  <main>Surface-aligned page content</main>\n  <esp-footer slot=\"footer\" brand-text=\"Aligned Studio\" columns=\"3\">\n    <esp-footer-link-group heading=\"Explore\">\n      <a href=\"/work\">Work</a>\n      <a href=\"/about\">About</a>\n    </esp-footer-link-group>\n  </esp-footer>\n</esp-page>\n\n<esp-footer full-bleed-content brand-text=\"Full-width Studio\"></esp-footer>\n```",
           "name": "EspalierFooter",
           "cssProperties": [
             {
@@ -27372,7 +27626,7 @@
               "name": "--esp-footer-content-lead"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -28489,6 +28743,17 @@
               "description": "Optional accessible label for pages containing multiple footer landmarks.",
               "fieldName": "landmarkLabel"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -30146,7 +30411,7 @@
         },
         {
           "kind": "class",
-          "description": "Renders data in a table. Specify grid column definitions by\nadding [esp-grid-column](/components/grid/grid-column) elements to\nthe default slot.",
+          "description": "Renders data in a table. Specify grid column definitions by\nadding [esp-grid-column](/components/grid/grid-column) elements to\nthe default slot.\n\nA field fills one layer above the surface it sits on.\nUse `surface-layer=\"1|2|3|4\"` to select the default painted layer.",
           "name": "EspalierGrid",
           "cssProperties": [
             {
@@ -30202,7 +30467,7 @@
               "name": "--esp-grid-link-hover-color"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -31930,6 +32195,17 @@
               "description": "The fields to include when filtering results. It defaults to\nan empty array, which includes all fields. The test dataset\nincludes an address field that is not displayed, so to only\nfilter results by fields displayed in the grid, specify those\nfields in the `search-fields` attribute.\n\n> **Warning:** When specifying arrays in plain HTML, the attributes\n> should be wrapped in single quotes.\n\n```html\n<esp-grid\n  data-url=\"/assets/data/grid-data.json\"\n  search-fields='[\"first_name\", \"last_name\"]'>\n  <esp-grid-column header=\"Id\" field-name=\"id\" text-align=\"right\" sortable sort-type=\"number\"></esp-grid-column>\n  <esp-grid-column header=\"Name\" sort-field=\"first_name\" sortable>\n    <a href=\"mailto:${email}\">${first_name} ${last_name}</a>\n  </esp-grid-column>\n</esp-grid>\n```",
               "fieldName": "searchFields"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -32124,7 +32400,7 @@
               },
               "privacy": "public",
               "default": "null",
-              "description": "Id of the region this button controls, forwarded to the inner\n`<button>`.\n\nThe host is not the control — it has no tabindex and no key handling, so\nthe native button inside the shadow root is what assistive technology and\nrole-based locators resolve to. State set on the host has no path to it\nunless the component carries it across, which is what this does.\n\nForwarding the string is not the same as forwarding the relationship: an\nid reference resolves only within the referring element's own tree, so a\ntarget outside this button's shadow root stays unresolved. ESP0222 tracks\ncarrying a resolved element reference instead.\n\n`ariaControls` is deliberately not an `override`: `ARIAMixin` carries\n`ariaControlsElements`, not a string reflection, so there is no base\nmember to override. If a future lib adds one, `noImplicitOverride` will\nsay so here.",
+              "description": "Id of the controlled region, forwarded to the inner native button.\n\nAssistive technology and role locators target that button, so host state must\nbe forwarded. A string id reference still cannot resolve a target outside\nits shadow root; ESP0222 tracks forwarding a resolved element reference.\n\n`ariaControls` has no base string member in the current DOM types. Keep it\nwithout `override`; `noImplicitOverride` will flag a future base declaration.",
               "attribute": "aria-controls"
             },
             {
@@ -32187,7 +32463,7 @@
                 "text": "string | null"
               },
               "default": "null",
-              "description": "Id of the region this button controls, forwarded to the inner\n`<button>`.\n\nThe host is not the control — it has no tabindex and no key handling, so\nthe native button inside the shadow root is what assistive technology and\nrole-based locators resolve to. State set on the host has no path to it\nunless the component carries it across, which is what this does.\n\nForwarding the string is not the same as forwarding the relationship: an\nid reference resolves only within the referring element's own tree, so a\ntarget outside this button's shadow root stays unresolved. ESP0222 tracks\ncarrying a resolved element reference instead.\n\n`ariaControls` is deliberately not an `override`: `ARIAMixin` carries\n`ariaControlsElements`, not a string reflection, so there is no base\nmember to override. If a future lib adds one, `noImplicitOverride` will\nsay so here.",
+              "description": "Id of the controlled region, forwarded to the inner native button.\n\nAssistive technology and role locators target that button, so host state must\nbe forwarded. A string id reference still cannot resolve a target outside\nits shadow root; ESP0222 tracks forwarding a resolved element reference.\n\n`ariaControls` has no base string member in the current DOM types. Keep it\nwithout `override`; `noImplicitOverride` will flag a future base declaration.",
               "fieldName": "ariaControls"
             },
             {
@@ -32254,7 +32530,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Used to build the top navigation for a site. An empty header\ndisplays a bar. It has three slots for populating header content:\n`topbar`, `brand`, `menu`, and `buttons`.\n\nThe header works together with several companion components:\n[`<esp-menu>`](/components/menu/) provides the navigation\ncontainer, [`<esp-menu-item>`](/components/menu/item/)\nrenders individual links, and\n[`<esp-header-button>`](/components/header/button/) adds icon\nbuttons for global actions.\n\n```html\n<esp-header>\n  <div slot=\"brand\" style=\"background-color: red;\" class=\"header-example\">brand</div>\n  <esp-menu slot=\"menu\" mode=\"horizontal\" style=\"background-color: green;\">\n    <esp-menu-item label=\"menu\" url=\"#\"></esp-menu-item>\n  </esp-menu>\n  <div slot=\"buttons\" style=\"background-color: yellow;\" class=\"header-example\">buttons</div>\n</esp-header>\n```",
+          "description": "Builds a site's top navigation bar. Use its four slots to add content:\n`topbar`, `brand`, `menu`, and `buttons`.\n\nA field fills one layer above the surface it sits on.\nUse `surface-layer=\"1|2|3|4\"` to select the default painted layer.\n\nThe header works together with several companion components:\n[`<esp-menu>`](/components/menu/) provides the navigation\ncontainer, [`<esp-menu-item>`](/components/menu/item/)\nrenders individual links, and\n[`<esp-header-button>`](/components/header/button/) adds icon\nbuttons for global actions.\n\n```html\n<esp-header>\n  <div slot=\"brand\" style=\"background-color: red;\" class=\"header-example\">brand</div>\n  <esp-menu slot=\"menu\" mode=\"horizontal\" style=\"background-color: green;\">\n    <esp-menu-item label=\"menu\" url=\"#\"></esp-menu-item>\n  </esp-menu>\n  <div slot=\"buttons\" style=\"background-color: yellow;\" class=\"header-example\">buttons</div>\n</esp-header>\n```",
           "name": "EspalierHeader",
           "cssProperties": [
             {
@@ -32418,7 +32694,7 @@
               "name": "--esp-header-button-stroke-width"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -34245,6 +34521,17 @@
               "description": "Opt out of surface alignment. When an `esp-header` is slotted into an\n`esp-page`, it constrains its bar content to the page's content\nsurface by default (the bar background stays full-bleed). Set this to\nlet the content span the full width instead, as it did before the\npage grew alignment modes. Standalone headers (outside `esp-page`) are\nalready full-bleed and unaffected.",
               "fieldName": "fullBleedContent"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -35252,6 +35539,17 @@
               "description": "Whether this button's exact help topic is currently showing.",
               "fieldName": "active"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -35318,7 +35616,7 @@
           "customElement": true,
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -36400,7 +36698,7 @@
           "customElement": true,
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -36457,6 +36755,17 @@
             }
           ],
           "attributes": [
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -36851,7 +37160,7 @@
               "name": "--esp-image-overlay-text-shadow"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -37612,7 +37921,7 @@
                   }
                 }
               ],
-              "description": "Grow the frame past its ratio when its copy would be clipped, and give\nthe ratio back once the copy fits again with its spacing (padding and\nmargins). Between the two the banner keeps its current state, so it\ncannot oscillate. A\nbanner only grows from a frame its ratio sizes: an explicit, capped, or\nstretched block size wins, as it always has.\n\nGrowth must take effect, and keep taking effect:\n- The first measurement after growing checks that the frame did not\n  widen. A banner sized by its content would widen, fit, shrink back,\n  and loop. (A frame that narrows, as when growing adds a classic\n  scrollbar, is not that loop; it simply stays grown.)\n- Every measurement while grown (including on a viewport resize, see\n  handleWindowResize) checks that the host grew with the frame. A\n  max-block-size cap would clip the end of the copy and crop the image\n  over a box nobody sees.\nEither failure returns the banner to its ratio and blocks growth until\nthe frame width or the host's max-block-size changes. The rollback\nwaits a frame, so a failed growth never loops inside one delivery.\n\nGrowing itself happens inside the observer callback, so the grown\nlayout paints in the same frame (no flash of clipped copy, no shift\nafter a static first paint). The host's own width observer then sees\nits height change in that delivery, and Chrome may log one benign\n\"ResizeObserver loop completed with undelivered notifications\" per\ngrowth; deferring growth a frame would trade that for a visible shift.\n\nReturns whether the state changed now (a re-render follows)."
+              "description": "Grow a ratio-sized banner when its text would be clipped; restore the ratio\nwhen the copy and its spacing fit again. Use separate grow and shrink checks\nto avoid oscillation. Explicit, capped, or stretched block sizes take precedence.\n\nAfter growth, verify that the frame did not widen and that the host grew\nwith it. Content-sized width can create a grow/shrink loop, while a host cap\ncan leave copy clipped outside the visible image. Roll back either failure\non the next frame, then retry after the width or cap changes.\n\nGrow in the observer callback to avoid a painted frame with clipped copy.\nChrome may report one benign ResizeObserver notification warning per growth;\ndeferring growth would introduce a visible shift.\n\nReturns whether the state changed and needs a render."
             },
             {
               "kind": "method",
@@ -38685,6 +38994,17 @@
               "description": "Aspect ratio used below the component-relative compact threshold.",
               "fieldName": "compactRatio"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -39179,7 +39499,7 @@
               "name": "--esp-image-picker-option-height"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -40357,6 +40677,17 @@
               "description": "The name used when this picker participates in a `<form>`.",
               "fieldName": "name"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -40460,7 +40791,7 @@
               "name": "--esp-image-preview-overlay-text"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -41620,6 +41951,17 @@
               "description": "Whether the upload for this image has failed.\nShows an error overlay with a retry button.",
               "fieldName": "failed"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -41699,7 +42041,7 @@
               "name": "--esp-image-upload-preview-background"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -43079,6 +43421,17 @@
               },
               "fieldName": "maxRowHeightVh"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -43259,7 +43612,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Used to show an informational message.\n\n```html\n<esp-info>\n  Info defaults to intent=\"info\" and its informational surface treatment.\n</esp-info>\n```",
+          "description": "Shows an informational or status message.\n\nA field fills one layer above the surface it sits on.\n\n```html\n<esp-info>\n  Info defaults to intent=\"info\" and its informational surface treatment.\n</esp-info>\n```",
           "name": "EspalierInfo",
           "cssProperties": [
             {
@@ -43275,7 +43628,7 @@
               "name": "--esp-info-color-text"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -44123,6 +44476,17 @@
               "description": "If an info box is destroyable, it has a button that will fire the\n`esp-info-destroy` event when clicked.\n\n```html\n<esp-info destroyable>\n  I am destroyable.\n</esp-info>\n```",
               "fieldName": "destroyable"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -45893,6 +46257,17 @@
               "description": "Space-separated list of region codes that defines which\nphone localities are accepted for `input-type=\"tel\"`. The\nfirst locality whose format matches wins. When omitted,\ndefaults to a set of 10 common regions.\n\n```html\n<esp-input input-type=\"tel\" tel-localities=\"US CA GB\"></esp-input>\n```",
               "fieldName": "telLocalities"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -45959,7 +46334,7 @@
           },
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -46158,7 +46533,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A full-screen lightbox for viewing high-res versions of\n[esp-image](/components/image) elements. Point the `for` attribute\nat a CSS selector for the container that holds the images. Clicking\nany image in that container opens the lightbox at that image.\n\nOn mobile, swipe left or right to navigate. The gallery wraps\naround — swiping past the last image goes back to the first.\n\nA subtle caret at the bottom of the screen reveals a drawer\noverlay containing the image caption and a `comments` slot.\n\nBoth halves of that panel are optional. `hide-comments` drops the\ncomment count and the `comments` slot; `hide-caption` drops the\nimage caption. With only the caption left, the bar shows it on one\nline and slides up only when the line is actually clipped — a\ncaption that already fits has no caret and no tab stop. With both\nhidden there is no bar, though navigation dots remain for a\nmulti-image gallery.\n\n```html\n<esp-lightbox for=\".gallery\" hide-comments></esp-lightbox>\n```\n\n```html\n<div class=\"gallery\">\n  <esp-image caption=\"A mountain lake\" original-width=\"1200\" original-height=\"800\" low-res=\"https://picsum.photos/id/29/300/200\">\n    <esp-image-option width=\"400\" url=\"https://picsum.photos/id/29/600/400\"></esp-image-option>\n    <esp-image-option width=\"800\" url=\"https://picsum.photos/id/29/900/600\"></esp-image-option>\n    <esp-image-option width=\"1024\" url=\"https://picsum.photos/id/29/1200/800\"></esp-image-option>\n  </esp-image>\n  <esp-image caption=\"A forest path\" original-width=\"1200\" original-height=\"800\" low-res=\"https://picsum.photos/id/15/300/200\">\n    <esp-image-option width=\"400\" url=\"https://picsum.photos/id/15/600/400\"></esp-image-option>\n    <esp-image-option width=\"800\" url=\"https://picsum.photos/id/15/900/600\"></esp-image-option>\n    <esp-image-option width=\"1024\" url=\"https://picsum.photos/id/15/1200/800\"></esp-image-option>\n  </esp-image>\n  <esp-image caption=\"Ocean waves\" original-width=\"1200\" original-height=\"800\" low-res=\"https://picsum.photos/id/65/300/200\">\n    <esp-image-option width=\"400\" url=\"https://picsum.photos/id/65/600/400\"></esp-image-option>\n    <esp-image-option width=\"800\" url=\"https://picsum.photos/id/65/900/600\"></esp-image-option>\n    <esp-image-option width=\"1024\" url=\"https://picsum.photos/id/65/1200/800\"></esp-image-option>\n  </esp-image>\n</div>\n<esp-lightbox for=\".gallery\"></esp-lightbox>\n```",
+          "description": "A full-screen lightbox for viewing high-res versions of\n[esp-image](/components/image) elements. Point the `for` attribute\nat a CSS selector for the container that holds the images. Clicking\nany image in that container opens the lightbox at that image.\n\nA field fills one layer above the surface it sits on.\nUse `surface-layer=\"1|2|3|4\"` to select the default painted layer.\n\nOn mobile, swipe left or right to navigate. The gallery wraps\naround — swiping past the last image goes back to the first.\n\nA subtle caret at the bottom of the screen reveals a drawer\noverlay containing the image caption and a `comments` slot.\n\nBoth halves of that panel are optional. `hide-comments` drops the\ncomment count and the `comments` slot; `hide-caption` drops the\nimage caption. With only the caption left, the bar shows it on one\nline and slides up only when the line is actually clipped — a\ncaption that already fits has no caret and no tab stop. With both\nhidden there is no bar, though navigation dots remain for a\nmulti-image gallery.\n\n```html\n<esp-lightbox for=\".gallery\" hide-comments></esp-lightbox>\n```\n\n```html\n<div class=\"gallery\">\n  <esp-image caption=\"A mountain lake\" original-width=\"1200\" original-height=\"800\" low-res=\"https://picsum.photos/id/29/300/200\">\n    <esp-image-option width=\"400\" url=\"https://picsum.photos/id/29/600/400\"></esp-image-option>\n    <esp-image-option width=\"800\" url=\"https://picsum.photos/id/29/900/600\"></esp-image-option>\n    <esp-image-option width=\"1024\" url=\"https://picsum.photos/id/29/1200/800\"></esp-image-option>\n  </esp-image>\n  <esp-image caption=\"A forest path\" original-width=\"1200\" original-height=\"800\" low-res=\"https://picsum.photos/id/15/300/200\">\n    <esp-image-option width=\"400\" url=\"https://picsum.photos/id/15/600/400\"></esp-image-option>\n    <esp-image-option width=\"800\" url=\"https://picsum.photos/id/15/900/600\"></esp-image-option>\n    <esp-image-option width=\"1024\" url=\"https://picsum.photos/id/15/1200/800\"></esp-image-option>\n  </esp-image>\n  <esp-image caption=\"Ocean waves\" original-width=\"1200\" original-height=\"800\" low-res=\"https://picsum.photos/id/65/300/200\">\n    <esp-image-option width=\"400\" url=\"https://picsum.photos/id/65/600/400\"></esp-image-option>\n    <esp-image-option width=\"800\" url=\"https://picsum.photos/id/65/900/600\"></esp-image-option>\n    <esp-image-option width=\"1024\" url=\"https://picsum.photos/id/65/1200/800\"></esp-image-option>\n  </esp-image>\n</div>\n<esp-lightbox for=\".gallery\"></esp-lightbox>\n```",
           "name": "EspalierLightbox",
           "cssProperties": [
             {
@@ -46178,7 +46553,7 @@
               "name": "--esp-vellum-background-image-opacity"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -47993,6 +48368,17 @@
               "description": "Remove the image caption from the bar and the drawer.",
               "fieldName": "hideCaption"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -48170,7 +48556,7 @@
               "name": "--esp-menu-item-font-family"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -49394,6 +49780,17 @@
               "description": "URL prefix for automatic expansion. If `location.pathname`\nstarts with this value, the group opens on connect.",
               "fieldName": "urlPrefix"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -49565,7 +49962,7 @@
               "name": "--esp-menu-item-icon-size"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -50488,6 +50885,17 @@
               "description": "Optional icon name from the configured Espalier SVG sprite.",
               "fieldName": "icon"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -50631,7 +51039,7 @@
               "name": "--esp-menu-top-offset"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -52472,6 +52880,17 @@
               "description": "Compatibility hook used by `esp-header` when inline navigation\nbecomes too wide. Prefer `mode`/`overflow` in application code.",
               "fieldName": "sliding"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -53602,7 +54021,7 @@
           "type": {
             "text": "array"
           },
-          "default": "[ ...EspalierElementBase.styles, css` :host { --_esp-page-resolved-max-width: var(--esp-page-main-max-width, 1536px); --_esp-page-main-min-width: var(--esp-page-main-min-width, 30rem); --_esp-page-preview-resolved-min-width: var(--esp-page-preview-min-width, 22.5rem); --_esp-page-preview-resolved-max-width: var(--esp-page-preview-max-width, 48rem); --_esp-page-flyout-resolved-min-width: var(--esp-page-flyout-min-width, 20rem); --_esp-page-flyout-resolved-max-width: var(--esp-page-flyout-max-width, 30rem); --_esp-page-preview-used-width: 0px; --_esp-page-flyout-used-width: 0px; --_esp-page-workspace-track: minmax( calc(var(--_esp-page-flyout-min) + var(--_esp-page-preview-min)), calc(var(--_esp-page-preview-used-width) + var(--_esp-page-flyout-used-width)) ); /* The cap sizes the main content *well*: the main track maxes at the cap and the surplus beyond the surface becomes canvas gutters. (Contract preserved from v2.1.0.) */ --_esp-page-main-track: minmax(0, var(--_esp-page-resolved-max-width)); /* Canvas gutter weights (physical left/right in LTR). The flexible gutters claim only the space left once the main track reaches its cap, so they appear exactly when the surface exceeds the cap — at any cap, with no viewport breakpoint (ADR-011). The start default keeps no leading gutter and lets all surplus collect trailing. Empty asides collapse to zero because the header and footer regions are inline-size-contained and no longer leak their min-content into the aside tracks (see the .esp-page-top / .esp-page-footer rules). The fr weights are written as 0fr/1fr (never bare 0) so the track list stays pairwise-interpolable and the flyout open/close can animate via grid track interpolation where supported. */ --_esp-page-gutter-left: 0fr; --_esp-page-gutter-right: 1fr; /* Help and preview share an exact auxiliary workspace track before the outer trailing gutter. Opening help raises that track's safe minimum; the allocator supplies its concrete used width. */ --_esp-page-flyout-min: 0px; /* Preview starts at the surface edge before help. Reclaiming raises this minimum so the auxiliary track reserves both pane floors while the main track retains its own floor. */ --_esp-page-preview-min: 0px; /* A raised surface edge's drop shadow, cast in the trailing (inline-end) direction. The surface mirrors it onto both inline edges; a match-surface flyout casts only this trailing edge, so it lifts off the canvas while staying attached at its leading perforation (no shadow bleeding over the content it flies out from). */ --_esp-page-surface-edge-shadow: 0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow); /* Resolve the surface shadow/border once (public override plus the built-in default) so the value is readable downstream — the surface layer and the match-surface flyout contract both consume it, and it stays a single source of truth. */ --_esp-page-surface-shadow: var( --esp-page-surface-shadow, -0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow), var(--_esp-page-surface-edge-shadow) ); --_esp-page-surface-border: var(--esp-page-surface-border, none); --_esp-page-fixed-header-offset: var( --esp-page-fixed-header-offset, var(--esp-header-height, calc(4.5 * var(--esp-size-small))) ); display: block; } :host([kind=\"narrow\"]) { --_esp-page-resolved-max-width: var(--esp-page-main-max-width, 768px); } :host([align=\"center\"]) { --_esp-page-gutter-left: 1fr; --_esp-page-gutter-right: 1fr; } :host([align=\"end\"]) { --_esp-page-gutter-left: 1fr; --_esp-page-gutter-right: 0fr; } /* Full is unbounded only while the consumer has not supplied the explicit main maximum. The internal marker is synchronized from the computed public token before workspace allocation, allowing a finite full-kind authoring surface to retain normal alignment gutters. */ :host([kind=\"full\"]) { --_esp-page-resolved-max-width: var(--esp-page-main-max-width, none); } :host([kind=\"full\"]:not([data-main-max-configured])) { --_esp-page-main-track: 1fr; --_esp-page-gutter-left: 0fr; --_esp-page-gutter-right: 0fr; } /* Site: the marketing shell (ESP0174). The main region is always unbounded — slotted esp-section bands own their centered wells — so this is the unconfigured-full geometry, unconditionally, and align's gutter weights do not apply. Declared after the align rules so it wins on order. */ :host([kind=\"site\"]) { --_esp-page-resolved-max-width: none; --_esp-page-main-track: 1fr; --_esp-page-gutter-left: 0fr; --_esp-page-gutter-right: 0fr; } /* Flyout placement ladder (ESP0111). Preview and help occupy an exact auxiliary track between the main surface and the outer gutter: 1. spare canvas is converted into the allocated auxiliary track while main remains at its natural maximum 2. help and preview contract to their floors 3. an eligible linked navigation rail yields before the main track narrows toward its minimum 4. if the complete main + preview + help minimums do not fit, JS requests the flyout's existing modal overlay presentation 5. mobile → the media query below releases the minimum and esp-flyout itself becomes a fixed overlay drawer. The flyout-open host attribute is maintained by syncFlyoutState (Blink cannot match :has() inside :host(), so the state is mirrored instead). Declared after the align/kind rules so the open state wins. */ :host([flyout-open]) { --_esp-page-flyout-min: var(--_esp-page-flyout-resolved-min-width); } :host([preview-reclaiming]) { --_esp-page-preview-min: var(--_esp-page-preview-resolved-min-width); } /* Configured defaults and retained drag/keyboard choices participate in the same grid minima as automatic allocation. This lets a target that must reclaim main do so instead of overflowing the gutter, while the allocator still clamps private used widths before they reach Grid. */ :host([flyout-open][data-workspace-targeted]) { --_esp-page-flyout-min: var(--_esp-page-flyout-used-width); } :host([preview-reclaiming][data-workspace-targeted]) { --_esp-page-preview-min: var(--_esp-page-preview-used-width); } :host([flyout-open]), :host([preview-reclaiming]) { --_esp-page-main-track: minmax( var(--_esp-page-main-min-width), var(--_esp-page-resolved-max-width) ); } :host([kind=\"full\"]:not([data-main-max-configured])[flyout-open]), :host([kind=\"full\"]:not([data-main-max-configured])[preview-reclaiming]), :host([kind=\"site\"][flyout-open]), :host([kind=\"site\"][preview-reclaiming]) { --_esp-page-main-track: minmax(var(--_esp-page-main-min-width), 1fr); } /* Deliberate ADR-011 exception: like the esp-menu drawer (same 50em threshold), the flyout's overlay rung is a genuinely viewport-level decision — below it the flyout leaves the grid for a fixed drawer, so the gutter must release the minimum it was reserving. */ @media ${unsafeCSS(COMPACT_VIEWPORT_MEDIA_QUERY)} { :host([flyout-open]) { --_esp-page-flyout-min: 0px; } :host([preview-reclaiming]) { --_esp-page-preview-min: 0px; } :host([flyout-open]), :host([preview-reclaiming]) { --_esp-page-main-track: minmax(0, var(--_esp-page-resolved-max-width)); } :host([kind=\"full\"]:not([data-main-max-configured])[flyout-open]), :host([kind=\"full\"]:not([data-main-max-configured])[preview-reclaiming]), :host([kind=\"site\"][flyout-open]), :host([kind=\"site\"][preview-reclaiming]) { --_esp-page-main-track: 1fr; } .esp-page > .esp-page-preview-space, .esp-page > .esp-page-workspace-resize-handles { display: none; } } /* A forced mode=\"overlay\" flyout is a fixed drawer at any viewport width, so its aside needs the same above-the-header hoist the sub-50em media rule gives the auto-mode drawer — without this the desktop drawer paints beneath the header (aside z 5 vs header z 20). Keyed off the flyout-overlay-open state attribute maintained by syncFlyoutState. */ :host([flyout-overlay-open]) .esp-page > div.esp-page-flyout { z-index: var(--esp-flyout-z-index, 3000); } /* A nested page's fixed drawer still participates in this page's main stacking context. Raise that complete context while the descendant modal is open so the drawer and vellum paint above this page's header instead of trapping their close control beneath it. */ :host([descendant-flyout-overlay-open]) .esp-page > div.esp-page-main { z-index: var(--esp-flyout-z-index, 3000); overflow: visible; } /* Trigger-anchored panels belong to the same document flow as their initiator. BiDirectionalStickyController can keep updating the wrapper's inline top, but position: static deliberately makes it inert until the anchored panel closes. */ :host([flyout-anchored]:not([flyout-full-height])) .esp-page > div.esp-page-flyout > .sticky-wrapper { position: static; } /* Full-document help owns the visible block-size rather than following one field. Span header through footer so the page footer cannot push a viewport-height panel out of view at the document boundary; the sticky controller pins this presentation to the viewport top. */ :host([flyout-full-height]) .esp-page > div.esp-page-flyout { grid-row: top-start / footer-end; z-index: calc(var(--esp-page-header-z-index, 20) + 2); } /* Anchored help connects back to its trigger across a visible preview. Raise only the sized help wrapper above the preview surface; the bridge itself is non-interactive inside esp-flyout. */ :host([flyout-anchored][preview-visible]) .esp-page > div.esp-page-flyout { z-index: calc(var(--esp-page-header-z-index, 20) + 2); } slot[name=\"flyout\"]::slotted(esp-flyout) { --_esp-flyout-used-width: var(--_esp-page-flyout-used-width); --_esp-flyout-preview-bridge-width: 0px; --_esp-flyout-preview-anchor-display: none; } :host([preview-visible]) slot[name=\"flyout\"]::slotted(esp-flyout) { --_esp-flyout-preview-bridge-width: var(--_esp-page-preview-used-width); --_esp-flyout-preview-anchor-display: block; } /* Flyout surface-match contract. A slotted esp-flyout with match-surface lifts its trailing edge with the surface's edge shadow, so the panel reads as a raised peer of the content surface rather than the shadowless tear-off. The leading edge keeps its perforation (the border is not overridden) and casts no shadow, so it stays attached at the tear line instead of floating over the content it flies out from. Opt-in and page-scoped: a standalone flyout has no surface to match and is unaffected. */ slot[name=\"flyout\"]::slotted(esp-flyout[match-surface]) { --esp-flyout-shadow: var(--_esp-page-surface-edge-shadow); } /* Header alignment contract. Published on the slotted esp-header (not :host) so it never shadows an inherited or author override and only the header-slot header adopts it — see the host-token-defaults architecture rule and ADR-005. max-width is the resolved cap; lead is the fraction of surplus placed before the content (0 = start, .5 = center, 1 = end). */ slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-max-width: var(--_esp-page-resolved-max-width); --esp-header-content-lead: 0; } :host([align=\"center\"]) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-lead: 0.5; } :host([align=\"end\"]) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-lead: 1; } /* full has no cap; publish 100% (not none) so the header contract calc resolves to zero surplus and leaves the header full-bleed. */ :host([kind=\"full\"]:not([data-main-max-configured])) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-max-width: 100%; } /* Footer alignment mirrors the header behavior with footer-owned contract names. The full-bleed footer paints its own background; only its internal content adopts the page's cap and lead fraction. */ slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-max-width: var(--_esp-page-resolved-max-width); --esp-footer-content-lead: 0; } :host([align=\"center\"]) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-lead: 0.5; } :host([align=\"end\"]) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-lead: 1; } :host([kind=\"full\"]:not([data-main-max-configured])) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-max-width: 100%; } /* Site: bar content aligns with the section wells, not a main cap. One public token governs the header, the footer, and every esp-section well, and the well is centered — declared after the align lead rules so the centered site column wins on order. */ :host([kind=\"site\"]) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-max-width: var(--esp-page-well-max-width, 72rem); --esp-header-content-lead: 0.5; } :host([kind=\"site\"]) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-max-width: var(--esp-page-well-max-width, 72rem); --esp-footer-content-lead: 0.5; } /* Contained shell: the header and footer ride the surface instead of the full viewport, so the whole page reads as one band on the canvas. Only their column placement changes — the full-height canvas and surface layers already do the rest. */ :host([contained]) .esp-page > div.esp-page-top, :host([contained]) .esp-page > div.esp-page-footer { grid-column: surface; } /* On the surface the bar already spans the content width, so the header fills it (no content padding) and drops its own shadow — the continuous surface edge shadow does the framing. */ :host([contained]) slot[name=\"header\"]::slotted(esp-header) { --esp-header-shadow: none; } /* The 100% contract belongs to the capped kinds, where the surface column IS the content width. A contained site keeps the shared well column (ESP0174) — sections and chrome must not split columns just because the shell is contained. */ :host([contained]:not([kind=\"site\"])) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-max-width: 100%; } :host([contained]:not([kind=\"site\"])) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-max-width: 100%; } :host([kind=\"narrow\"]) .esp-page > div.esp-page-main { /* The golden reading measure, from the shared token (ESP0174); 66ch remains the fallback and the default emission. */ > ::slotted(*) { max-inline-size: var(--esp-measure, 66ch); } } #dialog-drop-zone { z-index: 4000; position: absolute; } :host([preview-visible]) .esp-page > div.esp-page-preview-space > .esp-page-preview { display: block; } :host([workspace-resizable][preview-visible]:not([flyout-overlay-open])) .esp-page > div.esp-page-workspace-resize-handles > .esp-page-main-preview-resize-handle, :host([workspace-resizable][flyout-open]:not([flyout-overlay-open])) .esp-page > div.esp-page-workspace-resize-handles > .esp-page-preview-flyout-resize-handle { display: block; } :host([workspace-resizable]:not([data-workspace-resize-ready])) .esp-page > .esp-page-workspace-resize-handles { display: none; } :host([workspace-resizable][data-workspace-trailing-edge-exposed]:not([flyout-overlay-open])) .esp-page > div.esp-page-workspace-resize-handles > .esp-page-workspace-end-resize-handle, :host([workspace-resizable][data-workspace-position-held]:not([flyout-overlay-open])) .esp-page > div.esp-page-workspace-resize-handles > .esp-page-workspace-end-resize-handle { display: block; } /* Pointer-owned resizing controls the logical leading gutter. It stays fixed for zero-sum pane trades and yields as an outward drag consumes centered outside canvas, keeping the active separator under the pointer in both cases. On release JS moves this pixel track to the aligned target; the normal grid transition supplies the glide before the intrinsic fr gutter contract resumes. */ :host([data-workspace-position-held]) { --_esp-page-gutter-left: var(--_esp-page-resize-leading-gutter-width, 0px); --_esp-page-gutter-right: 1fr; } :host([data-workspace-resizing]) { cursor: col-resize; user-select: none; } /* The grid-track glide that makes programmatic open/close feel animated reads as cursor lag while a pointer owns the seam, and a mid-glide grid feeds stale geometry into the clamp ranges of the next keyboard step. Track changes must be immediate for the whole resize session, pointer or keyboard. */ :host([data-workspace-resizing]) .esp-page, :host([data-workspace-keyboard-adjusting]) .esp-page { transition: none; } /* The linked menu switches its rail to a fixed drawer, but light-DOM menu content can still contribute an intrinsic width to the page's sidebar track. Collapse the owning aside only after the validated header/menu handshake is active, so unmatched navigation remains visible and reachable. */ :host([data-preview-navigation-collapsed]) .esp-page > aside.esp-page-left { inline-size: 0; min-inline-size: 0; } :host([data-preview-measuring]) .esp-page { transition: none; } /* New preview layouts are validated against visible geometry before presentation. Keep that candidate surface non-visible so a rejected measurement can never flash on screen. */ :host([data-preview-validating]) .esp-page-preview { visibility: hidden; } .esp-page { /* dvh keeps the shell within the visible mobile viewport; 100vh is the fallback for browsers without dvh (dvh === vh on desktop). */ min-height: 100vh; min-height: 100dvh; display: grid; grid-template-columns: [full-start canvas-left-start] var(--_esp-page-gutter-left) [canvas-left-end surface-start left-start] min-content [left-end main-start] var(--_esp-page-main-track) [main-end right-start] min-content [right-end surface-end canvas-right-start flyout-start] var(--_esp-page-workspace-track) [flyout-end] var(--_esp-page-gutter-right) [canvas-right-end full-end]; /* Animate the flyout claiming/releasing its track (and the gutter rebalance) via grid track interpolation where supported; elsewhere the modes still apply, just without the glide. Keep this 0.25s duration synchronized with WORKSPACE_RECENTER_DURATION in workspace-resize-session.ts. */ transition: grid-template-columns 0.25s ease; grid-template-rows: [top-start] min-content [top-end content-start] 1fr [content-end footer-start] min-content [footer-end]; overflow-x: clip; background: var(--esp-page-background, var(--esp-color-background)); line-height: 1.5; font-family: var( --_esp-font-body-effective, var(--esp-font-body, var(--_esp-font-body-fallback)) ); font-size: var(--esp-type-normal); color: var(--esp-color-text); position: relative; &:before { content: \" \"; display: block; position: absolute; left: 0; top: 0; right: 0; bottom: 0; opacity: var(--esp-page-background-image-opacity, 1); background-image: var(--esp-page-background-image, none); z-index: 1; } > div.esp-page-top { z-index: var(--esp-page-header-z-index, 20); grid-column: full; grid-row: top; position: relative; /* The header spans every column, so without inline-size containment its content's min-content would be distributed into the aside tracks and inflate them below the cap (the asides would never collapse). Contain it like the main well so it takes its width from the grid, not the grid from it. */ contain: inline-size; } /* Sidebar containers — act as the \"track\" for sticky positioning */ aside.esp-page-left, aside.esp-page-right { z-index: 5; grid-row: content; position: relative; /* No explicit height — grid stretch fills the 1fr row, and the aside's bottom edge constrains sticky children. */ } > aside.esp-page-left { grid-column: left; } > div.esp-page-main { z-index: 5; grid-column: main; grid-row: content; position: relative; /* Clip oversized content without becoming a scroll container. A hidden-overflow wrapper traps descendant view timelines (and sticky positioning) on this non-scrolling main well. */ overflow: clip; /* The main well's own background. Defaults to transparent, so the well shows the page background exactly as before; set it to give the content well a distinct card color, or leave it transparent (with --esp-page-surface-shadow: none) for content that floats directly on the page/canvas. */ background: var(--esp-page-main-background, transparent); /* The cap now lives in the main track (minmax(0, cap)); the element fills its column. contain: inline-size still holds because the track gives a definite inline size. */ contain: inline-size; } > aside.esp-page-right { grid-column: right; } /* A neutral div, unlike the left/right asides: the slotted esp-flyout is itself the complementary landmark, and an aside wrapper would nest a second, empty landmark around it. */ > div.esp-page-flyout { /* Sits after preview inside the exact auxiliary track and sizes to the allocated help width. Outer surplus remains in the following gutter rather than under an empty stretched wrapper. */ grid-column: flyout; justify-self: start; grid-row: content; z-index: 5; position: relative; inline-size: var(--_esp-page-flyout-used-width); min-inline-size: 0; margin-inline-start: var(--_esp-page-preview-used-width); /* In the drawer rung the fixed esp-flyout paints inside this wrapper's stacking context, so the wrapper itself must rise above the header (z 20) while staying below the dialog drop zone (4000). Uses the same token as the drawer — set it on the page (or higher) to move both together. */ @media ${unsafeCSS(COMPACT_VIEWPORT_MEDIA_QUERY)} { z-index: var(--esp-flyout-z-index, 3000); } } /* Preview begins at the surface edge and help is offset after its resolved width, producing the logical order main → preview → help inside their exact shared auxiliary track. */ > div.esp-page-preview-space { grid-column: flyout; grid-row: content; z-index: 4; position: relative; min-inline-size: 0; > .esp-page-preview { display: none; box-sizing: border-box; inline-size: var(--_esp-page-preview-used-width); position: relative; background: var( --esp-page-preview-background, var(--esp-page-main-background, var(--esp-page-background, var(--esp-color-background))) ); border-inline-start: var(--esp-page-preview-border, 1px dotted var(--esp-color-border)); box-shadow: var(--esp-page-preview-shadow, var(--_esp-page-surface-edge-shadow)); } } /* A transparent interaction layer keeps the complete hit target above main, preview, and anchored help without raising either painted surface (which would hide the help bridge). */ > div.esp-page-workspace-resize-handles { grid-column: flyout; grid-row: top-start / footer-end; z-index: calc(var(--esp-page-header-z-index, 20) + 3); position: relative; min-inline-size: 0; pointer-events: none; } > div.esp-page-workspace-resize-handles > .esp-page-workspace-resize-handle { display: none; box-sizing: border-box; position: absolute; inset-block: 0; z-index: 3; inline-size: var(--esp-page-resize-handle-hit-size, 2.75rem); margin-inline-start: calc(-0.5 * var(--esp-page-resize-handle-hit-size, 2.75rem)); border: 0; outline: 0; background: transparent; cursor: col-resize; pointer-events: auto; touch-action: none; /* The target spans the seam so it remains reachable during document scroll. Focus draws a dashed line along the seam itself — the visible height of the dotted tear-off edge, capped at one viewport — kept in view by sticky positioning while the page scrolls. */ &::after { content: \"\"; display: block; position: sticky; inset-block-start: 0; box-sizing: border-box; inline-size: 0; margin-inline: auto; block-size: 100dvh; max-block-size: 100%; pointer-events: none; } &:focus-visible::after { border-inline-start: var( --esp-page-resize-focus-outline, 2px dashed var(--esp-color-link) ); /* Glow in the line's own color so the focused seam reads as one deliberate highlight rather than a neutral drop shadow. */ box-shadow: var(--esp-page-resize-focus-shadow, 0 0 0.75rem var(--esp-color-link)); } } > div.esp-page-workspace-resize-handles > .esp-page-main-preview-resize-handle { inset-inline-start: 0; } > div.esp-page-workspace-resize-handles > .esp-page-preview-flyout-resize-handle { inset-inline-start: var(--_esp-page-preview-used-width); } > div.esp-page-workspace-resize-handles > .esp-page-workspace-end-resize-handle { inset-inline-start: calc( var(--_esp-page-preview-used-width) + var(--_esp-page-flyout-used-width) ); } /* Keep token-sized probes outside the width-constrained gutter. If they lived inside a zero-width preview space, layout would clamp their rectangles to zero before JS could decide whether the reclaim rung should be activated. */ > .esp-page-preview-min-width-probe, > .esp-page-preview-default-width-probe, > .esp-page-preview-max-width-probe, > .esp-page-flyout-min-width-probe, > .esp-page-flyout-default-width-probe, > .esp-page-flyout-max-width-probe, > .esp-page-main-min-width-probe, > .esp-page-main-configured-max-width-probe, > .esp-page-main-max-width-probe, > .esp-page-resize-step-probe, > .esp-page-resize-large-step-probe { position: absolute; block-size: 0; visibility: hidden; pointer-events: none; contain: strict; } > .esp-page-preview-min-width-probe { inline-size: var(--_esp-page-preview-resolved-min-width); } > .esp-page-preview-max-width-probe { inline-size: var(--_esp-page-preview-resolved-max-width); } > .esp-page-preview-default-width-probe { inline-size: var(--esp-page-preview-default-width, 0px); } > .esp-page-flyout-min-width-probe { inline-size: var(--_esp-page-flyout-resolved-min-width); } > .esp-page-flyout-max-width-probe { inline-size: var(--_esp-page-flyout-resolved-max-width); } > .esp-page-flyout-default-width-probe { inline-size: var(--esp-page-flyout-default-width, 0px); } > .esp-page-main-min-width-probe { inline-size: var(--_esp-page-main-min-width); } > .esp-page-main-configured-max-width-probe { inline-size: var(--esp-page-main-max-width, 0px); } > .esp-page-main-max-width-probe { inline-size: var(--_esp-page-resolved-max-width); } > .esp-page-resize-step-probe { inline-size: var(--esp-page-resize-step, 1rem); } > .esp-page-resize-large-step-probe { inline-size: var(--esp-page-resize-large-step, 4rem); } /* Canvas: the outer gutter regions promoted to a styleable layer. They only have width once the viewport exceeds the cap, so with the transparent defaults they are invisible and narrow pages are unchanged. Painted below the content (z-index 5) and below the surface shadow. */ > .esp-page-canvas { /* Full height: the canvas runs top-to-bottom. In the default full-bleed chrome the header/footer span the gutters and cover it there, so only the content-band gutters show; in contained mode the header/footer sit on the surface and the canvas shows full height beside them. */ grid-row: top-start / footer-end; z-index: 1; position: relative; pointer-events: none; background-color: var(--esp-page-canvas-background, transparent); /* Image layer mirrors the page background-image knobs: a separate layer so its opacity does not fade the color. */ &::before { content: \"\"; position: absolute; inset: 0; background-image: var(--esp-page-canvas-background-image, none); opacity: var(--esp-page-canvas-background-image-opacity, 1); } } > .esp-page-canvas--left { grid-column: canvas-left; } > .esp-page-canvas--right { /* The canvas spans both the auxiliary workspace and the independent outer gutter beneath it. */ grid-column: canvas-right; } /* Surface: a transparent backdrop spanning the surface cluster (left aside + main + right aside). It carries the surface edge shadow (on by default) and an optional hairline border. The shadow casts outward into the gutters; when there are no gutters the surface fills the viewport and overflow-x: clip on .esp-page trims the shadow away — so it is visible only above the cap with no container query needed. */ > .esp-page-surface { grid-column: surface; /* Full height so the edge shadow is one continuous line from the header through the content to the footer — no fade at the region joins. */ grid-row: top-start / footer-end; z-index: 2; pointer-events: none; box-shadow: var(--_esp-page-surface-shadow); border-inline: var(--_esp-page-surface-border); } /* Internal wrapper manipulated by BiDirectionalStickyController */ .sticky-wrapper { will-change: top; display: block; width: 100%; position: sticky; top: 0; } > div.esp-page-footer { grid-column: full; grid-row: footer; z-index: 10; background: var(--esp-page-background, var(--esp-color-background)); /* Spans every column; contain it so its content does not inflate the aside tracks (see the header note above). */ contain: inline-size; } &.sticky-header { slot[name=\"header\"]::slotted(esp-header), slot[name=\"sidebar\"]::slotted(esp-menu), slot[name=\"right\"]::slotted(esp-menu) { --esp-menu-top-offset: var(--_esp-page-fixed-header-offset); } > div.esp-page-top { position: sticky; top: var(--esp-page-sticky-header-top, 0); } } &.fixed-header { slot[name=\"header\"]::slotted(esp-header), slot[name=\"sidebar\"]::slotted(esp-menu), slot[name=\"right\"]::slotted(esp-menu) { --esp-menu-top-offset: var(--_esp-page-fixed-header-offset); } > div.esp-page-top { position: fixed; top: 0; left: 0; right: 0; } > div.esp-page-main, > aside.esp-page-left, > aside.esp-page-right, > div.esp-page-flyout, > .esp-page-surface, > .esp-page-canvas { margin-top: var(--_esp-page-fixed-header-offset); } } /* Inherit fonts for inputs and buttons */ input, button, textarea, select { font-family: inherit; font-size: inherit; } /* Make sure text areas without a rows attribute are not tiny */ textarea:not([rows]) { min-height: 10em; } /* Anything that has been anchored to should have extra scroll margin */ :target { scroll-margin-block: 5ex; } } .esp-page:has(esp-dialog[is-open=\"true\"]) { overflow: hidden; } /* Main and preview are additive surfaces. Once preview owns the trailing edge, move elevation there so no shadow appears at the internal join; the surface resumes its normal frame when preview is hidden. */ :host([preview-visible]) .esp-page > .esp-page-surface { box-shadow: none; } /* The preview's outer grid item and landmark span the complete page so the sticky wrapper's containing block has enough travel to remain pinned throughout a tall document. Its dynamic-viewport block size and vertical overflow keep its scroll position independent from the main document. It paints above full-bleed header chrome only in the preview's negotiated gutter track; overlay flyouts still take precedence by hiding preview presentation. */ .esp-page > div.esp-page-preview-space { grid-row: top-start / footer-end; z-index: calc(var(--esp-page-header-z-index, 20) + 1); pointer-events: none; > .esp-page-preview { position: absolute; inset-block: 0; inset-inline-start: 0; pointer-events: auto; > .sticky-wrapper { block-size: 100vh; block-size: 100dvh; overflow-y: auto; /* Scroll preview first, then hand wheel/trackpad motion back to the document at either boundary (or when no overflow exists). */ overscroll-behavior-y: auto; } } } @media (prefers-reduced-motion: reduce) { .esp-page { transition: none; } } `, ]"
+          "default": "[ ...EspalierElementBase.styles, css` :host { --_esp-surface-layer: initial; --_esp-page-resolved-max-width: var(--esp-page-main-max-width, 1536px); --_esp-page-main-min-width: var(--esp-page-main-min-width, 30rem); --_esp-page-preview-resolved-min-width: var(--esp-page-preview-min-width, 22.5rem); --_esp-page-preview-resolved-max-width: var(--esp-page-preview-max-width, 48rem); --_esp-page-flyout-resolved-min-width: var(--esp-page-flyout-min-width, 20rem); --_esp-page-flyout-resolved-max-width: var(--esp-page-flyout-max-width, 30rem); --_esp-page-preview-used-width: 0px; --_esp-page-flyout-used-width: 0px; --_esp-page-workspace-track: minmax( calc(var(--_esp-page-flyout-min) + var(--_esp-page-preview-min)), calc(var(--_esp-page-preview-used-width) + var(--_esp-page-flyout-used-width)) ); /* The cap sizes the main content *well*: the main track maxes at the cap and the surplus beyond the surface becomes canvas gutters. (Contract preserved from v2.1.0.) */ --_esp-page-main-track: minmax(0, var(--_esp-page-resolved-max-width)); /* Canvas gutter weights (physical left/right in LTR). The flexible gutters claim only the space left once the main track reaches its cap, so they appear exactly when the surface exceeds the cap — at any cap, with no viewport breakpoint (ADR-011). The start default keeps no leading gutter and lets all surplus collect trailing. Empty asides collapse to zero because the header and footer regions are inline-size-contained and no longer leak their min-content into the aside tracks (see the .esp-page-top / .esp-page-footer rules). The fr weights are written as 0fr/1fr (never bare 0) so the track list stays pairwise-interpolable and the flyout open/close can animate via grid track interpolation where supported. */ --_esp-page-gutter-left: 0fr; --_esp-page-gutter-right: 1fr; /* Help and preview share an exact auxiliary workspace track before the outer trailing gutter. Opening help raises that track's safe minimum; the allocator supplies its concrete used width. */ --_esp-page-flyout-min: 0px; /* Preview starts at the surface edge before help. Reclaiming raises this minimum so the auxiliary track reserves both pane floors while the main track retains its own floor. */ --_esp-page-preview-min: 0px; /* A raised surface edge's drop shadow, cast in the trailing (inline-end) direction. The surface mirrors it onto both inline edges; a match-surface flyout casts only this trailing edge, so it lifts off the canvas while staying attached at its leading perforation (no shadow bleeding over the content it flies out from). */ --_esp-page-surface-edge-shadow: 0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow); /* Resolve the surface shadow/border once (public override plus the built-in default) so the value is readable downstream — the surface layer and the match-surface flyout contract both consume it, and it stays a single source of truth. */ --_esp-page-surface-shadow: var( --esp-page-surface-shadow, -0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow), var(--_esp-page-surface-edge-shadow) ); --_esp-page-surface-border: var(--esp-page-surface-border, none); --_esp-page-fixed-header-offset: var( --esp-page-fixed-header-offset, var(--esp-header-height, calc(4.5 * var(--esp-size-small))) ); display: block; } :host([kind=\"narrow\"]) { --_esp-page-resolved-max-width: var(--esp-page-main-max-width, 768px); } :host([align=\"center\"]) { --_esp-page-gutter-left: 1fr; --_esp-page-gutter-right: 1fr; } :host([align=\"end\"]) { --_esp-page-gutter-left: 1fr; --_esp-page-gutter-right: 0fr; } /* Full is unbounded only while the consumer has not supplied the explicit main maximum. The internal marker is synchronized from the computed public token before workspace allocation, allowing a finite full-kind authoring surface to retain normal alignment gutters. */ :host([kind=\"full\"]) { --_esp-page-resolved-max-width: var(--esp-page-main-max-width, none); } :host([kind=\"full\"]:not([data-main-max-configured])) { --_esp-page-main-track: 1fr; --_esp-page-gutter-left: 0fr; --_esp-page-gutter-right: 0fr; } /* Site: the marketing shell (ESP0174). The main region is always unbounded — slotted esp-section bands own their centered wells — so this is the unconfigured-full geometry, unconditionally, and align's gutter weights do not apply. Declared after the align rules so it wins on order. */ :host([kind=\"site\"]) { --_esp-page-resolved-max-width: none; --_esp-page-main-track: 1fr; --_esp-page-gutter-left: 0fr; --_esp-page-gutter-right: 0fr; } /* Flyout placement ladder (ESP0111). Preview and help occupy an exact auxiliary track between the main surface and the outer gutter: 1. spare canvas is converted into the allocated auxiliary track while main remains at its natural maximum 2. help and preview contract to their floors 3. an eligible linked navigation rail yields before the main track narrows toward its minimum 4. if the complete main + preview + help minimums do not fit, JS requests the flyout's existing modal overlay presentation 5. mobile → the media query below releases the minimum and esp-flyout itself becomes a fixed overlay drawer. The flyout-open host attribute is maintained by syncFlyoutState (Blink cannot match :has() inside :host(), so the state is mirrored instead). Declared after the align/kind rules so the open state wins. */ :host([flyout-open]) { --_esp-page-flyout-min: var(--_esp-page-flyout-resolved-min-width); } :host([preview-reclaiming]) { --_esp-page-preview-min: var(--_esp-page-preview-resolved-min-width); } /* Configured defaults and retained drag/keyboard choices participate in the same grid minima as automatic allocation. This lets a target that must reclaim main do so instead of overflowing the gutter, while the allocator still clamps private used widths before they reach Grid. */ :host([flyout-open][data-workspace-targeted]) { --_esp-page-flyout-min: var(--_esp-page-flyout-used-width); } :host([preview-reclaiming][data-workspace-targeted]) { --_esp-page-preview-min: var(--_esp-page-preview-used-width); } :host([flyout-open]), :host([preview-reclaiming]) { --_esp-page-main-track: minmax( var(--_esp-page-main-min-width), var(--_esp-page-resolved-max-width) ); } :host([kind=\"full\"]:not([data-main-max-configured])[flyout-open]), :host([kind=\"full\"]:not([data-main-max-configured])[preview-reclaiming]), :host([kind=\"site\"][flyout-open]), :host([kind=\"site\"][preview-reclaiming]) { --_esp-page-main-track: minmax(var(--_esp-page-main-min-width), 1fr); } /* Deliberate ADR-011 exception: like the esp-menu drawer (same 50em threshold), the flyout's overlay rung is a genuinely viewport-level decision — below it the flyout leaves the grid for a fixed drawer, so the gutter must release the minimum it was reserving. */ @media ${unsafeCSS(COMPACT_VIEWPORT_MEDIA_QUERY)} { :host([flyout-open]) { --_esp-page-flyout-min: 0px; } :host([preview-reclaiming]) { --_esp-page-preview-min: 0px; } :host([flyout-open]), :host([preview-reclaiming]) { --_esp-page-main-track: minmax(0, var(--_esp-page-resolved-max-width)); } :host([kind=\"full\"]:not([data-main-max-configured])[flyout-open]), :host([kind=\"full\"]:not([data-main-max-configured])[preview-reclaiming]), :host([kind=\"site\"][flyout-open]), :host([kind=\"site\"][preview-reclaiming]) { --_esp-page-main-track: 1fr; } .esp-page > .esp-page-preview-space, .esp-page > .esp-page-workspace-resize-handles { display: none; } } /* A forced mode=\"overlay\" flyout is a fixed drawer at any viewport width, so its aside needs the same above-the-header hoist the sub-50em media rule gives the auto-mode drawer — without this the desktop drawer paints beneath the header (aside z 5 vs header z 20). Keyed off the flyout-overlay-open state attribute maintained by syncFlyoutState. */ :host([flyout-overlay-open]) .esp-page > div.esp-page-flyout { z-index: var(--esp-flyout-z-index, 3000); } /* A nested page's fixed drawer still participates in this page's main stacking context. Raise that complete context while the descendant modal is open so the drawer and vellum paint above this page's header instead of trapping their close control beneath it. */ :host([descendant-flyout-overlay-open]) .esp-page > div.esp-page-main { z-index: var(--esp-flyout-z-index, 3000); overflow: visible; } /* Trigger-anchored panels belong to the same document flow as their initiator. BiDirectionalStickyController can keep updating the wrapper's inline top, but position: static deliberately makes it inert until the anchored panel closes. */ :host([flyout-anchored]:not([flyout-full-height])) .esp-page > div.esp-page-flyout > .sticky-wrapper { position: static; } /* Full-document help owns the visible block-size rather than following one field. Span header through footer so the page footer cannot push a viewport-height panel out of view at the document boundary; the sticky controller pins this presentation to the viewport top. */ :host([flyout-full-height]) .esp-page > div.esp-page-flyout { grid-row: top-start / footer-end; z-index: calc(var(--esp-page-header-z-index, 20) + 2); } /* Anchored help connects back to its trigger across a visible preview. Raise only the sized help wrapper above the preview surface; the bridge itself is non-interactive inside esp-flyout. */ :host([flyout-anchored][preview-visible]) .esp-page > div.esp-page-flyout { z-index: calc(var(--esp-page-header-z-index, 20) + 2); } slot[name=\"flyout\"]::slotted(esp-flyout) { --_esp-flyout-used-width: var(--_esp-page-flyout-used-width); --_esp-flyout-preview-bridge-width: 0px; --_esp-flyout-preview-anchor-display: none; } :host([preview-visible]) slot[name=\"flyout\"]::slotted(esp-flyout) { --_esp-flyout-preview-bridge-width: var(--_esp-page-preview-used-width); --_esp-flyout-preview-anchor-display: block; } /* Flyout surface-match contract. A slotted esp-flyout with match-surface lifts its trailing edge with the surface's edge shadow, so the panel reads as a raised peer of the content surface rather than the shadowless tear-off. The leading edge keeps its perforation (the border is not overridden) and casts no shadow, so it stays attached at the tear line instead of floating over the content it flies out from. Opt-in and page-scoped: a standalone flyout has no surface to match and is unaffected. */ slot[name=\"flyout\"]::slotted(esp-flyout[match-surface]) { --esp-flyout-shadow: var(--_esp-page-surface-edge-shadow); } /* Header alignment contract. Published on the slotted esp-header (not :host) so it never shadows an inherited or author override and only the header-slot header adopts it — see the host-token-defaults architecture rule and ADR-005. max-width is the resolved cap; lead is the fraction of surplus placed before the content (0 = start, .5 = center, 1 = end). */ slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-max-width: var(--_esp-page-resolved-max-width); --esp-header-content-lead: 0; } :host([align=\"center\"]) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-lead: 0.5; } :host([align=\"end\"]) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-lead: 1; } /* full has no cap; publish 100% (not none) so the header contract calc resolves to zero surplus and leaves the header full-bleed. */ :host([kind=\"full\"]:not([data-main-max-configured])) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-max-width: 100%; } /* Footer alignment mirrors the header behavior with footer-owned contract names. The full-bleed footer paints its own background; only its internal content adopts the page's cap and lead fraction. */ slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-max-width: var(--_esp-page-resolved-max-width); --esp-footer-content-lead: 0; } :host([align=\"center\"]) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-lead: 0.5; } :host([align=\"end\"]) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-lead: 1; } :host([kind=\"full\"]:not([data-main-max-configured])) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-max-width: 100%; } /* Site: bar content aligns with the section wells, not a main cap. One public token governs the header, the footer, and every esp-section well, and the well is centered — declared after the align lead rules so the centered site column wins on order. */ :host([kind=\"site\"]) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-max-width: var(--esp-page-well-max-width, 72rem); --esp-header-content-lead: 0.5; } :host([kind=\"site\"]) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-max-width: var(--esp-page-well-max-width, 72rem); --esp-footer-content-lead: 0.5; } /* Contained shell: the header and footer ride the surface instead of the full viewport, so the whole page reads as one band on the canvas. Only their column placement changes — the full-height canvas and surface layers already do the rest. */ :host([contained]) .esp-page > div.esp-page-top, :host([contained]) .esp-page > div.esp-page-footer { grid-column: surface; } /* On the surface the bar already spans the content width, so the header fills it (no content padding) and drops its own shadow — the continuous surface edge shadow does the framing. */ :host([contained]) slot[name=\"header\"]::slotted(esp-header) { --esp-header-shadow: none; } /* The 100% contract belongs to the capped kinds, where the surface column IS the content width. A contained site keeps the shared well column (ESP0174) — sections and chrome must not split columns just because the shell is contained. */ :host([contained]:not([kind=\"site\"])) slot[name=\"header\"]::slotted(esp-header) { --esp-header-content-max-width: 100%; } :host([contained]:not([kind=\"site\"])) slot[name=\"footer\"]::slotted(esp-footer) { --esp-footer-content-max-width: 100%; } :host([kind=\"narrow\"]) .esp-page > div.esp-page-main { /* The golden reading measure, from the shared token (ESP0174); 66ch remains the fallback and the default emission. */ > ::slotted(*) { max-inline-size: var(--esp-measure, 66ch); } } #dialog-drop-zone { z-index: 4000; position: absolute; } :host([preview-visible]) .esp-page > div.esp-page-preview-space > .esp-page-preview { display: block; } :host([workspace-resizable][preview-visible]:not([flyout-overlay-open])) .esp-page > div.esp-page-workspace-resize-handles > .esp-page-main-preview-resize-handle, :host([workspace-resizable][flyout-open]:not([flyout-overlay-open])) .esp-page > div.esp-page-workspace-resize-handles > .esp-page-preview-flyout-resize-handle { display: block; } :host([workspace-resizable]:not([data-workspace-resize-ready])) .esp-page > .esp-page-workspace-resize-handles { display: none; } :host([workspace-resizable][data-workspace-trailing-edge-exposed]:not([flyout-overlay-open])) .esp-page > div.esp-page-workspace-resize-handles > .esp-page-workspace-end-resize-handle, :host([workspace-resizable][data-workspace-position-held]:not([flyout-overlay-open])) .esp-page > div.esp-page-workspace-resize-handles > .esp-page-workspace-end-resize-handle { display: block; } /* Pointer-owned resizing controls the logical leading gutter. It stays fixed for zero-sum pane trades and yields as an outward drag consumes centered outside canvas, keeping the active separator under the pointer in both cases. On release JS moves this pixel track to the aligned target; the normal grid transition supplies the glide before the intrinsic fr gutter contract resumes. */ :host([data-workspace-position-held]) { --_esp-page-gutter-left: var(--_esp-page-resize-leading-gutter-width, 0px); --_esp-page-gutter-right: 1fr; } :host([data-workspace-resizing]) { cursor: col-resize; user-select: none; } /* The grid-track glide that makes programmatic open/close feel animated reads as cursor lag while a pointer owns the seam, and a mid-glide grid feeds stale geometry into the clamp ranges of the next keyboard step. Track changes must be immediate for the whole resize session, pointer or keyboard. */ :host([data-workspace-resizing]) .esp-page, :host([data-workspace-keyboard-adjusting]) .esp-page { transition: none; } /* The linked menu switches its rail to a fixed drawer, but light-DOM menu content can still contribute an intrinsic width to the page's sidebar track. Collapse the owning aside only after the validated header/menu handshake is active, so unmatched navigation remains visible and reachable. */ :host([data-preview-navigation-collapsed]) .esp-page > aside.esp-page-left { inline-size: 0; min-inline-size: 0; } :host([data-preview-measuring]) .esp-page { transition: none; } /* New preview layouts are validated against visible geometry before presentation. Keep that candidate surface non-visible so a rejected measurement can never flash on screen. */ :host([data-preview-validating]) .esp-page-preview { visibility: hidden; } .esp-page { /* dvh keeps the shell within the visible mobile viewport; 100vh is the fallback for browsers without dvh (dvh === vh on desktop). */ min-height: 100vh; min-height: 100dvh; display: grid; grid-template-columns: [full-start canvas-left-start] var(--_esp-page-gutter-left) [canvas-left-end surface-start left-start] min-content [left-end main-start] var(--_esp-page-main-track) [main-end right-start] min-content [right-end surface-end canvas-right-start flyout-start] var(--_esp-page-workspace-track) [flyout-end] var(--_esp-page-gutter-right) [canvas-right-end full-end]; /* Animate the flyout claiming/releasing its track (and the gutter rebalance) via grid track interpolation where supported; elsewhere the modes still apply, just without the glide. Keep this 0.25s duration synchronized with WORKSPACE_RECENTER_DURATION in workspace-resize-session.ts. */ transition: grid-template-columns 0.25s ease; grid-template-rows: [top-start] min-content [top-end content-start] 1fr [content-end footer-start] min-content [footer-end]; overflow-x: clip; background: var(--esp-page-background, var(--esp-color-background)); line-height: 1.5; font-family: var( --_esp-font-body-effective, var(--esp-font-body, var(--_esp-font-body-fallback)) ); font-size: var(--esp-type-normal); color: var(--esp-color-text); position: relative; &:before { content: \" \"; display: block; position: absolute; left: 0; top: 0; right: 0; bottom: 0; opacity: var(--esp-page-background-image-opacity, 1); background-image: var(--esp-page-background-image, none); z-index: 1; } > div.esp-page-top { z-index: var(--esp-page-header-z-index, 20); grid-column: full; grid-row: top; position: relative; /* The header spans every column, so without inline-size containment its content's min-content would be distributed into the aside tracks and inflate them below the cap (the asides would never collapse). Contain it like the main well so it takes its width from the grid, not the grid from it. */ contain: inline-size; } /* Sidebar containers — act as the \"track\" for sticky positioning */ aside.esp-page-left, aside.esp-page-right { z-index: 5; grid-row: content; position: relative; /* No explicit height — grid stretch fills the 1fr row, and the aside's bottom edge constrains sticky children. */ } > aside.esp-page-left { grid-column: left; } > div.esp-page-main { z-index: 5; grid-column: main; grid-row: content; position: relative; /* Clip oversized content without becoming a scroll container. A hidden-overflow wrapper traps descendant view timelines (and sticky positioning) on this non-scrolling main well. */ overflow: clip; /* The main well's own background. Defaults to transparent, so the well shows the page background exactly as before; set it to give the content well a distinct card color, or leave it transparent (with --esp-page-surface-shadow: none) for content that floats directly on the page/canvas. */ background: var(--esp-page-main-background, transparent); /* The cap now lives in the main track (minmax(0, cap)); the element fills its column. contain: inline-size still holds because the track gives a definite inline size. */ contain: inline-size; } > aside.esp-page-right { grid-column: right; } /* A neutral div, unlike the left/right asides: the slotted esp-flyout is itself the complementary landmark, and an aside wrapper would nest a second, empty landmark around it. */ > div.esp-page-flyout { /* Sits after preview inside the exact auxiliary track and sizes to the allocated help width. Outer surplus remains in the following gutter rather than under an empty stretched wrapper. */ grid-column: flyout; justify-self: start; grid-row: content; z-index: 5; position: relative; inline-size: var(--_esp-page-flyout-used-width); min-inline-size: 0; margin-inline-start: var(--_esp-page-preview-used-width); /* In the drawer rung the fixed esp-flyout paints inside this wrapper's stacking context, so the wrapper itself must rise above the header (z 20) while staying below the dialog drop zone (4000). Uses the same token as the drawer — set it on the page (or higher) to move both together. */ @media ${unsafeCSS(COMPACT_VIEWPORT_MEDIA_QUERY)} { z-index: var(--esp-flyout-z-index, 3000); } } /* Preview begins at the surface edge and help is offset after its resolved width, producing the logical order main → preview → help inside their exact shared auxiliary track. */ > div.esp-page-preview-space { grid-column: flyout; grid-row: content; z-index: 4; position: relative; min-inline-size: 0; > .esp-page-preview { display: none; box-sizing: border-box; inline-size: var(--_esp-page-preview-used-width); position: relative; background: var( --esp-page-preview-background, var(--esp-page-main-background, var(--esp-page-background, var(--esp-color-background))) ); border-inline-start: var(--esp-page-preview-border, 1px dotted var(--esp-color-border)); box-shadow: var(--esp-page-preview-shadow, var(--_esp-page-surface-edge-shadow)); } } /* A transparent interaction layer keeps the complete hit target above main, preview, and anchored help without raising either painted surface (which would hide the help bridge). */ > div.esp-page-workspace-resize-handles { grid-column: flyout; grid-row: top-start / footer-end; z-index: calc(var(--esp-page-header-z-index, 20) + 3); position: relative; min-inline-size: 0; pointer-events: none; } > div.esp-page-workspace-resize-handles > .esp-page-workspace-resize-handle { display: none; box-sizing: border-box; position: absolute; inset-block: 0; z-index: 3; inline-size: var(--esp-page-resize-handle-hit-size, 2.75rem); margin-inline-start: calc(-0.5 * var(--esp-page-resize-handle-hit-size, 2.75rem)); border: 0; outline: 0; background: transparent; cursor: col-resize; pointer-events: auto; touch-action: none; /* The target spans the seam so it remains reachable during document scroll. Focus draws a dashed line along the seam itself — the visible height of the dotted tear-off edge, capped at one viewport — kept in view by sticky positioning while the page scrolls. */ &::after { content: \"\"; display: block; position: sticky; inset-block-start: 0; box-sizing: border-box; inline-size: 0; margin-inline: auto; block-size: 100dvh; max-block-size: 100%; pointer-events: none; } &:focus-visible::after { border-inline-start: var( --esp-page-resize-focus-outline, 2px dashed var(--esp-color-link) ); /* Glow in the line's own color so the focused seam reads as one deliberate highlight rather than a neutral drop shadow. */ box-shadow: var(--esp-page-resize-focus-shadow, 0 0 0.75rem var(--esp-color-link)); } } > div.esp-page-workspace-resize-handles > .esp-page-main-preview-resize-handle { inset-inline-start: 0; } > div.esp-page-workspace-resize-handles > .esp-page-preview-flyout-resize-handle { inset-inline-start: var(--_esp-page-preview-used-width); } > div.esp-page-workspace-resize-handles > .esp-page-workspace-end-resize-handle { inset-inline-start: calc( var(--_esp-page-preview-used-width) + var(--_esp-page-flyout-used-width) ); } /* Keep token-sized probes outside the width-constrained gutter. If they lived inside a zero-width preview space, layout would clamp their rectangles to zero before JS could decide whether the reclaim rung should be activated. */ > .esp-page-preview-min-width-probe, > .esp-page-preview-default-width-probe, > .esp-page-preview-max-width-probe, > .esp-page-flyout-min-width-probe, > .esp-page-flyout-default-width-probe, > .esp-page-flyout-max-width-probe, > .esp-page-main-min-width-probe, > .esp-page-main-configured-max-width-probe, > .esp-page-main-max-width-probe, > .esp-page-resize-step-probe, > .esp-page-resize-large-step-probe { position: absolute; block-size: 0; visibility: hidden; pointer-events: none; contain: strict; } > .esp-page-preview-min-width-probe { inline-size: var(--_esp-page-preview-resolved-min-width); } > .esp-page-preview-max-width-probe { inline-size: var(--_esp-page-preview-resolved-max-width); } > .esp-page-preview-default-width-probe { inline-size: var(--esp-page-preview-default-width, 0px); } > .esp-page-flyout-min-width-probe { inline-size: var(--_esp-page-flyout-resolved-min-width); } > .esp-page-flyout-max-width-probe { inline-size: var(--_esp-page-flyout-resolved-max-width); } > .esp-page-flyout-default-width-probe { inline-size: var(--esp-page-flyout-default-width, 0px); } > .esp-page-main-min-width-probe { inline-size: var(--_esp-page-main-min-width); } > .esp-page-main-configured-max-width-probe { inline-size: var(--esp-page-main-max-width, 0px); } > .esp-page-main-max-width-probe { inline-size: var(--_esp-page-resolved-max-width); } > .esp-page-resize-step-probe { inline-size: var(--esp-page-resize-step, 1rem); } > .esp-page-resize-large-step-probe { inline-size: var(--esp-page-resize-large-step, 4rem); } /* Canvas: the outer gutter regions promoted to a styleable layer. They only have width once the viewport exceeds the cap, so with the transparent defaults they are invisible and narrow pages are unchanged. Painted below the content (z-index 5) and below the surface shadow. */ > .esp-page-canvas { /* Full height: the canvas runs top-to-bottom. In the default full-bleed chrome the header/footer span the gutters and cover it there, so only the content-band gutters show; in contained mode the header/footer sit on the surface and the canvas shows full height beside them. */ grid-row: top-start / footer-end; z-index: 1; position: relative; pointer-events: none; background-color: var(--esp-page-canvas-background, transparent); /* Image layer mirrors the page background-image knobs: a separate layer so its opacity does not fade the color. */ &::before { content: \"\"; position: absolute; inset: 0; background-image: var(--esp-page-canvas-background-image, none); opacity: var(--esp-page-canvas-background-image-opacity, 1); } } > .esp-page-canvas--left { grid-column: canvas-left; } > .esp-page-canvas--right { /* The canvas spans both the auxiliary workspace and the independent outer gutter beneath it. */ grid-column: canvas-right; } /* Surface: a transparent backdrop spanning the surface cluster (left aside + main + right aside). It carries the surface edge shadow (on by default) and an optional hairline border. The shadow casts outward into the gutters; when there are no gutters the surface fills the viewport and overflow-x: clip on .esp-page trims the shadow away — so it is visible only above the cap with no container query needed. */ > .esp-page-surface { grid-column: surface; /* Full height so the edge shadow is one continuous line from the header through the content to the footer — no fade at the region joins. */ grid-row: top-start / footer-end; z-index: 2; pointer-events: none; box-shadow: var(--_esp-page-surface-shadow); border-inline: var(--_esp-page-surface-border); } /* Internal wrapper manipulated by BiDirectionalStickyController */ .sticky-wrapper { will-change: top; display: block; width: 100%; position: sticky; top: 0; } > div.esp-page-footer { grid-column: full; grid-row: footer; z-index: 10; background: var(--esp-page-background, var(--esp-color-background)); /* Spans every column; contain it so its content does not inflate the aside tracks (see the header note above). */ contain: inline-size; } &.sticky-header { slot[name=\"header\"]::slotted(esp-header), slot[name=\"sidebar\"]::slotted(esp-menu), slot[name=\"right\"]::slotted(esp-menu) { --esp-menu-top-offset: var(--_esp-page-fixed-header-offset); } > div.esp-page-top { position: sticky; top: var(--esp-page-sticky-header-top, 0); } } &.fixed-header { slot[name=\"header\"]::slotted(esp-header), slot[name=\"sidebar\"]::slotted(esp-menu), slot[name=\"right\"]::slotted(esp-menu) { --esp-menu-top-offset: var(--_esp-page-fixed-header-offset); } > div.esp-page-top { position: fixed; top: 0; left: 0; right: 0; } > div.esp-page-main, > aside.esp-page-left, > aside.esp-page-right, > div.esp-page-flyout, > .esp-page-surface, > .esp-page-canvas { margin-top: var(--_esp-page-fixed-header-offset); } } /* Inherit fonts for inputs and buttons */ input, button, textarea, select { font-family: inherit; font-size: inherit; } /* Make sure text areas without a rows attribute are not tiny */ textarea:not([rows]) { min-height: 10em; } /* Anything that has been anchored to should have extra scroll margin */ :target { scroll-margin-block: 5ex; } } .esp-page:has(esp-dialog[is-open=\"true\"]) { overflow: hidden; } /* Main and preview are additive surfaces. Once preview owns the trailing edge, move elevation there so no shadow appears at the internal join; the surface resumes its normal frame when preview is hidden. */ :host([preview-visible]) .esp-page > .esp-page-surface { box-shadow: none; } /* The preview's outer grid item and landmark span the complete page so the sticky wrapper's containing block has enough travel to remain pinned throughout a tall document. Its dynamic-viewport block size and vertical overflow keep its scroll position independent from the main document. It paints above full-bleed header chrome only in the preview's negotiated gutter track; overlay flyouts still take precedence by hiding preview presentation. */ .esp-page > div.esp-page-preview-space { grid-row: top-start / footer-end; z-index: calc(var(--esp-page-header-z-index, 20) + 1); pointer-events: none; > .esp-page-preview { position: absolute; inset-block: 0; inset-inline-start: 0; pointer-events: auto; > .sticky-wrapper { block-size: 100vh; block-size: 100dvh; overflow-y: auto; /* Scroll preview first, then hand wheel/trackpad motion back to the document at either boundary (or when no overflow exists). */ overscroll-behavior-y: auto; } } } @media (prefers-reduced-motion: reduce) { .esp-page { transition: none; } } `, ]"
         }
       ],
       "exports": [
@@ -53622,7 +54041,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Used to lay out standard page structure.",
+          "description": "Arranges a page's header, navigation, main content, and footer.",
           "name": "EspalierPage",
           "cssProperties": [
             {
@@ -53742,7 +54161,7 @@
               "name": "--esp-page-header-z-index"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -56286,6 +56705,17 @@
               "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"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -57121,7 +57551,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Component for selecting a single option from a list of\noptions. For selecting multiple options, see\n[esp-pick-some](/components/pickers/pick-some/).\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick a fruit\">\n    <esp-pick-one>\n      <esp-picker-item text=\"Apple\" value=\"apple\" icon=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\" icon=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\" icon=\"lemon\"></esp-picker-item>\n    </esp-pick-one>\n  </esp-form-item>\n</esp-box>\n```\n\n### Initial state\n\nSet the initially selected item using the `selected` attribute\non the `esp-picker-item`:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick a fruit\">\n    <esp-pick-one>\n      <esp-picker-item text=\"Apple\" value=\"apple\" icon=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\" icon=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\" icon=\"lemon\" selected></esp-picker-item>\n    </esp-pick-one>\n  </esp-form-item>\n</esp-box>\n```\n\nAn item's `text`, `icon`, and `styles` may change after it is selected (a\nplaceholder label replaced once its data loads, say), and the picker shows\nthe new label; the selection follows the item's `value`.\n\n### Variable-height items\n\nItems with longer text wrap naturally. The menu sizes itself\nto fit the actual content height of each item:\n\n```html\n<div style=\"width: 260px\">\n  <esp-box>\n    <esp-form-item label=\"Pick a plan\">\n      <esp-pick-one>\n        <esp-picker-item\n          text=\"Basic - includes core features only\"\n          value=\"basic\">\n        </esp-picker-item>\n        <esp-picker-item\n          text=\"Pro - adds analytics, priority support, and advanced integrations for growing teams\"\n          value=\"pro\">\n        </esp-picker-item>\n        <esp-picker-item\n          text=\"Enterprise - everything in Pro plus SSO, audit logs, dedicated account management, and custom SLAs\"\n          value=\"enterprise\">\n        </esp-picker-item>\n        <esp-picker-item\n          text=\"Starter\"\n          value=\"starter\">\n        </esp-picker-item>\n      </esp-pick-one>\n    </esp-form-item>\n  </esp-box>\n</div>\n```\n\n### Typeahead (local filtering)\n\nAdd the `typeahead` attribute to let the user type to filter\nthe option list. The input becomes editable and the picker\nswitches to a filter icon on focus:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick a fruit\">\n    <esp-pick-one typeahead>\n      <esp-picker-item text=\"Apple\" value=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\"></esp-picker-item>\n    </esp-pick-one>\n  </esp-form-item>\n</esp-box>\n```\n\n### Typeahead (remote filtering)\n\nSet the `fetchItems` property to a callback that returns\nmatching items from a server. The picker debounces input\n(300 ms by default) and shows a loading indicator while\nthe request is in flight. Use the provided `AbortSignal`\nto cancel stale requests:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Search users\">\n    <esp-pick-one typeahead placeholder=\"Type a name\\u2026\">\n    </esp-pick-one>\n  </esp-form-item>\n</esp-box>\n<script>\n  const picker = findByTagName(\"esp-pick-one\")[0];\n  picker.fetchItems = async (query, signal) => {\n    const res = await fetch(\"/assets/data/grid-data.json\", { signal });\n    const all = await res.json();\n    const q = query.toLowerCase();\n    return all\n      .filter(u =>\n        u.first_name.toLowerCase().includes(q) ||\n        u.last_name.toLowerCase().includes(q))\n      .slice(0, 20)\n      .map(u => ({\n        text: `${u.first_name} ${u.last_name}`,\n        value: String(u.id),\n      }));\n  };\n</script>\n```",
+          "description": "Selects one option from a list. For selecting multiple options, see\n[esp-pick-some](/components/pickers/pick-some/).\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick a fruit\">\n    <esp-pick-one>\n      <esp-picker-item text=\"Apple\" value=\"apple\" icon=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\" icon=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\" icon=\"lemon\"></esp-picker-item>\n    </esp-pick-one>\n  </esp-form-item>\n</esp-box>\n```\n\n### Initial state\n\nSet the initially selected item using the `selected` attribute\non the `esp-picker-item`:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick a fruit\">\n    <esp-pick-one>\n      <esp-picker-item text=\"Apple\" value=\"apple\" icon=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\" icon=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\" icon=\"lemon\" selected></esp-picker-item>\n    </esp-pick-one>\n  </esp-form-item>\n</esp-box>\n```\n\nAn item's `text`, `icon`, and `styles` may change after it is selected (a\nplaceholder label replaced once its data loads, say), and the picker shows\nthe new label; the selection follows the item's `value`.\n\n### Variable-height items\n\nItems with longer text wrap naturally. The menu sizes itself\nto fit the actual content height of each item:\n\n```html\n<div style=\"width: 260px\">\n  <esp-box>\n    <esp-form-item label=\"Pick a plan\">\n      <esp-pick-one>\n        <esp-picker-item\n          text=\"Basic - includes core features only\"\n          value=\"basic\">\n        </esp-picker-item>\n        <esp-picker-item\n          text=\"Pro - adds analytics, priority support, and advanced integrations for growing teams\"\n          value=\"pro\">\n        </esp-picker-item>\n        <esp-picker-item\n          text=\"Enterprise - everything in Pro plus SSO, audit logs, dedicated account management, and custom SLAs\"\n          value=\"enterprise\">\n        </esp-picker-item>\n        <esp-picker-item\n          text=\"Starter\"\n          value=\"starter\">\n        </esp-picker-item>\n      </esp-pick-one>\n    </esp-form-item>\n  </esp-box>\n</div>\n```\n\n### Typeahead (local filtering)\n\nAdd the `typeahead` attribute to let the user type to filter\nthe option list. The input becomes editable and the picker\nswitches to a filter icon on focus:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick a fruit\">\n    <esp-pick-one typeahead>\n      <esp-picker-item text=\"Apple\" value=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\"></esp-picker-item>\n    </esp-pick-one>\n  </esp-form-item>\n</esp-box>\n```\n\n### Typeahead (remote filtering)\n\nSet the `fetchItems` property to a callback that returns\nmatching items from a server. The picker debounces input\n(300 ms by default) and shows a loading indicator while\nthe request is in flight. Use the provided `AbortSignal`\nto cancel stale requests:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Search users\">\n    <esp-pick-one typeahead placeholder=\"Type a name\\u2026\">\n    </esp-pick-one>\n  </esp-form-item>\n</esp-box>\n<script>\n  const picker = findByTagName(\"esp-pick-one\")[0];\n  picker.fetchItems = async (query, signal) => {\n    const res = await fetch(\"/assets/data/grid-data.json\", { signal });\n    const all = await res.json();\n    const q = query.toLowerCase();\n    return all\n      .filter(u =>\n        u.first_name.toLowerCase().includes(q) ||\n        u.last_name.toLowerCase().includes(q))\n      .slice(0, 20)\n      .map(u => ({\n        text: `${u.first_name} ${u.last_name}`,\n        value: String(u.id),\n      }));\n  };\n</script>\n```",
           "name": "EspalierPickOne",
           "members": [
             {
@@ -59011,6 +59441,17 @@
                 "module": "dist/pickers/esp-picker-base.js"
               }
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -59077,7 +59518,7 @@
           },
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -59160,7 +59601,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Component for selecting multiple options from a list of options.\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick some fruit\">\n    <esp-pick-some>\n      <esp-picker-item text=\"Apple\" value=\"apple\" icon=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\" icon=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"banana\" icon=\"lemon\"></esp-picker-item>\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n```\n\n### Initial state (HTML)\n\nSet the initially selected items using the `selected` attribute\non the `esp-picker-item` elements:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick a fruit\">\n    <esp-pick-some>\n      <esp-picker-item text=\"Apple\" value=\"apple\" icon=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\" icon=\"cherry\" selected></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\" icon=\"lemon\" selected></esp-picker-item>\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n```\n\n### Initial state (programmatic / pickerItems)\n\nWhen populating options via the `pickerItems` property (common\nin Lit templates that load data from an API), set `selected: true`\non items that should be pre-selected. The picker automatically\ndetects items with `selected: true` and renders them as chips:\n\n```ts\nconst allTopics = await fetchTopics();\nconst mySelectedIds = new Set(user.topicIds);\n\npicker.pickerItems = allTopics.map(t => ({\n  text: t.name,\n  value: t.id,\n  selected: mySelectedIds.has(t.id),\n}));\n```\n\nThis works with all modes — plain, typeahead (local), and\ntypeahead (remote via `fetchItems`). The component reads the\n`selected` flag from `pickerItems` during `willUpdate()` and\npopulates `selectedItems` automatically. **Do not** separately\nassign `selectedItems` — just set `selected: true` on the\nitems in `pickerItems`.\n\n### Typeahead (local filtering)\n\nAdd the `typeahead` attribute to let the user type to filter\nthe option list. The input becomes editable and the picker\nswitches to a filter icon on focus:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick some fruit\">\n    <esp-pick-some typeahead>\n      <esp-picker-item text=\"Apple\" value=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\"></esp-picker-item>\n      <esp-picker-item text=\"Banana\" value=\"banana\"></esp-picker-item>\n      <esp-picker-item text=\"Mango\" value=\"mango\"></esp-picker-item>\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n```\n\n### Typeahead (remote filtering)\n\nSet the `fetchItems` property to a callback that returns\nmatching items from a server. The picker debounces input\n(300 ms by default) and shows a loading indicator while\nthe request is in flight. Use the provided `AbortSignal`\nto cancel stale requests:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Search users\">\n    <esp-pick-some typeahead placeholder=\"Type a name…\">\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n<script>\n  const picker = findByTagName(\"esp-pick-some\")[0];\n  picker.fetchItems = async (query, signal) => {\n    const res = await fetch(\"/assets/data/grid-data.json\", { signal });\n    const all = await res.json();\n    const q = query.toLowerCase();\n    return all\n      .filter(u =>\n        u.first_name.toLowerCase().includes(q) ||\n        u.last_name.toLowerCase().includes(q))\n      .slice(0, 20)\n      .map(u => ({\n        text: `${u.first_name} ${u.last_name}`,\n        value: String(u.id),\n      }));\n  };\n</script>\n```\n\n### Add new value\n\nSet the `addNewValue` property to a callback that creates\na new picker item from the typed text. When the user types\na value that does not match any existing item, the dropdown\ncaret becomes a plus icon. Clicking the plus (or pressing\nEnter) invokes the callback and adds the returned item as\na checked selection:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick some tags\">\n    <esp-pick-some typeahead placeholder=\"Type to search or add…\">\n      <esp-picker-item text=\"Bug\" value=\"bug\"></esp-picker-item>\n      <esp-picker-item text=\"Feature\" value=\"feature\"></esp-picker-item>\n      <esp-picker-item text=\"Docs\" value=\"docs\"></esp-picker-item>\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n<script>\n  const picker = findByTagName(\"esp-pick-some\")[0];\n  picker.addNewValue = (text) => ({\n    text,\n    value: text.toLowerCase().replace(/\\s+/g, \"-\"),\n    selected: true,\n  });\n</script>\n```",
+          "description": "Selects multiple options from a list.\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick some fruit\">\n    <esp-pick-some>\n      <esp-picker-item text=\"Apple\" value=\"apple\" icon=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\" icon=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"banana\" icon=\"lemon\"></esp-picker-item>\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n```\n\n### Initial state (HTML)\n\nSet the initially selected items using the `selected` attribute\non the `esp-picker-item` elements:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick a fruit\">\n    <esp-pick-some>\n      <esp-picker-item text=\"Apple\" value=\"apple\" icon=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\" icon=\"cherry\" selected></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\" icon=\"lemon\" selected></esp-picker-item>\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n```\n\n### Initial state (programmatic / pickerItems)\n\nWhen populating options via the `pickerItems` property (common\nin Lit templates that load data from an API), set `selected: true`\non items that should be pre-selected. The picker automatically\ndetects items with `selected: true` and renders them as chips:\n\n```ts\nconst allTopics = await fetchTopics();\nconst mySelectedIds = new Set(user.topicIds);\n\npicker.pickerItems = allTopics.map(t => ({\n  text: t.name,\n  value: t.id,\n  selected: mySelectedIds.has(t.id),\n}));\n```\n\nThis works with all modes — plain, typeahead (local), and\ntypeahead (remote via `fetchItems`). The component reads the\n`selected` flag from `pickerItems` during `willUpdate()` and\npopulates `selectedItems` automatically. **Do not** separately\nassign `selectedItems` — just set `selected: true` on the\nitems in `pickerItems`.\n\n### Typeahead (local filtering)\n\nAdd the `typeahead` attribute to let the user type to filter\nthe option list. The input becomes editable and the picker\nswitches to a filter icon on focus:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick some fruit\">\n    <esp-pick-some typeahead>\n      <esp-picker-item text=\"Apple\" value=\"apple\"></esp-picker-item>\n      <esp-picker-item text=\"Cherry\" value=\"cherry\"></esp-picker-item>\n      <esp-picker-item text=\"Lemon\" value=\"lemon\"></esp-picker-item>\n      <esp-picker-item text=\"Banana\" value=\"banana\"></esp-picker-item>\n      <esp-picker-item text=\"Mango\" value=\"mango\"></esp-picker-item>\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n```\n\n### Typeahead (remote filtering)\n\nSet the `fetchItems` property to a callback that returns\nmatching items from a server. The picker debounces input\n(300 ms by default) and shows a loading indicator while\nthe request is in flight. Use the provided `AbortSignal`\nto cancel stale requests:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Search users\">\n    <esp-pick-some typeahead placeholder=\"Type a name…\">\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n<script>\n  const picker = findByTagName(\"esp-pick-some\")[0];\n  picker.fetchItems = async (query, signal) => {\n    const res = await fetch(\"/assets/data/grid-data.json\", { signal });\n    const all = await res.json();\n    const q = query.toLowerCase();\n    return all\n      .filter(u =>\n        u.first_name.toLowerCase().includes(q) ||\n        u.last_name.toLowerCase().includes(q))\n      .slice(0, 20)\n      .map(u => ({\n        text: `${u.first_name} ${u.last_name}`,\n        value: String(u.id),\n      }));\n  };\n</script>\n```\n\n### Add new value\n\nSet the `addNewValue` property to a callback that creates\na new picker item from the typed text. When the user types\na value that does not match any existing item, the dropdown\ncaret becomes a plus icon. Clicking the plus (or pressing\nEnter) invokes the callback and adds the returned item as\na checked selection:\n\n```html\n<esp-box>\n  <esp-form-item label=\"Pick some tags\">\n    <esp-pick-some typeahead placeholder=\"Type to search or add…\">\n      <esp-picker-item text=\"Bug\" value=\"bug\"></esp-picker-item>\n      <esp-picker-item text=\"Feature\" value=\"feature\"></esp-picker-item>\n      <esp-picker-item text=\"Docs\" value=\"docs\"></esp-picker-item>\n    </esp-pick-some>\n  </esp-form-item>\n</esp-box>\n<script>\n  const picker = findByTagName(\"esp-pick-some\")[0];\n  picker.addNewValue = (text) => ({\n    text,\n    value: text.toLowerCase().replace(/\\s+/g, \"-\"),\n    selected: true,\n  });\n</script>\n```",
           "name": "EspalierPickSome",
           "members": [
             {
@@ -61120,6 +61561,17 @@
                 "module": "dist/pickers/esp-picker-base.js"
               }
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -61178,7 +61630,7 @@
           },
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -62781,6 +63233,17 @@
               "description": "An explicit width for the picker trigger. Accepts any valid\nCSS width value (e.g. `\"5em\"`, `\"80px\"`). When set, the host\nelement is sized to this width while the dropdown menu is\nallowed to be wider to accommodate longer items.\n\n```html\n<esp-pick-one width=\"5em\">\n  <esp-picker-item text=\"Apple\" value=\"apple\"></esp-picker-item>\n</esp-pick-one>\n```",
               "fieldName": "width"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -62825,7 +63288,7 @@
           },
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -63946,7 +64409,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The single-select picker's selection state.\n\nTwo facts have to stay in step: which item is selected, and — when a `.value`\nwas set that matched nothing — what that unmatched value was so it can be\nre-applied once items arrive. Consumers can set `.value` before the slotted\n`esp-picker-item` elements have been extracted, so \"no match yet\" is a normal\nstate rather than an error.\n\nThe rule is *not* \"pending if and only if nothing matched\". A provisional\nselection derived from a DOM `selected` attribute can coexist with a pending\nprogrammatic `.value`, and the pending value must still win once items\nresolve — see withProvisionalItem. Encoding that as named\nconstructors replaces six hand-maintained assignment sites, three of which\nlived inside inline `render()` handlers where the distinction was invisible.\n\n`pending` is deliberately distinct from `undefined`: `.value = undefined` is\nan explicit clear, which is not the same as \"nothing is pending\".",
+          "description": "Track the selected item and any programmatic value waiting for matching options.\n\nConsumers may set `.value` before options arrive. A provisional selection\nfrom a DOM `selected` attribute can coexist with that pending value; the\nprogrammatic value wins once a matching item becomes available. See\nwithProvisionalItem.\n\n`pending` is separate from `undefined` because `.value = undefined` explicitly\nclears the selection.",
           "name": "PickOneSelection",
           "members": [
             {
@@ -64427,7 +64890,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Display a contextual UI overlay that appears when a\nuser interacts with an element, providing a temporary space\nfor additional information, options, or actions without blocking\nthe underlying content. Uses the native Popover API to render\nin the browser's top layer, escaping all ancestor `overflow`\nand `z-index` contexts.\n\n```html\n<esp-popover>\n  <esp-button label=\"Show popover\" slot=\"target\"></esp-button>\n  <esp-box slot=\"popover\">\n    <h2>I'm a popover!</h2>\n    <p>It can have anything in it.</p>\n    <esp-popover>\n      <esp-button label=\"Show nested popover\" slot=\"target\"></esp-button>\n      <esp-box slot=\"popover\">\n        <h2>I'm a nested popover!</h2>\n        <p>I will not cause my parent popover to close.</p>\n        <esp-popover>\n          <esp-button label=\"Show another popover\" slot=\"target\"></esp-button>\n          <esp-box slot=\"popover\">\n            <h2>I'm a very nested popover!</h2>\n            <p>I will not cause my parent popovers to close.</p>\n          </esp-box>\n        </esp-popover>\n      </esp-box>\n    </esp-popover>\n  </esp-box>\n</esp-popover>\n```",
+          "description": "Shows contextual information, options, or actions while the underlying\npage remains interactive. Uses the native Popover API to render\nin the browser's top layer, escaping all ancestor `overflow`\nand `z-index` contexts.\n\n```html\n<esp-popover>\n  <esp-button label=\"Show popover\" slot=\"target\"></esp-button>\n  <esp-box slot=\"popover\">\n    <h2>I'm a popover!</h2>\n    <p>It can have anything in it.</p>\n    <esp-popover>\n      <esp-button label=\"Show nested popover\" slot=\"target\"></esp-button>\n      <esp-box slot=\"popover\">\n        <h2>I'm a nested popover!</h2>\n        <p>I will not cause my parent popover to close.</p>\n        <esp-popover>\n          <esp-button label=\"Show another popover\" slot=\"target\"></esp-button>\n          <esp-box slot=\"popover\">\n            <h2>I'm a very nested popover!</h2>\n            <p>I will not cause my parent popovers to close.</p>\n          </esp-box>\n        </esp-popover>\n      </esp-box>\n    </esp-popover>\n  </esp-box>\n</esp-popover>\n```",
           "name": "EspalierPopover",
           "slots": [
             {
@@ -64922,7 +65385,7 @@
               "name": "--esp-progress-text-color"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -65864,6 +66327,17 @@
               "description": "Display mode for the progress indicator.\n\n- `bar` — linear progress bar (default)\n- `circle` — circular SVG ring",
               "fieldName": "mode"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -66990,6 +67464,17 @@
               "description": "Disables all child radio buttons in the group.",
               "fieldName": "disabled"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -67048,7 +67533,7 @@
           "customElement": true,
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -67147,7 +67632,7 @@
               "name": "--esp-radio-button-focus-shadow"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -68061,6 +68546,17 @@
               "description": "Controls whether the radio button is disabled.",
               "fieldName": "disabled"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -68192,7 +68688,7 @@
               "name": "--esp-repeater-grid-row-gap"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -70236,6 +70732,17 @@
               "description": "Optional consumer-provided error message. When set it takes priority\nover internal fetch errors for display purposes.",
               "fieldName": "errorMessage"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -70354,7 +70861,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Root container for the Espalier design system.\n\nProvides the full design-token pipeline — colors, scales, and\nfonts — to every descendant component.  All tokens are\nJS-computed from a pair of Base64-encoded theme objects and\nemitted as CSS custom properties on the host element.\n\n### Theme API\n\nSupply a `light-theme` and/or `dark-theme` attribute containing\na **Base64-encoded JSON** partial theme.  Fields you omit fall\nback to built-in defaults.  Switch between them with `scheme`.\n\n```html\n<esp-root\n  light-theme=\"eyJzZWVkQ29sb3IiOiJva2xjaCgwLjcgMC4yIDE1NSkifQ==\"\n  scheme=\"light\">\n  <esp-box>\n    <h2>Themed content</h2>\n  </esp-box>\n</esp-root>\n```\n\n### Nested theme previews and scoped events\n\nA nested root creates a scoped theme for its descendants. It does not create\na separate event bus: every root publishes theme changes through the same\nEspalier singleton. Subscribe through the root whose changes you own so a\nnested preview cannot be mistaken for an application-level theme change.\n\n```ts\nconst applicationRoot = document.querySelector<EspalierRoot>(\"#application-theme\")!;\n\nconst unsubscribe = applicationRoot.subscribeScoped(\"scheme-changed\", ({ scheme }) => {\n  localStorage.setItem(\"scheme\", scheme);\n});\n\n// Initial state is read directly; scoped events report later changes only.\nrenderScheme(applicationRoot.scheme);\n\n// Call when the owning integration is disposed.\nunsubscribe();\n```\n\nThis contract covers `scheme-changed`, `seed-color-changed`,\n`theme-changed`, and `icon-sprite-url-changed`. Components derived from\n`EspalierElementBase` use the same closest-root filter internally.\n\nThe root also owns the application's banner-texture vocabulary:\n`EspalierRoot.registerTexture(name, definition)` registers an\nimage-backed texture preset that any\n[esp-image](/components/image) banner in the application selects with\n`texture=\"<name>\"`, and `EspalierRoot.registeredTextures()` enumerates\nthe presets for building texture pickers.",
+          "description": "Root container for the Espalier design system.\n\nSupplies descendant components with color, size, and font tokens.\nConfigure light and dark themes through JavaScript properties or\nBase64-encoded attributes. The root emits CSS custom properties\nfor the active theme.\n\n### Theme API\n\nSupply a `light-theme` and/or `dark-theme` attribute containing\na **Base64-encoded JSON** partial theme.  Fields you omit fall\nback to built-in defaults.  Switch between them with `scheme`.\n\n```html\n<esp-root\n  light-theme=\"eyJzZWVkQ29sb3IiOiJva2xjaCgwLjcgMC4yIDE1NSkifQ==\"\n  scheme=\"light\">\n  <esp-box>\n    <h2>Themed content</h2>\n  </esp-box>\n</esp-root>\n```\n\n### Nested theme previews and scoped events\n\nA nested root creates a scoped theme for its descendants. It does not create\na separate event bus: every root publishes theme changes through the same\nEspalier singleton. Subscribe through the root whose changes you own so a\nnested preview cannot be mistaken for an application-level theme change.\n\n```ts\nconst applicationRoot = document.querySelector<EspalierRoot>(\"#application-theme\")!;\n\nconst unsubscribe = applicationRoot.subscribeScoped(\"scheme-changed\", ({ scheme }) => {\n  localStorage.setItem(\"scheme\", scheme);\n});\n\n// Initial state is read directly; scoped events report later changes only.\nrenderScheme(applicationRoot.scheme);\n\n// Call when the owning integration is disposed.\nunsubscribe();\n```\n\nThis contract covers `scheme-changed`, `seed-color-changed`,\n`theme-changed`, and `icon-sprite-url-changed`. Components derived from\n`EspalierElementBase` use the same closest-root filter internally.\n\nThe root also owns the application's banner-texture vocabulary:\n`EspalierRoot.registerTexture(name, definition)` registers an\nimage-backed texture preset that any\n[esp-image](/components/image) banner in the application selects with\n`texture=\"<name>\"`, and `EspalierRoot.registeredTextures()` enumerates\nthe presets for building texture pickers.",
           "name": "EspalierRoot",
           "cssProperties": [
             {
@@ -71176,7 +71683,7 @@
               "kind": "field",
               "name": "lightDomStyles",
               "static": true,
-              "default": "` /* ── Base typography ──────────────────────────────────── */ esp-root { font-family: var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif)); font-weight: var(--esp-font-weight-body); line-height: 1.5; font-size: var(--esp-type-normal); color: var(--esp-color-text); } /* ── Lists ────────────────────────────────────────────── */ esp-root ul[role=\"list\"], esp-root ol[role=\"list\"] { list-style: none; } esp-root ul li::marker, esp-root ol li::marker { font-weight: bold; } /* ── Form controls ────────────────────────────────────── */ esp-root input, esp-root select, esp-root button { font-family: var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif)); } /* ── Links ────────────────────────────────────────────── */ esp-root a:not([class]) { text-decoration-skip-ink: auto; font-weight: bold; color: var(--esp-color-link); } esp-root a { text-decoration: underline; text-decoration-skip-ink: auto; color: var(--esp-color-link); } esp-root a:hover { background-color: var(--esp-color-link-hover-bg); color: var(--esp-color-link-hover); text-decoration: none; } /* ── Inherited text styles ────────────────────────────── */ esp-root input, esp-root button, esp-root textarea, esp-root select, esp-root p, esp-root ul, esp-root li { font-family: var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif)); color: var(--esp-color-text); font-size: inherit; } esp-root textarea:not([rows]) { min-height: 10em; } /* ── Headings ─────────────────────────────────────────── */ esp-root h1, esp-root h2, esp-root h3, esp-root h4, esp-root h5 { font-family: var( --_esp-font-headings-effective, var( --esp-font-headings, var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif)) ) ); font-weight: var(--esp-font-weight-headings); color: var(--esp-color-headings); margin: var(--esp-size-small-to-normal) 0 var(--esp-size-tiny-to-small); } esp-root h5 { font-size: var(--esp-type-small); line-height: 1.4; } esp-root h4 { font-size: var(--esp-type-medium); line-height: 1.3; } esp-root h3 { font-size: var(--esp-type-big); line-height: 1.2; } esp-root h2 { font-size: var(--esp-type-large); line-height: 1.15; } esp-root h1 { font-size: var(--esp-type-huge); line-height: 1.1; } /* ── Code / Pre ───────────────────────────────────────── */ esp-root pre, esp-root code { font-family: var(--_esp-font-monospace-effective, var(--esp-font-monospace, monospace)); font-weight: var(--esp-font-weight-monospace); } esp-root code { font-size: var(--esp-type-small); background: var(--esp-color-layer-1); border-radius: var(--esp-size-border-radius); padding: 0 0.35em; display: inline-block; border: 1px dotted var(--esp-color-border); } esp-root pre { background-color: var(--esp-color-layer-1); border-radius: var(--esp-size-border-radius); border: 1px dotted var(--esp-color-border); } esp-root pre > code { font-size: var(--esp-type-tiny); display: block; background: none; border: none; hyphens: none; tab-size: 2; white-space: pre; padding: var(--esp-size-padding); overflow: auto; line-height: 1.8; } /* ── Images ────────────────────────────────────────────── */ esp-root img, esp-root picture { max-width: 100%; display: block; } `",
+              "default": "` ${surfaceLayerAttributes(\"esp-root [surface-layer]\").cssText} /* ── Base typography ──────────────────────────────────── */ esp-root { font-family: var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif)); font-weight: var(--esp-font-weight-body); line-height: 1.5; font-size: var(--esp-type-normal); color: var(--esp-color-text); } /* ── Lists ────────────────────────────────────────────── */ esp-root ul[role=\"list\"], esp-root ol[role=\"list\"] { list-style: none; } esp-root ul li::marker, esp-root ol li::marker { font-weight: bold; } /* ── Form controls ────────────────────────────────────── */ esp-root input, esp-root select, esp-root button { font-family: var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif)); } /* ── Links ────────────────────────────────────────────── */ esp-root a:not([class]) { text-decoration-skip-ink: auto; font-weight: bold; color: var(--esp-color-link); } esp-root a { text-decoration: underline; text-decoration-skip-ink: auto; color: var(--esp-color-link); } esp-root a:hover { background-color: var(--esp-color-link-hover-bg); color: var(--esp-color-link-hover); text-decoration: none; } /* ── Inherited text styles ────────────────────────────── */ esp-root input, esp-root button, esp-root textarea, esp-root select, esp-root p, esp-root ul, esp-root li { font-family: var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif)); color: var(--esp-color-text); font-size: inherit; } esp-root textarea:not([rows]) { min-height: 10em; } /* ── Headings ─────────────────────────────────────────── */ esp-root h1, esp-root h2, esp-root h3, esp-root h4, esp-root h5 { font-family: var( --_esp-font-headings-effective, var( --esp-font-headings, var(--_esp-font-body-effective, var(--esp-font-body, system-ui, sans-serif)) ) ); font-weight: var(--esp-font-weight-headings); color: var(--esp-color-headings); margin: var(--esp-size-small-to-normal) 0 var(--esp-size-tiny-to-small); } esp-root h5 { font-size: var(--esp-type-small); line-height: 1.4; } esp-root h4 { font-size: var(--esp-type-medium); line-height: 1.3; } esp-root h3 { font-size: var(--esp-type-big); line-height: 1.2; } esp-root h2 { font-size: var(--esp-type-large); line-height: 1.15; } esp-root h1 { font-size: var(--esp-type-huge); line-height: 1.1; } /* ── Code / Pre ───────────────────────────────────────── */ esp-root pre, esp-root code { font-family: var(--_esp-font-monospace-effective, var(--esp-font-monospace, monospace)); font-weight: var(--esp-font-weight-monospace); } esp-root code { font-size: var(--esp-type-small); background: var(--esp-color-layer-1); border-radius: var(--esp-size-border-radius); padding: 0 0.35em; display: inline-block; border: 1px dotted var(--esp-color-border); } esp-root pre { background-color: var(--esp-color-layer-1); border-radius: var(--esp-size-border-radius); border: 1px dotted var(--esp-color-border); } esp-root pre > code { font-size: var(--esp-type-tiny); display: block; background: none; border: none; hyphens: none; tab-size: 2; white-space: pre; padding: var(--esp-size-padding); overflow: auto; line-height: 1.8; } /* ── Images ────────────────────────────────────────────── */ esp-root img, esp-root picture { max-width: 100%; display: block; } `",
               "description": "Light-DOM styles injected into `document.head` so that\nslotted content (headings, links, code blocks, lists, etc.)\ninherits the design-system tokens defined on `:host`.\nSelectors are scoped to `esp-root` descendants to avoid\nleaking into content outside the root."
             }
           ],
@@ -71368,7 +71875,7 @@
         },
         {
           "kind": "class",
-          "description": "A horizontal flow: children sit in a wrapping row with a themed gap —\n\"row, wrap, gap Y\" without writing flexbox (ADR-010's micro half).\n\n```html\n<esp-row gap=\"small\" justify=\"between\">\n  <span>Yoga · 60 min</span>\n  <esp-button label=\"Book\"></esp-button>\n</esp-row>\n```\n\nRows wrap by default, so a button row or badge cluster degrades to\nmultiple lines at narrow widths instead of overflowing; set `nowrap`\nfor toolbars that must stay on one line. Cross-axis alignment\ndefaults to `center` — the icon-beside-label, text-beside-button\ncase a row exists for.",
+          "description": "Arranges children in a wrapping row with a themed gap.\n\n```html\n<esp-row gap=\"small\" justify=\"between\">\n  <span>Yoga · 60 min</span>\n  <esp-button label=\"Book\"></esp-button>\n</esp-row>\n```\n\nRows wrap by default, so a button row or badge cluster degrades to\nmultiple lines at narrow widths instead of overflowing; set `nowrap`\nfor toolbars that must stay on one line. Cross-axis alignment\ndefaults to `center` — the icon-beside-label, text-beside-button\ncase a row exists for.",
           "name": "EspalierRow",
           "cssProperties": [
             {
@@ -71376,7 +71883,7 @@
               "name": "--esp-row-gap"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -72255,6 +72762,17 @@
               "description": "Keeps every child on one line instead of wrapping.",
               "fieldName": "nowrap"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -72407,7 +72925,7 @@
               "name": "--esp-search-loading-indicator-track-color"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -73490,6 +74008,17 @@
               "description": "Placeholder text for the search input.",
               "fieldName": "placeholder"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -73591,7 +74120,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A full-bleed page band with a centered content well — the natural host\nfor a theme zone.\n\n`esp-section` paints the local `--esp-color-background` edge to edge\nand centers its content in a capped well. It carries no card identity:\nno raised surface, no border radius, no shadow. Give it a `context`\n(see the theming guide, `/guides/color/theming` on the docs site) and\nthe band renders the zone's complete token table with nothing to\nneutralize:\n\n```html\n<esp-section context=\"inverted\">\n  <h2>The reversed band</h2>\n  <p>Everything in here renders on the zone's tokens, and the band\n  spans its container edge to edge.</p>\n</esp-section>\n```\n\nInside `esp-page kind=\"site\"` sections stack full-width and their\nwells share the page's `--esp-page-well-max-width`, so section\ncontent, the header, and the footer all align on one column. Outside\na page the well defaults to the same width and the band fills\nwhatever container it is given.\n\nThe vertical rhythm defaults to the theme's fluid `--esp-size-section`\nstep. For edge-to-edge content (a full-bleed hero image) clear both\nthe well cap and the inline breathing room —\n`--esp-section-max-width: none; --esp-section-padding-inline: 0;` —\nand drop `--esp-section-padding-block` too when the media should\nmeet the band's edges; the band's zone behavior is unaffected.\n\nA section may also tint one raster alpha mask behind its content.\nThe component owns clipping, no-repeat mask behavior, stacking, and\ninteraction isolation; consumers opt in with the `decoration`\nattribute and supply only the image, semantic tint, position, size, and\nopacity:\n\n```html\n<esp-section\n  decoration\n  style=\"\n    --esp-section-decoration-image: url('/assets/brand-mark.png');\n    --esp-section-decoration-position: calc(100% + 2rem) -2rem;\n    --esp-section-decoration-size: min(34rem, 62%);\n    --esp-section-decoration-opacity: 0.09;\n  \"\n>\n  <h1>Rooted in warmth</h1>\n</esp-section>\n```\n\nWithout `decoration` the section renders no decorative layer at all, and\nthe `--esp-section-decoration-*` hooks have no effect. The attribute is\nwhat keeps an undecorated band free of painted planes: accessibility\nauditors such as axe-core and Lighthouse do not model `mask-image`, so a\ntinted plane hidden only by a mask is read as the background behind every\nword in the section. Set it together with the image, never on its own. A\ndecorated band is audited as though the tint covered it everywhere, so\ntext that passes an audit also reads where it crosses the mark.\n\nCSS image values are trusted stylesheet input. Products that accept image\nreferences from documents or users must enforce their own asset ownership\nand URL policy before mapping a value to this hook.",
+          "description": "A full-bleed page band with a centered content well — the natural host\nfor a theme zone.\n\n`esp-section` paints the local `--esp-color-background` edge to edge\nand centers its content in a capped well. It carries no card identity:\nno raised surface, no border radius, no shadow. Give it a `context`\n(see [theme overview](/espalier-guides/#foundations)) and\nthe band renders the zone's complete token table with nothing to\nneutralize:\n\n```html\n<esp-section context=\"inverted\">\n  <h2>The reversed band</h2>\n  <p>Everything in here renders on the zone's tokens, and the band\n  spans its container edge to edge.</p>\n</esp-section>\n```\n\nInside `esp-page kind=\"site\"` sections stack full-width and their\nwells share the page's `--esp-page-well-max-width`, so section\ncontent, the header, and the footer all align on one column. Outside\na page the well defaults to the same width and the band fills\nwhatever container it is given.\n\nThe vertical rhythm defaults to the theme's fluid `--esp-size-section`\nstep. For edge-to-edge content (a full-bleed hero image) clear both\nthe well cap and the inline breathing room —\n`--esp-section-max-width: none; --esp-section-padding-inline: 0;` —\nand drop `--esp-section-padding-block` too when the media should\nmeet the band's edges; the band's zone behavior is unaffected.\n\nA section may also tint one raster alpha mask behind its content.\nThe component owns clipping, no-repeat mask behavior, stacking, and\ninteraction isolation; consumers opt in with the `decoration`\nattribute and supply only the image, semantic tint, position, size, and\nopacity:\n\n```html\n<esp-section\n  decoration\n  style=\"\n    --esp-section-decoration-image: url('/assets/brand-mark.png');\n    --esp-section-decoration-position: calc(100% + 2rem) -2rem;\n    --esp-section-decoration-size: min(34rem, 62%);\n    --esp-section-decoration-opacity: 0.09;\n  \"\n>\n  <h1>Rooted in warmth</h1>\n</esp-section>\n```\n\nWithout `decoration` the section renders no decorative layer at all, and\nthe `--esp-section-decoration-*` hooks have no effect. The attribute is\nwhat keeps an undecorated band free of painted planes: accessibility\nauditors such as axe-core and Lighthouse do not model `mask-image`, so a\ntinted plane hidden only by a mask is read as the background behind every\nword in the section. Set it together with the image, never on its own. A\ndecorated band is audited as though the tint covered it everywhere, so\ntext that passes an audit also reads where it crosses the mark.\n\nCSS image values are trusted stylesheet input. Products that accept image\nreferences from documents or users must enforce their own asset ownership\nand URL policy before mapping a value to this hook.",
           "name": "EspalierSection",
           "cssProperties": [
             {
@@ -73631,7 +74160,7 @@
               "name": "--esp-section-decoration-opacity"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -74451,6 +74980,17 @@
               "description": "Whether the section paints its decorative mask plane. Set it whenever\n`--esp-section-decoration-image` names an image; without it the\nsection renders no decorative layer and the decoration hooks are\ninert.",
               "fieldName": "decoration"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -74930,7 +75470,7 @@
               "description": "The minimum absolute $L_c$ score (default 60)"
             }
           ],
-          "description": "Ensure that a text color achieves at least the target\n$|L_c|$ against a background color.\n\nIf the current contrast is insufficient, lightness is\nadjusted (made darker on light bg, lighter on dark bg)\nuntil the target is met or the lightness boundary is hit."
+          "description": "Adjust a text color toward the target absolute APCA Lc score.\n\nIf the current contrast is insufficient, lightness is\nadjusted (made darker on light bg, lighter on dark bg)\nuntil the target is met or the lightness boundary is hit."
         },
         {
           "kind": "function",
@@ -75372,13 +75912,13 @@
           "kind": "variable",
           "name": "CONFIGURED_BRAND_LOGO_ASPECT_RATIO",
           "default": "css`3 / 1`",
-          "description": "The ratio a configured-brand logo's box is reserved at before its bytes\narrive, shared by both consumers so they cannot drift apart.\n\nBoth hosts give the logo a definite block size and leave the inline size to\nthe image, so until the image resolves there is no natural ratio to derive it\nfrom: a pending request lays the element out at zero inline size and a failed\none at the width of its alt text. Either way the brand region resizes for a\nreason that has nothing to do with the logo — on first paint, and again on\nevery scheme swap that fails, because both schemes exchange `src` at runtime.\n\nEach host spends it as the fallback of its own\n`--esp-{header,footer}-brand-logo-aspect-ratio`, in an\n`aspect-ratio: auto <ratio>` declaration. `auto` is what makes this one\ndeclaration the whole fix: it keeps a replaced element's *natural* ratio\nauthoritative whenever it has one, so a logo that loads is laid out exactly\nas it is today — including a very wide one, where the inline cap clamps the\nused width without feeding back into the definite block size. The ratio\ngoverns only the states with nothing to measure.\n\n`3 / 1` because the existing caps already imply a wordmark of about that\nshape: the footer's `3rem` block size against a `12rem` inline cap clamps at\n4:1, and the header's `0.72 x --esp-header-height` against the same cap\nclamps near 3.7:1. A 3:1 reservation is therefore never born clamped, so the\nreserved box is always the full ratio box."
+          "description": "Reserve a logo's width while its image is loading or has failed.\n\nThe header and footer give logos a fixed block size, so an image without\nintrinsic dimensions would otherwise have zero width or use its alt text's\nwidth. `aspect-ratio: auto <ratio>` uses this fallback only until a natural\nratio is available, keeping loaded logos unchanged.\n\nThe 3:1 fallback fits below both hosts' existing inline caps, so the initial\nreservation is not clipped."
         },
         {
           "kind": "variable",
           "name": "configuredBrandLogoGeometry",
           "default": "css` .brand-logo { overflow-wrap: anywhere; } `",
-          "description": "Keep a failed logo's alt text from deciding how wide the logo's box is.\n\nThe `alt` text is not suppressed — it still names the image for assistive\ntechnology and still renders as the visible fallback. But a failed image is\nno longer replaced content, so it takes an automatic minimum size from its\nown text, and a minimum wider than the reserved box wins: measured in real\nChrome, a one-word alt of 37 characters pushed the header's logo back out to\nits inline cap and swallowed the reservation whole. Allowing a break anywhere\nmakes that minimum one character wide, so the reserved ratio decides the box\nand the alt text wraps inside it.\n\nThe footer already had this by inheritance — it sets `overflow-wrap` on\n`.configured-brand`, where the header sets it only on `.brand-text` — so this\nmakes the two consumers agree rather than changing the footer. It has no\neffect at all on an image that loads, because replaced content has no text to\nbreak."
+          "description": "Allow failed-image alt text to wrap within the reserved logo width.\n\nA failed image can take its automatic minimum width from its alt text.\nBreaking long words prevents that minimum from overriding the reserved box.\nThe text remains visible and accessible. Loaded images are unaffected."
         },
         {
           "kind": "function",
@@ -76216,11 +76756,11 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Shared base class for Espalier elements.\n\nThe reusable `.esp-field` shell used by text inputs, textareas,\npickers, date pickers, buttons, and similar controls exposes the\nfollowing shared styling hooks:",
+          "description": "Shared base class for Espalier elements.\n\nThe reusable `.esp-field` shell used by text inputs, textareas,\npickers, date pickers, buttons, and similar controls exposes the\nfollowing shared styling hooks:\n\nA field fills one layer above the surface it sits on.",
           "name": "EspalierElementBase",
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background"
             },
             {
@@ -76804,6 +77344,13 @@
           ],
           "events": [],
           "attributes": [
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer"
+            },
             {
               "name": "scheme",
               "type": {
@@ -78912,7 +79459,7 @@
               }
             }
           ],
-          "description": "Compute justified album rows with explicit cell widths.\n\nAlgorithm:\n1. Add images to a row one at a time, scaled to the target row height.\n2. When the combined width overflows the container, the row breaks either\n   before or after the overflowing image — whichever leaves the row height\n   closer to the target. Keeping the image shrinks the row slightly below\n   target; pushing it to the next row stretches the row above target.\n3. Scale the finished row so it fills the container width exactly.\n\nCompleted rows always span the available width. When their justified height exceeds\n`maxRowHeight`, their cells retain their relative widths while expanding to\nthe row width at the ceiling; a renderer can use `object-fit: cover` to crop\nthe resulting cells. A final row below a finite `maxImagesPerRow` instead\nremains partial and preserves its image proportions. Its height is capped by\nthe tallest preceding row (or the target height when it is the only row) and\nby `maxRowHeight`.\n\nWith an omitted or invalid `maxImagesPerRow`, rows are unlimited in length\nand every row is completed."
+          "description": "Compute justified album rows and the geometry a renderer needs for cropping.\n\nCompleted rows fill the available width. A row capped by `maxRowHeight` keeps\nrelative cell widths, allowing `object-fit: cover` to crop its images. A final\nrow below a finite `maxImagesPerRow` remains partial and preserves proportions;\nits height is capped by the preceding rows or target height and `maxRowHeight`.\n\nAn omitted or invalid `maxImagesPerRow` means unlimited, completed rows."
         }
       ],
       "exports": [
@@ -80418,6 +80965,47 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "dist/shared/surface-layer.js",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "surfaceLayerAttributes",
+          "return": {
+            "type": {
+              "text": "CSSResult"
+            }
+          },
+          "parameters": [
+            {
+              "name": "selector",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "defaultLayer",
+              "optional": true,
+              "type": {
+                "text": "SurfaceLayer"
+              }
+            }
+          ],
+          "description": "Support `surface-layer=\"1|2|3|4\"` on consumer surfaces in a shadow root.\nInclude `surfaceLayerAttributes(\":host\")` for the consumer component's host,\nor `surfaceLayerAttributes(\"[surface-layer]\")` for elements inside its shadow\ntree. Espalier installs these rules for its own hosts and root light DOM.\nThe attribute declares depth; consumer components still paint their surface.\nA component that always paints a known layer can pass that depth as its\ndefault, so callers do not need to declare it on each instance."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "surfaceLayerAttributes",
+          "declaration": {
+            "name": "surfaceLayerAttributes",
+            "module": "dist/shared/surface-layer.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "dist/shared/theme-fit-report.js",
@@ -80974,7 +81562,7 @@
             "text": "Readonly<\n  Record<RoleName, Readonly<Record<string, ReadonlyArray<[SemanticColorName, LightnessKey]>>>>\n>"
           },
           "default": "{ canvas: { color: [ [\"background\", \"surface\"], [\"layer1\", \"raised1\"], [\"layer2\", \"raised2\"], [\"layer3\", \"raised3\"], [\"layer4\", \"raised4\"], ], }, ink: { color: [ [\"text\", \"text\"], [\"typeOverline\", \"text\"], [\"typeLabel\", \"text\"], [\"typeLead\", \"text\"], [\"typeCaption\", \"text\"], [\"inputSelection\", \"text\"], ], heading: [ [\"headings\", \"muted\"], [\"headingsHover\", \"ink\"], ], }, accent: { color: [ [\"linkHoverBg\", \"raised2\"], [\"inputSelectionBg\", \"raised2\"], [\"inputCaret\", \"ink\"], ], text: [[\"link\", \"accent\"]], hover: [[\"linkHover\", \"text\"]], }, action: { // Neither stop here is fixed — both are derived per scheme, whether // or not the theme names the slot. See ACTION_SURFACE_TARGET_L, // ROLE_DERIVED_SURFACE, and ROLE_DERIVED_INK. The values below are // the token → stop structure this table exists to declare; the // derivation replaces them at compile time. color: [[\"actionBackground\", \"muted\"]], ink: [[\"actionText\", \"surface\"]], }, structure: { color: [ [\"border\", \"border\"], [\"shadow\", \"shadow\"], ], }, }",
-          "description": "Which semantic tokens each role slot paints, and at which ramp stop.\n\nThis is the compilation table: it turns five designer-facing roles\ninto the twenty-three engine-room tokens. `dangerText` is absent by\ndesign — the status family is reserved and keeps its own source.\n\nThe `accent` role has no body-text slot on purpose. \"Rose is\ndecorative only\" is a structural guarantee here, not a comment: text\nthat must come from the accent family comes through `accent.text`,\nthe deepened variant a designer picked for legibility. `accent.hover`\nlets a hover change *family*, not just lightness — \"plum link, rose\nhover\" is an ordinary brand rule (ESP0172); absent, `linkHover` keeps\nfollowing `accent.text` exactly as before."
+          "description": "Map role slots to semantic tokens and ramp stops.\n\n`dangerText` stays outside the roles layer because status meanings are reserved.\nAccent body copy must use the legible `accent.text` slot. `accent.hover` can\nselect a different family; without it, hovered links follow `accent.text`."
         },
         {
           "kind": "variable",
@@ -81029,7 +81617,7 @@
               }
             }
           ],
-          "description": "Compile roles into semantic mappings.\n\nOnly the tokens a declared role owns are emitted, so a theme that\ndeclares no roles compiles to nothing and every existing theme keeps\nits exact output. Token-level `semanticMappings` layer over the\nresult — the engine room stays available for the cases roles do not\nreach."
+          "description": "Compile declared roles into semantic mappings.\n\nA theme with no roles produces no role overrides. Token-level\n`semanticMappings` take precedence over the compiled result."
         },
         {
           "kind": "function",
@@ -82439,7 +83027,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A range slider for selecting numeric values. Built entirely from\ncustom elements with ARIA `role=\"slider\"` — no native\n`<input type=\"range\">` — for consistent cross-browser styling and\nintentional touch interaction.\n\nOn touch devices, only dragging the thumb changes the value.\nTapping the track is ignored so the user can scroll the page\nwithout accidentally adjusting the slider. On desktop, clicking\nanywhere on the track jumps to that value and begins a drag.\n\nThe slider accepts an accessible name from two sources, checked\nin priority order:\n\n1. Slot content — `<esp-slider>Volume</esp-slider>` renders a\n   visible label and names the slider via `aria-labelledby`.\n2. The `label` attribute — `<esp-slider label=\"Volume\">` applies\n   an invisible `aria-label` when no slot content is present.\n\n```html\n<esp-box>\n  <esp-slider min=\"0\" max=\"10\" step=\"0.5\" value=\"5\">\n    Rating\n  </esp-slider>\n  <esp-slider disabled min=\"0\" max=\"100\" value=\"30\"\n    label=\"Disabled slider\">\n  </esp-slider>\n</esp-box>\n```",
+          "description": "A numeric range slider with ARIA `role=\"slider\"`, keyboard support,\nand separate touch and pointer behavior.\n\nOn touch devices, only dragging the thumb changes the value.\nTapping the track is ignored so the user can scroll the page\nwithout accidentally adjusting the slider. On desktop, clicking\nanywhere on the track jumps to that value and begins a drag.\n\nThe slider accepts an accessible name from two sources, checked\nin priority order:\n\n1. Slot content — `<esp-slider>Volume</esp-slider>` renders a\n   visible label and names the slider via `aria-labelledby`.\n2. The `label` attribute — `<esp-slider label=\"Volume\">` applies\n   an invisible `aria-label` when no slot content is present.\n\n```html\n<esp-box>\n  <esp-slider min=\"0\" max=\"10\" step=\"0.5\" value=\"5\">\n    Rating\n  </esp-slider>\n  <esp-slider disabled min=\"0\" max=\"100\" value=\"30\"\n    label=\"Disabled slider\">\n  </esp-slider>\n</esp-box>\n```",
           "name": "EspalierSlider",
           "cssProperties": [
             {
@@ -82479,7 +83067,7 @@
               "name": "--esp-slider-focus-shadow"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -83841,6 +84429,17 @@
               "description": "Accessible label for the slider. Used as `aria-label` on the\nthumb when no slot content is present. When the default slot\nhas content, `aria-labelledby` takes precedence and this\nproperty is ignored.",
               "fieldName": "label"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -83948,7 +84547,7 @@
         },
         {
           "kind": "class",
-          "description": "A vertical flow: children stack in a column with a themed gap —\n\"column, gap X\" without writing flexbox (ADR-010's micro half).\n\n```html\n<esp-stack gap=\"medium\">\n  <h2>Title</h2>\n  <p>Copy under it.</p>\n  <esp-button label=\"Act\"></esp-button>\n</esp-stack>\n```\n\nThe default cross-axis alignment is `stretch`, matching normal block\nflow: grids, form fields, and text fill the column — with one\ndeliberate exception: slotted `esp-button` and `esp-button-group`\nkeep their natural width, because a field should fill its column\nwhile the submit button under it should not. That is the pairing a\nplain flex column cannot express with any single `align-items`\nvalue. An explicit `align` — `align=\"stretch\"` included, authored as\nan attribute or assigned to the property — governs every child\nuniformly; removing the attribute restores the default state, and\n`align-self` on any child overrides either way.",
+          "description": "Stacks children vertically with a themed gap.\n\n```html\n<esp-stack gap=\"medium\">\n  <h2>Title</h2>\n  <p>Copy under it.</p>\n  <esp-button label=\"Act\"></esp-button>\n</esp-stack>\n```\n\nThe default cross-axis alignment is `stretch`, matching normal block\nflow: grids, form fields, and text fill the column — with one\ndeliberate exception: slotted `esp-button` and `esp-button-group`\nkeep their natural width, because a field should fill its column\nwhile the submit button under it should not. That is the pairing a\nplain flex column cannot express with any single `align-items`\nvalue. An explicit `align` — `align=\"stretch\"` included, authored as\nan attribute or assigned to the property — governs every child\nuniformly; removing the attribute restores the default state, and\n`align-self` on any child overrides either way.",
           "name": "EspalierStack",
           "cssProperties": [
             {
@@ -83956,7 +84555,7 @@
               "name": "--esp-stack-gap"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -84793,6 +85392,17 @@
               "description": "Cross-axis alignment of children: `start`, `center`, `end`, or\n`stretch`.",
               "fieldName": "align"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -84921,7 +85531,7 @@
               "default": "32ch"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -85924,6 +86534,17 @@
               "description": "Visual chrome around the status icon. `pill` renders the filled\ncircular treatment, `outline` keeps only the border, and `none`\nrenders the intent-colored icon alone.",
               "fieldName": "chrome"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -86012,63 +86633,43 @@
     },
     {
       "kind": "javascript-module",
-      "path": "dist/switch/esp-switch.js",
+      "path": "dist/tabs/esp-tab-group.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "A toggle switch for boolean on/off values. Uses a CSS-only\ntrack-and-thumb design with a smooth sliding transition.\nFunctionally equivalent to a checkbox but visually communicates\nan immediate state change rather than a deferred selection.\n\n```html\n<esp-box>\n  <esp-form-item label=\"Notifications\">\n    <esp-switch value=\"notifications\">\n      Enable notifications\n    </esp-switch>\n  </esp-form-item>\n</esp-box>\n```\n\n```html\n<esp-box>\n  <esp-switch checked value=\"dark-mode\">\n    Dark mode\n  </esp-switch>\n  <esp-switch disabled value=\"disabled-opt\">\n    Disabled option\n  </esp-switch>\n</esp-box>\n```\n\n### Text mode\n\nSet `mode=\"text\"` with `off-label` and `on-label` to render a\ntwo-option text toggle instead of a track and thumb. This is\nideal for binary choices like a billing-period selector:\n\n```html\n<esp-box>\n  <esp-switch\n    mode=\"text\"\n    off-label=\"Monthly\"\n    on-label=\"Annual\"\n    value=\"annual\"\n  >Billing period</esp-switch>\n</esp-box>\n```\n\nThe slotted text is visually hidden in text mode and folded\ninto the control's accessible label together with the current\nselected option. Screen readers will announce both the label\nand the active choice while the `off-label` / `on-label`\ntext is presented visually.",
-          "name": "EspalierSwitch",
+          "description": "A tabbed interface that groups multiple\n[esp-tab](/components/tabs) elements. The tab strip is\ngenerated automatically from each child's `label` attribute.\nOnly one tab panel is visible at a time.\n\nA field fills one layer above the surface it sits on.\nUse `surface-layer=\"1|2|3|4\"` to select the default painted layer.\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Overview\">\n    <p>Overview content goes here.</p>\n  </esp-tab>\n  <esp-tab label=\"Details\">\n    <p>Detailed information lives here.</p>\n  </esp-tab>\n  <esp-tab label=\"Settings\">\n    <p>Configuration options.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Pre-selected tab\n\nSet `active` on a child `esp-tab` to make it the initially\nvisible panel:\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Alpha\">\n    <p>Alpha panel.</p>\n  </esp-tab>\n  <esp-tab label=\"Beta\" active>\n    <p>Beta starts active.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Disabled tab\n\nIndividual tabs can be disabled:\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Available\">\n    <p>You can select this tab.</p>\n  </esp-tab>\n  <esp-tab label=\"Locked\" disabled>\n    <p>This tab cannot be reached.</p>\n  </esp-tab>\n  <esp-tab label=\"Also available\">\n    <p>This tab works too.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Disabled group\n\nSet `disabled` on the group to disable all tabs at once:\n\n```html\n<esp-tab-group disabled>\n  <esp-tab label=\"One\">\n    <p>All tabs are disabled.</p>\n  </esp-tab>\n  <esp-tab label=\"Two\">\n    <p>Cannot switch to this.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Zone theming\n\nTab groups pick up zone theming from a `context` attribute:\n\n```html\n<esp-tab-group context=\"quiet\">\n  <esp-tab label=\"First\">\n    <p>Zone-correct content.</p>\n  </esp-tab>\n  <esp-tab label=\"Second\">\n    <p>More content.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Listening for tab changes\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Tab 1\">\n    <p>First panel.</p>\n  </esp-tab>\n  <esp-tab label=\"Tab 2\">\n    <p>Second panel.</p>\n  </esp-tab>\n</esp-tab-group>\n<script>\n  const tabs = findByTagName(\"esp-tab-group\")[0];\n  tabs.addEventListener(\"esp-tab-group-changed\", (ev) => {\n    console.log(\"Switched to:\", ev.detail.label, \"at index\", ev.detail.index);\n  });\n</script>\n```",
+          "name": "EspalierTabGroup",
           "cssProperties": [
             {
-              "description": "The width of the switch track. Defaults to `calc(var(--esp-size-normal-to-medium) * 1.75)`.",
-              "name": "--esp-switch-width"
-            },
-            {
-              "description": "The height of the switch track. Defaults to `var(--esp-size-normal-to-medium)`.",
-              "name": "--esp-switch-height"
-            },
-            {
-              "description": "The diameter of the thumb. Defaults to `calc(var(--esp-switch-height) - 4px)`.",
-              "name": "--esp-switch-thumb-size"
-            },
-            {
-              "description": "The track background color when the switch is off. Defaults to `var(--esp-color-border)`.",
-              "name": "--esp-switch-track-color"
-            },
-            {
-              "description": "The track background color when the switch is on. Defaults to `var(--esp-color-action-background)`.",
-              "name": "--esp-switch-track-color-on"
-            },
-            {
-              "description": "The thumb color. Defaults to `var(--esp-color-layer-1)`.",
-              "name": "--esp-switch-thumb-color"
+              "description": "Border color of the tab group container.",
+              "name": "--esp-tab-color-border"
             },
             {
-              "description": "The color of the focus ring shadow. Defaults to `var(--esp-color-shadow)`.",
-              "name": "--esp-switch-focus-shadow"
+              "description": "Background color of the overall component.",
+              "name": "--esp-tab-color-background"
             },
             {
-              "description": "Padding inside each text-mode label cell. Defaults to `var(--esp-size-tiny) var(--esp-size-small)`.",
-              "name": "--esp-switch-text-padding"
+              "description": "Background color of the tab strip.",
+              "name": "--esp-tab-color-strip-background"
             },
             {
-              "description": "Font size for text-mode labels. Defaults to `var(--esp-size-font)`.",
-              "name": "--esp-switch-text-font-size"
+              "description": "Tab button hover background.",
+              "name": "--esp-tab-color-button-hover"
             },
             {
-              "description": "Text color of the active label in text mode. Defaults to `var(--esp-color-action-text)`.",
-              "name": "--esp-switch-text-active-color"
+              "description": "Active tab button background.",
+              "name": "--esp-tab-color-button-active"
             },
             {
-              "description": "Text color of the inactive label in text mode. Defaults to `var(--esp-color-layer-1)`.",
-              "name": "--esp-switch-text-inactive-color"
+              "description": "Text color for tab buttons.",
+              "name": "--esp-tab-color-text"
             },
             {
-              "description": "Background color of the sliding highlight in text mode. Defaults to `var(--esp-color-action-background)`.",
-              "name": "--esp-switch-text-highlight-color"
+              "description": "Padding inside the panel area and tab buttons.",
+              "name": "--esp-tab-size-padding"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -86124,194 +86725,108 @@
               }
             }
           ],
+          "cssParts": [
+            {
+              "description": "The tab strip container.",
+              "name": "tab-list"
+            },
+            {
+              "description": "Each individual tab button in the strip.",
+              "name": "tab-button"
+            },
+            {
+              "description": "The panel area below the tab strip.",
+              "name": "panels"
+            }
+          ],
           "slots": [
             {
-              "description": "The label text for the switch. In default mode this renders beside the track; in text mode it is visually hidden and included in the control's accessible label.",
+              "description": "Place `esp-tab` elements in the default slot.",
               "name": ""
             }
           ],
           "members": [
             {
               "kind": "field",
-              "name": "formAssociated",
-              "type": {
-                "text": "boolean"
-              },
-              "static": true,
-              "default": "true"
-            },
-            {
-              "kind": "field",
-              "name": "internals",
+              "name": "panelsSlot",
               "privacy": "private"
             },
             {
               "kind": "field",
-              "name": "formCtrl",
-              "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",
-              "type": {
-                "text": "\"switch\" | \"text\""
-              },
-              "privacy": "public",
-              "default": "\"switch\"",
-              "description": "The visual presentation of the switch.\n- `\"switch\"` (default) renders a track-and-thumb toggle.\n- `\"text\"` renders two side-by-side text labels with a\n  sliding highlight behind the active one.",
-              "attribute": "mode",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "offLabel",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "public",
-              "default": "\"\"",
-              "description": "Label shown for the unchecked (off) state when\n`mode=\"text\"`.",
-              "attribute": "off-label"
-            },
-            {
-              "kind": "field",
-              "name": "onLabel",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "public",
-              "default": "\"\"",
-              "description": "Label shown for the checked (on) state when\n`mode=\"text\"`.",
-              "attribute": "on-label"
-            },
-            {
-              "kind": "field",
-              "name": "checked",
-              "type": {
-                "text": "boolean"
-              },
-              "privacy": "public",
-              "default": "false",
-              "description": "Whether the switch is in the on state.",
-              "attribute": "checked",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "value",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "public",
-              "default": "\"\"",
-              "description": "The value associated with this switch. Submitted with the\nform when the switch is on.",
-              "attribute": "value"
-            },
-            {
-              "kind": "field",
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "public",
-              "default": "\"\"",
-              "description": "The name used when the switch participates in a `<form>`.",
-              "attribute": "name",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "required",
+              "name": "disabled",
               "type": {
                 "text": "boolean"
               },
               "privacy": "public",
               "default": "false",
-              "description": "When true, the switch must be on before the form can\nbe submitted.",
-              "attribute": "required",
+              "description": "Disables all tabs in the group, preventing any tab from\nbeing selected.",
+              "attribute": "disabled",
               "reflects": true
             },
             {
               "kind": "field",
-              "name": "requiredMessage",
-              "type": {
-                "text": "string"
-              },
-              "privacy": "public",
-              "default": "\"\"",
-              "description": "A custom message to display when the switch is required but\nnot on. Defaults to `\"Please toggle this switch to continue.\"`\nwhen not set.\n\n```html\n<esp-switch required required-message=\"You must accept the terms.\">\n  I accept\n</esp-switch>\n```",
-              "attribute": "required-message"
-            },
-            {
-              "kind": "field",
-              "name": "disabled",
+              "name": "tabData",
               "type": {
-                "text": "boolean"
+                "text": "TabData[]"
               },
-              "privacy": "public",
-              "default": "false",
-              "description": "Controls whether the switch is disabled.",
-              "attribute": "disabled",
-              "reflects": true
+              "privacy": "private",
+              "default": "[]"
             },
             {
               "kind": "method",
-              "name": "focus",
-              "privacy": "public",
+              "name": "getTabs",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "options",
-                  "optional": true,
-                  "type": {
-                    "text": "FocusOptions"
-                  }
+                  "text": "EspalierTab[]"
                 }
-              ],
-              "description": "Focus the switch control."
+              }
             },
             {
               "kind": "method",
-              "name": "validate",
-              "privacy": "public",
+              "name": "syncTabData",
+              "privacy": "private",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              },
-              "description": "Re-run constraint validation and dispatch `esp-validity-changed`."
+              }
             },
             {
               "kind": "method",
-              "name": "checkValidity",
-              "privacy": "public",
+              "name": "activateTab",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "boolean"
+                  "text": "void"
                 }
               },
-              "description": "Check whether the current state is valid (delegates to ElementInternals)."
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
             },
             {
               "kind": "method",
-              "name": "toggle",
+              "name": "handleTabClick",
               "privacy": "private",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              }
+              },
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
             },
             {
               "kind": "method",
@@ -86333,7 +86848,7 @@
             },
             {
               "kind": "method",
-              "name": "handleLabelSlotChange",
+              "name": "handleChildUpdated",
               "privacy": "private",
               "return": {
                 "type": {
@@ -86343,69 +86858,13 @@
             },
             {
               "kind": "method",
-              "name": "getCurrentTextModeLabel",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "string"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "getTextModeAriaLabel",
+              "name": "handleSlotChange",
               "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "string"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "formResetCallback",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              },
-              "description": "Called by the browser when the owning `<form>` is reset."
-            },
-            {
-              "kind": "method",
-              "name": "formStateRestoreCallback",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "state",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ],
-              "description": "Called by the browser to restore form state (bfcache, etc.)."
-            },
-            {
-              "kind": "method",
-              "name": "formDisabledCallback",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "isDisabled",
-                  "type": {
-                    "text": "boolean"
-                  }
-                }
-              ],
-              "description": "Called by the browser when a parent `<fieldset>` is enabled or disabled."
+              }
             },
             {
               "kind": "field",
@@ -87135,100 +87594,32 @@
           "events": [
             {
               "type": {
-                "text": "CustomEvent<{ checked: boolean; value: string }>"
-              },
-              "description": "Fired when the switch is toggled. The detail contains the new `checked` state and the switch `value`.",
-              "name": "esp-value-changed"
-            },
-            {
-              "type": {
-                "text": "CustomEvent<{ valid: boolean; message: string }>"
+                "text": "CustomEvent<{ index: number; label: string }>"
               },
-              "description": "Fired whenever constraint validation runs.",
-              "name": "esp-validity-changed"
+              "description": "Fired when the active tab changes. The detail contains the `index` and `label` of the newly active tab.",
+              "name": "esp-tab-group-changed"
             }
           ],
           "attributes": [
             {
-              "name": "mode",
-              "type": {
-                "text": "\"switch\" | \"text\""
-              },
-              "default": "\"switch\"",
-              "description": "The visual presentation of the switch.\n- `\"switch\"` (default) renders a track-and-thumb toggle.\n- `\"text\"` renders two side-by-side text labels with a\n  sliding highlight behind the active one.",
-              "fieldName": "mode"
-            },
-            {
-              "name": "off-label",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "description": "Label shown for the unchecked (off) state when\n`mode=\"text\"`.",
-              "fieldName": "offLabel"
-            },
-            {
-              "name": "on-label",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "description": "Label shown for the checked (on) state when\n`mode=\"text\"`.",
-              "fieldName": "onLabel"
-            },
-            {
-              "name": "checked",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Whether the switch is in the on state.",
-              "fieldName": "checked"
-            },
-            {
-              "name": "value",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "description": "The value associated with this switch. Submitted with the\nform when the switch is on.",
-              "fieldName": "value"
-            },
-            {
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "description": "The name used when the switch participates in a `<form>`.",
-              "fieldName": "name"
-            },
-            {
-              "name": "required",
+              "name": "disabled",
               "type": {
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When true, the switch must be on before the form can\nbe submitted.",
-              "fieldName": "required"
-            },
-            {
-              "name": "required-message",
-              "type": {
-                "text": "string"
-              },
-              "default": "\"\"",
-              "description": "A custom message to display when the switch is required but\nnot on. Defaults to `\"Please toggle this switch to continue.\"`\nwhen not set.\n\n```html\n<esp-switch required required-message=\"You must accept the terms.\">\n  I accept\n</esp-switch>\n```",
-              "fieldName": "requiredMessage"
+              "description": "Disables all tabs in the group, preventing any tab from\nbeing selected.",
+              "fieldName": "disabled"
             },
             {
-              "name": "disabled",
               "type": {
-                "text": "boolean"
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
               },
-              "default": "false",
-              "description": "Controls whether the switch is disabled.",
-              "fieldName": "disabled"
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
             },
             {
               "name": "scheme",
@@ -87272,88 +87663,64 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
+          "tagName": "esp-tab-group",
+          "customElement": true,
           "docPageTitle": {
-            "name": "Switch",
-            "description": ""
+            "name": "Tab",
+            "description": "Group"
           },
           "docUrl": {
-            "name": "/components/switch",
+            "name": "/components/tabs",
             "description": ""
           },
           "menuGroup": {
-            "name": "Form",
-            "description": "Controls"
+            "name": "Navigation",
+            "description": ""
           },
           "menuLabel": {
-            "name": "Switch",
-            "description": ""
+            "name": "Tab",
+            "description": "Group"
           },
           "menuIcon": {
-            "name": "button",
+            "name": "layout-navbar",
             "description": ""
-          },
-          "tagName": "esp-switch",
-          "customElement": true
+          }
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierSwitch",
+          "name": "EspalierTabGroup",
           "declaration": {
-            "name": "EspalierSwitch",
-            "module": "dist/switch/esp-switch.js"
+            "name": "EspalierTabGroup",
+            "module": "dist/tabs/esp-tab-group.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-switch",
+          "name": "esp-tab-group",
           "declaration": {
-            "name": "EspalierSwitch",
-            "module": "dist/switch/esp-switch.js"
+            "name": "EspalierTabGroup",
+            "module": "dist/tabs/esp-tab-group.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "dist/tabs/esp-tab-group.js",
+      "path": "dist/tabs/esp-tab.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "A tabbed interface that groups multiple\n[esp-tab](/components/tabs) elements. The tab strip is\ngenerated automatically from each child's `label` attribute.\nOnly one tab panel is visible at a time.\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Overview\">\n    <p>Overview content goes here.</p>\n  </esp-tab>\n  <esp-tab label=\"Details\">\n    <p>Detailed information lives here.</p>\n  </esp-tab>\n  <esp-tab label=\"Settings\">\n    <p>Configuration options.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Pre-selected tab\n\nSet `active` on a child `esp-tab` to make it the initially\nvisible panel:\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Alpha\">\n    <p>Alpha panel.</p>\n  </esp-tab>\n  <esp-tab label=\"Beta\" active>\n    <p>Beta starts active.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Disabled tab\n\nIndividual tabs can be disabled:\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Available\">\n    <p>You can select this tab.</p>\n  </esp-tab>\n  <esp-tab label=\"Locked\" disabled>\n    <p>This tab cannot be reached.</p>\n  </esp-tab>\n  <esp-tab label=\"Also available\">\n    <p>This tab works too.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Disabled group\n\nSet `disabled` on the group to disable all tabs at once:\n\n```html\n<esp-tab-group disabled>\n  <esp-tab label=\"One\">\n    <p>All tabs are disabled.</p>\n  </esp-tab>\n  <esp-tab label=\"Two\">\n    <p>Cannot switch to this.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Zone theming\n\nTab groups pick up zone theming from a `context` attribute:\n\n```html\n<esp-tab-group context=\"quiet\">\n  <esp-tab label=\"First\">\n    <p>Zone-correct content.</p>\n  </esp-tab>\n  <esp-tab label=\"Second\">\n    <p>More content.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Listening for tab changes\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Tab 1\">\n    <p>First panel.</p>\n  </esp-tab>\n  <esp-tab label=\"Tab 2\">\n    <p>Second panel.</p>\n  </esp-tab>\n</esp-tab-group>\n<script>\n  const tabs = findByTagName(\"esp-tab-group\")[0];\n  tabs.addEventListener(\"esp-tab-group-changed\", (ev) => {\n    console.log(\"Switched to:\", ev.detail.label, \"at index\", ev.detail.index);\n  });\n</script>\n```",
-          "name": "EspalierTabGroup",
+          "description": "A single tab panel used inside\n[esp-tab-group](/components/tabs). Each tab provides a\n`label` that appears in the generated tab strip and a default\nslot for the panel content.\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"First\">\n    <p>Content for the first tab.</p>\n  </esp-tab>\n  <esp-tab label=\"Second\">\n    <p>Content for the second tab.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Pre-selected tab\n\nSet the `active` attribute to make a tab active on load:\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"One\">\n    <p>Not active by default.</p>\n  </esp-tab>\n  <esp-tab label=\"Two\" active>\n    <p>This tab starts active.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Disabled tab\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Enabled\">\n    <p>This tab works normally.</p>\n  </esp-tab>\n  <esp-tab label=\"Disabled\" disabled>\n    <p>Cannot reach this panel.</p>\n  </esp-tab>\n</esp-tab-group>\n```",
+          "name": "EspalierTab",
           "cssProperties": [
             {
-              "description": "Border color of the tab group container.",
-              "name": "--esp-tab-color-border"
-            },
-            {
-              "description": "Background color of the overall component.",
-              "name": "--esp-tab-color-background"
-            },
-            {
-              "description": "Background color of the tab strip.",
-              "name": "--esp-tab-color-strip-background"
-            },
-            {
-              "description": "Tab button hover background.",
-              "name": "--esp-tab-color-button-hover"
-            },
-            {
-              "description": "Active tab button background.",
-              "name": "--esp-tab-color-button-active"
-            },
-            {
-              "description": "Text color for tab buttons.",
-              "name": "--esp-tab-color-text"
-            },
-            {
-              "description": "Padding inside the panel area and tab buttons.",
+              "description": "Padding inside the panel area.",
               "name": "--esp-tab-size-padding"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -87411,144 +87778,51 @@
           ],
           "cssParts": [
             {
-              "description": "The tab strip container.",
-              "name": "tab-list"
-            },
-            {
-              "description": "Each individual tab button in the strip.",
-              "name": "tab-button"
-            },
-            {
-              "description": "The panel area below the tab strip.",
-              "name": "panels"
+              "description": "The panel wrapper element.",
+              "name": "panel"
             }
           ],
           "slots": [
             {
-              "description": "Place `esp-tab` elements in the default slot.",
+              "description": "The default slot holds the panel content displayed when this tab is active. Label, active-state, and disabled-state updates are reported through a private coordination event consumed by the parent tab group.",
               "name": ""
             }
           ],
           "members": [
             {
               "kind": "field",
-              "name": "panelsSlot",
-              "privacy": "private"
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "The text displayed in the tab button within the tab strip.",
+              "attribute": "label"
             },
             {
               "kind": "field",
-              "name": "disabled",
+              "name": "active",
               "type": {
                 "text": "boolean"
               },
               "privacy": "public",
               "default": "false",
-              "description": "Disables all tabs in the group, preventing any tab from\nbeing selected.",
-              "attribute": "disabled",
+              "description": "Whether this tab is currently active (its panel is visible).",
+              "attribute": "active",
               "reflects": true
             },
             {
               "kind": "field",
-              "name": "tabData",
+              "name": "disabled",
               "type": {
-                "text": "TabData[]"
-              },
-              "privacy": "private",
-              "default": "[]"
-            },
-            {
-              "kind": "method",
-              "name": "getTabs",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "EspalierTab[]"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "syncTabData",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "activateTab",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "index",
-                  "type": {
-                    "text": "number"
-                  }
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "handleTabClick",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "index",
-                  "type": {
-                    "text": "number"
-                  }
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "handleKeyDown",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+                "text": "boolean"
               },
-              "parameters": [
-                {
-                  "name": "ev",
-                  "type": {
-                    "text": "KeyboardEvent"
-                  }
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "handleChildUpdated",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "handleSlotChange",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether this tab is disabled (cannot be selected).",
+              "attribute": "disabled",
+              "reflects": true
             },
             {
               "kind": "field",
@@ -88275,25 +88549,46 @@
               }
             }
           ],
-          "events": [
+          "events": [],
+          "attributes": [
             {
+              "name": "label",
               "type": {
-                "text": "CustomEvent<{ index: number; label: string }>"
+                "text": "string"
               },
-              "description": "Fired when the active tab changes. The detail contains the `index` and `label` of the newly active tab.",
-              "name": "esp-tab-group-changed"
-            }
-          ],
-          "attributes": [
+              "default": "\"\"",
+              "description": "The text displayed in the tab button within the tab strip.",
+              "fieldName": "label"
+            },
+            {
+              "name": "active",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this tab is currently active (its panel is visible).",
+              "fieldName": "active"
+            },
             {
               "name": "disabled",
               "type": {
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Disables all tabs in the group, preventing any tab from\nbeing selected.",
+              "description": "Whether this tab is disabled (cannot be selected).",
               "fieldName": "disabled"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -88336,64 +88631,100 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
-          "tagName": "esp-tab-group",
+          "tagName": "esp-tab",
           "customElement": true,
           "docPageTitle": {
             "name": "Tab",
-            "description": "Group"
+            "description": ""
           },
           "docUrl": {
-            "name": "/components/tabs",
+            "name": "/components/tabs/tab",
             "description": ""
           },
           "menuGroup": {
             "name": "Navigation",
             "description": ""
-          },
-          "menuLabel": {
-            "name": "Tab",
-            "description": "Group"
-          },
-          "menuIcon": {
-            "name": "layout-navbar",
-            "description": ""
           }
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierTabGroup",
+          "name": "EspalierTab",
           "declaration": {
-            "name": "EspalierTabGroup",
-            "module": "dist/tabs/esp-tab-group.js"
+            "name": "EspalierTab",
+            "module": "dist/tabs/esp-tab.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-tab-group",
+          "name": "esp-tab",
           "declaration": {
-            "name": "EspalierTabGroup",
-            "module": "dist/tabs/esp-tab-group.js"
+            "name": "EspalierTab",
+            "module": "dist/tabs/esp-tab.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "dist/tabs/esp-tab.js",
+      "path": "dist/switch/esp-switch.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "A single tab panel used inside\n[esp-tab-group](/components/tabs). Each tab provides a\n`label` that appears in the generated tab strip and a default\nslot for the panel content.\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"First\">\n    <p>Content for the first tab.</p>\n  </esp-tab>\n  <esp-tab label=\"Second\">\n    <p>Content for the second tab.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Pre-selected tab\n\nSet the `active` attribute to make a tab active on load:\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"One\">\n    <p>Not active by default.</p>\n  </esp-tab>\n  <esp-tab label=\"Two\" active>\n    <p>This tab starts active.</p>\n  </esp-tab>\n</esp-tab-group>\n```\n\n### Disabled tab\n\n```html\n<esp-tab-group>\n  <esp-tab label=\"Enabled\">\n    <p>This tab works normally.</p>\n  </esp-tab>\n  <esp-tab label=\"Disabled\" disabled>\n    <p>Cannot reach this panel.</p>\n  </esp-tab>\n</esp-tab-group>\n```",
-          "name": "EspalierTab",
+          "description": "An on/off switch for settings that take effect immediately. Use a\ncheckbox when the choice should be applied with a later form submission.\n\n```html\n<esp-box>\n  <esp-form-item label=\"Notifications\">\n    <esp-switch value=\"notifications\">\n      Enable notifications\n    </esp-switch>\n  </esp-form-item>\n</esp-box>\n```\n\n```html\n<esp-box>\n  <esp-switch checked value=\"dark-mode\">\n    Dark mode\n  </esp-switch>\n  <esp-switch disabled value=\"disabled-opt\">\n    Disabled option\n  </esp-switch>\n</esp-box>\n```\n\n### Text mode\n\nSet `mode=\"text\"` with `off-label` and `on-label` to render a\ntwo-option text toggle instead of a track and thumb. This is\nideal for binary choices like a billing-period selector:\n\n```html\n<esp-box>\n  <esp-switch\n    mode=\"text\"\n    off-label=\"Monthly\"\n    on-label=\"Annual\"\n    value=\"annual\"\n  >Billing period</esp-switch>\n</esp-box>\n```\n\nThe slotted text is visually hidden in text mode and folded\ninto the control's accessible label together with the current\nselected option. Screen readers will announce both the label\nand the active choice while the `off-label` / `on-label`\ntext is presented visually.",
+          "name": "EspalierSwitch",
           "cssProperties": [
             {
-              "description": "Padding inside the panel area.",
-              "name": "--esp-tab-size-padding"
+              "description": "The width of the switch track. Defaults to `calc(var(--esp-size-normal-to-medium) * 1.75)`.",
+              "name": "--esp-switch-width"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "The height of the switch track. Defaults to `var(--esp-size-normal-to-medium)`.",
+              "name": "--esp-switch-height"
+            },
+            {
+              "description": "The diameter of the thumb. Defaults to `calc(var(--esp-switch-height) - 4px)`.",
+              "name": "--esp-switch-thumb-size"
+            },
+            {
+              "description": "The track background color when the switch is off. Defaults to `var(--esp-color-border)`.",
+              "name": "--esp-switch-track-color"
+            },
+            {
+              "description": "The track background color when the switch is on. Defaults to `var(--esp-color-action-background)`.",
+              "name": "--esp-switch-track-color-on"
+            },
+            {
+              "description": "The thumb color. Defaults to `var(--esp-color-layer-1)`.",
+              "name": "--esp-switch-thumb-color"
+            },
+            {
+              "description": "The color of the focus ring shadow. Defaults to `var(--esp-color-shadow)`.",
+              "name": "--esp-switch-focus-shadow"
+            },
+            {
+              "description": "Padding inside each text-mode label cell. Defaults to `var(--esp-size-tiny) var(--esp-size-small)`.",
+              "name": "--esp-switch-text-padding"
+            },
+            {
+              "description": "Font size for text-mode labels. Defaults to `var(--esp-size-font)`.",
+              "name": "--esp-switch-text-font-size"
+            },
+            {
+              "description": "Text color of the active label in text mode. Defaults to `var(--esp-color-action-text)`.",
+              "name": "--esp-switch-text-active-color"
+            },
+            {
+              "description": "Text color of the inactive label in text mode. Defaults to `var(--esp-color-layer-1)`.",
+              "name": "--esp-switch-text-inactive-color"
+            },
+            {
+              "description": "Background color of the sliding highlight in text mode. Defaults to `var(--esp-color-action-background)`.",
+              "name": "--esp-switch-text-highlight-color"
+            },
+            {
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -88449,42 +88780,131 @@
               }
             }
           ],
-          "cssParts": [
-            {
-              "description": "The panel wrapper element.",
-              "name": "panel"
-            }
-          ],
           "slots": [
             {
-              "description": "The default slot holds the panel content displayed when this tab is active. Label, active-state, and disabled-state updates are reported through a private coordination event consumed by the parent tab group.",
+              "description": "The label text for the switch. In default mode this renders beside the track; in text mode it is visually hidden and included in the control's accessible label.",
               "name": ""
             }
           ],
           "members": [
             {
               "kind": "field",
-              "name": "label",
+              "name": "formAssociated",
+              "type": {
+                "text": "boolean"
+              },
+              "static": true,
+              "default": "true"
+            },
+            {
+              "kind": "field",
+              "name": "internals",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "formCtrl",
+              "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",
+              "type": {
+                "text": "\"switch\" | \"text\""
+              },
+              "privacy": "public",
+              "default": "\"switch\"",
+              "description": "The visual presentation of the switch.\n- `\"switch\"` (default) renders a track-and-thumb toggle.\n- `\"text\"` renders two side-by-side text labels with a\n  sliding highlight behind the active one.",
+              "attribute": "mode",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "offLabel",
               "type": {
                 "text": "string"
               },
               "privacy": "public",
               "default": "\"\"",
-              "description": "The text displayed in the tab button within the tab strip.",
-              "attribute": "label"
+              "description": "Label shown for the unchecked (off) state when\n`mode=\"text\"`.",
+              "attribute": "off-label"
             },
             {
               "kind": "field",
-              "name": "active",
+              "name": "onLabel",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "Label shown for the checked (on) state when\n`mode=\"text\"`.",
+              "attribute": "on-label"
+            },
+            {
+              "kind": "field",
+              "name": "checked",
               "type": {
                 "text": "boolean"
               },
               "privacy": "public",
               "default": "false",
-              "description": "Whether this tab is currently active (its panel is visible).",
-              "attribute": "active",
+              "description": "Whether the switch is in the on state.",
+              "attribute": "checked",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "The value associated with this switch. Submitted with the\nform when the switch is on.",
+              "attribute": "value"
+            },
+            {
+              "kind": "field",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "The name used when the switch participates in a `<form>`.",
+              "attribute": "name",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "required",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "When true, the switch must be on before the form can\nbe submitted.",
+              "attribute": "required",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "requiredMessage",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "default": "\"\"",
+              "description": "A custom message to display when the switch is required but\nnot on. Defaults to `\"Please toggle this switch to continue.\"`\nwhen not set.\n\n```html\n<esp-switch required required-message=\"You must accept the terms.\">\n  I accept\n</esp-switch>\n```",
+              "attribute": "required-message"
+            },
             {
               "kind": "field",
               "name": "disabled",
@@ -88493,10 +88913,156 @@
               },
               "privacy": "public",
               "default": "false",
-              "description": "Whether this tab is disabled (cannot be selected).",
+              "description": "Controls whether the switch is disabled.",
               "attribute": "disabled",
               "reflects": true
             },
+            {
+              "kind": "method",
+              "name": "focus",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "FocusOptions"
+                  }
+                }
+              ],
+              "description": "Focus the switch control."
+            },
+            {
+              "kind": "method",
+              "name": "validate",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Re-run constraint validation and dispatch `esp-validity-changed`."
+            },
+            {
+              "kind": "method",
+              "name": "checkValidity",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "description": "Check whether the current state is valid (delegates to ElementInternals)."
+            },
+            {
+              "kind": "method",
+              "name": "toggle",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleKeyDown",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "ev",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "handleLabelSlotChange",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getCurrentTextModeLabel",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getTextModeAriaLabel",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "formResetCallback",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Called by the browser when the owning `<form>` is reset."
+            },
+            {
+              "kind": "method",
+              "name": "formStateRestoreCallback",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "state",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Called by the browser to restore form state (bfcache, etc.)."
+            },
+            {
+              "kind": "method",
+              "name": "formDisabledCallback",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "isDisabled",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Called by the browser when a parent `<fieldset>` is enabled or disabled."
+            },
             {
               "kind": "field",
               "name": "seedColorBacker",
@@ -89222,25 +89788,94 @@
               }
             }
           ],
-          "events": [],
+          "events": [
+            {
+              "type": {
+                "text": "CustomEvent<{ checked: boolean; value: string }>"
+              },
+              "description": "Fired when the switch is toggled. The detail contains the new `checked` state and the switch `value`.",
+              "name": "esp-value-changed"
+            },
+            {
+              "type": {
+                "text": "CustomEvent<{ valid: boolean; message: string }>"
+              },
+              "description": "Fired whenever constraint validation runs.",
+              "name": "esp-validity-changed"
+            }
+          ],
           "attributes": [
             {
-              "name": "label",
+              "name": "mode",
+              "type": {
+                "text": "\"switch\" | \"text\""
+              },
+              "default": "\"switch\"",
+              "description": "The visual presentation of the switch.\n- `\"switch\"` (default) renders a track-and-thumb toggle.\n- `\"text\"` renders two side-by-side text labels with a\n  sliding highlight behind the active one.",
+              "fieldName": "mode"
+            },
+            {
+              "name": "off-label",
               "type": {
                 "text": "string"
               },
               "default": "\"\"",
-              "description": "The text displayed in the tab button within the tab strip.",
-              "fieldName": "label"
+              "description": "Label shown for the unchecked (off) state when\n`mode=\"text\"`.",
+              "fieldName": "offLabel"
             },
             {
-              "name": "active",
+              "name": "on-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "Label shown for the checked (on) state when\n`mode=\"text\"`.",
+              "fieldName": "onLabel"
+            },
+            {
+              "name": "checked",
               "type": {
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether this tab is currently active (its panel is visible).",
-              "fieldName": "active"
+              "description": "Whether the switch is in the on state.",
+              "fieldName": "checked"
+            },
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "The value associated with this switch. Submitted with the\nform when the switch is on.",
+              "fieldName": "value"
+            },
+            {
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "The name used when the switch participates in a `<form>`.",
+              "fieldName": "name"
+            },
+            {
+              "name": "required",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When true, the switch must be on before the form can\nbe submitted.",
+              "fieldName": "required"
+            },
+            {
+              "name": "required-message",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "A custom message to display when the switch is required but\nnot on. Defaults to `\"Please toggle this switch to continue.\"`\nwhen not set.\n\n```html\n<esp-switch required required-message=\"You must accept the terms.\">\n  I accept\n</esp-switch>\n```",
+              "fieldName": "requiredMessage"
             },
             {
               "name": "disabled",
@@ -89248,9 +89883,20 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether this tab is disabled (cannot be selected).",
+              "description": "Controls whether the switch is disabled.",
               "fieldName": "disabled"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -89293,37 +89939,45 @@
             "name": "EspalierElementBase",
             "module": "dist/shared/esp-element-base.js"
           },
-          "tagName": "esp-tab",
-          "customElement": true,
           "docPageTitle": {
-            "name": "Tab",
+            "name": "Switch",
             "description": ""
           },
           "docUrl": {
-            "name": "/components/tabs/tab",
+            "name": "/components/switch",
             "description": ""
           },
           "menuGroup": {
-            "name": "Navigation",
+            "name": "Form",
+            "description": "Controls"
+          },
+          "menuLabel": {
+            "name": "Switch",
             "description": ""
-          }
+          },
+          "menuIcon": {
+            "name": "button",
+            "description": ""
+          },
+          "tagName": "esp-switch",
+          "customElement": true
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "EspalierTab",
+          "name": "EspalierSwitch",
           "declaration": {
-            "name": "EspalierTab",
-            "module": "dist/tabs/esp-tab.js"
+            "name": "EspalierSwitch",
+            "module": "dist/switch/esp-switch.js"
           }
         },
         {
           "kind": "custom-element-definition",
-          "name": "esp-tab",
+          "name": "esp-switch",
           "declaration": {
-            "name": "EspalierTab",
-            "module": "dist/tabs/esp-tab.js"
+            "name": "EspalierSwitch",
+            "module": "dist/switch/esp-switch.js"
           }
         }
       ]
@@ -90502,6 +91156,17 @@
               "description": "Maximum number of characters.",
               "fieldName": "maxlength"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -90568,7 +91233,7 @@
           },
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -90667,7 +91332,7 @@
               "name": "--esp-toaster-padding"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -91631,6 +92296,17 @@
           "tagName": "esp-toaster",
           "customElement": true,
           "attributes": [
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -91737,7 +92413,7 @@
               "name": "--esp-tooltip-focus-outline"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -92743,6 +93419,17 @@
               "description": "Tabindex applied to the tooltip trigger span.\n\nLeave it unset to get the right default automatically: a tooltip\nwrapping a focusable button (`<button>` or `<esp-button>`) takes its\nwrapper span out of the tab order (`-1`) so it does not add a second,\nredundant tab stop, while a tooltip wrapping non-interactive content\n(an icon, an abbreviation, plain text) keeps the wrapper focusable\n(`0`) so keyboard users can still reveal it on focus.\n\nSet it explicitly to override that auto-detection — for example\n`trigger-tabindex=\"0\"` to force a focusable wrapper, or\n`trigger-tabindex=\"-1\"` to opt a non-button trigger out. An explicit\nvalue always wins; a non-numeric or `NaN` value falls back to `0`.\n\nWhen the wrapper leaves the tab order, keyboard focus lands on the\nslotted control instead, so the tooltip's `aria-describedby` is\nmirrored onto that control and assistive tech still announces the\ndescription on focus.",
               "fieldName": "triggerTabindex"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -93794,6 +94481,17 @@
               "description": "Marks a branch whose children are lazy-loaded by the tree's\n`loadChildren` callback on first expand.",
               "fieldName": "hasChildren"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -93856,7 +94554,7 @@
           "customElement": true,
           "cssProperties": [
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -93975,7 +94673,7 @@
         },
         {
           "kind": "class",
-          "description": "A form-associated hierarchy primitive for displaying and selecting\nfrom a slug-structured tree — a folder/path picker, a category\nchooser, or any place a flat field should become an expandable tree.\nFor static declarative node definitions, see\n[`<esp-tree-item>`](/components/tree/item/).\n\nThe name is apt: an espalier is a tree trained flat against a frame,\nso the visual language — branches trained to vertical guide wires,\ngrafting a new shoot onto an existing limb — is the component's own\nmetaphor.\n\n## Data-driven first, composition-capable\n\nBind a hierarchy to the `nodes` property for the primary, data-driven\nAPI. For static trees, nest\n[`<esp-tree-item>`](/components/tree/item) children instead — they are\nparsed into the same model, so the keyboard and accessibility model is\nidentical either way. When both are supplied, `nodes` wins. Data-driven\nnodes must provide stable, unique `id` values; the tree keys expansion,\nlazy loading, focus, and host re-feeds by `id` so relabeling or moving a\nnode can change its path without changing its identity.\n\n```html\n<esp-form-item label=\"Folder\">\n  <esp-tree name=\"folder\" required></esp-tree>\n</esp-form-item>\n<script>\n  const tree = findByTagName(\"esp-tree\")[0];\n  tree.nodes = [\n    { id: \"weddings\", segment: \"weddings\", label: \"Weddings\", children: [\n      { id: \"w2026\", segment: \"2026\", label: \"2026\" },\n    ] },\n    { id: \"portraits\", segment: \"portraits\", label: \"Portraits\" },\n  ];\n</script>\n```\n\nNodes may also carry opaque host data. The tree never reads into `data`;\nit carries the value through select, edit, toggle, and graft events so a\nhost can round-trip its own model without a side lookup.\n\n```html\n<esp-tree id=\"navigation\"></esp-tree>\n<script>\n  const tree = findById(\"navigation\");\n  tree.nodes = [\n    {\n      id: \"nav-about\",\n      segment: \"about\",\n      label: \"About Us\",\n      data: { target: { kind: \"page\", pageId: \"about-us\" } },\n      editable: true,\n    },\n  ];\n  tree.addEventListener(\"esp-tree-select\", (event) => {\n    console.log(event.detail.node.id, event.detail.node.data);\n  });\n</script>\n```\n\n## Selection and form value\n\nSingle-select for v1. Clicking a selectable row selects it; selecting\na branch opens it, and clicking an already-selected branch toggles it\nopen or closed. Selecting a row outside the open selected branch\ncollapses that branch unless `keep-expanded` is set. Branches can also\nexpand and collapse through the leading icon button or with keyboard:\n`ArrowRight` expands closed branches first, then focuses a row's\ntrailing action button when one is present; `ArrowLeft` collapses or\nmoves to the parent. `Enter` and `Space` select the focused row. The\nsubmitted form value is the selected node's full path\n(defaulting to root-inclusive web paths like `/weddings/2026`), or\n`null` when nothing is selected. The root row is always present,\ndefaults to label and path `/`, and is selectable by default; set\n`root-selectable=\"false\"` when the root should be navigation-only.\nValidity reflects the committed selection through the standard\nEspalier form flow.\n\n## Lazy loading\n\nMark a branch with `hasChildren` and set the `loadChildren` callback to\nfetch its children on first expand. Expansion state is stable across\nre-renders and reloads.\n\n```html\n<esp-tree id=\"lazy\"></esp-tree>\n<script>\n  const tree = findById(\"lazy\");\n  tree.nodes = [{ id: \"root\", segment: \"library\", label: \"Library\", hasChildren: true }];\n  tree.loadChildren = async () => {\n    const res = await fetch(\"/assets/data/tree-library-children.json\");\n    return await res.json();\n  };\n</script>\n```\n\n## Grafting a new branch\n\nSet `allow-graft` to expose inline `+` affordances at the level where\na new child would appear. Clicking one opens the built-in graft\ndialog, which shows the parent and resulting path while the value is\nnormalized to a valid web-path segment. Enter commits, Escape\ncancels. Keyboard users can press `Insert` on the focused row to add\nbeneath it. Newly grafted branches are ephemeral client state the\nhost reads back via events — the component persists nothing.\n\n```html\n<esp-tree id=\"graftable\" allow-graft></esp-tree>\n<script>\n  const tree = findById(\"graftable\");\n  tree.nodes = [\n    { id: \"weddings\", segment: \"weddings\", label: \"Weddings\", children: [\n      { id: \"w2026\", segment: \"2026\", label: \"2026\" },\n    ] },\n    { id: \"portraits\", segment: \"portraits\", label: \"Portraits\" },\n  ];\n  tree.addEventListener(\"esp-tree-graft\", (e) => {\n    console.log(\"grafted\", e.detail.path);\n  });\n</script>\n```\n\nAs the input changes, the tree emits a live `esp-tree-graft-input`\nevent. A consumer can run an async check the offline component cannot\n(most importantly a server-side duplicate not present in the loaded\nchildren) and push the result back with `setGraftError(message)`; the\ntree then shows it inline and blocks the commit until it is cleared.\nFor advanced add flows, listen for the cancelable\n`esp-tree-graft-request` event and call `preventDefault()` to skip\nthe default dialog.\n\nReplace the `buildPath` property to use non-web path semantics, and\nreplace `normalizeGraftSegment` to loosen, tighten, or completely\nskip the default web-slug normalization used by the graft dialog.\n\n## Node actions\n\nMark a node with `editable: true` to render an edit action on the\ntrailing side of the row. Clicking it, or pressing `F2` on the\nfocused row, emits `esp-tree-edit` with the node path and public node\ndata so the host can open its own editor. Optional flags\n(`deletable`, `movableUp`, `movableDown`, `cuttable`, and\n`pasteChildTarget`) expose the matching built-in editing actions for\nhost-owned tree workflows.\n\nIf a row has exactly one action, the tree renders one trailing\nicon-only `esp-button` with an accessible label such as `Edit About`.\nIf a row has more than one action, the actions collapse into one\ntrailing `esp-action-menu` trigger so rows never accumulate multiple\nvisible action buttons. The tree only emits events — it does not\ndelete, move, cut, paste, mutate source nodes, or own clipboard state.\n\n```html\n<esp-tree id=\"navigation\"></esp-tree>\n<script>\n  const tree = findById(\"navigation\");\n  tree.nodes = [\n    {\n      id: \"about\",\n      segment: \"about\",\n      label: \"About\",\n      editable: true,\n      deletable: true,\n      movableDown: true,\n      cuttable: true,\n      children: [\n        {\n          id: \"team\",\n          segment: \"team\",\n          label: \"Team\",\n          editable: true,\n        },\n      ],\n    },\n    {\n      id: \"services\",\n      segment: \"services\",\n      label: \"Services\",\n      pasteChildTarget: true,\n    },\n  ];\n  tree.addEventListener(\"esp-tree-cut\", (event) => {\n    console.log(\"cut requested\", event.detail.path);\n  });\n  tree.addEventListener(\"esp-tree-paste-child\", (event) => {\n    console.log(\"paste as child requested\", event.detail.path);\n  });\n</script>\n```\n\n## Expand/collapse icon\n\nThe expand/collapse caret ships inline with the component, so unlike\nnode `icon`s it needs no icon sprite to be hosted. Override it by\nsetting the `expandIcon` property to your own (trusted) SVG markup; it\nrenders on every branch toggle and is rotated 90° when the branch is\nopen, so provide a right-pointing icon. For icon pairs that should not\nrotate, set `collapseIcon` to the trusted SVG markup to use while the\nbranch is open.\n\n```html\n<esp-tree id=\"custom-caret\"></esp-tree>\n<script>\n  const tree = findById(\"custom-caret\");\n  tree.nodes = [\n    { id: \"weddings\", segment: \"weddings\", label: \"Weddings\", children: [\n      { id: \"w2026\", segment: \"2026\", label: \"2026\" },\n    ] },\n  ];\n  // A filled triangle caret instead of the default outline chevron.\n  tree.expandIcon = `<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"\n    fill=\"currentColor\" stroke=\"none\"><path d=\"M9 6l6 6l-6 6z\" /></svg>`;\n</script>\n```",
+          "description": "A form-associated hierarchy primitive for displaying and selecting\nfrom a slug-structured tree — a folder/path picker, a category\nchooser, or any place a flat field should become an expandable tree.\nFor static declarative node definitions, see\n[`<esp-tree-item>`](/components/tree/item/).\n\n## Data-driven first, composition-capable\n\nBind a hierarchy to the `nodes` property for the primary, data-driven\nAPI. For static trees, nest\n[`<esp-tree-item>`](/components/tree/item) children instead — they are\nparsed into the same model, so the keyboard and accessibility model is\nidentical either way. When both are supplied, `nodes` wins. Data-driven\nnodes must provide stable, unique `id` values; the tree keys expansion,\nlazy loading, focus, and host re-feeds by `id` so relabeling or moving a\nnode can change its path without changing its identity.\n\n```html\n<esp-form-item label=\"Folder\">\n  <esp-tree name=\"folder\" required></esp-tree>\n</esp-form-item>\n<script>\n  const tree = findByTagName(\"esp-tree\")[0];\n  tree.nodes = [\n    { id: \"weddings\", segment: \"weddings\", label: \"Weddings\", children: [\n      { id: \"w2026\", segment: \"2026\", label: \"2026\" },\n    ] },\n    { id: \"portraits\", segment: \"portraits\", label: \"Portraits\" },\n  ];\n</script>\n```\n\nNodes may also carry opaque host data. The tree never reads into `data`;\nit carries the value through select, edit, toggle, and graft events so a\nhost can round-trip its own model without a side lookup.\n\n```html\n<esp-tree id=\"navigation\"></esp-tree>\n<script>\n  const tree = findById(\"navigation\");\n  tree.nodes = [\n    {\n      id: \"nav-about\",\n      segment: \"about\",\n      label: \"About Us\",\n      data: { target: { kind: \"page\", pageId: \"about-us\" } },\n      editable: true,\n    },\n  ];\n  tree.addEventListener(\"esp-tree-select\", (event) => {\n    console.log(event.detail.node.id, event.detail.node.data);\n  });\n</script>\n```\n\n## Selection and form value\n\nSingle-select for v1. Clicking a selectable row selects it; selecting\na branch opens it, and clicking an already-selected branch toggles it\nopen or closed. Selecting a row outside the open selected branch\ncollapses that branch unless `keep-expanded` is set. Branches can also\nexpand and collapse through the leading icon button or with keyboard:\n`ArrowRight` expands closed branches first, then focuses a row's\ntrailing action button when one is present; `ArrowLeft` collapses or\nmoves to the parent. `Enter` and `Space` select the focused row. The\nsubmitted form value is the selected node's full path\n(defaulting to root-inclusive web paths like `/weddings/2026`), or\n`null` when nothing is selected. The root row is always present,\ndefaults to label and path `/`, and is selectable by default; set\n`root-selectable=\"false\"` when the root should be navigation-only.\nValidity reflects the committed selection through the standard\nEspalier form flow.\n\n## Lazy loading\n\nMark a branch with `hasChildren` and set the `loadChildren` callback to\nfetch its children on first expand. Expansion state is stable across\nre-renders and reloads.\n\n```html\n<esp-tree id=\"lazy\"></esp-tree>\n<script>\n  const tree = findById(\"lazy\");\n  tree.nodes = [{ id: \"root\", segment: \"library\", label: \"Library\", hasChildren: true }];\n  tree.loadChildren = async () => {\n    const res = await fetch(\"/assets/data/tree-library-children.json\");\n    return await res.json();\n  };\n</script>\n```\n\n## Grafting a new branch\n\nSet `allow-graft` to expose inline `+` affordances at the level where\na new child would appear. Clicking one opens the built-in graft\ndialog, which shows the parent and resulting path while the value is\nnormalized to a valid web-path segment. Enter commits, Escape\ncancels. Keyboard users can press `Insert` on the focused row to add\nbeneath it. Newly grafted branches are ephemeral client state the\nhost reads back via events — the component persists nothing.\n\n```html\n<esp-tree id=\"graftable\" allow-graft></esp-tree>\n<script>\n  const tree = findById(\"graftable\");\n  tree.nodes = [\n    { id: \"weddings\", segment: \"weddings\", label: \"Weddings\", children: [\n      { id: \"w2026\", segment: \"2026\", label: \"2026\" },\n    ] },\n    { id: \"portraits\", segment: \"portraits\", label: \"Portraits\" },\n  ];\n  tree.addEventListener(\"esp-tree-graft\", (e) => {\n    console.log(\"grafted\", e.detail.path);\n  });\n</script>\n```\n\nAs the input changes, the tree emits a live `esp-tree-graft-input`\nevent. A consumer can run an async check the offline component cannot\n(most importantly a server-side duplicate not present in the loaded\nchildren) and push the result back with `setGraftError(message)`; the\ntree then shows it inline and blocks the commit until it is cleared.\nFor advanced add flows, listen for the cancelable\n`esp-tree-graft-request` event and call `preventDefault()` to skip\nthe default dialog.\n\nReplace the `buildPath` property to use non-web path semantics, and\nreplace `normalizeGraftSegment` to loosen, tighten, or completely\nskip the default web-slug normalization used by the graft dialog.\n\n## Node actions\n\nMark a node with `editable: true` to render an edit action on the\ntrailing side of the row. Clicking it, or pressing `F2` on the\nfocused row, emits `esp-tree-edit` with the node path and public node\ndata so the host can open its own editor. Optional flags\n(`deletable`, `movableUp`, `movableDown`, `cuttable`, and\n`pasteChildTarget`) expose the matching built-in editing actions for\nhost-owned tree workflows.\n\nIf a row has exactly one action, the tree renders one trailing\nicon-only `esp-button` with an accessible label such as `Edit About`.\nIf a row has more than one action, the actions collapse into one\ntrailing `esp-action-menu` trigger so rows never accumulate multiple\nvisible action buttons. The tree only emits events — it does not\ndelete, move, cut, paste, mutate source nodes, or own clipboard state.\n\n```html\n<esp-tree id=\"navigation\"></esp-tree>\n<script>\n  const tree = findById(\"navigation\");\n  tree.nodes = [\n    {\n      id: \"about\",\n      segment: \"about\",\n      label: \"About\",\n      editable: true,\n      deletable: true,\n      movableDown: true,\n      cuttable: true,\n      children: [\n        {\n          id: \"team\",\n          segment: \"team\",\n          label: \"Team\",\n          editable: true,\n        },\n      ],\n    },\n    {\n      id: \"services\",\n      segment: \"services\",\n      label: \"Services\",\n      pasteChildTarget: true,\n    },\n  ];\n  tree.addEventListener(\"esp-tree-cut\", (event) => {\n    console.log(\"cut requested\", event.detail.path);\n  });\n  tree.addEventListener(\"esp-tree-paste-child\", (event) => {\n    console.log(\"paste as child requested\", event.detail.path);\n  });\n</script>\n```\n\n## Expand/collapse icon\n\nThe expand/collapse caret ships inline with the component, so unlike\nnode `icon`s it needs no icon sprite to be hosted. Override it by\nsetting the `expandIcon` property to your own (trusted) SVG markup; it\nrenders on every branch toggle and is rotated 90° when the branch is\nopen, so provide a right-pointing icon. For icon pairs that should not\nrotate, set `collapseIcon` to the trusted SVG markup to use while the\nbranch is open.\n\n```html\n<esp-tree id=\"custom-caret\"></esp-tree>\n<script>\n  const tree = findById(\"custom-caret\");\n  tree.nodes = [\n    { id: \"weddings\", segment: \"weddings\", label: \"Weddings\", children: [\n      { id: \"w2026\", segment: \"2026\", label: \"2026\" },\n    ] },\n  ];\n  // A filled triangle caret instead of the default outline chevron.\n  tree.expandIcon = `<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"\n    fill=\"currentColor\" stroke=\"none\"><path d=\"M9 6l6 6l-6 6z\" /></svg>`;\n</script>\n```",
           "name": "EspalierTree",
           "cssProperties": [
             {
@@ -94023,7 +94721,7 @@
               "name": "--esp-tree-icon-color"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -97112,6 +97810,17 @@
               "description": "Keep already-expanded branches open when selecting a row outside of\nthe selected branch. By default, selecting outside an open selected\nbranch collapses that branch.",
               "fieldName": "keepExpanded"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -97301,7 +98010,7 @@
               "name": "--esp-video-message-color"
             },
             {
-              "description": "Background color of the shared field shell. Defaults to `var(--esp-color-layer-2)`.",
+              "description": "Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at `var(--esp-color-layer-4)`, or `var(--esp-color-layer-2)` without a declared surface. An explicit override wins.",
               "name": "--esp-field-background",
               "inheritedFrom": {
                 "name": "EspalierElementBase",
@@ -98957,6 +99666,17 @@
               "description": "CORS mode for the video's requests, as on `<video crossorigin>`. Needed\nfor caption tracks served from another origin.",
               "fieldName": "crossOrigin"
             },
+            {
+              "type": {
+                "text": "\"1\"|\"2\"|\"3\"|\"4\""
+              },
+              "description": "Declares the painted surface depth. Fields use the next local layer, capped at layer 4.",
+              "name": "surface-layer",
+              "inheritedFrom": {
+                "name": "EspalierElementBase",
+                "module": "dist/shared/esp-element-base.js"
+              }
+            },
             {
               "name": "scheme",
               "type": {
@@ -99682,7 +100402,7 @@
         {
           "kind": "variable",
           "name": "datePickerStyles",
-          "default": "css` /* ── Error state ─────────────────────────────────── */ .temporal-error { font-family: var( --_esp-font-body-effective, var(--esp-font-body, var(--_esp-font-body-fallback)) ); font-size: var(--esp-type-small); color: var(--esp-color-danger-text); padding: var(--esp-size-padding); } /* ── Trigger field ───────────────────────────────── */ .esp-field { display: grid; grid-template-columns: 1fr min-content; cursor: pointer; > input.esp-input { cursor: pointer; width: auto; } > .field-icon { display: grid; place-content: center; cursor: pointer; > svg { height: calc(1.2 * var(--esp-size-font)); width: calc(1.2 * var(--esp-size-font)); margin: 0 var(--esp-size-tiny); } } } /* ── Popover shell (native top-layer) ────────────── */ .picker-popover { position: fixed; inset: unset; margin: 0; padding: var(--esp-size-small); border-radius: var(--esp-size-border-radius); border: 1px solid var(--esp-color-border); background: var(--esp-color-layer-1); box-shadow: 0 4px 16px var(--esp-color-shadow); color: var(--esp-color-text); font-family: var( --_esp-font-body-effective, var(--esp-font-body, var(--_esp-font-body-fallback)) ); font-size: var(--esp-size-font); opacity: 0; transition: opacity 150ms ease-in; overflow: visible; } .picker-popover.visible { opacity: 1; } /* ── Calendar ────────────────────────────────────── */ .calendar { --_cell-size: 2.4em; display: flex; flex-direction: column; gap: var(--esp-size-tiny); user-select: none; /* Clip the swiping body, but with a margin so the title controls' outset focus ring (2px offset + 2px width) paints above the header: the header has no padding above the title, so a hard clip at the box edge cut the ring's top. Browsers without overflow-clip-margin clip at the edge, as hidden did. */ overflow: clip; overflow-clip-margin: 4px; } .cal-body { will-change: transform; } .cal-header { display: flex; align-items: center; justify-content: space-between; padding-bottom: var(--esp-size-tiny); } .cal-title { font-weight: bold; font-size: var(--esp-type-normal); color: var(--esp-color-headings); } /* The month and year are buttons that open the jump surfaces, but the title must look exactly as it did as a span: every native button default is reset and the typography is inherited from .cal-title. Users discover the controls by clicking; the pointer cursor is the only pointer affordance, and the focus ring shows for keyboard focus only. No hover or expanded treatment, by design. */ .cal-title-part { appearance: none; display: inline; margin: 0; padding: 0; border: 0; border-radius: var(--esp-size-border-radius); background: none; font: inherit; letter-spacing: inherit; color: inherit; cursor: pointer; /* Outset, unlike .nav-btn's inset ring: an inset ring would cross the glyphs of a padding-less control. The ring's top lies outside the calendar box; .calendar's overflow-clip-margin lets it paint. Focus rings read against the calendar's own ground, so they take --esp-color-text. They used --esp-color-action-text until ESP0223: that token is only guaranteed legible on --esp-color-action-background, and it happened to be near-black in light and near-white in dark, which is the polarity the calendar ground wants too. The moment the default action surface moved, the borrowed token inverted and the ring vanished into the calendar. A ring drawn inside a selected cell is the exception and overrides this, because that cell paints the action surface. */ &:focus-visible { outline: 2px solid var(--esp-color-text); outline-offset: 2px; } } .nav-btn { display: grid; place-content: center; background: none; border: none; cursor: pointer; padding: var(--esp-size-tiny); border-radius: var(--esp-size-border-radius); color: var(--esp-color-text); transition: background-color 120ms ease; > svg { height: var(--esp-size-normal); width: var(--esp-size-normal); } &:hover { background-color: var(--esp-color-layer-3); } &:focus-visible { outline: 2px solid var(--esp-color-text); outline-offset: -2px; } } /* ── Weekday labels ──────────────────────────────── */ .weekday-row { display: grid; grid-template-columns: repeat(7, 1fr); text-align: center; } .weekday-label { font-size: var(--esp-type-tiny); font-weight: 600; color: var(--esp-color-headings); text-decoration: none; padding: var(--esp-size-tiny) 0; } /* ── Day grid ────────────────────────────────────── */ .day-grid { display: flex; flex-direction: column; } /* Show the focused-day ring only when the grid itself contains focus, so it disappears when the user tabs to the nav arrows or time picker. */ .day-grid:focus-within .day-cell.focused { outline: 2px solid var(--esp-color-text); outline-offset: -2px; z-index: 1; } .day-row { display: grid; grid-template-columns: repeat(7, 1fr); } /* ── Day, month, and year cells ──────────────────── */ /* The month and year surfaces reuse the day cell's rest, hover, selected, disabled, and focus treatments so they read as the same calendar; only the geometry and the day-specific states differ. */ .day-cell, .jump-cell { position: relative; display: grid; place-content: center; border: none; border-radius: var(--esp-size-border-radius); background: none; cursor: pointer; font-family: inherit; font-size: inherit; color: var(--esp-color-text); transition: background-color 100ms ease, color 100ms ease; &:hover:not(.disabled):not(.selected) { background-color: var(--esp-color-layer-3); } &:focus-visible { outline: 2px solid var(--esp-color-text); outline-offset: -2px; z-index: 1; } /* Selected / range endpoints. A selected cell is a filled state, so it paints the one surface/ink pair the engine guarantees: APCA enforces --esp-color-action-text against --esp-color-action-background and nothing against --esp-color-layer-3, which this rule used to paint. Under a layer-3 ground the label had no enforced partner at all — it read at Lc 24.6 in light once ESP0223 moved the action surface, and 60.4 after taking --esp-color-text, still under the Lc 75 that ADR-002 sets for content text. On the action pair it is 76.0 and 81.6. In the dark scheme layer-3 and the action surface resolve to the same value, so that scheme is unchanged. */ &.selected { background-color: var(--esp-color-action-background); color: var(--esp-color-action-text); font-weight: bold; } } /* Everything drawn ON a selected cell reads against the action surface that cell paints, not against the calendar ground, so it takes that surface's own ink. These are declared at top level rather than nested under .selected because the focused-day ring is .day-grid:focus-within .day-cell.focused — specificity (0,4,0). A nested &:focus-visible compiles to (0,3,0) and loses to it, which is how a first attempt at this left a keyboard-focused selected day ringed in --esp-color-text at Lc 9.1 while looking correct on the month and year surfaces, whose cells carry no .focused rule. Naming the same selector plus .selected is what actually wins. A .day-cell.selected:focus-visible form would be unreachable: _renderDayCell drives .focused and tabindex=\"0\" off one flag and a day cell only renders inside .day-grid, so the grid selector always matches first. The jump surfaces have no .focused rule, so they take the :focus-visible form. */ .day-grid:focus-within .day-cell.focused.selected, .jump-cell.selected:focus-visible { outline-color: var(--esp-color-action-text); } .day-cell.today.selected { box-shadow: inset 0 0 0 1px var(--esp-color-action-text); } .day-cell { width: var(--_cell-size); height: var(--_cell-size); /* Outside month — dim */ &.outside-month { opacity: 0.38; } /* Today ring */ &.today { font-weight: bold; box-shadow: inset 0 0 0 1px var(--esp-color-border); border-radius: var(--esp-size-border-radius); } /* Range span highlight — washed-out brand colour */ &.in-range { background-color: oklch(from var(--esp-color-layer-3) calc(l + 0.15) calc(c * 0.4) h); border-radius: 0; } &.range-start { border-radius: var(--esp-size-border-radius) 0 0 var(--esp-size-border-radius); } &.range-end { border-radius: 0 var(--esp-size-border-radius) var(--esp-size-border-radius) 0; } } /* Disabled — declared after the day-specific states at the same specificity, so a disabled day that is also outside the month keeps the disabled opacity, as it did before the surfaces shared the cell rules. */ .day-cell.disabled, .jump-cell.disabled { opacity: 0.3; cursor: not-allowed; } /* ── Month and year jump surfaces ────────────────── */ /* A surface fills the body, which is pinned to the day grid's measured height while the surface is showing (see _applySurfaceChange), so the popover keeps its footprint and position. */ .jump-surface { box-sizing: border-box; block-size: 100%; } .month-surface { display: grid; grid-template-columns: repeat(3, 1fr); grid-auto-rows: 1fr; gap: var(--esp-size-tiny); } .year-surface { /* Relative so each year's offsetTop is measured against the list, which is what _scrollYearIntoView positions by. */ position: relative; display: flex; flex-direction: column; overflow-y: auto; overscroll-behavior: contain; scrollbar-width: thin; } .year-cell { flex: 0 0 auto; min-block-size: var(--_cell-size); } /* ── Time picker ─────────────────────────────────── */ .time-picker { display: flex; align-items: center; flex-wrap: nowrap; gap: var(--esp-size-tiny); padding-top: var(--esp-size-small); border-top: 1px solid var(--esp-color-border); margin-top: var(--esp-size-small); white-space: nowrap; /* Push the action buttons to the right edge */ > esp-button:first-of-type { margin-left: auto; } } /* Only-time mode: no top border */ :host([mode=\"time\"]) .time-picker { border-top: none; margin-top: 0; padding-top: 0; } .popover-actions { display: flex; gap: var(--esp-size-tiny); align-items: center; justify-content: flex-end; padding-top: var(--esp-size-small); border-top: 1px solid var(--esp-color-border); margin-top: var(--esp-size-small); } .time-sep { font-size: var(--esp-type-medium); font-weight: bold; color: var(--esp-color-headings); padding: 0 2px; } `",
+          "default": "css` /* ── Error state ─────────────────────────────────── */ .temporal-error { font-family: var( --_esp-font-body-effective, var(--esp-font-body, var(--_esp-font-body-fallback)) ); font-size: var(--esp-type-small); color: var(--esp-color-danger-text); padding: var(--esp-size-padding); } /* ── Trigger field ───────────────────────────────── */ .esp-field { display: grid; grid-template-columns: 1fr min-content; cursor: pointer; > input.esp-input { cursor: pointer; width: auto; } > .field-icon { display: grid; place-content: center; cursor: pointer; > svg { height: calc(1.2 * var(--esp-size-font)); width: calc(1.2 * var(--esp-size-font)); margin: 0 var(--esp-size-tiny); } } } /* ── Popover shell (native top-layer) ────────────── */ .picker-popover { --_esp-surface-layer: 1; position: fixed; inset: unset; margin: 0; padding: var(--esp-size-small); border-radius: var(--esp-size-border-radius); border: 1px solid var(--esp-color-border); background: var(--esp-color-layer-1); box-shadow: 0 4px 16px var(--esp-color-shadow); color: var(--esp-color-text); font-family: var( --_esp-font-body-effective, var(--esp-font-body, var(--_esp-font-body-fallback)) ); font-size: var(--esp-size-font); opacity: 0; transition: opacity 150ms ease-in; overflow: visible; } .picker-popover.visible { opacity: 1; } /* ── Calendar ────────────────────────────────────── */ .calendar { --_cell-size: 2.4em; display: flex; flex-direction: column; gap: var(--esp-size-tiny); user-select: none; /* Clip the swiping body, but with a margin so the title controls' outset focus ring (2px offset + 2px width) paints above the header: the header has no padding above the title, so a hard clip at the box edge cut the ring's top. Browsers without overflow-clip-margin clip at the edge, as hidden did. */ overflow: clip; overflow-clip-margin: 4px; } .cal-body { will-change: transform; } .cal-header { display: flex; align-items: center; justify-content: space-between; padding-bottom: var(--esp-size-tiny); } .cal-title { font-weight: bold; font-size: var(--esp-type-normal); color: var(--esp-color-headings); } /* The month and year are buttons that open the jump surfaces, but the title must look exactly as it did as a span: every native button default is reset and the typography is inherited from .cal-title. Users discover the controls by clicking; the pointer cursor is the only pointer affordance, and the focus ring shows for keyboard focus only. No hover or expanded treatment, by design. */ .cal-title-part { appearance: none; display: inline; margin: 0; padding: 0; border: 0; border-radius: var(--esp-size-border-radius); background: none; font: inherit; letter-spacing: inherit; color: inherit; cursor: pointer; /* Outset, unlike .nav-btn's inset ring: an inset ring would cross the glyphs of a padding-less control. The ring's top lies outside the calendar box; .calendar's overflow-clip-margin lets it paint. Focus rings read against the calendar's own ground, so they take --esp-color-text. They used --esp-color-action-text until ESP0223: that token is only guaranteed legible on --esp-color-action-background, and it happened to be near-black in light and near-white in dark, which is the polarity the calendar ground wants too. The moment the default action surface moved, the borrowed token inverted and the ring vanished into the calendar. A ring drawn inside a selected cell is the exception and overrides this, because that cell paints the action surface. */ &:focus-visible { outline: 2px solid var(--esp-color-text); outline-offset: 2px; } } .nav-btn { display: grid; place-content: center; background: none; border: none; cursor: pointer; padding: var(--esp-size-tiny); border-radius: var(--esp-size-border-radius); color: var(--esp-color-text); transition: background-color 120ms ease; > svg { height: var(--esp-size-normal); width: var(--esp-size-normal); } &:hover { background-color: var(--esp-color-layer-3); } &:focus-visible { outline: 2px solid var(--esp-color-text); outline-offset: -2px; } } /* ── Weekday labels ──────────────────────────────── */ .weekday-row { display: grid; grid-template-columns: repeat(7, 1fr); text-align: center; } .weekday-label { font-size: var(--esp-type-tiny); font-weight: 600; color: var(--esp-color-headings); text-decoration: none; padding: var(--esp-size-tiny) 0; } /* ── Day grid ────────────────────────────────────── */ .day-grid { display: flex; flex-direction: column; } /* Show the focused-day ring only when the grid itself contains focus, so it disappears when the user tabs to the nav arrows or time picker. */ .day-grid:focus-within .day-cell.focused { outline: 2px solid var(--esp-color-text); outline-offset: -2px; z-index: 1; } .day-row { display: grid; grid-template-columns: repeat(7, 1fr); } /* ── Day, month, and year cells ──────────────────── */ /* The month and year surfaces reuse the day cell's rest, hover, selected, disabled, and focus treatments so they read as the same calendar; only the geometry and the day-specific states differ. */ .day-cell, .jump-cell { position: relative; display: grid; place-content: center; border: none; border-radius: var(--esp-size-border-radius); background: none; cursor: pointer; font-family: inherit; font-size: inherit; color: var(--esp-color-text); transition: background-color 100ms ease, color 100ms ease; &:hover:not(.disabled):not(.selected) { background-color: var(--esp-color-layer-3); } &:focus-visible { outline: 2px solid var(--esp-color-text); outline-offset: -2px; z-index: 1; } /* Selected / range endpoints. A selected cell is a filled state, so it paints the one surface/ink pair the engine guarantees: APCA enforces --esp-color-action-text against --esp-color-action-background and nothing against --esp-color-layer-3, which this rule used to paint. Under a layer-3 ground the label had no enforced partner at all — it read at Lc 24.6 in light once ESP0223 moved the action surface, and 60.4 after taking --esp-color-text, still under the Lc 75 that ADR-002 sets for content text. On the action pair it is 76.0 and 81.6. In the dark scheme layer-3 and the action surface resolve to the same value, so that scheme is unchanged. */ &.selected { background-color: var(--esp-color-action-background); color: var(--esp-color-action-text); font-weight: bold; } } /* Everything drawn ON a selected cell reads against the action surface that cell paints, not against the calendar ground, so it takes that surface's own ink. These are declared at top level rather than nested under .selected because the focused-day ring is .day-grid:focus-within .day-cell.focused — specificity (0,4,0). A nested &:focus-visible compiles to (0,3,0) and loses to it, which is how a first attempt at this left a keyboard-focused selected day ringed in --esp-color-text at Lc 9.1 while looking correct on the month and year surfaces, whose cells carry no .focused rule. Naming the same selector plus .selected is what actually wins. A .day-cell.selected:focus-visible form would be unreachable: _renderDayCell drives .focused and tabindex=\"0\" off one flag and a day cell only renders inside .day-grid, so the grid selector always matches first. The jump surfaces have no .focused rule, so they take the :focus-visible form. */ .day-grid:focus-within .day-cell.focused.selected, .jump-cell.selected:focus-visible { outline-color: var(--esp-color-action-text); } .day-cell.today.selected { box-shadow: inset 0 0 0 1px var(--esp-color-action-text); } .day-cell { width: var(--_cell-size); height: var(--_cell-size); /* Outside month — dim */ &.outside-month { opacity: 0.38; } /* Today ring */ &.today { font-weight: bold; box-shadow: inset 0 0 0 1px var(--esp-color-border); border-radius: var(--esp-size-border-radius); } /* Range span highlight — washed-out brand colour */ &.in-range { background-color: oklch(from var(--esp-color-layer-3) calc(l + 0.15) calc(c * 0.4) h); border-radius: 0; } &.range-start { border-radius: var(--esp-size-border-radius) 0 0 var(--esp-size-border-radius); } &.range-end { border-radius: 0 var(--esp-size-border-radius) var(--esp-size-border-radius) 0; } } /* Disabled — declared after the day-specific states at the same specificity, so a disabled day that is also outside the month keeps the disabled opacity, as it did before the surfaces shared the cell rules. */ .day-cell.disabled, .jump-cell.disabled { opacity: 0.3; cursor: not-allowed; } /* ── Month and year jump surfaces ────────────────── */ /* A surface fills the body, which is pinned to the day grid's measured height while the surface is showing (see _applySurfaceChange), so the popover keeps its footprint and position. */ .jump-surface { box-sizing: border-box; block-size: 100%; } .month-surface { display: grid; grid-template-columns: repeat(3, 1fr); grid-auto-rows: 1fr; gap: var(--esp-size-tiny); } .year-surface { /* Relative so each year's offsetTop is measured against the list, which is what _scrollYearIntoView positions by. */ position: relative; display: flex; flex-direction: column; overflow-y: auto; overscroll-behavior: contain; scrollbar-width: thin; } .year-cell { flex: 0 0 auto; min-block-size: var(--_cell-size); } /* ── Time picker ─────────────────────────────────── */ .time-picker { display: flex; align-items: center; flex-wrap: nowrap; gap: var(--esp-size-tiny); padding-top: var(--esp-size-small); border-top: 1px solid var(--esp-color-border); margin-top: var(--esp-size-small); white-space: nowrap; /* Push the action buttons to the right edge */ > esp-button:first-of-type { margin-left: auto; } } /* Only-time mode: no top border */ :host([mode=\"time\"]) .time-picker { border-top: none; margin-top: 0; padding-top: 0; } .popover-actions { display: flex; gap: var(--esp-size-tiny); align-items: center; justify-content: flex-end; padding-top: var(--esp-size-small); border-top: 1px solid var(--esp-color-border); margin-top: var(--esp-size-small); } .time-sep { font-size: var(--esp-type-medium); font-weight: bold; color: var(--esp-color-headings); padding: 0 2px; } `",
           "description": "Component-specific styles for `esp-date-picker`."
         }
       ],