@instruments/materialgraph 0.9.1 → 0.11.0

package/composition-client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The COMPOSITION lens: the two synchronous scheme surfaces, as thin wrappers
+ * over the shared {@link HttpTransport}. `MaterialGraphClient.varyScheme` and
+ * `.slotPools` delegate here; the contract lives in this file.
+ *
+ * They are two altitudes of the same capability. `varyScheme` re-derives a
+ * scheme MaterialGraph itself composed; `slotPools` hands the ranked candidates
+ * to a composer that is not MaterialGraph, and keeps none of the ownership.
+ */
+import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.js";
+import { HttpTransport } from "./http-transport.js";
+import type { SlotPoolsRequest, SlotPoolsResponse } from "./slot-pool-types.js";
+/**
+ * THE QUESTION: "show me the same brief, decided differently." Re-derives an
+ * option B from a succeeded compose Run along ONE constraint axis. Deterministic
+ * and synchronous — the response IS the hydrated scheme (no Run envelope),
+ * stamped with axis + source provenance whose `notes` are the receipts.
+ * Requires the `mg:read` scope.
+ */
+export declare function varyScheme(transport: HttpTransport, body: VarySchemesRequest, signal?: AbortSignal): Promise<VarySchemesResponse>;
+/**
+ * THE QUESTION: "for each of these slots, what should I be choosing between?"
+ * Up to 24 self-contained tasks in, one ranked and gated candidate pool each
+ * out, correlated by YOUR `taskKey`. Synchronous, uncached and project-free —
+ * no Run, no programme, no state kept on the MaterialGraph side.
+ *
+ * READ THE POOLS, NOT JUST THE CANDIDATES. A task whose search failed comes back
+ * with a `search-failed` shortfall while the rest answer normally; a candidate
+ * with `eligible: false` is LABELLED rather than dropped (read `flags`); and a
+ * criterion that graded `missing` or `not_evaluated` was never a failure.
+ * Requires the `mg:read` scope.
+ */
+export declare function slotPools(transport: HttpTransport, body: SlotPoolsRequest, signal?: AbortSignal): Promise<SlotPoolsResponse>;

package/composition-client.js

@@ -0,0 +1,27 @@
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "show me the same brief, decided differently." Re-derives an
+ * option B from a succeeded compose Run along ONE constraint axis. Deterministic
+ * and synchronous — the response IS the hydrated scheme (no Run envelope),
+ * stamped with axis + source provenance whose `notes` are the receipts.
+ * Requires the `mg:read` scope.
+ */
+export function varyScheme(transport, body, signal) {
+    return transport.requestJson(resolveOperation("vary_schemes"), { body, signal });
+}
+/**
+ * THE QUESTION: "for each of these slots, what should I be choosing between?"
+ * Up to 24 self-contained tasks in, one ranked and gated candidate pool each
+ * out, correlated by YOUR `taskKey`. Synchronous, uncached and project-free —
+ * no Run, no programme, no state kept on the MaterialGraph side.
+ *
+ * READ THE POOLS, NOT JUST THE CANDIDATES. A task whose search failed comes back
+ * with a `search-failed` shortfall while the rest answer normally; a candidate
+ * with `eligible: false` is LABELLED rather than dropped (read `flags`); and a
+ * criterion that graded `missing` or `not_evaluated` was never a failure.
+ * Requires the `mg:read` scope.
+ */
+export function slotPools(transport, body, signal) {
+    return transport.requestJson(resolveOperation("slot_pools"), { body, signal });
+}

package/composition-types.d.ts

@@ -284,6 +284,34 @@ export interface ReviewProgrammeSuspendPayload {
         categorySource?: SlotCategorySource;
         provenance: ProgrammeProvenance;
     }>;
