@jgengine/react 0.14.0 → 0.15.0

package/dist/dialogueView.d.ts

@@ -0,0 +1,69 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { DialogueGraphChoice, DialogueGraphView, DialogueRun } from "@jgengine/core/game/dialogueGraph";
+/**
+ * Subscribe to a {@link DialogueRun} and re-render on every advance / jump / reset,
+ * returning the current node view (or `null` if the run's node id is unknown).
+ *
+ * @capability use-dialogue-run React hook binding a branching dialogue run to a component — re-renders as the player advances the conversation
+ */
+export declare function useDialogueRun(run: DialogueRun): DialogueGraphView | null;
+/** Reskin tokens for {@link DialogueView}. Each defaults to a HudTheme `--jg-*` token. */
+export interface DialogueViewTheme {
+    /** Panel background. Default reads `--jg-frame-bg`. */
+    background?: string;
+    /** Panel border. Default reads `--jg-frame-border`. */
+    border?: string;
+    /** Panel corner radius (any CSS length). Default reads `--jg-frame-radius`. */
+    radius?: string;
+    /** Panel outer glow / drop shadow. Default reads `--jg-frame-glow`. */
+    glow?: string;
+    /** Body/line text color. Default reads `--jg-bar-text`. */
+    text?: string;
+    /** Accent for the speaker name and choice hover/focus. Default reads `--jg-accent`. */
+    accent?: string;
+    /** Choice button background. Default reads `--jg-slot-bg`. */
+    choiceBackground?: string;
+    /** Choice button border. Default reads `--jg-slot-border`. */
+    choiceBorder?: string;
+    /** Choice button corner radius. Default reads `--jg-slot-radius`. */
+    choiceRadius?: string;
+}
+/** Props for {@link DialogueView}. */
+export interface DialogueViewProps {
+    /** The live branching-conversation run to render and advance. */
+    run: DialogueRun;
+    /**
+     * Render a portrait for the current node. Given the node's opaque `portrait` key/URL and
+     * its `speakerKind`; return `null` to omit the portrait slot. Omit the prop for no portrait.
+     */
+    renderPortrait?: (portrait: string | undefined, speakerKind: string | undefined) => ReactNode;
+    /** Called when the player picks the choice at `index` (after the run advances). */
+    onChoose?: (choice: DialogueGraphChoice, index: number) => void;
+    /**
+     * Called when the player advances a terminal node — a choice with no destination, or the
+     * Close control on a node with no choices. Wire this to `ctx.game.dialogue.close()`.
+     */
+    onClose?: () => void;
+    /** Label for the Close control shown on a terminal node with no choices. Default `"Close"`. */
+    closeLabel?: string;
+    theme?: DialogueViewTheme;
+    className?: string;
+    style?: CSSProperties;
+    speakerClassName?: string;
+    textClassName?: string;
+    choicesClassName?: string;
+    choiceClassName?: string;
+}
+/**
+ * A drop-in branching-conversation view over a {@link DialogueRun}: renders the current
+ * node's speaker name (+ an optional portrait slot), the line, and a list of clickable
+ * response choices that advance the conversation — the game passes its dialogue graph and
+ * gets working node traversal and choice state with no hand-rolled walk. A choice with a
+ * destination advances the run; a terminal choice (or the Close control on a choiceless
+ * node) fires `onClose`. Speaker/choice `kind` are free strings surfaced as `data-*`
+ * attributes for the game to style; the view never interprets them. HudTheme-skinned via
+ * `--jg-*` tokens; reskin further with {@link DialogueViewTheme}.
+ *
+ * @capability dialogue-view drop-in branching conversation UI — speaker + portrait slot, current line, clickable response choices that advance a DialogueRun
+ */
+export declare function DialogueView({ run, renderPortrait, onChoose, onClose, closeLabel, theme, className, style, speakerClassName, textClassName, choicesClassName, choiceClassName, }: DialogueViewProps): ReactNode;

