@jgengine/core 0.9.0 → 0.11.0

package/dist/editor/runtimeInspector.d.ts

@@ -0,0 +1,88 @@
+import type { EditorCommand } from "./commands.js";
+import type { EditorDocument } from "./types.js";
+import { type RuntimeEntityState, type RuntimeStateSnapshot } from "./liveSync.js";
+/** Play-mode sim gate held by the editor host — pause freezes ticks; step runs N frames then re-pauses. */
+export interface RuntimePlayControl {
+    paused: boolean;
+    pendingSteps: number;
+}
+/** Compact reverse-channel view for the play-mode inspector and `runtime_summary` RPC. */
+export interface RuntimeInspectorSummary {
+    seq: number;
+    entityCount: number;
+    entities: readonly {
+        id: string;
+        hasPosition: boolean;
+        rotationY?: number;
+        valueKeys: readonly string[];
+    }[];
+    tunableKeys: readonly string[];
+    overrideIds: readonly string[];
+    play: RuntimePlayControl;
+}
+/** One resolved runtime field returned by `runtime_get`. */
+export interface RuntimeInspectorGetResult {
+    id: string;
+    kind: "entity" | "tunable" | "missing";
+    entity?: RuntimeEntityState;
+    path?: string;
+    value?: unknown;
+    override?: RuntimeEntityState;
+}
+/** Desired mutation from `runtime_set` before the host applies it. */
+export interface RuntimeInspectorSetPlan {
+    entity?: RuntimeEntityState;
+    tunable?: {
+        key: string;
+        value: unknown;
+    };
+    writeBackCommands: readonly EditorCommand[];
+    error?: string;
+}
+/**
+ * Builds the compact reverse-channel summary used by the play-mode inspector panel and the
+ * `runtime_summary` bridge RPC.
+ * @capability editor-runtime-inspector summarize live runtime entities and tunables for play mode
+ */
+export declare function summarizeRuntimeInspector(snapshot: RuntimeStateSnapshot, overrides: Readonly<Record<string, RuntimeEntityState>>, play: RuntimePlayControl): RuntimeInspectorSummary;
+/**
+ * Resolves one entity, entity field, or tunable from the reverse-channel snapshot (with overrides
+ * layered on top for entity rows).
+ * @capability editor-runtime-inspector read one live runtime entity field or tunable
+ */
+export declare function getRuntimeInspectorValue(snapshot: RuntimeStateSnapshot, overrides: Readonly<Record<string, RuntimeEntityState>>, id: string, path?: string): RuntimeInspectorGetResult;
+/**
+ * Plans a play-mode poke: builds the ephemeral entity/tunable override and, when `writeBack` is
+ * true, the undoable document commands that promote it into the scene document.
+ * @capability editor-runtime-inspector plan a play-mode runtime_set with optional document write-back
+ */
+export declare function planRuntimeInspectorSet(document: EditorDocument, input: {
+    id: string;
+    path?: string;
+    value?: unknown;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY?: number;
+    values?: Record<string, unknown>;
+    writeBack?: boolean;
+}): RuntimeInspectorSetPlan;
+/**
+ * Promotes ephemeral runtime `values` into an undoable meta patch on a document-linked object.
+ * Returns null when the id is not in the document or there are no values.
+ * @capability editor-runtime-inspector promote runtime entity values into a document meta write-back
+ */
+export declare function runtimeEntityMetaWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null;
+/**
+ * Advances the play-control step counter: when paused with pending steps, consumes one and reports
+ * whether the sim should run this frame. When not paused, always runs.
+ * @capability editor-runtime-inspector gate a play-mode frame against pause/step control
+ */
+export declare function consumeRuntimePlayStep(play: RuntimePlayControl): {
+    runFrame: boolean;
+    next: RuntimePlayControl;
+};
+/** Default play-control state when entering play mode (running). */
+export declare function createRuntimePlayControl(paused?: boolean): RuntimePlayControl;

package/dist/editor/runtimeInspector.js

