@jgengine/core 0.10.0 → 0.12.0

package/dist/ui/hudLayout.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function isPanelDraggable(state, id) {
     return state.panels[id] !== undefined && (state.editing || !state.locked);
 }
@@ -13,9 +14,11 @@ export const HUD_ANCHOR_FRACTIONS = {
     "bottom-right": { fx: 1, fy: 1 },
 };
 const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+/** @internal */
 export function isHudAnchor(value) {
     return typeof value === "string" && value in HUD_ANCHOR_FRACTIONS;
 }
+/** @internal */
 export function anchoredPlacement(anchor, inset) {
     const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
     return {
@@ -24,6 +27,7 @@ export function anchoredPlacement(anchor, inset) {
         dy: fy === 1 ? -inset.y : inset.y,
     };
 }
+/** @internal */
 export function nearestAnchor(rect, viewport) {
     const cx = viewport.width > 0 ? (rect.x + rect.width / 2) / viewport.width : 0.5;
     const cy = viewport.height > 0 ? (rect.y + rect.height / 2) / viewport.height : 0.5;
@@ -39,6 +43,7 @@ export function nearestAnchor(rect, viewport) {
     }
     return best;
 }
+/** @internal */
 export function clampRect(rect, viewport) {
     return {
         x: Math.max(0, Math.min(rect.x, viewport.width - rect.width)),
@@ -47,6 +52,7 @@ export function clampRect(rect, viewport) {
         height: rect.height,
     };
 }
+/** @internal */
 export function placementFromRect(rect, viewport, snap = 1) {
     const clamped = clampRect(rect, viewport);
     const anchor = nearestAnchor(clamped, viewport);
@@ -60,6 +66,7 @@ export function placementFromRect(rect, viewport, snap = 1) {
         dy: Math.round(dy / step) * step,
     };
 }
+/** @internal */
 export function rectFromPlacement(placement, size, viewport) {
     const { fx, fy } = HUD_ANCHOR_FRACTIONS[placement.anchor];
     return {
@@ -86,19 +93,93 @@ function parseSerialized(raw) {
     for (const [id, value] of Object.entries(panels)) {
         if (typeof value !== "object" || value === null)
             continue;
-        const { anchor, dx, dy } = value;
+        const record = value;
+        const placementSource = record.placement ?? record;
+        const { anchor, dx, dy } = placementSource;
         if (!isHudAnchor(anchor))
             continue;
         if (typeof dx !== "number" || !Number.isFinite(dx))
             continue;
         if (typeof dy !== "number" || !Number.isFinite(dy))
             continue;
-        out.set(id, { anchor, dx, dy });
+        const override = { placement: { anchor, dx, dy } };
+        if (typeof record.width === "number" && Number.isFinite(record.width))
+            override.width = record.width;
+        if (typeof record.height === "number" && Number.isFinite(record.height))
+            override.height = record.height;
+        if (typeof record.visible === "boolean")
+            override.visible = record.visible;
+        if (typeof record.type === "string")
+            override.type = record.type;
+        out.set(id, override);
     }
     return out;
 }
+const activeHudLayouts = new Set();
+const activeHudLayoutListeners = new Set();
+/** @internal Agent bridge seam — HudCanvas registers its store while mounted so headless drivers can reach canvas mode. */
+export function registerActiveHudLayout(store) {
+    activeHudLayouts.add(store);
+    for (const listener of [...activeHudLayoutListeners])
+        listener();
+    return () => {
+        if (!activeHudLayouts.delete(store))
+            return;
+        for (const listener of [...activeHudLayoutListeners])
+            listener();
+    };
+}
+/** @internal */
+export function listActiveHudLayouts() {
+    return [...activeHudLayouts];
+}
+/**
+ * @internal Notified whenever a `HudCanvas` mounts or unmounts (the active-layout set changes).
+ * Lets the editor's HUD-layout surface enable editing on layouts that mount after it opens.
+ */
+export function subscribeActiveHudLayouts(listener) {
+    activeHudLayoutListeners.add(listener);
+    return () => {
+        activeHudLayoutListeners.delete(listener);
+    };
+}
+function panelToUi(panel) {
+    const layout = {
+        anchor: panel.placement.anchor,
+        dx: panel.placement.dx,
+        dy: panel.placement.dy,
+    };
+    if (panel.width !== undefined)
+        layout.width = panel.width;
+    if (panel.height !== undefined)
+        layout.height = panel.height;
+    if (panel.visible === false)
+        layout.visible = false;
+    if (panel.type !== undefined)
+        layout.type = panel.type;
+    return layout;
+}
+function overrideToUi(id, override) {
+    const layout = {
+        anchor: override.placement.anchor,
+        dx: override.placement.dx,
+        dy: override.placement.dy,
+    };
+    if (override.width !== undefined)
+        layout.width = override.width;
+    if (override.height !== undefined)
+        layout.height = override.height;
+    if (override.visible !== undefined)
+        layout.visible = override.visible;
+    if (override.type !== undefined)
+        layout.type = override.type;
+    void id;
+    return layout;
+}
+/** @internal */
 export function createHudLayout(options) {
     const snap = options?.snap ?? 1;
+    const onDocumentPatch = options?.onDocumentPatch;
     const defaults = new Map();
     const pending = new Map();
     let topZ = 0;
@@ -111,22 +192,37 @@ export function createHudLayout(options) {
     const setPanel = (panel) => {
         state = { ...state, panels: { ...state.panels, [panel.id]: panel } };
     };
+    const notifyDocument = (panel) => {
+        onDocumentPatch?.(panel.id, panelToUi(panel));
+    };
     return {
         getState: () => state,
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
-        register(id, placement) {
-            defaults.set(id, placement);
+        register(id, placement, registerOptions) {
+            const fallback = {
+                placement,
+                width: registerOptions?.width,
+                height: registerOptions?.height,
+                visible: registerOptions?.visible,
+                type: registerOptions?.type,
+            };
+            defaults.set(id, fallback);
             if (state.panels[id] !== undefined)
                 return;
             const override = pending.get(id);
+            const source = override ?? fallback;
             setPanel({
                 id,
-                placement: override ?? placement,
+                placement: source.placement,
                 z: ++topZ,
                 moved: override !== undefined,
+                width: source.width ?? fallback.width,
+                height: source.height ?? fallback.height,
+                visible: source.visible ?? fallback.visible !== false,
+                type: source.type ?? fallback.type,
             });
         },
         move(id, rect, viewport) {
@@ -134,8 +230,32 @@ export function createHudLayout(options) {
             if (panel === undefined)
                 return;
             const placement = placementFromRect(rect, viewport, snap);
-            setPanel({ ...panel, placement, moved: true });
+            const next = { ...panel, placement, moved: true };
+            setPanel(next);
+            emit();
+            notifyDocument(next);
+        },
+        resize(id, size) {
+            const panel = state.panels[id];
+            if (panel === undefined)
+                return;
+            const width = Math.max(1, Math.round(size.width));
+            const height = Math.max(1, Math.round(size.height));
+            if (panel.width === width && panel.height === height)
+                return;
+            const next = { ...panel, width, height, moved: true };
+            setPanel(next);
             emit();
+            notifyDocument(next);
+        },
+        setVisible(id, visible) {
+            const panel = state.panels[id];
+            if (panel === undefined || panel.visible === visible)
+                return;
+            const next = { ...panel, visible, moved: true };
+            setPanel(next);
+            emit();
+            notifyDocument(next);
         },
         bringToFront(id) {
             const panel = state.panels[id];
@@ -163,9 +283,23 @@ export function createHudLayout(options) {
                 pending.delete(panelId);
                 const panel = state.panels[panelId];
                 const fallback = defaults.get(panelId);
-                if (panel === undefined || fallback === undefined || !panel.moved)
+                if (panel === undefined || fallback === undefined)
                     continue;
-                setPanel({ ...panel, placement: fallback, moved: false });
+                const hasAuthored = panel.moved ||
+                    panel.width !== fallback.width ||
+                    panel.height !== fallback.height ||
+                    panel.visible !== (fallback.visible !== false);
+                if (!hasAuthored)
+                    continue;
+                setPanel({
+                    ...panel,
+                    placement: fallback.placement,
+                    width: fallback.width,
+                    height: fallback.height,
+                    visible: fallback.visible !== false,
+                    type: fallback.type,
+                    moved: false,
+                });
                 changed = true;
             }
             if (changed)
@@ -174,14 +308,32 @@ export function createHudLayout(options) {
         serialize() {
             const panels = {};
             for (const panel of Object.values(state.panels)) {
-                if (panel.moved)
-                    panels[panel.id] = panel.placement;
+                if (!panel.moved)
+                    continue;
+                panels[panel.id] = {
+                    anchor: panel.placement.anchor,
+                    dx: panel.placement.dx,
+                    dy: panel.placement.dy,
+                    ...(panel.width === undefined ? {} : { width: panel.width }),
+                    ...(panel.height === undefined ? {} : { height: panel.height }),
+                    ...(panel.visible === false ? { visible: false } : {}),
+                    ...(panel.type === undefined ? {} : { type: panel.type }),
+                };
             }
-            for (const [id, placement] of pending) {
-                if (state.panels[id] === undefined)
-                    panels[id] = placement;
+            for (const [id, override] of pending) {
+                if (state.panels[id] !== undefined)
+                    continue;
+                panels[id] = {
+                    anchor: override.placement.anchor,
+                    dx: override.placement.dx,
+                    dy: override.placement.dy,
+                    ...(override.width === undefined ? {} : { width: override.width }),
+                    ...(override.height === undefined ? {} : { height: override.height }),
+                    ...(override.visible === undefined ? {} : { visible: override.visible }),
+                    ...(override.type === undefined ? {} : { type: override.type }),
+                };
             }
-            const data = { v: 1, panels };
+            const data = { v: 2, panels };
             return JSON.stringify(data);
         },
         hydrate(raw) {
@@ -191,17 +343,68 @@ export function createHudLayout(options) {
             if (parsed.size === 0)
                 return;
             let changed = false;
-            for (const [id, placement] of parsed) {
+            for (const [id, override] of parsed) {
                 const panel = state.panels[id];
                 if (panel === undefined) {
-                    pending.set(id, placement);
+                    pending.set(id, override);
                     continue;
                 }
-                setPanel({ ...panel, placement, moved: true });
+                setPanel({
+                    ...panel,
+                    placement: override.placement,
+                    width: override.width ?? panel.width,
+                    height: override.height ?? panel.height,
+                    visible: override.visible ?? panel.visible,
+                    type: override.type ?? panel.type,
+                    moved: true,
+                });
                 changed = true;
             }
             if (changed)
                 emit();
         },
+        applyDocumentUi(ui) {
+            if (ui === undefined)
+                return;
+            let changed = false;
+            for (const [id, layout] of Object.entries(ui.panels)) {
+                const override = {
+                    placement: { anchor: layout.anchor, dx: layout.dx, dy: layout.dy },
+                    width: layout.width,
+                    height: layout.height,
+                    visible: layout.visible,
+                    type: layout.type,
+                };
+                const panel = state.panels[id];
+                if (panel === undefined) {
+                    pending.set(id, override);
+                    continue;
+                }
+                setPanel({
+                    ...panel,
+                    placement: override.placement,
+                    width: override.width ?? panel.width,
+                    height: override.height ?? panel.height,
+                    visible: override.visible ?? panel.visible,
+                    type: override.type ?? panel.type,
+                    moved: true,
+                });
+                changed = true;
+            }
+            if (changed)
+                emit();
+        },
+        toDocumentUi() {
+            const panels = {};
+            for (const panel of Object.values(state.panels)) {
+                if (panel.moved)
+                    panels[panel.id] = panelToUi(panel);
+            }
+            for (const [id, override] of pending) {
+                if (state.panels[id] === undefined)
+                    panels[id] = overrideToUi(id, override);
+            }
+            return { panels };
+        },
     };
 }

package/dist/ui/selectionModel.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Headless view model for a multi-entity selection — the data layer behind an RTS selection panel, a
+ * party frame, or a squad summary. It turns a caller-owned list of selected entity summaries into a
+ * primary detail focus, an ordered member strip, and same-kind buckets for large selections, with
+ * focus/hover and virtualization helpers. No rendering opinion: the React renderers in
+ * `@jgengine/react/selectionHud` consume this and a game supplies the entity data from wherever it
+ * lives (a `createSelectionSet`, a roster, a marquee query).
+ */
+/** One vital bar on an entity summary (health/shield/energy): current/max plus optional label and tone. */
+export interface EntityVital {
+    id: string;
+    label?: string;
+    current: number;
+    max: number;
+    /** Colour-ramp hint the renderer maps to a palette (e.g. `"health" | "shield"`); caller-owned. */
+    tone?: string;
+}
+/**
+ * A caller-provided summary of one selectable entity — the DATA input. `kind` is the grouping key
+ * used to bucket a large selection (unit type, catalog id); `icon` is a portrait id the renderer
+ * resolves. Only `id` is required.
+ */
+export interface EntitySummaryDef {
+    id: string;
+    name?: string;
+    /** Type/catalog id a large selection is bucketed by; falls back to `"unit"` when omitted. */
+    kind?: string;
+    /** Portrait id / glyph the caller maps to art. */
+    icon?: string;
+    vitals?: readonly EntityVital[];
+    tags?: readonly string[];
+    /** Ownership / faction tint id, caller-owned. */
+    owner?: string;
+}
+/** A bucket of same-`kind` entities in a large selection — the RTS "12 Marines" control chip. */
+export interface SelectionGroup {
+    kind: string;
+    label: string;
+    icon?: string;
+    count: number;
+    ids: readonly string[];
+}
+/**
+ * A resolved multi-selection view model. `primary` is the focused entity's full detail; `members` is
+ * the stable-order strip; `groups` buckets members by kind (count-desc, then label) for the
+ * portrait-overflow case; `grouped` is the hint that the selection is large enough to prefer groups
+ * over per-member portraits.
+ */
+export interface SelectionView {
+    count: number;
+    primary: EntitySummaryDef | null;
+    members: readonly EntitySummaryDef[];
+    groups: readonly SelectionGroup[];
+    focusIndex: number;
+    grouped: boolean;
+}
+/** Options for {@link summarizeSelection}. */
+export interface SummarizeSelectionOptions {
+    /** Id of the entity to treat as primary/focused. Wins over `focusIndex`; ignored when not present. */
+    primaryId?: string;
+    /** Index of the primary/focused member when `primaryId` is absent (default 0). */
+    focusIndex?: number;
+    /** Member count above which `grouped` flips true (default 12). */
+    groupThreshold?: number;
+    /** Map a `kind` to a display label for its group (default: the kind itself). */
+    labelOf?: (kind: string) => string;
+}
+/**
+ * Summarize a selected-entity list into a {@link SelectionView}: resolve the primary focus, keep the
+ * ordered members, and bucket them by `kind`. Pure and stable — deterministic group ordering and a
+ * clamped focus index, so it is safe to call every render and to assert on in a test.
+ */
+export declare function summarizeSelection(members: readonly EntitySummaryDef[], options?: SummarizeSelectionOptions): SelectionView;
+/** A 1-D focus move within the selection member strip. */
+export type SelectionFocusDirection = "next" | "prev" | "first" | "last";
+/**
+ * Pure next-focus math for the selection strip: step the focus index by one member (wrapping), or
+ * jump to an end. `-1` (no focus) steps to the first/last member. Returns `-1` for an empty selection.
+ */
+export declare function moveSelectionFocus(count: number, current: number, dir: SelectionFocusDirection): number;
+/** A contiguous slice of members for virtualizing a large selection strip. */
+export interface SelectionWindow {
+    start: number;
+    end: number;
+    items: readonly EntitySummaryDef[];
+}
+/**
+ * Compute a virtualization window over a large selection: a `size`-length slice starting near
+ * `scroll`, clamped so the window never runs past the end. Render only `items`, offsetting by
+ * `start * itemSize`, to keep a thousand-unit selection from mounting a thousand portraits.
+ */
+export declare function selectionWindow(members: readonly EntitySummaryDef[], scroll: number, size: number): SelectionWindow;

package/dist/ui/selectionModel.js

@@ -0,0 +1,88 @@
+/**
+ * Headless view model for a multi-entity selection — the data layer behind an RTS selection panel, a
+ * party frame, or a squad summary. It turns a caller-owned list of selected entity summaries into a
+ * primary detail focus, an ordered member strip, and same-kind buckets for large selections, with
+ * focus/hover and virtualization helpers. No rendering opinion: the React renderers in
+ * `@jgengine/react/selectionHud` consume this and a game supplies the entity data from wherever it
+ * lives (a `createSelectionSet`, a roster, a marquee query).
+ */
+/**
+ * Summarize a selected-entity list into a {@link SelectionView}: resolve the primary focus, keep the
+ * ordered members, and bucket them by `kind`. Pure and stable — deterministic group ordering and a
+ * clamped focus index, so it is safe to call every render and to assert on in a test.
+ */
+export function summarizeSelection(members, options) {
+    const count = members.length;
+    const threshold = options?.groupThreshold ?? 12;
+    const labelOf = options?.labelOf ?? ((kind) => kind);
+    let focusIndex = -1;
+    if (options?.primaryId !== undefined) {
+        focusIndex = members.findIndex((m) => m.id === options.primaryId);
+    }
+    if (focusIndex < 0)
+        focusIndex = options?.focusIndex ?? 0;
+    focusIndex = count === 0 ? -1 : Math.max(0, Math.min(count - 1, focusIndex));
+    const primary = focusIndex < 0 ? null : (members[focusIndex] ?? null);
+    return {
+        count,
+        primary,
+        members,
+        groups: groupSelection(members, labelOf),
+        focusIndex,
+        grouped: count > threshold,
+    };
+}
+/** @internal Bucket members by `kind` into count-desc, label-asc ordered {@link SelectionGroup}s. */
+function groupSelection(members, labelOf) {
+    const order = [];
+    const byKind = new Map();
+    for (const member of members) {
+        const kind = member.kind ?? "unit";
+        let bucket = byKind.get(kind);
+        if (bucket === undefined) {
+            bucket = { icon: member.icon, ids: [] };
+            byKind.set(kind, bucket);
+            order.push(kind);
+        }
+        bucket.ids.push(member.id);
+    }
+    const groups = order.map((kind) => {
+        const bucket = byKind.get(kind);
+        const group = { kind, label: labelOf(kind), count: bucket.ids.length, ids: bucket.ids };
+        if (bucket.icon !== undefined)
+            group.icon = bucket.icon;
+        return group;
+    });
+    groups.sort((a, b) => (b.count - a.count) || a.label.localeCompare(b.label));
+    return groups;
+}
+/**
+ * Pure next-focus math for the selection strip: step the focus index by one member (wrapping), or
+ * jump to an end. `-1` (no focus) steps to the first/last member. Returns `-1` for an empty selection.
+ */
+export function moveSelectionFocus(count, current, dir) {
+    if (count <= 0)
+        return -1;
+    if (dir === "first")
+        return 0;
+    if (dir === "last")
+        return count - 1;
+    if (current < 0)
+        return dir === "prev" ? count - 1 : 0;
+    if (dir === "next")
+        return (current + 1) % count;
+    return (current - 1 + count) % count;
+}
+/**
+ * Compute a virtualization window over a large selection: a `size`-length slice starting near
+ * `scroll`, clamped so the window never runs past the end. Render only `items`, offsetting by
+ * `start * itemSize`, to keep a thousand-unit selection from mounting a thousand portraits.
+ */
+export function selectionWindow(members, scroll, size) {
+    const count = members.length;
+    const windowSize = Math.max(1, Math.floor(size));
+    const maxStart = Math.max(0, count - windowSize);
+    const start = Math.max(0, Math.min(maxStart, Math.floor(scroll)));
+    const end = Math.min(count, start + windowSize);
+    return { start, end, items: members.slice(start, end) };
+}

package/dist/ui/tooltipModel.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Headless model for HUD tooltips and popovers — the shared description seam games have been
+ * hand-rolling with a bare DOM `title=` attribute. {@link actionTooltip} turns a
+ * {@link ResolvedAction} into structured {@link TooltipContent} (title, cost, cooldown, blocking
+ * notes), and {@link placePopover} is the pure, SSR-safe positioning math the React tooltip uses to
+ * flip and clamp against the viewport. Both are rendering-agnostic.
+ */
+import type { ActionCooldown, ActionCost, ResolvedAction } from "./actionModel.js";
+/** Structured tooltip content — a renderer lays these fields out; the model owns what is shown. */
+export interface TooltipContent {
+    title: string;
+    subtitle?: string;
+    body?: string;
+    /** Hotkey label to echo (e.g. `"Q"`). */
+    hotkey?: string;
+    costs?: readonly ActionCost[];
+    cooldown?: ActionCooldown | null;
+    /** Blocking reasons rendered as a warning footer (why the action is unavailable). */
+    notes?: readonly string[];
+}
+/**
+ * Build {@link TooltipContent} from a {@link ResolvedAction}: title from the label, the group as a
+ * subtitle, the description as the body, and the blocking reasons as warning notes. The single place
+ * an action's tooltip copy is assembled, so every renderer shows the same thing.
+ */
+export declare function actionTooltip(action: ResolvedAction): TooltipContent;
+/** Which side of its anchor a popover opens toward. */
+export type PopoverSide = "top" | "bottom" | "left" | "right";
+/** A positioned rectangle (viewport/anchor space, top-left origin, pixels). */
+export interface UiRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A width/height pair (pixels). */
+export interface UiSize {
+    width: number;
+    height: number;
+}
+/** The resolved popover position — the side it actually opened on and its clamped top-left. */
+export interface PopoverPlacement {
+    side: PopoverSide;
+    left: number;
+    top: number;
+}
+/** Options for {@link placePopover}. */
+export interface PopoverOptions {
+    /** Side to try first (default `"top"`). Flips to the opposite when it would overflow. */
+    preferred?: PopoverSide;
+    /** Gap between the anchor and the popover, in pixels (default 8). */
+    gap?: number;
+    /** Minimum inset from the viewport edges, in pixels (default 8). */
+    margin?: number;
+}
+/**
+ * Position a popover/tooltip of `content` size against its `anchor` rectangle inside `viewport`:
+ * open on the `preferred` side, flip to the opposite when that side lacks room and the opposite has
+ * more, then clamp the top-left so the box stays fully on screen (respecting `margin`). Pure and
+ * deterministic — no DOM reads — so it is SSR-safe and unit-testable, and the React tooltip is a thin
+ * shell over it.
+ */
+export declare function placePopover(anchor: UiRect, content: UiSize, viewport: UiSize, options?: PopoverOptions): PopoverPlacement;

package/dist/ui/tooltipModel.js

@@ -0,0 +1,82 @@
+/**
+ * Headless model for HUD tooltips and popovers — the shared description seam games have been
+ * hand-rolling with a bare DOM `title=` attribute. {@link actionTooltip} turns a
+ * {@link ResolvedAction} into structured {@link TooltipContent} (title, cost, cooldown, blocking
+ * notes), and {@link placePopover} is the pure, SSR-safe positioning math the React tooltip uses to
+ * flip and clamp against the viewport. Both are rendering-agnostic.
+ */
+/**
+ * Build {@link TooltipContent} from a {@link ResolvedAction}: title from the label, the group as a
+ * subtitle, the description as the body, and the blocking reasons as warning notes. The single place
+ * an action's tooltip copy is assembled, so every renderer shows the same thing.
+ */
+export function actionTooltip(action) {
+    const content = { title: action.label };
+    if (action.group !== undefined)
+        content.subtitle = action.group;
+    if (action.description !== undefined)
+        content.body = action.description;
+    if (action.hotkey !== undefined)
+        content.hotkey = action.hotkey;
+    if (action.costs.length > 0)
+        content.costs = action.costs;
+    if (action.cooldown !== null && !action.cooldown.ready)
+        content.cooldown = action.cooldown;
+    if (action.reasons.length > 0)
+        content.notes = action.reasons.map((reason) => reason.message);
+    return content;
+}
+const OPPOSITE = {
+    top: "bottom",
+    bottom: "top",
+    left: "right",
+    right: "left",
+};
+const clamp = (value, min, max) => Math.max(min, Math.min(max, max < min ? min : value));
+/** @internal Room in pixels between the anchor and the viewport edge on a given side. */
+function roomOn(side, anchor, viewport) {
+    if (side === "top")
+        return anchor.y;
+    if (side === "bottom")
+        return viewport.height - (anchor.y + anchor.height);
+    if (side === "left")
+        return anchor.x;
+    return viewport.width - (anchor.x + anchor.width);
+}
+/** @internal The top-left of `content` placed on `side` of `anchor`, before viewport clamping. */
+function topLeftFor(side, anchor, content, gap) {
+    if (side === "top") {
+        return { left: anchor.x + anchor.width / 2 - content.width / 2, top: anchor.y - gap - content.height };
+    }
+    if (side === "bottom") {
+        return { left: anchor.x + anchor.width / 2 - content.width / 2, top: anchor.y + anchor.height + gap };
+    }
+    if (side === "left") {
+        return { left: anchor.x - gap - content.width, top: anchor.y + anchor.height / 2 - content.height / 2 };
+    }
+    return { left: anchor.x + anchor.width + gap, top: anchor.y + anchor.height / 2 - content.height / 2 };
+}
+/**
+ * Position a popover/tooltip of `content` size against its `anchor` rectangle inside `viewport`:
+ * open on the `preferred` side, flip to the opposite when that side lacks room and the opposite has
+ * more, then clamp the top-left so the box stays fully on screen (respecting `margin`). Pure and
+ * deterministic — no DOM reads — so it is SSR-safe and unit-testable, and the React tooltip is a thin
+ * shell over it.
+ */
+export function placePopover(anchor, content, viewport, options) {
+    const gap = options?.gap ?? 8;
+    const margin = options?.margin ?? 8;
+    const preferred = options?.preferred ?? "top";
+    const needed = preferred === "top" || preferred === "bottom" ? content.height : content.width;
+    let side = preferred;
+    const opposite = OPPOSITE[preferred];
+    if (roomOn(preferred, anchor, viewport) < needed + gap && roomOn(opposite, anchor, viewport) > roomOn(preferred, anchor, viewport)) {
+        side = opposite;
+    }
+    const { left, top } = topLeftFor(side, anchor, content, gap);
+    return {
+        side,
+        left: clamp(left, margin, viewport.width - content.width - margin),
+        top: clamp(top, margin, viewport.height - content.height - margin),
+    };
+}