@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/distribution.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISTRIBUTION_KEY_PATTERN = exports.ITEM_DISTRIBUTION_CHANNELS = exports.ITEM_EDITION_MODES = void 0;
+exports.distributionIntentId = distributionIntentId;
+exports.buildItemDistribution = buildItemDistribution;
+exports.buildItemDistributionUpdate = buildItemDistributionUpdate;
+exports.editionFields = editionFields;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Canonical universal-item distribution vocabulary.
+ *
+ * An item definition says what the item is. A distribution is one creator-
+ * authorized primary acquisition route. Keeping this builder network-free
+ * lets `--dry-run` exercise exactly the payload the real command sends.
+ */
+exports.ITEM_EDITION_MODES = ['standard', 'collectible'];
+exports.ITEM_DISTRIBUTION_CHANNELS = ['marketplace', 'world'];
+exports.DISTRIBUTION_KEY_PATTERN = /^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$/;
+/**
+ * Derive the durable caller intent for one distribution request.
+ *
+ * The route API requires an `intentId` and treats it as an idempotency key:
+ * an exact retry returns the same distribution, while reusing one with
+ * different input conflicts. Deriving it from the request itself gives that
+ * property for free — re-running the same command cannot mint a second
+ * identical route, which is the whole hazard of a duplicated listing — while a
+ * genuinely different route hashes to a different id.
+ *
+ * The value is shaped as a v4 UUID because that is what the API validates. It
+ * is derived, not random, so `--intent-id` remains available for a caller that
+ * wants to retry across a changed request or force a distinct route.
+ */
+function distributionIntentId(fields) {
+    const canonical = JSON.stringify(Object.fromEntries(Object.entries(fields).sort(([a], [b]) => a.localeCompare(b))));
+    const digest = (0, node_crypto_1.createHash)('sha256').update(canonical).digest('hex');
+    return [
+        digest.slice(0, 8),
+        digest.slice(8, 12),
+        `4${digest.slice(13, 16)}`,
+        ((parseInt(digest.slice(16, 17), 16) & 0x3) | 0x8).toString(16) + digest.slice(17, 20),
+        digest.slice(20, 32),
+    ].join('-');
+}
+const positiveInt = (name, value) => {
+    if (value === undefined || value === null)
+        return;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${name} must be a whole number >= 1, or unlimited`);
+    }
+};
+const price = (value) => {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`--price-lix must be a number >= 0 LIX (got ${value})`);
+    }
+    return value;
+};
+const timestamp = (name, value) => {
+    if (value === undefined || value === null)
+        return value;
+    const parsed = new Date(value);
+    if (!Number.isFinite(parsed.valueOf())) {
+        throw new Error(`${name} must be an ISO-8601 timestamp (got "${value}")`);
+    }
+    return parsed.toISOString();
+};
+function buildItemDistribution(input) {
+    if (!exports.ITEM_DISTRIBUTION_CHANNELS.includes(input.channel)) {
+        throw new Error(`--channel must be marketplace or world (got "${input.channel}")`);
+    }
+    const priceLix = price(input.priceLix);
+    positiveInt('--max-per-player', input.maxPerPlayer);
+    positiveInt('--max-claims', input.maxClaims);
+    const startsAt = timestamp('--starts-at', input.startsAt);
+    const endsAt = timestamp('--ends-at', input.endsAt);
+    if (startsAt && endsAt && new Date(startsAt) >= new Date(endsAt)) {
+        throw new Error('--ends-at must be later than --starts-at');
+    }
+    const worldId = input.worldId?.trim();
+    const worldSlug = input.worldSlug?.trim();
+    const key = input.key?.trim();
+    if (input.channel === 'world') {
+        if (!worldId && !worldSlug) {
+            throw new Error('a world distribution requires --world <slug>');
+        }
+        if (!key)
+            throw new Error('a world distribution requires --distribution-key <key>');
+        if (!exports.DISTRIBUTION_KEY_PATTERN.test(key)) {
+            throw new Error(`--distribution-key "${key}" must use lowercase letters, digits, _ or - (1-64 characters)`);
+        }
+    }
+    else if (worldId || input.worldSlug || key) {
+        throw new Error('a marketplace distribution cannot carry --world or --distribution-key');
+    }
+    const fields = {
+        ...(input.itemId ? { itemId: input.itemId } : {}),
+        channel: input.channel,
+        priceLix,
+        ...(worldId ? { worldId } : {}),
+        ...(!worldId && worldSlug ? { worldSlug } : {}),
+        ...(key ? { key } : {}),
+        ...(input.maxPerPlayer !== undefined ? { maxPerPlayer: input.maxPerPlayer } : {}),
+        ...(input.maxClaims !== undefined ? { maxClaims: input.maxClaims } : {}),
+        ...(startsAt !== undefined ? { startsAt } : {}),
+        ...(endsAt !== undefined ? { endsAt } : {}),
+    };
+    return fields;
+}
+function buildItemDistributionUpdate(input) {
+    if (input.priceLix === undefined && input.maxPerPlayer === undefined &&
+        input.maxClaims === undefined && input.startsAt === undefined && input.endsAt === undefined) {
+        throw new Error('no distribution changes supplied');
+    }
+    if (input.priceLix !== undefined)
+        price(input.priceLix);
+    positiveInt('--max-per-player', input.maxPerPlayer);
+    positiveInt('--max-claims', input.maxClaims);
+    const startsAt = timestamp('--starts-at', input.startsAt);
+    const endsAt = timestamp('--ends-at', input.endsAt);
+    if (startsAt && endsAt && new Date(startsAt) >= new Date(endsAt)) {
+        throw new Error('--ends-at must be later than --starts-at');
+    }
+    return {
+        ...(input.priceLix !== undefined ? { priceLix: input.priceLix } : {}),
+        ...(input.maxPerPlayer !== undefined ? { maxPerPlayer: input.maxPerPlayer } : {}),
+        ...(input.maxClaims !== undefined ? { maxClaims: input.maxClaims } : {}),
+        ...(startsAt !== undefined ? { startsAt } : {}),
+        ...(endsAt !== undefined ? { endsAt } : {}),
+    };
+}
+function editionFields(collectibleSupply) {
+    if (collectibleSupply === undefined)
+        return { editionMode: 'standard' };
+    if (!Number.isInteger(collectibleSupply) || collectibleSupply < 1) {
+        throw new Error('--collectible-supply must be a whole number >= 1');
+    }
+    return { editionMode: 'collectible', collectibleSupply };
+}
+//# sourceMappingURL=distribution.js.map

package/dist/distribution.js.map

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

package/dist/enginePins.d.ts

@@ -0,0 +1,45 @@
+/** A complete x.y.z (optionally with a prerelease tag): the one shape that resolves to a single immutable build. */
+export declare const EXACT_VERSION: RegExp;
+export type ExactEnginePin = {
+    slug: string;
+    /** What helix.json asks for (or, for an import-map-only finding, the immutable URL's revision path). */
+    range: string;
+    /** Where the pin was seen. A pin usually appears in all three; a hand-edited artifact may carry only one. */
+    sources: Array<'helix.json' | 'helix.runtime.json' | 'index.html'>;
+};
+/** The flag every refusal, doc and tool names. One spelling, so it can be grepped. */
+export declare const ALLOW_EXACT_ENGINE_PIN_FLAG = "--allow-exact-engine-pin";
+export declare const EXACT_ENGINE_PIN_RUNBOOK: string;
+export declare function isImmutableEngineUrl(url: string): boolean;
+/**
+ * Every platform system this World delivers as an exact immutable build, from the three declarations a
+ * publish is made of: helix.json's `systems`, helix.runtime.json (`mode: "pinned"`) and the entry HTML's
+ * import map (an `@helix/*` specifier aimed at an immutable /packages/<id>/<rev>/code/ URL). Any one is enough:
+ * a descriptor that says "pinned" or an import map that points at a revision is delivered pinned whatever
+ * helix.json says. Compiled-in ('legacy-bundled') systems are NOT reported — different mode, different gate.
+ */
+export declare function detectExactEnginePins(input: {
+    manifestSystems?: Record<string, unknown> | null;
+    descriptor?: unknown;
+    entryHtml?: string | null;
+}): ExactEnginePin[];
+export declare function describeExactEnginePins(pins: ExactEnginePin[]): string;
+export declare function exactEnginePinRefusal(pins: ExactEnginePin[]): string;
+export declare function exactEnginePinOverrideWarning(pins: ExactEnginePin[], reason: string): string;
+/** The reason is the audit trail, so an empty/whitespace flag value is refused rather than defaulted. */
+export declare function requireOverrideReason(value: unknown): string;
+export type EnginePinOverrideRecord = {
+    at: string;
+    slug: string;
+    reason: string;
+    command: 'publish' | 'validate';
+    pins: Array<{
+        slug: string;
+        range: string;
+        sources: string[];
+    }>;
+    apiUrl?: string;
+};
+export declare function enginePinOverrideLogPath(): string;
+/** Append-only JSONL: one line per override actually used. Never throws into the publish path's caller silently — a log that cannot be written refuses the override. */
+export declare function recordEnginePinOverride(record: EnginePinOverrideRecord): string;

package/dist/enginePins.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXACT_ENGINE_PIN_RUNBOOK = exports.ALLOW_EXACT_ENGINE_PIN_FLAG = exports.EXACT_VERSION = void 0;
+exports.isImmutableEngineUrl = isImmutableEngineUrl;
+exports.detectExactEnginePins = detectExactEnginePins;
+exports.describeExactEnginePins = describeExactEnginePins;
+exports.exactEnginePinRefusal = exactEnginePinRefusal;
+exports.exactEnginePinOverrideWarning = exactEnginePinOverrideWarning;
+exports.requireOverrideReason = requireOverrideReason;
+exports.enginePinOverrideLogPath = enginePinOverrideLogPath;
+exports.recordEnginePinOverride = recordEnginePinOverride;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+// ENGINE SYSTEMS ARE RANGES. Jack's standing rule: every World and Home loads the latest PROMOTED engine at
+// load time through a platform runtime range (helix.json "systems": { "humanoid-character": "^0.3", ... }).
+// An exact version freezes that World on one immutable build: it never receives another engine fix, and the
+// usual reason it exists — an agent wanting a fix BEFORE it was promoted — is solved by promoting the fix
+// (POST /api/v1/instant-packages/<slug>/versions/<version>/rollout), not by pinning each World to it.
+//
+// This module is the ONE definition of "an exact engine pin" shared by `helix validate`, `helix publish`
+// (through checkBundle), `helix install` and the MCP. A compiled-in ('legacy-bundled') World is a different
+// delivery mode with its own refusal and is deliberately not touched here.
+/** A complete x.y.z (optionally with a prerelease tag): the one shape that resolves to a single immutable build. */
+exports.EXACT_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+/** The flag every refusal, doc and tool names. One spelling, so it can be grepped. */
+exports.ALLOW_EXACT_ENGINE_PIN_FLAG = '--allow-exact-engine-pin';
+exports.EXACT_ENGINE_PIN_RUNBOOK = 'To ship an engine fix to Worlds, PROMOTE it — POST {api}/api/v1/instant-packages/<slug>/versions/<version>/rollout ' +
+    '{"rolloutPercent":100,"reason":"…"} (the helix3 publish workflow\'s promote job does this) — and every World on the range receives it ' +
+    'on its next launch. Do not pin a World to get an unpromoted fix.';
+// `@helix/humanoid-character` or `@helix/engine-core/inspect` -> `humanoid-character` / `engine-core`.
+function slugOfSpecifier(specifier) {
+    const match = /^@helix\/([a-z0-9][a-z0-9-]*)(?:\/|$)/.exec(specifier);
+    return match ? match[1] : null;
+}
+// An immutable catalog URL: <cdn>/packages/<package-id>/<revision>/code/<module>. The compatible resolver URL
+// (<api>/api/v1/instant-packages/<slug>/runtime/<range>/<module>) also contains "packages/", so exclude it.
+const IMMUTABLE_CODE_URL = /\/packages\/[^/]+\/[^/]+\/code\//;
+const COMPATIBLE_RESOLVER_URL = /\/instant-packages\/[^/]+\/runtime\//;
+function isImmutableEngineUrl(url) {
+    return IMMUTABLE_CODE_URL.test(url) && !COMPATIBLE_RESOLVER_URL.test(url);
+}
+function importMapImports(html) {
+    const merged = {};
+    for (const match of html.matchAll(/<script[^>]*type=["']importmap["'][^>]*>([\s\S]*?)<\/script>/gi)) {
+        try {
+            const parsed = JSON.parse(match[1]);
+            for (const [specifier, url] of Object.entries(parsed.imports ?? {})) {
+                if (typeof url === 'string')
+                    merged[specifier] = url;
+            }
+        }
+        catch {
+            // A malformed import map is the existing validator's finding, not ours.
+        }
+    }
+    return merged;
+}
+/**
+ * Every platform system this World delivers as an exact immutable build, from the three declarations a
+ * publish is made of: helix.json's `systems`, helix.runtime.json (`mode: "pinned"`) and the entry HTML's
+ * import map (an `@helix/*` specifier aimed at an immutable /packages/<id>/<rev>/code/ URL). Any one is enough:
+ * a descriptor that says "pinned" or an import map that points at a revision is delivered pinned whatever
+ * helix.json says. Compiled-in ('legacy-bundled') systems are NOT reported — different mode, different gate.
+ */
+function detectExactEnginePins(input) {
+    const found = new Map();
+    const add = (slug, range, source) => {
+        const existing = found.get(slug);
+        if (existing) {
+            if (!existing.sources.includes(source))
+                existing.sources.push(source);
+        }
+        else {
+            found.set(slug, { slug, range, sources: [source] });
+        }
+    };
+    for (const [slug, range] of Object.entries(input.manifestSystems ?? {})) {
+        if (typeof range === 'string' && exports.EXACT_VERSION.test(range.trim()))
+            add(slug, range.trim(), 'helix.json');
+    }
+    const systems = input.descriptor?.systems;
+    if (Array.isArray(systems)) {
+        for (const entry of systems) {
+            if (entry && entry.mode === 'pinned' && typeof entry.slug === 'string') {
+                add(entry.slug, typeof entry.requestedRange === 'string' ? entry.requestedRange : 'pinned', 'helix.runtime.json');
+            }
+        }
+    }
+    if (input.entryHtml) {
+        for (const [specifier, url] of Object.entries(importMapImports(input.entryHtml))) {
+            const slug = slugOfSpecifier(specifier);
+            if (slug && isImmutableEngineUrl(url))
+                add(slug, found.get(slug)?.range ?? 'immutable-url', 'index.html');
+        }
+    }
+    return [...found.values()].sort((a, b) => a.slug.localeCompare(b.slug));
+}
+function describeExactEnginePins(pins) {
+    return pins.map((pin) => `${pin.slug} ${pin.range === 'immutable-url' || pin.range === 'pinned' ? '(immutable URL)' : `"${pin.range}"`} [${pin.sources.join(', ')}]`).join('; ');
+}
+function exactEnginePinRefusal(pins) {
+    return (`engine systems must be ranges, but this World is delivered pinned to an exact build: ${describeExactEnginePins(pins)}. ` +
+        `Use a caret line (e.g. "humanoid-character": "^0.3"), run \`helix install --update\`, rebuild. ${exports.EXACT_ENGINE_PIN_RUNBOOK} ` +
+        `Only if an exact pin is genuinely intended, pass ${exports.ALLOW_EXACT_ENGINE_PIN_FLAG} "<reason>" — the reason is required and the override is logged.`);
+}
+function exactEnginePinOverrideWarning(pins, reason) {
+    return (`EXACT ENGINE PIN OVERRIDE: publishing with ${describeExactEnginePins(pins)}. ` +
+        `This World will NOT receive engine fixes or promotions until it is re-published on a range. Reason recorded: "${reason}".`);
+}
+/** The reason is the audit trail, so an empty/whitespace flag value is refused rather than defaulted. */
+function requireOverrideReason(value) {
+    const reason = typeof value === 'string' ? value.trim() : '';
+    if (!reason) {
+        throw new Error(`${exports.ALLOW_EXACT_ENGINE_PIN_FLAG} needs a non-empty reason (it is recorded), e.g. ${exports.ALLOW_EXACT_ENGINE_PIN_FLAG} "fix X is staged, promotion blocked by Y — repin to a range once promoted"`);
+    }
+    return reason;
+}
+function enginePinOverrideLogPath() {
+    return process.env.HELIX_ENGINE_PIN_OVERRIDE_LOG || (0, node_path_1.join)((0, node_os_1.homedir)(), '.helix', 'engine-pin-overrides.jsonl');
+}
+/** Append-only JSONL: one line per override actually used. Never throws into the publish path's caller silently — a log that cannot be written refuses the override. */
+function recordEnginePinOverride(record) {
+    const path = enginePinOverrideLogPath();
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+        (0, node_fs_1.appendFileSync)(path, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    }
+    catch (err) {
+        throw new Error(`cannot record the exact-engine-pin override at ${path} (${err instanceof Error ? err.message : err}); an unlogged override is refused`);
+    }
+    return path;
+}
+//# sourceMappingURL=enginePins.js.map

package/dist/enginePins.js.map

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

package/dist/gesture/axisReference.d.ts

@@ -0,0 +1,22 @@
+/** Mirrors the engine's exported `BoneAxisReference` — a structural type for what we read, not a second copy. */
+export interface BoneAxisReference {
+    bones: RegExp;
+    /** Human-terms meaning of each axis (what a POSITIVE value does; negative is the opposite). */
+    axes: {
+        x: string;
+        y: string;
+        z: string;
+    };
+    /** Suggested natural range [min, max] per axis, degrees. Outside → compile warning, not error. */
+    natural: {
+        x: [number, number];
+        y: [number, number];
+        z: [number, number];
+    };
+}
+export declare function axisReferenceFor(table: readonly BoneAxisReference[], bone: string): BoneAxisReference | undefined;
+/** `/^upperarm_(l|r)$/` → `upperarm_l/r` — the regex is the matcher; this is what a human reads. */
+export declare function boneLabel(pattern: RegExp): string;
+/** Markdown table — what `helix gesture axes` prints and the MCP curriculum points at. */
+export declare function renderAxisTableMarkdown(table: readonly BoneAxisReference[]): string;
+export declare function renderAxisTableJson(table: readonly BoneAxisReference[]): unknown;

package/dist/gesture/axisReference.js

@@ -0,0 +1,32 @@
+"use strict";
+// Renderers for the bone axis table. There is NO copy of the table here: it is read at runtime from the
+// world's installed humanoid-character system, the same module this command already loads compileGesture
+// and GesturePlayer from. One authored home (the engine's src/animation/gestures/poseDsl.ts), and what
+// you see is the table the version YOU pinned actually lints against.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.axisReferenceFor = axisReferenceFor;
+exports.boneLabel = boneLabel;
+exports.renderAxisTableMarkdown = renderAxisTableMarkdown;
+exports.renderAxisTableJson = renderAxisTableJson;
+function axisReferenceFor(table, bone) {
+    return table.find((entry) => entry.bones.test(bone));
+}
+/** `/^upperarm_(l|r)$/` → `upperarm_l/r` — the regex is the matcher; this is what a human reads. */
+function boneLabel(pattern) {
+    return pattern.source.replace(/^\^/, '').replace(/\$$/, '').replace(/\((l\|r)\)/g, 'l/r').replace(/\\d\\d/g, 'NN');
+}
+const fmtRange = ([min, max]) => (min === -max ? `±${max}` : `${min}…${max}`);
+/** Markdown table — what `helix gesture axes` prints and the MCP curriculum points at. */
+function renderAxisTableMarkdown(table) {
+    const rows = table.map((e) => {
+        const nat = `${fmtRange(e.natural.x)} / ${fmtRange(e.natural.y)} / ${fmtRange(e.natural.z)}`;
+        return `| \`${boneLabel(e.bones)}\` | ${e.axes.x} | ${e.axes.y} | ${e.axes.z} | ${nat} |`;
+    });
+    return ['| Bone | X (+) | Y (+) | Z (+) | natural X / Y / Z |', '|---|---|---|---|---|', ...rows].join('\n');
+}
+function renderAxisTableJson(table) {
+    return {
+        groups: table.map((e) => ({ bones: boneLabel(e.bones), pattern: e.bones.source, axes: e.axes, natural: e.natural })),
+    };
+}
+//# sourceMappingURL=axisReference.js.map

package/dist/gesture/axisReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"axisReference.js","sourceRoot":"","sources":["../../src/gesture/axisReference.ts"],"names":[],"mappings":";AAAA,wGAAwG;AACxG,yGAAyG;AACzG,uGAAuG;AACvG,sEAAsE;;AAWtE,4CAEC;AAGD,8BAEC;AAKD,0DAMC;AAED,kDAIC;AAxBD,SAAgB,gBAAgB,CAAC,KAAmC,EAAE,IAAY;IAChF,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,oGAAoG;AACpG,SAAgB,SAAS,CAAC,OAAe;IACvC,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AACrH,CAAC;AAED,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAmB,EAAU,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC;AAExG,0FAA0F;AAC1F,SAAgB,uBAAuB,CAAC,KAAmC;IACzE,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC3B,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7F,OAAO,OAAO,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5F,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,sDAAsD,EAAE,uBAAuB,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/G,CAAC;AAED,SAAgB,mBAAmB,CAAC,KAAmC;IACrE,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;KACrH,CAAC;AACJ,CAAC"}

package/dist/gesture/capture.d.ts

@@ -0,0 +1,84 @@
+import { type BrowserKey } from '../screenshot/captureScreenshots';
+import { type HarnessConfig } from './harnessPage';
+import { type InspectAttachSpec } from './inspect';
+export declare const VIEW_NAMES: readonly ["front", "back", "right", "left", "three-quarter"];
+export type ViewName = typeof VIEW_NAMES[number];
+export declare const MAX_VIEWS = 2;
+/**
+ * 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.
+ */
+export declare function viewAzimuth(view: ViewName, side: 'left' | 'right'): number;
+export declare function viewLabel(view: ViewName, side: 'left' | 'right'): string;
+export type CaptureGestureOptions = {
+    worldDir: string;
+    clip: string;
+    out: string;
+    frames?: number;
+    /** Up to two of front | back | left | right. Omitted, the side is derived from which side the clip keys. */
+    views?: ViewName[];
+    /** One moment instead of a sequence: seconds, or a percentage of duration like '60%'. Views go side by
+     *  side at roughly 1.8x the cell size, for inspecting a specific detail rather than comparing over time. */
+    at?: number | string;
+    /** Render a prop attached while the clip plays — same spec as inspect's, resolved against the world's presets. */
+    attach?: InspectAttachSpec;
+    cellHeight?: number;
+    timeoutMs?: number;
+    browser?: BrowserKey;
+    onProgress?: (message: string) => void;
+};
+export type CaptureGestureResult = {
+    file: string;
+    clip: string;
+    duration: number;
+    times: number[];
+    views: ViewName[];
+    /** True when a single moment was captured, so views are columns rather than rows. */
+    moment: boolean;
+    /** True when both views look down the same axis, so neither reveals depth — worth telling the caller. */
+    sharedAxis: boolean;
+    warnings: string[];
+    /** What was attached, when a prop was requested. */
+    attachment: {
+        prop: string;
+        socket: string;
+        preset: string | null;
+    } | null;
+};
+export declare function captureGesture(opts: CaptureGestureOptions): Promise<CaptureGestureResult>;
+type ClipShape = {
+    duration?: unknown;
+    mask?: unknown;
+    overrideMask?: unknown;
+    keys?: unknown;
+};
+/**
+ * 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.
+ */
+export declare function arrangeGrid(times: number[], views: ViewName[], moment: boolean, side: 'left' | 'right'): Omit<HarnessConfig, 'cellW' | 'cellH'>;
+/** `--at` takes seconds or a percentage of duration, matching `inspect --t`. */
+export declare function parseMoment(at: number | string, duration: number): number;
+/**
+ * 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.
+ */
+export declare function clipSide(source: ClipShape): 'left' | '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.
+ */
+export declare function resolveViews(requested: ViewName[] | undefined, source: ClipShape, moment?: boolean): ViewName[];
+/** front+back and left+right are each a single axis seen twice: both are frontal projections of the same plane. */
+export declare function sharesAxis(views: ViewName[]): boolean;
+export {};