@uptimizr/playcanvas 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Uptimizr Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,193 @@
+# @uptimizr/playcanvas
+
+The PlayCanvas connector for Uptimizr. It registers as an
+[`@uptimizr/sdk-core`](../sdk-core) **collector** and captures:
+
+- **camera pose** (position + forward direction) → view-direction heatmap
+- **pointer move / click** (normalized screen + optional raycast hit) → screen heatmaps
+- **mesh picks** → object-engagement analytics
+- **FPS** → performance
+- **mesh visibility** (opt-in) → per-object dwell / attention, with an optional world AABB
+- **hover dwell** (opt-in) → hover hesitation (lingering without acting)
+
+`playcanvas` is a **peer dependency**: the connector reads from the host
+application's PlayCanvas instance and never bundles or mutates the scene. It tears
+down all DOM listeners, timers, and `frameend` handlers on stop. World-space data
+is normalized from PlayCanvas' native **right-handed, y-up** frame to the canonical
+wire frame (**left-handed, y-up**) at the emission boundary.
+
+## Install
+
+```bash
+npm install @uptimizr/playcanvas playcanvas
+```
+
+`playcanvas` is a **peer dependency** — the connector reads your existing
+PlayCanvas instance and never bundles its own.
+
+## Usage
+
+The quickest integration is a single call. Because PlayCanvas supports multiple
+camera entities with no single "active" camera, and the connector reads FPS and the
+canvas from `app.graphicsDevice`, the `camera` Entity is an explicit argument:
+
+```ts
+import { trackScene } from "@uptimizr/playcanvas";
+
+const client = trackScene(app, cameraEntity, {
+  projectId: "your-project",
+  endpoint: "https://collect.example.com",
+});
+
+// ... later, on teardown
+await client.stop("manual");
+```
+
+`trackScene` creates the client, registers the collector, reads device/GPU caps,
+and starts the session. It returns the [`@uptimizr/sdk-core`](../sdk-core)
+`UptimizrClient`, so you can read `client.sessionId`, emit custom events, or stop it.
+
+### Advanced: wire it up yourself
+
+For a custom transport, a `beforeSend` hook, or registering multiple collectors,
+compose the pieces directly:
+
+```ts
+import { UptimizrClient } from "@uptimizr/sdk-core";
+import { playcanvasCollector, readDeviceCaps } from "@uptimizr/playcanvas";
+
+const client = new UptimizrClient({
+  projectId: "your-project",
+  endpoint: "https://collect.example.com",
+});
+
+client.use(playcanvasCollector({ app, camera: cameraEntity }));
+
+// device/GPU caps ride along on session_start
+client.start({ device: readDeviceCaps(app) });
+
+// ... later, on teardown
+client.stop("manual");
+```
+
+### Options
+
+Both `trackScene` and `playcanvasCollector` accept the same sampling/capture knobs
+as the Babylon and three connectors:
+
+```ts
+playcanvasCollector({
+  app,
+  camera: cameraEntity,
+  sampleCameraMs: 1000, // camera-pose sampling interval
+  samplePerfMs: 2000, // FPS sampling interval (read from app.stats.frame.fps)
+  pointerMoveThrottleMs: 250, // min gap between pointer_move samples
+  capture: { camera: true, pointerMove: true, clicks: true, meshPicks: true, perf: true },
+});
+```
+
+### Capture fidelity
+
+The `sampling` profile sets the per-channel fidelity dial in **Hz** (`0` = off,
+`"frame"` = every render tick). It governs continuous channels only — camera pose,
+pointer move, and perf; discrete events (clicks, picks, custom) are always
+captured. `"frame"`-cadence channels are driven by the engine's own `frameend`
+event (the app's render tick), which the connector subscribes to and removes on
+stop.
+
+```ts
+playcanvasCollector({ app, camera, sampling: { camera: 10, pointerMove: 60, perf: 0.5 } });
+```
+
+### Opt-in dwell capture (mesh_visibility #37, hover_dwell #48)
+
+Two attention signals are **off by default** (privacy) and emit one
+bucketed summary per window/episode:
+
+- **`mesh_visibility`** — per-object on-screen time, time near the view centre (a
+  gaze proxy), and the max screen fraction reached. Enable `capture.meshVisibility`
+  and tune via `meshVisibility`. With `boundingBox: true` it rides each object's
+  world AABB along (#53) so the dashboard can draw a coarse scene "ghost"; the box
+  is sent once and only re-sent when it moves. The connector unions each entity's
+  per-`MeshInstance` **world** AABB directly (PlayCanvas exposes `meshInstance.aabb`
+  in world space) and uses a forward half-space visibility test — **import-free**.
+- **`hover_dwell`** — fires when the pointer rests on an object for at least
+  `minDwellMs` _without clicking it_ (a click is engagement, not hesitation).
+  Enable `capture.hoverDwell` and tune via `hoverDwell`.
+
+```ts
+playcanvasCollector({
+  app,
+  camera,
+  capture: { meshVisibility: true, hoverDwell: true },
+  meshVisibility: { windowMs: 5000, boundingBox: true, centeredAngleDeg: 12, maxMeshes: 50 },
+  hoverDwell: { minDwellMs: 500 },
+});
+```
+
+### Scene proxy (spatial heatmap backdrop)
+
+`scanSceneProxy(app, { sceneId })` walks the scene graph and produces an
+engine-agnostic, per-object **world AABB** proxy (already normalized to the
+canonical frame) so a world-space heatmap has a faint spatial backdrop without
+shipping the host's real assets. PlayCanvas hands back each `MeshInstance`'s world
+AABB directly, so the proxy is a straight min/max union per named entity.
+
+## PlayCanvas adaptations
+
+PlayCanvas differs from Babylon and three in a few places; each is handled at the
+connector boundary so the emitted events are identical:
+
+- **Camera forward:** a PlayCanvas `Entity.forward` getter already returns the
+  **true world-space** look direction (unlike three cameras, which look along local
+  **−Z**), so it converts straight through the canonical Z-negation — no extra
+  per-camera negation.
+- **Pointer/raycast:** PlayCanvas has no pointer observable, so DOM listeners are
+  attached to `app.graphicsDevice.canvas` and hits are resolved with a `pc.Ray`
+  against the scene's mesh-instance world AABBs (`BoundingBox.intersectsRay`). The
+  pick is **physics-free** — it never touches the rigidbody system, so the
+  connector adds no `ammo` dependency.
+- **Pointer lock (ADR 0034):** when the canvas holds the pointer lock
+  (`Mouse.enablePointerLock()`, first-person/FPS scenes), the OS cursor freezes, so
+  the connector reports `pointer_move`/`pointer_click` from the viewport centre
+  (`screen = [0.5, 0.5]`) and raycasts from NDC `(0, 0)` — the crosshair. Read the
+  spatial story from the gaze/floor-plan heatmaps, not the 2D pointer heatmap.
+- **FPS:** read directly from `app.stats.frame.fps` (PlayCanvas computes it), so —
+  unlike three — there is no frame-counter delta.
+- **"frame" cadence:** the connector owns no animation loop; it subscribes to the
+  engine's `frameend` event (the app's own render tick) and removes it on stop, so
+  dwell accumulation pauses when the tab is hidden (matching Babylon's
+  `onBeforeRender`).
+- **Mesh visibility:** the connector unions each entity's `meshInstance.aabb`
+  (already world-space) into one box and uses a **forward half-space** test for
+  visibility, rather than a full VP-matrix frustum (PlayCanvas doesn't expose flat
+  projection/view matrices structurally without importing the engine). Anything in
+  front of the camera counts — the documented divergence from three's clip-space
+  frustum path.
+- **Coordinate frame:** fixed right-handed, y-up (PlayCanvas has no per-scene
+  handedness flag like Babylon's `useRightHandedSystem`).
+- **`asset_load`:** **not captured.** Mirrors the three connector — the connector
+  does not hook PlayCanvas' asset registry; report load timing from your app via
+  `client.track(...)` if needed. (Follow-up: a first-class asset-load hook.)
+- **Compile stalls (`compile_stall`, #42):** **not captured.** Babylon exposes
+  engine-level shader-compilation observables the connector can time; PlayCanvas has
+  no equivalent public compile hook, so compile-stall capture is Babylon-only for now.
+- **Resource footprint (`resource_sample`, #44):** captured, but with **fewer
+  metrics** than Babylon. `app.stats.frame.triangles` gives the `triangles`
+  submitted last frame; there is no public per-frame vertex count, and resident
+  texture/geometry bytes aren't exposed, so those fields are omitted (the read
+  API's averages skip unreported metrics). `jsHeapBytes` comes from the
+  Chromium-only `performance.memory`. Opt-in (`capture.resourceSample`), low-rate,
+  and read-only like the rest.
+- **Capability changes (`capability_change`, #49):** **not auto-captured — by
+  design.** A WebGPU→WebGL2 downgrade or a re-init after a lost device is an
+  _app/engine decision_ with no reliable runtime hook the connector could observe
+  (PlayCanvas picks its backend at device creation). Report these transitions from
+  your app with the engine-neutral
+  `client.reportCapabilityChange({ kind, from?, to?, reason? })` (sdk-core). The
+  raw GPU lifecycle (`context_lost` / `context_restored`) is still captured by the
+  connector; `capability_change` is the higher-level companion.
+
+## License
+
+[Apache-2.0](./LICENSE) © Uptimizr.

package/dist/collector.d.ts

@@ -0,0 +1,259 @@
+import type { AppBase, Entity } from "playcanvas";
+import type { Collector, SamplingProfile } from "@uptimizr/sdk-core";
+import type { GazeProbe, GazeProbeOptions, RaycastProbe } from "./raycast.js";
+/** Which signals the collector captures. All default to `true`. */
+export interface PlayCanvasCaptureOptions {
+    camera?: boolean;
+    pointerMove?: boolean;
+    clicks?: boolean;
+    /** Raw `pointer_down` / `pointer_up` button transitions (press-and-hold, drags). */
+    buttons?: boolean;
+    /**
+     * Typed `camera_gesture` navigation capture (ADR 0025). **On by default**: it
+     * separates navigation intent (orbit/pan/dolly/zoom/roll/fly) from object
+     * selection, costs only a snapshot+diff per gesture, and carries no PII.
+     */
+    cameraGesture?: boolean;
+    meshPicks?: boolean;
+    perf?: boolean;
+    /** WebGL `webglcontextlost` / `webglcontextrestored` transitions on the canvas. */
+    contextLoss?: boolean;
+    /**
+     * Per-object dwell / attention capture (`mesh_visibility`, #37). **Opt-in, off
+     * by default** (privacy, ADR 0003). Each window the connector emits one
+     * bucketed summary per tracked object (ADR 0012): on-screen time, time spent
+     * near the view centre (a gaze proxy), and the max screen fraction reached.
+     * Configure via {@link PlayCanvasCollectorOptions.meshVisibility}.
+     */
+    meshVisibility?: boolean;
+    /**
+     * Hover-hesitation capture (`hover_dwell`, #48). **Opt-in, off by default**
+     * (privacy, ADR 0003): emits one bucketed summary per hover episode (ADR 0012)
+     * when the pointer lingers on an object *without acting on it*. Configure via
+     * {@link PlayCanvasCollectorOptions.hoverDwell}.
+     */
+    hoverDwell?: boolean;
+    /**
+     * GPU / memory footprint capture (`resource_sample`, #44). **Opt-in, off by
+     * default** (privacy + cost, ADR 0003): emits one low-rate summary per window
+     * (ADR 0012) of the triangles submitted last frame (`app.stats.frame`) and the
+     * JS heap size. Configure cadence via {@link PlayCanvasCollectorOptions.resourceSample}.
+     */
+    resourceSample?: boolean;
+    /**
+     * Gaze raycast capture (`camera_sample.hitPoint`/`hitMesh`, ADR 0030). **Opt-in,
+     * off by default** (privacy + cost, ADR 0003): when on, each emitted
+     * `camera_sample` carries the world-space point (and object name) the camera is
+     * looking at — one camera-forward raycast per sample, riding the throttled,
+     * idle-suppressed camera cadence. Configure via
+     * {@link PlayCanvasCollectorOptions.gaze}.
+     */
+    gaze?: boolean;
+    /**
+     * Scene-actor transform capture (`node_transform`, ADR 0027 Tier 1). **On by
+     * default**, but inert unless actors are declared in
+     * {@link PlayCanvasCollectorOptions.actors} AND given a rate in
+     * `sampling.nodes` — so nothing is captured until you opt a node in.
+     */
+    nodes?: boolean;
+    /**
+     * Skeleton bone-transform capture (`node_transform` with `boneId`, ADR 0027
+     * Tier 2). **On by default**, but inert unless an actor is declared in
+     * {@link PlayCanvasCollectorOptions.actors} AND given a per-bone allowlist in
+     * `sampling.bones` — each allowlisted bone's skeleton-local pose is captured so
+     * replay can re-drive an animated character.
+     */
+    bones?: boolean;
+    /**
+     * Keyboard `input_action` capture (ADR 0023). **Off unless `keyBindings` is
+     * provided** — only explicitly bound keys are recorded, never arbitrary typing
+     * (privacy, ADR 0003). On by default once bindings exist; set `false` to
+     * disable even when bindings are present.
+     */
+    keyboard?: boolean;
+}
+/** Per-object dwell capture options (`mesh_visibility`, #37) — mirrors Babylon. */
+export interface MeshVisibilityOptions {
+    /** Summary window length in ms — one event per object per window. Default 5000. */
+    windowMs?: number;
+    /**
+     * Allowlist of mesh names to track (low-cardinality, app-defined — ADR 0003).
+     * When omitted, every visible, renderable, non-overlay object is tracked, capped
+     * by {@link maxMeshes}.
+     */
+    meshes?: string[];
+    /**
+     * Half-angle in degrees from the camera forward axis within which an object's
+     * centre counts as "near the view centre" for `centeredMs`. Default 12.
+     */
+    centeredAngleDeg?: number;
+    /** Max meshes to track when no allowlist is given. Default 50. */
+    maxMeshes?: number;
+    /**
+     * Attach each tracked object's world-space AABB to its summary (#53), so the
+     * dashboard can render a coarse "ghost" reconstruction of the scene. Off by
+     * default (extra volume + discloses layout, ADR 0003). The box is sent once
+     * per object and re-sent only when it moves/resizes beyond a small epsilon.
+     */
+    boundingBox?: boolean;
+}
+/** Hover-hesitation capture options (`hover_dwell`, #48) — mirrors Babylon. */
+export interface HoverDwellOptions {
+    /**
+     * Minimum uninterrupted hover time in ms before an episode is reported. Short
+     * pass-overs aren't hesitation, so they're dropped. Default 500.
+     */
+    minDwellMs?: number;
+    /**
+     * Allowlist of mesh names to track (low-cardinality, app-defined — ADR 0003).
+     * When omitted, hover over any picked mesh is tracked.
+     */
+    meshes?: string[];
+}
+/** GPU / memory footprint capture options (`resource_sample`, #44) — mirrors Babylon. */
+export interface ResourceSampleOptions {
+    /**
+     * Sampling interval in ms — one footprint summary per window (ADR 0012). The
+     * footprint moves slowly, so the default is deliberately low-rate. Default
+     * 15000 (every 15s).
+     */
+    intervalMs?: number;
+}
+/**
+ * Gaze probe tuning (`camera_sample.hitPoint`/`hitMesh`, ADR 0030). Only consulted
+ * when `capture.gaze` is enabled. Mirrors Babylon's `GazeOptions`.
+ */
+export interface PlayCanvasGazeOptions extends GazeProbeOptions {
+    /**
+     * Override the gaze probe (a camera-forward raycaster). Defaults to
+     * {@link createGazeRaycaster}. Tests inject a stub so gaze is exercised without
+     * real geometry.
+     */
+    probe?: GazeProbe;
+}
+export interface PlayCanvasCollectorOptions {
+    /** The PlayCanvas application to instrument (read-only). */
+    app: AppBase;
+    /**
+     * Camera Entity to record for the view-direction / pose timeline. PlayCanvas
+     * supports multiple camera entities with no single "active" camera, so the one
+     * the viewer flies must be passed explicitly.
+     */
+    camera: Entity;
+    /** Camera-pose sampling interval in ms. Default 1000. */
+    sampleCameraMs?: number;
+    /** Performance (FPS) sampling interval in ms. Default 2000. */
+    samplePerfMs?: number;
+    /** Minimum gap between `pointer_move` samples in ms. Default 250. */
+    /** Minimum gap between `pointer_move` samples in ms. Default 250. */
+    pointerMoveThrottleMs?: number;
+    /**
+     * Sensitivity dial for `camera_gesture` classification (ADR 0025). Scales every
+     * motion dead-zone together: `> 1` is less sensitive, `< 1` more. Default 1.
+     */
+    cameraGestureSensitivity?: number;
+    /**
+     * Per-channel capture-fidelity dial in Hz / `"frame"` / `0`-off (ADR 0012).
+     * Governs continuous channels only (camera pose, pointer move, perf); discrete
+     * events are always captured. When a channel is set here it overrides the
+     * matching legacy ms knob above; omitted channels keep the conservative
+     * defaults. There is no enforced upper bound — `"frame"` captures every tick.
+     */
+    sampling?: SamplingProfile;
+    /**
+     * Skip timer-based **camera** samples when the pose is unchanged (within
+     * {@link cameraEpsilon}). The first sample is always emitted so the timeline has
+     * a baseline. Default `true`.
+     */
+    suppressIdleSamples?: boolean;
+    /**
+     * Skip timer-based `frame_perf` samples when FPS is unchanged (within
+     * {@link perfFpsThreshold}). Default `false` — a steady FPS is meaningful
+     * telemetry, so the perf channel reports continuously.
+     */
+    suppressIdlePerfSamples?: boolean;
+    /** Max per-axis pose change treated as "unchanged" for camera dedupe. Default 1e-3. */
+    cameraEpsilon?: number;
+    /** Max FPS change treated as "unchanged" for perf dedupe. Default 1. */
+    perfFpsThreshold?: number;
+    /** Toggle individual capture channels. */
+    capture?: PlayCanvasCaptureOptions;
+    /**
+     * Per-object dwell capture tuning (`mesh_visibility`, #37). Only consulted when
+     * `capture.meshVisibility` is enabled.
+     */
+    meshVisibility?: MeshVisibilityOptions;
+    /**
+     * Hover-hesitation capture tuning (`hover_dwell`, #48). Only consulted when
+     * `capture.hoverDwell` is enabled.
+     */
+    hoverDwell?: HoverDwellOptions;
+    /**
+     * GPU / memory footprint capture tuning (`resource_sample`, #44). Only consulted
+     * when `capture.resourceSample` is enabled.
+     */
+    resourceSample?: ResourceSampleOptions;
+    /**
+     * Gaze probe tuning (`camera_sample.hitPoint`/`hitMesh`, ADR 0030). Only
+     * consulted when `capture.gaze` is enabled.
+     */
+    gaze?: PlayCanvasGazeOptions;
+    /**
+     * Override the raycast probe used to resolve pointer hits (world point + object
+     * name). Defaults to a `pc.Ray` against the scene's mesh-instance world AABBs
+     * ({@link createSceneRaycaster}). Provide one to customize picking — and tests
+     * inject a stub so picking is exercised without real geometry.
+     */
+    raycast?: RaycastProbe;
+    /**
+     * Scene-actor map for `node_transform` capture (ADR 0027 Tier 1): developer-
+     * controlled, self-moving nodes (a patrolling NPC, a lift, a vehicle) whose
+     * world transform is sampled so replay can reproduce them. Each value resolves
+     * to a live node — a direct Entity reference, an entity **name** (looked up via
+     * `app.root.findByName`), or a `() => Entity` resolver (robust to load order).
+     * A node is only captured when its id also has a rate in `sampling.nodes`;
+     * cameras are refused (the visitor camera is already `camera_sample`).
+     */
+    actors?: Record<string, PlayCanvasActor>;
+    /**
+     * Keyboard bindings to capture as `input_action` events (ADR 0023): a map from
+     * `KeyboardEvent.code` (e.g. `"KeyW"`, `"ArrowLeft"`) to a semantic app action
+     * (e.g. `"move-forward"`). **Only bound keys are recorded** — unbound keys are
+     * never seen, so arbitrary typing is never captured (privacy, ADR 0003).
+     * Auto-repeat (held keys) is suppressed; each press and release emits once.
+     * PlayCanvas exposes no keyboard observable here, so the connector listens on `window`.
+     */
+    keyBindings?: Record<string, string>;
+}
+/** A PlayCanvas node that exposes a world transform (a `node_transform` actor, ADR 0027). */
+export type PlayCanvasActorNode = Entity;
+/**
+ * A declared scene actor (ADR 0027): a live {@link PlayCanvasActorNode}, an entity
+ * **name** resolved via `app.root.findByName`, or a `() => Entity` resolver called
+ * each sample (robust to load order and disposal).
+ */
+export type PlayCanvasActor = (() => PlayCanvasActorNode | null | undefined) | string | PlayCanvasActorNode;
+/**
+ * Create the PlayCanvas connector as an sdk-core {@link Collector}. Register it
+ * with `client.use(...)`.
+ *
+ * It samples camera pose (view-direction heatmap), pointer movement and clicks
+ * (screen heatmaps), mesh picks (object engagement), and FPS (perf). It only reads
+ * from the scene — it never mutates it — and tears every listener, timer, and
+ * frame handler down on stop (ADR 0003: no cookies, no persistent ids).
+ *
+ * Device/GPU capabilities are captured separately via {@link "./device".readDeviceCaps}.
+ *
+ * ## PlayCanvas adaptations (vs. the three connector)
+ * - **Camera pose:** a PlayCanvas Entity's `forward` getter already returns the
+ *   true world look direction (no local −Z negation), so it converts straight
+ *   through `toCanonicalDirection`.
+ * - **FPS:** PlayCanvas computes FPS itself, so perf reads `app.stats.frame.fps`
+ *   directly rather than deriving it from a frame-counter delta.
+ * - **"frame" cadence:** the connector owns no rAF loop; it subscribes to the
+ *   engine's `frameend` event (the app's own render tick) and removes it on stop.
+ * - **World AABBs:** `meshInstance.aabb` is already a world-space box, so mesh
+ *   visibility unions those directly instead of transforming local corners.
+ */
+export declare function playcanvasCollector(options: PlayCanvasCollectorOptions): Collector;
+//# sourceMappingURL=collector.d.ts.map

package/dist/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"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"}