@dicebear/core 10.0.0-rc.1 → 10.0.0-rc.3

package/lib/Resolver.js

@@ -0,0 +1,203 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Resolver_instances, _Resolver_style, _Resolver_options, _Resolver_prng, _Resolver_colorResolving, _Resolver_result, _Resolver_probability, _Resolver_isVisible, _Resolver_resolveColor, _Resolver_colorFillStops, _Resolver_pickFloat, _Resolver_memo;
+import { Prng } from './Prng.js';
+import { Color } from './Utils/Color.js';
+import { CircularColorReferenceError } from './Error/CircularColorReferenceError.js';
+/**
+ * Bundles the three inputs needed to derive any deterministic value for an
+ * avatar — the {@link Style}, the validated user {@link Options}, and a
+ * seeded {@link Prng} — and exposes them as named accessors. Each accessor
+ * memoizes its result so that repeated calls cannot drift, and the memo
+ * doubles as the snapshot returned by {@link resolved}.
+ */
+export class Resolver {
+    constructor(style, options) {
+        _Resolver_instances.add(this);
+        _Resolver_style.set(this, void 0);
+        _Resolver_options.set(this, void 0);
+        _Resolver_prng.set(this, void 0);
+        _Resolver_colorResolving.set(this, []);
+        _Resolver_result.set(this, {});
+        __classPrivateFieldSet(this, _Resolver_style, style, "f");
+        __classPrivateFieldSet(this, _Resolver_options, options, "f");
+        __classPrivateFieldSet(this, _Resolver_prng, new Prng(this.seed()), "f");
+    }
+    seed() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'seed', () => __classPrivateFieldGet(this, _Resolver_options, "f").seed() ?? '');
+    }
+    size() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'size', () => __classPrivateFieldGet(this, _Resolver_options, "f").size());
+    }
+    idRandomization() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'idRandomization', () => __classPrivateFieldGet(this, _Resolver_options, "f").idRandomization() ?? false);
+    }
+    title() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'title', () => __classPrivateFieldGet(this, _Resolver_options, "f").title());
+    }
+    flip() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'flip', () => __classPrivateFieldGet(this, _Resolver_prng, "f").pick('flip', __classPrivateFieldGet(this, _Resolver_options, "f").flip()) ?? 'none');
+    }
+    fontFamily() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'fontFamily', () => __classPrivateFieldGet(this, _Resolver_prng, "f").pick('fontFamily', __classPrivateFieldGet(this, _Resolver_options, "f").fontFamily()) ?? 'system-ui');
+    }
+    fontWeight() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'fontWeight', () => __classPrivateFieldGet(this, _Resolver_prng, "f").pick('fontWeight', __classPrivateFieldGet(this, _Resolver_options, "f").fontWeight()) ?? 400);
+    }
+    scale() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'scale', () => __classPrivateFieldGet(this, _Resolver_prng, "f").float('scale', __classPrivateFieldGet(this, _Resolver_options, "f").scale()) ?? 1);
+    }
+    borderRadius() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'borderRadius', () => __classPrivateFieldGet(this, _Resolver_prng, "f").float('borderRadius', __classPrivateFieldGet(this, _Resolver_options, "f").borderRadius()) ?? 0);
+    }
+    rotate() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'rotate', () => __classPrivateFieldGet(this, _Resolver_prng, "f").float('rotate', __classPrivateFieldGet(this, _Resolver_options, "f").rotate()) ?? 0);
+    }
+    translateX() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'translateX', () => __classPrivateFieldGet(this, _Resolver_prng, "f").float('translateX', __classPrivateFieldGet(this, _Resolver_options, "f").translateX()) ?? 0);
+    }
+    translateY() {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, 'translateY', () => __classPrivateFieldGet(this, _Resolver_prng, "f").float('translateY', __classPrivateFieldGet(this, _Resolver_options, "f").translateY()) ?? 0);
+    }
+    /**
+     * Selects a variant for the given component. Depending on what was passed
+     * as `${name}Variant` in the input data:
+     *
+     * - `undefined`: PRNG picks from all style variants using their weights.
+     * - `string` or `string[]`: PRNG picks from the given subset (weight 1 each).
+     * - `Record<string, number>`: PRNG picks using the provided weights.
+     *
+     * Only variants that exist in the style definition are considered.
+     */
+    variant(name) {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, `${name}Variant`, () => {
+            const component = __classPrivateFieldGet(this, _Resolver_style, "f").components().get(name);
+            if (!component || !__classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_isVisible).call(this, name, component)) {
+                return undefined;
+            }
+            const raw = __classPrivateFieldGet(this, _Resolver_options, "f").componentVariant(component.sourceName());
+            const variants = component.variants();
+            let entries;
+            if (raw === undefined) {
+                entries = Array.from(variants).map(([v, variant]) => [
+                    v,
+                    variant.weight(),
+                ]);
+            }
+            else if (Array.isArray(raw)) {
+                entries = raw
+                    .filter((v) => variants.has(v))
+                    .map((v) => [v, 1]);
+            }
+            else {
+                entries = Object.entries(raw).filter(([v]) => variants.has(v));
+            }
+            return __classPrivateFieldGet(this, _Resolver_prng, "f").weightedPick(`${name}Variant`, entries);
+        });
+    }
+    color(name) {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, `${name}Color`, () => __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_resolveColor).call(this, name));
+    }
+    colorFill(name) {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, `${name}ColorFill`, () => __classPrivateFieldGet(this, _Resolver_prng, "f").pick(`${name}ColorFill`, __classPrivateFieldGet(this, _Resolver_options, "f").colorFill(name)) ??
+            'solid');
+    }
+    colorAngle(name) {
+        return __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_memo).call(this, `${name}ColorAngle`, () => __classPrivateFieldGet(this, _Resolver_prng, "f").float(`${name}ColorAngle`, __classPrivateFieldGet(this, _Resolver_options, "f").colorAngle(name)) ?? 0);
+    }
+    /**
+     * Per-component transform values are render-time decorations derived per
+     * `<use>` reference, not user-input options that should round-trip. They
+     * are intentionally not memoized and so never appear in {@link resolved}.
+     */
+    componentTransform(name) {
+        const component = __classPrivateFieldGet(this, _Resolver_style, "f").components().get(name);
+        return {
+            rotate: __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_pickFloat).call(this, name, 'Rotate', component?.rotate() ?? [], 0),
+            translateX: __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_pickFloat).call(this, name, 'TranslateX', component?.translate().x() ?? [], 0),
+            translateY: __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_pickFloat).call(this, name, 'TranslateY', component?.translate().y() ?? [], 0),
+            scale: __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_pickFloat).call(this, name, 'Scale', component?.scale() ?? [], 1),
+        };
+    }
+    /**
+     * Returns every value that has been touched during this resolution. Only
+     * memoized entries are included; unset options remain `undefined` and
+     * disappear on `JSON.stringify()`. Per-component transform values from
+     * {@link componentTransform} are intentionally not memoized and therefore
+     * do not appear in the snapshot.
+     *
+     * The returned object aliases the internal cache; callers that need
+     * isolation (e.g. {@link Avatar.toJSON}) clone it themselves.
+     */
+    resolved() {
+        return __classPrivateFieldGet(this, _Resolver_result, "f");
+    }
+}
+_Resolver_style = new WeakMap(), _Resolver_options = new WeakMap(), _Resolver_prng = new WeakMap(), _Resolver_colorResolving = new WeakMap(), _Resolver_result = new WeakMap(), _Resolver_instances = new WeakSet(), _Resolver_probability = function _Resolver_probability(component) {
+    const raw = __classPrivateFieldGet(this, _Resolver_options, "f").componentProbability(component.sourceName());
+    return raw ?? component.probability();
+}, _Resolver_isVisible = function _Resolver_isVisible(name, component) {
+    return __classPrivateFieldGet(this, _Resolver_prng, "f").bool(`${name}Probability`, __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_probability).call(this, component));
+}, _Resolver_resolveColor = function _Resolver_resolveColor(name) {
+    const userColors = __classPrivateFieldGet(this, _Resolver_options, "f").color(name);
+    const styleColor = __classPrivateFieldGet(this, _Resolver_style, "f").colors().get(name);
+    const source = userColors ?? styleColor?.values() ?? [];
+    let candidates = source.map((c) => Color.toHex(c));
+    const fill = this.colorFill(name);
+    const stops = fill === 'solid' ? 1 : __classPrivateFieldGet(this, _Resolver_instances, "m", _Resolver_colorFillStops).call(this, name);
+    if (!styleColor) {
+        return __classPrivateFieldGet(this, _Resolver_prng, "f").shuffle(`${name}Color`, candidates).slice(0, stops);
+    }
+    // Detect circular references (e.g. a.contrastTo = b, b.contrastTo = a)
+    if (__classPrivateFieldGet(this, _Resolver_colorResolving, "f").includes(name)) {
+        throw new CircularColorReferenceError(__classPrivateFieldGet(this, _Resolver_colorResolving, "f").concat(name));
+    }
+    __classPrivateFieldGet(this, _Resolver_colorResolving, "f").push(name);
+    const contrastTo = styleColor.contrastTo();
+    const notEqualTo = styleColor.notEqualTo();
+    try {
+        if (contrastTo) {
+            const refColor = this.color(contrastTo)[0];
+            if (refColor) {
+                candidates = Color.sortByContrast(candidates, refColor);
+            }
+        }
+        if (notEqualTo.length > 0) {
+            const excluded = [];
+            for (const ref of notEqualTo) {
+                for (const color of this.color(ref)) {
+                    excluded.push(color);
+                }
+            }
+            candidates = Color.filterNotEqualTo(candidates, excluded);
+        }
+    }
+    finally {
+        __classPrivateFieldGet(this, _Resolver_colorResolving, "f").pop();
+    }
+    // Skip shuffle when sorted by contrast to preserve the ordering
+    const ordered = contrastTo
+        ? candidates
+        : __classPrivateFieldGet(this, _Resolver_prng, "f").shuffle(`${name}Color`, candidates);
+    return ordered.slice(0, stops);
+}, _Resolver_colorFillStops = function _Resolver_colorFillStops(name) {
+    return (__classPrivateFieldGet(this, _Resolver_prng, "f").integer(`${name}ColorFillStops`, __classPrivateFieldGet(this, _Resolver_options, "f").colorFillStops(name)) ?? 2);
+}, _Resolver_pickFloat = function _Resolver_pickFloat(name, suffix, range, fallback) {
+    return __classPrivateFieldGet(this, _Resolver_prng, "f").float(`${name}${suffix}`, range) ?? fallback;
+}, _Resolver_memo = function _Resolver_memo(key, compute) {
+    if (key in __classPrivateFieldGet(this, _Resolver_result, "f")) {
+        return __classPrivateFieldGet(this, _Resolver_result, "f")[key];
+    }
+    const value = compute();
+    __classPrivateFieldGet(this, _Resolver_result, "f")[key] = value;
+    return value;
+};

