fauna-api 0.0.0-stage → 1.0.679

package/dist/src/ui/chatSequence.d.ts

@@ -0,0 +1,36 @@
+/** The live room a tool opened, to watch it: a browser, or a machine's desktop, by access code. */
+export type ToolSession = {
+    kind: 'browser' | 'desktop';
+    code: string;
+    url?: string;
+};
+export type ChatSequenceToolCall = {
+    id?: string;
+    name: string;
+    args: Record<string, unknown>;
+    status?: 'running' | 'success' | 'error';
+    result?: string;
+    progress?: unknown;
+    session?: ToolSession;
+};
+/** A file in a message: its type and name, and the FILE part it came in (ref, access code) for opening it. */
+export type ChatFile = {
+    mime: string;
+    name: string;
+    part?: any;
+};
+export type ChatMessageBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool';
+    call: ChatSequenceToolCall;
+} | ({
+    type: 'file';
+} & ChatFile);
+export declare function roomPartsToChatFields(parts: any[]): {
+    text: string;
+    files?: ChatFile[];
+    toolCalls?: ChatSequenceToolCall[];
+    sequence?: ChatMessageBlock[];
+};

package/dist/src/ui/chatSequence.js

@@ -0,0 +1,42 @@
+function toolSession(raw) {
+    if (!raw || typeof raw.code !== 'string' || !raw.code)
+        return undefined;
+    return { kind: raw.kind === 'desktop' ? 'desktop' : 'browser', code: raw.code, ...(typeof raw.url === 'string' && raw.url ? { url: raw.url } : {}) };
+}
+export function roomPartsToChatFields(parts) {
+    const texts = [];
+    const files = [];
+    const toolCalls = [];
+    const sequence = [];
+    for (const part of parts ?? []) {
+        if (part?.type === 'TEXT' && typeof part.text === 'string') {
+            texts.push(part.text);
+            if (part.text.trim())
+                sequence.push({ type: 'text', text: part.text });
+        }
+        else if (part?.type === 'FILE') {
+            const file = { mime: part.contentType ?? '', name: part.name ?? part.ref ?? 'file', part };
+            files.push(file);
+            sequence.push({ type: 'file', ...file });
+        }
+        else if (part?.type === 'INVOCATION') {
+            const session = toolSession(part.session);
+            const call = {
+                id: part.id,
+                name: part.name,
+                args: part.args ?? {},
+                status: part.status,
+                result: part.result,
+                ...(session ? { session } : {}),
+            };
+            toolCalls.push(call);
+            sequence.push({ type: 'tool', call });
+        }
+    }
+    return {
+        text: texts.join('\n').trim(),
+        files: files.length > 0 ? files : undefined,
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+        sequence: sequence.length > 0 ? sequence : undefined,
+    };
+}

package/dist/src/ui/crown.d.ts

@@ -0,0 +1,19 @@
+export type CrownTheme = Partial<{
+    gold: string;
+    charcoal: string;
+    silver: string;
+}>;
+export type MountCrownOptions = CrownTheme & {
+    inset?: number;
+    host?: HTMLElement | null;
+    mode?: "hover" | "loop";
+    duration?: number;
+};
+export declare function renderCrown(context: CanvasRenderingContext2D, size: number, t?: number, theme?: CrownTheme): void;
+export declare function drawCrown(size: number, theme?: CrownTheme): HTMLImageElement;
+export declare function getFaunaLogoDataUrl(): string;
+export declare function mountCrown(icon: HTMLCanvasElement, options?: MountCrownOptions): () => void;
+/** Fills a link with the Powered by Fauna badge: the crown on its charcoal tile (`brands.css`), turning when the badge is hovered. */
+export declare function mountPoweredBy(link: HTMLAnchorElement, options?: CrownTheme & {
+    inset?: number;
+}): () => void;

package/dist/src/ui/crown.js

