@3driseai/3drise-core 1.0.21 → 1.0.23

package/dist/ui/uiBindings.js

@@ -0,0 +1,172 @@
+// =============================================================================
+// Reading and validating the bindings of a layer
+// =============================================================================
+//
+// `collectUiBindings` reads every binding attribute of a rendered (or parsed) layer.
+// The binder uses it to wire the DOM and to `inspect`; `validateUiLayer` uses it to
+// tell the agent what is wrong before anything is saved. Both read the same grammar
+// (uiSpec), so what validates is what runs.
+//
+import { UI_ATTR, UI_CLASSES, UI_SET_ENVIRONMENT, UI_TRIGGER_ATTRS, parseAnchor, parseBind, parseCommands, parseConditions, parseOffset, parseSetTarget, parseSetValue, } from './uiSpec.js';
+import { resolveUiRef } from './uiKeys.js';
+const BINDING_SELECTOR = Object.values(UI_ATTR).map(a => `[${a}]`).join(',');
+export function describeUiElement(el) {
+    const cls = (el.getAttribute('class') ?? '').trim().split(/\s+/).filter(Boolean).slice(0, 2).join('.');
+    const text = (el.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 30);
+    return `<${el.localName}${cls ? '.' + cls : ''}${el.id ? '#' + el.id : ''}>${text ? ` "${text}"` : ''}`;
+}
+/** Every element of `root` that carries a binding attribute. */
+export function collectUiBindings(root) {
+    const uses = [];
+    for (const el of Array.from(root.querySelectorAll(BINDING_SELECTOR))) {
+        const use = {
+            el, label: describeUiElement(el), errors: [], commands: [], state: [], showWhen: [],
+            anchorOcclude: el.hasAttribute(UI_ATTR.anchorOcclude), anchorOffset: null,
+        };
+        for (const trigger of Object.keys(UI_TRIGGER_ATTRS)) {
+            const attr = UI_TRIGGER_ATTRS[trigger];
+            if (!el.hasAttribute(attr))
+                continue;
+            const { commands, errors } = parseCommands(el.getAttribute(attr));
+            use.errors.push(...errors.map(e => `${attr}: ${e}`));
+            use.commands.push({ trigger, items: commands });
+        }
+        if (el.hasAttribute(UI_ATTR.state)) {
+            const { conditions, errors } = parseConditions(el.getAttribute(UI_ATTR.state));
+            use.state = conditions;
+            use.errors.push(...errors.map(e => `${UI_ATTR.state}: ${e}`));
+        }
+        if (el.hasAttribute(UI_ATTR.showWhen)) {
+            const { conditions, errors } = parseConditions(el.getAttribute(UI_ATTR.showWhen));
+            use.showWhen = conditions;
+            use.errors.push(...errors.map(e => `${UI_ATTR.showWhen}: ${e}`));
+        }
+        if (el.hasAttribute(UI_ATTR.bind)) {
+            const { bind, error } = parseBind(el.getAttribute(UI_ATTR.bind));
+            if (bind)
+                use.bind = bind;
+            if (error)
+                use.errors.push(`${UI_ATTR.bind}: ${error}`);
+        }
+        if (el.hasAttribute(UI_ATTR.anchor)) {
+            const { anchor, error } = parseAnchor(el.getAttribute(UI_ATTR.anchor));
+            if (anchor)
+                use.anchor = anchor;
+            if (error)
+                use.errors.push(`${UI_ATTR.anchor}: ${error}`);
+        }
+        if (el.hasAttribute(UI_ATTR.set)) {
+            const { set, error } = parseSetTarget(el.getAttribute(UI_ATTR.set));
+            if (set)
+                use.set = set;
+            if (error)
+                use.errors.push(`${UI_ATTR.set}: ${error}`);
+        }
+        if (el.hasAttribute(UI_ATTR.setValue))
+            use.setValue = parseSetValue(el.getAttribute(UI_ATTR.setValue));
+        if (el.hasAttribute(UI_ATTR.anchorOffset)) {
+            use.anchorOffset = parseOffset(el.getAttribute(UI_ATTR.anchorOffset));
+            if (!use.anchorOffset)
+                use.errors.push(`${UI_ATTR.anchorOffset}: expected two numbers in px, like "0 -12".`);
+        }
+        uses.push(use);
+    }
+    return uses;
+}
+const known = (items) => items.map(i => i.key || i.name).join(', ') || 'none yet';
+function checkRef(kind, ref, refs, layerIds) {
+    if (kind === 'ui')
+        return layerIds.has(ref.slice(1)) ? null : `no element with id "${ref.slice(1)}" in this layer.`;
+    const list = kind === 'action' ? refs.actions : kind === 'clip' ? refs.clips : refs.sequences;
+    return resolveUiRef(list, ref) ? null : `no ${kind} "${ref}". Known ${kind}s: ${known(list)}.`;
+}
+/** Generic control classes: a control with none of them gets a nudge, so users can restyle it in one place. */
+const GENERIC = new Set(UI_CLASSES.map(c => c.name));
+const hasGenericClass = (el) => (el.getAttribute('class') ?? '').split(/\s+/).some(c => GENERIC.has(c));
+export function validateUiRoot(root, refs) {
+    const issues = [];
+    const add = (level, element, message) => issues.push({ level, element, message });
+    const layerIds = new Set(Array.from(root.querySelectorAll('[id]')).map(e => e.id));
+    const uses = collectUiBindings(root);
+    for (const use of uses) {
+        for (const e of use.errors)
+            add('error', use.label, e);
+        for (const group of use.commands) {
+            for (const c of group.items) {
+                const problem = checkRef(c.kind, c.ref, refs, layerIds);
+                if (problem)
+                    add('error', use.label, `${UI_TRIGGER_ATTRS[group.trigger]}: ${problem}`);
+            }
+        }
+        for (const [attr, list] of [[UI_ATTR.state, use.state], [UI_ATTR.showWhen, use.showWhen]]) {
+            for (const c of list) {
+                const problem = checkRef(c.kind, c.ref, refs, layerIds);
+                if (problem)
+                    add('error', use.label, `${attr}: ${problem}`);
+            }
+        }
+        if (use.bind) {
+            const problem = checkRef(use.bind.kind, use.bind.ref, refs, layerIds);
+            if (problem)
+                add('error', use.label, `${UI_ATTR.bind}: ${problem}`);
+            if (!(use.el.localName === 'input' && use.el.getAttribute('type') === 'range')) {
+                add('error', use.label, `${UI_ATTR.bind} only works on <input type="range">.`);
+            }
+        }
+        if (use.anchor && !resolveUiRef(refs.objects, use.anchor.object)) {
+            add('error', use.label, `${UI_ATTR.anchor}: no object "${use.anchor.object}". Known objects: ${known(refs.objects)}.`);
+        }
+        if (use.set) {
+            const t = use.set;
+            const env = UI_SET_ENVIRONMENT.includes(t.target);
+            if (!env && !resolveUiRef(refs.objects, t.target)) {
+                add('error', use.label, `${UI_ATTR.set}: no object "${t.target}". Use ${UI_SET_ENVIRONMENT.join(', ')} or an object (known: ${known(refs.objects)}).`);
+            }
+            else {
+                const problem = refs.checkSet?.(t);
+                if (problem)
+                    add('error', use.label, `${UI_ATTR.set}: ${problem}`);
+            }
+            const tag = use.el.localName;
+            const type = (use.el.getAttribute('type') ?? 'text').toLowerCase();
+            const isInput = tag === 'input' || tag === 'select';
+            if (!isInput && use.setValue === undefined) {
+                add('error', use.label, `${UI_ATTR.set} on a <${tag}> needs ${UI_ATTR.setValue} (what a press writes); or use an <input> / <select>.`);
+            }
+            if (isInput && use.setValue !== undefined)
+                add('warning', use.label, `${UI_ATTR.setValue} is for buttons; on an input the control's own value is written.`);
+            if (tag === 'input' && type === 'range' && (!use.el.hasAttribute('min') || !use.el.hasAttribute('max'))) {
+                add('warning', use.label, 'a range with data-set writes its own value: set min and max in the property\'s units (the default is 0–100).');
+            }
+        }
+        else if (use.setValue !== undefined) {
+            add('error', use.label, `${UI_ATTR.setValue} needs ${UI_ATTR.set} (the property to write).`);
+        }
+        const hover = use.commands.some(c => (c.trigger === 'hoverIn' || c.trigger === 'hoverOut') && c.items.length);
+        const click = use.commands.some(c => c.trigger === 'click' && c.items.length);
+        if (hover && !click && !use.anchor) {
+            add('warning', use.label, 'hover does not fire on touch screens — give it a data-click too.');
+        }
+    }
+    // data-show-when rewrites `hidden` on every refresh, so a ui command on the same element would be undone.
+    const uiTargets = new Set();
+    for (const use of uses)
+        for (const g of use.commands)
+            for (const c of g.items)
+                if (c.kind === 'ui')
+                    uiTargets.add(c.ref.slice(1));
+    for (const use of uses) {
+        if (use.showWhen.length && use.el.id && uiTargets.has(use.el.id)) {
+            add('warning', use.label, 'has data-show-when and is also the target of a ui command; data-show-when wins on every refresh. Use one of the two.');
+        }
+    }
+    // Generic classes: controls without one are hard for users to restyle together.
+    for (const el of Array.from(root.querySelectorAll('button, input, select'))) {
+        if (hasGenericClass(el))
+            continue;
+        const t = el.localName === 'input' ? el.getAttribute('type') ?? 'text' : el.localName;
+        const want = t === 'range' ? 'rise-slider' : el.localName === 'button' ? 'rise-button (or rise-toggle)' : 'rise-input';
+        add('warning', describeUiElement(el), `has no generic class — add ${want} so users can restyle every control in one place.`);
+    }
+    return issues;
+}

