@instruments/materialgraph 0.32.0 → 0.35.0

package/{find-variants-by-colour-types.d.ts → find-variants-by-color-types.d.ts}

@@ -1,24 +1,24 @@
+import type { ImageReferenceInput } from "./image-reference-types.js";
 /**
- * @module find-variants-by-colour-types
- * @description Hand-maintained mirror of `find_variants_by_colour`'s
+ * @module find-variants-by-color-types
+ * @description Hand-maintained mirror of `find_variants_by_color`'s
  * (MG-2217/MG-2230/MG-2247/MG-2328) input and output wire shapes. The source
- * of truth is `packages/products/src/search/find-variants-by-colour.ts` —
+ * of truth is `packages/products/src/search/find-variants-by-color.ts` —
  * `rerank`'s `reference.candidates`/`reference.seed` still mirror
- * `compare-colour-similarity.ts`'s own seed shape, but its `matches[]` card
+ * `compare-color-similarity.ts`'s own seed shape, but its `matches[]` card
  * is the same shape CONTAINS/PALETTE use, not a copy of that module's result.
  * This SDK has no RUNTIME dependency on `@materialgraph/products` (it's a
  * devDependency only, for the parity tests in `__tests__/`), so the shapes
  * are copied here rather than imported. `contract-parity.test.ts` keeps this
  * mirror honest against the server types.
  */