+    /**
+     * Lines this room usually carries that the brief never named.
+     *
+     * Offered, never imposed: a programme that proceeds without them is a legal
+     * answer. `essential` marks the ones whose absence makes the room unbuildable
+     * as specified; `ffe` marks furniture and lighting the catalogue does not
+     * serve yet, carried because a bedroom with no bed on the schedule is a gap
+     * worth seeing coming. Add one with an `add-slot` correction.
+     */
+    unstated?: Array<{
+        spaceId: string;
+        key: string;
+        name: string;
+        element: SlotElement;
+        /**
+         * Absent and `null` both mean the graph has no category for this line, and a
+         * reader must treat them as one answer.
+         *
+         * The distinction does not survive the wire. A `null` set server-side
+         * arrives as an absent key on the far side of the workflow runtime, so a
+         * client that branched on which one it received would be reading transport
+         * noise as meaning. An FF&E line the catalogue does not serve — a table
+         * lamp, bed linen, ironmongery — has no category under either reading.
+         */
+        category?: string | null;
+        weight: "essential" | "optional";
+        ffe?: boolean;
+    }>;
 }
 /**
  * Resume grammar for the `review-programme` step: drop a slot, drop a space
@@ -310,6 +338,24 @@ export interface ReviewProgrammeResumeData {
         action: "set-slot-category";
         slotId: string;
         category: string;
+    }
+    /**
+     * ADD a line the brief never named — usually one the payload offered under
+     * `unstated`, though any line is legal. Every other verb here subtracts,
+     * which made the programme a ceiling: whatever the brief happened to
+     * mention was the most a schedule could ever contain.
+     *
+     * `category` may be null or absent, because some real lines — grout,
+     * ironmongery, sanitaryware — have no catalog category yet. Such a slot is
+     * skipped at retrieval with a counted `no-category` shortfall, which is the
+     * honest treatment of a line we can hold but not yet fill.
+     */
+     | {
+        action: "add-slot";
+        spaceId: string;
+        name: string;
+        element: SlotElement;
+        category?: string | null;
     }>;
 }
 /**

package/coordinate-client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The COORDINATION lens: given several materials already chosen, what completes
+ * them. A thin wrapper over the shared {@link HttpTransport};
+ * `MaterialGraphClient.coordinate` delegates here.
+ *
+ * Extracted from `client.ts`, which sits above the repository's source-size
+ * limit, in the same per-lens shape as `brands-client` / `codes-client` /
+ * `colours-client`. Behaviour is unchanged.
+ */
+import { HttpTransport } from "./http-transport.js";
+import type { CoordinateInput, CoordinateResponse } from "./types.js";
+/**
+ * THE QUESTION: "here is my whole scheme so far — what completes it?" The
+ * multi-seed form of `pairings`: lift is SUMMED across seeds, so a companion
+ * suiting one pick ranks below one suiting several. Returns demand-lift-ranked
+ * companions with colour swatches and an annotate-only `colourFit` that never
+ * reorders in v1.
+ *
+ * Instead use `pairings` for a single material, and `colours.palette()` when the
+ * scheme is COLOURS rather than materials. Check `unresolved` before presenting:
+ * a reference that resolved to nothing is named there, not dropped.
+ */
+export declare function coordinate(transport: HttpTransport, input: CoordinateInput, signal?: AbortSignal): Promise<CoordinateResponse>;

package/coordinate-client.js

@@ -0,0 +1,25 @@
+/**
+ * The COORDINATION lens: given several materials already chosen, what completes
+ * them. A thin wrapper over the shared {@link HttpTransport};
+ * `MaterialGraphClient.coordinate` delegates here.
+ *
+ * Extracted from `client.ts`, which sits above the repository's source-size
+ * limit, in the same per-lens shape as `brands-client` / `codes-client` /
+ * `colours-client`. Behaviour is unchanged.
+ */
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "here is my whole scheme so far — what completes it?" The
+ * multi-seed form of `pairings`: lift is SUMMED across seeds, so a companion
+ * suiting one pick ranks below one suiting several. Returns demand-lift-ranked
+ * companions with colour swatches and an annotate-only `colourFit` that never
+ * reorders in v1.
+ *
+ * Instead use `pairings` for a single material, and `colours.palette()` when the
+ * scheme is COLOURS rather than materials. Check `unresolved` before presenting:
+ * a reference that resolved to nothing is named there, not dropped.
+ */
+export function coordinate(transport, input, signal) {
+    return transport.requestJson(resolveOperation("coordinate_materials"), { body: input, signal });
+}

package/errors.js

@@ -53,7 +53,9 @@ function sanitizeRecord(value, secrets, depth) {
         .slice(0, MAX_EXTENSION_ITEMS)
         .flatMap(([key, item]) => {
         const sanitized = sanitizeValue(item, secrets, depth + 1);
-        return sanitized === undefined ? [] : [[safeString(key, secrets), sanitized]];
+        return sanitized === undefined
+            ? []
+            : [[safeString(key, secrets), sanitized]];
     });
     return Object.fromEntries(entries);
 }
