@gadxr/ui 0.0.0-stage → 0.1.0

package/dist/aframe/rounded.js

@@ -0,0 +1,121 @@
+// `rounded` A-Frame component (and <a-rounded> primitive): a rounded-rectangle slab,
+// solid or glass. Owned by the design system and registered on first use, so apps
+// don't need a <script> tag for it. Uses A-Frame's own three.js (AFRAME.THREE).
+// Erasable TypeScript only — tests import it with Node's type stripping.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const glassMaterial = (THREE) => new THREE.MeshPhysicalMaterial({
+    roughness: 0.5,
+    transmission: 1,
+    thickness: 0.7,
+    clearcoat: 0.61,
+    clearcoatRoughness: 0.39,
+});
+// The component definition, built against a given three.js (tests pass their own).
+export function roundedComponent(THREE) {
+    return {
+        schema: {
+            enabled: { default: true },
+            width: { type: 'number', default: 1 },
+            height: { type: 'number', default: 1 },
+            // Extrude thickness; ignored when `flat`.
+            depth: { type: 'number', default: 0.05 },
+            radius: { type: 'number', default: 0.3 },
+            topLeftRadius: { type: 'number', default: -1 },
+            topRightRadius: { type: 'number', default: -1 },
+            bottomLeftRadius: { type: 'number', default: -1 },
+            bottomRightRadius: { type: 'number', default: -1 },
+            color: { type: 'color', default: '#F0F0F0' },
+            opacity: { type: 'number', default: 1 },
+            glass: { type: 'boolean', default: false },
+            flat: { type: 'boolean', default: false },
+        },
+        init() {
+            // update() picks the material (glass or solid) right after init.
+            this.rounded = new THREE.Mesh(this.draw(), new THREE.MeshPhongMaterial({ color: new THREE.Color(this.data.color), side: THREE.DoubleSide }));
+            this.updateOpacity();
+            this.el.setObject3D('mesh', this.rounded);
+        },
+        update() {
+            if (!this.rounded)
+                return;
+            this.rounded.visible = this.data.enabled;
+            if (!this.data.enabled)
+                return;
+            this.rounded.geometry.dispose();
+            this.rounded.geometry = this.draw();
+            // Swap materials only when `glass` changes, so frequent updates (hover colors, resizing)
+            // don't leak materials, and turning glass off goes back to a solid slab.
+            if (this.data.glass !== !!this.rounded.material.isMeshPhysicalMaterial) {
+                this.rounded.material.dispose();
+                this.rounded.material = this.data.glass
+                    ? glassMaterial(THREE)
+                    : new THREE.MeshPhongMaterial({ side: THREE.DoubleSide });
+            }
+            // Glass stays clear; `color` only tints solid slabs.
+            if (!this.data.glass)
+                this.rounded.material.color.set(this.data.color);
+            this.updateOpacity();
+        },
+        updateOpacity() {
+            const opacity = Math.min(1, Math.max(0, this.data.opacity));
+            this.rounded.material.transparent = opacity < 1;
+            this.rounded.material.opacity = opacity;
+        },
+        remove() {
+            if (!this.rounded)
+                return;
+            this.el.removeObject3D('mesh');
+            this.rounded.geometry.dispose();
+            this.rounded.material.dispose();
+            this.rounded = null;
+        },
+        draw() {
+            const d = this.data;
+            const corner = (value) => (value !== -1 ? value : d.radius) || 0.00001;
+            const tl = corner(d.topLeftRadius);
+            const tr = corner(d.topRightRadius);
+            const bl = corner(d.bottomLeftRadius);
+            const br = corner(d.bottomRightRadius);
+            const w = d.width;
+            const h = d.height;
+            const shape = new THREE.Shape();
+            shape.moveTo(0, tl);
+            shape.lineTo(0, h - tl);
+            shape.quadraticCurveTo(0, h, tl, h);
+            shape.lineTo(w - tr, h);
+            shape.quadraticCurveTo(w, h, w, h - tr);
+            shape.lineTo(w, br);
+            shape.quadraticCurveTo(w, 0, w - br, 0);
+            shape.lineTo(bl, 0);
+            shape.quadraticCurveTo(0, 0, 0, bl);
+            return d.flat
+                ? new THREE.ShapeGeometry(shape)
+                : new THREE.ExtrudeGeometry(shape, { bevelEnabled: false, depth: d.depth });
+        },
+    };
+}
+// Registers `rounded` and <a-rounded> with the page's A-Frame, once.
+export function registerRounded(AFRAME = globalThis.AFRAME) {
+    if (!AFRAME)
+        throw new Error('gadxr ui: A-Frame must be loaded before 3D components are used');
+    if (!AFRAME.components.rounded)
+        AFRAME.registerComponent('rounded', roundedComponent(AFRAME.THREE));
+    if (!AFRAME.primitives.primitives['a-rounded']) {
+        AFRAME.registerPrimitive('a-rounded', {
+            defaultComponents: { rounded: {} },
+            mappings: {
+                enabled: 'rounded.enabled',
+                width: 'rounded.width',
+                height: 'rounded.height',
+                depth: 'rounded.depth',
+                radius: 'rounded.radius',
+                'top-left-radius': 'rounded.topLeftRadius',
+                'top-right-radius': 'rounded.topRightRadius',
+                'bottom-left-radius': 'rounded.bottomLeftRadius',
+                'bottom-right-radius': 'rounded.bottomRightRadius',
+                color: 'rounded.color',
+                opacity: 'rounded.opacity',
+            },
+        });
+    }
+}