package/dist/dialogueView.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer } from "react";
+/**
+ * Subscribe to a {@link DialogueRun} and re-render on every advance / jump / reset,
+ * returning the current node view (or `null` if the run's node id is unknown).
+ *
+ * @capability use-dialogue-run React hook binding a branching dialogue run to a component — re-renders as the player advances the conversation
+ */
+export function useDialogueRun(run) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => run.subscribe(bump), [run]);
+    return run.current();
+}
+function resolveTheme(theme) {
+    return {
+        background: theme?.background ?? "var(--jg-frame-bg, linear-gradient(180deg, rgba(20,24,32,0.92), rgba(10,12,16,0.94)))",
+        border: theme?.border ?? "var(--jg-frame-border, 1px solid rgba(255,255,255,0.12))",
+        radius: theme?.radius ?? "var(--jg-frame-radius, 12px)",
+        glow: theme?.glow ?? "var(--jg-frame-glow, 0 18px 48px rgba(0,0,0,0.5))",
+        text: theme?.text ?? "var(--jg-bar-text, #e5e9f0)",
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        choiceBackground: theme?.choiceBackground ?? "var(--jg-slot-bg, rgba(12,14,20,0.72))",
+        choiceBorder: theme?.choiceBorder ?? "var(--jg-slot-border, 1px solid rgba(148,163,184,0.28))",
+        choiceRadius: theme?.choiceRadius ?? "var(--jg-slot-radius, 8px)",
+    };
+}
+/**
+ * A drop-in branching-conversation view over a {@link DialogueRun}: renders the current
+ * node's speaker name (+ an optional portrait slot), the line, and a list of clickable
+ * response choices that advance the conversation — the game passes its dialogue graph and
+ * gets working node traversal and choice state with no hand-rolled walk. A choice with a
+ * destination advances the run; a terminal choice (or the Close control on a choiceless
+ * node) fires `onClose`. Speaker/choice `kind` are free strings surfaced as `data-*`
+ * attributes for the game to style; the view never interprets them. HudTheme-skinned via
+ * `--jg-*` tokens; reskin further with {@link DialogueViewTheme}.
+ *
+ * @capability dialogue-view drop-in branching conversation UI — speaker + portrait slot, current line, clickable response choices that advance a DialogueRun
+ */
+export function DialogueView({ run, renderPortrait, onChoose, onClose, closeLabel = "Close", theme, className, style, speakerClassName, textClassName, choicesClassName, choiceClassName, }) {
+    const view = useDialogueRun(run);
+    const t = resolveTheme(theme);
+    if (view === null)
+        return null;
+    const portrait = renderPortrait?.(view.portrait, view.speakerKind) ?? null;
+    const handleChoose = (choice, index) => {
+        const terminal = choice.to === undefined || choice.to === null;
+        run.choose(index);
+        onChoose?.(choice, index);
+        if (terminal)
+            onClose?.();
+    };
+    return (_jsxs("div", { className: className, "data-dialogue-node": view.nodeId, "data-speaker-kind": view.speakerKind, style: {
+            boxSizing: "border-box",
+            maxWidth: 560,
+            width: "100%",
+            padding: 18,
+            background: t.background,
+            border: t.border,
+            borderRadius: t.radius,
+            boxShadow: t.glow,
+            color: t.text,
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            display: "flex",
+            gap: 16,
+            alignItems: "flex-start",
+            pointerEvents: "auto",
+            ...style,
+        }, children: [portrait !== null ? (_jsx("div", { "data-dialogue-portrait": true, style: {
+                    flex: "0 0 auto",
+                    width: 72,
+                    height: 72,
+                    borderRadius: 10,
+                    overflow: "hidden",
+                    border: t.choiceBorder,
+                    display: "grid",
+                    placeItems: "center",
+                    background: t.choiceBackground,
+                }, children: portrait })) : null, _jsxs("div", { style: { flex: "1 1 auto", minWidth: 0 }, children: [view.speaker !== undefined ? (_jsx("div", { className: speakerClassName, "data-dialogue-speaker": true, style: {
+                            fontSize: 12,
+                            fontWeight: 800,
+                            letterSpacing: 0.6,
+                            textTransform: "uppercase",
+                            color: t.accent,
+                        }, children: view.speaker })) : null, _jsx("p", { className: textClassName, "data-dialogue-text": true, style: { margin: view.speaker !== undefined ? "6px 0 0" : 0, fontSize: 15, lineHeight: 1.55 }, children: view.text }), _jsx("div", { className: choicesClassName, "data-dialogue-choices": true, style: { marginTop: 14, display: "flex", flexDirection: "column", gap: 8 }, children: view.choices.length > 0
+                            ? view.choices.map((choice, index) => (_jsx("button", { type: "button", className: choiceClassName, "data-dialogue-choice": index, "data-choice-kind": choice.kind, onClick: () => handleChoose(choice, index), style: {
+                                    appearance: "none",
+                                    textAlign: "left",
+                                    cursor: "pointer",
+                                    padding: "9px 13px",
+                                    fontSize: 13.5,
+                                    fontWeight: 600,
+                                    color: t.text,
+                                    background: t.choiceBackground,
+                                    border: t.choiceBorder,
+                                    borderRadius: t.choiceRadius,
+                                }, children: choice.text }, index)))
+                            : onClose !== undefined
+                                ? (_jsx("button", { type: "button", className: choiceClassName, "data-dialogue-close": true, onClick: onClose, style: {
+                                        appearance: "none",
+                                        alignSelf: "flex-start",
+                                        cursor: "pointer",
+                                        padding: "9px 16px",
+                                        fontSize: 13.5,
+                                        fontWeight: 700,
+                                        color: "#06121b",
+                                        background: t.accent,
+                                        border: "1px solid transparent",
+                                        borderRadius: t.choiceRadius,
+                                    }, children: closeLabel }))
+                                : null })] })] }));
+}

