@jgengine/core 0.10.0 → 0.12.0

package/dist/ui.d.ts

@@ -0,0 +1,15 @@
+export { formatDistance } from "./format/distance.js";
+export { formatDelta, formatDuration, formatOrdinal } from "./format/duration.js";
+export { formatSpeed } from "./format/speed.js";
+export { resolveGameLook, type LookPreset } from "./render/lookPreset.js";
+export { STUDIO_STAGE_POST, type GradeConfig, type PostProcessingConfig, type ToneMappingMode, } from "./render/postProcessing.js";
+export { BUILT_IN_SETTING_CATEGORIES, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, busVolumeSettingId, createSettingsStore, type GameSettingDef, type GameSettingsConfig, type GraphicsQuality, type SettingCategory, type SettingCategoryDef, type SettingKind, type SettingOption, type SettingValue, type SettingsActionDef, type SettingsStore, type SettingsSurface, type SettingsVariant, } from "./settings/settingsModel.js";
+export { actionByHotkey, actionCooldown, actionCooldownFromFraction, actionCost, moveGridFocus, resolveAction, resolveActionCollection, type ActionCooldown, type ActionCost, type ActionDef, type ActionReason, type FocusDirection, type GridFocusOptions, type ResolvedAction, } from "./ui/actionModel.js";
+export { type GameLayoutMode, type GameViewportLayout, type HudPriority, type Insets, type LayoutCollision, type LayoutCollisionPolicy, type LayoutRect, type LayoutRegion, type MobileHudBehavior, } from "./ui/gameLayout.js";
+export { listHudPanelTypes, registerHudPanelType, resizePanelSize, resolveHudPanelLayout, type EditorUiDocument, type EditorUiPanelLayout, type HudResizeAxes, } from "./ui/hudDocument.js";
+export { HUD_ANCHOR_FRACTIONS, type HudAnchor, type HudLayoutStore, type HudPlacement, type HudSize, } from "./ui/hudLayout.js";
+export { hudScaleForViewport, overflowingPanels, resolveHudFit, type HudPlatform, type HudViewportConfig, } from "./ui/hudScale.js";
+export { orientationGateActive, orientationHintActive, resolveOrientationRequirement, type LayoutOrientation, } from "./ui/orientation.js";
+export { moveSelectionFocus, selectionWindow, summarizeSelection, type EntitySummaryDef, type EntityVital, type SelectionFocusDirection, type SelectionGroup, type SelectionView, type SelectionWindow, type SummarizeSelectionOptions, } from "./ui/selectionModel.js";
+export { swingTimerState, type SwingTargetInput } from "./ui/swingTimer.js";
+export { actionTooltip, placePopover, type PopoverOptions, type PopoverPlacement, type PopoverSide, type TooltipContent, type UiRect, type UiSize, } from "./ui/tooltipModel.js";

package/dist/ui.js

@@ -0,0 +1,15 @@
+export { formatDistance } from "./format/distance.js";
+export { formatDelta, formatDuration, formatOrdinal } from "./format/duration.js";
+export { formatSpeed } from "./format/speed.js";
+export { resolveGameLook } from "./render/lookPreset.js";
+export { STUDIO_STAGE_POST, } from "./render/postProcessing.js";
+export { BUILT_IN_SETTING_CATEGORIES, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, busVolumeSettingId, createSettingsStore, } from "./settings/settingsModel.js";
+export { actionByHotkey, actionCooldown, actionCooldownFromFraction, actionCost, moveGridFocus, resolveAction, resolveActionCollection, } from "./ui/actionModel.js";
+export {} from "./ui/gameLayout.js";
+export { listHudPanelTypes, registerHudPanelType, resizePanelSize, resolveHudPanelLayout, } from "./ui/hudDocument.js";
+export { HUD_ANCHOR_FRACTIONS, } from "./ui/hudLayout.js";
+export { hudScaleForViewport, overflowingPanels, resolveHudFit, } from "./ui/hudScale.js";
+export { orientationGateActive, orientationHintActive, resolveOrientationRequirement, } from "./ui/orientation.js";
+export { moveSelectionFocus, selectionWindow, summarizeSelection, } from "./ui/selectionModel.js";
+export { swingTimerState } from "./ui/swingTimer.js";
+export { actionTooltip, placePopover, } from "./ui/tooltipModel.js";

