@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/ui/modalStack.js

@@ -0,0 +1,160 @@
+/**
+ * Headless, serializable model for a stack of modal dialogs — the data layer behind a pause menu, a
+ * "quit to menu?" confirmation, a level-up popup, or any blocking overlay a game raises over its
+ * scene. It carries an ordered stack of opaque {@link ModalRecord}s (push to open, pop/resolve to
+ * close) and nothing about how they look: the model NEVER interprets a record's `kind` or a
+ * resolution's `result` string — those are free-form game vocabulary the React chrome in
+ * `@jgengine/react` renders. Observable ({@link ModalStack.subscribe}) and round-trips through a save
+ * ({@link ModalStack.snapshot}/{@link ModalStack.restore}). An injected clock powers optional
+ * per-modal auto-dismiss timers; leave those unset and the model is pure and clockless.
+ */
+/** Conventional confirm result for a two-button dialog — a shared string, not model behavior. */
+export const MODAL_CONFIRM = "confirm";
+/** Conventional cancel/dismiss result (also the default auto-dismiss and pop result). */
+export const MODAL_CANCEL = "cancel";
+/**
+ * A stack of modal dialogs: push opaque records to open blocking overlays (a pause menu, a confirm
+ * prompt, a reward popup), pop or resolve them with a free-form result to close, and query the top /
+ * open / depth to gate game input. The model is deliberately vocabulary-free — it never reads a
+ * record's `kind` or a resolution's `result`, so a game owns every dialog style — and fully
+ * serializable, with an optional injected clock driving per-modal auto-dismiss. A React host renders
+ * `top()`; `subscribe` re-renders it, `snapshot`/`restore` round-trip it through a save.
+ *
+ * @capability modal-stack serializable, observable stack of opaque modal/dialog records — push/pop/resolve blocking overlays (pause menu, confirm dialog) with optional auto-dismiss; never interprets kind or result
+ */
+export function createModalStack(options = {}) {
+    const now = options.now ?? Date.now;
+    const onOpen = options.onOpen;
+    const onResolve = options.onResolve;
+    const listeners = new Set();
+    let entries = [];
+    let seq = 0;
+    let last = null;
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function nextId() {
+        return `modal-${seq++}`;
+    }
+    function toRecord(input) {
+        const record = { id: input.id ?? nextId(), kind: input.kind };
+        if (input.payload !== undefined)
+            record.payload = input.payload;
+        if (input.timeoutMs !== undefined)
+            record.timeoutMs = input.timeoutMs;
+        if (input.timeoutResult !== undefined)
+            record.timeoutResult = input.timeoutResult;
+        return record;
+    }
+    /** @internal Remove the entry at `index` and produce+record its resolution. Does not notify. */
+    function resolveAt(index, result, payload, at = now()) {
+        const [entry] = entries.splice(index, 1);
+        const record = entry.record;
+        const resolution = {
+            id: record.id,
+            kind: record.kind,
+            result,
+            at,
+        };
+        const echo = payload !== undefined ? payload : record.payload;
+        if (echo !== undefined)
+            resolution.payload = echo;
+        last = resolution;
+        onResolve?.(resolution);
+        return resolution;
+    }
+    function push(input) {
+        const record = toRecord(input);
+        entries.push({ record, openedAt: now() });
+        onOpen?.(record);
+        notify();
+        return record;
+    }
+    for (const input of options.initial ?? [])
+        push(input);
+    return {
+        push,
+        pop() {
+            if (entries.length === 0)
+                return null;
+            const record = entries[entries.length - 1].record;
+            resolveAt(entries.length - 1, MODAL_CANCEL);
+            notify();
+            return record;
+        },
+        resolve(result, opts) {
+            const index = opts?.id !== undefined
+                ? entries.findIndex((entry) => entry.record.id === opts.id)
+                : entries.length - 1;
+            if (index < 0)
+                return null;
+            const resolution = resolveAt(index, result, opts?.payload);
+            notify();
+            return resolution;
+        },
+        top() {
+            return entries.length === 0 ? null : entries[entries.length - 1].record;
+        },
+        isOpen() {
+            return entries.length > 0;
+        },
+        has(id) {
+            return entries.some((entry) => entry.record.id === id);
+        },
+        depth() {
+            return entries.length;
+        },
+        stack() {
+            return entries.map((entry) => entry.record);
+        },
+        lastResolution() {
+            return last;
+        },
+        clear() {
+            if (entries.length === 0)
+                return;
+            while (entries.length > 0)
+                resolveAt(entries.length - 1, MODAL_CANCEL);
+            notify();
+        },
+        tick(nowOverride) {
+            const at = nowOverride ?? now();
+            const fired = [];
+            for (let i = entries.length - 1; i >= 0; i -= 1) {
+                const entry = entries[i];
+                const timeout = entry.record.timeoutMs;
+                if (timeout !== undefined && at - entry.openedAt >= timeout) {
+                    fired.push(resolveAt(i, entry.record.timeoutResult ?? MODAL_CANCEL, undefined, at));
+                }
+            }
+            if (fired.length > 0)
+                notify();
+            return fired;
+        },
+        timeRemaining(id) {
+            const entry = id !== undefined
+                ? entries.find((e) => e.record.id === id)
+                : entries[entries.length - 1];
+            if (entry === undefined || entry.record.timeoutMs === undefined)
+                return null;
+            return Math.max(0, entry.openedAt + entry.record.timeoutMs - now());
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                entries: entries.map((entry) => ({ record: { ...entry.record }, openedAt: entry.openedAt })),
+                seq,
+            };
+        },
+        restore(snapshot) {
+            entries = snapshot.entries.map((entry) => ({ record: { ...entry.record }, openedAt: entry.openedAt }));
+            seq = snapshot.seq;
+            last = null;
+            notify();
+        },
+    };
+}