package/dist/entityFrames.d.ts

@@ -0,0 +1,114 @@
+import { type CSSProperties, type ReactNode } from "react";
+/**
+ * World-anchored entity frames — a data-first seam for floating overhead UI
+ * (enemy nameplates + health bars, interaction prompts, objective pips) that
+ * tracks entities in the 3D world. The game keeps owning its entities: it passes
+ * a plain array of `{ id, worldPosition }` entries and a `project` function that
+ * turns a world position into a screen point, and composes each frame's markup
+ * itself (typically the shipped {@link ./bars!HealthBar} plus a name) reskinned
+ * through `HudTheme`/`barTokens`. This primitive owns only the reusable behavior:
+ * projecting, offsetting, culling entries that are off-screen or behind the
+ * camera, and stacking nearer entities above farther ones.
+ *
+ * No `GameProvider`, entity store, Three.js, or React Three Fiber is required or
+ * imported here — the same way {@link ./map!Minimap} takes display markers. An
+ * R3F game can get `project` for free from `useWorldProjection`/`WorldEntityFrames`
+ * in `@jgengine/shell/world/WorldEntityFrames`, which samples the live camera and
+ * composes this component.
+ *
+ * @capability entity-frames world-anchored overhead entity frames (nameplate/healthbar), data-first + caller-composed
+ */
+/** A world position projected to screen space by the caller's camera. */
+export interface EntityScreenProjection {
+    /** CSS px from the viewport's left edge. */
+    x: number;
+    /** CSS px from the viewport's top edge. */
+    y: number;
+    /**
+     * Stacking / draw-order key — larger means farther from the camera, so nearer
+     * frames paint on top. Optional; defaults to 0 when the projection omits it.
+     */
+    depth?: number;
+    /** `true` when the point is behind the camera; such entries are culled. */
+    behind?: boolean;
+}
+/**
+ * Projects a world position to a screen point, or returns `null` to cull the
+ * entry entirely (e.g. outside the frustum). Caller-owned so this seam never
+ * depends on a specific camera or renderer.
+ */
+export type ProjectEntity = (worldPosition: readonly [number, number, number]) => EntityScreenProjection | null;
+/** The minimum an entry must carry; games extend it with their own display data. */
+export interface EntityFrameEntry {
+    /** Stable key across frames — used for React keys and deterministic stacking. */
+    id: string;
+    /** World-space anchor, typically the entity's head (`[x, y + height, z]`). */
+    worldPosition: readonly [number, number, number];
+}
+/** One entry resolved to a screen placement, ready to render. */
+export interface EntityFramePlacement<E extends EntityFrameEntry> {
+    entry: E;
+    /** Final screen x after `offsetX`. */
+    x: number;
+    /** Final screen y after `offsetY`. */
+    y: number;
+    /** Resolved depth (0 when the projection omitted one). */
+    depth: number;
+}
+/** Anchoring, culling, and stacking options shared by the layout core and component. */
+export interface EntityFrameLayoutOptions {
+    /** Screen px added to every projected x. Default 0. */
+    offsetX?: number;
+    /** Screen px added to every projected y — negative lifts frames above the anchor. Default 0. */
+    offsetY?: number;
+    /**
+     * Viewport size used to cull frames that project past the edges. Omit to keep
+     * every in-front entry (the caller's `project` may already frustum-cull).
+     */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Extra px beyond each viewport edge still treated as on-screen. Default 64. */
+    margin?: number;
+    /** Cap the number of rendered frames, keeping the nearest. Omit for no cap. */
+    maxCount?: number;
+}
+/**
+ * Pure layout core: projects each entry, drops the ones behind the camera,
+ * off-screen (when `viewport` is set), or beyond `maxCount`, and returns the
+ * survivors sorted farthest-first so nearer frames render last (on top). Stable
+ * for equal depths via `id`. No React, no DOM — unit-testable in isolation.
+ */
+export declare function layoutEntityFrames<E extends EntityFrameEntry>(entries: readonly E[], project: ProjectEntity, options?: EntityFrameLayoutOptions): EntityFramePlacement<E>[];
+/** Props for {@link EntityFrames}. */
+export interface EntityFramesProps<E extends EntityFrameEntry> extends EntityFrameLayoutOptions {
+    /** Caller-owned entities to anchor. Only `id` + `worldPosition` are read here. */
+    entries: readonly E[];
+    /** World→screen projector; return `null` to cull. */
+    project: ProjectEntity;
+    /**
+     * Renders one entity's frame — compose the shipped bars (`HealthBar value/max`)
+     * and a name here, reskinned via `barTokens`/`HudTheme`. The wrapper handles
+     * positioning; render your content anchored at bottom-center of the point.
+     */
+    renderFrame: (entry: E, placement: EntityFramePlacement<E>) => ReactNode;
+    /** Class on the fullscreen overlay layer. */
+    className?: string;
+    /** Style on the fullscreen overlay layer (merged over the absolute-fill default). */
+    style?: CSSProperties;
+    /**
+     * CSS transform on each frame wrapper, controlling how content sits relative
+     * to the anchor point. Default `translate(-50%, -100%)` (centered, above).
+     */
+    anchorTransform?: string;
+}
+/**
+ * Absolutely-positioned overlay that renders a caller-composed frame over every
+ * on-screen entry. Drop it inside `HudCanvas` (or any positioned ancestor) and
+ * feed it fresh `entries`/`project` each frame. Every part carries `data-*`
+ * hooks (`data-entity-frames`, `data-entity-frame="<id>"`) for tests and skins.
+ *
+ * @capability entity-frames overlay that renders caller-composed frames over on-screen entities
+ */
+export declare function EntityFrames<E extends EntityFrameEntry>({ entries, project, renderFrame, className, style, anchorTransform, ...layout }: EntityFramesProps<E>): import("react").JSX.Element;

