@instruments/materialgraph 0.25.0 → 0.27.0

package/association-types.d.ts

@@ -10,6 +10,7 @@
  * with {@link PairingItem}, so the two can never be concatenated into one list.
  * Present them as separate sections, and never describe a pairing as available.
  */
+import type { CorpusScope } from "./corpus-scope-types.js";
 import type { Cursor, VariantId } from "./identifiers.js";
 import type { ProductTypeReceipt } from "./material-types.js";
 /**
@@ -21,24 +22,24 @@ import type { ProductTypeReceipt } from "./material-types.js";
  * score or used to rank. Declared associations carry no ranking at all: that is
  * the point of them.
  */
-export interface DeclaredProvenance {
+export type DeclaredProvenance = {
     /** The stored convention value (0.9 today). Never a per-edge measurement. */
     confidence: number;
     /** The manufacturer enumerated this association in their own catalog data. */
     basis: "manufacturer_declared";
     /** The provenance recorded on the edge — the manufacturer catalog feed. */
     source: "warehouse";
-}
+};
 /** The material the question was asked about, resolved to its identity. */
-export interface DeclaredAssociationSubject {
+export type DeclaredAssociationSubject = {
     variantId: VariantId;
     brand: string;
     product: string;
     /** The variant's own name; null when it is unnamed. */
     variantName: string | null;
-}
+};
 /** One declared association, plus why it is believed. */