package/dist/ui/uiKeys.d.ts

@@ -0,0 +1,14 @@
+import { isValidActionKey, uniqueActionKey } from '../utils/actionKeys';
+export declare const UI_KEY_MAX_LENGTH = 64;
+export declare const isValidUiLayerKey: typeof isValidActionKey;
+export declare const uniqueUiLayerKey: typeof uniqueActionKey;
+/** "Door controls" -> "door-controls". A name with no latin letters or digits (Hebrew, emoji…) falls back to "ui". */
+export declare function toUiLayerKey(name: string | undefined | null): string;
+export interface Refable {
+    id: string;
+    key?: string;
+    name: string;
+}
+/** Key, then id, then exact name — the same order SceneHandle uses. Undefined when nothing matches. */
+export declare function resolveUiRef<T extends Refable>(items: readonly T[], ref: string): T | undefined;
+//# sourceMappingURL=uiKeys.d.ts.map

package/dist/ui/uiKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiKeys.d.ts","sourceRoot":"","sources":["../../src/ui/uiKeys.ts"],"names":[],"mappings":"AAOA,OAAO,EAAyB,gBAAgB,EAAe,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE5G,eAAO,MAAM,iBAAiB,KAAwB,CAAC;AACvD,eAAO,MAAM,iBAAiB,yBAAmB,CAAC;AAClD,eAAO,MAAM,gBAAgB,wBAAkB,CAAC;AAEhD,sHAAsH;AACtH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAGpE;AAED,MAAM,WAAW,OAAO;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAEnE,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAG/F"}