@@ -0,0 +1,199 @@
+const GOLD = "rgb(247, 239, 138)";
+const CHARCOAL = "rgb(21, 21, 21)";
+const SILVER = "rgb(192, 192, 192)";
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+function parseColor(value, fallback) {
+    if (!value)
+        return fallback;
+    const hex = value.trim().match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+    if (hex) {
+        const raw = hex[1];
+        const full = raw.length === 3 ? raw.split("").map((c) => c + c).join("") : raw;
+        return [
+            parseInt(full.slice(0, 2), 16),
+            parseInt(full.slice(2, 4), 16),
+            parseInt(full.slice(4, 6), 16),
+        ];
+    }
+    const rgb = value.match(/\d+/g)?.map((c) => parseInt(c));
+    if (rgb && rgb.length >= 3)
+        return [rgb[0], rgb[1], rgb[2]];
+    return fallback;
+}
+function lerpRGB(a, b, t) {
+    const aRGB = parseColor(a, [21, 21, 21]);
+    const bRGB = parseColor(b, [247, 239, 138]);
+    return `rgb(${lerp(aRGB[0], bRGB[0], t)}, ${lerp(aRGB[1], bRGB[1], t)}, ${lerp(aRGB[2], bRGB[2], t)})`;
+}
+function sineInOut(x) {
+    return -(Math.cos(Math.PI * x) - 1) / 2;
+}
+export function renderCrown(context, size, t = Math.PI / 2, theme = {}) {
+    const gold = theme.gold ?? GOLD;
+    const charcoal = theme.charcoal ?? CHARCOAL;
+    const silver = theme.silver ?? SILVER;
+    const bars = 35;
+    const fov = 1.5;
+    const sagitta = size * (0.12 + 0.12 * Math.sin(t));
+    const barWidth = size / (fov ** 2 * bars);
+    const barHeight = size / 2;
+    const barAngles = (Math.PI * 2) / bars;
+    const radius = sagitta / 2 + size ** 2 / (8 * sagitta);
+    const bottomMidPoint = [size / 2, size / 2 + barHeight / 4];
+    const bottomApex = [bottomMidPoint[0], bottomMidPoint[1] - sagitta];
+    const bottomCenter = [bottomApex[0], bottomApex[1] + radius];
+    const ease = (v) => Math.sign(v) * Math.pow(Math.abs(v), 0.8);
+    const spikeMultiplier = (i) => 1 + 0.4 * Math.sin(2 * Math.PI * t + (i % 2) * Math.PI);
+    context.save();
+    context.beginPath();
+    context.arc(bottomCenter[0], bottomCenter[1], radius, 0, Math.PI * 2);
+    context.clip();
+    for (let i = 0; i < bars; i++) {
+        const angle = barAngles * i;
+        const raw = Math.sin(angle - t);
+        if (raw > 0)
+            continue;
+        const depth = ease(raw);
+        const spikeHeight = spikeMultiplier(i);
+        const x = (Math.cos(angle - t) * size) / 2 + size / 2;
+        const y = -sagitta * depth * spikeHeight;
+        const width = lerp(0, barWidth / fov, -depth);
+        context.fillStyle = lerpRGB(charcoal, gold, ((-depth + 1) / 2) * 0.5 + 0.5);
+        context.globalAlpha = lerp(0.4, 0.8, -depth);
+        context.beginPath();
+        context.roundRect(x - width / 2, size / 2 - barHeight / 2 + y, width, barHeight, width / 2);
+        context.fill();
+    }
+    context.restore();
+    context.save();
+    context.beginPath();
+    // Wider than the crown's box: spikes overshoot it mid turn and must reach into any inset.
+    context.rect(-size, -size, size * 3, size * 3);
+    context.arc(bottomCenter[0], bottomCenter[1], radius, 0, Math.PI * 2);
+    context.clip("evenodd");
+    for (let i = 0; i < bars; i++) {
+        const angle = barAngles * i;
+        const raw = Math.sin(angle - t);
+        if (raw <= 0)
+            continue;
+        const depth = ease(raw);
+        const spikeHeight = spikeMultiplier(i);
+        const x = (Math.cos(angle - t) * size) / 2 + size / 2;
+        const y = -sagitta * depth * spikeHeight;
+        const width = lerp(0, fov * barWidth, depth);
+        context.fillStyle = lerpRGB(charcoal, gold, ((depth + 1) / 2) * 0.5 + 0.5);
+        context.globalAlpha = lerp(0.7, 1, depth);
+        context.beginPath();
+        context.roundRect(x - width / 2, size / 2 - barHeight / 2 + y, width, barHeight, width / 2);
+        context.fill();
+    }
+    context.restore();
+    context.save();
+    context.strokeStyle = silver;
+    context.globalAlpha = 0.2;
+    context.lineWidth = size / 200;
+    context.beginPath();
+    context.arc(bottomCenter[0], bottomCenter[1], radius, 0, Math.PI * 2);
+    context.stroke();
+    context.restore();
+}
+export function drawCrown(size, theme = {}) {
+    const canvas = document.createElement("canvas");
+    canvas.width = size;
+    canvas.height = size;
+    const context = canvas.getContext("2d");
+    context.fillStyle = theme.charcoal ?? CHARCOAL;
+    context.fillRect(0, 0, size, size);
+    renderCrown(context, size, Math.PI / 2, theme);
+    const image = new Image(size, size);
+    image.src = canvas.toDataURL();
+    return image;
+}
+let logoDataUrl = null;
+export function getFaunaLogoDataUrl() {
+    if (!logoDataUrl)
+        logoDataUrl = drawCrown(192).src;
+    return logoDataUrl;
+}
+export function mountCrown(icon, options = {}) {
+    const dpr = window.devicePixelRatio || 1;
+    const mode = options.mode ?? "hover";
+    const duration = options.duration ?? (mode === "loop" ? 24000 : 2800);
+    const inset = Math.max(0, Math.min(0.35, options.inset ?? 0));
+    const theme = {
+        gold: options.gold,
+        charcoal: options.charcoal,
+        silver: options.silver,
+    };
+    const host = options.host ?? icon.parentElement ?? icon;
+    const draw = (t = Math.PI / 2) => {
+        const cssSize = icon.getBoundingClientRect().width;
+        if (cssSize <= 0)
+            return;
+        icon.width = cssSize * dpr;
+        icon.height = cssSize * dpr;
+        const context = icon.getContext("2d");
+        if (!context)
+            return;
+        context.save();
+        context.scale(dpr, dpr);
+        context.clearRect(0, 0, cssSize, cssSize);
+        const pad = cssSize * inset;
+        const drawSize = cssSize - pad * 2;
+        context.translate(pad, pad);
+        renderCrown(context, drawSize, t, theme);
+        context.restore();
+    };
+    draw();
+    const onResize = () => draw();
+    window.addEventListener("resize", onResize);
+    let raf = 0;
+    const stop = () => {
+        cancelAnimationFrame(raf);
+        raf = 0;
+    };
+    const onEnter = () => {
+        if (mode !== "hover")
+            return;
+        stop();
+        const start = performance.now();
+        const step = (now) => {
+            const p = Math.min((now - start) / duration, 1);
+            draw(2 * Math.PI * sineInOut(p) + Math.PI / 2);
+            if (p < 1)
+                raf = requestAnimationFrame(step);
+        };
+        raf = requestAnimationFrame(step);
+    };
+    if (mode === "hover")
+        host.addEventListener("mouseenter", onEnter);
+    if (mode === "loop") {
+        let last = performance.now();
+        let t = Math.PI / 2;
+        const step = (now) => {
+            t += ((now - last) / duration) * Math.PI * 2;
+            last = now;
+            draw(t);
+            raf = requestAnimationFrame(step);
+        };
+        raf = requestAnimationFrame(step);
+    }
+    return () => {
+        stop();
+        window.removeEventListener("resize", onResize);
+        host.removeEventListener("mouseenter", onEnter);
+    };
+}
+/** Fills a link with the Powered by Fauna badge: the crown on its charcoal tile (`brands.css`), turning when the badge is hovered. */
+export function mountPoweredBy(link, options = {}) {
+    link.href = "https://faunakit.com";
+    const crown = document.createElement("canvas");
+    crown.className = "fauna-powered-crown";
+    crown.setAttribute("aria-hidden", "true");
+    const label = document.createElement("span");
+    label.textContent = "Powered by Fauna";
+    link.replaceChildren(crown, label);
+    return mountCrown(crown, { inset: 0.14, host: link, ...options });
+}

