@realitycollective/webxr-uiextensions 0.1.0-preview.4 → 0.1.0-preview.5

package/CHANGELOG.md

@@ -36,5 +36,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 - The XR Blocks window handle gains `panel` - the document, which already implements `PanelHandle` - and `onReady`, which fires synchronously because uikitml interprets the markup during `createWindow`. The interface is now named `XrBlocksWindowHandle`, with `WindowHandle` kept as an alias, because the core exports a `WindowHandle` of its own.
 - Coverage gates `packages/iwsdk-uiextensions/src/factory.ts` and `src/scene-host.ts` at the same 100% as the core. `new World()` from `@iwsdk/core` constructs headlessly - no renderer, no WebGL, no XR session - so the factories, the scene host and its ECS query all run for real in a node test. The per-frame ECS systems still need a live world and stay outside the gate.
 - `@realitycollective/webxr-uiextensions` takes its geometry vocabulary from `@realitycollective/webxr-input` at `^0.1.1` rather than redeclaring it. `Vec3Tuple`, `QuatTuple`, `HeadPose`, `HeadPoseSource` and `PointerSample` are now that package's types, re-exported under the same names, so no import changes for a consumer. `PointerSample` is its `RayTuple`, which is what lets an input provider written against the shared contracts feed this contract unchanged. It is the core's only runtime dependency: the contracts package is engine-free and carries none of its own, and `test/architecture.test.ts` now allows exactly that one name and fails on any other.
+- `PointerSample` states its ownership rule: a delivered sample belongs to the listener and the source never writes to it again, so the core's hold-to-drag and drag maths may keep a press-time sample without copying. It mirrors the rule `@realitycollective/webxr-input` 0.1.3 writes on `InputSourceSnapshot`, so a provider feeding both contracts has one promise to keep.
 
 [0.1.0]: https://github.com/realitycollective/WebXR-UIExtensions/commits/main

package/dist/adapter.d.ts