package/dist/entityFrames.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+/**
+ * Pure layout core: projects each entry, drops the ones behind the camera,
+ * off-screen (when `viewport` is set), or beyond `maxCount`, and returns the
+ * survivors sorted farthest-first so nearer frames render last (on top). Stable
+ * for equal depths via `id`. No React, no DOM — unit-testable in isolation.
+ */
+export function layoutEntityFrames(entries, project, options = {}) {
+    const { offsetX = 0, offsetY = 0, viewport, margin = 64, maxCount } = options;
+    const placed = [];
+    for (const entry of entries) {
+        const projection = project(entry.worldPosition);
+        if (projection === null || projection.behind === true)
+            continue;
+        const x = projection.x + offsetX;
+        const y = projection.y + offsetY;
+        if (viewport !== undefined) {
+            if (x < -margin ||
+                x > viewport.width + margin ||
+                y < -margin ||
+                y > viewport.height + margin) {
+                continue;
+            }
+        }
+        placed.push({ entry, x, y, depth: projection.depth ?? 0 });
+    }
+    // Farthest first; ties resolved by id so the DOM/stacking order is deterministic.
+    placed.sort((a, b) => (b.depth - a.depth) || (a.entry.id < b.entry.id ? -1 : a.entry.id > b.entry.id ? 1 : 0));
+    if (maxCount !== undefined && placed.length > maxCount) {
+        // Keep the nearest `maxCount` (the tail of a farthest-first list).
+        return placed.slice(placed.length - maxCount);
+    }
+    return placed;
+}
+/**
+ * Absolutely-positioned overlay that renders a caller-composed frame over every
+ * on-screen entry. Drop it inside `HudCanvas` (or any positioned ancestor) and
+ * feed it fresh `entries`/`project` each frame. Every part carries `data-*`
+ * hooks (`data-entity-frames`, `data-entity-frame="<id>"`) for tests and skins.
+ *
+ * @capability entity-frames overlay that renders caller-composed frames over on-screen entities
+ */
+export function EntityFrames({ entries, project, renderFrame, className, style, anchorTransform = "translate(-50%, -100%)", ...layout }) {
+    const placements = layoutEntityFrames(entries, project, layout);
+    return (_jsx("div", { className: className, "data-entity-frames": "", style: { position: "absolute", inset: 0, pointerEvents: "none", ...style }, children: placements.map((placement, index) => (_jsx("div", { "data-entity-frame": placement.entry.id, style: {
+                position: "absolute",
+                left: placement.x,
+                top: placement.y,
+                transform: anchorTransform,
+                // Nearer frames come last in a farthest-first list; index gives them
+                // a higher z so overlapping plates stack front-over-back.
+                zIndex: index,
+            }, children: renderFrame(placement.entry, placement) }, placement.entry.id))) }));
+}