package/dist/ui/objectiveBanner.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Which part of its life a banner is in: flying `"in"`, holding centered, or
+ * fading `"out"`. Progress `0..1` (see {@link ObjectiveBannerView.progress})
+ * runs within whichever phase is active — the renderer maps phase + progress to
+ * opacity/scale/translate however it likes.
+ */
+export type ObjectiveBannerPhase = "in" | "hold" | "out";
+/** One announcement request handed to {@link ObjectiveBannerController.announce}. */
+export interface ObjectiveBannerAnnouncement {
+    /** The big centered headline (e.g. `"WAVE 3"`, `"VICTORY"`). */
+    title: string;
+    /** Optional smaller line under the title (e.g. `"Defend the core"`). */
+    subtitle?: string;
+    /**
+     * Free-string label the game owns and styles ("wave", "victory", "defeat",
+     * "objective", …); the model never interprets it — it only carries it through
+     * to the renderer so a game can color/skin per kind. Default `"default"`.
+     */
+    kind?: string;
+    /** Fly-in duration in ms. Default `350`. */
+    inMs?: number;
+    /** Centered hold duration in ms. Default `2000`. */
+    holdMs?: number;
+    /** Fade-out duration in ms. Default `500`. */
+    outMs?: number;
+}
+/**
+ * The banner to draw right now: its content, the game-owned `kind`, the current
+ * {@link ObjectiveBannerPhase}, and `progress` `0..1` through that phase. This
+ * object is pooled and overwritten on the next {@link ObjectiveBannerController.current}
+ * call — read it, don't retain it.
+ */
+export interface ObjectiveBannerView {
+    /** Stable id assigned at announce time. */
+    id: number;
+    /** The headline. */
+    title: string;
+    /** The optional subtitle, or `undefined`. */
+    subtitle: string | undefined;
+    /** The game-owned free-string label. */
+    kind: string;
+    /** Which phase the banner is in. */
+    phase: ObjectiveBannerPhase;
+    /** Progress `0..1` within the current phase. */
+    progress: number;
+}
+/** A persisted banner record — all announcement fields resolved, plus id and schedule. */
+export interface StoredObjectiveBanner {
+    id: number;
+    title: string;
+    subtitle: string | undefined;
+    kind: string;
+    inMs: number;
+    holdMs: number;
+    outMs: number;
+    /** Clock time (ms) this banner started its fly-in, or `null` while still queued. */
+    startAt: number | null;
+}
+/** Serializable state of the queue and the active banner, for save/restore. */
+export interface ObjectiveBannerSnapshot {
+    /** Wall-clock (ms) the snapshot was taken, so restore re-anchors elapsed time. */
+    now: number;
+    /** Next id to hand out. */
+    nextId: number;
+    /** The active banner (head) followed by everything still queued, in order. */
+    queue: readonly StoredObjectiveBanner[];
+}
+/** A live, clock-driven objective/stage banner controller. */
+export interface ObjectiveBannerController {
+    /**
+     * Enqueue a banner. If nothing is showing it starts flying in immediately;
+     * otherwise it waits its turn (one banner shows at a time). Returns the new id.
+     */
+    announce(announcement: ObjectiveBannerAnnouncement): number;
+    /**
+     * Advance the clock: transition the active banner through in → hold → out,
+     * reap it when its life ends, and start the next queued banner. Pass an explicit
+     * `nowMs` to drive deterministically, else the injected clock is read. Notifies
+     * subscribers. Call it each frame from the renderer.
+     */
+    advance(nowMs?: number): void;
+    /** The banner to draw right now (pooled — do not retain), or `null` when idle. */
+    current(): ObjectiveBannerView | null;
+    /** Dismiss the active banner immediately and start the next queued one, if any. */
+    skip(): void;
+    /** Drop the active banner and everything queued. */
+    clear(): void;
+    /** How many banners are waiting behind the active one. */
+    pending(): number;
+    /** Whether a banner is currently active. */
+    isActive(): boolean;
+    /** Observe changes (announce, advance, skip, clear, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): ObjectiveBannerSnapshot;
+    /** Restore from an {@link ObjectiveBannerSnapshot}. */
+    restore(snapshot: ObjectiveBannerSnapshot): void;
+}
+/** Options for {@link createObjectiveBanner}. */
+export interface ObjectiveBannerOptions {
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Default fly-in ms for announcements that omit `inMs`. Default `350`. */
+    inMs?: number;
+    /** Default hold ms for announcements that omit `holdMs`. Default `2000`. */
+    holdMs?: number;
+    /** Default fade-out ms for announcements that omit `outMs`. Default `500`. */
+    outMs?: number;
+}
+/**
+ * A serializable, clock-driven stage/objective banner controller: the classic
+ * transient centered title stamp ("WAVE 3", "VICTORY", "OBJECTIVE COMPLETE"). A
+ * game calls `announce({ title, subtitle?, kind? })` and the controller queues it,
+ * flies it in, holds it, and fades it out on an injected clock — one banner at a
+ * time — exposing the current banner plus its phase (in/hold/out) and `progress`
+ * `0..1` for a renderer to animate opacity/scale/translate. Nothing here is
+ * genre-specific: `kind` is a free label the game owns and styles, and all timings
+ * are parameters. Call `advance()` each frame; `current()` returns the pooled view
+ * to draw; `snapshot`/`restore` round-trips the queue through a save.
+ *
+ * @capability objective-banner serializable, clock-driven stage/objective banner queue — flies a big transient centered title + optional subtitle in, holds, and fades out one at a time, with phase + progress for animation, free-string kinds the game styles, and snapshot/restore
+ */
+export declare function createObjectiveBanner(options?: ObjectiveBannerOptions): ObjectiveBannerController;