@@ -0,0 +1,239 @@
+import { runtimeEntityWriteBackCommand, } from "./liveSync.js";
+/**
+ * Builds the compact reverse-channel summary used by the play-mode inspector panel and the
+ * `runtime_summary` bridge RPC.
+ * @capability editor-runtime-inspector summarize live runtime entities and tunables for play mode
+ */
+export function summarizeRuntimeInspector(snapshot, overrides, play) {
+    const entities = Object.values(snapshot.entities)
+        .map((entity) => ({
+        id: entity.id,
+        hasPosition: entity.position !== undefined,
+        ...(entity.rotationY === undefined ? {} : { rotationY: entity.rotationY }),
+        valueKeys: entity.values === undefined ? [] : Object.keys(entity.values).sort(),
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        seq: snapshot.seq,
+        entityCount: entities.length,
+        entities,
+        tunableKeys: Object.keys(snapshot.tunables).sort(),
+        overrideIds: Object.keys(overrides).sort(),
+        play: { paused: play.paused, pendingSteps: play.pendingSteps },
+    };
+}
+/**
+ * Resolves one entity, entity field, or tunable from the reverse-channel snapshot (with overrides
+ * layered on top for entity rows).
+ * @capability editor-runtime-inspector read one live runtime entity field or tunable
+ */
+export function getRuntimeInspectorValue(snapshot, overrides, id, path) {
+    if (id.startsWith("tunable:")) {
+        const key = id.slice("tunable:".length);
+        if (key.length === 0)
+            return { id, kind: "missing" };
+        if (!(key in snapshot.tunables) && path === undefined)
+            return { id, kind: "missing", path: key };
+        return {
+            id,
+            kind: "tunable",
+            path: key,
+            value: snapshot.tunables[key],
+        };
+    }
+    const base = snapshot.entities[id];
+    const override = overrides[id];
+    if (base === undefined && override === undefined) {
+        if (path !== undefined && path in snapshot.tunables) {
+            return { id: `tunable:${path}`, kind: "tunable", path, value: snapshot.tunables[path] };
+        }
+        return { id, kind: "missing", path };
+    }
+    const entity = {
+        id,
+        position: override?.position ?? base?.position,
+        rotationY: override?.rotationY ?? base?.rotationY,
+        values: override?.values === undefined && base?.values === undefined
+            ? undefined
+            : { ...base?.values, ...override?.values },
+    };
+    if (path === undefined || path === "") {
+        return { id, kind: "entity", entity, ...(override === undefined ? {} : { override }) };
+    }
+    if (path === "position") {
+        return { id, kind: "entity", entity, path, value: entity.position, ...(override === undefined ? {} : { override }) };
+    }
+    if (path === "rotationY") {
+        return { id, kind: "entity", entity, path, value: entity.rotationY, ...(override === undefined ? {} : { override }) };
+    }
+    if (path.startsWith("values.")) {
+        const key = path.slice("values.".length);
+        return {
+            id,
+            kind: "entity",
+            entity,
+            path,
+            value: entity.values?.[key],
+            ...(override === undefined ? {} : { override }),
+        };
+    }
+    return {
+        id,
+        kind: "entity",
+        entity,
+        path,
+        value: entity.values?.[path],
+        ...(override === undefined ? {} : { override }),
+    };
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function asPosition(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!isFiniteNumber(record.x) || !isFiniteNumber(record.y) || !isFiniteNumber(record.z))
+        return null;
+    return { x: record.x, y: record.y, z: record.z };
+}
+/**
+ * Plans a play-mode poke: builds the ephemeral entity/tunable override and, when `writeBack` is
+ * true, the undoable document commands that promote it into the scene document.
+ * @capability editor-runtime-inspector plan a play-mode runtime_set with optional document write-back
+ */
+export function planRuntimeInspectorSet(document, input) {
+    const writeBack = input.writeBack !== false;
+    const writeBackCommands = [];
+    if (input.id.startsWith("tunable:")) {
+        const key = input.id.slice("tunable:".length);
+        if (key.length === 0)
+            return { writeBackCommands, error: "tunable id is empty" };
+        if (input.value === undefined)
+            return { writeBackCommands, error: "tunable set requires value" };
+        return { tunable: { key, value: input.value }, writeBackCommands };
+    }
+    if (input.path !== undefined && input.path.startsWith("tunable:")) {
+        const key = input.path.slice("tunable:".length);
+        if (key.length === 0)
+            return { writeBackCommands, error: "tunable path is empty" };
+        if (input.value === undefined)
+            return { writeBackCommands, error: "tunable set requires value" };
+        return { tunable: { key, value: input.value }, writeBackCommands };
+    }
+    const entity = { id: input.id };
+    let touched = false;
+    if (input.position !== undefined) {
+        entity.position = { ...input.position };
+        touched = true;
+    }
+    if (input.rotationY !== undefined) {
+        if (!isFiniteNumber(input.rotationY))
+            return { writeBackCommands, error: "rotationY must be finite" };
+        entity.rotationY = input.rotationY;
+        touched = true;
+    }
+    if (input.values !== undefined) {
+        entity.values = { ...input.values };
+        touched = true;
+    }
+    if (input.path === "position") {
+        const position = asPosition(input.value);
+        if (position === null)
+            return { writeBackCommands, error: "position value must be {x,y,z}" };
+        entity.position = position;
+        touched = true;
+    }
+    else if (input.path === "rotationY") {
+        if (!isFiniteNumber(input.value))
+            return { writeBackCommands, error: "rotationY value must be finite" };
+        entity.rotationY = input.value;
+        touched = true;
+    }
+    else if (input.path !== undefined && input.path.startsWith("values.")) {
+        const key = input.path.slice("values.".length);
+        if (key.length === 0)
+            return { writeBackCommands, error: "values path is empty" };
+        entity.values = { [key]: input.value };
+        touched = true;
+    }
+    else if (input.path !== undefined && input.path.length > 0 && input.value !== undefined) {
+        entity.values = { [input.path]: input.value };
+        touched = true;
+    }
+    if (!touched) {
+        return { writeBackCommands, error: `runtime_set "${input.id}" has no position, rotationY, values, or path` };
+    }
+    if (writeBack) {
+        const transform = runtimeEntityWriteBackCommand(document, entity);
+        if (transform !== null)
+            writeBackCommands.push(transform);
+        if (entity.values !== undefined) {
+            const metaCommand = runtimeEntityMetaWriteBackCommand(document, entity);
+            if (metaCommand !== null)
+                writeBackCommands.push(metaCommand);
+        }
+    }
+    return { entity, writeBackCommands };
+}
+/**
+ * Promotes ephemeral runtime `values` into an undoable meta patch on a document-linked object.
+ * Returns null when the id is not in the document or there are no values.
+ * @capability editor-runtime-inspector promote runtime entity values into a document meta write-back
+ */
+export function runtimeEntityMetaWriteBackCommand(document, entity) {
+    if (entity.values === undefined || Object.keys(entity.values).length === 0)
+        return null;
+    const marker = document.markers.find((entry) => entry.id === entity.id);
+    if (marker !== undefined) {
+        return {
+            type: "setMarker",
+            id: entity.id,
+            patch: { meta: { ...marker.meta, ...entity.values } },
+        };
+    }
+    const volume = document.volumes.find((entry) => entry.id === entity.id);
+    if (volume !== undefined) {
+        return {
+            type: "setVolume",
+            id: entity.id,
+            patch: { meta: { ...volume.meta, ...entity.values } },
+        };
+    }
+    const path = document.paths.find((entry) => entry.id === entity.id);
+    if (path !== undefined) {
+        return {
+            type: "setPath",
+            id: entity.id,
+            patch: { meta: { ...path.meta, ...entity.values } },
+        };
+    }
+    const note = document.annotations.find((entry) => entry.id === entity.id);
+    if (note !== undefined) {
+        return {
+            type: "setNote",
+            id: entity.id,
+            patch: { meta: { ...note.meta, ...entity.values } },
+        };
+    }
+    return null;
+}
+/**
+ * Advances the play-control step counter: when paused with pending steps, consumes one and reports
+ * whether the sim should run this frame. When not paused, always runs.
+ * @capability editor-runtime-inspector gate a play-mode frame against pause/step control
+ */
+export function consumeRuntimePlayStep(play) {
+    if (!play.paused)
+        return { runFrame: true, next: play };
+    if (play.pendingSteps <= 0)
+        return { runFrame: false, next: play };
+    return {
+        runFrame: true,
+        next: { paused: true, pendingSteps: play.pendingSteps - 1 },
+    };
+}
+/** Default play-control state when entering play mode (running). */
+export function createRuntimePlayControl(paused = false) {
+    return { paused, pendingSteps: 0 };
+}

package/dist/editor/types.d.ts

@@ -0,0 +1,175 @@
+import type { ParamSchema } from "../scene/sceneKinds.js";
+import type { EditorUiDocument } from "../ui/hudDocument.js";
+import type { TerraformSnapshot } from "../world/terraform.js";
+import type { EditorGridLayer } from "./grid.js";
+export type { EditorUiDocument, EditorUiPanelLayout, HudResizeAxes, HudPanelTypeDef } from "../ui/hudDocument.js";
+/** A world-space point used across editor markers, volumes, and paths. */
+export type EditorVec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/** Collision shape a volume is rendered and tested as. */
+export type EditorVolumeShape = "sphere" | "cylinder" | "box";
+/** A placeable point object in the scene — spawn, mob, chest, POI, etc. */
+export interface EditorMarker {
+    id: string;
+    kind: string;
+    position: EditorVec3;
+    rotationY?: number;
+    color?: string;
+    label?: string;
+    /**
+     * Catalog object id for a placed prop mesh. Prefer this over `meta.catalogId` for new content;
+     * `resolveAuthoredObjects` still reads `meta.catalogId` as the migration alias.
+     */
+    catalogId?: string;
+    /** Id of the object this one is parented under; moving the parent moves this with it. */
+    parentId?: string;
+    meta?: Record<string, unknown>;
+}
+/** A spatial region — zone, aggro range, capture area — placed in the scene. */
+export interface EditorVolume {
+    id: string;
+    kind: string;
+    shape: EditorVolumeShape;
+    center: EditorVec3;
+    radius?: number;
+    height?: number;
+    halfExtents?: EditorVec3;
+    color?: string;
+    label?: string;
+    /** Id of the object this one is parented under; moving the parent moves this with it. */
+    parentId?: string;
+    meta?: Record<string, unknown>;
+}
+/** A polyline of points — road, corridor, patrol route — placed in the scene. */
+export interface EditorPath {
+    id: string;
+    kind: string;
+    points: readonly EditorVec3[];
+    width?: number;
+    color?: string;
+    label?: string;
+    /** Id of the object this one is parented under; moving the parent moves this with it. */
+    parentId?: string;
+    meta?: Record<string, unknown>;
+}
+/** A free-text annotation pinned to a world position for designers. */
+export interface EditorNote {
+    id: string;
+    text: string;
+    position: EditorVec3;
+    color?: string;
+    /** Id of the object this one is parented under; moving the parent moves this with it. */
+    parentId?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * A sculpted heightfield authored in the editor: the {@link TerraformSnapshot} of offset deltas
+ * over the game's base ground. Serializes with the scene; a game rebuilds the field with
+ * `editableTerrainFromSnapshot`.
+ */
+export type EditorTerrain = TerraformSnapshot;
+/** The four placeable-object collections a prefab fragment or clipboard fragment carries. */
+export interface EditorFragmentContent {
+    markers: readonly EditorMarker[];
+    volumes: readonly EditorVolume[];
+    paths: readonly EditorPath[];
+    annotations: readonly EditorNote[];
+}
+/**
+ * A serializable, reusable stamp of authored objects — markers/volumes/paths/notes centered on
+ * their own centroid so the same prefab inserts consistently anywhere, in this scene or another
+ * game's. `insertPrefab` tags every inserted object's `meta.prefabId`/`meta.prefabInstanceId`;
+ * `detachPrefabInstance` strips those tags to break the link without touching the content.
+ */
+export interface EditorPrefab {
+    id: string;
+    name: string;
+    fragment: EditorFragmentContent;
+}
+/**
+ * A named, persisted list of object ids — a selection bookmark (restore, add-to) that can also
+ * double as a production group: `locked` blocks `translate`/`setTransform`/`remove`/`removeMany`
+ * on its members, `color`/`visible` are UI-only hints for the collections panel.
+ */
+export interface EditorCollection {
+    id: string;
+    name: string;
+    memberIds: string[];
+    color?: string;
+    locked?: boolean;
+    visible?: boolean;
+}
+/**
+ * One row in a gameplay data catalog — id + optional label + a meta bag matching the catalog's
+ * `ParamSchema`. Values persist on the scene document; the schema lives in the game export.
+ * @capability editor-catalogs Persist and load one gameplay catalog entry's tuned params.
+ */
+export interface EditorCatalogEntry {
+    id: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Persisted values for one gameplay data catalog (weapons, waves, economy, …). Schemas are not
+ * stored here — they come from the game's `editorCatalogs` export and drive SchemaInspector.
+ * @capability editor-catalogs Persist gameplay tuning rows on the scene document.
+ */
+export interface EditorCatalogData {
+    id: string;
+    entries: EditorCatalogEntry[];
+}
+/**
+ * Game-exported catalog definition: a `ParamSchema` plus default entries. Schemas stay in code;
+ * entry values merge into `document.catalogs` and are what the editor/RPC edits and saves.
+ * @capability editor-catalogs Export typed gameplay catalogs for in-editor tuning.
+ */
+export interface EditorCatalogDefinition {
+    id: string;
+    label: string;
+    schema: ParamSchema;
+    entries: readonly EditorCatalogEntry[];
+}
+/** Accepted shape for a game's `editorCatalogs` export: definitions, or a factory. */
+export type EditorCatalogsInput = readonly EditorCatalogDefinition[] | (() => readonly EditorCatalogDefinition[]);
+/** The full authored scene: every marker, volume, path, note, and sculpted terrain for a game. */
+export interface EditorDocument {
+    version: 1;
+    markers: EditorMarker[];
+    volumes: EditorVolume[];
+    paths: EditorPath[];
+    annotations: EditorNote[];
+    /** Optional sculpted heightfield overlay; absent until terrain is created in the editor. */
+    terrain?: EditorTerrain;
+    /** Reusable object stamps authored with "make prefab", inserted anywhere with "insert prefab". */
+    prefabs: EditorPrefab[];
+    /** Named selection sets / production groups — restore, add-to, lock, color, visibility. */
+    collections: EditorCollection[];
+    /** Persisted gameplay catalog values; schemas come from the game's `editorCatalogs` export. */
+    catalogs: EditorCatalogData[];
+    /**
+     * Editor-owned grid/tile layers — sparse `col,row` → value-id maps authored in the editor and
+     * read by runtime + rendering through `@jgengine/core/editor/grid`. Absent until a game or the
+     * editor adds a grid layer, so existing documents load unchanged.
+     */
+    grids?: EditorGridLayer[];
+    /**
+     * HUD layout owned by the scene document — panel id → anchor/offset/size/visibility.
+     * Canvas mode (F2+C) and `canvas_move_panel` / `canvas_resize_panel` write here; HudPanel reads it.
+     */
+    ui?: EditorUiDocument;
+}
+/** Accepted shape for a game's `editorLayers` export: a document, partial data, or a factory. */
+export type EditorLayersInput = EditorDocument | Partial<Omit<EditorDocument, "version">> | (() => EditorDocument | Partial<Omit<EditorDocument, "version">>);
+/** Per-kind show/hide flags for the editor's layer panel. */
+export interface EditorKindVisibility {
+    [kind: string]: boolean;
+}
+/** Standard marker kinds recognized with default colors and behavior. */
+export declare const WELL_KNOWN_MARKER_KINDS: readonly ["player_spawn", "mob", "boss", "vendor", "chest", "travel", "npc", "poi", "prop", "goal", "branch"];
+/** Standard volume kinds recognized with default colors and behavior. */
+export declare const WELL_KNOWN_VOLUME_KINDS: readonly ["zone", "flatten", "cluster", "aggro", "leash", "discover", "capture", "prompt", "poi", "respawn_skip"];
+/** Standard path kinds recognized with default colors and behavior. */
+export declare const WELL_KNOWN_PATH_KINDS: readonly ["road", "corridor", "branch", "route"];

package/dist/editor/types.js

@@ -0,0 +1,29 @@
+/** Standard marker kinds recognized with default colors and behavior. */
+export const WELL_KNOWN_MARKER_KINDS = [
+    "player_spawn",
+    "mob",
+    "boss",
+    "vendor",
+    "chest",
+    "travel",
+    "npc",
+    "poi",
+    "prop",
+    "goal",
+    "branch",
+];
+/** Standard volume kinds recognized with default colors and behavior. */
+export const WELL_KNOWN_VOLUME_KINDS = [
+    "zone",
+    "flatten",
+    "cluster",
+    "aggro",
+    "leash",
+    "discover",
+    "capture",
+    "prompt",
+    "poi",
+    "respawn_skip",
+];
+/** Standard path kinds recognized with default colors and behavior. */
+export const WELL_KNOWN_PATH_KINDS = ["road", "corridor", "branch", "route"];

package/dist/faction/reputation.d.ts

@@ -5,6 +5,11 @@ export interface ReputationTier {
     relation: FactionRelation;
 }
 export declare const DEFAULT_REPUTATION_TIERS: readonly ReputationTier[];
+/**
+ * Map a faction standing value to its named reputation tier.
+ *
+ * @capability reputation faction standing that crosses named reputation tiers
+ */
 export declare function tierForStanding(tiers: readonly ReputationTier[], standing: number): ReputationTier;
 export interface ReputationLedgerConfig {
     tiers?: readonly ReputationTier[];

package/dist/faction/reputation.js

@@ -8,6 +8,11 @@ export const DEFAULT_REPUTATION_TIERS = [
     { id: "revered", min: 21000, relation: "friendly" },
     { id: "exalted", min: 42000, relation: "friendly" },
 ];
+/**
+ * Map a faction standing value to its named reputation tier.
+ *
+ * @capability reputation faction standing that crosses named reputation tiers
+ */
 export function tierForStanding(tiers, standing) {
     let match = tiers[0];
     for (const tier of tiers) {

package/dist/format/distance.d.ts

@@ -0,0 +1,17 @@
+/** Target unit for {@link formatDistance}: meters, kilometers, or `"auto"` (km past 1000m). */
+export type DistanceUnit = "m" | "km" | "auto";
+/** Options for {@link formatDistance}. */
+export interface DistanceFormat {
+    /** Target unit. `"auto"` switches to km at 1000m and above. Defaults to `"m"`. */
+    unit?: DistanceUnit;
+    /** Fractional digits to show. Defaults to 0 for meters, 1 for kilometers. */
+    decimals?: 0 | 1 | 2;
+    /** Append the unit label. Defaults to true; set false to compose custom unit styling. */
+    showUnit?: boolean;
+}
+/**
+ * Format a distance given in meters as a HUD-ready string, switching to km automatically past 1000m when `unit: "auto"`.
+ *
+ * @capability distance-format render meters as m or km for HUD stats, telemetry, and range readouts
+ */
+export declare function formatDistance(meters: number, options?: DistanceFormat): string;

package/dist/format/distance.js

@@ -0,0 +1,18 @@
+const AUTO_KM_THRESHOLD = 1000;
+/**
+ * Format a distance given in meters as a HUD-ready string, switching to km automatically past 1000m when `unit: "auto"`.
+ *
+ * @capability distance-format render meters as m or km for HUD stats, telemetry, and range readouts
+ */
+export function formatDistance(meters, options = {}) {
+    const requested = options.unit ?? "m";
+    const clamped = Math.max(0, meters);
+    const showUnit = options.showUnit ?? true;
+    const useKm = requested === "km" || (requested === "auto" && clamped >= AUTO_KM_THRESHOLD);
+    if (useKm) {
+        const text = (clamped / 1000).toFixed(options.decimals ?? 1);
+        return showUnit ? `${text}km` : text;
+    }
+    const text = clamped.toFixed(options.decimals ?? 0);
+    return showUnit ? `${text}m` : text;
+}

package/dist/format/duration.d.ts

@@ -0,0 +1,27 @@
+/** Options for {@link formatDuration}. */
+export interface DurationFormat {
+    /** Fractional-second digits to show (0, 1, or 2). Defaults to 0. */
+    decimals?: 0 | 1 | 2;
+    /** Force an `h:mm:ss` layout even under an hour. Defaults to auto (hours shown only when present). */
+    hours?: boolean;
+}
+/** Left-pad a non-negative integer to `width` digits with leading zeros. */
+export declare function padNumber(value: number, width: number): string;
+/**
+ * Format a duration in seconds as a clock string (`m:ss`, `m:ss.ff`, or `h:mm:ss`), the shape every timer and racing HUD needs.
+ *
+ * @capability clock-format render seconds as m:ss / m:ss.ff / h:mm:ss for timers and race HUDs
+ */
+export declare function formatDuration(seconds: number, options?: DurationFormat): string;
+/**
+ * Format a signed time gap as `+m:ss.ff` / `-m:ss.ff`, for race deltas and split times.
+ *
+ * @capability clock-format format a signed time gap like a race split (+/- m:ss.ff)
+ */
+export declare function formatDelta(seconds: number, decimals?: 0 | 1 | 2): string;
+/**
+ * English ordinal for a placement number: 1 → "1st", 2 → "2nd", 3 → "3rd", 11 → "11th".
+ *
+ * @capability ordinal-format format a placement number as 1st/2nd/3rd for HUD ranks
+ */
+export declare function formatOrdinal(value: number): string;

package/dist/format/duration.js

@@ -0,0 +1,45 @@
+/** Left-pad a non-negative integer to `width` digits with leading zeros. */
+export function padNumber(value, width) {
+    return Math.trunc(value).toString().padStart(width, "0");
+}
+/**
+ * Format a duration in seconds as a clock string (`m:ss`, `m:ss.ff`, or `h:mm:ss`), the shape every timer and racing HUD needs.
+ *
+ * @capability clock-format render seconds as m:ss / m:ss.ff / h:mm:ss for timers and race HUDs
+ */
+export function formatDuration(seconds, options = {}) {
+    const decimals = options.decimals ?? 0;
+    const total = Math.max(0, seconds);
+    const whole = Math.floor(total);
+    const frac = decimals > 0 ? (total - whole).toFixed(decimals).slice(1) : "";
+    const showHours = options.hours ?? total >= 3600;
+    if (showHours) {
+        const h = Math.floor(whole / 3600);
+        const m = Math.floor((whole % 3600) / 60);
+        const s = whole % 60;
+        return `${h}:${padNumber(m, 2)}:${padNumber(s, 2)}${frac}`;
+    }
+    const m = Math.floor(whole / 60);
+    const s = whole % 60;
+    return `${m}:${padNumber(s, 2)}${frac}`;
+}
+/**
+ * Format a signed time gap as `+m:ss.ff` / `-m:ss.ff`, for race deltas and split times.
+ *
+ * @capability clock-format format a signed time gap like a race split (+/- m:ss.ff)
+ */
+export function formatDelta(seconds, decimals = 2) {
+    const sign = seconds < 0 ? "-" : "+";
+    return `${sign}${formatDuration(Math.abs(seconds), { decimals })}`;
+}
+/**
+ * English ordinal for a placement number: 1 → "1st", 2 → "2nd", 3 → "3rd", 11 → "11th".
+ *
+ * @capability ordinal-format format a placement number as 1st/2nd/3rd for HUD ranks
+ */
+export function formatOrdinal(value) {
+    const n = Math.trunc(value);
+    const abs = Math.abs(n) % 100;
+    const suffix = abs >= 11 && abs <= 13 ? "th" : ["th", "st", "nd", "rd"][Math.abs(n) % 10] ?? "th";
+    return `${n}${suffix}`;
+}