@helix3/helix-cli 0.1.14-helix3.205 → 0.1.14-helix3.207

package/dist/character/avatarPreflight.d.ts

@@ -0,0 +1,60 @@
+import { type GlbSummary } from "../glb";
+/**
+ * WHAT THE PLATFORM WILL SAY ABOUT THIS AVATAR, SAID HERE INSTEAD.
+ *
+ * `publishItem` uploads the GLB byte-for-byte and the backend verifies it on arrival. That is the correct
+ * division of labour — the server must never trust a client's word about the file — but it means every
+ * rejection costs an upload, and the creator learns their character is a material over the cap after the round
+ * trip rather than before it. The failures are all statically checkable from the file, so this checks them.
+ *
+ * The numbers are the BACKEND's own defaults (`AVATAR_MAX_*` in its config), duplicated deliberately and
+ * labelled as such: a client-side preflight that guesses looser limits than the server is worse than no
+ * preflight, because it produces confident green output for a file that will be refused. When the server's
+ * numbers move, these move with them — and being wrong here costs a round trip, exactly what it costs today.
+ *
+ * The manifest checks are the other half, and they have no server counterpart at all. A character can pass
+ * every numeric limit and still arrive with no physics, no face and no first-person head declaration, which is
+ * a silently diminished avatar rather than a rejected one — the worst failure mode this pipeline has, and the
+ * one it has already shipped twice.
+ */
+/** The backend's `AVATAR_MAX_*` defaults. Mirrored, not derived: this process cannot see that config. */
+export declare const AVATAR_LIMITS: {
+    readonly maxTriangles: 60000;
+    readonly maxTextureEdge: 2048;
+    readonly maxFileBytes: number;
+    readonly maxMaterials: 8;
+};
+/** The wearable ceilings, roughly a third of an avatar's, because several are worn at once. */
+export declare const WEARABLE_LIMITS: {
+    readonly maxTriangles: 20000;
+    readonly maxTextureEdge: 2048;
+    readonly maxFileBytes: number;
+    readonly maxMaterials: 4;
+};
+export type PreflightSeverity = 'error' | 'warning';
+export interface PreflightFinding {
+    severity: PreflightSeverity;
+    /** Stable code so a caller can filter without matching prose. */
+    code: string;
+    message: string;
+}
+export interface AvatarPreflightResult {
+    ok: boolean;
+    findings: PreflightFinding[];
+    summary: GlbSummary;
+    /** What the character declares beyond geometry, for the report. */
+    manifests: {
+        dynamics: number | null;
+        faceChannels: number | null;
+        firstPersonHide: number | null;
+    };
+}
+/**
+ * Check a character GLB against the publish gate without touching the network.
+ *
+ * `kind` picks the ceiling set: an avatar and a wearable are the same file format with different budgets,
+ * because several wearables are worn on top of one avatar.
+ */
+export declare function preflightAvatar(buffer: Buffer, kind?: 'avatar' | 'wearable'): AvatarPreflightResult;
+/** One line per finding, plus the capability line, for the CLI's own output. */
+export declare function formatPreflight(result: AvatarPreflightResult): string;