@@ -66,10 +68,13 @@ function sanitizeIssues(value, secrets) {
         .map((issue) => sanitizeRecord(issue, secrets, 0));
 }
 function sanitizeSuggestions(value, secrets) {
-    if (!Array.isArray(value) || value.some((suggestion) => typeof suggestion !== "string")) {
+    if (!Array.isArray(value) ||
+        value.some((suggestion) => typeof suggestion !== "string")) {
         return undefined;
     }
-    return value.slice(0, MAX_EXTENSION_ITEMS).map((suggestion) => safeString(suggestion, secrets));
+    return value
+        .slice(0, MAX_EXTENSION_ITEMS)
+        .map((suggestion) => safeString(suggestion, secrets));
 }
 function normalizeProblem(body, secrets) {
     if (!isRecord(body) ||
@@ -89,11 +94,15 @@ function normalizeProblem(body, secrets) {
         title: safeString(body.title, secrets),
         status: body.status,
         detail: safeString(body.detail, secrets),
-        ...(body.instance === undefined ? {} : { instance: safeString(body.instance, secrets) }),
+        ...(body.instance === undefined
+            ? {}
+            : { instance: safeString(body.instance, secrets) }),
         is_retriable: body.is_retriable,
         trace_id: safeString(body.trace_id, secrets),
         ...(suggestions === undefined ? {} : { suggestions }),
-        ...(typeof body.doc_uri === "string" ? { doc_uri: safeString(body.doc_uri, secrets) } : {}),
+        ...(typeof body.doc_uri === "string"
+            ? { doc_uri: safeString(body.doc_uri, secrets) }
+            : {}),
         ...(issues === undefined ? {} : { issues }),
     };
 }
@@ -107,7 +116,9 @@ function normalizeSimple(body, secrets) {
     };
 }
 function unexpectedMessage(status, responseText, secrets) {
-    const sanitized = redact(responseText, secrets).trim().slice(0, MAX_UNEXPECTED_TEXT);
+    const sanitized = redact(responseText, secrets)
+        .trim()
+        .slice(0, MAX_UNEXPECTED_TEXT);
     return sanitized.length > 0
         ? `MaterialGraph request failed with HTTP ${status}: ${sanitized}`
         : `MaterialGraph request failed with HTTP ${status}`;
@@ -143,7 +154,10 @@ export class MaterialGraphError extends Error {
         return this.retriable;
     }
     static unexpected(message) {
-        return new MaterialGraphError(message, { kind: "unexpected", retriable: false });
+        return new MaterialGraphError(message, {
+            kind: "unexpected",
+            retriable: false,
+        });
     }
     static fromTransport(input) {
         if (input.callerSignal?.aborted === true) {
@@ -174,7 +188,9 @@ export class MaterialGraphError extends Error {
         const retriable = RETRIABLE_STATUS.has(input.status);
         const metadata = requestMetadata(input);
         if (input.status === 429) {
-            return new MaterialGraphError(problem?.detail ?? simple?.error ?? "MaterialGraph rate limit exceeded (429)", {
+            return new MaterialGraphError(problem?.detail ??
+                simple?.error ??
+                "MaterialGraph rate limit exceeded (429)", {
                 ...metadata,
                 status: input.status,
                 rateLimit: input.rateLimit,

package/exploration-types.d.ts

@@ -0,0 +1,110 @@
+import type { VariantId } from "./identifiers.js";
+export type GraphOperator = "colourways" | "same_category" | "still_listed" | "looks_like" | "same_colour" | "pairs_with" | "often_specified_with" | "substitutes_for" | "more_durable" | "outdoor_suitable" | "lower_cost" | "more_sustainable";
+export interface GraphOperatorAvailability {
+    operator: GraphOperator;
+    operatorClass: "identity" | "perceptual" | "relational" | "spec";
+    label: string;
+    available: boolean;
+    basis: string;
+    count?: number;
+}
+export interface GraphOperatorEvidence {
+    variantId: VariantId;
+    operators: GraphOperatorAvailability[];
+}
+export interface CandidateReadInput {
+    operator: "looks_like";
+    corpusScope?: "all" | "materialBankOrderable";
+    limit?: number;
+    excludeVariantIds?: VariantId[];
+}
+export interface CandidateReadImage {
+    url: string;
+    source: "r2" | "origin";
+    /** Null means this image has not been analysed for a uniform light background. */
+    isIsolated: boolean | null;
+}
+export interface CandidateReadPaletteSwatch {
+    hex: string;
+    proportion: number;
+    name?: string | null;
+}
+export interface CandidateReadCard {
+    variantId: VariantId;
+    productId: string;
+    brandSlug: string;
+    materialBankId: string | null;
+    brand: string;
+    product: string;
+    variantName: string | null;
+    color: string | null;
+    image: CandidateReadImage | null;
+    palette: CandidateReadPaletteSwatch[];
+}
+export interface CandidateRankEvidence {
+    rank: number;
+    distance: number;
+    similarity: number;
+    basis: "active_main_image_embedding";
+    provenanceGrade: "measured";
+    displayImageMatchedEvidence: boolean | null;
+}
+export interface CandidateReadCandidate extends CandidateReadCard {
+    evidence: CandidateRankEvidence;
+    reason: string;
+}
+export interface CandidateSeedEvidence {
+    evidenceImageSha256: string;
+    displayImageSha256: string | null;
+    basis: "active_main_image_embedding";
+    provenanceGrade: "measured";
+    displayImageMatchedEvidence: boolean | null;
+}
+export interface CandidateReadReceipt {
+    operator: "looks_like";
+    corpusScope: {
+        scope: "all" | "materialBankOrderable";
+        description: string;
+    } | null;
+    requestedLimit: number;
+    returnedCount: number;
+    exclusions: {
+        requested: number;
+        unique: number;
+        applied: number;
+    };
+    dedupe: {
+        retrieved: number;
+        removed: number;
+        truncated: number;
+        projectionMisses: number;
+    };
+    timing: {
+        /** Internal seed projection completion; not a consumer response milestone. */
+        seedProjectionMs: number;
+        retrievalMs: number;
+        projectionMs: number;
+        completeMs: number;
+    };
+}
+interface CandidateReadResponseBase {
+    seed: CandidateReadCard;
+    receipt: CandidateReadReceipt;
+}
+export type CandidateReadResponse = (CandidateReadResponseBase & {
+    status: "ready";
+    seedEvidence: CandidateSeedEvidence;
+    candidates: CandidateReadCandidate[];
+    reason: null;
+}) | (CandidateReadResponseBase & {
+    status: "no_candidates" | "no_unseen_candidates" | "bounded_retrieval_unavailable";
+    seedEvidence: CandidateSeedEvidence;
+    candidates: [];
+    reason: string;
+}) | (CandidateReadResponseBase & {
+    status: "operator_unavailable";
+    seedEvidence: null;
+    candidates: [];
+    reason: string;
+});
+export {};

package/exploration-types.js

@@ -0,0 +1 @@
+export {};

package/fan-deck-types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Wire types for a maker's whole range — GET `/api/v1/brands/{brandSlug}/colours`.
+ *
+ * The one read in the SDK that is deliberately UNPAGINATED. Family order is only
+ * correct over a complete range: the greys cannot be placed against the browns
+ * while holding one page of each. So the response carries the brand, and
+ * `truncatedAt` appears only if a range ever exceeds the server's ceiling.
+ */
+export interface FanDeckSwatch {
+    /** Opaque token. Never parse or construct one. */
+    variantId: string;
+    brand: string;
+    /** The maker's own colour name. Null when the catalogue publishes none. */
+    name: string | null;
+    /** The maker's PUBLISHED hex. This read never returns a derived colour. */
+    hex: string;
+    /** colorscope's family id, lower case (`cream`, `gray`, `blue`). */
+    family: string;
+    /** OKLab L, 0–1. The sort key within a family: light to dark. */
+    lightness: number;
+    imageUrl: string | null;
+}
+export interface FanDeckFamily {
+    family: string;
+    /** Count over the WHOLE range, computed before any truncation. */
+    count: number;
+}
+export interface BrandFanDeck {
+    /**
+     * The brand SLUGS the deck resolved to — round-trippable identifiers, not
+     * display names. The maker's name as it should be shown is on every swatch.
+     */
+    brands: string[];
+    /** Grouped by `families` order, light to dark within each family. */
+    swatches: FanDeckSwatch[];
+    families: FanDeckFamily[];
+    /**
+     * Present ONLY when the range exceeded the server ceiling. Absent means the
+     * deck is complete — absent is not zero.
+     */
+    truncatedAt?: number;
+}

package/fan-deck-types.js

@@ -0,0 +1,9 @@
+/**
+ * Wire types for a maker's whole range — GET `/api/v1/brands/{brandSlug}/colours`.
+ *
+ * The one read in the SDK that is deliberately UNPAGINATED. Family order is only
+ * correct over a complete range: the greys cannot be placed against the browns
+ * while holding one page of each. So the response carries the brand, and
+ * `truncatedAt` appears only if a range ever exceeds the server's ceiling.
+ */
+export {};

package/http-transport.js

@@ -19,7 +19,10 @@ function parseRateLimit(headers) {
     const remaining = parseIntOrNull(headers.get("x-ratelimit-remaining"));
     const reset = parseIntOrNull(headers.get("x-ratelimit-reset"));
     const retryAfter = parseIntOrNull(headers.get("retry-after"));
-    if (limit === null && remaining === null && reset === null && retryAfter === null) {
+    if (limit === null &&
+        remaining === null &&
+        reset === null &&
+        retryAfter === null) {
         return null;
     }
     return { limit, remaining, reset, retryAfter };
@@ -39,7 +42,11 @@ export class HttpTransport {
     }
     /** The bearer + JSON `Accept` headers, plus any per-request additions. */
     authHeaders(extra) {
-        return { Authorization: `Bearer ${this.apiKey}`, Accept: "application/json", ...extra };
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            ...extra,
+        };
     }
     buildUrl(path, query) {
         const url = new URL(`${this.baseUrl}${path}`);
@@ -83,7 +90,11 @@ export class HttpTransport {
             });
         }
         catch (cause) {
-            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: input.signal });
+            throw MaterialGraphError.fromTransport({
+                ...metadata,
+                cause,
+                callerSignal: input.signal,
+            });
         }
         const rateLimit = parseRateLimit(response.headers);
         this.#lastRateLimit = rateLimit;
@@ -92,7 +103,11 @@ export class HttpTransport {
             text = await response.text();
         }
         catch (cause) {
-            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: input.signal });
+            throw MaterialGraphError.fromTransport({
+                ...metadata,
+                cause,
+                callerSignal: input.signal,
+            });
         }
         let parsed;
         if (text.length > 0) {
@@ -147,7 +162,11 @@ export class HttpTransport {
             });
         }
         catch (cause) {
-            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: options.signal });
+            throw MaterialGraphError.fromTransport({
+                ...metadata,
+                cause,
+                callerSignal: options.signal,
+            });
         }
         const rateLimit = parseRateLimit(response.headers);
         this.#lastRateLimit = rateLimit;

package/index.d.ts

@@ -1,13 +1,15 @@
-export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.js";
-export type { MaterialGraphClientOptions, BrowseNamespace } from "./client.js";
+export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
+export type { MaterialGraphClientOptions, BrowseNamespace, ExplorationNamespace, SourceMaterialCommentsNamespace, } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
 export type * from "./identifiers.js";
+export type * from "./exploration-types.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type * from "./run-types.js";
 export type * from "./schedule-types.js";
 export { VARY_AXES } from "./composition-types.js";
 export type * from "./composition-types.js";
+export type * from "./slot-pool-types.js";
 export { PROJECT_EVENT_KINDS } from "./project-types.js";
 export type * from "./project-types.js";
 export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
@@ -16,6 +18,7 @@ export { MaterialGraphError } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
 export type * from "./match-types.js";
+export type * from "./browse-types.js";
 export type * from "./by-colour-types.js";
 export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 export type * from "./match-stream-types.js";
@@ -27,10 +30,11 @@ export type * from "./colour-aggregate-types.js";
 export type * from "./palette-search-types.js";
 export type * from "./association-types.js";
 export type * from "./brand-types.js";
+export type * from "./fan-deck-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
 export type * from "./search-refinement-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export type * from "./spec-types.js";
-export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specTerm, } from "./specifications.js";
+export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";

package/index.js

@@ -1,4 +1,4 @@
-export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.js";
+export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export { VARY_AXES } from "./composition-types.js";
@@ -9,4 +9,4 @@ export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STRE
 export { CodesClient } from "./codes-client.js";
 export { ColoursClient } from "./colours-client.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
-export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specTerm, } from "./specifications.js";
+export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";

package/match-stream-types.d.ts

@@ -1,3 +1,4 @@
+import type { MatchCategoryInference, MatchColourReading } from "./match-types.js";
 /**
  * The Material Match PROGRESS-STREAM contracts — the wire vocabulary of
  * {@link MaterialGraphClient.matchStream} (`POST /api/v1/search/match` under
@@ -16,7 +17,6 @@
  * UI legend from the same source the validator uses.
  */
 import type { SearchResultItem } from "./types.js";
-import type { MatchCategoryInference, MatchColourReading } from "./match-types.js";
 /** How the workflow classified the uploaded image. */
 export declare const MATCH_IMAGE_TYPES: readonly ["swatch", "installation", "flatplan"];
 export type MatchImageType = (typeof MATCH_IMAGE_TYPES)[number];

package/match-stream-types.js

@@ -1,5 +1,9 @@
 /** How the workflow classified the uploaded image. */
-export const MATCH_IMAGE_TYPES = ["swatch", "installation", "flatplan"];
+export const MATCH_IMAGE_TYPES = [
+    "swatch",
+    "installation",
+    "flatplan",
+];
 /** What a detected surface is FOR — the element the material would serve. */
 export const MATCH_MATERIAL_FUNCTIONS = [
     "flooring",
@@ -13,7 +17,12 @@ export const MATCH_MATERIAL_FUNCTIONS = [
     "sample",
 ];
 /** The workflow's coarse progress phase, narrated by a `step` event. */
-export const MATCH_WORKFLOW_STEPS = ["classifying", "decomposing", "matching", "complete"];
+export const MATCH_WORKFLOW_STEPS = [
+    "classifying",
+    "decomposing",
+    "matching",
+    "complete",
+];
 /**
  * Where one surface stands in the run.
  *
@@ -40,7 +49,11 @@ export const MATCH_STREAM_EVENT_TYPES = [
     "complete",
     "error",
 ];
-export const MATCH_SENSE_CHECK_VERDICTS = ["confirmed", "rejected", "abstained"];
+export const MATCH_SENSE_CHECK_VERDICTS = [
+    "confirmed",
+    "rejected",
+    "abstained",
+];
 /** The terminal Match workflow result — every surface in its final state. */
 /**
  * How a Match run ended. `no_surfaces` means the detector worked and found no

package/match-stream.js

@@ -55,16 +55,21 @@
  * invariants.
  */
 import { MaterialGraphError } from "./errors.js";
-import { findSdkOperation } from "./operations.js";
 import { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 import { readNdjsonLines } from "./ndjson.js";
+import { findSdkOperation, } from "./operations.js";
 import { checkSearchResultItems } from "./search-result-validation.js";
 import { requireArray, requireBoundedNumber, requireDefaultedArray, requireEnum, requireIntegerAtLeast, requireNumber, requireOptionalString, requireRecord, requireString, } from "./validation.js";
 /** The NDJSON media type the Match route negotiates the scene workflow on. */
 const MATCH_STREAM_ACCEPT = "application/x-ndjson";
 /** How much of an offending frame a diagnostic quotes (crops can be megabytes). */
 const MAX_FRAME_PREVIEW = 200;
-const BOUNDING_BOX_CORNERS = Object.freeze(["x0", "y0", "x1", "y1"]);
+const BOUNDING_BOX_CORNERS = Object.freeze([
+    "x0",
+    "y0",
+    "x1",
+    "y1",
+]);
 function operation(operationId) {
     const found = findSdkOperation(operationId);
     if (!found)
@@ -76,7 +81,9 @@ function operation(operationId) {
  * offending path and quoting a bounded slice of the frame.
  */
 function frameFailure(line) {
-    const preview = line.length > MAX_FRAME_PREVIEW ? `${line.slice(0, MAX_FRAME_PREVIEW)}…` : line;
+    const preview = line.length > MAX_FRAME_PREVIEW
+        ? `${line.slice(0, MAX_FRAME_PREVIEW)}…`
+        : line;
     return (reason) => MaterialGraphError.unexpected(`MaterialGraph match stream sent a malformed NDJSON frame: ${reason}. Frame: ${preview}`);
 }
 /** Check one `MatchCategoryInference` item. */
@@ -190,7 +197,10 @@ function readFrame(value, fail) {
             // Payload-free by contract — there is nothing else to check.
             return record;
         case "complete":
-            return { ...record, result: readWorkflowResult(record.result, "`result`", fail) };
+            return {
+                ...record,
+                result: readWorkflowResult(record.result, "`result`", fail),
+            };
         case "error":
             requireString(record.message, "`message`", fail);
             return record;

package/material-types.d.ts

@@ -1,3 +1,4 @@
+import type { ProductId, VariantId } from "./identifiers.js";
 /**
  * Hand-mirrored wire types for the material projections — the grid-card tile,
  * the detail record, and the availability/successor block they carry.
@@ -22,7 +23,6 @@
  * that says which.
  */
 import type { ImageSource, MaterialColour, OpenEnum, PaletteSwatch } from "./types.js";
-import type { ProductId, VariantId } from "./identifiers.js";
 /**
  * Whether a material can still be bought.
  *