@instruments/materialgraph 0.32.0 → 0.35.0

package/response-schemas.js

@@ -10,7 +10,7 @@
  * ```ts
  * import { responseSchema } from "@instruments/materialgraph/response-schemas";
  *
- * createTool({ outputSchema: responseSchema("search_materials_post"), … });
+ * createTool({ outputSchema: responseSchema("search_variants"), … });
  * ```
  *
  * Keyed by OpenAPI `operationId`, the same id `SDK_OPERATIONS` pairs with each

package/samplize-catalogue-types.d.ts

@@ -30,7 +30,7 @@ export type SamplizeCatalogueProduct = {
     /** The primary sample variant count, never an aggregate of product orders. */
     demand: SamplizeDemand | null;
     collectionMemberships: SamplizeCollectionMembership[];
-    colourAnalysis: Record<string, unknown>;
+    colorAnalysis: Record<string, unknown>;
     oklab: {
         L: number;
         a: number;
@@ -51,7 +51,7 @@ export type SamplizeCatalogueProduct = {
 };
 export type SamplizeCataloguePage = {
     schemaVersion: 2;
-    corpusScope: "samplizeCatalogue";
+    searchCatalogueSubset: "samplizeCatalogue";
     sourceVersion: string;
     source: Record<string, unknown>;
     /** Number of eligible records matching the supplied filters. */
@@ -66,7 +66,7 @@ export type SamplizeHexObservation = {
     publisher: string;
     source: string;
     sourceUrl: string | null;
-    sourceBasis: string;
+    valueOrigin: string;
     observedAt: string | null;
     differsFromSelected: boolean;
 };
@@ -83,7 +83,7 @@ export type SamplizeLrvObservation = {
 export type SamplizeDemand = {
     field: "recently_ordered_count";
     sourceVariantId: string;
-    grain: "shopify_variant";
+    defaultAttributeLevel: "shopify_variant";
     recentlyOrderedCount: number;
     /** The publisher does not supply the time window. */
     window: null;

package/samplize-colorvec.js

@@ -4,7 +4,7 @@ export const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = EMBEDDING_VERSION;
 const decodeVector = (encoded) => {
     const bytes = Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
     if (bytes.length !== EMBEDDING_VECTOR_SIZE * 4) {
-        throw new Error("Invalid colour vector size.");
+        throw new Error("Invalid color vector size.");
     }
     const view = new DataView(bytes.buffer);
     return Array.from({ length: EMBEDDING_VECTOR_SIZE }, (_, i) => view.getFloat32(i * 4, true));
@@ -13,7 +13,7 @@ const facets = ["brand", "family", "lightness", "intensity"];
 const identityOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 export const samplizeSolidColorVector = (hex) => {
     if (!/^#[0-9a-f]{6}$/i.test(hex)) {
-        throw new Error("A six-digit published colour is required.");
+        throw new Error("A six-digit published color is required.");
     }
     return paletteToEmbedding([{ hex, proportion: 1 }], { validateOklab: true });
 };
@@ -78,12 +78,12 @@ export const selectSamplizeEligiblePaints = (paints, input) => {
 export const createSamplizeColorVecIndex = (cache) => {
     if (cache.embeddingVersion !== EMBEDDING_VERSION ||
         cache.rankingVersion !== SAMPLIZE_COLORVEC_RANKING_VERSION) {
-        throw new Error("The colour cache uses an incompatible embedding or ranking version. Refresh it before searching.");
+        throw new Error("The color cache uses an incompatible embedding or ranking version. Refresh it before searching.");
     }
     if (!cache.sourceVersion ||
         !cache.dictionaryVersion ||
         !Number.isFinite(Date.parse(cache.generatedAt))) {
-        throw new Error("The colour cache is missing its provenance.");
+        throw new Error("The color cache is missing its provenance.");
     }
     const paints = cache.paints.map((p) => ({
         ...p,
@@ -95,7 +95,7 @@ export const createSamplizeColorVecIndex = (cache) => {
             paint.vector.length !== EMBEDDING_VECTOR_SIZE ||
             !paint.vector.every(Number.isFinite) ||
             ![paint.oklab.L, paint.oklab.a, paint.oklab.b].every(Number.isFinite)) {
-            throw new Error("The colour cache contains invalid or duplicate paint records.");
+            throw new Error("The color cache contains invalid or duplicate paint records.");
         }
         identities.add(paint.variantId);
     }
@@ -128,7 +128,7 @@ export const createSamplizeColorVecIndex = (cache) => {
                 palette.some((p) => !Number.isFinite(p.proportion) ||
                     p.proportion <= 0 ||
                     p.proportion > 1)) {
-                throw new Error("Supply up to twelve positive image colour shares.");
+                throw new Error("Supply up to twelve positive image color shares.");
             }
             const total = palette.reduce((sum, p) => sum + p.proportion, 0);
             const buckets = palette.map((p, position) => ({

package/{corpus-scope-types.d.ts → search-catalogue-subset-types.d.ts}

@@ -43,15 +43,15 @@ import type { OpenEnum } from "./types.js";
  * that were never in the Material Bank feed; if you mean orderable, use one of
  * the channel-backed scopes above.
  */
-export type CorpusScope = OpenEnum<"samplizeCatalogue" | "all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaAndCatalogue" | "materialBankNaOrderable" | "materialBankOrderable">;
+export type SearchCatalogueSubset = OpenEnum<"samplizeCatalogue" | "all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaAndCatalogue" | "materialBankNaOrderable" | "materialBankOrderable">;
 /**
  * The corpus a response AND its counts were drawn from. Present only when a
  * narrowing scope applied — absence means the whole graph. Read it alongside
  * the counts: a short page under a scope is a small SCOPED corpus, never a
  * truncated one.
  */
-export type CorpusScopeReceipt = {
-    scope: CorpusScope;
+export type SearchCatalogueSubsetReceipt = {
+    scope: SearchCatalogueSubset;
     /** What the scope admits, in one sentence, for a human reader. */
     description: string;
 };

package/search-variants-types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module search-variants-types
+ * @description Hand-maintained mirror of `search_variants`'s (MG-2223) input
+ * and output wire shapes. The source of truth is
+ * `packages/products/src/search-variants/search-variants.ts` and
+ * `compose-conditions.ts`; this SDK has no runtime dependency on
+ * `@materialgraph/products`, so the shapes are copied here and
+ * `contract-parity.test.ts` keeps them honest.
+ */
+import type { ColorRangeCondition, FilterGroups, ListVariantsInclude, ListVariantsOutput, OptionalFilterGroups } from "./list-variants-types.js";
+import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
+/** Switches one of a previous answer's `choices`: its `handle`, and the `group` and `id` of the alternative to read it as. */
+export type SearchVariantsSelection = {
+    group: string;
+    handle: string;
+    id: string;
+};
+export type SearchVariantsInput = {
+    /** Attribute ids to project under each item's `specifications`, as `listVariants()` takes. */
+    attributes?: string[];
+    /** The previous page's `pageInfo.endCursor`. Tied to the vocabulary version the query was read against, and not a `listVariants()` cursor. */
+    cursor?: string;
+    /** Optional per-item fields, as `listVariants()` takes; `image` adds each row's image. */
+    include?: ListVariantsInclude[];
+    /** 1–50; defaults to 10. */
+    limit?: number;
+    /** What to find, in plain words. 1–200 characters. */
+    query: string;
+    /** Only this corpus scope. Absent or all: every variant. */
+    searchCatalogueSubset?: SearchCatalogueSubset;
+    /** Up to eight choices to switch, from the previous answer's `choices`. */
+    selections?: SearchVariantsSelection[];
+};
+/**
+ * What became of one phrase of the query. `filter` narrowed the page,
+ * `preference` only ranked it, `not_applied` did neither and `note` says why.
+ */
+export type SearchVariantsUnderstood = {
+    applied: "filter" | "preference" | "not_applied";
+    /** The parser's condition id. */
+    id: string;
+    kind: "category" | "brand" | "term" | "number" | "color" | "paint";
+    /** What the words were read as. */
+    label: string;
+    note?: string;
+    /** The query words it came from. */
+    text: string;
+};
+/** One reading of an ambiguous phrase. */
+export type SearchVariantsReading = {
+    group: string;
+    id: string;
+    kind: string;
+    label: string;
+};
+/** A phrase with more than one meaning: the reading used, and the others a caller may switch to by `handle`. */
+export type SearchVariantsChoice = {
+    alternatives: SearchVariantsReading[];
+    basis: string;
+    handle: string;
+    reason: string;
+    selected: SearchVariantsReading;
+    text: string;
+};
+/** The `listVariants()` page, with how the words were read beside it. */
+export type SearchVariantsOutput = ListVariantsOutput & {
+    choices?: SearchVariantsChoice[];
+    /** The measured-color regions that ran. */
+    colors?: ColorRangeCondition[];
+    /** Words corrected to catalogue spellings. */
+    corrections?: {
+        correction: string;
+        word: string;
+    }[];
+    /** The `listVariants()` filters that ran: send them, with `optionalFilters` and `name`, to `listVariants()` to narrow or widen this search. */
+    filters?: FilterGroups;
+    /** The paint name looked up, as `listVariants()` takes it. */
+    name?: string;
+    /** A row per product, or per variant for a paint or color. */
+    oneRowPer: "product" | "variant";
+    /** The `listVariants()` preferences that ran. */
+    optionalFilters?: OptionalFilterGroups;
+    /** How the search ended. */
+    outcome: "page" | "no_match" | "nothing_understood" | "out_of_scope" | "brand_not_in_catalogue";
+    /** The fixed search scope, also present in `filters`. */
+    scope?: FilterGroups;
+    /** One entry per phrase the parser read, in the parser's order. */
+    understood: SearchVariantsUnderstood[];
+    /** Words nothing in the vocabulary could read. */
+    unresolved?: string[];
+};

package/types.d.ts

@@ -1,4 +1,6 @@
-import type { ResponseAttribution } from "./attribution-types.js";
+import type { Cursor, ProductId, VariantId } from "./identifiers.js";
+import type { FilterOp } from "./list-variants-types.js";
+import type { MaterialTile } from "./material-types.js";
 /**
  * Hand-mirrored wire types for the MaterialGraph public API (spec 0.5.0).
  * These interfaces intentionally have NO runtime dependency on any
@@ -19,52 +21,21 @@ import type { ResponseAttribution } from "./attribution-types.js";
  *     are canonical vocabulary you discover.
  *  2. **Absent is not false.** An optional field that is missing means UNKNOWN,
  *     not "known to be absent in reality" — most dangerously for booleans.
- *     Values carry `confidence` and `sourceBasis`; report them as claims.
- *  3. **A page is not a corpus.** `results.length` is this page.
- *     {@link CountedTotal} — with the `basis` it states — is the claim about the
- *     match set. Follow the cursor for the rest, and never report a page size as
- *     a total.
+ *     Values carry `confidence` and `valueOrigin`; report them as claims.
+ *  3. **A page is not a corpus.** A list is this page. Follow the cursor for
+ *     the rest, and never report a page size as a total.
  */
-import type { CorpusScope } from "./corpus-scope-types.js";
-import type { Cursor, ProductId, VariantId } from "./identifiers.js";
-import type { FilterOp } from "./list-variants-types.js";
-import type { MaterialTile } from "./material-types.js";
-import type { SearchMode, SearchResponseExplainReceipts } from "./search-response-receipt-types.js";
-export type { SearchResponse } from "./search-response-types.js";
-export type * from "./search-response-receipt-types.js";
+import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
 export type OpenEnum<T extends string> = T | (string & {});
 export type { JsonValue } from "./json-value-types.js";
-/**
- * One palette swatch of a material's main image — colour DERIVED FROM PRODUCT
- * IMAGERY, so read it as visual likeness, never as a declared colour spec.
- */
-export type PaletteSwatch = {
-    hex: string;
-    proportion: number;
-    /** Stored human colour name for the swatch, when one was extracted. */
-    name?: string | null;
-    /**
-     * `hex` in OKLab, derived server-side so you can sort or measure swatches
-     * without converting them yourself. Additive, so optional: the colour lane and
-     * the material record carry it, other surfaces may not, and absent means "not
-     * derived here" — never "achromatic".
-     */
-    oklab?: OklabTriple;
-};
-/** Loose colour metadata for a search result's main image; every field is independently optional. */
-export type ColourMeta = {
-    mood?: string;
-    dominantFamily?: string;
-    dominantHex?: string;
-};
 /** OKLab triple. */
 export type OklabTriple = {
     l: number;
     a: number;
     b: number;
 };
-/** The material's dominant-colour block (tile/detail projections). */
-export type MaterialColour = {
+/** The material's dominant-color block (tile/detail projections). */
+export type MaterialColor = {
     dominantHex: string | null;
     hsl: {
         h: number;
@@ -78,210 +49,6 @@ export type MaterialColour = {
 /** Where the served image came from. */
 export type ImageSource = OpenEnum<"r2" | "origin">;
 export type { MaterialAvailability, MaterialTile } from "./material-types.js";
-/**
- * One material in a search / match result list.
- *
- * ABSENT IS NOT FALSE. The optional fields here (`colourMeta`, `signals`,
- * `retired`, `productType`) are absent when the request did not ask for them or
- * the graph holds no answer — never because the answer is "no". A missing
- * `retired` is not "still current".
- */
-export type SearchResultItem = {
-    /** This hit's attribution key — see {@link ResponseAttribution}. Opaque. */
-    resultId?: string;
-    /** Accepted sampleability fact. Absent means unknown, never false. */
-    sampleable?: boolean;
-    /** Opaque — round-trip verbatim into `getVariant()`, `pairings()`, `similarTo`. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    brandSlug: string | null;
-    productId: ProductId | null;
-    /**
-     * The variant's Material Bank SKU, unlike our opaque `variantId`; this is the
-     * id you are expected to match
-     * against Material Bank's own catalogue, so a result list can be joined to a
-     * cart, an order or an analytics event without a per-result lookup.
-     * Populated on EVERY lane: `search()` (all four arms), `match()`, and
-     * full search responses.
-     * ABSENT means no MB identity is known for the variant — never that the SKU
-     * cannot be ordered. Presence identifies the source; it does not establish sampleability.
-     */
-    materialBankId?: string;
-    manufacturerCode?: string;
-    projectSaveCapability?: "allowed";
-    sourceStatus?: "provisional";
-    /**
-     * What kind of material this is — the variant's primary product type, as a
-     * display name (`"Wall Tile"`, `"Modular Carpet"`, `"Interior Paint"`).
-     *
-     * This is the field that lets you tell a wall tile from a bar stool without
-     * parsing `product`. Before it existed, callers grading Match results had to
-     * regex the product's NAME, and one such grader scored pendant lights and
-     * electrical sockets as correct answers for a wall — because they are neither
-     * a stool nor a chair.
-     *
-     * ABSENT means no primary type is on record for the variant. Unknown, never
-     * "uncategorised" and never "not a material".
-     */
-    productType?: string;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    /**
-     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest. Key a
-     * cache or dedupe on it rather than the URL. ABSENT means no hash is on
-     * record, never that there is no image.
-     */
-    imageSha256?: string;
-    hasImage: boolean;
-    /**
-     * How many eligible variants the row's product has, the same set
-     * `listVariants` pages, so a follow-up list returns this many: the card's
-     * "12 colourways". ABSENT means the product is unknown or has no eligible
-     * variant.
-     */
-    variantCount?: number;
-    palette: PaletteSwatch[];
-    colourMeta?: ColourMeta;
-    /**
-     * Present when this material's imagery carries nothing beyond ONE colour, so
-     * a surface should render that colour rather than the photograph — a paint's
-     * photo is a flat fill, and the colour we hold structured beats a JPEG of it.
-     *
-     * The hex is EXTRACTED FROM the product image (a visual likeness), never a
-     * manufacturer-declared colour specification; do not present it as one.
-     * ABSENT means the question was not established (unknown product type,
-     * unextracted or multi-swatch palette) and the image should be rendered — it
-     * NEVER asserts "this is not a coating".
-     */
-    colourChip?: {
-        hex: string;
-    };
-    /** Selected mode's weighted primary score; see maxScore. */
-    score: number;
-    retired?: boolean;
-    /**
-     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
-     * attribute id. ABSENT entirely when `returnAttributes` was not sent.
-     *
-     * Three states, all different, and reading them as two is the mistake this
-     * shape exists to prevent: no `attributes` key means you did not ask; a key
-     * whose value is `null` means this material carries no accepted value for that
-     * attribute; anything else is what the graph holds. Values resolve with the
-     * normal variant-over-product precedence, and an array is a multi-valued
-     * attribute rather than a list of candidates.
-     */
-    attributes?: Record<string, string | string[] | null>;
-};
-/**
- * A feed total with its honesty basis — THE CLAIM ABOUT THE MATCH SET, which is
- * a different number from `results.length` (this page).
- *
- * `exact` — the true count. Say "473 materials match".
- * `lowerBound` — a floor (cap hit or an ANN-pool bound). Say "at least
- * 1,000", never "1,000". Never a silent approximation.
- * `unknown` — the count query itself faulted (MG-2104): `value` is the pool
- * this page was drawn from, NOT a claim about the corpus — do not print it as
- * a bound. Check the response's `degraded.parts` for `"variant-count"`.
- *
- * Only `lowerBound` ever tells you a cap was hit. The SEARCH feed counts
- * exactly to 1,000 and reports a floor beyond it, because it counts over
- * attribute and tsquery universes where an unbounded count is a timeout. Read
- * `basis`; never assume a ceiling.
- *
- * A response with no `counts` at all states no total: `count: true` is opt-in,
- * and the absence of a total is not a total of zero.
- */
-export type CountedTotal = {
-    value: number;
-    basis: OpenEnum<"exact" | "lowerBound" | "unknown">;
-};
-/**
- * One value within a facet's counts: the CANONICAL token (send it back verbatim
- * as a filter term), its display label, and how many variants in the counted
- * set carry it.
- */
-export type SearchFacetValue = {
-    value: string;
-    label: string;
-    variants: number;
-};
-/**
- * One facet's counts. `basis` is the honesty label, and — per the negotiated
- * MG-1010 contract — its union is CLOSED: exactly `"exact"` or `"lowerBound"`,
- * never widened, which is why it is not an {@link OpenEnum}. `exact` — each
- * `variants` figure is a true count under the query's whole predicate
- * (filter-driven queries only). `lowerBound` — counted over the ranked
- * candidate pool (`SearchFacets.poolSize`), so each figure is a floor; a
- * pool-counted value is NEVER `exact`. `truncated` is ALWAYS present: true
- * when more distinct values existed beyond the reported list.
- */
-export type SearchFacetCount = {
-    values: SearchFacetValue[];
-    truncated: boolean;
-    basis: "exact" | "lowerBound";
-};
-/**
- * A requested facet that was not counted, with its reason: `"unsupported"` —
- * the id is known but facet counting does not cover it; `"timeout"` — the
- * facet stage's own time budget expired, and the RESULTS are unaffected (the
- * rail could not count; the page is intact). Render it as "couldn't count",
- * never as zero.
- */
-export type SearchAbsentFacet = {
-    facetId: string;
-    reason: OpenEnum<"unsupported" | "timeout">;
-};
-/**
- * Per-query facet counts (MG-1010) — present ONLY when the request sent
- * `facetCounts`. `counts` is keyed by requested facet id; every requested
- * facet not in `absent` has an entry, including empty ones. `poolSize` is
- * present exactly when the counts are pool-derived.
- */
-export type SearchFacets = {
-    poolSize?: number;
-    requested: string[];
-    absent: SearchAbsentFacet[];
-    counts: Record<string, SearchFacetCount>;
-};
-/**
- * The search response envelope. `view` discriminates the `results` union:
- * `"full"` (default) carries {@link SearchResultItem}s, `"card"` the lean
- * {@link SearchCardItem}s. Every other field is shared.
- *
- * A PAGE, NOT A CORPUS. `results.length` is what you were handed; follow
- * `cursor` for the rest. "I found 24 materials" is wrong whenever `limit` was
- * 24.
- */
-export type SearchData = {
-    /** Result attribution — see {@link ResponseAttribution}. `basis` is `mode` verbatim here. */
-    attribution?: ResponseAttribution;
-    /**
-     * Present when a word no material carries was corrected before the search
-     * ran: the page shows results for `to` (ADR 0031).
-     */
-    correctedQuery?: {
-        from: string;
-        to: string;
-    };
-    view: OpenEnum<"full" | "card">;
-    /** THIS PAGE. Its length is a page size, never a total. */
-    results: SearchResultItem[];
-    /** Always empty: the one search offers no refinements. */
-    suggestions: never[];
-    mode: SearchMode;
-    /** The first result's rank score, 1. */
-    maxScore: number;
-    cursor?: Cursor;
-    /** One or more sentences written for a person; absent when there is nothing to say. */
-    note?: string;
-    timings?: Record<string, number>;
-    /** Echo of the resolved query input (raw image bytes/vector are never echoed). */
-    query?: Record<string, unknown>;
-    /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
-    seed?: MaterialTile | Record<string, unknown>;
-} & SearchResponseExplainReceipts;
 export type DemandMomentum = {
     state: OpenEnum<"rising" | "fading" | "stable" | "emerging" | "insufficient_volume">;
     percentChange: number | null;
@@ -311,13 +78,13 @@ export type ProjectTypeShare = {
  *    carries no `sampled` edges, so a single response can be entirely
  *    `considered`.
  *
- * See {@link ColourPairing} for the third, non-evidential arm.
+ * See {@link ColorPairing} for the third, non-evidential arm.
  */
 export type CospecPairing = {
     /** The evidence tier. `cospec` = orders; `considered` = boards. Read it before phrasing. */
     source: "cospec" | "considered";
     /**
-     * Membership of the requested `corpusScope`: true in, false out, null when
+     * Membership of the requested `searchCatalogueSubset`: true in, false out, null when
      * the graph cannot say. Absent when no narrowing scope was asked for. It
      * flags, it never removes (MG-2292).
      */
@@ -338,7 +105,7 @@ export type CospecPairing = {
      * - `companion` — a DIFFERENT BRAND entirely. This is the cross-brand claim
      *   the rail exists to make.
      * - `brand_sibling` — the seed's own brand, a different product.
-     * - `colourway` — the seed's own product, restyled.
+     * - `colorway` — the seed's own product, restyled.
      *
      * **70.6% of edges are same-brand**, so a consumer that ignores this reports
      * the seed's own family as cross-brand intelligence (MG-1007).
@@ -346,7 +113,7 @@ export type CospecPairing = {
      * Optional because responses captured before the field existed are genuinely
      * in the wild; absent means "from an older version", never "unrelated".
      */
-    relation?: "companion" | "brand_sibling" | "colourway";
+    relation?: "companion" | "brand_sibling" | "colorway";
     category: string | null;
     projectCount: number;
     customerCount: number;
@@ -354,41 +121,41 @@ export type CospecPairing = {
     liftLabel: string;
     demand: CompanionDemand | null;
     topProjectTypes: ProjectTypeShare[];
-    /** Graph-owned colour ranking facts, present only for an explicitly ordered rail. */
+    /** Graph-owned color ranking facts, present only for an explicitly ordered rail. */
     ranking?: PairingRanking;
 };
 /**
- * A pairing item topped up from colour palette-similarity — a LOOK-ALIKE, not
+ * A pairing item topped up from color palette-similarity — a LOOK-ALIKE, not
  * evidence. Nobody ordered these together and nobody boarded them together; the
  * palettes sit near each other in OKLab. Say "shares a palette with" and never
  * "specified together" or "often paired with".
  */
-export type ColourPairing = {
-    source: "colour";
+export type ColorPairing = {
+    source: "color";
     score: number;
     /**
-     * Membership of the requested `corpusScope`: true in, false out, null when
+     * Membership of the requested `searchCatalogueSubset`: true in, false out, null when
      * the graph cannot say. Absent when no narrowing scope was asked for. It
      * flags, it never removes (MG-2292).
      */
     inScope?: boolean | null;
-    /** Graph-owned colour ranking facts, present only for an explicitly ordered rail. */
+    /** Graph-owned color ranking facts, present only for an explicitly ordered rail. */
     ranking?: PairingRanking;
 } & MaterialTile;
 export type PairingOrderMode = "relevance" | "lightness_asc" | "lightness_desc";
 export type PairingRanking = {
-    anchorColourSimilarity: number | null;
+    anchorColorSimilarity: number | null;
     lightness: number | null;
-    anchorColourSimilarityMeasurable: boolean;
+    anchorColorSimilarityMeasurable: boolean;
     lightnessMeasurable: boolean;
-    basis: OpenEnum<"dominant_colour_oklab">;
+    basis: OpenEnum<"dominant_color_oklab">;
 };
 export type PairingOrdering = {
     requested: OpenEnum<PairingOrderMode>;
     applied: OpenEnum<PairingOrderMode>;
     direction: OpenEnum<"ascending" | "descending">;
-    anchorColourBasis: OpenEnum<"one_minus_oklab_euclidean_distance">;
-    colourSpace: OpenEnum<"oklab">;
+    anchorColorBasis: OpenEnum<"one_minus_oklab_euclidean_distance">;
+    colorSpace: OpenEnum<"oklab">;
     lightnessRange: {
         min: 0;
         max: 1;
@@ -398,17 +165,17 @@ export type PairingOrdering = {
 };
 /**
  * One pairing, discriminated by `source` into three tiers of very different
- * strength: `cospec` (real orders) > `considered` (board activity) > `colour`
+ * strength: `cospec` (real orders) > `considered` (board activity) > `color`
  * (palette look-alike). Branch on `source` before you write a sentence about it.
  */
-export type PairingItem = CospecPairing | ColourPairing;
+export type PairingItem = CospecPairing | ColorPairing;
 export type PairingsResponse = {
     seed: MaterialTile;
     /** A rail, not a ranked corpus — mixed evidence tiers, capped by `limit`. */
     items: PairingItem[];
     /**
      * How many `items` came from real ORDER evidence (`source: "cospec"`). Zero
-     * with a full rail means every item is board activity or colour look-alike —
+     * with a full rail means every item is board activity or color look-alike —
      * check it before presenting the rail as demand evidence.
      */
     cospecCount: number;
@@ -481,43 +248,24 @@ export type ListAttributesResult = {
     };
 };
 export type * from "./catalog-discovery-types.js";
-export type * from "./resolve-colour-types.js";
+export type * from "./resolve-color-types.js";
 export type * from "./by-spec-types.js";
 export type WhoamiResponse = {
     principal: string;
     scopes: string[];
 };
-/** A single colour entry in a search palette — exactly one of `hex` or `name`. */
-export type ColourInput = {
-    hex?: string;
-    name?: string;
-    weight?: number;
-    role?: OpenEnum<"any" | "is" | "accent">;
-    sourceName?: string;
-};
-/** A raw incoming image to search by. */
-export type SearchImageInput = {
-    type: "url";
-    url: string;
-} | {
-    type: "base64";
-    data: string;
-};
-export type { SearchGetParams, SearchIndexFilter, SearchInput, } from "./search-request-types.js";
-export type { SearchIndexPlan, SearchPlanReceipt, } from "./search-index-plan-types.js";
-export type { ColourRegionRange } from "./colour-region-types.js";
 /** Options for a pairings read. */
 export type PairingsOptions = {
     /** Comma-separated coarse category display names; filters both arms. */
     categories?: string;
     /** Page size, 1–24 inclusive (default 12). The server rejects (400), not clamps, values outside this range. */
     limit?: number;
-    /** Return sampled order evidence only, without board or colour fallback. */
+    /** Return sampled order evidence only, without board or color fallback. */
     sampledOnly?: boolean;
-    /** Graph-owned order applied within fixed cospec → considered → colour tiers. */
+    /** Graph-owned order applied within fixed cospec → considered → color tiers. */
     order?: PairingOrderMode;
     /** Flags each item's `inScope` against this scope; never narrows the rail. */
-    corpusScope?: CorpusScope;
+    searchCatalogueSubset?: SearchCatalogueSubset;
     /** The previous response's `nextCursor`, passed back verbatim. */
     cursor?: Cursor;
 };