parley-live 0.4.2 → 0.5.1

package/lens-builder/verify.mjs

@@ -0,0 +1,186 @@
+// Verifier: runs the plan section 6.3 checklist against the live Lens Studio preview.
+// status: 'pass' | 'fail' | 'hardware' (cannot be judged in preview; flagged for on-device testing).
+// Nothing is marked pass unless it was actually observed in this run.
+import fs from 'node:fs';
+import path from 'node:path';
+import { LENS_VERSION } from './training/compile.mjs';
+import { readSubmissionState, SNAP_LENS_NAME_MAX } from './lib/submission.mjs';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const TAG = '[ParleyTG]';
+
+function printsOf(logs) {
+  return (logs?.prints || []).map((p) => (typeof p === 'string' ? p : p.text || p.message || JSON.stringify(p)));
+}
+function errorsOf(logs) {
+  return (logs?.errors || []).map((p) => (typeof p === 'string' ? p : p.text || p.message || JSON.stringify(p)));
+}
+
+// Log lines look like "I 11:36:52.645 [Preview 1] ...". Returns the time of day in ms, or null.
+function timeOfDayMs(line) {
+  const m = line.match(/^\s*[A-Z]\s+(\d{2}):(\d{2}):(\d{2})\.(\d{3})/);
+  return m ? ((+m[1] * 60 + +m[2]) * 60 + +m[3]) * 1000 + +m[4] : null;
+}
+
+// RunAndCollectLogsTool's refresh mode only returns lines after its reset marker, and a Lens's first OnStart prints
+// can land just before that marker (observed 5.24.0). So: restart the preview with refresh, then read the tail and keep
+// the lines written since the restart was triggered. Lines from earlier sessions are excluded by the timestamp.
+async function printsSince(bridge, sinceDate) {
+  const since = ((sinceDate.getHours() * 60 + sinceDate.getMinutes()) * 60 + sinceDate.getSeconds()) * 1000 + sinceDate.getMilliseconds() - 1500;
+  const tail = await bridge.tailLogs();
+  return printsOf(tail).filter((p) => { const t = timeOfDayMs(p); return t !== null && t >= since; });
+}
+
+export async function verify({ bridge, plan, form, runDir, iteration, projectDir, submission }) {
+  const checks = [];
+  const add = (item, status, detail, extra = {}) => checks.push({ item, status, detail, ...extra });
+  const n = form.steps.length;
+
+  // 1. Compiles with zero errors
+  const comp = await bridge.recompile();
+  add('Project compiles with zero errors', comp.ok && comp.errors.length === 0 ? 'pass' : 'fail', comp.ok ? 'RecompileTypeScriptTool: succeeded' : comp.errors.join(' | ').slice(0, 600) || JSON.stringify(comp.raw).slice(0, 300));
+  if (!comp.ok) return { pass: false, iteration, checks };
+
+  // 2. Start-up logs
+  let restartedAt = new Date();
+  let logs = await bridge.runAndCollectLogs(5000);
+  let prints = [...new Set([...printsOf(logs), ...(await printsSince(bridge, restartedAt))])];
+  // A freshly opened project can answer the first refresh before the new script has been picked up; retry briefly.
+  for (let attempt = 0; attempt < 3 && prints.filter((p) => p.includes(TAG)).length === 0; attempt++) {
+    await sleep(4000);
+    restartedAt = new Date();
+    logs = await bridge.runAndCollectLogs(6000);
+    prints = [...new Set([...printsOf(logs), ...(await printsSince(bridge, restartedAt))])];
+  }
+  fs.writeFileSync(path.join(runDir, 'preview', `logs-start-${iteration}.json`), JSON.stringify({ restartedAt, prints, refresh: logs }, null, 1));
+  const ready = prints.some((p) => p.includes(`${TAG} ready steps=${n}`));
+  const step1 = prints.some((p) => p.includes(`${TAG} step=1/${n}`));
+  add('Lens starts and shows step 1', ready && step1 ? 'pass' : 'fail', ready && step1 ? `log: "${TAG} ready steps=${n}", "${TAG} step=1/${n}"` : `prints: ${prints.slice(-5).join(' / ') || '(none)'}`, { transient: prints.length === 0 });
+
+  const version = form.version || LENS_VERSION;
+  const versionLogged = prints.some((p) => p.includes(`Lens Opened: v${version}`));
+  add('Version is logged on startup and shown on the panel (Snap Spectacles publishing checklist)', versionLogged ? 'pass' : 'fail', versionLogged ? `log: "Lens Opened: v${version}"; panel shows v${version}` : 'startup version line not found in the log');
+
+  // 3. Every step reachable: press the real buttons in the preview with simulated pinches.
+  let reach = { ok: false, detail: 'not attempted' };
+  if (ready && step1) reach = await walkFlow(bridge, n, runDir, iteration);
+  add('Every step in user_flow is reachable (Done pressed through to completion, Back returns)', reach.ok ? 'pass' : 'fail', reach.detail);
+
+  // 4. Runtime errors across the whole flow
+  const tail = await bridge.tailLogs().catch(() => null);
+  const VOICE_ENV = /Login to My Lenses is required|AsrTranscriber|VoiceML|speech::transcribe|GrpcTranscribe|fetch auth token/i;
+  const rawErrors = [...new Set([...errorsOf(logs), ...errorsOf(tail)])];
+  const voiceEnv = rawErrors.filter((e) => VOICE_ENV.test(e));
+  // Attribute errors. An error belongs to the Lens when it comes from the running Lens (framed by [Preview N]),
+  // names project files/packages, is a JS exception, or reports a missing asset. Editor housekeeping errors
+  // (for example Lens Studio failing to delete its own temp folder) are reported but do not fail the Lens.
+  const serious = rawErrors.filter((e) => !VOICE_ENV.test(e)).filter((e) => /^\s*[EF]\b|TypeError|ReferenceError|SyntaxError|Exception|Cannot find asset|\[ParleyTG\] ERROR/.test(e));
+  const LENS_ATTRIBUTED = /\[Preview|Assets\/|Packages\/|\.ts\b|\.js\b|\.lspkg|TypeError|ReferenceError|SyntaxError|Exception|Cannot find asset|\[ParleyTG\] ERROR|script/i;
+  const allErrors = serious.filter((e) => LENS_ATTRIBUTED.test(e));
+  const editorNoise = serious.filter((e) => !LENS_ATTRIBUTED.test(e));
+  add('No runtime errors from the Lens during the full user flow', allErrors.length === 0 ? 'pass' : 'fail',
+    allErrors.length ? allErrors.slice(0, 3).join(' | ').slice(0, 600)
+      : 'no script exceptions, no Lens-attributed E/F lines' + (editorNoise.length ? `. Not attributed to the Lens (${editorNoise.length}): ${editorNoise[0].slice(0, 200)}` : ''));
+
+  // 5. Assets resolve
+  const missing = [...errorsOf(logs), ...errorsOf(tail)].filter((e) => /Cannot find asset|missing reference|Failed to load/i.test(e));
+  add('All assets resolve (no missing references)', missing.length === 0 ? 'pass' : 'fail', missing.length ? missing[0].slice(0, 300) : 'no missing-asset diagnostics in the log');
+
+  // 6. Acceptance tests from the plan map onto the observations above
+  const accOk = comp.ok && ready && step1 && versionLogged && reach.ok && allErrors.length === 0;
+  add(`All ${plan.acceptance_tests.length} acceptance tests in the plan pass`, accOk ? 'pass' : 'fail', accOk ? 'compile, start-up log, full Done walk, Back, no runtime errors: all observed' : 'one or more observations above failed');
+
+  // 7. Text within bounds: enforced by form limits + Wrap/Shrink layout rects; screenshot kept as evidence.
+  const shot = path.join(runDir, 'preview', `final-${iteration}.png`);
+  const shotOk = await bridge.screenshot(shot).catch(() => false);
+  add('Text is within display bounds (53x77 cm area at 110 cm; wrap + shrink layout, length-limited form)', shotOk ? 'pass' : 'fail', shotOk ? `layout rects are 52 cm wide; screenshot: ${path.relative(runDir, shot)}` : 'screenshot could not be captured');
+
+  // 8. Size budget (proxy: bytes of project Assets + Packages)
+  const bytes = dirSize(path.join(projectDir, 'Assets')) + dirSize(path.join(projectDir, 'Packages'));
+  add('Lens size within the 25 MB limit Snap sets for a published Spectacles Lens', bytes < 25 * 1024 * 1024 ? 'pass' : 'fail', `${(bytes / 1048576).toFixed(1)} MB of project assets + packages on disk (upper bound; the published Lens is compressed)`);
+
+  // 9. What Snap requires of a submittable Lens, read back from the project rather than assumed.
+  const snap = await readSubmissionState(bridge).catch((e) => ({ error: e.message }));
+  if (snap.error) {
+    add('Ready for Snap submission (name, icon, signing key)', 'fail', snap.error.slice(0, 300));
+  } else {
+    const nameOk = snap.lensNameValid && snap.lensName.length <= SNAP_LENS_NAME_MAX;
+    add(`Lens name Snap accepts (at most ${SNAP_LENS_NAME_MAX} characters, not the template default)`, nameOk ? 'pass' : 'fail',
+      nameOk ? `"${snap.lensName}" (${snap.lensName.length} characters)` : `"${snap.lensName}" would be rejected at publish`);
+    add('Lens icon set on the project', snap.iconPresent ? 'pass' : 'fail', snap.iconPresent ? '320x320 PNG: ' + String(snap.iconPath).split(/[\\/]/).pop() : 'no icon; Snap requires one');
+    add('Production signing key attached', snap.productionKeySet ? 'pass' : 'fail', snap.productionKeySet ? 'ed25519 key set on the project' : 'no signing key; the SnapOS Package cannot be exported without one');
+  }
+
+  // 10. Items preview cannot judge
+  if (form.voiceShortcuts !== false) add('Voice shortcuts ("done", "next", "back") recognized reliably', 'hardware', (voiceEnv.length ? 'preview could not start speech recognition (Lens Studio is not logged in to My Lenses); the Lens fell back to buttons as designed. ' : '') + 'ASR needs a microphone and real speech; Snap advises buttons as the dependable path, which the checks above exercised');
+  add('Panel comfort and legibility in the real workspace', 'hardware', 'distance, glare and hand reach depend on the wearer and the room');
+  add('60 FPS, power and thermal budget', 'hardware', 'Snap requires checking the Lens Performance Overlay and Spectacles Monitor on a real device; the preview cannot measure this');
+  add('Signed in to Lens Studio, so the Lens can be exported and submitted', snap.signedIn ? 'pass' : 'hardware',
+    snap.signedIn === true ? 'signed in: Snap\'s preflight, the SnapOS Package export and the upload can run'
+      : 'not signed in. This is Snap\'s gate, not a missing piece of the build: it blocks their preflight, the package export and the upload. Everything on this side of it (name, icon, signing key) is done.');
+  add('Preview image or video for the store listing', 'hardware', 'captured from the Lens running on real glasses; the description, release notes and test list are already written into this report');
+
+  const pass = checks.every((c) => c.status !== 'fail');
+  return { pass, iteration, checks };
+}
+
+// UIKit buttons keep their collider on a child object, which PreviewInteractTool's id-targeted pinch reports as an
+// obstruction (observed 5.24.0). Snap's specs-preview-interaction skill documents the coordinate-targeted fallback:
+// read the live world position, then pinch there.
+async function pressButton(bridge, name) {
+  const q = await bridge.call('QueryRuntimeSceneTool', { query: `{ sceneObjects(filter:{nameContains:"${name}", enabledOnly:true}) { matches { summary transform { worldPosition } } } }` });
+  const match = (q?.data?.sceneObjects?.matches || []).find((m) => m.summary.name === name);
+  if (!match) throw new Error(`button "${name}" is not enabled in the running Lens`);
+  return bridge.call('PreviewInteractTool', { action: 'Pinch', worldPosition: match.transform.worldPosition, handType: 'right' });
+}
+
+async function lastPrints(bridge) {
+  const all = printsOf(await bridge.tailLogs());
+  // Only this Lens session counts: drop everything before the most recent start-up line.
+  let from = -1;
+  all.forEach((p, i) => { if (p.includes(`${TAG} ready steps=`)) from = i; });
+  return from >= 0 ? all.slice(from) : all;
+}
+
+async function walkFlow(bridge, n, runDir, iteration) {
+  const trace = [];
+  try {
+    for (let k = 2; k <= n; k++) {
+      await pressButton(bridge, 'TG_BtnNext');
+      await sleep(1200);
+      const seen = (await lastPrints(bridge)).some((p) => p.includes(`${TAG} step=${k}/${n}`));
+      trace.push(`Done -> step ${k}/${n}: ${seen ? 'seen' : 'NOT seen'}`);
+      if (!seen) return { ok: false, detail: trace.join('; ') };
+    }
+    if (n >= 2) {
+      await pressButton(bridge, 'TG_BtnBack');
+      await sleep(1200);
+      const prints = await lastPrints(bridge);
+      const idx = prints.map((p, i) => (p.includes(`${TAG} step=`) ? i : -1)).filter((i) => i >= 0).pop();
+      const backOk = idx !== undefined && prints[idx].includes(`${TAG} step=${n - 1}/${n}`);
+      trace.push(`Back -> step ${n - 1}/${n}: ${backOk ? 'seen' : 'NOT seen'}`);
+      if (!backOk) return { ok: false, detail: trace.join('; ') };
+      await pressButton(bridge, 'TG_BtnNext');
+      await sleep(1200);
+    }
+    await pressButton(bridge, 'TG_BtnNext');
+    await sleep(1200);
+    const done = (await lastPrints(bridge)).some((p) => p.includes(`${TAG} complete`));
+    trace.push(`Finish -> complete: ${done ? 'seen' : 'NOT seen'}`);
+    fs.writeFileSync(path.join(runDir, 'preview', `flow-${iteration}.txt`), trace.join('\n'));
+    return { ok: done, detail: trace.join('; ') };
+  } catch (e) {
+    trace.push(`interaction failed: ${e.message.slice(0, 400)}`);
+    return { ok: false, detail: trace.join('; ') };
+  }
+}
+
+function dirSize(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  let total = 0;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    total += e.isDirectory() ? dirSize(p) : fs.statSync(p).size;
+  }
+  return total;
+}