package/dist/src/ui/cursor.d.ts

@@ -0,0 +1,73 @@
+import React from "react";
+import type { Presence as Seat } from "../shared/server.js";
+/** FNV-1a style hash so the same seed always maps to the same color. */
+export declare function hashSeed(seed: string): number;
+/**
+ * Vibrant (high-sat, mid-light) HSL color deterministically derived from `seed`.
+ */
+export declare function colorFromSeed(seed: string): string;
+/** Pin / chip color seed. Email first so composer drafts match sent history. */
+export declare function authorColorSeed(author?: {
+    id?: string;
+    profile?: {
+        email?: string;
+    };
+}): string | undefined;
+/** Filled Material-style push pin. Color via CSS `currentColor`. */
+export declare function PinMark({ className, style }: {
+    className?: string;
+    style?: React.CSSProperties;
+}): React.JSX.Element;
+export type CursorProps = {
+    /** Stable id (presence id, user id, email, …) — seeds the color. */
+    seed: string;
+    /** Optional label under / beside the tip (display name). */
+    label?: string;
+    /** A CSS cursor keyword (`pointer`, `text`, `nwse-resize`...). Unknown ones draw the arrow. */
+    shape?: string;
+    className?: string;
+    style?: React.CSSProperties;
+};
+/**
+ * Returns a React SVG cursor whose fill is a vibrant color seeded by `seed`, drawn in
+ * `shape`. Its hotspot is at (0, 0) of the element's box — position with
+ * `style={{ left, top }}` (or transform) at the client's x/y.
+ */
+export declare function Cursor({ seed, label, shape, className, style }: CursorProps): React.JSX.Element;
+/** Convenience: seed → reusable cursor component with that color baked in. */
+export declare function cursorFor(seed: string): React.FC<Omit<CursorProps, "seed">>;
+export type PresenceProps = {
+    /** Where this seat's pointer moves, like a room's input layer. */
+    layer: HTMLElement | null;
+    self: Seat | null;
+    peers: Seat[];
+    /** Page coordinates for a client point, or null outside the page. */
+    toPage: (clientX: number, clientY: number) => {
+        x: number;
+        y: number;
+    } | null;
+    /** Where a page point sits in this container. */
+    toScreen: (x: number, y: number) => {
+        x: number;
+        y: number;
+    };
+    /** The room's real pointer and the seat driving it. That seat is drawn where the
+     *  pointer really is, in its shape, instead of where its presence says. */
+    machine?: {
+        seat: string;
+        x: number;
+        y: number;
+        shape?: string;
+    } | null;
+};
+/**
+ * Share this seat's pointer in page coordinates and draw everyone else's at this
+ * view's scale, so a cursor lands on the same spot however each person sized
+ * their window. Put it in a positioned container over the page.
+ */
+export declare function Presence({ layer, self, peers, toPage, toScreen, machine }: PresenceProps): React.JSX.Element;
+/** Presence cursors for apps without React. Call `update` as peers move or the view resizes. */
+export declare function mountPresence(el: HTMLElement, props: PresenceProps): {
+    update(props: PresenceProps): void;
+    destroy(): void;
+};

