@aelionsdk/render-ir 1.2.0-rc.5 → 2.0.0

package/README.md

@@ -6,10 +6,10 @@ evaluation for AelionSDK.
 ## Install
 
 ```bash
-npm install @aelionsdk/render-ir@next
+npm install @aelionsdk/render-ir
 ```
 
-`next` currently resolves to `1.2.0-rc.5`. Product applications should use
+`latest` currently resolves to `2.0.0`. Product applications should use
 `@aelionsdk/sdk`; direct use is for custom renderers, exporters and engine
 instrumentation.
 

package/dist/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,aAAa,EAAmB,MAAM,2BAA2B,CAAC;AAGpG,OAAO,KAAK,EAaV,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAscpB,qBAAa,yBAAyB;;IAIpC;;;;OAIG;IACI,IAAI,IAAI,yBAAyB;IAMxC,4EAA4E;IACrE,KAAK,IAAI,IAAI;IAOb,OAAO,CACZ,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,uBAAuB,GACnB,oBAAoB,GACpB,mBAAmB,CAAC,OAAO,CAAC,CAAC,gBAAgB,CAAM,GACtD,mBAAmB;CAwOvB"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAqC,MAAM,2BAA2B,CAAC;AAGlG,OAAO,KAAK,EAaV,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAkgBpB,qBAAa,yBAAyB;;IAcpC;;;;OAIG;IACI,IAAI,IAAI,yBAAyB;IAcxC,4EAA4E;IACrE,KAAK,IAAI,IAAI;IAOb,OAAO,CACZ,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,uBAAuB,GACnB,oBAAoB,GACpB,mBAAmB,CAAC,OAAO,CAAC,CAAC,gBAAgB,CAAM,GACtD,mBAAmB;CAyOvB"}

package/dist/compiler.js

@@ -1,15 +1,59 @@
-import { canonicalStringify } from '@aelionsdk/project-schema';
+import {} from '@aelionsdk/project-schema';
+/**
+ * Objects `deepFreezePlain` has already frozen, along with everything beneath
+ * them.
+ *
+ * An incremental compile reuses most of the previous IR verbatim, and those
+ * objects were deep-frozen by the compile that produced them. Re-walking them
+ * dominated incremental compile time -- roughly three quarters of a no-op
+ * compile at a thousand clips. Membership means the whole subtree is already
+ * frozen, so the walk can stop at the first reused node.
+ *
+ * Entries are held weakly, so a released IR is still collectable.
+ */
+const deepFrozen = new WeakSet();
+/** Item types the Render IR can compile, as a set so the check is one lookup. */
+const COMPILABLE_ITEM_TYPES = new Set([
+    'video',
+    'image',
+    'audio',
+    'text',
+    'caption',
+    'nested-sequence',
+    'generator',
+    'shape',
+    'material-content',
+    'adjustment',
+    // Compiles to no clip at all; see the Gap branch in the Track loop below.
+    'gap',
+]);
 function deepFreezePlain(value, seen = new WeakSet()) {
     if (value === null || typeof value !== 'object')
         return value;
-    if (seen.has(value))
+    if (deepFrozen.has(value))
         return value;
-    const prototype = Object.getPrototypeOf(value);
-    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+    if (seen.has(value))
         return value;
-    seen.add(value);
-    for (const entry of Object.values(value))
-        deepFreezePlain(entry, seen);
+    if (Array.isArray(value)) {
+        seen.add(value);
+        for (const entry of value)
+            deepFreezePlain(entry, seen);
+    }
+    else {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return value;
+        seen.add(value);
+        // `for...in` over a plain object walks V8's enumeration cache without
+        // materializing a key or value array for every node in the IR, which at a
+        // thousand clips is tens of thousands of throwaway arrays per compile.
+        for (const key in value) {
+            deepFreezePlain(value[key], seen);
+        }
+    }
+    // Recorded only after the whole subtree is frozen, so membership never
+    // promises more than has actually been done.
+    deepFrozen.add(value);
     return Object.freeze(value);
 }
 function object(value, context) {
@@ -185,22 +229,37 @@ function nestedSequenceSource(item) {
         boundary: boundary,
     };
 }
