@taprootio/espalier 2.0.2 → 2.1.0

package/dist/header/esp-header.d.ts

@@ -144,6 +144,8 @@ type HeaderThemeToggle = "hidden" | "visible";
  * @cssprop --esp-header-height - The height of the header bar. Defaults to `calc(4.5 * var(--esp-size-small))`.
  * @cssprop --esp-header-color - The text/icon color inherited by header controls. Defaults to `var(--esp-color-text)`.
  * @cssprop --esp-header-z-index - The z-index of the header host. Defaults to `20`.
+ * @cssprop --esp-header-content-max-width - Surface-alignment contract set by `esp-page`: the maximum width the bar content is constrained to (the bar background stays full-bleed). Defaults to `100%` (no constraint). `esp-page` sets this to its resolved content cap.
+ * @cssprop --esp-header-content-lead - Surface-alignment contract set by `esp-page`: the fraction of the leftover width placed before the content, aligning it (`0` = start, `0.5` = center, `1` = end). Defaults to `0`.
  * @cssprop --esp-header-compact-height - The height of compact scroll-reactive headers. Defaults to `max(44px, calc(3.5 * var(--esp-size-small)))`.
  * @cssprop --esp-header-extended-menu-height - The second-row menu height for extended layouts. Defaults to `calc(3.5 * var(--esp-size-small))`.
  * @cssprop --esp-header-extended-menu-border - The border between the primary row and second-row menu in extended layouts. Defaults to `1px solid var(--esp-color-border)`.