package/dist/ui/objectiveBanner.js

@@ -0,0 +1,162 @@
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * A serializable, clock-driven stage/objective banner controller: the classic
+ * transient centered title stamp ("WAVE 3", "VICTORY", "OBJECTIVE COMPLETE"). A
+ * game calls `announce({ title, subtitle?, kind? })` and the controller queues it,
+ * flies it in, holds it, and fades it out on an injected clock — one banner at a
+ * time — exposing the current banner plus its phase (in/hold/out) and `progress`
+ * `0..1` for a renderer to animate opacity/scale/translate. Nothing here is
+ * genre-specific: `kind` is a free label the game owns and styles, and all timings
+ * are parameters. Call `advance()` each frame; `current()` returns the pooled view
+ * to draw; `snapshot`/`restore` round-trips the queue through a save.
+ *
+ * @capability objective-banner serializable, clock-driven stage/objective banner queue — flies a big transient centered title + optional subtitle in, holds, and fades out one at a time, with phase + progress for animation, free-string kinds the game styles, and snapshot/restore
+ */
+export function createObjectiveBanner(options = {}) {
+    const now = options.now ?? Date.now;
+    const defaultIn = Math.max(0, options.inMs ?? 350);
+    const defaultHold = Math.max(0, options.holdMs ?? 2000);
+    const defaultOut = Math.max(0, options.outMs ?? 500);
+    // queue[0] is the active banner; the rest wait their turn.
+    const queue = [];
+    const listeners = new Set();
+    // Pooled view — reused across current() calls, never per-frame allocated.
+    const view = { id: 0, title: "", subtitle: undefined, kind: "", phase: "in", progress: 0 };
+    let nextId = 1;
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Total lifetime of a banner in ms. */
+    function totalMs(banner) {
+        return banner.inMs + banner.holdMs + banner.outMs;
+    }
+    /**
+     * Activate/chain the head, reap any that have fully expired at `t`, and cache
+     * the active banner's phase + progress. Deterministic regardless of how often
+     * it is called: a finished banner hands its scheduled end time to the next.
+     */
+    function recompute(t) {
+        while (queue.length > 0) {
+            const head = queue[0];
+            if (head.startAt === null)
+                head.startAt = t;
+            const total = totalMs(head);
+            const elapsed = t - head.startAt;
+            if (total <= 0 || elapsed >= total) {
+                queue.shift();
+                const next = queue[0];
+                if (next !== undefined && next.startAt === null)
+                    next.startAt = head.startAt + total;
+                continue;
+            }
+            if (elapsed < head.inMs) {
+                head.phase = "in";
+                head.progress = head.inMs > 0 ? clamp01(elapsed / head.inMs) : 1;
+            }
+            else if (elapsed < head.inMs + head.holdMs) {
+                head.phase = "hold";
+                head.progress = head.holdMs > 0 ? clamp01((elapsed - head.inMs) / head.holdMs) : 1;
+            }
+            else {
+                head.phase = "out";
+                head.progress = head.outMs > 0 ? clamp01((elapsed - head.inMs - head.holdMs) / head.outMs) : 1;
+            }
+            return;
+        }
+    }
+    return {
+        announce(announcement) {
+            const id = nextId++;
+            queue.push({
+                id,
+                title: announcement.title,
+                subtitle: announcement.subtitle,
+                kind: announcement.kind ?? "default",
+                inMs: Math.max(0, announcement.inMs ?? defaultIn),
+                holdMs: Math.max(0, announcement.holdMs ?? defaultHold),
+                outMs: Math.max(0, announcement.outMs ?? defaultOut),
+                startAt: null,
+                phase: "in",
+                progress: 0,
+            });
+            recompute(now());
+            notify();
+            return id;
+        },
+        advance(nowMs) {
+            recompute(nowMs ?? now());
+            notify();
+        },
+        current() {
+            const head = queue[0];
+            if (head === undefined || head.startAt === null)
+                return null;
+            view.id = head.id;
+            view.title = head.title;
+            view.subtitle = head.subtitle;
+            view.kind = head.kind;
+            view.phase = head.phase;
+            view.progress = head.progress;
+            return view;
+        },
+        skip() {
+            if (queue.length === 0)
+                return;
+            queue.shift();
+            recompute(now());
+            notify();
+        },
+        clear() {
+            if (queue.length === 0)
+                return;
+            queue.length = 0;
+            notify();
+        },
+        pending() {
+            return queue.length === 0 ? 0 : queue.length - 1;
+        },
+        isActive() {
+            const head = queue[0];
+            return head !== undefined && head.startAt !== null;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                now: now(),
+                nextId,
+                queue: queue.map((banner) => ({
+                    id: banner.id,
+                    title: banner.title,
+                    subtitle: banner.subtitle,
+                    kind: banner.kind,
+                    inMs: banner.inMs,
+                    holdMs: banner.holdMs,
+                    outMs: banner.outMs,
+                    startAt: banner.startAt,
+                })),
+            };
+        },
+        restore(snapshot) {
+            queue.length = 0;
+            nextId = snapshot.nextId;
+            const t = now();
+            const drift = t - snapshot.now;
+            for (const stored of snapshot.queue) {
+                queue.push({
+                    ...stored,
+                    startAt: stored.startAt === null ? null : stored.startAt + drift,
+                    phase: "in",
+                    progress: 0,
+                });
+            }
+            recompute(t);
+            notify();
+        },
+    };
+}

