@realitycollective/webxr-uiextensions 0.1.0-preview.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# 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.
+
+[0.1.0]: https://github.com/realitycollective/WebXR-UIExtensions/commits/main

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,61 @@
+# @realitycollective/webxr-uiextensions
+
+The core of the Reality Collective UI Extensions. It provides:
+
+- **Windows** - movable, resizable panels with a title bar and pin, dock, minimise and close buttons.
+- **Docking** - snapping a window into a named region of the scene, such as a row along a wall.
+- **Layout regions** - the named areas that windows snap into.
+- **Drag maths** - the pure calculations behind dragging, dropping and following the user.
+- **Controls** - the state behind steppers, toggles, expandable sections and log views.
+- **Markup upgrading** - code that turns a plain element carrying a `data-uix` attribute into a working control, so you write markup rather than components.
+- **Adapter interfaces** - what an engine package must implement to host all of the above.
+
+**This package has zero runtime dependencies and imports no 3D engine.** A test, `test/architecture.test.ts`, fails the moment `three`, `@iwsdk/*`, `@pmndrs/*` or `xrblocks` appears anywhere in `src/`. That is what lets the same interface run unchanged on every three.js WebXR runtime.
+
+## You probably want an adapter, not this package
+
+| Your engine | Install | Status |
+| --- | --- | --- |
+| Meta IWSDK (Quest / Horizon OS) | [`@realitycollective/iwsdk-uiextensions`](../iwsdk-uiextensions/README.md) | reference adapter, full feature set |
+| Google XR Blocks / plain three.js | [`@realitycollective/xrblocks-uiextensions`](../xrblocks-uiextensions/README.md) | **experimental**, partial feature set |
+
+Both adapters re-export everything here, so an app installs one package only. Depend on the core directly when writing headless logic, tests, tooling - or a new adapter.
+
+## What lives here
+
+```
+src/core/       window manager, dock state machine, region slot math,
+                drag math, hold-to-drag, control models (stepper/toggle/
+                expandable/log) - pure logic, 100% coverage gated
+src/controls/   data-uix markup upgraders, driven through the structural
+                UixElement interface (works on ANY conforming element tree)
+src/chrome/     window chrome conventions: contractual element ids
+                (uix-titlebar, uix-pin, ...) + reference UIKitML snippet
+src/adapter.ts  the platform-adapter contract: PanelHost, PanelHandle,
+                HeadPoseSource, PointerInputSource (plain tuples, no engine)
+```
+
+## Writing an adapter
+
+An adapter supplies three capabilities and drives the core from its frame loop:
+
+1. **Panels** - implement `PanelHost.createPanel(configJson)`: turn compiled UIKitML JSON into a live panel whose element tree satisfies `UixElement` (uikit does out of the box; ids land in `userData`).
+2. **Input** - deliver press/move/release into the core's `HoldToDrag` + drag math, or wire chrome clicks straight to `WindowManager`.
+3. **Viewer pose** - implement `HeadPoseSource` for follow mode and body-locked regions.
+
+The IWSDK adapter is the reference implementation; the XR Blocks adapter shows the same contract bound without an ECS.
+
+## Testing
+
+```bash
+npm test   # from the workspace root - vitest, 100% thresholds on src/core
+```
+
+## 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/adapter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Platform-adapter contract.
+ *
+ * The core package owns every UX decision - window lifecycle, dock state,
+ * region slot math, drag math, control models - and knows nothing about any
+ * engine. An engine adapter supplies the three capabilities the core cannot
+ * provide for itself, and drives the core from its own frame loop:
+ *
+ *  - {@link PanelHost}: turn compiled UIKitML JSON into a live spatial panel
+ *  - {@link PointerInputSource}: deliver ray/pointer press-move-release
+ *  - {@link HeadPoseSource}: the viewer pose, for follow mode & body-lock
+ *
+ * Known adapters:
+ *  - `@realitycollective/iwsdk-uiextensions` - Meta IWSDK (ECS systems bind
+ *    these capabilities to `@iwsdk/core` components)
+ *  - `@realitycollective/xrblocks-uiextensions` - Google XR Blocks / plain
+ *    three.js (experimental)
+ *
+ * The interfaces use plain tuples/records only - no engine, no three.js.
+ */
+import type { UixElement } from './controls/element.js';
+/** Position as [x, y, z] in meters, world space unless stated otherwise. */
+export type Vec3Tuple = [number, number, number];
+/** Orientation quaternion as [x, y, z, w]. */
+export type QuatTuple = [number, number, number, number];
+/** A viewer (head) pose sample. */
+export interface HeadPose {
+    position: Vec3Tuple;
+    quaternion: QuatTuple;
+}
+/** Supplies the viewer pose each frame - camera on desktop, HMD in XR. */
+export interface HeadPoseSource {
+    getHeadPose(): HeadPose;
+}
+/**
+ * A live spatial panel created from compiled UIKitML JSON.
+ * The `root` is traversable with the core's `walk`/`findRole` helpers and
+ * the `data-uix` control upgraders - identical markup works on every
+ * adapter.
+ */
+export interface PanelHandle {
+    /** Root element of the interpreted panel (UixElement-conformant). */
+    readonly root: UixElement;
+    /** Look up an element by its markup `id`. */
+    getElementById(id: string): UixElement | undefined;
+    /** Constrain the panel to fit within width × height meters. */
+    setTargetDimensions(width: number, height: number): void;
+    /** Release panel resources. */
+    dispose(): void;
+}
+/** Creates spatial panels - the engine-specific half of UIKitML rendering. */
+export interface PanelHost {
+    /**
+     * Create a panel from compiled UIKitML JSON (the `{ element, classes }`
+     * shape produced by the build plugin or by
+     * `@realitycollective/uix-devtools`' `compilePanelSource`).
+     */
+    createPanel(configJson: unknown): PanelHandle;
+}
+/**
+ * A window whose panel has finished loading and is ready to be wired.
+ * Delivered by {@link WindowHost.onPanelReady}.
+ */
+export interface PanelReadyEvent {
+    /** The window's id, as given to the scene descriptor / create call. */
+    id: string;
+    /** The live panel - traverse it, or look elements up by markup id. */
+    panel: PanelHandle;
+}
+/**
+ * The engine-agnostic surface an app needs to build a UI: spawn windows and
+ * regions from portable data, observe when panels become wireable, and reach
+ * the shared `WindowManager`.
+ *
+ * Panels load asynchronously on every adapter (IWSDK fetches the config;
+ * uikit lays out over following frames), so app code must never assume a
+ * panel exists immediately after creating its window. {@link onPanelReady}
+ * is the portable answer - it replaces engine-specific discovery (ECS
+ * queries on IWSDK, polling anywhere else) and fires for panels that became
+ * ready before the listener was registered, so wiring order never matters.
+ */
+export interface WindowHost extends PanelHost {
+    /**
+     * Subscribe to panel readiness. Late subscribers are replayed the windows
+     * that are already live. Returns an unsubscribe function.
+     */
+    onPanelReady(listener: (event: PanelReadyEvent) => void): () => void;
+}
+/** One pointer/ray interaction stream, engine-normalised. */
+export interface PointerSample {
+    /** Pointer world position (ray origin or touch point). */
+    origin: Vec3Tuple;
+    /** Normalised pointing direction. */
+    direction: Vec3Tuple;
+}
+/**
+ * Delivers press-move-release for one interaction source (a controller ray,
+ * a hand pinch, a mouse). The core's `hold-to-drag` and `drag-math` consume
+ * these; the adapter decides what constitutes press/release.
+ */
+export interface PointerInputSource {
+    onPress(listener: (sample: PointerSample) => void): () => void;
+    onMove(listener: (sample: PointerSample) => void): () => void;
+    onRelease(listener: (sample: PointerSample) => void): () => void;
+}

