@jgengine/core 0.9.0 → 0.11.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,77 @@ 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();
+/** @internal Agent bridge seam — HudCanvas registers its store while mounted so headless drivers can reach canvas mode. */
+export function registerActiveHudLayout(store) {
+    activeHudLayouts.add(store);
+    return () => {
+        activeHudLayouts.delete(store);
+    };
+}
+/** @internal */
+export function listActiveHudLayouts() {
+    return [...activeHudLayouts];
+}
+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 +176,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 +214,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 +267,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;
+                const hasAuthored = panel.moved ||
+                    panel.width !== fallback.width ||
+                    panel.height !== fallback.height ||
+                    panel.visible !== (fallback.visible !== false);
+                if (!hasAuthored)
                     continue;
-                setPanel({ ...panel, placement: fallback, moved: false });
+                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 +292,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 +327,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, 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();
+        },
+        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, 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();
         },
+        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/orientation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The game-level orientation contract. A game declares how it supports phone
+ * orientations; the shell resolves that against the live orientation to decide
+ * whether to show a dismissible rotate hint (advisory) or a full-screen gate
+ * that blocks gameplay until the device is turned (required).
+ */
+/** How a game supports a phone orientation on coarse-pointer displays. */
+export type MobileOrientationRule = "any" | "portrait" | "landscape" | "portrait-required" | "landscape-required" | "unsupported";
+/** Object form of the `orientation` field: the strict per-platform contract. */
+export interface GameOrientationConfig {
+    /** Orientation contract on coarse-pointer / phone displays. Default `"any"`. */
+    mobile?: MobileOrientationRule;
+}
+/**
+ * The `orientation` field of a game definition. Legacy shorthand `"landscape"`
+ * / `"portrait"` stays advisory (a dismissible rotate hint, never a gate). The
+ * object form `{ mobile: "landscape-required" }` is the strict contract that
+ * blocks gameplay behind the rotate screen until the device is turned.
+ */
+export type GameOrientation = "landscape" | "portrait" | GameOrientationConfig;
+/** A concrete device orientation. */
+export type LayoutOrientation = "portrait" | "landscape";
+/** The resolved orientation contract for a platform: whether it's supported, gated, or merely preferred. */
+export interface OrientationRequirement {
+    /** False only for `"unsupported"` — the game declares it isn't built for phones. */
+    supported: boolean;
+    /** Orientation gameplay is hard-gated to; `null` when there is no gate. */
+    required: LayoutOrientation | null;
+    /** Orientation the game reads best in; drives an advisory hint when not required. */
+    preferred: LayoutOrientation | null;
+}
+/** Normalize the `orientation` field (legacy string or object) to a single mobile rule. */
+export declare function resolveMobileOrientationRule(orientation: GameOrientation | undefined): MobileOrientationRule;
+/** Resolve the game's orientation declaration into a concrete requirement for a platform. Desktop is always unconstrained. */
+export declare function resolveOrientationRequirement(orientation: GameOrientation | undefined, platform: "mobile" | "desktop"): OrientationRequirement;
+/** The rotate gate blocks gameplay: a hard requirement (or `unsupported`) the live orientation doesn't satisfy. */
+export declare function orientationGateActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean;
+/** An advisory rotate hint applies: a preference (not a hard gate) the live orientation doesn't satisfy. */
+export declare function orientationHintActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean;

package/dist/ui/orientation.js