package/dist/visibility/bounds.d.ts

@@ -42,11 +42,17 @@ export type BoundsSpec = {
 };
 /** Conservative default: a unit sphere. Objects without explicit bounds cull as a small volume, never a point. */
 export declare const DEFAULT_BOUNDS: BoundsSpec;
+/** @internal */
 export declare function createRenderBounds(): RenderBounds;
-/** Resolve a spec + world position into concrete bounds. Writes into `out` when supplied (no allocation). */
+/** Resolve a spec + world position into concrete bounds. Writes into `out` when supplied (no allocation).
+ * @internal
+ */
 export declare function resolveBounds(spec: BoundsSpec, position: Vec3, out?: RenderBounds): RenderBounds;
+/** @internal */
 export declare function expandRenderBounds(bounds: RenderBounds, margin: number, out?: RenderBounds): RenderBounds;
+/** @internal */
 export declare function aabbIntersects(aMinX: number, aMinY: number, aMinZ: number, aMaxX: number, aMaxY: number, aMaxZ: number, bMinX: number, bMinY: number, bMinZ: number, bMaxX: number, bMaxY: number, bMaxZ: number): boolean;
+/** @internal */
 export declare function boundsIntersect(a: RenderBounds, b: RenderBounds): boolean;
 /**
  * BoundsSystem: caches resolved bounds per object and recomputes only when the caller's
@@ -63,4 +69,5 @@ export interface BoundsCache {
     size(): number;
     recomputes(): number;
 }
+/** @internal */
 export declare function createBoundsCache(): BoundsCache;

package/dist/visibility/bounds.js

@@ -1,5 +1,6 @@
 /** Conservative default: a unit sphere. Objects without explicit bounds cull as a small volume, never a point. */
 export const DEFAULT_BOUNDS = { kind: "sphere", radius: 1 };
