@3driseai/3drise-core 1.0.20 → 1.0.22

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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"}

package/dist/ui/uiSpec.js

@@ -0,0 +1,173 @@
+// =============================================================================
+// UI layers — the spec (types, vocabulary, attribute grammar)
+// =============================================================================
+//
+// A UI layer is HTML + CSS written by the AI agent (or by hand) that controls the
+// scene through data attributes. The viewer's binder turns the attributes into calls
+// on the project's SceneHandle (actions, clips, sequences). This file is the single
+// source of the vocabulary: the binder, the validator, the agent docs and the base
+// stylesheet all read it, so they cannot drift apart.
+//
+//   <button class="rise-button" data-click="action.toggle:open-door">Open</button>
+//
+// Refs are an item's key, then its id, then its exact name (same as SceneHandle).
+// Commands are separated by spaces, so a ref used in an attribute cannot contain one:
+// address things by key.
+//
+/** Attributes that run commands. */
+export const UI_TRIGGER_ATTRS = {
+    click: 'data-click',
+    hoverIn: 'data-hover-in',
+    hoverOut: 'data-hover-out',
+};
+export const UI_ATTR = {
+    ...UI_TRIGGER_ATTRS,
+    bind: 'data-bind',
+    state: 'data-state',
+    showWhen: 'data-show-when',
+    anchor: 'data-anchor',
+    anchorOcclude: 'data-anchor-occlude',
+    anchorOffset: 'data-anchor-offset',
+    set: 'data-set',
+    setValue: 'data-set-value',
+};
+/** Verbs per command kind. `toggle` for sequences and clips alternates forward / backward. */
+export const UI_VERBS = {
+    action: ['apply', 'revert', 'toggle'],
+    sequence: ['play', 'reverse', 'pause', 'resume', 'stop', 'toggle'],
+    clip: ['play', 'reverse', 'pause', 'resume', 'stop', 'toggle'],
+    ui: ['show', 'hide', 'toggle'],
+};
+/** What `data-set` writes to: an object (or a node of a model), or one of the environment elements. */
+export const UI_SET_ENVIRONMENT = ['camera', 'sky', 'clouds', 'ocean', 'terrain'];
+/** `engine:materialSettings.opacity`, `engine/Door_L:meshSettings.rotation.y`, `sky:elevation`. */
+export function parseSetTarget(value) {
+    // One target per attribute, so (unlike the command lists) names may contain spaces.
+    const m = /^([^:/]+?)(?:\/([^:]+?))?:([A-Za-z_][\w.]*)$/.exec((value ?? '').trim());
+    return m
+        ? { set: { target: m[1].trim(), node: m[2]?.trim(), path: m[3] } }
+        : { error: `"${value ?? ''}" is not target:path (e.g. engine:materialSettings.opacity or sky:elevation).` };
+}
+/** The value of `data-set-value`: a number, true/false, a JSON array (`[1,0,0]`), or a string (`#ff0000`). */
+export function parseSetValue(value) {
+    if (value == null)
+        return undefined;
+    const t = value.trim();
+    if (t === 'true')
+        return true;
+    if (t === 'false')
+        return false;
+    if (/^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i.test(t))
+        return Number(t);
+    if (t.startsWith('[')) {
+        try {
+            const a = JSON.parse(t);
+            if (Array.isArray(a) && a.every(n => typeof n === 'number'))
+                return a;
+        }
+        catch { /* fall through */ }
+    }
+    return t;
+}
+const KINDS = ['action', 'sequence', 'clip', 'ui'];
+const isKind = (k) => KINDS.includes(k);
+const tokens = (value) => (value ?? '').split(/\s+/).filter(Boolean);
+/** `action.toggle:open-door sequence.play:intro` */
+export function parseCommands(value) {
+    const commands = [];
+    const errors = [];
+    for (const token of tokens(value)) {
+        const m = /^([a-z]+)\.([a-z]+):(.+)$/.exec(token);
+        if (!m) {
+            errors.push(`"${token}" is not kind.verb:ref (e.g. action.toggle:open-door).`);
+            continue;
+        }
+        const [, kind, verb, ref] = m;
+        if (!isKind(kind)) {
+            errors.push(`"${token}": unknown kind "${kind}". Use ${KINDS.join(', ')}.`);
+            continue;
+        }
+        if (!UI_VERBS[kind].includes(verb)) {
+            errors.push(`"${token}": ${kind} has no verb "${verb}". Use ${UI_VERBS[kind].join(', ')}.`);
+            continue;
+        }
+        if (kind === 'ui' && !/^#[A-Za-z][\w-]*$/.test(ref)) {
+            errors.push(`"${token}": ui commands address an element id in this layer, like ui.toggle:#menu.`);
+            continue;
+        }
+        commands.push({ kind, verb, ref });
+    }
+    return { commands, errors };
+}
+/** `action:open-door !sequence:intro ui:#menu` — all must hold. */
+export function parseConditions(value) {
+    const conditions = [];
+    const errors = [];
+    for (const raw of tokens(value)) {
+        const negate = raw.startsWith('!');
+        const token = negate ? raw.slice(1) : raw;
+        const m = /^([a-z]+):(.+)$/.exec(token);
+        if (!m || !isKind(m[1])) {
+            errors.push(`"${raw}" is not [!]kind:ref (e.g. action:open-door).`);
+            continue;
+        }
+        if (m[1] === 'ui' && !/^#[A-Za-z][\w-]*$/.test(m[2])) {
+            errors.push(`"${raw}": ui conditions address an element id in this layer, like ui:#menu.`);
+            continue;
+        }
+        conditions.push({ negate, kind: m[1], ref: m[2] });
+    }
+    return { conditions, errors };
+}
+/** `sequence:intro` or `clip:spin` (for <input type="range">). */
+export function parseBind(value) {
+    const m = /^(sequence|clip):(.+)$/.exec((value ?? '').trim());
+    return m ? { bind: { kind: m[1], ref: m[2] } } : { error: `"${value ?? ''}" is not sequence:ref or clip:ref.` };
+}
+/** `object:engine` or `object:engine/Door_L` (the node name is everything after the first slash). */
+export function parseAnchor(value) {
+    const m = /^object:([^/]+)(?:\/(.+))?$/.exec((value ?? '').trim());
+    return m ? { anchor: { object: m[1], node: m[2] } } : { error: `"${value ?? ''}" is not object:ref or object:ref/NodeName.` };
+}
+/** `12 -8` (px, from the projected point). */
+export function parseOffset(value) {
+    const p = tokens(value).map(Number);
+    return p.length === 2 && p.every(Number.isFinite) ? [p[0], p[1]] : null;
+}
+// ---------------------------------------------------------------------------
+// Generic classes + variables (the base stylesheet in the viewer implements them)
+// ---------------------------------------------------------------------------
+//
+// The prefix is `rise-`, not `3drise-`: a CSS class cannot start with a digit
+// without escaping (`.3drise-button` is invalid; it has to be `.\33 drise-button`).
+export const UI_CLASS_PREFIX = 'rise-';
+export const UI_CLASSES = [
+    { name: 'rise-panel', use: 'A container grouping controls (a bar, a drawer, a side panel).' },
+    { name: 'rise-button', use: 'A button. Pressed / active state: [data-on="true"] when it has data-state.', for: 'button' },
+    { name: 'rise-toggle', use: 'A button showing an on/off state (use with data-state).', for: 'button' },
+    { name: 'rise-slider', use: 'A range input (<input type="range">), often with data-bind.', for: 'input[type=range]' },
+    { name: 'rise-input', use: 'A text or number input.', for: 'input' },
+    { name: 'rise-menu', use: 'A list of choices (a column of rise-menu-item).' },
+    { name: 'rise-menu-item', use: 'One choice in a rise-menu. Selected: [data-on="true"].' },
+    { name: 'rise-card', use: 'An info card.' },
+    { name: 'rise-card-title', use: 'The card heading.' },
+    { name: 'rise-card-body', use: 'The card text.' },
+    { name: 'rise-card-image', use: 'An <img> in a card.' },
+    { name: 'rise-hotspot', use: 'A marker anchored to an object or model part (data-anchor).' },
+    { name: 'rise-label', use: 'A small text label.' },
+];
+/** Set on the page (or the host element) to restyle every layer at once. */
+export const UI_VARIABLES = [
+    { name: '--rise-accent', default: '#6ea8ff', use: 'Accent colour: active states, slider thumb, hotspot.' },
+    { name: '--rise-accent-text', default: '#0b1220', use: 'Text on the accent colour.' },
+    { name: '--rise-bg', default: 'rgba(18, 22, 32, 0.72)', use: 'Control and card background.' },
+    { name: '--rise-text', default: '#f2f5fa', use: 'Text colour.' },
+    { name: '--rise-muted', default: 'rgba(242, 245, 250, 0.65)', use: 'Secondary text.' },
+    { name: '--rise-border', default: 'rgba(255, 255, 255, 0.16)', use: 'Border colour.' },
+    { name: '--rise-radius', default: '10px', use: 'Corner radius.' },
+    { name: '--rise-gap', default: '8px', use: 'Spacing between grouped controls.' },
+    { name: '--rise-font', default: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif', use: 'Font family (system fonts only).' },
+    { name: '--rise-blur', default: '12px', use: 'Backdrop blur of panels and cards.' },
+];
+/** Class of the host element each layer is rendered in (target it from the page to override variables). */
+export const UI_HOST_CLASS = 'rise-ui-layer';

package/dist/utils/environmentMigration.d.ts

@@ -0,0 +1,3 @@
+import type { CreatedObjectSettings } from '../types/scene3d';
+export declare function migrateEnvironmentObject<T extends CreatedObjectSettings>(obj: T): T;
+//# sourceMappingURL=environmentMigration.d.ts.map

package/dist/utils/environmentMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environmentMigration.d.ts","sourceRoot":"","sources":["../../src/utils/environmentMigration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAgB9D,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,qBAAqB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAkCnF"}

package/dist/utils/environmentMigration.js

@@ -0,0 +1,50 @@
+// =============================================================================
+// Environment objects — load-time migration of the legacy rain
+// =============================================================================
+//
+// Rain used to sit outside the environment family, with its own animation domain:
+// its keyframes in `animations.rain`, its pointer bindings in `mouseMove.rain`.
+// It is a family member now, driven through `animations.environment` /
+// `mouseMove.environment` like every other environment object, so a saved rain's
+// tracks move over (appended to anything already there). The never-rendered
+// `splash` knob is dropped.
+//
+// Pure and idempotent: returns the same object when there is nothing to migrate.
+//
+export function migrateEnvironmentObject(obj) {
+    if (!obj || obj.type !== 'environment')
+        return obj;
+    const config = obj.config;
+    if (!config || config.type !== 'rain')
+        return obj;
+    const animations = obj.animations;
+    const mouseMove = obj.mouseMove;
+    const hasAnim = !!animations && 'rain' in animations;
+    const hasMouse = !!mouseMove && typeof mouseMove === 'object' && 'rain' in mouseMove;
+    if (!('splash' in config) && !hasAnim && !hasMouse)
+        return obj;
+    const next = { ...obj };
+    if ('splash' in config) {
+        const { splash: _splash, ...rest } = config;
+        next.config = rest;
+    }
+    if (hasAnim) {
+        const { rain, ...others } = animations;
+        const env = others.environment ?? {};
+        next.animations = {
+            ...others,
+            environment: { ...rain, ...env, animations: [...(env.animations ?? []), ...(rain?.animations ?? [])] },
+        };
+    }
+    if (hasMouse) {
+        const { rain, ...others } = mouseMove;
+        const env = others.environment;
+        next.mouseMove = {
+            ...others,
+            environment: env
+                ? { ...env, enabled: env.enabled || !!rain?.enabled, properties: [...(env.properties ?? []), ...(rain?.properties ?? [])] }
+                : rain,
+        };
+    }
+    return next;
+}

package/dist/utils/generativeAnimatable.d.ts

@@ -2,7 +2,7 @@ export interface AnimatableConfigProperty {
     value: string;
     label: string;
 }
-export type GenerativeFamily = 'particles' | 'lights' | 'effects' | 'grids';
+export type GenerativeFamily = 'particles' | 'lights' | 'effects' | 'grids' | 'environment' | 'space' | 'land' | 'text';
 /** The animatable knobs of one generative object, by family and config.type. */
 export declare function getGenerativeAnimatable(family: GenerativeFamily, config: {
     type?: string;

package/dist/utils/generativeAnimatable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generativeAnimatable.d.ts","sourceRoot":"","sources":["../../src/utils/generativeAnimatable.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAY5E,gFAAgF;AAChF,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,wBAAwB,EAAE,CAM5B;AAED,sFAAsF;AACtF,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,OAAO,CAGT"}
+{"version":3,"file":"generativeAnimatable.d.ts","sourceRoot":"","sources":["../../src/utils/generativeAnimatable.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAoBxH,gFAAgF;AAChF,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,wBAAwB,EAAE,CAM5B;AAED,sFAAsF;AACtF,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,OAAO,CAGT"}

package/dist/utils/generativeAnimatable.js

@@ -2,6 +2,10 @@ import { GENERATIVE_PARTICLES_ANIMATABLE } from "../data/particlesDefaults.js";
 import { LIGHTS_ANIMATABLE } from "../data/lightsDefaults.js";
 import { EFFECTS_ANIMATABLE } from "../data/effectsDefaults.js";
 import { GRIDS_ANIMATABLE } from "../data/gridsDefaults.js";
+import { ENVIRONMENT_OBJECTS_ANIMATABLE } from "../data/environmentDefaults.js";
+import { SPACE_OBJECTS_ANIMATABLE } from "../data/spaceDefaults.js";
+import { LAND_OBJECTS_ANIMATABLE } from "../data/landDefaults.js";
+import { TEXT_OBJECTS_ANIMATABLE } from "../data/textDefaults.js";
 // Partial: grids list only the types converted to the config pattern so far (effects list all).
 const FAMILIES = {
     particles: GENERATIVE_PARTICLES_ANIMATABLE,
@@ -10,6 +14,14 @@ const FAMILIES = {
     lights: LIGHTS_ANIMATABLE,
     effects: EFFECTS_ANIMATABLE,
     grids: GRIDS_ANIMATABLE,
+    // Weather objects (type 'environment'): snow… The legacy rain is not in this table.
+    environment: ENVIRONMENT_OBJECTS_ANIMATABLE,
+    // Celestial bodies and backdrops (type 'space'): stars, earth, solarSystem, shootingStars.
+    space: SPACE_OBJECTS_ANIMATABLE,
+    // Placeable patches of terrain (type 'land'): mountains, hills, dunes, canyon.
+    land: LAND_OBJECTS_ANIMATABLE,
+    // Animated text looks (type 'text', config.type set): handwriting, neonTube, fourierSketch. The legacy bitmap / 3D text is not in this table.
+    text: TEXT_OBJECTS_ANIMATABLE,
 };
 /** The animatable knobs of one generative object, by family and config.type. */
 export function getGenerativeAnimatable(family, config) {

package/dist/utils/getAnimatableProperties.d.ts

@@ -1,6 +1,6 @@
 import type { MouseMoveInteraction, MouseMoveInteractions, ObjectAnimations } from "../types/objectSettings";
 import type { PropertyKind } from "../properties/types";
-export type AnimatableDomain = 'transform' | 'material' | 'edges' | 'light' | 'clouds' | 'rain' | 'particles' | 'effect' | 'grid';
+export type AnimatableDomain = 'transform' | 'material' | 'edges' | 'light' | 'clouds' | 'rain' | 'particles' | 'effect' | 'grid' | 'environment' | 'space' | 'land' | 'text' | 'sky' | 'ocean' | 'terrain';
 export interface AnimatableProperty {
     value: string;
     label: string;