package/dist/ui/photoMode.d.ts

@@ -0,0 +1,32 @@
+/** Serializable photo-mode preferences a game reads to compose its capture UI. */
+export interface PhotoModeState {
+    /** Photo mode is engaged (game frees the camera / pauses as it sees fit). */
+    active: boolean;
+    /** Hide the gameplay HUD for a clean shot. */
+    hideHud: boolean;
+}
+/** The out-of-the-box photo-mode state: not active, HUD hidden when it engages. */
+export declare const DEFAULT_PHOTO_MODE: PhotoModeState;
+/** Observable photo-mode store — genre-agnostic state a game binds its capture flow to. */
+export interface PhotoModeStore {
+    get(): PhotoModeState;
+    /** Engage photo mode. */
+    enter(): void;
+    /** Leave photo mode. */
+    exit(): void;
+    toggle(): void;
+    setHideHud(hide: boolean): void;
+    set(patch: Partial<PhotoModeState>): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): PhotoModeState;
+    restore(snapshot: Partial<PhotoModeState>): void;
+}
+/**
+ * Serializable, observable photo-mode state (active + hide-HUD). Genre-agnostic
+ * plumbing — a game engages it to free its camera and hide gameplay chrome for a
+ * clean capture, and reads `hideHud` to conditionally render its HUD. Pair with
+ * React `PhotoModeControls` and shell `captureCanvas`.
+ *
+ * @capability photo-mode observable photo-mode state (active + hide-HUD) a game binds its screenshot/camera flow to
+ */
+export declare function createPhotoModeStore(initial?: Partial<PhotoModeState>): PhotoModeStore;

