@taprootio/espalier 4.1.0 → 4.3.0

package/dist/cli/theme-check.js

@@ -1,2 +1,2 @@
-import{encodeTheme as h,validateThemePair as p}from"../shared/theme.js";import{themeFitReportSuite as m}from"../shared/theme-fit-report.js";const u="usage: espalier theme check <theme.json> [--json] [--expect <fit.json>] [--update-expect <fit.json>]";function S(t,e){const[n,o,...r]=t;if(n!=="theme"||o!=="check")return e.error(u),2;const i=g(r,e);return i?k(i,e):2}function g(t,e){const n={file:"",json:!1};for(let o=0;o<t.length;o+=1){const r=t[o];if(r==="--json")n.json=!0;else if(r==="--expect"||r==="--update-expect"){const i=t[o+1];if(i===void 0)return e.error(`${r} requires a file path. ${u}`),null;r==="--expect"?n.expect=i:n.updateExpect=i,o+=1}else if(!r.startsWith("--")&&n.file==="")n.file=r;else return e.error(`Unknown argument "${r}". ${u}`),null}return n.file===""?(e.error(u),null):n.expect!==void 0&&n.updateExpect!==void 0?(e.error(`--expect checks the committed fit tables and --update-expect rewrites them \u2014 pick one. ${u}`),null):n}function $(t,e){let n;try{n=e.readFile(t)}catch(i){return e.error(`Cannot read ${t}: ${i instanceof Error?i.message:String(i)}`),null}let o;try{o=JSON.parse(n)}catch(i){return e.error(`${t} is not JSON: ${i instanceof Error?i.message:String(i)}`),null}if(typeof o!="object"||o===null||Array.isArray(o))return e.error(`${t} must contain a theme object.`),null;const r=o;if("light"in r||"dark"in r){for(const i of["light","dark"]){const s=r[i];if(s!==void 0&&(typeof s!="object"||s===null||Array.isArray(s)))return e.error(`${t}: "${i}" must be a theme object.`),null}return{light:r.light??{},dark:r.dark??{}}}return{light:r,dark:r}}function k(t,e){const n=$(t.file,e);if(!n)return 2;const o=p(h(n.light),h(n.dark));for(const s of o.warnings)e.error(`warning: ${s}`);if(!o.valid){for(const s of o.errors)e.error(`error: ${s}`);return e.error(`${t.file}: ${o.errors.length} validation error(s).`),1}const r=m(n.light,n.dark),i=t.json?e.error:e.log;if(t.updateExpect!==void 0){try{e.writeFile(t.updateExpect,`${JSON.stringify(r,null,2)}
-`)}catch(s){return e.error(`Cannot write ${t.updateExpect}: ${s instanceof Error?s.message:String(s)}`),2}return i(`Wrote fit tables to ${t.updateExpect}.`),t.json&&e.log(JSON.stringify(r,null,2)),0}if(t.expect!==void 0){let s;try{s=e.readFile(t.expect)}catch{return e.error(`Expected fit tables not found at ${t.expect} \u2014 create them with --update-expect ${t.expect}.`),2}let f;try{f=JSON.parse(s)}catch{return e.error(`${t.expect} is not JSON.`),2}if(!y(f))return e.error(`${t.expect} is not a fit-table suite \u2014 regenerate it with --update-expect ${t.expect}.`),2;const a=x(f,r);if(a.length>0){for(const l of a)e.error(`drift: ${l}`);return e.error(`Fit tables drifted from ${t.expect} (${a.length} difference(s)). Review, then refresh deliberately with --update-expect.`),1}i(`Fit tables match ${t.expect}.`)}return t.json?(e.log(JSON.stringify(r,null,2)),0):(b(r,e),0)}function y(t){if(typeof t!="object"||t===null||Array.isArray(t))return!1;const e=t;if(!Array.isArray(e.surfaces)||!e.surfaces.every(n=>typeof n=="string"))return!1;for(const n of["light","dark"]){const o=e[n];if(!Array.isArray(o))return!1;for(const r of o){if(typeof r!="object"||r===null||Array.isArray(r))return!1;const i=r;if(typeof i.surface!="string"||!Array.isArray(i.tokens))return!1;for(const s of i.tokens){if(typeof s!="object"||s===null||Array.isArray(s))return!1;const f=s;if(typeof f.token!="string"||typeof f.resolved!="string")return!1}}}return!0}function x(t,e){const n=[];if(JSON.stringify(t)===JSON.stringify(e))return n;for(const o of["light","dark"]){const r=new Map((t[o]??[]).map(s=>[s.surface,s])),i=new Map((e[o]??[]).map(s=>[s.surface,s]));for(const s of new Set([...r.keys(),...i.keys()])){const f=r.get(s),a=i.get(s);if(!f||!a){n.push(`${o}/${s}: surface ${f?"removed":"added"}`);continue}const l=new Map(f.tokens.map(c=>[c.token,c]));for(const c of a.tokens){const d=l.get(c.token);d?d.resolved!==c.resolved&&n.push(`${o}/${s}/${c.token}: ${d.resolved} \u2192 ${c.resolved}`):n.push(`${o}/${s}/${c.token}: token added`),l.delete(c.token)}for(const c of l.keys())n.push(`${o}/${s}/${c}: token removed`)}}return n.length===0&&n.push("fit-table metadata changed (lints or provenance marks)"),n}function b(t,e){for(const o of["light","dark"])for(const r of t[o]){e.log(j(o,r));for(const i of r.lints)e.log(`  lint(${i.id}): ${i.message}`)}const n=[...t.light,...t.dark].reduce((o,r)=>o+r.lints.length,0);e.log(`Checked ${t.surfaces.length} surface(s) \xD7 2 schemes \u2014 `+(n===0?"no lints.":`${n} lint(s), listed above.`))}function j(t,e){const n=e.adjustedTokens.length===0?"contrast enforcement moved nothing":`contrast enforcement moved ${e.adjustedTokens.join(", ")}`,o=e.tokens.filter(i=>i.explicit==="inherited").length,r=o===0?"":`; ${o} inherited explicit pin(s) \u2014 see the fit tables`;return`${t}/${e.surface}: ${e.tokens.length} tokens, ${n}${r}.`}export{S as runEspalierCli};
+import{encodeTheme as D,isObjectRecord as p,isSemanticColorName as P,validateThemePair as G}from"../shared/theme.js";import{THEME_FIT_ANCHOR_FIELDS as C,THEME_FIT_APCA_FIELDS as N,THEME_FIT_DATA_PALETTE_LINT_FIELDS as M,THEME_FIT_DATA_PALETTE_LINT_IDS as X,THEME_FIT_EXPLICIT_VALUES as Y,THEME_FIT_LINT_FIELDS as R,THEME_FIT_LINT_IDS as B,THEME_FIT_LINT_SEVERITIES as Q,THEME_FIT_REPORT_FIELDS as _,THEME_FIT_SUITE_FIELDS as k,THEME_FIT_TOKEN_FIELDS as x,themeFitReportSuite as Z}from"../shared/theme-fit-report.js";import{COLOR_VISION_SIMULATIONS as v,DATA_SERIES_KEYS as w,isPaletteCollisionDescription as ee}from"../shared/data-colors.js";import{isSafeKey as te}from"../shared/unsafe-keys.js";const A="usage: espalier theme check <theme.json> [--json] [--expect <fit.json>] [--update-expect <fit.json>]";function Me(e,t){const[r,i,...n]=e;if(r!=="theme"||i!=="check")return t.error(A),2;const s=re(n,t);return s?ie(s,t):2}function re(e,t){const r={file:"",json:!1};for(let i=0;i<e.length;i+=1){const n=e[i];if(n==="--json")r.json=!0;else if(n==="--expect"||n==="--update-expect"){const s=e[i+1];if(s===void 0)return t.error(`${n} requires a file path. ${A}`),null;n==="--expect"?r.expect=s:r.updateExpect=s,i+=1}else if(!n.startsWith("--")&&r.file==="")r.file=n;else return t.error(`Unknown argument "${n}". ${A}`),null}return r.file===""?(t.error(A),null):r.expect!==void 0&&r.updateExpect!==void 0?(t.error(`--expect checks the committed fit tables and --update-expect rewrites them \u2014 pick one. ${A}`),null):r}function ne(e,t){let r;try{r=t.readFile(e)}catch(s){return t.error(`Cannot read ${e}: ${s instanceof Error?s.message:String(s)}`),null}let i;try{i=JSON.parse(r)}catch(s){return t.error(`${e} is not JSON: ${s instanceof Error?s.message:String(s)}`),null}if(typeof i!="object"||i===null||Array.isArray(i))return t.error(`${e} must contain a theme object.`),null;const n=i;if("light"in n||"dark"in n){for(const s of["light","dark"]){const o=n[s];if(o!==void 0&&(typeof o!="object"||o===null||Array.isArray(o)))return t.error(`${e}: "${s}" must be a theme object.`),null}return{light:n.light??{},dark:n.dark??{}}}return{light:n,dark:n}}function ie(e,t){const r=ne(e.file,t);if(!r)return 2;const i=G(D(r.light),D(r.dark));if(!i.valid){for(const c of i.warnings)t.error(`warning: ${c}`);for(const c of i.errors)t.error(`error: ${c}`);return t.error(`${e.file}: ${i.errors.length} validation error(s).`),1}const n=Z(r.light,r.dark);for(const c of i.warnings)Ie(c,n)||t.error(`warning: ${c}`);const s=Ae(n),o=e.json?t.error:t.log;if(e.updateExpect!==void 0){try{t.writeFile(e.updateExpect,`${JSON.stringify(n,null,2)}
+`)}catch(c){return t.error(`Cannot write ${e.updateExpect}: ${c instanceof Error?c.message:String(c)}`),2}o(`Wrote fit tables to ${e.updateExpect}.`)}if(e.expect!==void 0){let c;try{c=t.readFile(e.expect)}catch{return t.error(`Expected fit tables not found at ${e.expect} \u2014 create them with --update-expect ${e.expect}.`),2}let a;try{a=JSON.parse(c)}catch{return t.error(`${e.expect} is not JSON.`),2}if(se(a))return t.error(`${e.expect} was written by espalier \u22644.2.0 \u2014 regenerate it with --update-expect ${e.expect}.`),2;if(!oe(a))return t.error(`${e.expect} is not a fit-table suite \u2014 regenerate it with --update-expect ${e.expect}.`),2;const f=le(a,n);if(f.length>0){s>0&&we(n,s,t);for(const u of f)t.error(`drift: ${u}`);return t.error(`Fit tables drifted from ${e.expect} (${f.length} difference(s)). Review, then refresh deliberately with --update-expect.`),1}o(`Fit tables match ${e.expect}.`)}return e.json?(t.log(JSON.stringify(n,null,2)),s>0?1:0):(xe(n,s,t),s>0?1:0)}function oe(e){if(!p(e)||!k.every(({field:r,kind:i})=>T(e[String(r)],i)))return!1;const t=e;if(!I(t.surfaces))return!1;for(const r of["light","dark"]){const n=t.paletteLints[r].map(g);if(!I(n))return!1;const s=t[r],o=new Set;for(const c of s){if(!pe(c,r)||!t.surfaces.includes(c.surface)||o.has(c.surface))return!1;o.add(c.surface)}}return!0}function se(e){return p(e)&&H(e.surfaces)&&Array.isArray(e.light)&&Array.isArray(e.dark)&&!("dataPalette"in e)&&!("paletteLints"in e)}function ce(e){return typeof e=="number"&&Number.isFinite(e)}function H(e){return Array.isArray(e)&&e.every(t=>typeof t=="string")}function I(e){return new Set(e).size===e.length}function ae(e){return p(e)&&M.every(({field:t,kind:r})=>T(e[String(t)],r))}function fe(e){return p(e)&&R.every(({field:t,kind:r})=>T(e[String(t)],r))}function ue(e){return p(e)&&x.every(({field:t,kind:r})=>T(e[String(t)],r))}function T(e,t){switch(t){case"anchor":return e===void 0||V(e,C);case"anchor-record":return p(e)&&Object.keys(e).every(te)&&Object.values(e).every(r=>typeof r=="string");case"apca":return e===void 0||V(e,N);case"boolean":return typeof e=="boolean";case"data-palette-record":return p(e)?["light","dark"].every(r=>{const i=e[r];return p(i)&&w.every(n=>typeof i[n]=="string")}):!1;case"explicit":return e===void 0||Y.includes(e);case"fit-lint-id":return B.includes(e);case"lint-array":return Array.isArray(e)&&e.every(fe);case"message":case"string":return typeof e=="string";case"number":return ce(e);case"palette-lint-id":return X.includes(e);case"palette-lint-record":return p(e)&&["light","dark"].every(r=>Array.isArray(e[r])&&e[r].every(ae));case"report-array":return Array.isArray(e);case"scheme":return e==="light"||e==="dark";case"semantic":return P(e);case"semantic-array":return Array.isArray(e)&&e.every(P);case"series-pair":return de(e);case"simulation":return v.includes(e);case"string-array":return H(e);case"token-array":return Array.isArray(e)&&e.every(ue);case"warning":return Q.includes(e);default:{const r=t;return!1}}}function V(e,t){return p(e)&&t.every(({field:r,kind:i})=>T(e[String(r)],i))}function de(e){if(!Array.isArray(e)||e.length!==2)return!1;const t=w.indexOf(e[0]),r=w.indexOf(e[1]);return t>=0&&r>t}function pe(e,t){if(!p(e)||!_.every(({field:i,kind:n})=>T(e[String(i)],n)))return!1;const r=e;return r.scheme!==t?!1:I(r.tokens.map(i=>i.token))&&I(r.adjustedTokens)&&I(r.lints.map(i=>i.id))}function le(e,t){const r=[];for(const n of k)n.compared&&me(r,n,e,t);return(h(z(e))!==h(z(t))||r.length===0&&h(e)!==h(t))&&r.push("fit tables differ outside compared fields"),r}function me(e,t,r,i){const{field:n,kind:s}=t;if(s==="string-array"){const o=r[n],c=i[n];U(e,String(n),o,c),E(e,String(n),o,c);return}if(s==="data-palette-record"){const o=r[n],c=i[n];for(const a of["light","dark"])for(const f of w)K(e,`${a}/${String(n)}/${f}`,o[a][f],c[a][f]);return}if(s==="palette-lint-record"){const o=r[n],c=i[n];for(const a of["light","dark"])ke(e,a,String(n),o[a],c[a]),E(e,`${a}/${String(n)}`,o[a].map(g),c[a].map(g));return}if(s==="report-array"&&(n==="light"||n==="dark")){he(e,n,r[n],i[n]);return}F(e,"fit tables",String(n),r[n],i[n],s)}function he(e,t,r,i){const n=new Map(r.map(o=>[o.surface,o])),s=new Map(i.map(o=>[o.surface,o]));E(e,`${t}/reports`,r.map(o=>o.surface),i.map(o=>o.surface));for(const o of L(n.keys(),s.keys())){const c=n.get(o),a=s.get(o),f=`${t}/${o}`;if(!c||!a){e.push(`${f}: surface ${c?"removed":"added"}`);continue}ge(e,f,c,a)}}function ge(e,t,r,i){for(const n of _){const{compared:s,field:o,kind:c}=n;if(!(!s||o==="scheme"||o==="surface")){if(c==="anchor-record"){Te(e,`${t}/${String(o)}`,r[o],i[o]);continue}if(c==="semantic-array"){const a=r[o],f=i[o];U(e,`${t}/${String(o)}`,a,f),E(e,`${t}/${String(o)}`,a,f);continue}if(c==="lint-array"){const a=r[o],f=i[o];Se(e,t,String(o),a,f),E(e,`${t}/${String(o)}`,a.map(u=>u.id),f.map(u=>u.id));continue}if(c==="token-array"){$e(e,t,String(o),r[o],i[o]);continue}F(e,t,String(o),r[o],i[o],c)}}}function $e(e,t,r,i,n){const s=new Map(i.map(a=>[a.token,a])),o=new Map(n.map(a=>[a.token,a]));E(e,`${t}/${r}`,i.map(a=>a.token),n.map(a=>a.token));const c=r==="tokens"?t:`${t}/${r}`;for(const a of L(s.keys(),o.keys())){const f=s.get(a),u=o.get(a),S=`${c}/${a}`;if(!f||!u){e.push(`${S}: token ${f?"removed":"added"}`);continue}ye(e,S,f,u)}}function ye(e,t,r,i){for(const{compared:n,field:s,kind:o}of x)if(!(!n||s==="token")){if(o==="anchor"){J(e,t,"anchor",r.anchor,i.anchor,C);continue}if(o==="apca"){J(e,t,"apca",r.apca,i.apca,N);continue}F(e,t,String(s),r[s],i[s],o)}}function J(e,t,r,i,n,s){const o=i,c=n;for(const{compared:a,field:f,kind:u}of s)a&&F(e,t,`${r}.${String(f)}`,o?.[f],c?.[f],u)}function Se(e,t,r,i,n){const s=new Map(i.map(c=>[c.id,c])),o=new Map(n.map(c=>[c.id,c]));for(const c of L(s.keys(),o.keys())){const a=s.get(c),f=o.get(c),u=`${t}/${r}/${c}`;if(!a||!f){e.push(`${u}: lint ${a?"removed":"added"}`);continue}for(const{compared:S,field:d,kind:b}of R)if(!(!S||d==="id")){if(b==="semantic-array"){Ee(e,u,String(d),a[d],f[d]);continue}F(e,u,String(d),a[d],f[d],b)}}}function ke(e,t,r,i,n){const s=new Map(i.map(c=>[g(c),c])),o=new Map(n.map(c=>[g(c),c]));for(const c of L(s.keys(),o.keys())){const a=s.get(c),f=o.get(c),u=`${t}/${r}/${c}`;if(!a||!f){e.push(`${u}: lint ${a?"removed":"added"}`);continue}for(const{compared:S,field:d,kind:b}of M)!S||d==="id"||d==="series"||d==="simulation"||F(e,u,String(d),a[d],f[d],b)}}function g(e){return`${e.id}/${e.series[0]}+${e.series[1]}/${e.simulation}`}function Te(e,t,r,i){for(const n of L(Object.keys(r),Object.keys(i)))K(e,`${t}/${n}`,r[n],i[n])}function U(e,t,r,i){const n=new Set(r),s=new Set(i);for(const o of L(n,s))n.has(o)!==s.has(o)&&e.push(`${t}/${o}: ${n.has(o)?"removed":"added"}`)}function E(e,t,r,i){const n=new Set(r),s=new Set(i),o=r.filter(a=>s.has(a)),c=i.filter(a=>n.has(a));o.some((a,f)=>a!==c[f])&&e.push(`${t}: order changed`)}function Ee(e,t,r,i,n){const s=Math.max(i.length,n.length);for(let o=0;o<s;o+=1)W(e,t,`${r}[${o}]`,i[o],n[o])}function K(e,t,r,i){r!==i&&e.push(`${t}: ${j(r)} \u2192 ${j(i)}`)}function W(e,t,r,i,n,s){if(!Object.is(i,n)){if(s==="message"){e.push(`${t}: message changed`);return}e.push(`${t}: ${r} ${j(i)} \u2192 ${j(n)}`)}}function Fe(e,t,r,i,n){h(i)!==h(n)&&e.push(`${t}: ${r} changed`)}function F(e,t,r,i,n,s){if(_e(s)){W(e,t,r,i,n,s);return}Fe(e,t,r,i,n)}const Le={anchor:!1,"anchor-record":!1,apca:!1,boolean:!0,"data-palette-record":!1,explicit:!0,"fit-lint-id":!0,"lint-array":!1,message:!0,number:!0,"palette-lint-id":!0,"palette-lint-record":!1,"report-array":!1,scheme:!0,semantic:!0,"semantic-array":!1,"series-pair":!1,simulation:!0,string:!0,"string-array":!1,"token-array":!1,warning:!0};function _e(e){return Le[e]===!0}function j(e){return e===void 0?"(absent)":e===""?'""':String(e)}function L(e,t){return[...new Set([...e,...t])].sort()}function h(e){return Array.isArray(e)?`[${e.map(h).join(",")}]`:p(e)?`{${Object.keys(e).sort().map(t=>`${JSON.stringify(t)}:${h(e[t])}`).join(",")}}`:JSON.stringify(e)??"undefined"}function z(e){const t=m(e,$(k)),r=["light","dark"];if(y(k,"dataPalette")){const i=m(e.dataPalette,r);for(const n of r)l(i,n,m(e.dataPalette[n],w));l(t,"dataPalette",i)}if(y(k,"paletteLints")){const i=m(e.paletteLints,r);for(const n of r)l(i,n,q(e.paletteLints[n],g,$(M)));l(t,"paletteLints",i)}for(const i of r){if(!y(k,i))continue;const n=O();for(const s of e[i]){const o=m(s,$(_));if(y(_,"tokens")){const c=O();for(const a of s.tokens){const f=m(a,$(x));a.anchor&&y(x,"anchor")&&l(f,"anchor",m(a.anchor,$(C))),a.apca&&y(x,"apca")&&l(f,"apca",m(a.apca,$(N))),l(c,a.token,f)}l(o,"tokens",c)}y(_,"lints")&&l(o,"lints",q(s.lints,c=>c.id,$(R))),l(n,s.surface,o)}l(t,i,n)}return t}function q(e,t,r){const i=O();for(const n of e)l(i,t(n),m(n,r));return i}function $(e){return e.filter(({compared:t})=>t).map(({field:t})=>t)}function y(e,t){return e.some(r=>r.field===t&&r.compared)}function m(e,t){const r=new Set(t.map(String)),i=O();for(const[n,s]of Object.entries(e))r.has(n)||(i[n]=s);return i}function O(){return Object.create(null)}function l(e,t,r){Object.keys(r).length>0&&(e[t]=r)}function xe(e,t,r){for(const i of["light","dark"]){for(const n of e.paletteLints[i])r.log(`  ${i} lint(${n.id}): ${n.message}`);for(const n of e[i]){r.log(be(i,n));for(const s of n.lints)r.log(`  lint(${s.id}): ${s.message}`)}}r.log(`Checked ${e.surfaces.length} surface(s) \xD7 2 schemes \u2014 `+(t===0?"no lints.":`${t} lint(s), listed above.`))}function we(e,t,r){r.error(`${t} theme lint(s) are standing while fit-table drift is present:`);for(const i of["light","dark"]){for(const n of e.paletteLints[i])r.error(`lint: ${i}/paletteLints/${g(n)}: ${n.message}`);for(const n of e[i])for(const s of n.lints)r.error(`lint: ${i}/${n.surface}/lints/${s.id}: ${s.message}`)}}function Ae(e){return[...e.light,...e.dark].reduce((r,i)=>r+i.lints.length,0)+e.paletteLints.light.length+e.paletteLints.dark.length}function Ie(e,t){return["light","dark"].some(r=>{const i=`${r}: `;if(!e.startsWith(i))return!1;const n=e.slice(i.length);return t.paletteLints[r].some(s=>ee(n,s))})}function be(e,t){const r=t.adjustedTokens.length===0?"contrast enforcement moved nothing":`contrast enforcement moved ${t.adjustedTokens.join(", ")}`,i=t.tokens.filter(s=>s.explicit==="inherited").length,n=i===0?"":`; ${i} inherited explicit pin(s) \u2014 see the fit tables`;return`${e}/${t.surface}: ${t.tokens.length} tokens, ${r}${n}.`}export{Me as runEspalierCli};