@@ -179,6 +179,12 @@ export interface WindowOptionsBase {
  * `origin` (ray origin or touch point) and a normalised `direction`. It is
  * the Input package's `RayTuple`, which is what lets a provider written
  * against `@realitycollective/webxr-input` feed this contract unchanged.
+ *
+ * Once delivered, a sample belongs to the listener: the source never writes
+ * to it again, so `hold-to-drag` and `drag-math` may keep a press-time
+ * sample without copying it. This is the rule `@realitycollective/webxr-input`
+ * states on `InputSourceSnapshot`, so a provider feeding both contracts has
+ * one promise to keep.
  */
 export type PointerSample = RayTuple;
 /**

package/dist/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Platform-adapter contract.\n *\n * The core package owns every UX decision - window lifecycle, dock state,\n * region slot math, drag math, control models - and knows nothing about any\n * engine. An engine adapter supplies the three capabilities the core cannot\n * provide for itself, and drives the core from its own frame loop:\n *\n *  - {@link PanelHost}: turn compiled UIKitML JSON into a live spatial panel\n *  - {@link PointerInputSource}: deliver ray/pointer press-move-release\n *  - {@link HeadPoseSource}: the viewer pose, for follow mode & body-lock\n *\n * On top of those, {@link WindowHost} adds the portable window surface:\n * {@link WindowHost.onPanelReady} for readiness, {@link PanelReadyEvent.kind}\n * to tell a managed window from a bare panel, and\n * {@link WindowHost.supportsStandalonePanels} to say whether `createPanel` is\n * usable at all. Each adapter's own `createWindow` returns a\n * {@link WindowHandle} and takes options extending {@link WindowOptionsBase},\n * so window code reads the same on every engine even though the `config`\n * payload does not.\n *\n * Known adapters:\n *  - `@realitycollective/iwsdk-uiextensions` - Meta IWSDK (ECS systems bind\n *    these capabilities to `@iwsdk/core` components)\n *  - `@realitycollective/xrblocks-uiextensions` - Google XR Blocks / plain\n *    three.js (experimental)\n *\n * The interfaces use plain tuples/records only - no engine, no three.js. The\n * geometry vocabulary itself comes from `@realitycollective/webxr-input`, the\n * engine-free contracts package both extension families share, so a pose or a\n * ray means the same thing to Interactions and to UI Extensions and one input\n * stack drives both. The names below are re-exported, so importing them from\n * this package keeps working.\n */\nimport type { RayTuple, Vec3Tuple } from '@realitycollective/webxr-input';\nimport type { DockModeValue } from './core/dock-state.js';\nimport type { UixElement } from './controls/element.js';\n\n/**\n * The shared geometry vocabulary, re-exported so this package stays the one\n * import an adapter needs:\n *\n *  - `Vec3Tuple` - position as [x, y, z] in meters, world space unless stated\n *  - `QuatTuple` - orientation quaternion as [x, y, z, w]\n *  - `HeadPose` - a viewer (head) pose sample\n *  - `HeadPoseSource` - supplies that pose each frame, camera on desktop and\n *    HMD in XR\n */\nexport type {\n  HeadPose,\n  HeadPoseSource,\n  QuatTuple,\n  Vec3Tuple,\n} from '@realitycollective/webxr-input';\n\n/**\n * A live spatial panel created from compiled UIKitML JSON.\n * The `root` is traversable with the core's `walk`/`findRole` helpers and\n * the `data-uix` control upgraders - identical markup works on every\n * adapter.\n */\nexport interface PanelHandle {\n  /** Root element of the interpreted panel (UixElement-conformant). */\n  readonly root: UixElement;\n  /** Look up an element by its markup `id`. */\n  getElementById(id: string): UixElement | undefined;\n  /** Constrain the panel to fit within width × height meters. */\n  setTargetDimensions(width: number, height: number): void;\n  /** Release panel resources. */\n  dispose(): void;\n}\n\n/** Creates spatial panels - the engine-specific half of UIKitML rendering. */\nexport interface PanelHost {\n  /**\n   * Create a panel from compiled UIKitML JSON (the `{ element, classes }`\n   * shape produced by the build plugin or by\n   * `@realitycollective/uix-devtools`' `compilePanelSource`).\n   */\n  createPanel(configJson: unknown): PanelHandle;\n}\n\n/**\n * A window whose panel has finished loading and is ready to be wired.\n * Delivered by {@link WindowHost.onPanelReady}.\n */\nexport interface PanelReadyEvent {\n  /** The window's id, as given to the scene descriptor / create call. */\n  id: string;\n  /** The live panel - traverse it, or look elements up by markup id. */\n  panel: PanelHandle;\n  /**\n   * What became ready.\n   *\n   * - `window` - created through the adapter's window factory and managed by\n   *   the window manager, so `id` is the id the caller asked for.\n   * - `panel` - a bare panel the adapter noticed. `id` is then the adapter's\n   *   best stable identifier for it, which on IWSDK is the panel's config\n   *   path.\n   *\n   * Left optional so existing listeners keep compiling; adapters set it.\n   */\n  kind?: 'window' | 'panel';\n}\n\n/**\n * The engine-agnostic surface an app needs to build a UI: spawn windows and\n * regions from portable data, observe when panels become wireable, and reach\n * the shared `WindowManager`.\n *\n * Panels load asynchronously on every adapter (IWSDK fetches the config;\n * uikit lays out over following frames), so app code must never assume a\n * panel exists immediately after creating its window. {@link onPanelReady}\n * is the portable answer - it replaces engine-specific discovery (ECS\n * queries on IWSDK, polling anywhere else) and fires for panels that became\n * ready before the listener was registered, so wiring order never matters.\n */\nexport interface WindowHost extends PanelHost {\n  /**\n   * Whether {@link PanelHost.createPanel} works on this host. When `false`\n   * the method is not available and throws; spawn a window instead, so the\n   * engine owns the panel lifecycle. IWSDK is `false`, three.js/XR Blocks is\n   * `true`.\n   */\n  readonly supportsStandalonePanels: boolean;\n  /**\n   * Subscribe to panel readiness. Late subscribers are replayed the windows\n   * that are already live. Returns an unsubscribe function.\n   */\n  onPanelReady(listener: (event: PanelReadyEvent) => void): () => void;\n}\n\n/**\n * A window an adapter spawned, before its panel necessarily exists.\n *\n * `createWindow` itself stays adapter-specific because the `config` payload\n * differs per engine, but what it hands back is the same everywhere: an id, a\n * panel once there is one, and a one-shot readiness callback.\n */\nexport interface WindowHandle {\n  /** The window's id - the one passed in, or one the adapter generated. */\n  readonly id: string;\n  /**\n   * The live panel, or `undefined` until the adapter has attached the\n   * document. IWSDK loads and parses the markup over later frames; the\n   * three.js host interprets it during `createWindow`, so there it is set\n   * straight away.\n   */\n  readonly panel: PanelHandle | undefined;\n  /**\n   * Run `listener` once, when the panel is attached. Fires immediately if it\n   * already is, so wiring order never matters. Returns an unsubscribe\n   * function for the case where the caller gives up first.\n   */\n  onReady(listener: (panel: PanelHandle) => void): () => void;\n}\n\n/**\n * The window options every adapter understands.\n *\n * An adapter's own `CreateWindowOptions` extends this and adds only what its\n * engine needs - chiefly `config`, whose type differs (IWSDK takes a source\n * path, the three.js host takes parsed markup). Keeping the rest here is what\n * lets one `SceneWindow` map onto every adapter without a translation table.\n */\nexport interface WindowOptionsBase {\n  /** Stable window id. Adapters generate one when it is absent. */\n  id?: string;\n  /** Title text written into the window chrome's title element. */\n  title?: string;\n  dockMode?: DockModeValue;\n  /** World position for world-locked windows. */\n  position?: Vec3Tuple;\n  /** Fit the panel into this box in meters, preserving aspect ratio. */\n  maxWidth?: number;\n  maxHeight?: number;\n  /** Whether the title bar drags the window. */\n  movable?: boolean;\n  closable?: boolean;\n  minimizable?: boolean;\n  pinnable?: boolean;\n  /** Head-relative offset used in body-follow mode (meters). */\n  followOffset?: Vec3Tuple;\n  followSpeed?: number;\n  followTolerance?: number;\n  /** Dock straight into this region on spawn. */\n  region?: string;\n}\n\n/**\n * One pointer/ray interaction stream, engine-normalised: a world-space\n * `origin` (ray origin or touch point) and a normalised `direction`. It is\n * the Input package's `RayTuple`, which is what lets a provider written\n * against `@realitycollective/webxr-input` feed this contract unchanged.\n */\nexport type PointerSample = RayTuple;\n\n/**\n * Delivers press-move-release for one interaction source (a controller ray,\n * a hand pinch, a mouse). The core's `hold-to-drag` and `drag-math` consume\n * these; the adapter decides what constitutes press/release.\n */\nexport interface PointerInputSource {\n  onPress(listener: (sample: PointerSample) => void): () => void;\n  onMove(listener: (sample: PointerSample) => void): () => void;\n  onRelease(listener: (sample: PointerSample) => void): () => void;\n}\n"]}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Platform-adapter contract.\n *\n * The core package owns every UX decision - window lifecycle, dock state,\n * region slot math, drag math, control models - and knows nothing about any\n * engine. An engine adapter supplies the three capabilities the core cannot\n * provide for itself, and drives the core from its own frame loop:\n *\n *  - {@link PanelHost}: turn compiled UIKitML JSON into a live spatial panel\n *  - {@link PointerInputSource}: deliver ray/pointer press-move-release\n *  - {@link HeadPoseSource}: the viewer pose, for follow mode & body-lock\n *\n * On top of those, {@link WindowHost} adds the portable window surface:\n * {@link WindowHost.onPanelReady} for readiness, {@link PanelReadyEvent.kind}\n * to tell a managed window from a bare panel, and\n * {@link WindowHost.supportsStandalonePanels} to say whether `createPanel` is\n * usable at all. Each adapter's own `createWindow` returns a\n * {@link WindowHandle} and takes options extending {@link WindowOptionsBase},\n * so window code reads the same on every engine even though the `config`\n * payload does not.\n *\n * Known adapters:\n *  - `@realitycollective/iwsdk-uiextensions` - Meta IWSDK (ECS systems bind\n *    these capabilities to `@iwsdk/core` components)\n *  - `@realitycollective/xrblocks-uiextensions` - Google XR Blocks / plain\n *    three.js (experimental)\n *\n * The interfaces use plain tuples/records only - no engine, no three.js. The\n * geometry vocabulary itself comes from `@realitycollective/webxr-input`, the\n * engine-free contracts package both extension families share, so a pose or a\n * ray means the same thing to Interactions and to UI Extensions and one input\n * stack drives both. The names below are re-exported, so importing them from\n * this package keeps working.\n */\nimport type { RayTuple, Vec3Tuple } from '@realitycollective/webxr-input';\nimport type { DockModeValue } from './core/dock-state.js';\nimport type { UixElement } from './controls/element.js';\n\n/**\n * The shared geometry vocabulary, re-exported so this package stays the one\n * import an adapter needs:\n *\n *  - `Vec3Tuple` - position as [x, y, z] in meters, world space unless stated\n *  - `QuatTuple` - orientation quaternion as [x, y, z, w]\n *  - `HeadPose` - a viewer (head) pose sample\n *  - `HeadPoseSource` - supplies that pose each frame, camera on desktop and\n *    HMD in XR\n */\nexport type {\n  HeadPose,\n  HeadPoseSource,\n  QuatTuple,\n  Vec3Tuple,\n} from '@realitycollective/webxr-input';\n\n/**\n * A live spatial panel created from compiled UIKitML JSON.\n * The `root` is traversable with the core's `walk`/`findRole` helpers and\n * the `data-uix` control upgraders - identical markup works on every\n * adapter.\n */\nexport interface PanelHandle {\n  /** Root element of the interpreted panel (UixElement-conformant). */\n  readonly root: UixElement;\n  /** Look up an element by its markup `id`. */\n  getElementById(id: string): UixElement | undefined;\n  /** Constrain the panel to fit within width × height meters. */\n  setTargetDimensions(width: number, height: number): void;\n  /** Release panel resources. */\n  dispose(): void;\n}\n\n/** Creates spatial panels - the engine-specific half of UIKitML rendering. */\nexport interface PanelHost {\n  /**\n   * Create a panel from compiled UIKitML JSON (the `{ element, classes }`\n   * shape produced by the build plugin or by\n   * `@realitycollective/uix-devtools`' `compilePanelSource`).\n   */\n  createPanel(configJson: unknown): PanelHandle;\n}\n\n/**\n * A window whose panel has finished loading and is ready to be wired.\n * Delivered by {@link WindowHost.onPanelReady}.\n */\nexport interface PanelReadyEvent {\n  /** The window's id, as given to the scene descriptor / create call. */\n  id: string;\n  /** The live panel - traverse it, or look elements up by markup id. */\n  panel: PanelHandle;\n  /**\n   * What became ready.\n   *\n   * - `window` - created through the adapter's window factory and managed by\n   *   the window manager, so `id` is the id the caller asked for.\n   * - `panel` - a bare panel the adapter noticed. `id` is then the adapter's\n   *   best stable identifier for it, which on IWSDK is the panel's config\n   *   path.\n   *\n   * Left optional so existing listeners keep compiling; adapters set it.\n   */\n  kind?: 'window' | 'panel';\n}\n\n/**\n * The engine-agnostic surface an app needs to build a UI: spawn windows and\n * regions from portable data, observe when panels become wireable, and reach\n * the shared `WindowManager`.\n *\n * Panels load asynchronously on every adapter (IWSDK fetches the config;\n * uikit lays out over following frames), so app code must never assume a\n * panel exists immediately after creating its window. {@link onPanelReady}\n * is the portable answer - it replaces engine-specific discovery (ECS\n * queries on IWSDK, polling anywhere else) and fires for panels that became\n * ready before the listener was registered, so wiring order never matters.\n */\nexport interface WindowHost extends PanelHost {\n  /**\n   * Whether {@link PanelHost.createPanel} works on this host. When `false`\n   * the method is not available and throws; spawn a window instead, so the\n   * engine owns the panel lifecycle. IWSDK is `false`, three.js/XR Blocks is\n   * `true`.\n   */\n  readonly supportsStandalonePanels: boolean;\n  /**\n   * Subscribe to panel readiness. Late subscribers are replayed the windows\n   * that are already live. Returns an unsubscribe function.\n   */\n  onPanelReady(listener: (event: PanelReadyEvent) => void): () => void;\n}\n\n/**\n * A window an adapter spawned, before its panel necessarily exists.\n *\n * `createWindow` itself stays adapter-specific because the `config` payload\n * differs per engine, but what it hands back is the same everywhere: an id, a\n * panel once there is one, and a one-shot readiness callback.\n */\nexport interface WindowHandle {\n  /** The window's id - the one passed in, or one the adapter generated. */\n  readonly id: string;\n  /**\n   * The live panel, or `undefined` until the adapter has attached the\n   * document. IWSDK loads and parses the markup over later frames; the\n   * three.js host interprets it during `createWindow`, so there it is set\n   * straight away.\n   */\n  readonly panel: PanelHandle | undefined;\n  /**\n   * Run `listener` once, when the panel is attached. Fires immediately if it\n   * already is, so wiring order never matters. Returns an unsubscribe\n   * function for the case where the caller gives up first.\n   */\n  onReady(listener: (panel: PanelHandle) => void): () => void;\n}\n\n/**\n * The window options every adapter understands.\n *\n * An adapter's own `CreateWindowOptions` extends this and adds only what its\n * engine needs - chiefly `config`, whose type differs (IWSDK takes a source\n * path, the three.js host takes parsed markup). Keeping the rest here is what\n * lets one `SceneWindow` map onto every adapter without a translation table.\n */\nexport interface WindowOptionsBase {\n  /** Stable window id. Adapters generate one when it is absent. */\n  id?: string;\n  /** Title text written into the window chrome's title element. */\n  title?: string;\n  dockMode?: DockModeValue;\n  /** World position for world-locked windows. */\n  position?: Vec3Tuple;\n  /** Fit the panel into this box in meters, preserving aspect ratio. */\n  maxWidth?: number;\n  maxHeight?: number;\n  /** Whether the title bar drags the window. */\n  movable?: boolean;\n  closable?: boolean;\n  minimizable?: boolean;\n  pinnable?: boolean;\n  /** Head-relative offset used in body-follow mode (meters). */\n  followOffset?: Vec3Tuple;\n  followSpeed?: number;\n  followTolerance?: number;\n  /** Dock straight into this region on spawn. */\n  region?: string;\n}\n\n/**\n * One pointer/ray interaction stream, engine-normalised: a world-space\n * `origin` (ray origin or touch point) and a normalised `direction`. It is\n * the Input package's `RayTuple`, which is what lets a provider written\n * against `@realitycollective/webxr-input` feed this contract unchanged.\n *\n * Once delivered, a sample belongs to the listener: the source never writes\n * to it again, so `hold-to-drag` and `drag-math` may keep a press-time\n * sample without copying it. This is the rule `@realitycollective/webxr-input`\n * states on `InputSourceSnapshot`, so a provider feeding both contracts has\n * one promise to keep.\n */\nexport type PointerSample = RayTuple;\n\n/**\n * Delivers press-move-release for one interaction source (a controller ray,\n * a hand pinch, a mouse). The core's `hold-to-drag` and `drag-math` consume\n * these; the adapter decides what constitutes press/release.\n */\nexport interface PointerInputSource {\n  onPress(listener: (sample: PointerSample) => void): () => void;\n  onMove(listener: (sample: PointerSample) => void): () => void;\n  onRelease(listener: (sample: PointerSample) => void): () => void;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realitycollective/webxr-uiextensions",
-  "version": "0.1.0-preview.4",
+  "version": "0.1.0-preview.5",
   "description": "Engine-free core of the Reality Collective UI Extensions: windowing, docking, layout regions and control models for WebXR spatial UI, driven through platform-adapter interfaces. Pair with an engine adapter - @realitycollective/iwsdk-uiextensions (Meta IWSDK) or @realitycollective/xrblocks-uiextensions (Google XR Blocks).",
   "keywords": [
     "realitycollective",