@@ -306,6 +308,15 @@ export declare class EspalierHeader extends EspalierElementBase {
      * menu slotted into the header.
      */
     drawerTarget: string;
+    /**
+     * Opt out of surface alignment. When an `esp-header` is slotted into an
+     * `esp-page`, it constrains its bar content to the page's content
+     * surface by default (the bar background stays full-bleed). Set this to
+     * let the content span the full width instead, as it did before the
+     * page grew alignment modes. Standalone headers (outside `esp-page`) are
+     * already full-bleed and unaffected.
+     */
+    fullBleedContent: boolean;
     /**
      * The burger element inside the header. External code can use
      * this to programmatically reset the burger's visual state

package/dist/header/esp-header.js

@@ -1,7 +1,7 @@
-var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,t):o,i;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")a=Reflect.decorate(p,e,t,o);else for(var h=p.length-1;h>=0;h--)(i=p[h])&&(a=(s<3?i(a):s>3?i(e,t,a):i(e,t))||a);return s>3&&a&&Object.defineProperty(e,t,a),a};import{css as y,html as d,nothing as c}from"lit";import{customElement as x,property as l,state as u}from"lit/decorators.js";import{classMap as M}from"lit/directives/class-map.js";import{styleMap as S}from"lit/directives/style-map.js";import"../burger/esp-burger.js";import{createRef as b,ref as v}from"lit/directives/ref.js";import{EspalierMenu as T}from"./esp-menu.js";import{EspalierElementBase as f}from"../shared/esp-element-base.js";const D="(max-width: 36rem)";let r=class extends f{constructor(){super(...arguments),this.menuOpen=!1,this.menuTooLarge=!1,this.mobileMenu=!1,this.scrolled=!1,this.hiddenByScroll=!1,this.scrollProgress=0,this.showBurger=!1,this.layout="standard",this.brandText="",this.brandLogo="",this.brandHref="",this.brandAlt="",this.brandColor="",this.brandAlign="start",this.brandWrap="truncate",this.menuDisplay="auto",this.themeToggle="hidden",this.scrollBehavior="none",this.scrollThreshold=16,this.dockOffset=0,this.drawerTarget="",this.menuContainer=b(),this.menuButton=b(),this.menu=void 0,this.externalDrawerTarget=null,this.lastScrollY=0,this.lastInlineMenuWidth=0,this.mobileMenuQuery=null,this.menuDrawerListenersAttached=!1,this.observingMenuContainer=!1,this.scrollListenersAttached=!1,this.scrollRafId=null,this.resizeObserver=new ResizeObserver(()=>this.syncMenuLayout()),this.updateScrollState=()=>{this.scrollRafId===null&&(this.scrollRafId=requestAnimationFrame(()=>{this.scrollRafId=null,this.runScrollStateUpdate()}))},this.handleMobileMenuQueryChange=e=>{this.mobileMenu=e.matches,this.syncMenuLayout()},this.toggleTheme=()=>{const e=this.getThemeRoot();e&&(e.scheme=e.scheme==="dark"?"light":"dark")},this.handleMenuToggleClicked=()=>{if(this.menuOpen){this.closeNav();return}this.openNav()},this.onMenuDrawerOpened=()=>{this.menuOpen=!0,document.body.classList.add("menu-open"),this.burger&&(this.burger.menuOpen=!0)},this.onMenuDrawerClosed=()=>{this.menuOpen=!1,document.body.classList.remove("menu-open"),this.burger&&(this.burger.menuOpen=!1)}}syncMenuLayout(){if(!this.menuContainer.value||!this.menu||!this.menu.getWidth)return;const e=this.menuContainer.value.clientWidth,t=this.menu.getWidth();t>0&&(this.lastInlineMenuWidth=t);const o=this.lastInlineMenuWidth||t,s=this.getExternalDrawerTarget(),a=this.menuDisplay!=="inline",i=this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal";this.menuTooLarge=a&&this.menuDisplay==="auto"&&o>e,this.menu.sliding=a&&!s&&(this.menuTooLarge||i||this.mobileMenu)}getExternalDrawerTarget(){if(!this.drawerTarget)return null;const e=document.getElementById(this.drawerTarget);return e===this.menu?null:e&&"openDrawer"in e&&typeof e.openDrawer=="function"&&"closeDrawer"in e&&typeof e.closeDrawer=="function"?e:null}getBurgerFocusTarget(){const t=this.shadowRoot?.querySelector("esp-header-button.menu-toggle")?.shadowRoot?.querySelector("button"),o=this.menuButton.value?.shadowRoot?.querySelector("button");return t??o??null}getScrollTokens(){const e=this.scrollBehavior.split(/\s+/).map(t=>t.trim().toLowerCase()).filter(Boolean);return new Set(e.filter(t=>t!=="none"))}getEffectiveScrollThreshold(){return Number.isFinite(this.scrollThreshold)?Math.max(0,this.scrollThreshold):0}clearScrollState(){this.scrolled=!1,this.hiddenByScroll=!1,this.scrollProgress=0}runScrollStateUpdate(){const e=this.getScrollTokens();if(!e.size){this.clearScrollState();return}const t=Math.max(0,window.scrollY||document.documentElement.scrollTop||0),o=this.getEffectiveScrollThreshold(),s=Number.isFinite(this.dockOffset)?Math.max(0,this.dockOffset):o,a=t>(e.has("dock")?s:o),i=t>this.lastScrollY,h=e.has("reveal")&&i&&t>o&&!this.menuOpen;if(this.scrolled=a,this.hiddenByScroll=h,e.has("progress")){const m=document.documentElement,g=Math.max(1,m.scrollHeight-window.innerHeight);this.scrollProgress=Math.min(1,t/g)}else this.scrollProgress=0;this.lastScrollY=t}cancelScrollUpdate(){this.scrollRafId!==null&&(cancelAnimationFrame(this.scrollRafId),this.scrollRafId=null)}syncScrollListeners(){const e=this.getScrollTokens().size>0;if(e&&!this.scrollListenersAttached?(window.addEventListener("scroll",this.updateScrollState,{passive:!0}),window.addEventListener("resize",this.updateScrollState,{passive:!0}),this.scrollListenersAttached=!0):!e&&this.scrollListenersAttached&&this.removeScrollListeners(),e){this.updateScrollState();return}this.cancelScrollUpdate(),this.clearScrollState()}removeScrollListeners(){this.scrollListenersAttached&&(window.removeEventListener("scroll",this.updateScrollState),window.removeEventListener("resize",this.updateScrollState),this.scrollListenersAttached=!1)}addMenuDrawerListeners(){!this.menu||this.menuDrawerListenersAttached||(this.menu.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.menu.addEventListener("drawer-closed",this.onMenuDrawerClosed),this.menuDrawerListenersAttached=!0)}removeMenuDrawerListeners(){!this.menu||!this.menuDrawerListenersAttached||(this.menu.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.menu.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.menuDrawerListenersAttached=!1)}observeMenuContainer(){!this.menuContainer.value||this.observingMenuContainer||(this.resizeObserver.observe(this.menuContainer.value),this.observingMenuContainer=!0)}disconnectResizeObserver(){this.observingMenuContainer&&(this.resizeObserver.disconnect(),this.observingMenuContainer=!1)}syncMobileMenuQuery(){if("matchMedia"in window){if(!this.mobileMenuQuery){this.mobileMenuQuery=window.matchMedia(D),this.mobileMenu=this.mobileMenuQuery.matches,this.mobileMenuQuery.addEventListener("change",this.handleMobileMenuQueryChange);return}this.mobileMenu=this.mobileMenuQuery.matches}}getThemeRoot(){return this.traverseToClosest("esp-root")}syncExternalDrawerTarget(){const e=this.getExternalDrawerTarget(),t=e===this.menu?null:e;t!==this.externalDrawerTarget&&(this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget=t,this.externalDrawerTarget?.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.addEventListener("drawer-closed",this.onMenuDrawerClosed))}openNav(){const e=this.getBurgerFocusTarget(),t=this.getExternalDrawerTarget();if(this.burger&&(this.burger.menuOpen=!0),t){this.menuOpen=!0,t.openDrawer(e),document.body.classList.add("menu-open");return}if(this.menu){this.menu.sliding=!0,this.menuOpen=!0,this.menu.openDrawer(e),document.body.classList.add("menu-open");return}this.burger&&(this.burger.menuOpen=!1)}closeNav(){this.menuOpen=!1,this.burger&&(this.burger.menuOpen=!1);const e=this.getExternalDrawerTarget();if(e){e.closeDrawer(),document.body.classList.remove("menu-open");return}this.menu&&(this.menu.closeDrawer(),document.body.classList.remove("menu-open"))}get burger(){return this.menuButton.value??void 0}firstUpdated(e){if(super.firstUpdated(e),!this.menuContainer.value)return;const s=(this.menuContainer.value.firstElementChild?.assignedElements()??[])[0];s instanceof T?(this.menu=s,this.addMenuDrawerListeners()):s&&console.warn("<esp-header>: the menu slot expects an <esp-menu> element, received",s),this.observeMenuContainer(),this.syncExternalDrawerTarget(),this.syncMobileMenuQuery(),this.syncScrollListeners(),this.syncMenuLayout()}updated(e){super.updated(e),(e.has("showBurger")||e.has("drawerTarget")||e.has("menuDisplay")||e.has("layout"))&&(this.syncExternalDrawerTarget(),this.syncMenuLayout()),e.has("scrollBehavior")?this.syncScrollListeners():(e.has("scrollThreshold")||e.has("dockOffset"))&&this.updateScrollState()}connectedCallback(){super.connectedCallback(),this.syncScrollListeners(),this.syncMobileMenuQuery(),this.addMenuDrawerListeners(),this.syncExternalDrawerTarget(),this.observeMenuContainer()}disconnectedCallback(){this.removeMenuDrawerListeners(),this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget=null,this.mobileMenuQuery?.removeEventListener("change",this.handleMobileMenuQueryChange),this.mobileMenuQuery=null,this.removeScrollListeners(),this.cancelScrollUpdate(),this.disconnectResizeObserver(),super.disconnectedCallback()}renderConfiguredBrand(){if(!this.brandLogo&&!this.brandText)return c;const e=this.brandAlt||(this.brandText?"":"Site logo"),t=d`
+var n=function(p,e,t,a){var s=arguments.length,i=s<3?e:a===null?a=Object.getOwnPropertyDescriptor(e,t):a,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(p,e,t,a);else for(var h=p.length-1;h>=0;h--)(l=p[h])&&(i=(s<3?l(i):s>3?l(e,t,i):l(e,t))||i);return s>3&&i&&Object.defineProperty(e,t,i),i};import{css as y,html as d,nothing as c}from"lit";import{customElement as x,property as o,state as u}from"lit/decorators.js";import{classMap as M}from"lit/directives/class-map.js";import{styleMap as S}from"lit/directives/style-map.js";import"../burger/esp-burger.js";import{createRef as b,ref as f}from"lit/directives/ref.js";import{EspalierMenu as T}from"./esp-menu.js";import{EspalierElementBase as v}from"../shared/esp-element-base.js";const D="(max-width: 36rem)";let r=class extends v{constructor(){super(...arguments),this.menuOpen=!1,this.menuTooLarge=!1,this.mobileMenu=!1,this.scrolled=!1,this.hiddenByScroll=!1,this.scrollProgress=0,this.showBurger=!1,this.layout="standard",this.brandText="",this.brandLogo="",this.brandHref="",this.brandAlt="",this.brandColor="",this.brandAlign="start",this.brandWrap="truncate",this.menuDisplay="auto",this.themeToggle="hidden",this.scrollBehavior="none",this.scrollThreshold=16,this.dockOffset=0,this.drawerTarget="",this.fullBleedContent=!1,this.menuContainer=b(),this.menuButton=b(),this.menu=void 0,this.externalDrawerTarget=null,this.lastScrollY=0,this.lastInlineMenuWidth=0,this.mobileMenuQuery=null,this.menuDrawerListenersAttached=!1,this.observingMenuContainer=!1,this.scrollListenersAttached=!1,this.scrollRafId=null,this.resizeObserver=new ResizeObserver(()=>this.syncMenuLayout()),this.updateScrollState=()=>{this.scrollRafId===null&&(this.scrollRafId=requestAnimationFrame(()=>{this.scrollRafId=null,this.runScrollStateUpdate()}))},this.handleMobileMenuQueryChange=e=>{this.mobileMenu=e.matches,this.syncMenuLayout()},this.toggleTheme=()=>{const e=this.getThemeRoot();e&&(e.scheme=e.scheme==="dark"?"light":"dark")},this.handleMenuToggleClicked=()=>{if(this.menuOpen){this.closeNav();return}this.openNav()},this.onMenuDrawerOpened=()=>{this.menuOpen=!0,document.body.classList.add("menu-open"),this.burger&&(this.burger.menuOpen=!0)},this.onMenuDrawerClosed=()=>{this.menuOpen=!1,document.body.classList.remove("menu-open"),this.burger&&(this.burger.menuOpen=!1)}}syncMenuLayout(){if(!this.menuContainer.value||!this.menu||!this.menu.getWidth)return;const e=this.menuContainer.value.clientWidth,t=this.menu.getWidth();t>0&&(this.lastInlineMenuWidth=t);const a=this.lastInlineMenuWidth||t,s=this.getExternalDrawerTarget(),i=this.menuDisplay!=="inline",l=this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal";this.menuTooLarge=i&&this.menuDisplay==="auto"&&a>e,this.menu.sliding=i&&!s&&(this.menuTooLarge||l||this.mobileMenu)}getExternalDrawerTarget(){if(!this.drawerTarget)return null;const e=document.getElementById(this.drawerTarget);return e===this.menu?null:e&&"openDrawer"in e&&typeof e.openDrawer=="function"&&"closeDrawer"in e&&typeof e.closeDrawer=="function"?e:null}getBurgerFocusTarget(){const t=this.shadowRoot?.querySelector("esp-header-button.menu-toggle")?.shadowRoot?.querySelector("button"),a=this.menuButton.value?.shadowRoot?.querySelector("button");return t??a??null}getScrollTokens(){const e=this.scrollBehavior.split(/\s+/).map(t=>t.trim().toLowerCase()).filter(Boolean);return new Set(e.filter(t=>t!=="none"))}getEffectiveScrollThreshold(){return Number.isFinite(this.scrollThreshold)?Math.max(0,this.scrollThreshold):0}clearScrollState(){this.scrolled=!1,this.hiddenByScroll=!1,this.scrollProgress=0}runScrollStateUpdate(){const e=this.getScrollTokens();if(!e.size){this.clearScrollState();return}const t=Math.max(0,window.scrollY||document.documentElement.scrollTop||0),a=this.getEffectiveScrollThreshold(),s=Number.isFinite(this.dockOffset)?Math.max(0,this.dockOffset):a,i=t>(e.has("dock")?s:a),l=t>this.lastScrollY,h=e.has("reveal")&&l&&t>a&&!this.menuOpen;if(this.scrolled=i,this.hiddenByScroll=h,e.has("progress")){const m=document.documentElement,g=Math.max(1,m.scrollHeight-window.innerHeight);this.scrollProgress=Math.min(1,t/g)}else this.scrollProgress=0;this.lastScrollY=t}cancelScrollUpdate(){this.scrollRafId!==null&&(cancelAnimationFrame(this.scrollRafId),this.scrollRafId=null)}syncScrollListeners(){const e=this.getScrollTokens().size>0;if(e&&!this.scrollListenersAttached?(window.addEventListener("scroll",this.updateScrollState,{passive:!0}),window.addEventListener("resize",this.updateScrollState,{passive:!0}),this.scrollListenersAttached=!0):!e&&this.scrollListenersAttached&&this.removeScrollListeners(),e){this.updateScrollState();return}this.cancelScrollUpdate(),this.clearScrollState()}removeScrollListeners(){this.scrollListenersAttached&&(window.removeEventListener("scroll",this.updateScrollState),window.removeEventListener("resize",this.updateScrollState),this.scrollListenersAttached=!1)}addMenuDrawerListeners(){!this.menu||this.menuDrawerListenersAttached||(this.menu.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.menu.addEventListener("drawer-closed",this.onMenuDrawerClosed),this.menuDrawerListenersAttached=!0)}removeMenuDrawerListeners(){!this.menu||!this.menuDrawerListenersAttached||(this.menu.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.menu.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.menuDrawerListenersAttached=!1)}observeMenuContainer(){!this.menuContainer.value||this.observingMenuContainer||(this.resizeObserver.observe(this.menuContainer.value),this.observingMenuContainer=!0)}disconnectResizeObserver(){this.observingMenuContainer&&(this.resizeObserver.disconnect(),this.observingMenuContainer=!1)}syncMobileMenuQuery(){if("matchMedia"in window){if(!this.mobileMenuQuery){this.mobileMenuQuery=window.matchMedia(D),this.mobileMenu=this.mobileMenuQuery.matches,this.mobileMenuQuery.addEventListener("change",this.handleMobileMenuQueryChange);return}this.mobileMenu=this.mobileMenuQuery.matches}}getThemeRoot(){return this.traverseToClosest("esp-root")}syncExternalDrawerTarget(){const e=this.getExternalDrawerTarget(),t=e===this.menu?null:e;t!==this.externalDrawerTarget&&(this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget=t,this.externalDrawerTarget?.addEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.addEventListener("drawer-closed",this.onMenuDrawerClosed))}openNav(){const e=this.getBurgerFocusTarget(),t=this.getExternalDrawerTarget();if(this.burger&&(this.burger.menuOpen=!0),t){this.menuOpen=!0,t.openDrawer(e),document.body.classList.add("menu-open");return}if(this.menu){this.menu.sliding=!0,this.menuOpen=!0,this.menu.openDrawer(e),document.body.classList.add("menu-open");return}this.burger&&(this.burger.menuOpen=!1)}closeNav(){this.menuOpen=!1,this.burger&&(this.burger.menuOpen=!1);const e=this.getExternalDrawerTarget();if(e){e.closeDrawer(),document.body.classList.remove("menu-open");return}this.menu&&(this.menu.closeDrawer(),document.body.classList.remove("menu-open"))}get burger(){return this.menuButton.value??void 0}firstUpdated(e){if(super.firstUpdated(e),!this.menuContainer.value)return;const s=(this.menuContainer.value.firstElementChild?.assignedElements()??[])[0];s instanceof T?(this.menu=s,this.addMenuDrawerListeners()):s&&console.warn("<esp-header>: the menu slot expects an <esp-menu> element, received",s),this.observeMenuContainer(),this.syncExternalDrawerTarget(),this.syncMobileMenuQuery(),this.syncScrollListeners(),this.syncMenuLayout()}updated(e){super.updated(e),(e.has("showBurger")||e.has("drawerTarget")||e.has("menuDisplay")||e.has("layout"))&&(this.syncExternalDrawerTarget(),this.syncMenuLayout()),e.has("scrollBehavior")?this.syncScrollListeners():(e.has("scrollThreshold")||e.has("dockOffset"))&&this.updateScrollState()}connectedCallback(){super.connectedCallback(),this.syncScrollListeners(),this.syncMobileMenuQuery(),this.addMenuDrawerListeners(),this.syncExternalDrawerTarget(),this.observeMenuContainer()}disconnectedCallback(){this.removeMenuDrawerListeners(),this.externalDrawerTarget?.removeEventListener("drawer-opened",this.onMenuDrawerOpened),this.externalDrawerTarget?.removeEventListener("drawer-closed",this.onMenuDrawerClosed),this.externalDrawerTarget=null,this.mobileMenuQuery?.removeEventListener("change",this.handleMobileMenuQueryChange),this.mobileMenuQuery=null,this.removeScrollListeners(),this.cancelScrollUpdate(),this.disconnectResizeObserver(),super.disconnectedCallback()}renderConfiguredBrand(){if(!this.brandLogo&&!this.brandText)return c;const e=this.brandAlt||(this.brandText?"":"Site logo"),t=d`
       ${this.brandLogo?d`<img class="brand-logo" src=${this.brandLogo} alt=${e} />`:c}
       ${this.brandText?d`<span class="brand-text">${this.brandText}</span>`:c}
-    `;return this.brandHref?d`<a class="configured-brand" href=${this.brandHref}>${t}</a>`:d`<span class="configured-brand">${t}</span>`}render(){const{menuOpen:e,menuTooLarge:t,mobileMenu:o}=this,s=this.menuDisplay!=="inline",a=s&&(this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal"),i=this.getScrollTokens(),h=i.has("progress"),m={"--_esp-header-brand-color":this.brandColor||null,"--_esp-header-scroll-progress":String(this.scrollProgress)},g={"menu-open":e,"too-wide":s&&(t||o||a),[`layout-${this.layout}`]:!0,"is-scrolled":this.scrolled,"hide-on-scroll":this.hiddenByScroll,"scroll-compact":i.has("compact"),"scroll-elevate":i.has("elevate"),"scroll-transparent":i.has("transparent")||i.has("transparent-to-solid"),"scroll-collapse-topbar":i.has("collapse-topbar")},w=this.scheme==="dark"?"light":"dark";return d`
+    `;return this.brandHref?d`<a class="configured-brand" href=${this.brandHref}>${t}</a>`:d`<span class="configured-brand">${t}</span>`}render(){const{menuOpen:e,menuTooLarge:t,mobileMenu:a}=this,s=this.menuDisplay!=="inline",i=s&&(this.showBurger||this.menuDisplay==="drawer"||this.layout==="minimal"),l=this.getScrollTokens(),h=l.has("progress"),m={"--_esp-header-brand-color":this.brandColor||null,"--_esp-header-scroll-progress":String(this.scrollProgress)},g={"menu-open":e,"too-wide":s&&(t||a||i),[`layout-${this.layout}`]:!0,"is-scrolled":this.scrolled,"hide-on-scroll":this.hiddenByScroll,"scroll-compact":l.has("compact"),"scroll-elevate":l.has("elevate"),"scroll-transparent":l.has("transparent")||l.has("transparent-to-solid"),"scroll-collapse-topbar":l.has("collapse-topbar")},w=this.scheme==="dark"?"light":"dark";return d`
       <header class=${M(g)} style=${S(m)}>
         <section class="topbar">
           <slot name="topbar"></slot>
@@ -11,7 +11,7 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
           <slot name="brand">${this.renderConfiguredBrand()}</slot>
         </section>
 
-        <section ${v(this.menuContainer)} class="menu-container">
+        <section ${f(this.menuContainer)} class="menu-container">
           <slot name="menu"></slot>
         </section>
 
@@ -31,12 +31,12 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
             aria-expanded=${e?"true":"false"}
             @clicked=${this.handleMenuToggleClicked}
           >
-            <esp-burger ${v(this.menuButton)} presentation-only></esp-burger>
+            <esp-burger ${f(this.menuButton)} presentation-only></esp-burger>
           </esp-header-button>
         </section>
         ${h?d`<div class="scroll-progress" aria-hidden="true"></div>`:c}
       </header>
-    `}};r.styles=[...f.styles,y`
+    `}};r.styles=[...v.styles,y`
       :host {
         --_esp-header-current-height: var(--esp-header-height, calc(4.5 * var(--esp-size-small)));
 
@@ -51,6 +51,14 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
           var(--esp-header-brand-color, var(--esp-color-headings))
         );
 
+        
+        --_esp-header-content-surplus: max(
+          0px,
+          calc(100% - var(--esp-header-content-max-width, 100%))
+        );
+        padding-inline: calc(var(--_esp-header-content-surplus) * var(--esp-header-content-lead, 0))
+          calc(var(--_esp-header-content-surplus) * (1 - var(--esp-header-content-lead, 0)));
+
         display: grid;
         grid-template-columns: minmax(0, max-content) minmax(0, 1fr) max-content;
         grid-template-rows: min-content var(--_esp-header-current-height);
@@ -349,6 +357,11 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
         }
       }
 
+      
+      :host([full-bleed-content]) header {
+        padding-inline: 0;
+      }
+
       :host([brand-align="center"]) header section.brand {
         justify-content: center;
         text-align: center;
@@ -418,4 +431,4 @@ var n=function(p,e,t,o){var s=arguments.length,a=s<3?e:o===null?o=Object.getOwnP
           transition: none;
         }
       }
-    `],n([u()],r.prototype,"menuOpen",void 0),n([u()],r.prototype,"menuTooLarge",void 0),n([u()],r.prototype,"mobileMenu",void 0),n([u()],r.prototype,"scrolled",void 0),n([u()],r.prototype,"hiddenByScroll",void 0),n([u()],r.prototype,"scrollProgress",void 0),n([l({attribute:"show-burger",type:Boolean})],r.prototype,"showBurger",void 0),n([l({type:String,reflect:!0})],r.prototype,"layout",void 0),n([l({attribute:"brand-text",type:String})],r.prototype,"brandText",void 0),n([l({attribute:"brand-logo",type:String})],r.prototype,"brandLogo",void 0),n([l({attribute:"brand-href",type:String})],r.prototype,"brandHref",void 0),n([l({attribute:"brand-alt",type:String})],r.prototype,"brandAlt",void 0),n([l({attribute:"brand-color",type:String})],r.prototype,"brandColor",void 0),n([l({attribute:"brand-align",type:String,reflect:!0})],r.prototype,"brandAlign",void 0),n([l({attribute:"brand-wrap",type:String,reflect:!0})],r.prototype,"brandWrap",void 0),n([l({attribute:"menu-display",type:String,reflect:!0})],r.prototype,"menuDisplay",void 0),n([l({attribute:"theme-toggle",type:String,reflect:!0})],r.prototype,"themeToggle",void 0),n([l({attribute:"scroll-behavior",type:String})],r.prototype,"scrollBehavior",void 0),n([l({attribute:"scroll-threshold",type:Number})],r.prototype,"scrollThreshold",void 0),n([l({attribute:"dock-offset",type:Number})],r.prototype,"dockOffset",void 0),n([l({attribute:"drawer-target",type:String})],r.prototype,"drawerTarget",void 0),r=n([x("esp-header")],r);export{r as EspalierHeader};
+    `],n([u()],r.prototype,"menuOpen",void 0),n([u()],r.prototype,"menuTooLarge",void 0),n([u()],r.prototype,"mobileMenu",void 0),n([u()],r.prototype,"scrolled",void 0),n([u()],r.prototype,"hiddenByScroll",void 0),n([u()],r.prototype,"scrollProgress",void 0),n([o({attribute:"show-burger",type:Boolean})],r.prototype,"showBurger",void 0),n([o({type:String,reflect:!0})],r.prototype,"layout",void 0),n([o({attribute:"brand-text",type:String})],r.prototype,"brandText",void 0),n([o({attribute:"brand-logo",type:String})],r.prototype,"brandLogo",void 0),n([o({attribute:"brand-href",type:String})],r.prototype,"brandHref",void 0),n([o({attribute:"brand-alt",type:String})],r.prototype,"brandAlt",void 0),n([o({attribute:"brand-color",type:String})],r.prototype,"brandColor",void 0),n([o({attribute:"brand-align",type:String,reflect:!0})],r.prototype,"brandAlign",void 0),n([o({attribute:"brand-wrap",type:String,reflect:!0})],r.prototype,"brandWrap",void 0),n([o({attribute:"menu-display",type:String,reflect:!0})],r.prototype,"menuDisplay",void 0),n([o({attribute:"theme-toggle",type:String,reflect:!0})],r.prototype,"themeToggle",void 0),n([o({attribute:"scroll-behavior",type:String})],r.prototype,"scrollBehavior",void 0),n([o({attribute:"scroll-threshold",type:Number})],r.prototype,"scrollThreshold",void 0),n([o({attribute:"dock-offset",type:Number})],r.prototype,"dockOffset",void 0),n([o({attribute:"drawer-target",type:String})],r.prototype,"drawerTarget",void 0),n([o({attribute:"full-bleed-content",type:Boolean,reflect:!0})],r.prototype,"fullBleedContent",void 0),r=n([x("esp-header")],r);export{r as EspalierHeader};

package/dist/page/esp-page.d.ts

@@ -96,15 +96,33 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * </esp-page>
  * ```
  *
- * @cssprop --esp-page-background - The background color of the page.
- * Defaults to `var(--esp-color-background)`.
+ * @cssprop --esp-page-background - The background color of the page. Fills
+ * both the surface and the canvas gutters; the canvas tokens paint over it
+ * in the gutters only. Defaults to `var(--esp-color-background)`.
  * @cssprop --esp-page-max-width - The maximum width of the main content
  * well. Set automatically by the `kind` attribute: `1536px` (wide),
- * `768px` (narrow), or `none` (full).
+ * `768px` (narrow), or `none` (full). This cap now sizes the main grid
+ * track; surplus width beyond it becomes the canvas gutters.
  * @cssprop --esp-page-background-image - The background image to
  * display behind page content. Defaults to `none`.
  * @cssprop --esp-page-background-image-opacity - The opacity of the
  * background image layer. Defaults to `1`.
+ * @cssprop --esp-page-canvas-background - The background color of the
+ * canvas gutters (the outer regions revealed when the viewport exceeds
+ * the cap). Defaults to `transparent`, so gutters match the page until
+ * styled and narrow viewports are unaffected.
+ * @cssprop --esp-page-canvas-background-image - A background image for the
+ * canvas gutters, mirroring the page background-image knob. Defaults to
+ * `none`.
+ * @cssprop --esp-page-canvas-background-image-opacity - The opacity of the
+ * canvas gutter image layer. Defaults to `1`.
+ * @cssprop --esp-page-surface-shadow - The box shadow drawn on the left
+ * and right edges of the content surface. On by default; casts into the
+ * gutters and is clipped away when the surface fills the viewport, so it
+ * only shows above the cap. Set to `none` to remove it.
+ * @cssprop --esp-page-surface-border - An optional border on the inline
+ * edges of the surface, for themes preferring a hairline over a shadow.
+ * Defaults to `none` (e.g. `1px solid var(--esp-color-border)`).
  * @cssprop --esp-page-fixed-header-offset - Offset reserved for fixed
  * headers. Defaults to `var(--esp-header-height)`.
  * @cssprop --esp-page-sticky-header-top - Top inset for sticky headers.
@@ -112,6 +130,9 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * @cssprop --esp-page-header-z-index - Z-index for fixed/sticky header
  * regions. Defaults to `20`.
  *
+ * @csspart canvas - The two canvas gutter regions flanking the surface.
+ * @csspart surface - The surface backdrop carrying the edge shadow/border.
+ *
  * ```html
  * <style>
  * esp-page.with-background {
@@ -130,6 +151,29 @@ type HeaderPosition = "normal" | "sticky" | "fixed";
  * </esp-page>
  * ```
  *
+ * Use `align` to place the surface within the page once it hits its cap,
+ * and the canvas tokens to style the gutters. A low `--esp-page-max-width`
+ * is set here only so the gutters are visible inside the narrow demo
+ * frame; the surface edge shadow is on by default.
+ *
+ * ```html
+ * <style>
+ * esp-page.align-demo {
+ *   --esp-page-max-width: 520px;
+ *   --esp-page-canvas-background: var(--esp-color-layer-1);
+ * }
+ * </style>
+ * <esp-page class="docs align-demo" align="center">
+ *   <div slot="header" style="background-color: red;">header</div>
+ *   <div slot="sidebar" style="background-color: green;">sidebar</div>
+ *   <div slot="right" style="background-color: purple;">right</div>
+ *   <div slot="footer" style="background-color: blue;">footer</div>
+ *   <div style="background-color: black; overflow: hidden;">
+ *     content
+ *   </div>
+ * </esp-page>
+ * ```
+ *
  * @docPageTitle Page
  * @docUrl /components/page
  * @menuGroup Structure
@@ -153,6 +197,38 @@ export declare class EspalierPage extends EspalierElementBase {
      *   maps or design tools.
      */
     kind: "wide" | "narrow" | "full";
+    /**
+     * Horizontal alignment of the content **surface** (left aside + main
+     * well + right aside) within the page once the viewport is wider than
+     * the content cap. The surplus width becomes styleable **canvas**
+     * gutters on the outer edges, weighted by this attribute.
+     *
+     * - `start` (default) — the surface hugs the leading edge; all spare
+     *   width collects in the trailing gutter. This reproduces today's
+     *   layout.
+     * - `center` — spare width is split evenly into both gutters, centering
+     *   the surface.
+     * - `end` — the surface hugs the trailing edge; spare width collects in
+     *   the leading gutter.
+     *
+     * Has no effect when `kind="full"` (no cap means no gutters) or on
+     * viewports narrower than the cap (the surface already fills the width).
+     */
+    align: "start" | "center" | "end";
+    /**
+     * When set, the header and footer sit **on** the content surface —
+     * the same width as the left aside + main well + right aside — instead
+     * of spanning the full viewport. Combined with a styled canvas this
+     * frames the whole page as one contained band floating on the canvas,
+     * with a single continuous surface edge shadow running from the header
+     * through the content to the footer.
+     *
+     * Below the cap there are no gutters, so a contained page renders
+     * identically to the default full-bleed chrome. Designed for
+     * `header-position="normal"` or `"sticky"`; a fixed header cannot be
+     * banded to the surface.
+     */
+    contained: boolean;
     /**
      * Header positioning behavior for the `header` slot.
      *

package/dist/page/esp-page.js

@@ -1,5 +1,8 @@
-var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnPropertyDescriptor(e,i):o,p;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")t=Reflect.decorate(s,e,i,o);else for(var d=s.length-1;d>=0;d--)(p=s[d])&&(t=(r<3?p(t):r>3?p(e,i,t):p(e,i))||t);return r>3&&t&&Object.defineProperty(e,i,t),t};import{css as c,html as f}from"lit";import{customElement as m,property as l}from"lit/decorators.js";import{classMap as u}from"lit/directives/class-map.js";import{createRef as v,ref as x}from"lit/directives/ref.js";import{EspalierElementBase as g}from"../shared/esp-element-base.js";import{BiDirectionalStickyController as h}from"./bi-directional-sticky-controller.js";import{getEspBus as y}from"../shared/bus-events.js";import"../toaster/esp-toaster.js";let a=class extends g{constructor(){super(),this.dialogZone=v(),this.kind="wide",this.headerPosition="normal",this.fixedMenus=!1,new h(this,".esp-page-left > .sticky-wrapper"),new h(this,".esp-page-right > .sticky-wrapper")}AddDialog(e){this.dialogZone.value?.appendChild(e)}updated(e){super.updated(e),(e.has("fixedMenus")||e.has("headerPosition"))&&y().publish("fixed-menus-changed",{fixed:this.fixedMenus||this.headerPosition==="fixed"})}render(){const e=this.fixedMenus||this.headerPosition==="fixed",i=!e&&this.headerPosition==="sticky";return f`
-      <div part="wrapper" class="esp-page ${u({"fixed-menus":e,"fixed-header":e,"sticky-header":i})}">
+var o=function(n,e,s,r){var d=arguments.length,a=d<3?e:r===null?r=Object.getOwnPropertyDescriptor(e,s):r,p;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")a=Reflect.decorate(n,e,s,r);else for(var l=n.length-1;l>=0;l--)(p=n[l])&&(a=(d<3?p(a):d>3?p(e,s,a):p(e,s))||a);return d>3&&a&&Object.defineProperty(e,s,a),a};import{css as g,html as f}from"lit";import{customElement as u,property as i}from"lit/decorators.js";import{classMap as m}from"lit/directives/class-map.js";import{createRef as v,ref as w}from"lit/directives/ref.js";import{EspalierElementBase as h}from"../shared/esp-element-base.js";import{BiDirectionalStickyController as c}from"./bi-directional-sticky-controller.js";import{getEspBus as b}from"../shared/bus-events.js";import"../toaster/esp-toaster.js";let t=class extends h{constructor(){super(),this.dialogZone=v(),this.kind="wide",this.align="start",this.contained=!1,this.headerPosition="normal",this.fixedMenus=!1,new c(this,".esp-page-left > .sticky-wrapper"),new c(this,".esp-page-right > .sticky-wrapper")}AddDialog(e){this.dialogZone.value?.appendChild(e)}updated(e){super.updated(e),(e.has("fixedMenus")||e.has("headerPosition"))&&b().publish("fixed-menus-changed",{fixed:this.fixedMenus||this.headerPosition==="fixed"})}render(){const e=this.fixedMenus||this.headerPosition==="fixed",s=!e&&this.headerPosition==="sticky";return f`
+      <div part="wrapper" class="esp-page ${m({"fixed-menus":e,"fixed-header":e,"sticky-header":s})}">
+        <div part="canvas" class="esp-page-canvas esp-page-canvas--left" aria-hidden="true"></div>
+        <div part="canvas" class="esp-page-canvas esp-page-canvas--right" aria-hidden="true"></div>
+        <div part="surface" class="esp-page-surface" aria-hidden="true"></div>
         <div class="esp-page-top">
           <slot name="header"></slot>
         </div>
@@ -19,12 +22,17 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
         <footer>
           <slot name="footer"></slot>
         </footer>
-        <div id="dialog-drop-zone" ${x(this.dialogZone)}></div>
+        <div id="dialog-drop-zone" ${w(this.dialogZone)}></div>
         <esp-toaster></esp-toaster>
       </div>
-    `}};a.styles=[...g.styles,c`
+    `}};t.styles=[...h.styles,g`
       :host {
         --_esp-page-resolved-max-width: var(--esp-page-max-width, 1536px);
+        
+        --_esp-page-main-track: minmax(0, var(--_esp-page-resolved-max-width));
+        
+        --_esp-page-gutter-left: 0;
+        --_esp-page-gutter-right: 1fr;
         --_esp-page-fixed-header-offset: var(
           --esp-page-fixed-header-offset,
           var(--esp-header-height, calc(4.5 * var(--esp-size-small)))
@@ -37,8 +45,53 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
         --_esp-page-resolved-max-width: var(--esp-page-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: 0;
+      }
+
+      
       :host([kind="full"]) {
         --_esp-page-resolved-max-width: var(--esp-page-max-width, none);
+        --_esp-page-main-track: 1fr;
+        --_esp-page-gutter-left: 0;
+        --_esp-page-gutter-right: 0;
+      }
+
+      
+      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;
+      }
+
+      
+      :host([kind="full"]) slot[name="header"]::slotted(esp-header) {
+        --esp-header-content-max-width: 100%;
+      }
+
+      
+      :host([contained]) .esp-page > div.esp-page-top,
+      :host([contained]) .esp-page > footer {
+        grid-column: surface;
+      }
+
+      
+      :host([contained]) slot[name="header"]::slotted(esp-header) {
+        --esp-header-content-max-width: 100%;
+        --esp-header-shadow: none;
       }
 
       :host([kind="narrow"]) .esp-page > div.esp-page-main {
@@ -57,10 +110,12 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
         min-height: 100vh;
         display: grid;
         grid-template-columns:
-          [full-start left-start] min-content
-          [left-end main-start] 1fr
+          [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 full-end];
+          [right-end surface-end canvas-right-start] var(--_esp-page-gutter-right)
+          [canvas-right-end full-end];
         grid-template-rows:
           [top-start] min-content
           [top-end content-start] 1fr
@@ -113,7 +168,7 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
           grid-row: content;
           position: relative;
           overflow: hidden;
-          max-width: var(--_esp-page-resolved-max-width);
+          
           contain: inline-size;
         }
 
@@ -122,6 +177,48 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
         }
 
         
+        > .esp-page-canvas {
+          
+          grid-row: top-start / footer-end;
+          z-index: 1;
+          position: relative;
+          pointer-events: none;
+          background-color: var(--esp-page-canvas-background, transparent);
+
+          
+          &::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 {
+          grid-column: canvas-right;
+        }
+
+        
+        > .esp-page-surface {
+          grid-column: surface;
+          
+          grid-row: top-start / footer-end;
+          z-index: 2;
+          pointer-events: none;
+          box-shadow: var(
+            --esp-page-surface-shadow,
+            -0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow),
+            0.75rem 0 1.5rem -0.75rem var(--esp-color-shadow)
+          );
+          border-inline: var(--esp-page-surface-border, none);
+        }
+
+        
         .sticky-wrapper {
           will-change: top;
           display: block;
@@ -166,7 +263,9 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
 
           > div.esp-page-main,
           > aside.esp-page-left,
-          > aside.esp-page-right {
+          > aside.esp-page-right,
+          > .esp-page-surface,
+          > .esp-page-canvas {
             margin-top: var(--_esp-page-fixed-header-offset);
           }
         }
@@ -194,4 +293,4 @@ var n=function(s,e,i,o){var r=arguments.length,t=r<3?e:o===null?o=Object.getOwnP
       .esp-page:has(esp-dialog[is-open="true"]) {
         overflow: hidden;
       }
-    `],n([l({reflect:!0})],a.prototype,"kind",void 0),n([l({attribute:"header-position",reflect:!0})],a.prototype,"headerPosition",void 0),n([l({attribute:"fixed-menus",type:Boolean,reflect:!0})],a.prototype,"fixedMenus",void 0),a=n([m("esp-page")],a);export{a as EspalierPage};
+    `],o([i({reflect:!0})],t.prototype,"kind",void 0),o([i({reflect:!0})],t.prototype,"align",void 0),o([i({type:Boolean,reflect:!0})],t.prototype,"contained",void 0),o([i({attribute:"header-position",reflect:!0})],t.prototype,"headerPosition",void 0),o([i({attribute:"fixed-menus",type:Boolean,reflect:!0})],t.prototype,"fixedMenus",void 0),t=o([u("esp-page")],t);export{t as EspalierPage};

package/espalier.token-manifest.json

@@ -842,6 +842,18 @@
       "component": "esp-header",
       "description": "The height of compact scroll-reactive headers. Defaults to `max(44px, calc(3.5 * var(--esp-size-small)))`."
     },
+    {
+      "name": "--esp-header-content-lead",
+      "category": "component",
+      "component": "esp-header",
+      "description": "Surface-alignment contract set by `esp-page`: the fraction of the leftover width placed before the content, aligning it (`0` = start, `0.5` = center, `1` = end). Defaults to `0`."
+    },
+    {
+      "name": "--esp-header-content-max-width",
+      "category": "component",
+      "component": "esp-header",
+      "description": "Surface-alignment contract set by `esp-page`: the maximum width the bar content is constrained to (the bar background stays full-bleed). Defaults to `100%` (no constraint). `esp-page` sets this to its resolved content cap."
+    },
     {
       "name": "--esp-header-extended-menu-border",
       "category": "component",
@@ -1219,7 +1231,7 @@
       "name": "--esp-page-background",
       "category": "component",
       "component": "esp-page",
-      "description": "The background color of the page. Defaults to `var(--esp-color-background)`."
+      "description": "The background color of the page. Fills both the surface and the canvas gutters; the canvas tokens paint over it in the gutters only. Defaults to `var(--esp-color-background)`."
     },
     {
       "name": "--esp-page-background-image",
@@ -1231,6 +1243,24 @@
       "category": "root-theme",
       "description": "The opacity of the background image layer. Defaults to `1`."
     },
+    {
+      "name": "--esp-page-canvas-background",
+      "category": "component",
+      "component": "esp-page",
+      "description": "The background color of the canvas gutters (the outer regions revealed when the viewport exceeds the cap). Defaults to `transparent`, so gutters match the page until styled and narrow viewports are unaffected."
+    },
+    {
+      "name": "--esp-page-canvas-background-image",
+      "category": "component",
+      "component": "esp-page",
+      "description": "A background image for the canvas gutters, mirroring the page background-image knob. Defaults to `none`."
+    },
+    {
+      "name": "--esp-page-canvas-background-image-opacity",
+      "category": "component",
+      "component": "esp-page",
+      "description": "The opacity of the canvas gutter image layer. Defaults to `1`."
+    },
     {
       "name": "--esp-page-fixed-header-offset",
       "category": "component",
@@ -1247,7 +1277,7 @@
       "name": "--esp-page-max-width",
       "category": "component",
       "component": "esp-page",
-      "description": "The maximum width of the main content well. Set automatically by the `kind` attribute: `1536px` (wide), `768px` (narrow), or `none` (full)."
+      "description": "The maximum width of the main content well. Set automatically by the `kind` attribute: `1536px` (wide), `768px` (narrow), or `none` (full). This cap now sizes the main grid track; surplus width beyond it becomes the canvas gutters."
     },
     {
       "name": "--esp-page-sticky-header-top",
@@ -1255,6 +1285,18 @@
       "component": "esp-page",
       "description": "Top inset for sticky headers. Defaults to `0`."
     },
+    {
+      "name": "--esp-page-surface-border",
+      "category": "component",
+      "component": "esp-page",
+      "description": "An optional border on the inline edges of the surface, for themes preferring a hairline over a shadow. Defaults to `none` (e.g. `1px solid var(--esp-color-border)`)."
+    },
+    {
+      "name": "--esp-page-surface-shadow",
+      "category": "component",
+      "component": "esp-page",
+      "description": "The box shadow drawn on the left and right edges of the content surface. On by default; casts into the gutters and is clipped away when the surface fills the viewport, so it only shows above the cap. Set to `none` to remove it."
+    },
     {
       "name": "--esp-progress-border-color",
       "category": "component",

package/licenses/ASSET_PROVENANCE.md

@@ -14,6 +14,8 @@ removing, or replacing non-code assets.
 | `dist/shared/virtualizer/**` | Vendored Lit Virtualizer runtime source compiled into Espalier's package. | `licenses/THIRD_PARTY_NOTICES.md` |
 | Brand favicons/logos | Taproot-owned Espalier brand assets. | None |
 | Demo textures | Taproot-owned generated PNG textures created for this repository. | None |
+| `assets/canvas-bg.jpg` | Docs-only light canvas texture — Envato Elements item "Seamless Pattern Design With Colorful Flowers" by yusufdemirci; certificate `licenses/license_certificate_A2BVZ6Y9DN.pdf`; attribution not required; kept out of the published `@taprootio/espalier` package. | None |
+| `assets/canvas-bg-dark.jpg` | Docs-only dark canvas texture — Envato Elements item "Nocturnal Garden Pattern" by Webvilla; certificate `licenses/license_certificate_HF5ZVPRNC2.pdf`; attribution not required; kept out of the published package. | None |
 | Demo JSON data | Taproot-authored fictitious samples or standards-derived factual color data. | None |
 
 ## Texture Replacement

package/licenses/asset-provenance.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "updatedAt": "2026-06-30",
+  "updatedAt": "2026-07-11",
   "entries": [
     {
       "id": "google-font-preview-assets",
@@ -211,6 +211,44 @@
       "noticeRequirement": "none",
       "noticePaths": [],
       "reviewStatus": "documented"
+    },
+    {
+      "id": "envato-canvas-background-texture",
+      "paths": [
+        "assets/canvas-bg.jpg"
+      ],
+      "assetType": "decorative floral background texture (JPEG, 400x400 seamless tile)",
+      "classification": "third-party licensed",
+      "owner": "Envato Elements author \"yusufdemirci\" retains ownership; licensed to Jereme Evans / Taproot under an Envato Elements subscription",
+      "source": "Envato Elements item \"Seamless Pattern Design With Colorful Flowers\" (item id ab0dc3dd-7d36-44be-9898-d148173189da, https://app.envato.com/item/ab0dc3dd-7d36-44be-9898-d148173189da), downloaded 2026-07-11 under an active subscription. License certificate A2BVZ6Y9DN on file at licenses/license_certificate_A2BVZ6Y9DN.pdf.",
+      "license": "Envato Elements subscription license (certificate A2BVZ6Y9DN): broad commercial use permitted and attribution is not required for this use. The author retains ownership; the item (or any product using it) may not be trademarked or claimed as Taproot-owned, and it must not be redistributed so that others can extract it. Valid only while the Envato subscription remains active.",
+      "transformations": [
+        "None; used as-is as a repeating docs-site canvas gutter background at 50% image-layer opacity"
+      ],
+      "packageInclusion": "not included in npm package",
+      "docsInclusion": "docs-site only — referenced as --esp-page-canvas-background-image in css/docs.css (which the public @taprootio/espalier package excludes) and served from the Eleventy /assets passthrough",
+      "noticeRequirement": "none",
+      "noticePaths": [],
+      "reviewStatus": "documented"
+    },
+    {
+      "id": "envato-canvas-background-texture-dark",
+      "paths": [
+        "assets/canvas-bg-dark.jpg"
+      ],
+      "assetType": "decorative dark botanical background texture (JPEG, 500x500 seamless tile)",
+      "classification": "third-party licensed",
+      "owner": "Envato Elements author \"Webvilla\" retains ownership; licensed to Jereme Evans / Taproot under an Envato Elements subscription",
+      "source": "Envato Elements item \"Nocturnal Garden Pattern\" (item id df520f04-5dfb-41c3-aa87-2ce3c03c8c34, https://app.envato.com/item/df520f04-5dfb-41c3-aa87-2ce3c03c8c34), downloaded 2026-07-11 under an active subscription as the dark-mode counterpart to canvas-bg.jpg. License certificate HF5ZVPRNC2 on file at licenses/license_certificate_HF5ZVPRNC2.pdf.",
+      "license": "Envato Elements subscription license (certificate HF5ZVPRNC2), same terms as canvas-bg.jpg: broad commercial use permitted and attribution not required; author retains ownership, no trademark/ownership claims, no redistribution for extraction, valid only while the subscription is active.",
+      "transformations": [
+        "None; used as-is as a repeating docs-site dark-mode canvas gutter background at 50% image-layer opacity"
+      ],
+      "packageInclusion": "not included in npm package",
+      "docsInclusion": "docs-site only — referenced as --esp-page-canvas-background-image under esp-root[scheme=\"dark\"] in css/docs.css (excluded from the public @taprootio/espalier package) and served from the Eleventy /assets passthrough",
+      "noticeRequirement": "none",
+      "noticePaths": [],
+      "reviewStatus": "documented"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Espalier — a themeable, accessible, framework-agnostic, enterprise-grade design system built on web standards and love.",
   "customElements": "custom-elements.json",
   "type": "module",