package/dist/aframe/scene.d.ts

@@ -0,0 +1,9 @@
+export declare const RAYCASTABLE = "raycastable";
+export declare const MOUSE_CURSOR = "rayOrigin: mouse; fuse: false";
+export declare const TROIKA_SCRIPT = "https://unpkg.com/aframe-troika-text@0.14.0/dist/aframe-troika-text.min.js";
+export type SceneOptions = {
+    cursor?: string;
+    mouseCursorInVR?: boolean;
+};
+export declare function setupScene(scene: any, { cursor, mouseCursorInVR }?: SceneOptions): () => void;
+export declare function loadTroika(): Promise<void> | null;

package/dist/aframe/scene.js

@@ -0,0 +1,101 @@
+// What <Scene3D> does to its <a-scene>, kept free of Svelte so it's tested in Node: the
+// mouse cursor and lasers aim at `.raycastable`, the mouse cursor is removed in VR, and
+// troika-text (3D labels) is loaded if the page didn't load it.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// Cursors only hit entities with this class (on an entity that owns a mesh).
+export const RAYCASTABLE = 'raycastable';
+export const MOUSE_CURSOR = 'rayOrigin: mouse; fuse: false';
+export const TROIKA_SCRIPT = 'https://unpkg.com/aframe-troika-text@0.14.0/dist/aframe-troika-text.min.js';
+// Returns a function that undoes it.
+export function setupScene(scene, { cursor = MOUSE_CURSOR, mouseCursorInVR = false } = {}) {
+    const cleanups = [];
+    // Lasers: aim at `.raycastable` like the mouse, keeping the rest of their raycaster (far).
+    // Set once the entity has loaded, so a raycaster written in its markup is set up first.
+    const lasers = new WeakSet();
+    const aim = (el) => el.setAttribute('raycaster', 'objects', `.${RAYCASTABLE}`);
+    const watchLaser = (el) => {
+        if (lasers.has(el))
+            return;
+        lasers.add(el);
+        if (el.hasLoaded)
+            return aim(el);
+        const onLoaded = (event) => {
+            if (event.target !== el)
+                return;
+            el.removeEventListener('loaded', onLoaded);
+            aim(el);
+        };
+        el.addEventListener('loaded', onLoaded);
+        cleanups.push(() => el.removeEventListener('loaded', onLoaded));
+    };
+    const findLasers = (node) => {
+        if (node.nodeType !== 1)
+            return;
+        if (node.hasAttribute('laser-controls'))
+            watchLaser(node);
+        node.querySelectorAll('[laser-controls]').forEach(watchLaser);
+    };
+    findLasers(scene);
+    // Hands mounted later (e.g. inside an {#if}) or given laser-controls later.
+    const observer = new MutationObserver((records) => {
+        for (const record of records) {
+            if (record.type === 'attributes')
+                findLasers(record.target);
+            else
+                record.addedNodes.forEach(findLasers);
+        }
+    });
+    observer.observe(scene, { childList: true, subtree: true, attributes: true, attributeFilter: ['laser-controls'] });
+    cleanups.push(() => observer.disconnect());
+    // The mouse cursor is unused in a headset, but still hovers UI: it keeps casting along
+    // its last mouse ray, and it hears the lasers' raycaster events (they bubble to the
+    // scene), so its mouseleaves un-hover buttons a laser is still on. Remove it in VR
+    // (raycaster off first, which sends the leaves for anything it hovers); restore it after.
+    // enter-vr also fires for non-immersive fullscreen; only a real XR session counts.
+    if (!mouseCursorInVR) {
+        let removed = false;
+        const onVR = (event) => {
+            const vr = event.type === 'enter-vr' && !!scene.xrSession;
+            if (vr === removed)
+                return;
+            removed = vr;
+            scene.setAttribute('raycaster', 'enabled', !vr);
+            if (vr)
+                scene.removeAttribute('cursor');
+            else
+                scene.setAttribute('cursor', cursor);
+        };
+        scene.addEventListener('enter-vr', onVR);
+        scene.addEventListener('exit-vr', onVR);
+        cleanups.push(() => {
+            scene.removeEventListener('enter-vr', onVR);
+            scene.removeEventListener('exit-vr', onVR);
+        });
+    }
+    return () => cleanups.splice(0).forEach((cleanup) => cleanup());
+}
+let troika;
+// Resolves once A-Frame has `troika-text`, adding the pinned script if it isn't registered
+// (or being loaded) yet; null when it's already there, so a page that loads it needn't wait.
+// A script that fails to load is logged and still resolves: the scene shows, without labels.
+export function loadTroika() {
+    if (globalThis.AFRAME.components['troika-text'])
+        return null;
+    troika ??= new Promise((resolve) => {
+        const existing = document.querySelector(`script[src="${TROIKA_SCRIPT}"]`);
+        const script = existing ?? document.createElement('script');
+        const done = () => {
+            if (!globalThis.AFRAME.components['troika-text']) {
+                console.error(`gadxr ui: couldn't load troika-text from ${TROIKA_SCRIPT}; 3D labels won't show.`);
+            }
+            resolve();
+        };
+        script.addEventListener('load', done, { once: true });
+        script.addEventListener('error', done, { once: true });
+        if (!existing) {
+            script.src = TROIKA_SCRIPT;
+            document.head.appendChild(script);
+        }
+    });
+    return troika;
+}

