@jgengine/react 0.7.0 → 0.9.0

package/dist/settings.d.ts

@@ -0,0 +1,75 @@
+import { type ReactNode } from "react";
+import { type SettingCategory, type SettingKind, type SettingOption, type SettingsStore, type SettingsSurface, type SettingsVariant, type SettingValue } from "@jgengine/core/settings/settingsModel";
+export declare function SettingsProvider({ store, children }: {
+    store: SettingsStore;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The shared settings store, or a standalone one when no provider is mounted (game code read outside the shell). */
+export declare function useSettingsStore(): SettingsStore;
+/** Read + write one persisted setting; re-renders when the value changes anywhere. */
+export declare function useSetting<T extends SettingValue>(id: string, fallback: T): readonly [T, (value: SettingValue) => void];
+export interface SettingsRow {
+    id: string;
+    label: string;
+    kind: SettingKind;
+    value: SettingValue;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly SettingOption[];
+    format?: (value: number) => string;
+    set: (value: SettingValue) => void;
+}
+export interface SettingsKeybindRow {
+    action: string;
+    label: string;
+    bindingLabel: string;
+    isDefault: boolean;
+    rebind: (code: string) => void;
+    reset: () => void;
+}
+export interface SettingsCategoryView {
+    id: SettingCategory;
+    label: string;
+    rows: SettingsRow[];
+    keybinds: SettingsKeybindRow[];
+}
+/** A resolved game-state action — `run` is already bound to the game context and closes the menu. */
+export interface SettingsActionView {
+    id: string;
+    label: string;
+    kind: "default" | "danger";
+    description?: string;
+    run: () => void;
+}
+/** The live settings controller — every category/row/keybind/action plus open-state. Render it any way you like or drive the engine menu. */
+export interface SettingsController {
+    categories: SettingsCategoryView[];
+    /** Game-state actions (Restart, Quit…) — the menu shows them as its first "Game" tab. */
+    actions: SettingsActionView[];
+    variant: SettingsVariant;
+    surface: SettingsSurface | false;
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    setOpen: (open: boolean) => void;
+}
+export declare function SettingsControllerProvider({ controller, children, }: {
+    controller: SettingsController;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The engine settings controller for the current game — render your own settings UI from `categories`, or open the built-in menu with `open()`. Null-safe stub when mounted outside the shell. */
+export declare function useSettings(): SettingsController;
+/** True when the game has any setting or game-action to show — gate your own settings entry on it. */
+export declare function useHasSettings(): boolean;
+/**
+ * Inline settings entry — drop it anywhere in your game's menu or HUD; it opens
+ * the themed settings menu. Headless: pass `className` for placement/skin and
+ * `children` to replace the default gear glyph. Renders nothing when the game
+ * has no settings to show, so it never leaves a dead button behind.
+ */
+export declare function SettingsTrigger({ className, children, label, }: {
+    className?: string;
+    children?: ReactNode;
+    label?: string;
+}): import("react").JSX.Element | null;

package/dist/settings.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useSyncExternalStore } from "react";
+import { createSettingsStore, } from "@jgengine/core/settings/settingsModel";
+const SettingsStoreContext = createContext(null);
+export function SettingsProvider({ store, children }) {
+    return _jsx(SettingsStoreContext.Provider, { value: store, children: children });
+}
+/** The shared settings store, or a standalone one when no provider is mounted (game code read outside the shell). */
+export function useSettingsStore() {
+    const store = useContext(SettingsStoreContext);
+    return store ?? fallbackStore();
+}
+let standalone = null;
+function fallbackStore() {
+    if (standalone === null)
+        standalone = createSettingsStore();
+    return standalone;
+}
+/** Read + write one persisted setting; re-renders when the value changes anywhere. */
+export function useSetting(id, fallback) {
+    const store = useSettingsStore();
+    const value = useSyncExternalStore(store.subscribe, () => store.get(id, fallback), () => fallback);
+    const set = useCallback((next) => store.set(id, next), [store, id]);
+    return [value, set];
+}
+const SettingsControllerContext = createContext(null);
+export function SettingsControllerProvider({ controller, children, }) {
+    return _jsx(SettingsControllerContext.Provider, { value: controller, children: children });
+}
+/** The engine settings controller for the current game — render your own settings UI from `categories`, or open the built-in menu with `open()`. Null-safe stub when mounted outside the shell. */
+export function useSettings() {
+    return useContext(SettingsControllerContext) ?? EMPTY_CONTROLLER;
+}
+const noop = () => undefined;
+const EMPTY_CONTROLLER = {
+    categories: [],
+    actions: [],
+    variant: "panel",
+    surface: false,
+    isOpen: false,
+    open: noop,
+    close: noop,
+    setOpen: noop,
+};
+/** True when the game has any setting or game-action to show — gate your own settings entry on it. */
+export function useHasSettings() {
+    const s = useSettings();
+    return s.categories.length > 0 || s.actions.length > 0;
+}
+/**
+ * Inline settings entry — drop it anywhere in your game's menu or HUD; it opens
+ * the themed settings menu. Headless: pass `className` for placement/skin and
+ * `children` to replace the default gear glyph. Renders nothing when the game
+ * has no settings to show, so it never leaves a dead button behind.
+ */
+export function SettingsTrigger({ className, children, label = "Settings", }) {
+    const settings = useSettings();
+    if (settings.categories.length === 0 && settings.actions.length === 0)
+        return null;
+    return (_jsx("button", { type: "button", "aria-label": label, onClick: settings.open, className: className, children: children ?? (_jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round", width: "1em", height: "1em", "aria-hidden": true, children: [_jsx("circle", { cx: "12", cy: "12", r: "3" }), _jsx("path", { d: "M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" })] })) }));
+}

package/dist/skillCheckPaint.d.ts

@@ -0,0 +1,4 @@
+import type { SkillCheckConfig, SkillCheckResult } from "@jgengine/core/interaction/skillCheck";
+import type { QteStep } from "@jgengine/core/interaction/qte";
+export declare function paintSkillCheckDom(root: HTMLElement, zone: HTMLElement, marker: HTMLElement, config: SkillCheckConfig, result: SkillCheckResult): void;
+export declare function paintQteStepDom(elements: ReadonlyMap<string, HTMLElement>, steps: readonly QteStep[], elapsed: number, activeId: string | null, stepClassName?: string, activeClassName?: string, doneClassName?: string): void;

package/dist/skillCheckPaint.js

@@ -0,0 +1,28 @@
+export function paintSkillCheckDom(root, zone, marker, config, result) {
+    const zoneLeft = (result.zone.start / config.trackWidth) * 100;
+    const zoneWidth = ((result.zone.end - result.zone.start) / config.trackWidth) * 100;
+    const markerLeft = (result.markerPosition / config.trackWidth) * 100;
+    zone.style.left = `${zoneLeft}%`;
+    zone.style.width = `${zoneWidth}%`;
+    marker.style.left = `${markerLeft}%`;
+    root.dataset.inZone = result.success ? "true" : "false";
+    root.dataset.timedOut = result.timedOut ? "true" : "false";
+}
+export function paintQteStepDom(elements, steps, elapsed, activeId, stepClassName, activeClassName, doneClassName) {
+    for (const step of steps) {
+        const el = elements.get(step.id);
+        if (el === undefined)
+            continue;
+        const isActive = activeId === step.id;
+        const isDone = elapsed > step.windowEnd;
+        const classes = [stepClassName, isActive ? activeClassName : isDone ? doneClassName : undefined]
+            .filter(Boolean)
+            .join(" ");
+        if (classes.length > 0)
+            el.className = classes;
+        else
+            el.removeAttribute("class");
+        el.dataset.active = isActive ? "true" : "false";
+        el.dataset.done = isDone ? "true" : "false";
+    }
+}

package/dist/social.d.ts

@@ -0,0 +1,108 @@
+import { type ReactNode } from "react";
+import type { FriendEntry, FriendRequestEntry, PartyInviteEntry, PartyMemberEntry, WorldInvite, WorldInviteTarget } from "@jgengine/core/game/social";
+import { type MatchFilter, type SessionListing } from "@jgengine/core/multiplayer/matchmaking";
+export declare function PresenceDot({ userId, className }: {
+    userId: string;
+    className?: string;
+}): import("react").JSX.Element;
+export declare function FriendRow({ friend, className, dotClassName, children, }: {
+    friend: FriendEntry;
+    className?: string;
+    dotClassName?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function FriendsList({ className, rowClassName, dotClassName, emptyState, renderFriend, }: {
+    className?: string;
+    rowClassName?: string;
+    dotClassName?: string;
+    emptyState?: ReactNode;
+    renderFriend?: (friend: FriendEntry) => ReactNode;
+}): import("react").JSX.Element;
+export declare function AddFriendButton({ toUserId, className, children, onRequested, onRejected, }: {
+    toUserId: string;
+    className?: string;
+    children?: ReactNode;
+    onRequested?: (requestId: string) => void;
+    onRejected?: (reason: string) => void;
+}): import("react").JSX.Element;
+export declare function FriendRequestsList({ className, rowClassName, acceptClassName, declineClassName, emptyState, renderRequest, }: {
+    className?: string;
+    rowClassName?: string;
+    acceptClassName?: string;
+    declineClassName?: string;
+    emptyState?: ReactNode;
+    renderRequest?: (request: FriendRequestEntry) => ReactNode;
+}): import("react").JSX.Element;
+export declare function PartyMemberRow({ member, className, dotClassName, children, }: {
+    member: PartyMemberEntry;
+    className?: string;
+    dotClassName?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function PartyFrame({ className, rowClassName, dotClassName, emptyState, renderMember, }: {
+    className?: string;
+    rowClassName?: string;
+    dotClassName?: string;
+    emptyState?: ReactNode;
+    renderMember?: (member: PartyMemberEntry) => ReactNode;
+}): import("react").JSX.Element;
+export declare function PartyInviteToast({ className, acceptClassName, declineClassName, renderInvite, }: {
+    className?: string;
+    acceptClassName?: string;
+    declineClassName?: string;
+    renderInvite?: (invite: PartyInviteEntry) => ReactNode;
+}): import("react").JSX.Element | null;
+export declare function LeavePartyButton({ className, children, }: {
+    className?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element | null;
+export declare function WorldInviteToast({ className, acceptClassName, declineClassName, onAccepted, renderInvite, }: {
+    className?: string;
+    acceptClassName?: string;
+    declineClassName?: string;
+    onAccepted: (target: WorldInviteTarget) => void;
+    renderInvite?: (invite: WorldInvite) => ReactNode;
+}): import("react").JSX.Element | null;
+export declare function InviteToWorldButton({ toUserId, target, className, children, onInvited, onRejected, }: {
+    toUserId: string;
+    target: WorldInviteTarget;
+    className?: string;
+    children?: ReactNode;
+    onInvited?: (inviteId: string) => void;
+    onRejected?: (reason: string) => void;
+}): import("react").JSX.Element;
+export declare function WorldBrowser({ listings, onJoin, className, rowClassName, joinClassName, emptyState, renderListing, }: {
+    listings: readonly SessionListing[];
+    onJoin: (listing: SessionListing) => void;
+    className?: string;
+    rowClassName?: string;
+    joinClassName?: string;
+    emptyState?: ReactNode;
+    renderListing?: (listing: SessionListing) => ReactNode;
+}): import("react").JSX.Element;
+export declare function JoinByCode({ onJoin, className, inputClassName, buttonClassName, placeholder, children, }: {
+    onJoin: (code: string) => void;
+    className?: string;
+    inputClassName?: string;
+    buttonClassName?: string;
+    placeholder?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function QuickMatchButton({ listings, onJoin, onNoMatch, filter, className, children, }: {
+    listings: readonly SessionListing[];
+    onJoin: (listing: SessionListing) => void;
+    onNoMatch?: () => void;
+    filter?: MatchFilter;
+    className?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function EmoteWheel({ emotes, radius, open, className, emoteClassName, onPlayed, onRejected, renderEmote, }: {
+    emotes: readonly string[];
+    radius?: number;
+    open?: boolean;
+    className?: string;
+    emoteClassName?: string;
+    onPlayed?: (emoteId: string) => void;
+    onRejected?: (reason: string) => void;
+    renderEmote?: (emoteId: string) => ReactNode;
+}): import("react").JSX.Element | null;

package/dist/social.js

@@ -0,0 +1,119 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { normalizeJoinCode, quickMatch, } from "@jgengine/core/multiplayer/matchmaking";
+import { useGameContext } from "./provider.js";
+import { useFriendRequests, useFriends, useParty, usePartyInvites, usePresence, useWorldInvites, } from "./hooks.js";
+export function PresenceDot({ userId, className }) {
+    const presence = usePresence(userId);
+    return (_jsx("span", { className: className, "data-presence-dot": true, "data-user": userId, "data-online": presence.online, "data-server": presence.serverId }));
+}
+export function FriendRow({ friend, className, dotClassName, children, }) {
+    return (_jsxs("div", { className: className, "data-friend": friend.userId, "data-online": friend.online, children: [_jsx(PresenceDot, { userId: friend.userId, className: dotClassName }), _jsx("span", { "data-friend-name": true, children: friend.userId }), children] }));
+}
+export function FriendsList({ className, rowClassName, dotClassName, emptyState, renderFriend, }) {
+    const friends = useFriends();
+    return (_jsx("div", { className: className, "data-friends-list": true, children: friends.length === 0
+            ? emptyState ?? null
+            : friends.map((friend) => renderFriend !== undefined ? (renderFriend(friend)) : (_jsx(FriendRow, { friend: friend, className: rowClassName, dotClassName: dotClassName }, friend.userId))) }));
+}
+export function AddFriendButton({ toUserId, className, children, onRequested, onRejected, }) {
+    const ctx = useGameContext();
+    const denied = ctx.game.social.friends.canRequest(ctx.player.userId, toUserId);
+    return (_jsx("button", { type: "button", className: className, "data-add-friend": toUserId, disabled: denied !== null, title: denied?.reason, onClick: () => {
+            const result = ctx.game.social.friends.request(ctx.player.userId, toUserId);
+            if ("reason" in result)
+                onRejected?.(result.reason);
+            else
+                onRequested?.(result.requestId);
+        }, children: children ?? "Add friend" }));
+}
+export function FriendRequestsList({ className, rowClassName, acceptClassName, declineClassName, emptyState, renderRequest, }) {
+    const ctx = useGameContext();
+    const requests = useFriendRequests();
+    return (_jsx("div", { className: className, "data-friend-requests": true, children: requests.length === 0
+            ? emptyState ?? null
+            : requests.map((request) => renderRequest !== undefined ? (renderRequest(request)) : (_jsxs("div", { className: rowClassName, "data-friend-request": request.requestId, children: [_jsx("span", { "data-request-from": true, children: request.fromUserId }), _jsx("button", { type: "button", className: acceptClassName, "data-accept": true, onClick: () => ctx.game.social.friends.accept(ctx.player.userId, request.requestId), children: "Accept" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => ctx.game.social.friends.decline(ctx.player.userId, request.requestId), children: "Decline" })] }, request.requestId))) }));
+}
+export function PartyMemberRow({ member, className, dotClassName, children, }) {
+    return (_jsxs("div", { className: className, "data-party-member": member.userId, "data-role": member.role, children: [_jsx(PresenceDot, { userId: member.userId, className: dotClassName }), _jsx("span", { "data-member-name": true, children: member.userId }), children] }));
+}
+export function PartyFrame({ className, rowClassName, dotClassName, emptyState, renderMember, }) {
+    const members = useParty();
+    return (_jsx("div", { className: className, "data-party-frame": true, "data-party-size": members.length, children: members.length === 0
+            ? emptyState ?? null
+            : members.map((member) => renderMember !== undefined ? (renderMember(member)) : (_jsx(PartyMemberRow, { member: member, className: rowClassName, dotClassName: dotClassName }, member.userId))) }));
+}
+export function PartyInviteToast({ className, acceptClassName, declineClassName, renderInvite, }) {
+    const ctx = useGameContext();
+    const invites = usePartyInvites();
+    if (invites.length === 0)
+        return null;
+    return (_jsx("div", { className: className, "data-party-invites": true, children: invites.map((invite) => renderInvite !== undefined ? (renderInvite(invite)) : (_jsxs("div", { "data-party-invite": invite.inviteId, children: [_jsx("span", { "data-invite-from": true, children: invite.fromUserId }), _jsx("button", { type: "button", className: acceptClassName, "data-accept": true, onClick: () => ctx.game.social.party.accept(ctx.player.userId, invite.inviteId), children: "Join" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => ctx.game.social.party.decline(ctx.player.userId, invite.inviteId), children: "Decline" })] }, invite.inviteId))) }));
+}
+export function LeavePartyButton({ className, children, }) {
+    const ctx = useGameContext();
+    const members = useParty();
+    if (members.length === 0)
+        return null;
+    return (_jsx("button", { type: "button", className: className, "data-leave-party": true, onClick: () => ctx.game.social.party.leave(ctx.player.userId), children: children ?? "Leave party" }));
+}
+export function WorldInviteToast({ className, acceptClassName, declineClassName, onAccepted, renderInvite, }) {
+    const ctx = useGameContext();
+    const invites = useWorldInvites();
+    if (invites.length === 0)
+        return null;
+    return (_jsx("div", { className: className, "data-world-invites": true, children: invites.map((invite) => renderInvite !== undefined ? (renderInvite(invite)) : (_jsxs("div", { "data-world-invite": invite.id, children: [_jsx("span", { "data-invite-from": true, children: invite.fromUserId }), _jsx("span", { "data-invite-server": true, children: invite.serverId }), _jsx("button", { type: "button", className: acceptClassName, "data-accept": true, onClick: () => {
+                        const result = ctx.game.social.worldInvites.accept(ctx.player.userId, invite.id);
+                        if ("target" in result)
+                            onAccepted(result.target);
+                    }, children: "Join" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => ctx.game.social.worldInvites.decline(ctx.player.userId, invite.id), children: "Decline" })] }, invite.id))) }));
+}
+export function InviteToWorldButton({ toUserId, target, className, children, onInvited, onRejected, }) {
+    const ctx = useGameContext();
+    const denied = ctx.game.social.worldInvites.canInvite(ctx.player.userId, toUserId);
+    return (_jsx("button", { type: "button", className: className, "data-invite-to-world": toUserId, disabled: denied !== null, title: denied?.reason, onClick: () => {
+            const result = ctx.game.social.worldInvites.invite(ctx.player.userId, toUserId, target);
+            if ("reason" in result)
+                onRejected?.(result.reason);
+            else
+                onInvited?.(result.inviteId);
+        }, children: children ?? "Invite to world" }));
+}
+export function WorldBrowser({ listings, onJoin, className, rowClassName, joinClassName, emptyState, renderListing, }) {
+    return (_jsx("div", { className: className, "data-world-browser": true, children: listings.length === 0
+            ? emptyState ?? null
+            : listings.map((listing) => renderListing !== undefined ? (renderListing(listing)) : (_jsxs("div", { className: rowClassName, "data-world": listing.serverId, "data-mode": listing.mode, "data-full": listing.memberCount >= listing.slotsPerServer, children: [_jsx("span", { "data-world-label": true, children: listing.label ?? listing.serverId }), _jsxs("span", { "data-world-count": true, children: [listing.memberCount, "/", listing.slotsPerServer] }), _jsx("button", { type: "button", className: joinClassName, "data-join": true, disabled: listing.memberCount >= listing.slotsPerServer, onClick: () => onJoin(listing), children: "Join" })] }, listing.serverId))) }));
+}
+export function JoinByCode({ onJoin, className, inputClassName, buttonClassName, placeholder, children, }) {
+    const [code, setCode] = useState("");
+    function submit(event) {
+        event.preventDefault();
+        const normalized = normalizeJoinCode(code);
+        if (normalized.length === 0)
+            return;
+        onJoin(normalized);
+        setCode("");
+    }
+    return (_jsxs("form", { className: className, "data-join-by-code": true, onSubmit: submit, children: [_jsx("input", { className: inputClassName, type: "text", value: code, placeholder: placeholder ?? "Join code", onChange: (event) => setCode(event.target.value) }), _jsx("button", { type: "submit", className: buttonClassName, "data-join": true, children: children ?? "Join" })] }));
+}
+export function QuickMatchButton({ listings, onJoin, onNoMatch, filter, className, children, }) {
+    return (_jsx("button", { type: "button", className: className, "data-quick-match": true, onClick: () => {
+            const match = quickMatch(listings, filter);
+            if (match === null)
+                onNoMatch?.();
+            else
+                onJoin(match);
+        }, children: children ?? "Quick match" }));
+}
+export function EmoteWheel({ emotes, radius, open = true, className, emoteClassName, onPlayed, onRejected, renderEmote, }) {
+    const ctx = useGameContext();
+    if (!open)
+        return null;
+    return (_jsx("div", { className: className, role: "menu", "data-emote-wheel": true, "data-emote-count": emotes.length, children: emotes.map((emoteId, index) => (_jsx("button", { type: "button", role: "menuitem", className: emoteClassName, "data-emote": emoteId, "data-emote-index": index, onClick: () => {
+                const result = ctx.game.social.emotes.play(ctx.player.userId, emoteId, radius);
+                if ("reason" in result)
+                    onRejected?.(result.reason);
+                else
+                    onPlayed?.(emoteId);
+            }, children: renderEmote !== undefined ? renderEmote(emoteId) : emoteId }, emoteId))) }));
+}

package/dist/voice.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from "react";
+import { type PushToTalkMode, type PushToTalkStatus, type VoiceParticipant, type VoiceRoute, type VoiceTransport } from "@jgengine/core/multiplayer/voiceContract";
+export interface UseVoiceOptions {
+    transport?: VoiceTransport;
+    channelId?: string;
+    mode?: PushToTalkMode;
+    resolveRoutes?: () => readonly VoiceRoute[];
+    getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+}
+export interface VoiceState {
+    supported: boolean;
+    micStream: MediaStream | null;
+    micError: string | null;
+    requestMic(): Promise<boolean>;
+    transmitting: boolean;
+    status: PushToTalkStatus;
+    mode: PushToTalkMode;
+    setMode(mode: PushToTalkMode): void;
+    muted: boolean;
+    setMuted(muted: boolean): void;
+    keyDown(): void;
+    keyUp(): void;
+    participants: readonly VoiceParticipant[];
+    routes: readonly VoiceRoute[];
+    gainFor(userId: string): number;
+}
+/**
+ * Mic capture + push-to-talk + channel roster over the VoiceTransport
+ * signaling seam. Transmission gates the captured tracks' `enabled` flag; the
+ * media plane that actually moves audio bytes (WebRTC/SFU) stays behind the
+ * transport, host-supplied. Call once per voice channel and hand the returned
+ * state to the voice components.
+ */
+export declare function useVoice(options?: UseVoiceOptions): VoiceState;
+export declare function PushToTalkButton({ voice, className, children, }: {
+    voice: VoiceState;
+    className?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function MicToggle({ voice, className, mutedLabel, unmutedLabel, }: {
+    voice: VoiceState;
+    className?: string;
+    mutedLabel?: ReactNode;
+    unmutedLabel?: ReactNode;
+}): import("react").JSX.Element;
+export declare function SpeakingIndicator({ voice, userId, className, threshold, children, }: {
+    voice: VoiceState;
+    userId: string;
+    className?: string;
+    threshold?: number;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function VoiceRoster({ voice, className, participantClassName, renderParticipant, }: {
+    voice: VoiceState;
+    className?: string;
+    participantClassName?: string;
+    renderParticipant?: (participant: VoiceParticipant, gain: number) => ReactNode;
+}): import("react").JSX.Element;

package/dist/voice.js

@@ -0,0 +1,130 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createPushToTalk, } from "@jgengine/core/multiplayer/voiceContract";
+/**
+ * Mic capture + push-to-talk + channel roster over the VoiceTransport
+ * signaling seam. Transmission gates the captured tracks' `enabled` flag; the
+ * media plane that actually moves audio bytes (WebRTC/SFU) stays behind the
+ * transport, host-supplied. Call once per voice channel and hand the returned
+ * state to the voice components.
+ */
+export function useVoice(options) {
+    const transport = options?.transport;
+    const channelId = options?.channelId ?? "voice";
+    const resolveRoutes = options?.resolveRoutes;
+    const requestedMode = options?.mode ?? "hold";
+    const [transmitting, setTransmitting] = useState(false);
+    const [version, setVersion] = useState(0);
+    const bump = useCallback(() => setVersion((current) => current + 1), []);
+    void version;
+    const pttRef = useRef(null);
+    if (pttRef.current === null) {
+        pttRef.current = createPushToTalk({ mode: requestedMode, onChange: setTransmitting });
+    }
+    const ptt = pttRef.current;
+    const [micStream, setMicStream] = useState(null);
+    const [micError, setMicError] = useState(null);
+    const micRef = useRef(null);
+    const getUserMedia = options?.getUserMedia ??
+        (typeof navigator !== "undefined" && navigator.mediaDevices !== undefined
+            ? (constraints) => navigator.mediaDevices.getUserMedia(constraints)
+            : undefined);
+    const supported = getUserMedia !== undefined;
+    const requestMic = useCallback(async () => {
+        if (getUserMedia === undefined) {
+            setMicError("microphone capture not supported");
+            return false;
+        }
+        try {
+            const stream = await getUserMedia({ audio: true });
+            micRef.current = stream;
+            setMicStream(stream);
+            setMicError(null);
+            void transport?.publish(channelId, stream.id);
+            return true;
+        }
+        catch (error) {
+            setMicError(error instanceof Error ? error.message : "microphone permission denied");
+            return false;
+        }
+    }, [getUserMedia, transport, channelId]);
+    useEffect(() => {
+        const stream = micRef.current;
+        if (stream === null)
+            return;
+        for (const track of stream.getAudioTracks())
+            track.enabled = transmitting;
+    }, [transmitting, micStream]);
+    useEffect(() => {
+        return () => {
+            const stream = micRef.current;
+            if (stream !== null)
+                for (const track of stream.getTracks())
+                    track.stop();
+        };
+    }, []);
+    const [participants, setParticipants] = useState([]);
+    useEffect(() => {
+        if (transport === undefined)
+            return undefined;
+        void transport.join(channelId, micRef.current?.id);
+        const unsubscribe = transport.subscribers(channelId, setParticipants);
+        return () => {
+            unsubscribe();
+            void transport.leave(channelId);
+        };
+    }, [transport, channelId]);
+    const routes = resolveRoutes?.() ?? [];
+    return useMemo(() => ({
+        supported,
+        micStream,
+        micError,
+        requestMic,
+        transmitting,
+        status: ptt.status(),
+        mode: ptt.mode(),
+        setMode(mode) {
+            ptt.setMode(mode);
+            bump();
+        },
+        muted: ptt.muted(),
+        setMuted(muted) {
+            ptt.setMuted(muted);
+            bump();
+        },
+        keyDown() {
+            ptt.keyDown();
+            bump();
+        },
+        keyUp() {
+            ptt.keyUp();
+            bump();
+        },
+        participants,
+        routes,
+        gainFor(userId) {
+            let gain = 0;
+            for (const route of routes) {
+                if (route.fromUserId === userId && route.gain > gain)
+                    gain = route.gain;
+            }
+            return gain;
+        },
+    }), [supported, micStream, micError, requestMic, transmitting, participants, routes, ptt, bump]);
+}
+export function PushToTalkButton({ voice, className, children, }) {
+    return (_jsx("button", { type: "button", className: className, "data-push-to-talk": true, "data-transmitting": voice.transmitting, "data-status": voice.status, onPointerDown: () => voice.keyDown(), onPointerUp: () => voice.keyUp(), onPointerLeave: () => voice.keyUp(), children: children ?? (voice.transmitting ? "Transmitting" : "Push to talk") }));
+}
+export function MicToggle({ voice, className, mutedLabel, unmutedLabel, }) {
+    return (_jsx("button", { type: "button", className: className, "data-mic-toggle": true, "data-muted": voice.muted, "aria-pressed": voice.muted, onClick: () => voice.setMuted(!voice.muted), children: voice.muted ? (mutedLabel ?? "Unmute") : (unmutedLabel ?? "Mute") }));
+}
+export function SpeakingIndicator({ voice, userId, className, threshold = 0.01, children, }) {
+    const gain = voice.gainFor(userId);
+    return (_jsx("span", { className: className, "data-speaking": gain > threshold, "data-gain": gain.toFixed(3), "data-user": userId, children: children }));
+}
+export function VoiceRoster({ voice, className, participantClassName, renderParticipant, }) {
+    return (_jsx("div", { className: className, "data-voice-roster": true, children: voice.participants.map((participant) => {
+            const gain = voice.gainFor(participant.userId);
+            return (_jsx("div", { className: participantClassName, "data-voice-participant": participant.userId, "data-published": participant.streamId !== undefined, "data-speaking": gain > 0.01, children: renderParticipant !== undefined ? renderParticipant(participant, gain) : participant.userId }, participant.userId));
+        }) }));
+}