# 2D physics test harness types

Import these contracts with `type` from `@pibbl/core/physics/2d/testing`.

## `PibblPhysicsTestHarness2D`

```text
interface PibblPhysicsTestHarness2D<Observation> {
  readonly pendingFrames: number;
  flush(): boolean;
  advanceFrames(count: number, milliseconds?: number): number;
  act<Result>(callback: () => Result): Result;
  observe(): Observation;
  reset(): void;
  dispose(): void;
}
```

`flush()` runs one requested host frame. `advanceFrames()` returns host frames
run, rather than promising an equal number of fixed physics ticks. `act()`
flushes a state action without moving host time. `reset()` remounts with
monotonic time; `dispose()` is idempotent and restores the scheduler driver.

Use `createPhysicsTestHarness2D` from the
[test-harness function page](/reference/functions/physics-2d-testing/) and consult
the [2D physics guide](/guides/physics-2d/) for public world and handle
composition.

## `PibblPhysicsTestHarness2DOptions`

```text
interface PibblPhysicsTestHarness2DOptions<Observation> {
  readonly canvas: HTMLCanvasElement;
  readonly root: () => PibblNode;
  readonly observe: () => Observation;
}
```

The caller owns `canvas`; harness disposal never removes it. `root()` creates
the initial and reset composition. `observe()` reads public application state.
External fixtures stay under the test's ownership and are not reset.

## API details from source

<span id="api-PibblPhysicsTestHarness2DOptions"></span>

### PibblPhysicsTestHarness2DOptions

Caller-owned canvas, root factory, and observation callback for deterministic physics testing.

```ts
interface PibblPhysicsTestHarness2DOptions<Observation>
```

Related API: [PibblPhysicsTestHarness2DOptions](/reference/types/physics-2d-testing/#pibblphysicstestharness2doptions).

#### See also

[PibblNode](/reference/types/elements-components/#pibblnode)

[createPhysicsTestHarness2D](/reference/functions/physics-2d-testing/)

[View source — packages/core/src/features/physics/2d-testing.ts:21](/source/packages/core/src/features/physics/2d-testing-ts/#L21)

#### Properties and methods

<span id="api-PibblPhysicsTestHarness2DOptions-canvas"></span>
<details>
<summary>canvas</summary>


```ts
readonly canvas: HTMLCanvasElement
```

The caller owns this canvas; disposing the harness never removes it.

[View source — packages/core/src/features/physics/2d-testing.ts:23](/source/packages/core/src/features/physics/2d-testing-ts/#L23)

</details>

<span id="api-PibblPhysicsTestHarness2DOptions-root"></span>
<details>
<summary>root</summary>


```ts
readonly root: () => PibblNode
```

Related API: [PibblNode](/reference/types/elements-components/#pibblnode).

Creates a new public Pibbl root for the initial mount and each reset.

##### Returns

The Pibbl root tree mounted by the test harness. See [PibblNode](/reference/types/elements-components/#pibblnode).

[View source — packages/core/src/features/physics/2d-testing.ts:28](/source/packages/core/src/features/physics/2d-testing-ts/#L28)

</details>

<span id="api-PibblPhysicsTestHarness2DOptions-observe"></span>
<details>
<summary>observe</summary>


```ts
readonly observe: () => Observation
```

Reads application state after a frame or action.

##### Returns

The semantic state to expose through the harness's observe method.

[View source — packages/core/src/features/physics/2d-testing.ts:33](/source/packages/core/src/features/physics/2d-testing-ts/#L33)

</details>

<span id="api-PibblPhysicsTestHarness2D"></span>

### PibblPhysicsTestHarness2D

A disposable test mount with explicit host-frame advancement and public-state observations.

```ts
interface PibblPhysicsTestHarness2D<Observation>
```

Related API: [PibblPhysicsTestHarness2D](/reference/types/physics-2d-testing/#pibblphysicstestharness2d).

#### See also

[createPhysicsTestHarness2D](/reference/functions/physics-2d-testing/)

[View source — packages/core/src/features/physics/2d-testing.ts:41](/source/packages/core/src/features/physics/2d-testing-ts/#L41)

#### Properties and methods

<span id="api-PibblPhysicsTestHarness2D-pendingFrames"></span>
<details>
<summary>pendingFrames</summary>


```ts
readonly pendingFrames: number
```

Number of host callbacks currently requested by Pibbl (zero or one).

[View source — packages/core/src/features/physics/2d-testing.ts:43](/source/packages/core/src/features/physics/2d-testing-ts/#L43)

</details>

<span id="api-PibblPhysicsTestHarness2D-flush"></span>
<details>
<summary>flush</summary>


```ts
flush: () => boolean
```

Delivers one already-requested host frame at the current host time.

##### Returns

Whether a pending frame was flushed.

[View source — packages/core/src/features/physics/2d-testing.ts:48](/source/packages/core/src/features/physics/2d-testing-ts/#L48)

</details>

<span id="api-PibblPhysicsTestHarness2D-advanceFrames"></span>
<details>
<summary>advanceFrames</summary>


```ts
advanceFrames: (count: number, milliseconds?: number) => number
```

Advances up to `count` requested host frames by `milliseconds` each.
This advances the host clock, not a guaranteed count of physics fixed ticks.

##### Parameters

- **`count`** — Number of frames to advance.

- **`milliseconds`** — Duration of each frame in milliseconds.

##### Returns

The number of frames advanced.

[View source — packages/core/src/features/physics/2d-testing.ts:56](/source/packages/core/src/features/physics/2d-testing-ts/#L56)

</details>

<span id="api-PibblPhysicsTestHarness2D-act"></span>
<details>
<summary>act</summary>


```ts
act: <Result>(callback: () => Result) => Result
```

Runs an application action and delivers one resulting frame at the current time.

##### Parameters

- **`callback`** — Action to run within the harness's deterministic scheduling context.

##### Returns

The action's return value.

[View source — packages/core/src/features/physics/2d-testing.ts:62](/source/packages/core/src/features/physics/2d-testing-ts/#L62)

</details>

<span id="api-PibblPhysicsTestHarness2D-observe"></span>
<details>
<summary>observe</summary>


```ts
observe: () => Observation
```

Reads the caller-provided public observation without scheduling work.

##### Returns

The current observation from the configured observer.

[View source — packages/core/src/features/physics/2d-testing.ts:67](/source/packages/core/src/features/physics/2d-testing-ts/#L67)

</details>

<span id="api-PibblPhysicsTestHarness2D-reset"></span>
<details>
<summary>reset</summary>


```ts
reset: () => void
```

Disposes the mounted root and mounts a new one without moving host time backward.

[View source — packages/core/src/features/physics/2d-testing.ts:69](/source/packages/core/src/features/physics/2d-testing-ts/#L69)

</details>

<span id="api-PibblPhysicsTestHarness2D-dispose"></span>
<details>
<summary>dispose</summary>


```ts
dispose: () => void
```

Disposes the root and restores the previous realm scheduler driver.

[View source — packages/core/src/features/physics/2d-testing.ts:71](/source/packages/core/src/features/physics/2d-testing-ts/#L71)

</details>

## Implementation guidance for agents

Read the [Physics and geometry companion](/agents/topics/physics/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Deterministic physics test](/minimal-examples/physics/testing-harness/): Advance a public physics scene through controlled host frames. [Plain source](/minimal/physics/testing-harness.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.