@realitycollective/iwsdk-uiextensions 0.1.0-preview.4

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+Change log for the Reality Collective WebXR UI Extensions packages. All four packages are versioned and released together; the version below is the one carried by the `v<version>` release tag.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Preview builds are not listed separately. The entry for a version accumulates while its previews are published, and is dated when that version is released.
+
+## [0.1.0]
+
+### Added
+
+- `@realitycollective/webxr-uiextensions` - engine-free core: window manager, dock state and regions, drag maths, hold-to-drag, control models (stepper/toggle/expandable/log), the `SceneDescriptor` scene format, window chrome conventions and the platform-adapter contract.
+- `@realitycollective/iwsdk-uiextensions` - Meta IWSDK adapter binding the core onto IWSDK's ECS, UIKitML and interaction systems, with shipped examples.
+- `@realitycollective/xrblocks-uiextensions` - EXPERIMENTAL Google XR Blocks / plain three.js adapter: panel document, window host, follow and scale maths, desktop controls and locomotion, pointer forwarding.
+- `@realitycollective/uix-devtools` - dev-only tooling: edit-session launch gate, runtime UIKitML compilation, and the `uix-dev` CLI (Cloudflare quick tunnel, QR onboarding, environment doctor).
+- Demo clients: the IWSDK showcase, the devtools playground, and the multiplatform lab that picks its pipeline from the hardware.
+- `uixComponentSet`, exported from `@realitycollective/iwsdk-uiextensions`. Pass it to `spatialUI.componentSets` so the IWSDK 0.5 parser accepts the `<uix-*>` control elements. Without it a panel using any control fails to parse and never attaches. No equivalent is needed on the three.js or XR Blocks adapters.
+- `WindowHandle` and `WindowOptionsBase` in `@realitycollective/webxr-uiextensions`. `WindowHandle` is what every adapter's `createWindow` hands back: an `id`, a `panel` that is `undefined` until the adapter has attached the document, and `onReady(listener)`, which runs once and fires immediately if the panel is already there. `WindowOptionsBase` holds the options every adapter understands, and both adapters' option types now extend it, so an option name means the same thing on each. `createWindow` itself stays adapter-specific, because the `config` payload differs per engine.
+- `WindowHost.supportsStandalonePanels`. It says whether `createPanel` works on a host, rather than leaving callers to find out by catching. `false` on the IWSDK host, where the ECS owns panel lifecycles and `createPanel` throws; `true` on the three.js / XR Blocks host.
+- `PanelReadyEvent.kind`, either `window` or `panel`. `window` means the panel came from the adapter's window factory and is managed by the window manager. `panel` means a bare panel the adapter noticed, whose `id` is then the adapter's best stable identifier for it - the config path on IWSDK. The field is optional, so existing listeners keep compiling.
+- `createWindow` on the IWSDK scene host, returning an `IwsdkWindowHandle`: a `WindowHandle` plus the ECS `entity`. It spawns through `createUIWindow`, names the window `uix-window-<n>` when no id is given, and resolves `panel` and `onReady` once the document attaches, so wiring one window needs neither an ECS query nor a filtered `onPanelReady`. `createUIWindow` is unchanged and still returns the entity.
+- `getPanelHandle(entity)` in `@realitycollective/iwsdk-uiextensions`: the panel handle for an entity you already hold, or `undefined` while IWSDK is still loading its document.
+- `windowHostContractCases()` in `@realitycollective/webxr-uiextensions`, with `WindowHostContractCase` and `WindowHostContractSetup` - the `WindowHost` conformance suite as data rather than as tests. Each case is a `name` plus a `run(setup)` that throws an `Error` on failure, so an adapter runs the suite in its own test runner and needs nothing from this repository's `test/` folder. It was previously an in-repo vitest helper that only the two shipped adapters could reach, which left an adapter author outside this repository with no way to prove conformance. Both adapters now run the shipped cases through a three-line wrapper.
+
+### Changed
+
+- **Controls are declared as custom elements rather than attributes.** `<uix-stepper>` replaces `<div data-uix="stepper">`, and each part is its own element: `<uix-value>`, `<uix-line>`, `<uix-label>` and so on, replacing `data-uix-role`. Parameters are unchanged and stay `data-uix-*`. This is what makes one markup file portable: IWSDK 0.5 parses with `@drawcall/uikitml`, which rejects every `data-*` attribute on a built-in tag but accepts custom tags declared in a component set, while the three.js and XR Blocks parser accepts custom tags with no registration at all. Both expose the declared tag on `userData.customElement.componentName`, so the engine-free upgraders read one contract on every adapter.
+- The expandable label's `toggle` part is now `<uix-more>`. As an element the old name would have collided with the `<uix-toggle>` control.
+- `@realitycollective/iwsdk-uiextensions` targets **IWSDK 0.5.x**: peer range `>=0.5.0 <0.6.0`, developed against `@iwsdk/core` 0.5.3. `PanelUI` in 0.5 declares a single field, `config`, holding the URL of the UIKitML **source**; the compiled JSON it took on 0.4.x, and the `@iwsdk/vite-plugin-uikitml` step that produced it, are both gone. `maxWidth` and `maxHeight` were removed from the component schema, and ECS ignores unknown fields silently, so a panel that still writes them is mis-sized with no error. Size through `createUIWindow`, which routes to `UIWindow.targetWidth/Height`.
+- `UixWindowHost` resolves a window's `config` by fetching the `.uikitml` source and parsing it, where it previously fetched compiled JSON. Supplying `loadConfig` is no longer necessary for an ordinary panel; override it only for an unusual transport.
+- `compilePanelSource` in `@realitycollective/uix-devtools` serves the **source** on its `blob:` URL rather than compiled JSON, matching what 0.5 fetches. `CompiledPanel.json` is now `CompiledPanel.source`, and the `resolveFile` option is gone because the 0.5 parser has no `<link ref>` stylesheet resolution; put shared rules in a `<style>` block, of which several are allowed and merge. Validation now runs on `@drawcall/uikitml`, pinned to the version `@iwsdk/core` depends on, so a source that passes here is one `PanelUISystem` will accept and no second parser enters the tree.
+- Example and demo markup uses `rgba()` or eight-digit hex rather than `background-opacity`, which the 0.5 parser removed. Both parsers accept the replacement, so one stylesheet serves every adapter.
+- The IWSDK component kit is selected by name, `spatialUI: { kit: 'horizon' }`, rather than by passing an imported kit module. The kits now live inside the parser.
+- `@types/three` is pinned to `0.184.0` across the workspace. IWSDK 0.5.3 and xrblocks resolved different copies, and two copies of the three typings make structurally identical `Object3D` types mutually unassignable, which surfaces as spurious errors far from their cause.
+- `onPanelReady` on the IWSDK host announces bare panels as well as managed windows. A `PanelUI` entity with no `UIWindow`, or with an empty `windowId`, used to be dropped silently; it is now announced with `kind: 'panel'` and its config path as the id. Listeners that only want managed windows should check `kind`.
+- `id` is optional in the XR Blocks host's `CreateWindowOptions`; a window created without one is named `uix-window-<n>`, as on IWSDK. The options also accept `movable` for parity, but this host has no title-bar drag of its own yet, so the flag is recorded and not acted on.
+- 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.
+
+[0.1.0]: https://github.com/realitycollective/WebXR-UIExtensions/commits/main

