Free a redrawn picture only once no shader names it (#293)

Editing a vector drawing made Pixi warn "destroyed while still bound
to a shader", twice with every change, once it had begun. It began
where an object wears the drawing through a shader asset. Each
change draws the picture anew and destroyed the one before it, but
the mesh of that object keeps its picture bound until it syncs. The
issue also asks for the button "Add shape" to go: a shape without
points cannot be given any, the Pen draws a new one.

- GeneratedPictures takes two more callbacks. inUse says that a
  picture cannot be freed yet, soon runs a retry once whoever asked
  is done.
- A replaced picture that is still in use waits in a list of its
  own. It is freed right after the redraw that asked, as a rule. On
  a later ask where its wearer was not part of that redraw.
- TextureLibrary tells a bound picture by the listeners for change
  on its source. Under WebGL the bind groups are the only ones that
  listen there. The retry is a microtask.
- The rule is asked for every drawn picture alike, whoever wears it.
- The inspector of a drawing and of a shape has no "Add shape" any
  more. "Delete shapes" for several selected shapes stays.

Decided here:

- Under the list of shapes a second note says "The Pen draws a new
  shape." while only the asset is selected.

Found on the way:

- Reproduced on a throwaway copy of the project the report came
  from: 6 warnings for 3 changes with the shader override on the
  object, none without it. After the change none, and no replaced
  picture is left waiting.
- The fixture project of the tests never showed the warning. No
  object there wore a drawing through a shader.

Tests:
- Gate on melektaus-atx: 211 files, 3219 tests (3209 + 10), exit 0
- e2e 47,48 on melektaus-atx: 113 checks, all pass
- e2e 28,30,31,39,40,47,48: 350 checks, all pass, run before the
  wording of the new note changed
- The first gate was red: an existing test read the wording of the
  note that had changed. Only three test files had been run after
  the change.
- No full run and no smokes. The sum of 1668 (1667 + 1) is reckoned,
  1667 is what CI counted for ec2fd90.
- Ten unit tests, five of them against the real bind group of Pixi
  in tests/viewport/bound-pictures.test.ts
- One e2e check in block 47b-ii of module 47: a drawing worn through
  a shader, three changes, no warning. The check on "Add shape" now
  reads that there is no such button.
- Nine unit counter-probes and two browser counter-probes all fail
  their tests. Without the change the new check counts 6 warnings.
- Not checked: a tilemap or a particle emitter holding a picture
  bound the same way. Nothing was looked at after the build, the
  new note included.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/editor/shape-rows.test.ts

@@ -212,7 +212,9 @@ describe('shape rows', () => {
     buildShapeListSection(host, findAssetOf(host.state.project, assetId, 'vectorart')!);
     // The list carries its "SHAPES" header itself.
     expect(currentShapeList()?.shownIds).toHaveLength(2);
+    // The way to add is the Pen, said in the note: there is no button for it (#293).
     expect(texts(host)).toContain('The top row is drawn over the ones below it.');
+    expect(texts(host)).toContain('The Pen draws a new shape.');
   });
 
   it('an empty drawing says so instead of showing an empty list', () => {

tests/editor/vector-layers.test.ts

@@ -188,15 +188,18 @@ describe('the lists of the inspector', () => {
     expect(r.state.selection).toEqual({ kind: 'asset', assetId: r.asset.id });
   });
 
-  it('puts a shape added from the inspector onto the layer worked on', () => {
+  it('offers no button that adds a shape: the Pen draws one (#293)', () => {
     const r = rig();
-    const base = r.asset.layers[0]!.id;
-    r.addLayer();
-    pickVectorLayer(r.state, r.asset.id, base);
     r.build();
-    r.button('Add shape').onClick!();
-    expect(r.asset.layers[0]!.items).toHaveLength(4);
-    expect(r.asset.layers[1]!.items).toHaveLength(0);
+    expect(r.button('Add shape')).toBeUndefined();
+    expect(r.texts().some((line) => line.includes('The Pen draws a new shape'))).toBe(true);
+    r.state.select(shapeSelection(r.asset.id, ['a']));
+    r.build();
+    expect(r.button('Add shape')).toBeUndefined();
+    // Several shapes still go at once from here.
+    r.state.select(shapeSelection(r.asset.id, ['a', 'b']));
+    r.build();
+    expect(r.button('Delete shapes')).toBeDefined();
   });
 });
 

tests/viewport/bound-pictures.test.ts

@@ -0,0 +1,108 @@
+import { BindGroup, Texture, TextureSource } from 'pixi.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { TextureLibrary } from '../../src/viewport/TextureLibrary';
+
+/**
+ * #293: Pixi warned "[BindGroup] a 'textureSource' was destroyed while still bound to a shader"
+ * with every change to a drawing that an object wore through a shader asset. The mesh's shader
+ * names the picture until its next sync, and the library destroyed the old revision the moment it
+ * drew the new one – which is before any wearer can have heard of it.
+ *
+ * Measured with Pixi's own bind group, which is what a shader keeps its resources in.
+ */
+function rig() {
+  const library = new TextureLibrary();
+  const drawn: Texture[] = [];
+  library.setPictureFactory(() => {
+    const texture = new Texture({ source: new TextureSource({ width: 4, height: 4 }) });
+    drawn.push(texture);
+    return texture;
+  });
+  const warned = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  const warnings = () =>
+    warned.mock.calls.map((call) => call.join(' ')).filter((line) => line.includes('BindGroup'));
+  /** What a shader does with a picture it wears. */
+  const bind = (group: BindGroup, texture: Texture): void => {
+    group.setResource(texture.source, 0);
+    group.setResource(texture.source.style, 1);
+  };
+  return { library, drawn, warnings, bind };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('a drawn picture a shader still names (#293)', () => {
+  it('is told by the bind group listening on its source', () => {
+    const r = rig();
+    const picture = r.library.load('gen:a@1')!;
+    expect(picture.source.listenerCount('change')).toBe(0);
+    const group = new BindGroup({ 0: picture.source, 1: picture.source.style });
+    expect(picture.source.listenerCount('change')).toBe(1);
+    r.bind(group, Texture.WHITE);
+    expect(picture.source.listenerCount('change')).toBe(0);
+  });
+
+  it('is not destroyed under the shader when its drawing changes, and nothing is warned', () => {
+    const r = rig();
+    const first = r.library.load('gen:a@1')!;
+    const shader = new BindGroup({ 0: first.source, 1: first.source.style });
+
+    const second = r.library.load('gen:a@2')!;
+    expect(second).not.toBe(first);
+    expect(first.destroyed).toBe(false);
+    expect(first.source.destroyed).toBe(false);
+    expect(r.library.waitingPictures()).toEqual(['gen:a@1']);
+    // It is no longer what the library hands out.
+    expect(r.library.peek('gen:a@1')).toBeNull();
+    expect(r.warnings()).toEqual([]);
+
+    // The mesh syncs: its shader takes the new picture. The next ask frees the old one.
+    r.bind(shader, second);
+    expect(r.library.load('gen:a@2')).toBe(second);
+    expect(first.destroyed).toBe(true);
+    expect(r.library.waitingPictures()).toEqual([]);
+    expect(second.destroyed).toBe(false);
+    expect(r.warnings()).toEqual([]);
+  });
+
+  it('is freed right after the redraw in which the shader took the new picture', async () => {
+    const r = rig();
+    const first = r.library.load('gen:a@1')!;
+    const shader = new BindGroup({ 0: first.source, 1: first.source.style });
+    // One redraw: the mesh asks for its picture and hands it to its shader.
+    r.bind(shader, r.library.load('gen:a@2')!);
+    expect(first.destroyed).toBe(false);
+    await Promise.resolve();
+    expect(first.destroyed).toBe(true);
+    expect(r.library.waitingPictures()).toEqual([]);
+    expect(r.warnings()).toEqual([]);
+  });
+
+  it('stays through any number of changes while the shader does not sync, and only that one', () => {
+    const r = rig();
+    const first = r.library.load('gen:a@1')!;
+    const shader = new BindGroup({ 0: first.source, 1: first.source.style });
+    // The scene is not on screen: nobody syncs, the drawing is edited three times.
+    r.library.load('gen:a@2');
+    r.library.load('gen:a@3');
+    r.library.load('gen:a@4');
+    expect(r.drawn.map((texture) => texture.destroyed)).toEqual([false, true, true, false]);
+    expect(r.library.waitingPictures()).toEqual(['gen:a@1']);
+    expect(r.warnings()).toEqual([]);
+    shader.destroy();
+    r.library.load('gen:a@4');
+    expect(first.destroyed).toBe(true);
+    expect(r.warnings()).toEqual([]);
+  });
+
+  it('is destroyed right away when no shader names it', () => {
+    const r = rig();
+    const first = r.library.load('gen:a@1')!;
+    r.library.load('gen:a@2');
+    expect(first.destroyed).toBe(true);
+    expect(r.library.waitingPictures()).toEqual([]);
+    expect(r.warnings()).toEqual([]);
+  });
+});

tests/viewport/generated-pictures.test.ts

@@ -82,6 +82,113 @@ describe('generated pictures kept in memory', () => {
     expect(f.pictures.get('gen:a@1')).toBeNull();
   });
 
+  describe('a picture something still draws with (#293)', () => {
+    /** Like `library`, with pictures that can be held on to. */
+    function held() {
+      const freed: string[] = [];
+      const busy = new Set<string>();
+      const pictures = new GeneratedPictures<string>(
+        (picture, key) => freed.push(`${picture} ${key}`),
+        (picture) => busy.has(picture),
+      );
+      let revision = 0;
+      pictures.setFactory((assetId) => `${assetId}${++revision}`);
+      return { pictures, freed, busy };
+    }
+
+    it('keeps the old revision while it is in use and frees it on the next ask after', () => {
+      const f = held();
+      f.pictures.get('gen:a@1');
+      f.busy.add('a1');
+      expect(f.pictures.get('gen:a@2')).toBe('a2');
+      // Gone from what is handed out, but not freed.
+      expect(f.pictures.keys()).toEqual(['gen:a@2']);
+      expect(f.pictures.peek('gen:a@1')).toBeNull();
+      expect(f.freed).toEqual([]);
+      expect(f.pictures.waitingKeys()).toEqual(['gen:a@1']);
+      // Still held: asking again changes nothing.
+      f.pictures.get('gen:a@2');
+      expect(f.freed).toEqual([]);
+      // Let go: any ask frees it, also one for a picture that is already there.
+      f.busy.delete('a1');
+      f.pictures.get('gen:a@2');
+      expect(f.freed).toEqual(['a1 gen:a@1']);
+      expect(f.pictures.waitingKeys()).toEqual([]);
+      // And only once.
+      f.pictures.get('gen:a@2');
+      f.pictures.get('gen:a@3');
+      expect(f.freed).toEqual(['a1 gen:a@1', 'a2 gen:a@2']);
+    });
+
+    it('frees what waits in the order it was replaced, and leaves the one still held', () => {
+      const f = held();
+      f.pictures.get('gen:a@1');
+      f.busy.add('a1');
+      f.pictures.get('gen:a@2');
+      f.busy.add('a2');
+      f.pictures.get('gen:a@3');
+      expect(f.pictures.waitingKeys()).toEqual(['gen:a@1', 'gen:a@2']);
+      f.busy.delete('a2');
+      f.pictures.get('gen:a@3');
+      expect(f.freed).toEqual(['a2 gen:a@2']);
+      expect(f.pictures.waitingKeys()).toEqual(['gen:a@1']);
+    });
+
+    it('frees a picture nobody holds right away', () => {
+      const f = held();
+      f.pictures.get('gen:a@1');
+      f.pictures.get('gen:a@2');
+      expect(f.freed).toEqual(['a1 gen:a@1']);
+      expect(f.pictures.waitingKeys()).toEqual([]);
+    });
+
+    it('retries once whoever asked is done, and asks for that only once per wait', () => {
+      const freed: string[] = [];
+      const busy = new Set<string>();
+      const later: (() => void)[] = [];
+      const pictures = new GeneratedPictures<string>(
+        (picture) => freed.push(picture),
+        (picture) => busy.has(picture),
+        (retry) => later.push(retry),
+      );
+      let revision = 0;
+      pictures.setFactory((assetId) => `${assetId}${++revision}`);
+      pictures.get('gen:a@1');
+      pictures.get('gen:b@1');
+      busy.add('a1').add('b2');
+      pictures.get('gen:a@2');
+      pictures.get('gen:b@2');
+      expect(later).toHaveLength(1);
+      // The wearer of a took the new picture during the redraw, the one of b did not.
+      busy.delete('a1');
+      later.shift()!();
+      expect(freed).toEqual(['a1']);
+      expect(pictures.waitingKeys()).toEqual(['gen:b@1']);
+      // What still waits is not retried on a timer: the next ask does that.
+      expect(later).toHaveLength(0);
+      busy.delete('b2');
+      pictures.get('gen:b@2');
+      expect(freed).toEqual(['a1', 'b2']);
+      // A new wait asks for a retry again.
+      busy.add('a3');
+      pictures.get('gen:a@3');
+      expect(later).toHaveLength(1);
+    });
+
+    it('lets a held picture wait through a change of session too', () => {
+      const f = held();
+      f.pictures.get('gen:a@1');
+      f.pictures.get('gen:b@1');
+      f.busy.add('a1');
+      f.pictures.setFactory((assetId) => `${assetId}-next`);
+      expect(f.freed).toEqual(['b2 gen:b@1']);
+      expect(f.pictures.keys()).toEqual([]);
+      f.busy.delete('a1');
+      expect(f.pictures.get('gen:c@1')).toBe('c-next');
+      expect(f.freed).toEqual(['b2 gen:b@1', 'a1 gen:a@1']);
+    });
+  });
+
   it('answers peek only with what has been drawn', () => {
     const f = library();
     expect(f.pictures.peek('gen:a@1')).toBeNull();