package/dist/ui/uiKeys.js

@@ -0,0 +1,22 @@
+// =============================================================================
+// UI layer keys — same slug rules as action keys
+// =============================================================================
+//
+// Derived once from the name, then frozen; unique per project (the data-center
+// enforces it on save, like action keys — it keeps its own copy of the slug code).
+//
+import { ACTION_KEY_MAX_LENGTH, isValidActionKey, toActionKey, uniqueActionKey } from '../utils/actionKeys.js';
+export const UI_KEY_MAX_LENGTH = ACTION_KEY_MAX_LENGTH;
+export const isValidUiLayerKey = isValidActionKey;
+export const uniqueUiLayerKey = uniqueActionKey;
+/** "Door controls" -> "door-controls". A name with no latin letters or digits (Hebrew, emoji…) falls back to "ui". */
+export function toUiLayerKey(name) {
+    const slug = toActionKey(name);
+    return slug === 'action' && !/\baction\b/i.test(name ?? '') ? 'ui' : slug;
+}
+/** Key, then id, then exact name — the same order SceneHandle uses. Undefined when nothing matches. */
+export function resolveUiRef(items, ref) {
+    if (!ref)
+        return undefined;
+    return items.find(i => i.key === ref) ?? items.find(i => i.id === ref) ?? items.find(i => i.name === ref);
+}