package/dist/adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +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 * 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.\n */\nimport type { UixElement } from './controls/element.js';\n\n/** Position as [x, y, z] in meters, world space unless stated otherwise. */\nexport type Vec3Tuple = [number, number, number];\n\n/** Orientation quaternion as [x, y, z, w]. */\nexport type QuatTuple = [number, number, number, number];\n\n/** A viewer (head) pose sample. */\nexport interface HeadPose {\n  position: Vec3Tuple;\n  quaternion: QuatTuple;\n}\n\n/** Supplies the viewer pose each frame - camera on desktop, HMD in XR. */\nexport interface HeadPoseSource {\n  getHeadPose(): HeadPose;\n}\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\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   * 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/** One pointer/ray interaction stream, engine-normalised. */\nexport interface PointerSample {\n  /** Pointer world position (ray origin or touch point). */\n  origin: Vec3Tuple;\n  /** Normalised pointing direction. */\n  direction: Vec3Tuple;\n}\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/dist/chrome/markup.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Window chrome conventions.
+ *
+ * Windows are authored in UIKitML like any other IWSDK panel - the chrome is
+ * plain markup discovered by well-known element ids, not a parallel widget
+ * tree. Copy `WINDOW_CHROME_SNIPPET` into a `.uikitml` file and put the
+ * window body inside the `uix-content` element.
+ */
+export declare const WINDOW_CHROME_IDS: {
+    /** Root container of the window. */
+    readonly window: "uix-window";
+    /** Drag surface; also focuses the window on press. */
+    readonly titlebar: "uix-titlebar";
+    /** Text element receiving `UIWindow.title`. */
+    readonly title: "uix-title";
+    /** Toggles body-follow ⇄ world-locked; label auto-syncs to PIN/UNPIN. */
+    readonly pin: "uix-pin";
+    /** Returns the window to its home (spawn region or original placement). */
+    readonly dock: "uix-dock";
+    /** Minimize/restore toggle. */
+    readonly minimize: "uix-minimize";
+    /** Closes (destroys) the window. */
+    readonly close: "uix-close";
+    /** Collapsed while minimized. */
+    readonly content: "uix-content";
+};
+/**
+ * Reference chrome markup. The styles are intentionally minimal - restyle
+ * freely, only the element ids are contractual.
+ *
+ * Notes:
+ * - The placeholder "." in `uix-title`: UIKitML only creates a Text node for
+ *   elements with a literal string child, so dynamic text needs one.
+ * - The chrome buttons are `<div>`s on purpose: when an app registers a
+ *   component kit (e.g. `@pmndrs/uikit-horizon`), lowercase `<button>` tags
+ *   resolve to the kit's Button component, whose intrinsic sizing fights
+ *   compact title-bar chrome. Plain containers stay fully styleable and
+ *   still receive click events.
+ */
+export declare const WINDOW_CHROME_SNIPPET = "\n<div id=\"uix-window\" class=\"uix-window\">\n  <div id=\"uix-titlebar\" class=\"uix-titlebar\">\n    <span id=\"uix-title\" class=\"uix-title\">.</span>\n    <div class=\"uix-titlebar-buttons\">\n      <div id=\"uix-pin\" class=\"uix-titlebar-button\">PIN</div>\n      <div id=\"uix-dock\" class=\"uix-titlebar-button\">DOCK</div>\n      <div id=\"uix-minimize\" class=\"uix-titlebar-button\">MIN</div>\n      <div id=\"uix-close\" class=\"uix-titlebar-button\">X</div>\n    </div>\n  </div>\n  <div id=\"uix-content\" class=\"uix-content\">\n    <!-- window body goes here -->\n  </div>\n</div>\n";

