@realitycollective/uix-devtools 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,80 @@
+# @realitycollective/uix-devtools
+
+Developer tooling for [`@realitycollective/iwsdk-uiextensions`](../iwsdk-uiextensions/README.md): an edit-session **launch gate**, **runtime UIKitML compilation** for live UX editing, and the **`uix-dev` CLI** that gets a local build onto a headset in one command via a Cloudflare quick tunnel.
+
+> **This package is dev tooling. Never ship it in a player-facing bundle.** Install it as a `devDependency`, guard every use behind a build flag, and load overlays through dynamic import. The design makes the safe path the easy path - see [Safety model](#safety-model).
+
+## Install
+
+```bash
+npm install --save-dev @realitycollective/uix-devtools
+```
+
+## The edit gate
+
+```ts
+import { installEditGate } from '@realitycollective/uix-devtools';
+
+// Guarded so production builds ELIMINATE this whole block:
+if (import.meta.env.DEV || import.meta.env.VITE_UIX_EDIT) {
+  const expected = import.meta.env.VITE_UIX_EDIT_TOKEN as string | undefined;
+  installEditGate({
+    ...(expected ? { tokens: [expected] } : {}), // no token minted → local-dev open gate
+    load: (session) =>
+      import('./editor-overlay.js').then((m) => m.install(session)),
+  });
+}
+```
+
+- The gate opens only when the page URL carries `?uix-edit=<token>` and the token is accepted. Accepted tokens are remembered in `sessionStorage` (override with `remember: false`) so in-headset reloads keep the session.
+- `load` is invoked exactly once, and a throwing/rejecting overlay is contained - it can never take the host app down.
+- `clearEditSession()` forgets a remembered token (an "exit edit mode" affordance).
+
+All parts are individually exported (`readEditToken`, `isTokenAccepted`, `resolveEditSession`) and unit-tested - see `test/gate.test.ts`.
+
+## Runtime UIKitML compilation
+
+```ts
+import { compilePanelSource } from '@realitycollective/uix-devtools';
+import { createUIWindow } from '@realitycollective/iwsdk-uiextensions';
+
+const compiled = compilePanelSource(source); // same JSON the Vite plugin emits
+if (compiled.errors.length === 0) {
+  createUIWindow(world, { id: 'live', title: 'Live', config: compiled.configUrl });
+}
+```
+
+`compilePanelSource` runs the same `parse` the build-time Vite plugin uses and serves the JSON through a `blob:` URL, which IWSDK's `PanelUI` fetches like any file - so panels can be authored, edited and respawned entirely at runtime (desktop workbench or in-headset editor). Parse problems land in `errors` instead of throwing; linked stylesheets can be resolved via the `resolveFile` option.
+
+## The `uix-dev` CLI
+
+```bash
+uix-dev tunnel [--port N] [--cwd DIR] [--no-dev-server]
+uix-dev doctor
+uix-dev qr <url>
+```
+
+`tunnel` mints a per-run edit token, starts the demo's dev server with `VITE_UIX_EDIT`/`VITE_UIX_EDIT_TOKEN` exported, opens a Cloudflare quick tunnel (`cloudflared tunnel --url`) and prints QR codes for both the plain and the edit-mode URL. HTTPS + WSS means WebXR and Vite HMR both work from the headset. `doctor` checks node/cloudflared/adb with install hints.
+
+The demo's `vite.config.ts` must allow the tunnel host and, when driven by the CLI (`UIX_DEV_TUNNEL=1`), point HMR at wss:443 - see `demos/devtools-playground/vite.config.ts` for the reference snippet.
+
+## Safety model
+
+| Layer | Mechanism | Player-facing result |
+| --- | --- | --- |
+| packaging | separate dev-only package, never imported by the runtime library | not installed → not present |
+| build | gate call guarded by `import.meta.env` flags | branch eliminated from production bundles |
+| runtime | exact-token match required; overlay is a lazy chunk | wrong/no token → nothing loads, nothing downloads |
+
+## Demo
+
+[`demos/devtools-playground`](../../demos/devtools-playground/README.md) - the shared showcase scene plus this package's gate and a live in-headset UIKitML editor window.
+
+## 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/bin/uix-dev.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli/main.js';
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/dist/cli/lib.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Extract the assigned quick-tunnel URL from a chunk of cloudflared output.
+ * cloudflared prints it (to stderr) inside a box banner once the tunnel is up.
+ */
+export declare function extractTunnelUrl(outputChunk: string): string | undefined;
+/** Mint a URL-safe random session token. */
+export declare function mintToken(bytes?: number): string;
+/** Append the edit-session token to a base URL. */
+export declare function buildEditUrl(baseUrl: string, token: string, param?: string): string;
+export interface TunnelPlan {
+    /** Local dev-server port the tunnel forwards to. */
+    port: number;
+    /** Per-run edit-session token, exported as VITE_UIX_EDIT_TOKEN. */
+    token: string;
+    /** argv for the cloudflared process. */
+    cloudflaredArgs: string[];
+    /** Environment additions for the dev-server process. */
+    devServerEnv: Record<string, string>;
+}
+/** Compute everything a `uix-dev tunnel` run needs up front. */
+export declare function planTunnel(options?: {
+    port?: number;
+    token?: string;
+}): TunnelPlan;
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+    hint?: string;
+}
+/** Interpret a `node --version` string against the workspace requirement. */
+export declare function checkNodeVersion(versionString: string): DoctorCheck;
+/** Build the doctor result for an external binary probe. */
+export declare function checkBinary(name: string, found: boolean, version: string | undefined, installHint: string): DoctorCheck;
+/** Render doctor checks as terminal lines. */
+export declare function formatDoctorReport(checks: readonly DoctorCheck[]): string;

package/dist/cli/lib.js