+/** @internal */
 export function createRenderBounds() {
     return {
         centerX: 0,
@@ -27,7 +28,9 @@ function fillBounds(out, cx, cy, cz, hx, hy, hz) {
     out.radius = Math.sqrt(hx * hx + hy * hy + hz * hz);
     return out;
 }
-/** Resolve a spec + world position into concrete bounds. Writes into `out` when supplied (no allocation). */
+/** Resolve a spec + world position into concrete bounds. Writes into `out` when supplied (no allocation).
+ * @internal
+ */
 export function resolveBounds(spec, position, out = createRenderBounds()) {
     if (spec.kind === "point") {
         return fillBounds(out, position[0], position[1], position[2], 0, 0, 0);
@@ -49,6 +52,7 @@ export function resolveBounds(spec, position, out = createRenderBounds()) {
             return fillBounds(out, cx, cy, cz, spec.halfWidth, spec.halfHeight ?? 0, spec.halfDepth);
     }
 }
+/** @internal */
 export function expandRenderBounds(bounds, margin, out = createRenderBounds()) {
     out.centerX = bounds.centerX;
     out.centerY = bounds.centerY;
@@ -62,14 +66,17 @@ export function expandRenderBounds(bounds, margin, out = createRenderBounds()) {
     out.maxZ = bounds.maxZ + margin;
     return out;
 }
+/** @internal */
 export function aabbIntersects(aMinX, aMinY, aMinZ, aMaxX, aMaxY, aMaxZ, bMinX, bMinY, bMinZ, bMaxX, bMaxY, bMaxZ) {
     return (aMinX <= bMaxX && aMaxX >= bMinX &&
         aMinY <= bMaxY && aMaxY >= bMinY &&
         aMinZ <= bMaxZ && aMaxZ >= bMinZ);
 }
+/** @internal */
 export function boundsIntersect(a, b) {
     return aabbIntersects(a.minX, a.minY, a.minZ, a.maxX, a.maxY, a.maxZ, b.minX, b.minY, b.minZ, b.maxX, b.maxY, b.maxZ);
 }
+/** @internal */
 export function createBoundsCache() {
     const entries = new Map();
     let recomputes = 0;

package/dist/visibility/frustum.d.ts

@@ -36,12 +36,21 @@ export interface Frustum {
     maxY: number;
     maxZ: number;
 }
+/** @internal */
 export declare function createFrustum(): Frustum;
+/** @internal */
 export declare function updateFrustum(out: Frustum, view: CameraView): Frustum;
-/** Conservative AABB-vs-frustum: never a false negative (may keep a corner-case that is truly outside). */
+/** Conservative AABB-vs-frustum: never a false negative (may keep a corner-case that is truly outside).
+ * @internal
+ */
 export declare function aabbInFrustum(f: Frustum, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): boolean;
+/** @internal */
 export declare function sphereInFrustum(f: Frustum, cx: number, cy: number, cz: number, radius: number): boolean;
-/** Sphere broad-phase reject, then the tight AABB test. Both conservative. */
+/** Sphere broad-phase reject, then the tight AABB test. Both conservative.
+ * @internal
+ */
 export declare function boundsInFrustum(f: Frustum, b: RenderBounds): boolean;
-/** Push every plane outward by `margin` (unit normals ⇒ d += margin) to form a preload/hysteresis region. */
+/** Push every plane outward by `margin` (unit normals ⇒ d += margin) to form a preload/hysteresis region.
+ * @internal
+ */
 export declare function dilateFrustum(src: Frustum, margin: number, out: Frustum): Frustum;

package/dist/visibility/frustum.js

@@ -1,5 +1,6 @@
 const WORLD_UP = [0, 1, 0];
 const ALT_UP = [1, 0, 0];
+/** @internal */
 export function createFrustum() {
     return {
         planes: new Float64Array(24),
@@ -43,6 +44,7 @@ function planeFromCorners(planes, slot, corners, a, b, c, centroidX, centroidY,
     planes[slot * 4 + 2] = nz;
     planes[slot * 4 + 3] = d;
 }
+/** @internal */
 export function updateFrustum(out, view) {
     const { position, target } = view;
     let fx = target[0] - position[0];
@@ -137,7 +139,9 @@ export function updateFrustum(out, view) {
     planeFromCorners(planes, 5, corners, 2, 3, 6, cX, cY, cZ); // bottom
     return out;
 }
-/** Conservative AABB-vs-frustum: never a false negative (may keep a corner-case that is truly outside). */
+/** Conservative AABB-vs-frustum: never a false negative (may keep a corner-case that is truly outside).
+ * @internal
+ */
 export function aabbInFrustum(f, minX, minY, minZ, maxX, maxY, maxZ) {
     const planes = f.planes;
     for (let i = 0; i < 6; i += 1) {
@@ -150,6 +154,7 @@ export function aabbInFrustum(f, minX, minY, minZ, maxX, maxY, maxZ) {
     }
     return true;
 }
+/** @internal */
 export function sphereInFrustum(f, cx, cy, cz, radius) {
     const planes = f.planes;
     for (let i = 0; i < 6; i += 1) {
@@ -159,13 +164,17 @@ export function sphereInFrustum(f, cx, cy, cz, radius) {
     }
     return true;
 }
-/** Sphere broad-phase reject, then the tight AABB test. Both conservative. */
+/** Sphere broad-phase reject, then the tight AABB test. Both conservative.
+ * @internal
+ */
 export function boundsInFrustum(f, b) {
     if (!sphereInFrustum(f, b.centerX, b.centerY, b.centerZ, b.radius))
         return false;
     return aabbInFrustum(f, b.minX, b.minY, b.minZ, b.maxX, b.maxY, b.maxZ);
 }
-/** Push every plane outward by `margin` (unit normals ⇒ d += margin) to form a preload/hysteresis region. */
+/** Push every plane outward by `margin` (unit normals ⇒ d += margin) to form a preload/hysteresis region.
+ * @internal
+ */
 export function dilateFrustum(src, margin, out) {
     const sp = src.planes;
     const op = out.planes;

package/dist/work/jobQueue.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Generic timed work queue — a pure-data model for discrete jobs that reserve
+ * inputs, advance over game time, can be paused/cancelled, and emit an output on
+ * completion. It backs unit training, crafting jobs, construction, research,
+ * respawns, downloads, and fabrication without any of them re-implementing the
+ * reservation → progress → completion → output-routing loop.
+ *
+ * The state ({@link WorkQueueState}) is plain serializable data; all policy —
+ * duration, ordering, capacity, concurrency, input reservation, refund, and
+ * output mapping — lives in {@link WorkQueueConfig}, which is supplied by the
+ * caller and is never serialized. Side effects (charging a wallet, spawning an
+ * entity) are the caller's: reservations and refunds are returned as data, and
+ * completion emits a typed event carrying a pure output payload for an external
+ * completion adapter to route.
+ */
+export type JobId = string;
+/** Lifecycle phase of a single queued job. Terminal jobs are removed from state. */
+export type JobStatus = "queued" | "active" | "paused";
+/** One unit of timed work. Plain serializable data (given serializable `TSpec`/`TReserve`). */
+export interface Job<TSpec, TReserve = undefined> {
+    /** Stable id, unique within the queue for its lifetime. */
+    readonly id: JobId;
+    /** Caller-owned description of the work (e.g. `{ unitId }`). */
+    readonly spec: TSpec;
+    /** Reserved inputs computed at enqueue time (e.g. resource cost, population). */
+    readonly reservation: TReserve;
+    readonly status: JobStatus;
+    /** Seconds of work the job requires. */
+    readonly duration: number;
+    /** Seconds of work completed so far (0…duration). */
+    readonly elapsed: number;
+    /** Higher runs sooner under priority ordering; FIFO within equal priority. */
+    readonly priority: number;
+    /** Monotonic enqueue index — the FIFO tiebreak. */
+    readonly seq: number;
+}
+/** Serializable queue state. Holds only non-terminal jobs, so it stays bounded. */
+export interface WorkQueueState<TSpec, TReserve = undefined> {
+    readonly jobs: readonly Job<TSpec, TReserve>[];
+    readonly nextId: number;
+    readonly seq: number;
+}
+/** Comparator over jobs; negative means the first job runs sooner. */
+export type JobOrdering<TSpec, TReserve = undefined> = (a: Job<TSpec, TReserve>, b: Job<TSpec, TReserve>) => number;
+/** Result of pre-enqueue validation (population caps, prerequisites, affordability). */
+export interface JobValidation {
+    readonly ok: boolean;
+    readonly reason?: string;
+}
+/** Optional per-enqueue overrides. */
+export interface EnqueueOptions {
+    /** Higher runs sooner under priority ordering. Defaults to 0. */
+    readonly priority?: number;
+    /** Explicit id; defaults to a queue-assigned `job-<n>`. */
+    readonly id?: string;
+}
+/**
+ * Injected policy for a queue. Never serialized — pass the same config to every
+ * {@link enqueue}/{@link tick}/{@link cancelJob} call for a given queue.
+ */
+export interface WorkQueueConfig<TSpec, TReserve = undefined, TOutput = undefined> {
+    /** Seconds of work a spec requires. Negative values clamp to 0 (instant). */
+    duration: (spec: TSpec) => number;
+    /** Max concurrent active jobs (multi-server queue). Defaults to 1. */
+    concurrency?: number;
+    /** Max non-terminal jobs; further enqueues are rejected with `"capacity"`. */
+    capacity?: number;
+    /** Selection order for queued jobs. Defaults to {@link priorityOrdering}. */
+    ordering?: JobOrdering<TSpec, TReserve>;
+    /** Compute the reservation stored on the job (charge-now is the caller's job). */
+    reserve?: (spec: TSpec) => TReserve;
+    /** Validate before enqueue; a non-ok result rejects with its reason. */
+    validate?: (spec: TSpec, state: WorkQueueState<TSpec, TReserve>) => JobValidation;
+    /** Map a completed job to its output payload for a completion adapter to route. */
+    output?: (job: Job<TSpec, TReserve>) => TOutput;
+    /** Compute a refund on cancellation from the reservation and progress (0…1). */
+    refund?: (job: Job<TSpec, TReserve>, progress: number) => TReserve | null;
+}
+/** Typed lifecycle event emitted from {@link tick}. */
+export type WorkQueueEvent<TSpec, TReserve = undefined, TOutput = undefined> = {
+    readonly type: "started";
+    readonly job: Job<TSpec, TReserve>;
+} | {
+    readonly type: "completed";
+    readonly job: Job<TSpec, TReserve>;
+    readonly output: TOutput;
+};
+/** Outcome of {@link tick}: advanced state plus the events produced. */
+export interface TickResult<TSpec, TReserve = undefined, TOutput = undefined> {
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly events: readonly WorkQueueEvent<TSpec, TReserve, TOutput>[];
+}
+/** Outcome of {@link enqueue}. On rejection the state is returned unchanged. */
+export type EnqueueResult<TSpec, TReserve = undefined> = {
+    readonly ok: true;
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly job: Job<TSpec, TReserve>;
+} | {
+    readonly ok: false;
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly reason: string;
+};
+/** Outcome of {@link cancelJob}, carrying the removed job and its computed refund. */
+export type CancelResult<TSpec, TReserve = undefined> = {
+    readonly ok: true;
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly job: Job<TSpec, TReserve>;
+    readonly refund: TReserve | null;
+} | {
+    readonly ok: false;
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly reason: string;
+};
+/**
+ * Pure FIFO ordering by enqueue sequence.
+ *
+ * @capability work-order-fifo order queued jobs by enqueue sequence
+ */
+export declare function fifoOrdering<TSpec, TReserve = undefined>(a: Job<TSpec, TReserve>, b: Job<TSpec, TReserve>): number;
+/**
+ * Priority-first ordering (higher priority sooner), FIFO within equal priority.
+ *
+ * @capability work-order-priority order queued jobs by priority, then FIFO within equal priority
+ */
+export declare function priorityOrdering<TSpec, TReserve = undefined>(a: Job<TSpec, TReserve>, b: Job<TSpec, TReserve>): number;
+/**
+ * Create an empty timed work queue.
+ *
+ * @capability work-queue a serializable timed job queue with reservation, cancellation, completion, and output routing
+ */
+export declare function createWorkQueue<TSpec, TReserve = undefined>(): WorkQueueState<TSpec, TReserve>;
+/**
+ * Non-terminal job count (queued + active + paused).
+ *
+ * @capability work-queue-size count non-terminal jobs in a work queue
+ */
+export declare function queueSize<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>): number;
+/**
+ * Look up a job by id, or `null` if absent/terminal.
+ *
+ * @capability work-job-by-id look up a queued job by id
+ */
+export declare function jobById<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>, id: JobId): Job<TSpec, TReserve> | null;
+/**
+ * Jobs waiting for a slot, in selection order.
+ *
+ * @capability work-queued-jobs list jobs waiting for a slot, in selection order
+ */
+export declare function queuedJobs<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>, ordering?: JobOrdering<TSpec, TReserve>): Job<TSpec, TReserve>[];
+/**
+ * Jobs currently progressing.
+ *
+ * @capability work-active-jobs list jobs currently progressing in a work queue
+ */
+export declare function activeJobs<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>): Job<TSpec, TReserve>[];
+/**
+ * Fractional progress of a job (0…1); a zero-duration job reads as complete.
+ *
+ * @capability work-job-progress compute a job's fractional progress
+ */
+export declare function jobProgress<TSpec, TReserve>(job: Job<TSpec, TReserve>): number;
+/**
+ * Enqueue a new job. Validates capacity and the injected `validate` policy, then
+ * computes and stores the reservation. Charging the reservation (now or later) is
+ * the caller's responsibility using {@link EnqueueResult.job}'s `reservation`.
+ *
+ * @capability enqueue-work reserve inputs and add a timed job, honoring capacity and validation policy
+ */
+export declare function enqueue<TSpec, TReserve, TOutput>(state: WorkQueueState<TSpec, TReserve>, config: WorkQueueConfig<TSpec, TReserve, TOutput>, spec: TSpec, options?: EnqueueOptions): EnqueueResult<TSpec, TReserve>;
+/**
+ * Cancel a job and compute its refund. Removes the job from the queue and returns
+ * a refund payload (full reservation by default, or `config.refund` applied to the
+ * job's progress for partial/no refund). Applying the refund is the caller's job.
+ *
+ * @capability cancel-work remove a job and compute its refund from reservation and progress
+ */
+export declare function cancelJob<TSpec, TReserve, TOutput>(state: WorkQueueState<TSpec, TReserve>, config: WorkQueueConfig<TSpec, TReserve, TOutput>, id: JobId): CancelResult<TSpec, TReserve>;
+/**
+ * Pause a queued or active job in place; a paused job keeps its progress and yields its slot.
+ *
+ * @capability pause-work pause a queued or active job in place, retaining its progress
+ */
+export declare function pauseJob<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>, id: JobId): WorkQueueState<TSpec, TReserve>;
+/**
+ * Resume a paused job; it re-enters the queue and competes for a slot by ordering.
+ *
+ * @capability resume-work resume a paused job back into the queue's slot competition
+ */
+export declare function resumeJob<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>, id: JobId): WorkQueueState<TSpec, TReserve>;
+/**
+ * Advance the queue by `dt` seconds. Promotes queued jobs into up to `concurrency`
+ * active slots, advances active jobs, and completes those that reach their
+ * duration — emitting `started`/`completed` events in deterministic order. A large
+ * `dt` catches up across many jobs in one call: when a job completes with leftover
+ * time, the freed slot promotes the next queued job and applies the remainder, so a
+ * reconnect or save/load gap resolves in a single bounded pass. Completed jobs are
+ * removed from the returned state.
+ *
+ * @capability tick-work advance jobs over time, completing work and emitting typed lifecycle events
+ */
+export declare function tick<TSpec, TReserve, TOutput>(state: WorkQueueState<TSpec, TReserve>, config: WorkQueueConfig<TSpec, TReserve, TOutput>, dt: number): TickResult<TSpec, TReserve, TOutput>;

package/dist/work/jobQueue.js

@@ -0,0 +1,253 @@
+/**
+ * Generic timed work queue — a pure-data model for discrete jobs that reserve
+ * inputs, advance over game time, can be paused/cancelled, and emit an output on
+ * completion. It backs unit training, crafting jobs, construction, research,
+ * respawns, downloads, and fabrication without any of them re-implementing the
+ * reservation → progress → completion → output-routing loop.
+ *
+ * The state ({@link WorkQueueState}) is plain serializable data; all policy —
+ * duration, ordering, capacity, concurrency, input reservation, refund, and
+ * output mapping — lives in {@link WorkQueueConfig}, which is supplied by the
+ * caller and is never serialized. Side effects (charging a wallet, spawning an
+ * entity) are the caller's: reservations and refunds are returned as data, and
+ * completion emits a typed event carrying a pure output payload for an external
+ * completion adapter to route.
+ */
+/**
+ * Pure FIFO ordering by enqueue sequence.
+ *
+ * @capability work-order-fifo order queued jobs by enqueue sequence
+ */
+export function fifoOrdering(a, b) {
+    return a.seq - b.seq;
+}
+/**
+ * Priority-first ordering (higher priority sooner), FIFO within equal priority.
+ *
+ * @capability work-order-priority order queued jobs by priority, then FIFO within equal priority
+ */
+export function priorityOrdering(a, b) {
+    return b.priority - a.priority || a.seq - b.seq;
+}
+/**
+ * Create an empty timed work queue.
+ *
+ * @capability work-queue a serializable timed job queue with reservation, cancellation, completion, and output routing
+ */
+export function createWorkQueue() {
+    return { jobs: [], nextId: 1, seq: 0 };
+}
+/**
+ * Non-terminal job count (queued + active + paused).
+ *
+ * @capability work-queue-size count non-terminal jobs in a work queue
+ */
+export function queueSize(state) {
+    return state.jobs.length;
+}
+/**
+ * Look up a job by id, or `null` if absent/terminal.
+ *
+ * @capability work-job-by-id look up a queued job by id
+ */
+export function jobById(state, id) {
+    return state.jobs.find((job) => job.id === id) ?? null;
+}
+/**
+ * Jobs waiting for a slot, in selection order.
+ *
+ * @capability work-queued-jobs list jobs waiting for a slot, in selection order
+ */
+export function queuedJobs(state, ordering = priorityOrdering) {
+    return state.jobs.filter((job) => job.status === "queued").sort(ordering);
+}
+/**
+ * Jobs currently progressing.
+ *
+ * @capability work-active-jobs list jobs currently progressing in a work queue
+ */
+export function activeJobs(state) {
+    return state.jobs.filter((job) => job.status === "active");
+}
+/**
+ * Fractional progress of a job (0…1); a zero-duration job reads as complete.
+ *
+ * @capability work-job-progress compute a job's fractional progress
+ */
+export function jobProgress(job) {
+    if (job.duration <= 0)
+        return 1;
+    return Math.min(1, Math.max(0, job.elapsed / job.duration));
+}
+/**
+ * Enqueue a new job. Validates capacity and the injected `validate` policy, then
+ * computes and stores the reservation. Charging the reservation (now or later) is
+ * the caller's responsibility using {@link EnqueueResult.job}'s `reservation`.
+ *
+ * @capability enqueue-work reserve inputs and add a timed job, honoring capacity and validation policy
+ */
+export function enqueue(state, config, spec, options) {
+    if (config.capacity !== undefined && state.jobs.length >= config.capacity) {
+        return { ok: false, state, reason: "capacity" };
+    }
+    const validation = config.validate?.(spec, state);
+    if (validation !== undefined && !validation.ok) {
+        return { ok: false, state, reason: validation.reason ?? "invalid" };
+    }
+    const reservation = (config.reserve ? config.reserve(spec) : undefined);
+    const job = {
+        id: options?.id ?? `job-${state.nextId}`,
+        spec,
+        reservation,
+        status: "queued",
+        duration: Math.max(0, config.duration(spec)),
+        elapsed: 0,
+        priority: options?.priority ?? 0,
+        seq: state.seq,
+    };
+    return {
+        ok: true,
+        job,
+        state: { jobs: [...state.jobs, job], nextId: state.nextId + 1, seq: state.seq + 1 },
+    };
+}
+/**
+ * Cancel a job and compute its refund. Removes the job from the queue and returns
+ * a refund payload (full reservation by default, or `config.refund` applied to the
+ * job's progress for partial/no refund). Applying the refund is the caller's job.
+ *
+ * @capability cancel-work remove a job and compute its refund from reservation and progress
+ */
+export function cancelJob(state, config, id) {
+    const job = state.jobs.find((entry) => entry.id === id);
+    if (job === undefined)
+        return { ok: false, state, reason: "not-found" };
+    const refund = config.refund
+        ? config.refund(job, jobProgress(job))
+        : (job.reservation ?? null);
+    return { ok: true, state: { ...state, jobs: state.jobs.filter((entry) => entry.id !== id) }, job, refund };
+}
+function setStatus(state, id, from, to) {
+    let changed = false;
+    const jobs = state.jobs.map((job) => {
+        if (job.id === id && job.status === from) {
+            changed = true;
+            return { ...job, status: to };
+        }
+        return job;
+    });
+    return changed ? { ...state, jobs } : state;
+}
+/**
+ * Pause a queued or active job in place; a paused job keeps its progress and yields its slot.
+ *
+ * @capability pause-work pause a queued or active job in place, retaining its progress
+ */
+export function pauseJob(state, id) {
+    const active = setStatus(state, id, "active", "paused");
+    return active !== state ? active : setStatus(state, id, "queued", "paused");
+}
+/**
+ * Resume a paused job; it re-enters the queue and competes for a slot by ordering.
+ *
+ * @capability resume-work resume a paused job back into the queue's slot competition
+ */
+export function resumeJob(state, id) {
+    return setStatus(state, id, "paused", "queued");
+}
+/**
+ * Advance the queue by `dt` seconds. Promotes queued jobs into up to `concurrency`
+ * active slots, advances active jobs, and completes those that reach their
+ * duration — emitting `started`/`completed` events in deterministic order. A large
+ * `dt` catches up across many jobs in one call: when a job completes with leftover
+ * time, the freed slot promotes the next queued job and applies the remainder, so a
+ * reconnect or save/load gap resolves in a single bounded pass. Completed jobs are
+ * removed from the returned state.
+ *
+ * @capability tick-work advance jobs over time, completing work and emitting typed lifecycle events
+ */
+export function tick(state, config, dt) {
+    if (dt <= 0 || state.jobs.length === 0)
+        return { state, events: [] };
+    const concurrency = Math.max(1, Math.floor(config.concurrency ?? 1));
+    const ordering = config.ordering ?? priorityOrdering;
+    const jobs = state.jobs.map((job) => ({ ...job }));
+    const events = [];
+    const budget = new Map();
+    const completedIds = new Set();
+    const activeCount = () => jobs.reduce((n, job) => (job.status === "active" ? n + 1 : n), 0);
+    const nextQueued = () => {
+        let best;
+        for (const job of jobs) {
+            if (job.status !== "queued")
+                continue;
+            if (best === undefined || ordering(job, best) < 0)
+                best = job;
+        }
+        return best;
+    };
+    const promote = (job, slotBudget) => {
+        job.status = "active";
+        budget.set(job.id, Math.max(0, slotBudget));
+        events.push({ type: "started", job: { ...job } });
+    };
+    // Jobs already active from a prior tick get a fresh full budget this tick.
+    for (const job of jobs) {
+        if (job.status === "active")
+            budget.set(job.id, dt);
+    }
+    // Fill idle slots up to concurrency with a full tick budget each.
+    while (activeCount() < concurrency) {
+        const next = nextQueued();
+        if (next === undefined)
+            break;
+        promote(next, dt);
+    }
+    // Step through completions in time order; each freed slot pulls the next queued
+    // job forward with the leftover time. Bounded by the job count.
+    const guardMax = jobs.length * 2 + concurrency + 8;
+    for (let guard = 0; guard <= guardMax; guard += 1) {
+        let chosen;
+        let chosenRemaining = Infinity;
+        for (const job of jobs) {
+            if (job.status !== "active")
+                continue;
+            const available = budget.get(job.id) ?? 0;
+            if (available <= 0)
+                continue;
+            const remaining = job.duration - job.elapsed;
+            if (remaining > available)
+                continue;
+            if (chosen === undefined ||
+                remaining < chosenRemaining ||
+                (remaining === chosenRemaining && ordering(job, chosen) < 0)) {
+                chosen = job;
+                chosenRemaining = remaining;
+            }
+        }
+        if (chosen === undefined)
+            break;
+        const leftover = (budget.get(chosen.id) ?? 0) - Math.max(0, chosenRemaining);
+        chosen.elapsed = chosen.duration;
+        budget.delete(chosen.id);
+        completedIds.add(chosen.id);
+        const finished = { ...chosen, status: "active" };
+        const output = (config.output ? config.output(finished) : undefined);
+        events.push({ type: "completed", job: finished, output });
+        const next = nextQueued();
+        if (next !== undefined)
+            promote(next, leftover);
+    }
+    // Advance any active job that still holds budget but did not complete.
+    for (const job of jobs) {
+        if (job.status !== "active" || completedIds.has(job.id))
+            continue;
+        const available = budget.get(job.id) ?? 0;
+        if (available > 0)
+            job.elapsed = Math.min(job.duration, job.elapsed + available);
+    }
+    const remaining = jobs
+        .filter((job) => !completedIds.has(job.id))
+        .map((job) => ({ ...job }));
+    return { state: { ...state, jobs: remaining }, events };
+}