package/dist/assets/Geist-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/button-style.d.ts

@@ -0,0 +1,22 @@
+import type { ButtonKind, ButtonShape, ButtonSize, Font, Material3D, Theme } from './theme';
+export type ButtonStyleInput = {
+    kind?: ButtonKind;
+    size?: ButtonSize;
+    shape?: ButtonShape;
+    selected?: boolean;
+    disabled?: boolean;
+};
+export type ButtonStyle = {
+    height: number;
+    paddingX: number;
+    radius: number;
+    square: boolean;
+    font: Font;
+    fill: string;
+    hoverFill: string;
+    activeFill: string;
+    text: string;
+    material: Material3D;
+    text3d: string;
+};
+export declare function resolveButtonStyle(theme: Theme, input?: ButtonStyleInput): ButtonStyle;

package/dist/button-style.js

@@ -0,0 +1,34 @@
+export function resolveButtonStyle(theme, input = {}) {
+    const { kind = 'primary', size = 'default', shape = 'default', selected = false, disabled = false } = input;
+    const sizeTokens = theme.button.sizes[size];
+    const height = sizeTokens.height;
+    const square = shape === 'round' || shape === 'circle' || shape === 'square';
+    const fullyRounded = shape === 'pill' || shape === 'round' || shape === 'circle';
+    const radius = fullyRounded ? height / 2 : Math.min(theme.borders.buttonBorderRadius, height / 2);
+    const base = {
+        height,
+        paddingX: square ? 0 : sizeTokens.paddingX,
+        radius,
+        square,
+        font: theme.typography[sizeTokens.typography],
+    };
+    if (disabled) {
+        const c = theme.colors;
+        return { ...base, fill: c.buttonDisabledFill, hoverFill: c.buttonDisabledFill, activeFill: c.buttonDisabledFill, text: c.buttonDisabledText, material: 'solid', text3d: c.buttonDisabledText };
+    }
+    const colors = theme.colors.button[kind];
+    if (selected) {
+        return { ...base, fill: colors.selectedFill, hoverFill: colors.selectedFill, activeFill: colors.active, text: colors.selectedText, material: 'solid', text3d: colors.selectedText };
+    }
+    const material = theme.space3d.material[kind];
+    return {
+        ...base,
+        fill: colors.fill,
+        hoverFill: colors.hover,
+        activeFill: colors.active,
+        text: colors.text,
+        material,
+        // Glass ignores the fill color, so it gets its own label color.
+        text3d: material === 'glass' ? theme.space3d.glassText : colors.text,
+    };
+}