package/dist/index.d.ts

@@ -73,10 +73,10 @@ export * from "./shared/events.js";
 export { getImageDetails, releasePreviewUrl, type EspalierUploadImage, type ImageDetailsOptions, type SelectedUploadImage, type ExistingUploadImage, type ExistingImage, type ResponsiveImageUrl, type UploadCallbacks, type UploadEventDetail, } from "./image-upload/image-helpers.js";
 export { calculatePhotoLayout, type LayoutImage, type PhotoRow, } from "./shared/justified-layout.js";
 export { type TypeaheadFetchItems } from "./pickers/types.js";
-export { type EspalierTheme, type LightnessKey, type LightnessReference, type PartialTheme, type PartialThemeContexts, type PartialThemeTones, type ThemeContext, type ThemeContexts, type ThemeTones, type ToneReference, type VariantColorSource, encodeTheme, parseTheme, mergePartials, layerThemes, validateThemePair, resolveContextTheme, buildTaprootLightTheme, buildTaprootDarkTheme, NESTED_THEME_KEYS, } from "./shared/theme.js";
-export { auditDataPalette, generateSequentialRamp, generateDivergingRamp, COLOR_VISION_SIMULATIONS, DATA_SERIES_KEYS, DEFAULT_DATA_PALETTE, DEFAULT_DATA_RAMP_STEPS, DEFAULT_DIVERGING_NEUTRAL, MAX_DATA_RAMP_STEPS, MIN_DATA_COLOR_DISTANCE, MIN_DATA_RAMP_LIGHTNESS_STEP, MIN_DATA_RAMP_STEPS, type ColorVisionSimulation, type DataPalette, type DataPaletteIssue, type DataRamp, type DataRamps, type DataSeriesKey, type DivergingDataRamp, type DivergingRampOptions, type PartialDataRamp, type PartialDataRamps, type SequentialDataRamp, type SequentialRampOptions, } from "./shared/data-colors.js";
+export { type EspalierTheme, type LightnessKey, type LightnessReference, type PartialTheme, type PartialThemeContexts, type PartialThemeTones, type ThemeContext, type ThemeContexts, type ThemeTones, type ToneReference, type VariantColorSource, encodeTheme, parseTheme, mergePartials, layerThemes, validateThemePair, resolveContextTheme, isObjectRecord, isSemanticColorName, buildTaprootLightTheme, buildTaprootDarkTheme, NESTED_THEME_KEYS, } from "./shared/theme.js";
+export { auditDataPalette, describePaletteCollision, generateSequentialRamp, generateDivergingRamp, COLOR_VISION_SIMULATIONS, DATA_SERIES_KEYS, DEFAULT_DATA_PALETTE, DEFAULT_DATA_RAMP_STEPS, DEFAULT_DIVERGING_NEUTRAL, MAX_DATA_RAMP_STEPS, MIN_DATA_COLOR_DISTANCE, MIN_DATA_RAMP_LIGHTNESS_STEP, MIN_DATA_RAMP_STEPS, type ColorVisionSimulation, type DataPalette, type DataPaletteIssue, type DataRamp, type DataRamps, type DataSeriesKey, type DivergingDataRamp, type DivergingRampOptions, type PartialDataRamp, type PartialDataRamps, type SequentialDataRamp, type SequentialRampOptions, } from "./shared/data-colors.js";
 export { WEIGHT_LABELS, extractWeights, normalizeWeight, bestAvailableWeight, extractFamily, getFallbackFont, } from "./shared/font-helpers.js";
 export { getGoogleFonts } from "./font-picker/esp-font-picker.js";
