@taprootio/espalier 2.5.0 → 2.7.0

package/dist/image/esp-image.js

@@ -1,51 +1,442 @@
-var a=function(h,e,t,i){var o=arguments.length,r=o<3?e:i===null?i=Object.getOwnPropertyDescriptor(e,t):i,s;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(h,e,t,i);else for(var c=h.length-1;c>=0;c--)(s=h[c])&&(r=(o<3?s(r):o>3?s(e,t,r):s(e,t))||r);return o>3&&r&&Object.defineProperty(e,t,r),r},d;import{css as m,html as p,nothing as f}from"lit";import{customElement as y,property as l,state as b}from"lit/decorators.js";import{EspalierElementBase as g}from"../shared/esp-element-base.js";import{validImageDimensions as u}from"./image-dimensions.js";import"./esp-image-option.js";let n=d=class extends g{constructor(){super(...arguments),this.originalHeight=0,this.originalWidth=0,this.imageUrl="",this.localImage="",this.caption="",this.sizes="100vw",this.loading="eager",this.renderedWidth=0,this.resizeObserver=null,this.handleSlotChange=()=>{this.requestUpdate()}}get isPortrait(){const e=u(this.originalWidth,this.originalHeight);return e!==null&&e.height>e.width}findProjected(){for(const e of this.children)if(e.tagName==="PICTURE"||e.tagName==="IMG")return e;return null}connectedCallback(){super.connectedCallback(),d.ensureProjectionStyles(this.getRootNode()),this.resizeObserver??=new ResizeObserver(e=>{const t=e[0]?.contentBoxSize?.[0],i=Math.round(t?t.inlineSize:e[0]?.contentRect.width??0);i>0&&i!==this.renderedWidth&&(this.renderedWidth=i)}),this.resizeObserver.observe(this)}disconnectedCallback(){super.disconnectedCallback(),this.resizeObserver?.disconnect(),this.resizeObserver=null}effectiveSizes(){return this.renderedWidth>0?`${this.renderedWidth}px`:this.sizes}buildSources(){const e=Array.from(this.querySelectorAll("esp-image-option")),t=new Map;for(const i of e){const o=i.getAttribute("url"),r=Number(i.getAttribute("width"));if(!o||!Number.isFinite(r)||r<=0)continue;const s=i.getAttribute("type")??"",c=t.get(s)??[];c.push({url:o,width:r}),t.set(s,c)}return Array.from(t,([i,o])=>({type:i,srcset:o.sort((r,s)=>r.width-s.width).map(r=>`${r.url} ${r.width}w`).join(", ")})).filter(i=>i.srcset.length>0)}willUpdate(e){if(super.willUpdate(e),!this.hasUpdated||e.has("originalWidth")||e.has("originalHeight")){const t=u(this.originalWidth,this.originalHeight);t?this.style.setProperty("--_esp-image-aspect-ratio",`${t.width} / ${t.height}`):this.style.removeProperty("--_esp-image-aspect-ratio")}}updated(e){if(super.updated(e),this.renderedWidth<=0)return;const t=this.findProjected();if(!t)return;const i=this.effectiveSizes();if(t.tagName==="PICTURE")for(const r of t.querySelectorAll("source"))r.setAttribute("sizes",i);const o=t.tagName==="IMG"?t:t.querySelector("img");o?.hasAttribute("srcset")&&o.setAttribute("sizes",i)}render(){if(this.localImage)return p`<img
+var n=function(p,e,t,r){var i=arguments.length,o=i<3?e:r===null?r=Object.getOwnPropertyDescriptor(e,t):r,s;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(p,e,t,r);else for(var c=p.length-1;c>=0;c--)(s=p[c])&&(o=(i<3?s(o):i>3?s(e,t,o):s(e,t))||o);return i>3&&o&&Object.defineProperty(e,t,o),o},m;import{css as T,html as d,nothing as N}from"lit";import{customElement as P,property as l,state as u}from"lit/decorators.js";import{EspalierElementBase as y}from"../shared/esp-element-base.js";import{slotHasContent as f}from"../shared/slot-content.js";import{renderVisualOverlay as R,visualOverlayStyles as I}from"../shared/visual-overlay.js";import{focusConverter as E,normalizeFocus as O}from"./image-focus.js";import{ensureImageTextureFilters as A,imageTextureFilterId as W}from"./image-texture-filters.js";import{getImageTexture as b,isBuiltInImageTexture as x,subscribeToImageTextureRegistry as H}from"../shared/image-texture-registry.js";import{validImageDimensions as _}from"./image-dimensions.js";import"./esp-image-option.js";const k=new Set(["auto","none","flat","top","bottom","left","right","radial"]),S=new Set(["soft","medium","strong"]),w=new Set(["fine","medium","coarse"]),z=new Set(["auto","light","dark"]),j=new Set(["bottom-start","bottom","bottom-end","center","top-start","top","top-end"]);function h(p,e){return{fromAttribute(t){return t&&p.has(t)?t:e},toAttribute(t){return p.has(t)?t:e}}}function C(p){const e=p.trim();if(!e)return null;const t=e.split("/").map(i=>i.trim());if(t.length>2||t.some(i=>i.length===0))return null;const r=t.map(Number);return r.some(i=>!Number.isFinite(i)||i<=0)?null:r.length===1?String(r[0]):`${r[0]} / ${r[1]}`}let a=m=class extends y{constructor(){super(...arguments),this.originalHeight=0,this.originalWidth=0,this.imageUrl="",this.localImage="",this.caption="",this.sizes="100vw",this.loading="eager",this.banner=!1,this.bannerScheme="auto",this.scrim="auto",this.scrimStrength="medium",this.texture="none",this.textureScale="medium",this.contentPosition="bottom-start",this.focusPoint={x:.5,y:.5},this.ratio="",this.compactRatio="",this.renderedWidth=0,this.compact=!1,this.overlayHasContent=!1,this.resizeObserver=null,this.unsubscribeTextures=null,this.handleSlotChange=e=>{if(e.target instanceof HTMLSlotElement){if(e.target.name==="overlay"){const t=f(e.target);t!==this.overlayHasContent&&(this.overlayHasContent=t);return}this.requestUpdate()}}}get isPortrait(){const e=_(this.originalWidth,this.originalHeight);return e!==null&&e.height>e.width}findProjected(){for(const e of this.children)if(e.tagName==="PICTURE"||e.tagName==="IMG")return e;return null}connectedCallback(){super.connectedCallback(),m.ensureProjectionStyles(this.getRootNode()),this.unsubscribeTextures??=H(()=>this.requestUpdate()),this.resizeObserver??=new ResizeObserver(e=>{const t=e[0]?.contentBoxSize?.[0],r=Math.round(t?t.inlineSize:e[0]?.contentRect.width??0);r>0&&r!==this.renderedWidth&&(this.renderedWidth=r)}),this.resizeObserver.observe(this)}disconnectedCallback(){super.disconnectedCallback(),this.unsubscribeTextures?.(),this.unsubscribeTextures=null,this.resizeObserver?.disconnect(),this.resizeObserver=null}effectiveSizes(){return this.renderedWidth>0?`${this.renderedWidth}px`:this.sizes}buildSources(){const e=new Map;for(const t of this.querySelectorAll("esp-image-option")){const r=t.getAttribute("url"),i=Number(t.getAttribute("width"));if(!r||!Number.isFinite(i)||i<=0)continue;const o=t.getAttribute("type")??"",s=e.get(o)??[];s.push({url:r,width:i}),e.set(o,s)}return Array.from(e,([t,r])=>({type:t,srcset:r.sort((i,o)=>i.width-o.width).map(i=>`${i.url} ${i.width}w`).join(", ")})).filter(t=>t.srcset.length>0)}resolvedBannerScheme(){return this.bannerScheme!=="auto"?this.bannerScheme:this.scheme==="dark"?"dark":"light"}resolvedTexture(){return x(this.texture)?this.texture:b(this.texture)?this.texture:"none"}resolvedScrim(){return this.scrim!=="auto"?this.scrim:this.overlayHasContent?this.contentPosition.startsWith("top")?"top":this.contentPosition.startsWith("bottom")?"bottom":"radial":"none"}resolvedAspectRatio(){const e=_(this.originalWidth,this.originalHeight);if(!this.banner)return e?`${e.width} / ${e.height}`:null;const t=C(this.ratio);return(this.compact?C(this.compactRatio):null)??t??(e?`${e.width} / ${e.height}`:null)}normalizeEnums(e){e.has("scrim")&&!k.has(this.scrim)&&(this.scrim="auto"),e.has("bannerScheme")&&!z.has(this.bannerScheme)&&(this.bannerScheme="auto"),e.has("scrimStrength")&&!S.has(this.scrimStrength)&&(this.scrimStrength="medium"),e.has("textureScale")&&!w.has(this.textureScale)&&(this.textureScale="medium"),e.has("contentPosition")&&!j.has(this.contentPosition)&&(this.contentPosition="bottom-start")}willUpdate(e){super.willUpdate(e),this.normalizeEnums(e);const t=O(this.focusPoint),r=Number((t.x*100).toFixed(4)),i=Number((t.y*100).toFixed(4));this.style.setProperty("--_esp-image-object-position",`${r}% ${i}%`);const o=this.resolvedAspectRatio();o?this.style.setProperty("--_esp-image-aspect-ratio",o):this.style.removeProperty("--_esp-image-aspect-ratio");const s=this.resolvedTexture();if(["paper","grain","grunge"].includes(s)){const g=s==="grunge"&&this.resolvedBannerScheme()==="light"?"grunge-light":s;this.style.setProperty("--_esp-image-texture-filter",`url(#${W(g,this.textureScale)})`)}else this.style.removeProperty("--_esp-image-texture-filter");const c=x(s)?void 0:b(s),$=[["--_esp-image-registered-image",c?.image],["--_esp-image-registered-size",c?.size],["--_esp-image-registered-repeat",c?.repeat],["--_esp-image-registered-position",c?.position],["--_esp-image-registered-opacity",c?.opacity?.toString()],["--_esp-image-registered-blend-mode",c?.blendMode]];for(const[g,v]of $)v===void 0?this.style.removeProperty(g):this.style.setProperty(g,v)}firstUpdated(e){super.firstUpdated(e);const t=this.shadowRoot?.querySelector('slot[name="overlay"]');t&&(this.overlayHasContent=f(t))}updated(e){if(super.updated(e),["paper","grain","grunge"].includes(this.resolvedTexture())&&this.renderRoot&&A(this.renderRoot),this.renderedWidth>0){const s=this.shadowRoot?.querySelector(".compact-sentinel")?.getBoundingClientRect().width??0,c=s>0&&this.renderedWidth<s;c!==this.compact&&(this.compact=c)}if(this.renderedWidth<=0)return;const t=this.findProjected();if(!t)return;const r=this.effectiveSizes();if(t.tagName==="PICTURE")for(const o of t.querySelectorAll("source"))o.setAttribute("sizes",r);const i=t.tagName==="IMG"?t:t.querySelector("img");i?.hasAttribute("srcset")&&i.setAttribute("sizes",r)}renderMedia(){if(this.localImage)return d`<img
         src=${this.localImage}
         alt=${this.caption}
         decoding="async"
         loading=${this.loading}
-      />`;const e=p`<slot @slotchange=${this.handleSlotChange}></slot>`;if(this.findProjected())return e;const t=this.buildSources();return p`<picture>
-        ${t.map(i=>p`<source
-              srcset=${i.srcset}
+      />`;const e=d`<slot @slotchange=${this.handleSlotChange}></slot>`;if(this.findProjected())return e;const t=this.buildSources();return d`
+      <picture>
+        ${t.map(r=>d`
+            <source
+              srcset=${r.srcset}
               sizes=${this.effectiveSizes()}
-              type=${i.type||f}
-            />`)}
+              type=${r.type||N}
+            />
+          `)}
         <img src=${this.imageUrl} alt=${this.caption} decoding="async" loading=${this.loading} />
       </picture>
-      ${e}`}static ensureProjectionStyles(e){const t=e.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&"host"in e?e:e.nodeType===Node.DOCUMENT_NODE?e.head:e.ownerDocument?.head??document.head,i=Array.from(t.querySelectorAll("style[data-esp-image-projection-styles]")),o=i.find(s=>s.textContent===d.projectionStyles);if(o){for(const s of i)s!==o&&s.remove();return}for(const s of i)s.remove();const r=t.ownerDocument.createElement("style");r.dataset.espImageProjectionStyles="",r.textContent=d.projectionStyles,t.appendChild(r)}};n.projectionStyles=`
+      ${e}
+    `}render(){return d`
+      <div
+        part="frame"
+        class="frame"
+        data-banner-scheme=${this.resolvedBannerScheme()}
+        data-scrim=${this.resolvedScrim()}
+        data-scrim-strength=${this.scrimStrength}
+        data-texture=${this.resolvedTexture()}
+        data-texture-scale=${this.textureScale}
+        data-content-position=${this.contentPosition}
+      >
+        <div part="image" class="image">${this.renderMedia()}</div>
+        ${R({className:"banner-layers",imagePart:"texture",scrimPart:"scrim",texturePart:"texture"})}
+        <div part="overlay" class="overlay" ?hidden=${!this.banner||!this.overlayHasContent}>
+          <slot name="overlay" @slotchange=${this.handleSlotChange}></slot>
+        </div>
+        <span class="compact-sentinel" aria-hidden="true"></span>
+      </div>
+    `}static ensureProjectionStyles(e){const t=e.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&"host"in e?e:e.nodeType===Node.DOCUMENT_NODE?e.head:e.ownerDocument?.head??document.head,r=Array.from(t.querySelectorAll("style[data-esp-image-projection-styles]")),i=r.find(s=>s.textContent===m.projectionStyles);if(i){for(const s of r)s!==i&&s.remove();return}for(const s of r)s.remove();const o=t.ownerDocument.createElement("style");o.dataset.espImageProjectionStyles="",o.textContent=m.projectionStyles,t.append(o)}};a.projectionStyles=`
     esp-image > picture,
     esp-image > img {
       display: block;
       width: 100%;
       height: 100%;
       object-fit: var(--_esp-image-object-fit, cover);
+      object-position: var(--esp-image-object-position, var(--_esp-image-object-position, center));
     }
     esp-image > picture > img {
       display: block;
       width: 100%;
       height: 100%;
       object-fit: var(--_esp-image-object-fit, cover);
+      object-position: var(--esp-image-object-position, var(--_esp-image-object-position, center));
     }
-  `,n.styles=[...g.styles,m`
+  `,a.styles=[...y.styles,T`
       :host {
         display: block;
         aspect-ratio: var(--_esp-image-aspect-ratio, auto);
-        border: var(--esp-image-border, 2px solid var(--esp-color-border));
+        border: var(
+          --esp-image-border,
+          var(--_esp-image-border-default, 2px solid var(--esp-color-border))
+        );
         box-sizing: border-box;
-        border-radius: var(--esp-size-border-radius);
+        border-radius: var(
+          --esp-image-border-radius,
+          var(--_esp-image-radius-default, var(--esp-size-border-radius))
+        );
         overflow: hidden;
         position: relative;
       }
 
-      picture {
-        display: block;
-        height: 100%;
-        width: 100%;
+      :host([banner]) {
+        --_esp-image-border-default: none;
+        --_esp-image-radius-default: 0;
+      }
+
+      [hidden] {
+        display: none !important;
       }
 
+      .frame,
+      .image,
+      picture,
       img {
         display: block;
-        height: 100%;
-        width: 100%;
+        inline-size: 100%;
+        block-size: 100%;
+      }
+
+      .frame {
+        position: relative;
+        overflow: hidden;
+        
+        isolation: isolate;
+        
+        --_esp-image-scrim-resolved: var(
+          --esp-image-scrim-color,
+          var(--_esp-image-scrim-ink, oklch(0.12 0.015 255))
+        );
+        --_esp-image-texture-ink-resolved: var(
+          --esp-image-texture-color,
+          var(--_esp-image-texture-ink, oklch(0.1 0.015 255))
+        );
+        
+        --_esp-image-pitch-resolved: var(
+          --esp-image-texture-scale,
+          var(--_esp-image-texture-pitch, 8px)
+        );
+      }
+      .image {
+        position: relative;
+        z-index: 0;
+      }
+
+      img {
         object-fit: var(--_esp-image-object-fit, cover);
+        object-position: var(
+          --esp-image-object-position,
+          var(--_esp-image-object-position, center)
+        );
+      }
+
+      .banner-layers {
+        display: none;
+      }
+
+      :host([banner]) .banner-layers {
+        
+        
+        --_esp-overlay-image: var(
+          --esp-image-texture-image,
+          var(--_esp-image-registered-image, none)
+        );
+        --_esp-overlay-image-opacity: var(
+          --esp-image-texture-image-opacity,
+          var(--_esp-image-registered-opacity, 1)
+        );
+        --_esp-overlay-image-repeat: var(
+          --esp-image-texture-repeat,
+          var(--_esp-image-registered-repeat, repeat)
+        );
+        --_esp-overlay-image-position: var(
+          --esp-image-texture-position,
+          var(--_esp-image-registered-position, 0 0)
+        );
+        --_esp-overlay-image-size: var(
+          --esp-image-texture-size,
+          var(--_esp-image-registered-size, auto)
+        );
+        --_esp-overlay-image-blend-mode: var(
+          --esp-image-texture-blend-mode,
+          var(--_esp-image-registered-blend-mode, normal)
+        );
+        --_esp-overlay-scrim-opacity: var(
+          --esp-image-scrim-opacity,
+          var(--_esp-image-scrim-opacity, 0.56)
+        );
+        
+        --_esp-overlay-texture-opacity: var(
+          --esp-image-texture-opacity,
+          var(--_esp-image-texture-opacity, 1)
+        );
+        --_esp-overlay-texture-blend-mode: var(
+          --esp-image-texture-blend-mode,
+          var(--_esp-image-texture-blend-mode, normal)
+        );
+        --_esp-overlay-texture-filter: var(--_esp-image-texture-filter, none);
+        display: block;
+      }
+
+      .frame[data-scrim-strength="soft"] {
+        --_esp-image-scrim-opacity: 0.36;
+      }
+      .frame[data-scrim-strength="medium"] {
+        --_esp-image-scrim-opacity: 0.56;
+      }
+      .frame[data-scrim-strength="strong"] {
+        --_esp-image-scrim-opacity: 0.76;
+      }
+
+      .frame[data-scrim="none"] {
+        --_esp-overlay-scrim: none;
+      }
+      .frame[data-scrim="flat"] {
+        --_esp-overlay-scrim: var(--_esp-image-scrim-resolved);
+      }
+      .frame[data-scrim="top"] {
+        --_esp-overlay-scrim: linear-gradient(
+          to bottom,
+          var(--_esp-image-scrim-resolved) 0% 20%,
+          color-mix(in oklch, var(--_esp-image-scrim-resolved) 68%, transparent) 48%,
+          transparent 78%
+        );
+      }
+      .frame[data-scrim="bottom"] {
+        --_esp-overlay-scrim: linear-gradient(
+          to top,
+          var(--_esp-image-scrim-resolved) 0% 20%,
+          color-mix(in oklch, var(--_esp-image-scrim-resolved) 68%, transparent) 48%,
+          transparent 78%
+        );
+      }
+      .frame[data-scrim="left"] {
+        --_esp-overlay-scrim: linear-gradient(
+          to right,
+          var(--_esp-image-scrim-resolved) 0% 20%,
+          color-mix(in oklch, var(--_esp-image-scrim-resolved) 68%, transparent) 48%,
+          transparent 78%
+        );
+      }
+      .frame[data-scrim="right"] {
+        --_esp-overlay-scrim: linear-gradient(
+          to left,
+          var(--_esp-image-scrim-resolved) 0% 20%,
+          color-mix(in oklch, var(--_esp-image-scrim-resolved) 68%, transparent) 48%,
+          transparent 78%
+        );
+      }
+      .frame[data-scrim="radial"] {
+        --_esp-overlay-scrim: radial-gradient(
+          circle at center,
+          var(--_esp-image-scrim-resolved) 0%,
+          color-mix(in oklch, var(--_esp-image-scrim-resolved) 72%, transparent) 34%,
+          color-mix(in oklch, var(--_esp-image-scrim-resolved) 28%, transparent) 64%,
+          transparent 82%
+        );
+      }
+
+      
+      .frame[data-banner-scheme="dark"] {
+        --_esp-image-scrim-ink: oklch(from var(--esp-color-background, oklch(0.98 0 0)) 0.13 c h);
+        --_esp-image-texture-ink: oklch(from var(--esp-color-background, oklch(0.98 0 0)) 0.12 c h);
+        --_esp-image-overlay-ink: oklch(from var(--esp-color-headings, oklch(0.2 0 0)) 0.97 c h);
+        --_esp-image-overlay-text-shadow:
+          0 1px 2px oklch(0.1 0 0 / 0.45), 0 2px 12px oklch(0.1 0 0 / 0.3);
+      }
+      .frame[data-banner-scheme="light"] {
+        --_esp-image-scrim-ink: oklch(from var(--esp-color-background, oklch(0.98 0 0)) 0.97 c h);
+        --_esp-image-texture-ink: oklch(from var(--esp-color-background, oklch(0.98 0 0)) 0.98 c h);
+        --_esp-image-overlay-ink: oklch(from var(--esp-color-headings, oklch(0.2 0 0)) 0.2 c h);
+        --_esp-image-overlay-text-shadow:
+          0 1px 2px oklch(1 0 0 / 0.55), 0 2px 12px oklch(1 0 0 / 0.4);
+      }
+      
+      :host([scheme="light"]) .frame[data-banner-scheme="light"],
+      :host([scheme="dark"]) .frame[data-banner-scheme="dark"] {
+        --_esp-image-scrim-ink: var(--esp-color-background, oklch(0.98 0 0));
+        --_esp-image-texture-ink: var(--esp-color-background, oklch(0.98 0 0));
+        --_esp-image-overlay-ink: var(--esp-color-headings, oklch(0.2 0 0));
+      }
+      
+      .frame[data-banner-scheme="light"][data-texture="halftone"],
+      .frame[data-banner-scheme="light"][data-texture="grunge"] {
+        --_esp-image-texture-blend-mode: screen;
+      }
+
+      .frame[data-texture-scale="fine"] {
+        --_esp-image-texture-pitch: 4px;
+      }
+      .frame[data-texture-scale="medium"] {
+        --_esp-image-texture-pitch: 8px;
+      }
+      .frame[data-texture-scale="coarse"] {
+        --_esp-image-texture-pitch: 14px;
+      }
+      .frame[data-texture="none"] {
+        --_esp-overlay-texture: none;
+      }
+      .frame[data-texture="dots"] {
+        --_esp-overlay-texture: radial-gradient(
+          circle,
+          var(--_esp-image-texture-ink-resolved) 0 calc(var(--_esp-image-pitch-resolved) * 0.17),
+          transparent calc(var(--_esp-image-pitch-resolved) * 0.17 + 0.35px)
+        );
+        --_esp-overlay-texture-size: var(--_esp-image-pitch-resolved)
+          var(--_esp-image-pitch-resolved);
+        --_esp-image-texture-opacity: 0.8;
+        --_esp-image-texture-blend-mode: normal;
+      }
+      .frame[data-texture="halftone"] {
+        --_esp-overlay-texture: radial-gradient(
+          circle,
+          var(--_esp-image-texture-ink-resolved) 0 calc(var(--_esp-image-pitch-resolved) * 0.22),
+          transparent calc(var(--_esp-image-pitch-resolved) * 0.22 + 0.35px)
+        );
+        --_esp-overlay-texture-size: var(--_esp-image-pitch-resolved)
+          var(--_esp-image-pitch-resolved);
+        --_esp-image-texture-opacity: 0.9;
+        --_esp-image-texture-blend-mode: multiply;
+        
+        --_esp-overlay-texture-mask: linear-gradient(to top, black, transparent 82%);
+      }
+      .frame[data-texture="scanlines"] {
+        --_esp-overlay-texture: repeating-linear-gradient(
+          to bottom,
+          var(--_esp-image-texture-ink-resolved) 0 calc(var(--_esp-image-pitch-resolved) * 0.3),
+          transparent calc(var(--_esp-image-pitch-resolved) * 0.3) var(--_esp-image-pitch-resolved)
+        );
+        --_esp-image-texture-opacity: 0.35;
+        --_esp-image-texture-blend-mode: normal;
+      }
+      .frame[data-texture="duotone"] {
+        --_esp-overlay-texture: linear-gradient(
+          135deg,
+          var(
+              --esp-image-duotone-shadow-color,
+              oklch(from var(--esp-color-primary, oklch(0.45 0.1 265)) 0.32 c h)
+            )
+            0% 42%,
+          var(
+              --esp-image-duotone-highlight-color,
+              oklch(from var(--esp-color-complementary, oklch(0.75 0.1 85)) 0.84 c h)
+            )
+            100%
+        );
+        --_esp-image-texture-opacity: 0.9;
+        --_esp-image-texture-blend-mode: color;
+      }
+      
+      .frame[data-texture="paper"] {
+        --_esp-overlay-texture: linear-gradient(oklch(1 0 0), oklch(1 0 0));
+        --_esp-image-texture-opacity: 0.9;
+        --_esp-image-texture-blend-mode: overlay;
+      }
+      .frame[data-texture="grain"] {
+        --_esp-overlay-texture: linear-gradient(oklch(1 0 0), oklch(1 0 0));
+        --_esp-image-texture-opacity: 0.72;
+        --_esp-image-texture-blend-mode: overlay;
+      }
+      .frame[data-texture="grunge"] {
+        --_esp-overlay-texture: linear-gradient(oklch(1 0 0), oklch(1 0 0));
+        --_esp-image-texture-opacity: 0.42;
+        --_esp-image-texture-blend-mode: multiply;
+      }
+
+      .frame[data-texture="halftone"][data-scrim="top"] {
+        --_esp-overlay-texture-mask: linear-gradient(to bottom, black, transparent 82%);
+      }
+      .frame[data-texture="halftone"][data-scrim="bottom"] {
+        --_esp-overlay-texture-mask: linear-gradient(to top, black, transparent 82%);
+      }
+      .frame[data-texture="halftone"][data-scrim="left"] {
+        --_esp-overlay-texture-mask: linear-gradient(to right, black, transparent 82%);
+      }
+      .frame[data-texture="halftone"][data-scrim="right"] {
+        --_esp-overlay-texture-mask: linear-gradient(to left, black, transparent 82%);
+      }
+      .frame[data-texture="halftone"][data-scrim="radial"] {
+        --_esp-overlay-texture-mask: radial-gradient(circle at center, black, transparent 82%);
+      }
+
+      .overlay {
+        position: absolute;
+        z-index: 2;
+        inset: 0;
+        display: flex;
+        align-items: flex-end;
+        justify-content: flex-start;
+        padding: var(--esp-image-overlay-padding, var(--esp-size-padding-page));
+        color: var(--esp-image-overlay-color, var(--_esp-image-overlay-ink, white));
+        
+        text-shadow: var(
+          --esp-image-overlay-text-shadow,
+          var(--_esp-image-overlay-text-shadow, none)
+        );
+        pointer-events: none;
+      }
+      .overlay slot::slotted(*) {
+        color: inherit !important;
+        pointer-events: auto;
+      }
+      .frame[data-content-position="bottom"] .overlay {
+        justify-content: center;
+        text-align: center;
+      }
+      .frame[data-content-position="bottom-end"] .overlay {
+        justify-content: flex-end;
+        text-align: end;
+      }
+      .frame[data-content-position="center"] .overlay {
+        align-items: center;
+        justify-content: center;
+        text-align: center;
+      }
+      .frame[data-content-position="top-start"] .overlay {
+        align-items: flex-start;
+      }
+      .frame[data-content-position="top"] .overlay {
+        align-items: flex-start;
+        justify-content: center;
+        text-align: center;
+      }
+      .frame[data-content-position="top-end"] .overlay {
+        align-items: flex-start;
+        justify-content: flex-end;
+        text-align: end;
+      }
+
+      .compact-sentinel {
+        position: absolute;
+        inline-size: var(--esp-image-compact-width, 40rem);
+        block-size: 0;
+        visibility: hidden;
+        pointer-events: none;
+      }
+
+      @media (forced-colors: active) {
+        :host([banner]) .banner-layers {
+          display: none;
+        }
+        .overlay {
+          background: Canvas;
+          color: CanvasText;
+        }
+      }
+
+      @media (prefers-reduced-transparency: reduce) {
+        :host([banner]) .banner-layers {
+          --_esp-overlay-scrim-opacity: max(0.82, var(--esp-image-scrim-opacity, 0.82));
+        }
+        .esp-visual-overlay__texture,
+        .esp-visual-overlay__image {
+          display: none;
+        }
+      }
+
+      @media print {
+        :host([banner]) .banner-layers {
+          display: none;
+        }
+        
+        .overlay {
+          background: white;
+          color: black;
+        }
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        .banner-layers,
+        .overlay {
+          animation: none !important;
+          transition: none !important;
+        }
       }
-    `],a([l({attribute:"original-height",type:Number})],n.prototype,"originalHeight",void 0),a([l({attribute:"original-width",type:Number})],n.prototype,"originalWidth",void 0),a([l({attribute:"low-res",type:String})],n.prototype,"imageUrl",void 0),a([l({attribute:"local-image",type:String})],n.prototype,"localImage",void 0),a([l({type:String})],n.prototype,"caption",void 0),a([l({attribute:"sizes",type:String})],n.prototype,"sizes",void 0),a([l({attribute:"loading",type:String})],n.prototype,"loading",void 0),a([b()],n.prototype,"renderedWidth",void 0),n=d=a([y("esp-image")],n);export{n as EspalierImage};
+    `,I],n([l({attribute:"original-height",type:Number})],a.prototype,"originalHeight",void 0),n([l({attribute:"original-width",type:Number})],a.prototype,"originalWidth",void 0),n([l({attribute:"low-res",type:String})],a.prototype,"imageUrl",void 0),n([l({attribute:"local-image",type:String})],a.prototype,"localImage",void 0),n([l({type:String})],a.prototype,"caption",void 0),n([l({attribute:"sizes",type:String})],a.prototype,"sizes",void 0),n([l({attribute:"loading",type:String})],a.prototype,"loading",void 0),n([l({type:Boolean,reflect:!0})],a.prototype,"banner",void 0),n([l({attribute:"banner-scheme",converter:h(z,"auto"),reflect:!0})],a.prototype,"bannerScheme",void 0),n([l({converter:h(k,"auto"),reflect:!0})],a.prototype,"scrim",void 0),n([l({attribute:"scrim-strength",converter:h(S,"medium"),reflect:!0})],a.prototype,"scrimStrength",void 0),n([l({type:String,reflect:!0})],a.prototype,"texture",void 0),n([l({attribute:"texture-scale",converter:h(w,"medium"),reflect:!0})],a.prototype,"textureScale",void 0),n([l({attribute:"content-position",converter:h(j,"bottom-start"),reflect:!0})],a.prototype,"contentPosition",void 0),n([l({attribute:"focus",converter:E,reflect:!0})],a.prototype,"focusPoint",void 0),n([l({type:String})],a.prototype,"ratio",void 0),n([l({attribute:"compact-ratio",type:String})],a.prototype,"compactRatio",void 0),n([u()],a.prototype,"renderedWidth",void 0),n([u()],a.prototype,"compact",void 0),n([u()],a.prototype,"overlayHasContent",void 0),a=m=n([P("esp-image")],a);export{a as EspalierImage,C as parseImageRatio};

package/dist/image/image-focus.d.ts

@@ -0,0 +1,16 @@
+import type { ComplexAttributeConverter } from "lit";
+/** A normalized point within an image, from its top-left corner. */
+export interface FocusPoint {
+    x: number;
+    y: number;
+}
+export declare const CENTER_FOCUS: Readonly<FocusPoint>;
+/** Return a safe copy of a normalized focus value, or center when invalid. */
+export declare function normalizeFocus(value: unknown): FocusPoint;
+/** Parse the public `"x y"` attribute grammar. */
+export declare function parseFocus(value: string | null): FocusPoint;
+/** Serialize a focus value for HTML without losing round-trip precision. */
+export declare function serializeFocus(value: FocusPoint): string;
+export declare const focusConverter: ComplexAttributeConverter<FocusPoint>;
+/** Clamp an authoring value to the normalized focus range. */
+export declare function clampFocus(value: FocusPoint): FocusPoint;

package/dist/image/image-focus.js

@@ -0,0 +1 @@
+const n=Object.freeze({x:.5,y:.5});function o(t){return typeof t=="number"&&Number.isFinite(t)&&t>=0&&t<=1}function c(t){return typeof t=="object"&&t!==null&&"x"in t&&"y"in t&&o(t.x)&&o(t.y)?{x:t.x,y:t.y}:{...n}}function s(t){if(!t)return{...n};const r=t.trim().split(/\s+/);if(r.length!==2)return{...n};const[i,e]=r.map(Number);return o(i)&&o(e)?{x:i,y:e}:{...n}}function x(t){const r=c(t);return`${r.x} ${r.y}`}const m={fromAttribute:s,toAttribute(t){return x(t)}};function p(t){const r=i=>Math.min(1,Math.max(0,i));return{x:Number.isFinite(t.x)?r(t.x):n.x,y:Number.isFinite(t.y)?r(t.y):n.y}}export{n as CENTER_FOCUS,p as clampFocus,m as focusConverter,c as normalizeFocus,s as parseFocus,x as serializeFocus};

package/dist/image/image-texture-filters.js

@@ -0,0 +1 @@
+const p="data-esp-image-texture-filters",l=[{id:"paper-fine",baseFrequency:"0.016",octaves:6,post:"paper",contrast:2.6},{id:"paper-medium",baseFrequency:"0.011",octaves:6,post:"paper",contrast:2.6},{id:"paper-coarse",baseFrequency:"0.007",octaves:6,post:"paper",contrast:2.6},{id:"grain-fine",baseFrequency:"0.65",octaves:1,post:"grain",contrast:1.7},{id:"grain-medium",baseFrequency:"0.5",octaves:1,post:"grain",contrast:1.7},{id:"grain-coarse",baseFrequency:"0.38",octaves:1,post:"grain",contrast:1.7},{id:"grunge-fine",baseFrequency:"0.14",octaves:2,post:"grunge",markLightness:0},{id:"grunge-medium",baseFrequency:"0.09",octaves:3,post:"grunge",markLightness:0},{id:"grunge-coarse",baseFrequency:"0.05",octaves:4,post:"grunge",markLightness:0},{id:"grunge-light-fine",baseFrequency:"0.14",octaves:2,post:"grunge",markLightness:1},{id:"grunge-light-medium",baseFrequency:"0.09",octaves:3,post:"grunge",markLightness:1},{id:"grunge-light-coarse",baseFrequency:"0.05",octaves:4,post:"grunge",markLightness:1}];function m(e){return e.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&"host"in e?e:e.nodeType===Node.DOCUMENT_NODE?e.body:e.ownerDocument?.body??document.body}function h(e){const o=m(e);if(o.querySelector(`svg[${p}]`))return;const g="http://www.w3.org/2000/svg",d=o.ownerDocument,t=(n,r)=>{const s=d.createElementNS(g,n);for(const[a,i]of Object.entries(r))s.setAttribute(a,i);return s},c=t("svg",{[p]:"","aria-hidden":"true",width:"0",height:"0"});c.setAttribute("style","position:absolute;inline-size:0;block-size:0;overflow:hidden");const u=t("defs",{});for(const n of l){const r=t("filter",{id:`esp-image-texture-${n.id}`,x:"-10%",y:"-10%",width:"120%",height:"120%"});if(r.append(t("feTurbulence",{type:"fractalNoise",baseFrequency:n.baseFrequency,numOctaves:String(n.octaves),seed:"17",stitchTiles:"stitch",result:"noise"})),n.post==="grunge"){const s=n.markLightness??0;r.append(t("feColorMatrix",{in:"noise",type:"matrix",values:`0 0 0 0 ${s}  0 0 0 0 ${s}  0 0 0 0 ${s}  0 0 0 -1.4 0.95`,result:"thresholded"}));const a=t("feComponentTransfer",{in:"thresholded"});a.append(t("feFuncA",{type:"discrete",tableValues:"0 0 0 1 1"})),r.append(a)}else if(r.append(t("feColorMatrix",{in:"noise",type:"saturate",values:"0",result:"mono"})),n.contrast){const s=n.contrast,a=(1-s)/2,i=t("feComponentTransfer",{in:"mono"});for(const f of["feFuncR","feFuncG","feFuncB"])i.append(t(f,{type:"linear",slope:String(s),intercept:String(a)}));r.append(i)}u.append(r)}c.append(u),o.append(c)}function y(e,o){return`esp-image-texture-${e}-${o}`}export{h as ensureImageTextureFilters,y as imageTextureFilterId};

package/dist/index.d.ts

@@ -25,9 +25,11 @@ export * from "./empty-state/esp-empty-state.js";
 export * from "./image-upload/esp-image-upload.js";
 export * from "./file-upload/esp-file-upload.js";
 export * from "./font-picker/esp-font-picker.js";
+export * from "./focus-picker/esp-focus-picker.js";
 export * from "./footer/index.js";
 export * from "./grid/esp-grid.js";
 export * from "./image/esp-image.js";
+export * from "./image/image-focus.js";
 export * from "./lightbox/esp-lightbox.js";
 export * from "./info/esp-info.js";
 export * from "./input/esp-input.js";

package/dist/index.js

@@ -1 +1 @@
-export*from"./box/esp-box.js";export*from"./action-menu/esp-action-menu.js";export*from"./action-menu/esp-action-menu-item.js";export*from"./avatar/esp-avatar.js";export*from"./avatar/esp-profile-chip.js";export*from"./badge/esp-badge.js";export*from"./checkbox/esp-checkbox.js";export*from"./checkbox/esp-checkbox-group.js";export*from"./data-cell/esp-data-cell.js";export*from"./radio-button/esp-radio-button.js";export*from"./radio-button/esp-radio-button-group.js";export*from"./repeater/esp-repeater.js";export*from"./breadcrumbs/esp-breadcrumbs.js";export*from"./button/esp-button.js";export*from"./button/esp-button-group.js";export*from"./color-picker/esp-color-picker.js";export*from"./flyout/esp-flyout.js";export*from"./form/esp-form.js";export*from"./form-item/esp-form-item.js";export*from"./header/index.js";export*from"./page/esp-page.js";export*from"./popover/esp-popover.js";export*from"./dialog/esp-dialog.js";export*from"./empty-state/esp-empty-state.js";export*from"./image-upload/esp-image-upload.js";export*from"./file-upload/esp-file-upload.js";export*from"./font-picker/esp-font-picker.js";export*from"./footer/index.js";export*from"./grid/esp-grid.js";export*from"./image/esp-image.js";export*from"./lightbox/esp-lightbox.js";export*from"./info/esp-info.js";export*from"./input/esp-input.js";export*from"./textarea/esp-textarea.js";export*from"./pickers/esp-pick-one.js";export*from"./pickers/esp-pick-some.js";export*from"./pickers/esp-picker-menu.js";export*from"./pickers/esp-picker-item.js";export*from"./root/esp-root.js";export*from"./menu/index.js";export*from"./burger/esp-burger.js";export*from"./date-picker/esp-date-picker.js";export*from"./details/esp-details.js";export*from"./details/esp-details-group.js";export*from"./tabs/esp-tab.js";export*from"./tabs/esp-tab-group.js";export*from"./slider/esp-slider.js";export*from"./switch/esp-switch.js";export*from"./toaster/esp-toaster.js";export*from"./tooltip/esp-tooltip.js";export*from"./progress/esp-progress.js";export*from"./search/esp-search.js";export*from"./status-indicator/esp-status-indicator.js";export*from"./tree/esp-tree.js";export*from"./tree/esp-tree-item.js";import{DEFAULT_ICON_SPRITE_URL as to,DEFAULT_ICON_VIEW_BOX as mo,INTENT_VARIANTS as po,normalizeIntentVariant as fo,getIconHref as xo,getIconHrefForHost as ao,getIconSpriteUrl as lo}from"./shared/intent-values.js";import{EspalierElementBase as To}from"./shared/esp-element-base.js";import{VALIDITY_CHANGED_EVENT as io}from"./shared/validation.js";import{FormFieldController as Io}from"./shared/form-field-controller.js";import{traverseToClosest as ho}from"./shared/utilities.js";import{showToast as Fo}from"./shared/toast-events.js";import{showFlyout as Ao,closeFlyout as Lo}from"./shared/flyout-events.js";import{getEspBus as uo}from"./shared/bus-events.js";export*from"./shared/events.js";import{getImageDetails as So,releasePreviewUrl as bo}from"./image-upload/image-helpers.js";import{calculatePhotoLayout as Co}from"./shared/justified-layout.js";import{encodeTheme as Vo,parseTheme as Wo,mergePartials as Bo,layerThemes as Po,buildTaprootLightTheme as vo,buildTaprootDarkTheme as wo,NESTED_THEME_KEYS as Go}from"./shared/theme.js";import{WEIGHT_LABELS as Ro,extractWeights as ko,normalizeWeight as zo,bestAvailableWeight as Yo,extractFamily as Ko,getFallbackFont as Mo}from"./shared/font-helpers.js";import{getGoogleFonts as jo}from"./font-picker/esp-font-picker.js";export{to as DEFAULT_ICON_SPRITE_URL,mo as DEFAULT_ICON_VIEW_BOX,To as EspalierElementBase,Io as FormFieldController,po as INTENT_VARIANTS,Go as NESTED_THEME_KEYS,io as VALIDITY_CHANGED_EVENT,Ro as WEIGHT_LABELS,Yo as bestAvailableWeight,wo as buildTaprootDarkTheme,vo as buildTaprootLightTheme,Co as calculatePhotoLayout,Lo as closeFlyout,Vo as encodeTheme,Ko as extractFamily,ko as extractWeights,uo as getEspBus,Mo as getFallbackFont,jo as getGoogleFonts,xo as getIconHref,ao as getIconHrefForHost,lo as getIconSpriteUrl,So as getImageDetails,Po as layerThemes,Bo as mergePartials,fo as normalizeIntentVariant,zo as normalizeWeight,Wo as parseTheme,bo as releasePreviewUrl,Ao as showFlyout,Fo as showToast,ho as traverseToClosest};
+export*from"./box/esp-box.js";export*from"./action-menu/esp-action-menu.js";export*from"./action-menu/esp-action-menu-item.js";export*from"./avatar/esp-avatar.js";export*from"./avatar/esp-profile-chip.js";export*from"./badge/esp-badge.js";export*from"./checkbox/esp-checkbox.js";export*from"./checkbox/esp-checkbox-group.js";export*from"./data-cell/esp-data-cell.js";export*from"./radio-button/esp-radio-button.js";export*from"./radio-button/esp-radio-button-group.js";export*from"./repeater/esp-repeater.js";export*from"./breadcrumbs/esp-breadcrumbs.js";export*from"./button/esp-button.js";export*from"./button/esp-button-group.js";export*from"./color-picker/esp-color-picker.js";export*from"./flyout/esp-flyout.js";export*from"./form/esp-form.js";export*from"./form-item/esp-form-item.js";export*from"./header/index.js";export*from"./page/esp-page.js";export*from"./popover/esp-popover.js";export*from"./dialog/esp-dialog.js";export*from"./empty-state/esp-empty-state.js";export*from"./image-upload/esp-image-upload.js";export*from"./file-upload/esp-file-upload.js";export*from"./font-picker/esp-font-picker.js";export*from"./focus-picker/esp-focus-picker.js";export*from"./footer/index.js";export*from"./grid/esp-grid.js";export*from"./image/esp-image.js";export*from"./image/image-focus.js";export*from"./lightbox/esp-lightbox.js";export*from"./info/esp-info.js";export*from"./input/esp-input.js";export*from"./textarea/esp-textarea.js";export*from"./pickers/esp-pick-one.js";export*from"./pickers/esp-pick-some.js";export*from"./pickers/esp-picker-menu.js";export*from"./pickers/esp-picker-item.js";export*from"./root/esp-root.js";export*from"./menu/index.js";export*from"./burger/esp-burger.js";export*from"./date-picker/esp-date-picker.js";export*from"./details/esp-details.js";export*from"./details/esp-details-group.js";export*from"./tabs/esp-tab.js";export*from"./tabs/esp-tab-group.js";export*from"./slider/esp-slider.js";export*from"./switch/esp-switch.js";export*from"./toaster/esp-toaster.js";export*from"./tooltip/esp-tooltip.js";export*from"./progress/esp-progress.js";export*from"./search/esp-search.js";export*from"./status-indicator/esp-status-indicator.js";export*from"./tree/esp-tree.js";export*from"./tree/esp-tree-item.js";import{DEFAULT_ICON_SPRITE_URL as po,DEFAULT_ICON_VIEW_BOX as fo,INTENT_VARIANTS as xo,normalizeIntentVariant as ao,getIconHref as lo,getIconHrefForHost as so,getIconSpriteUrl as To}from"./shared/intent-values.js";import{EspalierElementBase as io}from"./shared/esp-element-base.js";import{VALIDITY_CHANGED_EVENT as Io}from"./shared/validation.js";import{FormFieldController as ho}from"./shared/form-field-controller.js";import{traverseToClosest as Fo}from"./shared/utilities.js";import{showToast as Ao}from"./shared/toast-events.js";import{showFlyout as No,closeFlyout as uo}from"./shared/flyout-events.js";import{getEspBus as Ho}from"./shared/bus-events.js";export*from"./shared/events.js";import{getImageDetails as yo,releasePreviewUrl as Co}from"./image-upload/image-helpers.js";import{calculatePhotoLayout as Vo}from"./shared/justified-layout.js";import{encodeTheme as Bo,parseTheme as Po,mergePartials as vo,layerThemes as wo,buildTaprootLightTheme as Go,buildTaprootDarkTheme as Oo,NESTED_THEME_KEYS as Ro}from"./shared/theme.js";import{WEIGHT_LABELS as zo,extractWeights as Yo,normalizeWeight as Ko,bestAvailableWeight as Mo,extractFamily as Xo,getFallbackFont as jo}from"./shared/font-helpers.js";import{getGoogleFonts as Jo}from"./font-picker/esp-font-picker.js";export{po as DEFAULT_ICON_SPRITE_URL,fo as DEFAULT_ICON_VIEW_BOX,io as EspalierElementBase,ho as FormFieldController,xo as INTENT_VARIANTS,Ro as NESTED_THEME_KEYS,Io as VALIDITY_CHANGED_EVENT,zo as WEIGHT_LABELS,Mo as bestAvailableWeight,Oo as buildTaprootDarkTheme,Go as buildTaprootLightTheme,Vo as calculatePhotoLayout,uo as closeFlyout,Bo as encodeTheme,Xo as extractFamily,Yo as extractWeights,Ho as getEspBus,jo as getFallbackFont,Jo as getGoogleFonts,lo as getIconHref,so as getIconHrefForHost,To as getIconSpriteUrl,yo as getImageDetails,wo as layerThemes,vo as mergePartials,ao as normalizeIntentVariant,Ko as normalizeWeight,Po as parseTheme,Co as releasePreviewUrl,No as showFlyout,Ao as showToast,Fo as traverseToClosest};

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

@@ -1,7 +1,10 @@
 import { LitElement, type PropertyValues } from "lit";
-import { type SeedColorRoot } from "../shared/bus-events.js";
+import { type SchemeEvents, type SeedColorRoot } from "../shared/bus-events.js";
 import { type EspalierTheme } from "../shared/theme.js";
+import { type ImageTextureDefinition } from "../shared/image-texture-registry.js";
+export { registerImageTexture, registeredImageTextures, BUILT_IN_IMAGE_TEXTURES, type ImageTextureDefinition, } from "../shared/image-texture-registry.js";
 export type GoogleFontLoadingPolicy = "auto" | "none";
+export type { SchemeEvents } from "../shared/bus-events.js";
 /**
  * Root container for the Espalier design system.
  *
@@ -26,6 +29,38 @@ export type GoogleFontLoadingPolicy = "auto" | "none";
  * </esp-root>
  * ```
  *
+ * ### Nested theme previews and scoped events
+ *
+ * A nested root creates a scoped theme for its descendants. It does not create
+ * a separate event bus: every root publishes theme changes through the same
+ * Espalier singleton. Subscribe through the root whose changes you own so a
+ * nested preview cannot be mistaken for an application-level theme change.
+ *
+ * ```ts
+ * const applicationRoot = document.querySelector<EspalierRoot>("#application-theme")!;
+ *
+ * const unsubscribe = applicationRoot.subscribeScoped("scheme-changed", ({ scheme }) => {
+ *   localStorage.setItem("scheme", scheme);
+ * });
+ *
+ * // Initial state is read directly; scoped events report later changes only.
+ * renderScheme(applicationRoot.scheme);
+ *
+ * // Call when the owning integration is disposed.
+ * unsubscribe();
+ * ```
+ *
+ * This contract covers `scheme-changed`, `seed-color-changed`,
+ * `theme-changed`, and `icon-sprite-url-changed`. Components derived from
+ * `EspalierElementBase` use the same closest-root filter internally.
+ *
+ * The root also owns the application's banner-texture vocabulary:
+ * `EspalierRoot.registerTexture(name, definition)` registers an
+ * image-backed texture preset that any
+ * [esp-image](/components/image) banner in the application selects with
+ * `texture="<name>"`, and `EspalierRoot.registeredTextures()` enumerates
+ * the presets for building texture pickers.
+ *
  * @customElement esp-root
  * @slot - Place Espalier components and content here.
  *
@@ -38,8 +73,30 @@ export type GoogleFontLoadingPolicy = "auto" | "none";
  *
  */
 export declare class EspalierRoot extends LitElement implements SeedColorRoot {
+    /**
+     * Register (or replace) a named, image-backed banner-texture preset.
+     * Any `esp-image` banner under a root selects it with `texture="<name>"`;
+     * banners already pointing at the name re-render, so registration at
+     * mount and markup order never race. Static delegate to
+     * `registerImageTexture` so script-only contexts (docs demos, published
+     * sites) can reach it from the root element without module imports.
+     */
+    static registerTexture(name: string, definition: ImageTextureDefinition): void;
+    /** Snapshot of the registered texture presets, for building pickers. */
+    static registeredTextures(): Map<string, Readonly<ImageTextureDefinition>>;
     /** Unique ID for correlating bus events across multiple roots. */
     correlationId: `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * Subscribe to a theme event published by this root only.
+     *
+     * All roots share Espalier's global bus. This method filters foreign and
+     * nested-root payloads by `correlationId` and returns a cleanup function.
+     * It reports changes after mount; read initial state from this root.
+     *
+     * @param event Root-scoped theme event to observe.
+     * @param handler Callback invoked with that event's typed payload.
+     */
+    subscribeScoped<K extends keyof SchemeEvents>(event: K, handler: (payload: SchemeEvents[K]) => void): () => void;
     /**
      * Base64-encoded JSON partial theme for the **light** scheme.
      *
@@ -178,6 +235,7 @@ export declare class EspalierRoot extends LitElement implements SeedColorRoot {
     get seedColor(): string;
     /** Returns the resolved theme for the active scheme. */
     get activeTheme(): EspalierTheme;
+    connectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(): void;
     protected updated(changedProperties: PropertyValues): void;