Fix lazy loading Labels method gaps (#61)

Add auto-materialization to Labels methods that access labeledFrames
directly: instances, find(), append(), toDict(), numpy(), negativeFrames.
These methods now call materialize() when in lazy mode, ensuring correct
results instead of silently returning empty/wrong data.

Also fix LazyFrameList iterator to skip null frames instead of stopping
early, read sessions in lazy reader, and add tests for lazy-mode methods.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: talmo

src/model/labels.ts

@@ -85,6 +85,7 @@ export class Labels {
   }
 
   get negativeFrames(): LabeledFrame[] {
+    if (this._lazyFrameList) this.materialize();
     return this.labeledFrames.filter((f) => f.isNegative);
   }
 
@@ -106,10 +107,12 @@ export class Labels {
   }
 
   get instances(): Array<Instance | PredictedInstance> {
+    if (this._lazyFrameList) this.materialize();
     return this.labeledFrames.flatMap((frame) => frame.instances);
   }
 
   find(options: { video?: Video; frameIdx?: number }): LabeledFrame[] {
+    if (this._lazyFrameList) this.materialize();
     return this.labeledFrames.filter((frame) => {
       if (options.video && frame.video !== options.video) {
         return false;
@@ -122,13 +125,15 @@ export class Labels {
   }
 
   append(frame: LabeledFrame): void {
+    if (this._lazyFrameList) this.materialize();
     this.labeledFrames.push(frame);
     if (!this.videos.includes(frame.video)) {
       this.videos.push(frame.video);
     }
   }
 
   toDict(options?: { video?: Video | number; skipEmptyFrames?: boolean }) {
+    if (this._lazyFrameList) this.materialize();
     return toDict(this, options);
   }
 
@@ -153,6 +158,7 @@ export class Labels {
   }
 
   numpy(options?: { video?: Video; returnConfidence?: boolean }): number[][][][] {
+    if (this._lazyFrameList) this.materialize();
     const targetVideo = options?.video ?? this.video;
     const frames = this.labeledFrames.filter((frame) => frame.video.matchesPath(targetVideo, true));
     if (!frames.length) return [];

src/model/lazy.ts

@@ -179,16 +179,17 @@ export class LazyFrameList {
     return result;
   }
 
-  /** Iterator support. */
+  /** Iterator support. Skips null frames instead of stopping early. */
   [Symbol.iterator](): Iterator<LabeledFrame> {
     let index = 0;
     const self = this;
     return {
       next(): IteratorResult<LabeledFrame> {
-        if (index >= self.length) return { done: true, value: undefined };
-        const frame = self.at(index++);
-        if (!frame) return { done: true, value: undefined };
-        return { done: false, value: frame };
+        while (index < self.length) {
+          const frame = self.at(index++);
+          if (frame) return { value: frame, done: false };
+        }
+        return { value: undefined as any, done: true };
       },
     };
   }

tests/lazy.test.ts

@@ -168,3 +168,46 @@ describe("LazyFrameList", () => {
     expect(arr.length).toBe(lazy.length);
   });
 });
+
+describe("Lazy auto-materialization", () => {
+  it("labels.instances in lazy mode returns correct results", async () => {
+    const eager = await loadFixture("typical.slp");
+    const lazy = await loadFixtureLazy("typical.slp");
+    expect(lazy.isLazy).toBe(true);
+    const instances = lazy.instances;
+    expect(instances.length).toBe(eager.instances.length);
+    expect(instances.length).toBeGreaterThan(0);
+  });
+
+  it("labels.find() in lazy mode works correctly", async () => {
+    const eager = await loadFixture("typical.slp");
+    const lazy = await loadFixtureLazy("typical.slp");
+    const video = lazy.videos[0];
+    const eagerResults = eager.find({ video: eager.videos[0] });
+    const lazyResults = lazy.find({ video });
+    expect(lazyResults.length).toBe(eagerResults.length);
+    expect(lazyResults.length).toBeGreaterThan(0);
+  });
+
+  it("labels.negativeFrames in lazy mode works", async () => {
+    const lazy = await loadFixtureLazy("typical.slp");
+    const negFrames = lazy.negativeFrames;
+    expect(Array.isArray(negFrames)).toBe(true);
+  });
+
+  it("auto-materialization sets isLazy to false", async () => {
+    const lazy = await loadFixtureLazy("typical.slp");
+    expect(lazy.isLazy).toBe(true);
+    lazy.instances;
+    expect(lazy.isLazy).toBe(false);
+  });
+
+  it("labels.numpy() in lazy mode returns data", async () => {
+    const eager = await loadFixture("typical.slp");
+    const lazy = await loadFixtureLazy("typical.slp");
+    const eagerNumpy = eager.numpy();
+    const lazyNumpy = lazy.numpy();
+    expect(lazyNumpy.length).toBe(eagerNumpy.length);
+    expect(lazyNumpy.length).toBeGreaterThan(0);
+  });
+});