@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/utils/sanitize-rich-text.js

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ // The one escaper (AGL-2706). The local `escapeAttribute` this replaces
+// omitted `'`, which single-quoted attributes delimit just as double quotes
+// do — the omission was survivable only because every value here lands in a
+// double-quoted slot, and a rule that holds by where its callers happen to
+// put it is the kind that stops holding quietly. `escapeText` below stays
+// local: it is the TEXT half, and a text node has no quote to break.
+import { escapeHtml } from "@aglyn/shared-util-tools/escape-html";
+/** Tags the inline rich-text editor may persist (AGL-54). */ const ALLOWED_TAGS = new Set([
+    'b',
+    'strong',
+    'i',
+    'em',
+    'u',
+    'a',
+    'ul',
+    'ol',
+    'li',
+    'br',
+    'p',
+    'div',
+    'span'
+]);
+/**
+ * The subset a PHRASING-ONLY surface may persist (AGL-2557) — the label of a
+ * Button, a Screen Link or an Accordion Summary, which ships inside a
+ * `<button>` or an `<a>`.
+ *
+ * Neither element may contain a block or a second control. A `<div>` here is
+ * not merely untidy: the parser closes the control on that start tag and
+ * promotes the rest to a sibling, which reaches the browser as a React
+ * hydration mismatch on the published page. The renderer enforces the same
+ * narrowing on the way out (`INLINE_AUTHOR_HTML_ELEMENTS`); this end of the
+ * round trip means what is STORED is what will be drawn, so the Attributes
+ * panel and the plain-text fallback describe the same element as the canvas.
+ *
+ * `br` stays: it is phrasing content, and Shift+Enter is the one line break
+ * these surfaces still offer.
+ */ const PHRASING_TAGS = new Set([
+    'b',
+    'strong',
+    'i',
+    'em',
+    'u',
+    'br',
+    'span'
+]);
+const SAFE_HREF = /^(https?:\/\/|mailto:|tel:|\/)/i;
+/**
+ * Allowlist HTML sanitizer for inline rich text: keeps basic formatting
+ * tags, strips every attribute except a safe `href` on links (which gains
+ * `rel="noopener noreferrer"`), and unwraps disallowed elements to their
+ * text content (so nothing script-capable survives). Runs at commit time in
+ * the editor (browser DOM available).
+ *
+ * `options.phrasingOnly` narrows the allowlist for a surface that ships
+ * inside a control (AGL-2557); omitted, every existing caller is unchanged.
+ */ export function sanitizeRichText(html, options) {
+    if (typeof document === 'undefined') return '';
+    const allowed = (options == null ? void 0 : options.phrasingOnly) ? PHRASING_TAGS : ALLOWED_TAGS;
+    const template = document.createElement('template');
+    template.innerHTML = html;
+    const sanitizeNode = (node)=>{
+        if (node.nodeType === Node.TEXT_NODE) {
+            var _node_textContent;
+            return escapeText((_node_textContent = node.textContent) != null ? _node_textContent : '');
+        }
+        if (node.nodeType !== Node.ELEMENT_NODE) return '';
+        const element = node;
+        const tag = element.tagName.toLowerCase();
+        const inner = Array.from(element.childNodes).map(sanitizeNode).join('');
+        if (!allowed.has(tag)) return inner;
+        // A bare `span` is INERT and is unwrapped (AGL-2486). Every attribute is
+        // stripped here, so a surviving `<span>` carries no styling, no class and
+        // no binding — it renders exactly as its own text. Keeping it would be
+        // dead weight with a cost: `html` is what marks a node as "formatted", so
+        // an inert wrapper left behind by a contentEditable merge would pin the
+        // Attributes Text field read-only forever over markup that does nothing.
+        // Measured on test-org: deleting the line break out of
+        // `About <div>us</div>` left Chrome with `About<span>us</span>`.
+        if (tag === 'span') return inner;
+        if (tag === 'br') return '<br>';
+        if (tag === 'a') {
+            var _element_getAttribute;
+            const href = (_element_getAttribute = element.getAttribute('href')) != null ? _element_getAttribute : '';
+            if (!SAFE_HREF.test(href)) return inner;
+            return `<a href="${escapeHtml(href)}" rel="noopener noreferrer">${inner}</a>`;
+        }
+        return `<${tag}>${inner}</${tag}>`;
+    };
+    return Array.from(template.content.childNodes).map(sanitizeNode).join('');
+}
+function escapeText(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/**
+ * Tags that end the line they are on. `br` is the explicit one; the rest are
+ * the block-level members of {@link ALLOWED_TAGS}, which a contentEditable
+ * produces on its own — pressing Enter in the rich surface forks the DOM
+ * into `div`s, and that fork IS the author's line break.
+ */ const LINE_BREAKING_TAGS = new Set([
+    'BR',
+    'DIV',
+    'P',
+    'LI',
+    'UL',
+    'OL'
+]);
+/**
+ * Plain-text projection of markup, for the `children` fallback prop.
+ *
+ * Line breaks SURVIVE (AGL-2486). A node that carries one stores
+ * `html: "Your entire web <div>presence. </div>"` beside
+ * `children: "Your entire web presence. "`. The canvas renders `html` and
+ * shows two lines; the Attributes panel renders `children`. Projected with
+ * `template.content.textContent` the panel shows one, because `textContent`
+ * concatenates across every element boundary — a `<div>` fork and a `<br>`
+ * both vanish into nothing.
+ *
+ * That is a real break silently dropped by the projection, not the soft wrap
+ * a bounding box misreports. `children` is not a display detail either: it is
+ * what every
+ * plain renderer, the SSR fallback and the panel field all read, so the
+ * break was being lost to all three.
+ *
+ * Only the trailing newline is trimmed — a block element closes at the end
+ * of the string and that boundary separates nothing.
+ */ export function richTextToPlain(html) {
+    if (typeof document === 'undefined') return html;
+    const template = document.createElement('template');
+    template.innerHTML = html;
+    const parts = [];
+    const endsOpen = ()=>parts.length > 0 && !parts[parts.length - 1].endsWith('\n');
+    const walk = (parent)=>{
+        for (const child of Array.from(parent.childNodes)){
+            if (child.nodeType === 3 /* TEXT_NODE */ ) {
+                var _child_nodeValue;
+                parts.push((_child_nodeValue = child.nodeValue) != null ? _child_nodeValue : '');
+                continue;
+            }
+            if (child.nodeType !== 1 /* ELEMENT_NODE */ ) continue;
+            const element = child;
+            if (element.tagName === 'BR') {
+                parts.push('\n');
+                continue;
+            }
+            const breaks = LINE_BREAKING_TAGS.has(element.tagName);
+            // A block that FOLLOWS content starts its own line; one that opens the
+            // string, or already sits after a break, does not add an empty one.
+            if (breaks && endsOpen()) parts.push('\n');
+            walk(element);
+            if (breaks && endsOpen()) parts.push('\n');
+        }
+    };
+    walk(template.content);
+    return parts.join('').replace(/\n+$/, '');
+}
+
+//# sourceMappingURL=sanitize-rich-text.js.map

package/src/lib/utils/sanitize-rich-text.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/utils/sanitize-rich-text.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// The one escaper (AGL-2706). The local `escapeAttribute` this replaces\n// omitted `'`, which single-quoted attributes delimit just as double quotes\n// do — the omission was survivable only because every value here lands in a\n// double-quoted slot, and a rule that holds by where its callers happen to\n// put it is the kind that stops holding quietly. `escapeText` below stays\n// local: it is the TEXT half, and a text node has no quote to break.\nimport { escapeHtml } from '@aglyn/shared-util-tools/escape-html'\n\n/** Tags the inline rich-text editor may persist (AGL-54). */\nconst ALLOWED_TAGS = new Set([\n  'b',\n  'strong',\n  'i',\n  'em',\n  'u',\n  'a',\n  'ul',\n  'ol',\n  'li',\n  'br',\n  'p',\n  'div',\n  'span',\n])\n\n/**\n * The subset a PHRASING-ONLY surface may persist (AGL-2557) — the label of a\n * Button, a Screen Link or an Accordion Summary, which ships inside a\n * `<button>` or an `<a>`.\n *\n * Neither element may contain a block or a second control. A `<div>` here is\n * not merely untidy: the parser closes the control on that start tag and\n * promotes the rest to a sibling, which reaches the browser as a React\n * hydration mismatch on the published page. The renderer enforces the same\n * narrowing on the way out (`INLINE_AUTHOR_HTML_ELEMENTS`); this end of the\n * round trip means what is STORED is what will be drawn, so the Attributes\n * panel and the plain-text fallback describe the same element as the canvas.\n *\n * `br` stays: it is phrasing content, and Shift+Enter is the one line break\n * these surfaces still offer.\n */\nconst PHRASING_TAGS = new Set(['b', 'strong', 'i', 'em', 'u', 'br', 'span'])\n\n/** How much markup one commit may keep — see {@link PHRASING_TAGS}. */\nexport interface SanitizeRichTextOptions {\n  phrasingOnly?: boolean\n}\n\nconst SAFE_HREF = /^(https?:\\/\\/|mailto:|tel:|\\/)/i\n\n/**\n * Allowlist HTML sanitizer for inline rich text: keeps basic formatting\n * tags, strips every attribute except a safe `href` on links (which gains\n * `rel=\"noopener noreferrer\"`), and unwraps disallowed elements to their\n * text content (so nothing script-capable survives). Runs at commit time in\n * the editor (browser DOM available).\n *\n * `options.phrasingOnly` narrows the allowlist for a surface that ships\n * inside a control (AGL-2557); omitted, every existing caller is unchanged.\n */\nexport function sanitizeRichText(\n  html: string,\n  options?: SanitizeRichTextOptions,\n): string {\n  if (typeof document === 'undefined') return ''\n  const allowed = options?.phrasingOnly ? PHRASING_TAGS : ALLOWED_TAGS\n  const template = document.createElement('template')\n  template.innerHTML = html\n\n  const sanitizeNode = (node: Node): string => {\n    if (node.nodeType === Node.TEXT_NODE) {\n      return escapeText(node.textContent ?? '')\n    }\n    if (node.nodeType !== Node.ELEMENT_NODE) return ''\n    const element = node as Element\n    const tag = element.tagName.toLowerCase()\n    const inner = Array.from(element.childNodes).map(sanitizeNode).join('')\n    if (!allowed.has(tag)) return inner\n    // A bare `span` is INERT and is unwrapped (AGL-2486). Every attribute is\n    // stripped here, so a surviving `<span>` carries no styling, no class and\n    // no binding — it renders exactly as its own text. Keeping it would be\n    // dead weight with a cost: `html` is what marks a node as \"formatted\", so\n    // an inert wrapper left behind by a contentEditable merge would pin the\n    // Attributes Text field read-only forever over markup that does nothing.\n    // Measured on test-org: deleting the line break out of\n    // `About <div>us</div>` left Chrome with `About<span>us</span>`.\n    if (tag === 'span') return inner\n    if (tag === 'br') return '<br>'\n    if (tag === 'a') {\n      const href = element.getAttribute('href') ?? ''\n      if (!SAFE_HREF.test(href)) return inner\n      return `<a href=\"${escapeHtml(href)}\" rel=\"noopener noreferrer\">${inner}</a>`\n    }\n    return `<${tag}>${inner}</${tag}>`\n  }\n\n  return Array.from(template.content.childNodes).map(sanitizeNode).join('')\n}\n\nfunction escapeText(text: string): string {\n  return text\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n}\n\n/**\n * Tags that end the line they are on. `br` is the explicit one; the rest are\n * the block-level members of {@link ALLOWED_TAGS}, which a contentEditable\n * produces on its own — pressing Enter in the rich surface forks the DOM\n * into `div`s, and that fork IS the author's line break.\n */\nconst LINE_BREAKING_TAGS = new Set(['BR', 'DIV', 'P', 'LI', 'UL', 'OL'])\n\n/**\n * Plain-text projection of markup, for the `children` fallback prop.\n *\n * Line breaks SURVIVE (AGL-2486). A node that carries one stores\n * `html: \"Your entire web <div>presence. </div>\"` beside\n * `children: \"Your entire web presence. \"`. The canvas renders `html` and\n * shows two lines; the Attributes panel renders `children`. Projected with\n * `template.content.textContent` the panel shows one, because `textContent`\n * concatenates across every element boundary — a `<div>` fork and a `<br>`\n * both vanish into nothing.\n *\n * That is a real break silently dropped by the projection, not the soft wrap\n * a bounding box misreports. `children` is not a display detail either: it is\n * what every\n * plain renderer, the SSR fallback and the panel field all read, so the\n * break was being lost to all three.\n *\n * Only the trailing newline is trimmed — a block element closes at the end\n * of the string and that boundary separates nothing.\n */\nexport function richTextToPlain(html: string): string {\n  if (typeof document === 'undefined') return html\n  const template = document.createElement('template')\n  template.innerHTML = html\n  const parts: string[] = []\n  const endsOpen = () =>\n    parts.length > 0 && !parts[parts.length - 1]!.endsWith('\\n')\n\n  const walk = (parent: Node): void => {\n    for (const child of Array.from(parent.childNodes)) {\n      if (child.nodeType === 3 /* TEXT_NODE */) {\n        parts.push(child.nodeValue ?? '')\n        continue\n      }\n      if (child.nodeType !== 1 /* ELEMENT_NODE */) continue\n      const element = child as Element\n      if (element.tagName === 'BR') {\n        parts.push('\\n')\n        continue\n      }\n      const breaks = LINE_BREAKING_TAGS.has(element.tagName)\n      // A block that FOLLOWS content starts its own line; one that opens the\n      // string, or already sits after a break, does not add an empty one.\n      if (breaks && endsOpen()) parts.push('\\n')\n      walk(element)\n      if (breaks && endsOpen()) parts.push('\\n')\n    }\n  }\n\n  walk(template.content)\n  return parts.join('').replace(/\\n+$/, '')\n}\n"],"names":["escapeHtml","ALLOWED_TAGS","Set","PHRASING_TAGS","SAFE_HREF","sanitizeRichText","html","options","document","allowed","phrasingOnly","template","createElement","innerHTML","sanitizeNode","node","nodeType","Node","TEXT_NODE","escapeText","textContent","ELEMENT_NODE","element","tag","tagName","toLowerCase","inner","Array","from","childNodes","map","join","has","href","getAttribute","test","content","text","replace","LINE_BREAKING_TAGS","richTextToPlain","parts","endsOpen","length","endsWith","walk","parent","child","push","nodeValue","breaks"],"mappings":"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"}

package/src/lib/utils/state-sx.d.ts

@@ -0,0 +1,255 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { BesignerStateFlag } from '@aglyn/besigner';
+/**
+ * Interaction-state style slices for the Styles panel (AGL-2486 item 39).
+ *
+ * Hover, focus and active states are reachable in the document already — the
+ * JSS tab's own caption advertises nested selectors — but only by typing raw
+ * sx, which most of this panel's audience cannot do. These slices are the
+ * picker for the same capability.
+ *
+ * ## What is stored is the REAL selector
+ *
+ * A state slice is `node.sx['&:hover']`, not a reserved `@state hover` key.
+ * That choice is what makes this feature need NO renderer change at all:
+ * MUI's `styleFunctionSx` hands an unrecognised object key straight back to
+ * itself (`wrapper.sx = value; css[styleKey] = styleFunctionSx(wrapper)`), so
+ * the slice gets the full sx treatment — palette tokens, system-prop aliases
+ * (`bgcolor`), and responsive breakpoint objects — identically on the canvas,
+ * in Preview and on the published page. A reserved key would have needed a
+ * substitution pass on every render path, and the recorded reason the scheme
+ * slices work is that there is exactly ONE such path.
+ *
+ * It also means the panel and the JSS tab are editing the same thing rather
+ * than two representations of it, and that an author who already hand-wrote
+ * `&:hover` finds the panel showing it.
+ *
+ * ## Nesting order: state OUTER, scheme INNER, breakpoints innermost
+ *
+ * ```ts
+ * { '&:hover': { '@scheme dark': { color: { xs: '#eee', md: '#fff' } } } }
+ * ```
+ *
+ * Not a new invariant — `scheme-rendering.spec.tsx` already proves
+ * `resolveSchemeSx` resolves exactly this shape, because it recurses into
+ * nested selector objects. The REVERSE order would be a bug: `mergeSchemeValue`
+ * replaces a nested object wholesale, so a `@scheme dark` slice containing
+ * `&:hover` would clobber the light hover block rather than merge with it.
+ *
+ * ## The scrub is not bypassed
+ *
+ * `sanitizeAuthorSx` walks nested records with no key filtering, and
+ * `leaf-author-css.spec.tsx` already asserts that a `url(http://…)` inside an
+ * `&:hover` slice is rewritten to `about:invalid`. Author CSS in a state slice
+ * goes through the same scrub as author CSS anywhere else.
+ */
+/**
+ * The interaction states the panel offers, in the order the chip row shows
+ * them.
+ *
+ * ## Why plain `:focus` is deliberately absent — do not "fix" this
+ *
+ * `:focus` matches on mouse and touch focus as well as keyboard focus, so the
+ * overwhelmingly common thing an author does with a `:focus` control is remove
+ * the ring they consider ugly on click — and that removes it for keyboard
+ * users too, who have no other way to tell where they are on the page. Adding
+ * the field would mean shipping a purpose-built UI for an accessibility
+ * regression, on a product whose authors are explicitly not expected to know
+ * CSS.
+ *
+ * `:focus-visible` is the same capability without that failure mode: the
+ * browser only matches it when it judges a focus indicator should be shown
+ * (keyboard and programmatic focus, not a mouse click), so styling it can
+ * essentially only ADD an indicator. That covers the legitimate reason to
+ * style focus — making the ring match the brand — while making the harmful
+ * one much harder to reach by accident.
+ *
+ * An author with a genuine `:focus` need still has the JSS (sx) tab, which
+ * accepts any selector. That friction is the point: it is reachable by someone
+ * who knows what they are doing and not by someone clicking through a panel.
+ */
+export declare const SX_STATES: readonly BesignerStateFlag[];
+/**
+ * Alias of the canvas flag union, which is declared in `@aglyn/besigner` so
+ * the flag store that HOLDS the state and the panel that WRITES the slice
+ * cannot drift apart.
+ */
+export type SxState = BesignerStateFlag;
+/** The CSS selector each state is stored under in `node.sx`. */
+export declare const SX_STATE_SELECTORS: Readonly<Record<SxState, string>>;
+/**
+ * Chip labels. **Keep them short — this row must never wrap.**
+ *
+ * These shipped once as "Focus (keyboard)", to stop a bare "Focus" implying
+ * that the mouse-click ring is what you are styling. The reasoning was right
+ * and the label was wrong: measured against the styles panel, the five chips
+ * needed **368px** of the **359px** a default 375px panel has, so `Disabled`
+ *
+ * Short labels bring the row to 272px, which fits every panel width down to
+ * about 290px, and {@link SX_STATE_LABEL_MAX} pins them so the next person to
+ * reach for a clarifying parenthetical gets a failing test instead of a
+ * wrapped row.
+ *
+ * The keyboard nuance did not get dropped, it moved somewhere better than a
+ * label: {@link SX_STATE_DESCRIPTIONS} carries the full rule in the chip
+ * tooltip, and {@link SX_STATE_PROSE} puts "keyboard focus" in the preview
+ * banner — which appears the moment Focus is selected, so it is READ rather
+ * than hovered for. That is the same job the long label was doing, done where
+ * there is room for it.
+ */
+export declare const SX_STATE_LABELS: Readonly<Record<SxState, string>>;
+/**
+ * The longest a chip label may be before the row stops fitting a narrow
+ * panel. `Disabled` is 8 and is the longest today; the budget is measured,
+ * not guessed — see {@link SX_STATE_LABELS}.
+ */
+export declare const SX_STATE_LABEL_MAX = 8;
+/** The same states in running prose — banners, the override chips. */
+export declare const SX_STATE_PROSE: Readonly<Record<SxState, string>>;
+/**
+ * What each state means, in the panel's voice — shown as the chip tooltip so
+ * an author can tell `Active` (held down) from `Focus` (keyboard) without
+ * knowing the selectors.
+ */
+export declare const SX_STATE_DESCRIPTIONS: Readonly<Record<SxState, string>>;
+/** Whether an sx key is one of the state selectors this module owns. */
+export declare function isSxStateSelector(key: string): boolean;
+/**
+ * The state a stored selector belongs to, or null when the key is not one of
+ * ours. Lets a surface that lists RAW sx keys — the instance-override chips —
+ * name a slice the way the chip row does instead of printing `&:hover` at an
+ * author who never typed it.
+ */
+export declare function sxStateForSelector(key: string): SxState | null;
+/** The override-chip label for a raw sx key, or null to fall through. */
+export declare function sxStateSliceLabel(key: string): string | null;
+/**
+ * The stored slice for a state, or undefined when the element has none.
+ *
+ * `state: null` is the base scope and returns the record itself, so callers
+ * can pass the panel's active scope through without branching.
+ */
+export declare function readStateSlice(sx: Record<string, any> | undefined, state: SxState | null): Record<string, any> | undefined;
+/**
+ * What the element actually LOOKS like in a state: the base styles with the
+ * state slice merged over them, which is what the browser paints because a
+ * `:hover` block only overrides the properties it names.
+ *
+ * This is what the panel reads from, so a field the author has not overridden
+ * for hover shows the inherited base value rather than empty — the same
+ * reading the breakpoint scope gives, and the reason the write seam can skip
+ * a value that would not change anything.
+ *
+ * `mergeNodeSx` is the house merge: responsive objects cascade mobile-first,
+ * `@scheme dark` and nested selector blocks merge key by key. Reusing it keeps
+ * the panel's reading identical to the graft's.
+ *
+ * Returns the input BY IDENTITY at base scope or when no slice exists, which
+ * is every element that has never been given a state style.
+ */
+/**
+ * The element's base styles with every state selector removed — the baseline a
+ * state slice is a difference FROM. Returned by identity when the element
+ * carries no state slices at all, which is every element today.
+ */
+export declare function stripStateSlices(sx: Record<string, any> | undefined): Record<string, any> | undefined;
+export declare function stateScopedSx(sx: Record<string, any> | undefined, state: SxState | null): Record<string, any> | undefined;
+/**
+ * Replaces one state's slice, removing it entirely when it comes back empty.
+ *
+ * An emptied slice is DELETED rather than stored as `{}` — the same rule
+ * `writeSxValue` applies to an emptied scheme slice and `getNodeStyleTarget`
+ * applies to an emptied instance override. A `{}` left behind would make
+ * "does this element have a hover style" answer yes forever, which the chip's
+ * own dot indicator and the override badge both read.
+ *
+ * Returns a new record; the input is never mutated.
+ */
+export declare function writeStateSlice(sx: Record<string, any> | undefined, state: SxState, slice: Record<string, any> | undefined): Record<string, any>;
+/**
+ * The slice implied by an edited state-scope reading (AGL-2486).
+ *
+ * The panel edits the MERGED record — base with the slice over it, which is
+ * what the element actually looks like in that state — so the write has to be
+ * split back out: only what genuinely differs from the base belongs in the
+ * slice. That split is what gives the three behaviours the panel needs, all
+ * from one rule:
+ *
+ * - a property the author changed for this state lands in the slice;
+ * - a property the author set back to the base value LEAVES the slice, because
+ *   a `:hover` block that restates the base paints nothing and would show as a
+ *   permanent override in the chip's dot;
+ * - a property the author cleared leaves the slice too, so the state falls
+ *   back to inheriting the base — which is the only thing a pseudo-class block
+ *   can express, since CSS has no way to un-declare a property.
+ *
+ * `base` must already have the state selectors stripped (which
+ * {@link stateScopedSx} does), or a sibling state's block would read as a
+ * difference and be copied in.
+ */
+export declare function deriveStateSlice(base: Record<string, any> | undefined, edited: Record<string, any> | undefined): Record<string, any>;
+/** Whether the element carries any styles for this state. */
+export declare function sxHasStateSlice(sx: Record<string, any> | undefined, state: SxState): boolean;
+/** Every state the element currently carries a slice for, in chip order. */
+export declare function sxStatesWithSlices(sx: Record<string, any> | undefined): SxState[];
+/**
+ * The advisory to show under the state chips, or null when the state makes
+ * plain sense on this element (AGL-2486 item 39).
+ *
+ * States are deliberately NOT constrained by element type. A hover effect on a
+ * Box or Section wrapping a link is among the commonest real designs, and
+ * refusing it would block more good work than it prevents mistakes. But
+ * `:focus-visible` on something with no tab stop and `:disabled` on something
+ * that cannot be disabled will simply never fire, and an author who styles one
+ * and sees nothing has no way to find out why. So: allow it, and say so.
+ */
+export declare function stateAdvisory(state: SxState | null, element: {
+    componentId?: string;
+    hasHref?: boolean;
+    hasTabIndex?: boolean;
+}): string | null;
+/**
+ * CANVAS ONLY: renders an element as if it were in the given state, by
+ * hoisting that state's slice over the base declarations (AGL-2486 item 39).
+ *
+ * You cannot hover an element while working in a side panel, so a state whose
+ * styles you cannot see is a state you cannot design. This is what holds the
+ * state on — and it is deliberately NOT a toggle that can be left on and
+ * published by mistake: selecting the state in the panel's chip row IS the
+ * hold, so you cannot be editing the hover slice and not see hover, and
+ * returning to `Default` ends it. It lives in editor UI state and never enters
+ * the document, so Preview and the published page cannot receive it.
+ *
+ * Applied through `LeafSxTransformContext` — the SAME canvas-only seam the
+ * artboard device-width transform already uses, at the one point in `Leaf`
+ * where the merged sx reaches the element. There is still exactly one
+ * substitution path, and the tenant never mounts the provider.
+ *
+ * Runs on the fully merged sx AFTER scheme resolution, so a slice that carried
+ * `@scheme dark` has already collapsed to the active scheme's values by the
+ * time it is hoisted. `mergeSchemeValue` does the per-value merge so a
+ * responsive override keeps the base's other breakpoints.
+ *
+ * The hoisted selector is removed, so what renders is exactly the state's
+ * appearance rather than the state's appearance plus a live `:hover` that
+ * would repaint the same declarations. Sibling states are left untouched.
+ *
+ * Returns the input BY IDENTITY when there is nothing to hoist.
+ */
+export declare function hoistStateSx<T>(sx: T, state: SxState | null): T;
+export default SX_STATES;