package/dist/chrome/markup.js

@@ -0,0 +1,56 @@
+/**
+ * Window chrome conventions.
+ *
+ * Windows are authored in UIKitML like any other IWSDK panel - the chrome is
+ * plain markup discovered by well-known element ids, not a parallel widget
+ * tree. Copy `WINDOW_CHROME_SNIPPET` into a `.uikitml` file and put the
+ * window body inside the `uix-content` element.
+ */
+export const WINDOW_CHROME_IDS = {
+    /** Root container of the window. */
+    window: 'uix-window',
+    /** Drag surface; also focuses the window on press. */
+    titlebar: 'uix-titlebar',
+    /** Text element receiving `UIWindow.title`. */
+    title: 'uix-title',
+    /** Toggles body-follow ⇄ world-locked; label auto-syncs to PIN/UNPIN. */
+    pin: 'uix-pin',
+    /** Returns the window to its home (spawn region or original placement). */
+    dock: 'uix-dock',
+    /** Minimize/restore toggle. */
+    minimize: 'uix-minimize',
+    /** Closes (destroys) the window. */
+    close: 'uix-close',
+    /** Collapsed while minimized. */
+    content: 'uix-content',
+};
+/**
+ * Reference chrome markup. The styles are intentionally minimal - restyle
+ * freely, only the element ids are contractual.
+ *
+ * Notes:
+ * - The placeholder "." in `uix-title`: UIKitML only creates a Text node for
+ *   elements with a literal string child, so dynamic text needs one.
+ * - The chrome buttons are `<div>`s on purpose: when an app registers a
+ *   component kit (e.g. `@pmndrs/uikit-horizon`), lowercase `<button>` tags
+ *   resolve to the kit's Button component, whose intrinsic sizing fights
+ *   compact title-bar chrome. Plain containers stay fully styleable and
+ *   still receive click events.
+ */
+export const WINDOW_CHROME_SNIPPET = `
+<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">
+    <!-- window body goes here -->
+  </div>
+</div>
+`;
+//# sourceMappingURL=markup.js.map

