@instruments/materialgraph 0.9.0 → 0.9.1

package/match-stream-types.d.ts

@@ -26,8 +26,16 @@ export type MatchMaterialFunction = (typeof MATCH_MATERIAL_FUNCTIONS)[number];
 /** The workflow's coarse progress phase, narrated by a `step` event. */
 export declare const MATCH_WORKFLOW_STEPS: readonly ["classifying", "decomposing", "matching", "complete"];
 export type MatchWorkflowStep = (typeof MATCH_WORKFLOW_STEPS)[number];
-/** Where one surface stands in the run. */
-export declare const MATCH_SURFACE_STATUSES: readonly ["pending", "matching", "complete", "error"];
+/**
+ * Where one surface stands in the run.
+ *
+ * `colour_fallback` (appended, additive): the surface completed, but through
+ * the colour lane — its visible sample was too small to read texture, so the
+ * results match the region's palette, scoped to the detected category. Such a
+ * surface carries a `note` saying so and no `senseCheck` verdicts (there is no
+ * texture to verify).
+ */
+export declare const MATCH_SURFACE_STATUSES: readonly ["pending", "matching", "complete", "error", "colour_fallback"];
 export type MatchSurfaceStatus = (typeof MATCH_SURFACE_STATUSES)[number];
 /** Every frame type the stream can carry — the union's discriminant values. */
 export declare const MATCH_STREAM_EVENT_TYPES: readonly ["step", "classified", "surfaces", "surface", "heartbeat", "complete", "error"];
@@ -112,9 +120,10 @@ export interface MatchSurfaceResult {
     senseCheck?: MatchSenseCheckCell[];
     /**
      * TRUE on the interim frame that delivers finished results while the verifier
-     * is still reading them. The verifier annotates; it never filters and never
-     * reorders, so this says "badges are coming", never "these results may
-     * change". Render the rows immediately.
+     * is still reading them. Render the rows immediately. The follow-up frame
+     * carries the SAME rows with verdicts attached, settled once into verdict
+     * bands (confirmed → abstained → rejected, stable within each band) — the
+     * page's one settling reorder. Nothing is ever removed.
      */
     senseCheckPending?: boolean;
     /**
@@ -128,6 +137,12 @@ export interface MatchSurfaceResult {
         hex: string;
         proportion: number;
     }>;
+    /**
+     * One sentence of provenance a consumer may render verbatim, when the server
+     * sent one — e.g. the `colour_fallback` explanation carrying the refused
+     * sample's pixel size. Absent on ordinary surfaces.
+     */
+    note?: string;
     /** Present only on `status: "error"` — why this one surface failed. */
     error?: string;
 }
@@ -161,6 +176,21 @@ export interface MatchWorkflowResult {
      * "nothing above the floor". Do not fold `surfaces[]` to tell those apart.
      */
     totals: MatchRunTotals;
+    /**
+     * Whole-image palette matches, sent ONLY when an installation photo yielded
+     * no usable surfaces at all. These match the image's overall palette — they
+     * are not material identifications, and the note says so. A consumer that
+     * ignores this field sees exactly the empty run it saw before the field
+     * existed.
+     */
+    paletteMatches?: {
+        results: SearchResultItem[];
+        palette: Array<{
+            hex: string;
+            proportion: number;
+        }>;
+        note: string;
+    };
     /**
      * What a SWATCH run compared against — a swatch detects no surfaces, so it has
      * nowhere else to put this. A scene run reports per surface instead.

package/match-stream-types.js

@@ -14,8 +14,22 @@ export const MATCH_MATERIAL_FUNCTIONS = [
 ];
 /** The workflow's coarse progress phase, narrated by a `step` event. */
 export const MATCH_WORKFLOW_STEPS = ["classifying", "decomposing", "matching", "complete"];
-/** Where one surface stands in the run. */
-export const MATCH_SURFACE_STATUSES = ["pending", "matching", "complete", "error"];
+/**
+ * Where one surface stands in the run.
+ *
+ * `colour_fallback` (appended, additive): the surface completed, but through
+ * the colour lane — its visible sample was too small to read texture, so the
+ * results match the region's palette, scoped to the detected category. Such a
+ * surface carries a `note` saying so and no `senseCheck` verdicts (there is no
+ * texture to verify).
+ */
+export const MATCH_SURFACE_STATUSES = [
+    "pending",
+    "matching",
+    "complete",
+    "error",
+    "colour_fallback",
+];
 /** Every frame type the stream can carry — the union's discriminant values. */
 export const MATCH_STREAM_EVENT_TYPES = [
     "step",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "exports": {
     ".": {