+/**
+ * Serializes a value for fingerprint comparison.
+ *
+ * A fingerprint is only ever compared against the fingerprint the previous
+ * compile recorded for the same entity, so it needs one property: two entities
+ * that differ must serialize differently. Canonical ordering buys the stronger
+ * property that two *equal* entities always agree even if their keys were
+ * written in a different order -- which here would at worst cause a recompile
+ * that produces the same clip, and costs a hand-written walk over every value
+ * in the Sequence to avoid. `JSON.stringify` is exact for the plain JSON an
+ * admitted Project contains, and the engine runs it natively.
+ */
+function fingerprintOf(value) {
+    return JSON.stringify(value);
+}
 function clipFingerprint(item, materials, assets) {
     const source = object(item.source ?? {}, `item ${item.id}.source`);
     const sourceAssetId = typeof source.assetId === 'string' ? source.assetId : undefined;
     const sourceAsset = sourceAssetId === undefined ? undefined : assets[sourceAssetId];
     return [
-        canonicalStringify(item),
+        fingerprintOf(item),
         ...(sourceAsset?.kind === 'image-sequence'
-            ? [canonicalStringify(sourceAsset.imageSequence ?? null)]
+            ? [fingerprintOf(sourceAsset.imageSequence ?? null)]
             : []),
         ...item.materialInstanceIds.map(id => materialFingerprint(materials[id])),
     ].join('|');
 }
 function materialFingerprint(instance) {
     if (instance === undefined)
-        return canonicalStringify(null);
-    return canonicalStringify({
+        return 'null';
+    return fingerprintOf({
         id: instance.id,
         definition: {
             packageId: instance.definition.packageId,
@@ -416,6 +475,16 @@ function contentDuration(project, trackIds) {
 export class IncrementalRenderCompiler {
     #previous;
     #compiling = false;
+    /**
+     * Track fingerprints keyed by the source track object.
+     *
+     * A track fingerprint serializes the whole Track, and a Track carries every
+     * item id on it, so recomputing it for a thousand-clip track dominated the cost
+     * of an incremental compile even when nothing on that track changed. Commits
+     * share structure: editing one item leaves every untouched track at the same
+     * object identity, so identity is a sound key and an edited track simply misses.
+     */
+    #trackFingerprints = new WeakMap();
     /**
      * Creates an isolated compiler that reuses this compiler's immutable baseline.
      * Compiling on the fork cannot advance or corrupt the parent baseline; a host
@@ -426,6 +495,14 @@ export class IncrementalRenderCompiler {
         fork.#previous = this.#previous;
         return fork;
     }
+    #trackFingerprint(track) {
+        const cached = this.#trackFingerprints.get(track);
+        if (cached !== undefined)
+            return cached;
+        const fingerprint = fingerprintOf(track);
+        this.#trackFingerprints.set(track, fingerprint);
+        return fingerprint;
+    }
     /** Releases the incremental baseline retained for clip/transition reuse. */
     clear() {
         if (this.#compiling) {
@@ -465,36 +542,40 @@ export class IncrementalRenderCompiler {
                 const track = project.tracks[trackId];
                 if (track === undefined)
                     throw new RangeError(`Track ${trackId} does not exist`);
-                const clips = track.itemIds.flatMap(itemId => {
+                // A plain loop rather than `flatMap`: the reuse path runs once per item on
+                // every commit, and wrapping each result in a throwaway single-element array
+                // was the largest remaining cost of an incremental compile.
+                const clips = [];
+                for (const itemId of track.itemIds) {
                     const item = project.items[itemId];
                     if (item === undefined)
                         throw new RangeError(`Item ${itemId} does not exist`);
-                    if (item.type !== 'video' &&
-                        item.type !== 'image' &&
-                        item.type !== 'audio' &&
-                        item.type !== 'text' &&
-                        item.type !== 'caption' &&
-                        item.type !== 'nested-sequence' &&
-                        item.type !== 'generator' &&
-                        item.type !== 'shape' &&
-                        item.type !== 'material-content' &&
-                        item.type !== 'adjustment')
+                    if (!COMPILABLE_ITEM_TYPES.has(item.type)) {
                         throw new TypeError(`Render IR cannot compile item type ${item.type}`);
+                    }
+                    // A Gap is time and nothing else. It still lengthens the Sequence,
+                    // because `contentDuration` reads the Project rather than the clip
+                    // list, but it produces no clip for the renderer or the mixer to
+                    // consider.
+                    if (item.type === 'gap')
+                        continue;
                     const previous = previousClips.get(itemId);
                     if (canReuseByEntity &&
                         previous !== undefined &&
                         !previous.dependencyEntityIds.some(id => affectedEntityIds.has(id))) {
                         reusedClips += 1;
-                        return [previous];
+                        clips.push(previous);
+                        continue;
                     }
                     const candidate = compileClip(item, materials, project.assets);
                     if (previous?.fingerprint === candidate.fingerprint) {
                         reusedClips += 1;
-                        return [previous];
+                        clips.push(previous);
+                        continue;
                     }
                     compiledClips += 1;
-                    return [candidate];
-                });
+                    clips.push(candidate);
+                }
                 return {
                     id: track.id,
                     kind: track.kind,
@@ -506,7 +587,7 @@ export class IncrementalRenderCompiler {
                         : {}),
                     clips,
                     materialInstanceIds: [...track.materialInstanceIds],
-                    fingerprint: canonicalStringify(track),
+                    fingerprint: this.#trackFingerprint(track),
                 };
             });
             const transitions = sequence.transitionIds.map(id => {
@@ -529,7 +610,7 @@ export class IncrementalRenderCompiler {
                     materialInstanceId: value.materialInstanceId,
                     dependencyEntityIds: [id, value.fromItemId, value.toItemId, value.materialInstanceId],
                     fingerprint: [
-                        canonicalStringify(value),
+                        fingerprintOf(value),
                         materialFingerprint(materials[value.materialInstanceId]),
                     ].join('|'),
                 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aelionsdk/render-ir",
-  "version": "1.2.0-rc.5",
+  "version": "2.0.0",
   "description": "Incremental render intermediate representation compiler for AelionSDK",
   "license": "MIT",
   "repository": {
@@ -34,9 +34,9 @@
     "provenance": true
   },
   "dependencies": {
-    "@aelionsdk/core": "1.2.0-rc.5",
-    "@aelionsdk/material-compiler": "1.2.0-rc.5",
-    "@aelionsdk/project-schema": "1.2.0-rc.5"
+    "@aelionsdk/core": "2.0.0",
+    "@aelionsdk/material-compiler": "2.0.0",
+    "@aelionsdk/project-schema": "2.0.0"
   },
   "scripts": {
     "build": "tsc -b",