package/dist/src/ui/cursor.js

@@ -0,0 +1,175 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { createRoot } from "react-dom/client";
+/** FNV-1a style hash so the same seed always maps to the same color. */
+export function hashSeed(seed) {
+    let h = 2166136261;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/**
+ * Vibrant (high-sat, mid-light) HSL color deterministically derived from `seed`.
+ */
+export function colorFromSeed(seed) {
+    const h = hashSeed(seed || "?");
+    const hue = h % 360;
+    // Keep sat/light in a punchy band so cursors stay readable on light/dark UI.
+    const sat = 68 + (h >>> 8) % 22; // 68–89%
+    const light = 48 + (h >>> 16) % 14; // 48–61%
+    return `hsl(${hue} ${sat}% ${light}%)`;
+}
+/** Pin / chip color seed. Email first so composer drafts match sent history. */
+export function authorColorSeed(author) {
+    const email = author?.profile?.email?.trim();
+    if (email)
+        return email;
+    const id = author?.id?.trim();
+    return id || undefined;
+}
+/** Filled Material-style push pin. Color via CSS `currentColor`. */
+export function PinMark({ className, style }) {
+    return (_jsx("svg", { className: className, width: "28", height: "28", viewBox: "0 0 24 24", fill: "none", xmlns: "http://www.w3.org/2000/svg", style: {
+            display: "block",
+            filter: "drop-shadow(0 1px 2px rgba(0,0,0,0.45))",
+            overflow: "visible",
+            ...style,
+        }, "aria-hidden": true, children: _jsx("path", { d: "M16 9V4h1c.55 0 1-.45 1-1s-.45-1-1-1H7c-.55 0-1 .45-1 1s.45 1 1 1h1v5c0 1.66-1.34 3-3 3v2h5.97v7l1 1 1-1v-7H19v-2c-1.66 0-3-1.34-3-3z", fill: "currentColor", stroke: "rgba(255,255,255,0.95)", strokeWidth: "2.1", strokeLinejoin: "round", strokeLinecap: "round", style: { paintOrder: "stroke fill" } }) }));
+}
+const ARROW = { d: "M4 2.5v16.2l4.1-3.5 2.4 5.8 2.5-1-2.4-5.7H17L4 2.5z", hotspot: [4, 2.5] };
+const RESIZE_EW = "M2.5 12l4-4v2.5h11V8l4 4-4 4v-2.5h-11V16z";
+const GLYPHS = {
+    pointer: {
+        d: "M9 3.5a1.5 1.5 0 0 1 3 0V10h.5V8.5a1.5 1.5 0 0 1 3 0V10h.5V9.5a1.5 1.5 0 0 1 3 0V11h.3a1.5 1.5 0 0 1 1.7 1.5V16c0 3-2.2 5.5-5.2 5.5H12c-1.6 0-3-.8-3.9-2.1L5.2 15a1.6 1.6 0 0 1 2.4-2L9 14.4V3.5z",
+        hotspot: [10.5, 2],
+    },
+    grab: {
+        d: "M8 9V6.5a1.5 1.5 0 0 1 3 0V9h.5V5a1.5 1.5 0 0 1 3 0v4h.5V6a1.5 1.5 0 0 1 3 0v4.5h.2V9a1.5 1.5 0 0 1 3 0v6.5c0 3.3-2.5 6-5.8 6h-2.2c-1.7 0-3.3-.9-4.2-2.3L4.6 15a1.5 1.5 0 0 1 2.5-1.7L8 14.5V9z",
+        hotspot: [13, 12],
+    },
+    grabbing: {
+        d: "M7.5 11a1.5 1.5 0 0 1 3 0v-.5a1.5 1.5 0 0 1 3 0v.5a1.5 1.5 0 0 1 3 0v.5a1.5 1.5 0 0 1 3 0v4c0 3.3-2.5 6-5.8 6h-2c-1.7 0-3.2-.8-4.1-2.2L5 15.5a1.5 1.5 0 0 1 2.5-1.6V11z",
+        hotspot: [13, 13],
+    },
+    text: { d: "M9 3.5h6M12 3.5v17M9 20.5h6", hotspot: [12, 12], lines: true },
+    move: {
+        d: "M12 2.5l3 3.2h-2v5.3h5.3v-2l3.2 3-3.2 3v-2H13v5.3h2l-3 3.2-3-3.2h2V13H5.7v2L2.5 12l3.2-3v2H11V5.7H9z",
+        hotspot: [12, 12],
+    },
+    "ew-resize": { d: RESIZE_EW, hotspot: [12, 12] },
+    "ns-resize": { d: RESIZE_EW, hotspot: [12, 12], rotate: 90 },
+    "nwse-resize": { d: RESIZE_EW, hotspot: [12, 12], rotate: 45 },
+    "nesw-resize": { d: RESIZE_EW, hotspot: [12, 12], rotate: -45 },
+    "not-allowed": { d: "M12 4.5a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15zM6.7 6.7l10.6 10.6", hotspot: [12, 12], lines: true },
+    crosshair: { d: "M12 3v18M3 12h18", hotspot: [12, 12], lines: true },
+};
+const ALIASES = {
+    "vertical-text": "text",
+    "all-scroll": "move",
+    "e-resize": "ew-resize", "w-resize": "ew-resize", "col-resize": "ew-resize",
+    "n-resize": "ns-resize", "s-resize": "ns-resize", "row-resize": "ns-resize",
+    "nw-resize": "nwse-resize", "se-resize": "nwse-resize",
+    "ne-resize": "nesw-resize", "sw-resize": "nesw-resize",
+    "no-drop": "not-allowed",
+    cell: "crosshair",
+};
+function glyphFor(shape) {
+    if (!shape)
+        return ARROW;
+    return GLYPHS[ALIASES[shape] ?? shape] ?? ARROW;
+}
+/**
+ * Returns a React SVG cursor whose fill is a vibrant color seeded by `seed`, drawn in
+ * `shape`. Its hotspot is at (0, 0) of the element's box — position with
+ * `style={{ left, top }}` (or transform) at the client's x/y.
+ */
+export function Cursor({ seed, label, shape, className, style }) {
+    const color = colorFromSeed(seed);
+    const glyph = glyphFor(shape);
+    const [hx, hy] = glyph.hotspot;
+    const turn = glyph.rotate ? `rotate(${glyph.rotate} 12 12)` : undefined;
+    return (_jsxs("div", { className: className, style: {
+            position: "absolute",
+            left: 0,
+            top: 0,
+            width: 0,
+            height: 0,
+            pointerEvents: "none",
+            zIndex: 40,
+            ...style,
+        }, "aria-hidden": true, children: [_jsx("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", xmlns: "http://www.w3.org/2000/svg", style: {
+                    display: "block",
+                    // Shift so the glyph's hotspot is element (0,0).
+                    transform: `translate(${-hx}px, ${-hy}px)`,
+                    filter: "drop-shadow(0 1px 2px rgba(0,0,0,0.35))",
+                    overflow: "visible",
+                }, children: glyph.lines ? (_jsxs("g", { transform: turn, strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("path", { d: glyph.d, stroke: "rgba(255,255,255,0.92)", strokeWidth: "4.5" }), _jsx("path", { d: glyph.d, stroke: color, strokeWidth: "2" })] })) : (_jsx("path", { d: glyph.d, transform: turn, fill: color, stroke: "rgba(255,255,255,0.92)", strokeWidth: "1.25", strokeLinejoin: "round" })) }), label ? (_jsx("span", { style: {
+                    position: "absolute",
+                    left: 16,
+                    top: 18,
+                    padding: "2px 6px",
+                    borderRadius: 6,
+                    background: color,
+                    color: "#fff",
+                    fontFamily: "Inter, system-ui, sans-serif",
+                    fontSize: 11,
+                    fontWeight: 600,
+                    lineHeight: 1.3,
+                    whiteSpace: "nowrap",
+                    boxShadow: "0 1px 3px rgba(0,0,0,0.25)",
+                }, children: label })) : null] }));
+}
+/** Convenience: seed → reusable cursor component with that color baked in. */
+export function cursorFor(seed) {
+    return function SeededCursor(props) {
+        return _jsx(Cursor, { seed: seed, ...props });
+    };
+}
+/**
+ * Share this seat's pointer in page coordinates and draw everyone else's at this
+ * view's scale, so a cursor lands on the same spot however each person sized
+ * their window. Put it in a positioned container over the page.
+ */
+export function Presence({ layer, self, peers, toPage, toScreen, machine }) {
+    const lastSent = useRef(0);
+    const toPageRef = useRef(toPage);
+    toPageRef.current = toPage;
+    useEffect(() => {
+        if (!layer || !self)
+            return;
+        const onMove = (event) => {
+            const now = performance.now();
+            if (now - lastSent.current < 40)
+                return;
+            const point = toPageRef.current(event.clientX, event.clientY);
+            if (!point)
+                return;
+            lastSent.current = now;
+            self.move([point.x, point.y, 0]);
+        };
+        layer.addEventListener("pointermove", onMove, { passive: true });
+        return () => layer.removeEventListener("pointermove", onMove);
+    }, [layer, self]);
+    // Id only: the same person twice is two seats, and both stay visible.
+    const others = self ? peers.filter((p) => p.id !== self.id) : peers;
+    return (_jsx("div", { className: "fauna-cursors", "aria-hidden": "true", children: others.map((peer) => {
+            const driving = machine?.seat === peer.id ? machine : null;
+            const [x, y] = driving ? [driving.x, driving.y] : peer.position;
+            if (!x && !y)
+                return null;
+            const at = toScreen(x, y);
+            const label = peer.profile?.displayName || peer.profile?.email?.split("@")[0] || "Guest";
+            return _jsx(Cursor, { seed: peer.id, label: label, shape: driving?.shape, style: { transform: `translate3d(${at.x}px, ${at.y}px, 0)` } }, peer.id);
+        }) }));
+}
+/** Presence cursors for apps without React. Call `update` as peers move or the view resizes. */
+export function mountPresence(el, props) {
+    const root = createRoot(el);
+    root.render(_jsx(Presence, { ...props }));
+    return {
+        update(next) { root.render(_jsx(Presence, { ...next })); },
+        destroy() { root.unmount(); },
+    };
+}