package/Examples/README.md

@@ -0,0 +1,13 @@
+# Examples
+
+Copy-paste starting points, shipped inside the npm package (Unity-style `Examples/` convention, as used across Reality Collective packages).
+
+| Example | Shows |
+| --- | --- |
+| [`basic-window/`](./basic-window) | A managed window with chrome, pin/minimize/close and body-follow |
+| [`dock-regions/`](./dock-regions) | Layout regions, drop-to-dock, a follow-region "toolbar" |
+| [`controls/`](./controls) | `data-uix` stepper, toggle, expandable label and log view |
+
+Each example assumes an IWSDK app created with `npm create @iwsdk@latest` (so the UIKitML Vite plugin is already wired: `.uikitml` files in `ui/` compile to `public/ui/*.json`).
+
+For a complete integrated application - five windows, two regions, a registration form, event log, and horizon-kit Slider - see the `showcase/` client in the repository, which deploys to Cloudflare Pages from CI.

package/Examples/basic-window/main.ts

@@ -0,0 +1,32 @@
+/**
+ * Basic window - chrome, focus, docking and drag with one call.
+ * Put window.uikitml in your app's public/ui/ folder - IWSDK 0.5 fetches and
+ * parses the source at runtime, so there is no compile step.
+ */
+import { World } from '@iwsdk/core';
+import {
+  DockMode,
+  createUIWindow,
+  registerUIExtensions,
+} from '@realitycollective/iwsdk-uiextensions';
+
+export async function start(container: HTMLDivElement) {
+  const world = await World.create(container, {
+    features: { spatialUI: true },
+  });
+
+  const windows = registerUIExtensions(world);
+
+  createUIWindow(world, {
+    id: 'hello',
+    title: 'Hello Window',
+    config: './ui/window.uikitml',
+    dockMode: DockMode.BodyFollow, // follows until pinned or dragged
+    followOffset: [0, -0.15, -1.2],
+  });
+
+  windows.events.on('dockChanged', ({ window, previous }) => {
+    console.log(`[uix] ${window.title}: ${previous} → ${window.dockMode}`);
+  });
+  windows.events.on('closed', (w) => console.log(`[uix] ${w.title} closed`));
+}