package/dist/chrome/markup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markup.js","sourceRoot":"","sources":["../../src/chrome/markup.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,oCAAoC;IACpC,MAAM,EAAE,YAAY;IACpB,sDAAsD;IACtD,QAAQ,EAAE,cAAc;IACxB,+CAA+C;IAC/C,KAAK,EAAE,WAAW;IAClB,yEAAyE;IACzE,GAAG,EAAE,SAAS;IACd,2EAA2E;IAC3E,IAAI,EAAE,UAAU;IAChB,+BAA+B;IAC/B,QAAQ,EAAE,cAAc;IACxB,oCAAoC;IACpC,KAAK,EAAE,WAAW;IAClB,iCAAiC;IACjC,OAAO,EAAE,aAAa;CACd,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;CAepC,CAAC","sourcesContent":["/**\n * Window chrome conventions.\n *\n * Windows are authored in UIKitML like any other IWSDK panel - the chrome is\n * plain markup discovered by well-known element ids, not a parallel widget\n * tree. Copy `WINDOW_CHROME_SNIPPET` into a `.uikitml` file and put the\n * window body inside the `uix-content` element.\n */\nexport const WINDOW_CHROME_IDS = {\n  /** Root container of the window. */\n  window: 'uix-window',\n  /** Drag surface; also focuses the window on press. */\n  titlebar: 'uix-titlebar',\n  /** Text element receiving `UIWindow.title`. */\n  title: 'uix-title',\n  /** Toggles body-follow ⇄ world-locked; label auto-syncs to PIN/UNPIN. */\n  pin: 'uix-pin',\n  /** Returns the window to its home (spawn region or original placement). */\n  dock: 'uix-dock',\n  /** Minimize/restore toggle. */\n  minimize: 'uix-minimize',\n  /** Closes (destroys) the window. */\n  close: 'uix-close',\n  /** Collapsed while minimized. */\n  content: 'uix-content',\n} as const;\n\n/**\n * Reference chrome markup. The styles are intentionally minimal - restyle\n * freely, only the element ids are contractual.\n *\n * Notes:\n * - The placeholder \".\" in `uix-title`: UIKitML only creates a Text node for\n *   elements with a literal string child, so dynamic text needs one.\n * - The chrome buttons are `<div>`s on purpose: when an app registers a\n *   component kit (e.g. `@pmndrs/uikit-horizon`), lowercase `<button>` tags\n *   resolve to the kit's Button component, whose intrinsic sizing fights\n *   compact title-bar chrome. Plain containers stay fully styleable and\n *   still receive click events.\n */\nexport const WINDOW_CHROME_SNIPPET = `\n<div id=\"uix-window\" class=\"uix-window\">\n  <div id=\"uix-titlebar\" class=\"uix-titlebar\">\n    <span id=\"uix-title\" class=\"uix-title\">.</span>\n    <div class=\"uix-titlebar-buttons\">\n      <div id=\"uix-pin\" class=\"uix-titlebar-button\">PIN</div>\n      <div id=\"uix-dock\" class=\"uix-titlebar-button\">DOCK</div>\n      <div id=\"uix-minimize\" class=\"uix-titlebar-button\">MIN</div>\n      <div id=\"uix-close\" class=\"uix-titlebar-button\">X</div>\n    </div>\n  </div>\n  <div id=\"uix-content\" class=\"uix-content\">\n    <!-- window body goes here -->\n  </div>\n</div>\n`;\n"]}