package/dist/ui/uiSanitize.d.ts

@@ -0,0 +1,18 @@
+export interface SanitizeResult {
+    out: string;
+    /** What was removed or changed, for the agent / the studio to show. */
+    removed: string[];
+}
+/** Keep the rules the browser understood and that are safe; drop the rest. */
+export declare function sanitizeUiCss(css: string): SanitizeResult;
+/** Parse, clean and serialise a layer's HTML. Always returns something safe to assign to innerHTML. */
+export declare function sanitizeUiHtml(html: string): SanitizeResult;
+/** Both fields of a layer. */
+export declare function sanitizeUiLayer<T extends {
+    html: string;
+    css: string;
+}>(layer: T): {
+    layer: T;
+    removed: string[];
+};
+//# sourceMappingURL=uiSanitize.d.ts.map

package/dist/ui/uiSanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiSanitize.d.ts","sourceRoot":"","sources":["../../src/ui/uiSanitize.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,cAAc;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,OAAO,EAAE,MAAM,EAAE,CAAC;CACrB;AAmFD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAQzD;AA2ED,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAK3D;AAED,8BAA8B;AAC9B,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAIlH"}

package/dist/ui/uiSanitize.js

@@ -0,0 +1,251 @@
+// =============================================================================
+// Sanitizer for UI layers
+// =============================================================================
+//
+// Agent-written HTML/CSS runs on 3drise.ai and on other people's sites, so it is
+// reduced to a closed, script-free subset before it is stored and again before it is
+// rendered (the viewer never trusts what it is handed). Browser only: it needs
+// DOMParser and constructable stylesheets.
+//
+// HTML:  tag + attribute allow-lists. Scripts, styles, forms, frames, `on*`,
+//        `javascript:` links and non-https / non-image sources are removed.
+// CSS:   parsed by the browser (CSSOM), so escapes cannot hide anything; rules are
+//        re-serialised from what the browser understood. @import, @font-face and
+//        other at-rules are dropped (system fonts only); a rule with a `url()` that
+//        is not https: / data:image / #fragment is dropped. External https images are
+//        allowed — that is the one thing a layer can fetch.
+//
+const HTML_TAGS = new Set([
+    'div', 'span', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'button', 'a', 'label', 'input', 'select', 'option',
+    'ul', 'ol', 'li', 'img', 'small', 'strong', 'em', 'b', 'i', 'u', 'br', 'hr', 'section', 'header', 'footer', 'nav',
+    'article', 'aside', 'figure', 'figcaption', 'table', 'thead', 'tbody', 'tr', 'td', 'th', 'dl', 'dt', 'dd', 'sub', 'sup', 'kbd', 'code', 'pre',
+]);
+const SVG_TAGS = new Set([
+    'svg', 'g', 'path', 'circle', 'ellipse', 'rect', 'line', 'polyline', 'polygon', 'defs', 'lineargradient', 'radialgradient',
+    'stop', 'title', 'desc', 'text', 'tspan', 'clippath', 'mask',
+]);
+/** Removed with their whole content (not unwrapped). */
+const DROP_TAGS = new Set([
+    'script', 'style', 'iframe', 'frame', 'frameset', 'object', 'embed', 'applet', 'link', 'meta', 'base', 'template', 'noscript',
+    'form', 'textarea', 'video', 'audio', 'source', 'track', 'canvas', 'portal', 'dialog',
+    'use', 'foreignobject', 'animate', 'animatetransform', 'animatemotion', 'set', 'image', 'filter', 'pattern', 'symbol', 'marker',
+]);
+const GLOBAL_ATTRS = new Set([
+    'class', 'id', 'style', 'title', 'role', 'hidden', 'lang', 'dir', 'draggable',
+]);
+const HTML_ATTRS = new Set([
+    'href', 'src', 'alt', 'width', 'height', 'type', 'min', 'max', 'step', 'value', 'placeholder', 'checked', 'disabled',
+    'for', 'tabindex', 'target', 'rel', 'colspan', 'rowspan', 'selected', 'readonly', 'maxlength', 'inputmode',
+]);
+const SVG_ATTRS = new Set([
+    'viewbox', 'd', 'fill', 'stroke', 'stroke-width', 'stroke-linecap', 'stroke-linejoin', 'stroke-opacity', 'fill-opacity',
+    'opacity', 'cx', 'cy', 'r', 'rx', 'ry', 'x', 'y', 'x1', 'y1', 'x2', 'y2', 'width', 'height', 'points', 'transform',
+    'offset', 'stop-color', 'stop-opacity', 'gradientunits', 'gradienttransform', 'fill-rule', 'clip-rule',
+    'preserveaspectratio', 'xmlns', 'font-size', 'text-anchor', 'dominant-baseline', 'stroke-dasharray', 'stroke-dashoffset',
+    'clip-path', 'mask', 'vector-effect',
+]);
+const INPUT_TYPES = new Set(['range', 'text', 'number', 'checkbox', 'radio', 'search', 'color']);
+const IMG_DATA = /^data:image\/(png|jpe?g|gif|webp|avif|svg\+xml)[;,]/i;
+const isHttps = (u) => /^https:\/\//i.test(u);
+/** Normalised CSS text is checked, never the raw text: the browser has already resolved escapes. */
+const BAD_CSS = /expression\s*\(|javascript:|vbscript:|-moz-binding|behavior\s*:|image-set\s*\(|\bsrc\s*\(|@import/i;
+const URL_RE = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^)\s]*))\s*\)/gi;
+function cssTextIsSafe(text) {
+    if (BAD_CSS.test(text))
+        return false;
+    URL_RE.lastIndex = 0;
+    let m;
+    while ((m = URL_RE.exec(text))) {
+        const u = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+        if (!(isHttps(u) || IMG_DATA.test(u) || u.startsWith('#')))
+            return false;
+    }
+    return true;
+}
+function newSheet() {
+    try {
+        return new CSSStyleSheet();
+    }
+    catch {
+        return null;
+    }
+}
+const GROUPING = /^@(media|supports|container|layer)\b/i;
+function serializeRule(rule, removed) {
+    const text = rule.cssText;
+    if (rule instanceof CSSStyleRule) {
+        const own = rule.style.cssText;
+        if (!cssTextIsSafe(own) || !cssTextIsSafe(rule.selectorText)) {
+            removed.push(`rule ${rule.selectorText}`);
+            return '';
+        }
+        const nested = Array.from(rule.cssRules ?? []).map(r => serializeRule(r, removed)).join('');
+        return `${rule.selectorText}{${own}${nested ? ';' + nested : ''}}`;
+    }
+    if (rule instanceof CSSKeyframesRule) {
+        const frames = Array.from(rule.cssRules).map(f => {
+            const k = f;
+            return cssTextIsSafe(k.style.cssText) ? `${k.keyText}{${k.style.cssText}}` : '';
+        }).join('');
+        return `@keyframes ${rule.name}{${frames}}`;
+    }
+    if (GROUPING.test(text) && 'cssRules' in rule) {
+        const header = text.slice(0, text.indexOf('{')).trim();
+        if (!cssTextIsSafe(header)) {
+            removed.push(header);
+            return '';
+        }
+        const inner = Array.from(rule.cssRules).map(r => serializeRule(r, removed)).join('');
+        return `${header}{${inner}}`;
+    }
+    removed.push(text.slice(0, 40).replace(/\s+/g, ' '));
+    return '';
+}
+/** Keep the rules the browser understood and that are safe; drop the rest. */
+export function sanitizeUiCss(css) {
+    const removed = [];
+    const sheet = newSheet();
+    if (!sheet)
+        return { out: '', removed: ['this browser cannot sanitize CSS (no constructable stylesheets); the CSS was not applied'] };
+    try {
+        sheet.replaceSync(css ?? '');
+    }
+    catch {
+        return { out: '', removed: ['the CSS could not be parsed'] };
+    }
+    const out = Array.from(sheet.cssRules).map(r => serializeRule(r, removed)).join('\n');
+    if (/@import/i.test(css ?? ''))
+        removed.push('@import');
+    return { out, removed };
+}
+/** An inline `style="…"` value, normalised, or '' when unsafe. */
+function sanitizeStyleAttr(value, removed) {
+    const sheet = newSheet();
+    if (!sheet) {
+        removed.push('style attribute');
+        return '';
+    }
+    try {
+        sheet.replaceSync(`x{${value}}`);
+    }
+    catch {
+        return '';
+    }
+    const rule = sheet.cssRules[0];
+    const text = rule instanceof CSSStyleRule ? rule.style.cssText : '';
+    if (!cssTextIsSafe(text)) {
+        removed.push('style attribute (unsafe url or function)');
+        return '';
+    }
+    return text;
+}
+const describe = (el) => `<${el.localName}>`;
+function cleanElement(el, removed) {
+    const tag = el.localName.toLowerCase();
+    const isSvg = el.namespaceURI === 'http://www.w3.org/2000/svg';
+    const allowedAttrs = isSvg ? SVG_ATTRS : HTML_ATTRS;
+    for (const attr of Array.from(el.attributes)) {
+        const name = attr.name.toLowerCase();
+        const value = attr.value;
+        let keep = false;
+        if (name.startsWith('data-') || name.startsWith('aria-'))
+            keep = true;
+        else if (GLOBAL_ATTRS.has(name))
+            keep = true;
+        else if (allowedAttrs.has(name))
+            keep = true;
+        if (!keep) {
+            removed.push(`${describe(el)} ${name}`);
+            el.removeAttribute(attr.name);
+            continue;
+        }
+        if (name === 'style') {
+            const clean = sanitizeStyleAttr(value, removed);
+            if (clean)
+                el.setAttribute('style', clean);
+            else
+                el.removeAttribute('style');
+        }
+        else if (name === 'href') {
+            if (!(isHttps(value) || /^mailto:/i.test(value) || value.startsWith('#'))) {
+                removed.push(`${describe(el)} href`);
+                el.removeAttribute(attr.name);
+            }
+        }
+        else if (name === 'src') {
+            if (!(isHttps(value) || IMG_DATA.test(value))) {
+                removed.push(`${describe(el)} src`);
+                el.removeAttribute(attr.name);
+            }
+        }
+        else if (name === 'target') {
+            if (value !== '_blank')
+                el.removeAttribute(attr.name);
+        }
+        else if (name === 'tabindex') {
+            if (value !== '0' && value !== '-1')
+                el.removeAttribute(attr.name);
+        }
+        else if (name === 'type') {
+            if (tag === 'input' && !INPUT_TYPES.has(value.toLowerCase())) {
+                removed.push(`input type=${value}`);
+                el.setAttribute('type', 'text');
+            }
+            if (tag === 'button')
+                el.setAttribute('type', 'button');
+        }
+        else if (isSvg && (name === 'fill' || name === 'stroke' || name === 'clip-path' || name === 'mask')) {
+            if (!cssTextIsSafe(value)) {
+                removed.push(`${describe(el)} ${name}`);
+                el.removeAttribute(attr.name);
+            }
+        }
+    }
+    if (tag === 'button' && !el.hasAttribute('type'))
+        el.setAttribute('type', 'button');
+    if (tag === 'a') {
+        el.setAttribute('rel', 'noopener noreferrer');
+    }
+}
+function cleanChildren(parent, removed) {
+    for (const child of Array.from(parent.childNodes)) {
+        if (child.nodeType === 1) {
+            const el = child;
+            const tag = el.localName.toLowerCase();
+            const isSvg = el.namespaceURI === 'http://www.w3.org/2000/svg';
+            if (DROP_TAGS.has(tag)) {
+                removed.push(`<${tag}>`);
+                parent.removeChild(el);
+                continue;
+            }
+            if (!(isSvg ? SVG_TAGS : HTML_TAGS).has(tag)) {
+                // Unknown tag: keep its content, drop the tag.
+                removed.push(`<${tag}>`);
+                while (el.firstChild)
+                    parent.insertBefore(el.firstChild, el);
+                parent.removeChild(el);
+                // The moved children are before `el`'s old position; re-clean the parent's new children.
+                cleanChildren(parent, removed);
+                return;
+            }
+            cleanElement(el, removed);
+            cleanChildren(el, removed);
+        }
+        else if (child.nodeType !== 3) {
+            parent.removeChild(child); // comments, processing instructions
+        }
+    }
+}
+/** Parse, clean and serialise a layer's HTML. Always returns something safe to assign to innerHTML. */
+export function sanitizeUiHtml(html) {
+    const removed = [];
+    const doc = new DOMParser().parseFromString(`<!doctype html><body>${html ?? ''}`, 'text/html');
+    cleanChildren(doc.body, removed);
+    return { out: doc.body.innerHTML, removed: Array.from(new Set(removed)) };
+}
+/** Both fields of a layer. */
+export function sanitizeUiLayer(layer) {
+    const h = sanitizeUiHtml(layer.html);
+    const c = sanitizeUiCss(layer.css);
+    return { layer: { ...layer, html: h.out, css: c.out }, removed: [...h.removed, ...c.removed] };
+}