-import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
-import type { ImageReferenceInput } from "./image-reference-types.js";
-export type FindVariantsByColourMode = "contains" | "palette" | "rerank";
-/** One colour condition. `role` defaults to `required`; every other field defaults to absent/false/0. */
-export type ColourConditionInput = {
+import type { SearchCatalogueSubset, SearchCatalogueSubsetReceipt } from "./search-catalogue-subset-types.js";
+export type FindVariantsByColorMode = "contains" | "palette" | "rerank";
+/** One color condition. `role` defaults to `required`; every other field defaults to absent/false/0. */
+export type ColorConditionInput = {
     /** Name, code or hex (e.g. "sage green"). */
-    colour?: string;
-    /** Must be the swatch's largest colour. */
+    color?: string;
+    /** Must be the swatch's largest color. */
     dominant?: boolean;
     role?: "required" | "preferred";
     /** Target (palette) or minimum (contains) share. */
@@ -26,29 +26,31 @@ export type ColourConditionInput = {
     /** Maximum share, e.g. an accent. */
     shareMax?: number;
 };
-export type FindVariantsByColourInput = {
+export type FindVariantsByColorInput = {
     /** Brand slugs or names to filter to. */
     brands?: string[];
-    /** One entry per colour (exactly one for rerank). */
-    colours?: ColourConditionInput[];
-    corpusScope?: CorpusScope;
+    /** One entry per color (exactly one for rerank). */
+    colors?: ColorConditionInput[];
+    /** Material Bank category IDs or exact source paths, including descendants against actual memberships. Materials and decking only. */
+    categoryIds?: string[];
+    searchCatalogueSubset?: SearchCatalogueSubset;
     cursor?: string;
-    /** Palette only: targets from this image's colours, not `colours[]`. */
+    /** Palette only: targets from this image's colors, not `colors[]`. */
     image?: ImageReferenceInput;
     limit?: number;
-    mode: FindVariantsByColourMode;
-    /** Category keys, e.g. wallcovering, floor_tile, upholstery. */
+    mode: FindVariantsByColorMode;
+    /** Independent specification type or group keys, e.g. wallcovering or coatings; filters specification types, not source categories. */
     productTypeIds?: string[];
-    /** palette: match its palette. rerank: rank by its colour. */
+    /** palette: match its palette. rerank: rank by its color. */
     targetVariantId?: string;
-    /** Ids to reorder by colour (rerank). */
+    /** Ids to reorder by color (rerank). */
     variantIds?: string[];
 };
-export type ColourConditionReceipt = {
+export type ColorConditionReceipt = {
     /** OKLab distance to the matched swatch. Never a probability. */
     distance: number;
     hex: string;
-    /** Position in the request's `colours[]`. */
+    /** Position in the request's `colors[]`. */
     index: number;
     /** The matched swatch's share of its image, 0 to 1. */
     proportion: number;
@@ -63,16 +65,16 @@ export type PaintCatalogVariant = {
     variantId: string;
     variantName: string | null;
 };
-export type ResolvedColour = {
+export type ResolvedColor = {
     catalogueVariant: PaintCatalogVariant | null;
     hex: string;
     index: number;
     /** `region`: a named meaning's own OKLCh bounds, kept — never collapsed to one hex. */
     kind: "point" | "region";
-    /** Renormalised share, image-extracted colours only; else null. */
+    /** Renormalised share, image-extracted colors only; else null. */
     share: number | null;
 };
-export type ColourAlternative = {
+export type ColorAlternative = {
     code?: string;
     hex: string;
     libraryId: string;
@@ -80,18 +82,22 @@ export type ColourAlternative = {
     name: string;
     query: string;
 };
-export type UnresolvedColour = {
-    alternatives: ColourAlternative[];
+export type UnresolvedColor = {
+    alternatives: ColorAlternative[];
     index: number;
     input: string | null;
 };
-export type ColourVariantMatch = {
+export type ColorVariantMatch = {
+    /** Accepted primary specification type; null when unknown. */
+    productTypeId: string | null;
     brand: string;
     brandId: string;
-    category: string;
+    category: string | null;
+    /** All original source category IDs in source order; empty when unknown. */
+    categories: string[];
     code: string | null;
-    colours: ColourConditionReceipt[];
-    /** Share of the request's colours this variant matched, 0 to 1. Never a probability. */
+    colors: ColorConditionReceipt[];
+    /** Share of the request's colors this variant matched, 0 to 1. Never a probability. */
     coverage: number;
     imageUrl: string | null;
     product: string;
@@ -99,7 +105,7 @@ export type ColourVariantMatch = {
     variantId: string;
     variantName: string;
 };
-export type ColourPageInfo = {
+export type ColorPageInfo = {
     endCursor: string | null;
     hasNextPage: boolean;
     /**
@@ -112,21 +118,21 @@ export type ColourPageInfo = {
     poolTruncated: boolean;
 };
 type ContainsOrPaletteResult = {
-    /** Colour-matched candidates dropped by `list_variants`' hard filters or eligibility. */
+    /** Color-matched candidates dropped by `list_variants`' hard filters or eligibility. */
     gatedOut: number;
-    matches: ColourVariantMatch[];
-    pageInfo: ColourPageInfo;
-    resolvedColours: ResolvedColour[];
-    unresolvedColours: UnresolvedColour[];
+    matches: ColorVariantMatch[];
+    pageInfo: ColorPageInfo;
+    resolvedColors: ResolvedColor[];
+    unresolvedColors: UnresolvedColor[];
 };
-export type FindVariantsByColourContainsResult = ContainsOrPaletteResult & {
+export type FindVariantsByColorContainsResult = ContainsOrPaletteResult & {
     mode: "contains";
 };
-export type FindVariantsByColourPaletteResult = ContainsOrPaletteResult & {
+export type FindVariantsByColorPaletteResult = ContainsOrPaletteResult & {
     mode: "palette";
 };
-/** `reference.candidates`/`reference.seed`'s shape — mirrors `compare-colour-similarity.ts`'s own seed, unlike `matches[]` below. */
-export type ColourRankedSeed = {
+/** `reference.candidates`/`reference.seed`'s shape — mirrors `compare-color-similarity.ts`'s own seed, unlike `matches[]` below. */
+export type ColorRankedSeed = {
     brand: string;
     brandSlug: string;
     color: string | null;
@@ -134,16 +140,16 @@ export type ColourRankedSeed = {
     product: string;
     productId: string;
     variantId: string;
-    /** The variant's own name — paint colourway names live here (label contract). */
+    /** The variant's own name — paint colorway names live here (label contract). */
     variantName: string | null;
 };
-/** RERANK's own card — the same shape `ColourVariantMatch` above (`brandId`, `code`), plus its two ranking-only fields. */
-export type ColourRankMatch = {
+/** RERANK's own card — the same shape `ColorVariantMatch` above (`brandId`, `code`), plus its two ranking-only fields. */
+export type ColorRankMatch = {
     brand: string;
     brandId: string;
     code: string | null;
-    /** Colour similarity in [0,1], 1 = identical palette; null when unembedded. */
-    colourSimilarity: number | null;
+    /** Color similarity in [0,1], 1 = identical palette; null when unembedded. */
+    colorSimilarity: number | null;
     /** Cosine distance computed in TypeScript (0 = identical); null when unembedded. */
     distance: number | null;
     imageUrl: string | null;
@@ -152,19 +158,19 @@ export type ColourRankMatch = {
     variantId: string;
     variantName: string | null;
 };
-export type ResolvedColourReference = {
+export type ResolvedColorReference = {
     hex: string;
     name: string | null;
     ref: string;
 };
-export type CompareColourSimilarityReference = {
+export type CompareColorSimilarityReference = {
     /** Best-per-brand candidates when `resolution === "ambiguous"`; empty otherwise. */
-    candidates: ColourRankedSeed[];
-    /** The resolved colour when the reference was a `colour`, else null. */
-    colour: ResolvedColourReference | null;
+    candidates: ColorRankedSeed[];
+    /** The resolved color when the reference was a `color`, else null. */
+    color: ResolvedColorReference | null;
     /** The input as given, so an agent can react to a miss. */
     input: {
-        colour?: string;
+        color?: string;
         material?: string;
         oklab?: {
             L: number;
@@ -173,25 +179,25 @@ export type CompareColourSimilarityReference = {
         };
         variantId?: string;
     };
-    /** `ambiguous` when a colour-name material reference spans several brands. */
+    /** `ambiguous` when a color-name material reference spans several brands. */
     resolution: "resolved" | "ambiguous";
     /** The resolved seed when the reference was a `material`/`variantId`, else null. */
-    seed: ColourRankedSeed | null;
+    seed: ColorRankedSeed | null;
 };
-export type FindVariantsByColourRerankResult = {
+export type FindVariantsByColorRerankResult = {
     /** Present ONLY when the request narrowed it. ABSENT means the whole graph. */
-    corpusScope?: CorpusScopeReceipt;
-    /** Real variant ids outside `corpusScope` or the materials catalogue. Present when a scope narrowed or any was excluded. */
-    excludedByCorpusScope?: string[];
-    /** Candidates ranked by ascending colour distance; unembedded ones last. */
-    matches: ColourRankMatch[];
+    searchCatalogueSubset?: SearchCatalogueSubsetReceipt;
+    /** Real variant ids outside `searchCatalogueSubset` or the materials catalogue. Present when a scope narrowed or any was excluded. */
+    excludedBySearchCatalogueSubset?: string[];
+    /** Candidates ranked by ascending color distance; unembedded ones last. */
+    matches: ColorRankMatch[];
     mode: "rerank";
     /** The reference, echoed with its resolution. */
-    reference: CompareColourSimilarityReference;
-    /** The reference colour, echoed in the same shape CONTAINS/PALETTE use — always 0 or 1 entries. */
-    resolvedColours: ResolvedColour[];
+    reference: CompareColorSimilarityReference;
+    /** The reference color, echoed in the same shape CONTAINS/PALETTE use — always 0 or 1 entries. */
+    resolvedColors: ResolvedColor[];
     /** Candidate ids that did not resolve to any variant. */
     unresolved: string[];
 };
-export type FindVariantsByColourOutput = FindVariantsByColourContainsResult | FindVariantsByColourPaletteResult | FindVariantsByColourRerankResult;
+export type FindVariantsByColorOutput = FindVariantsByColorContainsResult | FindVariantsByColorPaletteResult | FindVariantsByColorRerankResult;
 export {};

package/find-variants-by-vector-types.d.ts

@@ -8,6 +8,7 @@
  */
 import type { ImageReferenceInput } from "./image-reference-types.js";
 import type { FilterGroups, ListVariantsItem } from "./list-variants-types.js";
+import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
 export declare const FIND_VARIANTS_BY_VECTOR_MODES: readonly ["text", "image", "text_and_image"];
 export type FindVariantsByVectorMode = (typeof FIND_VARIANTS_BY_VECTOR_MODES)[number];
 export type FindVariantsByVectorQuery = {
@@ -26,6 +27,8 @@ export type FindVariantsByVectorInput = {
     /** Default 20. */
     limit?: number;
     query: FindVariantsByVectorQuery;
+    /** Only this corpus scope. Absent or all: every variant. */
+    searchCatalogueSubset?: SearchCatalogueSubset;
 };
 export type FindVariantsByVectorItem = Omit<ListVariantsItem, "materialBankId"> & {
     /** The variant's Material Bank SKU; null means none is recorded. Always present here, unlike `list_variants`' optional field. */
@@ -54,7 +57,7 @@ export type FindVariantsByVectorTimings = {
 };
 export type FindVariantsByVectorOutput = {
     /** Explicit `{field: "variant", op: "in"}` filter ids that name a real variant outside the materials catalogue — present only when at least one did. */
-    excludedByCorpusScope?: string[];
+    excludedBySearchCatalogueSubset?: string[];
     items: FindVariantsByVectorItem[];
     mode: FindVariantsByVectorMode;
     reference: FindVariantsByVectorReference;

package/get-variant-types.d.ts

@@ -7,7 +7,7 @@
  * `__tests__/contract-parity.test.ts` keeps the mirror honest against the
  * server types.
  */
-import type { ListVariantsNotApplicable, ListVariantsSpecifications } from "./list-variants-types.js";
+import type { ListVariantsNotApplicable, ListVariantsSpecifications, SampleSubject } from "./list-variants-types.js";
 /** The detail to add under `specifications`; absent, the answer is the compact item alone. */
 export type GetVariantOptions = {
     /** Canonical attribute ids, e.g. `["nrc_rating"]`. */
@@ -24,7 +24,19 @@ export type GetVariantOutput = {
     category: {
         id: string;
         name: string;
-    };
+    } | null;
+    categories: {
+        id: string;
+        name: string;
+    }[];
+    /** Null for a color sample or an unresolved subject. */
+    productType: {
+        id: string;
+        name: string;
+    } | null;
+    sampleSubject: SampleSubject;
+    /** The represented library color; null when none is established. */
+    colorOptionValueId: string | null;
     code: string | null;
     image: {
         alt: string;

package/http-transport.d.ts

@@ -13,7 +13,7 @@ export type RequestOptions = {
 export type StreamRequestOptions = {
     /** 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"`. */
+    /** Names this stream in the "returned no body" diagnostic, e.g. `"run-event stream"`. */
     subject: string;
 } & RequestOptions;
 /** A read, status-checked HTTP response with its parsed body. */

package/http-transport.js

@@ -2,8 +2,7 @@
  * 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, the SSE stream (`runs.ts`), and the NDJSON Match stream
- * (`match-stream.ts`) all fail identically. Retry-free by design; a single
+ * upload, and the SSE stream (`runs.ts`) all fail identically. Retry-free by design; a single
  * failure surfaces as one {@link MaterialGraphError}.
  */
 import { MaterialGraphError } from "./errors.js";

package/identifiers.d.ts

@@ -16,7 +16,7 @@
  *   `categoryKey`, `jurisdictionId`, `brandSlug`. These ARE meaningful, stable,
  *   and yours to compose queries from — but you DISCOVER them rather than
  *   invent them (`listVariantFacets()`, `listEnumValues()`,
- *   `listAttributes()`, `taxonomy()`, `colourFacets()`, `codes.context()`).
+ *   `listAttributes()`, `categories.list()`, `brands()`).
  *   A hand-guessed canonical token is the second-most-common caller bug.
  *
  * Every alias below is exactly `string`. They carry no runtime weight and no
@@ -30,7 +30,7 @@
 export type OpaqueId = string;
 /**
  * A variant id — the identity of ONE buyable material (this product in this
- * colourway/finish). The unit almost every read is keyed on.
+ * colorway/finish). The unit almost every read is keyed on.
  *
  * Opaque: preserve verbatim, never parse or construct one.
  */

package/identifiers.js

@@ -16,7 +16,7 @@
  *   `categoryKey`, `jurisdictionId`, `brandSlug`. These ARE meaningful, stable,
  *   and yours to compose queries from — but you DISCOVER them rather than
  *   invent them (`listVariantFacets()`, `listEnumValues()`,
- *   `listAttributes()`, `taxonomy()`, `colourFacets()`, `codes.context()`).
+ *   `listAttributes()`, `categories.list()`, `brands()`).
  *   A hand-guessed canonical token is the second-most-common caller bug.
  *
  * Every alias below is exactly `string`. They carry no runtime weight and no

package/index.d.ts

@@ -2,11 +2,12 @@ export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
 export type { MaterialGraphClientOptions } from "./client.js";
 export type * from "./list-variants-types.js";
 export type * from "./list-variant-facets-types.js";
+export type * from "./search-variants-types.js";
 export type * from "./list-enum-values-types.js";
 export type * from "./get-variant-types.js";
 export type * from "./image-reference-types.js";
 export type * from "./find-companions-types.js";
-export type * from "./find-variants-by-colour-types.js";
+export type * from "./find-variants-by-color-types.js";
 export { FIND_VARIANTS_BY_VECTOR_MODES } from "./find-variants-by-vector-types.js";
 export type * from "./find-variants-by-vector-types.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
@@ -18,25 +19,16 @@ export type * from "./citation-types.js";
 export { MATERIALGRAPH_PROBLEM_EXTENSIONS, 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 "./search-card-types.js";
 export type * from "./resolve-variant-types.js";
 export type * from "./catalogue-types.js";
-export type * from "./by-colour-types.js";
 export { CategoriesClient } from "./categories-client.js";
 export type * from "./category-types.js";
-export { ColoursClient } from "./colours-client.js";
-export type { ColoursTransport } from "./colours-client.js";
-export type * from "./palette-search-types.js";
-export type * from "./query-understanding-types.js";
-export type * from "./material-query-plan-types.js";
+export { ColorsClient } from "./colors-client.js";
+export type { ColorsTransport } from "./colors-client.js";
+export type * from "./color-profiles-types.js";
 export type * from "./association-types.js";
 export type * from "./brand-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 type * from "./attribution-types.js";
-export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
-export type * from "./spec-types.js";
-export { certificationProgramme, hasSpec, specTerm } from "./specifications.js";
 export type { SamplizePublicationSource, SamplizeLrvObservation, SamplizeDemand, SamplizeCollectionMembership, SamplizeCatalogueOptions, SamplizeCataloguePage, SamplizeCatalogueProduct, SamplizeHexObservation, } from "./samplize-catalogue-types.js";

package/index.js

@@ -4,6 +4,4 @@ export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
 export { CategoriesClient } from "./categories-client.js";
-export { ColoursClient } from "./colours-client.js";
-export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
-export { certificationProgramme, hasSpec, specTerm } from "./specifications.js";
+export { ColorsClient } from "./colors-client.js";

package/list-variant-facets-types.d.ts

@@ -1,3 +1,4 @@
+import type { FilterGroups } from "./list-variants-types.js";
 /**
  * @module list-variant-facets-types
  * @description Hand-maintained mirror of `list_variant_facets`'s (MG-2294)
@@ -7,14 +8,13 @@
  * dependency on `@materialgraph/products`, so the shapes are copied here and
  * `contract-parity.test.ts` keeps them honest.
  */
-import type { CorpusScope } from "./corpus-scope-types.js";
-import type { FilterGroups } from "./list-variants-types.js";
+import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
 export type ListVariantFacetsInput = {
-    /** 1–10 facetable attribute ids. Find them with `listAttributes()`. */
+    /** 1–10 facetable attribute ids, or `brand`. Find attribute ids with `listAttributes()`. */
     attributeIds: string[];
     /** The same kind-grouped filter tree `listVariants()` takes. */
     /** Count only this corpus scope; absent or `all` counts every variant. */
-    corpusScope?: CorpusScope;
+    searchCatalogueSubset?: SearchCatalogueSubset;
     filters?: FilterGroups;
     /** Top values per categorical or boolean facet, 1–50. Defaults to 10. */
     valuesPerFacet?: number;

package/list-variants-types.d.ts

@@ -9,11 +9,22 @@
  * copied here rather than imported. `contract-parity.test.ts` keeps this
  * mirror honest against the server types.
  */
-import type { CorpusScope } from "./corpus-scope-types.js";
+import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
 export type FilterOp = "in" | "not_in" | "all" | "exists" | "missing" | "eq" | "gt" | "gte" | "lt" | "lte";
 export type FilterTermCondition = {
     field: string;
     op: "in" | "all" | "not_in";
+    /**
+     * Meets the condition when the value is stated OR this phrase appears in the
+     * variant's text. One to 100 characters, on an `in` or `all` only, never a
+     * `not_in`. Term attributes only. Absent: the value must be stated.
+     */
+    orText?: string;
+    /**
+     * `"pass"` on a `not_in` lets the variants that do not state the attribute
+     * at all through. Absent: a variant must state the attribute to pass.
+     */
+    unstated?: "pass";
     values: string[];
 };
 export type FilterNumericCondition = {
@@ -26,24 +37,48 @@ export type FilterPresenceCondition = {
     op: "exists" | "missing";
 };
 /**
- * One filter condition, whichever of the three fully-required shapes. No
+ * A term stated under ANY of `fields` (2–8 distinct term attributes), for a
+ * concept stored under several of them. `in`: at least one of `values` under
+ * at least one field. `not_in`: at least one field stated at all, and none of
+ * `values` under any field.
+ */
+export type FilterAnyFieldCondition = {
+    fields: string[];
+    op: "in" | "not_in";
+    /**
+     * Meets the condition when the value is stated OR this phrase appears in the
+     * variant's text. One to 100 characters, on an `in` only, never a `not_in`.
+     * Absent: the value must be stated.
+     */
+    orText?: string;
+    /**
+     * `"pass"` on a `not_in` lets the variants that state none of the fields
+     * through. Absent: at least one field must be stated.
+     */
+    unstated?: "pass";
+    values: string[];
+};
+/**
+ * One filter condition, whichever of the four fully-required shapes. No
  * `unit` key (a numeric value is in the attribute's own canonical unit).
  */
-export type FilterCondition = FilterTermCondition | FilterNumericCondition | FilterPresenceCondition;
+export type FilterCondition = FilterTermCondition | FilterNumericCondition | FilterPresenceCondition | FilterAnyFieldCondition;
 /**
  * `filters`: kind-grouped, not a flat list (MG-2222) — `{terms, numbers,
- * presence}`. Every condition across all three arrays must match (AND); OR
- * within one field is `in`. Send only the arrays you need; an omitted or
- * empty array carries no conditions.
+ * presence, anyField}`. Every condition across all four arrays must match
+ * (AND); OR within one field is `in`, and `anyField` is OR across several
+ * fields. Send only the arrays you need; an omitted or empty array carries no
+ * conditions.
  */
 export type FilterGroups = {
     terms?: FilterTermCondition[];
     numbers?: FilterNumericCondition[];
     presence?: FilterPresenceCondition[];
+    anyField?: FilterAnyFieldCondition[];
 };
-/** `optionalFilters`: the same kind-grouped shape as `filters`, with every entry also carrying a required `weight` (1–10). Ranks matched items; never excludes. */
+/** `optionalFilters`: the same kind-grouped shape as `filters` but for `unstated`, with every entry also carrying a required `weight` (1–10). Ranks matched items; never excludes. */
 export type OptionalFilterGroups = {
-    terms?: (FilterTermCondition & {
+    terms?: (Omit<FilterTermCondition, "unstated"> & {
         weight: number;
     })[];
     numbers?: (FilterNumericCondition & {
@@ -52,6 +87,9 @@ export type OptionalFilterGroups = {
     presence?: (FilterPresenceCondition & {
         weight: number;
     })[];
+    anyField?: (Omit<FilterAnyFieldCondition, "unstated"> & {
+        weight: number;
+    })[];
 };
 export type OrderByEntry = {
     direction: "asc" | "desc";
@@ -59,23 +97,44 @@ export type OrderByEntry = {
     field: string;
 };
 export type ListVariantsInclude = "image" | "url";
-export type ListVariantsCollapse = "product";
+export type ListVariantsCollapse = "product" | "colorway";
+/** A region in OKLCh: lightness and chroma as bounds, hue an arc in degrees that wraps when its start is past its end, null for any hue. */
+export type ColorRegion = {
+    chroma: [number, number];
+    hue: [number, number] | null;
+    lightness: [number, number];
+};
+/**
+ * A measured-color condition. `in` keeps a variant with a large swatch inside
+ * `range`; `not_in` leaves those out and lets a variant with no measured
+ * color pass. `preferred` only orders and never narrows.
+ */
+export type ColorRangeCondition = {
+    /** The color's own point in the region, `#rrggbb`; it orders matches, nearest first. */
+    hex: string;
+    intent?: "required" | "preferred";
+    op: "in" | "not_in";
+    range: ColorRegion;
+};
 export type ListVariantsInput = {
     /** Attribute ids to project under each item's `specifications`. */
     attributes?: string[];
     /**
-     * `product`: one row per product, its lead colourway by the page's order,
-     * with `variantCount` saying how many colourways stand behind it. The
-     * cursor pages products.
+     * `product`: one row per product, its lead colorway by the page's order,
+     * with `variantCount` saying how many colorways stand behind it. The
+     * cursor pages products. `colorway`: one row per colorway, so a color
+     * sold on several substrates is one row.
      */
     collapse?: ListVariantsCollapse;
+    /** Up to four measured-color regions. */
+    colors?: ColorRangeCondition[];
     /**
      * Only variants in this corpus scope: the rows, the page and the cursor.
      * Absent or `all` is every variant.
      */
-    corpusScope?: CorpusScope;
+    searchCatalogueSubset?: SearchCatalogueSubset;
     cursor?: string;
-    /** Every condition, across `terms`/`numbers`/`presence`, must match. */
+    /** Every condition, across `terms`/`numbers`/`presence`/`anyField`, must match. */
     filters?: FilterGroups;
     include?: ListVariantsInclude[];
     /** 1–50; defaults to 10. */
@@ -89,10 +148,12 @@ export type ListVariantsInput = {
     /** Rank only — never excludes. */
     optionalFilters?: OptionalFilterGroups;
     orderBy?: OrderByEntry[];
+    /** Words each variant must name in its text, inside the filters. */
+    words?: string[];
 };
 /**
  * `score` sums the weights of the matched `optionalFilters`; `matched` lists
- * their positions in the flattened terms-then-numbers-then-presence order
+ * their positions in the flattened terms-then-numbers-then-presence-then-anyField order
  * the server reads `optionalFilters` in, not the caller's own array shape.
  */
 export type ListVariantsPreference = {
@@ -105,15 +166,36 @@ export type ListVariantsNotApplicable = {
     attributes?: string[];
     blocks?: string[];
 };
+/** What a sample represents, independently of its specification type. */
+export type SampleSubject = "material" | "paint_color_sample" | "unknown" | "conflict";
 /**
  * One list item: the compact identity needed to pick a variant, with image
  * and brand page only when requested (`include`) and selected attributes
  * under `specifications`. Leaner than `get_variant`'s item on purpose.
  */
 export type ListVariantsItem = {
-    category: string;
+    category: {
+        id: string;
+        name: string;
+    } | null;
+    categories: {
+        id: string;
+        name: string;
+    }[];
+    /** Null for a color sample or an unresolved subject. */
+    productType: {
+        id: string;
+        name: string;
+    } | null;
+    sampleSubject: SampleSubject;
+    /** The represented library color; null when none is established. */
+    colorOptionValueId: string | null;
     code: string | null;
-    image?: string | null;
+    /** Present only when `include` has `image`. */
+    image?: {
+        alt: string;
+        url: string;
+    } | null;
     brand: {
         id: string;
         name: string;
@@ -138,7 +220,7 @@ export type ListVariantsItem = {
 };
 export type ListVariantsOutput = {
     /** Explicit `{field: "variant", op: "in"}` ids that name a real variant outside the materials catalogue. Present only when at least one did. */
-    excludedByCorpusScope?: string[];
+    excludedBySearchCatalogueSubset?: string[];
     items: ListVariantsItem[];
     pageInfo: {
         endCursor: string | null;
@@ -146,8 +228,15 @@ export type ListVariantsOutput = {
     };
     /** False: nothing from this page on meets any `optionalFilters` entry. Absent when not measured. */
     preferenceMatchesRemain?: boolean;
-    /** Explicit `{field: "variant", op: "in"}` ids anywhere in `filters.terms` that did not resolve to an eligible variant in the requested `corpusScope`. */
+    /** Explicit `{field: "variant", op: "in"}` ids that name a variant in the materials catalogue that this list cannot show in the requested `searchCatalogueSubset`: retired, not orderable, or outside the scope. Read one with `getVariant`. Present only when at least one did. */
+    unavailableVariantIds?: string[];
+    /** Explicit `{field: "variant", op: "in"}` ids anywhere in `filters.terms` that name no variant at all. */
     unresolvedVariantIds?: string[];
     /** Filtered attributes no variant in scope states at all. Present only on an empty first page, so its absence means the empty page is a genuine no-match. */
     unstated?: string[];
+    /** Each requested word and whether any variant in scope names it. */
+    words?: {
+        matched: boolean;
+        word: string;
+    }[];
 };