package/dist/fastTravel.d.ts

@@ -0,0 +1,36 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { FastTravelNetwork, TravelPointView } from "@jgengine/core/world/fastTravel";
+import type { WorldXZ } from "@jgengine/core/world/minimap";
+/**
+ * Subscribe a component to a fast-travel network's discovery changes. Returns the
+ * network unchanged; the hook only forces a re-render when a point is discovered
+ * or the network is restored, so callers can read `destinations`/`list` in render.
+ *
+ * @capability use-fast-travel re-render a component when a fast-travel network's discovery state changes
+ */
+export declare function useFastTravel<TMeta = unknown>(network: FastTravelNetwork<TMeta>): FastTravelNetwork<TMeta>;
+/** Props for {@link FastTravelMenu}. */
+export interface FastTravelMenuProps<TMeta = unknown> {
+    network: FastTravelNetwork<TMeta>;
+    /** Origin for distance sorting/labels — usually the player's world-XZ. */
+    from?: WorldXZ;
+    /** Fires with the chosen destination id; the game applies the teleport. */
+    onTravel?: (id: string, point: TravelPointView<TMeta>) => void;
+    /** The id the player is standing on — shown as "You are here", not travelable. */
+    currentId?: string;
+    title?: string;
+    emptyLabel?: string;
+    onClose?: () => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Fast-travel menu — the discovered-destinations list players pick from: points
+ * grouped by region, distance-sorted from `from`, each showing icon, name, and
+ * distance, with a header counting discovered vs. total. Selecting a row calls
+ * `onTravel`; the current location is flagged and not travelable. Bind it to a
+ * `createFastTravelNetwork`.
+ *
+ * @capability fast-travel-menu discovered-destinations picker grouped by region with distances, a discovery counter, and a travel callback
+ */
+export declare function FastTravelMenu<TMeta = unknown>({ network, from, onTravel, currentId, title, emptyLabel, onClose, className, style, }: FastTravelMenuProps<TMeta>): ReactNode;

package/dist/fastTravel.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer } from "react";
+/**
+ * Subscribe a component to a fast-travel network's discovery changes. Returns the
+ * network unchanged; the hook only forces a re-render when a point is discovered
+ * or the network is restored, so callers can read `destinations`/`list` in render.
+ *
+ * @capability use-fast-travel re-render a component when a fast-travel network's discovery state changes
+ */
+export function useFastTravel(network) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => network.subscribe(bump), [network]);
+    return network;
+}
+function formatDistance(distance) {
+    if (distance === undefined)
+        return null;
+    if (distance < 1000)
+        return `${Math.round(distance)}m`;
+    return `${(distance / 1000).toFixed(1)}km`;
+}
+function groupByRegion(views) {
+    const groups = [];
+    const index = new Map();
+    for (const view of views) {
+        const key = view.region ?? null;
+        let bucket = index.get(key);
+        if (bucket === undefined) {
+            bucket = [];
+            index.set(key, bucket);
+            groups.push({ region: key, points: bucket });
+        }
+        bucket.push(view);
+    }
+    return groups;
+}
+/**
+ * Fast-travel menu — the discovered-destinations list players pick from: points
+ * grouped by region, distance-sorted from `from`, each showing icon, name, and
+ * distance, with a header counting discovered vs. total. Selecting a row calls
+ * `onTravel`; the current location is flagged and not travelable. Bind it to a
+ * `createFastTravelNetwork`.
+ *
+ * @capability fast-travel-menu discovered-destinations picker grouped by region with distances, a discovery counter, and a travel callback
+ */
+export function FastTravelMenu({ network, from, onTravel, currentId, title = "Fast Travel", emptyLabel = "No destinations discovered yet.", onClose, className, style, }) {
+    useFastTravel(network);
+    const destinations = network.destinations(from);
+    const groups = groupByRegion(destinations);
+    const discovered = network.discoveredCount();
+    const total = network.total();
+    return (_jsxs("div", { className: className, "data-fast-travel": true, style: {
+            width: 320,
+            maxHeight: 460,
+            display: "flex",
+            flexDirection: "column",
+            borderRadius: 14,
+            background: "linear-gradient(160deg, rgba(20,24,32,0.97), rgba(11,14,19,0.97))",
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.32))",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            boxShadow: "0 18px 44px rgba(0,0,0,0.5)",
+            ...style,
+        }, children: [_jsxs("div", { style: {
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "space-between",
+                    gap: 8,
+                    padding: "10px 12px",
+                    borderBottom: "1px solid rgba(148,163,184,0.2)",
+                }, children: [_jsxs("span", { style: { fontSize: 12, fontWeight: 700, letterSpacing: 1.2, textTransform: "uppercase" }, children: [title, _jsxs("span", { style: { marginLeft: 6, color: "rgba(148,163,184,0.7)", fontWeight: 500 }, children: [discovered, "/", total] })] }), onClose !== undefined ? (_jsx("button", { type: "button", onClick: onClose, style: {
+                            border: "1px solid rgba(148,163,184,0.4)",
+                            borderRadius: 6,
+                            background: "transparent",
+                            color: "rgba(226,232,240,0.85)",
+                            fontSize: 11,
+                            padding: "3px 8px",
+                            cursor: "pointer",
+                        }, children: "\u2715" })) : null] }), destinations.length === 0 ? (_jsx("p", { style: { margin: 0, padding: "16px 12px", fontSize: 12, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("div", { style: { overflowY: "auto", padding: 6, display: "flex", flexDirection: "column", gap: 8 }, children: groups.map((group) => (_jsxs("div", { "data-region": group.region ?? "", children: [group.region !== null ? (_jsx("div", { style: {
+                                fontSize: 10,
+                                fontWeight: 700,
+                                letterSpacing: 1,
+                                textTransform: "uppercase",
+                                color: "rgba(148,163,184,0.65)",
+                                padding: "2px 6px",
+                            }, children: group.region })) : null, _jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 4 }, children: group.points.map((point) => {
+                                const isCurrent = point.id === currentId;
+                                const distance = formatDistance(point.distance);
+                                return (_jsx("li", { children: _jsxs("button", { type: "button", "data-travel-point": point.id, "data-current": isCurrent, disabled: isCurrent, onClick: () => onTravel?.(point.id, point), style: {
+                                            width: "100%",
+                                            display: "flex",
+                                            alignItems: "center",
+                                            gap: 10,
+                                            padding: "9px 10px",
+                                            borderRadius: 9,
+                                            border: "1px solid transparent",
+                                            background: isCurrent ? "rgba(56,189,248,0.12)" : "rgba(148,163,184,0.06)",
+                                            color: "#e2e8f0",
+                                            textAlign: "left",
+                                            cursor: isCurrent ? "default" : "pointer",
+                                        }, children: [_jsx("span", { style: { fontSize: 18, width: 22, textAlign: "center", flexShrink: 0 }, children: point.icon ?? "📍" }), _jsxs("span", { style: { display: "flex", flexDirection: "column", minWidth: 0, flex: 1 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 600 }, children: point.name }), isCurrent ? (_jsx("span", { style: { fontSize: 10, color: "rgba(56,189,248,0.85)" }, children: "You are here" })) : null] }), distance !== null && !isCurrent ? (_jsx("span", { style: { fontSize: 11, color: "rgba(148,163,184,0.75)", whiteSpace: "nowrap" }, children: distance })) : null] }) }, point.id));
+                            }) })] }, group.region ?? "__none__"))) }))] }));
+}