@@ -0,0 +1,49 @@
+/**
+ * The game-level orientation contract. A game declares how it supports phone
+ * orientations; the shell resolves that against the live orientation to decide
+ * whether to show a dismissible rotate hint (advisory) or a full-screen gate
+ * that blocks gameplay until the device is turned (required).
+ */
+/** Normalize the `orientation` field (legacy string or object) to a single mobile rule. */
+export function resolveMobileOrientationRule(orientation) {
+    if (orientation === undefined)
+        return "any";
+    if (orientation === "landscape")
+        return "landscape";
+    if (orientation === "portrait")
+        return "portrait";
+    return orientation.mobile ?? "any";
+}
+/** Resolve the game's orientation declaration into a concrete requirement for a platform. Desktop is always unconstrained. */
+export function resolveOrientationRequirement(orientation, platform) {
+    if (platform === "desktop")
+        return { supported: true, required: null, preferred: null };
+    const rule = resolveMobileOrientationRule(orientation);
+    switch (rule) {
+        case "unsupported":
+            return { supported: false, required: null, preferred: null };
+        case "landscape-required":
+            return { supported: true, required: "landscape", preferred: "landscape" };
+        case "portrait-required":
+            return { supported: true, required: "portrait", preferred: "portrait" };
+        case "landscape":
+            return { supported: true, required: null, preferred: "landscape" };
+        case "portrait":
+            return { supported: true, required: null, preferred: "portrait" };
+        case "any":
+            return { supported: true, required: null, preferred: null };
+    }
+}
+/** The rotate gate blocks gameplay: a hard requirement (or `unsupported`) the live orientation doesn't satisfy. */
+export function orientationGateActive(requirement, liveOrientation) {
+    if (!requirement.supported)
+        return true;
+    return requirement.required !== null && requirement.required !== liveOrientation;
+}
+/** An advisory rotate hint applies: a preference (not a hard gate) the live orientation doesn't satisfy. */
+export function orientationHintActive(requirement, liveOrientation) {
+    return (requirement.supported &&
+        requirement.required === null &&
+        requirement.preferred !== null &&
+        requirement.preferred !== liveOrientation);
+}

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/swingTimer.d.ts

@@ -0,0 +1,42 @@
+/** The local player's auto-attack state for one frame. `swingTimer` counts DOWN in seconds to 0 (= a swing lands). */
+export interface SwingPlayerInput {
+    autoAttack: boolean;
+    swingTimer: number;
+    weapon: {
+        speed: number;
+    };
+}
+/** The current target, or the fields the bar needs from it. */
+export interface SwingTargetInput {
+    dead: boolean;
+    /** Entity kind; an `"object"` target (a node/chest) never shows a swing bar. */
+    kind: string;
+}
+/** Whether the bar shows a "ready" label or the seconds-remaining countdown. */
+export type SwingLabelKind = "ready" | "seconds";
+/** One frame of swing-bar state plus the cursor (`nextPeriod`/`nextTimer`) the caller carries back into the next call. */
+export interface SwingTimerState {
+    /** Whether the bar should render at all. */
+    visible: boolean;
+    /** Fill 0..1, growing toward 1 as the next swing nears. */
+    frac: number;
+    /** True the moment the swing is ready to land. */
+    ready: boolean;
+    labelKind: SwingLabelKind;
+    /** Seconds remaining until the next swing (0 when ready). */
+    seconds: number;
+    /** Recovered swing period this frame — pass back as `prevPeriod` next call. */
+    nextPeriod: number;
+    /** This frame's timer — pass back as `prevTimer` next call to detect the reset edge. */
+    nextTimer: number;
+}
+/** Threshold above which a timer jump is treated as a fresh swing (period reset). */
+export declare const SWING_EDGE_EPSILON = 0.0001;
+/**
+ * Pure swing-timer bar state — no hidden state, no clock, no DOM. The caller
+ * threads `prevPeriod`/`prevTimer` back each frame. The period is recovered on
+ * the reset edge (when `swingTimer` jumps up = a new swing began) as
+ * `max(swingTimer, weapon.speed)`, so the fill is correct even without knowing
+ * the weapon's exact cadence. Hidden unless auto-attacking a live, non-object target.
+ */
+export declare function swingTimerState(player: SwingPlayerInput, target: SwingTargetInput | null, prevPeriod: number, prevTimer: number): SwingTimerState;