package/dist/component-style.d.ts

@@ -0,0 +1,79 @@
+import type { Font, TagKind, TagSize, TagVariant, Theme, TooltipPlacement } from './theme';
+export type CheckboxType = 'checkbox' | 'toggle';
+export type CheckboxStyle = {
+    width: number;
+    height: number;
+    radius: number;
+    fill: string;
+    fill3d: string;
+    border: string;
+    mark: string;
+    knob: number;
+    knobColor: string;
+    labelColor: string;
+    font: Font;
+};
+export declare function resolveCheckboxStyle(theme: Theme, { type, checked, disabled }?: {
+    type?: CheckboxType;
+    checked?: boolean;
+    disabled?: boolean;
+}): CheckboxStyle;
+export declare function sliderFraction(value: number, min: number, max: number): number;
+export declare function sliderValueAt(fraction: number, min: number, max: number, step?: number): number;
+export type TagStyle = {
+    height: number;
+    paddingX: number;
+    radius: number;
+    fill: string;
+    text: string;
+    font: Font;
+};
+export declare function resolveTagStyle(theme: Theme, { kind, variant, size }?: {
+    kind?: TagKind;
+    variant?: TagVariant;
+    size?: TagSize;
+}): TagStyle;
+export declare function nextIndex(usable: boolean[], from: number, direction: 1 | -1, wrap?: boolean): number;
+export type InputStyle = {
+    height: number;
+    paddingX: number;
+    radius: number;
+    border: number;
+    fill: string;
+    borderColor: string;
+    text: string;
+    placeholder: string;
+    caret: string;
+    labelColor: string;
+    captionColor: string;
+    font: Font;
+    labelFont: Font;
+    captionFont: Font;
+};
+export declare function resolveInputStyle(theme: Theme, { focused, hovered, error, disabled }?: {
+    focused?: boolean;
+    hovered?: boolean;
+    error?: boolean;
+    disabled?: boolean;
+}): InputStyle;
+export declare function resolveKeyStyle(theme: Theme, { kind, hovered, pressed, on }?: {
+    kind?: 'char' | 'special' | 'accent';
+    hovered?: boolean;
+    pressed?: boolean;
+    on?: boolean;
+}): {
+    fill: string;
+    text: string;
+};
+export declare function initials(name: string): string;
+export declare function avatarColor(name: string, palette: string[]): string;
+export declare function tooltipOffset(placement: TooltipPlacement, trigger: {
+    width: number;
+    height: number;
+}, bubble: {
+    width: number;
+    height: number;
+}, gap: number): {
+    x: number;
+    y: number;
+};

package/dist/component-style.js