package/dist/floatingText.d.ts

@@ -0,0 +1,84 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { FloatingTextView } from "@jgengine/core/ui/floatingText";
+import type { ProjectEntity } from "./entityFrames.js";
+/**
+ * World-anchored floating text — the presentation half of the data-first
+ * `@jgengine/core/ui/floatingText` seam. The game keeps owning the simulation: it
+ * passes the field's `active()` views plus a `project` function (world → screen),
+ * exactly the transport {@link ./entityFrames!EntityFrames} uses, so an R3F game
+ * gets it for free from `useWorldProjection`. This component owns only the
+ * reusable presentation: projecting each entry, culling ones behind the camera or
+ * off-screen, and rendering absolutely-positioned text with the entry's color,
+ * current alpha, and pop-in scale — reskinnable per `kind` through `styleFor`.
+ *
+ * No `GameProvider`, Three.js, or React Three Fiber is imported here — the same
+ * way `EntityFrames` stays renderer-agnostic. An R3F game gets the one-line drop-in
+ * from `@jgengine/shell/vfx/WorldFloatingText`, which binds the live camera and
+ * advances the field.
+ *
+ * @capability floating-text world-anchored floating combat text / damage numbers overlay, data-first + caller-projected + per-kind skinnable
+ */
+/** One projected, on-screen floating-text entry ready to render. */
+export interface FloatingTextPlacement {
+    view: FloatingTextView;
+    /** Final screen x in CSS px after `offsetX`. */
+    x: number;
+    /** Final screen y in CSS px after `offsetY`. */
+    y: number;
+    /** Projected depth (0 when the projection omitted one); larger = farther. */
+    depth: number;
+}
+/** Anchoring and culling options shared by the layout core and the component. */
+export interface FloatingTextLayoutOptions {
+    /** Screen px added to every projected x. Default 0. */
+    offsetX?: number;
+    /** Screen px added to every projected y — negative lifts text above the anchor. Default 0. */
+    offsetY?: number;
+    /** Viewport size used to cull entries past the edges. Omit to keep every in-front entry. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Extra px beyond each viewport edge still treated as on-screen. Default 96. */
+    margin?: number;
+}
+/**
+ * Pure layout core: projects each view, drops the ones behind the camera or
+ * (when `viewport` is set) off-screen, and returns the survivors sorted
+ * farthest-first so nearer text paints on top. No React, no DOM — unit-testable.
+ *
+ * @capability floating-text pure world→screen layout for floating-text views (project, cull, depth-sort)
+ */
+export declare function layoutFloatingText(views: readonly FloatingTextView[], project: ProjectEntity, options?: FloatingTextLayoutOptions): FloatingTextPlacement[];
+/** Props for {@link FloatingText}. */
+export interface FloatingTextProps extends FloatingTextLayoutOptions {
+    /** The field's live views (`field.active()`), refreshed each frame. */
+    entries: readonly FloatingTextView[];
+    /** World→screen projector; return `null` to cull. Same shape `EntityFrames` takes. */
+    project: ProjectEntity;
+    /**
+     * Per-`kind` art direction: return extra CSS (color, font, weight, shadow) for a
+     * view. Merged over the defaults, so returning `{}` keeps them. The default look
+     * uses `view.color` (or white), a bold sans stack, and a readable shadow.
+     */
+    styleFor?: (view: FloatingTextView) => CSSProperties;
+    /** Base font size in px at `size === 1`; scaled by each view's `size`. Default 20. */
+    fontSizePx?: number;
+    /** Class on the fullscreen overlay layer. */
+    className?: string;
+    /** Style on the fullscreen overlay layer (merged over the absolute-fill default). */
+    style?: CSSProperties;
+    /** Per-entry render override; return your own node instead of the default text chip. */
+    renderEntry?: (placement: FloatingTextPlacement) => ReactNode;
+}
+/**
+ * Absolutely-positioned overlay that renders every on-screen floating-text entry
+ * as text with its color, current alpha, and pop-in scale. Drop it inside a
+ * positioned ancestor (e.g. an `<Html fullscreen>` overlay or `HudCanvas`) and feed
+ * it fresh `entries`/`project` each frame. Every part carries `data-*` hooks
+ * (`data-floating-text`, `data-floating-text-entry="<id>"`, `data-kind="<kind>"`)
+ * for tests and skins.
+ *
+ * @capability floating-text overlay that renders on-screen floating combat text with per-kind color, alpha, and pop-in scale
+ */
+export declare function FloatingText({ entries, project, styleFor, fontSizePx, className, style, renderEntry, ...layout }: FloatingTextProps): import("react").JSX.Element;