-export { ROOT_SURFACE, themeFitReport, themeFitRows, themeFitLints, themeFitReportSuite, printThemeFitReport, type ThemeFitReport, type ThemeFitReportOptions, type ThemeFitToken, type ThemeFitApcaAction, type ThemeFitAnchor, type ThemeFitRow, type ThemeFitLint, type ThemeFitSurfaceReport, type ThemeFitSuite, } from "./shared/theme-fit-report.js";
+export { ROOT_SURFACE, THEME_FIT_ANCHOR_FIELDS, THEME_FIT_APCA_FIELDS, THEME_FIT_DATA_PALETTE_LINT_FIELDS, THEME_FIT_DATA_PALETTE_LINT_IDS, THEME_FIT_EXPLICIT_VALUES, THEME_FIT_LINT_FIELDS, THEME_FIT_LINT_IDS, THEME_FIT_LINT_SEVERITIES, THEME_FIT_REPORT_FIELDS, THEME_FIT_SUITE_FIELDS, THEME_FIT_TOKEN_FIELDS, themeFitReport, themeFitRows, themeFitLints, themeFitReportSuite, printThemeFitReport, type ThemeFitReport, type ThemeFitReportOptions, type ThemeFitToken, type ThemeFitApcaAction, type ThemeFitAnchor, type ThemeFitRow, type ThemeFitLint, type ThemeFitDataPaletteLint, type ThemeFitFieldDescriptor, type ThemeFitFieldKind, type ThemeFitSurfaceReport, type ThemeFitSuite, } from "./shared/theme-fit-report.js";
 export { ICON_SPRITE, ICON_SPRITE_ID, installIconSprite } from "./icons/index.js";
 export { deriveLightnessRamp, themeFromSwatches, type ThemeFromSwatchesOptions, type ThemeFromSwatchesResult, } from "./shared/theme-swatches.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"./help/esp-help-button.js";export*from"./help/esp-help-provider.js";export*from"./header/index.js";export*from"./page/esp-page.js";export*from"./section/esp-section.js";export*from"./stack/esp-stack.js";export*from"./row/esp-row.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 _r,DEFAULT_ICON_VIEW_BOX as Er,INTENT_VARIANTS as ir,normalizeIntentVariant as Ar,getIconHrefForHost as lr,getIconSpriteUrl as Ir,getIconSpriteReference as Sr}from"./shared/intent-values.js";import{EspalierElementBase as nr}from"./shared/esp-element-base.js";import{VALIDITY_CHANGED_EVENT as hr}from"./shared/validation.js";import{FormFieldController as Fr}from"./shared/form-field-controller.js";import{traverseToClosest as Lr}from"./shared/utilities.js";import{showToast as Pr}from"./shared/toast-events.js";import{showFlyout as Or,closeFlyout as Cr}from"./shared/flyout-events.js";import{requestHelp as Ur}from"./shared/help-events.js";import{getEspBus as dr}from"./shared/bus-events.js";export*from"./shared/events.js";import{getImageDetails as Vr,releasePreviewUrl as Gr}from"./image-upload/image-helpers.js";import{calculatePhotoLayout as wr}from"./shared/justified-layout.js";import{encodeTheme as Wr,parseTheme as Br,mergePartials as Yr,layerThemes as kr,validateThemePair as qr,resolveContextTheme as zr,buildTaprootLightTheme as Kr,buildTaprootDarkTheme as Xr,NESTED_THEME_KEYS as jr}from"./shared/theme.js";import{auditDataPalette as Qr,generateSequentialRamp as Zr,generateDivergingRamp as $r,COLOR_VISION_SIMULATIONS as ro,DATA_SERIES_KEYS as oo,DEFAULT_DATA_PALETTE as eo,DEFAULT_DATA_RAMP_STEPS as to,DEFAULT_DIVERGING_NEUTRAL as mo,MAX_DATA_RAMP_STEPS as po,MIN_DATA_COLOR_DISTANCE as xo,MIN_DATA_RAMP_LIGHTNESS_STEP as fo,MIN_DATA_RAMP_STEPS as To}from"./shared/data-colors.js";import{WEIGHT_LABELS as _o,extractWeights as Eo,normalizeWeight as io,bestAvailableWeight as Ao,extractFamily as lo,getFallbackFont as Io}from"./shared/font-helpers.js";import{getGoogleFonts as so}from"./font-picker/esp-font-picker.js";import{ROOT_SURFACE as Ro,themeFitReport as ho,themeFitRows as Do,themeFitLints as Fo,themeFitReportSuite as go,printThemeFitReport as Lo}from"./shared/theme-fit-report.js";import{ICON_SPRITE as Po,ICON_SPRITE_ID as co,installIconSprite as Oo}from"./icons/index.js";import{deriveLightnessRamp as uo,themeFromSwatches as Uo}from"./shared/theme-swatches.js";export{ro as COLOR_VISION_SIMULATIONS,oo as DATA_SERIES_KEYS,eo as DEFAULT_DATA_PALETTE,to as DEFAULT_DATA_RAMP_STEPS,mo as DEFAULT_DIVERGING_NEUTRAL,_r as DEFAULT_ICON_SPRITE_URL,Er as DEFAULT_ICON_VIEW_BOX,nr as EspalierElementBase,Fr as FormFieldController,Po as ICON_SPRITE,co as ICON_SPRITE_ID,ir as INTENT_VARIANTS,po as MAX_DATA_RAMP_STEPS,xo as MIN_DATA_COLOR_DISTANCE,fo as MIN_DATA_RAMP_LIGHTNESS_STEP,To as MIN_DATA_RAMP_STEPS,jr as NESTED_THEME_KEYS,Ro as ROOT_SURFACE,hr as VALIDITY_CHANGED_EVENT,_o as WEIGHT_LABELS,Qr as auditDataPalette,Ao as bestAvailableWeight,Xr as buildTaprootDarkTheme,Kr as buildTaprootLightTheme,wr as calculatePhotoLayout,Cr as closeFlyout,uo as deriveLightnessRamp,Wr as encodeTheme,lo as extractFamily,Eo as extractWeights,$r as generateDivergingRamp,Zr as generateSequentialRamp,dr as getEspBus,Io as getFallbackFont,so as getGoogleFonts,lr as getIconHrefForHost,Sr as getIconSpriteReference,Ir as getIconSpriteUrl,Vr as getImageDetails,Oo as installIconSprite,kr as layerThemes,Yr as mergePartials,Ar as normalizeIntentVariant,io as normalizeWeight,Br as parseTheme,Lo as printThemeFitReport,Gr as releasePreviewUrl,Ur as requestHelp,zr as resolveContextTheme,Or as showFlyout,Pr as showToast,Fo as themeFitLints,ho as themeFitReport,go as themeFitReportSuite,Do as themeFitRows,Uo as themeFromSwatches,Lr as traverseToClosest,qr as validateThemePair};