-export interface DeclaredAssociation {
+export type DeclaredAssociation = {
     variantId: VariantId;
     brand: string;
     product: string;
@@ -54,16 +55,25 @@ export interface DeclaredAssociation {
     /** Review receipt; proposed types are never accepted categories. */
     productTypeReceipt: ProductTypeReceipt;
     declared: DeclaredProvenance;
-}
+    /** The accepted display category, for a card's kind pill. Null when none is accepted. */
+    kindLabel: string | null;
+    /** The accepted `price_tier` term (`$` to `$$$$$`). Absent means unknown, never cheap. */
+    priceTier?: string;
+    /**
+     * The eligible variants of this association's product, the set `listVariants`
+     * pages. Absent when the product has no eligible variant.
+     */
+    colourwayCount?: number;
+};
 /**
  * One page of declared associations.
  *
  * READ `totalAssociations`, NOT `associations.length`, when rendering a count
  * like "Compatible Finishes (128)": the array is one page (up to 48), the total
- * is the whole set for this subject, direction and corpus. A page is not a
+ * is the whole set for this subject, direction and corpus scope. A page is not a
  * corpus — walk `nextCursor` before making any claim about the full set.
  */
-export interface DeclaredAssociationsResponse {
+export type DeclaredAssociationsResponse = {
     subject: DeclaredAssociationSubject;
     /**
      * Constant discriminator. Its presence is how a caller tells a declared fact
@@ -71,35 +81,36 @@ export interface DeclaredAssociationsResponse {
      */
     kind: "declared_association";
     associations: DeclaredAssociation[];
-    /** The TRUE count for this subject, direction and corpus. Not the page size. */
+    /** The TRUE count for this subject, direction and corpus scope. Not the page size. */
     totalAssociations: number;
     /** How many associations this page carries. */
     returnedCount: number;
     /** Present only when another page exists; pass back verbatim as `cursor`. */
     nextCursor?: Cursor;
-}
+};
 /** Options for a declared-association read. */
-export interface AssociatedOptions {
+export type AssociatedOptions = {
     /**
      * Page size, 1–48 inclusive (default 24). The server rejects (400), not
      * clamps, values outside this range.
      */
     limit?: number;
     /**
-     * Source identity scope. `material_bank` returns associations pointing at a
-     * variant carrying a Material Bank SKU. A SKU alone does not establish current
-     * sampleability; use `sampleableOnly` for an accepted availability fact.
+     * Narrows the associations, `totalAssociations` and the cursor to one corpus
+     * scope. `materialBankOrderable` keeps associations pointing at a variant
+     * carrying a Material Bank id; absent or `all` is the whole declared set.
+     * Membership does not establish sampleability; use `sampleableOnly` for that.
      */
-    corpus?: "all" | "material_bank";
+    corpusScope?: CorpusScope;
     /** Return only associations whose effective sampleability is true. */
     sampleableOnly?: boolean;
     /**
      * The previous response's `nextCursor`, passed back verbatim. A cursor is
-     * bound to its subject, direction and corpus — replaying it against a
+     * bound to its subject, direction and corpus scope - replaying it against a
      * different one is a 400, never a silently different page.
      */
     cursor?: Cursor;
-}
+};
 export type ApplicabilitySubject = {
     kind: "product";
     id: string;
@@ -108,15 +119,15 @@ export type ApplicabilitySubject = {
     id: VariantId;
 };
 export type ApplicabilityCoverageState = "available" | "partial" | "none_declared" | "not_ingested" | "source_not_applicable" | "unavailable";
-export interface ApplicabilityCoverage {
+export type ApplicabilityCoverage = {
     state: ApplicabilityCoverageState;
     countKind: "exact" | "partial";
     declaredCount: number | null;
     sourceAuthority: string;
     sourceLocator: string;
     sourceRevision: string;
-}
-export interface ApplicabilityFact {
+};
+export type ApplicabilityFact = {
     id: string;
     subject: ApplicabilitySubject;
     finish: {
@@ -132,8 +143,8 @@ export interface ApplicabilityFact {
         revision: string;
     };
     lifecycle: "active";
-}
-export interface ApplicabilitySourceEntry {
+};
+export type ApplicabilitySourceEntry = {
     scope: {
         sourceAuthority: string;
         sourceLocator: string;
@@ -146,8 +157,8 @@ export interface ApplicabilitySourceEntry {
     facts: ApplicabilityFact[];
     /** Source endpoints that could not be resolved during reconciliation. */
     unresolved: UnresolvedApplicabilityEndpoint[];
-}
-export interface UnresolvedApplicabilityEndpoint {
+};
+export type UnresolvedApplicabilityEndpoint = {
     subjectLocator: string;
     subjectKind: "product" | "variant" | "unknown";
     finishLocator: string;
@@ -159,14 +170,14 @@ export interface UnresolvedApplicabilityEndpoint {
         locator: string;
         revision: string;
     };
-}
+};
 /** Source-grained response; sources are never merged or given hidden precedence. */
-export interface ApplicabilityResponse {
+export type ApplicabilityResponse = {
     kind: "manufacturer_declared_applicability";
     requestedSubject: ApplicabilitySubject;
     direction: "forward" | "reverse";
     sources: ApplicabilitySourceEntry[];
-}
+};
 export type ApplicabilityOptions = {
     subjectKind: "product";
     subjectId: string;

package/associations-client.d.ts

@@ -13,7 +13,7 @@
  * "available on".
  */
 import type { ApplicabilityOptions, ApplicabilityResponse, AssociatedOptions, DeclaredAssociationsResponse } from "./association-types.js";
-import { HttpTransport } from "./http-transport.js";
+import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 /**
  * THE QUESTION: "what finishes can I get on THIS chair?" — the fabrics,
@@ -33,7 +33,7 @@ import type { VariantId } from "./identifiers.js";
  *
  * @param variantId The PRODUCT variant. Opaque — pass back exactly what you were given.
  */
-export declare function declaredFinishes(transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<DeclaredAssociationsResponse>;
+export declare const declaredFinishes: (transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal) => Promise<DeclaredAssociationsResponse>;
 /**
  * THE QUESTION: "what furniture takes THIS fabric?" — the products the
  * MANUFACTURER declares a finish variant is available on (GET
@@ -48,6 +48,6 @@ export declare function declaredFinishes(transport: HttpTransport, variantId: Va
  *
  * @param variantId The FINISH variant. Opaque — pass back exactly what you were given.
  */
-export declare function declaredProducts(transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<DeclaredAssociationsResponse>;
+export declare const declaredProducts: (transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal) => Promise<DeclaredAssociationsResponse>;
 /** Read manufacturer-declared applicability without collapsing Product/Variant grain. */
-export declare function applicability(transport: HttpTransport, options: ApplicabilityOptions, signal?: AbortSignal): Promise<ApplicabilityResponse>;
+export declare const applicability: (transport: HttpTransport, options: ApplicabilityOptions, signal?: AbortSignal) => Promise<ApplicabilityResponse>;

package/associations-client.js

@@ -1,4 +1,3 @@
-import { HttpTransport } from "./http-transport.js";
 import { resolveOperation } from "./operations.js";
 /**
  * THE QUESTION: "what finishes can I get on THIS chair?" — the fabrics,
@@ -18,9 +17,7 @@ import { resolveOperation } from "./operations.js";
  *
  * @param variantId The PRODUCT variant. Opaque — pass back exactly what you were given.
  */
-export function declaredFinishes(transport, variantId, options, signal) {
-    return transport.requestJson(resolveOperation("list_associated_finishes"), { query: { variantId, ...options }, signal });
-}
+export const declaredFinishes = async (transport, variantId, options, signal) => await transport.requestJson(resolveOperation("list_associated_finishes"), { query: { variantId, ...options }, signal });
 /**
  * THE QUESTION: "what furniture takes THIS fabric?" — the products the
  * MANUFACTURER declares a finish variant is available on (GET
@@ -35,10 +32,6 @@ export function declaredFinishes(transport, variantId, options, signal) {
  *
  * @param variantId The FINISH variant. Opaque — pass back exactly what you were given.
  */
-export function declaredProducts(transport, variantId, options, signal) {
-    return transport.requestJson(resolveOperation("list_associated_products"), { query: { variantId, ...options }, signal });
-}
+export const declaredProducts = async (transport, variantId, options, signal) => await transport.requestJson(resolveOperation("list_associated_products"), { query: { variantId, ...options }, signal });
 /** Read manufacturer-declared applicability without collapsing Product/Variant grain. */
-export function applicability(transport, options, signal) {
-    return transport.requestJson(resolveOperation("get_applicability"), { query: options, signal });
-}
+export const applicability = async (transport, options, signal) => await transport.requestJson(resolveOperation("get_applicability"), { query: options, signal });

package/attribution-types.d.ts

@@ -13,12 +13,12 @@
 /**
  * The ranking basis, in one vocabulary across both ranked routes.
  *
- * The first five values are `search()`'s `mode` verbatim, and there
+ * The first seven values are `search()`'s `mode` verbatim, and there
  * `attribution.basis === mode` always. `"match"` is what `match()` reports;
  * that route has no `mode`, so this is the only field its outcomes can be
  * grouped by.
  */
-export type AttributionBasis = "image" | "colour" | "text" | "lexical" | "entity-browse" | "match";
+export type AttributionBasis = "image" | "colour" | "text" | "lexical" | "entity-browse" | "agent" | "attribute" | "match";
 /**
  * Envelope-level attribution receipt, on every successful ranked response.
  *
@@ -37,7 +37,7 @@ export type AttributionBasis = "image" | "colour" | "text" | "lexical" | "entity
  * Both fields are optional in the SDK types for one reason only: a server
  * predating MG-1131 does not send them. Every current response does.
  */
-export interface ResponseAttribution {
+export type ResponseAttribution = {
     /**
      * This response's stable id — the same value as the `X-Request-Id` header.
      * Opaque: store it verbatim, never parse it. Group your stored outcomes by
@@ -48,4 +48,4 @@ export interface ResponseAttribution {
     basis: AttributionBasis;
     /** ISO-8601 timestamp of when the response was assembled. */
     issuedAt: string;
-}
+};

package/brand-types.d.ts

@@ -5,15 +5,21 @@
  * The SDK's one OFFSET-paginated surface — everything else that pages uses an
  * opaque cursor. `meta` is where the page/corpus distinction is settled here.
  */
-export interface BrandsOptions {
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
+export type BrandsOptions = {
+    /**
+     * Which corpus to list from. Narrows the brands AND the corpus their counts
+     * are drawn from, inside the query. Absent or `"all"` is the whole graph.
+     */
+    corpusScope?: CorpusScope;
     /** Fuzzy name filter. Omit for the whole collection. */
     q?: string;
     /** Page size. Never a bound on the collection. */
     limit?: number;
     /** Row offset for the next page. Paired with `meta.hasMore`. */
     offset?: number;
-}
-export interface BrandCatalogListItem {
+};
+export type BrandCatalogListItem = {
     id: string;
     slug: string;
     name: string;
@@ -23,8 +29,10 @@ export interface BrandCatalogListItem {
     productCount: number;
     /** Variants ingested into MaterialGraph. A coverage figure, not a claim about the brand. */
     variantCount: number;
-}
-export interface BrandCatalogListPage {
+};
+export type BrandCatalogListPage = {
+    /** Present only when a narrowing scope applied; absence means the whole graph. */
+    corpusScope?: CorpusScopeReceipt;
     /** THIS PAGE. Its length is `meta.count`, never `meta.total`. */
     items: BrandCatalogListItem[];
     /**
@@ -41,4 +49,4 @@ export interface BrandCatalogListPage {
         offset: number;
         hasMore: boolean;
     };
-}
+};

package/brands-client.d.ts

@@ -1,48 +1,17 @@
 /**
- * The BRAND lens: the catalogue collection, one brand's profile, and one
- * brand's whole colour range, as thin wrappers over the shared
- * {@link HttpTransport}. `MaterialGraphClient.brands` / `.brand` /
- * `.brandColourDeck` delegate here; the contract lives in this file.
+ * The BRAND lens: the catalogue collection, as a thin wrapper over the shared
+ * {@link HttpTransport}. `MaterialGraphClient.brands` delegates here; the
+ * contract lives in this file.
  *
- * A brand is a COMPANY, not a catalogue. Every count these reads return is
+ * A brand is a COMPANY, not a catalogue. Every count this read returns is
  * coverage — what MaterialGraph has ingested — and never a claim about how
  * many products the maker sells.
  */
 import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
-import type { BrandFanDeck } from "./fan-deck-types.js";
-import { HttpTransport } from "./http-transport.js";
-import type { BrandOptions, BrandProfileResponse } from "./types.js";
+import type { HttpTransport } from "./http-transport.js";
 /**
  * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
  * one OFFSET-paginated surface: read `meta.total` for the collection size and
- * `meta.hasMore` to keep walking. Instead use {@link brandProfile} for one
- * brand's profile and trade signals.
+ * `meta.hasMore` to keep walking.
  */
-export declare function listBrands(transport: HttpTransport, options?: BrandsOptions, signal?: AbortSignal): Promise<BrandCatalogListPage>;
-/**
- * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
- * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
- * key means no value is held — never infer `false`. Instead use `search()` to
- * find their materials; this describes the company, not the catalog.
- */
-export declare function brandProfile(transport: HttpTransport, brandSlug: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
-/**
- * THE QUESTION: "show me this maker's whole range, the way a fan deck reads."
- * Colours grouped by family — creams together, then greys, then browns — and
- * ordered light to dark within each. No stored scalar produces that order: a
- * lightness sort interleaves the whites and the creams, and a reader loses the
- * sense that they are looking at two different families.
- *
- * Deliberately unpaginated, so there is no cursor to walk and no all-brands
- * form: family order is only correct over a COMPLETE range, because the greys
- * cannot be placed against the browns while holding one page of each. A range
- * past the server ceiling reports `truncatedAt` rather than being quietly cut,
- * and an absent `truncatedAt` means the deck is whole.
- *
- * Every swatch carries the maker's PUBLISHED hex — this read never returns a
- * colour derived from imagery. For "what is near this colour, across makers"
- * use `byColour()` instead.
- *
- * @param brandSlug The brand's slug, as `listBrands()` reports it.
- */
-export declare function brandColourDeck(transport: HttpTransport, brandSlug: string, signal?: AbortSignal): Promise<BrandFanDeck>;
+export declare const listBrands: (transport: HttpTransport, options?: BrandsOptions, signal?: AbortSignal) => Promise<BrandCatalogListPage>;

package/brands-client.js

@@ -1,45 +1,15 @@
-import { HttpTransport } from "./http-transport.js";
 import { resolveOperation } from "./operations.js";
 /**
  * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
  * one OFFSET-paginated surface: read `meta.total` for the collection size and
- * `meta.hasMore` to keep walking. Instead use {@link brandProfile} for one
- * brand's profile and trade signals.
+ * `meta.hasMore` to keep walking.
  */
-export function listBrands(transport, options = {}, signal) {
-    return transport.requestJson(resolveOperation("list_brands"), {
-        query: { q: options.q, limit: options.limit, offset: options.offset },
-        signal,
-    });
-}
-/**
- * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
- * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
- * key means no value is held — never infer `false`. Instead use `search()` to
- * find their materials; this describes the company, not the catalog.
- */
-export function brandProfile(transport, brandSlug, options, signal) {
-    return transport.requestJson(resolveOperation("get_brand_profile"), { query: { q: options?.q }, pathParams: { brandSlug }, signal });
-}
-/**
- * THE QUESTION: "show me this maker's whole range, the way a fan deck reads."
- * Colours grouped by family — creams together, then greys, then browns — and
- * ordered light to dark within each. No stored scalar produces that order: a
- * lightness sort interleaves the whites and the creams, and a reader loses the
- * sense that they are looking at two different families.
- *
- * Deliberately unpaginated, so there is no cursor to walk and no all-brands
- * form: family order is only correct over a COMPLETE range, because the greys
- * cannot be placed against the browns while holding one page of each. A range
- * past the server ceiling reports `truncatedAt` rather than being quietly cut,
- * and an absent `truncatedAt` means the deck is whole.
- *
- * Every swatch carries the maker's PUBLISHED hex — this read never returns a
- * colour derived from imagery. For "what is near this colour, across makers"
- * use `byColour()` instead.
- *
- * @param brandSlug The brand's slug, as `listBrands()` reports it.
- */
-export function brandColourDeck(transport, brandSlug, signal) {
-    return transport.requestJson(resolveOperation("brand_colour_deck"), { pathParams: { brandSlug }, signal });
-}
+export const listBrands = async (transport, options = {}, signal) => await transport.requestJson(resolveOperation("list_brands"), {
+    query: {
+        corpusScope: options.corpusScope,
+        limit: options.limit,
+        offset: options.offset,
+        q: options.q,
+    },
+    signal,
+});

package/by-colour-types.d.ts

@@ -11,10 +11,10 @@ import type { VariantId } from "./identifiers.js";
 import type { QueryUnderstanding } from "./query-understanding-types.js";
 import type { OklabTriple, OpenEnum, PaletteSwatch } from "./types.js";
 /** Coarse group + fine type of a colour match's primary product type. */
-export interface MatchCategory {
+export type MatchCategory = {
     group: string | null;
     type: string | null;
-}
+};
 /**
  * One colour-palette match.
  *
@@ -23,7 +23,7 @@ export interface MatchCategory {
  * colour"), never as a stated colour specification. `hex` itself may be the
  * manufacturer's published colour — read `sourceBasis` before repeating it.
  */
-export interface ByColourMatch {
+export type ByColourMatch = {
     /** Opaque — round-trip verbatim. */
     variantId: VariantId;
     brand: string;
@@ -37,11 +37,22 @@ export interface ByColourMatch {
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
+    /**
+     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest.
+     * ABSENT means no hash is on record, never that there is no image.
+     */
+    imageSha256?: string;
     hex: string | null;
     distance: number;
     closeness: number;
     category: MatchCategory | null;
     oklab: OklabTriple | null;
+    /**
+     * Whether the reported `hex` has a hue compatible with the query colour, by
+     * colorscope's `isHueCompatible` at its default thresholds. A flag, never a
+     * gate. ABSENT when the match has no hex or the query was a palette.
+     */
+    hueCompatible?: boolean;
     /**
      * Where `hex` came from — PER MATCH, never per response. `"declared"`: the
      * manufacturer published it (a paint's own colour system), so it may be
@@ -78,17 +89,17 @@ export interface ByColourMatch {
      * manufacturer.
      */
     palette?: ByColourSwatch[];
-}
+};
 /** A {@link PaletteSwatch} on the colour lane, where `oklab` is always derived. */
-export interface ByColourSwatch extends PaletteSwatch {
+export type ByColourSwatch = {
     /** `hex` in OKLab — guaranteed present on this surface. */
     oklab: OklabTriple;
-}
+} & PaletteSwatch;
 /**
  * Receipt for the `family` filter — ABSENT when none was asked for, so absence
  * means "no gate ran", never "a gate that dropped nothing".
  */
-export interface ColourFamilyGate {
+export type ColourFamilyGate = {
     /** The colorscope taxonomy family id the gate kept (normalised). */
     family: string;
     /** Candidates the gate examined — the retrieved pool. NOT a corpus total. */
@@ -108,45 +119,49 @@ export interface ColourFamilyGate {
      * boundary.
      */
     droppedOnPublishedHex?: number;
-}
+};
 /** Receipt for the hard category gate and its treatment of unknown typing. */
-export interface ColourCategoryGate {
-    /** Category names or keys the caller asked the gate to keep. */
+export type ColourCategoryGate = {
+    /**
+     * Present when the caller named no category: the page then holds surface
+     * materials only (the `materials` product-type groups, listed in
+     * `requested`), so lights, taps and furniture do not answer a colour.
+     */
+    defaulted?: true;
+    /** Category names or keys the gate kept: the caller's, or the default groups. */
     requested: string[];
     /** Only accepted primary product types can establish membership. */
     requiresAcceptedPrimaryProductType: true;
     /** Unknown/unclassified variants were ineligible, not proven non-members. */
     unclassifiedVariantsExcluded: true;
-}
+};
 /**
  * Receipt for the colour-identity collapse that turns a variant-grain ranking
  * into a page of TILES — one per (brand, product, dominant hex), one per stored
- * photograph. The live endpoint always sends it; it is optional here only so
- * responses captured before the collapse existed still type-check.
+ * photograph. Only responses stored before the one search carry it: the one
+ * search pages one row per product, so nothing collapses now.
  */
-export interface ColourCollapse {
+export type ColourCollapse = {
     /** Ranked rows the collapse examined — this page's pool, never a corpus total. */
     considered: number;
     /** Rows dropped for repeating a better-ranked row's brand, product and hex. */
     droppedByIdentity: number;
     /** Rows dropped for resolving to a better-ranked row's stored photograph. */
     droppedBySharedImage: number;
-}
+};
 /**
  * Receipt naming which retrieval lane answered, and the colours it actually ran
  * on. The live endpoint always sends it.
  *
- * Two lanes answer two different questions. A ONE-COLOUR query is a CONTAINMENT
- * question — which materials hold a swatch near this colour — and is answered as
- * a bounded OKLab ball over stored palette swatches. A multi-colour query is a
- * SIMILARITY question — which palettes as a whole resemble this palette — and is
- * answered by nearest-neighbour over the palette embedding. The two rank on
- * different geometries, so `colourDistance` on a match means a different thing
- * in each and is NOT comparable across them.
+ * Every live page says `index`: the one search's colour key, the colour's
+ * family on the search index, nearest first by OKLab distance. A palette is
+ * ordered by its first colour, and `droppedColours` names the rest.
+ * `containment` and `palette` appear only on responses stored before the one
+ * search.
  */
-export interface ColourLaneReceipt {
+export type ColourLaneReceipt = {
     /** Which lane answered. Widened so a new server lane still type-checks. */
-    lane: OpenEnum<"containment" | "palette">;
+    lane: OpenEnum<"index" | "containment" | "palette">;
     /** Why this lane, in one sentence, for a human reader. */
     reason: string;
     /**
@@ -169,9 +184,9 @@ export interface ColourLaneReceipt {
      * result is not evidence that nothing holds them.
      */
     droppedColours: string[];
-}
+};
 /** The `search/colours` response. */
-export interface ByColourResponse {
+export type ByColourResponse = {
     query: {
         /** Raw query provenance, when supplied. */
         q?: string;
@@ -234,9 +249,9 @@ export interface ByColourResponse {
     corpusScope?: CorpusScopeReceipt;
     /** Shared standard-search query-understanding receipt. */
     understanding?: QueryUnderstanding;
-}
+};
 /** Params for `search/colours`. */
-export interface ByColourParams {
+export type ByColourParams = {
     /** Raw material-domain query provenance for shared query understanding. */
     q?: string;
     /** A single hex (with or without `#`). */
@@ -247,7 +262,11 @@ export interface ByColourParams {
     l?: number;
     a?: number;
     b?: number;
-    /** HARD category filter — display names or taxonomy ids (repeatable). */
+    /**
+     * HARD category filter — display names or taxonomy ids (repeatable). Absent,
+     * the page holds surface materials only (`categoryGate.defaulted`), so
+     * lights, taps and furniture do not answer a colour.
+     */
     category?: string | string[];
     /**
      * HARD brand filter (repeatable) — a canonical brand id, exact brand SLUG
@@ -283,11 +302,19 @@ export interface ByColourParams {
      * drop.
      */
     family?: string;
-    /** Single-colour order; omitted keeps representative browsing order. */
+    /**
+     * Kept so existing callers still parse: every page is ordered nearest first
+     * by the one search's colour key, so both values return the same page.
+     */
     order?: "representative" | "nearest";
+    /**
+     * Order by the colour of an existing Variant: materials the same colour as
+     * this one. Used when no hex, colour or OKLab triple is given.
+     */
+    variantId?: string;
     /** Maximum OKLab distance to each match's reported hex. Single-colour only. */
     maxColourDistance?: number;
     /** Narrow retrieval inside the server query; absent means the whole graph. */
     corpusScope?: CorpusScope;
     limit?: number;
-}
+};