@helix3/helix-cli 0.1.7-helix3.43 → 0.1.7-helix3.45

package/dist/gesture/capture.js

@@ -0,0 +1,274 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_VIEWS = exports.VIEW_NAMES = void 0;
+exports.viewAzimuth = viewAzimuth;
+exports.viewLabel = viewLabel;
+exports.captureGesture = captureGesture;
+exports.arrangeGrid = arrangeGrid;
+exports.parseMoment = parseMoment;
+exports.clipSide = clipSide;
+exports.resolveViews = resolveViews;
+exports.sharesAxis = sharesAxis;
+// Renders a gesture clip as a contact sheet — front and side, several times across the clip — so an agent
+// with no browser can still LOOK at a pose before handing it to a human. Measurement (./inspect) says where
+// the bones are; this says how it reads, which is the one thing numbers cannot.
+//
+// Always the DEFAULT character: a clip replicates by name and plays on whatever body each player has, so a
+// pose is authored against the canonical body every custom character is conformed to. That is why the render
+// assets are vendored (see vendor/README.md) and this needs no asset download.
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const captureScreenshots_1 = require("../screenshot/captureScreenshots");
+const staticServe_1 = require("../screenshot/staticServe");
+const harnessPage_1 = require("./harnessPage");
+const worldRuntime_1 = require("./worldRuntime");
+const paths_1 = require("../paths");
+/** 0/25/50/75/100 % of the clip — enough to read a gesture's arc without a sheet per frame. */
+const DEFAULT_FRAMES = 5;
+exports.VIEW_NAMES = ['front', 'back', 'right', 'left', 'three-quarter'];
+exports.MAX_VIEWS = 2;
+/** Far enough off-axis to lift a limb clear of the torso silhouette, near enough to still read as a front view. */
+const THREE_QUARTER_DEG = 40;
+/**
+ * Camera azimuth around Y, 0 = front. left/right are the CHARACTER's own, matching the readback's
+ * character-left / character-right — a viewer-relative reading would invert them, which is the trap to avoid.
+ * `three-quarter` follows the clip's ACTIVE side: from the wrong side it occludes as badly as a lateral view.
+ */
+function viewAzimuth(view, side) {
+    switch (view) {
+        case 'front': return 0;
+        case 'back': return 180;
+        case 'right': return -90;
+        case 'left': return 90;
+        case 'three-quarter': return side === 'left' ? THREE_QUARTER_DEG : -THREE_QUARTER_DEG;
+    }
+}
+function viewLabel(view, side) {
+    if (view === 'three-quarter')
+        return `3/4 ${side}`;
+    return view === 'left' || view === 'right' ? `${view} side` : view;
+}
+// Portrait, because a standing figure is tall and narrow — a square cell spends ~40% of its pixels on background.
+const DEFAULT_CELL_H = 420;
+const CELL_ASPECT = 0.52;
+// A single moment gets the whole image budget instead of a fifth of it: with only two cells there is room to
+// see a hand's orientation, which is what a "fix this specific thing" question actually turns on.
+const MOMENT_CELL_H = 760;
+const MOMENT_ASPECT = 0.62;
+/** vendor/ ships beside dist/ in the published package and sits one level up from it in the repo. */
+function vendorDir() {
+    return (0, node_path_1.resolve)(__dirname, '..', '..', 'vendor');
+}
+async function captureGesture(opts) {
+    const onProgress = opts.onProgress ?? (() => undefined);
+    const frames = Math.max(2, opts.frames ?? DEFAULT_FRAMES);
+    const moment = opts.at !== undefined;
+    const cellH = opts.cellHeight ?? (moment ? MOMENT_CELL_H : DEFAULT_CELL_H);
+    const cellW = Math.round(cellH * (moment ? MOMENT_ASPECT : CELL_ASPECT));
+    const timeoutMs = opts.timeoutMs ?? 60000;
+    const systemDir = (0, node_path_1.join)(opts.worldDir, 'public', paths_1.MODULES_DIR, worldRuntime_1.SYSTEM_SLUG);
+    const threeDir = (0, worldRuntime_1.threeRoot)(opts.worldDir); // the same walk inspect uses — hoisted layouts, friendly npm-install error
+    const stage = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'helix-gesture-shot-'));
+    let browser;
+    let server;
+    try {
+        // Linked, not copied: three's addons tree is large, and the static server's traversal guard compares
+        // path STRINGS against the root, so a link resolving outside it still serves.
+        (0, node_fs_1.symlinkSync)(threeDir, (0, node_path_1.join)(stage, 'three'), 'junction');
+        (0, node_fs_1.symlinkSync)((0, node_path_1.dirname)(systemDir), (0, node_path_1.join)(stage, paths_1.MODULES_DIR), 'junction');
+        (0, node_fs_1.copyFileSync)((0, node_path_1.join)(vendorDir(), 'capture-body.glb'), (0, node_path_1.join)(stage, 'capture-body.glb'));
+        (0, node_fs_1.copyFileSync)((0, node_path_1.join)(vendorDir(), 'capture-face.glb'), (0, node_path_1.join)(stage, 'capture-face.glb'));
+        (0, node_fs_1.copyFileSync)(opts.clip, (0, node_path_1.join)(stage, 'clip.json'));
+        // The page needs concrete seconds, not fractions, so the clip is parsed here rather than in-page.
+        const source = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(stage, 'clip.json'), 'utf8'));
+        const duration = readDuration(source, opts.clip);
+        const side = clipSide(source);
+        const chosen = resolveViews(opts.views, source, moment);
+        const times = moment
+            ? [parseMoment(opts.at, duration)]
+            : Array.from({ length: frames }, (_, i) => Math.round((i / (frames - 1)) * duration * 1000) / 1000);
+        const config = { ...arrangeGrid(times, chosen, moment, side), cellW, cellH };
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(stage, 'index.html'), (0, harnessPage_1.harnessPage)(config));
+        const playwright = await Promise.resolve().then(() => __importStar(require('playwright')));
+        server = await (0, staticServe_1.startStaticServer)(stage);
+        const attempts = [];
+        for (const candidate of (0, captureScreenshots_1.selectBrowserCandidates)(opts.browser)) {
+            try {
+                browser = await playwright.chromium.launch(candidate.launchOptions);
+                onProgress(`using ${candidate.label}`);
+                break;
+            }
+            catch (err) {
+                attempts.push({ key: candidate.key, label: candidate.label, message: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        if (!browser)
+            throw new Error((0, captureScreenshots_1.composeLaunchFailure)(attempts));
+        const page = await browser.newPage({
+            viewport: { width: config.colLabels.length * cellW + 32, height: config.rowLabels.length * cellH + 32 },
+            deviceScaleFactor: 1,
+        });
+        const pageErrors = [];
+        page.on('pageerror', (err) => pageErrors.push(err.message));
+        page.on('console', (msg) => { if (msg.type() === 'error')
+            pageErrors.push(msg.text()); });
+        await page.goto(`http://127.0.0.1:${server.port}/`);
+        try {
+            await page.waitForFunction(`window.${harnessPage_1.READY_FLAG} !== undefined`, undefined, { timeout: timeoutMs });
+        }
+        catch {
+            throw new Error(`the capture page never finished after ${timeoutMs}ms.${pageErrors.length ? `\n  page errors:\n    ${pageErrors.join('\n    ')}` : ''}`);
+        }
+        const state = await page.evaluate(`window.${harnessPage_1.READY_FLAG}`);
+        if (!state.ready)
+            throw new Error(`the capture page failed to render:\n  ${state.error ?? 'unknown error'}`);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(opts.out), { recursive: true });
+        await page.locator('#sheet').screenshot({ path: opts.out });
+        return {
+            file: opts.out,
+            clip: state.clip ?? 'gesture',
+            duration: state.duration ?? duration,
+            times,
+            views: chosen,
+            moment,
+            sharedAxis: sharesAxis(chosen),
+            warnings: state.warnings ?? [],
+        };
+    }
+    finally {
+        if (browser)
+            await browser.close();
+        if (server)
+            await server.close();
+        (0, node_fs_1.rmSync)(stage, { recursive: true, force: true });
+    }
+}
+const timeLabel = (t) => `t=${t.toFixed(2)}s`;
+/**
+ * A sequence reads best with time across and views stacked; a single moment reads best with the views SIDE BY
+ * SIDE, so the two renders of the same instant sit next to each other for comparison.
+ */
+function arrangeGrid(times, views, moment, side) {
+    const cells = [];
+    const az = (v) => viewAzimuth(v, side);
+    if (moment) {
+        views.forEach((v, col) => times.forEach((t, row) => cells.push({ t, azimuth: az(v), col, row })));
+        return { cells, colLabels: views.map((v) => viewLabel(v, side)), rowLabels: times.map(timeLabel) };
+    }
+    views.forEach((v, row) => times.forEach((t, col) => cells.push({ t, azimuth: az(v), col, row })));
+    return { cells, colLabels: times.map(timeLabel), rowLabels: views.map((v) => viewLabel(v, side)) };
+}
+/** `--at` takes seconds or a percentage of duration, matching `inspect --t`. */
+function parseMoment(at, duration) {
+    const raw = typeof at === 'number' ? at : at.trim();
+    const seconds = typeof raw === 'number'
+        ? raw
+        : raw.endsWith('%') ? (parseFloat(raw) / 100) * duration : parseFloat(raw);
+    if (!Number.isFinite(seconds))
+        throw new Error(`--at: '${at}' is not a number of seconds or a percentage`);
+    if (seconds < 0 || seconds > duration)
+        throw new Error(`--at: ${seconds}s is outside the clip (0..${duration}s)`);
+    return Math.round(seconds * 1000) / 1000;
+}
+function readDuration(source, clipPath) {
+    const duration = typeof source.duration === 'number' ? source.duration : NaN;
+    if (!Number.isFinite(duration) || duration <= 0)
+        throw new Error(`${clipPath}: "duration" must be a positive number`);
+    return duration;
+}
+/**
+ * Which side of the body a clip actually works on, so a left-handed gesture is never rendered from the side
+ * its own torso hides. The clip already declares this, so it is derived rather than asked for.
+ *
+ * KEYED BONES ARE THE GROUND TRUTH — most masks say nothing about sidedness. Of the authorable set
+ * (upperBody, lowerBody, leftArm, rightArm, spine, armsHead) only two are one-sided; the rest are bilateral,
+ * so a left-handed clip masked `upperBody` is identified by its bones, not its mask. The mask is consulted
+ * only as a tiebreaker, and by PATTERN rather than an exact name, so a future one-sided mask works untouched.
+ */
+function clipSide(source) {
+    const bones = new Set();
+    for (const key of Array.isArray(source.keys) ? source.keys : []) {
+        const at = key.bones;
+        if (at !== null && typeof at === 'object')
+            for (const bone of Object.keys(at))
+                bones.add(bone);
+    }
+    let left = 0, right = 0;
+    for (const bone of bones) {
+        if (bone.endsWith('_l'))
+            left++;
+        else if (bone.endsWith('_r'))
+            right++;
+    }
+    if (left !== right)
+        return left > right ? 'left' : 'right';
+    const masks = `${typeof source.mask === 'string' ? source.mask : ''} ${typeof source.overrideMask === 'string' ? source.overrideMask : ''}`;
+    if (/left/i.test(masks))
+        return 'left';
+    if (/right/i.test(masks))
+        return 'right';
+    // Genuinely two-sided or unsided (a bow, a nod): either flank shows it, so take the one the standard
+    // action set is built around.
+    return 'right';
+}
+/**
+ * Defaults differ by MODE, because the modes answer different questions. A sequence is compared over time, so
+ * it wants the ORTHOGONAL pair — front plus a lateral — which is what makes "moves side-to-side, not
+ * front-to-back" readable; a 3/4 there would conflate the two axes it exists to separate. A single moment is
+ * being disambiguated, so it wants the 3/4, which lifts a limb clear of the torso instead of hiding it behind
+ * it. Every view stays legal in both modes: a mode-dependent enum would be a footgun to document, and neither
+ * pairing is actually invalid.
+ */
+function resolveViews(requested, source, moment = false) {
+    if (requested !== undefined && requested.length > 0) {
+        const unique = [...new Set(requested)];
+        if (unique.length > exports.MAX_VIEWS)
+            throw new Error(`--views takes at most ${exports.MAX_VIEWS} (got ${unique.length}) — more rows shrink every cell past useful`);
+        return unique;
+    }
+    return moment ? ['front', 'three-quarter'] : ['front', clipSide(source)];
+}
+/** front+back and left+right are each a single axis seen twice: both are frontal projections of the same plane. */
+function sharesAxis(views) {
+    if (views.length < 2)
+        return false;
+    // A 3/4 mixes both axes, so it never leaves a pairing depth-blind.
+    const axis = (v) => v === 'three-quarter' ? 'mixed' : v === 'front' || v === 'back' ? 'depth' : 'lateral';
+    const axes = views.map(axis);
+    return !axes.includes('mixed') && new Set(axes).size === 1;
+}
+//# sourceMappingURL=capture.js.map

package/dist/gesture/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/gesture/capture.ts"],"names":[],"mappings":"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"}

package/dist/gesture/harnessPage.d.ts

@@ -0,0 +1,17 @@
+export interface HarnessCell {
+    /** Sample time in seconds. */
+    t: number;
+    /** Camera azimuth in degrees around Y; 0 = front. */
+    azimuth: number;
+    col: number;
+    row: number;
+}
+export interface HarnessConfig {
+    cells: HarnessCell[];
+    colLabels: string[];
+    rowLabels: string[];
+    cellW: number;
+    cellH: number;
+}
+export declare const READY_FLAG = "__helixGestureCapture";
+export declare function harnessPage(config: HarnessConfig): string;

package/dist/gesture/harnessPage.js

@@ -0,0 +1,147 @@
+"use strict";
+// The capture harness page. Assembled as a string because `tsc` does not copy assets into dist, and the
+// page is written into a temp dir at run time anyway (alongside links to the world's three + system).
+//
+// The page renders a grid it is TOLD about — a flat cell list plus row/column labels — rather than deciding
+// the arrangement itself. That is what lets one code path serve both the contact sheet (times across, views
+// down) and the single-moment comparison (views across, one row, much larger cells).
+//
+// Why it poses TWO skeletons: the default character ships as body + face, each carrying its own skeleton
+// with a different skin joint count (77-node full tree vs a 16-node root->spine->neck->head chain), so they
+// cannot share one skin. Posing each by bone name is what keeps the head following spine and neck keys.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.READY_FLAG = void 0;
+exports.harnessPage = harnessPage;
+exports.READY_FLAG = '__helixGestureCapture';
+function harnessPage(config) {
+    return `<!doctype html>
+<meta charset="utf-8">
+<title>gesture capture</title>
+<style>
+  :root { color-scheme: light }
+  body { margin: 0; background: #f4f4f6; font: 12px/1.3 ui-sans-serif, system-ui, sans-serif; color: #222 }
+  #sheet { position: relative; display: inline-block }
+  #sheet canvas { display: block }
+  .lbl { position: absolute; font-variant-numeric: tabular-nums; color: #444; pointer-events: none; font-weight: 600 }
+  .col { top: 5px; transform: translateX(-50%) }
+  .row { left: 5px; transform: translateY(-50%) rotate(-90deg); transform-origin: left center }
+  #err { padding: 12px; color: #a00; font-family: ui-monospace, monospace; white-space: pre-wrap }
+</style>
+<div id="sheet"></div>
+<div id="err"></div>
+<script type="importmap">
+{ "imports": { "three": "/three/build/three.module.js", "three/": "/three/" } }
+</script>
+<script type="module">
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { compileGesture, GesturePlayer } from '/helix_modules/humanoid-character/index.js';
+
+const CONFIG = ${JSON.stringify(config)};
+const FLAG = ${JSON.stringify(exports.READY_FLAG)};
+const fail = (message) => { document.getElementById('err').textContent = message; window[FLAG] = { ready: false, error: message }; };
+
+try {
+  const clip = await (await fetch('/clip.json')).json();
+  const compiled = compileGesture(clip);
+
+  const loader = new GLTFLoader();
+  const parts = [];
+  for (const file of ['/capture-body.glb', '/capture-face.glb']) {
+    const gltf = await loader.loadAsync(file);
+    const root = gltf.scene;
+    root.traverse((o) => { if (o.isSkinnedMesh) { o.frustumCulled = false; o.castShadow = true; } });
+    // The bind pose must be restored before every pose, or deltas accumulate across grid cells.
+    const bind = new Map();
+    root.traverse((n) => { if (n.isBone === true) bind.set(n, n.quaternion.clone()); });
+    parts.push({ root, bind, player: new GesturePlayer(root) });
+  }
+
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0xf4f4f6);
+  for (const p of parts) scene.add(p.root);
+
+  // Three-point rig: a key light high and camera-left, a softer fill opposite, a rim from behind to keep
+  // the silhouette off the background. Ambient alone flattens exactly the depth cues a pose is judged by.
+  scene.add(new THREE.HemisphereLight(0xffffff, 0x555560, 0.55));
+  const key = new THREE.DirectionalLight(0xffffff, 2.0); key.position.set(-2.2, 3.2, 3.0); scene.add(key);
+  const fill = new THREE.DirectionalLight(0xffffff, 0.7); fill.position.set(2.6, 1.0, 1.8); scene.add(fill);
+  const rim = new THREE.DirectionalLight(0xffffff, 0.9); rim.position.set(0.4, 2.0, -3.2); scene.add(rim);
+
+  const poseAll = (t) => {
+    for (const p of parts) {
+      for (const [bone, q] of p.bind) bone.quaternion.copy(q);
+      p.player.pose(compiled.gesture, t);
+    }
+    for (const p of parts) p.root.updateMatrixWorld(true);
+  };
+
+  const cellW = CONFIG.cellW, cellH = CONFIG.cellH;
+
+  // Frame from the UNION of every pose in the grid, not the bind pose: one camera for the whole image keeps
+  // the cells comparable (a per-cell refit would make the body appear to zoom), while the union guarantees an
+  // overhead reach cannot be clipped out of frame.
+  const box = new THREE.Box3();
+  for (const t of [...new Set(CONFIG.cells.map((c) => c.t))]) { poseAll(t); box.expandByObject(scene); }
+  const centre = box.getCenter(new THREE.Vector3());
+  // Horizontal extent is per-VIEW: a camera at azimuth t sees |dx*cos t| + |dz*sin t| across, so an off-axis
+  // 3/4 is wider than the front view and would clip if only world X were budgeted. One camera is shared, so
+  // take the widest view in the grid.
+  const dx = box.max.x - box.min.x, dz = box.max.z - box.min.z;
+  const widest = Math.max(...CONFIG.cells.map((c) => {
+    const a = (c.azimuth * Math.PI) / 180;
+    return Math.abs(dx * Math.cos(a)) + Math.abs(dz * Math.sin(a));
+  }), 0.1);
+  const span = Math.max(box.max.y - box.min.y, widest / (cellW / cellH), 0.1);
+  const fov = 32;
+  const radius = (span * 0.60) / Math.tan((fov / 2) * Math.PI / 180);
+
+  const width = CONFIG.colLabels.length * cellW, totalHeight = CONFIG.rowLabels.length * cellH;
+  const renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true });
+  renderer.setPixelRatio(1);
+  renderer.setSize(width, totalHeight);
+  renderer.setScissorTest(true);
+  const sheet = document.getElementById('sheet');
+  sheet.appendChild(renderer.domElement);
+
+  const camera = new THREE.PerspectiveCamera(fov, cellW / cellH, 0.05, 100);
+
+  // Everything renders in ONE frame: with scissor per cell the drawing buffer ends up holding the whole
+  // image, so the screenshot needs no per-cell readback. Sorted by time so each pose is applied once per
+  // distinct time rather than once per cell.
+  for (const cell of [...CONFIG.cells].sort((a, b) => a.t - b.t)) {
+    poseAll(cell.t);
+    const angle = (cell.azimuth * Math.PI) / 180;
+    camera.position.set(centre.x + Math.sin(angle) * radius, centre.y, centre.z + Math.cos(angle) * radius);
+    camera.lookAt(centre);
+    camera.updateProjectionMatrix();
+    // WebGL's origin is bottom-left; row 0 must be the TOP of the image.
+    const y = totalHeight - (cell.row + 1) * cellH;
+    renderer.setViewport(cell.col * cellW, y, cellW, cellH);
+    renderer.setScissor(cell.col * cellW, y, cellW, cellH);
+    renderer.render(scene, camera);
+  }
+
+  CONFIG.colLabels.forEach((text, c) => {
+    const el = document.createElement('div');
+    el.className = 'lbl col';
+    el.style.left = (c * cellW + cellW / 2) + 'px';
+    el.textContent = text;
+    sheet.appendChild(el);
+  });
+  CONFIG.rowLabels.forEach((text, r) => {
+    const el = document.createElement('div');
+    el.className = 'lbl row';
+    el.style.top = (r * cellH + cellH / 2) + 'px';
+    el.textContent = text;
+    sheet.appendChild(el);
+  });
+
+  window[FLAG] = { ready: true, clip: compiled.gesture.name, duration: compiled.gesture.duration, warnings: compiled.warnings ?? [] };
+} catch (err) {
+  fail(err && err.stack ? err.stack : String(err));
+}
+</script>
+`;
+}
+//# sourceMappingURL=harnessPage.js.map

package/dist/gesture/harnessPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harnessPage.js","sourceRoot":"","sources":["../../src/gesture/harnessPage.ts"],"names":[],"mappings":";AAAA,wGAAwG;AACxG,sGAAsG;AACtG,EAAE;AACF,4GAA4G;AAC5G,4GAA4G;AAC5G,qFAAqF;AACrF,EAAE;AACF,yGAAyG;AACzG,4GAA4G;AAC5G,wGAAwG;;;AAqBxG,kCAkIC;AApIY,QAAA,UAAU,GAAG,uBAAuB,CAAC;AAElD,SAAgB,WAAW,CAAC,MAAqB;IAC/C,OAAO;;;;;;;;;;;;;;;;;;;;;;;iBAuBQ,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;eACxB,IAAI,CAAC,SAAS,CAAC,kBAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwGxC,CAAC;AACF,CAAC"}

package/dist/gesture/inspect.d.ts

@@ -0,0 +1,104 @@
+import { type BoneAxisReference } from './axisReference';
+export declare const DEFAULT_BONES: string[];
+export interface InspectOptions {
+    worldDir: string;
+    /** Clip JSON path, or '-' for stdin. */
+    clip: string;
+    /** Times in seconds, or '35%' of duration. Empty + no motion/axes ⇒ ['0']. */
+    times?: string[];
+    bones?: string[];
+    motion?: boolean;
+    axes?: boolean;
+    /** Isolate part of the clip for --motion; without it the rest→pose→rest travel dominates every number. */
+    motionWindow?: [number, number] | null;
+    /** Which bone --axes measures the effect on (default: the last requested bone that exists). */
+    probe?: string | null;
+    /** Custom character GLB; default is the embedded canonical skeleton. */
+    rig?: string | null;
+}
+export interface BoneReadback {
+    pos?: number[];
+    dir?: number[] | null;
+    reads: string;
+    facing?: FacingReadback | null;
+    error?: string;
+}
+export interface FacingReadback {
+    palm?: number[];
+    fingers?: number[];
+    reads?: string;
+    unavailable?: string;
+}
+export interface MotionReadback {
+    lateral?: number;
+    vertical?: number;
+    depth?: number;
+    pathLength?: number;
+    dominant?: string;
+    purity?: number;
+    reversals?: number;
+    reads: string;
+    error?: string;
+}
+export interface AxisRow {
+    axis: string;
+    magnitude: number;
+    delta?: number[];
+    reads: string;
+}
+/** A serializable axis-table row. `bones` is the group's pattern SOURCE, not a RegExp — the result of this
+ *  module is JSON-emitted (`--json`, the MCP), and a RegExp stringifies to `{}`, losing the group identity. */
+export interface AxisRangeRow {
+    bones: string;
+    axes: {
+        x: string;
+        y: string;
+        z: string;
+    };
+    natural: {
+        x: [number, number];
+        y: [number, number];
+        z: [number, number];
+    };
+}
+export interface InspectResult {
+    clip: string;
+    duration: number;
+    rig: string;
+    system: string;
+    warnings: string[];
+    frames: {
+        t: number;
+        bones: Record<string, BoneReadback>;
+    }[];
+    motion: Record<string, MotionReadback> | null;
+    axes: {
+        probe: string;
+        keys: {
+            t: number;
+            rows: AxisRow[];
+        }[];
+    } | null;
+    /** Axis-table rows for the bones this clip actually keys — the context a warning needs, not all 15 groups. */
+    keyedAxisRows: AxisRangeRow[];
+}
+/** Exported for tests: these two produce the human-facing readback, and are duck-typed on .x/.y/.z so
+ *  they need no three. A sign error here silently misleads every measurement an agent takes. */
+/** Coarse compass for a unit vector — never a precise angle, because conformed rigs differ by ~20° at the extremities. */
+export declare function compass(v: any): string;
+export interface Refs {
+    head: number | null;
+    shoulder: number;
+    hip: number;
+    centerX: number;
+    centerZ: number;
+}
+/** Plain-English readback so an agent with no eyes can still tell a good pose from a broken one. */
+export declare function describePose(name: string, pos: any, dir: any, ref: Refs): string;
+export declare function inspectGesture(opts: InspectOptions): Promise<InspectResult>;
+/** Human-readable report. `--json` returns the InspectResult instead. */
+export declare function formatInspect(r: InspectResult, opts?: {
+    motionWindow?: [number, number] | null;
+}): string;
+/** Natural-range context for the bones a clip actually keys — the table rows that matter, not all 15. */
+export declare function relevantAxisRows(table: readonly BoneAxisReference[] | null, clipJson: any): AxisRangeRow[];