package/dist/src/ui/device.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Lightweight device-class heuristics for UI layout (phone vs computer).
+ * Pure functions over optional overrides so tests don't need a real window.
+ */
+export type DeviceClass = 'phone' | 'computer';
+export type DeviceHints = {
+    /** CSS viewport width in CSS pixels. */
+    width?: number;
+    /** CSS viewport height in CSS pixels. */
+    height?: number;
+    /** navigator.userAgent / userAgentData brands string. */
+    userAgent?: string;
+    /** navigator.maxTouchPoints */
+    maxTouchPoints?: number;
+    /** matchMedia('(pointer: coarse)') */
+    coarsePointer?: boolean;
+    /** matchMedia('(hover: hover)') — true when a fine hover pointer exists. */
+    canHover?: boolean;
+};
+/**
+ * Classify the current (or provided) environment as phone vs computer.
+ *
+ * Heuristic (ordered):
+ * 1. Strong UA mobile tokens → phone
+ * 2. Narrow viewport (≤ 768) + coarse pointer / touch → phone
+ * 3. Narrow viewport + no hover + touch → phone
+ * 4. Otherwise computer
+ */
+export declare function detectDevice(hints?: DeviceHints): DeviceClass;
+/** Convenience: true when `detectDevice` says phone. */
+export declare function isPhone(hints?: DeviceHints): boolean;
+/** Convenience: true when `detectDevice` says computer. */
+export declare function isComputer(hints?: DeviceHints): boolean;