@@ -0,0 +1,88 @@
+/**
+ * Pure logic behind the `uix-dev` CLI - everything here is unit-testable in
+ * node with no processes spawned. The orchestration (spawning vite and
+ * cloudflared, wiring stdio) lives in `main.ts` and stays intentionally thin.
+ */
+import { randomBytes } from 'node:crypto';
+/** Matches the URL cloudflared assigns to a quick tunnel. */
+const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+/**
+ * Extract the assigned quick-tunnel URL from a chunk of cloudflared output.
+ * cloudflared prints it (to stderr) inside a box banner once the tunnel is up.
+ */
+export function extractTunnelUrl(outputChunk) {
+    const match = TUNNEL_URL_PATTERN.exec(outputChunk);
+    return match ? match[0] : undefined;
+}
+/** Mint a URL-safe random session token. */
+export function mintToken(bytes = 16) {
+    return randomBytes(bytes).toString('base64url');
+}
+/** Append the edit-session token to a base URL. */
+export function buildEditUrl(baseUrl, token, param = 'uix-edit') {
+    const url = new URL(baseUrl);
+    url.searchParams.set(param, token);
+    return url.toString();
+}
+/** Compute everything a `uix-dev tunnel` run needs up front. */
+export function planTunnel(options = {}) {
+    const port = options.port ?? 8081;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid port: ${String(options.port)}`);
+    }
+    const token = options.token ?? mintToken();
+    return {
+        port,
+        token,
+        cloudflaredArgs: ['tunnel', '--url', `http://localhost:${port}`],
+        devServerEnv: {
+            // Compile the edit gate in and pin the accepted token to this run.
+            VITE_UIX_EDIT: '1',
+            VITE_UIX_EDIT_TOKEN: token,
+            // Tells vite configs to emit HMR client settings that work through an
+            // HTTPS tunnel (wss on port 443) instead of the local port.
+            UIX_DEV_TUNNEL: '1',
+        },
+    };
+}
+/** Interpret a `node --version` string against the workspace requirement. */
+export function checkNodeVersion(versionString) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(versionString.trim());
+    if (!match) {
+        return {
+            name: 'node',
+            ok: false,
+            detail: `Unrecognised version "${versionString.trim()}"`,
+            hint: 'Install Node 20.19+, 22.12+ or 24+.',
+        };
+    }
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const ok = (major === 20 && minor >= 19) ||
+        (major === 22 && minor >= 12) ||
+        major >= 24;
+    return {
+        name: 'node',
+        ok,
+        detail: `Node ${match[0].replace(/^v?/, 'v')}`,
+        ...(ok ? {} : { hint: 'This workspace needs Node 20.19+, 22.12+ or 24+.' }),
+    };
+}
+/** Build the doctor result for an external binary probe. */
+export function checkBinary(name, found, version, installHint) {
+    if (!found) {
+        return { name, ok: false, detail: 'not found on PATH', hint: installHint };
+    }
+    return { name, ok: true, detail: version?.trim().split('\n')[0] ?? 'found' };
+}
+/** Render doctor checks as terminal lines. */
+export function formatDoctorReport(checks) {
+    return checks
+        .map((check) => {
+        const status = check.ok ? ' ok ' : 'FAIL';
+        const hint = check.hint ? `\n       ↳ ${check.hint}` : '';
+        return `[${status}] ${check.name}: ${check.detail}${hint}`;
+    })
+        .join('\n');
+}
+//# sourceMappingURL=lib.js.map