package/lib/Style/Canvas.d.ts

@@ -1,9 +1,23 @@
 import type { StyleDefinitionCanvas } from '../StyleDefinition.js';
 import { Element } from './Element.js';
+/**
+ * Read-only view over a style definition's `canvas` block, exposing the
+ * drawing area dimensions and the top-level element list.
+ */
 export declare class Canvas {
     #private;
     constructor(data: StyleDefinitionCanvas);
+    /**
+     * Returns the canvas width — the `width` value of the SVG `viewBox`.
+     */
     width(): number;
+    /**
+     * Returns the canvas height — the `height` value of the SVG `viewBox`.
+     */
     height(): number;
+    /**
+     * Returns the top-level elements rendered onto the canvas, lazily wrapped
+     * as {@link Element} instances on first access.
+     */
     elements(): readonly Element[];
 }

package/lib/Style/Canvas.js

@@ -11,18 +11,32 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _Canvas_data, _Canvas_elements;
 import { Element } from './Element.js';
+/**
+ * Read-only view over a style definition's `canvas` block, exposing the
+ * drawing area dimensions and the top-level element list.
+ */
 export class Canvas {
     constructor(data) {
         _Canvas_data.set(this, void 0);
         _Canvas_elements.set(this, void 0);
         __classPrivateFieldSet(this, _Canvas_data, data, "f");
     }
+    /**
+     * Returns the canvas width — the `width` value of the SVG `viewBox`.
+     */
     width() {
         return __classPrivateFieldGet(this, _Canvas_data, "f").width;
     }
+    /**
+     * Returns the canvas height — the `height` value of the SVG `viewBox`.
+     */
     height() {
         return __classPrivateFieldGet(this, _Canvas_data, "f").height;
     }
+    /**
+     * Returns the top-level elements rendered onto the canvas, lazily wrapped
+     * as {@link Element} instances on first access.
+     */
     elements() {
         __classPrivateFieldSet(this, _Canvas_elements, __classPrivateFieldGet(this, _Canvas_elements, "f") ?? __classPrivateFieldGet(this, _Canvas_data, "f").elements.map((el) => new Element(el)), "f");
         return __classPrivateFieldGet(this, _Canvas_elements, "f");

package/lib/Style/Color.d.ts

@@ -1,8 +1,22 @@
 import type { StyleDefinitionColor } from '../StyleDefinition.js';
+/**
+ * Read-only view over an entry in a style definition's `colors` block.
+ */
 export declare class Color {
     #private;
     constructor(data: StyleDefinitionColor);
+    /**
+     * Returns the candidate color values, in definition order.
+     */
     values(): readonly string[];
+    /**
+     * Returns the colors that the resolver should avoid picking, or an empty
+     * list when the field is unset.
+     */
     notEqualTo(): readonly string[];
+    /**
+     * Returns the name of another color that this one should contrast against,
+     * or `undefined` when no contrast constraint is defined.
+     */
     contrastTo(): string | undefined;
 }

package/lib/Style/Color.js

@@ -10,17 +10,31 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _Color_data;
+/**
+ * Read-only view over an entry in a style definition's `colors` block.
+ */
 export class Color {
     constructor(data) {
         _Color_data.set(this, void 0);
         __classPrivateFieldSet(this, _Color_data, data, "f");
     }
+    /**
+     * Returns the candidate color values, in definition order.
+     */
     values() {
         return __classPrivateFieldGet(this, _Color_data, "f").values;
     }
+    /**
+     * Returns the colors that the resolver should avoid picking, or an empty
+     * list when the field is unset.
+     */
     notEqualTo() {
         return __classPrivateFieldGet(this, _Color_data, "f").notEqualTo ?? [];
     }
+    /**
+     * Returns the name of another color that this one should contrast against,
+     * or `undefined` when no contrast constraint is defined.
+     */
     contrastTo() {
         return __classPrivateFieldGet(this, _Color_data, "f").contrastTo;
     }

package/lib/Style/Component.d.ts

@@ -1,13 +1,62 @@
 import type { StyleDefinitionComponent } from '../StyleDefinition.js';
 import { ComponentTranslate } from './ComponentTranslate.js';
 import { ComponentVariant } from './ComponentVariant.js';
+/**
+ * Read-only view over an entry in a style definition's `components` block.
+ *
+ * An entry is either a base component with its own dimensions and variants
+ * or an alias declared via `extends`. Aliases are pure references — they
+ * inherit dimensions, variants, and all transforms from the source.
+ */
 export declare class Component {
     #private;
-    constructor(data: StyleDefinitionComponent);
+    constructor(name: string, data: StyleDefinitionComponent, source?: Component);
+    /**
+     * Returns the entry's own name as declared in the style definition. For
+     * aliases this is the alias key, not the source component's name (use
+     * {@link sourceName} for the canonical user-option key prefix).
+     */
+    name(): string;
+    /**
+     * Returns the source component name when this entry is an alias, or
+     * `undefined` for a base component.
+     */
+    extendsName(): string | undefined;
+    /**
+     * Returns the canonical user-option key prefix: the source component's
+     * name when this entry is an alias, otherwise the entry's own name.
+     */
+    sourceName(): string;
+    /**
+     * Returns the component's intrinsic width in canvas coordinates. For
+     * aliases the source component's width is returned.
+     */
     width(): number;
+    /**
+     * Returns the component's intrinsic height in canvas coordinates. For
+     * aliases the source component's height is returned.
+     */
     height(): number;
+    /**
+     * Returns the probability (0–100) that this component is rendered.
+     * Aliases delegate to the source; defaults to 100 (always visible).
+     */
     probability(): number;
+    /**
+     * Returns the rotation range definition. Aliases delegate to the source.
+     */
     rotate(): readonly number[];
+    /**
+     * Returns the scale range definition. Aliases delegate to the source.
+     */
+    scale(): readonly number[];
+    /**
+     * Returns the translate descriptor. Aliases delegate to the source.
+     */
     translate(): ComponentTranslate;
+    /**
+     * Returns a name → {@link ComponentVariant} map for all defined variants.
+     * Aliases delegate to the source component's variants.
+     */
     variants(): ReadonlyMap<string, ComponentVariant>;
 }

package/lib/Style/Component.js

@@ -9,38 +9,117 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Component_data, _Component_translate, _Component_variants;
+var _Component_instances, _Component_data, _Component_name, _Component_source, _Component_translate, _Component_variants, _Component_asBase;
 import { ComponentTranslate } from './ComponentTranslate.js';
 import { ComponentVariant } from './ComponentVariant.js';
+/**
+ * Read-only view over an entry in a style definition's `components` block.
+ *
+ * An entry is either a base component with its own dimensions and variants
+ * or an alias declared via `extends`. Aliases are pure references — they
+ * inherit dimensions, variants, and all transforms from the source.
+ */
 export class Component {
-    constructor(data) {
+    constructor(name, data, source) {
+        _Component_instances.add(this);
         _Component_data.set(this, void 0);
+        _Component_name.set(this, void 0);
+        _Component_source.set(this, void 0);
         _Component_translate.set(this, void 0);
         _Component_variants.set(this, void 0);
         __classPrivateFieldSet(this, _Component_data, data, "f");
+        __classPrivateFieldSet(this, _Component_name, name, "f");
+        __classPrivateFieldSet(this, _Component_source, source, "f");
     }
+    /**
+     * Returns the entry's own name as declared in the style definition. For
+     * aliases this is the alias key, not the source component's name (use
+     * {@link sourceName} for the canonical user-option key prefix).
+     */
+    name() {
+        return __classPrivateFieldGet(this, _Component_name, "f");
+    }
+    /**
+     * Returns the source component name when this entry is an alias, or
+     * `undefined` for a base component.
+     */
+    extendsName() {
+        return 'extends' in __classPrivateFieldGet(this, _Component_data, "f") ? __classPrivateFieldGet(this, _Component_data, "f").extends : undefined;
+    }
+    /**
+     * Returns the canonical user-option key prefix: the source component's
+     * name when this entry is an alias, otherwise the entry's own name.
+     */
+    sourceName() {
+        return this.extendsName() ?? __classPrivateFieldGet(this, _Component_name, "f");
+    }
+    /**
+     * Returns the component's intrinsic width in canvas coordinates. For
+     * aliases the source component's width is returned.
+     */
     width() {
-        return __classPrivateFieldGet(this, _Component_data, "f").width;
+        return __classPrivateFieldGet(this, _Component_source, "f") ? __classPrivateFieldGet(this, _Component_source, "f").width() : __classPrivateFieldGet(this, _Component_instances, "m", _Component_asBase).call(this).width;
     }
+    /**
+     * Returns the component's intrinsic height in canvas coordinates. For
+     * aliases the source component's height is returned.
+     */
     height() {
-        return __classPrivateFieldGet(this, _Component_data, "f").height;
+        return __classPrivateFieldGet(this, _Component_source, "f") ? __classPrivateFieldGet(this, _Component_source, "f").height() : __classPrivateFieldGet(this, _Component_instances, "m", _Component_asBase).call(this).height;
     }
+    /**
+     * Returns the probability (0–100) that this component is rendered.
+     * Aliases delegate to the source; defaults to 100 (always visible).
+     */
     probability() {
-        return __classPrivateFieldGet(this, _Component_data, "f").probability ?? 100;
+        if (__classPrivateFieldGet(this, _Component_source, "f")) {
+            return __classPrivateFieldGet(this, _Component_source, "f").probability();
+        }
+        return __classPrivateFieldGet(this, _Component_instances, "m", _Component_asBase).call(this).probability ?? 100;
     }
+    /**
+     * Returns the rotation range definition. Aliases delegate to the source.
+     */
     rotate() {
-        return __classPrivateFieldGet(this, _Component_data, "f").rotate ?? [];
+        if (__classPrivateFieldGet(this, _Component_source, "f")) {
+            return __classPrivateFieldGet(this, _Component_source, "f").rotate();
+        }
+        return __classPrivateFieldGet(this, _Component_instances, "m", _Component_asBase).call(this).rotate ?? [];
     }
+    /**
+     * Returns the scale range definition. Aliases delegate to the source.
+     */
+    scale() {
+        if (__classPrivateFieldGet(this, _Component_source, "f")) {
+            return __classPrivateFieldGet(this, _Component_source, "f").scale();
+        }
+        return __classPrivateFieldGet(this, _Component_instances, "m", _Component_asBase).call(this).scale ?? [];
+    }
+    /**
+     * Returns the translate descriptor. Aliases delegate to the source.
+     */
     translate() {
-        __classPrivateFieldSet(this, _Component_translate, __classPrivateFieldGet(this, _Component_translate, "f") ?? new ComponentTranslate(__classPrivateFieldGet(this, _Component_data, "f").translate ?? {}), "f");
+        if (__classPrivateFieldGet(this, _Component_source, "f")) {
+            return __classPrivateFieldGet(this, _Component_source, "f").translate();
+        }
+        __classPrivateFieldSet(this, _Component_translate, __classPrivateFieldGet(this, _Component_translate, "f") ?? new ComponentTranslate(__classPrivateFieldGet(this, _Component_instances, "m", _Component_asBase).call(this).translate ?? {}), "f");
         return __classPrivateFieldGet(this, _Component_translate, "f");
     }
+    /**
+     * Returns a name → {@link ComponentVariant} map for all defined variants.
+     * Aliases delegate to the source component's variants.
+     */
     variants() {
-        __classPrivateFieldSet(this, _Component_variants, __classPrivateFieldGet(this, _Component_variants, "f") ?? new Map(Object.entries(__classPrivateFieldGet(this, _Component_data, "f").variants).map(([name, data]) => [
+        if (__classPrivateFieldGet(this, _Component_source, "f")) {
+            return __classPrivateFieldGet(this, _Component_source, "f").variants();
+        }
+        __classPrivateFieldSet(this, _Component_variants, __classPrivateFieldGet(this, _Component_variants, "f") ?? new Map(Object.entries(__classPrivateFieldGet(this, _Component_instances, "m", _Component_asBase).call(this).variants).map(([name, data]) => [
             name,
             new ComponentVariant(data),
         ])), "f");
         return __classPrivateFieldGet(this, _Component_variants, "f");
     }
 }
-_Component_data = new WeakMap(), _Component_translate = new WeakMap(), _Component_variants = new WeakMap();
+_Component_data = new WeakMap(), _Component_name = new WeakMap(), _Component_source = new WeakMap(), _Component_translate = new WeakMap(), _Component_variants = new WeakMap(), _Component_instances = new WeakSet(), _Component_asBase = function _Component_asBase() {
+    return __classPrivateFieldGet(this, _Component_data, "f");
+};

package/lib/Style/ComponentTranslate.d.ts

@@ -1,7 +1,17 @@
 import type { StyleDefinitionComponentTranslate } from '../StyleDefinition.js';
+/**
+ * Read-only view over a component's `translate` block, providing the X and Y
+ * offset ranges.
+ */
 export declare class ComponentTranslate {
     #private;
     constructor(data: StyleDefinitionComponentTranslate);
+    /**
+     * Returns the horizontal offset range, or an empty list when unset.
+     */
     x(): readonly number[];
+    /**
+     * Returns the vertical offset range, or an empty list when unset.
+     */
     y(): readonly number[];
 }

package/lib/Style/ComponentTranslate.js

@@ -10,14 +10,24 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _ComponentTranslate_data;
+/**
+ * Read-only view over a component's `translate` block, providing the X and Y
+ * offset ranges.
+ */
 export class ComponentTranslate {
     constructor(data) {
         _ComponentTranslate_data.set(this, void 0);
         __classPrivateFieldSet(this, _ComponentTranslate_data, data, "f");
     }
+    /**
+     * Returns the horizontal offset range, or an empty list when unset.
+     */
     x() {
         return __classPrivateFieldGet(this, _ComponentTranslate_data, "f").x ?? [];
     }
+    /**
+     * Returns the vertical offset range, or an empty list when unset.
+     */
     y() {
         return __classPrivateFieldGet(this, _ComponentTranslate_data, "f").y ?? [];
     }

package/lib/Style/ComponentVariant.d.ts

@@ -1,8 +1,18 @@
 import type { StyleDefinitionComponentVariant } from '../StyleDefinition.js';
 import { Element } from './Element.js';
+/**
+ * Read-only view over an entry in a component's `variants` block.
+ */
 export declare class ComponentVariant {
     #private;
     constructor(data: StyleDefinitionComponentVariant);
+    /**
+     * Returns the variant's elements, lazily wrapped as {@link Element}
+     * instances on first access.
+     */
     elements(): readonly Element[];
+    /**
+     * Returns the weighted-pick weight for this variant, defaulting to `1`.
+     */
     weight(): number;
 }

package/lib/Style/ComponentVariant.js

@@ -11,16 +11,26 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _ComponentVariant_data, _ComponentVariant_elements;
 import { Element } from './Element.js';
+/**
+ * Read-only view over an entry in a component's `variants` block.
+ */
 export class ComponentVariant {
     constructor(data) {
         _ComponentVariant_data.set(this, void 0);
         _ComponentVariant_elements.set(this, void 0);
         __classPrivateFieldSet(this, _ComponentVariant_data, data, "f");
     }
+    /**
+     * Returns the variant's elements, lazily wrapped as {@link Element}
+     * instances on first access.
+     */
     elements() {
         __classPrivateFieldSet(this, _ComponentVariant_elements, __classPrivateFieldGet(this, _ComponentVariant_elements, "f") ?? __classPrivateFieldGet(this, _ComponentVariant_data, "f").elements.map((el) => new Element(el)), "f");
         return __classPrivateFieldGet(this, _ComponentVariant_elements, "f");
     }
+    /**
+     * Returns the weighted-pick weight for this variant, defaulting to `1`.
+     */
     weight() {
         return __classPrivateFieldGet(this, _ComponentVariant_data, "f").weight ?? 1;
     }

package/lib/Style/Element.d.ts

@@ -1,10 +1,35 @@
 import type { StyleDefinitionElement, StyleDefinitionElementValue, StyleDefinitionElementType, StyleDefinitionAttributes } from '../StyleDefinition.js';
+/**
+ * Read-only view over a single render-tree element from a style definition.
+ *
+ * The same node type covers SVG elements, text, and component references —
+ * `type()` discriminates between them.
+ */
 export declare class Element {
     #private;
     constructor(data: StyleDefinitionElement);
+    /**
+     * Returns the element type discriminator (`svg`, `text`, `component`, …).
+     */
     type(): StyleDefinitionElementType;
+    /**
+     * Returns the element's tag/component name, or `undefined` for elements
+     * that don't have one.
+     */
     name(): string | undefined;
+    /**
+     * Returns the element's textual value (for `text` elements) or template
+     * fragment, or `undefined` when not applicable.
+     */
     value(): StyleDefinitionElementValue | undefined;
+    /**
+     * Returns the element's raw attribute map, or `undefined` when no
+     * attributes are defined.
+     */
     attributes(): StyleDefinitionAttributes | undefined;
+    /**
+     * Returns the element's children, lazily wrapped as {@link Element}
+     * instances on first access.
+     */
     children(): readonly Element[];
 }