@taprootio/espalier 2.6.0 → 2.7.1

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

@@ -1,6 +1,8 @@
 import { LitElement, type PropertyValues } from "lit";
 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";
 /**
@@ -52,6 +54,13 @@ export type { SchemeEvents } from "../shared/bus-events.js";
  * `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.
  *
@@ -64,6 +73,17 @@ export type { SchemeEvents } from "../shared/bus-events.js";
  *
  */
 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}`;
     /**

package/dist/root/esp-root.js

@@ -1,4 +1,4 @@
-var l=function(c,e,t,s){var h=arguments.length,o=h<3?e:s===null?s=Object.getOwnPropertyDescriptor(e,t):s,r;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(c,e,t,s);else for(var d=c.length-1;d>=0;d--)(r=c[d])&&(o=(h<3?r(o):h>3?r(e,t,o):r(e,t))||o);return h>3&&o&&Object.defineProperty(e,t,o),o},n;import{css as k,html as b,LitElement as C}from"lit";import{customElement as E,property as a}from"lit/decorators.js";import{getEspBus as p}from"../shared/bus-events.js";import{subscribeToRootEvent as T}from"../shared/root-event-subscription.js";import{DEFAULT_LIGHT_THEME as f,DEFAULT_DARK_THEME as g,parseTheme as y,mergeTheme as v}from"../shared/theme.js";import{computeThemeProperties as x}from"./helpers/compute-theme-properties.js";let i=n=class extends C{constructor(){super(...arguments),this.schemeBacker="",this.schemeExplicitlySet=!1,this.resolvingDefaultScheme=!1,this.themeEventsReady=!1,this.systemSchemeQuery=null,this.lastSeedColor="",this.resolvedLightTheme={...f},this.resolvedDarkTheme={...g},this.documentClickRegistrationActive=!1,this.correlationId=globalThis.crypto?.randomUUID?.()??Math.random().toString(36),this.lightThemeAttr="",this.darkThemeAttr="",this.fontCSSRoot="/css/fonts/",this.fontDefinitionsUrl="",this.googleFontLoading="auto",this.iconSpriteUrl="/assets/icons.svg",this.defaultScheme="light",this.resizeObserver=new ResizeObserver(()=>{p().publish("window-resized",{emWidth:window.innerWidth/parseFloat(getComputedStyle(document.documentElement).fontSize),emHeight:window.innerHeight/parseFloat(getComputedStyle(document.documentElement).fontSize),pxWidth:window.innerWidth,pxHeight:window.innerHeight})}),this.handleSystemSchemeChange=e=>{this.schemeExplicitlySet||this.defaultScheme!=="system"||(this.resolvingDefaultScheme=!0,this.scheme=e.matches?"dark":"light",this.resolvingDefaultScheme=!1)}}subscribeScoped(e,t){return T(this,e,t)}get scheme(){return this.schemeBacker}set scheme(e){const t=e==="dark"?"dark":e==="light"?"light":"",s=this.schemeBacker,h=this.schemeExplicitlySet;this.resolvingDefaultScheme||(this.schemeExplicitlySet=t.length>0);const o=t||this.resolveDefaultScheme();h!==this.schemeExplicitlySet&&this.isConnected&&this.syncSystemSchemeListener(),o!==s&&(this.schemeBacker=o,this.requestUpdate("scheme",s),this.themeEventsReady&&p().publish("scheme-changed",{scheme:o,correlationId:this.correlationId}))}get seedColor(){return this.activeTheme.seedColor}static extractFamily(e){if(!e)return"";const t=e.match(/^"([^"]+)"|^'([^']+)'/);return t&&(t[1]||t[2])||""}injectGoogleFontLink(e,t,s){const h="data-esp-font",o=`${this.correlationId}-${e}`,r=document.head.querySelector(`link[${h}="${o}"]`);if(this.googleFontLoading==="none"){r?.remove();return}if(r&&t&&r.dataset.espFamily===t&&r.dataset.espWeight===(s??"")||(r?.remove(),!t))return;const d=encodeURIComponent(t),u=s==="bold"?"700":s==="normal"?"400":s,S=u&&u!=="400"?`:wght@${u}`:"",m=document.createElement("link");m.rel="stylesheet",m.href=`https://fonts.googleapis.com/css2?family=${d}${S}&display=swap`,m.setAttribute(h,o),m.dataset.espFamily=t,m.dataset.espWeight=s??"",document.head.appendChild(m)}syncGoogleFontLinks(){this.googleFontLoading==="none"&&this.removeRuntimeGoogleFontLinks();const e=this.activeTheme;this.injectGoogleFontLink("body",n.extractFamily(e.fontBody),e.fontWeightBody),this.injectGoogleFontLink("headings",n.extractFamily(e.fontHeadings),e.fontWeightHeadings),this.injectGoogleFontLink("brand",n.extractFamily(e.fontBrand),e.fontWeightBrand),this.injectGoogleFontLink("monospace",n.extractFamily(e.fontMonospace),e.fontWeightMonospace)}removeRuntimeGoogleFontLinks(){for(const e of document.head.querySelectorAll(`link[data-esp-font^="${this.correlationId}-"]`))e.remove();for(const e of document.head.querySelectorAll(`link[data-esp-font-picker-root="${CSS.escape(this.correlationId)}"]`))e.remove()}get activeTheme(){return this.scheme==="dark"?this.resolvedDarkTheme:this.resolvedLightTheme}resolveThemes(){const e=this.lightThemeAttr?y(this.lightThemeAttr):null;this.resolvedLightTheme=e?v(f,e):{...f};const t=this.darkThemeAttr?y(this.darkThemeAttr):null;this.resolvedDarkTheme=t?v(g,t):{...g}}connectedCallback(){super.connectedCallback(),this.registerDocumentClickBridge(),this.resizeObserver.observe(this),this.hasUpdated&&(this.applyDefaultScheme(),this.syncGoogleFontLinks())}willUpdate(e){const t=["lightThemeAttr","darkThemeAttr"];(!this.lastSeedColor||t.some(r=>e.has(r)))&&(this.resolveThemes(),this.themeEventsReady&&p().publish("theme-changed",{correlationId:this.correlationId}));const h=x(this.activeTheme,this.scheme==="dark"?"dark":"light");for(const[r,d]of Object.entries(h))this.style.setProperty(r,d);const o=this.activeTheme.seedColor;this.themeEventsReady&&this.lastSeedColor&&this.lastSeedColor!==o&&p().publish("seed-color-changed",{seedColor:o,correlationId:this.correlationId}),this.lastSeedColor=o,this.themeEventsReady&&e.has("iconSpriteUrl")&&p().publish("icon-sprite-url-changed",{iconSpriteUrl:this.iconSpriteUrl,correlationId:this.correlationId}),this.syncGoogleFontLinks()}firstUpdated(){const e=this.activeTheme.stylesheets;if(e.length)for(const t of e){const s=document.createElement("link");s.rel="stylesheet",s.href=t,document.head.appendChild(s)}if(!document.getElementById("esp-root-base-styles")){const t=document.createElement("style");t.id="esp-root-base-styles",t.textContent=n.lightDomStyles,document.head.appendChild(t)}this.applyDefaultScheme(),this.lastSeedColor=this.activeTheme.seedColor,this.themeEventsReady=!0}updated(e){(e.has("defaultScheme")||e.has("scheme"))&&!this.schemeExplicitlySet&&this.applyDefaultScheme()}disconnectedCallback(){this.unregisterDocumentClickBridge(),this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null,this.resizeObserver.disconnect(),this.removeRuntimeGoogleFontLinks(),super.disconnectedCallback()}registerDocumentClickBridge(){this.documentClickRegistrationActive||(this.documentClickRegistrationActive=!0,n.connectedRootCount+=1,n.connectedRootCount===1&&document.addEventListener("click",n.handleDocumentClick))}unregisterDocumentClickBridge(){this.documentClickRegistrationActive&&(this.documentClickRegistrationActive=!1,n.connectedRootCount=Math.max(0,n.connectedRootCount-1),n.connectedRootCount===0&&document.removeEventListener("click",n.handleDocumentClick))}applyDefaultScheme(){this.schemeExplicitlySet||(this.resolvingDefaultScheme=!0,this.scheme=this.resolveDefaultScheme(),this.resolvingDefaultScheme=!1,this.syncSystemSchemeListener())}resolveDefaultScheme(){return this.defaultScheme==="dark"||this.defaultScheme==="system"&&window.matchMedia?.("(prefers-color-scheme: dark)").matches?"dark":"light"}syncSystemSchemeListener(){if(this.schemeExplicitlySet||this.defaultScheme!=="system"||!window.matchMedia){this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null;return}this.systemSchemeQuery||(this.systemSchemeQuery=window.matchMedia("(prefers-color-scheme: dark)"),this.systemSchemeQuery.addEventListener("change",this.handleSystemSchemeChange))}render(){return b`<slot></slot>`}};i.connectedRootCount=0,i.handleDocumentClick=c=>{const e=c.composedPath().filter(t=>t instanceof HTMLElement&&t.tagName==="ESP-POPOVER");p().publish("close-popovers",{source:c.target??void 0,skipPopovers:e})},i.lightDomStyles=`
+var l=function(c,e,t,s){var h=arguments.length,o=h<3?e:s===null?s=Object.getOwnPropertyDescriptor(e,t):s,r;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(c,e,t,s);else for(var d=c.length-1;d>=0;d--)(r=c[d])&&(o=(h<3?r(o):h>3?r(e,t,o):r(e,t))||o);return h>3&&o&&Object.defineProperty(e,t,o),o},n;import{css as k,html as b,LitElement as C}from"lit";import{customElement as E,property as a}from"lit/decorators.js";import{getEspBus as p}from"../shared/bus-events.js";import{subscribeToRootEvent as T}from"../shared/root-event-subscription.js";import{DEFAULT_LIGHT_THEME as g,DEFAULT_DARK_THEME as f,parseTheme as y,mergeTheme as v}from"../shared/theme.js";import{computeThemeProperties as x}from"./helpers/compute-theme-properties.js";import{registerImageTexture as R,registeredImageTextures as L}from"../shared/image-texture-registry.js";import{registerImageTexture as H,registeredImageTextures as M,BUILT_IN_IMAGE_TEXTURES as P}from"../shared/image-texture-registry.js";let i=n=class extends C{constructor(){super(...arguments),this.schemeBacker="",this.schemeExplicitlySet=!1,this.resolvingDefaultScheme=!1,this.themeEventsReady=!1,this.systemSchemeQuery=null,this.lastSeedColor="",this.resolvedLightTheme={...g},this.resolvedDarkTheme={...f},this.documentClickRegistrationActive=!1,this.correlationId=globalThis.crypto?.randomUUID?.()??Math.random().toString(36),this.lightThemeAttr="",this.darkThemeAttr="",this.fontCSSRoot="/css/fonts/",this.fontDefinitionsUrl="",this.googleFontLoading="auto",this.iconSpriteUrl="/assets/icons.svg",this.defaultScheme="light",this.resizeObserver=new ResizeObserver(()=>{p().publish("window-resized",{emWidth:window.innerWidth/parseFloat(getComputedStyle(document.documentElement).fontSize),emHeight:window.innerHeight/parseFloat(getComputedStyle(document.documentElement).fontSize),pxWidth:window.innerWidth,pxHeight:window.innerHeight})}),this.handleSystemSchemeChange=e=>{this.schemeExplicitlySet||this.defaultScheme!=="system"||(this.resolvingDefaultScheme=!0,this.scheme=e.matches?"dark":"light",this.resolvingDefaultScheme=!1)}}static registerTexture(e,t){R(e,t)}static registeredTextures(){return L()}subscribeScoped(e,t){return T(this,e,t)}get scheme(){return this.schemeBacker}set scheme(e){const t=e==="dark"?"dark":e==="light"?"light":"",s=this.schemeBacker,h=this.schemeExplicitlySet;this.resolvingDefaultScheme||(this.schemeExplicitlySet=t.length>0);const o=t||this.resolveDefaultScheme();h!==this.schemeExplicitlySet&&this.isConnected&&this.syncSystemSchemeListener(),o!==s&&(this.schemeBacker=o,this.requestUpdate("scheme",s),this.themeEventsReady&&p().publish("scheme-changed",{scheme:o,correlationId:this.correlationId}))}get seedColor(){return this.activeTheme.seedColor}static extractFamily(e){if(!e)return"";const t=e.match(/^"([^"]+)"|^'([^']+)'/);return t&&(t[1]||t[2])||""}injectGoogleFontLink(e,t,s){const h="data-esp-font",o=`${this.correlationId}-${e}`,r=document.head.querySelector(`link[${h}="${o}"]`);if(this.googleFontLoading==="none"){r?.remove();return}if(r&&t&&r.dataset.espFamily===t&&r.dataset.espWeight===(s??"")||(r?.remove(),!t))return;const d=encodeURIComponent(t),u=s==="bold"?"700":s==="normal"?"400":s,S=u&&u!=="400"?`:wght@${u}`:"",m=document.createElement("link");m.rel="stylesheet",m.href=`https://fonts.googleapis.com/css2?family=${d}${S}&display=swap`,m.setAttribute(h,o),m.dataset.espFamily=t,m.dataset.espWeight=s??"",document.head.appendChild(m)}syncGoogleFontLinks(){this.googleFontLoading==="none"&&this.removeRuntimeGoogleFontLinks();const e=this.activeTheme;this.injectGoogleFontLink("body",n.extractFamily(e.fontBody),e.fontWeightBody),this.injectGoogleFontLink("headings",n.extractFamily(e.fontHeadings),e.fontWeightHeadings),this.injectGoogleFontLink("brand",n.extractFamily(e.fontBrand),e.fontWeightBrand),this.injectGoogleFontLink("monospace",n.extractFamily(e.fontMonospace),e.fontWeightMonospace)}removeRuntimeGoogleFontLinks(){for(const e of document.head.querySelectorAll(`link[data-esp-font^="${this.correlationId}-"]`))e.remove();for(const e of document.head.querySelectorAll(`link[data-esp-font-picker-root="${CSS.escape(this.correlationId)}"]`))e.remove()}get activeTheme(){return this.scheme==="dark"?this.resolvedDarkTheme:this.resolvedLightTheme}resolveThemes(){const e=this.lightThemeAttr?y(this.lightThemeAttr):null;this.resolvedLightTheme=e?v(g,e):{...g};const t=this.darkThemeAttr?y(this.darkThemeAttr):null;this.resolvedDarkTheme=t?v(f,t):{...f}}connectedCallback(){super.connectedCallback(),this.registerDocumentClickBridge(),this.resizeObserver.observe(this),this.hasUpdated&&(this.applyDefaultScheme(),this.syncGoogleFontLinks())}willUpdate(e){const t=["lightThemeAttr","darkThemeAttr"];(!this.lastSeedColor||t.some(r=>e.has(r)))&&(this.resolveThemes(),this.themeEventsReady&&p().publish("theme-changed",{correlationId:this.correlationId}));const h=x(this.activeTheme,this.scheme==="dark"?"dark":"light");for(const[r,d]of Object.entries(h))this.style.setProperty(r,d);const o=this.activeTheme.seedColor;this.themeEventsReady&&this.lastSeedColor&&this.lastSeedColor!==o&&p().publish("seed-color-changed",{seedColor:o,correlationId:this.correlationId}),this.lastSeedColor=o,this.themeEventsReady&&e.has("iconSpriteUrl")&&p().publish("icon-sprite-url-changed",{iconSpriteUrl:this.iconSpriteUrl,correlationId:this.correlationId}),this.syncGoogleFontLinks()}firstUpdated(){const e=this.activeTheme.stylesheets;if(e.length)for(const t of e){const s=document.createElement("link");s.rel="stylesheet",s.href=t,document.head.appendChild(s)}if(!document.getElementById("esp-root-base-styles")){const t=document.createElement("style");t.id="esp-root-base-styles",t.textContent=n.lightDomStyles,document.head.appendChild(t)}this.applyDefaultScheme(),this.lastSeedColor=this.activeTheme.seedColor,this.themeEventsReady=!0}updated(e){(e.has("defaultScheme")||e.has("scheme"))&&!this.schemeExplicitlySet&&this.applyDefaultScheme()}disconnectedCallback(){this.unregisterDocumentClickBridge(),this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null,this.resizeObserver.disconnect(),this.removeRuntimeGoogleFontLinks(),super.disconnectedCallback()}registerDocumentClickBridge(){this.documentClickRegistrationActive||(this.documentClickRegistrationActive=!0,n.connectedRootCount+=1,n.connectedRootCount===1&&document.addEventListener("click",n.handleDocumentClick))}unregisterDocumentClickBridge(){this.documentClickRegistrationActive&&(this.documentClickRegistrationActive=!1,n.connectedRootCount=Math.max(0,n.connectedRootCount-1),n.connectedRootCount===0&&document.removeEventListener("click",n.handleDocumentClick))}applyDefaultScheme(){this.schemeExplicitlySet||(this.resolvingDefaultScheme=!0,this.scheme=this.resolveDefaultScheme(),this.resolvingDefaultScheme=!1,this.syncSystemSchemeListener())}resolveDefaultScheme(){return this.defaultScheme==="dark"||this.defaultScheme==="system"&&window.matchMedia?.("(prefers-color-scheme: dark)").matches?"dark":"light"}syncSystemSchemeListener(){if(this.schemeExplicitlySet||this.defaultScheme!=="system"||!window.matchMedia){this.systemSchemeQuery?.removeEventListener("change",this.handleSystemSchemeChange),this.systemSchemeQuery=null;return}this.systemSchemeQuery||(this.systemSchemeQuery=window.matchMedia("(prefers-color-scheme: dark)"),this.systemSchemeQuery.addEventListener("change",this.handleSystemSchemeChange))}render(){return b`<slot></slot>`}};i.connectedRootCount=0,i.handleDocumentClick=c=>{const e=c.composedPath().filter(t=>t instanceof HTMLElement&&t.tagName==="ESP-POPOVER");p().publish("close-popovers",{source:c.target??void 0,skipPopovers:e})},i.lightDomStyles=`
     
     esp-root {
       font-family: var(--esp-font-body);
@@ -125,4 +125,4 @@ var l=function(c,e,t,s){var h=arguments.length,o=h<3?e:s===null?s=Object.getOwnP
     :host {
       display: block;
     }
-  `,l([a({attribute:!1})],i.prototype,"correlationId",void 0),l([a({attribute:"light-theme"})],i.prototype,"lightThemeAttr",void 0),l([a({attribute:"dark-theme"})],i.prototype,"darkThemeAttr",void 0),l([a({attribute:"font-css-root",type:String})],i.prototype,"fontCSSRoot",void 0),l([a({attribute:"font-definitions-url",type:String})],i.prototype,"fontDefinitionsUrl",void 0),l([a({attribute:"google-font-loading",type:String})],i.prototype,"googleFontLoading",void 0),l([a({attribute:"icon-sprite-url",type:String})],i.prototype,"iconSpriteUrl",void 0),l([a({attribute:"default-scheme",type:String,reflect:!0})],i.prototype,"defaultScheme",void 0),l([a({attribute:"scheme",type:String,reflect:!0})],i.prototype,"scheme",null),i=n=l([E("esp-root")],i);export{i as EspalierRoot};
+  `,l([a({attribute:!1})],i.prototype,"correlationId",void 0),l([a({attribute:"light-theme"})],i.prototype,"lightThemeAttr",void 0),l([a({attribute:"dark-theme"})],i.prototype,"darkThemeAttr",void 0),l([a({attribute:"font-css-root",type:String})],i.prototype,"fontCSSRoot",void 0),l([a({attribute:"font-definitions-url",type:String})],i.prototype,"fontDefinitionsUrl",void 0),l([a({attribute:"google-font-loading",type:String})],i.prototype,"googleFontLoading",void 0),l([a({attribute:"icon-sprite-url",type:String})],i.prototype,"iconSpriteUrl",void 0),l([a({attribute:"default-scheme",type:String,reflect:!0})],i.prototype,"defaultScheme",void 0),l([a({attribute:"scheme",type:String,reflect:!0})],i.prototype,"scheme",null),i=n=l([E("esp-root")],i);export{P as BUILT_IN_IMAGE_TEXTURES,i as EspalierRoot,H as registerImageTexture,M as registeredImageTextures};

package/dist/shared/image-texture-registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Named banner-texture registry.
+ *
+ * The built-in procedural presets cover the asset-free styles. Image-backed
+ * looks previously required hand-wiring the five consumer texture tokens on
+ * every banner; registering the look once turns it into a reusable preset a
+ * banner selects with `texture="<name>"` — and gives hosts (e.g. an editor
+ * preset picker) one place to enumerate the available styles.
+ */
+/** Immutable snapshot of the built-in texture names, for pickers and docs. */
+export declare const BUILT_IN_IMAGE_TEXTURES: readonly string[];
+/** Whether a name is one of the built-in procedural textures. */
+export declare function isBuiltInImageTexture(name: string): boolean;
+/** A registered, image-backed texture preset. */
+export interface ImageTextureDefinition {
+    /** CSS `background-image` value (a `url(...)` or gradient). */
+    image: string;
+    /** CSS `background-size`. Defaults to `auto`. */
+    size?: string;
+    /** CSS `background-repeat`. Defaults to `repeat`. */
+    repeat?: string;
+    /** CSS `background-position`. Defaults to `0 0`. */
+    position?: string;
+    /** Layer opacity (0–1). Defaults to `1`. */
+    opacity?: number;
+    /** CSS `mix-blend-mode` against the photo. Defaults to `normal`. */
+    blendMode?: string;
+}
+/**
+ * Register (or replace) a named texture preset. Live `esp-image` banners
+ * already pointing at the name re-render, so registration at mount and
+ * markup order never race.
+ *
+ * @throws when the name is not lowercase kebab-case or shadows a built-in.
+ */
+export declare function registerImageTexture(name: string, definition: ImageTextureDefinition): void;
+/** Look up a registered texture preset. */
+export declare function getImageTexture(name: string): Readonly<ImageTextureDefinition> | undefined;
+/**
+ * A snapshot of every registered preset, for building texture pickers.
+ * Mutating the returned map does not affect the registry.
+ */
+export declare function registeredImageTextures(): Map<string, Readonly<ImageTextureDefinition>>;
+/** Subscribe to registry changes. Returns the unsubscribe function. */
+export declare function subscribeToImageTextureRegistry(listener: () => void): () => void;

package/dist/shared/image-texture-registry.js

@@ -0,0 +1 @@
+const n=new Set(["none","dots","halftone","paper","grain","grunge","scanlines","duotone"]),a=Object.freeze([...n]);function i(e){return n.has(e)}const u=/^[a-z][a-z0-9-]*$/,t=new Map,r=new Set;function c(e,o){if(!u.test(e))throw new Error(`Invalid texture name "${e}". Use lowercase kebab-case (e.g. "linen-paper").`);if(i(e))throw new Error(`"${e}" is a built-in esp-image texture and cannot be replaced.`);t.set(e,Object.freeze({...o}));for(const s of r)s()}function g(e){return t.get(e)}function p(){return new Map(t)}function x(e){return r.add(e),()=>r.delete(e)}export{a as BUILT_IN_IMAGE_TEXTURES,g as getImageTexture,i as isBuiltInImageTexture,c as registerImageTexture,p as registeredImageTextures,x as subscribeToImageTextureRegistry};

package/dist/shared/popover-controller.js

@@ -1 +1 @@
-import{getEspBus as n}from"./bus-events.js";class u{constructor(e){this.bus=n(),this.rafId=0,this.handleClosePopovers=s=>{if(!this.opts.isOpen())return;const t=this.opts.host;if(this.opts.closeStrategy==="source-identity"){if(!s.source||s.source===t||s.source instanceof Node&&(t.contains(s.source)||t.shadowRoot?.contains(s.source)))return}else if(s.skipPopovers?.includes(t))return;this.opts.onShouldClose()},this.onScrollOrResize=()=>{this.rafId||(this.rafId=requestAnimationFrame(()=>{if(this.rafId=0,!!this.opts.isOpen()){if(this.opts.shouldContinueTracking&&!this.opts.shouldContinueTracking()){this.opts.onShouldClose();return}this.opts.onPositionUpdate?.()}}))},this.onDocumentClick=s=>{const t=this.opts.host,o=s.composedPath();if(o.includes(t))return;const r=this.opts.getInsideElements?.()??[];for(const i of r)if(i&&o.includes(i))return;this.opts.isOpen()&&this.opts.onOutsideClick?.()},this.opts=e,e.host.addController(this)}hostConnected(){this.bus.subscribe("close-popovers",this.handleClosePopovers)}hostDisconnected(){this.bus.unsubscribe("close-popovers",this.handleClosePopovers),this.stopTracking(),this.stopOutsideClick()}startTracking(){this.opts.onPositionUpdate&&(window.addEventListener("scroll",this.onScrollOrResize,{capture:!0,passive:!0}),window.addEventListener("resize",this.onScrollOrResize,{passive:!0}))}stopTracking(){window.removeEventListener("scroll",this.onScrollOrResize,{capture:!0}),window.removeEventListener("resize",this.onScrollOrResize),this.rafId&&(cancelAnimationFrame(this.rafId),this.rafId=0)}startOutsideClick(){this.opts.onOutsideClick&&document.addEventListener("click",this.onDocumentClick,!0)}stopOutsideClick(){document.removeEventListener("click",this.onDocumentClick,!0)}publishCloseOthers(){this.bus.publish("close-popovers",{source:this.opts.host})}publishCloseExcept(e){this.bus.publish("close-popovers",{skipPopovers:e})}}export{u as PopoverController};
+import{getEspBus as c}from"./bus-events.js";function u(r){const t=[],e=new Set;let s=r;for(;s&&!e.has(s);){e.add(s);const i=s["linked-popover"];if(i){s=i;continue}const o=s.closest("esp-popover");if(o){t.includes(o)||t.push(o),s=o.parentElement||o.getRootNode()?.host;continue}const n=s.getRootNode();s=n instanceof ShadowRoot?n.host:void 0}return t}class l{constructor(t){this.bus=c(),this.rafId=0,this.handleClosePopovers=e=>{if(!this.opts.isOpen())return;const s=this.opts.host;if(this.opts.closeStrategy==="source-identity"){if(!e.source||e.source===s||e.source instanceof Node&&(s.contains(e.source)||s.shadowRoot?.contains(e.source)))return}else if(e.skipPopovers?.includes(s))return;this.opts.onShouldClose()},this.onScrollOrResize=()=>{this.rafId||(this.rafId=requestAnimationFrame(()=>{if(this.rafId=0,!!this.opts.isOpen()){if(this.opts.shouldContinueTracking&&!this.opts.shouldContinueTracking()){this.opts.onShouldClose();return}this.opts.onPositionUpdate?.()}}))},this.onDocumentClick=e=>{const s=this.opts.host,i=e.composedPath();if(i.includes(s))return;const o=this.opts.getInsideElements?.()??[];for(const n of o)if(n&&i.includes(n))return;this.opts.isOpen()&&this.opts.onOutsideClick?.()},this.opts=t,t.host.addController(this)}hostConnected(){this.bus.subscribe("close-popovers",this.handleClosePopovers)}hostDisconnected(){this.bus.unsubscribe("close-popovers",this.handleClosePopovers),this.stopTracking(),this.stopOutsideClick()}startTracking(){this.opts.onPositionUpdate&&(window.addEventListener("scroll",this.onScrollOrResize,{capture:!0,passive:!0}),window.addEventListener("resize",this.onScrollOrResize,{passive:!0}))}stopTracking(){window.removeEventListener("scroll",this.onScrollOrResize,{capture:!0}),window.removeEventListener("resize",this.onScrollOrResize),this.rafId&&(cancelAnimationFrame(this.rafId),this.rafId=0)}startOutsideClick(){this.opts.onOutsideClick&&document.addEventListener("click",this.onDocumentClick,!0)}stopOutsideClick(){document.removeEventListener("click",this.onDocumentClick,!0)}publishCloseOthers(t=[]){this.bus.publish("close-popovers",{source:this.opts.host,...t.length>0?{skipPopovers:t}:{}})}publishCloseExcept(t){this.bus.publish("close-popovers",{source:this.opts.host,skipPopovers:t})}}export{l as PopoverController,u as findContainingPopovers};

package/dist/shared/visual-overlay.js

@@ -0,0 +1,51 @@
+import{css as r,html as o,nothing as a}from"lit";function i(e={}){return o`
+    <div
+      class="esp-visual-overlay ${e.className??""}"
+      part=${e.rootPart||a}
+      aria-hidden="true"
+    >
+      <div class="esp-visual-overlay__image" part=${e.imagePart||a}></div>
+      <div class="esp-visual-overlay__scrim" part=${e.scrimPart||a}></div>
+      <div class="esp-visual-overlay__texture" part=${e.texturePart||a}></div>
+    </div>
+  `}const v=r`
+  .esp-visual-overlay {
+    position: absolute;
+    z-index: var(--_esp-overlay-z-index, auto);
+    inset: 0;
+    overflow: hidden;
+    pointer-events: none;
+    background: var(--_esp-overlay-base-color, transparent);
+  }
+
+  .esp-visual-overlay__image,
+  .esp-visual-overlay__scrim,
+  .esp-visual-overlay__texture {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+
+  .esp-visual-overlay__image {
+    background-image: var(--_esp-overlay-image, none);
+    background-repeat: var(--_esp-overlay-image-repeat, repeat);
+    background-position: var(--_esp-overlay-image-position, 0 0);
+    background-size: var(--_esp-overlay-image-size, auto);
+    opacity: var(--_esp-overlay-image-opacity, 1);
+    mix-blend-mode: var(--_esp-overlay-image-blend-mode, normal);
+  }
+
+  .esp-visual-overlay__scrim {
+    background: var(--_esp-overlay-scrim, none);
+    opacity: var(--_esp-overlay-scrim-opacity, 1);
+  }
+
+  .esp-visual-overlay__texture {
+    background: var(--_esp-overlay-texture, none);
+    background-size: var(--_esp-overlay-texture-size, auto);
+    opacity: var(--_esp-overlay-texture-opacity, 1);
+    mix-blend-mode: var(--_esp-overlay-texture-blend-mode, normal);
+    filter: var(--_esp-overlay-texture-filter, none);
+    mask: var(--_esp-overlay-texture-mask, none);
+  }
+`;export{i as renderVisualOverlay,v as visualOverlayStyles};

package/espalier.token-manifest.json

@@ -496,6 +496,48 @@
       "component": "esp-flyout",
       "description": "Stack order of the overlay-drawer mode. Defaults to `3000` — above page chrome, below the dialog drop zone (4000). Set it on the `esp-page` (or an ancestor), not on the flyout itself: the page reads the same token to hoist the drawer's aside above its header."
     },
+    {
+      "name": "--esp-focus-picker-focus-outline",
+      "category": "component",
+      "component": "esp-focus-picker",
+      "description": "Marker focus-visible outline."
+    },
+    {
+      "name": "--esp-focus-picker-gap",
+      "category": "component",
+      "component": "esp-focus-picker",
+      "description": "Gap between the stage and previews."
+    },
+    {
+      "name": "--esp-focus-picker-marker-border",
+      "category": "component",
+      "component": "esp-focus-picker",
+      "description": "Focal marker border."
+    },
+    {
+      "name": "--esp-focus-picker-marker-color",
+      "category": "component",
+      "component": "esp-focus-picker",
+      "description": "Focal marker fill."
+    },
+    {
+      "name": "--esp-focus-picker-marker-shadow",
+      "category": "component",
+      "component": "esp-focus-picker",
+      "description": "Focal marker shadow."
+    },
+    {
+      "name": "--esp-focus-picker-marker-size",
+      "category": "component",
+      "component": "esp-focus-picker",
+      "description": "Focal marker diameter."
+    },
+    {
+      "name": "--esp-focus-picker-stage-background",
+      "category": "component",
+      "component": "esp-focus-picker",
+      "description": "Empty/loading stage color."
+    },
     {
       "name": "--esp-font-body",
       "category": "root-theme",
@@ -1122,7 +1164,55 @@
       "name": "--esp-image-border",
       "category": "component",
       "component": "esp-image",
-      "description": "Set the border property of the image."
+      "description": "Border; defaults to `2px solid var(--esp-color-border)` or none in banner mode."
+    },
+    {
+      "name": "--esp-image-border-radius",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Corner radius; defaults to `var(--esp-size-border-radius)` or zero in banner mode."
+    },
+    {
+      "name": "--esp-image-compact-width",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Component-width threshold; defaults to `40rem`."
+    },
+    {
+      "name": "--esp-image-duotone-highlight-color",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Duotone highlight stop; defaults to a light stop derived from the theme complementary."
+    },
+    {
+      "name": "--esp-image-duotone-shadow-color",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Duotone shadow stop; defaults to a dark stop derived from the theme primary."
+    },
+    {
+      "name": "--esp-image-object-position",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Final object-position override."
+    },
+    {
+      "name": "--esp-image-overlay-color",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Overlay text color; defaults to the theme heading color when the banner polarity matches the scheme."
+    },
+    {
+      "name": "--esp-image-overlay-padding",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Overlay content padding."
+    },
+    {
+      "name": "--esp-image-overlay-text-shadow",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Overlay text shadow; defaults to a soft polarity-matched halo. Set to `none` to disable."
     },
     {
       "name": "--esp-image-preview-border-color",
@@ -1142,6 +1232,72 @@
       "component": "esp-image-preview",
       "description": "The text color of the remove button."
     },
+    {
+      "name": "--esp-image-scrim-color",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Scrim ink; defaults to the theme background when the banner polarity matches the scheme, else a polarity-pinned derivation."
+    },
+    {
+      "name": "--esp-image-scrim-opacity",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Scrim-strength opacity override."
+    },
+    {
+      "name": "--esp-image-texture-blend-mode",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Texture blend-mode override."
+    },
+    {
+      "name": "--esp-image-texture-color",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Procedural texture ink; defaults to a theme-derived color following `banner-scheme`."
+    },
+    {
+      "name": "--esp-image-texture-image",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Consumer-supplied texture background image."
+    },
+    {
+      "name": "--esp-image-texture-image-opacity",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Consumer texture opacity."
+    },
+    {
+      "name": "--esp-image-texture-opacity",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Procedural texture opacity override."
+    },
+    {
+      "name": "--esp-image-texture-position",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Consumer texture position."
+    },
+    {
+      "name": "--esp-image-texture-repeat",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Consumer texture repeat."
+    },
+    {
+      "name": "--esp-image-texture-scale",
+      "category": "component",
+      "component": "esp-image",
+      "description": "CSS-gradient texture pitch override."
+    },
+    {
+      "name": "--esp-image-texture-size",
+      "category": "component",
+      "component": "esp-image",
+      "description": "Consumer texture size."
+    },
     {
       "name": "--esp-image-upload-preview-background",
       "category": "component",

package/licenses/ASSET_PROVENANCE.md

@@ -14,6 +14,9 @@ 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 |
+| `css/textures/*.png` | Deterministic 256×256 first-party tiles from `node scripts/generate-banner-textures.js`; byte-for-byte verification uses `--check`. | None |
+| Banner preset reference sheets | Taproot-authored browser captures of the locked visual recipes over the provenance-cleared bright and dark canvas images. | None |
+| `assets/focus-picker-unsplash.jpg` | Docs-only landscape photograph by Sasha Freemind, downloaded from Unsplash and used to make focal-point movement easy to see. | Attribution is included in the focus-picker demos. |
 | `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 |

package/licenses/asset-provenance.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "updatedAt": "2026-07-11",
+  "updatedAt": "2026-07-21",
   "entries": [
     {
       "id": "google-font-preview-assets",
@@ -155,6 +155,73 @@
       "noticePaths": [],
       "reviewStatus": "documented"
     },
+    {
+      "id": "generated-banner-textures",
+      "paths": [
+        "css/textures/espalier-paper.png",
+        "css/textures/espalier-grain.png",
+        "css/textures/espalier-grunge.png"
+      ],
+      "assetType": "deterministic seamless banner texture tiles (PNG, 256x256)",
+      "classification": "generated Taproot-owned",
+      "owner": "Taproot",
+      "source": "First-party procedural generator committed at scripts/generate-banner-textures.js",
+      "license": "Taproot-owned generated assets distributed with Espalier",
+      "transformations": [
+        "Generate periodic paper fibers, deterministic film grain, and toroidal distressed marks",
+        "Encode RGBA pixels as reproducible PNG bytes with Node built-ins",
+        "Regenerate with: node scripts/generate-banner-textures.js",
+        "Verify byte-for-byte with: node scripts/generate-banner-textures.js --check"
+      ],
+      "dimensions": "256x256 each",
+      "packageInclusion": "included in private and public npm packages under css/textures/",
+      "docsInclusion": "available to esp-image examples through css/textures/banner-textures.css",
+      "noticeRequirement": "none",
+      "noticePaths": [],
+      "reviewStatus": "manifest-gated"
+    },
+    {
+      "id": "banner-preset-reference-sheets",
+      "paths": [
+        "assets/esp-image-banners/reference-bright.jpg",
+        "assets/esp-image-banners/reference-dark.jpg"
+      ],
+      "assetType": "browser-captured banner preset reference sheets (JPEG, 1120x1768)",
+      "classification": "Taproot-authored derived documentation assets",
+      "owner": "Taproot",
+      "source": "Captured from __tests__/image/esp-image-banner-reference.browser.html in the Codex in-app browser on 2026-07-20, using the provenance-cleared canvas-bg.jpg and canvas-bg-dark.jpg source images",
+      "license": "Taproot-owned reference composition; underlying source-image ownership and license remain recorded in their own manifest entries",
+      "transformations": [
+        "Rendered the locked procedural scrim and texture recipes over the bright and dark source images",
+        "Captured one 1120x1768 browser viewport per scheme"
+      ],
+      "packageInclusion": "not included in npm package",
+      "docsInclusion": "copied to public docs assets and embedded by docs/guides/esp-image-banners.md",
+      "noticeRequirement": "none",
+      "noticePaths": [],
+      "reviewStatus": "documented"
+    },
+    {
+      "id": "unsplash-focus-picker-demo",
+      "paths": [
+        "assets/focus-picker-unsplash.jpg"
+      ],
+      "assetType": "docs-only landscape photograph (JPEG, 1800x1200)",
+      "classification": "third-party licensed",
+      "owner": "Sasha Freemind",
+      "source": "https://unsplash.com/photos/woman-standing-on-grass-field-frq5Q6Ne9k4",
+      "license": "Unsplash License (https://unsplash.com/license)",
+      "transformations": [
+        "Downloaded through the Unsplash image CDN at 1800px width with JPEG quality 85",
+        "No local crop or retouching"
+      ],
+      "dimensions": "1800x1200",
+      "packageInclusion": "not included in npm package",
+      "docsInclusion": "copied to public docs assets and used by esp-focus-picker examples",
+      "noticeRequirement": "none",
+      "noticePaths": [],
+      "reviewStatus": "documented"
+    },
     {
       "id": "demo-grid-data",
       "paths": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "2.6.0",
+  "version": "2.7.1",
   "packageManager": "bun@1.3.12",
   "description": "Espalier — a themeable, accessible, framework-agnostic, enterprise-grade design system built on web standards and love.",
   "customElements": "custom-elements.json",
@@ -98,6 +98,10 @@
       "types": "./dist/font-picker/esp-font-picker.d.ts",
       "import": "./dist/font-picker/esp-font-picker.js"
     },
+    "./focus-picker": {
+      "types": "./dist/focus-picker/esp-focus-picker.d.ts",
+      "import": "./dist/focus-picker/esp-focus-picker.js"
+    },
     "./footer": {
       "types": "./dist/footer/index.d.ts",
       "import": "./dist/footer/index.js"
@@ -275,6 +279,10 @@
       "import": "./dist/shared/bus-events.js"
     },
     "./espalier.token-manifest.json": "./espalier.token-manifest.json",
+    "./textures/banner-textures.css": "./css/textures/banner-textures.css",
+    "./textures/espalier-paper.png": "./css/textures/espalier-paper.png",
+    "./textures/espalier-grain.png": "./css/textures/espalier-grain.png",
+    "./textures/espalier-grunge.png": "./css/textures/espalier-grunge.png",
     "./custom-elements.json": "./custom-elements.json",
     "./espalier.css-data.json": "./espalier.css-data.json",
     "./css/esp-reset.css": "./css/esp-reset.css",
@@ -295,6 +303,8 @@
     "css/esp-reset.css",
     "css/fonts/**/*.css",
     "css/fonts/font-definitions.json",
+    "css/textures/banner-textures.css",
+    "css/textures/*.png",
     "custom-elements.json",
     "espalier.css-data.json",
     "espalier.token-manifest.json",