package/lens-builder/webxr/generate.mjs

@@ -0,0 +1,238 @@
+// Phase 5: WebXR fallback. Same training form -> one self-contained HTML page that runs in the Specs Browser Lens
+// (WebXR Core + AR module + hand input: https://developers.snap.com/spectacles/about-spectacles-features/webxr)
+// and degrades to an on-page 3D preview and a plain 2D step-through on any other browser.
+// Usage: node lens-builder/webxr/generate.mjs <form.json> [outDir]
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateForm, lensIdFor } from '../training/compile.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const THREE_VERSION = '0.170.0';
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+
+export function generateWebXR(form) {
+  const errors = validateForm(form);
+  if (errors.length) throw new Error('Form is not buildable: ' + errors.join('; '));
+  const data = {
+    title: form.procedureName,
+    steps: form.steps.map((s) => ({ instruction: s.instruction, warning: s.warning || '' })),
+    completion: form.completionMessage || 'Procedure complete. Well done.',
+  };
+  // </script> inside JSON would end the script block early
+  const json = JSON.stringify(data).replace(/</g, '\\u003c');
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(form.procedureName)}</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: #09090b; color: #f4f4f5; font: 16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+  main { max-width: 760px; margin: 0 auto; padding: 24px 16px 48px; }
+  h1 { font-size: 1.5rem; margin: 0 0 4px; }
+  .muted { color: #a1a1aa; font-size: .9rem; }
+  .card { border: 1px solid #27272a; background: #18181b; border-radius: 16px; padding: 20px; margin-top: 16px; }
+  #progress { color: #38bdf8; font-size: .85rem; font-weight: 600; letter-spacing: .02em; }
+  #instruction { font-size: 1.25rem; margin: 8px 0; min-height: 3.2em; }
+  #warning { color: #fbbf24; font-weight: 600; min-height: 1.5em; }
+  .row { display: flex; gap: 12px; margin-top: 16px; flex-wrap: wrap; }
+  button { font: inherit; font-weight: 600; border-radius: 12px; border: 1px solid #3f3f46; background: #27272a; color: #f4f4f5; padding: 12px 22px; cursor: pointer; }
+  button.primary { background: #0ea5e9; border-color: #0ea5e9; color: #09090b; }
+  button:disabled { opacity: .4; cursor: default; }
+  canvas#preview { width: 100%; aspect-ratio: 16 / 10; display: block; border-radius: 12px; background: #000; touch-action: none; }
+  #xrNote { margin-top: 8px; }
+</style>
+</head>
+<body>
+<main>
+  <h1>${esc(form.procedureName)}</h1>
+  <div class="muted">Hands-free guide, ${form.steps.length} step${form.steps.length === 1 ? '' : 's'}. Built with Parley.</div>
+
+  <div class="card">
+    <button id="enterXR" class="primary" disabled>Start on glasses</button>
+    <div id="xrNote" class="muted">Checking this device...</div>
+  </div>
+
+  <div class="card">
+    <div class="muted" style="margin-bottom:8px">3D preview. Click Done or Back on the panel, the same way a pinch works on glasses.</div>
+    <canvas id="preview"></canvas>
+  </div>
+
+  <div class="card" aria-live="polite">
+    <div id="progress"></div>
+    <div id="instruction"></div>
+    <div id="warning"></div>
+    <div class="row">
+      <button id="back">Back</button>
+      <button id="next" class="primary">Done</button>
+    </div>
+  </div>
+</main>
+
+<script type="importmap">{ "imports": { "three": "https://cdn.jsdelivr.net/npm/three@${THREE_VERSION}/build/three.module.js" } }</script>
+<script type="module">
+import * as THREE from 'three';
+
+const GUIDE = ${json};
+
+// ---------------------------------------------------------------- state (shared by 2D, preview and XR)
+const state = { index: 0, finished: false, lastPressAt: 0 };
+const listeners = [];
+function changed() { listeners.forEach((fn) => fn()); }
+function press(which) {
+  const now = performance.now();
+  if (now - state.lastPressAt < 600) return; // one press per pinch
+  state.lastPressAt = now;
+  if (which === 'next') {
+    if (state.finished) return;
+    if (state.index < GUIDE.steps.length - 1) state.index++; else state.finished = true;
+  } else if (!state.finished && state.index > 0) state.index--;
+  changed();
+}
+function view() {
+  if (state.finished) return { progress: 'Complete', instruction: GUIDE.completion, warning: '', next: 'Finished', canBack: false };
+  const s = GUIDE.steps[state.index];
+  return { progress: 'Step ' + (state.index + 1) + ' of ' + GUIDE.steps.length, instruction: s.instruction, warning: s.warning ? 'Caution: ' + s.warning : '', next: state.index === GUIDE.steps.length - 1 ? 'Finish' : 'Done', canBack: state.index > 0 };
+}
+window.__guide = { state, press, view }; // test hook
+
+// ---------------------------------------------------------------- 2D fallback
+const $ = (id) => document.getElementById(id);
+listeners.push(() => {
+  const v = view();
+  $('progress').textContent = v.progress;
+  $('instruction').textContent = v.instruction;
+  $('warning').textContent = v.warning;
+  $('next').textContent = v.next;
+  $('next').disabled = state.finished;
+  $('back').disabled = !v.canBack;
+});
+$('next').addEventListener('click', () => press('next'));
+$('back').addEventListener('click', () => press('back'));
+
+// ---------------------------------------------------------------- panel (canvas texture) used by preview and XR
+const PANEL = { w: 0.62, h: 0.44, z: -1.1, y: -0.04 }; // metres: 110 cm away, slightly below eye level (Snap spatial design guidance)
+const BTN = { w: 0.16, h: 0.06, y: -0.15, x: 0.13 };   // 6 cm tall targets
+
+function wrap(ctx, text, maxWidth) {
+  const words = text.split(/\\s+/); const lines = []; let line = '';
+  for (const w of words) { const t = line ? line + ' ' + w : w; if (ctx.measureText(t).width > maxWidth && line) { lines.push(line); line = w; } else line = t; }
+  if (line) lines.push(line);
+  return lines;
+}
+
+function makePanel() {
+  const canvas = document.createElement('canvas'); canvas.width = 1240; canvas.height = 880;
+  const ctx = canvas.getContext('2d');
+  const texture = new THREE.CanvasTexture(canvas); texture.colorSpace = THREE.SRGBColorSpace;
+  const group = new THREE.Group();
+  const panel = new THREE.Mesh(new THREE.PlaneGeometry(PANEL.w, PANEL.h), new THREE.MeshBasicMaterial({ map: texture, transparent: true }));
+  group.add(panel);
+  const mk = (name, x) => { const m = new THREE.Mesh(new THREE.PlaneGeometry(BTN.w, BTN.h), new THREE.MeshBasicMaterial({ transparent: true, opacity: 0, depthWrite: false })); m.position.set(x, BTN.y, 0.002); m.name = name; group.add(m); return m; };
+  const buttons = [mk('back', -BTN.x), mk('next', BTN.x)];
+  group.position.set(0, PANEL.y, PANEL.z);
+
+  function draw() {
+    const v = view(); const W = canvas.width, H = canvas.height, px = W / PANEL.w;
+    ctx.clearRect(0, 0, W, H);
+    ctx.fillStyle = 'rgba(24,24,27,0.92)'; ctx.beginPath(); ctx.roundRect(0, 0, W, H, 40); ctx.fill();
+    ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+    ctx.fillStyle = '#f4f4f5'; ctx.font = '700 54px system-ui, sans-serif'; ctx.fillText(GUIDE.title, W / 2, 90, W - 120);
+    ctx.fillStyle = '#38bdf8'; ctx.font = '600 38px system-ui, sans-serif'; ctx.fillText(v.progress, W / 2, 165);
+    ctx.fillStyle = '#f4f4f5'; ctx.font = '500 44px system-ui, sans-serif';
+    const lines = wrap(ctx, v.instruction, W - 160).slice(0, 5);
+    lines.forEach((l, i) => ctx.fillText(l, W / 2, 330 - (lines.length - 1) * 28 + i * 56));
+    if (v.warning) { ctx.fillStyle = '#fbbf24'; ctx.font = '700 38px system-ui, sans-serif'; wrap(ctx, v.warning, W - 160).slice(0, 2).forEach((l, i) => ctx.fillText(l, W / 2, 530 + i * 46)); }
+    const drawBtn = (cx, label, primary, enabled) => {
+      if (!enabled) return;
+      const bw = BTN.w * px, bh = BTN.h * px, x = W / 2 + cx * px - bw / 2, y = H / 2 - BTN.y * px - bh / 2;
+      ctx.fillStyle = primary ? '#0ea5e9' : '#3f3f46'; ctx.beginPath(); ctx.roundRect(x, y, bw, bh, 24); ctx.fill();
+      ctx.fillStyle = primary ? '#09090b' : '#f4f4f5'; ctx.font = '600 40px system-ui, sans-serif'; ctx.fillText(label, x + bw / 2, y + bh / 2 + 2);
+    };
+    drawBtn(-BTN.x, 'Back', false, v.canBack);
+    drawBtn(BTN.x, v.next, true, !state.finished);
+    buttons[0].visible = v.canBack; buttons[1].visible = !state.finished;
+    texture.needsUpdate = true;
+  }
+  return { group, buttons, draw };
+}
+
+const raycaster = new THREE.Raycaster();
+function hitButton(buttons) {
+  const hit = raycaster.intersectObjects(buttons.filter((b) => b.visible), false)[0];
+  return hit ? hit.object.name : null;
+}
+
+// ---------------------------------------------------------------- on-page 3D preview (mouse / touch)
+const previewCanvas = $('preview');
+const renderer = new THREE.WebGLRenderer({ canvas: previewCanvas, antialias: true, alpha: true });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(36, 16 / 10, 0.05, 20);
+const ui = makePanel();
+scene.add(ui.group);
+listeners.push(ui.draw);
+
+function resize() {
+  const w = previewCanvas.clientWidth, h = previewCanvas.clientHeight;
+  if (previewCanvas.width !== Math.floor(w * renderer.getPixelRatio())) { renderer.setSize(w, h, false); camera.aspect = w / h; camera.updateProjectionMatrix(); }
+}
+previewCanvas.addEventListener('pointerdown', (e) => {
+  if (renderer.xr.isPresenting) return;
+  const r = previewCanvas.getBoundingClientRect();
+  raycaster.setFromCamera(new THREE.Vector2(((e.clientX - r.left) / r.width) * 2 - 1, -((e.clientY - r.top) / r.height) * 2 + 1), camera);
+  const name = hitButton(ui.buttons);
+  if (name) press(name);
+});
+renderer.setAnimationLoop(() => { if (!renderer.xr.isPresenting) resize(); renderer.render(scene, camera); });
+
+// ---------------------------------------------------------------- WebXR (immersive-ar). A pinch arrives as a 'select' event.
+renderer.xr.enabled = true;
+const tmpMatrix = new THREE.Matrix4();
+for (let i = 0; i < 2; i++) {
+  const controller = renderer.xr.getController(i);
+  controller.addEventListener('select', () => {
+    tmpMatrix.identity().extractRotation(controller.matrixWorld);
+    raycaster.ray.origin.setFromMatrixPosition(controller.matrixWorld);
+    raycaster.ray.direction.set(0, 0, -1).applyMatrix4(tmpMatrix);
+    const name = hitButton(ui.buttons);
+    if (name) press(name);
+  });
+  scene.add(controller);
+}
+
+async function setupXR() {
+  const note = $('xrNote'), btn = $('enterXR');
+  if (!navigator.xr) { note.textContent = 'This browser has no WebXR. Use the preview or the buttons below, or open this page in the Browser Lens on Specs.'; return; }
+  const ok = await navigator.xr.isSessionSupported('immersive-ar').catch(() => false);
+  if (!ok) { note.textContent = 'This device cannot show AR. Use the preview or the buttons below, or open this page in the Browser Lens on Specs.'; return; }
+  note.textContent = 'Pinch Done to move on. Use the palm button to leave.';
+  btn.disabled = false;
+  btn.addEventListener('click', async () => {
+    try {
+      const session = await navigator.xr.requestSession('immersive-ar', { optionalFeatures: ['hand-tracking', 'local-floor'] });
+      await renderer.xr.setSession(session);
+      session.addEventListener('end', () => { note.textContent = 'Session ended. You can start again.'; });
+    } catch (err) { note.textContent = 'Could not start AR: ' + err.message; }
+  });
+}
+
+changed();
+setupXR();
+</script>
+</body>
+</html>
+`;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const form = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  const outDir = process.argv[3] || path.join(ROOT, 'webxr-out', lensIdFor(form));
+  fs.mkdirSync(outDir, { recursive: true });
+  const file = path.join(outDir, 'index.html');
+  fs.writeFileSync(file, generateWebXR(form));
+  console.log(file);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "parley-live",
-  "version": "0.4.2",
-  "description": "Generate images, video clips with named camera moves, narration, YouTube thumbnails, product ads, complete videos and Studio films, and deploy static sites, from the terminal with Parley. Built for coding agents: every command has a --json mode.",
+  "version": "0.5.1",
+  "description": "Generate images, video clips with named camera moves, narration, YouTube thumbnails, product ads, complete videos and Studio films, deploy static sites, and build Snap Specs Lenses through Lens Studio, from the terminal with Parley. Built for coding agents: every command has a --json mode.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -10,7 +10,9 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "lens-builder",
+    "kb/index"
   ],
   "engines": {
     "node": ">=20"
@@ -18,7 +20,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node test/cli.test.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm run stage:lens",
+    "stage:lens": "node scripts/stage-lens-builder.cjs"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -30,6 +33,9 @@
     "video",
     "image",
     "cli",
-    "agent-skills"
+    "agent-skills",
+    "snap-specs",
+    "lens-studio",
+    "ar"
   ]
 }