+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"./help/esp-help-button.js";export*from"./help/esp-help-provider.js";export*from"./header/index.js";export*from"./page/esp-page.js";export*from"./section/esp-section.js";export*from"./stack/esp-stack.js";export*from"./row/esp-row.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 _o,DEFAULT_ICON_VIEW_BOX as Io,INTENT_VARIANTS as ao,normalizeIntentVariant as Ao,getIconHrefForHost as So,getIconSpriteUrl as io,getIconSpriteReference as Fo}from"./shared/intent-values.js";import{EspalierElementBase as Lo}from"./shared/esp-element-base.js";import{VALIDITY_CHANGED_EVENT as so}from"./shared/validation.js";import{FormFieldController as No}from"./shared/form-field-controller.js";import{traverseToClosest as Po}from"./shared/utilities.js";import{showToast as Mo}from"./shared/toast-events.js";import{showFlyout as Ho,closeFlyout as co}from"./shared/flyout-events.js";import{requestHelp as Oo}from"./shared/help-events.js";import{getEspBus as uo}from"./shared/bus-events.js";export*from"./shared/events.js";import{getImageDetails as vo,releasePreviewUrl as Go}from"./image-upload/image-helpers.js";import{calculatePhotoLayout as yo}from"./shared/justified-layout.js";import{encodeTheme as Bo,parseTheme as Ko,mergePartials as Xo,layerThemes as Yo,validateThemePair as ko,resolveContextTheme as qo,isObjectRecord as zo,isSemanticColorName as jo,buildTaprootLightTheme as Jo,buildTaprootDarkTheme as Qo,NESTED_THEME_KEYS as Zo}from"./shared/theme.js";import{auditDataPalette as or,describePaletteCollision as rr,generateSequentialRamp as er,generateDivergingRamp as tr,COLOR_VISION_SIMULATIONS as mr,DATA_SERIES_KEYS as pr,DEFAULT_DATA_PALETTE as xr,DEFAULT_DATA_RAMP_STEPS as Tr,DEFAULT_DIVERGING_NEUTRAL as fr,MAX_DATA_RAMP_STEPS as Er,MIN_DATA_COLOR_DISTANCE as _r,MIN_DATA_RAMP_LIGHTNESS_STEP as Ir,MIN_DATA_RAMP_STEPS as ar}from"./shared/data-colors.js";import{WEIGHT_LABELS as Sr,extractWeights as ir,normalizeWeight as Fr,bestAvailableWeight as lr,extractFamily as Lr,getFallbackFont as Dr}from"./shared/font-helpers.js";import{getGoogleFonts as Rr}from"./font-picker/esp-font-picker.js";import{ROOT_SURFACE as nr,THEME_FIT_ANCHOR_FIELDS as Pr,THEME_FIT_APCA_FIELDS as hr,THEME_FIT_DATA_PALETTE_LINT_FIELDS as Mr,THEME_FIT_DATA_PALETTE_LINT_IDS as gr,THEME_FIT_EXPLICIT_VALUES as Hr,THEME_FIT_LINT_FIELDS as cr,THEME_FIT_LINT_IDS as Cr,THEME_FIT_LINT_SEVERITIES as Or,THEME_FIT_REPORT_FIELDS as Ur,THEME_FIT_SUITE_FIELDS as ur,THEME_FIT_TOKEN_FIELDS as dr,themeFitReport as Vr,themeFitRows as br,themeFitLints as vr,themeFitReportSuite as Gr,printThemeFitReport as wr}from"./shared/theme-fit-report.js";import{ICON_SPRITE as Wr,ICON_SPRITE_ID as Br,installIconSprite as Kr}from"./icons/index.js";import{deriveLightnessRamp as Yr,themeFromSwatches as kr}from"./shared/theme-swatches.js";export{mr as COLOR_VISION_SIMULATIONS,pr as DATA_SERIES_KEYS,xr as DEFAULT_DATA_PALETTE,Tr as DEFAULT_DATA_RAMP_STEPS,fr as DEFAULT_DIVERGING_NEUTRAL,_o as DEFAULT_ICON_SPRITE_URL,Io as DEFAULT_ICON_VIEW_BOX,Lo as EspalierElementBase,No as FormFieldController,Wr as ICON_SPRITE,Br as ICON_SPRITE_ID,ao as INTENT_VARIANTS,Er as MAX_DATA_RAMP_STEPS,_r as MIN_DATA_COLOR_DISTANCE,Ir as MIN_DATA_RAMP_LIGHTNESS_STEP,ar as MIN_DATA_RAMP_STEPS,Zo as NESTED_THEME_KEYS,nr as ROOT_SURFACE,Pr as THEME_FIT_ANCHOR_FIELDS,hr as THEME_FIT_APCA_FIELDS,Mr as THEME_FIT_DATA_PALETTE_LINT_FIELDS,gr as THEME_FIT_DATA_PALETTE_LINT_IDS,Hr as THEME_FIT_EXPLICIT_VALUES,cr as THEME_FIT_LINT_FIELDS,Cr as THEME_FIT_LINT_IDS,Or as THEME_FIT_LINT_SEVERITIES,Ur as THEME_FIT_REPORT_FIELDS,ur as THEME_FIT_SUITE_FIELDS,dr as THEME_FIT_TOKEN_FIELDS,so as VALIDITY_CHANGED_EVENT,Sr as WEIGHT_LABELS,or as auditDataPalette,lr as bestAvailableWeight,Qo as buildTaprootDarkTheme,Jo as buildTaprootLightTheme,yo as calculatePhotoLayout,co as closeFlyout,Yr as deriveLightnessRamp,rr as describePaletteCollision,Bo as encodeTheme,Lr as extractFamily,ir as extractWeights,tr as generateDivergingRamp,er as generateSequentialRamp,uo as getEspBus,Dr as getFallbackFont,Rr as getGoogleFonts,So as getIconHrefForHost,Fo as getIconSpriteReference,io as getIconSpriteUrl,vo as getImageDetails,Kr as installIconSprite,zo as isObjectRecord,jo as isSemanticColorName,Yo as layerThemes,Xo as mergePartials,Ao as normalizeIntentVariant,Fr as normalizeWeight,Ko as parseTheme,wr as printThemeFitReport,Go as releasePreviewUrl,Oo as requestHelp,qo as resolveContextTheme,Ho as showFlyout,Mo as showToast,vr as themeFitLints,Vr as themeFitReport,Gr as themeFitReportSuite,br as themeFitRows,kr as themeFromSwatches,Po as traverseToClosest,ko as validateThemePair};

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

@@ -116,6 +116,12 @@ export type { SchemeEvents } from "../shared/bus-events.js";
  * @cssprop --esp-type-caption-font-weight - Font weight for captions.
  * @cssprop --esp-type-caption-letter-spacing - Letter spacing for captions.
  * @cssprop --esp-type-caption-color - Context-local color alias for captions.
+ * @cssprop --esp-type-display-font-family - Heading font family for opt-in display text.
+ * @cssprop --esp-type-display-font-size - Fluid display size spanning the large mobile floor through the huge desktop ceiling.
+ * @cssprop --esp-type-display-font-weight - Heading font weight for opt-in display text.
+ * @cssprop --esp-type-display-line-height - Line height for opt-in display text.
+ * @cssprop --esp-type-display-letter-spacing - Letter spacing for opt-in display text.
+ * @cssprop --esp-type-display-color - Context-local heading-color alias for opt-in display text.
  *
  * @docPageTitle Root
  * @docUrl /components/root

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

@@ -31,6 +31,28 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  * and drop `--esp-section-padding-block` too when the media should
  * meet the band's edges; the band's zone behavior is unaffected.
  *
+ * A section may also tint one raster alpha mask behind its content.
+ * The component owns clipping, no-repeat mask behavior, stacking, and
+ * interaction isolation; consumers supply only the image, semantic tint,
+ * position, size, and opacity:
+ *
+ * ```html
+ * <esp-section
+ *   style="
+ *     --esp-section-decoration-image: url('/assets/brand-mark.png');
+ *     --esp-section-decoration-position: calc(100% + 2rem) -2rem;
+ *     --esp-section-decoration-size: min(34rem, 62%);
+ *     --esp-section-decoration-opacity: 0.09;
+ *   "
+ * >
+ *   <h1>Rooted in warmth</h1>
+ * </esp-section>
+ * ```
+ *
+ * CSS image values are trusted stylesheet input. Products that accept image
+ * references from documents or users must enforce their own asset ownership
+ * and URL policy before mapping a value to this hook.
+ *
  * @customElement esp-section
  * @slot - The section's content, centered in the well.
  * @csspart section - The full-bleed band.
@@ -39,6 +61,11 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  * @cssprop --esp-section-max-width - The content well's cap. Defaults to `var(--esp-page-well-max-width, 72rem)`; `none` lets content span the band.
  * @cssprop --esp-section-padding-block - Vertical rhythm above and below the well. Defaults to `var(--esp-size-section)`.
  * @cssprop --esp-section-padding-inline - Horizontal breathing room inside the band at narrow viewports. Defaults to `var(--esp-size-medium)`.
+ * @cssprop --esp-section-decoration-image - Raster alpha mask painted behind the well. Defaults to `none`.
+ * @cssprop --esp-section-decoration-color - Semantic tint applied through the mask. Defaults to the local `--esp-color-headings`.
+ * @cssprop --esp-section-decoration-position - Mask position, including responsive or bleeding values. Defaults to `center`.
+ * @cssprop --esp-section-decoration-size - Mask size. Defaults to `contain`.
+ * @cssprop --esp-section-decoration-opacity - Decoration opacity from `0` through `1`. Defaults to `1`.
  * @docPageTitle Section
  * @docUrl /components/section
  * @menuGroup Structure

package/dist/section/esp-section.js

