@instruments/materialgraph 0.2.0 → 0.4.0

package/composition-types.d.ts

@@ -45,13 +45,95 @@ export interface VarySchemesRequest {
     locks?: SchemeLock[];
     exclusions?: SchemeExclusions;
 }
-export type CompositionMatchState = OpenEnum<"matched" | "mismatched" | "unknown">;
-/** One resolved criterion → material match, as scored during composition. */
+/**
+ * One anchor (MG-613): a variant the designer has already pinned to a place in
+ * the programme, supplied on the `compose-material-schemes` run input's
+ * `anchors[]`. Exactly ONE of `variantId` (an exact catalog variant) or `query`
+ * (free-text "Brand Product Colour", resolved server-side) is required. An
+ * anchored slot is LOCKED — composition completes the OPEN slots in relation to
+ * it. Anchors that cannot be resolved leave the slot open and surface a run
+ * warning (never a failure).
+ */
+export interface ComposeAnchorInput {
+    /** The building element the anchor fills (flooring, wall, textile, …). */
+    element: SlotElement;
+    /** Optional named space to scope the anchor to (matched by name/slug). */
+    spaceName?: string;
+    /** An exact catalog variant id. Mutually exclusive with `query`. */
+    variantId?: string;
+    /** Free-text "Brand Product Colour". Mutually exclusive with `variantId`. */
+    query?: string;
+    /** Display name for slot naming and warnings. */
+    label?: string;
+}
+/**
+ * One standing rule in a project's compliance preset (MG-615): free-text
+ * `criteria` phrases that apply to a `scope` of slots. `scope: "all"` reaches
+ * every slot (including slots with no element and slots classified `other`); a
+ * named element reaches only slots carrying exactly that element, so an
+ * unclassified slot receives `"all"` rules only. Phrases are resolved
+ * server-side through the same vocabulary as brief criteria — sustainability
+ * wording ("LEED", "GREENGUARD Gold") resolves to a named certification
+ * programme. A phrase that grounds to nothing is dropped with a run warning.
+ */
+export interface CompliancePresetRule {
+    scope: "all" | SlotElement;
+    criteria: string[];
+}
+/** A project's standing rules, declared once on the compose run (max 12 rules). */
+export interface CompliancePreset {
+    rules: CompliancePresetRule[];
+}
+/**
+ * The `inputJson` for a `compose-material-schemes` run. `batchId` is required;
+ * everything else has a server default. `anchors` (max 24) carry externally
+ * decided picks (MG-613); `compliancePreset` carries the project's standing
+ * rules (MG-615), which cascade into slots as PREFERRED criteria — they grade
+ * every candidate but never exclude one.
+ */
+export interface ComposeMaterialSchemesInput {
+    batchId: string;
+    count?: number;
+    seed?: number;
+    exclusions?: SchemeExclusions;
+    anchors?: ComposeAnchorInput[];
+    compliancePreset?: CompliancePreset;
+}
+/**
+ * The state of one criterion verdict cell (MG-627: the shared MaterialGraph
+ * verdict states). The six LIVE states are `matched` (accepted value satisfies
+ * the criterion), `deviated` (directionally off but named), `failed` (an
+ * accepted value exists and does not satisfy it), `unverified` (a real value
+ * that did not clear the trust bar), `missing` (no accepted value to evaluate),
+ * and `not_evaluated` (the engine did not check it). `mismatched`/`unknown` are
+ * the two LEGACY tokens old persisted runs still carry (never emitted again).
+ * Open per the response-enum policy: treat unknown states forward-compatibly.
+ */
+export type CompositionMatchState = OpenEnum<"matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated" | "mismatched" | "unknown">;
+/** How a criterion cell was baselined — what the candidate was compared against. */
+export type CompositionMatchBaseline = {
+    kind: "term";
+    term: string;
+} | {
+    kind: "presence";
+} | {
+    kind: "seed";
+    variantId: string;
+};
+/** One resolved criterion → material verdict cell, as graded during composition. */
 export interface CompositionMatch {
     attributeId: string;
     state: CompositionMatchState;
     confidence: number | null;
     sourceBasis: string | null;
+    /** Required vs preferred criterion (MG-627). Absent on legacy persisted runs. */
+    strength?: "required" | "preferred";
+    /** What the cell was evaluated against (MG-627). Absent on legacy persisted runs. */
+    baseline?: CompositionMatchBaseline;
+    /** The candidate's own accepted value label, when the cell carries one (MG-627). */
+    value?: string | null;
+    /** Why an `unverified` cell missed the trust bar (MG-627), else null. */
+    trustGap?: "below_confidence" | "basis_unmet" | "proposed" | null;
 }
 /** One slot's chosen material plus the reason it was picked. */
 export interface CompositionPick {
@@ -72,6 +154,12 @@ export interface CompositionPick {
         matched: CompositionMatch[];
         notes: string[];
     };
+    /**
+     * True when this pick is an ANCHOR the designer pinned to the slot (MG-613):
+     * composition never replaced it and vary keeps it fixed. Absent for ordinary
+     * composed picks.
+     */
+    locked?: boolean;
 }
 /** The multi-objective score for one scheme (each component in [0, 1]). */
 export interface CompositionObjective {
@@ -115,3 +203,141 @@ export interface VarySchemesResponse {
     provenance: VaryProvenance;
     shortfall: CompositionShortfall | null;
 }
+/**
+ * Whether a programme element (space, slot, or palette) was `stated` in a text
+ * source or `inferred` from imagery/mood. Only inferred elements raise a review
+ * question. Absent → treated as `stated`.
+ */
+export type ProgrammeProvenance = "stated" | "inferred";
+/**
+ * The broad building element a slot fills — a pragmatically-extended Uniclass EF
+ * vocabulary. Widened with {@link OpenEnum} so a newer server term still
+ * type-checks.
+ */
+export type SlotElement = OpenEnum<"flooring" | "wall" | "ceiling" | "textile" | "surface" | "furniture" | "lighting" | "other">;
+/** One colour cue: a hex swatch with an optional human name. */
+export interface BriefColourCue {
+    hex: string;
+    name?: string;
+}
+/** A source anchor (document id + optional page) attributing derived content. */
+export interface CompositionSourceRef {
+    sourceId: string;
+    page: number | null;
+}
+/**
+ * One candidate colour direction the pile's colour evidence implies when no
+ * palette was explicitly committed. `directionId` is a stable kebab-case handle;
+ * `sourceRefs` attribute the direction to the palette source(s) it was drawn
+ * from (empty when unattributable).
+ */
+export interface PaletteDirection {
+    directionId: string;
+    name: string;
+    colours: BriefColourCue[];
+    sourceRefs: CompositionSourceRef[];
+}
+/**
+ * Suspend payload for the compose `review-programme` step: the FULL programme
+ * picture — every space and slot tagged with its provenance — so the card can
+ * show the whole thing and highlight what was inferred.
+ */
+export interface ReviewProgrammeSuspendPayload {
+    spaces: Array<{
+        spaceId: string;
+        name: string;
+        spaceType?: string;
+        provenance: ProgrammeProvenance;
+    }>;
+    slots: Array<{
+        slotId: string;
+        name: string;
+        spaceId?: string;
+        element?: SlotElement;
+        provenance: ProgrammeProvenance;
+    }>;
+}
+/**
+ * Resume grammar for the `review-programme` step: drop a slot, drop a space
+ * (cascade-dropping its slots), or rename a space.
+ */
+export interface ReviewProgrammeResumeData {
+    corrections: Array<{
+        action: "drop-slot";
+        slotId: string;
+    } | {
+        action: "drop-space";
+        spaceId: string;
+    } | {
+        action: "rename-space";
+        spaceId: string;
+        name: string;
+    }>;
+}
+/**
+ * Suspend payload for the compose `commit-palette` step. Today only the
+ * `directions` mode ships; the shape carries `mode` so a later `ab-images` mode
+ * is an additive member, not a migration.
+ */
+export interface CommitPaletteSuspendPayload {
+    mode: OpenEnum<"directions">;
+    directions: PaletteDirection[];
+}
+/**
+ * Resume grammar for the `commit-palette` step: commit to one direction (by id)
+ * or adopt the union of every direction's colours.
+ */
+export type CommitPaletteResumeData = {
+    choice: "direction";
+    directionId: string;
+} | {
+    choice: "all";
+};
+/**
+ * Resume grammar for the `review-material-criteria` step: accept a resolved
+ * attribute/term for an unresolved phrase, or drop it.
+ */
+export interface ReviewCriteriaResumeData {
+    corrections: Array<{
+        action: "accept";
+        slotId: string;
+        raw: string;
+        attributeId: string;
+        term?: string;
+    } | {
+        action: "drop";
+        slotId: string;
+        raw: string;
+    }>;
+}
+/** The union of every socratic-step resume payload, keyed by the suspended step. */
+export type InterviewResumeData = ReviewCriteriaResumeData | ReviewProgrammeResumeData | CommitPaletteResumeData;
+/** The three socratic interview steps, in procedure order. */
+export type InterviewStepId = "review-programme" | "commit-palette" | "review-material-criteria";
+/**
+ * Payload of a `composition.answered` event — the pile answered a question with
+ * no human turn, or a suspension resolved. `answer` is a stable slug; `citation`
+ * attributes an answer to its source when the brief stated it.
+ */
+export interface CompositionAnsweredPayload {
+    step: InterviewStepId;
+    answer: string;
+    citation: CompositionSourceRef | null;
+    counts?: Record<string, number>;
+}
+/**
+ * Payload of a `composition.slot-pool` event — the candidate theater for one
+ * slot: how many were considered and the top picks (≤5) hydrated for identity.
+ */
+export interface SlotPoolEventPayload {
+    slotId: string;
+    slotName: string;
+    considered: number;
+    top: Array<{
+        variantId: string;
+        brand: string;
+        product: string;
+        imageUrl: string | null;
+        score: number;
+    }>;
+}

package/http-transport.d.ts

@@ -2,8 +2,9 @@
  * The shared low-level HTTP transport for {@link MaterialGraphClient}. It owns
  * URL building, the bearer header, rate-limit capture, response reading, and the
  * one error-mapping path — so the JSON read surface (`client.ts`), the multipart
- * upload, and the SSE stream (`runs.ts`) all fail identically. Retry-free by
- * design; a single failure surfaces as one {@link MaterialGraphError}.
+ * upload, the SSE stream (`runs.ts`), and the NDJSON Match stream
+ * (`match-stream.ts`) all fail identically. Retry-free by design; a single
+ * failure surfaces as one {@link MaterialGraphError}.
  */
 import { type RateLimit } from "./errors.js";
 import { type SdkOperation } from "./operations.js";
@@ -15,6 +16,12 @@ export interface RequestOptions {
     signal?: AbortSignal;
     pathParams?: Readonly<Record<string, string>>;
 }
+export interface StreamRequestOptions extends RequestOptions {
+    /** The streaming media type to negotiate (`text/event-stream`, `application/x-ndjson`). */
+    accept: string;
+    /** Names this stream in the "returned no body" diagnostic, e.g. `"match stream"`. */
+    subject: string;
+}
 /** A read, status-checked HTTP response with its parsed body. */
 export interface SentResponse {
     response: Response;
@@ -51,6 +58,16 @@ export declare class HttpTransport {
      * it consumes the whole body via `response.text()`.
      */
     send(input: SendInput): Promise<SentResponse>;
+    /**
+     * Open a streaming operation and hand back its UNREAD byte body — the one
+     * entry point for every long-lived read (SSE run events, NDJSON Match
+     * progress). Everything up to the first byte behaves exactly like
+     * {@link send}: same URL building, same bearer header, same rate-limit
+     * capture, same {@link MaterialGraphError} mapping for a transport failure or
+     * a non-2xx (whose short error body IS read, since it is not a stream).
+     * Framing and cancellation belong to the caller.
+     */
+    openStream(sdkOperation: SdkOperation, options: StreamRequestOptions): Promise<ReadableStream<Uint8Array>>;
     /** Execute a registered JSON operation and return its typed body. */
     requestJson<T>(sdkOperation: SdkOperation, options?: RequestOptions): Promise<T>;
 }

package/http-transport.js

@@ -2,8 +2,9 @@
  * The shared low-level HTTP transport for {@link MaterialGraphClient}. It owns
  * URL building, the bearer header, rate-limit capture, response reading, and the
  * one error-mapping path — so the JSON read surface (`client.ts`), the multipart
- * upload, and the SSE stream (`runs.ts`) all fail identically. Retry-free by
- * design; a single failure surfaces as one {@link MaterialGraphError}.
+ * upload, the SSE stream (`runs.ts`), and the NDJSON Match stream
+ * (`match-stream.ts`) all fail identically. Retry-free by design; a single
+ * failure surfaces as one {@link MaterialGraphError}.
  */
 import { MaterialGraphError } from "./errors.js";
 import { operationPath } from "./operations.js";
@@ -115,6 +116,75 @@ export class HttpTransport {
         }
         return { response, text, parsed };
     }
+    /**
+     * Open a streaming operation and hand back its UNREAD byte body — the one
+     * entry point for every long-lived read (SSE run events, NDJSON Match
+     * progress). Everything up to the first byte behaves exactly like
+     * {@link send}: same URL building, same bearer header, same rate-limit
+     * capture, same {@link MaterialGraphError} mapping for a transport failure or
+     * a non-2xx (whose short error body IS read, since it is not a stream).
+     * Framing and cancellation belong to the caller.
+     */
+    async openStream(sdkOperation, options) {
+        const url = this.buildUrl(operationPath(sdkOperation, options.pathParams), options.query);
+        const requestUrl = new URL(url);
+        const metadata = {
+            method: sdkOperation.method,
+            origin: requestUrl.origin,
+            path: requestUrl.pathname,
+        };
+        const hasBody = options.body !== undefined;
+        let response;
+        try {
+            response = await this.fetch(url, {
+                method: sdkOperation.method,
+                headers: this.authHeaders({
+                    Accept: options.accept,
+                    ...(hasBody ? { "Content-Type": "application/json" } : {}),
+                }),
+                body: hasBody ? JSON.stringify(options.body) : undefined,
+                signal: options.signal,
+            });
+        }
+        catch (cause) {
+            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: options.signal });
+        }
+        const rateLimit = parseRateLimit(response.headers);
+        this.#lastRateLimit = rateLimit;
+        if (!response.ok) {
+            let text = "";
+            try {
+                text = await response.text();
+            }
+            catch {
+                // The status IS the error; a body that will not read adds nothing and
+                // must not mask it. Report the failure with an empty detail instead.
+                text = "";
+            }
+            let parsed;
+            if (text.length > 0) {
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    parsed = text;
+                }
+            }
+            throw MaterialGraphError.fromResponse({
+                ...metadata,
+                status: response.status,
+                body: parsed,
+                responseText: text,
+                rateLimit,
+                apiKey: this.apiKey,
+                queryValues: [...requestUrl.searchParams.values()],
+            });
+        }
+        if (response.body === null) {
+            throw MaterialGraphError.unexpected(`MaterialGraph ${options.subject} returned no body`);
+        }
+        return response.body;
+    }
     /** Execute a registered JSON operation and return its typed body. */
     async requestJson(sdkOperation, options = {}) {
         const url = this.buildUrl(operationPath(sdkOperation, options.pathParams), options.query);

package/index.d.ts

@@ -4,6 +4,7 @@ export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.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 { PROJECT_EVENT_KINDS } from "./project-types.js";
@@ -13,7 +14,13 @@ export type * from "./run-events.js";
 export { MaterialGraphError } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
+export { MATCH_IMAGE_TYPES, 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";
+export { CodesClient } from "./codes-client.js";
 export type * from "./codes-types.js";
+export { ColoursClient } from "./colours-client.js";
+export type { ColoursTransport } from "./colours-client.js";
+export type * from "./colour-aggregate-types.js";
 export type * from "./brand-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";

package/index.js

@@ -5,5 +5,8 @@ export { VARY_AXES } from "./composition-types.js";
 export { PROJECT_EVENT_KINDS } from "./project-types.js";
 export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
 export { MaterialGraphError } from "./errors.js";
+export { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+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";

package/match-stream-types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The Material Match PROGRESS-STREAM contracts — the wire vocabulary of
+ * {@link MaterialGraphClient.matchStream} (`POST /api/v1/search/match` under
+ * `Accept: application/x-ndjson`). One JSON object per line; the run ends on a
+ * `complete` or an `error` event.
+ *
+ * These shapes are HAND-MIRRORED from `matchStreamEventSchema` in
+ * `@materialgraph/products` — the SDK publishes with zero runtime dependencies,
+ * so it cannot import the Zod schema itself. `contract-parity.test.ts` re-checks
+ * the mirror against the real schema, deriving the enum members FROM the
+ * canonical schemas so a server-side addition fails that test rather than
+ * silently widening the client.
+ *
+ * Every enum here is CLOSED, exactly as the canonical `z.enum(…)` members are.
+ * The value lists are exported so a consumer can build an exhaustive switch or a
+ * UI legend from the same source the validator uses.
+ */
+import type { MatchCategoryInference, SearchResultItem } from "./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];
+/** What a detected surface is FOR — the element the material would serve. */
+export declare const MATCH_MATERIAL_FUNCTIONS: readonly ["flooring", "wall_surface", "ceiling", "partition", "upholstery", "millwork", "countertop", "accent", "sample"];
+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"];
+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"];
+export type MatchStreamEventType = (typeof MATCH_STREAM_EVENT_TYPES)[number];
+/** Where a surface sits in the image, in Gemini-style 0–1000 image space. */
+export interface MatchBoundingBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** One surface the decompose step found in the image. */
+export interface MatchDetectedSurface {
+    id: string;
+    label: string;
+    materialFunction: MatchMaterialFunction;
+    /** The detector's catalog category answer, when it named one. */
+    categoryHint?: string;
+    /** Detector confidence, always within [0, 1]. */
+    confidence: number;
+    description?: string;
+    boundingBox: MatchBoundingBox;
+    /** JPEG data-URI crop used for Match retrieval — the thumbnail to show. */
+    cropDataUri?: string;
+}
+/**
+ * One surface's matching state and its ranked results. The same `surface.id`
+ * arrives repeatedly as the run progresses (`matching` → `complete` / `error`);
+ * render by replacing on id rather than appending.
+ *
+ * `results` and `inferredCategories` are always present on a yielded event: the
+ * canonical schema defaults each to `[]`, and the reader fills them when the
+ * server omits them, so neither ever arrives as `undefined`.
+ */
+export interface MatchSurfaceResult {
+    surface: MatchDetectedSurface;
+    status: MatchSurfaceStatus;
+    results: SearchResultItem[];
+    inferredCategories: MatchCategoryInference[];
+    /** Present only on `status: "error"` — why this one surface failed. */
+    error?: string;
+}
+/** The terminal Match workflow result — every surface in its final state. */
+export interface MatchWorkflowResult {
+    imageType: MatchImageType;
+    surfaces: MatchSurfaceResult[];
+    /** Present for swatch / single-surface runs that skip decompose. */
+    results?: SearchResultItem[];
+    inferredCategories?: MatchCategoryInference[];
+    /**
+     * How the run ended, counted rather than inferred. `surfacesFailed > 0` with
+     * no results is a broken run; zero failures with no results is a genuine
+     * "nothing above the floor". Do not fold `surfaces[]` to tell those apart.
+     */
+    totals: MatchRunTotals;
+}
+/** Progress narration for the phase the workflow just entered. */
+export interface MatchStreamStepEvent {
+    type: "step";
+    step: MatchWorkflowStep;
+    message: string;
+}
+/** The image type the classify step settled on. */
+export interface MatchStreamClassifiedEvent {
+    type: "classified";
+    imageType: MatchImageType;
+}
+/** Every surface the decompose step found, before any of them has matched. */
+export interface MatchStreamSurfacesEvent {
+    type: "surfaces";
+    surfaces: MatchDetectedSurface[];
+}
+/**
+ * The run's tally at the moment a `surface` event was emitted, so a consumer
+ * reads the server's arithmetic rather than reimplementing it.
+ *
+ * A FAILED surface is the case this exists to settle: failing is a way of
+ * RESOLVING. An errored surface counts in `surfacesResolved` (it will never be
+ * reported again), counts again in `surfacesFailed`, and adds nothing to
+ * `matchesSoFar`. `surfacesResolved === surfacesDetected` is therefore the
+ * correct "the run is done" test, and never stalls at 3/4 on a failure.
+ */
+export interface MatchRunTotals {
+    /** Surfaces the decompose step found. The denominator; fixed for the run. */
+    surfacesDetected: number;
+    /** Surfaces that reached a terminal state — `complete` OR `error`. */
+    surfacesResolved: number;
+    /** Of those resolved, how many ended in `error`. Always ≤ `surfacesResolved`. */
+    surfacesFailed: number;
+    /** Result items accumulated across every surface resolved so far. */
+    matchesSoFar: number;
+}
+/** One surface's state changed — the frame that makes Match progressive. */
+export interface MatchStreamSurfaceEvent {
+    type: "surface";
+    surface: MatchSurfaceResult;
+    /** The run's tally as of this frame. Always present on a `surface` event. */
+    totals: MatchRunTotals;
+}
+/**
+ * CONNECTION LIVENESS ONLY — never progress. Proxies and load balancers kill
+ * idle connections, so the server sends this when the stream has been quiet, and
+ * a client can tell a slow run from a dropped one. It carries no payload, and no
+ * consumer should treat it as a state change: do not advance a step, reset a
+ * no-progress watchdog, or count it towards anything.
+ */
+export interface MatchStreamHeartbeatEvent {
+    type: "heartbeat";
+}
+/** Terminal: the whole run finished and carries its assembled result. */
+export interface MatchStreamCompleteEvent {
+    type: "complete";
+    result: MatchWorkflowResult;
+}
+/** Terminal: the run failed as a whole (a single surface failing is not this). */
+export interface MatchStreamErrorEvent {
+    type: "error";
+    message: string;
+}
+/** One frame of the Match progress stream, discriminated by `type`. */
+export type MatchStreamEvent = MatchStreamStepEvent | MatchStreamClassifiedEvent | MatchStreamSurfacesEvent | MatchStreamSurfaceEvent | MatchStreamHeartbeatEvent | MatchStreamCompleteEvent | MatchStreamErrorEvent;

package/match-stream-types.js

@@ -0,0 +1,28 @@
+/** How the workflow classified the uploaded image. */
+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",
+    "wall_surface",
+    "ceiling",
+    "partition",
+    "upholstery",
+    "millwork",
+    "countertop",
+    "accent",
+    "sample",
+];
+/** 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"];
+/** Every frame type the stream can carry — the union's discriminant values. */
+export const MATCH_STREAM_EVENT_TYPES = [
+    "step",
+    "classified",
+    "surfaces",
+    "surface",
+    "heartbeat",
+    "complete",
+    "error",
+];

package/match-stream.d.ts

@@ -0,0 +1,22 @@
+import type { HttpTransport } from "./http-transport.js";
+import { type MatchStreamEvent } from "./match-stream-types.js";
+import type { MatchInput } from "./types.js";
+/**
+ * Decode one NDJSON line into a validated {@link MatchStreamEvent}, raising a
+ * {@link MaterialGraphError} on anything the contract does not allow. Exported
+ * for `contract-parity.test.ts`, which re-checks it against the real Zod schema;
+ * it is not part of the published surface.
+ */
+export declare function decodeMatchStreamEvent(line: string): MatchStreamEvent;
+/**
+ * Stream Match progress as an async iterator. Iterates until the run reaches a
+ * `complete` or an `error` event, and raises if the connection ends before one
+ * arrives.
+ *
+ * `signal` genuinely cancels: it is linked to the AbortController that owns the
+ * in-flight request, so aborting (or simply `break`ing out of the loop) tears
+ * down the HTTP connection rather than merely stopping the yields. A
+ * caller-requested abort ends the iteration CLEANLY — the caller already knows
+ * it cancelled, so the truncated-stream error is not raised for it.
+ */
+export declare function matchStream(transport: HttpTransport, input: MatchInput, signal?: AbortSignal): AsyncGenerator<MatchStreamEvent, void, unknown>;