package/dist/src/ui/device.js

@@ -0,0 +1,49 @@
+/**
+ * Lightweight device-class heuristics for UI layout (phone vs computer).
+ * Pure functions over optional overrides so tests don't need a real window.
+ */
+const PHONE_UA = /Android.+Mobile|iPhone|iPod|Windows Phone|webOS|BlackBerry|IEMobile|Opera Mini|Mobile Safari|Mobile\/\w+/i;
+/**
+ * Classify the current (or provided) environment as phone vs computer.
+ *
+ * Heuristic (ordered):
+ * 1. Strong UA mobile tokens → phone
+ * 2. Narrow viewport (≤ 768) + coarse pointer / touch → phone
+ * 3. Narrow viewport + no hover + touch → phone
+ * 4. Otherwise computer
+ */
+export function detectDevice(hints = {}) {
+    const width = hints.width ??
+        (typeof window !== 'undefined' ? window.innerWidth : undefined);
+    const userAgent = hints.userAgent ??
+        (typeof navigator !== 'undefined' ? navigator.userAgent : '');
+    const maxTouchPoints = hints.maxTouchPoints ??
+        (typeof navigator !== 'undefined' ? navigator.maxTouchPoints ?? 0 : 0);
+    let coarsePointer = hints.coarsePointer;
+    let canHover = hints.canHover;
+    if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+        if (coarsePointer === undefined) {
+            coarsePointer = window.matchMedia('(pointer: coarse)').matches;
+        }
+        if (canHover === undefined) {
+            canHover = window.matchMedia('(hover: hover)').matches;
+        }
+    }
+    if (userAgent && PHONE_UA.test(userAgent))
+        return 'phone';
+    const narrow = width !== undefined && width <= 768;
+    const touchy = maxTouchPoints > 0 || coarsePointer === true;
+    if (narrow && touchy)
+        return 'phone';
+    if (narrow && canHover === false && maxTouchPoints > 0)
+        return 'phone';
+    return 'computer';
+}
+/** Convenience: true when `detectDevice` says phone. */
+export function isPhone(hints) {
+    return detectDevice(hints) === 'phone';
+}
+/** Convenience: true when `detectDevice` says computer. */
+export function isComputer(hints) {
+    return detectDevice(hints) === 'computer';
+}