package/dist/ui/photoMode.js

@@ -0,0 +1,51 @@
+/** The out-of-the-box photo-mode state: not active, HUD hidden when it engages. */
+export const DEFAULT_PHOTO_MODE = { active: false, hideHud: true };
+/**
+ * Serializable, observable photo-mode state (active + hide-HUD). Genre-agnostic
+ * plumbing — a game engages it to free its camera and hide gameplay chrome for a
+ * clean capture, and reads `hideHud` to conditionally render its HUD. Pair with
+ * React `PhotoModeControls` and shell `captureCanvas`.
+ *
+ * @capability photo-mode observable photo-mode state (active + hide-HUD) a game binds its screenshot/camera flow to
+ */
+export function createPhotoModeStore(initial = {}) {
+    let state = { ...DEFAULT_PHOTO_MODE, ...initial };
+    const listeners = new Set();
+    function commit(next) {
+        if (next.active === state.active && next.hideHud === state.hideHud)
+            return;
+        state = next;
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        get() {
+            return state;
+        },
+        enter() {
+            commit({ ...state, active: true });
+        },
+        exit() {
+            commit({ ...state, active: false });
+        },
+        toggle() {
+            commit({ ...state, active: !state.active });
+        },
+        setHideHud(hide) {
+            commit({ ...state, hideHud: hide });
+        },
+        set(patch) {
+            commit({ ...state, ...patch });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return state;
+        },
+        restore(snapshot) {
+            commit({ ...DEFAULT_PHOTO_MODE, ...snapshot });
+        },
+    };
+}

package/dist/ui/radialMenu.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Arc the slices span. Omit for a full wheel (index 0 at the top). A partial
+ * `sweep` (e.g. `Math.PI` for a bottom half, `Math.PI / 2` for a quarter) packs
+ * the slices evenly inside `[startAngle, startAngle + sweep]` — the arc/quick-bar
+ * forms. Angles are radians from "up" (−Y), clockwise.
+ */
+export interface RadialArc {
+    startAngle?: number;
+    sweep?: number;
+}
+/** One wedge of a radial menu — geometry for rendering a slice. Angles are radians from "up" (−Y), clockwise. */
+export interface RadialSlice {
+    index: number;
+    /** Angle at the slice's center. */
+    centerAngle: number;
+    /** Leading edge angle. */
+    startAngle: number;
+    /** Trailing edge angle. */
+    endAngle: number;
+}
+/**
+ * Divide a ring (or `arc`) into `count` wedges — the geometry a radial/quick
+ * menu (weapon wheel, emote arc, ping bar) renders. A full wheel centers index 0
+ * at the top; a partial `arc` packs the slices inside its sweep.
+ */
+export declare function radialSlices(count: number, arc?: RadialArc): RadialSlice[];
+/** Map an angle to a slice index; returns -1 when the angle falls outside a partial `arc`. */
+export declare function radialIndexFromAngle(angle: number, count: number, arc?: RadialArc): number;
+/** Options for {@link radialIndexFromVector}. */
+export interface RadialVectorOptions extends RadialArc {
+    /** Minimum vector magnitude to register a selection; shorter vectors return null (the neutral center). Default 0. */
+    deadZone?: number;
+}
+/**
+ * Pick the slice a pointer/stick vector points at. `dx`/`dy` are screen-space
+ * (y down): up is `(0, -1)`. Returns null inside `deadZone` or (for a partial
+ * `arc`) outside the arc, so a centered stick or a click off the arc selects
+ * nothing.
+ *
+ * @capability radial-select map a pointer/stick vector to a radial-menu slice index, with a neutral dead zone and optional arc bounds
+ */
+export declare function radialIndexFromVector(dx: number, dy: number, count: number, options?: RadialVectorOptions): number | null;
+/** Unit-circle position of a slice center (up = `(0, -1)`), scaled by `radius` — where to place a wedge's icon/label. */
+export declare function radialSlicePosition(index: number, count: number, radius: number, arc?: RadialArc): {
+    x: number;
+    y: number;
+};