package/dist/ui/uiSpec.d.ts

@@ -0,0 +1,116 @@
+export interface UiLayer {
+    id: string;
+    /** Stable, code-facing name; unique per project (see uiKeys). */
+    key: string;
+    name: string;
+    description?: string;
+    html: string;
+    css: string;
+    visible: boolean;
+    /** Position in the project's list (junction table `layerOrder`). */
+    layerOrder?: number;
+}
+export type UiRefKind = 'action' | 'sequence' | 'clip';
+/** `ui` addresses an element of the same layer by CSS id: `ui.toggle:#menu`. */
+export type UiCommandKind = UiRefKind | 'ui';
+/** Attributes that run commands. */
+export declare const UI_TRIGGER_ATTRS: {
+    readonly click: "data-click";
+    readonly hoverIn: "data-hover-in";
+    readonly hoverOut: "data-hover-out";
+};
+export type UiTrigger = keyof typeof UI_TRIGGER_ATTRS;
+export declare const UI_ATTR: {
+    readonly bind: "data-bind";
+    readonly state: "data-state";
+    readonly showWhen: "data-show-when";
+    readonly anchor: "data-anchor";
+    readonly anchorOcclude: "data-anchor-occlude";
+    readonly anchorOffset: "data-anchor-offset";
+    readonly set: "data-set";
+    readonly setValue: "data-set-value";
+    readonly click: "data-click";
+    readonly hoverIn: "data-hover-in";
+    readonly hoverOut: "data-hover-out";
+};
+/** Verbs per command kind. `toggle` for sequences and clips alternates forward / backward. */
+export declare const UI_VERBS: Record<UiCommandKind, readonly string[]>;
+export interface UiCommand {
+    kind: UiCommandKind;
+    verb: string;
+    ref: string;
+}
+/** A condition on scene state: `action:key`, `!sequence:key`, `ui:#panel`. */
+export interface UiCondition {
+    negate: boolean;
+    kind: UiCommandKind;
+    ref: string;
+}
+export interface UiBind {
+    kind: 'sequence' | 'clip';
+    ref: string;
+}
+export interface UiAnchor {
+    /** Object ref (id or name). */
+    object: string;
+    /** Name of a node inside a model. */
+    node?: string;
+}
+/** What `data-set` writes to: an object (or a node of a model), or one of the environment elements. */
+export declare const UI_SET_ENVIRONMENT: readonly ["camera", "sky", "clouds", "ocean", "terrain"];
+export interface UiSetTarget {
+    /** `camera` / `sky` / `clouds` / `ocean` / `terrain`, or an object ref (key, id or name). */
+    target: string;
+    /** Name of a node inside a model. */
+    node?: string;
+    /** Settings path, the same ones clip tracks use: `materialSettings.opacity`, `meshSettings.position.y`, `config.intensity`. */
+    path: string;
+}
+/** `engine:materialSettings.opacity`, `engine/Door_L:meshSettings.rotation.y`, `sky:elevation`. */
+export declare function parseSetTarget(value: string | null | undefined): {
+    set?: UiSetTarget;
+    error?: string;
+};
+/** The value of `data-set-value`: a number, true/false, a JSON array (`[1,0,0]`), or a string (`#ff0000`). */
+export declare function parseSetValue(value: string | null | undefined): number | boolean | string | number[] | undefined;
+/** `action.toggle:open-door sequence.play:intro` */
+export declare function parseCommands(value: string | null | undefined): {
+    commands: UiCommand[];
+    errors: string[];
+};
+/** `action:open-door !sequence:intro ui:#menu` — all must hold. */
+export declare function parseConditions(value: string | null | undefined): {
+    conditions: UiCondition[];
+    errors: string[];
+};
+/** `sequence:intro` or `clip:spin` (for <input type="range">). */
+export declare function parseBind(value: string | null | undefined): {
+    bind?: UiBind;
+    error?: string;
+};
+/** `object:engine` or `object:engine/Door_L` (the node name is everything after the first slash). */
+export declare function parseAnchor(value: string | null | undefined): {
+    anchor?: UiAnchor;
+    error?: string;
+};
+/** `12 -8` (px, from the projected point). */
+export declare function parseOffset(value: string | null | undefined): [number, number] | null;
+export declare const UI_CLASS_PREFIX = "rise-";
+export interface UiClassInfo {
+    name: string;
+    /** What it is for — shown in the agent docs. */
+    use: string;
+    /** Elements the validator expects it on (warns when a control has none of the generic classes). */
+    for?: string;
+}
+export declare const UI_CLASSES: readonly UiClassInfo[];
+export interface UiVariableInfo {
+    name: string;
+    default: string;
+    use: string;
+}
+/** Set on the page (or the host element) to restyle every layer at once. */
+export declare const UI_VARIABLES: readonly UiVariableInfo[];
+/** Class of the host element each layer is rendered in (target it from the page to override variables). */
+export declare const UI_HOST_CLASS = "rise-ui-layer";
+//# sourceMappingURL=uiSpec.d.ts.map

package/dist/ui/uiSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiSpec.d.ts","sourceRoot":"","sources":["../../src/ui/uiSpec.ts"],"names":[],"mappings":"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"}