package/Examples/basic-window/window.uikitml

@@ -0,0 +1,58 @@
+<style>
+  .uix-window {
+    display: flex;
+    flex-direction: column;
+    width: 300;
+    background-color: rgba(16, 26, 38, 0.92);
+    border-radius: 12.5;
+    border-color: #2e4a66;
+    border-width: 0.75;
+  }
+  .uix-titlebar {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+    width: 100%;
+    padding: 8;
+    background-color: #1b2c40;
+    border-top-left-radius: 12.5;
+    border-top-right-radius: 12.5;
+    cursor: pointer;
+  }
+  .uix-title { flex-shrink: 1; font-size: 12; font-weight: bold; color: #dce9f7; }
+  .uix-titlebar-buttons { display: flex; flex-direction: row; flex-shrink: 0; }
+  .uix-titlebar-button {
+    width: 34;
+    height: 20;
+    align-items: center;
+    justify-content: center;
+    text-align: center;
+    margin-left: 4;
+    font-size: 9;
+    color: #9fb8d4;
+    background-color: #223850;
+    border-radius: 6;
+    cursor: pointer;
+  }
+  .uix-titlebar-button:hover { background-color: #33547a; color: #ffffff; }
+  .uix-content { display: flex; flex-direction: column; width: 100%; padding: 10; }
+  .body-text { font-size: 11; color: #c4d6ea; }
+</style>
+<div id="uix-window" class="uix-window">
+  <div id="uix-titlebar" class="uix-titlebar">
+    <span id="uix-title" class="uix-title">.</span>
+    <div class="uix-titlebar-buttons">
+      <div id="uix-pin" class="uix-titlebar-button">PIN</div>
+      <div id="uix-dock" class="uix-titlebar-button">DOCK</div>
+      <div id="uix-minimize" class="uix-titlebar-button">MIN</div>
+      <div id="uix-close" class="uix-titlebar-button">X</div>
+    </div>
+  </div>
+  <div id="uix-content" class="uix-content">
+    <span class="body-text">
+      Drag my title bar to move me. PIN toggles between following you and
+      staying put. MIN collapses me to the title bar.
+    </span>
+  </div>
+</div>

package/Examples/controls/controls.uikitml

@@ -0,0 +1,49 @@
+<style>
+  .panel {
+    display: flex;
+    flex-direction: column;
+    width: 300;
+    padding: 10;
+    background-color: rgba(16, 26, 38, 0.92);
+    border-radius: 12.5;
+  }
+  .row { display: flex; flex-direction: row; align-items: center; justify-content: space-between; width: 100%; margin-top: 7; }
+  .label { font-size: 11; color: #9fb8d4; }
+  .stepper { display: flex; flex-direction: row; align-items: center; }
+  .stepper-button { padding: 4; font-size: 13; color: #eaf6ff; background-color: #2c4a6b; border-radius: 6; cursor: pointer; }
+  .stepper-value { font-size: 13; color: #ffffff; margin-left: 7; margin-right: 7; }
+  .toggle { padding: 5.5; border-radius: 7; cursor: pointer; }
+  .toggle-label { font-size: 11; font-weight: bold; color: #ffffff; }
+  .long { display: flex; flex-direction: column; width: 100%; margin-top: 8; }
+  .long-text { font-size: 9.5; color: #c4d6ea; }
+  .long-toggle { margin-top: 3; font-size: 9.5; color: #6fb4ff; cursor: pointer; }
+  .log { display: flex; flex-direction: column; width: 100%; margin-top: 8; }
+  .log-line { font-size: 9; color: #9fe0a8; margin-top: 2; }
+</style>
+<div class="panel">
+  <div class="row">
+    <span class="label">Volume</span>
+    <div data-uix="stepper" data-uix-id="volume" data-uix-min="0" data-uix-max="10" class="stepper">
+      <div data-uix-role="decrement" class="stepper-button">-</div>
+      <span data-uix-role="value" class="stepper-value">.</span>
+      <div data-uix-role="increment" class="stepper-button">+</div>
+    </div>
+  </div>
+  <div class="row">
+    <span class="label">Music</span>
+    <div data-uix="toggle" data-uix-id="music" data-uix-on-color="#1f6d3d" data-uix-off-color="#5a3037" class="toggle">
+      <span data-uix-role="label" class="toggle-label">.</span>
+    </div>
+  </div>
+  <div data-uix="expandable-label" data-uix-id="details" data-uix-lines="2" data-uix-chars-per-line="40"
+       data-uix-text="Long descriptive text collapses to two lines with an ellipsis, and the more/less affordance expands it in place - no scrolling, no clipping."
+       class="long">
+    <span data-uix-role="text" class="long-text">.</span>
+    <div data-uix-role="toggle" class="long-toggle">more</div>
+  </div>
+  <div data-uix="log-view" data-uix-id="log" class="log">
+    <span data-uix-role="line" class="log-line">.</span>
+    <span data-uix-role="line" class="log-line">.</span>
+    <span data-uix-role="line" class="log-line">.</span>
+  </div>
+</div>

package/Examples/controls/main.ts

@@ -0,0 +1,48 @@
+/**
+ * Controls - data-uix markup upgrades on any IWSDK panel.
+ *
+ * The controls work in plain panels too (no window required): the
+ * UIControlsSystem upgrades every loaded PanelDocument.
+ */
+import { PanelDocument, PanelUI, UIKitDocument, World, createSystem, eq } from '@iwsdk/core';
+import {
+  registerUIExtensions,
+  upgradePanel,
+  type UixElement,
+} from '@realitycollective/iwsdk-uiextensions';
+
+export async function start(container: HTMLDivElement) {
+  const world = await World.create(container, {
+    features: { spatialUI: true },
+  });
+  registerUIExtensions(world);
+
+  // `config` is the only field PanelUI carries in IWSDK 0.5. maxWidth/maxHeight
+  // were removed from the schema; ECS ignores unknown fields silently, so
+  // writing them here would mis-size the panel with no error. Size a panel
+  // through createUIWindow instead, which routes to UIWindow.targetWidth/Height.
+  const panel = world
+    .createTransformEntity()
+    .addComponent(PanelUI, { config: './ui/controls.uikitml' });
+  panel.object3D!.position.set(0, 1.5, -1.2);
+
+  // Wire the handles once the panel loads.
+  class WireSystem extends createSystem({
+    panel: {
+      required: [PanelUI, PanelDocument],
+      where: [eq(PanelUI, 'config', './ui/controls.uikitml')],
+    },
+  }) {
+    override init(): void {
+      this.queries.panel.subscribe('qualify', (entity) => {
+        const document = PanelDocument.data.document[entity.index] as UIKitDocument;
+        // upgradePanel is idempotent - safe regardless of system order.
+        const controls = upgradePanel(document, document.rootElement as unknown as UixElement);
+        const log = controls.logView('log');
+        controls.stepper('volume').events.on('change', (v) => log.push(`volume ${v}`));
+        controls.toggle('music').events.on('change', (on) => log.push(`music ${on ? 'on' : 'off'}`));
+      });
+    }
+  }
+  world.registerSystem(WireSystem);
+}

package/Examples/dock-regions/main.ts

@@ -0,0 +1,55 @@
+/**
+ * Dock regions - snap windows into named layout regions.
+ *
+ * A region is an anchor entity with slot layout (row / column / grid).
+ * Drop a window inside its snap radius to dock it; drag it out to undock.
+ * Regions can follow the player, turning their contents into a toolbar.
+ */
+import { World } from '@iwsdk/core';
+import {
+  createDockRegion,
+  createUIWindow,
+  registerUIExtensions,
+} from '@realitycollective/iwsdk-uiextensions';
+
+export async function start(container: HTMLDivElement) {
+  const world = await World.create(container, {
+    features: { spatialUI: true },
+  });
+  registerUIExtensions(world);
+
+  // A world-locked column on the wall - drop windows to stack them.
+  createDockRegion(world, {
+    id: 'wall',
+    flow: 'column',
+    pitch: 0.6,
+    capacity: 3,
+    snapRadius: 0.65,
+    position: [1.6, 1.9, -1.5],
+  });
+
+  // A row that follows the player - a floating toolbar.
+  createDockRegion(world, {
+    id: 'toolbar',
+    flow: 'row',
+    pitch: 0.55,
+    follow: true,
+    followOffset: [0, -0.7, -1.1],
+  });
+
+  // Spawn a window straight into a region…
+  createUIWindow(world, {
+    id: 'docked',
+    title: 'Docked Window',
+    config: './ui/window.uikitml',
+    region: 'wall',
+  });
+
+  // …and one free-floating to drag into either region.
+  createUIWindow(world, {
+    id: 'floating',
+    title: 'Drag Me Into A Region',
+    config: './ui/window.uikitml',
+    position: [0, 1.5, -1.4],
+  });
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reality Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @realitycollective/iwsdk-uiextensions
+
+Windowing, docking, layout regions and extra controls for [Meta's Immersive Web SDK](https://iwsdk.dev) (`@iwsdk/core`).
+
+**This is the Meta IWSDK adapter** - and the reference implementation - for the engine-free [`@realitycollective/webxr-uiextensions`](../webxr-uiextensions/README.md) core, which it re-exports in full: one dependency gets IWSDK apps the whole surface. (A sibling [`@realitycollective/xrblocks-uiextensions`](../xrblocks-uiextensions/README.md) adapter binds the same core to Google XR Blocks, experimentally.)
+
+**Reuse, not recreation.** The IWSDK already ships an excellent spatial UI stack - UIKitML markup, `@pmndrs/uikit` rendering, `Follower`/`ScreenSpace` anchoring, grab/ray/poke interaction. This package adds the missing layer above it:
+
+| Feature | What you get |
+| --- | --- |
+| **Windows** | Title-bar chrome (pin / minimize / close), focus & z-ordering, a per-world `WindowManager` with typed events |
+| **Dock states** | `world-locked` (place in space) ⇄ `body-follow` (lazy follow) ⇄ `head-locked`, realised with the IWSDK's own `Follower`/`ScreenSpace` |
+| **Manipulation** | Drag windows by the title bar (powered by `@pmndrs/handle`, the same library behind IWSDK grabbing), billboard-while-dragging, drop-to-dock |
+| **Layout regions** | Named regions (row / column / grid slots) windows snap into; regions can themselves follow the player |
+| **Controls** | `data-uix` markup upgrades: **stepper**, **toggle**, **expandable multi-line label**, **log/list view** - plus everything UIKitML already has (buttons, inputs, textareas, images, and the horizon kit's Slider/Checkbox/…) |
+
+Everything is authored in plain UIKitML (HTML/CSS-like) - no new markup language, no custom renderer, no wrapper widgets around things the IWSDK already does.
+
+## Install
+
+```bash
+npm install @realitycollective/iwsdk-uiextensions
+# peer: @iwsdk/core >=0.5.0 <0.6.0
+```
+
+## Quick start
+
+```ts
+import { World } from '@iwsdk/core';
+import {
+  registerUIExtensions,
+  createUIWindow,
+  createDockRegion,
+  DockMode,
+} from '@realitycollective/iwsdk-uiextensions';
+
+const world = await World.create(container, {
+  features: { spatialUI: true },
+});
+
+const windows = registerUIExtensions(world); // registers all systems, returns the WindowManager
+
+createDockRegion(world, { id: 'wall', flow: 'column', position: [1.5, 1.8, -1.5] });
+
+createUIWindow(world, {
+  id: 'status',
+  title: 'Player Status',
+  config: './ui/status.uikitml', // UIKitML source; IWSDK 0.5 parses it at runtime
+  dockMode: DockMode.BodyFollow,   // follows until the user pins it
+});
+
+windows.events.on('closed', (w) => console.log(`${w.title} closed`));
+```
+
+### Window markup
+
+Windows are ordinary UIKitML panels; the chrome is discovered by well-known element ids (only the ids are contractual - restyle freely):
+
+```html
+<div id="uix-window" class="my-window">
+  <div id="uix-titlebar" class="my-titlebar">      <!-- drag surface -->
+    <span id="uix-title" class="my-title">.</span>
+    <div id="uix-pin">PIN</div>                    <!-- follow ⇄ placed; label auto-syncs to PIN/UNPIN -->
+    <div id="uix-dock">DOCK</div>                  <!-- return to home (spawn region / placement) -->
+    <div id="uix-minimize">MIN</div>
+    <div id="uix-close">X</div>
+  </div>
+  <div id="uix-content">
+    <!-- window body -->
+  </div>
+</div>
+```
+
+> Use `<div>`s (not `<button>`s) for chrome buttons: with a component kit registered, lowercase `<button>` resolves to the kit's Button component, whose intrinsic sizing fights compact title-bar chrome.
+
+### Controls markup
+
+Annotate any element with `data-uix` and the `UIControlsSystem` upgrades it - in any panel, not just windows:
+
+```html
+<div data-uix="stepper" data-uix-id="health" data-uix-min="0" data-uix-max="100" data-uix-step="10">
+  <button data-uix-role="decrement">-</button>
+  <span data-uix-role="value">.</span>
+  <button data-uix-role="increment">+</button>
+</div>
+```
+
+```ts
+import { panelControlsFor } from '@realitycollective/iwsdk-uiextensions';
+
+const controls = panelControlsFor(document); // the panel's UIKitDocument
+controls.stepper('health').events.on('change', (hp) => setHealth(hp));
+```
+
+> UIKitML note: every dynamic-text element needs a literal placeholder child (`<span data-uix-role="value">.</span>`) or no Text node is created.
+
+### Interaction model
+
+- **Drag** the title bar with the ray (or mouse on desktop) to move a window; it billboards toward you while dragging and settles facing you when released. A press only becomes a drag after `dragDelay` seconds (default 0.3, per-window on `UIWindow`) - shorter presses stay clicks, and the chrome buttons swallow their presses entirely, so PIN/DOCK/MIN/X never fight the drag gesture.
+- **Drop** a window inside a region's snap radius to dock it into the next slot; drag it out again to undock.
+- **Pin** toggles `body-follow` ⇄ `world-locked` ("place in space").
+- Dragging a following window implicitly places it - pin re-attaches it.
+
+See `Examples/` (shipped in this package) and the deployable showcase client in the repository for complete, working demonstrations of every feature.
+
+## Windows and panel readiness
+
+`createUIWindow` returns the ECS entity, which is what you want when you are going to add components to it. When you want the PANEL, use the scene host: `createWindow` gives you a handle that resolves itself.
+
+```ts
+import { createSceneHost, getPanelHandle } from '@realitycollective/iwsdk-uiextensions';
+
+const host = createSceneHost(world);          // call after registerUIExtensions(world)
+
+const status = host.createWindow({
+  id: 'status',                                // optional - omit and you get uix-window-<n>
+  title: 'Player Status',
+  config: './ui/status.uikitml',
+});
+
+status.panel;                                  // undefined until IWSDK attaches the document
+status.onReady((panel) => {                    // runs once, immediately if it is already there
+  panel.getElementById('uix-title');
+});
+status.entity;                                 // still the entity, for ECS work
+```
+
+`getPanelHandle(entity)` does the same lookup for an entity you already hold, and returns `undefined` while the document is still loading.
+
+Across a whole scene, subscribe to the host instead:
+
+```ts
+host.onPanelReady(({ id, panel, kind }) => {
+  if (kind === 'panel') {
+    // A bare PanelUI entity with no UIWindow: `id` is its config path.
+    return;
+  }
+  wireMyWindow(id, panel);
+});
+```
+
+Bare panels are announced as well as managed windows, which is how devtools and hand-built `PanelUI` entities show up in the same stream. `supportsStandalonePanels` is `false` on this host: IWSDK owns panel lifecycles through the ECS, so `createPanel()` throws rather than half-working. Spawn a window instead.
+
+## Headless core
+
+All decision logic (window manager, dock state machine, region slot math, drag math, control models) lives in `@realitycollective/webxr-uiextensions` - pure TypeScript with no engine imports, tested at 100% coverage. The ECS systems in this package are thin appliers of that core onto `@iwsdk/core` components.
+
+## Live demos
+
+- Showcase: **[webxr-uiextensions.pages.dev](https://webxr-uiextensions.pages.dev)**
+- Multiplatform lab: **[webxr-uix-lab.pages.dev](https://webxr-uix-lab.pages.dev)**
+
+## License
+
+MIT © Reality Collective

package/dist/component-set.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The UIKitML component set for `<uix-*>` control elements.
+ *
+ * IWSDK 0.5 parses panels with `@drawcall/uikitml`, which validates every tag
+ * against a component schema and rejects anything it does not know - including
+ * every `data-*` attribute on a built-in tag. Declaring the control elements
+ * here is the supported way to extend that vocabulary.
+ *
+ * The three.js and XR Blocks adapters need no equivalent: their parser accepts
+ * custom tags unregistered, exposing the tag on
+ * `userData.customElement.componentName`. This set reproduces that convention
+ * on the IWSDK side - the constructor below stamps the same key and lifts
+ * `data-uix-*` attributes into `userData` - so ONE markup file drives every
+ * adapter and the engine-free upgraders read it identically everywhere.
+ *
+ * Register it when creating the world:
+ * ```ts
+ * const world = await World.create(container, {
+ *   features: { spatialUI: { kit: 'horizon', componentSets: [uixComponentSet] } },
+ * });
+ * ```
+ */
+import { type ComponentSet } from '@drawcall/uikitml';
+/**
+ * Pass to `spatialUI.componentSets` so `<uix-*>` elements parse on IWSDK 0.5.
+ * Without it, a panel using any control fails to parse and never attaches.
+ */
+export declare const uixComponentSet: ComponentSet;

package/dist/component-set.js

@@ -0,0 +1,108 @@
+/**
+ * The UIKitML component set for `<uix-*>` control elements.
+ *
+ * IWSDK 0.5 parses panels with `@drawcall/uikitml`, which validates every tag
+ * against a component schema and rejects anything it does not know - including
+ * every `data-*` attribute on a built-in tag. Declaring the control elements
+ * here is the supported way to extend that vocabulary.
+ *
+ * The three.js and XR Blocks adapters need no equivalent: their parser accepts
+ * custom tags unregistered, exposing the tag on
+ * `userData.customElement.componentName`. This set reproduces that convention
+ * on the IWSDK side - the constructor below stamps the same key and lifts
+ * `data-uix-*` attributes into `userData` - so ONE markup file drives every
+ * adapter and the engine-free upgraders read it identically everywhere.
+ *
+ * Register it when creating the world:
+ * ```ts
+ * const world = await World.create(container, {
+ *   features: { spatialUI: { kit: 'horizon', componentSets: [uixComponentSet] } },
+ * });
+ * ```
+ */
+import { htmlComponentSet } from '@drawcall/uikitml';
+import { z } from 'zod';
+/**
+ * Base container, taken from the parser's own `<div>` definition rather than
+ * imported from `@pmndrs/uikit` directly - that keeps a single copy of uikit
+ * in the tree, whichever version `@iwsdk/core` resolves.
+ */
+const BaseContainer = htmlComponentSet['div']
+    ?.component;
+/** Control elements an author writes, and the parts that live inside them. */
+const CONTROL_TAGS = [
+    'uix-stepper',
+    'uix-toggle',
+    'uix-expandable-label',
+    'uix-log-view',
+];
+const ROLE_TAGS = [
+    'uix-decrement',
+    'uix-value',
+    'uix-increment',
+    'uix-label',
+    'uix-line',
+    'uix-up',
+    'uix-down',
+    'uix-clear',
+    'uix-status',
+    'uix-text',
+    'uix-more',
+];
+/**
+ * `data-uix-min` → `uixMin`, matching how the other parser fills userData.
+ *
+ * The parser hands properties over already camelCased, so `data-uix-min`
+ * arrives as `dataUixMin`; both spellings are normalised here.
+ */
+function toUserDataKey(attribute) {
+    if (/^data[A-Z]/.test(attribute)) {
+        const rest = attribute.slice(4);
+        return rest.charAt(0).toLowerCase() + rest.slice(1);
+    }
+    return attribute
+        .replace(/^data-/, '')
+        .replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * A plain uikit Container that records what it was declared as.
+ *
+ * Anything the schema let through that is not a uikit property - the
+ * `data-uix-*` parameters - is moved into `userData` rather than handed to
+ * uikit, which would warn about properties it does not recognise.
+ */
+function controlComponent(tag) {
+    return class UixControlContainer extends BaseContainer {
+        constructor(properties = {}) {
+            const uikitProps = {};
+            const userData = {};
+            for (const [key, value] of Object.entries(properties)) {
+                if (key.startsWith('data-') || /^data[A-Z]/.test(key)) {
+                    userData[toUserDataKey(key)] = value;
+                }
+                else {
+                    uikitProps[key] = value;
+                }
+            }
+            super(uikitProps);
+            Object.assign(this.userData, userData, {
+                customElement: { componentName: tag, sourceTag: tag },
+            });
+        }
+    };
+}
+/** Permissive: the parameters are ours, and the upgraders validate them. */
+const schema = z.object({}).passthrough();
+function define(tag) {
+    return {
+        component: controlComponent(tag),
+        schema,
+        canHaveChildren: true,
+    };
+}
+/**
+ * Pass to `spatialUI.componentSets` so `<uix-*>` elements parse on IWSDK 0.5.
+ * Without it, a panel using any control fails to parse and never attaches.
+ */
+export const uixComponentSet = Object.fromEntries([...CONTROL_TAGS, ...ROLE_TAGS].map((tag) => [tag, define(tag)]));
+//# sourceMappingURL=component-set.js.map

package/dist/component-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-set.js","sourceRoot":"","sources":["../src/component-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,gBAAgB,EAA+C,MAAM,mBAAmB,CAAC;AAClG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,aAAa,GAAG,gBAAgB,CAAC,KAAK,CAAC;IAC3C,EAAE,SAEH,CAAC;AAEF,8EAA8E;AAC9E,MAAM,YAAY,GAAG;IACnB,aAAa;IACb,YAAY;IACZ,sBAAsB;IACtB,cAAc;CACN,CAAC;AAEX,MAAM,SAAS,GAAG;IAChB,eAAe;IACf,WAAW;IACX,eAAe;IACf,WAAW;IACX,UAAU;IACV,QAAQ;IACR,UAAU;IACV,WAAW;IACX,YAAY;IACZ,UAAU;IACV,UAAU;CACF,CAAC;AAEX;;;;;GAKG;AACH,SAAS,aAAa,CAAC,SAAiB;IACtC,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,SAAS;SACb,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,OAAO,MAAM,mBAAoB,SAAQ,aAAa;QACpD,YAAY,aAAsC,EAAE;YAClD,MAAM,UAAU,GAA4B,EAAE,CAAC;YAC/C,MAAM,QAAQ,GAA4B,EAAE,CAAC;YAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;gBACtD,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBACtD,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;gBACvC,CAAC;qBAAM,CAAC;oBACN,UAAU,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAC1B,CAAC;YACH,CAAC;YACD,KAAK,CAAC,UAAU,CAAC,CAAC;YAClB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE;gBACrC,aAAa,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE;aACtD,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AAE1C,SAAS,MAAM,CAAC,GAAW;IACzB,OAAO;QACL,SAAS,EAAE,gBAAgB,CAAC,GAAG,CAAgD;QAC/E,MAAM;QACN,eAAe,EAAE,IAAI;KACtB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAiB,MAAM,CAAC,WAAW,CAC7D,CAAC,GAAG,YAAY,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CACjE,CAAC","sourcesContent":["/**\n * The UIKitML component set for `<uix-*>` control elements.\n *\n * IWSDK 0.5 parses panels with `@drawcall/uikitml`, which validates every tag\n * against a component schema and rejects anything it does not know - including\n * every `data-*` attribute on a built-in tag. Declaring the control elements\n * here is the supported way to extend that vocabulary.\n *\n * The three.js and XR Blocks adapters need no equivalent: their parser accepts\n * custom tags unregistered, exposing the tag on\n * `userData.customElement.componentName`. This set reproduces that convention\n * on the IWSDK side - the constructor below stamps the same key and lifts\n * `data-uix-*` attributes into `userData` - so ONE markup file drives every\n * adapter and the engine-free upgraders read it identically everywhere.\n *\n * Register it when creating the world:\n * ```ts\n * const world = await World.create(container, {\n *   features: { spatialUI: { kit: 'horizon', componentSets: [uixComponentSet] } },\n * });\n * ```\n */\nimport { htmlComponentSet, type ComponentSet, type ComponentDefinition } from '@drawcall/uikitml';\nimport { z } from 'zod';\n\n/**\n * Base container, taken from the parser's own `<div>` definition rather than\n * imported from `@pmndrs/uikit` directly - that keeps a single copy of uikit\n * in the tree, whichever version `@iwsdk/core` resolves.\n */\nconst BaseContainer = htmlComponentSet['div']\n  ?.component as unknown as new (properties?: Record<string, unknown>) => {\n  userData: Record<string, unknown>;\n};\n\n/** Control elements an author writes, and the parts that live inside them. */\nconst CONTROL_TAGS = [\n  'uix-stepper',\n  'uix-toggle',\n  'uix-expandable-label',\n  'uix-log-view',\n] as const;\n\nconst ROLE_TAGS = [\n  'uix-decrement',\n  'uix-value',\n  'uix-increment',\n  'uix-label',\n  'uix-line',\n  'uix-up',\n  'uix-down',\n  'uix-clear',\n  'uix-status',\n  'uix-text',\n  'uix-more',\n] as const;\n\n/**\n * `data-uix-min` → `uixMin`, matching how the other parser fills userData.\n *\n * The parser hands properties over already camelCased, so `data-uix-min`\n * arrives as `dataUixMin`; both spellings are normalised here.\n */\nfunction toUserDataKey(attribute: string): string {\n  if (/^data[A-Z]/.test(attribute)) {\n    const rest = attribute.slice(4);\n    return rest.charAt(0).toLowerCase() + rest.slice(1);\n  }\n  return attribute\n    .replace(/^data-/, '')\n    .replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());\n}\n\n/**\n * A plain uikit Container that records what it was declared as.\n *\n * Anything the schema let through that is not a uikit property - the\n * `data-uix-*` parameters - is moved into `userData` rather than handed to\n * uikit, which would warn about properties it does not recognise.\n */\nfunction controlComponent(tag: string): typeof BaseContainer {\n  return class UixControlContainer extends BaseContainer {\n    constructor(properties: Record<string, unknown> = {}) {\n      const uikitProps: Record<string, unknown> = {};\n      const userData: Record<string, unknown> = {};\n      for (const [key, value] of Object.entries(properties)) {\n        if (key.startsWith('data-') || /^data[A-Z]/.test(key)) {\n          userData[toUserDataKey(key)] = value;\n        } else {\n          uikitProps[key] = value;\n        }\n      }\n      super(uikitProps);\n      Object.assign(this.userData, userData, {\n        customElement: { componentName: tag, sourceTag: tag },\n      });\n    }\n  };\n}\n\n/** Permissive: the parameters are ours, and the upgraders validate them. */\nconst schema = z.object({}).passthrough();\n\nfunction define(tag: string): ComponentDefinition {\n  return {\n    component: controlComponent(tag) as unknown as ComponentDefinition['component'],\n    schema,\n    canHaveChildren: true,\n  };\n}\n\n/**\n * Pass to `spatialUI.componentSets` so `<uix-*>` elements parse on IWSDK 0.5.\n * Without it, a panel using any control fails to parse and never attaches.\n */\nexport const uixComponentSet: ComponentSet = Object.fromEntries(\n  [...CONTROL_TAGS, ...ROLE_TAGS].map((tag) => [tag, define(tag)]),\n);\n"]}