package/dist/cli/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../../src/cli/lib.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure logic behind the `uix-dev` CLI - everything here is unit-testable in\n * node with no processes spawned. The orchestration (spawning vite and\n * cloudflared, wiring stdio) lives in `main.ts` and stays intentionally thin.\n */\nimport { randomBytes } from 'node:crypto';\n\n/** Matches the URL cloudflared assigns to a quick tunnel. */\nconst TUNNEL_URL_PATTERN = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/;\n\n/**\n * Extract the assigned quick-tunnel URL from a chunk of cloudflared output.\n * cloudflared prints it (to stderr) inside a box banner once the tunnel is up.\n */\nexport function extractTunnelUrl(outputChunk: string): string | undefined {\n  const match = TUNNEL_URL_PATTERN.exec(outputChunk);\n  return match ? match[0] : undefined;\n}\n\n/** Mint a URL-safe random session token. */\nexport function mintToken(bytes = 16): string {\n  return randomBytes(bytes).toString('base64url');\n}\n\n/** Append the edit-session token to a base URL. */\nexport function buildEditUrl(\n  baseUrl: string,\n  token: string,\n  param = 'uix-edit',\n): string {\n  const url = new URL(baseUrl);\n  url.searchParams.set(param, token);\n  return url.toString();\n}\n\nexport interface TunnelPlan {\n  /** Local dev-server port the tunnel forwards to. */\n  port: number;\n  /** Per-run edit-session token, exported as VITE_UIX_EDIT_TOKEN. */\n  token: string;\n  /** argv for the cloudflared process. */\n  cloudflaredArgs: string[];\n  /** Environment additions for the dev-server process. */\n  devServerEnv: Record<string, string>;\n}\n\n/** Compute everything a `uix-dev tunnel` run needs up front. */\nexport function planTunnel(options: { port?: number; token?: string } = {}): TunnelPlan {\n  const port = options.port ?? 8081;\n  if (!Number.isInteger(port) || port < 1 || port > 65535) {\n    throw new Error(`Invalid port: ${String(options.port)}`);\n  }\n  const token = options.token ?? mintToken();\n  return {\n    port,\n    token,\n    cloudflaredArgs: ['tunnel', '--url', `http://localhost:${port}`],\n    devServerEnv: {\n      // Compile the edit gate in and pin the accepted token to this run.\n      VITE_UIX_EDIT: '1',\n      VITE_UIX_EDIT_TOKEN: token,\n      // Tells vite configs to emit HMR client settings that work through an\n      // HTTPS tunnel (wss on port 443) instead of the local port.\n      UIX_DEV_TUNNEL: '1',\n    },\n  };\n}\n\nexport interface DoctorCheck {\n  name: string;\n  ok: boolean;\n  detail: string;\n  hint?: string;\n}\n\n/** Interpret a `node --version` string against the workspace requirement. */\nexport function checkNodeVersion(versionString: string): DoctorCheck {\n  const match = /^v?(\\d+)\\.(\\d+)\\.(\\d+)/.exec(versionString.trim());\n  if (!match) {\n    return {\n      name: 'node',\n      ok: false,\n      detail: `Unrecognised version \"${versionString.trim()}\"`,\n      hint: 'Install Node 20.19+, 22.12+ or 24+.',\n    };\n  }\n  const major = Number(match[1]);\n  const minor = Number(match[2]);\n  const ok =\n    (major === 20 && minor >= 19) ||\n    (major === 22 && minor >= 12) ||\n    major >= 24;\n  return {\n    name: 'node',\n    ok,\n    detail: `Node ${match[0].replace(/^v?/, 'v')}`,\n    ...(ok ? {} : { hint: 'This workspace needs Node 20.19+, 22.12+ or 24+.' }),\n  };\n}\n\n/** Build the doctor result for an external binary probe. */\nexport function checkBinary(\n  name: string,\n  found: boolean,\n  version: string | undefined,\n  installHint: string,\n): DoctorCheck {\n  if (!found) {\n    return { name, ok: false, detail: 'not found on PATH', hint: installHint };\n  }\n  return { name, ok: true, detail: version?.trim().split('\\n')[0] ?? 'found' };\n}\n\n/** Render doctor checks as terminal lines. */\nexport function formatDoctorReport(checks: readonly DoctorCheck[]): string {\n  return checks\n    .map((check) => {\n      const status = check.ok ? ' ok ' : 'FAIL';\n      const hint = check.hint ? `\\n       ↳ ${check.hint}` : '';\n      return `[${status}] ${check.name}: ${check.detail}${hint}`;\n    })\n    .join('\\n');\n}\n"]}

package/dist/cli/main.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli/main.js

@@ -0,0 +1,170 @@
+/**
+ * `uix-dev` - get an IWSDK UI Extensions client onto a headset in one command.
+ *
+ * Commands:
+ *   uix-dev tunnel [--port N] [--cwd DIR] [--no-dev-server]
+ *       Mint an edit-session token, start the Vite dev server (npm run dev)
+ *       with the token exported, open a Cloudflare quick tunnel to it and
+ *       print both the plain and the edit-mode URL as text + QR codes.
+ *   uix-dev doctor
+ *       Check node / cloudflared / adb availability with install hints.
+ *   uix-dev qr <url>
+ *       Print a QR code for any URL (e.g. a staging deploy).
+ *
+ * Orchestration only - all decision logic lives in lib.ts where it is unit
+ * tested.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import process from 'node:process';
+import qrcode from 'qrcode-terminal';
+import { buildEditUrl, checkBinary, checkNodeVersion, extractTunnelUrl, formatDoctorReport, planTunnel, } from './lib.js';
+function printQr(url) {
+    return new Promise((resolve) => {
+        qrcode.generate(url, { small: true }, (code) => {
+            console.log(code);
+            resolve();
+        });
+    });
+}
+function probeBinary(command, args) {
+    const result = spawnSync(command, args, { encoding: 'utf8' });
+    if (result.error || result.status !== 0) {
+        return undefined;
+    }
+    return (result.stdout || result.stderr || '').trim() || 'found';
+}
+async function runDoctor() {
+    const checks = [
+        checkNodeVersion(process.version),
+        checkBinary('cloudflared', probeBinary('cloudflared', ['--version']) !== undefined, probeBinary('cloudflared', ['--version']), 'Install: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ (brew install cloudflared / winget install Cloudflare.cloudflared)'),
+        checkBinary('adb', probeBinary('adb', ['--version']) !== undefined, probeBinary('adb', ['--version']), 'Optional (USB loop): install Android platform-tools for `adb reverse`.'),
+    ];
+    console.log(formatDoctorReport(checks));
+    return checks.every((check) => check.ok || check.name === 'adb') ? 0 : 1;
+}
+function parseTunnelFlags(argv) {
+    const flags = { port: 8081, cwd: process.cwd(), devServer: true };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--port') {
+            flags.port = Number(argv[i + 1]);
+            i += 1;
+        }
+        else if (arg === '--cwd') {
+            flags.cwd = argv[i + 1] ?? flags.cwd;
+            i += 1;
+        }
+        else if (arg === '--no-dev-server') {
+            flags.devServer = false;
+        }
+    }
+    return flags;
+}
+async function runTunnel(argv) {
+    const flags = parseTunnelFlags(argv);
+    const plan = planTunnel({ port: flags.port });
+    const children = [];
+    const shutdown = () => {
+        for (const child of children) {
+            child.kill('SIGTERM');
+        }
+    };
+    process.on('SIGINT', () => {
+        shutdown();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        shutdown();
+        process.exit(0);
+    });
+    if (flags.devServer) {
+        console.log(`[uix-dev] starting dev server (npm run dev) in ${flags.cwd} ...`);
+        const dev = spawn('npm', ['run', 'dev'], {
+            cwd: flags.cwd,
+            env: { ...process.env, ...plan.devServerEnv },
+            stdio: ['ignore', 'inherit', 'inherit'],
+        });
+        children.push(dev);
+        dev.on('exit', (code) => {
+            console.error(`[uix-dev] dev server exited (${String(code)}); stopping tunnel.`);
+            shutdown();
+            process.exit(code ?? 1);
+        });
+    }
+    else {
+        console.log(`[uix-dev] --no-dev-server: expecting a server on port ${String(plan.port)}. ` +
+            `Export VITE_UIX_EDIT_TOKEN=${plan.token} yourself for the gate to match.`);
+    }
+    console.log('[uix-dev] opening Cloudflare quick tunnel (no account needed) ...');
+    const tunnel = spawn('cloudflared', plan.cloudflaredArgs, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    children.push(tunnel);
+    let announced = false;
+    const onChunk = async (chunk) => {
+        const text = chunk.toString('utf8');
+        process.stderr.write(text);
+        if (announced) {
+            return;
+        }
+        const url = extractTunnelUrl(text);
+        if (!url) {
+            return;
+        }
+        announced = true;
+        const editUrl = buildEditUrl(url, plan.token);
+        console.log('\n──────────────────────────────────────────────────────');
+        console.log('  Quick tunnel is up. HTTPS + WSS, HMR flows through.');
+        console.log(`\n  Runtime  : ${url}`);
+        await printQr(url);
+        console.log(`\n  EDIT MODE: ${editUrl}`);
+        await printQr(editUrl);
+        console.log('  Scan the second code on the headset to open an edit session.');
+        console.log('  URL and token are minted per run - Ctrl+C invalidates both.');
+        console.log('──────────────────────────────────────────────────────\n');
+    };
+    tunnel.stderr?.on('data', onChunk);
+    tunnel.stdout?.on('data', onChunk);
+    tunnel.on('error', () => {
+        console.error('[uix-dev] could not start cloudflared - is it installed? Run `uix-dev doctor`.');
+        shutdown();
+        process.exit(1);
+    });
+    tunnel.on('exit', (code) => {
+        console.error(`[uix-dev] tunnel exited (${String(code)}).`);
+        shutdown();
+        process.exit(code ?? 1);
+    });
+    return new Promise(() => {
+        // Runs until Ctrl+C or a child exits - handlers above end the process.
+    });
+}
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    switch (command) {
+        case 'tunnel':
+            return runTunnel(rest);
+        case 'doctor':
+            return runDoctor();
+        case 'qr': {
+            const url = rest[0];
+            if (!url) {
+                console.error('Usage: uix-dev qr <url>');
+                return 1;
+            }
+            await printQr(url);
+            return 0;
+        }
+        default:
+            console.log([
+                'uix-dev - IWSDK UI Extensions dev tooling',
+                '',
+                'Usage:',
+                '  uix-dev tunnel [--port N] [--cwd DIR] [--no-dev-server]',
+                '  uix-dev doctor',
+                '  uix-dev qr <url>',
+            ].join('\n'));
+            return command === undefined || command === 'help' ? 0 : 1;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/cli/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `uix-dev` - get an IWSDK UI Extensions client onto a headset in one command.\n *\n * Commands:\n *   uix-dev tunnel [--port N] [--cwd DIR] [--no-dev-server]\n *       Mint an edit-session token, start the Vite dev server (npm run dev)\n *       with the token exported, open a Cloudflare quick tunnel to it and\n *       print both the plain and the edit-mode URL as text + QR codes.\n *   uix-dev doctor\n *       Check node / cloudflared / adb availability with install hints.\n *   uix-dev qr <url>\n *       Print a QR code for any URL (e.g. a staging deploy).\n *\n * Orchestration only - all decision logic lives in lib.ts where it is unit\n * tested.\n */\nimport { spawn, spawnSync, type ChildProcess } from 'node:child_process';\nimport process from 'node:process';\nimport qrcode from 'qrcode-terminal';\nimport {\n  buildEditUrl,\n  checkBinary,\n  checkNodeVersion,\n  extractTunnelUrl,\n  formatDoctorReport,\n  planTunnel,\n} from './lib.js';\n\nfunction printQr(url: string): Promise<void> {\n  return new Promise((resolve) => {\n    qrcode.generate(url, { small: true }, (code: string) => {\n      console.log(code);\n      resolve();\n    });\n  });\n}\n\nfunction probeBinary(command: string, args: string[]): string | undefined {\n  const result = spawnSync(command, args, { encoding: 'utf8' });\n  if (result.error || result.status !== 0) {\n    return undefined;\n  }\n  return (result.stdout || result.stderr || '').trim() || 'found';\n}\n\nasync function runDoctor(): Promise<number> {\n  const checks = [\n    checkNodeVersion(process.version),\n    checkBinary(\n      'cloudflared',\n      probeBinary('cloudflared', ['--version']) !== undefined,\n      probeBinary('cloudflared', ['--version']),\n      'Install: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ (brew install cloudflared / winget install Cloudflare.cloudflared)',\n    ),\n    checkBinary(\n      'adb',\n      probeBinary('adb', ['--version']) !== undefined,\n      probeBinary('adb', ['--version']),\n      'Optional (USB loop): install Android platform-tools for `adb reverse`.',\n    ),\n  ];\n  console.log(formatDoctorReport(checks));\n  return checks.every((check) => check.ok || check.name === 'adb') ? 0 : 1;\n}\n\ninterface TunnelFlags {\n  port: number;\n  cwd: string;\n  devServer: boolean;\n}\n\nfunction parseTunnelFlags(argv: string[]): TunnelFlags {\n  const flags: TunnelFlags = { port: 8081, cwd: process.cwd(), devServer: true };\n  for (let i = 0; i < argv.length; i += 1) {\n    const arg = argv[i];\n    if (arg === '--port') {\n      flags.port = Number(argv[i + 1]);\n      i += 1;\n    } else if (arg === '--cwd') {\n      flags.cwd = argv[i + 1] ?? flags.cwd;\n      i += 1;\n    } else if (arg === '--no-dev-server') {\n      flags.devServer = false;\n    }\n  }\n  return flags;\n}\n\nasync function runTunnel(argv: string[]): Promise<number> {\n  const flags = parseTunnelFlags(argv);\n  const plan = planTunnel({ port: flags.port });\n  const children: ChildProcess[] = [];\n\n  const shutdown = () => {\n    for (const child of children) {\n      child.kill('SIGTERM');\n    }\n  };\n  process.on('SIGINT', () => {\n    shutdown();\n    process.exit(0);\n  });\n  process.on('SIGTERM', () => {\n    shutdown();\n    process.exit(0);\n  });\n\n  if (flags.devServer) {\n    console.log(`[uix-dev] starting dev server (npm run dev) in ${flags.cwd} ...`);\n    const dev = spawn('npm', ['run', 'dev'], {\n      cwd: flags.cwd,\n      env: { ...process.env, ...plan.devServerEnv },\n      stdio: ['ignore', 'inherit', 'inherit'],\n    });\n    children.push(dev);\n    dev.on('exit', (code) => {\n      console.error(`[uix-dev] dev server exited (${String(code)}); stopping tunnel.`);\n      shutdown();\n      process.exit(code ?? 1);\n    });\n  } else {\n    console.log(\n      `[uix-dev] --no-dev-server: expecting a server on port ${String(plan.port)}. ` +\n        `Export VITE_UIX_EDIT_TOKEN=${plan.token} yourself for the gate to match.`,\n    );\n  }\n\n  console.log('[uix-dev] opening Cloudflare quick tunnel (no account needed) ...');\n  const tunnel = spawn('cloudflared', plan.cloudflaredArgs, {\n    stdio: ['ignore', 'pipe', 'pipe'],\n  });\n  children.push(tunnel);\n\n  let announced = false;\n  const onChunk = async (chunk: Buffer) => {\n    const text = chunk.toString('utf8');\n    process.stderr.write(text);\n    if (announced) {\n      return;\n    }\n    const url = extractTunnelUrl(text);\n    if (!url) {\n      return;\n    }\n    announced = true;\n    const editUrl = buildEditUrl(url, plan.token);\n    console.log('\\n──────────────────────────────────────────────────────');\n    console.log('  Quick tunnel is up. HTTPS + WSS, HMR flows through.');\n    console.log(`\\n  Runtime  : ${url}`);\n    await printQr(url);\n    console.log(`\\n  EDIT MODE: ${editUrl}`);\n    await printQr(editUrl);\n    console.log('  Scan the second code on the headset to open an edit session.');\n    console.log('  URL and token are minted per run - Ctrl+C invalidates both.');\n    console.log('──────────────────────────────────────────────────────\\n');\n  };\n  tunnel.stderr?.on('data', onChunk);\n  tunnel.stdout?.on('data', onChunk);\n  tunnel.on('error', () => {\n    console.error(\n      '[uix-dev] could not start cloudflared - is it installed? Run `uix-dev doctor`.',\n    );\n    shutdown();\n    process.exit(1);\n  });\n  tunnel.on('exit', (code) => {\n    console.error(`[uix-dev] tunnel exited (${String(code)}).`);\n    shutdown();\n    process.exit(code ?? 1);\n  });\n\n  return new Promise<number>(() => {\n    // Runs until Ctrl+C or a child exits - handlers above end the process.\n  });\n}\n\nexport async function main(argv: string[]): Promise<number> {\n  const [command, ...rest] = argv;\n  switch (command) {\n    case 'tunnel':\n      return runTunnel(rest);\n    case 'doctor':\n      return runDoctor();\n    case 'qr': {\n      const url = rest[0];\n      if (!url) {\n        console.error('Usage: uix-dev qr <url>');\n        return 1;\n      }\n      await printQr(url);\n      return 0;\n    }\n    default:\n      console.log(\n        [\n          'uix-dev - IWSDK UI Extensions dev tooling',\n          '',\n          'Usage:',\n          '  uix-dev tunnel [--port N] [--cwd DIR] [--no-dev-server]',\n          '  uix-dev doctor',\n          '  uix-dev qr <url>',\n        ].join('\\n'),\n      );\n      return command === undefined || command === 'help' ? 0 : 1;\n  }\n}\n"]}

package/dist/gate.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Edit-session launch gate.
+ *
+ * The gate is how a client opts into dev/edit mode WITHOUT the tooling ever
+ * being reachable by players:
+ *
+ * 1. Production builds compile the whole gate call out behind a build flag
+ *    (`if (import.meta.env.VITE_UIX_EDIT) installEditGate(...)`) - the
+ *    bundler removes the branch, so the code does not exist in player builds.
+ * 2. Where the gate IS compiled in (dev / staging), it only opens when the
+ *    page URL carries an explicit session token (`?uix-edit=<token>`) that
+ *    matches one the developer minted (`uix-dev tunnel` prints the URL).
+ * 3. The dev overlay itself is loaded through the `load` callback - always a
+ *    `dynamic import()` - so it lives in a separate chunk that is never even
+ *    downloaded for normal visitors.
+ *
+ * Everything here is DOM-optional and injectable so it is unit-testable in
+ * node: pass `href`/`storage` explicitly, or let it default to `window`.
+ */
+/** Default URL query parameter carrying the edit-session token. */
+export declare const DEFAULT_EDIT_PARAM = "uix-edit";
+/** sessionStorage key used to keep the session alive across reloads. */
+export declare const EDIT_SESSION_STORAGE_KEY = "uix-devtools:edit-token";
+/** An open edit session. */
+export interface EditSession {
+    /** The token the page presented. */
+    token: string;
+    /** How the token arrived: fresh from the URL, or remembered from storage. */
+    source: 'url' | 'storage';
+}
+/** Minimal storage surface (sessionStorage-compatible), injectable for tests. */
+export interface TokenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface EditGateOptions {
+    /**
+     * Loader called exactly once when the gate opens. Do the dynamic import of
+     * your dev overlay here so it stays in its own chunk:
+     * `load: (session) => import('./dev-overlay.js').then(m => m.install(session))`
+     */
+    load: (session: EditSession) => void | Promise<unknown>;
+    /**
+     * Tokens that are allowed to open the gate. Typically
+     * `[import.meta.env.VITE_UIX_EDIT_TOKEN]` - minted per run by `uix-dev`.
+     * When omitted or empty, ANY non-empty token opens the gate; only do that
+     * in local dev builds that never leave your machine.
+     */
+    tokens?: readonly string[];
+    /** URL query parameter name. Default: {@link DEFAULT_EDIT_PARAM}. */
+    param?: string;
+    /** Page URL to inspect. Default: `window.location.href`. */
+    href?: string;
+    /**
+     * Remember an accepted token in sessionStorage so reloads (e.g. re-entering
+     * VR) keep the session without the query param. Default: true.
+     */
+    remember?: boolean;
+    /** Storage override for tests. Default: `window.sessionStorage`. */
+    storage?: TokenStorage;
+}
+export interface EditGateResult {
+    /** True when an accepted token opened the gate and `load` was invoked. */
+    active: boolean;
+    session?: EditSession;
+    /** Present when a token arrived but was rejected. */
+    rejected?: string;
+}
+/** Extract the raw edit token from a URL, if any. Pure. */
+export declare function readEditToken(href: string, param?: string): string | undefined;
+/** Token acceptance rule. Pure. */
+export declare function isTokenAccepted(token: string, allowed: readonly string[] | undefined): boolean;
+/**
+ * Resolve the edit session for a page: URL token first, remembered token as
+ * fallback. Does NOT invoke any loader - pure resolution, used by
+ * {@link installEditGate} and directly testable.
+ */
+export declare function resolveEditSession(options: {
+    tokens?: readonly string[];
+    param?: string;
+    href?: string;
+    remember?: boolean;
+    storage?: TokenStorage;
+}): EditGateResult;
+/** Forget a remembered session (e.g. an "exit edit mode" button). */
+export declare function clearEditSession(storage?: TokenStorage): void;
+/**
+ * Install the gate: resolve the session and, when it opens, invoke `load`
+ * exactly once. Never throws into the host app - a broken overlay must not
+ * take the runtime down.
+ */
+export declare function installEditGate(options: EditGateOptions): EditGateResult;

package/dist/gate.js

@@ -0,0 +1,118 @@
+/**
+ * Edit-session launch gate.
+ *
+ * The gate is how a client opts into dev/edit mode WITHOUT the tooling ever
+ * being reachable by players:
+ *
+ * 1. Production builds compile the whole gate call out behind a build flag
+ *    (`if (import.meta.env.VITE_UIX_EDIT) installEditGate(...)`) - the
+ *    bundler removes the branch, so the code does not exist in player builds.
+ * 2. Where the gate IS compiled in (dev / staging), it only opens when the
+ *    page URL carries an explicit session token (`?uix-edit=<token>`) that
+ *    matches one the developer minted (`uix-dev tunnel` prints the URL).
+ * 3. The dev overlay itself is loaded through the `load` callback - always a
+ *    `dynamic import()` - so it lives in a separate chunk that is never even
+ *    downloaded for normal visitors.
+ *
+ * Everything here is DOM-optional and injectable so it is unit-testable in
+ * node: pass `href`/`storage` explicitly, or let it default to `window`.
+ */
+/** Default URL query parameter carrying the edit-session token. */
+export const DEFAULT_EDIT_PARAM = 'uix-edit';
+/** sessionStorage key used to keep the session alive across reloads. */
+export const EDIT_SESSION_STORAGE_KEY = 'uix-devtools:edit-token';
+/** Extract the raw edit token from a URL, if any. Pure. */
+export function readEditToken(href, param = DEFAULT_EDIT_PARAM) {
+    let url;
+    try {
+        url = new URL(href);
+    }
+    catch {
+        return undefined;
+    }
+    const token = url.searchParams.get(param);
+    return token && token.length > 0 ? token : undefined;
+}
+/** Token acceptance rule. Pure. */
+export function isTokenAccepted(token, allowed) {
+    if (token.length === 0) {
+        return false;
+    }
+    if (!allowed || allowed.length === 0) {
+        return true; // open gate - local dev only, see EditGateOptions.tokens
+    }
+    return allowed.some((candidate) => candidate.length > 0 && candidate === token);
+}
+/* v8 ignore start -- environment shims, exercised only in a real browser */
+function defaultHref() {
+    return typeof window !== 'undefined' ? window.location.href : undefined;
+}
+function defaultStorage() {
+    try {
+        return typeof window !== 'undefined' ? window.sessionStorage : undefined;
+    }
+    catch {
+        return undefined; // storage can throw in privacy modes - gate still works
+    }
+}
+/* v8 ignore stop */
+/**
+ * Resolve the edit session for a page: URL token first, remembered token as
+ * fallback. Does NOT invoke any loader - pure resolution, used by
+ * {@link installEditGate} and directly testable.
+ */
+export function resolveEditSession(options) {
+    const param = options.param ?? DEFAULT_EDIT_PARAM;
+    const remember = options.remember ?? true;
+    const storage = options.storage ?? defaultStorage();
+    const href = options.href ?? defaultHref();
+    const urlToken = href !== undefined ? readEditToken(href, param) : undefined;
+    if (urlToken !== undefined) {
+        if (!isTokenAccepted(urlToken, options.tokens)) {
+            return { active: false, rejected: urlToken };
+        }
+        if (remember && storage) {
+            storage.setItem(EDIT_SESSION_STORAGE_KEY, urlToken);
+        }
+        return { active: true, session: { token: urlToken, source: 'url' } };
+    }
+    if (remember && storage) {
+        const remembered = storage.getItem(EDIT_SESSION_STORAGE_KEY);
+        if (remembered !== null && remembered.length > 0) {
+            if (!isTokenAccepted(remembered, options.tokens)) {
+                storage.removeItem(EDIT_SESSION_STORAGE_KEY);
+                return { active: false, rejected: remembered };
+            }
+            return { active: true, session: { token: remembered, source: 'storage' } };
+        }
+    }
+    return { active: false };
+}
+/** Forget a remembered session (e.g. an "exit edit mode" button). */
+export function clearEditSession(storage) {
+    const target = storage ?? defaultStorage();
+    target?.removeItem(EDIT_SESSION_STORAGE_KEY);
+}
+/**
+ * Install the gate: resolve the session and, when it opens, invoke `load`
+ * exactly once. Never throws into the host app - a broken overlay must not
+ * take the runtime down.
+ */
+export function installEditGate(options) {
+    const result = resolveEditSession(options);
+    if (result.active && result.session) {
+        try {
+            const outcome = options.load(result.session);
+            if (outcome && typeof outcome.catch === 'function') {
+                outcome.catch((error) => {
+                    console.error('[uix-devtools] edit overlay failed to load:', error);
+                });
+            }
+        }
+        catch (error) {
+            console.error('[uix-devtools] edit overlay failed to load:', error);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Edit-session launch gate.\n *\n * The gate is how a client opts into dev/edit mode WITHOUT the tooling ever\n * being reachable by players:\n *\n * 1. Production builds compile the whole gate call out behind a build flag\n *    (`if (import.meta.env.VITE_UIX_EDIT) installEditGate(...)`) - the\n *    bundler removes the branch, so the code does not exist in player builds.\n * 2. Where the gate IS compiled in (dev / staging), it only opens when the\n *    page URL carries an explicit session token (`?uix-edit=<token>`) that\n *    matches one the developer minted (`uix-dev tunnel` prints the URL).\n * 3. The dev overlay itself is loaded through the `load` callback - always a\n *    `dynamic import()` - so it lives in a separate chunk that is never even\n *    downloaded for normal visitors.\n *\n * Everything here is DOM-optional and injectable so it is unit-testable in\n * node: pass `href`/`storage` explicitly, or let it default to `window`.\n */\n\n/** Default URL query parameter carrying the edit-session token. */\nexport const DEFAULT_EDIT_PARAM = 'uix-edit';\n\n/** sessionStorage key used to keep the session alive across reloads. */\nexport const EDIT_SESSION_STORAGE_KEY = 'uix-devtools:edit-token';\n\n/** An open edit session. */\nexport interface EditSession {\n  /** The token the page presented. */\n  token: string;\n  /** How the token arrived: fresh from the URL, or remembered from storage. */\n  source: 'url' | 'storage';\n}\n\n/** Minimal storage surface (sessionStorage-compatible), injectable for tests. */\nexport interface TokenStorage {\n  getItem(key: string): string | null;\n  setItem(key: string, value: string): void;\n  removeItem(key: string): void;\n}\n\nexport interface EditGateOptions {\n  /**\n   * Loader called exactly once when the gate opens. Do the dynamic import of\n   * your dev overlay here so it stays in its own chunk:\n   * `load: (session) => import('./dev-overlay.js').then(m => m.install(session))`\n   */\n  load: (session: EditSession) => void | Promise<unknown>;\n  /**\n   * Tokens that are allowed to open the gate. Typically\n   * `[import.meta.env.VITE_UIX_EDIT_TOKEN]` - minted per run by `uix-dev`.\n   * When omitted or empty, ANY non-empty token opens the gate; only do that\n   * in local dev builds that never leave your machine.\n   */\n  tokens?: readonly string[];\n  /** URL query parameter name. Default: {@link DEFAULT_EDIT_PARAM}. */\n  param?: string;\n  /** Page URL to inspect. Default: `window.location.href`. */\n  href?: string;\n  /**\n   * Remember an accepted token in sessionStorage so reloads (e.g. re-entering\n   * VR) keep the session without the query param. Default: true.\n   */\n  remember?: boolean;\n  /** Storage override for tests. Default: `window.sessionStorage`. */\n  storage?: TokenStorage;\n}\n\nexport interface EditGateResult {\n  /** True when an accepted token opened the gate and `load` was invoked. */\n  active: boolean;\n  session?: EditSession;\n  /** Present when a token arrived but was rejected. */\n  rejected?: string;\n}\n\n/** Extract the raw edit token from a URL, if any. Pure. */\nexport function readEditToken(\n  href: string,\n  param: string = DEFAULT_EDIT_PARAM,\n): string | undefined {\n  let url: URL;\n  try {\n    url = new URL(href);\n  } catch {\n    return undefined;\n  }\n  const token = url.searchParams.get(param);\n  return token && token.length > 0 ? token : undefined;\n}\n\n/** Token acceptance rule. Pure. */\nexport function isTokenAccepted(\n  token: string,\n  allowed: readonly string[] | undefined,\n): boolean {\n  if (token.length === 0) {\n    return false;\n  }\n  if (!allowed || allowed.length === 0) {\n    return true; // open gate - local dev only, see EditGateOptions.tokens\n  }\n  return allowed.some((candidate) => candidate.length > 0 && candidate === token);\n}\n\n/* v8 ignore start -- environment shims, exercised only in a real browser */\nfunction defaultHref(): string | undefined {\n  return typeof window !== 'undefined' ? window.location.href : undefined;\n}\n\nfunction defaultStorage(): TokenStorage | undefined {\n  try {\n    return typeof window !== 'undefined' ? window.sessionStorage : undefined;\n  } catch {\n    return undefined; // storage can throw in privacy modes - gate still works\n  }\n}\n/* v8 ignore stop */\n\n/**\n * Resolve the edit session for a page: URL token first, remembered token as\n * fallback. Does NOT invoke any loader - pure resolution, used by\n * {@link installEditGate} and directly testable.\n */\nexport function resolveEditSession(options: {\n  tokens?: readonly string[];\n  param?: string;\n  href?: string;\n  remember?: boolean;\n  storage?: TokenStorage;\n}): EditGateResult {\n  const param = options.param ?? DEFAULT_EDIT_PARAM;\n  const remember = options.remember ?? true;\n  const storage = options.storage ?? defaultStorage();\n  const href = options.href ?? defaultHref();\n\n  const urlToken = href !== undefined ? readEditToken(href, param) : undefined;\n  if (urlToken !== undefined) {\n    if (!isTokenAccepted(urlToken, options.tokens)) {\n      return { active: false, rejected: urlToken };\n    }\n    if (remember && storage) {\n      storage.setItem(EDIT_SESSION_STORAGE_KEY, urlToken);\n    }\n    return { active: true, session: { token: urlToken, source: 'url' } };\n  }\n\n  if (remember && storage) {\n    const remembered = storage.getItem(EDIT_SESSION_STORAGE_KEY);\n    if (remembered !== null && remembered.length > 0) {\n      if (!isTokenAccepted(remembered, options.tokens)) {\n        storage.removeItem(EDIT_SESSION_STORAGE_KEY);\n        return { active: false, rejected: remembered };\n      }\n      return { active: true, session: { token: remembered, source: 'storage' } };\n    }\n  }\n\n  return { active: false };\n}\n\n/** Forget a remembered session (e.g. an \"exit edit mode\" button). */\nexport function clearEditSession(storage?: TokenStorage): void {\n  const target = storage ?? defaultStorage();\n  target?.removeItem(EDIT_SESSION_STORAGE_KEY);\n}\n\n/**\n * Install the gate: resolve the session and, when it opens, invoke `load`\n * exactly once. Never throws into the host app - a broken overlay must not\n * take the runtime down.\n */\nexport function installEditGate(options: EditGateOptions): EditGateResult {\n  const result = resolveEditSession(options);\n  if (result.active && result.session) {\n    try {\n      const outcome = options.load(result.session);\n      if (outcome && typeof (outcome as Promise<unknown>).catch === 'function') {\n        (outcome as Promise<unknown>).catch((error) => {\n          console.error('[uix-devtools] edit overlay failed to load:', error);\n        });\n      }\n    } catch (error) {\n      console.error('[uix-devtools] edit overlay failed to load:', error);\n    }\n  }\n  return result;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @realitycollective/uix-devtools - client-side entry.
+ *
+ * Only the pieces safe to reference from app code are exported here: the
+ * edit-session gate (designed to be compiled out of production builds) and
+ * the runtime UIKitML compiler that powers live panel editing.
+ *
+ * The `uix-dev` CLI ships from the same package (`bin/uix-dev.mjs`,
+ * `@realitycollective/uix-devtools/cli`) but is node-only - never import it
+ * from client code.
+ */
+export { DEFAULT_EDIT_PARAM, EDIT_SESSION_STORAGE_KEY, clearEditSession, installEditGate, isTokenAccepted, readEditToken, resolveEditSession, type EditGateOptions, type EditGateResult, type EditSession, type TokenStorage, } from './gate.js';
+export { compilePanelSource, type CompiledPanel } from './runtime-compile.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @realitycollective/uix-devtools - client-side entry.
+ *
+ * Only the pieces safe to reference from app code are exported here: the
+ * edit-session gate (designed to be compiled out of production builds) and
+ * the runtime UIKitML compiler that powers live panel editing.
+ *
+ * The `uix-dev` CLI ships from the same package (`bin/uix-dev.mjs`,
+ * `@realitycollective/uix-devtools/cli`) but is node-only - never import it
+ * from client code.
+ */
+export { DEFAULT_EDIT_PARAM, EDIT_SESSION_STORAGE_KEY, clearEditSession, installEditGate, isTokenAccepted, readEditToken, resolveEditSession, } from './gate.js';
+export { compilePanelSource } from './runtime-compile.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,aAAa,EACb,kBAAkB,GAKnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAsB,MAAM,sBAAsB,CAAC","sourcesContent":["/**\n * @realitycollective/uix-devtools - client-side entry.\n *\n * Only the pieces safe to reference from app code are exported here: the\n * edit-session gate (designed to be compiled out of production builds) and\n * the runtime UIKitML compiler that powers live panel editing.\n *\n * The `uix-dev` CLI ships from the same package (`bin/uix-dev.mjs`,\n * `@realitycollective/uix-devtools/cli`) but is node-only - never import it\n * from client code.\n */\nexport {\n  DEFAULT_EDIT_PARAM,\n  EDIT_SESSION_STORAGE_KEY,\n  clearEditSession,\n  installEditGate,\n  isTokenAccepted,\n  readEditToken,\n  resolveEditSession,\n  type EditGateOptions,\n  type EditGateResult,\n  type EditSession,\n  type TokenStorage,\n} from './gate.js';\nexport { compilePanelSource, type CompiledPanel } from './runtime-compile.js';\n"]}

package/dist/runtime-compile.d.ts

@@ -0,0 +1,24 @@
+export interface CompiledPanel {
+    /** Compiled panel JSON, same shape the Vite plugin writes to public/ui. */
+    json: string;
+    /** Parse diagnostics. Empty when the source compiled cleanly. */
+    errors: string[];
+    /**
+     * `blob:` URL serving {@link json}; hand this to `PanelUI.config`.
+     * Empty string in non-browser environments (node tests).
+     */
+    configUrl: string;
+    /** Release the blob URL once the panel has loaded (or on discard). */
+    revoke(): void;
+}
+export interface CompileOptions {
+    /**
+     * Resolver for `<link ref="...">` stylesheet references in the source -
+     * return the CSS text for a path, throw for unknown paths (reported as a
+     * diagnostic). Omit to leave linked stylesheets unresolved (inline
+     * `<style>` always works).
+     */
+    resolveFile?: (filePath: string) => string;
+}
+/** Compile UIKitML source text. Collects errors instead of throwing. */
+export declare function compilePanelSource(source: string, options?: CompileOptions): CompiledPanel;

package/dist/runtime-compile.js

@@ -0,0 +1,42 @@
+/**
+ * Runtime UIKitML compilation.
+ *
+ * The `@iwsdk/vite-plugin-uikitml` build step is literally
+ * `JSON.stringify(parse(source))` - so the same `parse` from
+ * `@pmndrs/uikitml` can compile panel markup live in the browser. IWSDK's
+ * `PanelUI` loads its `config` with a plain `fetch()`, which accepts `blob:`
+ * URLs, so a runtime-compiled panel is:
+ *
+ *   const compiled = compilePanelSource(source);
+ *   createUIWindow(world, { config: compiled.configUrl, ... });
+ *
+ * This is the mechanism behind live UX editing (desktop workbench and
+ * in-headset editor alike): edit markup → recompile → respawn the window.
+ */
+import { parse } from '@pmndrs/uikitml';
+/** Compile UIKitML source text. Collects errors instead of throwing. */
+export function compilePanelSource(source, options = {}) {
+    const errors = [];
+    const result = parse(source, {
+        onError: (message) => {
+            errors.push(message);
+        },
+        ...(options.resolveFile ? { resolveFile: options.resolveFile } : {}),
+    });
+    if (result.element === undefined) {
+        errors.push('UIKitML source produced no root element.');
+    }
+    const json = JSON.stringify(result, null, 2);
+    const blobSupported = typeof URL !== 'undefined' &&
+        typeof URL.createObjectURL === 'function' &&
+        typeof Blob !== 'undefined';
+    /* v8 ignore start -- only reachable in environments without Blob support */
+    if (!blobSupported) {
+        return { json, errors, configUrl: '', revoke: () => { } };
+    }
+    /* v8 ignore stop */
+    const blob = new Blob([json], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    return { json, errors, configUrl: url, revoke: () => URL.revokeObjectURL(url) };
+}
+//# sourceMappingURL=runtime-compile.js.map

package/dist/runtime-compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-compile.js","sourceRoot":"","sources":["../src/runtime-compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AA0BxC,wEAAwE;AACxE,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,UAA0B,EAAE;IAE5B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE;QAC3B,OAAO,EAAE,CAAC,OAAe,EAAE,EAAE;YAC3B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;QACD,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACrE,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE7C,MAAM,aAAa,GACjB,OAAO,GAAG,KAAK,WAAW;QAC1B,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;QACzC,OAAO,IAAI,KAAK,WAAW,CAAC;IAC9B,4EAA4E;IAC5E,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IAC3D,CAAC;IACD,oBAAoB;IAEpB,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACtC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;AAClF,CAAC","sourcesContent":["/**\n * Runtime UIKitML compilation.\n *\n * The `@iwsdk/vite-plugin-uikitml` build step is literally\n * `JSON.stringify(parse(source))` - so the same `parse` from\n * `@pmndrs/uikitml` can compile panel markup live in the browser. IWSDK's\n * `PanelUI` loads its `config` with a plain `fetch()`, which accepts `blob:`\n * URLs, so a runtime-compiled panel is:\n *\n *   const compiled = compilePanelSource(source);\n *   createUIWindow(world, { config: compiled.configUrl, ... });\n *\n * This is the mechanism behind live UX editing (desktop workbench and\n * in-headset editor alike): edit markup → recompile → respawn the window.\n */\nimport { parse } from '@pmndrs/uikitml';\n\nexport interface CompiledPanel {\n  /** Compiled panel JSON, same shape the Vite plugin writes to public/ui. */\n  json: string;\n  /** Parse diagnostics. Empty when the source compiled cleanly. */\n  errors: string[];\n  /**\n   * `blob:` URL serving {@link json}; hand this to `PanelUI.config`.\n   * Empty string in non-browser environments (node tests).\n   */\n  configUrl: string;\n  /** Release the blob URL once the panel has loaded (or on discard). */\n  revoke(): void;\n}\n\nexport interface CompileOptions {\n  /**\n   * Resolver for `<link ref=\"...\">` stylesheet references in the source -\n   * return the CSS text for a path, throw for unknown paths (reported as a\n   * diagnostic). Omit to leave linked stylesheets unresolved (inline\n   * `<style>` always works).\n   */\n  resolveFile?: (filePath: string) => string;\n}\n\n/** Compile UIKitML source text. Collects errors instead of throwing. */\nexport function compilePanelSource(\n  source: string,\n  options: CompileOptions = {},\n): CompiledPanel {\n  const errors: string[] = [];\n  const result = parse(source, {\n    onError: (message: string) => {\n      errors.push(message);\n    },\n    ...(options.resolveFile ? { resolveFile: options.resolveFile } : {}),\n  });\n\n  if (result.element === undefined) {\n    errors.push('UIKitML source produced no root element.');\n  }\n\n  const json = JSON.stringify(result, null, 2);\n\n  const blobSupported =\n    typeof URL !== 'undefined' &&\n    typeof URL.createObjectURL === 'function' &&\n    typeof Blob !== 'undefined';\n  /* v8 ignore start -- only reachable in environments without Blob support */\n  if (!blobSupported) {\n    return { json, errors, configUrl: '', revoke: () => {} };\n  }\n  /* v8 ignore stop */\n\n  const blob = new Blob([json], { type: 'application/json' });\n  const url = URL.createObjectURL(blob);\n  return { json, errors, configUrl: url, revoke: () => URL.revokeObjectURL(url) };\n}\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@realitycollective/uix-devtools",
+  "version": "0.1.0-preview.0",
+  "description": "Developer tooling for @realitycollective/iwsdk-uiextensions - edit-session launch gate, runtime UIKitML compilation, and the uix-dev CLI (Cloudflare quick tunnel + QR onboarding for headset testing). Never ship this in a player-facing bundle.",
+  "keywords": [
+    "realitycollective",
+    "iwsdk",
+    "webxr",
+    "devtools",
+    "uikitml",
+    "cloudflared",
+    "quest",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Reality Collective",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/lib.d.ts",
+      "default": "./dist/cli/lib.js"
+    }
+  },
+  "bin": {
+    "uix-dev": "./bin/uix-dev.mjs"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "bin",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@pmndrs/uikitml": "^0.1.12",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realitycollective/WebXR-UIExtensions.git",
+    "directory": "packages/uix-devtools"
+  },
+  "homepage": "https://github.com/realitycollective/WebXR-UIExtensions#readme",
+  "bugs": {
+    "url": "https://github.com/realitycollective/WebXR-UIExtensions/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0"
+  }
+}