@flighthq/render 0.3.1-next.509.c235802 → 0.3.1-next.616.aa7ae7f

package/dist/explainScene2DCoverage.d.ts

@@ -1,4 +1,4 @@
-import type { RenderState, Scene2DKindUsage, SceneCoverageEntry } from '@flighthq/types/contract';
-export declare function explainScene2DCoverage(out: SceneCoverageEntry[], state: RenderState, usage: Readonly<Scene2DKindUsage>): void;
+import type { RenderState, Scene2DKindUsage, SceneCoverageCatalog, SceneCoverageEntry } from '@flighthq/types/contract';
+export declare function explainScene2DCoverage(out: SceneCoverageEntry[], state: RenderState, usage: Readonly<Scene2DKindUsage>, catalog: SceneCoverageCatalog): void;
 export declare function hasScene2DCoverage(state: RenderState, usage: Readonly<Scene2DKindUsage>): boolean;
 //# sourceMappingURL=explainScene2DCoverage.d.ts.map

package/dist/explainScene2DCoverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explainScene2DCoverage.d.ts","sourceRoot":"","sources":["../src/explainScene2DCoverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAelG,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,kBAAkB,EAAE,EACzB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAChC,IAAI,CAGN;AAID,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,OAAO,CAEjG"}
+{"version":3,"file":"explainScene2DCoverage.d.ts","sourceRoot":"","sources":["../src/explainScene2DCoverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAiBlC,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,kBAAkB,EAAE,EACzB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EACjC,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAGN;AAID,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,OAAO,CAEjG"}

package/dist/explainScene2DCoverage.js

@@ -1,4 +1,4 @@
-import { RenderRegistry, SceneCoverage } from '@flighthq/types/contract';
+import { RenderRegistry, RequirementFacet, SceneCoverage } from '@flighthq/types/contract';
 import { getRenderStateRuntime } from './renderState';
 // Clears `out`, then reports every requirement in `usage` that any 2D backend answers the same way,
 // with how well this state is wired for it — satisfied entries included, so one call is a manifest.
@@ -10,18 +10,20 @@ import { getRenderStateRuntime } from './renderState';
 //
 // Unlike the 3D seam, node kinds ARE a requirement here: the 2D pipeline resolves every node through
 // `registerRenderer(state, kind, renderer)`, where the 3D pipeline collects meshes structurally.
-export function explainScene2DCoverage(out, state, usage) {
+// `catalog` is the caller's complete backend inventory; an unserved requirement uses its first ordered
+// registration as the primary remedy, while a satisfied requirement needs no catalog lookup.
+export function explainScene2DCoverage(out, state, usage, catalog) {
     out.length = 0;
-    collectScene2DCoverageGaps(out, state, usage, false);
+    collectScene2DCoverageGaps(out, state, usage, false, catalog);
 }
 // Whether this state can serve every node kind and shape command `usage` names. Stops at the first
 // shortfall and never allocates. Use the explain form to find out WHICH requirement and how badly.
 export function hasScene2DCoverage(state, usage) {
-    return !collectScene2DCoverageGaps(null, state, usage, true);
+    return !collectScene2DCoverageGaps(null, state, usage, true, null);
 }
 // The single implementation both tiers read, so the boolean can never disagree with the explanation.
 // `found` counts only real shortfalls, so appending satisfied entries to `out` never flips the predicate.
-function collectScene2DCoverageGaps(out, state, usage, stopAtFirst) {
+function collectScene2DCoverageGaps(out, state, usage, stopAtFirst, catalog) {
     let found = false;
     const runtime = getRenderStateRuntime(state);
     // A node kind with no renderer produces no render proxy, so the node and its whole subtree are
@@ -29,13 +31,18 @@ function collectScene2DCoverageGaps(out, state, usage, stopAtFirst) {
     for (let i = 0; i < usage.nodeKinds.length; i++) {
         const kind = usage.nodeKinds[i];
         if (runtime.rendererMap.has(kind)) {
-            out?.push({ coverage: SceneCoverage.Satisfied, kind, registry: RenderRegistry.NodeRenderer });
+            out?.push({
+                coverage: SceneCoverage.Satisfied,
+                facet: RequirementFacet.SceneNodeKind,
+                kind,
+                registry: RenderRegistry.NodeRenderer,
+            });
             continue;
         }
         found = true;
         if (stopAtFirst)
             return true;
-        out?.push({ coverage: SceneCoverage.Missing, kind, registry: RenderRegistry.NodeRenderer });
+        out?.push(createShortfallEntry(catalog, false, RequirementFacet.SceneNodeKind, kind, RenderRegistry.NodeRenderer));
     }
     // Only meaningful for a state that rasterizes shapes. A GL or WebGPU state drawing every shape
     // through the mesh path never replays a command, so these entries are reported and simply not acted
@@ -44,14 +51,45 @@ function collectScene2DCoverageGaps(out, state, usage, stopAtFirst) {
     for (let i = 0; i < usage.shapeCommandKeys.length; i++) {
         const kind = usage.shapeCommandKeys[i];
         if (commands?.has(kind) === true) {
-            out?.push({ coverage: SceneCoverage.Satisfied, kind, registry: RenderRegistry.ShapeCommandHandler });
+            out?.push({
+                coverage: SceneCoverage.Satisfied,
+                facet: RequirementFacet.SceneShapeCommand,
+                kind,
+                registry: RenderRegistry.ShapeCommandHandler,
+            });
             continue;
         }
         found = true;
         if (stopAtFirst)
             return true;
-        out?.push({ coverage: SceneCoverage.Missing, kind, registry: RenderRegistry.ShapeCommandHandler });
+        out?.push(createShortfallEntry(catalog, false, RequirementFacet.SceneShapeCommand, kind, RenderRegistry.ShapeCommandHandler));
     }
     return found;
 }
+function createShortfallEntry(catalog, fallback, facet, kind, registry) {
+    const registration = findCatalogRegistration(catalog, kind, registry);
+    const base = { facet, kind, registry };
+    if (registration === null) {
+        return {
+            ...base,
+            coverage: fallback ? SceneCoverage.FallbackUnavailable : SceneCoverage.Unavailable,
+        };
+    }
+    return {
+        ...base,
+        coverage: fallback ? SceneCoverage.FallbackRemediable : SceneCoverage.Unregistered,
+        module: registration.module,
+        registrar: registration.registrar,
+    };
+}
+// Package-private and row-agnostic: generated, probed, and fixture catalogs all feed the same seam.
+function findCatalogRegistration(catalog, kind, registry) {
+    if (catalog === null)
+        return null;
+    for (const entry of catalog) {
+        if (entry.kind === kind && entry.registry === registry)
+            return entry.registrations[0] ?? null;
+    }
+    return null;
+}
 //# sourceMappingURL=explainScene2DCoverage.js.map

package/dist/explainScene2DCoverage.js.map

@@ -1 +1 @@
-{"version":3,"file":"explainScene2DCoverage.js","sourceRoot":"","sources":["../src/explainScene2DCoverage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,oGAAoG;AACpG,oGAAoG;AACpG,EAAE;AACF,uGAAuG;AACvG,uGAAuG;AACvG,sGAAsG;AACtG,iGAAiG;AACjG,EAAE;AACF,qGAAqG;AACrG,iGAAiG;AACjG,MAAM,UAAU,sBAAsB,CACpC,GAAyB,EACzB,KAAkB,EAClB,KAAiC;IAEjC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACf,0BAA0B,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,mGAAmG;AACnG,mGAAmG;AACnG,MAAM,UAAU,kBAAkB,CAAC,KAAkB,EAAE,KAAiC;IACtF,OAAO,CAAC,0BAA0B,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,qGAAqG;AACrG,0GAA0G;AAC1G,SAAS,0BAA0B,CACjC,GAAgC,EAChC,KAAkB,EAClB,KAAiC,EACjC,WAAoB;IAEpB,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,MAAM,OAAO,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAE7C,+FAA+F;IAC/F,iGAAiG;IACjG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAChC,IAAI,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,GAAG,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,CAAC,YAAY,EAAE,CAAC,CAAC;YAC9F,SAAS;QACX,CAAC;QACD,KAAK,GAAG,IAAI,CAAC;QACb,IAAI,WAAW;YAAE,OAAO,IAAI,CAAC;QAC7B,GAAG,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,CAAC,YAAY,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,+FAA+F;IAC/F,oGAAoG;IACpG,kFAAkF;IAClF,MAAM,QAAQ,GAAG,OAAO,CAAC,0BAA0B,CAAC;IACpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;QACvC,IAAI,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACjC,GAAG,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,CAAC,mBAAmB,EAAE,CAAC,CAAC;YACrG,SAAS;QACX,CAAC;QACD,KAAK,GAAG,IAAI,CAAC;QACb,IAAI,WAAW;YAAE,OAAO,IAAI,CAAC;QAC7B,GAAG,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,CAAC,mBAAmB,EAAE,CAAC,CAAC;IACrG,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"explainScene2DCoverage.js","sourceRoot":"","sources":["../src/explainScene2DCoverage.ts"],"names":[],"mappings":"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"}

package/dist/renderRegistryGuards.js

@@ -32,9 +32,11 @@ function getRenderRegistryMissMessage(state, registry) {
             return 'computeRenderEffectPadding: effect kind has no registered padding resolver — call registerRenderEffectPaddingResolver(state, kind, resolver)';
         // Reported by the resource layer, not the frame path: a material kind with no lister has its
         // texture slots invisible to anything that walks materials. Discovery no longer depends on this
-        // (it reads the resource back-edge), so the surviving cost is a mesh whose reveal never fires.
+        // (it reads the resource back-edge). On an all-unlisted mesh, reveal-on-resolve leaves the starting
+        // alpha unchanged. On a mixed mesh, it can reveal after the listed textures settle while an unlisted
+        // texture is still pending.
         case RenderRegistry.MaterialTextureLister:
-            return 'a material kind in this scene has no registered texture lister, so a mesh waiting on its maps never reveals — call registerScene3DMaterialTextures(registry, kind, lister), or the named door for that family';
+            return "a material kind in this scene has no registered texture lister, so an all-unlisted mesh gets no fade, while a mixed mesh can reveal before that material's textures settle and show a later texture pop-in — call registerScene3DMaterialTextures(registry, kind, lister), or the named door for that family";
         // Reported only by the GPU backends, where an unresolved material means the node does not draw at
         // all. The Canvas renderer treats a missing material renderer as "draw normally", so the same
         // absence there is the ordinary case rather than a defect.

package/dist/renderRegistryGuards.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/render",
-  "version": "0.3.1-next.509.c235802",
+  "version": "0.3.1-next.616.aa7ae7f",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,16 +38,16 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/adjustments": "0.3.1-next.509.c235802",
-    "@flighthq/color": "0.3.1-next.509.c235802",
-    "@flighthq/entity": "0.3.1-next.509.c235802",
-    "@flighthq/geometry": "0.3.1-next.509.c235802",
-    "@flighthq/log": "0.3.1-next.509.c235802",
-    "@flighthq/materials": "0.3.1-next.509.c235802",
-    "@flighthq/mesh": "0.3.1-next.509.c235802",
-    "@flighthq/node": "0.3.1-next.509.c235802",
-    "@flighthq/signals": "0.3.1-next.509.c235802",
-    "@flighthq/types": "0.3.1-next.509.c235802"
+    "@flighthq/adjustments": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/color": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/entity": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/geometry": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/log": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/materials": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/mesh": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/node": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/signals": "0.3.1-next.616.aa7ae7f",
+    "@flighthq/types": "0.3.1-next.616.aa7ae7f"
   },
   "devDependencies": {
     "@flighthq/camera": "*",

package/src/explainScene2DCoverage.test.ts

@@ -1,5 +1,5 @@
-import type { Renderer, Scene2DKindUsage, SceneCoverageEntry } from '@flighthq/types/contract';
-import { RenderRegistry, SceneCoverage } from '@flighthq/types/contract';
+import type { Renderer, Scene2DKindUsage, SceneCoverageCatalog, SceneCoverageEntry } from '@flighthq/types/contract';
+import { RenderRegistry, RequirementFacet, SceneCoverage } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
 import { explainScene2DCoverage, hasScene2DCoverage } from './explainScene2DCoverage';
@@ -8,14 +8,38 @@ import { createRenderState } from './renderState';
 import { getRenderStateRuntime } from './renderState';
 
 const renderer: Renderer = { createData: () => null, submit: () => {} } as unknown as Renderer;
+const coverageCatalog: SceneCoverageCatalog = [
+  {
+    kind: 'Shape',
+    registrations: [
+      { module: '@flighthq/scene2d', registrar: 'registerShapeRenderer' },
+      { module: '@flighthq/scene2d-canvas', registrar: 'registerCanvasShapeCommands' },
+    ],
+    registry: RenderRegistry.NodeRenderer,
+  },
+  {
+    kind: 'Sprite',
+    registrations: [{ module: '@flighthq/scene2d', registrar: 'registerSpriteRenderer' }],
+    registry: RenderRegistry.NodeRenderer,
+  },
+  {
+    kind: 'beginFill',
+    registrations: [{ module: '@flighthq/scene2d-canvas', registrar: 'registerCanvasShapeCommands' }],
+    registry: RenderRegistry.ShapeCommandHandler,
+  },
+];
 
 function usage(overrides: Partial<Scene2DKindUsage> = {}): Scene2DKindUsage {
   return { blendModes: [], materialKinds: [], nodeKinds: [], shapeCommandKeys: [], ...overrides };
 }
 
-function entries(state: ReturnType<typeof createRenderState>, u: Scene2DKindUsage): SceneCoverageEntry[] {
+function entries(
+  state: ReturnType<typeof createRenderState>,
+  u: Scene2DKindUsage,
+  catalog: SceneCoverageCatalog = coverageCatalog,
+): SceneCoverageEntry[] {
   const out: SceneCoverageEntry[] = [];
-  explainScene2DCoverage(out, state, u);
+  explainScene2DCoverage(out, state, u, catalog);
   return out;
 }
 
@@ -27,9 +51,27 @@ function wireShapeCommand(state: ReturnType<typeof createRenderState>, key: stri
 }
 
 describe('explainScene2DCoverage', () => {
-  it('reports an unregistered node kind as Missing, since the node and its subtree never draw', () => {
+  it('reports an unregistered node kind with the primary catalog remedy', () => {
     expect(entries(createRenderState(), usage({ nodeKinds: ['Shape'] }))).toEqual([
-      { coverage: SceneCoverage.Missing, kind: 'Shape', registry: RenderRegistry.NodeRenderer },
+      {
+        coverage: SceneCoverage.Unregistered,
+        facet: RequirementFacet.SceneNodeKind,
+        kind: 'Shape',
+        module: '@flighthq/scene2d',
+        registrar: 'registerShapeRenderer',
+        registry: RenderRegistry.NodeRenderer,
+      },
+    ]);
+  });
+
+  it('reports an uncatalogued node kind as Unavailable, with no remedy fields', () => {
+    expect(entries(createRenderState(), usage({ nodeKinds: ['Shape'] }), [])).toEqual([
+      {
+        coverage: SceneCoverage.Unavailable,
+        facet: RequirementFacet.SceneNodeKind,
+        kind: 'Shape',
+        registry: RenderRegistry.NodeRenderer,
+      },
     ]);
   });
 
@@ -37,14 +79,22 @@ describe('explainScene2DCoverage', () => {
     const state = createRenderState();
     registerRenderer(state, 'Shape', renderer);
     expect(entries(state, usage({ nodeKinds: ['Shape'] }))).toEqual([
-      { coverage: SceneCoverage.Satisfied, kind: 'Shape', registry: RenderRegistry.NodeRenderer },
+      {
+        coverage: SceneCoverage.Satisfied,
+        facet: RequirementFacet.SceneNodeKind,
+        kind: 'Shape',
+        registry: RenderRegistry.NodeRenderer,
+      },
     ]);
   });
 
   it('reports an unhandled shape command key against the state that would replay it', () => {
     expect(entries(createRenderState(), usage({ shapeCommandKeys: ['beginFill'] }))).toContainEqual({
-      coverage: SceneCoverage.Missing,
+      coverage: SceneCoverage.Unregistered,
+      facet: RequirementFacet.SceneShapeCommand,
       kind: 'beginFill',
+      module: '@flighthq/scene2d-canvas',
+      registrar: 'registerCanvasShapeCommands',
       registry: RenderRegistry.ShapeCommandHandler,
     });
   });
@@ -54,6 +104,7 @@ describe('explainScene2DCoverage', () => {
     wireShapeCommand(state, 'beginFill');
     expect(entries(state, usage({ shapeCommandKeys: ['beginFill'] }))).toContainEqual({
       coverage: SceneCoverage.Satisfied,
+      facet: RequirementFacet.SceneShapeCommand,
       kind: 'beginFill',
       registry: RenderRegistry.ShapeCommandHandler,
     });
@@ -64,7 +115,7 @@ describe('explainScene2DCoverage', () => {
     registerRenderer(state, 'Shape', renderer);
     const found = entries(state, usage({ nodeKinds: ['Shape', 'Sprite'], shapeCommandKeys: ['beginFill'] }));
     expect(found).toHaveLength(3);
-    expect(found.filter((e) => e.coverage === SceneCoverage.Missing).map((e) => e.kind)).toEqual([
+    expect(found.filter((e) => e.coverage !== SceneCoverage.Satisfied).map((e) => e.kind)).toEqual([
       'Sprite',
       'beginFill',
     ]);
@@ -74,9 +125,9 @@ describe('explainScene2DCoverage', () => {
     const state = createRenderState();
     const u = usage({ nodeKinds: ['Shape'] });
     const out: SceneCoverageEntry[] = [];
-    explainScene2DCoverage(out, state, u);
+    explainScene2DCoverage(out, state, u, coverageCatalog);
     const first = out.length;
-    explainScene2DCoverage(out, state, u);
+    explainScene2DCoverage(out, state, u, coverageCatalog);
     expect(out).toHaveLength(first);
   });
 });
@@ -92,7 +143,7 @@ describe('hasScene2DCoverage', () => {
     wireShapeCommand(state, 'beginFill');
     const u = usage({ nodeKinds: ['Shape'], shapeCommandKeys: ['beginFill'] });
     const out: SceneCoverageEntry[] = [];
-    explainScene2DCoverage(out, state, u);
+    explainScene2DCoverage(out, state, u, coverageCatalog);
     expect(out.every((e) => e.coverage === SceneCoverage.Satisfied)).toBe(true);
     expect(hasScene2DCoverage(state, u)).toBe(true);
   });
@@ -102,7 +153,7 @@ describe('hasScene2DCoverage', () => {
     registerRenderer(state, 'Shape', renderer);
     const u = usage({ nodeKinds: ['Shape', 'Sprite'] });
     const out: SceneCoverageEntry[] = [];
-    explainScene2DCoverage(out, state, u);
+    explainScene2DCoverage(out, state, u, coverageCatalog);
     const gaps = out.filter((e) => e.coverage !== SceneCoverage.Satisfied);
     expect(hasScene2DCoverage(state, u)).toBe(gaps.length === 0);
   });