@@ -1,5 +1,6 @@
-var a=function(t,i,s,n){var o=arguments.length,e=o<3?i:n===null?n=Object.getOwnPropertyDescriptor(i,s):n,l;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")e=Reflect.decorate(t,i,s,n);else for(var c=t.length-1;c>=0;c--)(l=t[c])&&(e=(o<3?l(e):o>3?l(i,s,e):l(i,s))||e);return o>3&&e&&Object.defineProperty(i,s,e),e};import{css as d,html as m}from"lit";import{customElement as v}from"lit/decorators.js";import{EspalierElementBase as p}from"../shared/esp-element-base.js";let r=class extends p{render(){return m`
+var c=function(i,o,t,n){var a=arguments.length,e=a<3?o:n===null?n=Object.getOwnPropertyDescriptor(o,t):n,s;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")e=Reflect.decorate(i,o,t,n);else for(var l=i.length-1;l>=0;l--)(s=i[l])&&(e=(a<3?s(e):a>3?s(o,t,e):s(o,t))||e);return a>3&&e&&Object.defineProperty(o,t,e),e};import{css as d,html as v}from"lit";import{customElement as m}from"lit/decorators.js";import{EspalierElementBase as p}from"../shared/esp-element-base.js";import{renderVisualOverlay as u,visualOverlayStyles as y}from"../shared/visual-overlay.js";let r=class extends p{render(){return v`
       <div class="esp-section" part="section">
+        ${u({className:"decoration"})}
         <div class="esp-section-well" part="well">
           <slot></slot>
         </div>
@@ -11,12 +12,32 @@ var a=function(t,i,s,n){var o=arguments.length,e=o<3?i:n===null?n=Object.getOwnP
 
       .esp-section {
         background: var(--esp-section-background, var(--esp-color-background));
+        isolation: isolate;
         padding-block: var(--esp-section-padding-block, var(--esp-size-section));
         padding-inline: var(--esp-section-padding-inline, var(--esp-size-medium));
+        position: relative;
+      }
+
+      .decoration {
+        --_esp-overlay-z-index: 0;
+        --_esp-overlay-texture: none;
+        --_esp-overlay-texture-color: var(
+          --esp-section-decoration-color,
+          var(--esp-color-headings)
+        );
+        
+        --_esp-overlay-texture-mask:
+          var(--esp-section-decoration-image, none), linear-gradient(transparent, transparent);
+        --_esp-overlay-texture-mask-position: var(--esp-section-decoration-position, center);
+        --_esp-overlay-texture-mask-repeat: no-repeat;
+        --_esp-overlay-texture-mask-size: var(--esp-section-decoration-size, contain);
+        --_esp-overlay-texture-opacity: var(--esp-section-decoration-opacity, 1);
       }
 
       .esp-section-well {
         max-inline-size: var(--esp-section-max-width, var(--esp-page-well-max-width, 72rem));
         margin-inline: auto;
+        position: relative;
+        z-index: 1;
       }
-    `],r=a([v("esp-section")],r);export{r as EspalierSection};
+    `,y],r=c([m("esp-section")],r);export{r as EspalierSection};

package/dist/shared/data-colors.d.ts

@@ -44,6 +44,20 @@ export interface DataPaletteIssue {
     /** The threshold the pair was checked against. */
     threshold: number;
 }
+/**
+ * Describe one categorical-palette collision in the shared validation
+ * vocabulary. Runtime validation and fit-table lints both use this formatter;
+ * the co-located matcher below deliberately ignores numeric measurements while
+ * preserving the pair and simulation identity.
+ */
+export declare function describePaletteCollision(issue: DataPaletteIssue): string;
+/**
+ * Match a formatted collision by its stable pair and simulation, deliberately
+ * ignoring the displayed measurement. Validation audits authored colors while
+ * fit tables audit emitted gamut-mapped colors, so their rounded distances can
+ * differ without representing two findings.
+ */
+export declare function isPaletteCollisionDescription(description: string, issue: Pick<DataPaletteIssue, "series" | "simulation">): boolean;
 /**
  * Audit every categorical pair after full CVD simulation.
  *

package/dist/shared/data-colors.js

@@ -1 +1 @@
-import{clampChannel as x,gamutMapToSRGB as m,linearRgbToOklab as S,oklabToOklch as k,oklchToOklab as b,oklchToSRGB as P,parseCssColor as F,serializeOklch as E,srgbToLinearRGB as q}from"./color-engine.js";const p=["series1","series2","series3","series4","series5","series6","series7","series8"],G={series1:"#000000",series2:"#E69F00",series3:"#56B4E9",series4:"#009E73",series5:"#F0E442",series6:"#0072B2",series7:"#D55E00",series8:"#CC79A7"},A=["deuteranopia","protanopia","tritanopia"],T=.07,_={protanopia:[[.152286,1.052583,-.204868],[.114503,.786281,.099216],[-.003882,-.048116,1.051998]],deuteranopia:[[.367322,.860646,-.227968],[.280085,.672501,.047413],[-.01182,.04294,.968881]],tritanopia:[[1.255528,-.076749,-.178779],[-.078411,.930809,.147602],[.004733,.691367,.3039]]};function d(e,t){const s=P(m(e)),a=q(s),n=o=>x(o[0]*a.r+o[1]*a.g+o[2]*a.b);return{r:n(t[0]),g:n(t[1]),b:n(t[2])}}function R(e,t){return Math.hypot(e.L-t.L,e.a-t.a,e.b-t.b)}function g(e,t){const s=F(e);if(!s)throw new TypeError(`${t} is not a valid opaque CSS color: "${e}".`);return s}function U(e,t=T){if(!Number.isFinite(t)||t<0)throw new RangeError("Data-palette distance threshold must be a finite number \u2265 0.");const s=new Map;for(const n of p)s.set(n,g(e[n],`dataPalette.${n}`));const a=[];for(const n of A){const o=new Map;for(const r of p)o.set(r,S(d(s.get(r),_[n])));for(let r=0;r<p.length;r+=1)for(let i=r+1;i<p.length;i+=1){const l=p[r],c=p[i],u=R(o.get(l),o.get(c));u<t&&a.push({series:[l,c],simulation:n,distance:u,threshold:t})}}return a}const v=[[1,0,0],[0,1,0],[0,0,1]];function B(e,t=T,s=["normal",...A]){if(!Number.isFinite(t)||t<0)throw new RangeError("Color distance threshold must be a finite number \u2265 0.");const a=e.map(([r,i])=>[r,g(i,r)]),n=[],o=s.map(r=>[r,r==="normal"?v:_[r]]);for(const[r,i]of o){const l=a.map(([,c])=>S(d(c,i)));for(let c=0;c<e.length;c+=1)for(let u=c+1;u<e.length;u+=1){const f=R(l[c],l[u]);f<t&&n.push({pair:[e[c][0],e[u][0]],simulation:r,distance:f,threshold:t})}}return n}const D=3,I=11,L=7,C=1e-6,$="oklch(0.96 0 0)";function M(e,t){if(!Number.isInteger(e)||e<D||e>I)throw new RangeError(`Data-ramp steps must be an integer from ${D} through ${I}.`);if(t&&e%2===0)throw new RangeError("Diverging data-ramp steps must be odd so the neutral is the midpoint.")}function w(e,t){if(!Number.isFinite(e)||e<0||e>1)throw new RangeError(`${t} must be a finite number from 0 through 1.`)}function V(e,t={}){const s=g(e,"Sequential ramp source"),a=t.steps??L,n=t.lightnessStart??.95,o=t.lightnessEnd??.25;if(M(a,!1),w(n,"Sequential ramp lightnessStart"),w(o,"Sequential ramp lightnessEnd"),n<=o)throw new RangeError("Sequential ramp lightnessStart must be greater than lightnessEnd.");if((n-o)/(a-1)<=C)throw new RangeError(`Sequential ramp lightness bounds must leave more than ${C} lightness between serialized stops.`);return Array.from({length:a},(r,i)=>{const l=i/(a-1),c=n+(o-n)*l;return E(m({l:c,c:s.c,h:s.h}))})}function N(e,t,s){return{L:e.L+(t.L-e.L)*s,a:e.a+(t.a-e.a)*s,b:e.b+(t.b-e.b)*s}}function z(e,t,s={}){const a=g(e,"Diverging ramp start"),n=g(t,"Diverging ramp end"),o=g(s.neutral??$,"Diverging ramp neutral"),r=s.steps??L;M(r,!0);const i=(r-1)/2,l=b(a),c=b(o),u=b(n);return Array.from({length:r},(f,h)=>{if(h===i)return E(m(o));const O=h<i?N(l,c,h/i):N(c,u,(h-i)/i);return E(m(k(O)))})}export{A as COLOR_VISION_SIMULATIONS,p as DATA_SERIES_KEYS,G as DEFAULT_DATA_PALETTE,L as DEFAULT_DATA_RAMP_STEPS,$ as DEFAULT_DIVERGING_NEUTRAL,I as MAX_DATA_RAMP_STEPS,T as MIN_DATA_COLOR_DISTANCE,C as MIN_DATA_RAMP_LIGHTNESS_STEP,D as MIN_DATA_RAMP_STEPS,B as auditColorDistances,U as auditDataPalette,z as generateDivergingRamp,V as generateSequentialRamp};
+import{clampChannel as N,gamutMapToSRGB as m,linearRgbToOklab as E,oklabToOklch as $,oklchToOklab as f,oklchToSRGB as O,parseCssColor as k,serializeOklch as b,srgbToLinearRGB as F}from"./color-engine.js";const p=["series1","series2","series3","series4","series5","series6","series7","series8"],G={series1:"#000000",series2:"#E69F00",series3:"#56B4E9",series4:"#009E73",series5:"#F0E442",series6:"#0072B2",series7:"#D55E00",series8:"#CC79A7"},S=["deuteranopia","protanopia","tritanopia"],A=.07;function U(t){return`dataPalette.${t.series[0]} and dataPalette.${t.series[1]} are only ${t.distance.toFixed(4)} apart under ${t.simulation} simulation (minimum ${t.threshold.toFixed(4)}); also distinguish the series with labels, shapes, or patterns.`}function B(t,e){return t.startsWith(`dataPalette.${e.series[0]} and dataPalette.${e.series[1]} are only `)&&t.includes(` apart under ${e.simulation} simulation `)}const T={protanopia:[[.152286,1.052583,-.204868],[.114503,.786281,.099216],[-.003882,-.048116,1.051998]],deuteranopia:[[.367322,.860646,-.227968],[.280085,.672501,.047413],[-.01182,.04294,.968881]],tritanopia:[[1.255528,-.076749,-.178779],[-.078411,.930809,.147602],[.004733,.691367,.3039]]};function _(t,e){const s=O(m(t)),o=F(s),n=a=>N(a[0]*o.r+a[1]*o.g+a[2]*o.b);return{r:n(e[0]),g:n(e[1]),b:n(e[2])}}function R(t,e){return Math.hypot(t.L-e.L,t.a-e.a,t.b-e.b)}function g(t,e){const s=k(t);if(!s)throw new TypeError(`${e} is not a valid opaque CSS color: "${t}".`);return s}function V(t,e=A){if(!Number.isFinite(e)||e<0)throw new RangeError("Data-palette distance threshold must be a finite number \u2265 0.");const s=new Map;for(const n of p)s.set(n,g(t[n],`dataPalette.${n}`));const o=[];for(const n of S){const a=new Map;for(const r of p)a.set(r,E(_(s.get(r),T[n])));for(let r=0;r<p.length;r+=1)for(let i=r+1;i<p.length;i+=1){const c=p[r],l=p[i],u=R(a.get(c),a.get(l));u<e&&o.push({series:[c,l],simulation:n,distance:u,threshold:e})}}return o}const y=[[1,0,0],[0,1,0],[0,0,1]];function z(t,e=A,s=["normal",...S]){if(!Number.isFinite(e)||e<0)throw new RangeError("Color distance threshold must be a finite number \u2265 0.");const o=t.map(([r,i])=>[r,g(i,r)]),n=[],a=s.map(r=>[r,r==="normal"?y:T[r]]);for(const[r,i]of a){const c=o.map(([,l])=>E(_(l,i)));for(let l=0;l<t.length;l+=1)for(let u=l+1;u<t.length;u+=1){const d=R(c[l],c[u]);d<e&&n.push({pair:[t[l][0],t[u][0]],simulation:r,distance:d,threshold:e})}}return n}const D=3,I=11,L=7,C=1e-6,q="oklch(0.96 0 0)";function w(t,e){if(!Number.isInteger(t)||t<D||t>I)throw new RangeError(`Data-ramp steps must be an integer from ${D} through ${I}.`);if(e&&t%2===0)throw new RangeError("Diverging data-ramp steps must be odd so the neutral is the midpoint.")}function M(t,e){if(!Number.isFinite(t)||t<0||t>1)throw new RangeError(`${e} must be a finite number from 0 through 1.`)}function X(t,e={}){const s=g(t,"Sequential ramp source"),o=e.steps??L,n=e.lightnessStart??.95,a=e.lightnessEnd??.25;if(w(o,!1),M(n,"Sequential ramp lightnessStart"),M(a,"Sequential ramp lightnessEnd"),n<=a)throw new RangeError("Sequential ramp lightnessStart must be greater than lightnessEnd.");if((n-a)/(o-1)<=C)throw new RangeError(`Sequential ramp lightness bounds must leave more than ${C} lightness between serialized stops.`);return Array.from({length:o},(r,i)=>{const c=i/(o-1),l=n+(a-n)*c;return b(m({l,c:s.c,h:s.h}))})}function x(t,e,s){return{L:t.L+(e.L-t.L)*s,a:t.a+(e.a-t.a)*s,b:t.b+(e.b-t.b)*s}}function H(t,e,s={}){const o=g(t,"Diverging ramp start"),n=g(e,"Diverging ramp end"),a=g(s.neutral??q,"Diverging ramp neutral"),r=s.steps??L;w(r,!0);const i=(r-1)/2,c=f(o),l=f(a),u=f(n);return Array.from({length:r},(d,h)=>{if(h===i)return b(m(a));const P=h<i?x(c,l,h/i):x(l,u,(h-i)/i);return b(m($(P)))})}export{S as COLOR_VISION_SIMULATIONS,p as DATA_SERIES_KEYS,G as DEFAULT_DATA_PALETTE,L as DEFAULT_DATA_RAMP_STEPS,q as DEFAULT_DIVERGING_NEUTRAL,I as MAX_DATA_RAMP_STEPS,A as MIN_DATA_COLOR_DISTANCE,C as MIN_DATA_RAMP_LIGHTNESS_STEP,D as MIN_DATA_RAMP_STEPS,z as auditColorDistances,V as auditDataPalette,U as describePaletteCollision,H as generateDivergingRamp,X as generateSequentialRamp,B as isPaletteCollisionDescription};

package/dist/shared/scale-engine.js

@@ -1 +1 @@
-const l=["tiny","small","normal","medium","big","large","huge"],O=2,b=1.125,g=1.3333333333333333,f=[["tiny","small"],["small","normal"],["normal","medium"],["medium","big"],["big","large"],["large","huge"]],E=.375,z={rootFontSize:16,typeRatio:1.25,spaceRatio:1.618,borderRadius:.2,viewportMin:320,viewportMax:1200};function c(o,e=4){const t=10**e;return Math.round(o*t)/t}function d(o,e,t,s,p){if(Math.abs(e-o)<1e-4)return`${c(o)}rem`;const m=(e-o)*t*100/(p-s),n=o-m*s/(100*t);return`clamp(${c(o)}rem, ${c(n)}rem + ${c(m)}vw, ${c(e)}rem)`}function h(o){const e={};for(let t=0;t<l.length;t++){const s=t-2,p=1.125*o.typeRatio**s;e[l[t]]={min:p,max:p*g}}return e}function x(o){const e={};for(let t=0;t<l.length;t++){const s=E*o.spaceRatio**t;e[l[t]]={min:s,max:s*g}}return e}const S={"--esp-shadow-1":"1px 1px 4px var(--esp-color-shadow)","--esp-shadow-2":"0 2px 8px var(--esp-color-shadow)","--esp-shadow-3":"0 6px 20px var(--esp-color-shadow)"},_={"--esp-type-overline-color":"var(--esp-color-type-overline, var(--esp-color-text))","--esp-type-label-color":"var(--esp-color-type-label, var(--esp-color-text))","--esp-type-lead-color":"var(--esp-color-type-lead, var(--esp-color-text))","--esp-type-caption-color":"var(--esp-color-type-caption, var(--esp-color-text))"},w={"--esp-type-overline-font-size":"var(--esp-type-tiny)","--esp-type-overline-font-weight":"var(--esp-font-weight-headings)","--esp-type-overline-letter-spacing":"0.08em","--esp-type-overline-text-transform":"uppercase","--esp-type-label-font-size":"var(--esp-type-normal)","--esp-type-label-font-weight":"var(--esp-font-weight-headings)","--esp-type-label-letter-spacing":"0.01em","--esp-type-lead-font-size":"var(--esp-type-medium)","--esp-type-lead-font-weight":"var(--esp-font-weight-body)","--esp-type-lead-letter-spacing":"normal","--esp-type-caption-font-size":"var(--esp-type-small)","--esp-type-caption-font-weight":"var(--esp-font-weight-body)","--esp-type-caption-letter-spacing":"normal",..._};function P(o){const e={},{rootFontSize:t,viewportMin:s,viewportMax:p,borderRadius:m}=o,n=16,a=t/n,u=h(o);for(const r of l){const{min:i,max:v}=u[r];e[`--esp-type-${r}`]=d(i*a,v*a,n,s,p)}Object.assign(e,w);const y=x(o);for(const r of l){const{min:i,max:v}=y[r];e[`--esp-size-${r}`]=d(i*a,v*a,n,s,p)}for(const[r,i]of f)e[`--esp-size-${r}-to-${i}`]=d(y[r].min*a,y[i].max*a,n,s,p);return e["--esp-size-font"]="var(--esp-type-normal)",e["--esp-size-padding"]="var(--esp-size-tiny-to-small)",e["--esp-size-padding-page"]="var(--esp-size-small-to-normal)",e["--esp-size-border-radius"]=`${c(m*a)}rem`,e["--esp-measure"]="66ch",e["--esp-measure-wide"]="90ch",e["--esp-size-section"]="clamp(var(--esp-size-big), 7vw, var(--esp-size-huge))",Object.assign(e,S),e["--esp-card-min"]="16rem",e}export{z as DEFAULT_SCALE_CONFIG,S as ELEVATION_PROPERTIES,l as STEP_NAMES,_ as TYPE_ROLE_COLOR_PROPERTIES,w as TYPE_ROLE_PROPERTIES,P as generateScaleProperties};
+const l=["tiny","small","normal","medium","big","large","huge"],O=2,b=1.125,f=1.3333333333333333,h=[["tiny","small"],["small","normal"],["normal","medium"],["medium","big"],["big","large"],["large","huge"]],u=.375,z={rootFontSize:16,typeRatio:1.25,spaceRatio:1.618,borderRadius:.2,viewportMin:320,viewportMax:1200};function c(s,e=4){const t=10**e;return Math.round(s*t)/t}function m(s,e,t,p,o){if(Math.abs(e-s)<1e-4)return`${c(s)}rem`;const y=(e-s)*t*100/(o-p),n=s-y*p/(100*t);return`clamp(${c(s)}rem, ${c(n)}rem + ${c(y)}vw, ${c(e)}rem)`}function E(s){const e={};for(let t=0;t<l.length;t++){const p=t-2,o=1.125*s.typeRatio**p;e[l[t]]={min:o,max:o*f}}return e}function x(s){const e={};for(let t=0;t<l.length;t++){const p=u*s.spaceRatio**t;e[l[t]]={min:p,max:p*f}}return e}const w={"--esp-shadow-1":"1px 1px 4px var(--esp-color-shadow)","--esp-shadow-2":"0 2px 8px var(--esp-color-shadow)","--esp-shadow-3":"0 6px 20px var(--esp-color-shadow)"},S={"--esp-type-overline-color":"var(--esp-color-type-overline, var(--esp-color-text))","--esp-type-label-color":"var(--esp-color-type-label, var(--esp-color-text))","--esp-type-lead-color":"var(--esp-color-type-lead, var(--esp-color-text))","--esp-type-caption-color":"var(--esp-color-type-caption, var(--esp-color-text))","--esp-type-display-color":"var(--esp-color-headings, var(--esp-color-text))"},_={"--esp-type-overline-font-size":"var(--esp-type-tiny)","--esp-type-overline-font-weight":"var(--esp-font-weight-headings)","--esp-type-overline-letter-spacing":"0.08em","--esp-type-overline-text-transform":"uppercase","--esp-type-label-font-size":"var(--esp-type-normal)","--esp-type-label-font-weight":"var(--esp-font-weight-headings)","--esp-type-label-letter-spacing":"0.01em","--esp-type-lead-font-size":"var(--esp-type-medium)","--esp-type-lead-font-weight":"var(--esp-font-weight-body)","--esp-type-lead-letter-spacing":"normal","--esp-type-caption-font-size":"var(--esp-type-small)","--esp-type-caption-font-weight":"var(--esp-font-weight-body)","--esp-type-caption-letter-spacing":"normal","--esp-type-display-font-family":"var(--esp-font-headings)","--esp-type-display-font-weight":"var(--esp-font-weight-headings)","--esp-type-display-line-height":"1.1","--esp-type-display-letter-spacing":"normal",...S};function P(s){const e={},{rootFontSize:t,viewportMin:p,viewportMax:o,borderRadius:y}=s,n=16,r=t/n,d=E(s);for(const a of l){const{min:i,max:v}=d[a];e[`--esp-type-${a}`]=m(i*r,v*r,n,p,o)}e["--esp-type-display-font-size"]=m(d.large.min*r,d.huge.max*r,n,p,o),Object.assign(e,_);const g=x(s);for(const a of l){const{min:i,max:v}=g[a];e[`--esp-size-${a}`]=m(i*r,v*r,n,p,o)}for(const[a,i]of h)e[`--esp-size-${a}-to-${i}`]=m(g[a].min*r,g[i].max*r,n,p,o);return e["--esp-size-font"]="var(--esp-type-normal)",e["--esp-size-padding"]="var(--esp-size-tiny-to-small)",e["--esp-size-padding-page"]="var(--esp-size-small-to-normal)",e["--esp-size-border-radius"]=`${c(y*r)}rem`,e["--esp-measure"]="66ch",e["--esp-measure-wide"]="90ch",e["--esp-size-section"]="clamp(var(--esp-size-big), 7vw, var(--esp-size-huge))",Object.assign(e,w),e["--esp-card-min"]="16rem",e}export{z as DEFAULT_SCALE_CONFIG,w as ELEVATION_PROPERTIES,l as STEP_NAMES,S as TYPE_ROLE_COLOR_PROPERTIES,_ as TYPE_ROLE_PROPERTIES,P as generateScaleProperties};

package/dist/shared/theme-fit-report.d.ts

@@ -48,6 +48,7 @@
  * report.adjustedTokens;                // ['linkHover']
  * ```
  */
+import { type ColorVisionSimulation, type DataPalette, type DataSeriesKey } from "./data-colors.js";
 import { type EspalierTheme, type LightnessReference, type MappingSource, type PartialTheme, type SemanticColorName } from "./theme.js";
 /** What APCA enforcement did to one token. */
 export interface ThemeFitApcaAction {
@@ -193,6 +194,51 @@ export interface ThemeFitLint {
     /** Human-readable finding, with the remedy phrased as a retune. */
     message: string;
 }
+/** One scheme-level categorical-palette collision. */
+export interface ThemeFitDataPaletteLint {
+    /** Stable lint identifier. */
+    id: "data-palette-cvd-collision";
+    /** The metric is advisory, but the named theme-check lint is gated. */
+    severity: "warning";
+    /** The two stable palette slots whose simulated colors are too close. */
+    series: readonly [DataSeriesKey, DataSeriesKey];
+    /** The simulated color-vision deficiency under which they collide. */
+    simulation: ColorVisionSimulation;
+    /** The measured OKLab distance, rounded for stable JSON. */
+    measured: number;
+    /** The minimum distance the pair was checked against. */
+    threshold: number;
+    /** Human-readable finding with the redundant-coding remedy. */
+    message: string;
+}
+/** Runtime validation/comparison vocabulary used by the exported field descriptors. */
+export type ThemeFitFieldKind = "anchor" | "anchor-record" | "apca" | "boolean" | "data-palette-record" | "explicit" | "fit-lint-id" | "lint-array" | "message" | "number" | "palette-lint-id" | "palette-lint-record" | "report-array" | "scheme" | "semantic" | "semantic-array" | "series-pair" | "simulation" | "string" | "string-array" | "token-array" | "warning";
+/** One runtime field descriptor used by fit-suite validation and comparison. */
+export interface ThemeFitFieldDescriptor<Field extends PropertyKey = PropertyKey> {
+    readonly field: Field;
+    readonly kind: ThemeFitFieldKind;
+    /** Whether drift is already reported by comparison, validation, or an identity key. */
+    readonly compared: boolean;
+}
+/** Every stable surface-lint id, exhaustively checked against {@link ThemeFitLint}. */
+export declare const THEME_FIT_LINT_IDS: readonly ThemeFitLint["id"][];
+/** Every stable palette-lint id, exhaustively checked against the lint interface. */
+export declare const THEME_FIT_DATA_PALETTE_LINT_IDS: readonly ThemeFitDataPaletteLint["id"][];
+/** Every stable explicit-pin provenance value. */
+export declare const THEME_FIT_EXPLICIT_VALUES: readonly NonNullable<ThemeFitToken["explicit"]>[];
+type ThemeFitLintSeverity = ThemeFitLint["severity"] | ThemeFitDataPaletteLint["severity"];
+/** Every stable fit-suite lint severity. */
+export declare const THEME_FIT_LINT_SEVERITIES: readonly ThemeFitLintSeverity[];
+/** Runtime schema for every token field; adding an interface field requires a descriptor. */
+export declare const THEME_FIT_TOKEN_FIELDS: readonly ThemeFitFieldDescriptor<keyof ThemeFitToken>[];
+/** Runtime schema for every anchor-detail field. */
+export declare const THEME_FIT_ANCHOR_FIELDS: readonly ThemeFitFieldDescriptor<keyof ThemeFitAnchor>[];
+/** Runtime schema for every APCA-detail field. */
+export declare const THEME_FIT_APCA_FIELDS: readonly ThemeFitFieldDescriptor<keyof ThemeFitApcaAction>[];
+/** Runtime schema for every surface-lint field. */
+export declare const THEME_FIT_LINT_FIELDS: readonly ThemeFitFieldDescriptor<keyof ThemeFitLint>[];
+/** Runtime schema for every categorical-palette lint field. */
+export declare const THEME_FIT_DATA_PALETTE_LINT_FIELDS: readonly ThemeFitFieldDescriptor<keyof ThemeFitDataPaletteLint>[];
 /**
  * Cross-token lints over one surface's report (ESP0175).
  *
@@ -232,11 +278,19 @@ export interface ThemeFitSurfaceReport extends ThemeFitReport {
 export interface ThemeFitSuite {
     /** Surface names in report order: {@link ROOT_SURFACE}, then contexts, sorted. */
     surfaces: string[];
+    /** Fully resolved categorical slots, once per scheme rather than per context. */
+    dataPalette: Record<"light" | "dark", DataPalette>;
+    /** Scheme-level CVD findings over {@link dataPalette}. */
+    paletteLints: Record<"light" | "dark", ThemeFitDataPaletteLint[]>;
     /** One report per surface the light theme defines. */
     light: ThemeFitSurfaceReport[];
     /** One report per surface the dark theme defines. */
     dark: ThemeFitSurfaceReport[];
 }
+/** Runtime schema for every surface-report field. */
+export declare const THEME_FIT_REPORT_FIELDS: readonly ThemeFitFieldDescriptor<keyof ThemeFitSurfaceReport>[];
+/** Runtime schema for every fit-suite field. */
+export declare const THEME_FIT_SUITE_FIELDS: readonly ThemeFitFieldDescriptor<keyof ThemeFitSuite>[];
 /**
  * Fit-report every surface a themed site has (ESP0175): for each scheme,
  * the root plus every declared context, each with its cross-token lints.
@@ -248,5 +302,10 @@ export interface ThemeFitSuite {
  * schemes' context names so an asymmetric pair still reports every
  * surface it can; `validateThemePair` is the gate that rejects the
  * asymmetry itself.
+ *
+ * @throws When a merged scheme emits no root properties (for example, its
+ * seed color is unparseable), because the required palette snapshot cannot be
+ * produced. {@link themeFitReport} retains its narrower empty-report behavior.
  */
 export declare function themeFitReportSuite(lightPartial: PartialTheme, darkPartial: PartialTheme): ThemeFitSuite;
+export {};

package/dist/shared/theme-fit-report.js

@@ -1 +1 @@
-import{apcaContrast as h,deltaEOK as f,parseOklch as p,serializeOklch as k}from"./color-engine.js";import{DEFAULT_DARK_THEME as T,DEFAULT_LIGHT_THEME as R,explicitMappingTokens as $,mergeTheme as m,parseAnchorSource as x,resolveContextTheme as H}from"./theme.js";import{computeThemeProperties as A}from"../root/helpers/compute-theme-properties.js";function _(e,o,n={}){let t=e,r=null;if(n.context!==void 0){const c=H(e,n.context);if(!c)throw new Error(`themeFitReport: context "${n.context}" is not defined by the theme.`);t=c,r=new Set(Object.keys(e.contexts[n.context]?.semanticMappings??{}))}const i=[];A(t,o,i);const l=$(t),u=i.map(c=>{const s=j(c);return l.has(s.token)&&(s.explicit=r===null||r.has(s.token)?"declared":"inherited"),s});return{scheme:o,seedColor:t.seedColor,anchors:M(t.anchors),tokens:u,adjustedTokens:u.filter(c=>c.adjusted).map(c=>c.token)}}function w(e){return e.tokens.map(o=>({token:o.token,source:o.source,requested:o.requested,resolved:o.resolved,apca:I(o),anchor:B(o)}))}function D(e){const o=e.adjustedTokens.length>0?`APCA moved ${e.adjustedTokens.join(", ")}`:"APCA moved nothing";console.info(`Espalier theme fit \u2014 ${e.scheme} scheme, seed ${e.seedColor}. ${o}.`),console.table(w(e))}const L=.045,b=.5,v=75,O=.045;function C(e){const o=[],n=new Map(e.tokens.map(s=>[s.token,s.resolved])),t=s=>{const a=n.get(s);return a===void 0?null:p(a)},r=t("background"),i=t("actionBackground");if(r&&i){const s=f(i,r);if(s<L){const a=d(s,4);o.push({id:"action-canvas-separation",severity:"warning",tokens:["actionBackground","background"],measured:a,message:`actionBackground sits \u0394E ${a} from background (floor ${L}) \u2014 filled actions vanish into this canvas. Retune the surface apart: move the background stop, or pin actionBackground to a separated stop.`})}}const l=t("link"),u=t("linkHover"),c=t("linkHoverBg");if(r&&l&&u&&c){const s=Math.abs(h(l,r)),a=Math.abs(h(u,c));f(c,r)>=O?a+b<v&&o.push({id:"link-hover-ordering",severity:"warning",tokens:["linkHoverBg","linkHover"],measured:d(v-a,1),message:`linkHover reaches only Lc ${d(a,1)} on the linkHoverBg wash it actually paints (tier ${v}) \u2014 retune linkHoverBg before changing linkHover; the wash has one consumer while the ink has many.`}):a+b<s&&o.push({id:"link-hover-ordering",severity:"warning",tokens:["linkHover","link"],measured:d(s-a,1),message:`linkHover reads weaker than link on the same canvas (Lc ${d(a,1)} vs ${d(s,1)}) \u2014 a dimming hover feels disabled. Retune linkHover toward more contrast than the resting link.`})}return o}const g=":root";function V(e,o){const n=m(R,e),t=m(T,o),r=[g,...[...new Set([...Object.keys(n.contexts),...Object.keys(t.contexts)])].sort()],i=(l,u)=>{const c=[];for(const s of r){if(s!==g&&!(s in l.contexts))continue;const a=_(l,u,s===g?{}:{context:s});c.push({...a,surface:s,lints:C(a)})}return c};return{surfaces:r,light:i(n,"light"),dark:i(t,"dark")}}function d(e,o){const n=Math.pow(10,o);return Math.round(e*n)/n}function E(e,o){return o===void 0?e:`${e}.${o}`}function M(e){const o={};for(const[n,t]of Object.entries(e)){if(typeof t=="string"){o[n]=t;continue}for(const[r,i]of Object.entries(t))o[r==="color"?n:E(n,r)]=i}return o}function j(e){const o=p(e.resolved),n=e.requested===void 0?e.resolved:k(e.requested),t={token:e.token,property:e.property,source:e.source,lightness:e.lightness,requested:n,resolved:e.resolved,adjusted:n!==e.resolved,sourceResolved:e.sourceResolved},r=x(e.source);if(r&&e.sourceResolved&&(t.anchor={reference:E(r.name,r.slot),color:k(e.base),deltaE:d(f(e.base,o),4)}),e.contrast){const i=e.contrast.background;t.apca={from:n,to:e.resolved,targetLc:e.contrast.targetLc,against:e.contrast.against,againstColor:k(i),fromLc:d(Math.abs(h(p(n),i)),1),toLc:d(Math.abs(h(o,i)),1)}}return t}function I(e){if(!e.apca)return"";const{targetLc:o,against:n,fromLc:t,toLc:r}=e.apca;return e.adjusted?`Lc ${o} vs ${n} \u2014 pushed from Lc ${t} to Lc ${r}`:`Lc ${o} vs ${n} \u2014 met at Lc ${t}`}function B(e){return e.anchor?`${e.anchor.reference} \u0394E ${e.anchor.deltaE}`:e.sourceResolved?"":"unresolved \u2014 seed used"}export{g as ROOT_SURFACE,D as printThemeFitReport,C as themeFitLints,_ as themeFitReport,V as themeFitReportSuite,w as themeFitRows};
+import{apcaContrast as g,deltaEOK as _,parseOklch as v,serializeOklch as I}from"./color-engine.js";import{DATA_SERIES_KEYS as A,auditDataPalette as j,describePaletteCollision as C}from"./data-colors.js";import{DEFAULT_DARK_THEME as D,DEFAULT_LIGHT_THEME as $,explicitMappingTokens as w,mergeTheme as F,parseAnchorSource as P,resolveContextTheme as N}from"./theme.js";import{computeThemeProperties as y}from"../root/helpers/compute-theme-properties.js";function te(e,t,r={}){return L(e,t,r).report}function L(e,t,r={}){let o=e,s=null;if(r.context!==void 0){const n=N(e,r.context);if(!n)throw new Error(`themeFitReport: context "${r.context}" is not defined by the theme.`);o=n,s=new Set(Object.keys(e.contexts[r.context]?.semanticMappings??{}))}const c=[],m=y(o,t,c),k=w(o),l=c.map(n=>{const a=Y(n);return k.has(a.token)&&(a.explicit=s===null||s.has(a.token)?"declared":"inherited"),a});return{properties:m,report:{scheme:t,seedColor:o.seedColor,anchors:G(o.anchors),tokens:l,adjustedTokens:l.filter(n=>n.adjusted).map(n=>n.token)}}}function B(e){return e.tokens.map(t=>({token:t.token,source:t.source,requested:t.requested,resolved:t.resolved,apca:X(t),anchor:W(t)}))}function re(e){const t=e.adjustedTokens.length>0?`APCA moved ${e.adjustedTokens.join(", ")}`:"APCA moved nothing";console.info(`Espalier theme fit \u2014 ${e.scheme} scheme, seed ${e.seedColor}. ${t}.`),console.table(B(e))}function E(e){const t=Object.entries(e).map(([r,o])=>Object.freeze({field:r,kind:o.kind,compared:o.compared}));return Object.freeze(t)}const V={"action-canvas-separation":!0,"link-hover-ordering":!0},oe=Object.freeze(Object.keys(V)),q={"data-palette-cvd-collision":!0},ne=Object.freeze(Object.keys(q)),z={declared:!0,inherited:!0},se=Object.freeze(Object.keys(z)),U={warning:!0},ae=Object.freeze(Object.keys(U)),ce=E({token:{kind:"semantic",compared:!0},property:{kind:"string",compared:!0},source:{kind:"string",compared:!0},lightness:{kind:"string",compared:!0},requested:{kind:"string",compared:!0},resolved:{kind:"string",compared:!0},adjusted:{kind:"boolean",compared:!0},sourceResolved:{kind:"boolean",compared:!0},anchor:{kind:"anchor",compared:!0},apca:{kind:"apca",compared:!0},explicit:{kind:"explicit",compared:!0}}),ie=E({reference:{kind:"string",compared:!0},color:{kind:"string",compared:!0},deltaE:{kind:"number",compared:!0}}),de=E({from:{kind:"string",compared:!0},to:{kind:"string",compared:!0},targetLc:{kind:"number",compared:!0},against:{kind:"semantic",compared:!0},againstColor:{kind:"string",compared:!0},fromLc:{kind:"number",compared:!0},toLc:{kind:"number",compared:!0}}),ue=E({id:{kind:"fit-lint-id",compared:!0},severity:{kind:"warning",compared:!0},tokens:{kind:"semantic-array",compared:!0},measured:{kind:"number",compared:!0},message:{kind:"message",compared:!0}}),le=E({id:{kind:"palette-lint-id",compared:!0},severity:{kind:"warning",compared:!0},series:{kind:"series-pair",compared:!0},simulation:{kind:"simulation",compared:!0},measured:{kind:"number",compared:!0},threshold:{kind:"number",compared:!0},message:{kind:"message",compared:!0}}),x=.045,O=.5,b=75,K=.045;function S(e){const t=[],r=new Map(e.tokens.map(n=>[n.token,n.resolved])),o=n=>{const a=r.get(n);return a===void 0?null:v(a)},s=o("background"),c=o("actionBackground");if(s&&c){const n=_(c,s);if(n<x){const a=u(n,4);t.push({id:"action-canvas-separation",severity:"warning",tokens:["actionBackground","background"],measured:a,message:`actionBackground sits \u0394E ${a} from background (floor ${x}) \u2014 filled actions vanish into this canvas. Retune the surface apart: move the background stop, or pin actionBackground to a separated stop.`})}}const m=o("link"),k=o("linkHover"),l=o("linkHoverBg");if(s&&m&&k&&l){const n=Math.abs(g(m,s)),a=Math.abs(g(k,l));_(l,s)>=K?a+O<b&&t.push({id:"link-hover-ordering",severity:"warning",tokens:["linkHoverBg","linkHover"],measured:u(b-a,1),message:`linkHover reaches only Lc ${u(a,1)} on the linkHoverBg wash it actually paints (tier ${b}) \u2014 retune linkHoverBg before changing linkHover; the wash has one consumer while the ink has many.`}):a+O<n&&t.push({id:"link-hover-ordering",severity:"warning",tokens:["linkHover","link"],measured:u(n-a,1),message:`linkHover reads weaker than link on the same canvas (Lc ${u(a,1)} vs ${u(n,1)}) \u2014 a dimming hover feels disabled. Retune linkHover toward more contrast than the resting link.`})}return t}const R=":root",pe=E({scheme:{kind:"scheme",compared:!0},seedColor:{kind:"string",compared:!0},anchors:{kind:"anchor-record",compared:!0},tokens:{kind:"token-array",compared:!0},adjustedTokens:{kind:"semantic-array",compared:!0},surface:{kind:"string",compared:!0},lints:{kind:"lint-array",compared:!0}}),me=E({surfaces:{kind:"string-array",compared:!0},dataPalette:{kind:"data-palette-record",compared:!0},paletteLints:{kind:"palette-lint-record",compared:!0},light:{kind:"report-array",compared:!0},dark:{kind:"report-array",compared:!0}});function ke(e,t){const r=F($,e),o=F(D,t),s=[R,...[...new Set([...Object.keys(r.contexts),...Object.keys(o.contexts)])].sort()],c=p=>{const i={};for(let d=0;d<A.length;d+=1){const f=A[d],h=`--esp-color-series-${d+1}`,T=p[h];if(T===void 0)throw new Error(`Theme fit report did not emit required property ${h}.`);i[f]=T}return i},m=p=>j(p).map(i=>{const d=u(i.distance,4);return{id:"data-palette-cvd-collision",severity:"warning",series:i.series,simulation:i.simulation,measured:d,threshold:i.threshold,message:C(i)}}),k=(p,i)=>{const d=L(p,i);if(Object.keys(d.properties).length===0)throw new Error(`themeFitReportSuite: ${i} root emitted no properties for seed "${p.seedColor}".`);const f=[{...d.report,surface:R,lints:S(d.report)}];for(const h of s){if(h===R||!(h in p.contexts))continue;const H=L(p,i,{context:h}).report;f.push({...H,surface:h,lints:S(H)})}return{dataPalette:c(d.properties),reports:f}},l=k(r,"light"),n=k(o,"dark"),a={light:l.dataPalette,dark:n.dataPalette};return{surfaces:s,dataPalette:a,paletteLints:{light:m(a.light),dark:m(a.dark)},light:l.reports,dark:n.reports}}function u(e,t){const r=Math.pow(10,t);return Math.round(e*r)/r}function M(e,t){return t===void 0?e:`${e}.${t}`}function G(e){const t={};for(const[r,o]of Object.entries(e)){if(typeof o=="string"){t[r]=o;continue}for(const[s,c]of Object.entries(o))t[s==="color"?r:M(r,s)]=c}return t}function Y(e){const t=v(e.resolved),r=e.requested===void 0?e.resolved:I(e.requested),o={token:e.token,property:e.property,source:e.source,lightness:e.lightness,requested:r,resolved:e.resolved,adjusted:r!==e.resolved,sourceResolved:e.sourceResolved},s=P(e.source);if(s&&e.sourceResolved&&(o.anchor={reference:M(s.name,s.slot),color:I(e.base),deltaE:u(_(e.base,t),4)}),e.contrast){const c=e.contrast.background;o.apca={from:r,to:e.resolved,targetLc:e.contrast.targetLc,against:e.contrast.against,againstColor:I(c),fromLc:u(Math.abs(g(v(r),c)),1),toLc:u(Math.abs(g(t,c)),1)}}return o}function X(e){if(!e.apca)return"";const{targetLc:t,against:r,fromLc:o,toLc:s}=e.apca;return e.adjusted?`Lc ${t} vs ${r} \u2014 pushed from Lc ${o} to Lc ${s}`:`Lc ${t} vs ${r} \u2014 met at Lc ${o}`}function W(e){return e.anchor?`${e.anchor.reference} \u0394E ${e.anchor.deltaE}`:e.sourceResolved?"":"unresolved \u2014 seed used"}export{R as ROOT_SURFACE,ie as THEME_FIT_ANCHOR_FIELDS,de as THEME_FIT_APCA_FIELDS,le as THEME_FIT_DATA_PALETTE_LINT_FIELDS,ne as THEME_FIT_DATA_PALETTE_LINT_IDS,se as THEME_FIT_EXPLICIT_VALUES,ue as THEME_FIT_LINT_FIELDS,oe as THEME_FIT_LINT_IDS,ae as THEME_FIT_LINT_SEVERITIES,pe as THEME_FIT_REPORT_FIELDS,me as THEME_FIT_SUITE_FIELDS,ce as THEME_FIT_TOKEN_FIELDS,re as printThemeFitReport,S as themeFitLints,te as themeFitReport,ke as themeFitReportSuite,B as themeFitRows};

package/dist/shared/theme.d.ts

@@ -582,6 +582,8 @@ type TokenPairing = Readonly<{
 export declare const TOKEN_PAIRINGS: Readonly<Record<"actionText", TokenPairing> & Partial<Record<SemanticColorName, TokenPairing>>>;
 /** Ordered list of all semantic color token names. */
 export declare const SEMANTIC_COLOR_NAMES: readonly SemanticColorName[];
+/** `true` when `value` is one of the stable semantic color token names. */
+export declare function isSemanticColorName(value: unknown): value is SemanticColorName;
 /** Valid color-source identifiers for {@link SemanticMapping.source}. */
 export declare const COLOR_SOURCES: readonly ColorSource[];
 /** The four fixed status families, matching {@link StatusColorSource}. */
@@ -685,6 +687,8 @@ export declare function parseTheme(base64: string): PartialTheme | null;
  * @returns A Base64-encoded JSON string.
  */
 export declare function encodeTheme(partial: PartialTheme): string;
+/** True for an ordinary record whose entries can be merged by key. */
+export declare function isObjectRecord(value: unknown): value is Record<string, unknown>;
 /**
  * Recover explicit mapping provenance from a resolved theme.
  *