@@ -0,0 +1,129 @@
+export function resolveCheckboxStyle(theme, { type = 'checkbox', checked = false, disabled = false } = {}) {
+    const t = theme.checkbox;
+    const c = theme.colors.checkbox;
+    const toggle = type === 'toggle';
+    const on = toggle ? c.toggleTrackChecked : c.fillChecked;
+    const off = toggle ? c.toggleTrack : 'transparent';
+    const fill = disabled ? theme.colors.buttonDisabledFill : checked ? on : off;
+    return {
+        width: toggle ? t.trackWidth : t.box,
+        height: toggle ? t.trackHeight : t.box,
+        radius: toggle ? t.trackHeight / 2 : t.boxRadius,
+        fill,
+        fill3d: fill === 'transparent' ? c.fill3d : fill,
+        border: disabled ? theme.colors.buttonDisabledFill : checked || toggle ? fill : c.border,
+        mark: disabled ? theme.colors.buttonDisabledText : c.mark,
+        knob: t.knob,
+        knobColor: disabled ? theme.colors.buttonDisabledText : c.toggleKnob,
+        labelColor: disabled ? theme.colors.buttonDisabledText : theme.colors.contentPrimary,
+        font: theme.typography[t.typography],
+    };
+}
+// Slider value <-> position along the track (0 = min end, 1 = max end).
+export function sliderFraction(value, min, max) {
+    if (max <= min)
+        return 0;
+    return Math.min(1, Math.max(0, (value - min) / (max - min)));
+}
+export function sliderValueAt(fraction, min, max, step = 1) {
+    const clamped = Math.min(1, Math.max(0, fraction));
+    const raw = min + clamped * (max - min);
+    if (!(step > 0))
+        return raw;
+    const snapped = min + Math.round((raw - min) / step) * step;
+    // Round off float noise (0.1 + 0.2) to the step's precision, and stay in range.
+    const decimals = (String(step).split('.')[1] ?? '').length;
+    return Math.min(max, Math.max(min, Number(snapped.toFixed(decimals))));
+}
+export function resolveTagStyle(theme, { kind = 'neutral', variant = 'light', size = 'small' } = {}) {
+    const sizeTokens = theme.tag.sizes[size];
+    const c = theme.colors.tag[kind];
+    return {
+        height: sizeTokens.height,
+        paddingX: sizeTokens.paddingX,
+        radius: Math.min(theme.tag.radius, sizeTokens.height / 2),
+        fill: variant === 'solid' ? c.solidFill : c.lightFill,
+        text: variant === 'solid' ? c.solidText : c.lightText,
+        font: theme.typography[sizeTokens.typography],
+    };
+}
+// Keyboard navigation over a list where some entries can't take focus (disabled
+// items, dividers). Returns the next usable index in `direction`, or `from` if none.
+export function nextIndex(usable, from, direction, wrap = true) {
+    const n = usable.length;
+    for (let step = 1; step <= n; step++) {
+        let i = from + direction * step;
+        if (wrap)
+            i = ((i % n) + n) % n;
+        else if (i < 0 || i >= n)
+            return from;
+        if (usable[i])
+            return i;
+    }
+    return from;
+}
+// Input field colors: the border shows hover, focus (accent) and error (wins over focus).
+export function resolveInputStyle(theme, { focused = false, hovered = false, error = false, disabled = false } = {}) {
+    const t = theme.input;
+    const c = theme.colors.input;
+    const fill = disabled ? theme.colors.buttonDisabledFill : c.fill;
+    return {
+        height: t.height,
+        paddingX: t.paddingX,
+        radius: t.radius,
+        border: t.border,
+        fill,
+        borderColor: disabled ? fill : error ? c.error : focused ? c.focus : hovered ? c.hover : c.border,
+        text: disabled ? theme.colors.buttonDisabledText : c.text,
+        placeholder: disabled ? theme.colors.buttonDisabledText : c.placeholder,
+        caret: c.caret,
+        labelColor: disabled ? theme.colors.buttonDisabledText : c.label,
+        captionColor: error ? c.errorText : c.caption,
+        font: theme.typography[t.typography],
+        labelFont: theme.typography[t.labelTypography],
+        captionFont: theme.typography[t.captionTypography],
+    };
+}
+// VR keyboard keys: letters, special keys (shift, backspace, pages…) and the accent
+// enter key. Pressed flips to white so a laser press is unmistakable; `on` is a latched
+// shift / caps.
+export function resolveKeyStyle(theme, { kind = 'char', hovered = false, pressed = false, on = false } = {}) {
+    const c = theme.colors.keyboard;
+    if (pressed)
+        return { fill: c.pressed, text: c.pressedText };
+    if (on)
+        return { fill: c.on, text: c.onText };
+    const [fill, hover] = kind === 'accent' ? [c.accent, c.accentHover] : kind === 'special' ? [c.special, c.specialHover] : [c.key, c.keyHover];
+    return { fill: hovered ? hover : fill, text: c.text };
+}
+// Avatar initials: first letters of the first and last words ("Ada Lovelace" → "AL",
+// "rhys" → "R"). Whole characters, so an emoji name keeps its emoji.
+export function initials(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return '';
+    const first = [...words[0]][0];
+    const last = words.length > 1 ? [...words[words.length - 1]][0] : '';
+    return (first + last).toUpperCase();
+}
+// A stable color per name, so the same player looks the same everywhere.
+export function avatarColor(name, palette) {
+    let hash = 0;
+    for (const ch of name.trim().toLowerCase())
+        hash = (hash * 31 + ch.codePointAt(0)) >>> 0;
+    return palette[hash % palette.length];
+}
+// Where a tooltip bubble's center goes relative to its trigger's center (3D, y up):
+// `gap` clear of the trigger's edge on the `placement` side.
+export function tooltipOffset(placement, trigger, bubble, gap) {
+    switch (placement) {
+        case 'bottom':
+            return { x: 0, y: -(trigger.height / 2 + gap + bubble.height / 2) };
+        case 'left':
+            return { x: -(trigger.width / 2 + gap + bubble.width / 2), y: 0 };
+        case 'right':
+            return { x: trigger.width / 2 + gap + bubble.width / 2, y: 0 };
+        default:
+            return { x: 0, y: trigger.height / 2 + gap + bubble.height / 2 };
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,16 @@
+import type { ButtonKind, ButtonShape, ButtonSize, Dimension, Theme } from './theme';
+export declare function setTheme(get: () => Theme): void;
+export declare function getTheme(): () => Theme;
+export declare function setDimension(dimension: Dimension): void;
+export declare function getDimension(): Dimension;
+export type ButtonGroupContext = {
+    readonly kind?: ButtonKind;
+    readonly size?: ButtonSize;
+    readonly shape?: ButtonShape;
+    readonly disabled: boolean;
+    register(): number;
+    isSelected(index: number): boolean | undefined;
+    select(index: number): void;
+};
+export declare function setButtonGroup(group: ButtonGroupContext): void;
+export declare function getButtonGroup(): ButtonGroupContext | undefined;

package/dist/context.js

@@ -0,0 +1,26 @@
+// Svelte context for the design system: the active theme, whether a subtree
+// renders as HTML or A-Frame, and the ButtonGroup a Button belongs to.
+import { getContext, setContext } from 'svelte';
+import { defaultTheme } from './theme';
+const THEME = Symbol('ui-theme');
+const DIMENSION = Symbol('ui-dimension');
+const GROUP = Symbol('ui-button-group');
+// Contexts hold getters so a ThemeProvider whose `theme` prop changes updates its children.
+export function setTheme(get) {
+    setContext(THEME, get);
+}
+export function getTheme() {
+    return getContext(THEME) ?? (() => defaultTheme);
+}
+export function setDimension(dimension) {
+    setContext(DIMENSION, dimension);
+}
+export function getDimension() {
+    return getContext(DIMENSION) ?? '2d';
+}
+export function setButtonGroup(group) {
+    setContext(GROUP, group);
+}
+export function getButtonGroup() {
+    return getContext(GROUP);
+}

package/dist/fonts.css

@@ -0,0 +1,7 @@
+/* The library's own copy of Geist (OFL, see assets/Geist-OFL.txt). */
+@font-face {
+	font-family: 'Geist';
+	src: url('./assets/Geist-Regular.ttf') format('truetype');
+	font-weight: normal;
+	font-display: swap;
+}

package/dist/fonts.d.ts

@@ -0,0 +1,2 @@
+import type { Theme } from './theme';
+export declare function font3d(theme: Theme): string;

package/dist/fonts.js

@@ -0,0 +1,7 @@
+// The library's own copy of Geist (OFL, see assets/Geist-OFL.txt), so 3D text
+// doesn't depend on files the app serves.
+import geistUrl from './assets/Geist-Regular.ttf?url';
+// troika loads fonts by URL; an empty `typography.font3d` means the bundled Geist.
+export function font3d(theme) {
+    return theme.typography.font3d || geistUrl;
+}