package/dist/controls/element.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Structural view of a uikit element as the controls layer needs it.
+ *
+ * UIKitML preserves `data-*` attributes into `element.userData` (camelCased,
+ * `data-` stripped): `data-uix="stepper"` → `userData.uix`. Controls are
+ * discovered by traversing a panel's object tree for those markers - no
+ * custom uikit component classes, so any markup (or kit) works.
+ */
+export interface UixElement {
+    userData: Record<string, unknown>;
+    children: UixElement[];
+    addEventListener(type: string, listener: (event?: unknown) => void): void;
+    setProperties(props: Record<string, unknown>): void;
+}
+/** Depth-first traversal over uikit element children. */
+export declare function walk(element: UixElement, visit: (element: UixElement) => void): void;
+/** All descendants (including self) with `data-uix-role="<role>"`. */
+export declare function findRoles(root: UixElement, role: string): UixElement[];
+export declare function findRole(root: UixElement, role: string): UixElement | undefined;
+export declare function attrString(element: UixElement, key: string): string | undefined;
+export declare function attrNumber(element: UixElement, key: string): number | undefined;
+export declare function attrBoolean(element: UixElement, key: string): boolean | undefined;

package/dist/controls/element.js

@@ -0,0 +1,40 @@
+/** Depth-first traversal over uikit element children. */
+export function walk(element, visit) {
+    visit(element);
+    for (const child of element.children ?? []) {
+        walk(child, visit);
+    }
+}
+/** All descendants (including self) with `data-uix-role="<role>"`. */
+export function findRoles(root, role) {
+    const found = [];
+    walk(root, (element) => {
+        if (element.userData?.['uixRole'] === role) {
+            found.push(element);
+        }
+    });
+    return found;
+}
+export function findRole(root, role) {
+    return findRoles(root, role)[0];
+}
+export function attrString(element, key) {
+    const value = element.userData?.[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+export function attrNumber(element, key) {
+    const raw = attrString(element, key);
+    if (raw === undefined) {
+        return undefined;
+    }
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+export function attrBoolean(element, key) {
+    const raw = attrString(element, key);
+    if (raw === undefined) {
+        return undefined;
+    }
+    return raw === 'true' || raw === '1' || raw === 'on';
+}
+//# sourceMappingURL=element.js.map

package/dist/controls/element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.js","sourceRoot":"","sources":["../../src/controls/element.ts"],"names":[],"mappings":"AAeA,yDAAyD;AACzD,MAAM,UAAU,IAAI,CAAC,OAAmB,EAAE,KAAoC;IAC5E,KAAK,CAAC,OAAO,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QAC3C,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,IAAgB,EAAE,IAAY;IACtD,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE;QACrB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,IAAY;IACrD,OAAO,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAmB,EAAE,GAAW;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAmB,EAAE,GAAW;IACzD,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAmB,EAAE,GAAW;IAC1D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,IAAI,CAAC;AACvD,CAAC","sourcesContent":["/**\n * Structural view of a uikit element as the controls layer needs it.\n *\n * UIKitML preserves `data-*` attributes into `element.userData` (camelCased,\n * `data-` stripped): `data-uix=\"stepper\"` → `userData.uix`. Controls are\n * discovered by traversing a panel's object tree for those markers - no\n * custom uikit component classes, so any markup (or kit) works.\n */\nexport interface UixElement {\n  userData: Record<string, unknown>;\n  children: UixElement[];\n  addEventListener(type: string, listener: (event?: unknown) => void): void;\n  setProperties(props: Record<string, unknown>): void;\n}\n\n/** Depth-first traversal over uikit element children. */\nexport function walk(element: UixElement, visit: (element: UixElement) => void): void {\n  visit(element);\n  for (const child of element.children ?? []) {\n    walk(child, visit);\n  }\n}\n\n/** All descendants (including self) with `data-uix-role=\"<role>\"`. */\nexport function findRoles(root: UixElement, role: string): UixElement[] {\n  const found: UixElement[] = [];\n  walk(root, (element) => {\n    if (element.userData?.['uixRole'] === role) {\n      found.push(element);\n    }\n  });\n  return found;\n}\n\nexport function findRole(root: UixElement, role: string): UixElement | undefined {\n  return findRoles(root, role)[0];\n}\n\nexport function attrString(element: UixElement, key: string): string | undefined {\n  const value = element.userData?.[key];\n  return typeof value === 'string' && value.length > 0 ? value : undefined;\n}\n\nexport function attrNumber(element: UixElement, key: string): number | undefined {\n  const raw = attrString(element, key);\n  if (raw === undefined) {\n    return undefined;\n  }\n  const value = Number(raw);\n  return Number.isFinite(value) ? value : undefined;\n}\n\nexport function attrBoolean(element: UixElement, key: string): boolean | undefined {\n  const raw = attrString(element, key);\n  if (raw === undefined) {\n    return undefined;\n  }\n  return raw === 'true' || raw === '1' || raw === 'on';\n}\n"]}

package/dist/controls/expandable-label.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Expandable label - `data-uix="expandable-label"`.
+ *
+ * A multi-line label that collapses to a character budget with an ellipsis
+ * and an inline more/less affordance.
+ *
+ * ```html
+ * <div data-uix="expandable-label" data-uix-id="lore"
+ *      data-uix-lines="2" data-uix-chars-per-line="40"
+ *      data-uix-text="Long text..." class="my-label">
+ *   <span data-uix-role="text">.</span>
+ *   <button data-uix-role="toggle">more</button>
+ * </div>
+ * ```
+ */
+import { Emitter } from '../core/events.js';
+import { ExpandableModel } from '../core/expandable-model.js';
+import { UixElement } from './element.js';
+export declare class ExpandableLabelHandle {
+    readonly model: ExpandableModel;
+    private textElement;
+    private toggleElement;
+    readonly events: Emitter<{
+        change: boolean;
+    }>;
+    constructor(model: ExpandableModel, textElement: UixElement | undefined, toggleElement: UixElement | undefined);
+    get expanded(): boolean;
+    setText(text: string): void;
+    toggle(): void;
+    private render;
+}
+export declare function upgradeExpandableLabel(root: UixElement): ExpandableLabelHandle;

package/dist/controls/expandable-label.js

@@ -0,0 +1,63 @@
+/**
+ * Expandable label - `data-uix="expandable-label"`.
+ *
+ * A multi-line label that collapses to a character budget with an ellipsis
+ * and an inline more/less affordance.
+ *
+ * ```html
+ * <div data-uix="expandable-label" data-uix-id="lore"
+ *      data-uix-lines="2" data-uix-chars-per-line="40"
+ *      data-uix-text="Long text..." class="my-label">
+ *   <span data-uix-role="text">.</span>
+ *   <button data-uix-role="toggle">more</button>
+ * </div>
+ * ```
+ */
+import { Emitter } from '../core/events.js';
+import { ExpandableModel } from '../core/expandable-model.js';
+import { attrNumber, attrString, findRole } from './element.js';
+export class ExpandableLabelHandle {
+    model;
+    textElement;
+    toggleElement;
+    events = new Emitter();
+    constructor(model, textElement, toggleElement) {
+        this.model = model;
+        this.textElement = textElement;
+        this.toggleElement = toggleElement;
+        this.render();
+    }
+    get expanded() {
+        return this.model.expanded;
+    }
+    setText(text) {
+        this.model.setText(text);
+        this.render();
+    }
+    toggle() {
+        this.events.emit('change', this.model.toggle());
+        this.render();
+    }
+    render() {
+        this.textElement?.setProperties({ text: this.model.displayText });
+        // Hide the affordance entirely when the text fits the collapsed budget.
+        this.toggleElement?.setProperties({
+            text: this.model.toggleLabel,
+            display: this.model.overflows ? 'flex' : 'none',
+        });
+    }
+}
+export function upgradeExpandableLabel(root) {
+    const lines = attrNumber(root, 'uixLines');
+    const charsPerLine = attrNumber(root, 'uixCharsPerLine');
+    const model = new ExpandableModel({
+        text: attrString(root, 'uixText') ?? '',
+        ...(lines !== undefined && { collapsedLines: lines }),
+        ...(charsPerLine !== undefined && { charsPerLine }),
+    });
+    const toggle = findRole(root, 'toggle');
+    const handle = new ExpandableLabelHandle(model, findRole(root, 'text'), toggle);
+    toggle?.addEventListener('click', () => handle.toggle());
+    return handle;
+}
+//# sourceMappingURL=expandable-label.js.map

package/dist/controls/expandable-label.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expandable-label.js","sourceRoot":"","sources":["../../src/controls/expandable-label.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAc,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE5E,MAAM,OAAO,qBAAqB;IAIrB;IACD;IACA;IALD,MAAM,GAAG,IAAI,OAAO,EAAuB,CAAC;IAErD,YACW,KAAsB,EACvB,WAAmC,EACnC,aAAqC;QAFpC,UAAK,GAAL,KAAK,CAAiB;QACvB,gBAAW,GAAX,WAAW,CAAwB;QACnC,kBAAa,GAAb,aAAa,CAAwB;QAE7C,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC7B,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAEO,MAAM;QACZ,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QAClE,wEAAwE;QACxE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC;YAChC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW;YAC5B,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;SAChD,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAgB;IACrD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC;QAChC,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;QACvC,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;QACrD,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,CAAC;KACpD,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,qBAAqB,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IAChF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["/**\n * Expandable label - `data-uix=\"expandable-label\"`.\n *\n * A multi-line label that collapses to a character budget with an ellipsis\n * and an inline more/less affordance.\n *\n * ```html\n * <div data-uix=\"expandable-label\" data-uix-id=\"lore\"\n *      data-uix-lines=\"2\" data-uix-chars-per-line=\"40\"\n *      data-uix-text=\"Long text...\" class=\"my-label\">\n *   <span data-uix-role=\"text\">.</span>\n *   <button data-uix-role=\"toggle\">more</button>\n * </div>\n * ```\n */\nimport { Emitter } from '../core/events.js';\nimport { ExpandableModel } from '../core/expandable-model.js';\nimport { UixElement, attrNumber, attrString, findRole } from './element.js';\n\nexport class ExpandableLabelHandle {\n  readonly events = new Emitter<{ change: boolean }>();\n\n  constructor(\n    readonly model: ExpandableModel,\n    private textElement: UixElement | undefined,\n    private toggleElement: UixElement | undefined,\n  ) {\n    this.render();\n  }\n\n  get expanded(): boolean {\n    return this.model.expanded;\n  }\n\n  setText(text: string): void {\n    this.model.setText(text);\n    this.render();\n  }\n\n  toggle(): void {\n    this.events.emit('change', this.model.toggle());\n    this.render();\n  }\n\n  private render(): void {\n    this.textElement?.setProperties({ text: this.model.displayText });\n    // Hide the affordance entirely when the text fits the collapsed budget.\n    this.toggleElement?.setProperties({\n      text: this.model.toggleLabel,\n      display: this.model.overflows ? 'flex' : 'none',\n    });\n  }\n}\n\nexport function upgradeExpandableLabel(root: UixElement): ExpandableLabelHandle {\n  const lines = attrNumber(root, 'uixLines');\n  const charsPerLine = attrNumber(root, 'uixCharsPerLine');\n  const model = new ExpandableModel({\n    text: attrString(root, 'uixText') ?? '',\n    ...(lines !== undefined && { collapsedLines: lines }),\n    ...(charsPerLine !== undefined && { charsPerLine }),\n  });\n  const toggle = findRole(root, 'toggle');\n  const handle = new ExpandableLabelHandle(model, findRole(root, 'text'), toggle);\n  toggle?.addEventListener('click', () => handle.toggle());\n  return handle;\n}\n"]}

package/dist/controls/log-view.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Log view - `data-uix="log-view"`.
+ *
+ * A console-style scrolling list rendered into a fixed pool of row elements
+ * (UIKitML's text rule: each row needs a literal placeholder child). Rows
+ * are the descendants with role `line`, in document order; their count is
+ * the viewport height.
+ *
+ * ```html
+ * <div data-uix="log-view" data-uix-id="combat" data-uix-capacity="200">
+ *   <div class="rows">
+ *     <span data-uix-role="line">.</span>
+ *     <span data-uix-role="line">.</span>
+ *     <span data-uix-role="line">.</span>
+ *   </div>
+ *   <div class="log-buttons">
+ *     <button data-uix-role="up">▲</button>
+ *     <button data-uix-role="down">▼</button>
+ *     <button data-uix-role="clear">clear</button>
+ *   </div>
+ *   <span data-uix-role="status">.</span>
+ * </div>
+ * ```
+ */
+import { LogModel } from '../core/log-model.js';
+import { UixElement } from './element.js';
+export declare class LogViewHandle {
+    readonly model: LogModel;
+    private rows;
+    private statusElement;
+    constructor(model: LogModel, rows: UixElement[], statusElement: UixElement | undefined);
+    push(message: string, level?: string): void;
+    clear(): void;
+    scrollUp(rows?: number): void;
+    scrollDown(rows?: number): void;
+    private render;
+}
+export declare function upgradeLogView(root: UixElement): LogViewHandle;

package/dist/controls/log-view.js

@@ -0,0 +1,83 @@
+/**
+ * Log view - `data-uix="log-view"`.
+ *
+ * A console-style scrolling list rendered into a fixed pool of row elements
+ * (UIKitML's text rule: each row needs a literal placeholder child). Rows
+ * are the descendants with role `line`, in document order; their count is
+ * the viewport height.
+ *
+ * ```html
+ * <div data-uix="log-view" data-uix-id="combat" data-uix-capacity="200">
+ *   <div class="rows">
+ *     <span data-uix-role="line">.</span>
+ *     <span data-uix-role="line">.</span>
+ *     <span data-uix-role="line">.</span>
+ *   </div>
+ *   <div class="log-buttons">
+ *     <button data-uix-role="up">▲</button>
+ *     <button data-uix-role="down">▼</button>
+ *     <button data-uix-role="clear">clear</button>
+ *   </div>
+ *   <span data-uix-role="status">.</span>
+ * </div>
+ * ```
+ */
+import { LogModel } from '../core/log-model.js';
+import { attrNumber, findRole, findRoles } from './element.js';
+export class LogViewHandle {
+    model;
+    rows;
+    statusElement;
+    constructor(model, rows, statusElement) {
+        this.model = model;
+        this.rows = rows;
+        this.statusElement = statusElement;
+        this.render();
+    }
+    push(message, level = 'info') {
+        this.model.push(message, level);
+        this.render();
+    }
+    clear() {
+        this.model.clear();
+        this.render();
+    }
+    scrollUp(rows = 1) {
+        this.model.scrollUp(rows);
+        this.render();
+    }
+    scrollDown(rows = 1) {
+        this.model.scrollDown(rows);
+        this.render();
+    }
+    render() {
+        const visible = this.model.visible();
+        this.rows.forEach((row, index) => {
+            const entry = visible[index];
+            row.setProperties({
+                // UIKitML renders "" as empty text - exactly what vacant rows need.
+                text: entry ? entry.message : '',
+            });
+        });
+        if (this.statusElement) {
+            const suffix = this.model.isFollowing ? '' : ' (scrolled)';
+            this.statusElement.setProperties({
+                text: `${this.model.count} entries${suffix}`,
+            });
+        }
+    }
+}
+export function upgradeLogView(root) {
+    const rows = findRoles(root, 'line');
+    const capacity = attrNumber(root, 'uixCapacity');
+    const model = new LogModel({
+        visibleRows: Math.max(1, rows.length),
+        ...(capacity !== undefined && { capacity }),
+    });
+    const handle = new LogViewHandle(model, rows, findRole(root, 'status'));
+    findRole(root, 'up')?.addEventListener('click', () => handle.scrollUp());
+    findRole(root, 'down')?.addEventListener('click', () => handle.scrollDown());
+    findRole(root, 'clear')?.addEventListener('click', () => handle.clear());
+    return handle;
+}
+//# sourceMappingURL=log-view.js.map