package/dist/ui/radialMenu.js

@@ -0,0 +1,74 @@
+const TWO_PI = Math.PI * 2;
+function normalize(angle) {
+    let value = angle % TWO_PI;
+    if (value < 0)
+        value += TWO_PI;
+    return value;
+}
+function arcConfig(count, arc) {
+    const startAngle = arc?.startAngle ?? 0;
+    const sweep = arc?.sweep ?? TWO_PI;
+    const full = sweep >= TWO_PI - 1e-6;
+    const size = full ? (count > 0 ? TWO_PI / count : 0) : (count > 0 ? sweep / count : 0);
+    // Full wheels wrap, so a slice sits exactly on the start angle (index 0 = top).
+    // Partial arcs offset by half a slice so wedges fit inside the arc.
+    const centerOf = (index) => startAngle + (full ? index : index + 0.5) * size;
+    return { startAngle, sweep, full, size, centerOf };
+}
+/**
+ * Divide a ring (or `arc`) into `count` wedges — the geometry a radial/quick
+ * menu (weapon wheel, emote arc, ping bar) renders. A full wheel centers index 0
+ * at the top; a partial `arc` packs the slices inside its sweep.
+ */
+export function radialSlices(count, arc) {
+    if (count <= 0)
+        return [];
+    const { size, centerOf } = arcConfig(count, arc);
+    const slices = [];
+    for (let index = 0; index < count; index += 1) {
+        const centerAngle = centerOf(index);
+        slices.push({
+            index,
+            centerAngle: normalize(centerAngle),
+            startAngle: normalize(centerAngle - size / 2),
+            endAngle: normalize(centerAngle + size / 2),
+        });
+    }
+    return slices;
+}
+/** Map an angle to a slice index; returns -1 when the angle falls outside a partial `arc`. */
+export function radialIndexFromAngle(angle, count, arc) {
+    if (count <= 0)
+        return -1;
+    const { full, size, startAngle, sweep } = arcConfig(count, arc);
+    if (full)
+        return Math.round(normalize(angle - startAngle) / size) % count;
+    const rel = normalize(angle - startAngle);
+    if (rel > sweep)
+        return -1;
+    return Math.max(0, Math.min(count - 1, Math.floor(rel / size)));
+}
+/**
+ * Pick the slice a pointer/stick vector points at. `dx`/`dy` are screen-space
+ * (y down): up is `(0, -1)`. Returns null inside `deadZone` or (for a partial
+ * `arc`) outside the arc, so a centered stick or a click off the arc selects
+ * nothing.
+ *
+ * @capability radial-select map a pointer/stick vector to a radial-menu slice index, with a neutral dead zone and optional arc bounds
+ */
+export function radialIndexFromVector(dx, dy, count, options = {}) {
+    if (count <= 0)
+        return null;
+    const magnitude = Math.hypot(dx, dy);
+    if (magnitude < (options.deadZone ?? 0))
+        return null;
+    // atan2(dx, -dy): 0 = up, increasing clockwise toward +x (right).
+    const index = radialIndexFromAngle(Math.atan2(dx, -dy), count, options);
+    return index < 0 ? null : index;
+}
+/** Unit-circle position of a slice center (up = `(0, -1)`), scaled by `radius` — where to place a wedge's icon/label. */
+export function radialSlicePosition(index, count, radius, arc) {
+    const { centerOf } = arcConfig(count, arc);
+    const angle = count <= 0 ? 0 : centerOf(index);
+    return { x: Math.sin(angle) * radius, y: -Math.cos(angle) * radius };
+}