package/dist/character/avatarPreflight.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEARABLE_LIMITS = exports.AVATAR_LIMITS = void 0;
+exports.preflightAvatar = preflightAvatar;
+exports.formatPreflight = formatPreflight;
+const glb_1 = require("../glb");
+/**
+ * WHAT THE PLATFORM WILL SAY ABOUT THIS AVATAR, SAID HERE INSTEAD.
+ *
+ * `publishItem` uploads the GLB byte-for-byte and the backend verifies it on arrival. That is the correct
+ * division of labour — the server must never trust a client's word about the file — but it means every
+ * rejection costs an upload, and the creator learns their character is a material over the cap after the round
+ * trip rather than before it. The failures are all statically checkable from the file, so this checks them.
+ *
+ * The numbers are the BACKEND's own defaults (`AVATAR_MAX_*` in its config), duplicated deliberately and
+ * labelled as such: a client-side preflight that guesses looser limits than the server is worse than no
+ * preflight, because it produces confident green output for a file that will be refused. When the server's
+ * numbers move, these move with them — and being wrong here costs a round trip, exactly what it costs today.
+ *
+ * The manifest checks are the other half, and they have no server counterpart at all. A character can pass
+ * every numeric limit and still arrive with no physics, no face and no first-person head declaration, which is
+ * a silently diminished avatar rather than a rejected one — the worst failure mode this pipeline has, and the
+ * one it has already shipped twice.
+ */
+/** The backend's `AVATAR_MAX_*` defaults. Mirrored, not derived: this process cannot see that config. */
+exports.AVATAR_LIMITS = {
+    maxTriangles: 60_000,
+    maxTextureEdge: 2048,
+    maxFileBytes: 10 * 1024 * 1024,
+    maxMaterials: 8,
+};
+/** The wearable ceilings, roughly a third of an avatar's, because several are worn at once. */
+exports.WEARABLE_LIMITS = {
+    maxTriangles: 20_000,
+    maxTextureEdge: 2048,
+    maxFileBytes: 6 * 1024 * 1024,
+    maxMaterials: 4,
+};
+/**
+ * Core joints the runtime needs to embed a body at all.
+ *
+ * Deliberately the SHORT list — the handful whose absence means the avatar cannot be driven — rather than all
+ * 68. A preflight that reimplements the server's full skeleton check will drift from it; this one catches the
+ * case where the file is not a HELIX character at all.
+ */
+const REQUIRED_JOINTS = ['root', 'pelvis', 'spine_01', 'head', 'hand_l', 'hand_r', 'foot_l', 'foot_r'];
+/**
+ * Read the scene extras straight out of the GLB's JSON chunk.
+ *
+ * Parsed here rather than through `@gltf-transform` because a preflight must not fail on a file the reader
+ * cannot fully load: an unknown extension, a Draco stream without its decoder, a KTX2 texture. The one thing
+ * this needs is the JSON chunk, and every valid GLB has one.
+ */
+function readSceneExtras(buffer) {
+    if (buffer.byteLength < 20)
+        return {};
+    const jsonLength = buffer.readUInt32LE(12);
+    if (jsonLength <= 0 || 20 + jsonLength > buffer.byteLength)
+        return {};
+    try {
+        const json = JSON.parse(buffer.subarray(20, 20 + jsonLength).toString('utf8'));
+        return json.scenes?.[0]?.extras ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Check a character GLB against the publish gate without touching the network.
+ *
+ * `kind` picks the ceiling set: an avatar and a wearable are the same file format with different budgets,
+ * because several wearables are worn on top of one avatar.
+ */
+function preflightAvatar(buffer, kind = 'avatar') {
+    const limits = kind === 'avatar' ? exports.AVATAR_LIMITS : exports.WEARABLE_LIMITS;
+    const summary = (0, glb_1.summarizeGlb)(buffer);
+    const extras = readSceneExtras(buffer);
+    const findings = [];
+    const fail = (code, message) => { findings.push({ severity: 'error', code, message }); };
+    const warn = (code, message) => { findings.push({ severity: 'warning', code, message }); };
+    if (summary.triangleCount > limits.maxTriangles) {
+        fail('triangles', `${summary.triangleCount.toLocaleString()} triangles exceeds the ${limits.maxTriangles.toLocaleString()} ${kind} cap`);
+    }
+    if (summary.materialCount > limits.maxMaterials) {
+        fail('materials', `${summary.materialCount} materials exceeds the ${limits.maxMaterials}-material ${kind} cap — `
+            + 'atlas them at import (this is the limit a converted VRM fails first, and by the widest margin)');
+    }
+    if (summary.maxTextureEdge > limits.maxTextureEdge) {
+        fail('texture-edge', `largest texture edge ${summary.maxTextureEdge}px exceeds the ${limits.maxTextureEdge}px cap`);
+    }
+    if (summary.sizeBytes > limits.maxFileBytes) {
+        const mb = (n) => `${(n / 1024 / 1024).toFixed(1)} MB`;
+        fail('file-size', `${mb(summary.sizeBytes)} exceeds the ${mb(limits.maxFileBytes)} ${kind} cap`);
+    }
+    if (kind === 'avatar') {
+        if (summary.skinCount === 0) {
+            fail('no-skin', 'an avatar must carry a skinned mesh; this file has none');
+        }
+        const joints = new Set(summary.boneNames);
+        const missing = REQUIRED_JOINTS.filter((joint) => !joints.has(joint));
+        if (missing.length > 0) {
+            fail('skeleton', `missing core helix-humanoid joints: ${missing.join(', ')} — the runtime cannot drive this body`);
+        }
+        // A cm-scale rig binds pristinely and renders correctly at rest, then explodes the moment a clip plays.
+        if (summary.skeletonSpanY !== null && summary.skeletonSpanY > 10) {
+            fail('rig-scale', `skeleton spans ${summary.skeletonSpanY.toFixed(1)}m — the rig is not in metres`);
+        }
+    }
+    const dynamics = Array.isArray(extras.helixDynamics?.chains) ? extras.helixDynamics.chains.length : null;
+    const faceChannels = extras.helixFace?.channels ? Object.keys(extras.helixFace.channels).length : null;
+    const firstPersonHide = Array.isArray(extras.helixAvatar?.firstPersonHide)
+        ? extras.helixAvatar.firstPersonHide.length
+        : null;
+    if (kind === 'avatar') {
+        // Warnings, not errors: a character with no hair does not need physics, and a stylised avatar may have no
+        // visemes. Each one is a capability the platform WILL look for at runtime, so silence about them is how an
+        // avatar ships diminished and nobody notices until someone speaks to it.
+        if (dynamics === null)
+            warn('no-dynamics', 'no helixDynamics — hair, tails and cloth will not move');
+        if (faceChannels === null)
+            warn('no-face', 'no helixFace — this character cannot lip-sync or blink');
+        if (firstPersonHide === null) {
+            warn('no-first-person-hide', 'no helixAvatar.firstPersonHide — first person will render this head across the camera unless a mesh '
+                + 'happens to be named FaceMesh');
+        }
+    }
+    return {
+        ok: findings.every((finding) => finding.severity !== 'error'),
+        findings,
+        summary,
+        manifests: { dynamics, faceChannels, firstPersonHide },
+    };
+}
+/** One line per finding, plus the capability line, for the CLI's own output. */
+function formatPreflight(result) {
+    const lines = result.findings.map((f) => `${f.severity === 'error' ? '✗' : '⚠'} ${f.message}`);
+    const { dynamics, faceChannels, firstPersonHide } = result.manifests;
+    lines.push(`  ${result.summary.triangleCount.toLocaleString()} tris · ${result.summary.materialCount} materials · `
+        + `${result.summary.maxTextureEdge}px · ${(result.summary.sizeBytes / 1024 / 1024).toFixed(1)} MB · `
+        + `${result.summary.boneNames.length} joints`);
+    lines.push(`  physics ${dynamics ?? 0} chains · face ${faceChannels ?? 0} channels · first-person ${firstPersonHide ?? 0} surfaces`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=avatarPreflight.js.map

package/dist/character/avatarPreflight.js.map

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

package/dist/index.js

@@ -3832,7 +3832,7 @@ continuum
         const creds = requireAuth();
         const backend = await continuumStagedPackageVersionSupport(creds.apiUrl);
         console.log(JSON.stringify({
-            contract: 'helix.creator.publication-capabilities/1',
+            contract: 'helix.creator.continuum-publication-capabilities/1',
             apiOrigin: creds.apiUrl,
             existingObjectSource: true,
             sealedNonCurrentStaging: true,