@helix3/helix-cli 0.1.20-helix3.381 → 0.1.20-helix3.382

package/dist/continuum/adminPackagePublishCommand.d.ts

@@ -4,6 +4,7 @@ export interface ContinuumAdminPackagePublishDependencies {
     requireAuth(): CliCredentials;
     publishLegacyItemPackage(credentials: CliCredentials, path: string, options: {
         confirmPublicListing: boolean;
+        allowMissingNormals?: boolean;
     }): Promise<unknown>;
     printJson(value: unknown): void;
     fail(message: string): never;

package/dist/continuum/adminPackagePublishCommand.js

@@ -8,9 +8,10 @@ function registerContinuumAdminPackagePublishCommand(continuum, dependencies) {
         .description('Admin-only: publish and pin a legacy Universal Item Package through Continuum')
         .argument('<input>', 'publication JSON; file object paths are resolved beside this file')
         .option('--confirm-public-listing', 'explicitly authorize public Vault/Marketplace Listings for this CLI invocation')
+        .option('--allow-missing-normals', 'publish GLB objects exactly as written even when they have no NORMAL attribute (default: smooth normals are written first)')
         .action(async (path, options) => {
         try {
-            const receipt = await dependencies.publishLegacyItemPackage(dependencies.requireAuth(), path, { confirmPublicListing: options.confirmPublicListing === true });
+            const receipt = await dependencies.publishLegacyItemPackage(dependencies.requireAuth(), path, { confirmPublicListing: options.confirmPublicListing === true, ...(options.allowMissingNormals ? { allowMissingNormals: true } : {}) });
             dependencies.printJson(receipt);
         }
         catch (error) {

package/dist/continuum/adminPackagePublishCommand.js.map

@@ -1 +1 @@
-{"version":3,"file":"adminPackagePublishCommand.js","sourceRoot":"","sources":["../../src/continuum/adminPackagePublishCommand.ts"],"names":[],"mappings":";;AAeA,kGAqBC;AAtBD,4FAA4F;AAC5F,SAAgB,2CAA2C,CACzD,SAAkB,EAClB,YAAsD;IAEtD,SAAS;SACN,OAAO,CAAC,6BAA6B,CAAC;SACtC,WAAW,CAAC,+EAA+E,CAAC;SAC5F,QAAQ,CAAC,SAAS,EAAE,mEAAmE,CAAC;SACxF,MAAM,CAAC,0BAA0B,EAAE,gFAAgF,CAAC;SACpH,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,OAA2C,EAAE,EAAE;QAC1E,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,wBAAwB,CACzD,YAAY,CAAC,WAAW,EAAE,EAC1B,IAAI,EACJ,EAAE,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,KAAK,IAAI,EAAE,CAChE,CAAC;YACF,YAAY,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,IAAI,CAAC,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"adminPackagePublishCommand.js","sourceRoot":"","sources":["../../src/continuum/adminPackagePublishCommand.ts"],"names":[],"mappings":";;AAeA,kGAsBC;AAvBD,4FAA4F;AAC5F,SAAgB,2CAA2C,CACzD,SAAkB,EAClB,YAAsD;IAEtD,SAAS;SACN,OAAO,CAAC,6BAA6B,CAAC;SACtC,WAAW,CAAC,+EAA+E,CAAC;SAC5F,QAAQ,CAAC,SAAS,EAAE,mEAAmE,CAAC;SACxF,MAAM,CAAC,0BAA0B,EAAE,gFAAgF,CAAC;SACpH,MAAM,CAAC,yBAAyB,EAAE,4HAA4H,CAAC;SAC/J,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,OAA0E,EAAE,EAAE;QACzG,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,wBAAwB,CACzD,YAAY,CAAC,WAAW,EAAE,EAC1B,IAAI,EACJ,EAAE,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,KAAK,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CACvI,CAAC;YACF,YAAY,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,IAAI,CAAC,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/continuum/missingNormals.d.ts

@@ -0,0 +1,48 @@
+import type { ContinuumPackageVersion } from '@hypersoniclabs/helix-manifest';
+import { type EnsureNormalsReport } from '../glb/smooth-normals';
+import type { ContinuumObjectPublication } from './types';
+/**
+ * Publication-time guard for a Package's GLB objects.
+ *
+ * A GLB with no NORMAL attribute renders faceted everywhere (glTF 2.0 makes
+ * every runtime fall back to flat face normals), and a sealed Package Version
+ * is immutable: the bytes you seal are the bytes every owner gets, forever.
+ * The only moment the defect is cheap to fix is before sealing, so
+ * `helix continuum publish-package` writes smooth NORMALs into any GLB object
+ * that lacks them, then re-derives the CID and byte counts the descriptor
+ * declared.
+ *
+ * That re-derivation is only sound when the descriptor names the GLB solely
+ * through Package Version object references (`root`, `variants[].object`,
+ * `source`). A vehicle definition or any other sibling object that quotes the
+ * mesh by CID would be left pointing at bytes that no longer exist, so in that
+ * case nothing is rewritten and the publish is refused with the remedy
+ * (`helix glb add-normals`, rebuild the descriptor) or an explicit opt-out.
+ */
+export interface MissingNormalsOptions {
+    creaseAngleDeg?: number;
+    /** Receives one line per rewritten object. Defaults to stderr so a receipt on stdout stays machine-readable. */
+    log?: (message: string) => void;
+}
+export interface NormalsRewrite {
+    filename: string;
+    oldCid: string;
+    newCid: string;
+    oldBytes: number;
+    newBytes: number;
+    report: EnsureNormalsReport;
+}
+export declare class MissingNormalsError extends Error {
+    readonly filename: string;
+    readonly cid: string;
+    readonly fixablePrimitives: number;
+    constructor(filename: string, cid: string, fixablePrimitives: number, detail: string);
+}
+/**
+ * Adds smooth normals to every GLB object that lacks them, rewriting the
+ * Package Version and the object list in place. Returns what changed.
+ *
+ * Only inline (file) objects are examined: an object adopted by CID from an
+ * existing asset is already published and cannot be re-derived here.
+ */
+export declare function addMissingNormalsToPublication(packageVersion: ContinuumPackageVersion, objects: ContinuumObjectPublication[], options?: MissingNormalsOptions): Promise<NormalsRewrite[]>;

package/dist/continuum/missingNormals.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingNormalsError = void 0;
+exports.addMissingNormalsToPublication = addMissingNormalsToPublication;
+const node_crypto_1 = require("node:crypto");
+const smooth_normals_1 = require("../glb/smooth-normals");
+class MissingNormalsError extends Error {
+    filename;
+    cid;
+    fixablePrimitives;
+    constructor(filename, cid, fixablePrimitives, detail) {
+        super(`${filename} has ${fixablePrimitives} mesh primitive(s) with no NORMAL attribute, so it renders faceted everywhere, ` +
+            `and ${detail}. Fix the mesh first: \`helix glb add-normals ${filename}\`, rebuild the descriptor around the new file, ` +
+            'and publish again. Pass --allow-missing-normals only for a mesh that is deliberately flat-shaded.');
+        this.filename = filename;
+        this.cid = cid;
+        this.fixablePrimitives = fixablePrimitives;
+        this.name = 'MissingNormalsError';
+    }
+}
+exports.MissingNormalsError = MissingNormalsError;
+const GLB_MEDIA_TYPE = 'model/gltf-binary';
+const cidOf = (bytes) => `cid:sha256:${(0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex')}`;
+function isReference(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.cid === 'string' &&
+        typeof value.bytes === 'number');
+}
+/** Visits every Package Version object reference carrying `cid`, in place. */
+function replaceReferences(node, oldCid, next) {
+    if (Array.isArray(node))
+        return node.reduce((n, child) => n + replaceReferences(child, oldCid, next), 0);
+    if (typeof node !== 'object' || node === null)
+        return 0;
+    let replaced = 0;
+    if (isReference(node) && node.cid === oldCid) {
+        node.cid = next.cid;
+        node.bytes = next.bytes;
+        replaced++;
+    }
+    for (const value of Object.values(node))
+        replaced += replaceReferences(value, oldCid, next);
+    return replaced;
+}
+function mentions(bytes, text) {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).includes(text);
+}
+/**
+ * Adds smooth normals to every GLB object that lacks them, rewriting the
+ * Package Version and the object list in place. Returns what changed.
+ *
+ * Only inline (file) objects are examined: an object adopted by CID from an
+ * existing asset is already published and cannot be re-derived here.
+ */
+async function addMissingNormalsToPublication(packageVersion, objects, options = {}) {
+    const log = options.log ?? ((message) => console.error(message));
+    const creaseAngleDeg = options.creaseAngleDeg ?? smooth_normals_1.DEFAULT_CREASE_ANGLE_DEG;
+    const rewrites = [];
+    for (const object of objects) {
+        if (object.source.kind !== 'inline')
+            continue;
+        const filename = object.source.filename ?? object.reference.cid;
+        if (object.reference.mediaType !== GLB_MEDIA_TYPE && !/\.glb$/i.test(filename))
+            continue;
+        const original = object.source.bytes;
+        const { bytes, report } = await (0, smooth_normals_1.ensureSmoothNormalsGlb)(original, { creaseAngleDeg });
+        if (!report.changed)
+            continue;
+        const oldCid = object.reference.cid;
+        const oldHex = oldCid.slice('cid:sha256:'.length);
+        const quotedBy = objects.find((other) => other !== object && other.source.kind === 'inline' && mentions(other.source.bytes, oldHex));
+        if (quotedBy) {
+            throw new MissingNormalsError(filename, oldCid, report.fixable, `another object in this publication (${quotedBy.reference.role ?? quotedBy.reference.cid}) quotes the mesh by its CID, so it cannot be rewritten safely here`);
+        }
+        const next = { cid: cidOf(bytes), bytes: bytes.byteLength };
+        const references = replaceReferences(packageVersion, oldCid, next);
+        if (references === 0) {
+            throw new MissingNormalsError(filename, oldCid, report.fixable, 'the Package Version does not reference it as root, variant or source, so the descriptor cannot be re-derived safely here');
+        }
+        object.reference = { ...object.reference, cid: next.cid, bytes: next.bytes };
+        object.source = { ...object.source, bytes };
+        const closure = packageVersion.expectedClosure;
+        if (closure)
+            closure.totalBytes += next.bytes - original.byteLength;
+        rewrites.push({
+            filename,
+            oldCid,
+            newCid: next.cid,
+            oldBytes: original.byteLength,
+            newBytes: next.bytes,
+            report,
+        });
+        log(`✔ ${filename}: ${report.fixable} primitive(s) had no NORMAL; wrote smooth normals ` +
+            `(crease ${creaseAngleDeg}°, ${original.byteLength} → ${next.bytes} bytes, ${oldCid.slice(0, 22)}… → ${next.cid.slice(0, 22)}…)`);
+    }
+    return rewrites;
+}
+//# sourceMappingURL=missingNormals.js.map

package/dist/continuum/missingNormals.js.map

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

package/dist/glb/index.d.ts

@@ -9,3 +9,4 @@
  */
 export { GlbParseError, summarizeGlb, type GlbBoundingBox, type GlbSummary, type GlbTextureInfo, } from './glb-summary';
 export { measureDrawCalls, type DrawCallBreakdown, type DrawCallOffender, } from './draw-calls';
+export { DEFAULT_CREASE_ANGLE_DEG, addSmoothNormals, auditGlbNormals, auditNormals, ensureSmoothNormalsGlb, type EnsureNormalsReport, type NormalsAudit, type NormalsSkipReason, type SmoothNormalsOptions, type SmoothNormalsResult, } from './smooth-normals';

package/dist/glb/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.measureDrawCalls = exports.summarizeGlb = exports.GlbParseError = void 0;
+exports.ensureSmoothNormalsGlb = exports.auditNormals = exports.auditGlbNormals = exports.addSmoothNormals = exports.DEFAULT_CREASE_ANGLE_DEG = exports.measureDrawCalls = exports.summarizeGlb = exports.GlbParseError = void 0;
 /**
  * `@hypersoniclabs/helix-cli/glb` — shared GLB pipeline modules.
  *
@@ -15,4 +15,10 @@ Object.defineProperty(exports, "GlbParseError", { enumerable: true, get: functio
 Object.defineProperty(exports, "summarizeGlb", { enumerable: true, get: function () { return glb_summary_1.summarizeGlb; } });
 var draw_calls_1 = require("./draw-calls");
 Object.defineProperty(exports, "measureDrawCalls", { enumerable: true, get: function () { return draw_calls_1.measureDrawCalls; } });
+var smooth_normals_1 = require("./smooth-normals");
+Object.defineProperty(exports, "DEFAULT_CREASE_ANGLE_DEG", { enumerable: true, get: function () { return smooth_normals_1.DEFAULT_CREASE_ANGLE_DEG; } });
+Object.defineProperty(exports, "addSmoothNormals", { enumerable: true, get: function () { return smooth_normals_1.addSmoothNormals; } });
+Object.defineProperty(exports, "auditGlbNormals", { enumerable: true, get: function () { return smooth_normals_1.auditGlbNormals; } });
+Object.defineProperty(exports, "auditNormals", { enumerable: true, get: function () { return smooth_normals_1.auditNormals; } });
+Object.defineProperty(exports, "ensureSmoothNormalsGlb", { enumerable: true, get: function () { return smooth_normals_1.ensureSmoothNormalsGlb; } });
 //# sourceMappingURL=index.js.map

package/dist/glb/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/glb/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,6CAMuB;AALrB,4GAAA,aAAa,OAAA;AACb,2GAAA,YAAY,OAAA;AAMd,2CAIsB;AAHpB,8GAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/glb/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,6CAMuB;AALrB,4GAAA,aAAa,OAAA;AACb,2GAAA,YAAY,OAAA;AAMd,2CAIsB;AAHpB,8GAAA,gBAAgB,OAAA;AAKlB,mDAW0B;AAVxB,0HAAA,wBAAwB,OAAA;AACxB,kHAAA,gBAAgB,OAAA;AAChB,iHAAA,eAAe,OAAA;AACf,8GAAA,YAAY,OAAA;AACZ,wHAAA,sBAAsB,OAAA"}

package/dist/glb/smooth-normals.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Smooth vertex NORMALs for meshes that ship without any.
+ *
+ * glTF 2.0 obliges a renderer to fall back to FLAT per-face normals when a
+ * primitive has no NORMAL attribute. three.js, the HELIX viewer and the
+ * thumbnail renderer all do exactly that, so a mesh exported without normals
+ * (Meshy/Tripo output, `trimesh` exports, hand-rolled writers) renders as a
+ * faceted polygon soup no matter how dense it is. The fix belongs in the asset:
+ * the renderers are correct.
+ *
+ * This module synthesises the missing attribute deterministically:
+ *   - vertices are grouped by POSITION (a UV seam duplicates a vertex, and a
+ *     seam must NOT become a lighting seam),
+ *   - each triangle corner gets the angle-weighted average of the face normals
+ *     around its position group that lie within `creaseAngleDeg` of the
+ *     corner's own face, so hard edges (a car's panel lines, a table's corners)
+ *     stay crisp while curved surfaces shade smooth,
+ *   - a vertex is split only where the resulting corner normals differ.
+ *
+ * Invariants:
+ *   - A primitive that already carries NORMAL is NEVER touched. Authored
+ *     normals are the creator's intent, flat or smooth.
+ *   - Only TRIANGLES primitives are shaded. Lines, points, strips and fans have
+ *     no meaningful surface normal here.
+ *   - Primitives with morph targets are left alone: a split vertex table would
+ *     have to be mirrored into every target, and a face rig that loses a
+ *     blendshape is a worse defect than a faceted one. They are reported.
+ *   - Primitives whose material is KHR_materials_unlit never read a normal and
+ *     are left alone, so an unlit asset round-trips byte-identical.
+ *   - A GLB with nothing to fix comes back as the SAME bytes, never a
+ *     re-serialisation: no needless change of content identity.
+ *
+ * The backend ships a sibling of this routine for generated (Dreamer) props
+ * (`helix-backend-api/src/universal-items/optimization/smooth-normals.ts`); the
+ * two share the algorithm, not the crease default.
+ */
+import type { Document } from '@gltf-transform/core';
+/**
+ * Edges sharper than this stay hard. 40 degrees keeps 45-degree bevels,
+ * panel-line steps and box corners crisp while smoothing the 5-25 degree facets
+ * of a tessellated curve; Dreamer's 60 is looser because generated props lean
+ * on a baked normal map for their hard detail.
+ */
+export declare const DEFAULT_CREASE_ANGLE_DEG = 40;
+export interface SmoothNormalsOptions {
+    creaseAngleDeg?: number;
+}
+/** Why a primitive without NORMAL was left without one. */
+export type NormalsSkipReason = 'morph-targets' | 'non-triangles' | 'no-position' | 'no-faces' | 'unlit';
+export interface NormalsAudit {
+    /** Every primitive in the document. */
+    primitives: number;
+    /** Primitives that already carry NORMAL. */
+    withNormal: number;
+    /** Primitives with no NORMAL that `addSmoothNormals` can fix. */
+    fixable: number;
+    /** Primitives with no NORMAL that it will not touch, by reason. */
+    skipped: Record<NormalsSkipReason, number>;
+}
+export interface SmoothNormalsResult {
+    primitivesProcessed: number;
+    verticesBefore: number;
+    verticesAfter: number;
+}
+export interface EnsureNormalsReport extends NormalsAudit {
+    changed: boolean;
+    creaseAngleDeg: number;
+    verticesBefore: number;
+    verticesAfter: number;
+    /** Set when the file could not be read (for example Draco-compressed); nothing was changed. */
+    unreadable?: string;
+}
+/** Counts what a document has and what `addSmoothNormals` would do about it. */
+export declare function auditNormals(doc: Document): NormalsAudit;
+/**
+ * Add smooth vertex normals to every fixable triangle primitive of `doc` that
+ * has none. Run `pruneReplacedAccessors` (or write through an optimiser that
+ * prunes) afterwards to drop the accessors that were replaced.
+ */
+export declare function addSmoothNormals(doc: Document, options?: SmoothNormalsOptions): SmoothNormalsResult;
+/**
+ * Audit a GLB's normals without changing it. `unreadable` is set instead of
+ * counts when the file cannot be parsed here (Draco needs a decoder this
+ * package does not ship).
+ */
+export declare function auditGlbNormals(bytes: Uint8Array): Promise<{
+    audit: NormalsAudit | null;
+    unreadable?: string;
+}>;
+/**
+ * Return `bytes` with smooth NORMALs added to every primitive that lacks them.
+ * When there is nothing to fix (or the file cannot be read) the original bytes
+ * come back untouched and `changed` is false.
+ */
+export declare function ensureSmoothNormalsGlb(bytes: Uint8Array, options?: SmoothNormalsOptions): Promise<{
+    bytes: Uint8Array;
+    report: EnsureNormalsReport;
+}>;