package/dist/floatingText.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+/**
+ * Pure layout core: projects each view, drops the ones behind the camera or
+ * (when `viewport` is set) off-screen, and returns the survivors sorted
+ * farthest-first so nearer text paints on top. No React, no DOM — unit-testable.
+ *
+ * @capability floating-text pure world→screen layout for floating-text views (project, cull, depth-sort)
+ */
+export function layoutFloatingText(views, project, options = {}) {
+    const { offsetX = 0, offsetY = 0, viewport, margin = 96 } = options;
+    const placed = [];
+    for (const view of views) {
+        const projection = project(view.position);
+        if (projection === null || projection.behind === true)
+            continue;
+        const x = projection.x + offsetX;
+        const y = projection.y + offsetY;
+        if (viewport !== undefined &&
+            (x < -margin || x > viewport.width + margin || y < -margin || y > viewport.height + margin)) {
+            continue;
+        }
+        placed.push({ view, x, y, depth: projection.depth ?? 0 });
+    }
+    placed.sort((a, b) => b.depth - a.depth || a.view.id - b.view.id);
+    return placed;
+}
+/**
+ * Absolutely-positioned overlay that renders every on-screen floating-text entry
+ * as text with its color, current alpha, and pop-in scale. Drop it inside a
+ * positioned ancestor (e.g. an `<Html fullscreen>` overlay or `HudCanvas`) and feed
+ * it fresh `entries`/`project` each frame. Every part carries `data-*` hooks
+ * (`data-floating-text`, `data-floating-text-entry="<id>"`, `data-kind="<kind>"`)
+ * for tests and skins.
+ *
+ * @capability floating-text overlay that renders on-screen floating combat text with per-kind color, alpha, and pop-in scale
+ */
+export function FloatingText({ entries, project, styleFor, fontSizePx = 20, className, style, renderEntry, ...layout }) {
+    const placements = layoutFloatingText(entries, project, layout);
+    return (_jsx("div", { className: className, "data-floating-text": "", style: { position: "absolute", inset: 0, pointerEvents: "none", overflow: "hidden", ...style }, children: placements.map((placement, index) => {
+            const { view } = placement;
+            const custom = styleFor?.(view);
+            return (_jsx("div", { "data-floating-text-entry": view.id, "data-kind": view.kind, style: {
+                    position: "absolute",
+                    left: placement.x,
+                    top: placement.y,
+                    transform: `translate(-50%, -50%) scale(${view.size})`,
+                    transformOrigin: "center",
+                    opacity: view.alpha,
+                    zIndex: index,
+                    whiteSpace: "nowrap",
+                    fontFamily: "system-ui, sans-serif",
+                    fontWeight: 800,
+                    fontSize: fontSizePx,
+                    lineHeight: 1,
+                    color: view.color ?? "#ffffff",
+                    textShadow: "0 2px 4px rgba(0,0,0,0.9), 0 0 2px rgba(0,0,0,0.9)",
+                    ...custom,
+                }, children: renderEntry !== undefined ? renderEntry(placement) : view.text }, view.id));
+        }) }));
+}